Exécutez des tâches de traitement SageMaker Clarify pour l'analyse des biais et l'explicabilité - Amazon SageMaker
Comment exécuter des tâches de traitement parallèles SageMaker Clarify

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Exécutez des tâches de traitement SageMaker Clarify pour l'analyse des biais et l'explicabilité

Pour analyser vos données et modèles afin de détecter les biais et l'explicabilité à l'aide de SageMaker Clarify, vous devez configurer une tâche de traitement SageMaker Clarify. Ce guide explique comment configurer les entrées, les sorties, les ressources et la configuration de l'analyse des tâches à l'aide de l'API SageMaker SageMakerClarifyProcessor Python SDK.

L'API agit comme un wrapper de haut niveau de l' SageMaker CreateProcessingJobAPI. Il masque de nombreux détails liés à la configuration d'une tâche de traitement SageMaker Clarify. Les détails nécessaires à la configuration d'une tâche incluent la récupération de l'URI de l'image du conteneur SageMaker Clarify et la génération du fichier de configuration d'analyse. Les étapes suivantes vous montrent comment configurer, initialiser et lancer une tâche de traitement SageMaker Clarify.

Configuration d'une tâche de traitement SageMaker Clarify à l'aide de l'API

  1. Définissez les objets de configuration pour chaque partie de la configuration de la tâche. Ces parties peuvent inclure les éléments suivants :

    • Le jeu de données en entrée et l'emplacement en sortie : DataConfig.

    • Le modèle ou le point final à analyser : ModelConfig.

    • Paramètres de l'analyse des biais : BiasConfig

    • Les paramètres d'analyse SHapley Additive exPlanations (SHAP) : SHAPConfig.

    Les objets de configuration d'une tâche de traitement SageMaker Clarify varient en fonction des différents types de formats de données et de cas d'utilisation. Des exemples de configuration pour des données tabulaires au format CSV ou JSON Lines, le traitement du langage naturel (NLP) et des problèmes de computer vision sont fournis dans les sections suivantes.

  2. Créez un objet SageMakerClarifyProcessor et initialisez-le avec des paramètres qui spécifient les ressources de la tâche. Ces ressources incluent des paramètres tels que le nombre d'instances de calcul à utiliser.

    L'exemple de code suivant montre comment créer un objet SageMakerClarifyProcessor et lui indique d'utiliser une seule instance de calcul ml.c4.xlarge pour effectuer l'analyse.

    from sagemaker import clarify

clarify_processor = clarify.SageMakerClarifyProcessor(
    role=role,
    instance_count=1,
    instance_type='ml.c4.xlarge',
    sagemaker_session=session,
)

  3. Appelez la méthode d'exécution spécifique de l'SageMakerClarifyProcessorobjet avec les objets de configuration correspondant à votre cas d'utilisation pour lancer le job. Ces méthodes d'exécution incluent les suivantes :

    • run_pre_training_bias

    • run_post_training_bias

    • run_bias

    • run_explainability

    • run_bias_and_explainability

    Cet objet SageMakerClarifyProcessor traite plusieurs tâches en arrière-plan. Ces tâches incluent la récupération de l'identifiant de ressource universel (URI) de l'image du conteneur SageMaker Clarify, la composition d'un fichier de configuration d'analyse basé sur les objets de configuration fournis, le téléchargement du fichier dans un compartiment Amazon S3 et la configuration de la tâche de traitement SageMaker Clarify.

    Les sections extensibles suivantes montrent comment calculer les métriques de biais de pré-entraînement et de post-entraînement, les valeurs SHAP et les graphiques de dépendance partielle (PDPs). Les sections montrent l'importance des fonctionnalités pour les types de données suivants :

    • Jeux de données tabulaires au format CSV ou au format JSON Lines

    • Jeux de données de traitement du langage naturel (NLP)

    • Jeux de données de vision par ordinateur

Un guide pour exécuter des tâches de traitement SageMaker Clarify en parallèle avec une formation distribuée à l'aide de Spark suit les sections extensibles.

Les exemples suivants montrent comment configurer l'analyse des biais et l'analyse de l'explicabilité pour un jeu de données tabulaire au format CSV. Dans ces exemples, le jeu de données entrant comporte quatre colonnes de fonctionnalités et une colonne d'étiquettes binaires, Target. Le contenu du jeu de données est le suivant. Une valeur d'étiquette de 1 indique un résultat positif. 

