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'`CreateProcessingJob`API SageMaker AI. 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.
**Configurer 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](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.DataConfig).
+ Le modèle ou le point final à analyser : [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig).
+ Paramètres de l'analyse des biais : [BiasConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.BiasConfig)
+ SHapley Paramètres d'analyse Additive Explanations (SHAP) : [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)
+ Paramètres d'analyse des valeurs asymétriques de Shapley (pour les séries chronologiques uniquement) :. [AsymmetricShapleyValueConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.AsymmetricShapleyValueConfig)
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](#clarify-processing-job-run-tabular-csv) ou [JSON Lines](#clarify-processing-job-run-tabular-jsonlines), et des problèmes liés au traitement du langage naturel ([NLP](#clarify-processing-job-run-tabular-nlp)), à [computer vision](#clarify-processing-job-run-cv) (CV) et aux séries temporelles (TS) sont fournis dans les sections suivantes.
1. 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,
)
```
1. Appelez la méthode d'exécution spécifique de l'[SageMakerClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor.run)objet 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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html).
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.
## Analyse de données tabulaires au format CSV
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 L'IA les utilise `s3_output_path` lors de la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou `ExecutionVariable` d'une expression d' SageMaker AI 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 d’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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html) 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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html) et la [différence de proportions entre les étiquettes](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-data-bias-metric-true-label-imbalance.html).
### 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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-post-training-bias.html), 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'`ModelConfig`objet demande à la tâche de déployer le modèle d' SageMaker IA 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](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-dppl.html) et l'[impact disparate](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-di.html).
### 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 ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb) 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](https://arxiv.org/abs/1705.07874). 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é](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html).
```
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 ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb) 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 pour effectuer un calculPDPs.
```
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)](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb).
### 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],
)
```
## Analyse de données tabulaires au format JSON Lines
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 JSON SageMaker AI. Pour plus d’informations, consultez [Format de demande JSONLINES](cdf-inference.md#cm-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 d’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'[JMESPath](https://jmespath.org/)expression `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 JMESPath expression `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 L'IA les utilise `s3_output_path` lors de la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou `ExecutionVariable` d'une expression d' SageMaker AI Pipeline utilisés pendant l'exécution.
Vous devez disposer d’un modèle entraîné pour calculer l’importance des caractéristiques ou les indicateurs 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 modèle d' SageMaker IA 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'`$features`espace réservé par un ensemble de fonctionnalités.
L'exemple de configuration suivant montre comment définir le paramètre d'étiquette de l'`ModelPredictedLabelConfig`objet sur l' JMESPath expression`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 `probability` paramètre de l'`ModelPredictedLabelConfig`objet sur l' JMESPathexpression`probability`. Cela permet d'extraire le score de la sortie de modèle.
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
Pour calculer les indicateurs de biais et l’importance des caractéristiques 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)](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.ipynb).
## Analyse de données tabulaires pour l'explicabilité du NLP
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 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 d’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 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 L'IA les utilise `s3_output_path` lors de la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou `ExecutionVariable` d'une expression d' SageMaker AI 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 d’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'`ModelConfig`objet pour déployer un modèle d' SageMaker IA. 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](https://spacy.io/usage/linguistic-features#tokenization), 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](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/text_explainability/text_explainability.ipynb) à l'aide de Clarify. SageMaker
## Analyse de données d’image pour l’explicabilité de la vision par ordinateur
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 d’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’objet `DataConfig` contient un élément `s3_data_input_path` défini sur un préfixe 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 L'IA les utilise `s3_output_path` lors de la compilation et ne peut pas prendre la valeur d'un paramètre, d'une propriété, d'une expression ou `ExecutionVariable` d'une expression d' SageMaker AI 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](image-classification.md).
```
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'`ModelConfig`objet indique à la tâche de traitement SageMaker Clarify de déployer le modèle d' SageMaker IA 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)](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) 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](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb).
### 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,
)
```
1. 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](object-detection-in-formats.md#object-detection-recordio).
1. 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'objets basé sur l' SageMaker IA `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'`ModelConfig`objet indique à la tâche de traitement SageMaker Clarify de déployer le modèle d' SageMaker IA 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 [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
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 AI Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb).
## Analyse des explications pour les modèles de prévision de séries temporelles
Les exemples suivants montrent comment configurer les données au format dense SageMaker AI JSON pour expliquer un modèle de prévision de séries chronologiques. Pour en savoir plus sur le formatage JSON, consultez [Format de demande JSON](cdf-inference.md#cm-json).
```
[
{
"item_id": "item1",
"timestamp": "2019-09-11",
"target_value": 47650.3,
"dynamic_feature_1": 0.4576,
"dynamic_feature_2": 0.2164,
"dynamic_feature_3": 0.1906,
"static_feature_1": 3,
"static_feature_2": 4
},
{
"item_id": "item1",
"timestamp": "2019-09-12",
"target_value": 47380.3,
"dynamic_feature_1": 0.4839,
"dynamic_feature_2": 0.2274,
"dynamic_feature_3": 0.1889,
"static_feature_1": 3,
"static_feature_2": 4
},
{
"item_id": "item2",
"timestamp": "2020-04-23",
"target_value": 35601.4,
"dynamic_feature_1": 0.5264,
"dynamic_feature_2": 0.3838,
"dynamic_feature_3": 0.4604,
"static_feature_1": 1,
"static_feature_2": 2
},
]
```
### Configuration des données
Utilisez `TimeSeriesDataConfig` pour communiquer à votre tâche d’explicabilité comment analyser correctement les données du jeu de données d’entrée transmis, comme indiqué dans l’exemple de configuration suivant :
```
time_series_data_config = clarify.TimeSeriesDataConfig(
target_time_series='[].target_value',
item_id='[].item_id',
timestamp='[].timestamp',
related_time_series=['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
static_covariates=['[].static_feature_1', '[].static_feature_2'],
dataset_format='timestamp_records',
)
```
### Configuration des valeurs de Shapley asymétriques
Utilisez `AsymmetricShapleyValueConfig` pour définir des arguments pour l’analyse des explications du modèle de prévision des séries temporelles, tels que la référence, la direction, la granularité et le nombre d’échantillons. Les valeurs de référence sont définies pour les trois types de données : séries temporelles associées, covariables statiques et séries temporelles cibles. La `AsymmetricShapleyValueConfig` configuration indique au processeur SageMaker Clarify comment calculer les attributions de fonctionnalités pour un élément à la fois. La configuration suivante montre un exemple de définition de `AsymmetricShapleyValueConfig`.
```
asymmetric_shapley_value_config = AsymmetricShapleyValueConfig(
direction="chronological",
granularity="fine-grained",
num_samples=10,
baseline={
"related_time_series": "zero",
"static_covariates": {
"item1": [0, 0], "item2": [0, 0]
},
"target_time_series": "zero"
},
)
```
Les valeurs que vous fournissez à `AsymmetricShapleyValueConfig` sont transmises à la configuration d’analyse sous forme d’entrée dans `methods` avec la clé `asymmetric_shapley_value`.
### Configuration du modèle
Vous pouvez contrôler la structure de la charge utile envoyée par le processeur SageMaker Clarify. Dans l'exemple de code suivant, un objet de `ModelConfig` configuration dirige une tâche d'explicabilité des prévisions de séries chronologiques afin d'agréger les enregistrements à l'aide de la JMESPath syntaxe dans `'{"instances": $records}'` laquelle la structure de chaque enregistrement est définie avec le record\$1template suivant. `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` Notez que `$start_time`, `$target_time_series`, `$related_time_series` et `$static_covariates` sont des jetons internes utilisés pour mapper les valeurs du jeu de données aux valeurs des demandes de point de terminaison.
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
record_template='{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}',
content_template='{"instances": $records}',,
time_series_model_config=TimeSeriesModelConfig(
forecast={'forecast': 'predictions[*].mean[:2]'}
)
)
```
De même, l’attribut `forecast` dans `TimeSeriesModelConfig`, transmis à la configuration d’analyse avec la clé `time_series_predictor_config`, est utilisé pour extraire la prévision du modèle à partir de la réponse du point de terminaison. Par exemple, un exemple de réponse par lots de point de terminaison peut être le suivant :
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
Si l' JMESPath expression fournie `forecast` est \$1'predictions [\$1] .mean [:2] '\$1\$1, la valeur de prévision est analysée comme suit :
```
[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]
```
## 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](https://spark.apache.org/) 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 plus d'une instance 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 au`SageMakerClarifyProcessor`, 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 [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)à`True`, 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 [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)pour 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-processinginstances.