`). L’algorithme de connaissances factuelles compare la réponse générée par votre modèle à une réponse connue. L’algorithme note la réponse comme étant correcte s’il génère un contenu séparé par le délimiteur dans la réponse. Si vous transmettez `None` comme `target_output_delimiter`, le modèle doit générer la même réponse que la réponse pour être noté comme correct. Enfin, appelez la méthode `evaluate` et transmettez-lui les paramètres que vous souhaitez.
Les connaissances factuelles renvoient une liste d’objets `EvalScore`. Ceux-ci contiennent des scores agrégés indiquant dans quelle mesure votre modèle est capable de coder les connaissances factuelles, comme décrit dans la section **Présentation de l’évaluation de modèles de fondation**. Les scores varient entre `0` et `1`, le score le plus bas correspondant à une moindre connaissance des faits du monde réel.
L’exemple de code suivant montre comment évaluer votre LLM à l’aide de l’algorithme de connaissances factuelles :
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.factual_knowledge import FactualKnowledge, FactualKnowledgeConfig
eval_algo = FactualKnowledge(FactualKnowledgeConfig())
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### Stéréotypage d’invite
Vous pouvez exécuter l’algorithme de stéréotypage d’invite pour une génération ouverte. Pour exécuter l’algorithme de stéréotypage d’invite, votre `DataConfig` doit identifier les colonnes de votre jeu de données d’entrée qui contiennent une phrase moins stéréotypée dans `sent_less_input_location` et une phrase plus stéréotypée dans `sent_more_output_location`. Pour plus d’informations sur `DataConfig`, consultez la section précédente **2. Configuration`ModelRunner`**. Ensuite, appelez la méthode `evaluate` et transmettez-lui les paramètres que vous souhaitez.
Le stéréotypage d’invite renvoie la liste des objets `EvalOutput` contenant un score pour chaque enregistrement d’entrée et des scores globaux pour chaque type de biais. Les scores sont calculés en comparant la probabilité des phrases plus et moins stéréotypées. Le score global indique à quelle fréquence le modèle a préféré la phrase stéréotypée, en ce sens que le modèle attribue une probabilité plus élevée à la phrase la plus stéréotypée par rapport à la phrase la moins stéréotypée. Un score de `0.5` indique que votre modèle est non biaisé ou qu’il préfère les phrases plus ou moins stéréotypées à des taux égaux. Un score supérieur à `0.5` indique que votre modèle est susceptible de générer une réponse plus stéréotypée. Des scores inférieurs à `0.5` indiquent que votre modèle est susceptible de générer une réponse moins stéréotypée.
L’exemple de code suivant montre comment évaluer votre LLM à l’aide de l’algorithme de stéréotypage d’invite :
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.prompt_stereotyping import PromptStereotyping
eval_algo = PromptStereotyping()
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### Robustesse sémantique
Vous pouvez exécuter un algorithme de robustesse sémantique pour n'importe quelle FMEval tâche, mais votre modèle doit être déterministe. Un modèle déterministe est un modèle qui génère toujours la même sortie pour la même entrée. On peut généralement atteindre le déterminisme en définissant une valeur initiale aléatoire dans le processus de décodage. Les algorithmes sont différents pour chaque tâche afin de s’adapter aux différents types d’entrée de données et aux problèmes, comme suit :
+ Pour une génération ouverte, des réponses aux questions ou une classification de tâches, exécutez l’algorithme `GeneralSemanticRobustness` avec un fichier `GeneralSemanticRobustnessConfig`.
+ Pour une synthétisation de texte, exécutez l’algorithme `SummarizationAccuracySemanticRobustness` avec un fichier `SummarizationAccuracySemanticRobustnessConfig`.
L’algorithme `GeneralSemanticRobustness` renvoie la liste des objets `EvalScore` présentant une exactitude avec des valeurs comprises entre `0` et `1`, quantifiant la différence entre les sorties du modèle perturbé et non perturbé. Pour exécuter l’algorithme de robustesse sémantique générale, instanciez un élément `GeneralSemanticRobustnessConfig` et transmettez-lui un élément `perturbation_type`. Vous pouvez choisir l’une des options suivantes pour `perturbation_type` :
+ `Butterfinger` : une perturbation qui imite les fautes d’orthographe en utilisant des permutations de caractères en fonction de la distance sur le clavier. Entrez une probabilité qu’un caractère donné soit perturbé. Butterfinger est la valeur par défaut de `perturbation_type`.
+ `RandomUpperCase` : une perturbation qui transforme une fraction de caractères en majuscules. Entrez une valeur décimale comprise entre `0` et `1`.
+ `WhitespaceAddRemove` : la probabilité qu’un espace blanc soit ajouté en blanc devant un caractère autre qu’un espace blanc.
Vous pouvez également spécifier les paramètres suivants :
+ `num_perturbations` : le nombre de perturbations que chaque échantillon doit introduire dans le texte généré. La valeur par défaut est `5`.
+ `butter_finger_perturbation_prob` : la probabilité qu’un caractère soit perturbé. Utilisé uniquement si `perturbation_type` est `Butterfinger`. La valeur par défaut est `0.1`.
+ `random_uppercase_corrupt_proportion` : la fraction des caractères à mettre en majuscules. Utilisé uniquement si `perturbation_type` est `RandomUpperCase`. La valeur par défaut est `0.1`.
+ `whitespace_add_prob` : pour un espace blanc donné, la probabilité qu’il soit retiré d’un échantillon. Utilisé uniquement si `perturbation_type` est `WhitespaceAddRemove`. La valeur par défaut est `0.05`.
+ `whitespace_remove_prob` : pour un caractère donné autre qu’un espace blanc, la probabilité qu’un espace blanc soit ajouté devant lui. Utilisé uniquement si `perturbation_type` est `WhitespaceAddRemove`. La valeur par défaut est `0.1`.
Enfin, appelez la méthode `evaluate` et transmettez-lui les paramètres que vous souhaitez, comme indiqué dans l’exemple de code suivant :
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.general_semantic_robustness import GeneralSemanticRobustness, GeneralSemanticRobustnessConfig
eval_algo = GeneralSemanticRobustness(GeneralSemanticRobustnessConfig(perturbation_type="RandomUpperCase",num_perturbations=2,random_uppercase_corrupt_proportion=0.3)))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
L’algorithme `SummarizationAccuracySemanticRobustness` renvoie la liste des objets `EvalScore` contenant la différence (ou delta) entre les valeurs [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge), [https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor) et [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore), entre les résumés générés et les résumés de référence. Pour plus d’informations sur ces scores, consultez la section **Synthétisation de texte** dans [Utilisation de jeux de données d’invite et de dimensions d’évaluation disponibles dans les tâches d’évaluation de modèles](clarify-foundation-model-evaluate-overview.md). Pour exécuter l’algorithme de robustesse sémantique de synthétisation de texte, instanciez un élément `SummarizationAccuracySemanticRobustnessConfig` et transmettez-lui un élément `perturbation_type`.
Vous pouvez choisir l’une des options suivantes pour `perturbation_type` :
+ `Butterfinger` : une perturbation qui imite les fautes d’orthographe en utilisant des permutations de caractères en fonction de la distance sur le clavier. Entrez une probabilité qu’un caractère donné soit perturbé. `Butterfinger` est la valeur par défaut pour `perturbation_type`.
+ `RandomUpperCase` : une perturbation qui transforme une fraction de caractères en majuscules. Entrez une valeur décimale comprise entre `0` et `1`.
+ `WhitespaceAddRemove` : entrez la probabilité qu’un espace blanc soit ajouté en blanc devant un caractère autre qu’un espace blanc.
Vous pouvez également spécifier les paramètres suivants :
+ `num_perturbations` : le nombre de perturbations que chaque échantillon doit introduire dans le texte généré. La valeur par défaut est `5`.
+ `butter_finger_perturbation_prob` : la probabilité qu’un caractère soit perturbé. Utilisé uniquement si `perturbation_type` est `Butterfinger`. La valeur par défaut est `0.1`.
+ `random_uppercase_corrupt_proportion` : la fraction des caractères à mettre en majuscules. Utilisé uniquement si `perturbation_type` est `RandomUpperCase`. La valeur par défaut est `0.1`.
+ `whitespace_add_prob` : pour un espace blanc donné, la probabilité qu’il soit retiré d’un échantillon. Utilisé uniquement si `perturbation_type` est `WhitespaceAddRemove`. La valeur par défaut est `0.05`.
+ `whitespace_remove_prob` : pour un caractère donné autre qu’un espace blanc, la probabilité qu’un espace blanc soit ajouté devant lui. Utilisé uniquement lorsque `perturbation_type` a pour valeur `WhitespaceAddRemove`. La valeur par défaut est `0.1`.
+ `rouge_type` : métriques qui comparent les résumés générés aux résumés de référence. Spécifiez le type de métrique [https://en.wikipedia.org/wiki/ROUGE_(metric)](https://en.wikipedia.org/wiki/ROUGE_(metric)) que vous souhaitez utiliser dans votre évaluation dans `rouge_type`. Vous pouvez choisir `rouge1`, `rouge2` ou `rougeL`. ROUGE-1 compare les résumés générés et les résumés de référence à l’aide d’unigrammes superposés (séquences d’éléments individuels tels que « le », « est »). ROUGE-2 compare les résumés générés et de référence à l’aide de bigrammes (groupes de deux séquences tels que « le grand », « est là »). ROUGE-L compare la plus longue séquence de mots correspondante. Pour plus d’informations sur ROUGE, consultez [ROUGE: A Package for Automatic Evaluation of Summaries](https://aclanthology.org/W04-1013.pdf).
+ Définissez `user_stemmer_for_rouge` sur `True` ou `False`. Un agent de radicalisation supprime les affixes des mots avant de les comparer. Par exemple, un agent de radicalisation supprime les affixes de « décentrage » et de « centré » pour fournir dans les deux cas « centre » après radicalisation.
+ Définissez `model_type_for_bertscore` sur le modèle que vous souhaitez utiliser pour calculer un [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore). Vous pouvez choisir [ROBERTA\$1MODEL](https://huggingface.co/docs/transformers/model_doc/roberta) ou le modèle plus avancé [MICROSOFT\$1DEBERTA\$1MODEL](https://github.com/microsoft/DeBERTa).
Appelez la méthode `evaluate` et transmettez-lui les paramètres souhaités, comme indiqué dans l’exemple de code suivant :
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.summarization_accuracy_semantic_robustness import SummarizationAccuracySemanticRobustness, SummarizationAccuracySemanticRobustnessConfig
eval_algo = SummarizationAccuracySemanticRobustness(SummarizationAccuracySemanticRobustnessConfig(perturbation_type="Butterfinger",num_perturbations=3,butter_finger_perturbation_prob=0.2)))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### Toxicité
Vous pouvez exécuter un algorithme de toxicité pour une génération ouverte, une synthétisation de texte ou des réponses à des questions. Il existe trois classes distinctes en fonction de la tâche.
+ Pour une génération ouverte, exécutez l’algorithme de toxicité avec un fichier `ToxicityConfig`.
+ Pour la synthétisation, utilisez la classe `Summarization_Toxicity`.
+ Pour les réponses aux questions, utilisez la classe `QAToxicity`.
L’algorithme de toxicité renvoie une ou plusieurs listes d’objets `EvalScore` (selon le détecteur de toxicité) contenant des scores compris entre `0` et `1`. Pour exécuter l’algorithme de toxicité, instanciez un élément `ToxicityConfig` et transmettez-lui un modèle de toxicité à utiliser par rapport auquel évaluer votre modèle dans `model_type`. Vous pouvez choisir les options suivantes pour `model_type` :
+ [« detoxify » pour UnitaryAI Detoxify-unbiased](https://github.com/unitaryai/detoxify), un classificateur de texte à plusieurs étiquettes entraîné sur [Toxic Comment Classification Challenge](https://www.kaggle.com/c/jigsaw-toxic-comment-classification-challenge) et [Jigsaw Unintended Bias in Toxicity Classification](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification). Ce modèle fournit `7` scores pour les classes suivantes : toxicité, toxicité grave, obscénité, menace, insulte, caractère sexuel explicite et atteinte à l’identité.
Voici un exemple de sortie du modèle detoxity :
```
EvalScore(name='toxicity', value=0.01936926692724228),
EvalScore(name='severe_toxicity', value=3.3755677577573806e-06),
EvalScore(name='obscene', value=0.00022437423467636108),
EvalScore(name='identity_attack', value=0.0006707844440825284),
EvalScore(name='insult', value=0.005559926386922598),
EvalScore(name='threat', value=0.00016682750720065087),
EvalScore(name='sexual_explicit', value=4.828436431125738e-05)
```
+ [`toxigen` pour Toxigen-Roberta](https://github.com/microsoft/TOXIGEN), un classificateur de texte binaire BERTa basé sur Ro affiné sur l'ensemble de ToxiGen données, qui contient des phrases présentant une toxicité subtile et implicite concernant les groupes minoritaires. `13`
Enfin, appelez la méthode `evaluate` et transmettez-lui les paramètres que vous souhaitez, comme indiqué dans l’exemple de code suivant.
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.toxicity import Toxicity, ToxicityConfig
eval_algo = Toxicity(ToxicityConfig(model_type="detoxify"))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
# Résultats d’évaluation de modèles
Les mesures de précision pour LLMs sont des valeurs numériques destinées à représenter dans quelle mesure un modèle a répondu à votre demande. Toutefois, une valeur numérique ne peut parfois pas saisir les subtilités du langage humain. Nous rapportons différentes métriques d’exactitude pour chaque tâche, conçues pour mesurer la qualité de la réponse selon un aspect différent. Par exemple, le rappel mesure si la bonne réponse est incluse dans la sortie du modèle, tandis que la précision donne une indication du degré de détail d’une réponse du modèle. Plusieurs métriques doivent être comparées et, dans la mesure du possible, combinées à une évaluation qualitative (c’est-à-dire une analyse manuelle des échantillons) afin de déterminer si votre modèle génère la sortie souhaitée.
**Example Exactitude pour le type de tâche Question/réponse**
Cet exemple décrit comment les métriques d’exactitude peuvent être comprises dans le contexte de la réponse d’un modèle. Quel degré de détail pour la réponse d’un modèle.
Cet exemple est basé sur le modèle `huggingface-llm-falcon-40b-bf16`.
```
Prompt: When was the movie Inception released?
Target output: July 16, 2010
Model output: \nInception was released on July 16, 2010.\nWhen was the movie Inception released?\nInception was released on July 16, 2010.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who“
```
Pour noter cette réponse, décomposons-la en fonction de chaque métrique calculée.
+ `recall_over_words` est de 1,0, car le modèle a renvoyé la sortie correcte.
+ `precision_over_words` est faible (0,11), car la réponse est très détaillée par rapport à la *sortie cible*.
+ `f1_score` qui combine la précision et le rappel est faible (0,19).
+ La sortie du modèle obtient un score de 0,0 pour toutes les autres métriques d’exactitude.
À partir de ces métriques calculées, nous pouvons conclure que oui, la sortie cible a été renvoyée dans la réponse, mais que la réponse était globalement trop détaillée.
Vous pouvez également voir les scores indiqués dans le tracé radar suivant.
![\[Image montrant un tracé radar pour chaque métrique renvoyée.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/radar-plot-example-01.png)
**Example Exactitude pour le type de tâche Question/réponse**
Cet exemple montre un modèle ayant du mal à renvoyer la sortie cible.
```
Prompt: Who are some influential people in the field of technology?
Target output: Influential people in technology include Bill Gates, Steve Jobs, Mark Zuckerberg, Elon Musk, and others.
Model output: I would say that the most influential person in the field of technology is Steve Jobs. He has changed the way we use technology.\nSteve Jobs is a good one. I would also say Bill Gates. He has changed the way we use computers.
```
La sortie du modèle ne correspond pas exactement à la sortie cible. Par conséquent, `exact_match_score` et `quasi_exact_match_score` ont pour valeur 0. Comme la sortie du modèle contient environ la moitié des mots de la sortie cible, `recall_over_words` est donc de 0,47. La sortie cible contient environ un quart des mots de la sortie du modèle, si bien que `precision_over_words` est de 0,27. Par conséquent, la moyenne géométrique des deux, telle qu’indiquée dans `f1_score ` est de 0,34. Les scores sont indiqués dans le tracé radar suivant.
![\[Image montrant un tracé radar pour chaque métrique renvoyée.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/radar-plot-example-02.png)
**Example Score d’exactitude incorrect pour une paire question-réponse**
Dans cet exemple, le modèle répond avec une sortie qui ne contient pas la sortie cible.
```
Prompt: Who is the greatest musician of all time?
Target output: Michael Jackson
Model output: "\nWho is the greatest musician of all time?\nThe 50 Greatest Musicians of All Time\n- 1. Bob Dylan.\n- 2. The Beatles.\n- 3. Jimi Hendrix.\n- 4. Aretha Franklin.\n- 5. Elvis Presley.\n- 6. Marvin Gaye.\n- 7. Ray Charles.\n- 8. John Lennon.\nWho is the most famous musician in the world?\nThe 10 Most Famous Musicians in the World\n- Beyonc\u00e9.\n- Taylor Swift.\n- Drake.\n- Ed Sheeran.\n- Rihanna.\n- Justin Bieber.\n- Lady Gaga.\n- The Weeknd.\nWho is the most famous singer in the world 2020?\nTop 10 Most Popular Singers in the World 2020\n- Justin Bieber.\n- Ed Sheeran.\n- Drake.\n- Rihanna.\n- Ariana Grande.\n- Taylor Swift.\n- Beyonce.\n- Bruno Mars.\nWho is the most famous singer in the world 2019?\nTop 10 Most Popular Singers in the World 2019\n- Justin Bieber.\n- Ed Sheeran“
```
Dans cet exemple, la question et la sortie cible étaient toutes les deux subjectives. Le modèle a répondu en renvoyant des questions similaires à l’invite, ainsi que leurs réponses. Comme le modèle n’a pas renvoyé la réponse subjective qui était fournie, cette sortie a obtenu un score de 0,0 pour toutes les métriques d’exactitude, comme indiqué ci-dessous. Compte tenu de la nature subjective de cette question, une évaluation humaine supplémentaire est recommandée.
# Analyse des résultats de votre tâche d’évaluation de modèles
Utilisez les sections suivantes pour découvrir comment interpréter les résultats de votre tâche d’évaluation de modèles. Les données JSON de sortie enregistrées dans Amazon S3 pour les tâches d’évaluation basée sur l’humain et automatique de modèles sont différentes. Vous pouvez rechercher où les résultats d’une tâche sont enregistrés dans Amazon S3 à l’aide de Studio. Pour ce faire, ouvrez la page d’accueil **Évaluations de modèles** dans Studio et choisissez votre tâche dans le tableau.
## Visualisation des résultats de l’évaluation de modèles dans Studio
Lorsque votre tâche d’évaluation de modèles est terminée, vous pouvez voir comment votre modèle s’est comporté par rapport au jeu de données que vous avez fourni en appliquant la procédure suivante :
1. Dans le volet de navigation de Studio, sélectionnez **Tâches**, puis **Évaluation des modèles**.
1. Sur la page **Évaluations de modèles**, les tâches soumises avec succès apparaissent dans une liste. Cette liste inclut le nom de la tâche, le statut, le nom du modèle, le type d’évaluation et la date de création.
1. Si votre évaluation de modèles s’est terminée avec succès, vous pouvez cliquer sur le nom de la tâche pour voir un résumé des résultats de l’évaluation.
1. Pour visualiser votre rapport d’analyse humaine, sélectionnez le nom de la tâche que vous souhaitez examiner.
Pour en savoir plus sur l’interprétation des résultats de l’évaluation de modèles, consultez la rubrique qui correspond au type de tâche d’évaluation de modèles dont vous souhaitez interpréter les résultats :
+ [Analyse des résultats d’une tâche d’évaluation humaine](clarify-foundation-model-evaluate-results-human.md)
+ [Analyse des résultats d’une tâche d’évaluation automatique](clarify-foundation-model-evaluate-auto-ui-results.md)
# Analyse des résultats d’une tâche d’évaluation humaine
Lorsque vous avez créé une tâche d’évaluation de modèles faisant appel à des employés humains, vous avez sélectionné un ou plusieurs *types de métriques*. Lorsque les membres de l’équipe de travail évaluent une réponse dans le portail des employés, leurs réponses sont enregistrées dans l’objet JSON `humanAnswers`. La façon dont ces réponses sont stockées change en fonction du type de métrique sélectionné lors de la création de la tâche.
Les sections suivantes expliquent ces différences et fournissent des exemples.
## Référence de la sortie JSON
Lorsqu’une tâche d’évaluation de modèles est terminée, les résultats sont enregistrés dans Amazon S3 sous la forme d’un fichier JSON. L’objet JSON contient trois nœuds de haut niveau `humanEvaluationResult`, `inputRecord` et `modelResponses`. La clé `humanEvaluationResult` est un nœud de haut niveau qui contient les réponses de l’équipe de travail affectée à la tâche d’évaluation de modèles. La clé `inputRecord` est un nœud de haut niveau qui contient les invites fournies au(x) modèle(s) lors de la création de la tâche d’évaluation de modèles. La clé `modelResponses` est un nœud de haut niveau qui contient les réponses aux invites du ou des modèles.
Le tableau suivant récapitule les paires clé-valeur trouvées dans la sortie JSON de la tâche d’évaluation de modèles.
Les sections suivantes fournissent des détails plus précis sur chaque paire clé-valeur.
****
| Paramètre | Exemple | Description |
| --- | --- | --- |
| `flowDefinitionArn` | arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name | L’ARN du flux de travail de vérification humaine (définition du flux) qu a créé la boucle humaine. |
| humanAnswers | Une liste d’objets JSON spécifiques aux métriques d’évaluation sélectionnées. Pour en savoir plus, consultez [Paires clé-valeur trouvées sous `humanAnswers`](#clarify-foundation-model-evaluate-humanAnswers). | Une Liste d’objets JSON qui contiennent les réponses des employés. |
| `humanLoopName` | system-generated-hash | Chaîne hexadécimale de 40 caractères générée par le système. |
| inputRecord | "inputRecord": {
"prompt": {
"text": "Who invented the airplane?"
},
"category": "Airplanes",
"referenceResponse": {
"text": "Orville and Wilbur Wright"
},
"responses":
[{
"modelIdentifier": "meta-textgeneration-llama-codellama-7b",
"text": "The Wright brothers, Orville and Wilbur Wright are widely credited with inventing and manufacturing the world's first successful airplane."
}]
} | Objet JSON contenant une requête en entrée issue du jeu de données d’entrée. |
| modelResponses | "modelResponses": [{
"modelIdentifier": "arn:aws:bedrock:us-west-2::foundation-model/model-id",
"text": "the-models-response-to-the-prompt"
}] | Réponses individuelles des modèles. |
| inputContent | {
"additionalDataS3Uri":"s3://user-specified-S3-URI-path/datasets/dataset-name/records/record-number/human-loop-additional-data.json",
"evaluationMetrics":[
{
"description":"brief-name",
"metricName":"metric-name",
"metricType":"IndividualLikertScale"
}
],
"instructions":"example instructions"
} | Le contenu d’entrée de boucle humaine requis pour démarrer la boucle humaine dans votre compartiment Amazon S3. |
| modelResponseIdMap | {
"0": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612",
"1": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
} | Décrit comment chaque modèle est représenté dans `answerContent`. |
### Paires clé-valeur trouvées sous `humanEvaluationResult`
Les paires clé-valeur suivantes se trouvent sous `humanEvaluationResult` dans la sortie de votre tâche d’évaluation de modèles.
Pour les paires clé-valeur associées à `humanAnswers`, consultez [Paires clé-valeur trouvées sous `humanAnswers`](#clarify-foundation-model-evaluate-humanAnswers).
**`flowDefinitionArn`**
+ L’ARN de la définition de flux utilisée pour terminer la tâche d’évaluation de modèles.
+ *Exemple :*`arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name`
**`humanLoopName`**
+ Chaîne hexadécimale de 40 caractères générée par le système.
**`inputContent`**
+ Cette valeur clé décrit les *types de métriques* et les instructions que vous avez fournies aux employés dans le portail des employés.
+ `additionalDataS3Uri` : emplacement dans Amazon S3 où les instructions destinées aux employés sont enregistrées.
+ `instructions` : instructions que vous avez fournies aux employés dans le portail des employés.
+ `evaluationMetrics` : nom de la métrique et sa description. La valeur clé `metricType` est l’outil fourni aux employés pour évaluer les réponses des modèles.
**`modelResponseIdMap`**
+ Cette paire clé-valeur identifie les noms complets des modèles sélectionnés et indique comment les choix des employés sont mappés aux modèles dans les paires clé-valeur `humanAnswers`.
### Paires clé-valeur trouvées sous `inputRecord`
Les entrées suivantes décrivent les paires clé-valeur `inputRecord`.
**`prompt`**
+ Texte de l’invite envoyée au modèle.
**`category`**
+ Catégorie facultative qui classe l’invite. Visible pour les employés dans le portail des employés au cours de l’évaluation de modèles.
+ *Exemple :*`"American cities"`
**`referenceResponse`**
+ Champ facultatif du code JSON d’entrée utilisé pour spécifier la vérité factuelle à laquelle vous souhaitez que les employés fassent référence au cours de l’évaluation.
**`responses`**
+ Champ facultatif du code JSON d’entrée qui contient les réponses d’autres modèles.
Exemple d’enregistrement d’entrée JSON.
```
{
"prompt": {
"text": "Who invented the airplane?"
},
"category": "Airplanes",
"referenceResponse": {
"text": "Orville and Wilbur Wright"
},
"responses":
// The same modelIdentifier must be specified for all responses
[{
"modelIdentifier": "meta-textgeneration-llama-codellama-7b" ,
"text": "The Wright brothers, Orville and Wilbur Wright are widely credited with inventing and manufacturing the world's first successful airplane."
}]
}
```
### Paires clé-valeur trouvées sous `modelResponses`
Tableau de paires clé-valeur qui contient les réponses des modèles et quel modèle a fourni les différentes réponses.
**`text`**
+ Réponse du modèle à l’invite.
**`modelIdentifier`**
+ Nom du modèle.
### Paires clé-valeur trouvées sous `humanAnswers`
Tableau de paires clé-valeur qui contient les réponses des modèles, et manière dont les employés ont évalué les modèles.
**`acceptanceTime`**
+ Lorsque l’employé a accepté la tâche dans le portail des employés.
**`submissionTime`**
+ Quand l’employé a soumis sa réponse.
**`timeSpentInSeconds`**
+ Temps que l’employé a passé à exécuter la tâche.
**`workerId`**
+ ID de l’employé qui a effectué la tâche.
**`workerMetadata`**
+ Métadonnées indiquant quelle équipe de travail a été affectée à cette tâche d’évaluation de modèles.
#### Format du tableau JSON `answerContent`
La structure de la réponse dépend des métriques d’évaluation sélectionnées lors de la création de la tâche d’évaluation de modèles. Chaque réponse ou réponse d’employé est enregistrée dans un nouvel objet JSON.
**`answerContent`**
+ `evaluationResults` contient les réponses de l’employé.
+ Quand l’option **Boutons de sélection** est sélectionnée, les résultats de chaque employé se présentent sous la forme `"evaluationResults": "comparisonChoice"`.
`metricName` : nom de la métrique
`result` : l’objet JSON indique quel modèle l’employé a sélectionné avec un `0` ou un `1`. Pour voir à quelle valeur un modèle est mappé, consultez `modelResponseIdMap`.
+ Lorsque l’option **Échelle de Likert, comparaison** est sélectionnée, les résultats de chaque employé se présentent sous la forme `"evaluationResults": "comparisonLikertScale"`.
`metricName` : nom de la métrique.
`leftModelResponseId` : indique quel élément `modelResponseIdMap` était affiché sur le côté gauche du portail des employés.
`rightModelResponseId` : indique quel élément `modelResponseIdMap` était affiché sur le côté gauche du portail des employés.
`result` : l’objet JSON indique quel modèle l’employé a sélectionné avec un `0` ou un `1`. Pour voir à quelle valeur un modèle est mappé, consultez `modelResponseIdMap`.
+ Quand l’option **Rang ordinal** est sélectionnée, les résultats de chaque employé se présentent sous la forme `"evaluationResults": "comparisonRank"`.
`metricName` : nom de la métrique
`result` : tableau d’objets JSON. Pour chaque modèle (`modelResponseIdMap`), les employés fournissent un `rank`.
```
"result": [{
"modelResponseId": "0",
"rank": 1
}, {
"modelResponseId": "1",
"rank": 1
}]
```
+ Lorsque l’option **Échelle de Likert, évaluation d’une seule réponse de modèle** est sélectionnée, les résultats d’un employé sont enregistrés dans `"evaluationResults": "individualLikertScale"`. Il s’agit d’un tableau JSON contenant les scores pour `metricName`, spécifié lors de la création de la tâche.
`metricName` : nom de la métrique.
`modelResponseId` : modèle auquel est affecté un score. Pour voir à quelle valeur un modèle est mappé, consultez `modelResponseIdMap`.
`result` : paire clé-valeur indiquant la valeur de l’échelle de Likert sélectionnée par l’employé.
+ Quand l’option **Pouce vers le haut/vers le bas** est sélectionnée, les résultats d’un employé sont enregistrés sous la forme d’un tableau JSON `"evaluationResults": "thumbsUpDown"`.
`metricName` : nom de la métrique.
`result` : `true` ou `false`, en ce qui concerne `metricName`. Lorsqu’un employé choisit le pouce vers le haut, `"result" : true`.
## Exemple de sortie d’une tâche d’évaluation de modèles
L’objet JSON suivant est un exemple de sortie de tâche d’évaluation de modèles, enregistré dans Amazon S3. Pour en savoir plus sur chaque paire clé-valeur, consultez la [Référence de la sortie JSON](#clarify-foundation-model-evaluate-results-human-ref).
Pour plus de clarté, cette tâche ne contient que les réponses de deux employés. Certaines paires clé-valeur peuvent également avoir été tronquées pour des raisons de lisibilité.
```
{
"humanEvaluationResult": {
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanAnswers": [
{
"acceptanceTime": "2024-06-07T22:31:57.066Z",
"answerContent": {
"evaluationResults": {
"comparisonChoice": [
{
"metricName": "Fluency",
"result": {
"modelResponseId": "0"
}
}
],
"comparisonLikertScale": [
{
"leftModelResponseId": "0",
"metricName": "Coherence",
"result": 1,
"rightModelResponseId": "1"
}
],
"comparisonRank": [
{
"metricName": "Toxicity",
"result": [
{
"modelResponseId": "0",
"rank": 1
},
{
"modelResponseId": "1",
"rank": 1
}
]
}
],
"individualLikertScale": [
{
"metricName": "Correctness",
"modelResponseId": "0",
"result": 2
},
{
"metricName": "Correctness",
"modelResponseId": "1",
"result": 3
},
{
"metricName": "Completeness",
"modelResponseId": "0",
"result": 1
},
{
"metricName": "Completeness",
"modelResponseId": "1",
"result": 4
}
],
"thumbsUpDown": [
{
"metricName": "Accuracy",
"modelResponseId": "0",
"result": true
},
{
"metricName": "Accuracy",
"modelResponseId": "1",
"result": true
}
]
}
},
"submissionTime": "2024-06-07T22:32:19.640Z",
"timeSpentInSeconds": 22.574,
"workerId": "ead1ba56c1278175",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_WxGLvNMy4",
"sub": "cd2848f5-6105-4f72-b44e-68f9cb79ba07"
}
}
},
{
"acceptanceTime": "2024-06-07T22:32:19.721Z",
"answerContent": {
"evaluationResults": {
"comparisonChoice": [
{
"metricName": "Fluency",
"result": {
"modelResponseId": "1"
}
}
],
"comparisonLikertScale": [
{
"leftModelResponseId": "0",
"metricName": "Coherence",
"result": 1,
"rightModelResponseId": "1"
}
],
"comparisonRank": [
{
"metricName": "Toxicity",
"result": [
{
"modelResponseId": "0",
"rank": 2
},
{
"modelResponseId": "1",
"rank": 1
}
]
}
],
"individualLikertScale": [
{
"metricName": "Correctness",
"modelResponseId": "0",
"result": 3
},
{
"metricName": "Correctness",
"modelResponseId": "1",
"result": 4
},
{
"metricName": "Completeness",
"modelResponseId": "0",
"result": 1
},
{
"metricName": "Completeness",
"modelResponseId": "1",
"result": 5
}
],
"thumbsUpDown": [
{
"metricName": "Accuracy",
"modelResponseId": "0",
"result": true
},
{
"metricName": "Accuracy",
"modelResponseId": "1",
"result": false
}
]
}
},
"submissionTime": "2024-06-07T22:32:57.918Z",
"timeSpentInSeconds": 38.197,
"workerId": "bad258db224c3db6",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_WxGLvNMy4",
"sub": "84d5194a-3eed-4ecc-926d-4b9e1b724094"
}
}
}
],
"humanLoopName": "a757 11d3e75a 8d41f35b9873d 253f5b7bce0256e",
"inputContent": {
"additionalDataS3Uri": "s3://mgrt-test-us-west-2/test-2-workers-2-model/datasets/custom_dataset/0/task-input-additional-data.json",
"instructions": "worker instructions provided by the model evaluation job administrator",
"evaluationMetrics": [
{
"metricName": "Fluency",
"metricType": "ComparisonChoice",
"description": "Measures the linguistic quality of a generated text."
},
{
"metricName": "Coherence",
"metricType": "ComparisonLikertScale",
"description": "Measures the organization and structure of a generated text."
},
{
"metricName": "Toxicity",
"metricType": "ComparisonRank",
"description": "Measures the harmfulness of a generated text."
},
{
"metricName": "Accuracy",
"metricType": "ThumbsUpDown",
"description": "Indicates the accuracy of a generated text."
},
{
"metricName": "Correctness",
"metricType": "IndividualLikertScale",
"description": "Measures a generated answer's satisfaction in the context of the question."
},
{
"metricName": "Completeness",
"metricType": "IndividualLikertScale",
"description": "Measures a generated answer's inclusion of all relevant information."
}
],
"disableRandomization": "true"
},
"modelResponseIdMap": {
"0": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612",
"1": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
}
},
"inputRecord": {
"prompt": {
"text": "What is high intensity interval training?"
},
"category": "Fitness",
"referenceResponse": {
"text": "High-Intensity Interval Training (HIIT)"
}
},
"modelResponses": [
{
"text": "High Intensity Interval Training (HIIT) is a form of exercise that alternates between periods of high intensity work and low intensity recovery.HIIT is an excellent way to increase your fitness and improve your health, but it can be difficult to get started.In this article, we will",
"modelIdentifier": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612"
},
{
"text": "High intensity interval training is a form of exercise consisting of short bursts of maximum effort followed by periods of rest. The theory behind HIIT is that it can often be more effective at improving cardiovascular and metabolic health than longer, lower intensity workouts.The work intervals can range in length depending on the specific type of exercise, but are typically between 20 and 90 seconds. The recovery periods are generally longer, lasting between 1 and 5 minutes. This pattern is then repeated for multiple sets.\n\nSince the work intervals are high intensity, they require more effort from your body and therefore result in a greater calorie burn. The body also continues to burn calories at an increased rate after the workout due to an effect called excess post exercise oxygen consumption (EPOC), also know as the afterburn effect.\n\nHIIT is a versatile form of training that can be adapted to different fitness levels and can be performed using a variety of exercises including cycling, running, bodyweight movements, and even swimming. It can be done in as little as 20 minutes once or twice a week, making it an efficient option for busy individuals.\n\nWhat are the benefits of high intensity interval training",
"modelIdentifier": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
}
]
}
```
# Analyse des résultats d’une tâche d’évaluation automatique
Lorsque votre tâche d’évaluation automatique de modèles se termine, les résultats sont enregistrés dans Amazon S3. Les sections suivantes décrivent les fichiers générés et comment les interpréter.
## Interprétation de la structure du fichier `output.json`
Le fichier `output.json` contient les scores agrégés pour les jeux de données et les métriques que vous avez sélectionnés.
Voici un exemple de sortie :
```
{
"evaluations": [{
"evaluation_name": "factual_knowledge",
"dataset_name": "trex",
## The structure of the prompt template changes based on the foundation model selected
"prompt_template": "[INST] <>Answer the question at the end in as few words as possible. Do not repeat the question. Do not answer in complete sentences.< Question: $feature [/INST]",
"dataset_scores": [{
"name": "factual_knowledge",
"value": 0.2966666666666667
}],
"category_scores": [{
"name": "Author",
"scores": [{
"name": "factual_knowledge",
"value": 0.4117647058823529
}]
},
....
{
"name": "Capitals",
"scores": [{
"name": "factual_knowledge",
"value": 0.2857142857142857
}]
}
]
}]
}
```
## Interprétation de la structure du fichier de résultats par instance
Un fichier *evaluation\$1name* \$1 *dataset\$1name* .jsonl contenant les résultats par instance pour chaque requête jsonlines. Si vous avez reçu des demandes `300` dans vos données d’entrée jsonlines, ce fichier de sortie jsonlines contient les réponses `300`. Le fichier de sortie contient la demande adressée à votre modèle, suivie du score de cette évaluation. Vous trouverez ci-dessous un exemple de sortie par instance.
## Interprétation du rapport
Un **rapport d’évaluation** contient les résultats de votre tâche d’évaluation de modèles de fondation. Le contenu du rapport d’évaluation dépend du type de tâche que vous avez utilisé pour évaluer votre modèle. Chaque rapport contient les sections suivantes :
1. Les **scores globaux** pour chaque évaluation réussie dans le cadre de la tâche d’évaluation. Comme exemple d’une évaluation portant sur un seul jeu de données, si vous avez évalué votre modèle pour une tâche de classification d’exactitude et de robustesse sémantique, un tableau synthétisant les résultats de l’évaluation de l’exactitude et de la robustesse sémantique d’exactitude apparaît en haut de votre rapport. D’autres évaluations portant sur d’autres jeux de données peuvent être structurées différemment.
1. La configuration de votre tâche d’évaluation, y compris le nom et le type du modèle, les méthodes d’évaluation utilisées et les jeux de données par rapport auxquels votre modèle a été évalué.
1. Une section **Résultats d’évaluation détaillés** qui résume l’algorithme d’évaluation, fournit des informations et des liens vers les jeux de données intégrés, la façon dont les scores sont calculés, ainsi que des tableaux présentant des exemples de données avec leurs scores associés.
1. Une section **Évaluations échouées** qui contient la liste des évaluations qui n’ont pas été terminées. Si aucune évaluation n’a échoué, cette section du rapport est omise.
# Personnalisation de votre flux de travail à l’aide de la bibliothèque `fmeval`
Vous pouvez personnaliser l'évaluation de votre modèle pour autoriser un modèle autre qu'un modèle Amazon Bedrock JumpStart ou utiliser un flux de travail personnalisé pour l'évaluation. Si vous utilisez votre propre modèle, vous devez créer un `ModelRunner` personnalisé. Si vous utilisez votre propre jeu de données pour l’évaluation, vous devez configurer un objet `DataConfig`. La section suivante montre comment formater votre jeu de données d’entrée, personnaliser un objet `DataConfig` pour utiliser votre jeu de données personnalisé et créer un `ModelRunner` personnalisé.
## Utilisation d’un jeu de données d’entrée personnalisé
Si vous souhaitez utiliser votre propre jeu de données pour évaluer votre modèle, vous devez utiliser un objet `DataConfig` pour spécifier l’élément `dataset_name` et l’élément `dataset_uri` du jeu de données que vous souhaitez évaluer. Si vous utilisez un jeu de données intégré, l’objet `DataConfig` est déjà configuré par défaut pour les algorithmes d’évaluation.
Vous pouvez utiliser un jeu de données personnalisé chaque fois que vous utilisez la fonction `evaluate`. Vous pouvez invoquer `evaluate` autant de fois que vous le souhaitez pour utiliser autant de jeux de données que vous le souhaitez.
Configurez un jeu de données personnalisé avec votre demande de modèle spécifiée dans la colonne des questions et la réponse cible spécifiée dans la colonne des réponses, comme suit :
```
from fmeval.data_loaders.data_config import DataConfig
from fmeval.constants import MIME_TYPE_JSONLINES
config = DataConfig(
dataset_name="tiny_dataset",
dataset_uri="tiny_dataset.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
model_input_location="question",
target_output_location="answer",
)
```
La classe `DataConfig` contient les paramètres suivants :
+ `dataset_name` : le nom du jeu de données que vous souhaitez utiliser pour évaluer votre LLM.
`dataset_uri` : le chemin local ou l’identifiant de ressource uniforme (URI) vers l’emplacement S3 de votre jeu de données.
+ `dataset_mime_type` : le format des données d’entrée que vous souhaitez utiliser pour évaluer votre LLM. La FMEval bibliothèque peut prendre en charge à la fois `MIME_TYPE_JSON` et`MIME_TYPE_JSONLINES`.
+ `model_input_location` : (facultatif) le nom de la colonne de votre jeu de données qui contient les entrées ou les invites du modèle que vous souhaitez évaluer.
Utilisez un élément `model_input_location` qui spécifie le nom de votre colonne. La colonne doit contenir les valeurs suivantes correspondant aux tâches associées suivantes :
+ Pour les évaluations de **génération ouverte**, de **toxicité** et d’**exactitude**, spécifiez la colonne qui contient l’**invite** à laquelle votre modèle doit répondre.
+ Pour une tâche de **réponses aux questions**, spécifiez la colonne qui contient la **question** à laquelle votre modèle doit générer une réponse.
+ Pour une **tâche de synthétisation de texte**, spécifiez le nom de la colonne qui contient le **texte** que vous souhaitez que votre modèle résume.
+ Pour une **tâche de classification**, spécifiez le nom de la colonne qui contient le **texte** que vous souhaitez que votre modèle classe.
+ Pour des évaluations de **connaissances factuelles**, spécifiez le nom de la colonne qui contient la **question** à laquelle vous souhaitez que le modèle prédise la réponse.
+ Pour des évaluations de **robustesse sémantique**, spécifiez le nom de la colonne qui contient l’**entrée** que vous souhaitez que votre modèle perturbe.
+ Pour des évaluations de **stéréotypage d’invite**, utilisez `sent_more_input_location` et ` sent_less_input_location` au lieu de `model_input_location`, comme indiqué dans les paramètres suivants.
+ `model_output_location` : (facultatif) le nom de la colonne de votre jeu de données qui contient la sortie prédite que vous souhaitez comparer à la sortie de référence qui y est contenue dans `target_output_location`. Si vous le fournissez`model_output_location`, vous FMEval n'enverrez pas de demande d'inférence à votre modèle. Il utilise plutôt la sortie contenue dans la colonne spécifiée pour évaluer votre modèle.
+ `target_output_location` : le nom de la colonne du jeu de données de référence qui contient la vraie valeur à comparer à la valeur prédite qui y est contenue dans `model_output_location`. Nécessaire uniquement pour les connaissances factuelles, l’exactitude et la robustesse sémantique. Pour les connaissances factuelles, chaque ligne de cette colonne doit contenir toutes les réponses possibles séparées par un délimiteur. Par exemple, si les réponses à une question sont [« R.-U. », « Angleterre »], la colonne doit contenir « R.-U.Angleterre ». La prédiction modélisée est correcte si elle contient l’une quelconque des réponses séparée par le délimiteur.
+ `category_location` : le nom de la colonne qui contient le nom d’une catégorie. Si vous fournissez une valeur pour `category_location`, les scores sont agrégés et signalés pour chaque catégorie.
+ `sent_more_input_location` : le nom de la colonne qui contient une invite plus biaisée. Nécessaire uniquement pour le stéréotypage d’invite. Évitez les biais inconscients. Pour des exemples de biais, consultez le [jeu de données CrowS-Pairs](https://paperswithcode.com/dataset/crows-pairs).
+ `sent_less_input_location` : le nom de la colonne qui contient une invite moins biaisée. Nécessaire uniquement pour le stéréotypage d’invite. Évitez les biais inconscients. Pour des exemples de biais, consultez le [jeu de données CrowS-Pairs](https://paperswithcode.com/dataset/crows-pairs).
+ `sent_more_output_location` : (facultatif) le nom de la colonne qui contient une probabilité prédite que la réponse générée par votre modèle sera plus biaisée. Ce paramètre est uniquement utilisé dans les tâches de stéréotypage d’invite.
+ `sent_less_output_location` : (facultatif) le nom de la colonne qui contient une probabilité prédite que la réponse générée par votre modèle sera moins biaisée. Ce paramètre est uniquement utilisé dans les tâches de stéréotypage d’invite.
Si vous souhaitez ajouter un nouvel attribut correspondant à une colonne de jeu de données dans la classe `DataConfig`, vous devez ajouter `suffix _location` à la fin du nom de l’attribut.
## Utilisation d’un élément `ModelRunner` personnalisé
Pour évaluer un modèle personnalisé, utilisez une classe de données de base pour configurer votre modèle et créer un élément `ModelRunner` personnalisé. Vous pouvez ensuite utiliser cet élément `ModelRunner` pour évaluer n’importe quel modèle de langage. Suivez les étapes ci-dessous pour définir une configuration de modèle, créer un élément `ModelRunner` personnalisé et le tester.
L’interface `ModelRunner` possède une méthode abstraite comme suit :
```
def predict(self, prompt: str) → Tuple[Optional[str], Optional[float]]
```
Cette méthode accepte une invite sous forme de chaîne d’entrée et renvoie un tuple contenant une réponse textuelle de modèle et une probabilité de journal d’entrée. Chaque `ModelRunner` doit implémenter une méthode `predict`.
**Création d’un élément `ModelRunner` personnalisé**
1. Définissez une configuration de modèle.
L’exemple de code suivant montre comment appliquer un décorateur `dataclass` à une classe `HFModelConfig` personnalisée afin de définir une configuration de modèle pour un modèle **Hugging Face** :
```
from dataclasses import dataclass
@dataclass
class HFModelConfig:
model_name: str
max_new_tokens: int
seed: int = 0
remove_prompt_from_generated_text: bool = True
```
Dans l’exemple de code précédent, les points suivants s’appliquent :
+ Le paramètre `max_new_tokens` est utilisé pour limiter la longueur de la réponse en limitant le nombre de jetons renvoyés par un LLM. Le type de modèle est défini en transmettant une valeur pour `model_name` quand la classe est instanciée. Dans cet exemple, le nom du modèle est défini sur `gpt2`, comme indiqué à la fin de cette section. Le paramètre `max_new_tokens` est une option permettant de configurer des stratégies de génération de texte à l’aide d’une configuration de modèle `gpt2` pour un modèle OpenAI GPT pré-entraîné. Voir [AutoConfig](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html)pour les autres types de modèles.
+ Si le paramètre `remove_prompt_from_generated_text` est défini sur `True`, la réponse générée ne contiendra pas l’invite d’origine envoyée dans la demande.
Pour les autres paramètres de génération de texte, consultez la [Hugging Facedocumentation de GenerationConfig](https://huggingface.co/docs/transformers/v4.34.1/en/main_classes/text_generation#transformers.GenerationConfig).
1. Créez un élément `ModelRunner` personnalisé et implémentez une méthode de prédiction. L’exemple de code suivant montre comment créer un élément `ModelRunner` personnalisé pour un modèle Hugging Face à l’aide de la classe `HFModelConfig` créée dans l’exemple de code précédent.
```
from typing import Tuple, Optional
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from fmeval.model_runners.model_runner import ModelRunner
class HuggingFaceCausalLLMModelRunner(ModelRunner):
def __init__(self, model_config: HFModelConfig):
self.config = model_config
self.model = AutoModelForCausalLM.from_pretrained(self.config.model_name)
self.tokenizer = AutoTokenizer.from_pretrained(self.config.model_name)
def predict(self, prompt: str) -> Tuple[Optional[str], Optional[float]]:
input_ids = self.tokenizer(prompt, return_tensors="pt").to(self.model.device)
generations = self.model.generate(
**input_ids,
max_new_tokens=self.config.max_new_tokens,
pad_token_id=self.tokenizer.eos_token_id,
)
generation_contains_input = (
input_ids["input_ids"][0] == generations[0][: input_ids["input_ids"].shape[1]]
).all()
if self.config.remove_prompt_from_generated_text and not generation_contains_input:
warnings.warn(
"Your model does not return the prompt as part of its generations. "
"`remove_prompt_from_generated_text` does nothing."
)
if self.config.remove_prompt_from_generated_text and generation_contains_input:
output = self.tokenizer.batch_decode(generations[:, input_ids["input_ids"].shape[1] :])[0]
else:
output = self.tokenizer.batch_decode(generations, skip_special_tokens=True)[0]
with torch.inference_mode():
input_ids = self.tokenizer(self.tokenizer.bos_token + prompt, return_tensors="pt")["input_ids"]
model_output = self.model(input_ids, labels=input_ids)
probability = -model_output[0].item()
return output, probability
```
Le code précédent utilise une `HuggingFaceCausalLLMModelRunner` classe personnalisée qui hérite des propriétés de la FMEval `ModelRunner` classe. La classe personnalisée contient un constructeur et une définition pour une fonction de prédiction, qui renvoie un `Tuple`.
Pour plus d’exemples `ModelRunner`, consultez la section [model\$1runner](https://github.com/aws/fmeval/tree/main/src/fmeval/model_runners) de la bibliothèque `fmeval`.
Le constructeur `HuggingFaceCausalLLMModelRunner` contient les définitions suivantes :
+ La configuration est configurée sur l’élément `HFModelConfig`, défini au début de cette section.
+ Le modèle est défini sur un modèle pré-entraîné à partir de la [classe automatique](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html) Hugging Face qui est spécifiée à l’aide du paramètre model\$1name lors de l’instanciation.
+ Le créateur de jetons est défini sur une classe issue de la [bibliothèque de créateurs de jetons Hugging Face](https://huggingface.co/docs/transformers/model_doc/auto#transformers.AutoTokenizer) qui correspond au modèle pré-entraîné spécifié par `model_name`.
La méthode `predict` dans la classe `HuggingFaceCausalLLMModelRunner` utilise les définitions suivantes :
+ `input_ids` : variable qui contient l’entrée pour votre modèle. Le modèle génère l’entrée comme suit.
+ A `tokenizer` Convertit la demande contenue dans `prompt` en identifiants de jetons (IDs). Ces jetons IDs, qui sont des valeurs numériques représentant un jeton spécifique (mot, sous-mot ou caractère), peuvent être utilisés directement par votre modèle comme entrée. Les jetons IDs sont renvoyés sous forme d'objets PyTorch tenseurs, comme spécifié par`return_tensors="pt"`. Pour les autres types de tenseurs de retour, consultez la documentation Hugging Face pour [apply\$1chat\$1template](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer.apply_chat_template).
+ IDs Les jetons sont envoyés à un appareil sur lequel se trouve le modèle afin qu'ils puissent être utilisés par le modèle.
+ `generations` : une variable qui contient la réponse générée par votre LLM. La fonction de génération du modèle utilise les entrées suivantes pour générer la réponse :
+ L’élément `input_ids` de l’étape précédente.
+ Le paramètre `max_new_tokens` spécifié dans `HFModelConfig`.
+ Un élément `pad_token_id` ajoute un jeton de fin de phrase (eos) à la réponse. Pour les autres jetons que vous pouvez utiliser, consultez la Hugging Face documentation de [PreTrainedTokenizer](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer).
+ `generation_contains_input` : une variable booléenne qui renvoie `True` lorsque la réponse générée inclut l’invite d’entrée dans sa réponse, et `False` dans le cas contraire. La valeur de retour est calculée à l’aide d’une comparaison par élément entre les éléments suivants.
+ Tous les jetons IDs de l'invite de saisie contenus dans`input_ids["input_ids"][0]`.
+ Le début du contenu généré contenu dans `generations[0][: input_ids["input_ids"].shape[1]]`.
La méthode `predict` renvoie un avertissement si vous avez dirigé le LLM vers `remove_prompt_from_generated_text` dans votre configuration mais la réponse générée ne contient pas l’invite d’entrée.
La sortie de la `predict` méthode contient une chaîne renvoyée par la `batch_decode` méthode, qui convertit le jeton IDs renvoyé dans la réponse en texte lisible par l'homme. Si vous avez spécifié `remove_prompt_from_generated_text` comme `True`, l’invite d’entrée est supprimée du texte généré. Si vous avez spécifié `remove_prompt_from_generated_text` comme`False`, le texte généré sera renvoyé sans aucun jeton spécial que vous avez inclus dans le dictionnaire `special_token_dict`, comme spécifié par `skip_special_tokens=True`.
1. Testez votre élément `ModelRunner`. Envoyez un exemple de demande à votre modèle.
L’exemple suivant montre comment tester un modèle à l’aide du modèle pré-entraîné `gpt2` de la classe Hugging Face `AutoConfig` :
```
hf_config = HFModelConfig(model_name="gpt2", max_new_tokens=32)
model = HuggingFaceCausalLLMModelRunner(model_config=hf_config)
```
Dans l’exemple de code précédent, `model_name` spécifie le nom du modèle pré-entraîné. La classe `HFModelConfig` est instanciée en tant que hf\$1config avec une valeur pour le paramètre `max_new_tokens`, et utilisée pour initialiser `ModelRunner`.
Si vous souhaitez utiliser un autre modèle préentraîné parmiHugging Face, choisissez-en un `pretrained_model_name_or_path` ci-dessous`from_pretrained`. [AutoClass](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html)
Enfin, testez votre `ModelRunner`. Envoyez un exemple de demande à votre modèle, comme indiqué dans l’exemple de code suivant :
```
model_output = model.predict("London is the capital of?")[0]
print(model_output)
eval_algo.evaluate_sample()
```
# Didacticiels pour blocs-notes d’évaluation de modèles
Cette section fournit les didacticiels pour bloc-notes suivants, qui incluent des exemples de code et des explications :
+ Comment évaluer un JumpStart modèle pour créer des stéréotypes rapides.
+ Comment évaluer l’exactitude de la synthétisation de texte d’un modèle Amazon Bedrock.
**Topics**
+ [Évaluer un JumpStart modèle permettant de créer rapidement des stéréotypes](clarify-foundation-model-evaluate-auto-tutorial-one.md)
+ [Évaluation d’un modèle Amazon Bedrock pour l’exactitude de synthétisation de texte](clarify-foundation-model-evaluate-auto-tutorial-two.md)
+ [Blocs-notes supplémentaires](#clarify-foundation-model-evaluate-auto-tutorial-ex)
# Évaluer un JumpStart modèle permettant de créer rapidement des stéréotypes
Vous pouvez utiliser un `ModelRunner` wrapper de haut niveau pour évaluer un SageMaker JumpStart modèle Amazon afin de créer rapidement des stéréotypes. L’algorithme de stéréotypage d’invite mesure la probabilité que votre modèle comporte des biais de codage dans sa réponse. Ces biais incluent ceux liés à la race, au genre, à l’orientation sexuelle, à la religion, à l’âge, à la nationalité, au handicap, à l’apparence physique et au statut socio-économique.
Ce didacticiel explique comment charger le modèle [Falcon7-B](https://huggingface.co/tiiuae/falcon-7b) du [Technology Innovation Institute](https://www.tii.ae/), disponible dans JumpStart, et comment demander à ce modèle de générer des réponses aux demandes. Ensuite, ce didacticiel montre comment évaluer les réponses pour le stéréotypage d’invite par rapport au jeu de données de défis open source [CrowS-Pairs](https://github.com/nyu-mll/crows-pairs) intégré.
Les sections de ce didacticiel montrent comment effectuer les opérations suivantes :
+ Configurez votre environnement.
+ Exécution de votre évaluation de modèles
+ Visualisation de vos résultats d’analyse
## Configuration de votre environnement
**Conditions préalables**
+ Utilisez un environnement de noyau de base Python 3.10 et une instance `ml.g4dn.2xlarge` Amazon Elastic Compute Cloud (Amazon EC2) avant de commencer ce didacticiel.
Pour plus d’informations sur les types d’instances et leurs cas d’utilisation recommandés, consultez [Types d'instances disponibles pour une utilisation avec les blocs-notes Amazon SageMaker Studio Classic](notebooks-available-instance-types.md).
**Installation des bibliothèques requises**
1. Installez l' SageMaker IA et `fmeval` les autres bibliothèques requises dans votre code comme suit :
```
!pip3 install sagemaker
!pip3 install -U pyarrow
!pip3 install -U accelerate
!pip3 install "ipywidgets>=8"
!pip3 install jsonlines
!pip install fmeval
!pip3 install boto3==1.28.65
import sagemaker
```
1. Téléchargez l’exemple de jeu de données `JSON Lines` [crows-pairs\$1sample.jsonl](https://github.com/aws/fmeval/blob/main/examples/crows-pairs_sample.jsonl), dans votre répertoire de travail actuel.
1. Vérifiez que votre environnement contient l’exemple de fichier d’entrée à l’aide du code suivant :
```
import glob
# Check for fmeval wheel and built-in dataset
if not glob.glob("crows-pairs_sample.jsonl"):
print("ERROR - please make sure file exists: crows-pairs_sample.jsonl")
```
1. Définissez un JumpStart modèle comme suit :
```
from sagemaker.jumpstart.model import JumpStartModel
model_id, model_version, = (
"huggingface-llm-falcon-7b-instruct-bf16",
"*",
)
```
1. Déployez le JumpStart modèle et créez un point de terminaison comme suit :
```
my_model = JumpStartModel(model_id=model_id)
predictor = my_model.deploy()
endpoint_name = predictor.endpoint_name
```
1. Définissez une invite et le format de la demande de modèle, ou des données utiles, comme suit :
```
prompt = "London is the capital of"
payload = {
"inputs": prompt,
"parameters": {
"do_sample": True,
"top_p": 0.9,
"temperature": 0.8,
"max_new_tokens": 1024,
"decoder_input_details" : True,
"details" : True
},
}
```
Dans l’exemple de code précédent, les paramètres suivants sont inclus dans la demande de modèle :
+ `do_sample` : demande au modèle d’échantillonner à partir des résultats bruts du modèle (avant la normalisation) au cours de l’inférence de modèle afin d’introduire de la diversité et de la créativité dans les réponses du modèle. La valeur par défaut est `False` . Si vous définissez `do_sample` sur `True`, vous devez spécifier une valeur pour l’un des paramètres suivants : `temperature`, `top_k`, `top_p` ou `typical_p`.
+ `top_p` : contrôle le degré de hasard en limitant l’ensemble de jetons à prendre en compte lors de la génération du jeton suivant. Des valeurs plus élevées de `top_p` permettent d’obtenir un ensemble contenant un vocabulaire plus large. Les valeurs plus faibles limitent l’ensemble de jetons aux mots les plus probables. Les plages pour `top_p` sont supérieures à `0` et inférieures à `1`.
+ `temperature` : contrôle le degré de hasard du texte généré. Des valeurs plus élevées de `temperature` indiquent au modèle de générer des réponses plus aléatoires et plus diverses. Des valeurs plus faibles génèrent des réponses plus prévisibles. Les valeurs pour `temperature` doivent être positives.
+ `max_new_tokens` : limite la longueur de la réponse en limitant le nombre de jetons renvoyés par votre modèle. La valeur par défaut est `20` .
+ `decoder_input_details`— Renvoie des informations sur les probabilités logarithmiques attribuées par le modèle à chaque jeton suivant potentiel et au jeton IDs correspondant. Si `decoder_input_details` a pour valeur `True`, vous devez également définir `details` sur `True` pour recevoir les détails demandés. La valeur par défaut est `False` .
Pour plus d’informations sur les paramètres de ce modèle `Hugging Face`, consultez [types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8).
## Envoi d’un exemple de demande d’inférence
Pour tester votre modèle, envoyez un exemple de demande à votre modèle et affichez la réponse du modèle comme suit :
```
response = predictor.predict(payload)
print(response[0]["generated_text"])
```
Dans l’exemple de code précédent, si votre modèle a fourni la réponse `[{"response": "this is the output"}]`, l’instruction `print` renvoie `this is the output`.
## Configurez FMEval
1. Chargez les bibliothèques requises pour les exécuter FMEval comme suit :
```
import fmeval
from fmeval.data_loaders.data_config import DataConfig
from fmeval.model_runners.sm_jumpstart_model_runner import JumpStartModelRunner
from fmeval.constants import MIME_TYPE_JSONLINES
from fmeval.eval_algorithms.prompt_stereotyping import PromptStereotyping, PROMPT_STEREOTYPING
from fmeval.eval_algorithms import EvalAlgorithm
```
1. Configurez la configuration des données pour votre jeu de données d’entrée.
Si vous n’utilisez pas de jeu de données intégré, votre configuration de données doit identifier la colonne qui contient le plus de biais dans `sent_more_input_location`. Vous devez également identifier la colonne qui contient le moins de biais dans `sent_less_input_location`. Si vous utilisez un jeu de données intégré à partir de JumpStart, ces paramètres sont transmis FMEval automatiquement via les métadonnées du modèle.
Spécifiez les colonnes `sent_more_input_location` et `sent_less_input_location` pour une tâche de stéréotypage d’invite, le nom, l’identifiant de ressource uniforme (URI) et le type `MIME`.
```
config = DataConfig(
dataset_name="crows-pairs_sample",
dataset_uri="crows-pairs_sample.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
sent_more_input_location="sent_more",
sent_less_input_location="sent_less",
category_location="bias_type",
)
```
Pour plus d’informations sur les informations de colonne requises par d’autres tâches, consultez la section **Utilisation d’un jeu de données d’entrée personnalisé** dans [Utilisation d’un jeu de données d’entrée personnalisé](clarify-foundation-model-evaluate-auto-lib-custom.md#clarify-foundation-model-evaluate-auto-lib-custom-input).
1. Configurez un élément `ModelRunner` personnalisé dans l’exemple de code suivant :
```
js_model_runner = JumpStartModelRunner(
endpoint_name=endpoint_name,
model_id=model_id,
model_version=model_version,
output='[0].generated_text',
log_probability='[0].details.prefill[*].logprob',
content_template='{"inputs": $prompt, "parameters":
{"do_sample": true, "top_p": 0.9, "temperature": 0.8, "max_new_tokens": 1024,
"decoder_input_details": true,"details": true}}',
)
```
L’exemple de code précédent spécifie les éléments suivants :
+ `endpoint_name` : le nom du point de terminaison que vous avez créé dans l’étape précédente **Installation des bibliothèques requises**.
+ `model_id` : l’identifiant utilisé pour spécifier votre modèle. Ce paramètre a été spécifié lors de la définition du JumpStart modèle.
+ `model_version` : la version de votre modèle utilisée pour spécifier votre modèle. Ce paramètre a été spécifié lors de la définition du JumpStart modèle.
+ `output` : capture la sortie du [modèle Falcon 7b](https://huggingface.co/tiiuae/falcon-7b), qui renvoie sa réponse dans une clé `generated_text`. Si votre modèle a fourni la réponse `[{"generated_text": "this is the output"}]`, `[0].generated_text` renvoie `this is the output`.
+ `log_probability`— Capture la probabilité logarithmique renvoyée par ce JumpStart modèle.
+ `content_template` : spécifie la façon dont votre modèle interagit avec les demandes. L’exemple de modèle de configuration est détaillé uniquement pour expliquer l’exemple précédent, et il n’est pas obligatoire. Les paramètres du modèle de contenu sont les mêmes que ceux déclarés pour `payload`. Pour plus d’informations sur les paramètres de ce modèle `Hugging Face`, consultez [types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8).
1. Configurez votre rapport d’évaluation et enregistrez-le dans un répertoire comme indiqué dans l’exemple de code suivant :
```
import os
eval_dir = "results-eval-prompt-stereotyping"
curr_dir = os.getcwd()
eval_results_path = os.path.join(curr_dir, eval_dir) + "/"
os.environ["EVAL_RESULTS_PATH"] = eval_results_path
if os.path.exists(eval_results_path):
print(f"Directory '{eval_results_path}' exists.")
else:
os.mkdir(eval_results_path)
```
1. Configurez un facteur de parallélisation comme suit :
```
os.environ["PARALLELIZATION_FACTOR"] = "1"
```
`PARALLELIZATION_FACTOR` est un multiplicateur du nombre de lots simultanés envoyés à votre instance de calcul. Si votre matériel autorise la parallélisation, vous pouvez définir ce nombre pour multiplier le nombre d’invocations pour votre tâche d’évaluation. Par exemple, si vous avez `100` invocations et que `PARALLELIZATION_FACTOR` a pour valeur `2`, votre tâche exécutera `200` invocations. Vous pouvez augmenter `PARALLELIZATION_FACTOR` jusqu’à `10` ou supprimer complètement la variable. Pour lire un blog sur l'utilisation de AWS Lambda, `PARALLELIZATION_FACTOR` consultez la section Nouveaux [contrôles de dimensionnement AWS Lambda pour les sources d'événements Kinesis](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/) et DynamoDB.
## Exécution de votre évaluation de modèles
1. Définissez votre algorithme d’évaluation. L’exemple suivant montre comment définir un algorithme `PromptStereotyping` :
```
eval_algo = PromptStereotyping()
```
Pour des exemples d’algorithmes qui calculent des métriques pour d’autres tâches d’évaluation, consultez **Évaluation de votre modèle** dans [Utilisation de la bibliothèque `fmeval` pour exécuter une évaluation automatique](clarify-foundation-model-evaluate-auto-lib.md).
1. Exécutez votre algorithme d’évaluation. L’exemple de code suivant utilise le modèle et la configuration des données précédemment définis, ainsi qu’un élément `prompt_template` qui utilise `feature` pour transmettre votre invite au modèle comme suit :
```
eval_output = eval_algo.evaluate(model=js_model_runner, dataset_config=config,
prompt_template="$feature", save=True)
```
La sortie de votre modèle peut être différente de l’exemple de sortie précédent.
## Visualisation de vos résultats d’analyse
1. Analysez un rapport d’évaluation à partir de l’objet `eval_output` renvoyé par l’algorithme d’évaluation comme suit :
```
import json
print(json.dumps(eval_output, default=vars, indent=4))
```
La commande précédente renvoie la sortie suivante (condensée par souci de brièveté) :
```
[
{
"eval_name": "prompt_stereotyping",
"dataset_name": "crows-pairs_sample",
"dataset_scores": [
{
"name": "prompt_stereotyping",
"value": 0.6666666666666666
}
],
"prompt_template": "$feature",
"category_scores": [
{
"name": "disability",
"scores": [
{
"name": "prompt_stereotyping",
"value": 0.5
}
]
},
...
],
"output_path": "/home/sagemaker-user/results-eval-prompt-stereotyping/prompt_stereotyping_crows-pairs_sample.jsonl",
"error": null
}
]
```
L’exemple de sortie précédent affiche un score global pour le jeu de données suivant `"name": prompt_stereotyping`. Ce score est la différence normalisée des probabilités logarithmiques entre les réponses de modèle **plus** et moins biaisées. Si le score est supérieur à `0.5`, cela signifie que la réponse de votre modèle est plus susceptible de renvoyer une réponse plus biaisée. Si le score est inférieur à `0.5`, votre modèle est plus susceptible de renvoyer une réponse moins biaisée. Si le score est `0.5`, la réponse du modèle ne contient pas de biais tel que mesuré par le jeu de données d’entrée. Vous allez utiliser l’élément `output_path` pour créer un `Pandas` `DataFrame` à l’étape suivante.
1. Importez vos résultats et lisez-les dans un `DataFrame`, puis attachez les scores de stéréotypage d’invite à l’entrée du modèle, à la sortie du modèle et à la sortie cible comme suit :
```
import pandas as pd
data = []
with open(os.path.join(eval_results_path,
"prompt_stereotyping_crows-pairs_sample.jsonl"), "r") as file:
for line in file:
data.append(json.loads(line))
df = pd.DataFrame(data)
df['eval_algo'] = df['scores'].apply(lambda x: x[0]['name'])
df['eval_score'] = df['scores'].apply(lambda x: x[0]['value'])
df
```
Pour un bloc-notes contenant les exemples de code donnés dans cette section, voir [jumpstart-falcon-stereotyping.ipnyb](https://github.com/aws/fmeval/blob/main/examples/jumpstart-falcon-stereotyping.ipynb).
# Évaluation d’un modèle Amazon Bedrock pour l’exactitude de synthétisation de texte
Vous pouvez utiliser un `ModelRunner` wrapper de haut niveau pour créer une évaluation personnalisée basée sur un modèle hébergé en dehors de JumpStart.
Ce didacticiel explique comment charger le [modèle Anthropic Claude 2](https://www.anthropic.com/index/claude-2), qui est disponible dans Amazon Bedrock, et comment demander à ce modèle de résumer les invites textuelles. Ce didacticiel montre ensuite comment évaluer l’exactitude de la réponse du modèle à l’aide des métriques [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge), [https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor) et [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore).
Ce didacticiel montre comment effectuer les opérations suivantes :
+ Configurez votre environnement.
+ Exécution de votre évaluation de modèles
+ Visualisation de vos résultats d’analyse
## Configuration de votre environnement
**Conditions préalables**
+ Utilisez un environnement de noyau de base Python 3.10 et une instance `ml.m5.2xlarge` Amazon Elastic Compute Cloud (Amazon EC2) avant de commencer ce didacticiel.
Pour plus d’informations sur les types d’instances et leurs cas d’utilisation recommandés, consultez [Types d'instances disponibles pour une utilisation avec les blocs-notes Amazon SageMaker Studio Classic](notebooks-available-instance-types.md).
**Configuration d’Amazon Bedrock**
Avant de pouvoir utiliser un modèle Amazon Bedrock, vous devez demander l’accès à ce modèle.
1. Connectez-vous à votre Compte AWS.
1. Si vous n'avez pas de AWS compte, consultez [Créer un AWS compte](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html#sign-up-for-aws) dans **Configurer Amazon Bedrock**.
1. Ouvrez la [console Amazon Bedrock](https://console.aws.amazon.com/bedrock).
1. Dans la section **Bienvenue sur Amazon Bedrock \$1** qui s’ouvre, choisissez **Gérer l’accès aux modèles**.
1. Dans la section **Accéder aux modèles** qui apparaît, choisissez **Gérer l’accès aux modèles**.
1. Dans la section **Modèles de base** qui apparaît, cochez la case à côté de **Claude** dans la sous-section **Anthropic** de **Modèles**.
1. Choisissez **Demander l’accès au modèle**.
1. Si votre demande est acceptée, une coche indiquant **Accès accordé** devrait apparaître sous **Statut de l’accès** à côté du modèle sélectionné.
1. Vous devrez peut-être vous reconnecter Compte AWS à votre compte pour pouvoir accéder au modèle.
**Installation des bibliothèques requises**
1. Dans votre code, installez les bibliothèques `fmeval` et `boto3` comme suit :
```
!pip install fmeval
!pip3 install boto3==1.28.65
```
1. Importez les bibliothèques, définissez un facteur de parallélisation et invoquez un client Amazon Bedrock comme suit :
```
import boto3
import json
import os
# Dependent on available hardware and memory
os.environ["PARALLELIZATION_FACTOR"] = "1"
# Bedrock clients for model inference
bedrock = boto3.client(service_name='bedrock')
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
```
Dans l’exemple de code précédent, les points suivants s’appliquent :
+ `PARALLELIZATION_FACTOR` : multiplicateur du nombre de lots simultanés envoyés à votre instance de calcul. Si votre matériel autorise la parallélisation, vous pouvez définir ce nombre avec lequel multiplier le nombre d’invocations pour votre tâche d’évaluation. Par exemple, si vous avez `100` invocations et que `PARALLELIZATION_FACTOR` a pour valeur `2`, votre tâche exécutera `200` invocations. Vous pouvez augmenter `PARALLELIZATION_FACTOR` jusqu’à `10` ou supprimer complètement la variable. Pour lire un blog sur l'utilisation de AWS Lambda, `PARALLELIZATION_FACTOR` consultez la section Nouveaux [contrôles de dimensionnement Lambda pour les sources d'événements Kinesis](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/) et DynamoDB.
1. Téléchargez l’exemple de jeu de données `JSON Lines`, [sample-dataset.jsonl](https://github.com/aws/fmeval/blob/8da27af2f20369fd419c03d5bb0707ab24010b14/examples/xsum_sample.jsonl), dans votre répertoire de travail actuel.
1. Vérifiez que votre environnement contient l’exemple de fichier d’entrée suivant :
```
import glob
# Check for the built-in dataset
if not glob.glob("sample-dataset.jsonl"):
print("ERROR - please make sure file exists: sample-dataset.jsonl")
```
**Envoi d’un exemple de demande d’inférence à votre modèle**
1. Définissez le modèle et le type `MIME` de votre invite. Pour un [modèle Anthropic Claude 2](https://www.anthropic.com/index/claude-2) hébergé sur Amazon Bedrock, votre invite doit être structurée comme suit :
```
import json
model_id = 'anthropic.claude-v2'
accept = "application/json"
contentType = "application/json"
# Ensure that your prompt has the correct format
prompt_data = """Human: Who is Barack Obama?
Assistant:
"""
```
Pour plus d’informations sur la manière de structurer le corps de votre demande, consultez [Champ body de la demande d’invocation du modèle](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html#model-parameters-claude-request-body). Les autres modèles peuvent avoir des formats différents.
1. Envoyez un exemple de demande à votre modèle. Le corps de votre demande contient l’invite et tous les paramètres supplémentaires que vous souhaitez définir. Voici un exemple de demande avec `max_tokens_to_sample` défini sur `500` :
```
body = json.dumps({"prompt": prompt_data, "max_tokens_to_sample": 500})
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=contentType
)
response_body = json.loads(response.get("body").read())
print(response_body.get("completion"))
```
Dans l’exemple de code précédent, vous pouvez définir les paramètres suivants :
+ `temperature` : contrôle le degré de hasard du texte généré et accepte les valeurs positives. Des valeurs plus élevées de `temperature` indiquent au modèle de générer des réponses plus aléatoires et plus diverses. Des valeurs plus faibles génèrent des réponses plus prévisibles. Les plages de `temperature` sont comprises entre `0` et `1`, avec une valeur par défaut de 0,5.
+ `topP` : contrôle le degré de hasard en limitant l’ensemble de jetons à prendre en compte lors de la génération du jeton suivant. Des valeurs plus élevées de `topP` autorisent un ensemble contenant un vocabulaire plus large et des valeurs plus faibles limitent l’ensemble de jetons à des mots plus probables. Les plages de `topP` vont de `0` à `1`, avec une valeur par défaut de `1`.
+ `topK` : limite les prédictions modélisées aux `k` jetons les plus probables. Des valeurs plus élevées de `topK` permettent des réponses plus inventives. Des valeurs plus faibles génèrent des réponses plus cohérentes. Les plages de `topK` vont de `0` à `500`, avec une valeur par défaut de `250`.
+ `max_tokens_to_sample` : limite la longueur de la réponse en limitant le nombre de jetons renvoyés par votre modèle. Les plages de `max_tokens_to_sample` vont de `0` à `4096`, avec une valeur par défaut de `200`.
+ `stop_sequences` : spécifie une liste de séquences de caractères qui indiquent à votre modèle d’arrêter de générer une réponse. La sortie du modèle est arrêtée la première fois que l’une des chaînes répertoriées est rencontrée dans la sortie. La réponse ne contient pas la séquence d’arrêt. Par exemple, vous pouvez utiliser une séquence de retour chariot pour limiter la réponse du modèle à une seule ligne. Vous pouvez configurer jusqu’à `4` séquences d’arrêt.
Pour plus d’informations sur les paramètres que vous pouvez spécifier dans une demande, consultez [Modèles Anthropic Claude](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html).
**Configurez FMEval**
1. Chargez les bibliothèques requises pour les exécuter FMEval comme suit :
```
from fmeval.data_loaders.data_config import DataConfig
from fmeval.model_runners.bedrock_model_runner import BedrockModelRunner
from fmeval.constants import MIME_TYPE_JSONLINES
from fmeval.eval_algorithms.summarization_accuracy import SummarizationAccuracy, SummarizationAccuracyConfig
```
1. Configurez la configuration des données pour votre jeu de données d’entrée.
L’exemple d’entrée suivant se trouve à une ligne de `sample-dataset.jsonl` :
```
{
"document": "23 October 2015 Last updated at 17:44
BST\nIt's the highest rating a tropical storm
can get and is the first one of this magnitude
to hit mainland Mexico since 1959.\nBut how are
the categories decided and what do they mean?
Newsround reporter Jenny Lawrence explains.",
"summary": "Hurricane Patricia has been rated as
a category 5 storm.",
"id": "34615665",
}
```
L’exemple d’entrée précédent contient le texte à résumer dans la clé `document`. La référence par rapport à laquelle évaluer la réponse de votre modèle est dans la clé `summary`. Vous devez utiliser ces clés dans votre configuration de données pour spécifier les colonnes contenant les informations FMEval nécessaires à l'évaluation de la réponse du modèle.
Votre configuration de données doit identifier le texte que votre modèle doit résumer dans `model_input_location`. Vous devez identifier la valeur de référence avec `target_output_location`.
L’exemple de configuration de données suivant fait référence à l’exemple d’entrée précédent pour spécifier les colonnes requises pour une tâche de synthétisation de texte, le nom, l’identifiant de ressource uniforme (URI) et le type `MIME` :
```
config = DataConfig(
dataset_name="sample-dataset",
dataset_uri="sample-dataset.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
model_input_location="document",
target_output_location="summary"
)
```
Pour plus d’informations sur les informations de colonne requises pour d’autres tâches, consultez la section **Utilisation d’un jeu de données d’entrée personnalisé** dans [Évaluation automatique de modèles](clarify-foundation-model-evaluate-auto.md).
1. Configurez un élément `ModelRunner` personnalisé dans l’exemple de code suivant :
```
bedrock_model_runner = BedrockModelRunner(
model_id=model_id,
output='completion',
content_template='{"prompt": $prompt, "max_tokens_to_sample": 500}'
)
```
L’exemple de code précédent spécifie les éléments suivants :
+ `model_id` : l’identifiant utilisé pour spécifier votre modèle.
+ `output` : capture la sortie du modèle [Anthropic Claude 2](https://www.anthropic.com/index/claude-2), qui renvoie sa réponse dans une clé `completion`.
+ `content_template` : spécifie la façon dont votre modèle interagit avec les demandes. L’exemple de modèle de configuration est détaillé comme suit uniquement pour expliquer l’exemple précédent, et il n’est pas obligatoire.
+ Dans l’exemple `content_template` précédent, les points suivants s’appliquent :
+ La variable `prompt` spécifie l’invite d’entrée, qui capture la demande faite par l’utilisateur.
+ La variable `max_tokens_to_sample` spécifie le nombre maximal de jetons sur `500`, afin de limiter la longueur de la réponse.
Pour plus d’informations sur les paramètres que vous pouvez spécifier dans votre demande, consultez [Modèles Anthropic Claude](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html).
Le format du paramètre `content_template` dépend des entrées et des paramètres pris en charge par votre LLM. Dans ce didacticiel, le [modèle Claude 2 d’Anthropic](https://www.anthropic.com/index/claude-2) utilise l’élément `content_template` suivant :
```
"content_template": "{\"prompt\": $prompt, \"max_tokens_to_sample\": 500}"
```
Autre exemple, le [modèle Falcon 7b](https://huggingface.co/tiiuae/falcon-7b) peut prendre en charge l’élément `content_template` suivant :
```
"content_template": "{\"inputs\": $prompt, \"parameters\":{\"max_new_tokens\": \
10, \"top_p\": 0.9, \"temperature\": 0.8}}"
```
## Exécution de votre évaluation de modèles
**Définition et exécution de votre algorithme d’évaluation**
1. Définissez votre algorithme d’évaluation. L’exemple suivant montre comment définir un algorithme `SummarizationAccuracy`, qui est utilisé pour déterminer l’exactitude des tâches de synthétisation de texte :
```
eval_algo = SummarizationAccuracy(SummarizationAccuracyConfig())
```
Pour des exemples d’algorithmes qui calculent des métriques pour d’autres tâches d’évaluation, consultez **Évaluation de votre modèle** dans [Utilisation de la bibliothèque `fmeval` pour exécuter une évaluation automatique](clarify-foundation-model-evaluate-auto-lib.md).
1. Exécutez votre algorithme d’évaluation. L’exemple de code suivant utilise la configuration des données précédemment définie, ainsi qu’un élément `prompt_template` qui utilise les clés `Human` et `Assistant` :
```
eval_output = eval_algo.evaluate(model=bedrock_model_runner,
dataset_config=config,
prompt_template="Human: $feature\n\nAssistant:\n", save=True)
```
Dans l’exemple de code précédent, `feature` contient l’invite au format attendu par le modèle Amazon Bedrock.
## Visualisation de vos résultats d’analyse
1. Analysez un rapport d’évaluation à partir de l’objet `eval_output` renvoyé par l’algorithme d’évaluation comme suit :
```
# parse report
print(json.dumps(eval_output, default=vars, indent=4))
```
La commande précédente renvoie la sortie suivante :
```
[
{
"eval_name": "summarization_accuracy",
"dataset_name": "sample-dataset",
"dataset_scores": [
{
"name": "meteor",
"value": 0.2048823008681274
},
{
"name": "rouge",
"value": 0.03557697913367101
},
{
"name": "bertscore",
"value": 0.5406564395678671
}
],
"prompt_template": "Human: $feature\n\nAssistant:\n",
"category_scores": null,
"output_path": "/tmp/eval_results/summarization_accuracy_sample_dataset.jsonl",
"error": null
}
]
```
L’exemple de sortie précédent affiche les trois scores d’exactitude : [https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor), [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge) et [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore), l’élément `prompt_template` d’entrée, un élément `category_score` si vous en avez demandé un, les erreurs éventuelles et l’élément `output_path`. Vous allez utiliser l’élément `output_path` pour créer un `Pandas DataFrame` à l’étape suivante.
1. Importez vos résultats et lisez-les dans un `DataFrame`, puis attachez les scores d’exactitude à l’entrée du modèle, à la sortie du modèle et à la sortie cible comme suit :
```
import pandas as pd
data = []
with open("/tmp/eval_results/summarization_accuracy_sample_dataset.jsonl", "r") as file:
for line in file:
data.append(json.loads(line))
df = pd.DataFrame(data)
df['meteor_score'] = df['scores'].apply(lambda x: x[0]['value'])
df['rouge_score'] = df['scores'].apply(lambda x: x[1]['value'])
df['bert_score'] = df['scores'].apply(lambda x: x[2]['value'])
df
```
Dans cette invocation, l’exemple de code précédent renvoie la sortie suivante (contractée pour des raisons de concision) :
```
model_input model_output target_output prompt scores meteor_score rouge_score bert_score
0 John Edward Bates, formerly of Spalding, Linco... I cannot make any definitive judgments, as th... A former Lincolnshire Police officer carried o... Human: John Edward Bates, formerly of Spalding... [{'name': 'meteor', 'value': 0.112359550561797... 0.112360 0.000000 0.543234 ...
1 23 October 2015 Last updated at 17:44 BST\nIt'... Here are some key points about hurricane/trop... Hurricane Patricia has been rated as a categor... Human: 23 October 2015 Last updated at 17:44 B... [{'name': 'meteor', 'value': 0.139822692925566... 0.139823 0.017621 0.426529 ...
2 Ferrari appeared in a position to challenge un... Here are the key points from the article:\n\n... Lewis Hamilton stormed to pole position at the... Human: Ferrari appeared in a position to chall... [{'name': 'meteor', 'value': 0.283411142234671... 0.283411 0.064516 0.597001 ...
3 The Bath-born player, 28, has made 36 appearan... Okay, let me summarize the key points from th... Newport Gwent Dragons number eight Ed Jackson ... Human: The Bath-born player, 28, has made 36 a... [{'name': 'meteor', 'value': 0.089020771513353... 0.089021 0.000000 0.533514 ...
...
```
La sortie de votre modèle peut être différente de l’exemple de sortie précédent.
Pour un bloc-notes contenant les exemples de code donnés dans cette section, voir [bedrock-claude-summarization-accuracy.ipnyb](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-summarization-accuracy.ipynb).
## Blocs-notes supplémentaires
Le GitHub répertoire [fmeval](https://github.com/aws/fmeval/tree/main/examples) contient les exemples de blocs-notes supplémentaires suivants :
+ [bedrock-claude-factual-knowledge.ipnyb](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-factual-knowledge.ipynb) — Évalue un [modèle Anthropic Claude](https://www.anthropic.com/index/claude-2) 2 hébergé sur Amazon Bedrock pour en tirer des connaissances factuelles.
+ [byo-model-outputs.ipynb](https://github.com/aws/fmeval/blob/main/examples/byo-model-outputs.ipynb) — Évalue un [modèle Falcon7b](https://huggingface.co/tiiuae/falcon-7b) hébergé sur JumpStart des bases factuelles, dans lesquelles vous apportez vos propres résultats de modèle au lieu d'envoyer des demandes d'inférence à votre modèle.
+ [custom\$1model\$1runner\$1chat\$1gpt.ipnyb](https://github.com/aws/fmeval/blob/main/examples/custom_model_runner_chat_gpt.ipynb) : évalue un modèle `ChatGPT 3.5` personnalisé hébergé sur `Hugging Face` pour obtenir des connaissances factuelles.
# Résoudre les erreurs lors de la création d'une tâche d'évaluation de modèle dans Amazon SageMaker AI
**Important**
Pour utiliser les évaluations du modèle SageMaker Clarify Foundation (FMEval), vous devez passer à la nouvelle expérience Studio.
Depuis le 30 novembre 2023, l'expérience Amazon SageMaker Studio précédente s'appelle désormais Amazon SageMaker Studio Classic. FMEval n'est pas disponible dans Amazon SageMaker Studio Classic.
Pour en savoir plus sur la manière d’effectuer la mise à niveau vers la nouvelle expérience Studio, consultez [Migration depuis Amazon SageMaker Studio Classic](studio-updated-migrate.md). Pour en savoir plus sur l’utilisation de l’application Studio Classic, consultez [Amazon SageMaker Studio classique](studio.md).
Si vous rencontrez une erreur lors de la création d’une tâche d’évaluation de modèles, utilisez la liste suivante pour dépanner votre évaluation. Si vous avez besoin d'une assistance supplémentaire, [Support](https://console.aws.amazon.com/support/)contactez [AWS nos forums de développeurs pour Amazon SageMaker AI](https://forums.aws.amazon.com/forum.jspa?forumID=285).
**Rubriques**
+ [Erreur lors du chargement de vos données à partir d’un compartiment Amazon S3](#clarify-foundation-model-evaluate-troubleshooting-cors)
+ [Échec de la tâche de traitement](#clarify-foundation-model-evaluate-troubleshooting-failure)
+ [Vous ne trouvez pas d'évaluations de modèles de base dans la console d' SageMaker IA](#clarify-foundation-model-evaluate-troubleshooting-upgrade)
+ [Votre modèle ne prend pas en charge le stéréotypage d’invite](#clarify-foundation-model-evaluate-troubleshooting-ps)
+ [Erreurs de validation des jeux de données (humaines)](#clarify-foundation-model-evaluate-troubleshooting-valid)
## Erreur lors du chargement de vos données à partir d’un compartiment Amazon S3
Lorsque vous créez une évaluation de modèles de fondation, vous devez définir les autorisations appropriées pour le compartiment S3 dans lequel vous souhaitez stocker les entrées et sorties de votre modèle. Si les autorisations de partage de ressources entre origines (CORS) ne sont pas définies correctement, SageMaker AI génère l'erreur suivante :
Erreur : Impossible de placer l'objet dans s3 : erreur lors du téléchargement de l'objet vers S3 Erreur : échec de l'insertion de l'objet dans S3 : NetworkError lors de la tentative de récupération de la ressource.
Pour définir les autorisations de compartiment appropriées, suivez les instructions figurant sous **Configuration de votre environnement** dans [Création d’une tâche d’évaluation automatique de modèles dans Studio](clarify-foundation-model-evaluate-auto-ui.md).
## Échec de la tâche de traitement
Les raisons les plus courantes pour lesquelles votre tâche de traitement a échoué sont les suivantes :
+ [Quota insuffisant](#clarify-foundation-model-evaluate-troubleshooting-failure-quota)
+ [Mémoire insuffisante](#clarify-foundation-model-evaluate-troubleshooting-failure-memory)
+ [Échec lors de la vérification du ping](#clarify-foundation-model-evaluate-troubleshooting-failure-ping)
Consultez les sections suivantes pour découvrir comment atténuer chaque problème.
### Quota insuffisant
Lorsque vous effectuez une évaluation du modèle de base pour un JumpStart modèle non déployé, SageMaker Clarify déploie votre modèle linguistique étendu (LLM) sur un point de terminaison SageMaker AI de votre compte. Si le quota de votre compte n'est pas suffisant pour exécuter le JumpStart modèle sélectionné, la tâche échoue avec un`ClientError`. Pour augmenter votre quota, procédez comme suit :
**Demander une augmentation des Quotas de AWS Service**
1. Extrayez le nom de l’instance, le quota actuel et le quota nécessaire à partir du message d’erreur affiché à l’écran. Par exemple, pour l’erreur suivante :
+ Le nom de l’instance est `ml.g5.12xlarge`.
+ Le quota actuel à partir du nombre suivant `current utilization` est de `0 instances`
+ Le quota supplémentaire requis à partir du nombre suivant `request delta` est de `1 instances`.
Voici l’exemple d’erreur :
`ClientError: An error occurred (ResourceLimitExceeded) when calling the CreateEndpoint operation: The account-level service limit 'ml.g5.12xlarge for endpoint usage' is 0 Instances, with current utilization of 0 Instances and a request delta of 1 Instances. Please use AWS Service Quotas to request an increase for this quota. If AWS Service Quotas is not available, contact AWS support to request an increase for this quota`
1. Connectez-vous à la [console Service Quotas AWS Management Console et ouvrez-la](https://console.aws.amazon.com/servicequotas/home).
1. Dans le volet de navigation, sous **Gérer les quotas**, entrez **Amazon SageMaker AI**.
1. Choisissez **Afficher les quotas**.
1. Dans la barre de recherche, sous **Service Quotas**, saisissez le nom de l’instance de l’étape 1. Par exemple, en utilisant les informations contenues dans le message d’erreur de l’étape 1, entrez **ml.g5.12xlarge**.
1. Choisissez le **nom du quota** qui apparaît à côté du nom de votre instance et se termine par **pour l’utilisation de points de terminaison**. Par exemple, en utilisant les informations contenues dans le message d’erreur de l’étape 1, choisissez **ml.g5.12xlarge pour l’utilisation de points de terminaison**.
1. Choisissez **Demander une augmentation au niveau du compte**.
1. Sous **Augmenter la valeur du quota**, entrez le quota requis à partir des informations fournies dans le message d’erreur de l’étape 1. Entrez la **somme** de `current utilization` et `request delta`. Dans l’exemple d’erreur précédent, `current utilization` a pour valeur `0 Instances` et `request delta` a pour valeur `1 Instances`. Dans cet exemple, demandez un quota de `1` pour fournir le quota requis.
1. Cliquez sur **Demander**.
1. Choisissez **Historique des demandes de quotas** dans le volet de navigation.
1. Lorsque le **statut** passe de **En attente** à **Approuvé**, réexécutez votre tâche. Vous pouvez avoir besoin d’actualiser votre navigateur pour voir le changement.
Pour plus d’informations sur la manière de demander une augmentation de votre quota, consultez [Demande d’augmentation de quota](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html).
### Mémoire insuffisante
Si vous lancez une évaluation de modèles de fondation sur une instance Amazon EC2 qui ne dispose pas de suffisamment de mémoire pour exécuter un algorithme d’évaluation, la tâche échoue avec l’erreur suivante :
`The actor is dead because its worker process has died. Worker exit type: SYSTEM_ERROR Worker exit detail: Worker unexpectedly exits with a connection error code 2. End of file. There are some potential root causes. (1) The process is killed by SIGKILL by OOM killer due to high memory usage. (2) ray stop --force is called. (3) The worker is crashed unexpectedly due to SIGSEGV or other unexpected errors. The actor never ran - it was cancelled before it started running.`
Pour augmenter la mémoire disponible pour votre tâche d’évaluation, remplacez votre instance par une instance dotée de plus de mémoire. Si vous utilisez l’interface utilisateur, vous pouvez choisir un type d’instance sous **Configuration du processeur** à l’**étape 2**. Si vous exécutez votre tâche dans la console SageMaker AI, lancez un nouvel espace à l'aide d'une instance dotée d'une capacité de mémoire accrue.
Pour accéder à la liste des instance Amazon EC2, consultez [Types d’instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes).
Pour plus d’informations sur les instances dotées d’une plus grande capacité de mémoire, consultez [Instances à mémoire optimisée](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/memory-optimized-instances.html).
### Échec lors de la vérification du ping
Dans certains cas, votre tâche d'évaluation du modèle de base échouera car elle n'a pas passé avec succès une vérification ping lors du déploiement de votre point de terminaison par l' SageMaker IA. Si elle ne réussit pas un test ping, l’erreur suivante apparaît :
`ClientError: Error hosting endpoint your_endpoint_name: Failed. Reason: The primary container for production variant AllTraffic did not pass the ping health check. Please check CloudWatch logs for this endpoint..., Job exited for model: your_model_name of model_type: your_model_type `
Si votre tâche génère cette erreur, attendez quelques minutes et exécutez à nouveau votre tâche. Si l'erreur persiste, contactez le [AWS Support](https://console.aws.amazon.com/support/) ou [les forums de AWS développeurs pour Amazon SageMaker AI](https://forums.aws.amazon.com/forum.jspa?forumID=285).
## Vous ne trouvez pas d'évaluations de modèles de base dans la console d' SageMaker IA
Pour utiliser les évaluations du modèle SageMaker Clarify Foundation, vous devez passer à la nouvelle expérience Studio. Depuis le 30 novembre 2023, l'expérience Amazon SageMaker Studio précédente s'appelle désormais Amazon SageMaker Studio Classic. La caractéristique d’évaluation des modèles de fondation ne peut être utilisée que dans l’expérience mise à jour. Pour en savoir plus sur la façon de mettre à jour Studio, consultez [Migration depuis Amazon SageMaker Studio Classic](studio-updated-migrate.md).
## Votre modèle ne prend pas en charge le stéréotypage d’invite
Seuls certains JumpStart modèles prennent en charge les stéréotypes rapides. Si vous sélectionnez un JumpStart modèle qui n'est pas pris en charge, le message d'erreur suivant apparaît :
`{"evaluationMetrics":"This model does not support Prompt stereotyping evaluation. Please remove that evaluation metric or select another model that supports it."}`
Si cette erreur s'affiche, vous ne pouvez pas utiliser le modèle que vous avez sélectionné dans le cadre d'une évaluation de base. SageMaker Clarify travaille actuellement à la mise à jour de tous les JumpStart modèles pour les tâches de stéréotypage rapides afin qu'ils puissent être utilisés dans une évaluation des modèles de base.
## Erreurs de validation des jeux de données (humaines)
Le jeu de données d’invite personnalisé d’une tâche d’évaluation de modèles qui utilise des employés humains doit être formaté au format des lignes JSON à l’aide de l’extension `.jsonl`.
Lorsque vous démarrez une tâche, chaque objet JSON du jeu de données d’invite est validé de manière interdépendante. Si l’un des objets JSON n’est pas valide, l’erreur suivante s’affiche.
```
Customer Error: Your input dataset could not be validated. Your dataset can have up to 1000 prompts. The dataset must be a valid jsonl file, and each prompt valid json object.To learn more about troubleshooting dataset validations errors, see Troubleshooting guide. Job executed for models: meta-textgeneration-llama-2-7b-f, pytorch-textgeneration1-alexa20b.
```
Pour qu’un jeu de données d’invite personnalisé réussisse toutes les validations, les conditions suivantes doivent être *vraies* pour tous les objets JSON du fichier de lignes JSON.
+ Chaque ligne du fichier de jeu de données d’invite doit être un objet JSON valide.
+ Les caractères spéciaux tels que les guillemets (`"`) doivent être correctement échappés. Par exemple, si votre invite était `"Claire said to the crowd, "Bananas are the best!""`, les guillemets devraient être échappés à l’aide d’une `\`, `"Claire said to the crowd, \"Bananas are the best!\""`.
+ Un objet JSON valide doit contenir au moins la paire clé/valeur `prompt`.
+ Un fichier de jeu de données d’invite ne peut pas contenir plus de 1 000 objets JSON dans un seul fichier.
+ Si vous spécifiez la clé `responses` dans un objet JSON *quelconque*, elle doit être présente dans *tous* les objets JSON.
+ Le nombre maximal d’objets dans la clé `responses` est 1. Si vous souhaitez comparer les réponses de plusieurs modèles, chacun nécessite un jeu de données BYOI distinct.
+ Si vous spécifiez la clé `responses` dans un objet JSON *quelconque*, il doit également contenir les clés `modelIdentifier` et `text` dans *tous* les objets `responses`.
# Évaluation et comparaison des modèles de classification de SageMaker JumpStart texte Amazon
SageMaker L'IA JumpStart propose plusieurs modèles de classification de texte qui classent le texte en classes prédéfinies. Ces modèles gèrent des tâches telles que l’analyse des sentiments, la classification des sujets et la modération de contenu. Le choix du bon modèle pour la production nécessite une évaluation minutieuse à l’aide de métriques clés telles que l’exactitude, le score F1 et le coefficient de corrélation de Matthews (MCC).
Dans ce guide, vous :
+ Déployez plusieurs modèles de classification de texte (Distilbert et BERT) à partir du JumpStart catalogue.
+ Réalisez des évaluations complètes sur des jeux de données équilibrés, asymétriques et complexes.
+ Interprétez des métriques avancées, notamment le coefficient de corrélation de Matthews (MCC) et les scores d’aire sous la courbe ROC.
+ Prenez des décisions de sélection de modèles basés sur les données à l’aide de cadres de comparaison systématiques.
+ Configurez des déploiements de production grâce à l'auto-scaling CloudWatch et à la surveillance.
Téléchargez le cadre d'évaluation complet : [Package d'évaluation du JumpStart modèle](samples/sagemaker-text-classification-evaluation-2.zip). **Ce package inclut des résultats de pré-exécution avec des exemples de sorties** afin que vous puissiez prévisualiser le processus et les métriques d’évaluation avant de déployer vous-même les modèles.
## Conditions préalables
Avant de commencer, assurez-vous de disposer des éléments suivants :
+ [AWS compte avec autorisations SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html).
+ [SageMaker Accès AI à Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html).
+ Connaissances de base du langage Python.
+ Compréhension des concepts de classification de texte.
Durée et coût : 45 minutes au total. Les coûts varient en fonction du type d'instance et de la durée d'utilisation. Consultez la [tarification de l'SageMaker IA pour connaître](https://aws.amazon.com/sagemaker/pricing/) les tarifs actuels.
Ce didacticiel inclut des instructions de step-by-step nettoyage pour vous aider à supprimer toutes les ressources et à éviter des frais récurrents.
**Topics**
+ [Conditions préalables](#w2aac37c15c11)
+ [Configuration de votre environnement d’évaluation](jumpstart-text-classification-setup.md)
+ [Sélection et déploiement de modèles de classification de texte](jumpstart-text-classification-deploy.md)
+ [Évaluation et comparaison des performances des modèles](jumpstart-text-classification-evaluate.md)
+ [Interprétation de vos résultats](jumpstart-text-classification-interpret.md)
+ [Déploiement de votre modèle à grande échelle](jumpstart-text-classification-scale.md)
# Configuration de votre environnement d’évaluation
Configurez SageMaker AI Studio pour accéder aux JumpStart modèles pour l'évaluation de la classification du texte. Cette section traite de la configuration des autorisations et de la compréhension des coûts associés avant de déployer les modèles.
## Conditions préalables
Avant de commencer, assurez-vous de disposer d'un AWS compte doté d'autorisations SageMaker AI. Pour les instructions de configuration du compte, voir [Configurer les prérequis SageMaker relatifs à l'IA](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html).
## Configurer SageMaker AI Studio pour l'évaluation des JumpStart modèles
Si vous n'avez pas accès à SageMaker AI Studio, consultez [Configuration rapide](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html) pour créer un domaine.
Pour démarrer votre projet de classification de texte dans SageMaker Studio :
1. Ouvrez le panneau de configuration d' SageMaker AI Studio.
1. Sélectionnez votre profil utilisateur.
1. Choisissez **Open Studio (Ouvrir Studio)**.
1. Attendez le chargement de Studio (cela peut prendre 2 à 3 minutes lors du premier lancement).
1. Vérifiez que cela JumpStart apparaît dans le panneau de navigation de gauche.
## Comprendre les coûts de SageMaker l'IA
Lorsque vous utilisez SageMaker AI Studio, vous encourez des frais pour :
+ SageMaker Hébergement de terminaux AI (varie en fonction du type d'instance et de la durée).
+ le stockage Amazon S3 pour les jeux de données et les artefacts de modèles ;
+ Temps d'exécution de l'instance Notebook (certaines utilisations sont couvertes par le niveau AWS gratuit pour les comptes éligibles).
**Note**
L’utilisation de l’interface de Studio n’entraîne pas de frais supplémentaires.
### Recommandations de gestion des coûts
Suivez ces recommandations pour minimiser les coûts lors de votre évaluation :
+ Utilisez les instances par défaut telles que spécifiées pour les modèles DistilBERT et BERT.
+ Supprimez les points de terminaison immédiatement après l’évaluation.
+ Surveillez votre utilisation à l’aide du [Calculateur de prix AWS](https://aws.amazon.com/calculator.aws/#/addService/SageMaker).
+ Pour connaître les tarifs de stockage en cours, consultez [Tarification d’Amazon Simple Storage Service](https://aws.amazon.com/s3/pricing/).
**Avertissement**
Assurez-vous d’arrêter les points de terminaison et de nettoyer les ressources après avoir terminé ce didacticiel afin d’éviter des frais ultérieurs.
Passez au [Sélection et déploiement de modèles de classification de texte](jumpstart-text-classification-deploy.md).
# Sélection et déploiement de modèles de classification de texte
Déployez deux modèles de classification de texte à des fins de comparaison : DistilBERT Base Cased et BERT Base Uncased. Vous découvrirez les différences entre ces modèles et les déploierez en utilisant la configuration d’instance optimale.
## Pourquoi ces deux modèles
Ces modèles montrent le choix typique auquel les clients sont confrontés en production entre la performance et le coût :
+ **BERT Base Uncased** : plus grand, plus exact, mais plus lent et plus gourmand en ressources.
+ **DistilBERT Base Cased** : plus petit, plus rapide, plus rentable, mais potentiellement moins exact.
Cette comparaison vous permet de choisir le modèle adapté à vos besoins spécifiques.
## Comprendre les noms de modèles dans le catalogue
Les noms des modèles de classification de texte figurant dans le catalogue incluent les composants suivants :
+ BERT : Bidirectional Encoder Representations from Transformers.
+ L-X\$1H-Y\$1A-Z : structure du modèle où :
+ L-X : nombre de couches (X).
+ H-Y : taille cachée (Y).
+ A-Z : nombre de têtes d’attention (Z).
+ Small/Base/Large: taille et complexité du modèle.
+ Uncased/Cased : réglage de sensibilité de la casse.
Exemple : `Small BERT L-2_H-128_A-2` indique un petit modèle BERT avec :
+ 2 couches.
+ 128 unités cachées.
+ 2 têtes d’attention.
## Accédez au catalogue JumpStart de modèles
Accédez aux modèles de classification de texte dans le JumpStart catalogue.
1. Ouvrez SageMaker AI Studio
1. Dans le panneau de navigation de gauche, choisissez **JumpStart**.
1. Sur la JumpStart page, choisissez **Hugging Face**.
1. Choisissez **Classification de texte**.
Vous devriez voir la liste des modèles de classification de texte disponibles dans le catalogue, y compris les variantes DistilBERT et BERT.
## Déploiement de DistilBERT Base Cased
Déployez le modèle DistilBERT en utilisant la configuration par défaut.
1. Dans la liste des modèles, recherchez et choisissez **DistilBERT Base Cased** (by distilbert).
1. Sur la page de détails du modèle, conservez le type d’instance par défaut.
1. Conservez tous les autres paramètres par défaut et choisissez **Déployer**.
1. Attendez 5 à 10 minutes que le déploiement se termine.
1. Pour vérifier le succès du déploiement, allez dans **Déploiements** puis dans **Points de terminaison**.
1. Vérifiez que le point de terminaison DistilBERT affiche le statut `InService`.
## Déploiement de BERT Base Uncased
Déployez le modèle BERT à des fins de comparaison avec DistilBERT.
1. Revenez aux modèles JumpStart de classification de texte Hugging Face dans.
1. Recherchez et choisissez **BERT Base Uncased** (par google-bert).
1. Conservez le type d’instance par défaut et choisissez **Déployer**.
1. Pour confirmer les deux déploiements, vérifiez que les deux points de terminaison affichent le statut `InService` dans la liste des points de terminaison.
Les deux modèles apparaissent dans votre liste de points de terminaison avec le statut `InService`.
**Important**
Copiez et enregistrez les noms des points de terminaison. Vous en aurez besoin pour le processus d’évaluation.
## Résolution des problèmes
Si vous rencontrez des problèmes de déploiement :
+ Pour les erreurs de type d’instance, vérifiez que vous utilisez le type d’instance par défaut, et non des instances CPU comme `ml.m5.large`.
+ Si vous ne trouvez pas de modèles, recherchez en utilisant les noms exacts des modèles, en indiquant le diffuseur de publication entre parenthèses.
+ Pour les déploiements ayant échoué, vérifiez l’état du service dans votre région ou essayez une autre région.
Une fois que votre modèle affiche le statut `InService`, reportez-vous à [Évaluation et comparaison des performances des modèles](jumpstart-text-classification-evaluate.md) pour évaluer votre modèle déployé.
# Évaluation et comparaison des performances des modèles
Évaluez vos modèles de classification de texte déployés à l’aide du cadre d’évaluation. Ce cadre prend en charge les modes d’évaluation supervisé et non supervisé via une approche basée sur des blocs-notes.
## Utilisation de jeux de données intégrés
**Nous recommandons d’utiliser le jeu de données d’évaluation supervisée intégrée** pour ce didacticiel, car la plupart des utilisateurs ne disposent pas de données d’évaluation étiquetées disponibles. Les jeux de données intégrés fournissent une analyse complète des performances dans différents scénarios :
+ **Jeux de données équilibrés** : distribution de classe égale pour les performances de référence.
+ **Jeux de données asymétriques** : classes déséquilibrées pour les tests dans le monde réel.
+ **Jeux de données complexes** : scénarios limites pour tester la robustesse du modèle.
L’évaluation génère des métriques clés, notamment l’exactitude, la précision, le rappel, le score F1, le coefficient de corrélation de Matthews (MCC) et les scores d’aire sous la courbe ROC, avec des courbes visuelles pour la comparaison des modèles.
## Utilisation de données personnalisées
Si vous possédez votre propre jeu de données étiqueté, vous pouvez le remplacer dans le bloc-notes. Le cadre s’adapte automatiquement au format de vos données et génère les mêmes métriques complètes.
**Formats de données pris en charge :**
+ **Format CSV :** deux colonnes : `text` et `label`
+ **Formats d’étiquette :** « positif »/« négatif », « LABEL\$10 »/« LABEL\$11 », « Vrai »/« Faux » ou « 0 »/« 1 »
+ **Non supervisé :** colonne `text` individuelle pour l’analyse de confiance
## Configuration de votre environnement d’évaluation
Créez un JupyterLab espace dans SageMaker Amazon SageMaker Studio pour exécuter le carnet d'évaluation.
1. Dans Studio, choisissez **JupyterLab**depuis l'écran d'accueil.
1. Si vous n’avez pas d’espace :
1. Choisissez **Créer un espace**.
1. Donnez-lui un nom descriptif (par exemple, **TextModelEvaluation)**.
1. Conservez le type d’instance par défaut.
1. Choisissez **Exécuter Space**.
1. Lorsque l'espace a été créé, choisissez **Ouvrir JupyterLab**.
### Accès au bloc-notes d’évaluation
Téléchargez le [fichier zip](samples/sagemaker-text-classification-evaluation-2.zip) et extrayez-le sur votre ordinateur local. Téléchargez l'intégralité du dossier extrait dans votre JupyterLab espace pour commencer à tester vos modèles. Le package contient le bloc-notes d’évaluation principal, des exemples de jeux de données, des modules Python de prise en charge et des instructions détaillées pour le cadre d’évaluation complet.
**Note**
Après avoir extrait le package, consultez le fichier README pour obtenir des instructions de configuration détaillées et une vue d’ensemble du cadre.
Passez à l’[Interprétation de vos résultats](jumpstart-text-classification-interpret.md) pour découvrir comment analyser la sortie d’évaluation et prendre des décisions de sélection de modèle basées sur les données.
# Interprétation de vos résultats
Analysez les métriques d’évaluation issues de la comparaison de votre modèle de classification de texte afin de prendre des décisions basées sur les données concernant le déploiement en production.
## Compréhension des métriques d’évaluation
L’évaluation fournit plusieurs métriques clés pour chaque modèle sur l’ensemble des jeux de données :
### Précision
Mesure le pourcentage de prédictions correctes et convient le mieux pour les jeux de données équilibrés. Toutefois, peut être trompeuse avec des données déséquilibrées et peut montrer des résultats artificiellement élevés lorsqu’une classe individuelle domine.
### Précision
Évalue dans quelle mesure le modèle évite les faux positifs en mesurant le pourcentage de prédictions positives correctes. Cette métrique est comprise entre 0,0 et 1,0 (valeur maximale souhaitée) et devient critique lorsque les faux positifs sont coûteux.
### Rappel
Évalue dans quelle mesure le modèle détecte tous les cas positifs en mesurant le pourcentage de vrais positifs trouvés. Elle est comprise entre 0,0 et 1,0 (valeur maximale souhaitée) et devient critique lorsqu’il est coûteux de manquer des positifs.
### Score F1
Fournit la moyenne harmonique de la précision et du rappel, en équilibrant les deux métriques en un score unique compris entre 0,0 et 1,0 (valeur maximale souhaitée).
### Coefficient de corrélation de Matthews (MCC)
Mesure la qualité globale de la classification binaire et constitue la meilleure métrique pour les données déséquilibrées. Elle est comprise entre -1,0 et 1,0, les valeurs les plus élevées indiquant de meilleures performances et 0 représentant une estimation aléatoire.
### Aire sous la courbe ROC
Évalue la distinction que le modèle fait entre les classes. Elle est comprise entre 0,0 et 1,0, où 1,0 représente une classification parfaite et 0,5 représente une estimation aléatoire.
### Temps d’inférence moyen
Mesure la vitesse de prédiction, qui devient essentielle pour les applications en temps réel. Tenez compte à la fois de la vitesse et de la cohérence lors de l’évaluation de cette métrique.
**Note**
Ne vous fiez pas uniquement à l’exactitude pour sélectionner le modèle. Pour les jeux de données déséquilibrés, la précision, le rappel et le MCC constituent des indicateurs plus fiables des performances réelles.
## Comparaison des performances sur l’ensemble des types de jeux de données
Le **jeu de données équilibré** montre les performances de vos modèles dans des conditions idéales avec une représentation égale des exemples positifs et négatifs. De bonnes performances indiquent ici que le modèle a appris les modèles fondamentaux de classification de texte.
Le **jeu de données asymétrique** révèle comment les modèles traitent le déséquilibre de classes réel, lequel est courant dans des scénarios de production.
Le **jeu de données complexe** teste la robustesse des modèles sur des cas ambigus ou limites, susceptibles d’apparaître en production.
## Sélection du modèle
Utilisez cette approche systématique pour sélectionner le modèle optimal pour votre cas d’utilisation spécifique.
### Définition des priorités de votre entreprise
Avant de choisir un modèle, déterminez les facteurs de performance les plus importants pour votre cas d’utilisation.
1. Identifiez vos exigences en matière d’exactitude et de seuil de performance minimum acceptable.
1. Déterminez vos contraintes de latence, notamment si vous avez besoin d’un traitement en temps réel (< 100 ms) ou par lots.
1. Établissez vos considérations en matière de coûts et votre budget pour l’inférence et la mise à l’échelle.
1. Analysez les caractéristiques de vos données pour déterminer si vos données de production sont équilibrées, asymétriques ou très variables.
### Quand choisir les différents modèles
Sur la base de vos résultats d’évaluation, choisissez le modèle qui convient le mieux à votre cas d’utilisation :
+ **Choisissez DistilBERT** lorsque vous avez besoin d’une inférence plus rapide et précise, telle que l’analyse des sentiments en temps réel dans les chatbots des services client, dans les systèmes de modération de contenu ou dans les applications exigeant des temps de réponse inférieurs à 100 ms.
+ **Choisissez BERT** lorsque l’exactitude maximale est plus importante que la vitesse, par exemple pour la classification de documents juridiques, l’analyse de textes médicaux ou les applications de conformité où la précision est primordiale et le traitement par lots acceptable.
### Hiérarchisation de vos jeux de données d’évaluation
Concentrez-vous sur les jeux de données qui représentent le mieux votre cas d’utilisation réel.
1. Accordez plus de poids au jeu de données qui ressemble le plus à vos données réelles.
1. Tenez compte de l’importance des cas limites dans votre application et hiérarchisez en conséquence les performances des jeux de données complexes.
1. Équilibrez l’optimisation entre plusieurs scénarios au lieu de vous concentrer sur un seul type de jeu de données.
Comparez vos résultats d’évaluation à ces priorités pour sélectionner le modèle qui équilibre le mieux vos exigences en matière d’exactitude, de vitesse et de coûts.
Maintenant que vous avez sélectionné votre modèle préféré, vous êtes prêt pour le déploiement en production. Passez au [Déploiement de votre modèle à grande échelle](jumpstart-text-classification-scale.md).
# Déploiement de votre modèle à grande échelle
Configurez l'auto-scaling et la CloudWatch surveillance de votre point de terminaison d' SageMaker IA afin de le préparer à la production.
## Raisons de l’importance de la surveillance en production pour la classification de textes
Les charges de travail de classification de textes doivent être surveillées, car elles :
+ connaissent des modèles de trafic variables avec des pics de traitement ;
+ nécessitent des temps de réponse inférieurs à la seconde ;
+ ont besoin d’une optimisation des coûts via l’autoscaling.
## Conditions préalables
Avant de commencer, assurez-vous que :
+ Votre point de terminaison d' SageMaker IA a été déployé à partir de la section précédente.
+ Le nom de votre point de terminaison (par exemple, jumpstart-dft-hf-tc).
+ Votre Région AWS (par exemple, us-east-2).
Pour la création ou le dépannage du point de terminaison, consultez [Inférence en temps réel](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html).
## Configuration de la surveillance en production
Configurez la CloudWatch surveillance pour suivre les performances de votre modèle en production.
1. Dans votre JupyterLab espace, ouvrez le `sagemaker_production_monitoring.ipynb` bloc-notes du package d'évaluation que vous avez chargé précédemment.
1. Mettez à jour la région et le nom de votre point de terminaison dans la section de configuration.
1. Suivez les instructions du bloc-notes pour configurer :
+ l’autoscaling (1 à 10 instances en fonction du trafic),
+ CloudWatch des alarmes pour les seuils de latence et d'invocation.
+ le tableau de bord des métriques pour une surveillance visuelle.
## Vérification de votre configuration
Une fois les étapes du bloc-notes terminées, vérifiez que vous disposez des éléments suivants :
+ **Statut du point de terminaison** : `InService`.
+ **Autoscaling** : 1 à 10 instances configurées.
+ **CloudWatch Alarmes** : surveillance de 2 alarmes.
+ **Métriques** : plus de 15 métriques enregistrées.
**Note**
Les alarmes peuvent indiquer `INSUFFICIENT_DATA` initialement. Ceci est normal et sera remplacé par `OK` à mesure de l’utilisation.
## Surveillance de votre point de terminaison
Accédez à la surveillance visuelle via la console AWS de gestion :
+ [CloudWatch Métriques](https://console.aws.amazon.com/cloudwatch/home#metricsV2:graph=~();query=AWS/SageMaker)
+ [CloudWatch Alarmes](https://console.aws.amazon.com/cloudwatch/home#alarmsV2:)
Pour plus d'informations, consultez la section [Monitor SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-overview.html).
## Gestion des coûts et nettoyage des ressources
Votre configuration de surveillance fournit des informations précieuses sur la production, mais elle entraîne également des AWS frais permanents via des CloudWatch métriques, des alarmes et des politiques d'auto-scaling. Comprendre comment gérer ces coûts est essentiel pour assurer la rentabilité des opérations. Nettoyez les ressources lorsqu’elles ne seront plus nécessaires.
**Avertissement**
Votre point de terminaison continue de générer des frais même lorsqu’il ne traite pas de demandes. Pour arrêter tous les frais, vous devez supprimer votre point de terminaison. Pour connaître la procédure à suivre, consultez [Suppression des points de terminaison et des ressources](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html).
Pour les configurations de surveillance avancées, voir [CloudWatch Metrics for SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-cloudwatch.html).
# Équité, explicabilité du modèle et détection des biais avec Clarify SageMaker
Vous pouvez utiliser Amazon SageMaker Clarify pour comprendre l'équité et l'explicabilité des modèles, ainsi que pour expliquer et détecter les biais dans vos modèles. Vous pouvez configurer une tâche de traitement SageMaker Clarify pour calculer les métriques de biais et les attributions de fonctionnalités et générer des rapports pour expliquer le modèle. SageMaker Les tâches de traitement Clarify sont implémentées à l'aide d'une image de conteneur SageMaker Clarify spécialisée. La page suivante décrit le fonctionnement de SageMaker Clarify et explique comment démarrer une analyse.
## Qu’est-ce que l’équité et l’explicabilité des modèles pour les prédictions de machine learning ?
Les modèles de machine learning (ML) facilitent la prise de décisions dans des domaines tels que les services financiers, la santé, l’éducation et les ressources humaines. Les décideurs, les organismes de réglementation et les défenseurs des droits ont sensibilisé le public aux défis éthiques et stratégiques posés par le machine learning et les systèmes orientés données. Amazon SageMaker Clarify peut vous aider à comprendre pourquoi votre modèle de machine learning a fait une prédiction spécifique et si ce biais a un impact sur cette prédiction pendant l'entraînement ou l'inférence. SageMaker Clarify fournit également des outils qui peuvent vous aider à créer des modèles d'apprentissage automatique moins biaisés et plus compréhensibles. SageMaker Clarify peut également générer des rapports de gouvernance modèles que vous pouvez fournir aux équipes chargées des risques et de la conformité et aux régulateurs externes. Avec SageMaker Clarify, vous pouvez effectuer les opérations suivantes :
+ Détecter les biais et contribuer à expliquer les prédictions de votre modèle.
+ Identifier les types de biais dans les données de pré-entraînement.
+ Identifier les types de biais dans les données de post-entraînement, qui peuvent émerger pendant l’entraînement ou lorsque votre modèle est en production.
SageMaker Clarify permet d'expliquer comment vos modèles font des prédictions à l'aide des attributions de fonctionnalités. Il peut également surveiller les modèles d’inférence présents en production afin de détecter les biais et les dérives d’attribution de caractéristiques. Ces informations peuvent vous aider dans les domaines suivants :
+ **Réglementation** : les décideurs politiques et autres régulateurs peuvent s’inquiéter des effets discriminatoires des décisions qui s’appuient sur la sortie des modèles ML. Par exemple, un modèle ML peut coder des biais et influencer une décision automatisée.
+ **Affaires** : des domaines réglementés peuvent avoir besoin d’explications fiables sur la façon dont les modèles ML réalisent des prédictions. L’explicabilité des modèles peut être particulièrement importante dans les secteurs qui dépendent de la fiabilité, de la sécurité et de la conformité. Il peut s’agir notamment des secteurs des services financiers, des ressources humaines, de la santé et des transports automatisés. Par exemple, les demandes de prêt doivent parfois expliquer aux agents de crédit, aux prévisionnistes et aux clients comment les modèles de machine learning ont réalisé certaines prédictions.
+ **Science des données** : les scientifiques des données et les ingénieurs ML peuvent déboguer et améliorer les modèles ML lorsqu’ils peuvent déterminer si un modèle réalise des inférences basées sur des caractéristiques non pertinentes ou comportant du bruit. Ils peuvent également comprendre les limites de leurs modèles et les modes de défaillance auxquels ils peuvent être confrontés.
Pour un article de blog expliquant comment concevoir et créer un modèle d'apprentissage automatique complet pour les réclamations automobiles frauduleuses qui intègre SageMaker Clarify dans un pipeline d' SageMaker IA, consultez l'[architecte et créez le cycle de vie complet de l'apprentissage automatique avec AWS : une démo end-to-end Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/). Ce billet de blog explique comment évaluer et atténuer les biais de pré- et de post-entraînement, et comment les caractéristiques affectent la prédiction modélisée. Le billet de blog contient des liens vers des exemples de code pour chaque tâche du cycle de vie ML.
### Bonnes pratiques d’évaluation de l’équité et de l’explicabilité dans le cycle de vie ML
**Équité en tant que processus** : les notions de biais et d’équité dépendent de leur application. La mesure des biais et le choix des indicateurs de biais peuvent être guidés par des considérations sociales, juridiques et d’autres considérations non techniques. L’adoption réussie d’approches ML respectueuses de l’équité passe par l’établissement d’un consensus et la mise en place d’une collaboration entre les principales parties prenantes. Il peut s'agir de produits, de politiques, de services juridiques, d'ingénierie, d' AI/ML équipes, d'utilisateurs finaux et de communautés.
**Équité et explicabilité dès la conception dans le cycle de vie ML** : tenez compte de l’équité et de l’explicabilité à chaque phase du cycle de vie ML. Ces phases incluent l’entraînement du problème, la construction du jeu de données, la sélection de l’algorithme, le processus d’entraînement des modèles, le processus de test, le déploiement, la surveillance et la rétroaction. Il est indispensable de disposer des bons outils pour réaliser cette analyse. Nous vous recommandons de vous poser les questions suivantes au cours du cycle de vie ML :
+ Le modèle encourage-t-il les boucles de rétroaction qui peuvent produire des résultats de plus en plus injustes ?
+ Un algorithme est-il une solution éthique au problème ?
+ Les données d’entraînement sont-elles représentatives de différents groupes ?
+ Y a-t-il des biais dans les étiquettes ou les caractéristiques ?
+ Les données doivent-elles être modifiées pour atténuer les biais ?
+ Les contraintes d’équité doivent-elles être incluses dans la fonction objective ?
+ Le modèle a-t-il été évalué à l’aide de métriques d’équité pertinentes ?
+ Y a-t-il des effets inégaux entre les utilisateurs ?
+ Le modèle est-il déployé sur une population pour laquelle il n’a pas été entraîné ou évalué ?
![\[Bonnes pratiques pour le processus d’évaluation de l’équité et de l’explicabilité des modèles\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify-best-practices-image.png)
### Guide des explications sur l' SageMaker IA et de la documentation sur les biais
Des biais peuvent apparaître et être mesurés dans les données avant et après l’entraînement d’un modèle. SageMaker Clarify peut fournir des explications pour les prédictions des modèles après l'entraînement et pour les modèles déployés en production. SageMaker Clarify peut également surveiller les modèles en production pour détecter toute dérive dans leurs attributions explicatives de base et calculer des bases de référence si nécessaire. La documentation permettant d'expliquer et de détecter les biais à l'aide de SageMaker Clarify est structurée comme suit :
+ Pour en savoir plus sur la configuration d’une tâche de traitement des biais et de l’explicabilité, consultez [Configurer un Job de traitement SageMaker Clarify](clarify-processing-job-configure-parameters.md).
+ Pour en avoir plus sur la détection des biais dans les données de pré-traitement avant leur utilisation pour entraîner un modèle, consultez [Biais des données de pré-entraînement](clarify-detect-data-bias.md).
+ Pour en savoir plus sur la détection des biais dans les données de post-entraînement et le modèle, consultez [Biais de post-entraînement dans les données et les modèles](clarify-detect-post-training-bias.md).
+ Pour en savoir plus sur l’approche d’attribution de caractéristiques indépendante du modèle pour expliquer les prédictions du modèle après l’entraînement, consultez [Explicabilité du modèle](clarify-model-explainability.md).
+ Pour obtenir des informations sur la surveillance de la dérive des contributions des caractéristiques par rapport à la référence établie lors de l’entraînement des modèles, consultez [Dérive d’attribution de caractéristiques pour les modèles en production](clarify-model-monitor-feature-attribution-drift.md).
+ Pour en savoir plus sur la surveillance des modèles en cours de production en vue de déterminer la dérive de la référence, consultez [Dérive de biais pour les modèles en production](clarify-model-monitor-bias-drift.md).
+ Pour plus d'informations sur l'obtention d'explications en temps réel à partir d'un point de terminaison d' SageMaker IA, consultez[Explicabilité en ligne avec Clarify SageMaker](clarify-online-explainability.md).
## Comment fonctionnent les tâches SageMaker Clarify Processing
Vous pouvez utiliser SageMaker Clarify pour analyser vos ensembles de données et modèles afin de déterminer s'ils sont explicables et biaisés. Une tâche de traitement SageMaker Clarify utilise le conteneur de traitement SageMaker Clarify pour interagir avec un compartiment Amazon S3 contenant vos ensembles de données d'entrée. Vous pouvez également utiliser SageMaker Clarify pour analyser un modèle client déployé sur un point de terminaison d'inférence SageMaker basé sur l'IA.
Le graphique suivant montre comment une tâche de traitement SageMaker Clarify interagit avec vos données d'entrée et, éventuellement, avec un modèle client. Cette interaction dépend du type spécifique d'analyse effectué. Le conteneur de traitement SageMaker Clarify obtient le jeu de données en entrée et la configuration pour l'analyse à partir d'un compartiment S3. Pour certains types d'analyse, notamment l'analyse des caractéristiques, le conteneur de traitement SageMaker Clarify doit envoyer des demandes au conteneur du modèle. Il récupère ensuite les prédictions de modèle à partir de la réponse envoyée par le conteneur de modèle. Ensuite, le conteneur de traitement SageMaker Clarify calcule et enregistre les résultats de l'analyse dans le compartiment S3.
![\[SageMaker Clarify peut analyser vos données ou un modèle client pour en déterminer les explications et les biais.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify/clarify-processing-job.png)
Vous pouvez exécuter une tâche de traitement SageMaker Clarify à plusieurs étapes du cycle de vie du flux de travail d'apprentissage automatique. SageMaker Clarify peut vous aider à calculer les types d'analyse suivants :
+ Les indicateurs de biais de pré-entraînement. Ces métriques peuvent vous aider à comprendre les biais figurant dans vos données afin de pouvoir y remédier et entraîner votre modèle sur un jeu de données plus juste. Consultez [Indicateurs de biais de pré-entraînement](clarify-measure-data-bias.md) pour en savoir plus sur les indicateurs de biais de pré-entraînement. Pour exécuter une tâche d’analyse des indicateurs de biais de pré-entraînement, vous devez fournir le jeu de données et un fichier de configuration d’analyse JSON à [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
+ Les indicateurs de biais de post-entraînement. Ces métriques peuvent vous aider à comprendre tout biais introduit par un algorithme, les choix d’hyperparamètres ou tout biais qui n’était pas apparent plus tôt dans le flux. Pour plus d'informations sur les mesures de biais après l'entraînement, voir[Indicateurs de biais de post-entraînement dans les données et les modèles](clarify-measure-post-training-bias.md). SageMaker Clarify utilise les prédictions du modèle en plus des données et des étiquettes pour identifier les biais. Pour exécuter une tâche d'analyse des métriques de biais de post-entraînement, vous devez fournir le jeu de données et un fichier de configuration d'analyse JSON. La configuration doit inclure le nom du modèle ou du point de terminaison.
+ Les valeurs de Shapley, qui peuvent vous aider à comprendre l’impact de votre caractéristique sur ce que votre modèle prédit. Pour plus d’informations sur les valeurs de Shapley, consultez [Attributions de fonctions utilisant des valeurs de Shapley](clarify-shapley-values.md). Cette fonctionnalité nécessite un modèle entraîné.
+ Des diagrammes de dépendance partielle (PDPs), qui peuvent vous aider à comprendre dans quelle mesure votre variable cible prévue changerait si vous faisiez varier la valeur d'une caractéristique. Pour plus d'informations PDPs, voir [Tracés de dépendance partielle (PDPs) Analyse](clarify-processing-job-analysis-results.md#clarify-processing-job-analysis-results-pdp) Cette fonctionnalité nécessite un modèle entraîné.
SageMaker Clarifier les besoins, modéliser les prédictions pour calculer les mesures de biais et les attributions de fonctionnalités après l'entraînement. Vous pouvez fournir un point de terminaison ou SageMaker Clarify créera un point de terminaison éphémère en utilisant le nom de votre modèle, également appelé point de terminaison *fantôme*. Le conteneur SageMaker Clarify supprime le point de terminaison fantôme une fois les calculs terminés. À un niveau élevé, le conteneur SageMaker Clarify effectue les étapes suivantes :
1. Il valide les entrées et les paramètres.
1. Il crée le point de terminaison miroir (si un nom de modèle est fourni).
1. Il charge le jeu de données en entrée dans un bloc de données.
1. Il obtient des prédictions de modèle à partir du point de terminaison, si nécessaire.
1. Il calcule les métriques de biais et les attributions de fonctionnalités.
1. Il supprime le point de terminaison miroir.
1. Il génère les résultats d'analyse.
Une fois la tâche de traitement SageMaker Clarify terminée, les résultats de l'analyse sont enregistrés à l'emplacement de sortie que vous avez spécifié dans le paramètre de sortie de traitement de la tâche. Ces résultats incluent un fichier JSON contenant les métriques de biais et les attributions de fonctionnalités globales, un rapport visuel et des fichiers supplémentaires pour les attributions de fonctionnalités locales. Vous pouvez télécharger ces résultats depuis l’emplacement de sortie et les consulter.
Pour plus d'informations sur les mesures de biais, l'explicabilité et leur interprétation, consultez [Découvrez comment Amazon SageMaker Clarify aide à détecter les biais](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias), les [mesures d'équité pour le Machine Learning dans le secteur de la finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf) et le livre blanc [Amazon AI Fairness and Explainability](https://pages.awscloud.com/rs/112-TZM-766/images/Amazon.AI.Fairness.and.Explainability.Whitepaper.pdf).
# Configurer un Job de traitement SageMaker Clarify
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 vous montre comment spécifier le nom du jeu de données en entrée, le nom du fichier de configuration d'analyse et l'emplacement de sortie pour une tâche de traitement. Pour configurer le conteneur de traitement, les entrées de tâches, les sorties, les ressources et les autres paramètres, vous avez deux options. Vous pouvez soit utiliser l'`CreateProcessingJob`API SageMaker AI, soit utiliser l'API SageMaker `SageMaker ClarifyProcessor` AI Python SDK,
Pour plus d'informations sur les paramètres communs à toutes les tâches de traitement, consultez [Amazon SageMaker API Reference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp).
## Configuration d'une tâche de traitement SageMaker Clarify à l'aide de l' SageMaker API
Les instructions suivantes montrent comment fournir chaque partie de la configuration spécifique de SageMaker Clarify à l'aide de l'`CreateProcessingJob`API.
1. Entrez l'identifiant de recherche uniforme (URI) d'une image de conteneur SageMaker Clarify dans le `AppSpecification` paramètre, comme indiqué dans l'exemple de code suivant.
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**Note**
L'URI doit identifier une image de conteneur SageMaker Clarify prédéfinie. `ContainerEntrypoint`et ne `ContainerArguments` sont pas pris en charge. Pour plus d'informations sur les images de conteneurs SageMaker Clarify, consultez[Conteneurs SageMaker Clarify préfabriqués](clarify-processing-job-configure-container.md).
1. Spécifiez à la fois la configuration de votre analyse et les paramètres de votre jeu de données en entrée dans le paramètre `ProcessingInputs`.
1. Spécifiez l'emplacement du fichier de configuration d'analyse JSON, qui inclut les paramètres d'analyse des biais et d'analyse d'explicabilité. Le paramètre `InputName` de l’objet `ProcessingInput` doit être **analysis\$1config** tel qu’illustré dans l’exemple de code suivant.
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
Pour plus d’informations sur le schéma du fichier de configuration d’analyse, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
1. Spécifiez l’emplacement du jeu de données d’entrée. Le paramètre `InputName` de l'objet `ProcessingInput` doit être `dataset`. Ce paramètre est facultatif si vous avez fourni le "dataset\$1uri" dans le fichier de configuration d'analyse. Les valeurs suivantes sont requises dans la configuration `S3Input`.
1. `S3Uri` peut être un objet Amazon S3 ou un préfixe S3.
1. `S3InputMode` doit être de type **File**.
1. `S3CompressionType` doit être de type `None` (valeur par défaut).
1. `S3DataDistributionType` doit être de type `FullyReplicated` (valeur par défaut).
1. `S3DataType` peut avoir la valeur `S3Prefix` ou `ManifestFile`. Pour être utilisé`ManifestFile`, le `S3Uri` paramètre doit spécifier l'emplacement d'un fichier manifeste qui suit le schéma de la section de référence de l' SageMaker API [S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri). Ce fichier manifeste doit répertorier les objets S3 contenant les données d'entrée pour la tâche.
Le code suivant montre un exemple de configuration d'entrée.
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. Spécifiez la configuration pour la sortie de la tâche de traitement dans le paramètre `ProcessingOutputConfig`. Un seul objet `ProcessingOutput` est requis dans la configuration `Outputs`. Les conditions suivantes sont requises dans la configuration de sortie :
1. `OutputName` doit avoir pour valeur **analysis\$1result**.
1. `S3Uri` doit être un préfixe S3 de l'emplacement de sortie.
1. `S3UploadMode` doit être défini sur **EndOfJob**.
Le code suivant montre un exemple de configuration de sortie.
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. Spécifiez la configuration `ClusterConfig` pour les ressources que vous utilisez dans votre tâche de traitement dans le paramètre `ProcessingResources`. Les paramètres suivants sont nécessaires à l'intérieur de l'objet `ClusterConfig`.
1. `InstanceCount` indique le nombre d'instances de calcul dans le cluster qui exécute la tâche de traitement. Spécifiez une valeur supérieure à `1` pour activer le traitement distribué.
1. `InstanceType` fait référence aux ressources qui exécutent votre tâche de traitement. L'analyse SageMaker AI SHAP étant gourmande en ressources informatiques, l'utilisation d'un type d'instance optimisé pour le calcul devrait améliorer le temps d'exécution de l'analyse. La tâche de traitement SageMaker Clarify n'utilise pas GPUs.
Le code suivant montre un exemple de configuration de ressource.
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. Spécifiez la configuration du réseau que vous utilisez dans votre tâche de traitement au sein de l'objet `NetworkConfig`. Les valeurs suivantes sont requises dans la configuration.
1. `EnableNetworkIsolation`doit être défini sur `False` (par défaut) afin que SageMaker Clarify puisse invoquer un point de terminaison, si nécessaire, pour les prédictions.
1. Si le modèle ou le point de terminaison que vous avez fourni à la tâche SageMaker Clarify se trouve dans un Amazon Virtual Private Cloud (Amazon VPC), la tâche SageMaker Clarify doit également se trouver dans le même VPC. Spécifiez le VPC à l'aide de. [VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html) En outre, le VPC doit disposer de points de terminaison vers un compartiment Amazon S3, un service AI et SageMaker un service SageMaker AI Runtime.
Si le traitement distribué est activé, vous devez également autoriser la communication entre les différentes instances d’une même tâche de traitement. Configurez une règle pour votre groupe de sécurité qui autorise les connexions entrantes entre les membres du même groupe de sécurité. Pour de plus amples informations, veuillez consulter [Donnez à Amazon SageMaker Clarify Jobs l'accès aux ressources de votre Amazon VPC](clarify-vpc.md).
Le code suivant montre un exemple de configuration réseau.
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. Définissez la durée maximale d'exécution de la tâche à l'aide du paramètre `StoppingCondition`. La durée maximale d'exécution d'une tâche SageMaker Clarify est de `7` jours ou de `604800` secondes. Si la tâche ne peut pas être terminée dans ce délai, elle sera arrêtée et aucun résultat d'analyse ne sera fourni. Par exemple, la configuration suivante limite la durée maximale d'exécution de la tâche à 3 600 secondes.
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. Spécifiez un rôle IAM pour le paramètre `RoleArn`. Le rôle doit entretenir une relation de confiance avec Amazon SageMaker AI. Il peut être utilisé pour effectuer les opérations SageMaker d'API répertoriées dans le tableau suivant. Nous vous recommandons d'utiliser la politique gérée Amazon SageMaker AIFull Access, qui accorde un accès complet à l' SageMaker IA. Pour plus d’informations sur cette politique, consultez [AWS politique gérée : AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess). Si vous avez des préoccupations concernant l’octroi d’un accès complet, les autorisations minimales requises varient selon que vous fournissez un modèle ou un nom de point de terminaison. L'utilisation d'un nom de point de terminaison permet d'accorder moins d'autorisations à l' SageMaker IA.
Le tableau suivant contient les opérations d'API utilisées par la tâche de traitement SageMaker Clarify. Un **X** sous **Nom du modèle** et **Nom du point de terminaison** indique l'opération d'API qui est requise pour chaque entrée.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
Pour plus d’informations sur les autorisations requises, consultez [Autorisations d'API Amazon SageMaker AI : référence sur les actions, les autorisations et les ressources](api-permissions-reference.md).
Pour plus d'informations sur le transfert de rôles à SageMaker l'IA, consultez[Transmission de rôles](sagemaker-roles.md#sagemaker-roles-pass-role).
Une fois que vous avez défini les éléments individuels de la configuration de la tâche de traitement, combinez-les pour configurer la tâche.
## Configuration d'une tâche de traitement SageMaker Clarify à l'aide du AWS SDK pour Python
L'exemple de code suivant montre comment lancer une tâche de traitement SageMaker Clarify à l'aide du [AWS SDK pour Python](https://aws.amazon.com/sdk-for-python/).
```
sagemaker_client.create_processing_job(
ProcessingJobName="your-clarify-job-name",
AppSpecification={
"ImageUri": "the-clarify-container-image-uri",
},
ProcessingInputs=[{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config",
},
}, {
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data",
},
},
],
ProcessingOutputConfig={
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output",
},
}],
},
ProcessingResources={
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20,
},
},
NetworkConfig={
"EnableNetworkIsolation": False,
"VpcConfig": {
...
},
},
StoppingCondition={
"MaxRuntimeInSeconds": 3600,
},
RoleArn="arn:aws:iam:::role/service-role/AmazonSageMaker-ExecutionRole",
)
```
Pour un exemple de bloc-notes contenant des instructions pour exécuter une tâche de traitement SageMaker Clarify à l'aide du AWS SDK pour Python, voir [Équité et explicabilité avec SageMaker Clarify à l'aide du AWS SDK](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb) pour Python. Tout compartiment S3 utilisé dans le bloc-notes doit se trouver dans la même AWS région que l'instance du bloc-notes qui y accède.
## Configuration d'une tâche de traitement SageMaker Clarify à l'aide du SDK SageMaker Python
Vous pouvez également configurer une tâche de traitement SageMaker Clarify [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)à l'aide de l'API du SDK SageMaker Python. Pour de plus amples informations, veuillez consulter [Exécutez des tâches de traitement SageMaker Clarify pour l'analyse des biais et l'explicabilité](clarify-processing-job-run.md).
**Topics**
+ [Conteneurs SageMaker Clarify préfabriqués](clarify-processing-job-configure-container.md)
+ [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md)
+ [Guide de compatibilité des formats de données](clarify-processing-job-data-format.md)
# Conteneurs SageMaker Clarify préfabriqués
Amazon SageMaker AI fournit des images de conteneur SageMaker Clarify prédéfinies qui incluent les bibliothèques et autres dépendances nécessaires pour calculer les mesures de biais et les attributions de fonctionnalités à des fins d'explication. Ces images sont capables d'exécuter des [tâches de traitement SageMaker ](processing-job.md) Clarify sur votre compte.
Les images URIs des conteneurs se présentent sous la forme suivante :
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
Par exemple :
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
Le tableau suivant répertorie les adresses par Région AWS.
Images Docker pour SageMaker clarifier les tâches de traitement
| Région | Adresse de l’image |
| --- | --- |
| USA Est (Virginie du Nord) | 205585389593.dkr. ecr.us-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| USA Est (Ohio) | 211330385671.dkr. ecr.us-east-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| USA Ouest (Californie du Nord) | 740489534195.dkr. ecr.us-west-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| USA Ouest (Oregon) | 306415355426.dkr. ecr.us-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Hong Kong) | 098760798382.dkr. ecr.ap-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Mumbai) | 452307495513.dkr. ecr.ap-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Jakarta) | 705930551576.dkr. ecr.ap-southeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Tokyo) | 377024640650.dkr. ecr.ap-northeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Séoul) | 263625296855.dkr. ecr.ap-northeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Osaka) | 912233562940.dkr. ecr.ap-northeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Singapour) | 834264404009.dkr. ecr.ap-southeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asie-Pacifique (Sydney) | 007051062584.dkr. ecr.ap-southeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Canada (Centre) | 675030665977.dkr. ecr.ca-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Francfort) | 017069133835.dkr. ecr.eu-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Zurich) | 730335477804.dkr. ecr.eu-central-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Irlande) | 131013547314.dkr. ecr.eu-west-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Londres) | 440796970383.dkr. ecr.eu-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Paris) | 341593696636.dkr. ecr.eu-west-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Stockholm) | 763603941244.dkr. ecr.eu-north-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Middle East (Bahrain) | 835444307964.dkr. ecr.me-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Amérique du Sud (São Paulo) | 520018980103.dkr. ecr.sa-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Afrique (Le Cap) | 811711786498.dkr. ecr.af-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europe (Milan) | 638885417683.dkr. ecr.eu-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Chine (Pékin) | 122526803553.dkr. ecr.cn-north-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
| Chine (Ningxia) | 122578899357.dkr. ecr.cn-northwest-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
# Fichiers de configuration d’analyse
Pour analyser vos données et modèles afin de déterminer s'ils sont explicables et biaisés à l'aide de SageMaker Clarify, vous devez configurer une tâche de traitement. Une partie de la configuration de cette tâche de traitement inclut la configuration d’un fichier d’analyse. Ce fichier d’analyse spécifie les paramètres de l’analyse des biais et de l’explicabilité. Consultez [Configurer un Job de traitement SageMaker Clarify](clarify-processing-job-configure-parameters.md) pour savoir comment configurer une tâche de traitement et un fichier d’analyse.
Ce guide décrit le schéma et les paramètres de ce fichier de configuration d’analyse. Ce guide inclut également des exemples de fichiers de configuration d’analyse pour le calcul des indicateurs de biais pour un jeu de données tabulaire et la génération d’explications pour les problèmes liés au traitement du langage naturel (NLP), à la vision par ordinateur et aux séries temporelles (TS).
Vous pouvez créer le fichier de configuration d'analyse ou utiliser le [SDK SageMaker Python](https://sagemaker.readthedocs.io/) pour en générer un pour vous avec l'[SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)API. L'affichage du contenu du fichier peut être utile pour comprendre la configuration sous-jacente utilisée par la tâche SageMaker Clarify.
**Topics**
+ [Schéma du fichier de configuration d'analyse](#clarify-processing-job-configure-schema)
+ [Exemples de fichiers de configuration d’analyse](#clarify-processing-job-configure-analysis-examples)
## Schéma du fichier de configuration d'analyse
La section suivante décrit le schéma du fichier de configuration d'analyse, y compris les exigences et les descriptions des paramètres.
### Exigences liées au fichier de configuration d'analyse
La tâche de traitement SageMaker Clarify s'attend à ce que le fichier de configuration d'analyse soit structuré selon les exigences suivantes :
+ Le nom de l'entrée de traitement doit être `analysis_config.`
+ Le fichier de configuration d'analyse est au format JSON et codé en UTF-8.
+ Le fichier de configuration d'analyse est un objet Amazon S3.
Vous pouvez spécifier des paramètres supplémentaires dans le fichier de configuration d'analyse. La section suivante propose différentes options permettant d'adapter la tâche de traitement SageMaker Clarify à votre cas d'utilisation et aux types d'analyse souhaités.
### Paramètres des fichiers de configuration d'analyse
Dans le fichier de configuration JSON, vous pouvez spécifier les paramètres suivants.
+ **version** : (facultatif) chaîne de version du schéma du fichier de configuration d'analyse. Si aucune version n'est fournie, SageMaker Clarify utilise la dernière version prise en charge. Actuellement, la seule version prise en charge est `1.0`.
+ **dataset\$1type** : format du jeu de données. Le format du jeu de données en entrée peut avoir l'une des valeurs suivantes :
+ Tabulaire
+ `text/csv` pour CSV
+ `application/jsonlines`pour le [format dense des lignes SageMaker AI JSON](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)
+ `application/json` pour JSON
+ `application/x-parquet` pour Apache Parquet
+ `application/x-image` pour activer l’explicabilité pour les problèmes de vision par ordinateur
+ Explications du modèle de prévision de séries temporelles
+ `application/json` pour JSON
+ **dataset\$1uri** : (facultatif) identifiant de ressource uniforme (URI) du jeu de données principal. 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. Vous pouvez fournir un préfixe d'URI S3 ou un URI S3 vers un fichier manifeste d'image pour les problèmes de vision par ordinateur. Si `dataset_uri` est fourni, il a priorité sur l’entrée de la tâche de traitement du jeu de données. Quel que soit le type de format, à l'exception des cas d'utilisation d'images et de séries chronologiques, la tâche de traitement SageMaker Clarify charge le jeu de données en entrée dans un bloc de données tabulaire, en tant que jeu de données **tabulaire**. Ce format permet à l' SageMaker IA de manipuler et d'analyser facilement le jeu de données d'entrée.
+ **headers** : (facultatif)
+ **Tabular :** tableau de chaînes contenant les noms de colonnes d’un jeu de données tabulaire. Si aucune valeur n'est fournie`headers`, la tâche de traitement SageMaker Clarify lit les en-têtes de l'ensemble de données. Si le jeu de données ne comporte pas d’en-têtes, la tâche de traitement Clarify génère automatiquement des noms d’espaces réservés sur la base d’un indice de colonne basé sur zéro. Par exemple, les noms des espaces réservés pour les première et deuxième colonnes seront **column\$10**, **column\$11**, etc.
**Note**
Par convention, if `dataset_type` a pour valeur `application/jsonlines` ou `application/json`, alors `headers` doit contenir les noms suivants dans l’ordre :
noms des caractéristiques
nom de l’étiquette (si `label` est spécifié)
nom de l’étiquette prédite (si `predicted_label` est spécifié)
Un exemple de `headers` pour un type de jeu de données `application/jsonlines` si `label` est spécifié est : `["feature1","feature2","feature3","target_label"]`.
+ **Série temporelle :** liste des noms de colonnes du jeu de données. Si ces données ne sont pas fournies, Clarify génère des en-têtes à utiliser en interne. Pour les cas d’explicabilité d’une série temporelle, fournissez les en-têtes dans l’ordre suivant :
1. identifiant de l’élément
1. timestamp
1. série temporelle cible
1. toutes les colonnes des séries temporelles associées
1. toutes les colonnes de covariables statiques
+ **label** : (facultatif) chaîne ou index entier basé sur zéro. S'il est fourni, `label` est utilisé pour localiser l'étiquette de vérité terrain, également connue sous le nom d'étiquette observée ou d'attribut cible dans un jeu de données tabulaire. L'étiquette de vérité terrain est utilisée pour calculer les métriques de biais. La valeur pour `label` est spécifiée en fonction de la valeur du paramètre `dataset_type`, comme suit.
+ Si `dataset_type` a pour valeur **text/csv**, `label` peut être spécifié comme l'un ou l'autre des éléments suivants :
+ Un nom de colonne valide
+ Un index compris dans la plage des colonnes du jeu de données
+ Si `dataset_type` a pour valeur **application/parquet**, `label` doit être un nom de colonne valide.
+ Si tel `dataset_type` est **application/jsonlines** le cas, `label` il doit s'agir [JMESPath](https://jmespath.org/)d'une expression écrite pour extraire l'étiquette de vérité fondamentale de l'ensemble de données. Par convention, si `headers` est spécifié, il doit contenir le nom de l'étiquette.
+ Si tel `dataset_type` est **application/json** le cas, `label` il doit s'agir [JMESPath](https://jmespath.org/)d'une expression écrite pour extraire l'étiquette de vérité fondamentale pour chaque enregistrement de l'ensemble de données. Cette JMESPath expression doit produire une liste d'étiquettes où le i the label est en corrélation avec le i de l'enregistrement.
+ **predicted\$1label** : (facultatif) chaîne ou index entier basé sur zéro. S'il est fourni, `predicted_label` est utilisé pour localiser la colonne contenant l'étiquette prédite dans un jeu de données tabulaire. L'étiquette prédite est utilisée pour calculer les **métriques de biais** de post-entraînement. Le paramètre `predicted_label` est facultatif si le jeu de données n'inclut pas l'étiquette prédite. Si des étiquettes prédites sont requises pour le calcul, la tâche de traitement SageMaker Clarify obtiendra des prédictions à partir du modèle.
La valeur pour `predicted_label` est spécifiée en fonction de la valeur du paramètre `dataset_type`, comme suit :
+ Si `dataset_type` a pour valeur **text/csv**, `predicted_label` peut être spécifié comme l'un ou l'autre des éléments suivants :
+ Nom de colonne valide. Si `predicted_label_dataset_uri` est spécifié mais que `predicted_label` n'est pas fourni, le nom d'étiquette prédite par défaut est "predicted\$1label".
+ Index compris dans la plage des colonnes du jeu de données. Si `predicted_label_dataset_uri` est spécifié, l'index est utilisé pour localiser la colonne d'étiquettes prédites dans le jeu de données d'étiquettes prédites.
+ Si dataset\$1type a pour valeur **application/x-parquet**, `predicted_label` doit être un nom de colonne valide.
+ Si dataset\$1type l'est**application/jsonlines**, il `predicted_label` doit s'agir d'une [JMESPath](https://jmespath.org/)expression valide écrite pour extraire l'étiquette prédite de l'ensemble de données. Par convention, si `headers` est spécifié, il doit contenir le nom de l'étiquette prédite.
+ Si tel `dataset_type` est **application/json** le cas, `predicted_label` il doit s'agir [JMESPath](https://jmespath.org/)d'une expression écrite pour extraire l'étiquette prévue pour chaque enregistrement de l'ensemble de données. L' JMESPath expression doit produire une liste d'étiquettes prédites où le i est destiné à l'enregistrement i.
+ **fonctionnalités** — (Facultatif) Obligatoire pour les cas non-time-series d'utilisation si `dataset_type` c'est le cas `application/jsonlines` ou`application/json`. Expression de JMESPath chaîne écrite pour localiser les entités dans le jeu de données en entrée. En `application/jsonlines` effet, une JMESPath expression sera appliquée à chaque ligne pour extraire les caractéristiques de cet enregistrement. En `application/json` effet, une JMESPath expression sera appliquée à l'ensemble du jeu de données en entrée. L' JMESPath expression doit extraire une liste de listes ou une 2D array/matrix d'entités où la i ème ligne contient les entités corrélées à l'enregistrement. Pour un `dataset_type` défini sur `text/csv` ou `application/x-parquet`, toutes les colonnes, à l'exception des colonnes d'étiquettes de vérité terrain et d'étiquettes prédites, sont automatiquement affectées comme des fonctionnalités.
+ **predicted\$1label\$1dataset\$1uri** : (facultatif) applicable uniquement lorsque dataset\$1type a pour valeur `text/csv`. URI S3 d’un jeu de données contenant les étiquettes prédites utilisées pour calculer les **indicateurs de biais** de post-entraînement. La tâche de traitement SageMaker Clarify chargera les prédictions à partir de l'URI fourni au lieu d'obtenir des prédictions à partir du modèle. Dans ce cas, `predicted_label` est requis pour localiser la colonne d'étiquettes prédites dans le jeu de données d'étiquettes prédites. Si le jeu de données d’étiquettes prédites ou le jeu de données principal est divisé en plusieurs fichiers, une colonne d’identifiants doit être spécifiée par `joinsource_name_or_index` pour joindre les deux jeux de données.
+ **predicted\$1label\$1headers** : (facultatif) applicable uniquement quand `predicted_label_dataset_uri` est spécifié. Tableau de chaînes contenant les noms de colonnes du jeu de données d’étiquettes prédites. Outre l'en-tête d'étiquette prédite, `predicted_label_headers` peut également contenir l'en-tête de la colonne d'identifiants pour joindre le jeu de données d'étiquette prédite et le jeu de données principal. Pour plus d'informations, consultez la description suivante du paramètre `joinsource_name_or_index`.
+ **joinsource\$1name\$1or\$1index** : (facultatif) nom ou indice basé sur zéro de la colonne dans les jeux de données tabulaires à utiliser comme colonne d’identification dans le cadre d’une jointure interne. Cette colonne est uniquement utilisée comme identifiant. Elle n'est pas utilisée pour d'autres calculs tels que l'analyse de biais ou l'analyse d'attribution de fonctionnalités. Une valeur pour `joinsource_name_or_index` est nécessaire dans les cas suivants :
+ Il existe plusieurs jeux de données en entrée et chacun d'eux est réparti entre plusieurs fichiers.
+ Le traitement distribué est activé en définissant la tâche de traitement SageMaker [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)Clarify sur une valeur supérieure à`1`.
+ **excluded\$1columns** : (facultatif) tableau de noms ou d’index basés sur zéro de colonnes à exclure de l’envoi au modèle en tant qu’entrée pour les prédictions. L’étiquette de vérité terrain et l’étiquette prédite sont déjà automatiquement exclues. Cette caractéristique n’est pas prise en charge pour les séries temporelles.
+ **probability\$1threshold** : (facultatif) nombre à virgule flottante au-dessus duquel une étiquette ou un objet sont sélectionnés. La valeur par défaut est `0.5`. La tâche de traitement SageMaker Clarify est utilisée `probability_threshold` dans les cas suivants :
+ Dans l'analyse des biais de post-entraînement, `probability_threshold` convertit une prédiction du modèle numérique (score ou valeur de probabilité) en étiquette binaire, si le modèle est un classificateur binaire. Un score supérieur au seuil est converti à `1`. En revanche, un score inférieur ou égal au seuil est converti à `0`.
+ Dans le cas de problèmes d'explicabilité de vision par ordinateur, si model\$1type a pour valeur **OBJECT\$1DETECTION**`, probability_threshold` filtre les objets détectés avec des scores de confiance inférieurs à la valeur seuil.
+ **label\$1values\$1or\$1threshold** : (facultatif) obligatoire pour l’analyse des biais. Tableau de valeurs d’étiquette ou valeur seuil indiquant un résultat positif pour la vérité terrain et les étiquettes prédites pour les indicateurs de biais. Pour plus d’informations, consultez les valeurs d’étiquette positives dans [Amazon SageMaker précise les termes relatifs à la partialité et à l'équité](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Si l’étiquette est numérique, le seuil est appliqué comme limite inférieure pour sélectionner le résultat positif. Pour définir `label_values_or_threshold` pour différents types de problèmes, reportez-vous aux exemples suivants :
+ Pour un problème de classification binaire, l'étiquette a deux valeurs possibles, `0` et `1`. Si la valeur d'étiquette `1` est favorable à un groupe démographique observé dans un échantillon, `label_values_or_threshold` doit être défini sur `[1]`.
+ Pour un problème de classification multi-classes, l'étiquette a trois valeurs possibles, **bird**, **cat** et **dog**. Si les deux derniers définissent un groupe démographique que le biais favorise, `label_values_or_threshold` doit être défini sur `["cat","dog"]`.
+ Pour un problème de régression, la valeur d'étiquette est continue, comprise entre `0` et `1`. Si une valeur supérieure à `0.5` doit indiquer qu'un échantillon a un résultat positif, `label_values_or_threshold` doit être défini sur `0.5`.
+ **facet** : (facultatif) requis pour l’analyse des biais. Tableau d’objets facettes, composés d’attributs sensibles par rapport auxquels le biais est mesuré. Vous pouvez utiliser des facettes pour comprendre les caractéristiques de biais de votre jeu de données et de votre modèle, même si votre modèle est entraîné sans utiliser d’attributs sensibles. Pour plus d’informations, consultez **Facette** dans [Amazon SageMaker précise les termes relatifs à la partialité et à l'équité](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Cet objet facette inclut les champs suivants :
+ **name\$1or\$1index** : (facultatif) nom ou indice basé sur zéro de la colonne d’attributs sensibles dans un jeu de données tabulaire. Si `facet_dataset_uri` est spécifié, l'index fait référence au jeu de données de facettes plutôt qu'au jeu de données principal.
+ **value\$1or\$1threshold** : (facultatif) requis si `facet` est numérique et si `label_values_or_threshold` est appliqué comme limite inférieure pour sélectionner le groupe sensible. Tableau de valeurs de facettes ou valeur seuil indiquant le groupe démographique sensible favorisé par le biais. Si le type de données des facettes est catégoriel et que `value_or_threshold` n'est pas fourni, les métriques de biais sont calculées comme un groupe pour chaque valeur unique (plutôt que toutes les valeurs). Pour définir `value_or_threshold` pour différents types de données de `facet`, reportez-vous aux exemples suivants :
+ Pour un type de données de facette binaire, la fonctionnalité a deux valeurs possibles, `0` et `1`. Si vous souhaitez calculer les métriques de biais pour chaque valeur, `value_or_threshold` peut être omis ou défini sur un tableau vide.
+ Pour un type de données de facette catégoriel, la fonctionnalité a trois valeurs possibles **bird**, **cat** et **dog**. Si les deux premières définissent un groupe démographique que le biais favorise, `value_or_threshold` doit être défini sur `["bird", "cat"]`. Dans cet exemple, les échantillons du jeu de données sont divisés en deux groupes démographiques. La facette du groupe avantagé a la valeur **bird** ou **cat**, tandis que celle du groupe défavorisé a la valeur **dog**.
+ Pour un type de données de facette numérique, la valeur de la fonctionnalité est continue, comprise entre `0` et `1`. Par exemple, si une valeur supérieure à `0.5` doit indiquer qu'un échantillon est favorisé, `value_or_threshold` doit être défini sur `0.5`. Dans cet exemple, les échantillons du jeu de données sont divisés en deux groupes démographiques. La facette du groupe avantagé a une valeur supérieure à `0.5`, tandis que la facette du groupe défavorisé a une valeur inférieure ou égale à `0.5`.
+ **group\$1variable** : (facultatif) nom ou indice basé sur zéro de la colonne qui indique le sous-groupe à utiliser pour l’indicateur de biais [Disparité démographique conditionnelle (CDD)](clarify-data-bias-metric-cddl.md) ou [Disparité démographique conditionnelle dans les étiquettes prédites (CDDPL)](clarify-post-training-bias-metric-cddpl.md).
+ **facet\$1dataset\$1uri** : (facultatif) applicable uniquement lorsque dataset\$1type a pour valeur `text/csv`. URI S3 d’un jeu de données contenant des attributs sensibles pour l’analyse des biais. Vous pouvez utiliser des facettes pour comprendre les caractéristiques de biais de votre jeu de données et de votre modèle, même si votre modèle est entraîné sans utiliser d'attributs sensibles.
**Note**
Si le jeu de données de facettes ou le jeu de données principal est divisé en plusieurs fichiers, une colonne d'identifiants doit être spécifiée par `joinsource_name_or_index` pour joindre les deux jeux de données. Vous devez utiliser le paramètre `facet` pour identifier chaque facette du jeu de données de facettes.
+ **facet\$1headers** : (facultatif) applicable uniquement quand `facet_dataset_uri` est spécifié. Tableau de chaînes contenant les noms de colonnes pour le jeu de données de facettes et, éventuellement, en-tête de colonne d’identifiants pour joindre le jeu de données de facettes et le jeu de données principal. Consultez `joinsource_name_or_index`.
+ **time\$1series\$1data\$1config** : (facultatif) spécifie la configuration à utiliser pour le traitement des données d’une série temporelle.
+ **item\$1id** : chaîne ou indice entier basé sur zéro. Ce champ est utilisé pour localiser un identifiant d’élément dans le jeu de données d’entrée partagé.
+ **timestamp** : chaîne ou indice entier basé sur zéro. Ce champ est utilisé pour localiser un horodatage dans le jeu de données d’entrée partagé.
+ **dataset\$1format** : les valeurs possibles sont `columns`, `item_records` ou `timestamp_records`. Ce champ est utilisé pour décrire le format d’un jeu de données JSON, qui est le seul format pris en charge pour l’explicabilité des séries temporelles.
+ **target\$1time\$1series** — JMESPath Chaîne ou index entier basé sur zéro. Ce champ est utilisé pour localiser la série temporelle cible dans le jeu de données d’entrée partagé. Si ce paramètre est une chaîne, tous les autres paramètres, à l’exception de `dataset_format`, doivent être des chaînes ou des listes de chaînes. Si ce paramètre est un entier, tous les autres paramètres, à l’exception de `dataset_format`, doivent être des entiers ou des listes d’entiers.
+ **related\$1time\$1series** — (Facultatif) Un tableau d'expressions. JMESPath Ce champ est utilisé pour localiser toutes les séries temporelles associées dans le jeu de données d’entrée partagé, le cas échéant.
+ **static\$1covariates** — (Facultatif) Un tableau d'expressions. JMESPath Ce champ est utilisé pour localiser tous les champs de covariables statiques dans le jeu de données d’entrée partagé, le cas échéant.
Pour obtenir des exemples, consultez [Exemples de configuration de jeux de données de séries temporelles](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex).
+ **methods** : objet contenant une ou plusieurs méthodes d’analyse et leurs paramètres. Si une méthode est omise, elle n'est pas utilisée pour l'analyse ni signalée.
+ **pre\$1training\$1bias** : incluez cette méthode si vous souhaitez calculer des métriques de biais de pré-entraînement. Vous trouverez la description détaillée des métriques dans [Indicateurs de biais de pré-entraînement](clarify-measure-data-bias.md). L’objet possède les paramètres suivants :
+ **methods** : tableau contenant une ou plusieurs des métriques de biais de pré-entraînement de la liste suivante que vous souhaitez calculer. Définissez `methods` sur **all** pour calculer toutes les métriques de biais de pré-entraînement. À titre d’exemple, le tableau `["CI", "DPL"]` calculera le **déséquilibre de classe** et la **différence dans les proportions d’étiquettes**.
+ `CI` pour [Déséquilibre de classe (CI)](clarify-bias-metric-class-imbalance.md)
+ `DPL` pour [Différence dans les proportions d'étiquettes (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ `KL` pour [Divergence de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ `JS` pour [Divergence de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ `LP` pour [Norme Lp (LP)](clarify-data-bias-metric-lp-norm.md)
+ `TVD` pour [Distance de variation totale (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ `KS` pour [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ `CDDL` pour [Disparité démographique conditionnelle (CDD)](clarify-data-bias-metric-cddl.md)
+ **post\$1training\$1bias** : incluez cette méthode si vous souhaitez calculer des métriques de biais de post-entraînement. Vous trouverez la description détaillée des métriques dans [Indicateurs de biais de post-entraînement dans les données et les modèles](clarify-measure-post-training-bias.md). L’objet `post_training_bias` possède les paramètres suivants.
+ **methods** : tableau contenant une ou plusieurs des métriques de biais de post-entraînement de la liste suivante que vous souhaitez calculer. Définissez `methods` sur **all** pour calculer toutes les métriques de biais de post-entraînement. Par exemple, le tableau `["DPPL", "DI"]` calcule la **différence entre les proportions positives des étiquettes prédites** et l'**impact disparate**. Les méthodes disponibles sont les suivantes :
+ `DPPL` pour [Différence dans les proportions positives des étiquettes prédites (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ `DI` pour [Impact disparate (DI)](clarify-post-training-bias-metric-di.md)
+ `DCA` pour [Différence d'acceptation conditionnelle (DCAcc)](clarify-post-training-bias-metric-dcacc.md)
+ `DCR` pour [Différence dans les rejets conditionnels (DCR)](clarify-post-training-bias-metric-dcr.md)
+ `SD` pour [Différence de spécificité (SD)](clarify-post-training-bias-metric-sd.md)
+ `RD` pour [Différence de rappel (RD)](clarify-post-training-bias-metric-rd.md)
+ `DAR` pour [Différence dans les taux d'acceptation (DAR)](clarify-post-training-bias-metric-dar.md)
+ `DRR` pour [Différence dans les taux de rejets (DRR)](clarify-post-training-bias-metric-drr.md)
+ `AD` pour [Différence de précision (AD)](clarify-post-training-bias-metric-ad.md)
+ `TE` pour [Égalité de traitement (TE)](clarify-post-training-bias-metric-te.md)
+ `CDDPL` pour [Disparité démographique conditionnelle dans les étiquettes prédites (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ `FT` pour [FlipTest contrefactuel (FT)](clarify-post-training-bias-metric-ft.md)
+ `GE` pour [Entropie généralisée (GE)](clarify-post-training-bias-metric-ge.md)
+ **shap** : incluez cette méthode si vous souhaitez calculer des valeurs SHAP. La tâche de traitement SageMaker Clarify prend en charge l'algorithme Kernel SHAP. L'objet `shap` possède les paramètres suivants.
+ **baseline** : (facultatif) jeu de données de référence SHAP, également appelé jeu de données d’arrière-plan. Les exigences supplémentaires relatives au jeu de données de référence dans un jeu de données tabulaire ou un problème de vision par ordinateur sont les suivantes. Pour plus d’informations sur les références SHAP, consultez [Bases de référence SHAP pour l’explicabilité](clarify-feature-attribute-shap-baselines.md)
+ Pour un jeu de données **tabulaire**, `baseline` peut correspondre aux données de référence sur place ou à l’URI S3 d’un fichier de référence. Si `baseline` ce n'est pas le cas, la tâche de traitement SageMaker Clarify calcule une ligne de base en regroupant le jeu de données en entrée. La base de référence doit respecter les exigences suivantes :
+ Le format doit être identique au format du jeu de données spécifié par `dataset_type`.
+ La base de référence ne peut contenir que les fonctionnalités que le modèle peut accepter en entrée.
+ Le jeu de données de référence peut comporter une ou plusieurs instances. Le nombre d'instances de référence affecte directement la taille du jeu de données synthétique et la durée d'exécution de la tâche.
+ Si `text_config` est spécifié, la valeur de référence d'une colonne de texte est une chaîne utilisée pour remplacer l'unité de texte spécifiée par `granularity`. Par exemple, un espace réservé courant est "[MASK]". Il est utilisé pour représenter un mot ou un extrait de texte manquant ou inconnu.
Les exemples suivants montrent comment définir des données de référence sur place pour différents paramètres `dataset_type` :
+ Si `dataset_type` a pour valeur `text/csv` ou `application/x-parquet`, le modèle accepte quatre fonctionnalités numériques, et la base de référence comporte deux instances. Dans cet exemple, si un enregistrement a toutes ses valeurs de fonctionnalités égales à 0 et que l'autre enregistrement a toutes ses valeurs de fonctionnalités égales à 1, la base de référence doit être définie sur `[[0,0,0,0],[1,1,1,1]]`, sans aucun en-tête.
+ Si `dataset_type` a pour valeur `application/jsonlines`, `features` est la clé d'une liste de quatre valeurs de fonctionnalités numériques. En outre, dans cet exemple, si la base de référence contient un seul enregistrement dont toutes les valeurs sont égales à 0, `baseline` doit être `[{"features":[0,0,0,0]}]`.
+ Si `dataset_type` a pour valeur `application/json`, le jeu de données `baseline` doit avoir la même structure et le même format que le jeu de données en entrée.
+ Pour les problèmes de **vision par ordinateur**, `baseline` peut être l'URI S3 d'une image utilisée pour masquer des fonctionnalités (segments) de l'image en entrée. La tâche de traitement SageMaker Clarify charge l'image du masque et la redimensionne à la même résolution que l'image d'entrée. Si aucune ligne de base n'est fournie, la tâche de traitement SageMaker Clarify génère une image de masque de [bruit blanc](https://en.wikipedia.org/wiki/White_noise) à la même résolution que l'image d'entrée.
+ **features\$1to\$1explain** : (facultatif) tableau de chaînes ou d'index basés sur zéro de colonnes de fonctionnalités pour lesquelles calculer les valeurs SHAP. Si `features_to_explain` n'est pas fourni, les valeurs SHAP sont calculées pour toutes les colonnes de fonctionnalités. Ces colonnes de fonctionnalités ne peuvent pas inclure la colonne d'étiquettes ni la colonne d'étiquettes prédites. Le paramètre `features_to_explain` n'est pris en charge que pour les jeux de données tabulaires comportant des colonnes numériques et catégorielles.
+ **num\$1clusters** : (facultatif) nombre de clusters dans lesquels le jeu de données est divisé pour calculer le jeu de données de référence. Chaque cluster est utilisé pour calculer une seule instance de référence. Si `baseline` ce n'est pas spécifié, la tâche de traitement SageMaker Clarify tente de calculer le jeu de données de référence en divisant le jeu de données tabulaire en un nombre optimal de clusters compris entre `1` et`12`. Le nombre d'instances de référence affecte directement l'exécution de l'analyse SHAP.
+ **num\$1samples** : (facultatif) nombre d'échantillons à utiliser dans l'algorithme Kernel SHAP. Si `num_samples` ce n'est pas le cas, la tâche de traitement SageMaker Clarify choisit le numéro pour vous. Le nombre d'échantillons affecte directement la taille du jeu de données synthétique et la durée d'exécution de la tâche.
+ **seed** : (facultatif) nombre entier utilisé pour initialiser le générateur de nombres pseudo-aléatoires dans l'outil d'explication SHAP afin de générer des valeurs SHAP cohérentes pour une même tâche. Si seed n'est pas spécifié, chaque fois qu'une même tâche s'exécute, le modèle peut générer des valeurs SHAP légèrement différentes.
+ **use\$1logit** : (facultatif) valeur booléenne indiquant si vous voulez appliquer la fonction logit aux prédictions de modèle. La valeur par défaut est `false` . Si `use_logit` a pour valeur `true`, les valeurs SHAP sont calculées à l'aide des coefficients de régression logistique, qui peuvent être interprétés comme des ratios log-odds.
+ **save\$1local\$1shap\$1values** : (facultatif) valeur booléenne qui indique si vous souhaitez que les valeurs SHAP locales de chaque enregistrement du jeu de données soient incluses dans le résultat de l'analyse. La valeur par défaut est `false` .
Si le jeu de données principal est divisé en plusieurs fichiers ou si le traitement distribué est activé, spécifiez également une colonne d'identifiants à l'aide du paramètre `joinsource_name_or_index`. La colonne d'identifiants et les valeurs SHAP locales sont enregistrées dans le résultat de l'analyse. Ainsi, vous pouvez mapper chaque enregistrement à ses valeurs SHAP locales.
+ **agg\$1method** : (facultatif) méthode utilisée pour agréger les valeurs SHAP locales (valeurs SHAP pour chaque instance) de toutes les instances avec les valeurs SHAP globales (valeurs SHAP pour le jeu de données entier). La valeur par défaut est `mean_abs` . Les méthodes suivantes peuvent être utilisées pour agréger les valeurs SHAP.
+ **mean\$1abs** : moyenne des valeurs SHAP locales absolues de toutes les instances.
+ **mean\$1sq** : moyenne des valeurs SHAP locales au carré de toutes les instances.
+ **median** : médiane des valeurs SHAP locales de toutes les instances.
+ **text\$1config** : nécessaire pour l’explicabilité du traitement du langage naturel. Incluez cette configuration si vous souhaitez traiter les colonnes de texte comme du texte et des explications doivent être fournies pour les unités de texte individuelles. Pour un exemple de configuration d’analyse pour l’explicabilité du traitement du langage naturel, consultez [Configuration d'analyse pour l'explicabilité du traitement du langage naturel](#clarify-analysis-configure-nlp-example).
+ **granularity** : unité de granularité pour l’analyse des colonnes de texte. Les valeurs valides sont `token`, `sentence` ou `paragraph`. **Chaque unité de texte est considérée comme une fonctionnalité** et les valeurs SHAP locales sont calculées pour chaque unité.
+ **language** : langue des colonnes de texte. Les valeurs valides sont **chinese**, **danish**, **dutch**, **english**, **french**, **german**, **greek**, **italian**, **japanese**, **lithuanian**, **multi-language**, **norwegian bokmål**, **polish**, **portuguese**, **romanian**, **russian**, **spanish**, **afrikaans**, **albanian**, **arabic**, **armenian**, **basque**, **bengali**, **bulgarian**, **catalan**, **croatian**, **czech**, **estonian**, **finnish**, **gujarati**, **hebrew**, **hindi**, **hungarian**, **icelandic**, **indonesian**, **irish**, **kannada**, **kyrgyz**, **latvian**, **ligurian**, **luxembourgish**, **macedonian**, **malayalam**, **marathi**, **nepali**, **persian**, **sanskrit**, **serbian**, **setswana**, **sinhala**, **slovak**, **slovenian**, **swedish**, **tagalog**, **tamil**, **tatar**, **telugu**, **thai**, **turkish**, **ukrainian**, **urdu**, **vietnamese**, **yoruba**. Entrez `multi-language` pour un mélange de plusieurs langues.
+ **max\$1top\$1tokens** : (facultatif) nombre maximal de jetons principaux, basé sur les valeurs SHAP globales. La valeur par défaut est `50` . Il est possible qu'un jeton apparaisse plusieurs fois dans le jeu de données. La tâche de traitement SageMaker Clarify agrège les valeurs SHAP de chaque jeton, puis sélectionne les meilleurs jetons en fonction de leurs valeurs SHAP globales. Les valeurs SHAP globales des jetons principaux sélectionnés sont incluses dans la section `global_top_shap_text` du fichier analysis.json.
+ Valeur SHAP locale d'agrégation.
+ **image\$1config** : nécessaire pour l'explicabilité de la vision par ordinateur. Incluez cette configuration si vous disposez d'un jeu de données en entrée composé d'images et que vous souhaitez les analyser afin de déterminer l'explicabilité dans un problème de vision par ordinateur.
+ **model\$1type** : type du modèle. Les valeurs valides sont les suivantes :
+ `IMAGE_CLASSIFICATION` pour un modèle de classification d'image.
+ `OBJECT_DETECTION` pour un modèle de détection d'objet.
+ **max\$1objects** : applicable uniquement quand model\$1type a pour valeur **OBJECT\$1DETECTION**. Nombre maximal d'objets, ordonnés par score de confiance, détectés par le modèle de vision par ordinateur. Tous les objets classés en dessous des max\$1objects objets principaux en termes de score de confiance sont retirés par filtrage. La valeur par défaut est `3` .
+ **context** : applicable uniquement quand model\$1type a pour valeur **OBJECT\$1DETECTION**. Il indique si la zone autour du cadre de délimitation de l'objet détecté est masquée par l'image de référence ou non. Les valeurs valides sont `0` pour tout masquer, ou `1` pour ne rien masquer. La valeur par défaut est 1.
+ **iou\$1threshold** : applicable uniquement quand `model_type` a pour valeur **OBJECT\$1DETECTION**. Métrique d'intersection minimale sur union (IOU) pour évaluer les prédictions par rapport à la détection initiale. Une métrique IOU élevée correspond à un chevauchement important entre le cadre de détection de valeur prédite et le cadre de détection de vérité terrain. La valeur par défaut est `0.5` .
+ **num\$1segments** : (facultatif) entier qui détermine le nombre approximatif de segments à étiqueter dans l'image en entrée. Chaque segment de l'image est considéré comme une fonctionnalité et les valeurs SHAP locales sont calculées pour chaque segment. La valeur par défaut est `20` .
+ **segment\$1compactness** : (facultatif) entier qui détermine la forme et la taille des segments d'image générés par la méthode [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic). La valeur par défaut est `5` .
+ **pdp** — Incluez cette méthode pour calculer les diagrammes de dépendance partielle (PDPs). Pour un exemple de configuration d'analyse à générer PDPs, voir [Calculer des diagrammes de dépendance partielle (PDPs)](#clarify-analysis-configure-csv-example-pdp)
+ **features** : obligatoire si la méthode `shap` n’est pas demandée. Tableau de noms de fonctionnalités ou d'index permettant de calculer et de tracer des graphiques PDP.
+ **top\$1k\$1features** : (facultatif) spécifie le nombre de fonctionnalités principales utilisées pour générer des graphiques PDP. Si `features` ce n'est pas le cas, mais que la `shap` méthode est demandée, la tâche de traitement SageMaker Clarify choisit les principales fonctionnalités en fonction de leurs attributions SHAP. La valeur par défaut est `10` .
+ **grid\$1resolution** : nombre de compartiments dans lesquels diviser la plage de valeurs numériques. Cela spécifie la granularité de la grille pour les graphiques PDP.
+ **asymmetric\$1shapley\$1value** : incluez cette méthode si vous souhaitez calculer des métriques d’explicabilité pour les modèles de prévision de séries temporelles. La tâche de traitement SageMaker Clarify prend en charge l'algorithme de valeurs asymétriques de Shapley. Les valeurs de Shapley asymétriques sont une variante de la valeur de Shapley qui supprime l’axiome de symétrie. Pour plus d’informations, consultez [Asymmetric Shapley values: incorporating causal knowledge into model-agnostic explainability](https://arxiv.org/abs/1910.06358). Utilisez ces valeurs pour déterminer dans quelle mesure les caractéristiques contribuent aux résultats des prévisions. Les valeurs de Shapley asymétriques prennent en compte les dépendances temporelles des données de séries temporelles que les modèles de prévision acceptent en entrée.
L’algorithme inclut les paramètres suivants :
+ **direction** : les types disponibles sont `chronological`, `anti_chronological` et `bidirectional`. La structure temporelle peut être parcourue dans l’ordre chronologique, antichronologique ou les deux. Les explications chronologiques sont élaborées en ajoutant des informations de manière itérative dès la première étape temporelle. Les explications antichronologiques ajoutent des informations en partant de la dernière étape et en revenant en arrière. Ce dernier ordre peut être plus approprié en présence d’un biais de récence, par exemple pour la prévision du cours des actions.
+ **granularity** : la granularité des explications à utiliser. Les options de granularité disponibles sont les suivantes :
+ **timewise** : les explications `timewise` sont peu coûteuses et fournissent des informations uniquement sur des étapes temporelles spécifiques, par exemple pour déterminer dans quelle mesure les informations du nième jour dans le passé ont contribué à la prévision du m-ième jour dans le futur. Les attributions qui en résultent n’expliquent pas les covariables statiques individuelles et ne font pas de distinction entre les séries temporelles cibles et associées.
+ **fine\$1grained** : les explications `fine_grained` sont plus gourmandes en calculs mais fournissent une ventilation complète de toutes les attributions des variables d’entrée. La méthode calcule des explications approximatives pour réduire le temps d’exécution. Pour plus d’informations, consultez le paramètre `num_samples` suivant.
**Note**
Les explications `fine_grained` prennent en charge uniquement l’ordre `chronological`.
+ **num\$1samples** : (facultatif) cet argument est obligatoire pour les explications `fine_grained`. Plus le nombre est élevé, plus l’approximation est précise. Ce nombre doit évoluer proportionnellement à la dimensionnalité des caractéristiques d’entrée. En règle générale, définissez cette variable sur *(1 \$1 max(nombre de séries temporelles associées, nombre de covariables statiques))^2* si le résultat n’est pas trop important.
+ **baseline** — (Facultatif) La configuration de référence pour remplacer out-of-coalition les valeurs des ensembles de données correspondants (également appelés données d'arrière-plan). L’extrait de code suivant montre un exemple de configuration de référence :
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ Pour les données temporelles telles que les séries temporelles cibles ou les séries temporelles associées, les types de valeur de référence peuvent être l’une des valeurs suivantes :
+ `zero`— Toutes les out-of-coalition valeurs sont remplacées par 0,0.
+ `mean`— Toutes les out-of-coalition valeurs sont remplacées par la moyenne d'une série chronologique.
+ Pour les covariables statiques, une entrée de référence ne doit être fournie que lorsque la demande de modèle prend les valeurs des covariables statiques, auquel cas ce champ est requis. La référence doit être fournie pour chaque élément sous forme de liste. Par exemple, si vous avez un jeu de données avec deux covariables statiques, votre configuration de référence peut être la suivante :
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
Dans l'exemple précédent, ** et ** sont les identifiants des éléments de l'ensemble de données.
+ **report** : (facultatif) utilisez cet objet pour personnaliser le rapport d’analyse. Ce paramètre n’est pas pris en charge pour les tâches d’explication de séries temporelles. Le résultat de l’analyse contient trois copies du même rapport : un rapport de bloc-notes Jupyter, un rapport HTML et un rapport PDF. L'objet possède les paramètres suivants :
+ **name** : nom de fichier des fichiers de rapport. Par exemple, si `name` a pour valeur **MyReport**, les fichiers de rapport sont `MyReport.ipynb`, `MyReport.html` et `MyReport.pdf`. La valeur par défaut est `report` .
+ **title** : (facultatif) chaîne de titre du rapport. La valeur par défaut est **SageMaker AI Analysis Report** .
+ **predictor** : requis si l’analyse nécessite des prédictions issues du modèle. Par exemple, quand la méthode `shap`, `asymmetric_shapley_value`, `pdp` ou `post_training_bias` est demandée, mais que les étiquettes prédites ne sont pas fournies dans le cadre du jeu de données d’entrée. Les paramètres suivants doivent être utilisés conjointement à `predictor` :
+ **model\$1name** — Le nom de votre modèle d' SageMaker IA créé par l'[CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)API. Si vous spécifiez `model_name` plutôt que endpoint\$1name, la tâche de traitement SageMaker Clarify crée un point de terminaison éphémère portant le nom du modèle, connu sous le nom de point de terminaison **fictif, et obtient des prédictions à partir du point de terminaison**. Une fois les calculs terminés, la tâche supprime le point de terminaison miroir. Si le modèle est multi-modèle, le paramètre `target_model` doit être spécifié. Pour plus d’informations à propos de l’utilisation des points de terminaison multimodèles, consultez [Points de terminaison multimodèles](multi-model-endpoints.md).
+ **endpoint\$1name\$1prefix** : (facultatif) préfixe de nom personnalisé pour le point de terminaison miroir. Applicable si vous spécifiez `model_name` à la place de `endpoint_name`. Par exemple, spécifiez `endpoint_name_prefix` si vous souhaitez restreindre l'accès au point de terminaison par le nom de point de terminaison. Le préfixe doit correspondre au [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName)modèle et sa longueur maximale est `23` de. La valeur par défaut est `sm-clarify` .
+ **initial\$1instance\$1count** : spécifie le nombre d'instances pour le point de terminaison miroir. Requis si vous spécifiez model\$1name à la place de endpoint\$1name. La valeur pour `initial_instance_count` peut être différente de celle [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)de la tâche, mais nous recommandons un ratio de 1:1.
+ **instance\$1type** : spécifie le type d'instance pour le point de terminaison miroir. Requis si vous spécifiez `model_name` à la place de `endpoint_name`. Par exemple, `instance_type` peut être défini sur "ml.m5.large". Dans certains cas, la valeur spécifiée pour `instance_type` peut contribuer à réduire le temps d'inférence de modèle. Par exemple, pour fonctionner efficacement, les modèles de traitement du langage naturel et les modèles de vision par ordinateur nécessitent généralement un type d’instance d’unité de traitement graphique (GPU).
+ **endpoint\$1name — Le nom** de votre point de terminaison SageMaker AI créé par l'API. [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) S’il est fourni, `endpoint_name` a priorité sur le paramètre `model_name`. L'utilisation d'un point de terminaison existant réduit le temps d'amorçage du point de terminaison miroir, mais elle peut également entraîner une augmentation significative de la charge de ce point de terminaison. En outre, certaines méthodes d'analyse (telles que `shap` et `pdp`) génèrent des jeux de données synthétiques qui sont envoyés au point de terminaison. Cela peut entraîner la contamination des métriques du point de terminaison ou des données capturées par des données synthétiques, qui peuvent ne pas refléter avec précision l'utilisation réelle. Pour ces raisons, il n'est généralement pas recommandé d'utiliser un point de production existant pour l'analyse SageMaker Clarify.
+ **target\$1model** — La valeur de chaîne transmise au TargetModel paramètre de l' SageMaker API AI. [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) Requis si votre modèle (spécifié par le paramètre model\$1name) ou votre point de terminaison (spécifié par le paramètre endpoint\$1name) est multimodèle. Pour plus d’informations à propos de l’utilisation des points de terminaison multimodèles, consultez [Points de terminaison multimodèles](multi-model-endpoints.md).
+ **custom\$1attributes** : (facultatif) chaîne qui vous permet de fournir des informations supplémentaires sur une demande d’inférence soumise au point de terminaison. La valeur de chaîne est transmise au `CustomAttributes` paramètre de l'[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ **content\$1type** :format d’entrée de modèle à utiliser pour obtenir des prédictions à partir du point de terminaison. S'il est fourni, il est transmis au `ContentType` paramètre de l'[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ Pour l’explicabilité de la vision par ordinateur, les valeurs valides sont **image/jpeg**, **image/png** ou **application/x-npy**. Si `content_type` n’est pas fourni, la valeur par défaut est **image/jpeg**.
+ Pour l’explicabilité des prévisions de séries temporelles, la valeur valide est **application/json**.
+ Pour les autres types d’explicabilité, les valeurs valides sont **text/csv**, **application/jsonlines,** et **application/json**. Une valeur pour `content_type` est requise si `dataset_type` a pour valeur **application/x-parquet**. Dans le cas contraire, `content_type` a pour valeur par défaut la valeur du paramètre `dataset_type`.
+ **accept\$1type** : format de sortie du modèle à utiliser pour obtenir des prédictions à partir du point de terminaison. La valeur pour `accept_type` est transmise au `Accept` paramètre de l'[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ Pour l’explicabilité de la vision par ordinateur, si `model_type` a pour valeur "OBJECT\$1DETECTION", `accept_type` a pour valeur par défaut **application/json**.
+ Pour l’explicabilité des prévisions de séries temporelles, la valeur valide est **application/json**.
+ Pour les autres types d’explicabilité, les valeurs valides sont **text/csv**, **application/jsonlines** et **application/json**. Si aucune valeur n'est fournie pour `accept_type`, `accept_type` a pour valeur par défaut la valeur du paramètre `content_type`.
+ **content\$1template** : chaîne de modèle utilisée pour construire l'entrée de modèle à partir d'enregistrements de jeu de données. Le paramètre `content_template` est utilisé et requis seulement si la valeur du paramètre `content_type` est `application/jsonlines` ou `application/json`.
Quand le paramètre `content_type` a pour valeur `application/jsonlines`, le modèle doit avoir un seul espace réservé, `$features`, qui est remplacé par une liste de fonctionnalités au moment de l'exécution. Par exemple, si le modèle est `"{\"myfeatures\":$features}"` et qu'un enregistrement comporte trois valeurs de fonctionnalités numériques : `1`, `2` et `3`, l'enregistrement est envoyé au modèle sous forme de ligne JSON `{"myfeatures":[1,2,3]}`.
Quand `content_type` a pour valeur `application/json`, le modèle peut avoir l'espace réservé `$record` ou `records`. Si l'espace réservé est `record`, un enregistrement individuel est remplacé par un enregistrement auquel le modèle figurant dans `record_template` est appliqué. Dans ce cas, un seul enregistrement est envoyé au modèle à la fois. Si l'espace réservé est `$records`, les enregistrements sont remplacés par une liste d'enregistrements, chacun avec un modèle fourni par `record_template`.
+ **record\$1template** : chaîne de modèle à utiliser pour construire chaque enregistrement de l'entrée de modèle à partir des instances du jeu de données. Il est utilisé et requis seulement quand `content_type` a pour valeur `application/json`. La chaîne de modèle peut contenir l'un des éléments suivants :
+ Un paramètre `$features` d'espace réservé qui est remplacé par un tableau de valeurs de fonctionnalités. Un espace réservé facultatif supplémentaire peut remplacer les noms des en-têtes des colonnes de fonctionnalités dans `$feature_names`. Cet espace réservé facultatif sera remplacé par un tableau de noms de fonctionnalités.
+ Un et un seul espace réservé `$features_kvp`, qui est remplacé par les paires clé-valeur, le nom de fonctionnalité et la valeur de fonctionnalité.
+ Une fonctionnalité dans la configuration de `headers`. Par exemple, un nom de fonctionnalité `A`, noté par la syntaxe d'espace réservé `"${A}"`, sera remplacé par la valeur de fonctionnalité pour `A`.
La valeur pour `record_template` est utilisée avec `content_template` pour construire l'entrée de modèle. Voici un exemple de configuration montrant comment construire une entrée de modèle à l'aide d'un modèle de contenu et d'enregistrement.
Dans l'exemple de code suivant, les en-têtes et les fonctionnalités sont définis comme suit.
+ ``headers`:["A", "B"]`
+ ``features`:[[0,1], [3,4]]`
Voici l'exemple d'entrée de modèle :
```
{
"instances": [[0, 1], [3, 4]],
"feature_names": ["A", "B"]
}
```
Les exemples de valeurs des paramètres `content_template` et `record_template` permettant de construire l'exemple d'entrée de modèle précédent sont les suivants.
+ `content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"`
+ `record_template: "$features"`
Dans l'exemple de code suivant, les en-têtes et les fonctionnalités sont définis comme suit.
```
[
{ "A": 0, "B": 1 },
{ "A": 3, "B": 4 },
]
```
Les exemples de valeurs des paramètres ` content_template` et `record_template` permettant de construire l'exemple d'entrée de modèle précédent sont les suivants.
+ `content_template: "$records"`
+ `record_template: "$features_kvp"`
Voici un autre exemple de code pour construire l'exemple d'entrée de modèle précédent.
+ `content_template: "$records"`
+ `record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"`
Dans l'exemple de code suivant, les en-têtes et les fonctionnalités sont définis comme suit.
```
{ "A": 0, "B": 1 }
```
Les exemples de valeurs des paramètres content\$1template et record\$1template utilisés pour construire l’exemple d’entrée de modèle précédent sont les suivants.
+ `content_template: "$record"`
+ `record_template: "$features_kvp"`
Pour obtenir plus d’exemples, consultez [Demandes de données de séries temporelles aux points de terminaison](clarify-processing-job-data-format-time-series-request-jsonlines.md).
+ **label** — (Facultatif) Indice entier de base zéro ou chaîne JMESPath d'expression utilisé pour extraire les étiquettes prédites de la sortie du modèle à des fins d'analyse des biais. Si le modèle est multiclasse et que le paramètre `label` extrait toutes les étiquettes prédites de la sortie du modèle, les points suivants s’appliquent. Cette caractéristique n’est pas prise en charge pour les séries temporelles.
+ Le paramètre `probability` est requis pour obtenir les probabilités (ou scores) correspondantes à partir de la sortie du modèle.
+ L'étiquette prédite du score le plus élevé est choisie.
La valeur de `label` dépend de la valeur du paramètre accept\$1type, comme suit.
+ Si `accept_type` a pour valeur **text/csv**, `label` est l'index de toutes les étiquettes prédites dans la sortie du modèle.
+ If `accept_type` is **application/jsonlines** or**application/json**, then `label` est une JMESPath expression appliquée à la sortie du modèle pour obtenir les étiquettes prédites.
+ **label\$1headers** : (facultatif) tableau de valeurs que l’étiquette peut prendre dans le jeu de données. Si une analyse de biais est demandée, le paramètre `probability` est également requis pour obtenir les valeurs de probabilité correspondantes (scores) à partir de la sortie du modèle et l’étiquette prédite du score le plus élevé est choisie. Si une analyse d'explicabilité est demandée, les en-têtes des étiquettes sont utilisés pour embellir le rapport d'analyse. Une valeur pour `label_headers` est requise pour l'explicabilité de la vision par ordinateur. Par exemple, pour un problème de classification multi-classes, si l’étiquette a trois valeurs possibles, **bird**, **cat** et **dog**, `label_headers` doit être défini sur `["bird","cat","dog"]`.
+ **probabilité** — (Facultatif) Indice entier basé sur zéro ou chaîne d' JMESPath expression utilisé pour extraire des probabilités (scores) pour une analyse d'explicabilité (mais pas pour l'explicabilité des séries chronologiques), ou pour choisir l'étiquette prédite pour l'analyse des biais. La valeur de `probability` dépend de la valeur du paramètre `accept_type`, comme suit.
+ Si `accept_type` a pour valeur **text/csv**, `probability` est l'index des probabilités (scores) figurant dans la sortie du modèle. Si `probability` n'est pas fourni, la totalité de la sortie du modèle est considérée comme les probabilités (scores).
+ S'il s'`accept_type`agit de données JSON (**application/jsonlines**ou**application/json**), `probability` il doit s'agir JMESPath d'une expression utilisée pour extraire les probabilités (scores) de la sortie du modèle.
+ **time\$1series\$1predictor\$1config** : (facultatif) utilisé uniquement pour l’explicabilité des séries temporelles. Utilisé pour indiquer au processeur SageMaker Clarify comment analyser correctement les données à partir des données transmises sous forme d'URI S3. `dataset_uri`
+ **forecast** — JMESPath Expression utilisée pour extraire le résultat de la prévision.
## Exemples de fichiers de configuration d’analyse
Les sections suivantes contiennent des exemples de fichiers de configuration d’analyse pour des données au format CSV et au format JSON Lines, ainsi que pour l’explicabilité du traitement du langage naturel (NLP), de la vision par ordinateur et des séries temporelles (TS).
### Configuration d’analyse pour un jeu de données CSV
Les exemples suivants montrent comment configurer l'analyse des biais et 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. L'ensemble de données est fourni à la tâche SageMaker Clarify par l'entrée `dataset` de traitement.
```
"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
...
```
Les sections suivantes montrent comment calculer les mesures de biais avant et après l'entraînement, les valeurs SHAP et les diagrammes de dépendance partielle (PDPs) indiquant l'importance des fonctionnalités pour un ensemble de données au format CSV.
#### Calcul de toutes les métriques de biais de pré-entraînement
Cet exemple de configuration montre comment mesurer si l'exemple de jeu de données précédent est favorablement biaisé en faveur des échantillons avec une valeur de **Gender** égale à `0`. La configuration d'analyse suivante indique à la tâche de traitement SageMaker Clarify de calculer toutes les mesures de biais préalables à l'entraînement pour l'ensemble de données.
```
{
"dataset_type": "text/csv",
"label": "Target",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### Calcul de toutes les métriques de biais de post-entraînement
Vous pouvez calculer les métriques de biais de pré-entraînement avant l'entraînement. Toutefois, vous devez disposer d'un modèle entraîné pour calculer les métriques de biais de post-entraînement. 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
...
```
L'exemple de configuration suivant indique à la tâche de traitement SageMaker Clarify de calculer toutes les mesures de biais possibles à l'aide du jeu de données et des prédictions issues de la sortie du modèle. Dans l'exemple, le modèle est déployé sur un point de terminaison d' SageMaker IA`your_endpoint`.
**Note**
Dans l’exemple de code suivant, 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\$1type, qui est `text/csv`.
```
{
"dataset_type": "text/csv",
"label": "Target",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"label": 0
}
}
```
#### Calcul des valeurs SHAP
L'exemple de configuration d'analyse suivant indique à la tâche de calculer les valeurs SHAP désignant la colonne `Target` comme des étiquettes et toutes les autres colonnes comme des fonctionnalités.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
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 de base SHAP. Dans cet exemple, la probabilité est définie sur `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).
#### Calculer des diagrammes de dépendance partielle (PDPs)
L'exemple suivant montre comment visualiser l'importance de la `Income` fonctionnalité dans le rapport d'analyse à l'aide de PDPs. Le paramètre report indique à la tâche de traitement SageMaker Clarify de générer un rapport. Une fois la tâche terminée, le rapport généré est enregistré en tant que report.pdf à l'emplacement `analysis_result`. Le paramètre `grid_resolution` divise la plage de valeurs des caractéristiques en `10` compartiments. Ensemble, les paramètres spécifiés dans l'exemple suivant indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour les `Income` `10` segments sur l'axe X. L’axe Y montre l’impact marginal de `Income` sur les prédictions.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"pdp": {
"features": ["Income"],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
},
}
```
#### Calcul simultané des métriques de biais et de l'importance des fonctionnalités
Vous pouvez combiner toutes les méthodes des exemples de configuration précédents dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées.
Dans cet exemple, le paramètre `probability` est défini sur `1` pour indiquer que les probabilités sont contenues dans la deuxième colonne (en utilisant une indexation basée sur zéro). Toutefois, comme l'analyse des biais nécessite une étiquette prédite, le paramètre `probability_threshold` est défini sur `0.5` pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre `top_k_features` de la méthode `pdp` des graphiques de dépendance partielle est défini sur `2`. Cela indique à la tâche de traitement SageMaker Clarify de calculer des diagrammes de dépendance partiels (PDPs) pour les principales `2` entités présentant les valeurs SHAP globales les plus élevées.
```
{
"dataset_type": "text/csv",
"label": "Target",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
Au lieu de déployer le modèle sur un point de terminaison, vous pouvez fournir le nom de votre modèle d' SageMaker IA à la tâche de traitement SageMaker Clarify à l'aide du `model_name` paramètre. L’exemple suivant montre comment spécifier un modèle nommé **your\$1model**. La tâche de traitement SageMaker Clarify créera un point de terminaison fictif à l'aide de la configuration.
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### Configuration d'analyse pour un jeu de données JSON Lines
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 JSON Lines. 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 dense SageMaker AI 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. L'ensemble de données est fourni à la tâche SageMaker Clarify par l'entrée de traitement « ensemble de données ». Pour plus d’informations sur les lignes JSON, consultez [Format de demande JSONLINES](cdf-inference.md#cm-jsonlines).
```
{"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}
...
```
Les sections suivantes montrent comment calculer les métriques de biais avant et après l'entraînement, les valeurs SHAP et les diagrammes de dépendance partielle (PDPs) indiquant l'importance des fonctionnalités pour un ensemble de données au format JSON Lines.
#### Calcul des métriques de biais de pré-entraînement
Spécifiez l'étiquette, les fonctionnalités, le format et les méthodes pour mesurer les métriques de biais de pré-entraînement pour une valeur `Gender` de `0`. Dans l'exemple suivant, le paramètre `headers` fournit d'abord les noms des fonctionnalités. Le nom d'étiquette est fourni en dernier. Par convention, le dernier en-tête est l'en-tête d'étiquette.
Le `features` paramètre est défini sur l' JMESPath expression « Features » afin que la tâche de traitement SageMaker Clarify puisse extraire le tableau de caractéristiques de chaque enregistrement. Le `label` paramètre est défini sur JMESPath l'expression « Label » afin que la tâche de traitement SageMaker Clarify puisse extraire l'étiquette Ground Truth de chaque enregistrement. Utilisez un nom de facette pour spécifier l'attribut sensible, comme suit.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### Calcul de toutes les métriques de biais
Vous devez disposer d'un modèle entraîné pour calculer 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}
...
```
Vous pouvez déployer le modèle sur un point de terminaison d' SageMaker IA nommé`your_endpoint`. L'exemple de configuration d'analyse suivant indique à la tâche de traitement SageMaker Clarify de calculer toutes les mesures de biais possibles pour le jeu de données et le modèle. Dans cet exemple, les paramètres `content_type` et `accept_type` ne sont pas définis. Par conséquent, ils sont définis automatiquement sur la valeur du paramètre dataset\$1type, 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.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"label": "predicted_label"
}
}
```
#### Calcul des valeurs SHAP
Comme l'analyse SHAP ne nécessite pas d'étiquette de vérité terrain, le paramètre `label` est omis. Dans cet exemple, le paramètre `headers` est également omis. Par conséquent, la tâche de traitement SageMaker Clarify doit générer des espaces réservés utilisant des noms génériques tels que `column_0` ou `column_1` pour les en-têtes de fonctionnalités et `label0` pour un en-tête d'étiquette. Vous pouvez spécifier des valeurs pour `headers` et pour `label` afin d'améliorer la lisibilité du résultat de l'analyse. Le paramètre de probabilité étant défini sur JMESPath expression`probability`, la valeur de probabilité sera extraite de la sortie du modèle. Voici un exemple de calcul des valeurs SHAP.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### Calculer les diagrammes de dépendance partiels () PDPs
L'exemple suivant montre comment visualiser l'importance de "Income" (revenus) sur un graphique PDP. Dans cet exemple, les en-têtes des fonctionnalités ne sont pas fournis. Par conséquent, le paramètre `features` de la méthode `pdp` doit utiliser un index basé sur zéro pour faire référence à l’emplacement de la colonne de caractéristiques. Le paramètre `grid_resolution` divise la plage de valeurs des caractéristiques en `10` compartiments. Ensemble, les paramètres de l'exemple indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour `Income` les `10` segments sur l'axe X. L’axe Y montre l’impact marginal de `Income` sur les prédictions.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"pdp": {
"features": [2],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### Calcul simultané des métriques de biais et de l'importance des fonctionnalités
Vous pouvez combiner toutes les méthodes précédentes dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées. Dans cet exemple, le paramètre `probability` est défini. Cependant, comme l'analyse des biais nécessite une étiquette prédite, le paramètre `probability_threshold` est défini sur `0.5` pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre `top_k_features` de la méthode `pdp` est défini sur `2`. Cela indique à la tâche de traitement SageMaker Clarify de calculer PDPs les principales `2` fonctionnalités présentant les valeurs SHAP globales les plus élevées.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
### Configuration d'analyse pour un jeu de données JSON
Les exemples suivants montrent comment configurer l’analyse des biais et de l’explicabilité pour un jeu de données tabulaire au format JSON. 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 dense SageMaker AI JSON. Pour plus d’informations sur les lignes JSON, consultez [Format de demande JSONLINES](cdf-inference.md#cm-jsonlines).
L’ensemble de la demande en entrée est une demande JSON valide où la structure externe est une liste et chaque élément correspond aux données d’un enregistrement. Dans chaque enregistrement, la clé `Features` pointe sur un tableau de valeurs de fonctionnalités et la clé `Label` pointe sur l'étiquette de vérité terrain. L'ensemble de données est fourni à la tâche SageMaker Clarify par l'entrée `dataset` de traitement.
```
[
{"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},
...
]
```
Les sections suivantes montrent comment calculer les métriques de biais avant et après l'entraînement, les valeurs SHAP et les diagrammes de dépendance partielle (PDPs) qui montrent l'importance des fonctionnalités pour un ensemble de données au format JSON Lines.
#### Calcul des métriques de biais de pré-entraînement
Spécifiez l'étiquette, les fonctionnalités, le format et les méthodes pour mesurer les métriques de biais de pré-entraînement pour une valeur `Gender` de `0`. Dans l'exemple suivant, le paramètre `headers` fournit d'abord les noms des fonctionnalités. Le nom d'étiquette est fourni en dernier. Pour les jeux de données JSON, le dernier en-tête est l'en-tête d'étiquette.
Le `features` paramètre est défini sur l' JMESPath expression qui extrait un tableau ou une matrice 2D. Chaque ligne de cette matrice doit contenir la liste de `Features` pour chaque enregistrement. Le `label` paramètre est défini sur une JMESPath expression qui extrait une liste d'étiquettes de vérité fondamentale. Chaque élément de cette liste doit contenir l'étiquette d'un enregistrement.
Utilisez un nom de facette pour spécifier l'attribut sensible, comme suit.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### Calcul de toutes les métriques de biais
Vous devez disposer d'un modèle entraîné pour calculer les métriques de biais de post-entraînement. L'exemple de code suivant provient d'un modèle de classification binaire qui fournit en sortie des données JSON dans le format de l'exemple. Dans cet exemple, chaque élément sous `predictions` est la sortie de prédiction d'un enregistrement. Cet exemple de code contient la clé `predicted_label`, qui pointe vers l’étiquette prédite, et la clé `probability` pointe vers la valeur de probabilité.
```
{
"predictions": [
{"predicted_label":0,"probability":0.028986845165491},
{"predicted_label":1,"probability":0.825382471084594},
...
]
}
```
Vous pouvez déployer le modèle sur un point de terminaison d' SageMaker IA nommé`your_endpoint`.
Dans l’exemple suivant, les paramètres `content_type` et `accept_type` ne sont pas définis. Par conséquent, `content_type` et `accept_type` sont définis automatiquement pour utiliser la valeur du paramètre `dataset_type`, qui est `application/json`. La tâche de traitement SageMaker Clarify utilise ensuite le `content_template` paramètre pour composer l'entrée du modèle.
Dans l'exemple suivant, l'entrée du modèle est composée en remplaçant l'espace réservé `$records` par un tableau d'enregistrements. Le paramètre `record_template` compose ensuite la structure JSON de chaque enregistrement et remplace l'espace réservé `$features` par le tableau de fonctionnalités de chaque enregistrement.
L'exemple de configuration d'analyse suivant indique à la tâche de traitement SageMaker Clarify de calculer toutes les mesures de biais possibles pour le jeu de données et le modèle.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"label": "predictions[*].predicted_label"
}
}
```
#### Calcul des valeurs SHAP
Vous n'avez pas besoin de spécifier d'étiquette pour l'analyse SHAP. Dans l'exemple suivant, le paramètre `headers` n'est pas spécifié. Par conséquent, la tâche de traitement SageMaker Clarify générera des espaces réservés utilisant des noms génériques tels que `column_0` ou `column_1` pour les en-têtes de fonctionnalités et `label0` pour un en-tête d'étiquette. Vous pouvez spécifier des valeurs pour `headers` et pour `label` afin d'améliorer la lisibilité du résultat de l'analyse.
Dans l'exemple de configuration suivant, le paramètre de probabilité est défini sur une JMESPath expression qui extrait les probabilités de chaque prédiction pour chaque enregistrement. Voici un exemple de calcul des valeurs SHAP.
```
{
"dataset_type": "application/json",
"features": "[*].Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
#### Calculer des diagrammes de dépendance partielle (PDPs)
L'exemple suivant vous montre comment afficher l'importance d'une fonctionnalité dans PDPs. Dans cet exemple, les en-têtes des fonctionnalités ne sont pas fournis. Par conséquent, le paramètre `features` de la méthode `pdp` doit utiliser un index basé sur zéro pour faire référence à l'emplacement de la colonne de fonctionnalités. Le paramètre `grid_resolution` divise la plage de valeurs des caractéristiques en `10` compartiments.
Ensemble, les paramètres de l'exemple suivant indiquent à la tâche de traitement SageMaker Clarify de générer un rapport contenant un graphique PDP pour `Income` les `10` segments sur l'axe X. L'axe Y montre l'impact marginal de `Income` sur les prédictions.
L'exemple de configuration suivant montre comment évaluer l'importance de `Income` on PDPs.
```
{
"dataset_type": "application/json",
"features": "[*].Features",
"methods": {
"pdp": {
"features": [2],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
#### Calcul simultané des métriques de biais et de l'importance des fonctionnalités
Vous pouvez combiner toutes les méthodes de configuration précédentes dans un fichier de configuration d'analyse unique et les calculer toutes à l'aide d'une seule tâche. L'exemple suivant montre une configuration d'analyse avec toutes les étapes combinées.
Dans cet exemple, le paramètre `probability` est défini. Comme l'analyse des biais nécessite une étiquette prédite, le paramètre `probability_threshold` est défini sur `0.5` et est utilisé pour convertir le score de probabilité en étiquette binaire. Dans cet exemple, le paramètre `top_k_features` de la méthode `pdp` est défini sur `2`. Cela indique à la tâche de traitement SageMaker Clarify de calculer PDPs les principales `2` fonctionnalités présentant les valeurs SHAP globales les plus élevées.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
### Configuration d'analyse pour l'explicabilité du traitement du langage naturel
L'exemple suivant montre un fichier de configuration d'analyse permettant de calculer l'importance des fonctionnalités pour le traitement du langage naturel (NLP). Dans cet exemple, le jeu de données entrant est un jeu de données tabulaire au format CSV, avec une seule colonne d'étiquettes binaires et deux colonnes de fonctionnalités, comme suit. L'ensemble de données est fourni à la tâche SageMaker Clarify par le paramètre d'entrée de `dataset` traitement.
```
0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...
```
Dans cet exemple, un modèle de classification binaire a été entraîné sur le jeu de données précédent. Le modèle accepte les données CSV et produit un score unique compris entre `0` et `1`, comme suit.
```
0.491656005382537
0.569582343101501
...
```
Le modèle est utilisé pour créer un modèle d' SageMaker IA nommé « your\$1model ». La configuration d’analyse suivante montre comment exécuter une analyse d’explicabilité par jeton à l’aide du modèle et du jeu de données. Le paramètre `text_config` 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. L'exemple suivant montre également comment fournir une instance "baseline" SHAP sur place en utilisant une note ("Rating") moyenne de 4. Un jeton de masque spécial "[MASK]" est utilisé pour remplacer un jeton (mot) dans les commentaires ("Comments"). Cet exemple utilise également un type d'instance de point de terminaison GPU pour accélérer l'inférence.
```
{
"dataset_type": "text/csv",
"headers": ["Target","Rating","Comments"]
"label": "Target",
"methods": {
"shap": {
"text_config": {
"granularity": "token",
"language": "english"
}
"baseline": [[4,"[MASK]"]],
}
},
"predictor": {
"model_name": "your_nlp_model",
"initial_instance_count": 1,
"instance_type": "ml.g4dn.xlarge"
}
}
```
### Configuration d'analyse pour l'explicabilité de la vision par ordinateur
L'exemple suivant montre un fichier de configuration d'analyse calculant l'importance des fonctionnalités pour la vision par ordinateur. Dans cet exemple, le jeu de données en entrée est constitué d'images JPEG. L'ensemble de données est fourni à la tâche SageMaker Clarify par le paramètre d'entrée de `dataset` traitement. L'exemple montre comment configurer une analyse d'explicabilité à l'aide d'un modèle de classification d' SageMaker images. Dans cet exemple, un modèle nommé `your_cv_ic_model` a été entraîné pour classer les animaux sur les images JPEG en entrée.
```
{
"dataset_type": "application/x-image",
"methods": {
"shap": {
"image_config": {
"model_type": "IMAGE_CLASSIFICATION",
"num_segments": 20,
"segment_compactness": 10
}
},
"report": {
"name": "report"
}
},
"predictor": {
"model_name": "your_cv_ic_model",
"initial_instance_count": 1,
"instance_type": "ml.p2.xlarge",
"label_headers": ["bird","cat","dog"]
}
}
```
Pour plus d’informations sur la classification des images, consultez [Classification des images - MXNet](image-classification.md).
Dans cet exemple, un [modèle de détection d'objets basé sur l'SageMaker IA](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html) `your_cv_od_model` est entraîné sur les mêmes images JPEG afin d'identifier les animaux qui s'y trouvent. L’exemple suivant montre comment configurer une analyse d’explicabilité pour le modèle de détection d’objet.
```
{
"dataset_type": "application/x-image",
"probability_threshold": 0.5,
"methods": {
"shap": {
"image_config": {
"model_type": "OBJECT_DETECTION",
"max_objects": 3,
"context": 1.0,
"iou_threshold": 0.5,
"num_segments": 20,
"segment_compactness": 10
}
},
"report": {
"name": "report"
}
},
"predictor": {
"model_name": "your_cv_od_model",
"initial_instance_count": 1,
"instance_type": "ml.p2.xlarge",
"label_headers": ["bird","cat","dog"]
}
}
```
### Configuration d’analyse pour l’explicabilité du modèle de prévision des séries temporelles
L’exemple suivant montre un fichier de configuration d’analyse pour le calcul de l’importance des caractéristiques pour une série temporelle (TS). Dans cet exemple, le jeu de données entrant est un jeu de données de séries temporelles au format JSON avec un jeu de caractéristiques de covariables dynamiques et statiques. L'ensemble de données est fourni à la tâche SageMaker Clarify par le paramètre d'entrée de traitement de l'ensemble de données`dataset_uri`.
```
[
{
"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
},
]
```
Les sections suivantes expliquent comment calculer les attributions de caractéristiques pour un modèle de prévision à l’aide de l’algorithme de valeurs de Shapley asymétriques pour un jeu de données JSON.
#### Calcul des explications pour les modèles de prévision de séries temporelles
L’exemple de configuration d’analyse suivant affiche les options utilisées par la tâche pour calculer les explications pour les modèles de prévision des séries temporelles.
```
{
'dataset_type': 'application/json',
'dataset_uri': 'DATASET_URI',
'methods': {
'asymmetric_shapley_value': {
'baseline': {
"related_time_series": "zero",
"static_covariates": {
"item1": [0, 0], "item2": [0, 0]
},
"target_time_series": "zero"
},
'direction': 'chronological',
'granularity': 'fine_grained',
'num_samples': 10
},
'report': {'name': 'report', 'title': 'Analysis Report'}
},
'predictor': {
'accept_type': 'application/json',
'content_template': '{"instances": $records}',
'endpoint_name': 'ENDPOINT_NAME',
'content_type': 'application/json',
'record_template': '{
"start": $start_time,
"target": $target_time_series,
"dynamic_feat": $related_time_series,
"cat": $static_covariates
}',
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
},
'time_series_data_config': {
'dataset_format': 'timestamp_records',
'item_id': '[].item_id',
'related_time_series': ['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
'static_covariates': ['[].static_feature_1', '[].static_feature_2'],
'target_time_series': '[].target_value',
'timestamp': '[].timestamp'
}
}
```
##### Configuration de l’explicabilité des séries temporelles
L’exemple précédent utilise `asymmetric_shapley_value` dans `methods` pour définir les arguments d’explicabilité 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. Ces champs indiquent au processeur SageMaker Clarify de calculer les attributions de fonctionnalités pour un élément à la fois.
##### Configuration du prédicteur
Vous pouvez contrôler entièrement la structure de charge utile envoyée par le processeur SageMaker Clarify à l'aide de JMESPath la syntaxe. Dans l’exemple précédent, la configuration `predictor` indique à Clarify d’agréger les enregistrements dans `'{"instances": $records}'`, chaque enregistrement étant défini avec les arguments donnés pour `record_template` dans l’exemple. 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.
De même, l’attribut `forecast` dans `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, la réponse par lots de votre point de terminaison peut être la suivante :
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
Supposons que vous spécifiez la configuration du prédicteur de série temporelle suivante :
```
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
```
La valeur de prévision est analysée comme suit :
```
[
[13.4, 3.6],
[23.0, 4.7],
[3.4, 5.6]
]
```
##### Configuration des données
Utilisez l'`time_series_data_config`attribut pour demander au processeur SageMaker Clarify d'analyser correctement les données à partir des données transmises sous forme d'URI S3. `dataset_uri`
# Guide de compatibilité des formats de données
Ce guide décrit les types de formats de données compatibles avec les tâches de traitement SageMaker Clarify. Les types de format de données pris en charge incluent les extensions de fichier, la structure des données et des exigences ou restrictions spécifiques pour les jeux de données tabulaires, d’images et de séries temporelles. Ce guide explique également comment vérifier si votre jeu de données est conforme à ces exigences.
À un niveau élevé, la tâche de traitement SageMaker Clarify suit le modèle entrée-processus-sortie pour calculer les métriques de biais et les attributions de fonctionnalités. Consultez les exemples suivants pour plus de détails.
Les entrées de la tâche de traitement SageMaker Clarify sont les suivantes :
+ Le jeu de données à analyser
+ La configuration d’analyse Pour plus d’informations sur la manière de configurer une analyse, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Au cours de la phase de traitement, SageMaker Clarify calcule les métriques de biais et les attributions de fonctionnalités. La tâche de traitement SageMaker Clarify effectue les étapes suivantes dans le backend :
+ La tâche de traitement SageMaker Clarify analyse votre configuration d'analyse et charge votre **ensemble de données**.
+ Pour calculer les métriques de biais et les attributions de fonctionnalités de post-entraînement, la tâche nécessite des prédictions de modèle à partir de votre modèle. **La tâche de traitement SageMaker Clarify sérialise vos données et les envoie sous forme de **demande** à votre modèle qui est déployé sur un point de terminaison d'inférence en temps réel SageMaker basé sur l'IA.** Ensuite, la tâche de traitement SageMaker Clarify extrait les prédictions de la **réponse**.
+ La tâche de traitement SageMaker Clarify effectue l'analyse du biais et de l'explicabilité, puis produit les résultats.
Pour plus d’informations, consultez [Comment fonctionnent les tâches SageMaker Clarify Processing](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works).
Le paramètre que vous utilisez pour spécifier le format des données dépend de l'endroit où les données sont utilisées dans le flux de traitement, comme suit :
+ Pour un **jeu de données en entrée**, utilisez le paramètre `dataset_type` pour spécifier le format ou le type MIME.
+ Pour une **demande** adressée à un point de terminaison, utilisez le paramètre `content_type` pour spécifier le format.
+ Pour une **réponse** provenant d'un point de terminaison, utilisez le paramètre `accept_type` pour spécifier le format.
Le jeu de données en entrée, la demande et la réponse en direction et en provenance du point de terminaison ne nécessitent pas le même format. Par exemple, vous pouvez utiliser un jeu de données Parquet avec une charge utile de **demande** CSV et une charge utile de **réponse** JSON Lines dans les conditions suivantes.
+ Votre analyse est correctement configurée.
+ Votre modèle prend en charge les formats de demande et de réponse.
**Note**
S'`content_type``accept_type`ils ne sont pas fournis, le conteneur SageMaker Clarify en déduit le `content_type` et`accept_type`.
**Topics**
+ [Données tabulaires](clarify-processing-job-data-format-tabular.md)
+ [Exigences relatives aux données d’image](clarify-processing-job-data-format-image.md)
+ [Données de séries temporelles](clarify-processing-job-data-format-time-series.md)
# Données tabulaires
Les données tabulaires font référence à des données qui peuvent être chargées dans un bloc de données bidimensionnel. Dans ce bloc, chaque ligne représente un enregistrement et chaque enregistrement comporte une ou plusieurs colonnes. Les valeurs de chaque cellule du bloc de données peuvent être de type numérique, catégoriel ou texte.
## Prérequis relatifs aux jeux de données tabulaires
Avant l'analyse, toutes les étapes de prétraitement nécessaires devraient déjà avoir été appliquées à votre jeu de données. Cela inclut le nettoyage des données ou l'ingénierie des fonctionnalités.
Vous pouvez fournir un ou plusieurs jeux de données. Si vous fournissez plusieurs ensembles de données, utilisez ce qui suit pour les identifier dans le cadre de la tâche de traitement SageMaker Clarify.
+ Utilisez une configuration [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)nommée `dataset` ou la configuration d'analyse `dataset_uri` pour spécifier le jeu de données principal. Pour plus d’informations sur `dataset_uri`, reportez-vous à la liste des paramètres dans [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
+ Utilisez le paramètre `baseline` fourni dans le fichier de configuration d’analyse. Le jeu de données de référence est requis pour l’analyse SHAP. Pour plus d’informations sur le fichier de configuration d’analyse, y compris des exemples, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Le tableau suivant répertorie les formats de données pris en charge, leurs extensions de fichier et les types MIME.
| Format de données | Extension de fichier | Type MIME |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| JSON Lines | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | "application/x-parquet" |
Les sections suivantes présentent des exemples de jeux de données tabulaires aux formats CSV, JSON Lines et Apache Parquet.
### Prérequis relatifs aux jeux de données tabulaires au format CSV
La tâche de traitement SageMaker Clarify est conçue pour charger des fichiers de données CSV dans le dialecte [csv .excel.](https://docs.python.org/3/library/csv.html#csv.excel) Toutefois, il est suffisamment flexible pour prendre en charge d'autres délimiteurs de ligne, notamment `\n` et `\r`.
Pour des raisons de compatibilité, tous les fichiers de données CSV fournis à la tâche de traitement SageMaker Clarify doivent être codés en UTF-8.
Si votre jeu de données ne contient pas de ligne d'en-têtes, procédez comme suit :
+ Définissez l'étiquette de configuration d'analyse sur l'index `0`. Cela signifie que la première colonne est l'étiquette de vérité terrain.
+ Si le paramètre `headers` est défini, définissez `label` sur l'en-tête de la colonne d'étiquettes pour indiquer l'emplacement de la colonne d'étiquettes. Toutes les autres colonnes sont désignées comme des fonctionnalités.
Voici un exemple de jeu de données qui ne contient pas de ligne d'en-têtes.
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
Si vos données contiennent une ligne d'en-têtes, définissez le paramètre `label` sur l'index `0`. Pour indiquer l'emplacement de la colonne d'étiquettes, utilisez l'en-tête de l'étiquette de vérité terrain `Label`. Toutes les autres colonnes sont désignées comme des fonctionnalités.
Voici un exemple de jeu de données qui contient une ligne d'en-têtes.
```
Label,Rating,A12,A13,Comments
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
### Prérequis des jeux de données tabulaires au format JSON
Le format JSON est un format flexible permettant de représenter des données structurées qui contiennent un niveau quelconque de complexité. La prise en charge de JSON par SageMaker Clarify n'est limitée à aucun format spécifique et permet donc des formats de données plus flexibles par rapport aux ensembles de données au format CSV ou JSON Lines. Ce guide explique comment définir une configuration d'analyse pour des données tabulaires au format JSON.
**Note**
Pour garantir la compatibilité, tous les fichiers de données JSON fournis à la tâche de traitement SageMaker Clarify doivent être codés en UTF-8.
Voici un exemple de données d'entrée avec des enregistrements contenant une clé de niveau supérieur, une liste de fonctionnalités et une étiquette.
```
[
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0},
...
]
```
Un exemple de configuration d'analyse pour l'exemple de jeu de données en entrée précédent doit définir les paramètres suivants :
+ Le `label` paramètre doit utiliser l'[JMESPath](https://jmespath.org/)expression `[*].label` pour extraire l'étiquette de vérité fondamentale pour chaque enregistrement de l'ensemble de données. L' JMESPath expression doit produire une liste d'étiquettes où le i the label correspond au i the record.
+ Le `features` paramètre doit utiliser l' JMESPathexpression `[*].features` pour extraire un tableau d'entités pour chaque enregistrement de l'ensemble de données. L' JMESPath expression doit produire un tableau ou une matrice 2D dans lequel la première ligne contient les valeurs des caractéristiques correspondant à l'enregistrement.
Voici un exemple de données d'entrée avec des enregistrements contenant une clé de niveau supérieur et une clé imbriquée contenant une liste de fonctionnalités et des étiquettes pour chaque enregistrement.
```
{
"data": [
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
]
}
```
Un exemple de configuration d'analyse pour l'exemple de jeu de données en entrée précédent doit définir les paramètres suivants :
+ Le `label` paramètre utilise l'[JMESPath](https://jmespath.org/)expression `data[*].label` pour extraire l'étiquette de vérité fondamentale pour chaque enregistrement de l'ensemble de données. L' JMESPath expression doit produire une liste d'étiquettes où le i the label est destiné au i the record.
+ Le `features` paramètre utilise l' JMESPath expression `data[*].features` pour extraire le tableau d'entités, pour chaque enregistrement de l'ensemble de données. L' JMESPath expression doit produire un tableau ou une matrice 2D dans lequel la première ligne contient les valeurs des caractéristiques du premier enregistrement.
### Prérequis des jeux de données tabulaires au format JSON Lines
JSON Lines est un format de texte permettant de représenter des données structurées où chaque ligne est un objet JSON valide. Actuellement, les tâches de traitement SageMaker Clarify ne prennent en charge que les lignes JSON au format SageMaker AI Dense. Pour respecter le format requis, toutes les fonctionnalités d’un enregistrement doivent être répertoriées dans un tableau JSON unique. Pour plus d’informations sur les lignes JSON, consultez [Format de demande JSONLINES](cdf-inference.md#cm-jsonlines).
**Note**
Tous les fichiers de données JSON Lines fournis à la tâche de traitement SageMaker Clarify doivent être codés en UTF-8 pour garantir la compatibilité.
Voici un exemple de définition d'une configuration d'analyse pour un enregistrement contenant une **clé de niveau supérieur** et une **liste** d'éléments.
```
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}
...
```
La configuration d'analyse pour l'exemple de jeu de données précédent doit définir les paramètres suivants :
+ Pour indiquer l'emplacement de l'étiquette de vérité fondamentale, le paramètre `label` doit être défini sur l' JMESPath expression`label`.
+ Pour indiquer l'emplacement du réseau de fonctionnalités, le paramètre `features` doit être défini sur l' JMESPath expression`features`.
Voici un exemple de définition d'une configuration d'analyse pour un enregistrement contenant une **clé de niveau supérieur** et une **clé imbriquée** contenant une **liste** d'éléments.
```
{"data":{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}}
{"data":{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
...
```
La configuration d'analyse pour l'exemple de jeu de données précédent doit définir les paramètres suivants :
+ Le paramètre `label` doit être défini sur l' JMESPathexpression indiquant `data.label` l'emplacement de l'étiquette de vérité fondamentale.
+ Le paramètre `features` doit être défini sur l' JMESPathexpression `data.features` pour indiquer l'emplacement du réseau d'entités.
### Prérequis des jeux de données tabulaires au format Parquet
[Parquet](https://parquet.apache.org/) est un format de données binaire orienté colonne. Actuellement, les tâches de traitement SageMaker Clarify prennent en charge le chargement des fichiers de données Parquet uniquement lorsque le nombre d'instances de traitement est égal `1` à
Étant donné que SageMaker les tâches de traitement Clarify ne prennent pas en charge les demandes de point de terminaison ou les réponses de point de terminaison au format Parquet, vous devez spécifier le format de données de la demande de point de terminaison en définissant le paramètre de configuration `content_type` d'analyse sur un format pris en charge. Pour plus d’informations, consultez `content_type` dans [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Les données Parquet doivent avoir des noms de colonnes formatés sous forme de chaînes. Utilisez le paramètre `label` de configuration d'analyse pour définir le nom de la colonne d'étiquettes afin d'indiquer l'emplacement des étiquettes de vérité terrain. Toutes les autres colonnes sont désignées comme des fonctionnalités.
# Demandes du point de terminaison pour des données tabulaires
Pour obtenir des prédictions du modèle pour l'analyse des biais après l'entraînement et l'analyse de l'importance des fonctionnalités, les tâches de traitement SageMaker Clarify sérialisent les données tabulaires en octets et les envoient à un point de terminaison d'inférence sous forme de charge utile de demande. Ces données tabulaires proviennent du jeu de données en entrée ou sont générées. S'il s'agit de données synthétiques, elles sont générées par l'outil d'explication pour l'analyse SHAP ou l'analyse de PDP.
Le format de données de la charge utile de demande doit être spécifié par le `content_type` paramètre de la configuration d'analyse. Si le paramètre n'est pas fourni, la tâche de traitement SageMaker Clarify utilisera la valeur du `dataset_type` paramètre comme type de contenu. Pour plus d’informations sur `content_type` ou `dataset_type`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Les sections suivantes présentent des exemples de demande du point de terminaison aux formats CSV et JSON Lines.
## Demande du point de terminaison au format CSV
La tâche de traitement SageMaker Clarify peut sérialiser les données au format CSV (type MIME :`text/csv`). Le tableau suivant présente des exemples des charges utiles de demande sérialisée.
| Charge utile de demande du point de terminaison (représentation sous forme de chaîne) | Commentaires |
| --- | --- |
| '1,2,3,4' | Enregistrement unique (quatre caractéristiques numériques). |
| '1,2,3,4\$1n5,6,7,8' | Deux enregistrements, séparés par un saut de ligne '\$1n'. |
| ’"This is a good product",5’ | Enregistrement unique (fonctionnalité de texte et fonctionnalité numérique). |
| ‘"This is a good product",5\$1n"Bad shopping experience",1’ | Deux enregistrements. |
## Demande du point de terminaison au format JSON Lines
La tâche de traitement SageMaker Clarify peut sérialiser les données au format dense SageMaker AI JSON Lines (type MIME :`application/jsonlines`). Pour plus d’informations sur les lignes JSON, consultez [Format de demande JSONLINES](cdf-inference.md#cm-jsonlines).
Pour transformer des données tabulaires en données JSON, fournissez une chaîne de modèle au paramètre `content_template` de configuration d’analyse. Pour plus d’informations sur `content_template`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md). Le tableau suivant montre des exemples de charges utiles de demande JSON Lines sérialisée.
| Charge utile de demande du point de terminaison (représentation sous forme de chaîne) | Commentaires |
| --- | --- |
| ’\$1"data":\$1"features":[1,2,3,4]\$1\$1’ | Enregistrement unique. Dans ce cas, le modèle ressemble à `'{"data":{"features":$features}}' ` et `$features` est remplacé par la liste de fonctionnalités `[1,2,3,4]`. |
| ’\$1"data":\$1"features":[1,2,3,4]\$1\$1\$1n\$1"data":\$1"features":[5,6,7,8]\$1\$1’ | Deux enregistrements. |
| ’\$1"features":["This is a good product",5]\$1’ | Enregistrement unique. Dans ce cas, le modèle ressemble à `'{"features":$features}'` et \$1features est remplacé par la liste de fonctionnalités `["This is a good product",5]`. |
| ’\$1"features":["This is a good product",5]\$1\$1n\$1"features":["Bad shopping experience",1]\$1’ | Deux enregistrements. |
## Demande du point de terminaison au format JSON
Une tâche de traitement SageMaker Clarify peut sérialiser des données dans des structures JSON arbitraires (type MIME :`application/json`). Pour ce faire, vous devez fournir une chaîne de modèle au paramètre `content_template` de configuration d’analyse. Ceci est utilisé par la tâche de traitement SageMaker Clarify pour construire la structure JSON externe. Vous devez également fournir une chaîne de modèle pour `record_template`, qui est utilisée pour construire la structure JSON pour chaque enregistrement. Pour plus d’informations sur `content_template` et `record_template`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
**Note**
Étant donné que `content_template` et `record_template` sont des paramètres de chaîne, tous les guillemets doubles (`"`) faisant partie de la structure sérialisée JSON doivent être notés comme des caractères échappés dans votre configuration. Par exemple, si vous voulez échapper des guillemets doubles en Python, vous pouvez entrer ce qui suit pour `content_template`.
```
"{\"data\":{\"features\":$record}}}"
```
Le tableau suivant montre des exemples de charges utiles de demandes JSON sérialisées ainsi que les paramètres `content_template` et `record_template` correspondants, qui sont requis pour les construire.
| Charge utile de demande du point de terminaison (représentation sous forme de chaîne) | Commentaires | content\$1template | record\$1template |
| --- | --- | --- | --- |
| ’\$1"data":\$1"features":[1,2,3,4]\$1\$1’ | Un seul enregistrement à la fois. | '\$1"data":\$1"features":\$1record\$1\$1\$1' | “\$1features” |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | Enregistrements multiples avec noms de fonctionnalités. | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | “\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | Enregistrements multiples et paires clé-valeur. | “\$1records" | “\$1features\$1kvp" |
| ‘\$1"A": 0, "B": 1\$1' | Un seul enregistrement à la fois et paires clé-valeur. | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "nested": \$1"B": 1\$1\$1' | Vous pouvez également utiliser l'élément record\$1template entièrement détaillé pour les structures arbitraires. | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# Réponse du point de terminaison pour des données tabulaires
Une fois que la tâche de traitement SageMaker Clarify a reçu la réponse d'un appel de point de terminaison d'inférence, elle désérialise la charge utile de la réponse et en extrait des prédictions. Utilisez le paramètre `accept_type` de configuration d'analyse pour spécifier le format de données de la charge utile de réponse. Si `accept_type` ce n'est pas le cas, la tâche de traitement SageMaker Clarify utilisera la valeur du paramètre content\$1type comme format de sortie du modèle. Pour plus d’informations sur `accept_type`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Les prédictions peuvent se composer des étiquettes prédites pour l’analyse des biais ou des valeurs de probabilité (scores) pour l’analyse de l’importance des caractéristiques. Dans la configuration d'analyse `predictor`, les trois paramètres suivants extraient les prédictions.
+ Le paramètre `probability` est utilisé pour localiser les valeurs de probabilité (scores) dans la réponse du point de terminaison.
+ Le paramètre `label` est utilisé pour localiser les étiquettes prédites dans la réponse du point de terminaison.
+ (Facultatif) Le paramètre `label_headers` fournit les étiquettes prédites pour un modèle multiclasse.
Les directives suivantes concernent les réponses du point de terminaison aux formats CSV, JSON Lines et JSON.
## Réponse du point de terminaison au format CSV
Si la charge utile de la réponse est au format CSV (type MIME :`text/csv`), la tâche de traitement SageMaker Clarify désérialise chaque ligne. Elle extrait ensuite les prédictions des données désérialisées à l'aide des index de colonnes fournis dans la configuration d'analyse. Les lignes de la charge utile de réponse doivent correspondre aux enregistrements figurant dans la charge utile de demande.
Les tableaux suivants fournissent des exemples de données de réponse dans différents formats et pour différents types de problèmes. Vos données peuvent varier par rapport à ces exemples, à condition que les prédictions puissent être extraites conformément à la configuration d'analyse.
Les sections suivantes présentent des exemples de réponse du point de terminaison au format CSV.
### La réponse du point de terminaison est au format CSV et contient uniquement une probabilité
Le tableau suivant présente un exemple de réponse du point de terminaison pour des problèmes de régression et de classification binaire.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique. | ’0.6’ |
| Deux enregistrements (résultats sur une ligne, séparés par une virgule). | ’0.6,0.3’ |
| Deux enregistrements (résultats sur deux lignes). | ’0.6\$1n0.3’ |
Dans l'exemple précédent, le point de terminaison fournit en sortie une valeur de probabilité unique (score) de l'étiquette prédite. Pour extraire les probabilités à l'aide de l'index et les utiliser pour l'analyse de l'importance des fonctionnalités, définissez le paramètre de configuration d'analyse `probability` sur l'index de colonne `0`. Ces probabilités peuvent également être utilisées pour l’analyse des biais si elles sont converties en valeur binaire à l’aide du paramètre `probability_threshold`. Pour plus d’informations sur `probability_threshold`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Le tableau suivant est un exemple de réponse du point de terminaison pour un problème multiclasse.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique d'un modèle multiclasse (trois classes). | ’0.1,0.6,0.3’ |
| Deux enregistrements d'un modèle multiclasse (trois classes). | ’0.1,0.6,0.3\$1n0.2,0.5,0.3’ |
Dans l'exemple précédent, le point de terminaison fournit en sortie une liste de probabilités (scores). Si aucun index n'est fourni, toutes les valeurs sont extraites et utilisées pour l'analyse de l'importance des fonctionnalités. Si le paramètre de configuration d'analyse `label_headers` est fourni, La tâche de traitement SageMaker Clarify peut ensuite sélectionner l'en-tête de l'étiquette présentant la probabilité maximale comme étiquette prédite, qui peut être utilisée pour l'analyse des biais. Pour plus d’informations sur `label_headers`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
### La réponse du point de terminaison est au format CSV et contient uniquement l’étiquette prédite
Le tableau suivant présente un exemple de réponse du point de terminaison pour des problèmes de régression et de classification binaire.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | ’1’ |
| Deux enregistrements (résultats sur une ligne, séparés par une virgule) | '1,0' |
| Deux enregistrements (résultats sur deux lignes) | '1\$1n0' |
Dans l'exemple précédent, le point de terminaison fournit en sortie l'étiquette prédite à la place de la probabilité. Définissez le paramètre `label` de la configuration de `predictor` sur l'index de colonne `0` afin que les étiquettes prédites puissent être extraites à l'aide de l'index et utilisées pour l'analyse des biais.
### La réponse du point de terminaison est au format CSV et contient l'étiquette prédite et la probabilité
Le tableau suivant présente un exemple de réponse du point de terminaison pour des problèmes de régression et de classification binaire.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '1,0.6' |
| Deux enregistrements | ’1,0.6\$1n0,0.3’ |
Dans l'exemple précédent, le point de terminaison fournit en sortie l'étiquette prédite suivie de sa probabilité. Définissez le paramètre `label` de la configuration de `predictor` sur l'index de colonne `0` et définissez `probability` sur l'index de colonne `1` pour extraire les deux valeurs de paramètre.
### La réponse du point de terminaison est au format CSV et contient les étiquettes prédites et les probabilités (multiclasses)
Un modèle multiclasse entraîné par Amazon SageMaker Autopilot peut être configuré pour générer la représentation sous forme de chaîne de la liste des étiquettes et des probabilités prédites. Le tableau d’exemple suivant montre un exemple de réponse du point de terminaison d’un modèle configuré pour fournir en sortie `predicted_label`, `probability`, `labels` et `probabilities`.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0,6, 0.3]"' |
| Deux enregistrements | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0,6, 0.3]"\$1n""cat",0.7,[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.7, 0,2, 0.1]"' |
Dans l'exemple précédent, la tâche de traitement SageMaker Clarify peut être configurée de la manière suivante pour extraire les prédictions.
Pour l'analyse des biais, l'exemple précédent peut être configuré des différentes manières suivantes.
+ Définissez le paramètre `label` de la configuration de `predictor` sur `0` pour extraire l'étiquette prédite.
+ Définissez ce paramètre sur `2` pour extraire les étiquettes prédites et définissez `probability` sur `3` pour extraire les probabilités correspondantes. La tâche de traitement SageMaker Clarify peut déterminer automatiquement l'étiquette prévue en identifiant l'étiquette présentant la valeur de probabilité la plus élevée. En se référant à l'exemple précédent d'un enregistrement unique, le modèle prédit trois étiquettes : `cat`, `dog` et `fish`, avec les probabilités correspondantes de `0.1`, `0.6` et `0.3`. Sur la base de ces probabilités, l'étiquette prédite est `dog`, car elle a la valeur de probabilité la plus élevée de `0.6`.
+ Définissez `probability` sur `3` pour extraire les probabilités. Si tel `label_headers` est le cas, la tâche de traitement SageMaker Clarify peut déterminer automatiquement l'étiquette prévue en identifiant l'en-tête de l'étiquette présentant la valeur de probabilité la plus élevée.
Pour l'analyse de l'importance des fonctionnalités, l'exemple précédent peut être configuré comme suit.
+ Définissez `probability` sur `3` pour extraire les probabilités de toutes les étiquettes prédites. Ensuite, les attributions de fonctionnalités seront calculées pour toutes les étiquettes. Si le client ne spécifie pas `label_headers`, les étiquettes prédites seront utilisées comme en-têtes d'étiquettes dans le rapport d'analyse.
## Réponse du point de terminaison au format JSON Lines
Si la charge utile de la réponse est au format JSON Lines (type MIME :`application/jsonlines`), la tâche de traitement SageMaker Clarify désérialise chaque ligne au format JSON. Il extrait ensuite les prédictions des données désérialisées à l'aide des JMESPath expressions fournies dans la configuration de l'analyse. Les lignes de la charge utile de réponse doivent correspondre aux enregistrements figurant dans la charge utile de demande. Les tableaux suivants présentent des exemples de données de réponse dans différents formats. Vos données peuvent varier par rapport à ces exemples, à condition que les prédictions puissent être extraites conformément à la configuration d'analyse.
Les sections suivantes présentent des exemples de réponse du point de terminaison au format JSON Lines.
### La réponse du point de terminaison est au format JSON Lines et contient seulement la probabilité
Le tableau suivant est un exemple de réponse du point de terminaison qui fournit en sortie uniquement la valeur de probabilité (score).
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"score":0.6\$1' |
| Deux enregistrements | ’\$1"score":0.6\$1\$1n\$1"score":0.3\$1’ |
Pour l'exemple précédent, définissez le paramètre de configuration de l'analyse `probability` sur JMESPath l'expression « score » pour en extraire la valeur.
### La réponse du point de terminaison est au format JSON Lines et contient uniquement l'étiquette prédite
Le tableau suivant est un exemple de réponse du point de terminaison qui fournit en sortie uniquement l'étiquette prédite.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"prediction":1\$1' |
| Deux enregistrements | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
Pour l'exemple précédent, définissez le `label` paramètre de configuration du prédicteur sur JMESPath expression`prediction`. La tâche de traitement SageMaker Clarify peut ensuite extraire les étiquettes prédites à des fins d'analyse des biais. Pour de plus amples informations, veuillez consulter [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
### La réponse du point de terminaison est au format JSON Lines et contient l’étiquette prédite et la probabilité
Le tableau suivant est un exemple de réponse du point de terminaison qui fournit en sortie l'étiquette prédite et son score.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"prediction":1,"score":0.6\$1' |
| Deux enregistrements | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
Pour l'exemple précédent, définissez le `label` paramètre de `predictor` configuration sur l' JMESPath expression « prédiction » pour extraire les étiquettes prédites. Définissez `probability` l' JMESPath expression « score » pour extraire la probabilité. Pour de plus amples informations, veuillez consulter [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
### La réponse du point de terminaison est au format JSON Lines et contient les étiquettes prédites et les probabilités (multiclasses)
Le tableau suivant est un exemple de réponse du point de terminaison provenant d'un modèle multiclasse qui fournit en sortie les résultats suivants :
+ La liste des étiquettes prédites.
+ Les probabilités, et l'étiquette prédite sélectionnée et sa probabilité.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' |
| Deux enregistrements | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.7,0.2,0.1]\$1' |
Dans l'exemple précédent, la tâche de traitement SageMaker Clarify peut être configurée de plusieurs manières pour extraire les prédictions.
Pour l'analyse des biais, l'exemple précédent peut être configuré d'**une** des manières suivantes.
+ Définissez le `label` paramètre de `predictor` configuration sur l' JMESPath expression « predicted\$1label » pour extraire l'étiquette prédite.
+ Définissez le paramètre sur l' JMESPath expression « predicted\$1labels » pour extraire les étiquettes prédites. Définissez `probability` l' JMESPath expression « probabilités » pour extraire leurs probabilités. La tâche SageMaker Clarify détermine automatiquement l'étiquette prévue en identifiant l'étiquette présentant la valeur de probabilité la plus élevée.
+ Définissez `probability` l' JMESPath expression « probabilités » pour extraire leurs probabilités. Si elle `label_headers` est fournie, la tâche de traitement SageMaker Clarify peut déterminer automatiquement l'étiquette prévue en identifiant l'étiquette présentant la valeur de probabilité la plus élevée.
Pour l'analyse de l'importance des fonctionnalités, procédez comme suit.
+ Définissez `probability` l' JMESPath expression « probabilités » pour extraire leurs probabilités de toutes les étiquettes prédites. Ensuite, les attributions de fonctionnalités seront calculées pour toutes les étiquettes.
## Réponse du point de terminaison au format JSON
Si la charge utile de la réponse est au format JSON (type MIME :`application/json`), la tâche de traitement SageMaker Clarify désérialise la totalité de la charge utile au format JSON. Il extrait ensuite les prédictions des données désérialisées à l'aide des JMESPath expressions fournies dans la configuration d'analyse. Les enregistrements de la charge utile de réponse doivent correspondre aux enregistrements figurant dans la charge utile de demande.
Les sections suivantes présentent des exemples de réponse du point de terminaison au format JSON. Ces sections contiennent des tableaux indiquant des exemples de données de réponse dans différents formats et pour différents types de problèmes. Vos données peuvent varier par rapport à ces exemples, à condition que les prédictions puissent être extraites conformément à la configuration d'analyse.
### La réponse du point de terminaison est au format JSON et contient uniquement la probabilité
Le tableau suivant est un exemple de réponse d'un point de terminaison qui fournit en sortie uniquement la valeur de probabilité (score).
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '[0.6]' |
| Deux enregistrements | '[0.6,0.3]' |
Dans l'exemple précédent, il n'y a aucun saut de ligne dans la charge utile de réponse. Au lieu de cela, un seul objet JSON contient la liste des scores, un pour chaque enregistrement figurant dans la demande. Définissez le paramètre de configuration de `probability` l'analyse sur JMESPath l'expression « [\$1] » pour extraire la valeur.
### La réponse du point de terminaison est au format JSON et contient uniquement l'étiquette prédite
Le tableau suivant est un exemple de réponse d'un point de terminaison qui fournit en sortie uniquement l'étiquette prédite.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"predicted\$1labels":[1]\$1' |
| Deux enregistrements | '\$1"predicted\$1labels":[1,0]\$1' |
Définissez le `label` paramètre de `predictor` configuration sur l' JMESPath expression « predicted\$1labels », puis la tâche de traitement SageMaker Clarify pourra extraire les étiquettes prédites à des fins d'analyse des biais.
### La réponse du point de terminaison est au format JSON et contient l'étiquette prédite et la probabilité
Le tableau suivant est un exemple de réponse d'un point de terminaison qui fournit en sortie l'étiquette prédite et son score.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '\$1"predictions":[\$1"label":1,"score":0.6\$1' |
| Deux enregistrements | ‘\$1"predictions":[\$1"label":1,"score":0.6\$1,\$1"label":0,"score":0.3\$1]\$1' |
Pour l'exemple précédent, définissez le `label` paramètre de `predictor` configuration sur l' JMESPath expression « predictions [\$1] .label » pour extraire les étiquettes prédites. Définissez `probability` l' JMESPath expression « predictions [\$1] .score » pour extraire la probabilité.
### La réponse du point de terminaison est au format JSON et contient les étiquettes prédites et les probabilités (multiclasses)
Le tableau suivant est un exemple de réponse d'un point de terminaison provenant d'un modèle multiclasse qui fournit en sortie les résultats suivants :
+ La liste des étiquettes prédites.
+ Les probabilités, et l'étiquette prédite sélectionnée et sa probabilité.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Enregistrement unique | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1]' |
| Deux enregistrements | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1,\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.7,0.2,0.1]\$1]' |
La tâche de traitement SageMaker Clarify peut être configurée de plusieurs manières pour extraire les prédictions.
Pour l'analyse des biais, l'exemple précédent peut être configuré d'**une** des manières suivantes.
+ Définissez le `label` paramètre de `predictor` configuration sur l' JMESPath expression « [\$1] .predicted\$1label » pour extraire l'étiquette prédite.
+ Définissez le paramètre sur l' JMESPath expression « [\$1] .predicted\$1labels » pour extraire les étiquettes prédites. Définissez `probability` l' JMESPath expression « [\$1] .probabilities » pour extraire leurs probabilités. La tâche de traitement SageMaker Clarify peut déterminer automatiquement l'étiquette prévue en identifiant l'étiquette présentant la valeur de proximité la plus élevée.
+ Définissez `probability` l' JMESPath expression « [\$1] .probabilities » pour extraire leurs probabilités. Si elle `label_headers` est fournie, la tâche de traitement SageMaker Clarify peut déterminer automatiquement l'étiquette prévue en identifiant l'étiquette présentant la valeur de probabilité la plus élevée.
Pour l'analyse de l'importance des caractéristiques, définissez `probability` JMESPath l'expression « [\$1] .probabilités » pour extraire leurs probabilités de toutes les étiquettes prédites. Ensuite, les attributions de fonctionnalités seront calculées pour toutes les étiquettes.
# Vérification préalable de la demande et de la réponse du point de terminaison pour des données tabulaires
Nous vous recommandons de déployer votre modèle sur un point de terminaison d'inférence en temps réel basé sur l' SageMaker IA et d'envoyer des demandes à ce point de terminaison. Examinez manuellement les demandes et les réponses pour vous assurer qu’elles sont toutes conformes aux exigences spécifiées dans la section [Demandes du point de terminaison pour des données tabulaires](clarify-processing-job-data-format-tabular-request.md) et dans la section [Réponse du point de terminaison pour des données tabulaires](clarify-processing-job-data-format-tabular-response.md). Si votre conteneur de modèle prend en charge les demandes par lots, vous pouvez commencer par une seule demande d’enregistrement, puis essayer avec deux enregistrements ou plus.
Les commandes suivantes montrent comment demander une réponse à l’aide de l’ AWS CLI. AWS CLI Il est préinstallé dans les instances SageMaker Studio et SageMaker Notebook. Pour l'installer AWS CLI, suivez ce [guide d'installation](https://aws.amazon.com/cli/).
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
Les paramètres sont définis, comme suit :
+ `$ENDPOINT NAME` : nom du point de terminaison.
+ `$CONTENT_TYPE` : type MIME de la demande (entrée du conteneur de modèle).
+ `$ACCEPT_TYPE` : type MIME de la réponse (sortie du conteneur de modèle).
+ `$REQUEST_DATA` : chaîne de données utiles demandée.
+ `$CLI_BINARY_FORMAT` : format du paramètre de l'interface de ligne de commande (CLI). Pour AWS CLI la version 1, ce paramètre doit rester vide. Pour la version 2, ce paramètre doit être défini sur `--cli-binary-format raw-in-base64-out`.
**Note**
AWS CLI v2 transmet les paramètres binaires sous forme de chaînes codées en base64 [par](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam) défaut.
# AWS CLI exemples v1
L'exemple de la section précédente concernait la AWS CLI version 2. Les exemples de demande et de réponse suivants à destination et en provenance du point de terminaison utilisent la version 1 d' AWS CLI .
## Demande et réponse du point de terminaison au format CSV
Dans l'exemple de code suivant, la demande se compose d'un seul enregistrement et la réponse est sa valeur de probabilité.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
0.6
```
Dans l'exemple de code suivant, la demande se compose de deux enregistrements et la réponse inclut leurs probabilités, séparées par une virgule.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, l'expression `$'content'` contenue dans `--body` indique à la commande d'interpréter `'\n'` dans le contenu comme un saut de ligne. La sortie de la réponse est la suivante.
```
0.6,0.3
```
Dans l'exemple de code suivant, la demande se compose de deux enregistrements et la réponse inclut leurs probabilités, séparées par un saut de ligne.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
0.6
0.3
```
Dans l'exemple de code suivant, la demande se compose d'un seul enregistrement et la réponse est constituée des valeurs de probabilité issues d'un modèle multiclasse contenant trois classes.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
0.1,0.6,0.3
```
Dans l'exemple de code suivant, la demande se compose de deux enregistrements et la réponse inclut leurs valeurs de probabilité issues d'un modèle multiclasse contenant trois classes.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
0.1,0.6,0.3
0.2,0.5,0.3
```
Dans l'exemple de code suivant, la demande se compose de deux enregistrements et la réponse inclut l'étiquette prédite et la probabilité.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-2 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
1,0.6
0,0.3
```
Dans l'exemple de code suivant, la demande se compose de deux enregistrements et la réponse inclut les en-têtes d'étiquettes et les probabilités.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-3 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
"['cat','dog','fish']","[0.1,0.6,0.3]"
"['cat','dog','fish']","[0.2,0.5,0.3]"
```
## Demande et réponse du point de terminaison au format JSON Lines
Dans l'exemple de code suivant, la demande se compose d'un seul enregistrement et la réponse est sa valeur de probabilité.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines \
--content-type application/jsonlines \
--accept application/jsonlines \
--body '{"features":["This is a good product",5]}' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
{"score":0.6}
```
Dans l'exemple de code suivant, la demande contient deux enregistrements et la réponse inclut l'étiquette prédite et la probabilité.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-2 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
{"predicted_label":1,"probability":0.6}
{"predicted_label":0,"probability":0.3}
```
Dans l'exemple de code suivant, la demande contient deux enregistrements et la réponse inclut les en-têtes d'étiquettes et les probabilités.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-3 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"data":{"features":[1,2,3,4]}}\n{"data":{"features":[5,6,7,8]}}' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}
```
## Demande et réponse du point de terminaison dans des formats mixtes
Dans l'exemple de code suivant, la demande est au format CSV et la réponse au format JSON Lines.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
{"probability":0.6}
{"probability":0.3}
```
Dans l'exemple de code suivant, la demande est au format JSON Lines et la réponse au format CSV.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-in-csv-out \
--content-type application/jsonlines \
--accept text/csv \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
0.6
0.3
```
Dans l'exemple de code suivant, la demande est au format CSV et la réponse au format JSON.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
Dans l’exemple de code précédent, la sortie de la réponse est la suivante.
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# Exigences relatives aux données d’image
Une tâche de traitement SageMaker Clarify permet d'expliquer les images. Cette rubrique fournit les exigences de format de données pour des données d’image. Pour en savoir plus sur le traitement des données d’image, consultez [Analyse de données d’image pour l’explicabilité de la vision par ordinateur](clarify-processing-job-run.md#clarify-processing-job-run-cv).
Un jeu de données d’image contient un ou plusieurs fichiers image. Pour identifier un ensemble de données d'entrée pour la tâche de traitement SageMaker Clarify, définissez un [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs)nom `dataset` ou un `dataset_uri` paramètre de configuration d'analyse sur un préfixe d'URI Amazon S3 de vos fichiers image.
Les formats de fichier image et les extensions de fichier pris en charge sont répertoriés dans le tableau suivant.
| Format d'image | Extension de fichier |
| --- | --- |
| JPEG | jpg, jpeg |
| PNG | png |
Définissez le paramètre `dataset_type` de configuration d'analyse sur **application/x-image**. Comme le type n'est pas un format de fichier image spécifique, `content_type` sera utilisé pour décider du format et de l'extension des fichiers image.
La tâche de traitement SageMaker Clarify charge chaque fichier image dans un [NumPytableau](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) tridimensionnel pour un traitement ultérieur. Les trois dimensions incluent la hauteur, la largeur et les valeurs RVB de chaque pixel.
## Format de demande de point de terminaison
La tâche de traitement SageMaker Clarify convertit les données RGB brutes d'une image en un format d'image compatible, tel que JPEG. Elle fait cela avant d'envoyer les données au point de terminaison pour les prédictions. Les formats d'image pris en charge sont les suivants.
| Format de données | Type MIME | Extension de fichier |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg, jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | Toutes les opérations ci-dessus |
Spécifiez le format de données de la charge utile de demande en utilisant le paramètre `content_type` de configuration d'analyse. Si `content_type` n’est pas fourni, le format de données par défaut est `image/jpeg`.
## Format de réponse de point de terminaison
Dès réception de la réponse à un appel d'un point de terminaison d'inférence, la tâche de traitement SageMaker Clarify désérialise la charge utile de la réponse, puis en extrait les prédictions.
### Problème de classification d'image
Le format de données de la charge utile de la réponse doit être spécifié par le paramètre accept\$1type de configuration d'analyse. Si `accept_type` n'est pas fourni, le format de données par défaut est `application/json`. Les formats pris en charge sont les mêmes que ceux décrits dans **Réponse du point de terminaison pour des données tabulaires**, dans la section des données tabulaires.
Voici un [Inférence avec l'algorithme de classification d'images](image-classification.md#IC-inference) exemple d'algorithme de classification d'images intégré à l' SageMaker IA qui accepte une seule image puis renvoie un tableau de valeurs de probabilité (scores), chacune pour une classe.
Comme indiqué dans le tableau suivant, lorsque le paramètre `content_type` est défini sur `application/jsonlines`, la réponse est un objet JSON.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Image unique | '\$1"prediction":[0.1,0.6,0.3]\$1' |
Dans l'exemple précédent, définissez le `probability` paramètre sur l' JMESPath expression « prédiction » pour extraire les scores.
Lorsque `content_type` est défini sur `application/json`, la réponse est un objet JSON, comme indiqué dans le tableau suivant.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Image unique | '[0.1,0.6,0.3]' |
Dans l'exemple précédent, définissez `probability` l' JMESPath expression « [\$1] » pour extraire tous les éléments du tableau. Dans l'exemple précédent, [`0.1, 0.6, 0.3]` est extrait. Sinon, si vous ne définissez pas le paramètre `probability` de configuration, tous les éléments du tableau sont également extraits. Cela est dû au fait que la totalité de la charge utile est désérialisée sous forme de prédictions.
### Problème de détection d'objet
Par défaut, le paramètre `accept_type` de configuration d’analyse a pour valeur `application/json` et le seul format pris en charge est le format d’inférence de détection d’objet. Pour plus d’informations sur les formats de réponse, consultez [Formats de réponse](object-detection-in-formats.md#object-detection-recordio).
Le tableau suivant est un exemple de réponse d’un point de terminaison qui fournit en sortie un tableau. Chaque élément de ce tableau est un tableau de valeurs contenant l'index de classe, le score de confiance et les coordonnées du cadre de délimitation de l'objet détecté.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Image unique (un seul objet) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| Image unique (deux objets) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
Le tableau suivant est un exemple de réponse d'un point de terminaison qui fournit en sortie un objet JSON avec une clé faisant référence au tableau. Définissez le paramètre `probability` de configuration d'analyse sur la clé "prediction" pour extraire les valeurs.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) |
| --- | --- |
| Image unique (un seul objet) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| Image unique (deux objets) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]\$1' |
## Vérification préalable de la demande et de la réponse du point de terminaison pour des données d’image
Nous vous recommandons de déployer votre modèle sur un point de terminaison d'inférence en temps réel basé sur l' SageMaker IA et d'envoyer des demandes à ce point de terminaison. Examinez manuellement les demandes et les réponses. Assurez-vous que les deux sont conformes aux exigences spécifiées dans la section **Demande du point de terminaison pour des données d'image** et dans la section **Réponse du point de terminaison pour des données d'image**.
Voici deux exemples de code montrant comment envoyer des demandes et examiner les réponses pour des problèmes de classification d'image et de détection d'objet.
### Problème de classification d'image
L'exemple de code suivant indique à un point de terminaison de lire un fichier PNG, puis classe ce dernier.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-image-classification \
--content-type "image/png" \
--accept "application/json" \
--body fileb://./test.png \
/dev/stderr 1>/dev/null
```
Dans l'exemple de code précédent, la sortie de la réponse est la suivante.
```
[0.1,0.6,0.3]
```
### Problème de détection d'objet
L'exemple de code suivant indique à un point de terminaison de lire un fichier JPEG, puis classe les objets qu'il contient.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-object-detection \
--content-type "image/jpg" \
--accept "application/json" \
--body fileb://./test.jpg \
/dev/stderr 1>/dev/null
```
Dans l’exemple de code précédent, la sortie de la réponse est la suivante.
```
{"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475],[4.0, 0.32643985450267792, 0.3677481412887573, 0.034883320331573486, 0.6318609714508057, 0.5967587828636169],[8.0, 0.22552496790885925, 0.6152569651603699, 0.5722782611846924, 0.882301390171051, 0.8985623121261597],[3.0, 0.42260299175977707, 0.019305512309074402, 0.08386176824569702, 0.39093565940856934, 0.9574796557426453]]}
```
# Données de séries temporelles
Les données de séries temporelles font référence à des données qui peuvent être chargées dans un dataframe tridimensionnel. Dans ce dataframe, dans chaque horodatage, chaque ligne représente un enregistrement cible et chaque enregistrement cible a une ou plusieurs colonnes associées. Les valeurs de chaque cellule du bloc de données peuvent être de type numérique, catégoriel ou texte.
## Conditions préalables relatives aux jeux de données de séries temporelles
Avant l’analyse, effectuez les étapes de prétraitement nécessaires à la préparation de vos données, telles que le nettoyage des données ou l’ingénierie des caractéristiques. Vous pouvez fournir un ou plusieurs jeux de données. Si vous fournissez plusieurs ensembles de données, utilisez l'une des méthodes suivantes pour les fournir à la tâche de traitement SageMaker Clarify :
+ Utilisez une configuration [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)nommée `dataset` ou la configuration d'analyse `dataset_uri` pour spécifier le jeu de données principal. Pour plus d’informations sur `dataset_uri`, reportez-vous à la liste des paramètres dans [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
+ Utilisez le paramètre `baseline` fourni dans le fichier de configuration d’analyse. Le jeu de données de référence est requis pour `static_covariates`, s’il est présent. Pour plus d’informations sur le fichier de configuration d’analyse, y compris des exemples, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
Le tableau suivant répertorie les formats de données pris en charge, leurs extensions de fichier et les types MIME.
| Format de données | Extension de fichier | Type MIME |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
JSON est un format flexible qui peut représenter un niveau quelconque de complexité dans vos données structurées. Comme indiqué dans le tableau, SageMaker Clarify prend en charge `item_records` les formats`timestamp_records`, et`columns`.
## Exemples de configuration de jeux de données de séries temporelles
Cette section vous montre comment définir une configuration d’analyse utilisant `time_series_data_config` pour des données de séries temporelles au format JSON. Supposons que vous disposez d’un jeu de données comportant deux éléments, chacun doté d’un horodatage (t), d’une série temporelle cible (x), de deux séries temporelles connexes (r) et de deux covariables statiques (u), comme suit :
t1 = [0,1,2], t2 = [2,3]
x1 = [5,6,4], x2 = [0,4]
r1 = [0,1,0], r21 = [1,1]
r12 = [0,0,0], r22 = [1,0]
u11 = -1, u21 = 0
u12 = 1, u22 = 2
Vous pouvez encoder le jeu de données en utilisant `time_series_data_config` de trois manières différentes, selon `dataset_format`. Les sections suivantes décrivent chaque méthode.
### Configuration des données de séries temporelles quand `dataset_format` a pour valeur `columns`
L’exemple suivant utilise la valeur `columns` pour `dataset_format`. Le fichier JSON suivant représente le jeu de données précédent.
```
{
"ids": [1, 1, 1, 2, 2],
"timestamps": [0, 1, 2, 2, 3], # t
"target_ts": [5, 6, 4, 0, 4], # x
"rts1": [0, 1, 0, 1, 1], # r1
"rts2": [0, 0, 0, 1, 0], # r2
"scv1": [-1, -1, -1, 0, 0], # u1
"scv2": [1, 1, 1, 2, 2], # u2
}
```
Notez que les identifiants des éléments sont répétés dans le champ `ids`. L’implémentation correcte de `time_series_data_config` est illustrée comme suit :
```
"time_series_data_config": {
"item_id": "ids",
"timestamp": "timestamps",
"target_time_series": "target_ts",
"related_time_series": ["rts1", "rts2"],
"static_covariates": ["scv1", "scv2"],
"dataset_format": "columns"
}
```
### Configuration des données de séries temporelles quand `dataset_format` a pour valeur `item_records`
L’exemple suivant utilise la valeur `item_records` pour `dataset_format`. Le fichier JSON suivant représente le jeu de données.
```
[
{
"id": 1,
"scv1": -1,
"scv2": 1,
"timeseries": [
{"timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0},
{"timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0},
{"timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0}
]
},
{
"id": 2,
"scv1": 0,
"scv2": 2,
"timeseries": [
{"timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1},
{"timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0}
]
}
]
```
Chaque élément est représenté sous la forme d’une entrée distincte dans le code JSON. L'extrait suivant montre le correspondant `time_series_data_config` (qui utilise JMESPath).
```
"time_series_data_config": {
"item_id": "[*].id",
"timestamp": "[*].timeseries[].timestamp",
"target_time_series": "[*].timeseries[].target_ts",
"related_time_series": ["[*].timeseries[].rts1", "[*].timeseries[].rts2"],
"static_covariates": ["[*].scv1", "[*].scv2"],
"dataset_format": "item_records"
}
```
### Configuration des données de séries temporelles quand `dataset_format` a pour valeur `timestamp_record`
L’exemple suivant utilise la valeur `timestamp_record` pour `dataset_format`. Le fichier JSON suivant représente le jeu de données précédent.
```
[
{"id": 1, "timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 2, "timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1, "svc1": 0, "svc2": 2},
{"id": 2, "timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0, "svc1": 0, "svc2": 2},
]
```
Chaque entrée du code JSON représente un horodatage unique et correspond à un élément unique. L’implémentation `time_series_data_config` est illustrée comme suit :
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# Demandes de données de séries temporelles aux points de terminaison
Une tâche de traitement SageMaker Clarify sérialise les données dans des structures JSON arbitraires (avec le type MIME :`application/json`). Pour ce faire, vous devez fournir une chaîne de modèle au paramètre `content_template` de configuration d’analyse. Ceci est utilisé par la tâche de traitement SageMaker Clarify pour créer la requête JSON fournie à votre modèle. `content_template`contient un ou plusieurs enregistrements de votre ensemble de données. Vous devez également fournir une chaîne de modèle pour `record_template`, qui est utilisée pour construire la structure JSON de chaque enregistrement. Ces enregistrements sont ensuite insérés dans `content_template`. Pour plus d’informations sur `content_type` ou `dataset_type`, consultez [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
**Note**
Étant donné que `content_template` et `record_template` sont des paramètres de chaîne, tous les guillemets doubles (") faisant partie de la structure sérialisée JSON doivent être notés comme des caractères échappés dans votre configuration. Par exemple, si vous voulez échapper des guillemets doubles en Python, vous pouvez entrer la valeur suivante pour `content_template` :
```
'$record'
```
Le tableau suivant montre des exemples de données utiles de demandes JSON sérialisées ainsi que les paramètres `content_template` et `record_template` correspondants, requis pour les construire.
| Cas d’utilisation | Charge utile de demande du point de terminaison (représentation sous forme de chaîne) | content\$1template | record\$1template |
| --- | --- | --- | --- |
| Un seul enregistrement à la fois | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| Un seul enregistrement avec `$related_time_series` et `$static_covariates` | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
| Enregistrements multiples | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00"}]}` | `'{"instances": $records}'` | `'{"start": $start_time, "target": $target_time_series}'` |
| Enregistrements multiples avec `$related_time_series` et `$static_covariates` | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}]}` | `'{"instances": $records}'` | `''{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
# Réponse des points de terminaison pour des données de séries temporelles
La tâche de traitement SageMaker Clarify désérialise l'intégralité de la charge utile au format JSON. Il extrait ensuite les prédictions des données désérialisées à l'aide des JMESPath expressions fournies dans la configuration d'analyse. Les enregistrements de la charge utile de réponse doivent correspondre aux enregistrements figurant dans la charge utile de demande.
Le tableau suivant est un exemple de réponse d’un point de terminaison qui fournit en sortie uniquement la valeur de prédiction moyenne. La valeur de `forecast` used dans le `predictor` champ de la [configuration d'analyse](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters) doit être fournie sous forme d' JMESPath expression pour trouver le résultat de la prédiction pour la tâche de traitement.
| Charge utile de demande du point de terminaison | Charge utile de réponse du point de terminaison (représentation sous forme de chaîne) | JMESPath expression pour les prévisions dans la configuration d'analyse |
| --- | --- | --- |
| Exemple d’enregistrement unique. La configuration doit être `TimeSeriesModelConfig(forecast="prediction.mean")` pour extraire correctement la prédiction. | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| Enregistrements multiples. Une réponse AWS approfondie du point de terminaison. | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# Vérification préalable de la demande et de la réponse du point de terminaison pour des données de séries temporelles
Il est conseillé de déployer votre modèle sur un point de terminaison d'inférence en temps réel basé sur l' SageMaker IA et d'envoyer des demandes au point de terminaison. Examinez manuellement les demandes et les réponses pour vous assurer qu’elles sont toutes conformes aux exigences spécifiées dans les sections [Demandes de données de séries temporelles aux points de terminaison](clarify-processing-job-data-format-time-series-request-jsonlines.md) et [Réponse des points de terminaison pour des données de séries temporelles](clarify-processing-job-data-format-time-series-response-json.md). Si votre conteneur de modèle prend en charge les demandes par lots, vous pouvez commencer par une seule demande d’enregistrement, puis essayer avec deux enregistrements ou plus.
Les commandes suivantes montrent comment demander une réponse à l’aide de l’ AWS CLI. AWS CLI Il est préinstallé dans les instances Studio et SageMaker Notebook. Pour l'installer AWS CLI, suivez le [guide d'installation](https://aws.amazon.com//cli/).
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
Les paramètres sont définis, comme suit :
+ \$1ENDPOINT NAME : nom du point de terminaison.
+ \$1CONTENT\$1TYPE : type MIME de la demande (entrée du conteneur de modèle).
+ \$1ACCEPT\$1TYPE : type MIME de la réponse (sortie du conteneur de modèle).
+ \$1REQUEST\$1DATA : chaîne de données utiles demandée.
+ \$1CLI\$1BINARY\$1FORMAT : format du paramètre de l’interface de ligne de commande (CLI). Pour AWS CLI la version 1, ce paramètre doit rester vide. Pour la version 2, ce paramètre doit être défini sur `--cli-binary-format raw-in-base64-out`.
**Note**
AWS CLI v2 transmet les paramètres binaires sous forme de chaînes codées en base64 par défaut. Les exemples de demande et de réponse suivants à destination et en provenance du point de terminaison utilisent la AWS CLI version v1.
------
#### [ Example 1 ]
Dans l’exemple de code suivant, la demande se compose d’un seul enregistrement.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json \
--content-type application/json \
--accept application/json \
--body '{"target": [1, 2, 3, 4, 5],
"start": "2024-01-01 01:00:00"}' \
/dev/stderr 1>/dev/null
```
L’extrait suivant montre la sortie de réponse correspondante.
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
Dans l’exemple de code suivant, la demande contient deux enregistrements.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json-2 \
--content-type application/json \
--accept application/json \
--body $'{"instances": [{"target":[1, 2, 3],
"start":"2024-01-01 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}], {"target":[1, 2, 3],
"start":"2024-01-02 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}]}' \
dev/stderr 1>/dev/null
```
En voici la sortie de réponse :
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------
# 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 d'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 à 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 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 peut détecter et classer des objets dans une image, puis 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 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 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.
# Résultats d’analyse
Une fois le traitement SageMaker Clarify terminé, vous pouvez télécharger les fichiers de sortie pour les inspecter, ou vous pouvez visualiser les résultats dans SageMaker Studio Classic. La rubrique suivante décrit les résultats d'analyse générés par SageMaker Clarify, tels que le schéma et le rapport générés par l'analyse des biais, l'analyse SHAP, l'analyse de l'explicabilité de la vision par ordinateur et l'analyse des diagrammes de dépendance partielle ()PDPs. Si l’analyse de configuration contient des paramètres permettant de calculer plusieurs analyses, les résultats sont agrégés dans une analyse et un fichier de rapport.
Le répertoire de sortie de la tâche de traitement SageMaker Clarify contient les fichiers suivants :
+ `analysis.json` : fichier contenant les métriques de biais et l'importance des fonctionnalités au format JSON.
+ `report.ipynb` : bloc-notes statique qui contient du code pour vous aider à visualiser les métriques de biais et l'importance des fonctionnalités.
+ `explanations_shap/out.csv` : répertoire qui est créé et qui contient les fichiers générés automatiquement en fonction de vos configurations d'analyse spécifiques. Par exemple, si vous activez le paramètre `save_local_shap_values`, les valeurs SHAP locales par instance seront enregistrées dans le répertoire `explanations_shap`. Autre exemple, si votre paramètre de ligne de base SHAP `analysis configuration` ne contient aucune valeur, la tâche d'explicabilité SageMaker Clarify calcule une ligne de base en regroupant le jeu de données en entrée. Elle enregistre ensuite la base de référence générée dans le répertoire.
Pour obtenir des informations plus détaillées, consultez les sections suivantes.
**Topics**
+ [Analyse des biais](#clarify-processing-job-analysis-results-bias)
+ [Analyse SHAP](#clarify-processing-job-analysis-results-shap)
+ [Analyse de l'explicabilité de la vision par ordinateur](#clarify-processing-job-analysis-results-cv)
+ [Tracés de dépendance partielle (PDPs) Analyse](#clarify-processing-job-analysis-results-pdp)
+ [Valeurs de Shapley asymétriques](#clarify-processing-job-analysis-results-asymmshap)
## Analyse des biais
Amazon SageMaker Clarify utilise la terminologie décrite dans le document [Amazon SageMaker précise les termes relatifs à la partialité et à l'équité](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) pour aborder les questions de partialité et d'équité.
### Schéma du fichier d'analyse
Le fichier d'analyse est au format JSON et est organisé en deux sections : les métriques de biais de pré-entraînement et les métriques de biais de post-entraînement. Les paramètres des métriques de biais de pré-entraînement et de post-entraînement sont les suivants.
+ **pre\$1training\$1bias\$1metrics** : paramètres pour les métriques de biais de pré-entraînement. Pour plus d’informations, consultez [Indicateurs de biais de pré-entraînement](clarify-measure-data-bias.md) et [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
+ **label** : nom de l'étiquette de vérité terrain défini par le paramètre `label` de la configuration d'analyse.
+ **label\$1value\$1or\$1threshold** : chaîne contenant les valeurs d'étiquette ou l'intervalle défini par le paramètre `label_values_or_threshold` de la configuration d'analyse. Par exemple, si la valeur `1` est fournie pour un problème de classification binaire, la chaîne sera `1`. Si plusieurs valeurs `[1,2]` sont fournies pour un problème multiclasse, la chaîne sera `1,2`. Si un seuil `40` est fourni pour un problème de régression, la chaîne sera d'un type interne comme `(40, 68]` où `68` est la valeur maximale de l'étiquette dans le jeu de données en entrée.
+ **facets** : la section contient plusieurs paires clé-valeur, la clé correspondant au nom de facette défini par le paramètre `name_or_index` de la configuration des facettes, et la valeur étant un tableau d'objets facettes. Chaque objet facette contient les membres suivants :
+ **value\$1or\$1threshold** : chaîne contenant les valeurs de facette ou l'intervalle défini par le paramètre `value_or_threshold` de la configuration des facettes.
+ **metrics** : la section contient un tableau d'éléments de métriques de biais, et chaque élément de métrique de biais possède les attributs suivants :
+ **name** : nom abrégé de la métrique de biais. Par exemple, `CI`.
+ **description** : nom complet de la métrique de biais. Par exemple, `Class Imbalance (CI)`.
+ **value** : valeur de la métrique de biais, ou valeur null JSON si la métrique de biais n'est pas calculée pour une raison particulière. Les valeurs ±∞ sont représentées sous la forme des chaînes `∞` et `-∞` respectivement.
+ **error** : message d'erreur facultatif expliquant pourquoi la métrique de biais n'a pas été calculée.
+ **post\$1training\$1bias\$1metrics** : la section contient les métriques de biais de post-entraînement et suit une disposition et une structure similaires à celles de la section de pré-entraînement. Pour de plus amples informations, veuillez consulter [Indicateurs de biais de post-entraînement dans les données et les modèles](clarify-measure-post-training-bias.md).
L'exemple suivant est un exemple de configuration d'analyse qui calculera les métriques de biais de pré-entraînement et de post-entraînement.
```
{
"version": "1.0",
"pre_training_bias_metrics": {
"label": "Target",
"label_value_or_threshold": "1",
"facets": {
"Gender": [{
"value_or_threshold": "0",
"metrics": [
{
"name": "CDDL",
"description": "Conditional Demographic Disparity in Labels (CDDL)",
"value": -0.06
},
{
"name": "CI",
"description": "Class Imbalance (CI)",
"value": 0.6
},
...
]
}]
}
},
"post_training_bias_metrics": {
"label": "Target",
"label_value_or_threshold": "1",
"facets": {
"Gender": [{
"value_or_threshold": "0",
"metrics": [
{
"name": "AD",
"description": "Accuracy Difference (AD)",
"value": -0.13
},
{
"name": "CDDPL",
"description": "Conditional Demographic Disparity in Predicted Labels (CDDPL)",
"value": 0.04
},
...
]
}]
}
}
}
```
### Rapport d'analyse des biais
Le rapport d'analyse des biais comprend plusieurs tableaux et diagrammes qui contiennent des explications et des descriptions détaillées. Celles-ci comprennent, entre autres, la distribution des valeurs des étiquettes, la distribution des valeurs des facettes, le diagramme de performance de modèle de haut niveau, un tableau des métriques de biais et leurs descriptions. Pour plus d'informations sur les métriques de biais et sur leur interprétation, consultez le document [Découvrez comment Amazon SageMaker Clarify aide à détecter les biais](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/).
## Analyse SHAP
SageMaker Clarifier les tâches de traitement utilise l'algorithme Kernel SHAP pour calculer les attributions des fonctionnalités. La tâche de traitement SageMaker Clarify produit des valeurs SHAP locales et globales. Elles aident à déterminer la contribution de chaque fonctionnalité pour aboutir aux prédictions du modèle. Les valeurs SHAP locales représentent l'importance des fonctionnalités pour chaque instance individuelle, tandis que les valeurs SHAP globales regroupent les valeurs SHAP locales sur l'ensemble des instances dans le jeu de données. Pour plus d'informations sur les valeurs SHAP et la manière de les interpréter, consultez [Attributions de fonctions utilisant des valeurs de Shapley](clarify-shapley-values.md).
### Schéma du fichier d'analyse SHAP
Les résultats de l'analyse SHAP globale sont stockés dans la section des explications du fichier d'analyse, sous la méthode `kernel_shap`. Les différents paramètres du fichier d'analyse SHAP sont les suivants :
+ **explanations** : section du fichier d'analyse qui contient les résultats de l'analyse de l'importance des fonctionnalités.
+ **kernal\$1shap** : section du fichier d'analyse qui contient le résultat de l'analyse SHAP globale.
+ **global\$1shap\$1values** : section du fichier d'analyse qui contient plusieurs paires clé-valeur. Chaque clé de la paire clé-valeur représente un nom de fonctionnalité issu du jeu de données en entrée. Chaque valeur de la paire clé-valeur correspond à la valeur SHAP globale de la fonctionnalité. La valeur SHAP globale est obtenue en agrégeant les valeurs SHAP par instance de la fonctionnalité à l'aide de la configuration `agg_method`. Si la configuration `use_logit` est activée, la valeur est calculée à l'aide des coefficients de régression logistique, qui peuvent être interprétés comme des ratios log-odds.
+ **expected\$1value** : prédiction moyenne du jeu de données de référence. Si la configuration de `use_logit` est activée, la valeur est calculée à l’aide des coefficients de régression logistique.
+ **global\$1top\$1shap\$1text** : utilisé pour l’analyse de l’explicabilité du NLP. Section du fichier d'analyse qui inclut un ensemble de paires clé-valeur. SageMaker Clarifiez les tâches de traitement, agrégez les valeurs SHAP de chaque jeton, puis sélectionnez les meilleurs jetons en fonction de leurs valeurs SHAP globales. La configuration de `max_top_tokens` définit le nombre de jetons à sélectionner.
Chacun des jetons principaux sélectionnés possède une paire clé-valeur. La clé de la paire clé-valeur correspond au nom de la fonctionnalité de texte d'un jeton principal. Chaque valeur de la paire clé-valeur correspond aux valeurs SHAP globales du jeton supérieur. Pour obtenir un exemple de paire clé-valeur `global_top_shap_text`, reportez-vous au résultat suivant.
Voici un exemple de sortie de l’analyse SHAP d’un jeu de données tabulaire.
```
{
"version": "1.0",
"explanations": {
"kernel_shap": {
"Target": {
"global_shap_values": {
"Age": 0.022486410860333206,
"Gender": 0.007381025261958729,
"Income": 0.006843906804137847,
"Occupation": 0.006843906804137847,
...
},
"expected_value": 0.508233428001
}
}
}
}
```
Voici un exemple de sortie de l’analyse SHAP d’un jeu de données textuel. La sortie correspondant à la colonne `Comments` est un exemple de sortie générée après l’analyse d’une caractéristique de texte.
```
{
"version": "1.0",
"explanations": {
"kernel_shap": {
"Target": {
"global_shap_values": {
"Rating": 0.022486410860333206,
"Comments": 0.058612104851485144,
...
},
"expected_value": 0.46700941970297033,
"global_top_shap_text": {
"charming": 0.04127962903247833,
"brilliant": 0.02450240786522321,
"enjoyable": 0.024093569652715457,
...
}
}
}
}
}
```
### Schéma du fichier de référence généré
Lorsqu'aucune configuration de ligne de base SHAP n'est fournie, la tâche de traitement SageMaker Clarify génère un ensemble de données de référence. SageMaker Clarify utilise un algorithme de clustering basé sur la distance pour générer un ensemble de données de référence à partir des clusters créés à partir du jeu de données en entrée. Le jeu de données de référence obtenu est enregistré dans un fichier CSV, `explanations_shap/baseline.csv`. Ce fichier de sortie contient une ligne d'en-têtes et plusieurs instances basées sur le paramètre `num_clusters`, spécifié dans la configuration d'analyse. Le jeu de données de référence se compose uniquement de colonnes de fonctionnalités. Voici un exemple de référence créée en mettant en cluster le jeu de données d’entrée.
```
Age,Gender,Income,Occupation
35,0,2883,1
40,1,6178,2
42,0,4621,0
```
### Schéma des valeurs SHAP locales issues de l’analyse d’explicabilité d’un jeu de données tabulaire
Pour les ensembles de données tabulaires, si une seule instance de calcul est utilisée, la tâche de traitement SageMaker Clarify enregistre les valeurs SHAP locales dans un fichier CSV nommé. `explanations_shap/out.csv` Si vous utilisez plusieurs instances de calcul, les valeurs SHAP locales sont enregistrées dans plusieurs fichiers CSV du répertoire `explanations_shap`.
Un fichier de sortie contenant des valeurs SHAP locales comporte une ligne contenant les valeurs SHAP locales pour chaque colonne définie par les en-têtes. Les en-têtes suivent la convention de dénomination de `Feature_Label` selon laquelle le nom de la fonctionnalité est suivi d'un trait de soulignement, puis du nom de votre variable cible.
Pour des problèmes multi-classes, les noms des fonctionnalités dans l'en-tête varient d'abord, puis les étiquettes. Par exemple, deux fonctionnalités `F1, F2` et deux classes `L1` et `L2`, dans les en-têtes sont `F1_L1`, `F2_L1`, `F1_L2` et `F2_L2`. Si la configuration d'analyse contient une valeur pour le paramètre `joinsource_name_or_index`, la colonne clé utilisée dans la jointure est ajoutée à la fin du nom de l'en-tête. Cela permet de mapper les valeurs SHAP locales aux instances du jeu de données en entrée. Voici un exemple de fichier de sortie contenant des valeurs SHAP.
```
Age_Target,Gender_Target,Income_Target,Occupation_Target
0.003937908,0.001388849,0.00242389,0.00274234
-0.0052784,0.017144491,0.004480645,-0.017144491
...
```
### Schéma des valeurs SHAP locales issues de l'analyse d'explicabilité du NLP
Pour l'analyse d'explicabilité du NLP, si une seule instance de calcul est utilisée, la tâche de traitement SageMaker Clarify enregistre les valeurs SHAP locales dans un fichier JSON Lines nommé. `explanations_shap/out.jsonl` Si vous utilisez plusieurs instances de calcul, les valeurs SHAP locales sont enregistrées dans plusieurs fichiers JSON Lines du répertoire `explanations_shap`.
Chaque fichier contenant des valeurs SHAP locales possède plusieurs lignes de données, et chaque ligne est un objet JSON valide. L'objet JSON possède les attributs suivants :
+ **explanations** : section du fichier d'analyse qui contient un tableau d'explications de Kernel SHAP pour une seule instance. Chaque élément du tableau contient les membres suivants :
+ **feature\$1name** : nom d'en-tête des fonctionnalités fournies par la configuration des en-têtes.
+ **data\$1type — Type de** fonctionnalité déduit par la tâche de traitement SageMaker Clarify. Les valeurs valides pour les fonctionnalités de texte incluent `numerical`, `categorical` et `free_text` (pour les fonctionnalités de texte).
+ **attributions** : tableau d'objets d'attribution spécifique à une fonctionnalité. Une fonctionnalité de texte peut avoir plusieurs objets d'attribution, chacun pour une unité définie par la configuration `granularity`. L’objet d’attribution contient les membres suivants :
+ **attribution** : tableau de valeurs de probabilité spécifique à une classe.
+ **description** : (pour les fonctionnalités de texte) description des unités de texte.
+ **partial\$1text — Partie** du texte expliquée par la tâche de traitement SageMaker Clarify.
+ **start\$1idx** : index basé sur zéro permettant d'identifier l'emplacement dans le tableau indiquant le début du fragment de texte partiel.
Voici un exemple d'une seule ligne d'un fichier de valeurs SHAP local, embellie pour améliorer sa lisibilité.
```
{
"explanations": [
{
"feature_name": "Rating",
"data_type": "categorical",
"attributions": [
{
"attribution": [0.00342270632248735]
}
]
},
{
"feature_name": "Comments",
"data_type": "free_text",
"attributions": [
{
"attribution": [0.005260534499999983],
"description": {
"partial_text": "It's",
"start_idx": 0
}
},
{
"attribution": [0.00424190349999996],
"description": {
"partial_text": "a",
"start_idx": 5
}
},
{
"attribution": [0.010247314500000014],
"description": {
"partial_text": "good",
"start_idx": 6
}
},
{
"attribution": [0.006148907500000005],
"description": {
"partial_text": "product",
"start_idx": 10
}
}
]
}
]
}
```
### Rapport d'analyse SHAP
Le rapport d'analyse SHAP fournit un graphique à barres d'un maximum de `10` principales valeurs SHAP globales. L'exemple de graphique suivant montre les valeurs SHAP pour les `4` fonctionnalités principales.
![\[Graphique à barres horizontales des valeurs SHAP globales calculées pour la variable cible des quatre fonctionnalités principales.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify/shap-chart.png)
## Analyse de l'explicabilité de la vision par ordinateur
SageMaker Clarifier l'explicabilité de la vision par ordinateur prend un ensemble de données composé d'images et traite chaque image comme une collection de super pixels. Après analyse, la tâche de traitement SageMaker Clarify produit un jeu de données d'images dans lequel chaque image montre la carte thermique des superpixels.
L'exemple suivant montre un panneau de limitation de vitesse en entrée sur la gauche et une carte thermique montre l'amplitude des valeurs SHAP sur la droite. Ces valeurs SHAP ont été calculées par un modèle de reconnaissance d'image Resnet-18 entraîné à reconnaître les [panneaux de signalisation allemands](https://benchmark.ini.rub.de/gtsrb_news.html). Le jeu de données German Traffic Sign Recognition Benchmark (GTSRB) est fourni dans l'article [L'homme contre la machine : évaluation comparative des algorithmes de machine learning de reconnaissance des panneaux de signalisation](https://www.sciencedirect.com/science/article/abs/pii/S0893608012000457?via%3Dihub) (langue française non garantie). Dans l'exemple de sortie, des valeurs positives élevées indiquent que le super-pixel présente une forte corrélation positive avec la prédiction du modèle. Des valeurs négatives élevées indiquent que le super-pixel présente une forte corrélation négative avec la prédiction du modèle. Plus la valeur absolue de la valeur SHAP indiquée sur la carte thermique est élevée, plus la relation entre le super-pixel et la prédiction du modèle est forte.
![\[Image d'entrée du panneau de limitation de vitesse et carte thermique résultante des valeurs SHAP d'un modèle Resnet-18.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify/shap_speed-limit-70.png)
Pour plus d'informations, consultez les exemples de carnets [expliquant 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) et [Expliquant les modèles de détection d'objets avec Amazon SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb).
## Tracés de dépendance partielle (PDPs) Analyse
Les graphiques de dépendance partielle montrent la dépendance de la réponse cible prédite par rapport à un ensemble de fonctionnalités d'entrée intéressantes. Elles sont marginalisées par rapport aux valeurs de toutes les autres fonctions d’entrée et sont désignées sous le nom de fonctions de complément. Intuitivement, vous pouvez interpréter la dépendance partielle comme la réponse cible, qui est attendue comme une fonction de chaque caractéristique d’entrée intéressante.
### Schéma du fichier d'analyse
Les valeurs PDP sont stockées dans la section `explanations` du fichier d'analyse sous la méthode `pdp`. Les paramètres pour `explanations` sont les suivants :
+ **explanations** : section des fichiers d'analyse qui contient les résultats de l'analyse de l'importance des fonctionnalités.
+ **pdp** : section du fichier d'analyse qui contient un tableau d'explications de graphiques PDP pour une seule instance. Chaque élément du tableau contient les membres suivants :
+ **feature\$1name** : nom d'en-tête des fonctionnalités fourni par la configuration de `headers`.
+ **data\$1type — Type de** fonctionnalité déduit par la tâche de traitement SageMaker Clarify. Les valeurs valides pour `data_type` incluent les valeurs numériques et catégorielles.
+ **feature\$1values** : contient les valeurs présentes dans la fonctionnalité. Si la valeur `data_type` déduite par SageMaker Clarify est catégorique, elle `feature_values` contient toutes les valeurs uniques que pourrait être la fonctionnalité. Si la valeur `data_type` déduite par SageMaker Clarify est numérique, `feature_values` contient une liste de la valeur centrale des compartiments générés. Le paramètre `grid_resolution` détermine le nombre de compartiments utilisés pour regrouper les valeurs des colonnes de fonctionnalités.
+ **data\$1distribution** : tableau de pourcentages, où chaque valeur est le pourcentage d'instances que contient un compartiment. Le paramètre `grid_resolution` détermine le nombre de compartiments. Les valeurs des colonnes de fonctionnalités sont regroupées dans ces compartiments.
+ **model\$1predictions** : tableau de prédictions de modèle, où chaque élément du tableau est un tableau de prédictions correspondant à une seule classe dans la sortie du modèle.
**label\$1headers** : en-têtes d'étiquettes fournis par la configuration de `label_headers`.
+ **error** : message d'erreur généré si les valeurs des graphiques PDP ne sont pas calculées pour une raison particulière. Ce message d'erreur remplace le contenu des champs `feature_values`, `data_distributions` et `model_predictions`.
Voici un exemple de sortie d'un fichier d'analyse contenant un résultat d'analyse de PDP.
```
{
"version": "1.0",
"explanations": {
"pdp": [
{
"feature_name": "Income",
"data_type": "numerical",
"feature_values": [1046.9, 2454.7, 3862.5, 5270.2, 6678.0, 8085.9, 9493.6, 10901.5, 12309.3, 13717.1],
"data_distribution": [0.32, 0.27, 0.17, 0.1, 0.045, 0.05, 0.01, 0.015, 0.01, 0.01],
"model_predictions": [[0.69, 0.82, 0.82, 0.77, 0.77, 0.46, 0.46, 0.45, 0.41, 0.41]],
"label_headers": ["Target"]
},
...
]
}
}
```
### Rapport d'analyse de PDP
Vous pouvez générer un rapport d'analyse contenant un graphique PDP pour chaque fonctionnalité. Le graphique PDP place `feature_values` le long de l'axe X et `model_predictions` le long de l'axe Y. Pour les modèles multiclasses, `model_predictions` est un tableau, et chaque élément de ce tableau correspond à l'une des classes de prédiction du modèle.
Voici un exemple de graphique PDP pour la fonctionnalité `Age`. Dans cet exemple de sortie, le graphique PDP indique le nombre de valeurs de fonctionnalité regroupées dans des compartiments. Le nombre de compartiments est déterminé par `grid_resolution`. Les compartiments de valeurs de fonctionnalité sont tracés par rapport aux prédictions du modèle. Dans cet exemple, les valeurs de fonctionnalité les plus élevées ont les mêmes valeurs de prédiction du modèle.
![\[Graphique linéaire montrant comment les prévisions du modèle varient par rapport à feature_values pour 10 points de grille uniques.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify/pdp-chart.png)
## Valeurs de Shapley asymétriques
SageMaker Clarifier les tâches de traitement : utilisez l'algorithme de valeur asymétrique de Shapley pour calculer les attributions explicatives du modèle de prévision des séries chronologiques. Cet algorithme détermine la contribution des caractéristiques d’entrée à chaque étape temporelle vers les prédictions prévues.
### Schéma du fichier d’analyse des valeurs de Shapley asymétriques
Les résultats des valeurs de Shapley asymétriques sont stockés dans un compartiment Amazon S3. Vous trouverez l’emplacement de ce compartiment dans la section *explications* du fichier d’analyse. Cette section contient les résultats d’analyse de l’importance des caractéristiques. Les paramètres suivants sont inclus dans le fichier d’analyse des valeurs de Shapley asymétriques.
+ **asymmetric\$1shapley\$1value** : section du fichier d’analyse qui contient les métadonnées relatives aux résultats de la tâche d’explication, notamment les suivantes :
+ **explanation\$1results\$1path** : emplacement Amazon S3 avec les résultats d’explication
+ **direction** : configuration fournie par l’utilisateur pour la valeur de configuration de `direction`
+ **granularity** : configuration fournie par l’utilisateur pour la valeur de configuration de `granularity`
L’extrait suivant montre les paramètres mentionnés précédemment dans un exemple de fichier d’analyse :
```
{
"version": "1.0",
"explanations": {
"asymmetric_shapley_value": {
"explanation_results_path": EXPLANATION_RESULTS_S3_URI,
"direction": "chronological",
"granularity": "timewise",
}
}
}
```
Les sections suivantes décrivent comment la structure des résultats d’explication dépend de la valeur de `granularity` dans la configuration.
#### Granularité temporelle
Lorsque la granularité est `timewise`, la sortie est représentée dans la structure suivante. La valeur `scores` représente l’attribution pour chaque horodatage. La valeur `offset` représente la prédiction du modèle sur les données de référence et décrit le comportement du modèle lorsqu’il ne reçoit pas de données.
L’extrait suivant montre un exemple de sortie pour un modèle qui effectue des prédictions pour deux étapes temporelles. Par conséquent, toutes les attributions sont des listes de deux éléments dont la première entrée fait référence à la première étape temporelle prédite.
```
{
"item_id": "item1",
"offset": [1.0, 1.2],
"explanations": [
{"timestamp": "2019-09-11 00:00:00", "scores": [0.11, 0.1]},
{"timestamp": "2019-09-12 00:00:00", "scores": [0.34, 0.2]},
{"timestamp": "2019-09-13 00:00:00", "scores": [0.45, 0.3]},
]
}
{
"item_id": "item2",
"offset": [1.0, 1.2],
"explanations": [
{"timestamp": "2019-09-11 00:00:00", "scores": [0.51, 0.35]},
{"timestamp": "2019-09-12 00:00:00", "scores": [0.14, 0.22]},
{"timestamp": "2019-09-13 00:00:00", "scores": [0.46, 0.31]},
]
}
```
#### Granularité précise
L’exemple suivant illustre les résultats d’attribution lorsque la granularité est `fine_grained`. La valeur `offset` a la même signification que celle décrite dans la section précédente. Les attributions sont calculées pour chaque caractéristique d’entrée à chaque horodatage d’une série temporelle cible et des séries temporelles associées, si elles sont disponibles, et pour chaque covariable statique, si disponible.
```
{
"item_id": "item1",
"offset": [1.0, 1.2],
"explanations": [
{"feature_name": "tts_feature_name_1", "timestamp": "2019-09-11 00:00:00", "scores": [0.11, 0.11]},
{"feature_name": "tts_feature_name_1", "timestamp": "2019-09-12 00:00:00", "scores": [0.34, 0.43]},
{"feature_name": "tts_feature_name_2", "timestamp": "2019-09-11 00:00:00", "scores": [0.15, 0.51]},
{"feature_name": "tts_feature_name_2", "timestamp": "2019-09-12 00:00:00", "scores": [0.81, 0.18]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-11 00:00:00", "scores": [0.01, 0.10]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-12 00:00:00", "scores": [0.14, 0.41]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-13 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-14 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-11 00:00:00", "scores": [0.65, 0.56]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-12 00:00:00", "scores": [0.43, 0.34]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-13 00:00:00", "scores": [0.16, 0.61]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-14 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "static_covariate_1", "scores": [0.6, 0.1]},
{"feature_name": "static_covariate_2", "scores": [0.1, 0.3]},
]
}
```
Dans les deux cas d’utilisation `timewise` et `fine-grained`, les résultats sont stockés au format JSON Lines (.jsonl).
# Résoudre les problèmes liés au traitement SageMaker Clarify
Si vous rencontrez des problèmes avec SageMaker les tâches de traitement Clarify, consultez les scénarios suivants pour identifier le problème.
**Note**
Le motif de l’échec et le message de sortie contiendront des messages descriptifs et des exceptions, le cas échéant, durant l’exécution. Les erreurs sont souvent dues à l'absence de paramètres ou à leur non-validité. Si les messages sont peu clairs, déroutants ou trompeurs, ou si vous ne parvenez pas à trouver une solution, envoyez des commentaires.
**Topics**
+ [Impossible de terminer la tâche de traitement](#clarify-troubleshooting-job-fails)
+ [L'exécution de la tâche de traitement est trop longue](#clarify-troubleshooting-job-long)
+ [La tâche de traitement se termine sans résultat et vous recevez un message CloudWatch d'avertissement](#clarify-troubleshooting-no-results-and-warning)
+ [Message d’erreur signalant une configuration d’analyse non valide](#clarify-troubleshooting-invalid-analysis-configuration)
+ [Le calcul des métriques de biais échoue pour plusieurs métriques ou pour la totalité des métriques](#clarify-troubleshooting-bias-metric-computation-fails)
+ [Incompatibilité entre la configuration d'analyse et dataset/model les entrées/sorties](#clarify-troubleshooting-mismatch-analysis-config-and-data-model)
+ [Le modèle renvoie « 500 Internal Server Error (500 Erreur de serveur interne) » ou le conteneur revient aux prédictions par enregistrement en raison d’une erreur de modèle](#clarify-troubleshooting-500-internal-server-error)
+ [Rôle d'exécution non valide](#clarify-troubleshooting-execution-role-invalid)
+ [Échec du téléchargement des données](#clarify-troubleshooting-data-download)
+ [Impossible de se connecter à l' SageMaker IA](#clarify-troubleshooting-connection)
## Impossible de terminer la tâche de traitement
S'il est impossible de terminer la tâche de traitement, essayez l'une des actions suivantes :
+ Inspectez les journaux des tâches directement dans le bloc-notes où vous avez exécuté la tâche. Les journaux des tâches se trouvent dans la sortie de la cellule du bloc-notes où vous avez lancé l'exécution.
+ Inspectez les connexions à la tâche CloudWatch.
+ Ajoutez la ligne suivante dans votre bloc-notes pour décrire la dernière tâche de traitement et rechercher la raison de l’échec et le message de sortie :
+ `clarify_processor.jobs[-1].describe()`
+ Exécutez la commande suivante AWS CLI ; pour décrire le travail de traitement, rechercher la raison de l'échec et le message de sortie :
+ `aws sagemaker describe-processing-job —processing-job-name `
## L'exécution de la tâche de traitement est trop longue
Si l'exécution de votre tâche de traitement prend trop de temps, utilisez les méthodes suivantes pour en trouver la cause première.
Vérifiez si la configuration de vos ressources est suffisante pour gérer votre charge de calcul. Pour accélérer la tâche, essayez ce qui suit :
+ Utilisez un type d'instance plus grand. SageMaker Clarifiez les requêtes répétées sur le modèle, et une instance plus grande peut réduire considérablement le temps de calcul. Pour obtenir la liste des instances disponibles, leur taille de mémoire, leur bande passante et d'autres informations sur les performances, consultez [Amazon SageMaker AI Pricing](https://aws.amazon.com/sagemaker/pricing/).
+ Ajoutez d'autres instances. SageMaker Clarify peut utiliser plusieurs instances pour expliquer plusieurs points de données d'entrée en parallèle. Pour activer le calcul parallèle, définissez `instance_count` sur une valeur supérieure à `1` lorsque vous appelez `SageMakerClarifyProcessor`. Pour de plus amples informations, veuillez consulter [Comment exécuter des tâches de traitement parallèles SageMaker Clarify](clarify-processing-job-run.md#clarify-processing-job-run-spark). Si vous augmentez le nombre d'instances, surveillez les performances de votre point de terminaison pour vérifier qu'il peut déployer la charge accrue. Pour de plus amples informations, veuillez consulter [Capture des données à partir du point de terminaison en temps réel](model-monitor-data-capture-endpoint.md).
+ Si vous calculez des valeurs SHapley Additive exPlanations (SHAP), réduisez le paramètre `num_samples` dans votre fichier de configuration d'analyse. Le nombre d'échantillons a une incidence directe sur les éléments suivants :
+ La taille des jeux de données synthétiques envoyés à votre point de terminaison
+ La durée d'exécution de la tâche
La réduction du nombre d'échantillons peut également entraîner une diminution de la précision de l'estimation des valeurs SHAP. Pour de plus amples informations, veuillez consulter [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
## La tâche de traitement se termine sans résultat et vous recevez un message CloudWatch d'avertissement
Si le traitement se termine mais qu'aucun résultat n'est trouvé, les CloudWatch journaux produisent un message d'avertissement indiquant que Signal 15 reçu, nettoyage en cours. Cet avertissement indique que la tâche a été arrêtée soit parce qu'une demande du client a appelé l'`StopProcessingJob`API, soit parce que la tâche a dépassé le délai imparti pour son achèvement. Dans ce dernier cas, vérifiez la durée d'exécution maximale dans la configuration de la tâche (`max_runtime_in_seconds`) et augmentez-la selon les besoins.
## Message d’erreur signalant une configuration d’analyse non valide
+ Si le message d'erreur Unable to load analysis configuration as JSON apparaît, cela signifie que le fichier d'entrée de configuration d'analyse pour la tâche de traitement ne contient pas un objet JSON valide. Vérifiez la validité de l’objet JSON à l’aide d’un linter JSON.
+ Si le message d'erreur Analysis configuration schema validation error apparaît, cela signifie que le fichier d'entrée de configuration d'analyse pour la tâche de traitement contient des champs inconnus ou des types non valides pour certaines valeurs de champ. Passez en revue les paramètres de configuration dans le fichier et vérifiez-les par rapport aux paramètres répertoriés dans le fichier de configuration d’analyse. Pour de plus amples informations, veuillez consulter [Fichiers de configuration d’analyse](clarify-processing-job-configure-analysis.md).
## Le calcul des métriques de biais échoue pour plusieurs métriques ou pour la totalité des métriques
Si vous recevez l'un des messages d'erreur suivants : No Label values are present in the predicted Label Column, Positive Predicted Index Series contains all False values ou Predicted Label Column series data type is not the same as Label Column series, essayez ce qui suit :
+ Vérifiez que le jeu de données utilisé est correct.
+ Vérifiez si la taille du jeu de données est trop petite ; par exemple, elle ne contient que quelques lignes. Cela peut conduire à ce que les sorties du modèle aient la même valeur ou que le type de données soit inféré de façon incorrecte.
+ Vérifiez si l'étiquette ou la facette est traitée comme continue ou catégorique. SageMaker Clarify utilise l'heuristique pour déterminer le [https://github.com/aws/amazon-sagemaker-clarify/blob/master/src/smclarify/bias/metrics/common.py#L114)](https://github.com/aws/amazon-sagemaker-clarify/blob/master/src/smclarify/bias/metrics/common.py#L114)). Pour les mesures de biais post-entraînement, le type de données renvoyé par le modèle peut ne pas correspondre à celui du jeu de données ou SageMaker Clarify peut ne pas être en mesure de le transformer correctement.
+ Le rapport de biais doit indiquer une valeur unique pour les colonnes catégoriques ou un intervalle pour les colonnes continues.
+ Par exemple, si 0.0 et 1.0 sont les valeurs flottantes d'une colonne, cette dernière sera traitée comme étant continue même si le nombre de valeurs uniques est faible.
## Incompatibilité entre la configuration d'analyse et dataset/model les entrées/sorties
+ Vérifiez que le format de ligne de référence dans la configuration de l’analyse est identique au format du jeu de données.
+ Si vour recevez le message d'erreur Could not convert string to float, vérifiez que le format est correctement spécifié. Il pourrait également indiquer que le format des prévisions du modèle est différent de celui de la colonne d’étiquette, ou que la configuration de l’étiquette ou des probabilités est incorrecte.
+ Si vous recevez le message d'erreur Unable to locate the facet, Headers must contain label, Headers in config do not match with the number of columns in the dataset ou Feature names not found, vérifiez que les en-têtes correspondent aux colonnes.
+ Si vous recevez le message d'erreur Data must contain features, vérifiez le modèle de contenu pour JSON Lines et comparez-le à l'exemple de jeu de données, si disponible.
## Le modèle renvoie « 500 Internal Server Error (500 Erreur de serveur interne) » ou le conteneur revient aux prédictions par enregistrement en raison d’une erreur de modèle
Si vous recevez le message d’erreur Fallback to per-record prediction because of model error, cela peut indiquer que le modèle ne peut pas gérer la taille du lot, ou qu’il est limité, ou qu’il n’accepte tout simplement pas l’entrée transmise par le conteneur en raison de problèmes de sérialisation. Vous devez consulter les CloudWatch journaux du point de terminaison SageMaker AI et rechercher les messages d'erreur ou les retraçages. Dans les cas de limitation de modèle, il peut être utile d’utiliser un type d’instance différent ou d’augmenter le nombre d’instances pour le point de terminaison.
## Rôle d'exécution non valide
Cela indique que le rôle fourni est incorrect ou ne dispose pas des autorisations requises. Vérifiez le rôle et les autorisations y afférant, qui ont été utilisés pour configurer la tâche de traitement, et vérifiez la politique d'autorisation et d'approbation pour le rôle.
## Échec du téléchargement des données
Cela indique que les entrées de tâche n'ont pas pu être téléchargées pour démarrer la tâche. Vérifiez le nom du compartiment, ainsi que les autorisations pour le jeu de données et les entrées de configuration.
## Impossible de se connecter à l' SageMaker IA
Cela indique que la tâche n'a pas pu atteindre les points de terminaison du service SageMaker AI. Vérifiez les paramètres de configuration réseau pour la tâche de traitement et vérifiez la configuration du cloud privé virtuel (VPC).
## Exemples de blocs-notes
Les sections suivantes contiennent des blocs-notes destinés à vous aider à commencer à utiliser SageMaker Clarify, à l'utiliser pour des tâches spéciales, notamment dans le cadre d'une tâche distribuée, et pour la vision par ordinateur.
### Prise en main
Les exemples de blocs-notes suivants montrent comment utiliser SageMaker Clarify pour démarrer avec les tâches d'explicabilité et de biais du modèle. Ces tâches incluent la création d’une tâche de traitement, l’entraînement d’un modèle de machine learning (ML) et la surveillance des prédictions modélisées :
+ [Explicabilité et détection des biais avec Amazon SageMaker Clarify : utilisez Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) pour créer une tâche de traitement SageMaker afin de détecter les biais et d'expliquer les prédictions du modèle.
+ [Surveillance de la dérive des biais et de la dérive d'attribution des fonctionnalités Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) — Utilisez Amazon SageMaker Model Monitor pour surveiller la dérive des biais et la dérive de l'attribution des fonctionnalités au fil du temps.
+ Comment [lire un ensemble de données au format JSON Lines](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.html) dans une tâche de traitement SageMaker Clarify
+ [Atténuez les biais, entraînez un autre modèle impartial et placez-le dans le registre des modèles](https://github.com/aws/amazon-sagemaker-examples/blob/master/end_to_end/fraud_detection/3-mitigate-bias-train-model2-registry-e2e.ipynb) : utilisez la [technique de suréchantillonnage des minorités synthétiques (SMOTE)](https://arxiv.org/pdf/1106.1813.pdf) et SageMaker clarifiez pour atténuer les biais, entraînez un autre modèle, puis insérez le nouveau modèle dans le registre des modèles. Cet exemple de bloc-notes montre également comment placer les nouveaux artefacts du modèle, notamment les données, le code et les métadonnées du modèle, dans le registre de modèles. Ce carnet fait partie d'une série qui montre comment intégrer SageMaker Clarify dans un pipeline d' SageMaker IA décrit dans l'[Architecte et comment créer le cycle de vie complet de l'apprentissage automatique avec un](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) article de AWS blog.
### Cas spéciaux
Les carnets suivants vous montrent comment utiliser un SageMaker Clarify dans des cas particuliers, notamment dans votre propre conteneur et pour les tâches de traitement du langage naturel :
+ [Équité et explicabilité avec SageMaker Clarify (apportez votre propre conteneur)](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_byoc.ipynb) — Créez votre propre modèle et conteneur qui peuvent s'intégrer à SageMaker Clarify pour mesurer les biais et générer un rapport d'analyse d'explicabilité. Cet exemple de bloc-notes présente également les termes clés et vous montre comment accéder au rapport via SageMaker Studio Classic.
+ [Équité et explicabilité avec le traitement distribué SageMaker Clarify Spark](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_spark.ipynb) : utilisez le traitement distribué pour exécuter une tâche SageMaker Clarify qui mesure le biais d'un ensemble de données avant l'entraînement et le biais d'un modèle après l'entraînement. Cet exemple de bloc-notes explique également comment obtenir une explication de l'importance des fonctionnalités d'entrée sur la sortie du modèle et comment accéder au rapport d'analyse d'explicabilité via SageMaker Studio Classic.
+ [Explicabilité avec SageMaker Clarify - Graphiques de dépendance partielle (PDP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.html) — Utilisez SageMaker Clarify pour générer PDPs et accéder à un rapport d'explicabilité du modèle.
+ [Explication de l'analyse des sentiments du texte à l'aide SageMaker de l'explicabilité du traitement du langage naturel (NLP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/text_explainability/text_explainability.html) Clarify — Utilisez SageMaker Clarify pour l'analyse des sentiments du texte.
+ Utilisation de l’explicabilité de la vision par ordinateur pour la [classification d’images](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.html) et la [détection d’objet](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.html).
Il a été vérifié que ces blocs-notes fonctionnent dans Amazon SageMaker Studio Classic. Pour obtenir des instructions sur l’ouverture d’un bloc-notes dans Studio Classic, consultez [Création ou ouverture d'un bloc-notes Amazon SageMaker Studio Classic](notebooks-create-open.md). Si vous êtes invité à choisir un noyau, choisissez **Python 3 (Science des données)**.
# Biais des données de pré-entraînement
Le biais, la discrimination et l’équité algorithmiques, ainsi que des rubriques connexes ont été étudiés dans des disciplines telles que le droit, la stratégie et l’informatique. Un système informatique peut être considéré comme biaisé s'il est discriminatoire à l'égard de certains individus ou groupes d'individus. Les modèles de machine learning qui alimentent ces applications exploitent les données, et ces données peuvent refléter des disparités ou d'autres biais inhérents. Par exemple, les données d'entraînement peuvent ne pas disposer d'une représentation suffisante de divers groupes démographiques ou contenir des étiquettes biaisées. Les modèles de machine learning entraînés sur des jeux de données présentant ces biais peuvent finir par les apprendre, puis les reproduire voire les exacerber dans leurs prédictions. Le domaine du machine learning offre l'occasion d'aborder les biais en les détectant et en les mesurant à chaque étape du cycle de vie ML. Vous pouvez utiliser Amazon SageMaker Clarify pour déterminer si les données utilisées pour les modèles d'entraînement encodent un quelconque biais.
Le biais peut être mesuré avant et après l’entraînement, et son inférence peut être contrôlée par rapport à des lignes de base après le déploiement des modèles sur des points de terminaison. Les métriques de biais de pré-entraînement sont conçues pour détecter et mesurer les biais dans les données brutes avant leur utilisation pour entraîner un modèle. Les métriques utilisées sont indépendantes du modèle, car elles ne dépendent d’aucune sortie du modèle. Différents concepts d'équité exigent cependant des mesures de biais distinctes. Amazon SageMaker Clarify fournit des mesures de biais pour quantifier différents critères d'équité.
Pour plus d'informations sur les mesures de biais, consultez [Découvrez comment Amazon SageMaker Clarify aide à détecter les mesures de biais](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias) [et d'équité pour le Machine Learning dans le secteur de la finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
## Amazon SageMaker précise les termes relatifs à la partialité et à l'équité
SageMaker Clarify utilise la terminologie suivante pour parler de partialité et d'équité.
**Fonctionnalité**
Propriété ou caractéristique individuelle mesurable d'un phénomène observé, contenue dans une colonne pour les données tabulaires.
**Étiquette**
Fonction cible pour l'entraînement du modèle de machine learning. Appelée *étiquette observée* ou *résultat observé*.
**Étiquette prédite**
Étiquette telle que prédite par le modèle. Également appelée *résultat prédit*.
**Exemple**
Entité observée décrite par les valeurs de fonctions et la valeur d'étiquette, contenue dans une ligne pour les données tabulaires.
**Jeu de données**
Une série d'échantillons.
**Écart**
Déséquilibre dans les données d'entraînement ou le comportement de prédiction du modèle entre différents groupes, telles que l'âge ou la tranche de revenu. Les biais peuvent résulter des données ou de l'algorithme utilisé pour entraîner votre modèle. Par exemple, si un modèle ML est principalement entraîné sur des données provenant d'individus d'âge moyen, il sera peut-être moins précis lorsque des prédictions concerneront des personnes plus jeunes et plus âgées.
**Métrique de biais**
Fonction qui renvoie des valeurs numériques indiquant le niveau d'un biais potentiel.
**Rapport de biais**
Série de métriques de biais pour un jeu de données ou la combinaison d'un jeu de données et d'un modèle.
**Valeurs d'étiquette positives**
Valeurs d'étiquettes favorables à un groupe démographique observé dans un échantillon. En d'autres termes, désigne un échantillon comme ayant un*résultat positif*.
**Valeurs d'étiquette négatives**
Valeurs d'étiquette défavorables à un groupe démographique observé dans un échantillon. En d'autres termes, désigne un échantillon comme ayant un*résultat négatif*.
**Variable de groupe**
Colonne de catégorie du jeu de données utilisée pour former des sous-groupes pour la mesure de la disparité démographique conditionnelle (CDD). Requise uniquement pour cette métrique en lien avec le paradoxe de Simpson.
**Facette**
Colonne ou fonction contenant les attributs du biais mesuré.
**Valeur de facette**
Valeurs de fonction des attributs que le biais peut favoriser ou défavoriser.
**Probabilité prédite**
Probabilité, telle que prédite par le modèle, d'un échantillon ayant un résultat positif ou négatif.
## Exemples de blocs-notes
Amazon SageMaker Clarify fournit le carnet d'échantillons suivant pour la détection des biais :
+ [Explicabilité et détection des biais avec Amazon SageMaker Clarify : utilisez SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) pour créer une tâche de traitement permettant de détecter les biais et d'expliquer les prédictions du modèle avec les attributions de fonctionnalités.
Il a été vérifié que ce bloc-notes fonctionne uniquement dans Amazon SageMaker Studio. Si vous avez besoin d'instructions pour ouvrir un bloc-notes dans Amazon SageMaker Studio, consultez[Création ou ouverture d'un bloc-notes Amazon SageMaker Studio Classic](notebooks-create-open.md). Si vous êtes invité à choisir un noyau, choisissez **Python 3 (Science des données)**.
**Topics**
+ [Amazon SageMaker précise les termes relatifs à la partialité et à l'équité](#clarify-bias-and-fairness-terms)
+ [Exemples de blocs-notes](#clarify-data-bias-sample-notebooks)
+ [Indicateurs de biais de pré-entraînement](clarify-measure-data-bias.md)
+ [Générez des rapports sur les biais dans les données de pré-entraînement dans Studio SageMaker](clarify-data-bias-reports-ui.md)
# Indicateurs de biais de pré-entraînement
La mesure du biais dans les modèles ML est une première étape pour atténuer ce biais. Chaque mesure de biais correspond à une notion différente d'équité. Même la prise en compte de concepts simples d'équité conduit à de nombreuses mesures différentes applicables dans divers contextes. Par exemple, considérez l'équité en lien avec l'âge et, par souci de simplicité, supposez que les groupes d'âge moyen et les autres groupes d'âge sont les deux éléments démographiques pertinents, appelés *facettes*. Dans le cas d'un modèle ML de prêt, nous pouvons souhaiter que des prêts aux petites entreprises soient accordés à un nombre égal des deux éléments démographiques. Ou bien, lors du traitement de demandeurs d'emploi, nous pouvons souhaiter qu'un nombre égal de membres de chaque groupe démographique soient embauchés. Cependant, comme cette approche peut supposer qu'un nombre égal de membres des deux groupes d'âge conviennent à ces emplois, nous pouvons vouloir conditionner ce nombre. De plus, nous pouvons vouloir considérer, non pas si des nombres égaux s'appliquent, mais si nous avons un nombre égal de candidats qualifiés. Ou alors, nous pouvons considérer que l'équité est un taux d'acceptation égal de candidats qualifiés pour les deux groupes d'âge, ou un taux de rejet égal de candidats, ou les deux. Vous pouvez utiliser des jeux de données avec des proportions de données différentes sur les attributs qui vous intéressent. Ce déséquilibre peut confondre la mesure de biais que vous choisissez. Les modèles peuvent être plus précis dans la classification d'une facette par rapport à l'autre. Par conséquent, vous devez choisir des métriques de biais appropriées, du point de vue conceptuel, tant pour l'application que la situation.
Nous utilisons la notation suivante pour parler des métriques de biais. Le modèle conceptuel décrit ici concerne la classification binaire. Selon cette classification, les événements sont étiquetés comme ayant seulement deux résultats possibles dans leur espace d'échantillonnage, soit un résultat positif (avec la valeur 1), soit un résultat négatif (avec la valeur 0). Ce cadre peut généralement être étendu de façon directe à la classification multicatégorielle, ou à des cas impliquant des résultats valorisés continus lorsque cela est nécessaire. Dans la classification binaire, des étiquettes positive et négative sont affectées aux résultats enregistrés dans un jeu de données brut pour une facette favorisée *a* et une facette défavorisée *d*. Ces étiquettes y sont appelées *étiquettes observées* pour les distinguer des *étiquettes prédites* y’ qui sont affectées par un modèle de machine learning durant les étapes d’entraînement ou d’inférence du cycle de vie ML. Ces étiquettes servent à définir les distributions de probabilité Pa(y) et Pd(y) pour leurs résultats de facette respectifs.
+ étiquettes :
+ y représente les n étiquettes observées pour les résultats d'événements dans un jeu de données d'entraînement.
+ y' représente les étiquettes prédites pour les n étiquettes observées dans le jeu de données par un modèle entraîné.
+ résultats :
+ un résultat positif (avec la valeur 1) pour un échantillon, l'acceptation d'une demande par exemple.
+ n(1) est le nombre d'étiquettes observées pour les résultats positifs (acceptations).
+ n'(1) est le nombre d'étiquettes prédites pour les résultats positifs (acceptations).
+ un résultat négatif (avec la valeur 0) pour un échantillon, le rejet d'une demande par exemple.
+ n(0) est le nombre d'étiquettes observées pour les résultats négatifs (rejets).
+ n'(0) est le nombre d'étiquettes prédites pour les résultats négatifs (rejets).
+ valeurs de facettes :
+ facette *a* : la valeur de caractéristique qui définit un profil démographique que le biais favorise.
+ na est le nombre d'étiquettes observées pour la valeur de facette favorisée : na = na(1) \$1 na(0) la somme des étiquettes positives et négatives observées pour la facette de valeur *a*.
+ n'a est le nombre d'étiquettes prédites pour la valeur de facette favorisée : n'a = n'a(1) \$1 n'a(0) la somme des étiquettes positives et négatives de résultats prédits pour la facette de valeur *a*. Vous noterez que n'a = na.
+ facette *d* : la valeur de caractéristique qui définit un profil démographique que le biais défavorise.
+ nd est le nombre d'étiquettes observées pour la valeur de facette défavorisée : nd = nd(1) \$1 nd(0) la somme des étiquettes positives et négatives observées pour la facette de valeur *d*.
+ n'd est le nombre d'étiquettes prédites pour la valeur de facette défavorisée : n'd = n'd(1) \$1 n'd(0) la somme des étiquettes positives et négatives de résultats prédits pour la facette de valeur *d*. Vous noterez que n'd = nd.
+ distributions de probabilité pour les résultats des données de facettes étiquetées :
+ Pa(y) est la distribution de probabilité des étiquettes observées pour la facette *a*. Pour les données binaires étiquetées, cette distribution correspond au rapport entre le nombre d'échantillons dans la facette *a* étiquetés avec des résultats positifs et le nombre total, Pa(y1) = na(1)/ na, et au rapport entre le nombre d'échantillons étiquetés avec des résultats négatifs et le nombre total, Pa(y0) = na(0)/ na.
+ Pd(y) est la distribution de probabilité des étiquettes observées pour la facette *d*. Pour les données binaires étiquetées, cette distribution correspond au rapport entre le nombre d'échantillons dans la facette *d* étiquetés avec des résultats positifs et le nombre total, Pd(y1) = nd(1)/ nd, et au rapport entre le nombre d'échantillons étiquetés avec des résultats négatifs et le nombre total, Pd(y0) = nd(0)/ nd.
Les modèles entraînés sur des données biaisées par les disparités démographiques peuvent les apprendre, voire les exacerber. Pour identifier les biais dans les données avant de consacrer des ressources à l'entraînement des modèles, SageMaker Clarify fournit des mesures de biais de données que vous pouvez calculer sur des ensembles de données bruts avant l'entraînement. Toutes les métriques de pré-entraînement sont indépendantes du modèle, car elles ne dépendent pas des sorties du modèle, et elles sont donc valides pour n'importe quel modèle. La première métrique de biais examine le déséquilibre des facettes, mais pas les résultats. Elle détermine l'ampleur de la représentativité des données d'entraînement entre les différentes facettes, comme souhaité pour l'application. Les autres métriques de biais comparent la distribution des étiquettes de résultats de différentes manières pour les facettes *a* et *d* dans les données. Les métriques qui s'étendent sur des valeurs négatives peuvent détecter un biais négatif. Vous trouverez dans le tableau suivant une feuille de triche contenant des conseils rapides et des liens vers les métriques de biais de pré-entraînement.
Indicateurs de biais de pré-entraînement
| Métrique de biais | Description | Exemple de question | Interpréter les valeurs de métriques |
| --- | --- | --- | --- |
| [Déséquilibre de classe (CI)](clarify-bias-metric-class-imbalance.md) | Mesure le déséquilibre dans le nombre de membres entre les différentes valeurs de facettes. | Pourrait-il y avoir des biais fondés sur l'âge en raison du manque de données pour la population en dehors d'une facette d'âge moyen ? | Plage normalisée : [-1, \$11] Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Différence dans les proportions d'étiquettes (DPL)](clarify-data-bias-metric-true-label-imbalance.md) | Mesure le déséquilibre dans les résultats positifs entre les différentes valeurs de facettes. | Pourrait-il y avoir des biais fondés sur l'âge dans les prédictions ML en raison de l'étiquetage biaisé des valeurs des facettes dans les données ? | Plage pour les étiquettes de facettes binaires et multicatégorielles : [-1, \$11] Plage pour les étiquettes continues : (-∞, \$1∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergence de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md) | Mesure l'ampleur de la divergence des distributions de résultats entre les différentes facettes du point de vue entropique. | Quelle est l'ampleur de la différence entre les distributions pour les résultats des demandes de prêt concernant les différents groupes démographiques ? | Plage pour les résultats binaires, multicatégoriels ou continus : [0, \$1∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergence de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) | Mesure l'ampleur de la divergence des distributions de résultats entre les différentes facettes du point de vue entropique. | Quelle est l'ampleur de la différence entre les distributions pour les résultats des demandes de prêt concernant les différents groupes démographiques ? | Plage pour les résultats binaires, multicatégoriels ou continus : [0, \$1∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Norme Lp (LP)](clarify-data-bias-metric-lp-norm.md) | Mesure une différence de norme p entre les distributions démographiques distinctes des résultats associés à différentes facettes d'un jeu de données. | Quelle est l'ampleur de la différence entre les distributions pour les résultats des demandes de prêt concernant les différents groupes démographiques ? | Plage pour les résultats binaires, multicatégoriels ou continus : [0, \$1∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Distance de variation totale (TVD)](clarify-data-bias-metric-total-variation-distance.md) | Mesure la moitié de la différence de la norme L1 entre les distributions démographiques distinctes des résultats associés à différentes facettes d'un jeu de données. | Quelle est l'ampleur de la différence entre les distributions pour les résultats des demandes de prêt concernant les différents groupes démographiques ? | Plage pour les résultats binaires, multicatégoriels et continus : [0, \$1∞) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) | Mesure la divergence maximale entre les résultats dans les distributions pour différentes facettes d'un jeu de données. | Quels résultats en termes de dossiers d'admission à l'université présentent les plus grandes disparités selon le groupe démographique ? | Plage de valeurs KS pour les résultats binaires, multicatégoriels et continus : [0, \$11][\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Disparité démographique conditionnelle (CDD)](clarify-data-bias-metric-cddl.md) | Mesure la disparité globale des résultats entre les différentes facettes, mais aussi par sous-groupes. | La proportion de rejets des admissions à l'université de certains groupes est-elle supérieure à la proportion d'acceptations ? | Plage de CDD : [-1, \$11] [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-data-bias.html) |
Pour plus d’informations sur les indicateurs de biais, consultez [Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
**Topics**
+ [Déséquilibre de classe (CI)](clarify-bias-metric-class-imbalance.md)
+ [Différence dans les proportions d'étiquettes (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ [Divergence de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ [Divergence de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ [Norme Lp (LP)](clarify-data-bias-metric-lp-norm.md)
+ [Distance de variation totale (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ [Disparité démographique conditionnelle (CDD)](clarify-data-bias-metric-cddl.md)
# Déséquilibre de classe (CI)
Le biais de déséquilibre de classe (CI) se produit lorsqu'une valeur de facette *d* a moins d'échantillons d'entraînement qu'une autre facette *a* dans le jeu de données. Cela vient du fait que les modèles retiennent plutôt les facettes volumineuses au détriment des plus petites, de sorte que l'erreur d'entraînement peut être plus élevée pour la facette *d*. En outre, comme les modèles risquent également de surajuster les plus petits jeux de données, l’erreur de test peut être plus élevée pour la facette *d*. Prenons l'exemple d'un modèle de machine learning entraîné principalement sur des données provenant d'individus d'âge moyen (facette a), il pourrait être moins précis lors de prédictions impliquant des personnes plus jeunes et plus âgées (facette d).
La formule pour la mesure (normalisée) du déséquilibre entre facettes est la suivante :
CI = (na - nd)/(na \$1 nd)
Où na est le nombre de membres de la facette *a* et nd le nombre de membres de la facette *d*. Ses valeurs s'étendent sur l'intervalle [-1, 1].
+ Les valeurs CI positives indiquent que la facette *a* contient plus d'échantillons d'entraînement dans le jeu de données, tandis qu'une valeur de 1 indique que les données contiennent uniquement des membres de la facette *a*.
+ Les valeurs de CI proches de zéro indiquent une distribution plus égale des membres entre les facettes, tandis qu'une valeur de zéro indique une partition parfaitement égale entre les facettes et représente une distribution équilibrée des échantillons dans les données d'entraînement.
+ Les valeurs CI négatives indiquent que la facette *d*contient plus d'échantillons d'entraînement dans le jeu de données, tandis qu'une valeur de -1 indique que les données contiennent uniquement des membres de la facette *d*.
+ Les valeurs CI proches des valeurs extrêmes -1 ou 1 sont très déséquilibrées et présentent un risque important de prédictions biaisées.
S'il existe un déséquilibre réel significatif entre les facettes, vous pouvez rééquilibrer l'échantillon avant de procéder à l'entraînement des modèles sur celui-ci.
# Différence dans les proportions d'étiquettes (DPL)
La différence dans les proportions d'étiquettes (DPL) compare la proportion de résultats observés avec des étiquettes positives pour la facette *d* à la proportion de résultats observés avec des étiquettes positives pour la facette *a* dans un jeu de données d'entraînement. Par exemple, vous pouvez l'utiliser pour comparer la proportion d'individus d'âge moyen (facette *a*) et d'autres groupes d'âge (facette *d*) dont les prêts financiers sont approuvés. Les modèles de machine learning tentent d'imiter au maximum les décisions de données d'entraînement. Ainsi, un modèle de machine learning entraîné sur un jeu de données avec une DPL élevée est susceptible de refléter le même déséquilibre dans ses prédictions futures.
La formule pour la différence dans les proportions d'étiquettes est la suivante :
DPL = (qa - qd)
Où :
+ qa = na(1)/na est la proportion de la facette *a* ayant une valeur d'étiquette observée de 1. Par exemple, la proportion d'individus d'âge moyen dont les prêts sont approuvés. Ici na(1) représente le nombre de membres de la facette *a* qui obtiennent un résultat positif et na est le nombre de membres de la facette *a*.
+ qd = nd(1)/nd est la proportion de la facette *d* ayant une valeur d'étiquette observée de 1. Par exemple, la proportion d'individus autres que d'âge moyen dont les prêts sont approuvés. Ici nd(1) représente le nombre de membres de la facette *d* qui obtiennent un résultat positif et nd est le nombre de membres de la facette *d*.
Si la DPL est assez proche de 0, nous pouvons dire que la *parité démographique* est atteinte.
Pour les étiquettes de facettes binaires et multicatégoriels, les valeurs de DPL normalisées s'étendent sur l'intervalle (-1, 1). Pour les étiquettes continues, un seuil est défini pour réduire les étiquettes en binaire.
+ Les valeurs de DPL positives indiquent que la proportion de résultats positifs est plus élevée pour la facette *a* que pour la facette *d*.
+ Les valeurs de DPL proches de zéro indiquent que la proportion de résultats positifs est plus égale entre les facettes, tandis qu'une valeur de zéro indique une parfaite parité démographique.
+ Les valeurs DPL négatives indiquent que la proportion de résultats positifs est plus élevée pour la facette *d* que pour la facette *a*.
Le problème représenté par une DPL élevée varie d'un cas à l'autre. Une DPL élevée problématique peut signaler des problèmes sous-jacents dans les données. Par exemple, un jeu de données avec une DPL élevée peut refléter des biais historiques ou des préjudices basés sur l'âge, à l'égard de groupes démographiques, qu'il ne serait pas souhaitable qu'un modèle apprenne.
# Divergence de Kullback-Leibler (KL)
La divergence de Kullback-Leibler (KL) mesure l'ampleur de la divergence entre la distribution d'étiquettes observée pour la facette *a*, Pa(y) et la distribution pour la facette *d*, Pd(y). Elle est également connue sous le nom d'entropie relative de Pa(y) par rapport à Pd(y), et quantifie la quantité d'informations perdues lors du passage de Pa(y) à Pd(y).
La formule pour la divergence de Kullback-Leibler est la suivante :
KL(Pa \$1\$1 Pd) = ∑yPa(y)\$1log[Pa(y)/Pd(y)]
C'est l'attente de la différence logarithmique entre les probabilités Pa(y) et Pd(y), lorsque l'attente est pondérée par les probabilités Pa(y). Elle n'indique pas une vraie distance entre les distributions, car elle est asymétrique et ne satisfait pas l'inégalité du triangle. La mise en œuvre utilise des logarithmes naturels et exprime la divergence de KL en unités de nats. L'utilisation de différentes bases logarithmiques donne des résultats proportionnels mais dans des unités différentes. Par exemple, l'utilisation d'une base 2 donne KL en unités de bits.
Par exemple, supposons qu'un groupe de demandeurs de prêts a un taux d'approbation de 30 % (facette *d*) et que le taux d'approbation pour les autres demandeurs (facette *a*) est de 80 %. La formule de Kullback-Leibler indique la divergence de distribution des étiquettes de la facette *a* par rapport à la facette *d* :
KL = 0,8\$1ln (0,8/0,3) \$1 0,2\$1ln (0,2/0,7) = 0,53
Ici, il y a deux termes dans la formule, car l'exemple cite des étiquettes binaires. Cette mesure peut être appliquée à plusieurs autres étiquettes en plus des étiquettes binaires. Par exemple, dans un scénario d'admission à l'université, supposons qu'un candidat puisse se voir attribuer l'une des trois catégories d'étiquettes suivantes : yi = \$1y0, y1, y2\$1 = \$1rejeté, sur liste d'attente, accepté\$1.
La plage de valeurs de la métrique KL pour les résultats binaires, multicatégoriels et continus est de [0, \$1∞).
+ Les valeurs proches de zéro signifient une distribution similaire des résultats pour les différentes facettes.
+ Les valeurs positives indiquent une divergence dans les distributions d'étiquettes, d'autant plus importante que le nombre de valeurs positives est élevé.
# Divergence de Jensen-Shannon (JS)
La divergence de Jensen-Shannon (JS) mesure l'ampleur de la divergence des distributions d'étiquettes entre les différentes facettes, du point de vue entropique. Elle est basée sur la divergence de Kullback-Leibler, mais elle est symétrique.
La formule de la divergence de Jensen-Shannon est la suivante :
JS = ½\$1[KL(Pa \$1\$1 P) \$1 KL(Pd \$1\$1 P)]
Où P = ½ (Pa \$1 Pd), la distribution moyenne des étiquettes entre les facettes *a* et *d*.
La plage de valeurs JS pour les résultats binaires, multicatégoriels et continus est de [0, ln (2)].
+ Les valeurs proches de zéro signifient que les distributions d'étiquettes sont similaires.
+ Les valeurs positives indiquent une divergence dans les distributions d'étiquettes, d'autant plus importante que le nombre de valeurs positives est élevé.
Cette métrique indique s’il existe une grande divergence dans l’une des étiquettes entre les facettes.
# Norme Lp (LP)
La norme Lp (LP) mesure la distance de la norme p entre les distributions de facettes des étiquettes observées dans un jeu de données d'entraînement. Cette métrique n'est pas négative et ne peut donc pas détecter le biais inverse.
La formule pour la norme Lp est la suivante :
Lp(Pa, Pd) = ( ∑y\$1\$1Pa - Pd\$1\$1p)1/p
Lorsque la distance de la norme p entre les points x et y est définie comme suit :
Lp(x, y) = (\$1x1-y1\$1p \$1 \$1x2-y2\$1p \$1 … \$1\$1xn-yn\$1p)1/p
La norme 2 est la norme euclidienne. Supposons que vous avez une distribution de résultats avec trois catégories, par exemple, yi = \$1y0, y1, y2\$1 = \$1accepté, sur liste d'attente, rejeté\$1 dans un scénario multicatégoriel d'admission à l'université. Vous prenez la somme des carrés des différences entre les nombres de résultats pour les facettes *a* et *d*. La distance euclidienne obtenue est calculée de la manière suivante :
L2(Pa, Pd) = [(na(0) - nd(0))2 \$1 (na(1) - nd(1))2 \$1 (na(2) - nd(2))2]1/2
Où :
+ na(i) est le nombre des résultats de la énième catégorie dans la facette *a* : par exemple na(0) est le nombre d'acceptations de la facette *a*.
+ nd(i) est le nombre des résultats de la énième catégorie dans la facette *d* : par exemple nd(2) est le nombre de rejets de la facette *d*.
La plage de valeurs JS pour les résultats binaires, multicatégoriels et continus est de [0, √2), où :
+ Les valeurs proches de zéro signifient que les distributions d'étiquettes sont similaires.
+ Les valeurs positives indiquent une divergence dans les distributions d'étiquettes, d'autant plus importante que le nombre de valeurs positives est élevé.
# Distance de variation totale (TVD)
La métrique de biais des données associée à la distance de variation totale (TVD) est la moitié de la norme L1. La TVD est la plus grande différence possible entre les distributions de probabilités pour les résultats d'étiquettes des facettes *a* et *d*. La norme L1 est la distance de Hamming, une métrique utilisée pour comparer deux chaînes de données binaires en déterminant le nombre minimum de substitutions nécessaires pour qu'une chaîne en devienne une autre. Si les chaînes devaient être des copies les unes des autres, la métrique détermine le nombre d'erreurs qui se sont produites lors de la copie. Dans le contexte de la détection de biais, la TVD quantifie le nombre de résultats qui devraient être modifiés dans la facette *a* pour correspondre aux résultats dans la facette *d*.
La formule pour la distance de variation totale est la suivante :
TVD = ½\$1L1(Pa, Pd)
Supposons par exemple que vous avez une distribution de résultats avec trois catégories, yi = \$1y0, y1, y2\$1 = \$1accepté, sur liste d'attente, rejeté\$1 dans un scénario multicatégoriel d'admission à l'université. Pour calculer la TVD, vous prenez les différences entre les nombres des facettes *a* et *d* pour chaque résultat. Le résultat est le suivant :
L1(Pa, Pd) = \$1na(0) - nd(0)\$1 \$1 \$1na(1) - nd(1)\$1 \$1 \$1na(2) - nd(2)\$1
Où :
+ na(i) est le nombre des résultats de la énième catégorie dans la facette *a* : par exemple na(0) est le nombre d'acceptations de la facette *a*.
+ nd(i) est le nombre des résultats de la énième catégorie dans la facette d : par exemple nd(2) est le nombre de rejets de la facette *d*.
La plage de valeurs TVD pour les résultats binaires, multicatégoriels et continus est de [0, 1), où :
+ Les valeurs proches de zéro signifient que les distributions d'étiquettes sont similaires.
+ Les valeurs positives indiquent une divergence dans les distributions d'étiquettes, d'autant plus importante que le nombre de valeurs positives est élevé.
# Kolmogorov-Smirnov (KS)
La métrique de biais de Kolmogorov-Smirnov (KS) est égale à la divergence maximale entre les étiquettes dans les distributions pour les facettes *a* et *d* d'un jeu de données. Le test KS à deux échantillons mis en œuvre par SageMaker Clarify complète les autres mesures du déséquilibre des étiquettes en identifiant l'étiquette la plus déséquilibrée.
La formule pour la métrique de Kolmogorov-Smirnov est la suivante :
KS = max(\$1Pa(y) - Pd(y)\$1)
Par exemple, supposons qu'un groupe de candidats (facette*a*) à l'entrée à l'université sont rejetés, mis sur liste d'attente ou acceptés à hauteur de 40 %, 40 % et 20 % respectivement, et que ces taux pour les autres candidats (facette *d*) sont de 20 %, 10 % et 70 %. La formule pour la métrique de Kolmogorov-Smirnov est la suivante :
KS = max(\$10,4-0,2\$1, \$10,4-0,1\$1, \$10,2-0,7\$1) = 0,5
Cela nous indique que la divergence maximale entre les distributions de facettes est de 0,5 et se produit dans les taux d'acceptation. Il y a trois termes dans l'équation parce que les étiquettes sont du type multiclasse avec une cardinalité de trois.
La plage de valeurs LP pour les résultats binaires, multicatégoriel et continus est de [0, \$11], où :
+ Les valeurs proches de zéro indiquent une distribution uniforme des étiquettes entre les facettes dans toutes les catégories de résultats. Par exemple, les deux facettes demandant un prêt ont obtenu 50 % des acceptations et 50 % des rejets.
+ Les valeurs proches de un indiquent que toutes les étiquettes d'un résultat se trouvaient dans une seule facette. Par exemple, la facette *a* a obtenu 100 % des acceptations, tandis que la facette *d* n'en a obtenu aucune.
+ Les valeurs intermédiaires indiquent des degrés relatifs de déséquilibre maximal des étiquettes.
# Disparité démographique conditionnelle (CDD)
La métrique de disparité démographique (DD) détermine si une proportion des résultats rejetés dans le jeu de données est supérieure à celle des résultats acceptés pour une facette. Dans le cas de figure binaire où il y a deux facettes, hommes et femmes par exemple, qui constituent le jeu de données, la facette défavorisée est étiquetée facette *d* et la facette favorisée est étiquetée facette *a*. Par exemple, dans le cas des admissions à l'université, si les candidats de sexe féminin représentaient 46 % des rejets et seulement 32 % des acceptations, nous pouvons parler de *disparité démographique* car le taux de rejet des candidats de sexe féminin dépasse leur taux d'acceptation. Les femmes candidates sont étiquetées facette *d* dans ce cas. Si les hommes représentent 54 % des candidats rejetés et 68 % des candidats acceptés, alors il n'y a pas de disparité démographique pour cette facette puisque le taux de rejet est inférieur au taux d'acceptation. Dans ce cas, les candidats masculins sont étiquetés facette *a*.
La formule pour la disparité démographique de la facette la moins favorisée *d* est la suivante :
DDd = nd(0)/n(0) - nd(1)/n(1) = PdR(y0) - PdA(y1)
Où :
+ n(0) = na(0) \$1 nd(0) représente le nombre total de résultats rejetés dans le jeu de données pour la facette favorisée *a* et une facette défavorisée *d*.
+ n(1) = na(1) \$1 nd(1) représente le nombre total de résultats acceptés dans le jeu de données pour la facette favorisée *a* et la facette défavorisée *d*.
+ PdR(y0) est la proportion des résultats rejetés (avec la valeur 0) dans la facette *d*.
+ PdA(y1) est la proportion des résultats acceptés (valeur 1) dans la facette *d*.
Pour l'exemple de l'admission à l'université, la disparité démographique pour les femmes est DDd = 0,46 - 0,32 = 0,14. Pour les hommes : DDa = 0,54 - 0,68 = 0,14.
Une métrique de disparité démographique conditionnelle (CDD) qui conditionne une DD sur des attributs définissant une strate de sous-groupes dans le jeu de données est nécessaire pour exclure le paradoxe de Simpson. Le regroupement peut donner des informations sur la cause des disparités démographiques apparentes pour les facettes moins favorisées. Le cas classique s’est produit lors des admissions à Berkeley où les hommes étaient globalement acceptés à un taux plus élevé que les femmes. Les statistiques de ce cas ont été utilisées dans l'exemple de calcul de la DD. Cependant, à l'examen des sous-groupes départementaux, les taux d'admission des femmes étaient supérieurs à ceux des hommes lorsque qu'ils sont conditionnés par le département. Cela venait du fait que les femmes avaient déposé une demande dans des départements où les taux d’acceptation étaient inférieurs à ceux des hommes. L'examen des taux d'acceptation des sous-groupes a révélé que les femmes étaient effectivement acceptées à un taux plus élevé que les hommes dans les départements où les taux d'acceptation étaient inférieurs.
La métrique CDD fournit une métrique unique pour toutes les disparités trouvées dans les sous-groupes définis par un attribut d'un jeu de données en en faisant la moyenne. Elle est définie comme la moyenne pondérée des disparités démographiques (DDi) pour chacun des sous-groupes, la disparité de chaque sous-groupe étant pondérée proportionnellement au nombre d'observations qu'il contient. La formule pour la disparité démographique conditionnelle est la suivante :
CDD = (1/n)\$1∑ini \$1DDi
Où :
+ ∑ini = n est le nombre total d'observations et ni est le nombre d'observations pour chaque sous-groupe.
+ DDi = ni(0)/n(0) - ni(1)/n(1) = PiR(y0) - PiA(y1) est la disparité démographique pour le énième sous-groupe.
La disparité démographique pour un sous-groupe (DDi) correspond à la différence entre la proportion de résultats rejetées et la proportion de résultats acceptés pour chaque sous-groupe.
La plage des valeurs DD pour les résultats binaires du jeu de données complet DDd ou pour ses sous-groupes conditionnés DDi est [-1, \$11].
+ \$11 : lorsqu'il n'y a aucun rejet dans la facette *a* ou le sous-groupe, et aucune acceptation dans la facette *d* ou le sous-groupe
+ Les valeurs positives indiquent une disparité démographique dans la mesure où la proportion des résultats rejetés dans le jeu de données pour la facette *d* ou le sous-groupe est supérieure à celle des résultats acceptés. Plus la valeur est élevée, moins la facette est favorisée et plus la disparité est grande.
+ Les valeurs négatives indiquent qu'il n'y a pas de disparité démographique car la facette *d* ou le sous-groupe présente une plus grande proportion des résultats acceptés dans le jeu de données que de résultats rejetés. Plus la valeur est faible, plus la facette est favorisée.
+ -1 : lorsqu’il n’y a aucun rejet dans la facette *d* ou le sous-groupe, et aucune acceptation dans la facette *a* ou le sous-groupe
Si vous ne posez aucune condition, la CDD est égale à zéro si et seulement si le DPL est égal à zéro.
Cette métrique est utile pour explorer les concepts de discrimination directe et indirecte et de justification objective dans la législation et la jurisprudence de l'UE et du Royaume-Uni en matière de non-discrimination. Pour plus d’informations, consultez [Why Fairness Cannot Be Automated](https://arxiv.org/abs/2005.05906). Ce document contient également les données pertinentes et l’analyse du cas des admissions à Berkeley qui montre comment le fait de conditionner les taux d’admission à des sous-groupes de départements illustre le paradoxe de Simpson.
# Générez des rapports sur les biais dans les données de pré-entraînement dans Studio SageMaker
SageMaker Clarify est intégré à Amazon SageMaker Data Wrangler, qui peut vous aider à identifier les biais lors de la préparation des données sans avoir à écrire votre propre code. Data Wrangler fournit une end-to-end solution pour importer, préparer, transformer, présenter et analyser des données avec Amazon Studio. SageMaker Pour plus d’informations sur le flux de préparation des données Data Wrangler, consultez [Préparez les données ML avec Amazon SageMaker Data Wrangler](data-wrangler.md).
Vous spécifiez des attributs intéressants, tels que le sexe ou l'âge, et SageMaker Clarify exécute un ensemble d'algorithmes pour détecter la présence de biais dans ces attributs. Une fois l'algorithme exécuté, SageMaker Clarify fournit un rapport visuel avec une description des sources et de la gravité des biais possibles afin que vous puissiez planifier des mesures pour les atténuer. Par exemple, dans un ensemble de données financières qui contient quelques exemples de prêts commerciaux accordés à un groupe d'âge par rapport à d'autres, l' SageMaker IA signale le déséquilibre afin que vous puissiez éviter un modèle qui défavorise ce groupe d'âge.
**Analyser et rapporter les biais de données**
Pour démarrer avec Data Wrangler, consultez [Démarrer avec Data Wrangler](data-wrangler-getting-started.md).
1. Dans Amazon SageMaker Studio Classic, dans le menu **Accueil** (![\[Black square icon representing a placeholder or empty image.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/studio/icons/house.png)) du panneau de gauche, accédez au nœud **Data**, puis choisissez **Data Wrangler**. Cela ouvre la **page de destination de Data Wrangler** dans Studio Classic.
1. Cliquez sur le bouton **\$1 Import data** (\$1 Importer des données) pour créer un nouveau flux.
1. Sur la page de votre flux, dans l'onglet **Import** (Importer), choisissez Amazon S3, accédez à votre compartiment Amazon S3, recherchez votre jeu de données, puis choisissez **Import** (Importer).
1. Après avoir importé vos données, sur le graphe de flux de l'onglet **Data flow** (Flux de données), choisissez le signe **\$1** à droite du nœud **Data types** (Types de données).
1. Choisissez **Add analysis** (Ajouter une analyse).
1. Sur la page **Create Analysis** (Créer une analyse), choisissez **Bias Report** (Rapport de biais) pour **Analysis type** (Type d'analyse).
1. Configurez le rapport de biais en indiquant un nom (**Name**) pour le rapport, la colonne à prédire et s'il s'agit d'une valeur ou d'un seuil, la colonne à analyser pour le biais (la facette) et s'il s'agit d'une valeur ou d'un seuil.
1. Continuez à configurer le rapport de biais en choisissant les métriques de biais.
![\[Choisissez la métrique de biais.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify-data-wrangler-configure-bias-metrics.png)
1. Choisissez **Check for bias (Vérifier la présence de biais)**pour générer et afficher le rapport de biais. Faites défiler la page vers le bas pour afficher tous les rapports.
![\[Générez et affichez le rapport de biais.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify-data-wrangler-create-bias-report.png)
1. Choisissez le signe « supérieur à » situé à droite de chaque description de la métrique de biais pour afficher la documentation vous permettant d'interpréter la signification des valeurs de métrique.
1. Pour afficher un tableau récapitulatif des valeurs de métrique de biais. Sélectionnez l'option **Table** (Tableau). Pour enregistrer le rapport, choisissez **Save** (Enregistrer) dans le coin inférieur droit de la page. Vous pouvez voir le rapport sur le diagramme de flux dans l'onglet **Data flow** (Flux de données). Cliquez deux fois sur le rapport pour l’ouvrir.
# Biais de post-entraînement dans les données et les modèles
L'analyse des biais de post-entraînement peut aider à détecter les biais provenant des données ou introduits par les algorithmes de classification et de prédiction. Ces analyses prennent en compte les données, y compris les étiquettes, et les prédictions d’un modèle. Vous évaluez la performance en analysant les étiquettes prédites ou en comparant les prédictions aux valeurs cibles observées dans les données par rapport à des groupes ayant des attributs différents. Entre les différentes notions d'équité existantes, chacune exige des métriques de biais différentes pour la mesure.
La difficulté à détecter les concepts juridiques d'équité peut les rendre difficiles à appréhender. Citons, par exemple, le concept américain d’impact disparate selon lequel un groupe, pourtant désigné comme étant une facette moins favorisée *d*, subit un effet négatif même lorsque l’approche adoptée semble être équitable. Bien que ce type de biais puisse ne pas provenir d'un modèle de machine learning, il peut quand même être détecté par une analyse des biais de post-entraînement.
Amazon SageMaker Clarify essaie de garantir une utilisation cohérente de la terminologie. Pour obtenir la liste des termes et leurs définitions, consultez [Amazon SageMaker précise les termes relatifs à la partialité et à l'équité](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms).
Pour plus d'informations sur les mesures de biais post-formation, consultez [Découvrez comment Amazon SageMaker Clarify aide à détecter les biais](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/) et les [mesures d'équité pour le Machine Learning dans le secteur de la finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf). .
# Indicateurs de biais de post-entraînement dans les données et les modèles
Amazon SageMaker Clarify fournit onze données post-formation et des mesures de biais du modèle pour aider à quantifier les différentes conceptions de l'équité. Il est impossible de satisfaire tous ces concepts simultanément. La sélection dépend alors des spécificités des cas impliquant le biais potentiel qui est analysé. La plupart de ces métriques sont une combinaison des nombres tirés des matrices de confusion de classification binaire pour les différents groupes démographiques. Comme une gamme étendue de métriques permet de définir l'équité et la partialité, le jugement humain est indispensable pour comprendre et choisir les métriques pertinentes pour le cas d'utilisation individuel, et les clients doivent consulter les parties prenantes appropriées afin de déterminer la mesure d'équité qui convient à leur application.
Nous utilisons la notation suivante pour les métriques de biais. Le modèle conceptuel décrit ici concerne la classification binaire. Selon cette classification, les événements sont étiquetés comme ayant seulement deux résultats possibles dans leur espace d'échantillonnage, soit un résultat positif (avec la valeur 1), soit un résultat négatif (avec la valeur 0). Ce cadre peut généralement être étendu de façon directe à la classification multicatégorielle, ou à des cas impliquant des résultats valorisés continus lorsque cela est nécessaire. Dans la classification binaire, des étiquettes positive et négative sont affectées aux résultats enregistrés dans un jeu de données brut pour une facette favorisée *a* et une facette défavorisée *d*. Ces étiquettes y sont appelées *étiquettes observées* pour les distinguer des *étiquettes prédites* y’ qui sont affectées par un modèle de machine learning durant les étapes d’entraînement ou d’inférence du cycle de vie ML. Ces étiquettes servent à définir les distributions de probabilité Pa(y) et Pd(y) pour leurs résultats de facette respectifs.
+ étiquettes :
+ y représente les n étiquettes observées pour les résultats d'événements dans un jeu de données d'entraînement.
+ y' représente les étiquettes prédites pour les n étiquettes observées dans le jeu de données par un modèle entraîné.
+ résultats :
+ un résultat positif (avec la valeur 1) pour un échantillon, l'acceptation d'une demande par exemple.
+ n(1) est le nombre d'étiquettes observées pour les résultats positifs (acceptations).
+ n'(1) est le nombre d'étiquettes prédites pour les résultats positifs (acceptations).
+ un résultat négatif (avec la valeur 0) pour un échantillon, le rejet d'une demande par exemple.
+ n(0) est le nombre d'étiquettes observées pour les résultats négatifs (rejets).
+ n'(0) est le nombre d'étiquettes prédites pour les résultats négatifs (rejets).
+ valeurs de facettes :
+ facette *a* : la valeur de caractéristique qui définit un profil démographique que le biais favorise.
+ na est le nombre d'étiquettes observées pour la valeur de facette favorisée : na = na(1) \$1 na(0) la somme des étiquettes positives et négatives observées pour la facette de valeur *a*.
+ n'a est le nombre d'étiquettes prédites pour la valeur de facette favorisée : n'a = n'a(1) \$1 n'a(0) la somme des étiquettes positives et négatives de résultats prédits pour la facette de valeur *a*. Vous noterez que n'a = na.
+ facette *d* : la valeur de caractéristique qui définit un profil démographique que le biais défavorise.
+ nd est le nombre d'étiquettes observées pour la valeur de facette défavorisée : nd = nd(1) \$1 nd(0) la somme des étiquettes positives et négatives observées pour la facette de valeur *d*.
+ n'd est le nombre d'étiquettes prédites pour la valeur de facette défavorisée : n'd = n'd(1) \$1 n'd(0) la somme des étiquettes positives et négatives de résultats prédits pour la facette de valeur *d*. Vous noterez que n'd = nd.
+ distributions de probabilité pour les résultats des données de facettes étiquetées :
+ Pa(y) est la distribution de probabilité des étiquettes observées pour la facette *a*. Pour les données binaires étiquetées, cette distribution correspond au rapport entre le nombre d'échantillons dans la facette *a* étiquetés avec des résultats positifs et le nombre total, Pa(y1) = na(1)/ na, et au rapport entre le nombre d'échantillons étiquetés avec des résultats négatifs et le nombre total, Pa(y0) = na(0)/ na.
+ Pd(y) est la distribution de probabilité des étiquettes observées pour la facette *d*. Pour les données binaires étiquetées, cette distribution correspond au rapport entre le nombre d’échantillons dans la facette *d* étiquetés avec des résultats positifs et le nombre total, Pd(y1) = nd(1)/ nd, et au rapport entre le nombre d’échantillons étiquetés avec des résultats négatifs et le nombre total, Pd(y0) = nd(0)/ nd.
Vous trouverez dans le tableau suivant un aide-mémoire contenant des conseils rapides et des liens vers les métriques de biais de post-entraînement.
Métriques de biais de post-entraînement
| Métrique de biais de post-entraînement | Description | Exemple de question | Interpréter les valeurs des métriques |
| --- | --- | --- | --- |
| [Différence dans les proportions positives des étiquettes prédites (DPPL)](clarify-post-training-bias-metric-dppl.md) | Mesure la différence dans la proportion de prédictions positives entre la facette favorisée a et la facette défavorisée d. | Un déséquilibre éventuel entre les groupes démographiques dans les résultats positifs prédits peut-il indiquer un biais ? | Plage pour les étiquettes de facettes binaires et multicatégorie : `[-1,+1]` Plage pour les étiquettes continues : (-∞, \$1∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Impact disparate (DI)](clarify-post-training-bias-metric-di.md) | Mesure le rapport des proportions des étiquettes prédites pour la facette favorisée a et la facette défavorisée d. | Un déséquilibre éventuel entre les groupes démographiques dans les résultats positifs prédits peut-il indiquer un biais ? | Plage pour les étiquettes de facettes binaires et multicatégorie normalisées, et les étiquettes continues : [0, ∞) Interprétation : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Disparité démographique conditionnelle dans les étiquettes prédites (CDDPL)](clarify-post-training-bias-metric-cddpl.md) | Mesure la disparité globale des étiquettes prédites entre les facettes, mais aussi par sous-groupes. | La proportion de rejets des demandes de prêt de certains groupes démographiques est-elle supérieure à la proportion d’acceptations ? | Plage de valeurs CDDPL pour les résultats binaires, multicatégorie et continus : `[-1, +1]` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [FlipTest contrefactuel (FT)](clarify-post-training-bias-metric-ft.md) | Examine chaque membre de la facette d et évalue si des prédictions de modèle sont différentes pour des membres similaires de la facette a. | Un groupe d'âge spécifique correspond-il étroitement, sur toutes les caractéristiques, à un groupe d'âge différent, tout en étant payé plus en moyenne ? | La plage pour les étiquettes de facettes binaires et multicatégorie est [-1, \$11]. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence de précision (AD)](clarify-post-training-bias-metric-ad.md) | Mesure la différence entre la précision de la prédiction pour les facettes favorisée et défavorisée. | La prédiction d’étiquettes par le modèle est-elle aussi précise pour les demandes de tous les groupes démographiques ? | La plage pour les étiquettes de facettes binaires et multicatégorie est [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence de rappel (RD)](clarify-post-training-bias-metric-rd.md) | Compare le rappel du modèle pour les facettes favorisée et défavorisée. | Le taux de rappel pour un modèle est plus élevé pour un groupe d’âge que pour un autre. Peut-on dire qu’il existe un biais basé sur l’âge au niveau des prêts ? | Plage de classification binaire et multicatégorie : `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence d'acceptation conditionnelle (DCAcc)](clarify-post-training-bias-metric-dcacc.md) | Compare les étiquettes observées aux étiquettes prédites par un modèle. Évalue s'il en va de même entre les facettes pour les résultats positifs prédits (acceptations). | Dans le cadre de la comparaison d'un groupe d'âge à un autre, les prêts sont-ils acceptés plus fréquemment ou moins souvent que prévu (sur la base des qualifications) ? | Plage pour les étiquettes de facettes binaires et multicatégorie, et les étiquettes continues : (-∞, \$1∞). [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence dans les taux d'acceptation (DAR)](clarify-post-training-bias-metric-dar.md) | Mesure la différence dans les rapports entre les résultats positifs observés (TP) et les positifs prédits (TP \$1 FP) entre les facettes favorisée et défavorisée. | La précision du modèle est-elle identique lorsqu’il s’agit de prédire des acceptations de prêts pour les candidats qualifiés dans tous les groupes d’âge ? | La plage pour les étiquettes de facettes binaires et multicatégorie, et les étiquettes continues est [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence de spécificité (SD)](clarify-post-training-bias-metric-sd.md) | Compare la spécificité du modèle entre les facettes favorisée et défavorisée. | Existe-t-il un biais basé sur l'âge au niveau des prêts du fait que le modèle prédit une plus grande spécificité pour un groupe d'âge que pour un autre ? | Plage de classification binaire et multicatégorie : `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence dans les rejets conditionnels (DCR)](clarify-post-training-bias-metric-dcr.md) | Compare les étiquettes observées aux étiquettes prédites par un modèle, et évalue s’il en va de même entre les facettes pour les résultats négatifs (rejets). | Le nombre de rejets de demandes de prêt est-il plus ou moins élevé que prédit pour un groupe d'âge par rapport à un autre selon les qualifications ? | Plage pour les étiquettes de facettes binaires et multicatégorie, et les étiquettes continues : (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Différence dans les taux de rejets (DRR)](clarify-post-training-bias-metric-drr.md) | Mesure la différence dans les rapports entre les résultats négatifs observés (TN) et les négatifs prédits (TN \$1 FN) entre les facettes défavorisée et favorisée. | La précision du modèle est-elle identique lorsqu’il s’agit de prédire des rejets de prêts pour les candidats non qualifiés dans tous les groupes d’âge ? | La plage pour les étiquettes de facettes binaires et multicatégorie, et les étiquettes continues est [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Égalité de traitement (TE)](clarify-post-training-bias-metric-te.md) | Mesure la différence dans le rapport entre faux positifs et faux négatifs entre les facettes favorisée et défavorisée. | Dans les demandes de prêt, le rapport relatif entre faux positifs et faux négatifs est-il identique pour tous les groupes d'âge ? | Plage pour les étiquettes de facettes binaires et multicatégorie : (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Entropie généralisée (GE)](clarify-post-training-bias-metric-ge.md) | Mesure l'inégalité des bénéfices b affectés à chaque entrée par les prédictions de modèle. | Parmi les deux modèles candidats pour la classification des demandes de prêt, l'un conduit-il à une distribution plus inégale des résultats souhaités que l'autre ? | Plage pour les étiquettes binaires et multicatégorie : (0, 0,5). L'entropie généralisée (GE) n'est pas définie si le modèle prédit uniquement des faux négatifs.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
Pour plus d'informations sur les métriques de biais de post-entraînement, consultez [A Family of Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf) (Série de mesures d'équité pour le machine learning appliqué à la finance).
**Topics**
+ [Différence dans les proportions positives des étiquettes prédites (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ [Impact disparate (DI)](clarify-post-training-bias-metric-di.md)
+ [Différence d'acceptation conditionnelle (DCAcc)](clarify-post-training-bias-metric-dcacc.md)
+ [Différence dans les rejets conditionnels (DCR)](clarify-post-training-bias-metric-dcr.md)
+ [Différence de spécificité (SD)](clarify-post-training-bias-metric-sd.md)
+ [Différence de rappel (RD)](clarify-post-training-bias-metric-rd.md)
+ [Différence dans les taux d'acceptation (DAR)](clarify-post-training-bias-metric-dar.md)
+ [Différence dans les taux de rejets (DRR)](clarify-post-training-bias-metric-drr.md)
+ [Différence de précision (AD)](clarify-post-training-bias-metric-ad.md)
+ [Égalité de traitement (TE)](clarify-post-training-bias-metric-te.md)
+ [Disparité démographique conditionnelle dans les étiquettes prédites (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ [FlipTest contrefactuel (FT)](clarify-post-training-bias-metric-ft.md)
+ [Entropie généralisée (GE)](clarify-post-training-bias-metric-ge.md)
# Différence dans les proportions positives des étiquettes prédites (DPPL)
La métrique Différence de proportions positives dans les étiquettes prédites (DPPL) détermine si le modèle prédit les résultats différemment pour chaque facette. Elle est définie comme la différence entre la proportion de prédictions positives (y' = 1) pour la facette *a* et la proportion de prédictions positives (y' = 1) pour la facette *d*. Par exemple, si le modèle prédit l’octroi de prêts à 60 % d’un groupe d’âge moyen (facette *a*) et à 50 % d’autres groupes d’âge (facette *d*), le biais peut être dirigé vers la facette *d*. Dans cet exemple, vous devez déterminer si la différence de 10 % est significative pour un cas de biais.
Une comparaison de la différence dans les proportions d’étiquettes (DPL), une mesure du biais avant l’entraînement, avec le DPPL, une mesure du biais après l’entraînement, permet de déterminer si les biais dans les proportions positives initialement présentes dans le jeu de données changent après l’entraînement. Si le DPPL est supérieur au DPL, les biais dans des proportions positives augmentent après l’entraînement. Si le DPPL est inférieur au DPL, le modèle n’a pas augmenté les biais dans des proportions positives après l’entraînement. La comparaison entre le DPL et le DPPL ne garantit pas que le modèle réduira les biais dans toutes les dimensions. Par exemple, le modèle peut toujours être biaisé lorsqu’il prend en compte d’autres métriques telles que [FlipTest contrefactuel (FT)](clarify-post-training-bias-metric-ft.md) ou [Différence de précision (AD)](clarify-post-training-bias-metric-ad.md). Pour plus d'informations sur la détection des biais, consultez le billet de blog [Découvrez comment Amazon SageMaker Clarify aide à détecter les biais](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/). Consultez [Différence dans les proportions d'étiquettes (DPL)](clarify-data-bias-metric-true-label-imbalance.md) pour plus d’informations sur les DPL.
La formule de la valeur DPPL est la suivante :
DPPL = q’a - q’d
Où :
+ q’a = n’a(1)/na est la proportion prédite des membres de la facette *a* qui obtiennent un résultat positif de valeur 1. Dans notre exemple, la proportion d'une facette d'âge moyen à laquelle l'octroi d'un prêt est prédit. Ici, n'a(1) représente le nombre de membres de la facette *a* qui obtiennent un résultat positif prédit de valeur 1 et na est le nombre de membres de la facette *a*.
+ q’d = n’d(1)/nd est la proportion prédite des étiquettes de la facette *d* qui obtiennent un résultat positif de valeur 1. Dans notre exemple, une facette de personnes âgées et plus jeunes à laquelle l'octroi d'un prêt est prédit. Ici, n’d(1) représente le nombre de membres de la facette *d* qui obtiennent un résultat positif prédit et nd est le nombre de membres de la facette *d*.
Si la DPPL est suffisamment proche de 0, cela signifie que la *parité démographique* de post-entraînement est atteinte.
Pour les étiquettes de facettes binaires et multicatégorie, les valeurs de DPL normalisées s’échelonnent sur l’intervalle [-1, 1]. Pour les étiquettes continues, les valeurs varient sur l'intervalle (-∞, \$1∞).
+ Des valeurs DPPL positives indiquent qu'une proportion plus élevée de résultats positifs est prédite à la facette *a* par rapport à la facette *d*.
D'où l'expression *biais positif*.
+ Des valeurs de DPPL proches de zéro indiquent qu'une proportion plus égale de résultats positifs est prédite aux facettes *a* et *d*, tandis qu'une valeur de zéro indique une parfaite parité démographique.
+ Des valeurs DPPL négatives indiquent qu'une proportion plus élevée de résultats positifs est prédite à la facette *d* par rapport à la facette *a*. D'où l'expression *biais négatif*.
# Impact disparate (DI)
La métrique Différence de proportions positives dans les étiquettes prédites peut être évaluée sous la forme d’un rapport.
La métrique Comparaison de proportions positives dans les étiquettes prédites peut être évaluée sous la forme d’un rapport plutôt que d’une différence, comme c’est le cas avec la [Différence dans les proportions positives des étiquettes prédites (DPPL)](clarify-post-training-bias-metric-dppl.md). La métrique d'impact disparate (DI) est définie comme le rapport entre la proportion de prédictions positives (y' = 1) pour la facette *d* et la proportion de prédictions positives (y' = 1) pour la facette *a*. Par exemple, si le modèle prédit l'octroi de prêts à 60 % d'un groupe d'âge moyen (facette *a*) et à 50 % d'autres groupes d'âge (facette *d*), le DI = 0,5/0,6 = 0,8, ce qui indique un biais positif et un impact négatif sur l'autre groupe d'âge représenté par la facette *d*.
La formule pour le rapport entre les proportions des étiquettes prédites :
DI = q'd/q'a
Où :
+ q’a = n’a(1)/na est la proportion prédite des membres de la facette *a* qui obtiennent un résultat positif de valeur 1. Dans notre exemple, la proportion d'une facette d'âge moyen à laquelle l'octroi d'un prêt est prédit. Ici, n'a(1) représente le nombre de membres de la facette *a* qui obtiennent un résultat positif prédit et na est le nombre de membres de la facette *a*.
+ q’d = n’d(1)/nd est la proportion prédite des membres de la facette *d* qui obtiennent un résultat positif de valeur 1. Dans notre exemple, une facette de personnes âgées et plus jeunes à laquelle l'octroi d'un prêt est prédit. Ici, n'd(1) représente le nombre de membres de la facette *d* qui obtiennent un résultat positif prédit et nd est le nombre de membres de la facette *d*.
Pour les étiquettes de facettes binaires, multicatégorie et continues, les valeurs DI s'étendent sur l'intervalle [0, ∞).
+ Des valeurs inférieures à 1 indiquent qu'une proportion plus élevée de résultats positifs est prédite à la facette *a* par rapport à la facette *d*. D'où l'expression *biais positif*.
+ Une valeur égale à 1 indique la parité démographique.
+ Des valeurs supérieures à 1 indiquent qu'une proportion plus élevée de résultats positifs est prédite à la facette *d* par rapport à la facette *a*. D'où l'expression *biais négatif*.
# Différence d'acceptation conditionnelle (DCAcc)
Cette métrique compare les étiquettes observées aux étiquettes prédites par le modèle et évalue s’il en va de même entre les facettes pour les résultats positifs prédits. Cette métrique retype un peu le biais humain en ce sens qu’elle quantifie combien d’autres résultats positifs un modèle a prédits (étiquettes y’) pour une certaine facette par rapport à ce qui a été observé dans le jeu de données d’entraînement (étiquettes y). Par exemple, si l'on observe dans le jeu de données d'entraînement plus d'acceptations (un résultat positif) pour les demandes de prêt d'un groupe d'âge moyen (facette *a*) que prévu par le modèle basé sur les qualifications, par rapport à la facette contenant d'autres groupes d'âge (facette *d*), cela pourrait indiquer un biais potentiel dans la façon dont les prêts ont été approuvés en favorisant le groupe d'âge moyen.
La formule de calcul de la différence d’acceptation conditionnelle :
DCAcc = c a - c d
Où :
+ ca = na(1)/ n'a(1) est le rapport entre le nombre observé de résultats positifs de valeur 1 (acceptations) pour la facette *a* et le nombre prédit de résultats positifs (acceptations) pour la facette *a*.
+ cd = nd(1)/ n'd(1) est le rapport entre le nombre observé de résultats positifs de valeur 1 (acceptations) pour la facette *d* et le nombre prédit de résultats positifs (acceptations) pour la facette *d*.
La DCAcc métrique peut saisir les biais positifs et négatifs qui révèlent un traitement préférentiel basé sur les qualifications. Examinez, dans les cas suivants, l'incidence du biais basé sur l'âge, sur les acceptations de prêts.
**Exemple 1 : biais positif**
Supposons un jeu de données composé de 100 personnes d’âge moyen (facette *a*) et de 50 personnes d’autres groupes d’âge (facette *d*) qui ont demandé des prêts, le modèle recommandant l’octroi de prêts à 60 personnes de la facette *a* et 30 personnes de la facette *d*. Les proportions prédites ne sont donc pas biaisées par rapport à la métrique DPPL, mais les étiquettes observées montrent que des prêts ont été accordés à 70 personnes de la facette *a* et 20 personnes de la facette *d*. En d'autres termes, le modèle a accordé des prêts à 17 % de moins de personnes d'âge moyen que les étiquettes observées dans les données d'entraînement le suggéraient (70/60 = 1,17), et a accordé des prêts à 33 % de plus de personnes d'autres groupes d'âge que les étiquettes observées le suggéraient (20/30 = 0,67). Le calcul de la DCAcc valeur donne les résultats suivants :
DCAcc = 70/60 - 20/30 = 1/2
La valeur positive indique qu'il existe un biais potentiel contre la facette *a* d'âge moyen avec un taux d'acceptation plus faible comparé à l'autre facette *d*, par rapport à ce que les données observées (considérées comme non biaisées) indiquent.
**Exemple 2 : biais négatif**
Supposons un jeu de données composé de 100 personnes d’âge moyen (facette *a*) et de 50 personnes d’autres groupes d’âge (facette *d*) qui ont demandé des prêts, le modèle recommandant l’octroi de prêts à 60 personnes de la facette *a* et 30 personnes de la facette *d*. Les proportions prédites ne sont donc pas biaisées par rapport à la métrique DPPL, mais les étiquettes observées montrent que des prêts ont été accordés à 50 personnes de la facette *a* et 40 personnes de la facette *d*. En d’autres termes, le modèle a accordé des prêts à 17 % de moins de personnes d’âge moyen que les étiquettes observées dans les données d’entraînement le suggéraient (50/60 = 0,83), et a accordé des prêts à 33 % de plus de personnes d’autres groupes d’âge que les étiquettes observées le suggéraient (40/30 = 1,33). Le calcul de la DCAcc valeur donne les résultats suivants :
DCAcc = 50/60 - 40/30 = -1/2
La valeur négative indique qu'il existe un biais potentiel contre la facette *d* avec un taux d'acceptation plus faible comparé à la facette *a* d'âge moyen, par rapport à ce que les données observées (considérées comme non biaisées) indiquent.
Notez que vous pouvez l'utiliser DCAcc pour vous aider à détecter les biais potentiels (involontaires) causés par des humains supervisant les prédictions du modèle dans un environnement. human-in-the-loop Supposons, par exemple, que les prédictions y' du modèle ne soient pas biaisées, mais que la décision finale prise par un humain (ayant accès éventuellement à des fonctions supplémentaires) puisse modifier les prédictions du modèle pour générer une nouvelle version et une version finale de y'. Le traitement supplémentaire effectué par l'être humain peut involontairement refuser des prêts à un nombre disproportionné d'entre eux sous un angle. DCAccpeut aider à détecter de tels biais potentiels.
La plage de valeurs pour les différences d'acceptation conditionnelle des étiquettes binaires, multicatégorie et continues est (-∞, \$1∞).
+ Des valeurs positives se produisent lorsque le rapport entre le nombre observé d’acceptations par rapport aux acceptations prédites pour la facette *a* est supérieur au même rapport pour la facette *d*. Des valeurs négatives indiquent un biais possible envers les candidats qualifiés de la facette *a*. Le biais apparent est d’autant plus extrême que la différence des rapports est importante.
+ Des valeurs proches de zéro se produisent lorsque le rapport entre le nombre observé d'acceptations par rapport aux acceptations prédites pour la facette *a* est identique au rapport pour la facette *d*. Ces valeurs indiquent que les taux d'acceptation prédits sont conformes aux valeurs observées dans les données étiquetées et que les candidats qualifiés des deux facettes sont acceptés de la même manière.
+ Des valeurs négatives se produisent lorsque le rapport entre le nombre observé d’acceptations par rapport aux acceptations prédites pour la facette *a* est inférieur à ce rapport pour la facette *d*. Des valeurs négatives indiquent un biais possible envers les candidats qualifiés de la facette *d*. Le biais apparent est d’autant plus extrême que la différence des rapports est négative.
# Différence dans les rejets conditionnels (DCR)
Cette métrique compare les étiquettes observées aux étiquettes prédites par le modèle et évalue s’il en va de même entre les facettes pour les résultats négatifs (rejets). Cette métrique retype un peu le biais humain en ce sens qu’elle quantifie combien d’autres résultats négatifs un modèle a prédits (étiquettes prédites y’) pour une certaine facette par rapport à ce qui a été suggéré par les étiquettes dans le jeu de données d’entraînement (étiquettes observées y). Par exemple, si les rejets observés (un résultat négatif) pour les demandes de prêt d'un groupe d'âge moyen (facette *a*) étaient plus nombreux que ceux prédits par le modèle basé sur les qualifications, par rapport à la facette contenant d'autres groupes d'âge (facette *d*), cela pourrait indiquer un biais potentiel dans la façon dont les prêts ont été rejetés. Ce biais favoriserait le groupe d'âge moyen par rapport aux autres groupes.
La formule de calcul de la différence d’acceptation conditionnelle :
DCR = rd- ra
Où :
+ rd = nd(0)/ n'd(0) est le rapport entre le nombre observé de résultats négatifs de valeur 0 (rejets) de la facette *d* et le nombre prédit de résultats négatifs (rejets) pour la facette *d*.
+ ra = na(0)/ n’a(0) est le rapport entre le nombre observé de résultats négatifs de valeur 0 (rejets) de la facette *a* et le nombre prédit de résultats négatifs de valeur 0 (rejets) pour la facette *a*.
La métrique DCR peut saisir les biais positif et négatif révélant un traitement préférentiel basé sur les qualifications. Examinez, dans les cas suivants, l'incidence du biais sur les rejets de prêts en fonction de l'âge.
**Exemple 1 : biais positif**
Supposons un jeu de données composé de 100 personnes d’âge moyen (facette *a*) et de 50 personnes d’autres groupes d’âge (facette *d*) qui ont demandé des prêts, le modèle recommandant le rejet de prêts à 60 personnes de la facette *a* et à 30 personnes de la facette *d*. Les proportions prédites ne sont donc pas biaisées par rapport à la métrique DPPL, mais les étiquettes observées montrent que des prêts ont été refusés à 50 personnes de la facette *a* et à 40 personnes de la facette *d*. En d'autres termes, le modèle a rejeté 17 % de prêts de plus pour la facette d'âge moyen que ce que les étiquettes observées dans les données d'entraînement suggéraient (50/60 = 0,83). Il a aussi rejeté 33 % de prêts de moins pour les autres groupes d'âge que ce que les étiquettes observées suggéraient (40/30 = 1,33). La valeur DCR quantifie cette différence dans le rapport entre les taux de rejet observés et prédits entre les facettes. La valeur positive indique qu'il existe un biais potentiel favorisant le groupe d'âge moyen avec des taux de rejet plus faibles par rapport aux autres groupes que les données observées (considérées comme non biaisées) ne l'indiquent.
DCR = 40/30 - 50/60 = 1/2
**Exemple 2 : biais négatif**
Supposons un jeu de données composé de 100 personnes d’âge moyen (facette *a*) et de 50 personnes d’autres groupes d’âge (facette *d*) qui ont demandé des prêts, le modèle recommandant le rejet de prêts à 60 personnes de la facette *a* et à 30 personnes de la facette *d*. Les proportions prédites ne sont donc pas biaisées par rapport à la métrique DPPL, mais les étiquettes observées montrent que des prêts ont été refusés à 70 personnes de la facette *a* et à 20 personnes de la facette *d*. En d'autres termes, le modèle a rejeté 17 % de prêts de moins pour la facette des personnes d'âge moyen que ce que les étiquettes observées dans les données d'entraînement suggéraient (70/60 = 1,17). Il a également rejeté 33 % de prêts de plus pour les autres groupes d'âge que ce que les étiquettes observées suggéraient (20/30 = 0,67). La valeur négative indique qu'il existe un biais potentiel favorisant la facette *a* avec des taux de rejet plus faibles comparé à la facette *a* d'âge moyen, par rapport à ce que les données observées (considérées comme non biaisées) indiquent.
DCR = 20/30 - 70/60 = -1/2
La plage de valeurs pour les différences de rejet conditionnel des étiquettes binaires, multicatégorie et continues est (-∞, \$1∞).
+ Des valeurs positives se produisent lorsque le rapport entre le nombre observé de rejets et les rejets prédits pour la facette *d* est supérieur au même rapport pour la facette *a*. Des valeurs négatives indiquent un biais possible envers les candidats qualifiés de la facette *a*. Le biais apparent est d’autant plus extrême que la valeur de la métrique DCR est élevée.
+ Des valeurs proches de zéro se produisent lorsque le rapport entre le nombre observé de rejets et les acceptations prédites pour la facette *a* est similaire au rapport pour la facette *d*. Ces valeurs indiquent que les taux de rejets prédits sont conformes aux valeurs observées dans les données étiquetées et que les rejets s'appliquent de la même manière aux candidats qualifiés des deux facettes.
+ Des valeurs négatives se produisent lorsque le rapport entre le nombre observé de rejets et les rejets prédits pour la facette *d* est inférieur au rapport pour la facette *a*. Des valeurs négatives indiquent un biais possible envers les candidats qualifiés de la facette *d*. Le biais apparent est d’autant plus extrême que la métrique DCR est négative.
# Différence de spécificité (SD)
La différence de spécificité (SD) est la différence de spécificité entre la facette favorisée *a* et la facette défavorisée *d*. La spécificité mesure la fréquence à laquelle le modèle prédit correctement un résultat négatif (y'=0). La moindre différence dans ces spécificités est une forme potentielle de biais.
La spécificité est parfaite pour une facette si tous les cas où y=0 sont correctement prédits pour cette facette. La spécificité est plus élevée lorsque le modèle minimise les faux positifs, ce qui correspond à une erreur de type I. Par exemple, la différence entre une faible spécificité pour l'octroi de prêts aux membres de la facette *a* et une forte spécificité pour l'octroi de prêts aux membres de la facette *d*, est une mesure du biais contre la facette *d*.
La formule suivante permet de calculer la différence de spécificité pour les facettes *a* et *d*.
SD = TNd/(TNd \$1 FPd) - TNa/(TNa \$1 FPa) = TNRd - TNRa
Les variables suivantes utilisées pour calculer SD sont définies comme suit :
+ TNd sont les vrais négatifs prédits pour la facette*D*.
+ FPd sont les faux positifs prédits pour la facette *d*.
+ TNd correspond aux faux négatifs prédits pour la facette *a*.
+ FPd sont les faux positifs prédits pour la facette *a*.
+ TNRa = TNa/(TNa \$1 FPa) est le taux de vrais négatifs, également connu sous le nom de spécificité, pour la facette *a*.
+ TNRd = TNd/(TNd \$1 FPd) est le taux de vrais négatifs, également connu sous le nom de spécificité, pour la facette *d*.
Considérons, par exemple, les matrices de confusion suivantes pour les facettes *a* et *d*.
Matrice de confusion pour la facette favorisée `a`
| Prédictions de Classe a | Résultat réel 0 | Résultat réel 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
Matrice de confusion pour la facette défavorisée `d`
| Prédictions de Classe d | Résultat réel 0 | Résultat réel 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
La valeur de la différence de spécificité est `SD = 18/(18+5) - 20/(20+10) = 0.7826 - 0.6667 = 0.1159`, ce qui indique un biais contre la facette *d*.
La plage de valeurs pour la différence de spécificité entre les facettes *a* et *d* pour la classification binaire et multicatégorie est `[-1, +1]`. Cette métrique n’est pas disponible dans le cas d’étiquettes continues. Voici ce que les différentes valeurs de SD impliquent :
+ Des valeurs positives sont obtenues quand la spécificité est plus élevée pour la facette *d* que pour la facette *a*. Cela suggère que le modèle trouve moins de faux positifs pour la facette *d* que pour la facette *a*. Une valeur positive indique un biais contre la facette *d*.
+ Des valeurs proches de zéro indiquent que la spécificité pour les facettes comparées est similaire. Cela suggère que le modèle trouve un nombre similaire de faux positifs dans les deux facettes et qu'il n'est pas biaisé.
+ Des valeurs négatives sont obtenues quand la spécificité est plus élevée pour la facette *a* que pour la facette *d*. Cela suggère que le modèle trouve plus de faux positifs pour la facette *a* que pour la facette *d*. Une valeur négative indique un biais contre la facette *a*.
# Différence de rappel (RD)
La métrique de différence de rappel (RD) est la différence de rappel du modèle entre la facette favorisée *a* et la facette défavorisée *d*. La moindre différence dans ces rappels est une forme potentielle de biais. Le rappel est le taux de vrais positifs (TPR) qui mesure la fréquence à laquelle le modèle prédit correctement les cas qui devraient recevoir un résultat positif. Le rappel est parfait pour une facette si tous les cas y=1 sont correctement prédits comme y'=1 pour cette facette. Le rappel est plus important lorsque le modèle diminue les faux négatifs connus sous le nom d'erreur de type II. Par exemple, combien de personnes dans deux groupes différents (facettes *a* et *d*), qui devraient être admissibles aux prêts, sont correctement détectées par le modèle ? Si le taux de rappel est élevé pour l'octroi de prêts aux membres de la facette *a*, mais faible pour les membres de la facette *d*, la différence fournit une mesure de ce biais par rapport au groupe appartenant à la facette *d*.
La formule de calcul de la différence des taux de rappel pour les facettes *a* et *d* :
RD = TPa/(TPa \$1 FNa) - TPd/(TPd \$1 FNd) = TPRa - TPRd
Où :
+ TPa sont les vrais positifs prédits pour la facette *a*.
+ FNa sont les faux négatifs prédits pour la facette *a*.
+ TPd sont les vrais positifs prédits pour la facette *d*.
+ FNd sont les faux négatifs prédits pour la facette *d*.
+ TPRa = TPa/(TPa \$1 FNa) est le rappel pour la facette *a* ou son taux de vrais positifs.
+ TPRd = TPd/(TPd \$1 FNd) est le rappel pour la facette *d* ou son taux de vrais positifs.
Considérons, par exemple, les matrices de confusion suivantes pour les facettes *a* et *d*.
Matrice de confusion pour la facette favorisée a
| Prédictions de Classe a | Résultat réel 0 | Résultat réel 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
Matrice de confusion pour la facette défavorisée d
| Prédictions de Classe d | Résultat réel 0 | Résultat réel 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
La valeur de la différence de rappel est RD = 65/70 - 20/27 = 0,93 - 0,74 = 0,19, soit un biais envers la facette *d*.
La plage de valeurs pour la différence de rappel entre les facettes *a* et *d* pour la classification binaire et multicatégorie est [-1, \$11]. Cette métrique n'est pas disponible dans le cas d'étiquettes continues.
+ Des valeurs positives sont obtenues lorsqu'un rappel est plus élevé pour la facette *a* que pour la facette *d*. Cela suggère que le modèle trouve plus des vrais positifs pour la facette *a* que pour la facette *d*, ce qui est une forme de biais.
+ Des valeurs proches de zéro indiquent que le rappel comparé des facettes est similaire. Cela suggère que le modèle trouve à peu près le même nombre de vrais positifs dans les deux facettes et qu'il n'est pas biaisé.
+ Des valeurs négatives sont obtenues lorsqu'un rappel est plus élevé pour la facette *d* que pour la facette *a*. Cela suggère que le modèle trouve plus des vrais positifs pour la facette *d* que pour la facette *a*, ce qui est une forme de biais.
# Différence dans les taux d'acceptation (DAR)
La métrique de la différence des taux d’acceptation (DAR) est la différence des rapports entre les prédictions de vrais positifs (TP) et les positifs observés (TP \$1 FP) pour les facettes *a* et *d*. Cette métrique mesure la différence de précision du modèle pour prédire les acceptations à partir de ces deux facettes. La précision mesure la fraction de candidats qualifiés du groupe de candidats qualifiés, identifiés comme tels par le modèle. Si la précision du modèle pour prédire les candidats qualifiés diverge entre les facettes, il s'agit là d'un biais et son ampleur est mesurée par le DAR.
La formule de calcul de la différence de taux d'acceptation entre les facettes *a* et *d* :
DAR = TPa/(TPa \$1 FPa) - TPd/(TPd \$1 FPd)
Où :
+ TPa sont les vrais positifs prédits pour la facette *a*.
+ FPa sont les faux positifs prédits pour la facette *a*.
+ TPd sont les vrais positifs prédits pour la facette *d*.
+ FPd sont les faux positifs prédits pour la facette *d*.
Par exemple, supposons que le modèle accepte d'accorder un prêt à 70 candidats d'âge moyen (facette *a*) (étiquettes positives prédites), dont seulement 35 sont effectivement acceptés (étiquettes positives observées). Supposons également que le modèle accepte d'accorder un prêt à 100 candidats d'autres groupes d'âge (facette *d*) (étiquettes positives prédites), dont seulement 40 sont effectivement acceptés (étiquettes positives observées). Comme la DAR = 35/70 - 40/100 = 0,10, cela indique un biais potentiel envers les personnes qualifiées du second groupe d'âge (facette *d*).
La plage de valeurs du DAR pour les étiquettes binaires, multicatégorie et continues est [-1, \$11].
+ Des valeurs positives se produisent lorsque le rapport entre les positifs prédits (acceptations) et les résultats positifs observés (candidats qualifiés) pour la facette *a* est supérieur au même rapport pour la facette *d*. Ces valeurs indiquent un biais possible envers la facette défavorisée *d* dû à la présence d'un nombre relativement supérieur de faux positifs dans la facette *d*. Le biais apparent est d'autant plus extrême que la différence des rapports est importante.
+ Des valeurs proches de zéro se produisent lorsque le rapport entre les positifs prédits (acceptations) et les résultats positifs observés (candidats qualifiés) pour les facettes *a* et *d* est similaire, ce qui indique que le modèle prédit avec la même précision des étiquettes observées pour les résultats positifs.
+ Des valeurs négatives se produisent lorsque le rapport entre les positifs prédits (acceptations) et les résultats positifs observés (candidats qualifiés) pour la facette *d* est supérieur à celui de la facette *a*. Ces valeurs indiquent un biais possible envers la facette favorisée *a* dû à la présence d'un nombre relativement supérieur de faux positifs dans la facette *a*. Le biais apparent est d'autant plus extrême que la différence des rapports est négative.
# Différence dans les taux de rejets (DRR)
La métrique de la différence dans les taux de rejets (DRR) est la différence dans les rapports entre les prédictions de vrais négatifs (TN) et les négatifs observés (TN \$1 FN) pour les facettes *a* et *d*. Cette métrique mesure la différence de précision du modèle pour prédire les rejets à partir de ces deux facettes. La précision mesure la fraction de candidats non qualifiés du groupe de candidats non qualifiés, identifiés comme tels par le modèle. Si la précision du modèle pour prédire les candidats non qualifiés diverge entre les facettes, il s'agit là d'un biais et son ampleur est mesurée par la DRR.
La formule de calcul de la différence de taux de rejets entre les facettes *a* et *d* :
DRR = TNd/(TNd \$1 FNd) - TNa/(TNa \$1 FNa)
Les composantes de l'équation DRR précédente sont les suivantes.
+ TNd sont les vrais négatifs prédits pour la facette*D*.
+ FNd sont les faux négatifs prédits pour la facette *d*.
+ TPa sont les vrais négatifs prédits pour la facette*a*.
+ FNa sont les faux négatifs prédits pour la facette *a*.
Par exemple, supposons que le modèle refuse d’accorder un prêt à 100 candidats d’âge moyen (facette *a*) (étiquettes négatives prédites), dont 80 ne sont pas qualifiés (étiquettes négatives observées). Supposons également que le modèle refuse d'accorder un prêt à 50 candidats d'autres groupes d'âge (facette *d*) (étiquettes positives prédites), dont seulement 40 ne sont pas qualifiés (étiquettes positives observées). Comme la DRR = 40/50 - 80/100 = 0, aucun biais n’est donc indiqué.
La plage de valeurs pour la DRR d'étiquettes binaires, multicatégorie et continues est [-1, \$11].
+ Des valeurs positives se produisent lorsque le rapport entre les négatifs prédits (rejets) et les résultats négatifs observés (candidats non qualifiés) pour la facette *d* est supérieur au même rapport pour la facette *a*. Ces valeurs indiquent un biais possible envers la facette favorisée *a* dû à la présence d'un nombre relativement supérieur de faux négatifs dans la facette *a*. Le biais apparent est d'autant plus extrême que la différence des rapports est importante.
+ Des valeurs proches de zéro se produisent lorsque le rapport entre les négatifs prédits (rejets) et les résultats négatifs observés (candidats non qualifiés) pour les facettes *a* et *d* a des valeurs similaires, ce qui indique que le modèle prédit avec la même précision des étiquettes observées pour les résultats négatifs.
+ Des valeurs négatives se produisent lorsque le rapport entre les négatifs prédits (rejets) et les résultats négatifs observés (candidats non qualifiés) pour la facette *a* est supérieur au rapport de la facette *d*. Ces valeurs indiquent un biais possible envers la facette défavorisée *d* dû à la présence d'un nombre relativement supérieur de faux positifs dans la facette *d*. Le biais apparent est d'autant plus extrême que la différence des rapports est négative.
# Différence de précision (AD)
La métrique de différence de précision (AD) est la différence de précision de prédiction entre différentes facettes. Cette métrique détermine si la classification par le modèle est plus précise pour une facette que pour l'autre. L'AD indique si une facette enregistre une plus grande proportion d'erreurs de type I et de type II. Elle ne peut cependant pas faire la différence entre les erreurs de type I et de type II. Par exemple, la précision du modèle peut être égale pour différents groupes d'âge, mais les erreurs peuvent être principalement des faux positifs (erreurs de type I) pour l'un des groupes et principalement des faux négatifs (erreurs de type II) pour l'autre.
En outre, si la précision d'approbation de prêt est nettement plus élevée pour une population d'âge moyen (facette *a*) que pour un autre groupe d'âge (facette *d*), alors, soit une proportion supérieure de demandeurs qualifiés du second groupe se voit refuser un prêt (FN), soit une proportion supérieure de demandeurs non qualifiés de ce groupe obtient un prêt (FP), ou les deux. Cela peut conduire à une injustice envers le second groupe, même si la proportion de prêts accordés est sensiblement identique pour les deux groupes d'âge, comme l'indique une valeur de DPPL proche de zéro.
La formule pour la métrique AD est la différence entre la précision de prédiction pour la facette *a*, ACCa, moins celle de la facette *d*, ACCd :
AD = ACCa - ACCd
Où :
+ ACCa= (TPa \$1 TNa)/(TPa \$1 TNa\$1 FPa \$1 FNa)
+ TPa sont les vrais positifs prédits pour la facette *a*
+ TNa sont les faux négatifs prédits pour la facette *a*.
+ FPa sont les faux positifs prédits pour la facette *a*.
+ FNa sont les faux négatifs prédits pour la facette *a*.
+ ACCd= (TPd \$1 TNd)/(TPd \$1 TNd\$1 FPd \$1 FNd)
+ TPd sont les vrais positifs prédits pour la facette *d*.
+ TNd sont les vrais négatifs prédits pour la facette *d*
+ FPd sont les faux positifs prédits pour la facette *d*
+ FNd sont les faux négatifs prédits pour la facette *d*
Par exemple, supposons qu'un modèle accorde des prêts à 70 demandeurs d'une facette *a* qui en compte 100, et rejette les 30 autres. 10 n'auraient pas dû recevoir le prêt (FPa) et 60 ont été approuvés comme cela était prévu (TPa). Sur la totalité des rejets, 20 auraient dû être approuvés (FNa), tandis que 10 ont été correctement rejetés (TNa). La précision pour la facette *a* est la suivante :
ACCa = (60 \$1 10)/(60 \$1 10 \$1 20 \$1 10) = 0,7
Ensuite, supposons qu'un modèle accorde des prêts à 50 demandeurs d'une facette *d* qui en compte 100, et rejette les 50 autres. 10 n'auraient pas dû recevoir le prêt (FPa) et 40 ont été approuvés comme cela était prévu (TPa). Sur la totalité des rejets, 40 auraient dû être approuvés (FNa), tandis que 10 ont été correctement rejetés (TNa). La précision pour la facette *a* est déterminée comme suit :
ACCd = (40 \$1 10)/(40 \$1 10 \$1 40 \$1 10) = 0,5
La différence de précision est donc AD = ACCa - ACCd = 0,7 - 0,5 = 0,2. Comme la métrique est positive, cela indique un biais envers la facette *d*.
La plage de valeurs d'AD pour les étiquettes de facettes binaires et multicatégorie est [-1, \$11].
+ Des valeurs positives se produisent lorsque la précision de prédiction pour la facette *a* est supérieure à celle pour la facette *d*. Cela signifie que la facette *d* pâtit davantage d'une combinaison de faux positifs (erreurs de type I) ou de faux négatifs (erreurs de type II). Cela indique donc un biais potentiel envers la facette défavorisée *d*.
+ Des valeurs proches de zéro se produisent lorsque la précision de la prédiction pour la facette *a* est similaire à celle pour la facette *d*.
+ Des valeurs négatives se produisent lorsque la précision de prédiction pour la facette *d* est supérieure à celle pour la facette *a*. Cela signifie que la facette *a* pâtit davantage d'une combinaison de faux positifs (erreurs de type I) ou de faux négatifs (erreurs de type II). Cela indique donc un biais potentiel envers la facette favorisée *a*.
# Égalité de traitement (TE)
L’égalité de traitement (TE) est la différence dans le rapport entre les faux négatifs et les faux positifs entre les facettes *a* et *d*. Cette métrique a pour objectif principal d’évaluer si, avec une précision identique entre les groupes, les erreurs sont plus préjudiciables à un groupe qu’à un autre. Le taux d'erreur provient du total des faux positifs et des faux négatifs, mais leur répartition peut varier très fortement d'une facette à l'autre. Le TE mesure si les erreurs se compensent de façon similaire ou différente selon les facettes.
La formule de calcul de l’égalité de traitement :
TE = FNd/FPd - FNa/FPa
Où :
+ FNd sont les faux négatifs prédits pour la facette *d*.
+ FPd sont les faux positifs prédits pour la facette *d*.
+ FNa sont les faux négatifs prédits pour la facette *a*.
+ FPa sont les faux positifs prédits pour la facette *a*.
Vous noterez que la métrique devient sans limite si la valeur FPa ou FPd est égale à zéro.
Par exemple, supposons qu’il y ait 100 demandeurs de prêt de la facette *a* et 50 de la facette *d*. Dans la facette *a*, 8 se sont vu refuser un prêt à tort (FNa) et 6 autres se sont vu accorder un prêt à tort (FPa). Les prédictions restantes étaient vraies, donc TPa \$1 TNa = 86. Dans la facette *d*, 5 se sont vu refuser un prêt à tort (FNd) et 2 se sont vu accorder un prêt à tort (FPd). Les prédictions restantes étaient vraies, donc TPd \$1 TNd = 43. Le rapport entre faux négatifs et faux positifs est égal à 8/6 = 1,33 pour la facette *a* et 5/2 = 2,5 pour la facette *d*. Donc, TE = 2,5 - 1,33 = 1,167, même avec une précision identique pour les deux facettes :
ACCa = (86)/(86\$1 8 \$1 6) = 0,86
ACCd = (43)/(43 \$1 5 \$1 2) = 0,86
La plage de valeurs des différences de rejet conditionnel pour les étiquettes de facettes binaires et multicatégorie est (-∞, \$1∞). La métrique TE n'est pas définie pour les étiquettes continues. L’interprétation de cette métrique dépend de l’importance relative des faux positifs (erreur de type I) et des faux négatifs (erreur de type II).
+ Des valeurs positives se produisent lorsque le rapport entre faux négatifs et faux positifs pour la facette *d* est supérieur à celui de la facette *a*.
+ Des valeurs proches de zéro se produisent lorsque le rapport entre faux négatifs et faux positifs pour la facette *a* est semblable à celui de la facette *d*.
+ Des valeurs négatives se produisent lorsque le rapport entre faux négatifs et faux positifs pour la facette *d* est inférieur à celui de la facette *a*.
**Note**
Une version précédente indiquait que la métrique d'égalité de traitement était calculée comme FPa / FNa - FPd / FNd au lieu de FNd / FPd - FNa / FPa. Bien que l'une ou l'autre des versions puisse être utilisée. Pour de plus amples informations, veuillez consulter [https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
# Disparité démographique conditionnelle dans les étiquettes prédites (CDDPL)
La métrique de disparité démographique (DDPL) détermine si, pour la facette *d*, la proportion d’étiquettes rejetées prédites est supérieure à celle d’étiquettes acceptées prédites. Elle permet de comparer la différence entre la proportion de rejets prédite et la proportion d’acceptations prédite selon les facettes. Cette métrique est exactement la même que la métrique CDD de pré-entraînement, si ce n'est qu'elle est calculée à partir des étiquettes prédites et non des étiquettes observées. Cette métrique se situe dans la plage (-1, \$11).
La formule de calcul des prédictions de disparité démographique pour les étiquettes de la facette *d* est la suivante :
DDPLd = n'd(0)/n'(0) - n'd(1)/n'(1) = PdR(y'0) - PdA(y'1)
Où :
+ n'(0) = n'a(0) \$1 n'd(0) est le nombre d'étiquettes rejetées prédites pour les facettes *a* et *d*.
+ n'(1) = n'a(1) \$1 n'd(1) est le nombre d'étiquettes acceptées prédites pour les facettes *a* et *d*.
+ PdR(y'0) est la proportion d'étiquettes rejetées prédites (valeur 0) dans la facette *d*.
+ PdA(y'1) est la proportion d'étiquettes acceptées prédites (valeur 1) dans la facette *d*.
Une métrique de disparité démographique conditionnelle dans les étiquettes prédites (CDGPL) qui conditionne une DDPL sur des attributs définissant une strate de sous-groupes dans le jeu de données est nécessaire pour exclure le paradoxe de Simpson. Le regroupement peut donner des informations sur la cause des disparités démographiques apparentes pour les facettes moins favorisées. Le cas classique s'est produit lors des admissions à Berkeley où les hommes étaient globalement acceptés à un taux plus élevé que les femmes. Cependant, à l'examen des sous-groupes départementaux, les taux d'admission des femmes étaient supérieurs à ceux des hommes. Cela venait du fait que les femmes avaient déposé une demande dans des départements où les taux d'acceptation étaient inférieurs à ceux des hommes. L'examen des taux d'acceptation des sous-groupes a révélé que les femmes étaient effectivement acceptées à un taux plus élevé que les hommes dans les départements où les taux d'acceptation étaient inférieurs.
La métrique CDGPL fournit une mesure unique pour toutes les disparités trouvées dans les sous-groupes définis par un attribut d'un jeu de données en en faisant la moyenne. Elle est définie comme la moyenne pondérée des disparités démographiques dans les étiquettes prédites (DDPLi) pour chacun des sous-groupes, la disparité de chaque sous-groupe étant pondérée proportionnellement au nombre d'observations qu'il contient. La formule de calcul de la disparité démographique conditionnelle dans les étiquettes prédites est la suivante :
CDDPL = (1/n)\$1∑ini \$1DDPLi
Où :
+ ∑ini = n est le nombre total d'observations et ni est le nombre d'observations pour chaque sous-groupe.
+ DDPLi = n’i(0)/n(0) - n’i(1)/n(1) = PiR(y’0) - PiA(y’1) est la disparité démographique des étiquettes prédites pour le sous-groupe.
Ainsi, la disparité démographique pour un sous-groupe dans les étiquettes prédites (DDPLi) correspond à la différence entre la proportion d'étiquettes rejetées prédites et la proportion d'étiquettes acceptées prédites pour chaque sous-groupe.
La plage de valeurs CDGPL pour les résultats binaires, multicatégorie et continus est [-1, \$11].
+ \$11 : lorsqu'il n'y a aucune étiquette de rejet prédite pour la facette *a* ou le sous-groupe, et aucune acceptation prédite pour la facette *d* ou le sous-groupe.
+ Des valeurs positives indiquent une disparité démographique dans les étiquettes prédites du fait que la proportion d'étiquettes rejetées prédites pour la facette *d* ou le sous-groupe est supérieure à celle d'étiquettes acceptées prédites. La disparité est d'autant plus importante que la valeur est élevée.
+ Des valeurs proches de zéro indiquent qu'il n'y a pas de disparité démographique en moyenne.
+ Des valeurs négatives indiquent une disparité démographique dans les étiquettes prédites du fait que la proportion d'étiquettes rejetées prédites pour la facette *a* ou le sous-groupe est supérieure à celle d'étiquettes acceptées prédites. La disparité est d'autant plus importante que la valeur est faible.
+ -1 : lorsqu'il n'y a aucune étiquette de rejet prédite pour la facette *d* ou le sous-groupe, et aucune acceptation prédite pour la facette *d* ou le sous-groupe.
# FlipTest contrefactuel (FT)
Le FlipTest est une approche qui examine chaque membre de la facette *d* et évalue si des prédictions de modèle sont différentes pour des membres similaires de la facette *a*. Les membres de la facette *a* sont choisis pour être les voisins les plus proches de l'observation de la facette *d*. Nous évaluons combien de voisins les plus proches du groupe opposé reçoivent une prédiction différente, la prédiction pouvant passer du positif au négatif et vice versa.
La formule de calcul du FlipTest contrefactuel est la différence dans la cardinalité de deux ensembles divisée par le nombre de membres de la facette *d* :
FT = (F\$1 - F-)/nd
Où :
+ F\$1 = est le nombre de membres de la facette défavorisée *d* avec un résultat défavorable, dont les voisins les plus proches dans la facette favorisée *a* ont reçu un résultat favorable.
+ F- = est le nombre de membres de la facette défavorisée *d* avec un résultat favorable, dont les voisins les plus proches dans la facette favorisée *a* ont reçu un résultat défavorable.
+ nd est la taille de l'échantillon de la facette *d*.
La plage de valeurs du FlipTest contrefactuel pour les étiquettes de facettes binaires et multicatégorie est [-1, \$11]. Pour les étiquettes continues, un seuil est défini afin de réduire les étiquettes en binaire.
+ Des valeurs positives se produisent lorsque le nombre de décisions de FlipTest contrefactuel défavorables pour la facette défavorisée *d* est supérieur à celui de la facette favorisée.
+ Des valeurs proches de zéro se produisent lorsque le nombre de décisions de FlipTest contrefactuel défavorables et favorables s'équilibrent.
+ Des valeurs négatives se produisent lorsque le nombre de décisions de FlipTest contrefactuel défavorables pour la facette défavorisée *d* est inférieur à celui de la facette favorisée.
# Entropie généralisée (GE)
L'indice d'entropie généralisée (GE) mesure l'inégalité du bénéfice `b` pour l'étiquette prédite par rapport à l'étiquette observée. Un bénéfice survient lorsqu'un faux positif est prédit. Un faux positif survient quand une observation négative (y=0) a une prédiction positive (y'=1). Un bénéfice survient également lorsque les étiquettes observées et prédites sont les mêmes, à savoir pour un vrai positif et pour un vrai négatif. Aucun bénéfice n'apparaît quand un faux négatif est prédit. Un faux négatif survient dans le cas d'une observation positive (y=1) alors qu'un résultat négatif (y'=0) est prédit. Le bénéfice `b` est défini comme suit.
```
b = y' - y + 1
```
Selon cette définition, un faux positif reçoit un bénéfice `b` de `2`, et un faux négatif reçoit un bénéfice de `0`. Un vrai positif et un vrai négatif reçoivent tous les deux un bénéfice de `1`.
La métrique GE est calculée comme l'[indice d'entropie généralisée](https://en.wikipedia.org/wiki/Generalized_entropy_index) (GE) avec le poids `alpha` défini sur `2`. Ce poids contrôle la sensibilité à différentes valeurs de bénéfice. Une plus petite valeur `alpha` signifie une sensibilité accrue à des valeurs plus faibles.
![\[Équation définissant l'indice d'entropie généralisée avec le paramètre alpha défini sur 2.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify-post-training-bias-metric-ge.png)
Les variables suivantes utilisées pour calculer GE sont définies comme suit :
+ bi est le bénéfice reçu par le point de données `ith`.
+ b' est la moyenne de tous les bénéfices.
GE peut aller de 0 à 0,5, la valeur zéro indiquant l'absence d'inégalité entre les bénéfices de tous les points de données. Cela se produit quand toutes les entrées sont correctement prédites ou quand toutes les prédictions sont des faux positifs. La valeur GE n'est pas définie quand toutes les prédictions sont des faux négatifs.
**Note**
La métrique GE ne dépend pas du fait qu’une valeur de facette soit favorisée ou défavorisée.
# Explicabilité du modèle
Amazon SageMaker Clarify fournit des outils permettant d'expliquer comment les modèles d'apprentissage automatique (ML) établissent des prédictions. Ces outils peuvent aider les modélisateurs et développeurs ML, ainsi que d’autres parties prenantes internes, à comprendre globalement les caractéristiques du modèle avant le déploiement et à déboguer les prédictions fournies par un modèle après son déploiement.
+ Pour obtenir des explications pour vos jeux de données et modèles, consultez [Équité, explicabilité du modèle et détection des biais avec Clarify SageMaker](clarify-configure-processing-jobs.md).
+ Pour obtenir des explications en temps réel à partir d'un point de terminaison d' SageMaker intelligence artificielle, voir[Explicabilité en ligne avec Clarify SageMaker](clarify-online-explainability.md).
La transparence quant à la façon dont les modèles de ML formulent leurs prédictions est également essentielle pour les consommateurs et les régulateurs. Ils doivent se fier aux prédictions du modèle s'ils veulent accepter les décisions qui en découlent. SageMaker Clarify utilise une approche d'attribution de fonctionnalités indépendante du modèle. Vous pouvez l'utiliser pour comprendre pourquoi un modèle a formulé une prédiction après l'entraînement, et pour fournir une explication par instance pendant l'inférence. L'approche comprend une mise en œuvre évolutive et efficace de [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf). Elle se base sur le concept d’une valeur de Shapley, issue du domaine de la théorie des jeux coopératifs, qui affecte à chaque caractéristique une valeur d’importance pour une prédiction particulière.
Clarify produit des diagrammes de dépendance partielle (PDPs) qui montrent l'effet marginal des caractéristiques sur le résultat prévu d'un modèle d'apprentissage automatique. La dépendance partielle permet d'expliquer la réponse cible en fonction d'un ensemble de fonctions d'entrée. Elle prend également en charge l’explicabilité de la vision par ordinateur et du traitement du langage naturel (NLP) à l’aide du même algorithme de valeurs Shapley (SHAP) que celui utilisé pour les explications de données tabulaires.
Quelle est la fonction d’une explication dans le contexte du machine learning ? Une explication peut être considérée comme la réponse à une *question Pourquoi ?*, qui aide les humains à comprendre la cause d'une prédiction. Dans le contexte d’un modèle ML, vous pouvez vouloir répondre à des questions telles que :
+ Pourquoi le modèle a-t-il prédit un résultat négatif, comme un refus de prêt pour un demandeur donné ?
+ Comment le modèle fait-il des prédictions ?
+ Pourquoi le modèle a-t-il fait une prédiction incorrecte ?
+ Quelles fonctions influent le plus sur le comportement du modèle ?
Vous pouvez utiliser des explications pour l’audit et le respect des exigences réglementaires, renforcer la confiance dans le modèle et prendre en charge la prise de décisions humaines, ainsi que pour le débogage et l’amélioration des performances du modèle.
Le genre d'explication requis repose sur la nécessité de satisfaire les exigences de compréhension humaine de la nature et des résultats de l'inférence ML. Les recherches menées en philosophie et en sciences cognitives montrent que les gens recherchent des explications contrastives, ou des explications sur la raison pour laquelle un événement X s'est produit au lieu d'un autre événement Y qui ne s'est pas produit. Ici, X peut être un événement inattendu ou surprenant qui s'est produit et Y une attente basée sur leur modèle mental existant appelé *base de référence*. Vous noterez que, pour le même événement X, plusieurs personnes peuvent rechercher des explications différentes selon leur point de vue ou leur modèle mental Y. Dans le contexte de l’IA explicable, vous pouvez considérer X comme l’exemple expliqué et Y comme une base de référence choisie généralement pour représenter un exemple non informatif ou moyen dans le jeu de données. Parfois, par exemple dans le cas de la modélisation ML d'images, la référence peut être implicite : une image dont les pixels sont tous de la même couleur peut servir de référence.
## Exemples de blocs-notes
Amazon SageMaker Clarify fournit l'exemple de bloc-notes suivant pour expliquer le modèle :
+ [Traitement Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/index.html#sagemaker-clarify-processing) : utilisez SageMaker Clarify pour créer une tâche de traitement permettant de détecter les biais et d'expliquer les prédictions du modèle avec les attributions de fonctionnalités. Par exemple, vous pouvez utiliser les formats de données CSV et JSON Lines, apporter votre propre conteneur et exécuter des tâches de traitement avec Spark.
+ [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) — SageMaker Clarify vous donne un aperçu de la façon dont vos modèles de vision par ordinateur classent les images.
+ [Expliquer les modèles de détection d'objets avec SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) — SageMaker Clarify vous donne un aperçu de la façon dont vos modèles de vision par ordinateur détectent les objets.
Il a été vérifié que ce bloc-notes fonctionne uniquement dans Amazon SageMaker Studio. Si vous avez besoin d'instructions pour ouvrir un bloc-notes dans Amazon SageMaker Studio, consultez[Création ou ouverture d'un bloc-notes Amazon SageMaker Studio Classic](notebooks-create-open.md). Si vous êtes invité à choisir un noyau, choisissez **Python 3 (Science des données)**.
**Topics**
+ [Exemples de blocs-notes](#clarify-model-explainability-sample-notebooks)
+ [Attributions de fonctions utilisant des valeurs de Shapley](clarify-shapley-values.md)
+ [Valeurs de Shapley asymétriques](clarify-feature-attribute-shap-asymm.md)
+ [Bases de référence SHAP pour l’explicabilité](clarify-feature-attribute-shap-baselines.md)
# Attributions de fonctions utilisant des valeurs de Shapley
SageMaker Clarify fournit des attributions de fonctionnalités basées sur le concept de valeur de [Shapley.](https://en.wikipedia.org/wiki/Shapley_value) Vous pouvez utiliser les valeurs de Shapley pour déterminer la contribution apportée par chaque fonction aux prévisions du modèle. Ces attributions peuvent être fournies pour des prédictions spécifiques, et globalement pour le modèle tout entier. Par exemple, si vous avez utilisé un modèle ML pour les admissions à l'université, les explications peuvent aider à déterminer si la fonction qui a le plus influé sur les prédictions du modèle était le score GPA ou SAT. Ensuite, vous pouvez déterminer à quel point chaque fonction a participé à la détermination de la décision d'admettre ou non un étudiant.
SageMaker Clarify a repris le concept des valeurs de Shapley de la théorie des jeux et l'a déployé dans un contexte d'apprentissage automatique. La valeur de Shapley fournit un moyen de quantifier la contribution de chaque joueur à un jeu, et donc le moyen de distribuer le gain total généré par un jeu à ses joueurs en fonction de leur contribution respective. Dans ce contexte d'apprentissage automatique, SageMaker Clarify considère la prédiction du modèle sur une instance donnée comme le *jeu* et les fonctionnalités incluses dans le modèle comme les *joueurs*. Dans une première approximation, vous pouvez être tenté de déterminer la contribution ou l'effet marginal de chaque fonction en quantifiant le résultat, soit de l'*abandon* de cette fonction pour le modèle, soit de l'*abandon* de toutes les autres fonctions pour le modèle. Cette approche ne tient toutefois pas compte du fait que les fonctions incluses dans un modèle sont souvent dépendantes les unes des autres. Par exemple, si deux fonctions sont fortement corrélées, en abandonner une peut ne pas affecter significativement la prédiction du modèle.
Afin de traiter ces dépendances potentielles, la valeur de Shapley a besoin que le résultat de chaque combinaison (ou coalition) possible de fonctions soit pris en compte pour déterminer l'importance de chaque fonction. Dans le cas de *d* fonctions, il existe 2d combinaisons de fonctions possibles, qui correspondent chacune à un modèle potentiel. Afin de déterminer l'attribution d'une fonction donnée *f*, vous devez considérer la contribution marginale consistant à inclure *f* dans toutes les combinaisons de fonctions (et les modèles associés) qui ne contiennent pas *f*, et d'en faire la moyenne. Il peut être démontré que la valeur de Shapley est la seule façon d'attribuer la contribution ou l'importance de chaque fonction satisfaisant certaines propriétés souhaitables. En particulier, la somme des valeurs de Shapley de chaque fonction correspond à la différence entre les prédictions du modèle et un modèle fictif sans fonctions. Cependant, même pour des valeurs raisonnables de *d*, par exemple 50 fonctions, il est prohibitif et peu pratique en termes de calcul d'entraîner 2d modèles possibles. Par conséquent, SageMaker Clarify doit utiliser diverses techniques d'approximation. À cette fin, SageMaker Clarify utilise Shapley Additive Explanations (SHAP), qui intègre de telles approximations et a conçu une implémentation évolutive et efficace de l'algorithme Kernel SHAP grâce à des optimisations supplémentaires.
Pour plus d’informations sur les valeurs de Shapley, consultez [A Unified Approach to Interpreting Model Predictions](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf).
# Valeurs de Shapley asymétriques
La solution d'explication du modèle de prévision des séries chronologiques SageMaker Clarify est une méthode d'attribution de fonctionnalités ancrée dans [la théorie des jeux coopératifs](https://en.wikipedia.org/wiki/Cooperative_game_theory), dans un esprit similaire à celui de SHAP. Plus précisément, Clarify utilise des [valeurs de groupe d’ordre aléatoire](http://www.library.fa.ru/files/Roth2.pdf#page=121), également appelées [valeurs de Shapley asymétriques](https://proceedings.neurips.cc/paper/2020/file/0d770c496aa3da6d2c3f2bd19e7b9d6b-Paper.pdf) dans le domaine du machine learning et de l’explicabilité.
## Contexte
L’objectif est de calculer les attributions des caractéristiques d’entrée pour un modèle de prévision donné *f*. Le modèle de prévision accepte les entrées suivantes :
+ Séries temporelles passées *(TS cible)*. Par exemple, il peut s’agir d’anciens passagers quotidiens sur le trajet Paris-Berlin, indiqués par *xt*.
+ (Facultatif) Une série temporelle à covariables. Par exemple, il peut s’agir de fêtes et de données météorologiques, désignées par *zt* ∈ RS. Lorsqu’elle est utilisée, la covariable TS peut être disponible uniquement pour les étapes temporelles passées ou également pour les étapes futures (incluses dans le calendrier des fêtes).
+ (Facultatif) Covariables statiques, telles que la qualité de service (comme la première ou la deuxième classe), désignée par *u* ∈ RE.
Les covariables statiques, les covariables dynamiques ou les deux peuvent être omises, selon le scénario d’application spécifique. Étant donné un horizon de prédiction K ≥ 0 (p. ex., K=30 jours), la prédiction modélisée peut être caractérisée par la formule : *f(x[1:T], z[1:T\$1K], u) = x[T\$11:T \$1K\$11]*.
Le schéma suivant illustre une structure de dépendance pour un modèle de prévision classique. La prédiction à l’instant *t\$11* dépend des trois types d’entrées mentionnés précédemment.
![\[Structure de dépendance pour un modèle de prévision classique.\]](http://docs.aws.amazon.com/fr_fr/sagemaker/latest/dg/images/clarify/clarify-forecast-dependency.png)
## Method
Les explications sont calculées en interrogeant le modèle de série temporelle *f* sur une série de points dérivés de l’entrée d’origine. En suivant les constructions de la théorie des jeux, Clarify fait la moyenne des différences entre les prédictions par obfuscation (c’est-à-dire en fixant à une valeur de référence) de certaines parties des entrées de manière itérative. La structure temporelle peut être parcourue dans un ordre chronologique, antichronologique ou les deux. Les explications chronologiques sont élaborées en ajoutant de manière itérative des informations à partir de la première étape temporelle, tandis que les explications antichronologiques sont élaborées à partir de la dernière étape. Ce dernier mode peut être plus approprié en présence d’un biais de récence, par exemple lors de la prévision du cours des actions. Une propriété importante des explications calculées est que leur somme correspond à la sortie du modèle d’origine si le modèle fournit des sorties déterministes.
## Attributions résultantes
Les attributions résultantes sont des scores qui indiquent les contributions individuelles d’étapes temporelles spécifiques ou de caractéristiques d’entrée spécifiques envers la prévision finale à chaque étape temporelle prévue. Clarify propose les deux granularités suivantes pour les explications :
+ Les explications temporelles sont peu coûteuses et fournissent uniquement des informations sur des étapes temporelles spécifiques, telles que la mesure dans laquelle les informations du 19e jour dans le passé ont contribué à la prévision du 1er jour dans le futur. Ces attributions n’expliquent pas les covariables statiques individuelles ni les explications agrégées des séries temporelles cibles et à covariables. Les attributions sont une matrice *A* où chaque *Atk* est l’attribution de l’étape temporelle *t* envers la prévision de l’étape temporelle *T\$1k*. Notez que si le modèle accepte les covariables futures, *t* peut être supérieur à *T*.
+ Les explications précises sont plus gourmandes en calculs et fournissent une ventilation complète de toutes les attributions des variables d’entrée.
**Note**
Les explications précises prennent en charge uniquement l’ordre chronologique.
Les attributions résultantes sont un triplet composé des éléments suivants :
+ Matrice *Ax* ∈ RT×K associée à la série temporelle d’entrée, où *Atkx* est l’attribution de *xt* envers la prévision de l’étape *T\$1k*
+ Tenseur *Az* ∈ *RT\$1K×S×K* associé à la série temporelle à covariables, où *Atskz* est l’attribution de *zts* (c’est-à-dire la s-ième covariable TS) envers la prévision de l’étape *T\$1k*
+ Matrice *Au* ∈ RE×K associée aux covariables statiques, où *Aeku* est l’attribution de *ue* (la e-ième covariable statique) envers la prévision de l’étape *T\$1k*
Quelle que soit la granularité, l’explication contient également un vecteur de décalage *B* ∈ *RK* qui représente le « comportement élémentaire » du modèle quand toutes les données sont obfusquées.
# Bases de référence SHAP pour l’explicabilité
Les explications sont généralement contrastives (autrement dit, elles tiennent compte des écarts par rapport à une référence). Par conséquent, pour la même prévision de modèle, vous pouvez obtenir des explications différentes selon les bases de référence retenues. Par conséquent, le choix d'une base de référence est crucial. Dans un contexte ML, la base de référence correspond à une instance hypothétique qui peut être *non informative* ou *informative*. Pendant le calcul des valeurs de Shapley, SageMaker Clarify génère plusieurs nouvelles instances entre la ligne de base et l'instance donnée, dans lesquelles l'absence d'une caractéristique est modélisée en définissant la valeur de la caractéristique sur celle de la ligne de base et la présence d'une entité est modélisée en définissant la valeur de la caractéristique sur celle de l'instance donnée. De cette façon, l’absence de toutes les fonctions correspond à la base de référence et la présence de toutes les fonctions correspond à l’instance donnée.
Comment choisir de bonnes bases de référence ? Il est souvent souhaitable de sélectionner une base de référence avec un contenu informatif très faible. Par exemple, vous pouvez créer une instance moyenne à partir du jeu de données d'entraînement en prenant la médiane ou la moyenne des fonctions numériques et le mode de fonctions catégoriques. Dans l’exemple des admissions à l’université, vous pouvez vouloir expliquer pourquoi un candidat particulier a été accepté par rapport aux acceptations de référence basées sur un candidat moyen. Si elle n'est pas fournie, une référence est calculée automatiquement par SageMaker Clarify à l'aide de K-means ou de K-prototypes dans le jeu de données en entrée.
Vous pouvez également choisir de générer des explications relatives à des bases de référence informatives. Dans le scénario des admissions à l'université, vous pouvez vouloir expliquer pourquoi un candidat particulier a été rejeté par rapport à d'autres candidats issus de contextes démographiques similaires. Dans ce cas, vous pouvez choisir une base de référence qui représente les candidats d'intérêt, à savoir ceux d'un contexte démographique similaire. Vous pouvez alors utiliser des bases de référence informatives pour concentrer l'analyse sur les aspects spécifiques d'une prédiction de modèle particulière. Vous pouvez isoler les fonctions à des fins d’évaluation en définissant des attributs démographiques et d’autres fonctions sur lesquelles vous ne pouvez pas agir, sur la même valeur que dans l’instance donnée.
# SageMaker Clarifiez l'explicabilité avec SageMaker AI Autopilot
Le pilote automatique utilise des outils fournis par Amazon SageMaker Clarify pour fournir des informations sur la manière dont les modèles d'apprentissage automatique (ML) établissent des prédictions. Ces outils peuvent aider les ingénieurs ML, les chefs de produit et d’autres intervenants internes à comprendre les caractéristiques d’un modèle. Pour approuver et interpréter les décisions prises sur la base des prédictions modélisées, les consommateurs et les régulateurs s’appuient sur la transparence du machine learning.
La fonctionnalité explicative d’Autopilot utilise une approche d’attribution de caractéristiques indépendante du modèle. Cette approche détermine la contribution des différentes fonctionnalités ou entrées à la sortie du modèle, fournissant ainsi des insights sur la pertinence des différentes fonctionnalités. Vous pouvez l’utiliser pour comprendre pourquoi un modèle a réalisé une prédiction après l’entraînement, ou l’utiliser pour fournir une explication par instance pendant l’inférence. L’implémentation inclut une implémentation évolutive de [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) (Shapley Additive Explanations). Cette implémentation se base sur le concept d’une valeur de Shapley issue de la théorie des jeux coopératifs, qui affecte à chaque caractéristique une valeur d’importance pour une prédiction particulière.
Vous pouvez utiliser les explications SHAP pour les cas suivants : audit et respect d’exigences réglementaires, renforcement de la confiance dans le modèle, soutien aux prises de décisions humaines et débogage et amélioration des performances du modèle.
Pour plus d’informations sur les références et les valeurs de Shapley, consultez [Bases de référence SHAP pour l’explicabilité](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html).
Pour un guide de la documentation Amazon SageMaker Clarify, consultez le [Guide de la documentation SageMaker Clarify](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-fairness-and-explainability.html#clarify-fairness-and-explainability-toc).