Target,Age,Gender,Income,Occupation
0,25,0,2850,2
1,36,0,6585,0
1,22,1,1759,1
0,48,0,3446,1
...

Cet objet DataConfig spécifie le jeu de données en entrée et l'emplacement de stockage de la sortie. Le paramètre s3_data_input_path peut être un URI d'un fichier de jeu de données ou un préfixe d'URI Amazon S3. Si vous fournissez un préfixe d'URI S3, la tâche de traitement SageMaker Clarify collecte de manière récursive tous les fichiers Amazon S3 situés sous le préfixe. La valeur pour s3_output_path doit être un préfixe d'URI S3 pour contenir les résultats de l'analyse. SageMaker utilise le s3_output_path pendant la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou ExecutionVariable d'un SageMaker pipeline utilisés pendant l'exécution. L'exemple de code suivant montre comment spécifier une configuration de données pour l'exemple de jeu de données en entrée précédent.

data_config = clarify.DataConfig(
    s3_data_input_path=dataset_s3_uri,
    dataset_type='text/csv',
    headers=['Target', 'Age', 'Gender', 'Income', 'Occupation'],
    label='Target',
    s3_output_path=clarify_job_output_s3_uri,
)

Comment calculer toutes les métriques de biais de pré-entraînement pour un jeu de données CSV

L'exemple de code suivant montre comment configurer un objet BiasConfig pour mesurer le biais de l'échantillon en entrée précédent par rapport aux échantillons ayant une valeur de Gender égale à 0.

bias_config = clarify.BiasConfig(
    label_values_or_threshold=[1],
    facet_name='Gender',
    facet_values_or_threshold=[0],
)

L'exemple de code suivant montre comment utiliser une instruction run pour lancer une tâche de traitement SageMaker Clarify qui calcule toutes les mesures de biais préalables à l'entraînement pour un ensemble de données en entrée. 

clarify_processor.run_pre_training_bias(
     data_config=data_config,
    data_bias_config=bias_config,
    methods="all",
)

Vous pouvez également choisir les métriques à calculer en affectant une liste de métriques de biais de pré-entraînement au paramètre methods. Par exemple, le remplacement methods="all" par methods=["CI", "DPL"] indique au processeur SageMaker Clarify de calculer uniquement le déséquilibre des classes et la différence de proportions entre les étiquettes.

Comment calculer toutes les métriques de biais de post-entraînement pour un jeu de données CSV

Vous pouvez calculer les métriques de biais de pré-entraînement avant l'entraînement. Toutefois, pour calculer les métriques de biais de post-entraînement, vous devez disposer d'un modèle entraîné. L'exemple de sortie suivant provient d'un modèle de classification binaire qui fournit en sortie des données au format CSV. Dans cet exemple de sortie, chaque ligne contient deux colonnes. La première colonne contient l'étiquette prédite et la deuxième colonne contient la valeur de probabilité pour cette étiquette.

0,0.028986845165491
1,0.825382471084594
...

Dans l'exemple de configuration suivant, l'ModelConfigobjet indique à la tâche de déployer le SageMaker modèle sur un point de terminaison éphémère. Le point de terminaison utilise une seule instance d'inférence ml.m4.xlarge. Comme les paramètres content_type et accept_type ne sont pas définis, ils utilisent automatiquement la valeur du paramètre dataset_type, qui est text/csv.

model_config = clarify.ModelConfig(
    model_name=your_model,
    instance_type='ml.m4.xlarge',
    instance_count=1,
)

L'exemple de configuration suivant utilise un objet ModelPredictedLabelConfig avec un index d'étiquette égal à 0. Cela indique à la tâche de traitement SageMaker Clarify de localiser l'étiquette prévue dans la première colonne de la sortie du modèle. La tâche de traitement utilise une indexation basée sur zéro dans cet exemple.

predicted_label_config = clarify.ModelPredictedLabelConfig(
    label=0,
)

Combiné à l'exemple de configuration précédent, l'exemple de code suivant lance une tâche de traitement SageMaker Clarify pour calculer toutes les mesures de biais après l'entraînement.

clarify_processor.run_post_training_bias(
    data_config=data_config,
    data_bias_config=bias_config,
    model_config=model_config,
    model_predicted_label_config=predicted_label_config,
    methods="all",
)

De même, vous pouvez choisir les métriques à calculer en affectant une liste de métriques de biais de post-entraînement au paramètre methods. Par exemple, remplacez methods=“all” par methods=["DPPL", "DI"] pour calculer uniquement la différence entre les proportions positives des étiquettes prédites et l'impact disparate.

Comment calculer toutes les métriques de biais pour un jeu de données CSV

L'exemple de configuration suivant montre comment exécuter toutes les mesures de biais avant et après l'entraînement dans une seule tâche de traitement SageMaker Clarify.

clarify_processor.run_bias(
    data_config=data_config,
     bias_config=bias_config,
     model_config=model_config,
    model_predicted_label_config=predicted_label_config,
    pre_training_methods="all",
    post_training_methods="all",
)

Pour un exemple de bloc-notes contenant des instructions sur la façon d'exécuter une tâche de traitement SageMaker Clarify dans SageMaker Studio Classic afin de détecter les biais, voir Équité et explicabilité avec SageMaker Clarify.

Comment calculer les valeurs SHAP pour un jeu de données CSV

SageMaker Clarify fournit des attributions de fonctionnalités à l'aide de l'algorithme KernelShap. SHAPl'analyse nécessite la valeur de probabilité ou le score au lieu de l'étiquette prédite, de sorte que cet ModelPredictedLabelConfig objet possède un indice de probabilité1. Cela indique à la tâche de traitement SageMaker Clarify d'extraire le score de probabilité de la deuxième colonne de la sortie du modèle (en utilisant une indexation basée sur zéro).

probability_config = clarify.ModelPredictedLabelConfig(
    probability=1,
)

L'objet SHAPConfig fournit les paramètres d'analyse SHAP. Dans cet exemple, le paramètre SHAP baseline est omis et la valeur du paramètre num_clusters est 1. Cela indique au processeur SageMaker Clarify de calculer un échantillon SHAP de base en regroupant le jeu de données d'entrée. Si vous souhaitez choisir le jeu de données de référence, consultez Bases de référence SHAP pour l'explicabilité.

shap_config = clarify.SHAPConfig(
    num_clusters=1,
)

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify pour calculer SHAP des valeurs.

clarify_processor.run_explainability(
    data_config=data_config,
    model_config=model_config,
    model_scores=probability_config,
    explainability_config=shap_config,
)

Pour un exemple de bloc-notes contenant des instructions sur la façon d'exécuter une tâche de traitement SageMaker Clarify dans SageMaker Studio Classic pour calculer SHAP des valeurs, voir Équité et explicabilité avec SageMaker Clarify.

Comment calculer des graphiques de dépendance partielle (PDPs) pour un jeu de données CSV

Les PDPs montrent la dépendance de la réponse cible prédite sur une ou plusieurs fonctionnalités en entrée intéressantes tout en maintenant constantes toutes les autres fonctionnalités. Une ligne ou une courbe inclinée vers le haut sur le graphique PDP indique que la relation entre la cible et la ou les fonctionnalités en entrée est positive, et la pente indique la force de la relation. Une ligne ou une courbe inclinée vers le bas indique que si une fonctionnalité en entrée diminue, la variable cible augmente. Intuitivement, vous pouvez interpréter la dépendance partielle comme la réponse de la variable cible à chaque fonctionnalité en entrée intéressante.

L'exemple de configuration suivant concerne l'utilisation d'un PDPConfig objet pour demander à la tâche de traitement SageMaker Clarify de calculer l'importance de la Income fonctionnalité.

pdp_config = clarify.PDPConfig(
    features=["Income"],
    grid_resolution=10,
)

Dans l'exemple précédent, le paramètre grid_resolution divise la plage des valeurs de la fonctionnalité Income en 10 compartiments. La tâche de traitement SageMaker Clarify sera générée PDPs pour être Income divisée en 10 segments sur l'axe X. L'axe Y montre l'impact marginal de Income sur la variable cible.

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify à calculerPDPs.

clarify_processor.run_explainability(
    data_config=data_config,
    model_config=model_config,
    model_scores=probability_config,
    explainability_config=pdp_config,
)

Pour un exemple de bloc-notes contenant des instructions sur la façon d'exécuter une tâche de traitement SageMaker Clarify dans SageMaker Studio Classic à des fins de calculPDPs, voir Explicabilité avec SageMaker Clarify - Partial Dependence Plots (PDP).

Comment calculer des valeurs SHAP et des graphiques PDPs pour un jeu de données CSV

Vous pouvez calculer les deux SHAP valeurs PDPs en une seule tâche de traitement SageMaker Clarify. Dans l'exemple de configuration suivant, le paramètre top_k_features d'un nouvel objet PDPConfig est défini sur 2. Cela indique à la tâche de traitement SageMaker Clarify de calculer PDPs les 2 entités dont les SHAP valeurs globales sont les plus élevées. 

shap_pdp_config = clarify.PDPConfig(
    top_k_features=2,
    grid_resolution=10,
)

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify pour calculer à la fois SHAP les valeurs etPDPs.

clarify_processor.run_explainability(
    data_config=data_config,
    model_config=model_config,
    model_scores=probability_config,
    explainability_config=[shap_config, shap_pdp_config],
)

Les exemples suivants montrent comment configurer l'analyse des biais et l'analyse d'explicabilité pour un jeu de données tabulaire au format dense > Lignes SageMaker JSON. Pour plus d’informations, consultez Format de demande JSONLINES. Dans ces exemples, le jeu de données entrant contient les mêmes données que dans la section précédente, mais elles sont au format JSON Lines. Chaque ligne est un objet JSON valide. La clé Features pointe sur un tableau de valeurs de fonctionnalités, et la clé Label pointe sur l'étiquette de vérité terrain.

{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...

Dans l'exemple de configuration suivant, l'objet DataConfig spécifie le jeu de données en entrée et l'emplacement de stockage de la sortie. 

data_config = clarify.DataConfig(
    s3_data_input_path=jsonl_dataset_s3_uri,
    dataset_type='application/jsonlines',
    headers=['Age', 'Gender', 'Income', 'Occupation', 'Target'],
    label='Label',
    features='Features',
    s3_output_path=clarify_job_output_s3_uri,
)

Dans l'exemple de configuration précédent, le paramètre features est défini sur l'expression JMESpath Features afin que la tâche de traitement SageMaker Clarify puisse extraire le tableau d'entités de chaque enregistrement. Le label paramètre est défini sur l'expression JMESpath Label afin que la tâche de traitement SageMaker Clarify puisse extraire l'étiquette Ground Truth de chaque enregistrement. Le paramètre s3_data_input_path peut être un URI d'un fichier de jeu de données ou un préfixe d'URI Amazon S3. Si vous fournissez un préfixe d'URI S3, la tâche de traitement SageMaker Clarify collecte de manière récursive tous les fichiers S3 situés sous le préfixe. La valeur pour s3_output_path doit être un préfixe d'URI S3 pour contenir les résultats de l'analyse. SageMaker utilise le s3_output_path pendant la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou ExecutionVariable d'un SageMaker pipeline utilisés pendant l'exécution.

Vous devez disposer d'un modèle entraîné pour calculer l'importance des fonctionnalités ou les métriques de biais de post-entraînement. L'exemple suivant provient d'un modèle de classification binaire qui fournit en sortie des données JSON Lines dans le format de l'exemple. Chaque ligne de la sortie du modèle est un objet JSON valide. La clé predicted_label pointe vers l'étiquette prédite et la clé probability pointe vers la valeur de probabilité.

{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...

Dans l'exemple de configuration suivant, un ModelConfig objet demande à la tâche de traitement SageMaker Clarify de déployer le SageMaker modèle sur un point de terminaison éphémère. Le point de terminaison utilise une seule instance d'inférence ml.m4.xlarge.

model_config = clarify.ModelConfig(
    model_name=your_model,
    instance_type='ml.m4.xlarge',
    instance_count=1,
    content_template='{"Features":$features}',
)

Dans l'exemple de configuration précédent, les paramètres content_type et accept_type ne sont pas définis. Par conséquent, ils utilisent automatiquement la valeur du paramètre dataset_type de l'objet DataConfig, qui est application/jsonlines. La tâche de traitement SageMaker Clarify utilise le content_template paramètre pour composer l'entrée du modèle en remplaçant l'$featuresespace réservé par un ensemble de fonctionnalités.

L'exemple de configuration suivant montre comment définir le paramètre label de l'objet ModelPredictedLabelConfig sur l'expression JMESpath predicted_label. Cela permet d'extraire l'étiquette prédite de la sortie de modèle.

predicted_label_config = clarify.ModelPredictedLabelConfig(
    label='predicted_label',
)

L'exemple de configuration suivant montre comment définir le paramètre probability de l'objet ModelPredictedLabelConfig sur l'expression JMESpath probability. Cela permet d'extraire le score de la sortie de modèle.

probability_config = clarify.ModelPredictedLabelConfig(
    probability='probability',
)

Pour calculer les métriques de biais et l'importance des fonctionnalités pour les jeux de données au format JSON Lines, utilisez les mêmes instructions d'exécution et les mêmes objets de configuration que dans la section précédente relative aux jeux de données CSV. Vous pouvez exécuter une tâche de traitement SageMaker Clarify dans SageMaker Studio Classic pour détecter les biais et calculer l'importance des fonctionnalités. Pour obtenir des instructions et un exemple de bloc-notes, voir Équité et explicabilité avec SageMaker Clarify (format de lignes JSON).

SageMaker Clarify prend en charge les explications des modèles de traitement du langage naturel (NLP). Ces explications vous aident à comprendre quelles sections de texte sont les plus importantes pour les prédictions de votre modèle. Vous pouvez expliquer la prédiction du modèle pour une instance unique du jeu de données en entrée ou les prédictions du modèle à partir du jeu de données de référence. Pour comprendre et visualiser le comportement d'un modèle, vous pouvez spécifier plusieurs niveaux de granularité. Pour ce faire, définissez la longueur du segment de texte, comme des jetons, des phrases ou des paragraphes.

SageMaker Clarifier l'explicabilité de la PNL est compatible à la fois avec les modèles de classification et de régression. Vous pouvez également utiliser SageMaker Clarify pour expliquer le comportement de votre modèle sur des ensembles de données multimodaux contenant du texte, des entités catégorielles ou numériques. L'explicabilité du NLP pour les ensembles de données multimodaux peut vous aider à comprendre l'importance de chaque caractéristique pour le résultat du modèle. SageMaker Clarify prend en charge 62 langues et peut gérer du texte en plusieurs langues.

L'exemple suivant montre un fichier de configuration d'analyse pour le calcul de l'importance des fonctionnalités pour le NLP. Dans cet exemple, le jeu de données entrant est un jeu de données tabulaire au format CSV, avec une colonne d'étiquettes binaires et deux colonnes de fonctionnalités.

0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...

L'exemple de configuration suivant montre comment spécifier un jeu de données en entrée au format CSV et le chemin des données en sortie à l'aide de l'objet DataConfig.

nlp_data_config = clarify.DataConfig(
    s3_data_input_path=nlp_dataset_s3_uri,
    dataset_type='text/csv',
    headers=['Target', 'Rating', 'Comments'],
    label='Target',
    s3_output_path=clarify_job_output_s3_uri,
)

Dans l'exemple de configuration précédent, le s3_data_input_path paramètre peut être l'URI d'un fichier d'ensemble de données ou un préfixe d'URI Amazon S3. Si vous fournissez un préfixe d'URI S3, la tâche de traitement SageMaker Clarify collecte de manière récursive tous les fichiers S3 situés sous le préfixe. La valeur pour s3_output_path doit être un préfixe d'URI S3 pour contenir les résultats de l'analyse. SageMaker utilise le s3_output_path pendant la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou ExecutionVariable d'un SageMaker pipeline utilisés pendant l'exécution.

L'exemple de sortie suivant a été créé à partir d'un modèle de classification binaire entraîné sur le jeu de données en entrée précédent. Le modèle de classification accepte les données CSV et produit un score unique compris entre 0 et 1.

0.491656005382537
0.569582343101501
...

L'exemple suivant montre comment configurer l'ModelConfigobjet pour déployer un SageMaker modèle. Dans cet exemple, un point de terminaison éphémère déploie le modèle. Ce point de terminaison utilise une seule instance d'inférence ml.g4dn.xlarge équipée d'un GPU pour accélérer l'inférence.

nlp_model_config = clarify.ModelConfig(
    model_name=your_nlp_model_name,
    instance_type='ml.g4dn.xlarge',
    instance_count=1,
)

L'exemple suivant montre comment configurer l'objet ModelPredictedLabelConfig pour localiser la probabilité (score) dans la première colonne avec un index de 0.

probability_config = clarify.ModelPredictedLabelConfig(
    probability=0,
)

L'exemple suivant de configuration SHAP montre comment exécuter une analyse d'explicabilité par jeton à l'aide d'un modèle et d'un jeu de données en entrée en langue anglaise.

text_config = clarify.TextConfig(
    language='english',
    granularity='token',
)
nlp_shap_config = clarify.SHAPConfig(
    baseline=[[4, '[MASK]']],
    num_samples=100,
    text_config=text_config,
)

Dans l'exemple précédent, l'objet TextConfig active l'analyse d'explicabilité du NLP. Le paramètre granularity indique que l'analyse doit analyser les jetons. En anglais, chaque jeton est un mot. Pour les autres langages, consultez la documentation de SpacY sur la tokenisation, que SageMaker Clarify utilise pour le traitement NLP. L'exemple précédent montre également comment utiliser une note (Rating) moyenne de 4 pour définir une instance de référence SHAP sur place. Un jeton de masque spécial [MASK] est utilisé pour remplacer un jeton (mot) dans Comments.

Dans l'exemple précédent, si l'instance est 2,"Flavor needs work", définissez la base de référence sur une note (Rating) moyenne de 4 avec la base de référence suivante.

4, '[MASK]'

Dans l'exemple précédent, l' SageMaker explicateur Clarify parcourt chaque jeton et le remplace par le masque, comme suit.

2,"[MASK] needs work"

4,"Flavor [MASK] work"

4,"Flavor needs [MASK]"

Ensuite, la fiche SageMaker explicative Clarify enverra chaque ligne à votre modèle pour des prédictions. De cette façon, l'outil d'explication apprend les prédictions avec et sans les mots masqués. La fiche SageMaker explicative Clarify utilise ensuite ces informations pour calculer la contribution de chaque jeton.

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify pour calculer SHAP des valeurs.

clarify_processor.run_explainability(
    data_config=nlp_data_config,
    model_config=nlp_model_config,
    model_scores=probability_config,
    explainability_config=nlp_shap_config,
)

Pour un exemple de bloc-notes contenant des instructions sur la façon d'exécuter une tâche de traitement SageMaker Clarify dans SageMaker Studio Classic pour l'analyse d'explicabilité du langage naturel, voir Expliquer l'analyse des sentiments du texte à l'aide de Clarify. SageMaker

SageMaker Clarify génère des cartes thermiques qui fournissent des informations sur la façon dont vos modèles de vision par ordinateur classent et détectent les objets dans vos images.

Dans l'exemple de configuration suivant, le jeu de données en entrée est constitué d'images JPEG.

cv_data_config = clarify.DataConfig(
    s3_data_input_path=cv_dataset_s3_uri,
    dataset_type="application/x-image",
    s3_output_path=clarify_job_output_s3_uri,
)

Dans l'exemple de configuration précédent, l'DataConfigobjet contient un s3_data_input_path ensemble de préfixes d'URI Amazon S3. La tâche de traitement SageMaker Clarify collecte de manière récursive tous les fichiers image situés sous le préfixe. Le paramètre s3_data_input_path peut être un URI d'un fichier de jeu de données ou un préfixe d'URI Amazon S3. Si vous fournissez un préfixe d'URI S3, la tâche de traitement SageMaker Clarify collecte de manière récursive tous les fichiers S3 situés sous le préfixe. La valeur pour s3_output_path doit être un préfixe d'URI S3 pour contenir les résultats de l'analyse. SageMaker utilise le s3_output_path pendant la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou ExecutionVariable d'un SageMaker pipeline utilisés pendant l'exécution.

Comment expliquer un modèle de classification d'image

La tâche de traitement SageMaker Clarify explique les images à l'aide de l'algorithme KernelShap, qui traite l'image comme une collection de super pixels. Compte tenu d'un jeu de données composé d'images, la tâche de traitement génère un jeu de données d'images dans lequel chaque image affiche la carte thermique des super pixels correspondants.

L'exemple de configuration suivant montre comment configurer une analyse d'explicabilité à l'aide d'un modèle de classification d' SageMaker images. Pour plus d’informations, consultez Classification des images – MXNet.

ic_model_config = clarify.ModelConfig(
    model_name=your_cv_ic_model,
    instance_type="ml.p2.xlarge",
    instance_count=1,
    content_type="image/jpeg",
    accept_type="application/json",
)

Dans l'exemple de configuration précédent, un modèle nommé your_cv_ic_model a été entraîné pour classer les animaux figurant sur les images JPEG en entrée. Dans l'exemple précédent, l'ModelConfigobjet indique à la tâche de traitement SageMaker Clarify de déployer le SageMaker modèle sur un point de terminaison éphémère. Pour une inférence accélérée, le point de terminaison utilise une seule instance d'inférence ml.p2.xlarge équipée d'un GPU.

Une fois qu'une image JPEG est envoyée à un point de terminaison, celui-ci la classe et renvoie une liste de scores. Chaque score correspond à une catégorie. L'objet ModelPredictedLabelConfig fournit le nom de chaque catégorie, comme suit.

ic_prediction_config = clarify.ModelPredictedLabelConfig(
    label_headers=['bird', 'cat', 'dog'],
)

Un exemple de sortie pour l'entrée précédente de ['bird','cat','dog'] peut être 0.3,0.6,0.1, où 0.3 représente le score de confiance pour classer une image en tant qu'oiseau.

L'exemple suivant de configuration SHAP montre comment générer des explications pour un problème de classification d'image. Il utilise un objet ImageConfig pour activer l'analyse.

ic_image_config = clarify.ImageConfig(
    model_type="IMAGE_CLASSIFICATION",
    num_segments=20,
    segment_compactness=5,
)

ic_shap_config = clarify.SHAPConfig(
    num_samples=100,
    image_config=ic_image_config,
)

SageMaker Clarifiez les fonctionnalités des extraits à l'aide de la méthode SLIC (Simple Linear Iterative Clustering) de la bibliothèque scikit-learn pour la segmentation d'images. Dans l'exemple de configuration précédent, le paramètre model_type indique le type de problème de classification d'image. Le paramètre num_segments estime le nombre approximatif de segments à étiqueter dans l'image en entrée. Le nombre de segments est ensuite transmis au paramètre SLIC n_segments.

Chaque segment de l'image est considéré comme un super pixel et les valeurs SHAP locales sont calculées pour chaque segment. Le paramètre segment_compactness détermine la forme et la taille des segments d'image générés par la méthode SLIC scikit-image. Les tailles et les formes des segments d'image sont ensuite transmises au paramètre SLIC compactness.

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify afin de générer des cartes thermiques pour vos images. Les valeurs positives de carte thermique indiquent que la fonctionnalité a augmenté le score de confiance de détection de l'objet. Les valeurs négatives indiquent que la fonctionnalité a diminué le score de confiance.

clarify_processor.run_explainability(
    data_config=cv_data_config,
    model_config=ic_model_config,
    model_scores=ic_prediction_config,
    explainability_config=ic_shap_config,
)

Pour un exemple de bloc-notes utilisant SageMaker Clarify pour classer les images et expliquer sa classification, voir Expliquer la classification des images avec SageMaker Clarify.

Comment expliquer un modèle de détection d'objet

Une tâche de traitement SageMaker Clarify permet de détecter et de classer des objets dans une image, puis de fournir une explication de l'objet détecté. Le processus d'explication est le suivant.

  1. Les objets d'image sont d'abord classés dans l'une des classes d'une collection spécifiée. Par exemple, si un modèle de détection d'objet peut reconnaître un chat, un chien et un poisson, ces trois classes font partie d'une collection. Cette collection est spécifiée par le paramètre label_headers comme suit.

    clarify.ModelPredictedLabelConfig(

label_headers=object_categories,

)

  2. La tâche de traitement SageMaker Clarify produit un score de confiance pour chaque objet. Un score de confiance élevé indique qu'il appartient à l'une des classes d'une collection spécifiée. La tâche de traitement SageMaker Clarify produit également les coordonnées d'un cadre délimitant l'objet. Pour plus d'informations sur les scores de confiance et les cadres de délimitation, consultez Formats de réponse.

  3. SageMaker Clarify fournit ensuite une explication pour la détection d'un objet dans la scène d'image. Il utilise les méthodes décrites dans la section Comment expliquer un modèle de classification d'image.

Dans l'exemple de configuration suivant, un modèle de détection d' SageMaker objets your_cv_od_model est entraîné sur des images JPEG afin d'identifier les animaux qui s'y trouvent. 

od_model_config = clarify.ModelConfig(
    model_name=your_cv_ic_model,
    instance_type="ml.p2.xlarge",
    instance_count=1,
    content_type="image/jpeg",
    accept_type="application/json",
)

Dans l'exemple de configuration précédent, l'ModelConfigobjet indique à la tâche de traitement SageMaker Clarify de déployer le SageMaker modèle sur un point de terminaison éphémère. Pour une imagerie accélérée, ce point de terminaison utilise une seule instance d'inférence ml.p2.xlarge équipée d'un GPU.

Dans l'exemple de configuration suivant, l'objet ModelPredictedLabelConfig fournit le nom de chaque catégorie à des fins de classification.

ic_prediction_config = clarify.ModelPredictedLabelConfig(
    label_headers=['bird', 'cat', 'dog'],
)

L'exemple suivant de configuration SHAP montre comment générer des explications pour une détection d'objet.

od_image_config = clarify.ImageConfig(
    model_type="OBJECT_DETECTION",
    num_segments=20,
    segment_compactness=5,
    max_objects=5,
    iou_threshold=0.5,
    context=1.0,
)
od_shap_config = clarify.SHAPConfig(
    num_samples=100,
    image_config=image_config,
)

Dans l'exemple précédent de configuration, l'objet ImageConfig active l'analyse. Le paramètre model_type indique que le type de problème est la détection d'objet. Pour obtenir une description détaillée des autres paramètres, consultez Configurer l'analyse.

L'exemple de code suivant lance une tâche de traitement SageMaker Clarify afin de générer des cartes thermiques pour vos images. Les valeurs positives de carte thermique indiquent que la fonctionnalité a augmenté le score de confiance de détection de l'objet. Les valeurs négatives indiquent que la fonctionnalité a diminué le score de confiance.

clarify_processor.run_explainability(
    data_config=cv_data_config,
    model_config=od_model_config,
    model_scores=od_prediction_config,
    explainability_config=od_shap_config,
)

Pour un exemple de bloc-notes utilisant SageMaker Clarify pour détecter des objets dans une image et expliquer ses prédictions, consultez Expliquer les modèles de détection d'objets avec Amazon SageMaker Clarify.

Comment exécuter des tâches de traitement parallèles SageMaker Clarify

Lorsque vous travaillez avec de grands ensembles de données, vous pouvez utiliser Apache Spark pour augmenter la vitesse de vos tâches de traitement SageMaker Clarify. Spark est un moteur analytique unifié pour le traitement de données à grande échelle. Lorsque vous demandez plusieurs instances par processeur SageMaker Clarify, SageMaker Clarify utilise les fonctionnalités de calcul distribué de Spark.

L'exemple de configuration suivant montre comment SageMakerClarifyProcessor créer un processeur SageMaker Clarify avec des instances de 5 calcul. Pour exécuter les tâches associées auSageMakerClarifyProcessor, SageMaker Clarify à l'aide du traitement distribué Spark.

from sagemaker import clarify

spark_clarify_processor = clarify.SageMakerClarifyProcessor(
    role=role,
    instance_count=5,
    instance_type='ml.c5.xlarge',
)

Si vous définissez le save_local_shap_values paramètre de ShapConfig surTrue, la tâche de traitement SageMaker Clarify enregistre la SHAP valeur locale sous forme de fichiers partiels multiples dans l'emplacement de sortie de la tâche.

Pour associer les valeurs SHAP locales aux instances de jeu de données en entrée, utilisez le paramètre joinsource de DataConfig. Si vous ajoutez d'autres instances de calcul, nous vous recommandons également d'augmenter le nombre instance_count de ModelConfigpour le point de terminaison éphémère. Cela évite que les demandes d'inférence simultanées des applications de travail Spark ne surchargent le point de terminaison. Plus précisément, nous vous recommandons d'utiliser un one-to-one ratio d' endpoint-to-processing instances.