` per impostazione predefinita). L’algoritmo di conoscenze fattuali confronta la risposta generata dal modello con una risposta nota. L’algoritmo valuta la risposta come corretta se genera uno qualsiasi dei contenuti separati dal delimitatore nella risposta. Se passi `None` come `target_output_delimiter`, il modello deve generare la stessa risposta della domanda per essere valutato come corretto. Infine, chiama il metodo `evaluate` e passa i parametri desiderati.
Le conoscenze fattuali restituiscono un elenco di oggetti `EvalScore`. Questi contengono punteggi aggregati sulla capacità del modello di codificare le conoscenze fattuali, come descritto nella sezione **Panoramica sulla valutazione del modello di fondazione**. I punteggi variano tra `0` e `1`, con il punteggio più basso che corrisponde a una minore conoscenza dei fatti del mondo reale.
Il codice di esempio seguente mostra come valutare il tuo LLM utilizzando l’algoritmo di conoscenze fattuali:
```
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)
```
### Stereotipizzazione dei prompt
Puoi eseguire l’algoritmo di stereotipizzazione dei prompt per la generazione aperta. Per eseguire l’algoritmo di stereotipizzazione dei prompt, `DataConfig` deve identificare le colonne nel set di dati di input che contengono una frase meno stereotipata in `sent_less_input_location` e una frase più stereotipata in `sent_more_output_location`. Per ulteriori informazioni su `DataConfig`, consulta la sezione precedente **2. Configurazione`ModelRunner`**. Quindi, chiama il metodo `evaluate` e passa i parametri desiderati.
La stereotipizzazione dei prompt restituisce un elenco di oggetti `EvalOutput` che contiene un punteggio per ogni record di input e punteggi complessivi per ogni tipo di bias. I punteggi vengono calcolati confrontando la probabilità associata alle frasi più e meno stereotipate. Il punteggio complessivo indica la frequenza con cui il modello ha preferito la frase stereotipata, in quanto il modello assegna una probabilità maggiore alla frase più stereotipata rispetto a quella meno stereotipata. Un punteggio di `0.5` indica che il modello è imparziale o che sceglie con la stessa frequenza frasi più e meno stereotipate. Un punteggio superiore a `0.5` indica che è probabile che il modello generi una risposta più stereotipata. Un punteggio inferiore a `0.5` indica che è probabile che il modello generi una risposta meno stereotipata.
Il codice di esempio seguente mostra come valutare il tuo LLM utilizzando l’algoritmo di stereotipizzazione dei prompt:
```
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)
```
### Robustezza semantica
È possibile eseguire un algoritmo di robustezza semantica per qualsiasi FMEval attività, tuttavia il modello deve essere deterministico. Un modello è deterministico quando genera sempre lo stesso output per lo stesso input. Per ottenerlo, imposta un seed casuale nel processo di decodifica. Gli algoritmi sono diversi per ogni attività, per adattarsi ai diversi problemi e tipi di input dei dati, come descritto di seguito:
+ Per la generazione aperta, la risposta alle domande o la classificazione delle attività, esegui l’algoritmo `GeneralSemanticRobustness` con un file `GeneralSemanticRobustnessConfig`.
+ Per la sintesi testuale, esegui l’algoritmo `SummarizationAccuracySemanticRobustness` con un file `SummarizationAccuracySemanticRobustnessConfig`.
L’algoritmo `GeneralSemanticRobustness` restituisce un elenco di oggetti `EvalScore` che contiene la metrica di accuratezza con valori compresi tra `0` e `1`, che quantifica la differenza tra gli output del modello perturbati e imperturbati. Per eseguire l’algoritmo generale di robustezza semantica, crea un’istanza di `GeneralSemanticRobustnessConfig` e passa `perturbation_type`. Per `perturbation_type`, puoi scegliere una delle seguenti opzioni:
+ `Butterfinger`: una perturbazione che imita gli errori di ortografia scambiando i caratteri in base alla distanza sulla tastiera. Inserisci una probabilità che un determinato carattere sia perturbato. Butterfinger è il valore predefinito per `perturbation_type`.
+ `RandomUpperCase`: una perturbazione che trasforma una frazione di caratteri in maiuscolo. Inserisci un decimale da `0` a `1`.
+ `WhitespaceAddRemove`: la probabilità che un carattere di spazio vuoto venga aggiunto prima di un carattere non di spazio vuoto.
Puoi anche specificare i parametri seguenti:
+ `num_perturbations`: il numero di perturbazioni da introdurre nel testo generato per ogni campione. Il valore predefinito è `5`.
+ `butter_finger_perturbation_prob`: la probabilità che un carattere sia perturbato. Usato solo quando `perturbation_type` è `Butterfinger`. Il valore predefinito è `0.1`.
+ `random_uppercase_corrupt_proportion`: la frazione di caratteri da convertire in lettere maiuscole. Usato solo quando `perturbation_type` è `RandomUpperCase`. Il valore predefinito è `0.1`.
+ `whitespace_add_prob`: dato uno spazio vuoto, la probabilità che venga rimosso da un campione. Usato solo quando `perturbation_type` è `WhitespaceAddRemove`. Il valore predefinito è `0.05`.
+ `whitespace_remove_prob`: dato uno spazio non vuoto, la probabilità che venga aggiunto uno spazio vuoto davanti ad esso. Usato solo quando `perturbation_type` è `WhitespaceAddRemove`. Il valore predefinito è `0.1`.
Infine, chiama il metodo `evaluate` e passa i parametri desiderati come mostrato nell’esempio di codice seguente:
```
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’algoritmo `SummarizationAccuracySemanticRobustness` restituisce un elenco di oggetti `EvalScore` che contiene la differenza (o Delta) tra i valori [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) e [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) del confronto tra le sintesi generate e quelle di riferimento. Per ulteriori informazioni su questi punteggi, consulta la sezione **Sintesi testuale** in [Utilizzo dei set di dati dei prompt e delle dimensioni di valutazione disponibili nei processi di valutazione del modello](clarify-foundation-model-evaluate-overview.md). Per eseguire l’algoritmo di robustezza semantica della sintesi testuale, crea un’istanza di `SummarizationAccuracySemanticRobustnessConfig` e passa `perturbation_type`.
Per `perturbation_type`, puoi scegliere una delle seguenti opzioni:
+ `Butterfinger`: una perturbazione che imita gli errori di ortografia scambiando i caratteri in base alla distanza sulla tastiera. Inserisce una probabilità che un determinato carattere sia disturbato. `Butterfinger` è il valore predefinito per `perturbation_type`.
+ `RandomUpperCase`: una perturbazione che trasforma una frazione di caratteri in maiuscolo. Inserisci un decimale da `0` a `1`.
+ `WhitespaceAddRemove`: immetti una probabilità a probabilità che un carattere di spazio vuoto venga aggiunto prima di un carattere non di spazio vuoto.
Puoi anche specificare i parametri seguenti:
+ `num_perturbations`: il numero di perturbazioni da introdurre nel testo generato per ogni campione. Il valore predefinito è “`5`”.
+ `butter_finger_perturbation_prob`: la probabilità che un carattere sia perturbato. Usato solo quando `perturbation_type` è `Butterfinger`. Il valore predefinito è “`0.1`”.
+ `random_uppercase_corrupt_proportion`: la frazione di caratteri da convertire in lettere maiuscole. Usato solo quando `perturbation_type` è `RandomUpperCase`. Il valore predefinito è “`0.1`”.
+ `whitespace_add_prob`: dato uno spazio vuoto, la probabilità che venga rimosso da un campione. Usato solo quando `perturbation_type` è `WhitespaceAddRemove`. Il valore predefinito è “`0.05`”.
+ `whitespace_remove_prob`: dato uno spazio non vuoto, la probabilità che venga aggiunto uno spazio vuoto davanti ad esso. Utilizzato solo quando `perturbation_type` è `WhitespaceAddRemove`. L’impostazione predefinita è `0.1`.
+ `rouge_type`: metriche che confrontano le sintesi generate con le sintesi di riferimento. Specifica in `rouge_type` il tipo di metrica [https://en.wikipedia.org/wiki/ROUGE_(metric)](https://en.wikipedia.org/wiki/ROUGE_(metric)) da utilizzare nella valutazione. Puoi scegliere `rouge1`, `rouge2` o `rougeL`. ROUGE-1 confronta le sintesi generate con le sintesi di riferimento utilizzando unigrammi sovrapposti (sequenze di un solo elemento come “il”, “è”). ROUGE-2 confronta le sintesi generate e quelle di riferimento utilizzando bigrammi (gruppi di due sequenze come “il grande”, “è casa”). ROUGE-L confronta la sequenza più lunga di parole corrispondenti. Per ulteriori informazioni su ROUGE, consulta [ROUGE: A Package for Automatic Evaluation of Summaries](https://aclanthology.org/W04-1013.pdf).
+ Imposta `user_stemmer_for_rouge` su `True` o `False`. Uno stemmer rimuove gli affissi dalle parole prima di confrontarle. Ad esempio, uno stemmer rimuove gli affissi da “nuotando” e “nuotava”, trasformando entrambi in “nuotare” dopo lo stemming.
+ Imposta `model_type_for_bertscore` sul modello da utilizzare per calcolare [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore). Puoi scegliere [ROBERTA\$1MODEL](https://huggingface.co/docs/transformers/model_doc/roberta) o il più avanzato [MICROSOFT\$1DEBERTA\$1MODEL](https://github.com/microsoft/DeBERTa).
Chiama il metodo `evaluate` e passa i parametri desiderati come mostrato nell’esempio di codice seguente:
```
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)
```
### Tossicità
Puoi eseguire un algoritmo di tossicità per la generazione aperta, la sintesi testuale o la risposta alle domande. Sono disponibili tre classi distinte a seconda dell’attività.
+ Per una generazione aperta, esegui l’algoritmo Tossicità con un file `ToxicityConfig`.
+ Per la sintesi, utilizza la classe `Summarization_Toxicity`.
+ Per le attività di risposta alle domande, utilizza la classe `QAToxicity`.
L’algoritmo di tossicità restituisce un elenco di oggetti `EvalScore` (a seconda del rilevatore di tossicità) che contiene punteggi compresi tra `0` e `1`. Per eseguire l’algoritmo di tossicità, crea un’istanza di `ToxicityConfig` e passa un modello di tossicità da utilizzare per valutare il tuo modello in `model_type`. Puoi scegliere le opzioni seguenti per `model_type`:
+ [`detoxify` for UnitaryAI Detoxify-unbiased](https://github.com/unitaryai/detoxify), un classificatore di testo multi-etichetta addestrato su [Toxic Comment Classification Challenge](https://www.kaggle.com/c/jigsaw-toxic-comment-classification-challenge) e [Jigsaw Unintended Bias in Toxicity Classification](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification). Il modello fornisce `7` punteggi per le seguenti classi: tossicità, tossicità grave, oscenità, minacce, insulti, riferimenti sessuali espliciti e attacchi all’identità.
Di seguito è riportato l’output di esempio del modello di eliminazione della tossicità:
```
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` per Toxigen-Roberta, un classificatore di testo binario BERTa basato su Ro ottimizzato sul set di dati, che contiene frasi con tossicità](https://github.com/microsoft/TOXIGEN) sottile e implicita relative a gruppi minoritari. ToxiGen `13`
Infine, chiama il metodo `evaluate` e passa i parametri desiderati come mostrato nell’esempio di codice seguente.
```
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)
```
# Risultati della valutazione del modello
Le metriche di precisione per sono valori numerici destinati a LLMs rappresentare la risposta di un modello alla richiesta. Tuttavia, a volte un valore numerico non è in grado di catturare le complessità del linguaggio umano. Riportiamo metriche di accuratezza specifiche per ogni attività, progettate per misurare la qualità della risposta per ogni singolo aspetto. Ad esempio, il comando di richiamo misura se la risposta corretta è inclusa nell’output del modello, mentre la precisione fornisce un’indicazione di quanto sia dettagliata la risposta del modello. Per sapere se il modello fornisce l’output desiderato, devi confrontare più metriche e, ove possibile, combinarle con una valutazione qualitativa (ad esempio, l’analisi manuale dei campioni).
**Example Accuratezza per il tipo di attività Domande e risposte**
Questo esempio descrive come interpretare le metriche di accuratezza nel contesto della risposta di un modello e quanto quest’ultima sia dettagliata.
Questo esempio si basa sul modello `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“
```
Per assegnare un punteggio a questa risposta, suddividiamola in base a ciascuna metrica calcolata.
+ `recall_over_words` è 1,0 perché il modello ha restituito l’output corretto.
+ `precision_over_words` è basso (0,11) perché la risposta è molto dettagliata rispetto all’*output di destinazione*.
+ `f1_score`, che combina precisione e richiamo, restituisce un valore basso (0,19).
+ L’output del modello ottiene un punteggio di 0,0 per tutte le altre metriche di accuratezza.
Da queste metriche calcolate possiamo concludere che sì, l’output di destinazione è stato restituito nella risposta, ma la risposta è stata complessivamente troppo dettagliata.
I punteggi sono visualizzati anche nel grafico radar seguente.
![\[Un’immagine che mostra un grafico radar per ogni metrica restituita.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/radar-plot-example-01.png)
**Example Accuratezza per il tipo di attività Domande e risposte**
In questo esempio, il modello ha difficoltà a restituire l’output di destinazione
```
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.
```
L’output del modello non corrisponde esattamente all’output di destinazione, pertanto sia `exact_match_score` che `quasi_exact_match_score` vengono valutati 0. Poiché l’output del modello contiene circa la metà delle parole dell’output di destinazione, `recall_over_words` restituisce 0,47. L’output di destinazione contiene circa un quarto delle parole nell’output del modello, quindi `precision_over_words` è 0,27. Di conseguenza, la media geometrica dei due valori riportata in `f1_score `è di 0,34. I punteggi vengono visualizzati nel grafico radar seguente.
![\[Un’immagine che mostra un grafico radar per ogni metrica restituita.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/radar-plot-example-02.png)
**Example Il punteggio Accuratezza per una coppia di domande e risposte non è corretto**
In questo esempio, il modello risponde con un output che non contiene l’output di destinazione.
```
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“
```
In questo esempio, la domanda e l’output di destinazione erano entrambi soggettivi. Il modello ha risposto restituendo domande simili al prompt e le relative risposte. Poiché il modello non ha restituito la risposta soggettiva fornita, l’output ha ottenuto un punteggio di 0,0 per tutte le metriche di accuratezza, come illustrato di seguito. Data la natura soggettiva di questa domanda, si raccomanda un’ulteriore valutazione umana.
# Informazioni sui risultati del processo di valutazione del modello
Utilizza le sezioni seguenti per scoprire come interpretare i risultati del processo di valutazione del modello. I dati JSON di output salvati in Amazon S3 per i processi di valutazione del modello automatici e umani sono diversi. Scopri dove vengono salvati i risultati di un processo in Amazon S3 utilizzando Studio. A tale scopo, apri la home page **Valutazioni dei modelli** in Studio e scegli il tuo processo dalla tabella.
## Visualizzazione dei risultati della valutazione del modello in Studio
Una volta completato il processo di valutazione del modello, puoi vedere le prestazioni del modello rispetto al set di dati che hai fornito utilizzando la procedura seguente:
1. Dal riquadro di navigazione di Studio, seleziona **Processi**, quindi seleziona **Valutazione del modello**.
1. Nella pagina **Valutazioni del modello**, i processi inviati correttamente vengono visualizzati in un elenco. L’elenco include il nome del processo, lo stato, il nome del modello, il tipo di valutazione e la data di creazione.
1. Se la valutazione del modello è stata completata correttamente, puoi fare clic sul nome del processo per visualizzare un riepilogo dei risultati della valutazione.
1. Per visualizzare il report dell’analisi umana, seleziona il nome del processo da esaminare.
Per informazioni sull’interpretazione dei risultati della valutazione del modello, consulta l’argomento che corrisponde al tipo di processo di valutazione del modello di cui desideri interpretare i risultati.
+ [Informazioni sui risultati di un processo di valutazione umana](clarify-foundation-model-evaluate-results-human.md)
+ [Informazioni sui risultati di un processo di valutazione automatica](clarify-foundation-model-evaluate-auto-ui-results.md)
# Informazioni sui risultati di un processo di valutazione umana
Quando hai creato un processo di valutazione del modello con lavoratori umani, hai selezionato uno o più *tipi di metriche*. Quando i membri del team di lavoro valutano una risposta nel portale per i lavoratori, le loro risposte vengono salvate nell’oggetto json `humanAnswers`. Il modo in cui tali risposte vengono archiviate cambia in base al tipo di metrica selezionato al momento della creazione del processo.
Le sezioni seguenti spiegano queste differenze e forniscono esempi.
## Documentazione di riferimento dell’output JSON
Al termine di un processo di valutazione del modello, i risultati vengono salvati in Amazon S3 come file JSON. L’oggetto JSON contiene tre nodi generali, `humanEvaluationResult`, `inputRecord` e `modelResponses`. La `humanEvaluationResult` chiave è un nodo generale che contiene le risposte del team di lavoro assegnato al processo di valutazione del modello. La chiave `inputRecord` è un nodo generale che contiene i prompt forniti ai modelli al momento della creazione del processo di valutazione del modello. La chiave `modelResponses` è un nodo generale che contiene le risposte ai prompt di uno o più modelli.
La tabella seguente riassume le coppie chiave-valore trovate nell’output JSON del processo di valutazione del modello.
Le sezioni successive forniscono dettagli più granulari su ciascuna coppia chiave-valore.
****
| Parametro | Esempio | Description |
| --- | --- | --- |
| `flowDefinitionArn` | arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name | L’ARN del flusso di lavoro di revisione umana (definizione del flusso) utilizzato per creare il ciclo umano. |
| humanAnswers | Un elenco di oggetti JSON specifici per le metriche di valutazione selezionate. Per ulteriori informazioni, consulta [Coppie chiave-valore trovate in `humanAnswers`.](#clarify-foundation-model-evaluate-humanAnswers). | Un elenco di oggetti JSON che contiene le risposte dei lavoratori. |
| `humanLoopName` | system-generated-hash | Una stringa esadecimale di 40 caratteri generata dal sistema. |
| 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."
}]
} | Un oggetto JSON contenente un prompt di immissione dal set di dati di input. |
| modelResponses | "modelResponses": [{
"modelIdentifier": "arn:aws:bedrock:us-west-2::foundation-model/model-id",
"text": "the-models-response-to-the-prompt"
}] | Le risposte individuali dei modelli. |
| 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"
} | Il contenuto di input del ciclo umano necessario per avviare tale ciclo nel tuo bucket Amazon S3. |
| modelResponseIdMap | {
"0": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612",
"1": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
} | Descrive come viene rappresentato ogni modello in `answerContent`. |
### Coppie chiave-valore trovate in `humanEvaluationResult`.
Le seguenti coppie chiave-valore sono state trovate in `humanEvaluationResult` nell’output del processo di valutazione del modello.
Per le coppie chiave-valore associate a `humanAnswers`, consulta [Coppie chiave-valore trovate in `humanAnswers`.](#clarify-foundation-model-evaluate-humanAnswers).
**`flowDefinitionArn`**
+ L’ARN della definizione del flusso utilizzato per completare il processo di valutazione del modello.
+ *Esempio*`arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name`:
**`humanLoopName`**
+ Una stringa esadecimale di 40 caratteri generata dal sistema.
**`inputContent`**
+ Questo valore della chiave descrive i *tipi di metriche* e le istruzioni fornite ai lavoratori nel portale per i lavoratori.
+ `additionalDataS3Uri`: la posizione in Amazon S3 in cui vengono salvate le istruzioni per i lavoratori.
+ `instructions`: le istruzioni fornite ai lavoratori nel portale per i lavoratori.
+ `evaluationMetrics`: il nome della metrica e la relativa descrizione. Il valore della chiave `metricType` è lo strumento fornito ai lavoratori per valutare le risposte dei modelli.
**`modelResponseIdMap`**
+ Questa coppia chiave-valore identifica i nomi completi dei modelli selezionati e il modo in cui le scelte dei lavoratori vengono mappate ai modelli nelle coppie chiave-valore `humanAnswers`.
### Coppie chiave-valore trovate in `inputRecord`.
Le voci seguenti descrivono le coppie chiave-valore `inputRecord`.
**`prompt`**
+ Il testo del prompt inviato al modello.
**`category`**
+ Una categoria facoltativa che classifica il prompt. Visibile ai lavoratori nel portale per i lavoratori durante la valutazione del modello.
+ *Esempio*`"American cities"`:
**`referenceResponse`**
+ Un campo facoltativo dell’input JSON utilizzato per specificare la Ground Truth a cui si desidera che i lavoratori facciano riferimento durante la valutazione.
**`responses`**
+ Un campo facoltativo dell’input JSON che contiene le risposte di altri modelli.
Un esempio di record di input 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."
}]
}
```
### Coppie chiave-valore trovate in `modelResponses`.
Un array di coppie chiave-valore che contiene le risposte dei modelli e il modello che ha fornito le risposte.
**`text`**
+ La risposta del modello al prompt.
**`modelIdentifier`**
+ Il nome del modello.
### Coppie chiave-valore trovate in `humanAnswers`.
Un array di coppie chiave-valore che contiene le risposte dei modelli e il modo in cui i lavoratori hanno valutato i modelli.
**`acceptanceTime`**
+ L’ora in cui il lavoratore ha accettato l’attività nel portale per i lavoratori.
**`submissionTime`**
+ L’ora in cui il lavoratore ha inviato la risposta.
**`timeSpentInSeconds`**
+ La durata per il completamento dell’attività del lavoratore.
**`workerId`**
+ L’ID del lavoratore che ha completato l’attività.
**`workerMetadata`**
+ Metadati relativi al team di lavoro assegnato a questo processo di valutazione del modello.
#### Formato dell’array JSON `answerContent`
La struttura della risposta dipende dalle metriche di valutazione selezionate al momento della creazione del processo di valutazione del modello. Ogni risposta o risposta del lavoratore viene registrata in un nuovo oggetto JSON.
**`answerContent`**
+ `evaluationResults` contiene le risposte del lavoratore.
+ Quando è selezionato **Pulsanti di scelta**, i risultati di ogni lavoratore sono uguali a `"evaluationResults": "comparisonChoice"`.
`metricName`: il nome della metrica.
`result`: l’oggetto JSON indica quale modello ha selezionato il lavoratore utilizzando `0` o`1`. Per vedere a quale valore viene mappato un modello, consulta `modelResponseIdMap`.
+ Quando è selezionato **Scala Likert - Confronto**, i risultati di ogni lavoratore sono uguali a `"evaluationResults": "comparisonLikertScale"`.
`metricName`: il nome della metrica.
`leftModelResponseId`: indica quale `modelResponseIdMap` era visualizzato sul lato sinistro del portale per i lavoratori.
`rightModelResponseId`: indica quale `modelResponseIdMap` era visualizzato sul lato sinistro del portale per i lavoratori.
`result`: l’oggetto JSON indica quale modello ha selezionato il lavoratore utilizzando `0` o`1`. Per vedere a quale valore viene mappato un modello, consulta `modelResponseIdMap`.
+ Quando è selezionato **Classificazione ordinale**, i risultati di ogni lavoratore sono uguali a `"evaluationResults": "comparisonRank"`.
`metricName`: il nome della metrica.
`result`: un array di oggetti JSON. I lavoratori forniscono `rank` per ogni modello (`modelResponseIdMap`).
```
"result": [{
"modelResponseId": "0",
"rank": 1
}, {
"modelResponseId": "1",
"rank": 1
}]
```
+ Quando è selezionato **Scala Likert, valutazione della risposta di un singolo modello**, i risultati di un lavoratore vengono salvati in `"evaluationResults": "individualLikertScale"`. Si tratta di un array JSON che contiene i punteggi per `metricName` specificati al momento della creazione del processo.
`metricName`: il nome della metrica.
`modelResponseId`: il modello a cui viene assegnato il punteggio. Per vedere a quale valore viene mappato un modello, consulta `modelResponseIdMap`.
`result`: una coppia chiave-valore che indica il valore della scala likert selezionato dal worker.
+ Quando è selezionato **Pollice su/giù**, i risultati di un lavoratore vengono salvati come array JSON `"evaluationResults": "thumbsUpDown"`.
`metricName`: il nome della metrica.
`result`: `true` o `false`, perché è associato a `metricName`. Quando un lavoratore sceglie il pollice su, `"result" : true`.
## Esempio di output di un processo di valutazione del modello
Il seguente oggetto JSON è un esempio di output del processo di valutazione del modello salvato in Amazon S3. Per ulteriori informazioni su ciascuna coppia chiave-valore, consulta [Documentazione di riferimento dell’output JSON](#clarify-foundation-model-evaluate-results-human-ref).
Per chiarezza, questo processo contiene solo le risposte di due lavoratori. Inoltre, alcune coppie chiave-valore potrebbero essere state troncate per una maggiore leggibilità.
```
{
"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"
}
]
}
```
# Informazioni sui risultati di un processo di valutazione automatica
Al termine del processo di valutazione automatica del modello, i risultati vengono salvati in Amazon S3. Le sezioni seguenti descrivono i file generati e spiegano come interpretarli.
## Interpretazione della struttura del file `output.json`
Il file `output.json` contiene i punteggi aggregati per i set di dati e le metriche selezionati.
Di seguito è riportato un esempio di output.
```
{
"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
}]
}
]
}]
}
```
## Interpretazione della struttura del file dei risultati relativi all’istanza
Un file *evaluation\$1name* \$1 *dataset\$1name* .jsonl contenente risultati a livello di istanza per ogni richiesta jsonlines. Se erano presenti `300` richieste nei dati di input di jsonlines, questo file di output jsonlines conterrà `300` risposte. Il file di output contiene la richiesta al modello seguita dal punteggio per quella valutazione. Segue un esempio di output relativo all’istanza.
## Interpretazione del report
Un **report di valutazione** contiene i risultati del processo di valutazione del modello di fondazione. Il contenuto del report di valutazione dipende dal tipo di attività utilizzato per valutare il modello. Ogni report contiene le sezioni seguenti:
1. I **punteggi complessivi** per ogni valutazione riuscita nell’ambito dell’attività di valutazione. Come esempio di valutazione con un set di dati, se hai valutato il tuo modello per un’attività di classificazione per Accuratezza e Robustezza semantica, nella parte superiore del report viene visualizzata una tabella che riassume i risultati della valutazione per Accuratezza e Robustezza semantica. Altre valutazioni con altri set di dati possono essere strutturate in modo diverso.
1. La configurazione per il processo di valutazione, inclusi il nome del modello, il tipo, i metodi di valutazione utilizzati e i set di dati rispetto ai quali è stato valutato il modello.
1. Una sezione **Risultati dettagliati della valutazione** con un riepilogo dell’algoritmo di valutazione, informazioni e link a tutti i set di dati integrati, le modalità di calcolo dei punteggi e le tabelle che mostrano alcuni dati di esempio con i punteggi associati.
1. Una sezione **Valutazioni non riuscite** che contiene un elenco di valutazioni non completate. Se tutte le valutazioni sono state eseguite correttamente, questa sezione del report viene omessa.
# Personalizzazione del flusso di lavoro con la libreria `fmeval`
Puoi personalizzare la valutazione del modello per consentire un modello diverso da un modello Amazon Bedrock JumpStart o utilizzare un flusso di lavoro personalizzato per la valutazione. Se utilizzi il tuo modello, devi creare un `ModelRunner` personalizzato. Se utilizzi il tuo set di dati per la valutazione, devi configurare un oggetto `DataConfig`. La sezione seguente mostra come formattare il set di dati di input, personalizzare un oggetto `DataConfig` per utilizzare tale set di dati e creare un `ModelRunner` personalizzato.
## Utilizzo di un set di dati di input personalizzato
Per valutare il modello con il tuo set di dati, devi utilizzare un oggetto `DataConfig` per specificare `dataset_name` e `dataset_uri` del set di dati da valutare. Se utilizzi un set di dati integrato, l’oggetto `DataConfig` è già configurato come predefinito per gli algoritmi di valutazione.
Puoi utilizzare un solo set di dati personalizzato ogni volta che utilizzi la funzione `evaluate`. Puoi invocare `evaluate` tutte le volte che vuoi per utilizzare il numero di set di dati desiderato.
Configura un set di dati personalizzato con la richiesta del modello specificata nella colonna della domanda e la risposta di destinazione specificata nella colonna della risposta, come descritto di seguito:
```
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` contiene i parametri seguenti:
+ `dataset_name`: il nome del set di dati da utilizzare per valutare il tuo LLM.
`dataset_uri`: il percorso locale o l’URI (Uniform Resource Identifier) della posizione S3 del set di dati.
+ `dataset_mime_type`: il formato dei dati di input da utilizzare per valutare il tuo LLM. La FMEval libreria può supportare entrambi `MIME_TYPE_JSON` e`MIME_TYPE_JSONLINES`.
+ `model_input_location`: (facoltativo) il nome della colonna nel set di dati che contiene gli input o i prompt del modello da valutare.
Utilizza `model_input_location` per specificare il nome della colonna. La colonna deve contenere i valori seguenti, associati alle relative attività:
+ Per le valutazioni di **generazione aperta**, **tossicità** e **accuratezza**, specifica la colonna che contiene il **prompt** a cui il modello deve rispondere.
+ Per un’attività di **risposta alle domande**, specifica la colonna che contiene la **domanda** a cui il modello deve rispondere.
+ Per un’**attività di sintesi testuale**, specifica il nome della colonna che contiene il **testo** che il modello deve sintetizzare.
+ Per un’**attività di classificazione**, specifica il nome della colonna che contiene il **testo** che il modello deve classificare.
+ Per le valutazioni delle **conoscenze fattuali**, specifica il nome della colonna che contiene la **domanda** per la quale il modello deve prevedere la risposta.
+ Per le valutazioni di **robustezza semantica**, specifica il nome della colonna che contiene l’**input** da modificare nel modello.
+ Per le **valutazioni di stereotipizzazione dei prompt**, utilizza `sent_more_input_location` e ` sent_less_input_location` invece di `model_input_location`, come illustrato nei parametri seguenti.
+ `model_output_location`: (facoltativo) il nome della colonna del set di dati che contiene l’output previsto da confrontare con l’output di riferimento contenuto in `target_output_location`. Se fornisci`model_output_location`, FMEval non invierà una richiesta di inferenza al tuo modello. Utilizzerà invece l’output contenuto nella colonna specificata per valutare il modello.
+ `target_output_location`: il nome della colonna nel set di dati di riferimento che contiene il valore true da confrontare con il valore previsto contenuto in `model_output_location`. Richiesto solo per le conoscenze fattuali, l’accuratezza e la robustezza semantica. Per le conoscenze fattuali, ogni riga di questa colonna deve contenere tutte le possibili risposte separate da un delimitatore. Ad esempio, se le risposte a una domanda sono [“UK”, “England”], la colonna dovrebbe contenere “UKEngland”. La previsione tramite modello è corretta se contiene una delle risposte separate dal delimitatore.
+ `category_location`: il nome della colonna che contiene il nome di una categoria. Se fornisci un valore per `category_location`, i punteggi vengono aggregati e registrati per ogni categoria.
+ `sent_more_input_location`: il nome della colonna che contiene il prompt con più bias. Obbligatorio solo per la stereotipizzazione dei prompt. Evita i bias inconsci. Per esempi di bias, consulta il [set di dati CrowS-Pairs](https://paperswithcode.com/dataset/crows-pairs).
+ `sent_less_input_location`: il nome della colonna che contiene il prompt con meno bias. Obbligatorio solo per la stereotipizzazione dei prompt. Evita i bias inconsci. Per esempi di bias, consulta il [set di dati CrowS-Pairs](https://paperswithcode.com/dataset/crows-pairs).
+ `sent_more_output_location`: (facoltativo) il nome della colonna che contiene una probabilità prevista che la risposta generata dal modello contenga più bias. Questo parametro viene utilizzato solo nelle attività di stereotipizzazione dei prompt.
+ `sent_less_output_location`: (facoltativo) il nome della colonna che contiene una probabilità prevista che la risposta generata dal modello contenga meno bias. Questo parametro viene utilizzato solo nelle attività di stereotipizzazione dei prompt.
Per aggiungere alla `DataConfig` classe un nuovo attributo che corrisponde a una colonna del set di dati, è necessario aggiungere `suffix _location` alla fine del nome dell’attributo.
## Utilizzo di un `ModelRunner` personalizzato
Per valutare un modello personalizzato, utilizza una classe di dati di base per configurare il modello e creare un `ModelRunner` personalizzato. Quindi, puoi utilizzare `ModelRunner` per valutare qualsiasi modello linguistico. Utilizza la procedura seguente per definire una configurazione del modello, creare un `ModelRunner` personalizzato e testarlo.
L’interfaccia `ModelRunner` dispone di un metodo astratto come descritto di seguito:
```
def predict(self, prompt: str) → Tuple[Optional[str], Optional[float]]
```
Questo metodo accetta un prompt come input di stringa e restituisce una Tupla che contiene una risposta testuale del modello e una probabilità logaritmica di input. Ogni `ModelRunner` deve implementare un metodo `predict`.
**Creazione di un `ModelRunner` personalizzato**
1. Definisci una configurazione del modello.
L’esempio di codice seguente mostra come applicare un decoratore `dataclass` a una classe `HFModelConfig` personalizzata per definire una configurazione per un modello **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
```
Nell’esempio di codice precedente, si applica quanto segue:
+ Il parametro `max_new_tokens` viene utilizzato per contenere la lunghezza della risposta limitando il numero di token restituiti da un LLM. Il tipo di modello viene impostato passando un valore per `model_name` quando viene creata un’istanza della classe. In questo esempio, il nome del modello è impostato su `gpt2`, come mostrato alla fine di questa sezione. Il parametro `max_new_tokens` è un’opzione per configurare le strategie di generazione del testo utilizzando una configurazione del modello `gpt2` per un modello GPT OpenAI preaddestrato. Vedi [AutoConfig](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html)per altri tipi di modelli.
+ Se il parametro `remove_prompt_from_generated_text` è impostato su `True`, la risposta generata non conterrà il prompt di origine inviato nella richiesta.
Per altri parametri di generazione del testo, consultate la [Hugging Facedocumentazione di GenerationConfig](https://huggingface.co/docs/transformers/v4.34.1/en/main_classes/text_generation#transformers.GenerationConfig).
1. Crea un `ModelRunner` personalizzato e implementa un metodo di previsione. L’esempio di codice seguente mostra come creare un `ModelRunner` personalizzato per un modello Hugging Face utilizzando la classe `HFModelConfig` creata nell’esempio di codice precedente.
```
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
```
Il codice precedente utilizza una `HuggingFaceCausalLLMModelRunner` classe personalizzata che eredita le proprietà dalla FMEval `ModelRunner` classe. La classe personalizzata contiene un costruttore e una definizione per una funzione di previsione, che restituisce `Tuple`.
Per altri esempi di `ModelRunner`, consulta la sezione [model\$1runner](https://github.com/aws/fmeval/tree/main/src/fmeval/model_runners) della libreria `fmeval`.
Il costruttore `HuggingFaceCausalLLMModelRunner` contiene le seguenti definizioni:
+ La configurazione è impostata su `HFModelConfig`, definito all’inizio di questa sezione.
+ Il modello è impostato su un modello preaddestrato di Hugging Face [Auto Class](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html), specificato con il parametro model\$1name al momento della creazione dell’istanza.
+ Il tokenizer è impostato su una classe della [libreria di tokenizer Hugging Face](https://huggingface.co/docs/transformers/model_doc/auto#transformers.AutoTokenizer), che corrisponde al modello preaddestrato specificato da `model_name`.
Il metodo `predict` nella classe `HuggingFaceCausalLLMModelRunner` utilizza le definizioni seguenti:
+ `input_ids`: una variabile che contiene l’input per il modello. Il modello genera l’input come segue.
+ A `tokenizer` Converte la richiesta contenuta `prompt` in identificatori di token (). IDs Questi token IDs, che sono valori numerici che rappresentano un token specifico (parola, sottoparola o carattere), possono essere utilizzati direttamente dal modello come input. I token IDs vengono restituiti come oggetti PyTorch tensoriali, come specificato da. `return_tensors="pt"` Per altri tipi di tensori restituiti, consulta la documentazione di Hugging Face per [apply\$1chat\$1template](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer.apply_chat_template).
+ IDs I token vengono inviati a un dispositivo in cui si trova il modello in modo che possano essere utilizzati dal modello.
+ `generations`: una variabile che contiene la risposta generata dal tuo LLM. La funzione di generazione del modello utilizza i seguenti input per generare la risposta:
+ I valori `input_ids` della fase precedente.
+ Il parametro `max_new_tokens` specificato in `HFModelConfig`.
+ `pad_token_id` aggiunge un token di fine frase (eos) alla risposta. Per altri token che puoi usare, consulta la Hugging Face documentazione di [PreTrainedTokenizer](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer).
+ `generation_contains_input`: una variabile booleana che restituisce `True` quando la risposta generata include il prompt di input nella sua risposta, altrimenti restituisce `False`. Il valore restituito viene calcolato utilizzando un confronto a livello di elemento tra quanto segue.
+ Tutti i token IDs presenti nel prompt di input contenuti in. `input_ids["input_ids"][0]`
+ L’inizio del contenuto generato contenuto in `generations[0][: input_ids["input_ids"].shape[1]]`.
Il metodo `predict` restituisce un avviso se hai indirizzato l’LLM a `remove_prompt_from_generated_text` nella configurazione, ma la risposta generata non contiene il prompt di input.
L'output del `predict` metodo contiene una stringa restituita dal `batch_decode` metodo, che converte il token IDs restituito nella risposta in testo leggibile dall'uomo. Se hai specificato `remove_prompt_from_generated_text` come `True`, il prompt di input viene rimosso dal testo generato. Se hai specificato `remove_prompt_from_generated_text` come `False`, il testo generato verrà restituito senza i token speciali che hai incluso nel dizionario `special_token_dict`, come specificato da `skip_special_tokens=True`.
1. Testa `ModelRunner`. Invia una richiesta di esempio al tuo modello.
L’esempio seguente mostra come testare un modello con il modello preaddestrato `gpt2` della classe Hugging Face `AutoConfig`:
```
hf_config = HFModelConfig(model_name="gpt2", max_new_tokens=32)
model = HuggingFaceCausalLLMModelRunner(model_config=hf_config)
```
Nell’esempio di codice precedente, `model_name` specifica il nome del modello preaddestrato. Per la classe `HFModelConfig` viene creata un’istanza hf\$1config con un valore per il parametro `max_new_tokens`, che viene utilizzata per l’inizializzazione di `ModelRunner`.
Se desideri utilizzare un altro modello pre-addestrato diHugging Face, scegline uno `pretrained_model_name_or_path` in sotto. `from_pretrained` [AutoClass](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html)
Infine, testa `ModelRunner`. Invia una richiesta di esempio al tuo modello come mostrato nell’esempio di codice seguente:
```
model_output = model.predict("London is the capital of?")[0]
print(model_output)
eval_algo.evaluate_sample()
```
# Tutorial sui notebook per la valutazione del modello
Questa sezione fornisce i seguenti tutorial per i notebook, con codice di esempio e spiegazioni:
+ Come valutare un JumpStart modello per una rapida stereotipizzazione.
+ Come valutare un modello Amazon Bedrock per l’accuratezza della sintesi testuale.
**Topics**
+ [Valuta un JumpStart modello per una rapida stereotipizzazione](clarify-foundation-model-evaluate-auto-tutorial-one.md)
+ [Valutazione di un modello Amazon Bedrock per l’accuratezza della sintesi testuale](clarify-foundation-model-evaluate-auto-tutorial-two.md)
+ [Notebook aggiuntivi](#clarify-foundation-model-evaluate-auto-tutorial-ex)
# Valuta un JumpStart modello per una rapida stereotipizzazione
Puoi utilizzare un `ModelRunner` wrapper di alto livello per valutare un SageMaker JumpStart modello Amazon per una rapida stereotipizzazione. L’algoritmo di stereotipizzazione dei prompt misura la probabilità che il modello includa bias nella risposta. Questi bias riguardano razza, genere, orientamento sessuale, religione, età, nazionalità, disabilità, aspetto fisico e status socioeconomico.
Questo tutorial mostra come caricare il modello [Falcon 7-B](https://huggingface.co/tiiuae/falcon-7b) del [Technology Innovation Institute](https://www.tii.ae/), disponibile in JumpStart, e chiedere a questo modello di generare risposte ai prompt. Quindi, questo tutorial mostra come valutare le risposte per rilevare la stereotipizzazione dei prompt nel set di dati complesso open source [CrowS-Pairs](https://github.com/nyu-mll/crows-pairs) integrato.
Le sezioni del tutorial spiegano come:
+ Configurare l’ambiente.
+ Eseguire la valutazione del modello.
+ Visualizzare i risultati dell’analisi.
## Configurare l'ambiente
**Prerequisiti**
+ Utilizza un ambiente kernel Python 3.10 di base e un’istanza `ml.g4dn.2xlarge` di Amazon Elastic Compute Cloud (Amazon EC2) prima di iniziare il tutorial.
Per ulteriori informazioni sui tipi di istanze e sui relativi casi d’uso consigliati, consulta [Tipi di istanze disponibili per l'uso con i notebook Amazon SageMaker Studio Classic](notebooks-available-instance-types.md).
**Installazione delle librerie richieste**
1. Installa l' SageMaker IA e `fmeval` le altre librerie richieste nel codice come segue:
```
!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. Scarica il set di dati `JSON Lines` di esempio [crows-pairs\$1sample.jsonl](https://github.com/aws/fmeval/blob/main/examples/crows-pairs_sample.jsonl) nella directory di lavoro corrente.
1. Verifica che il tuo ambiente contenga il file di input di esempio utilizzando il codice seguente:
```
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. Definisci un JumpStart modello come segue:
```
from sagemaker.jumpstart.model import JumpStartModel
model_id, model_version, = (
"huggingface-llm-falcon-7b-instruct-bf16",
"*",
)
```
1. Implementate il JumpStart modello e create un endpoint come segue:
```
my_model = JumpStartModel(model_id=model_id)
predictor = my_model.deploy()
endpoint_name = predictor.endpoint_name
```
1. Definisci un prompt e il formato della richiesta del modello, o payload, come descritto di seguito:
```
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
},
}
```
Nell’esempio di codice precedente, nella richiesta del modello sono inclusi i seguenti parametri:
+ `do_sample`: indica al modello di campionare i risultati del modello non elaborato (prima della normalizzazione) durante l’inferenza del modello per introdurre diversità e creatività nelle risposte del modello. L’impostazione predefinita è `False`. Se imposti `do_sample` su `True`, devi specificare un valore per uno dei seguenti parametri: `temperature`, `top_k`, `top_p` o `typical_p`.
+ `top_p`: controlla la casualità limitando il set di token da considerare nella generazione del token successivo. I valori più alti di `top_p` indicano un set che contiene un vocabolario più ampio. I valori più bassi limitano il set di token alle parole più probabili. Gli intervalli per `top_p` sono maggiori di `0` e minori di `1`.
+ `temperature`: controlla la casualità del testo generato. I valori più alti di `temperature` indicano al modello di generare risposte più casuali e diversificate. I valori più bassi generano risposte più prevedibili. I valori per `temperature` devono essere positivi.
+ `max_new_tokens`: limita la lunghezza della risposta contenendo il numero di token restituiti dal modello. L’impostazione predefinita è `20`.
+ `decoder_input_details`— Restituisce informazioni sulle probabilità di registro assegnate dal modello a ciascun potenziale token successivo e al token corrispondente. IDs Se `decoder_input_details` è impostato su `True`, devi impostare anche `details` su `True` per ricevere le informazioni richieste. L’impostazione predefinita è `False`.
Per ulteriori informazioni sui parametri per questo modello `Hugging Face`, consulta [types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8).
## Invio di una richiesta di inferenza di esempio
Per testare il modello, invia una richiesta di esempio al modello e stampa la risposta del modello come descritto di seguito:
```
response = predictor.predict(payload)
print(response[0]["generated_text"])
```
Nell’esempio di codice precedente, se il modello ha fornito la risposta `[{"response": "this is the output"}]`, l’istruzione `print` restituisce `this is the output`.
## Configura FMEval
1. Carica le librerie richieste per eseguirle FMEval come segue:
```
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. Configura i dati per il tuo set di dati di input.
Se non utilizzi un set di dati integrato, la configurazione dei dati deve identificare la colonna che contiene più bias in `sent_more_input_location`. Devi anche identificare la colonna che contiene meno bias in `sent_less_input_location`. Se si utilizza un set di dati integrato da JumpStart, questi parametri vengono passati FMEval automaticamente tramite i metadati del modello.
Specifica le colonne `sent_more_input_location` e `sent_less_input_location` per un’attività di stereotipizzazione dei prompt, oltre che per il nome, l’URI (Uniform Resource Identifier) e il tipo `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",
)
```
Per ulteriori informazioni sulle informazioni delle colonne richieste da altre attività, consulta la sezione **Utilizzo di un set di dati di input personalizzato** in [Utilizzo di un set di dati di input personalizzato](clarify-foundation-model-evaluate-auto-lib-custom.md#clarify-foundation-model-evaluate-auto-lib-custom-input).
1. Configura un `ModelRunner` personalizzato come mostrato nell’esempio di codice seguente:
```
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’esempio di codice precedente specifica quanto segue:
+ `endpoint_name`: il nome dell’endpoint creato nella fase precedente **Installazione delle librerie richieste**.
+ `model_id`: l’ID utilizzato per specificare il modello. Questo parametro è stato specificato al momento della definizione del JumpStart modello.
+ `model_version`: la versione del modello utilizzata per specificare il modello. Questo parametro è stato specificato al momento della definizione del JumpStart modello.
+ `output`: acquisisce l’output del [modello Falcon 7b](https://huggingface.co/tiiuae/falcon-7b), che restituisce la risposta in una chiave `generated_text`. Se il modello ha fornito la risposta `[{"generated_text": "this is the output"}]`, `[0].generated_text` restituisce `this is the output`.
+ `log_probability`— Cattura la probabilità logaritmica restituita da questo JumpStart modello.
+ `content_template`: specifica in che modo il modello interagisce con le richieste. Il modello di configurazione di esempio viene fornito esclusivamente per spiegare l’esempio precedente e non è obbligatorio. I parametri nel modello di contenuto sono gli stessi dichiarati per `payload`. Per ulteriori informazioni sui parametri per questo modello `Hugging Face`, consulta [types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8).
1. Configura il report di valutazione e salvalo in una directory come mostrato nel codice di esempio seguente:
```
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. Configura un fattore di parallelizzazione come descritto di seguito:
```
os.environ["PARALLELIZATION_FACTOR"] = "1"
```
`PARALLELIZATION_FACTOR` è un moltiplicatore per il numero di batch simultanei inviati all’istanza di calcolo. Se l’hardware consente la parallelizzazione, puoi impostare questo numero per moltiplicare il numero di invocazioni per il processo di valutazione. Ad esempio, se disponi di `100` invocazioni e `PARALLELIZATION_FACTOR` è impostato su `2`, il processo eseguirà `200` invocazioni. Puoi aumentare `PARALLELIZATION_FACTOR` fino a `10` o rimuovere completamente la variabile. Per leggere un blog sull'utilizzo di AWS Lambda, `PARALLELIZATION_FACTOR` consulta Nuovi [controlli di scalabilità AWS Lambda per le sorgenti di eventi Kinesis](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/) e DynamoDB.
## Esecuzione della valutazione del modello
1. Definisci il tuo algoritmo di valutazione. L’esempio seguente mostra come definire un algoritmo `PromptStereotyping`.
```
eval_algo = PromptStereotyping()
```
Per esempi di algoritmi che calcolano le metriche per altre attività di valutazione, consulta **Valutazione del modello** in [Utilizzo della libreria `fmeval` per eseguire una valutazione automatica](clarify-foundation-model-evaluate-auto-lib.md).
1. Esegui l’algoritmo di valutazione. L’esempio di codice seguente utilizza il modello e la configurazione dei dati precedentemente definiti, oltre a `prompt_template`, che utilizza `feature` per passare il prompt al modello nel modo seguente:
```
eval_output = eval_algo.evaluate(model=js_model_runner, dataset_config=config,
prompt_template="$feature", save=True)
```
L’output del modello potrebbe essere diverso dall’output di esempio precedente.
## Visualizzazione dei risultati dell’analisi
1. Analizza un report di valutazione dall’oggetto `eval_output` restituito dall’algoritmo di valutazione come descritto di seguito:
```
import json
print(json.dumps(eval_output, default=vars, indent=4))
```
Il comando precedente restituisce l’output seguente (ridotto per brevità):
```
[
{
"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’output di esempio precedente mostra un punteggio complessivo per il set di dati che segue `"name": prompt_stereotyping`. Questo punteggio rappresenta la differenza normalizzata in termini di probabilità logaritmiche tra la risposta del modello con **più** bias rispetto a una con meno bias. Se il punteggio è maggiore di `0.5`, significa che è più probabile che il modello restituisca una risposta che contiene più bias. Se il punteggio è minore di `0.5`, significa che è più probabile che il modello restituisca una risposta che contiene meno bias. Se il punteggio è `0.5`, la risposta del modello non contiene bias misurati dal set di dati di input. Nella fase seguente, utilizzerai `output_path` per creare `Pandas` `DataFrame`.
1. Importa i risultati e leggili in un `DataFrame`, quindi collega i punteggi di stereotipizzazione dei prompt all’input del modello, all’output del modello e all’output di destinazione come illustrato di seguito:
```
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
```
[Per un taccuino che contiene gli esempi di codice forniti in questa sezione, consulta .ipnyb. jumpstart-falcon-stereotyping](https://github.com/aws/fmeval/blob/main/examples/jumpstart-falcon-stereotyping.ipynb)
# Valutazione di un modello Amazon Bedrock per l’accuratezza della sintesi testuale
È possibile utilizzare un `ModelRunner` wrapper di alto livello per creare una valutazione personalizzata basata su un modello ospitato all'esterno di. JumpStart
Questo tutorial mostra come caricare il [modello Anthropic Claude 2](https://www.anthropic.com/index/claude-2), disponibile in Amazon Bedrock, e chiedere a questo modello di riepilogare i prompt di testo. Questo tutorial mostra anche come valutare l’accuratezza della risposta del modello utilizzando le metriche [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) e [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore).
Il tutorial spiega come:
+ Configurare l’ambiente.
+ Eseguire la valutazione del modello.
+ Visualizzare i risultati dell’analisi.
## Configurare l'ambiente
**Prerequisiti**
+ Utilizza un ambiente kernel Python 3.10 di base e un’istanza `ml.m5.2xlarge` di Amazon Elastic Compute Cloud (Amazon EC2) prima di iniziare il tutorial.
Per ulteriori informazioni sui tipi di istanze e sui relativi casi d’uso consigliati, consulta [Tipi di istanze disponibili per l'uso con i notebook Amazon SageMaker Studio Classic](notebooks-available-instance-types.md).
**Configurazione di Amazon Bedrock**
Prima di utilizzare un modello Amazon Bedrock, devi richiederne l’accesso.
1. Accedi al tuo. Account AWS
1. Se non disponi di un AWS account, consulta [Registrare un AWS account](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html#sign-up-for-aws) in **Configurare Amazon Bedrock**.
1. Apri la [console di Amazon Bedrock](https://console.aws.amazon.com/bedrock).
1. Nella sezione visualizzata **Ti diamo il benvenuto su Amazon Bedrock**, scegli **Gestisci l’accesso al modello**.
1. Nella sezione **Accesso al modello** visualizzata, scegli **Gestisci l’accesso al modello**.
1. Nella sezione **Modelli di base** visualizzata, seleziona la casella accanto a **Claude** nella sottosezione **Anthropic** di **Modelli**.
1. Scegli **Richiedi l’accesso al modello**.
1. Se la richiesta ha esito positivo, dovrebbe apparire un segno di spunta con **Accesso concesso** sotto **Stato di accesso** accanto al modello selezionato.
1. Potrebbe essere necessario accedere nuovamente al tuo account Account AWS per poter accedere al modello.
**Installazione delle librerie richieste**
1. Nel codice, installa le librerie `fmeval` e `boto3` come descritto di seguito:
```
!pip install fmeval
!pip3 install boto3==1.28.65
```
1. Importa le librerie, imposta un fattore di parallelizzazione e invoca un client Amazon Bedrock come descritto di seguito:
```
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')
```
Nell’esempio di codice precedente, si applica quanto segue:
+ `PARALLELIZATION_FACTOR`: un moltiplicatore per il numero di batch simultanei inviati all’istanza di calcolo. Se l’hardware consente la parallelizzazione, puoi impostare questo numero per moltiplicare il numero di invocazioni per il processo di valutazione. Ad esempio, se disponi di `100` invocazioni e `PARALLELIZATION_FACTOR` è impostato su `2`, il processo eseguirà `200` invocazioni. Puoi aumentare `PARALLELIZATION_FACTOR` fino a `10` o rimuovere completamente la variabile. Per leggere un blog sull'utilizzo di AWS Lambda, `PARALLELIZATION_FACTOR` consulta Nuovi [controlli di scalabilità Lambda per le sorgenti di eventi Kinesis](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/) e DynamoDB.
1. Scarica il set di dati `JSON Lines` di esempio [sample-dataset.jsonl](https://github.com/aws/fmeval/blob/8da27af2f20369fd419c03d5bb0707ab24010b14/examples/xsum_sample.jsonl) nella directory di lavoro corrente.
1. Verifica che il tuo ambiente contenga il file di input di esempio come descritto di seguito:
```
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")
```
**Invio di una richiesta di inferenza di esempio al modello**
1. Definisci il modello e il tipo `MIME` del prompt. Per un [modello Anthropic Claude 2](https://www.anthropic.com/index/claude-2) ospitato su Amazon Bedrock, il prompt deve essere strutturato come descritto di seguito:
```
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:
"""
```
Per ulteriori informazioni su come strutturare il corpo della richiesta, consulta [Model invocation request body field](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html#model-parameters-claude-request-body). Altri modelli possono avere formati diversi.
1. Invia una richiesta di esempio al tuo modello. Il corpo della richiesta contiene il prompt e tutti i parametri aggiuntivi da impostare. Di seguito è riportato un esempio di richiesta con `max_tokens_to_sample` impostato su `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"))
```
Nell’esempio di codice precedente, puoi impostare i parametri seguenti:
+ `temperature`: controlla la casualità del testo generato e accetta valori positivi. I valori più alti di `temperature` indicano al modello di generare risposte più casuali e diversificate. I valori più bassi generano risposte più prevedibili. Gli intervalli per `temperature` sono compresi tra `0` e `1`, con un valore predefinito di 0,5.
+ `topP`: controlla la casualità limitando il set di token da considerare nella generazione del token successivo. I valori più alti di `topP` producono un set che contiene un vocabolario più ampio, mentre i valori più bassi limitano il set di token alle parole più probabili. Gli intervalli per `topP` sono compresi tra `0` e `1`, con un valore predefinito di `1`.
+ `topK`: limita le previsioni tramite modello ai primi `k` token più probabili. I valori più alti `topK` indicano risposte più creative. I valori più bassi generano risposte più coerenti. Gli intervalli per `topK` sono compresi tra `0` e `500`, con un valore predefinito di `250`.
+ `max_tokens_to_sample`: limita la lunghezza della risposta contenendo il numero di token restituiti dal modello. Gli intervalli per `max_tokens_to_sample` sono compresi tra `0` e `4096`, con un valore predefinito di `200`.
+ `stop_sequences`: specifica un elenco di sequenze di caratteri che indicano al modello di arrestare la generazione di una risposta. L’output del modello viene arrestato la prima volta che una delle stringhe elencate viene rilevata nell’output. La risposta non contiene la sequenza di arresto. Ad esempio, puoi utilizzare una sequenza di ritorno a capo per limitare la risposta del modello a una sola riga. Puoi configurare fino a `4` sequenze di arresto.
Per ulteriori informazioni sui parametri che puoi specificare in una richiesta, consulta [Modelli Anthropic Claude](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html).
**Configurare FMEval**
1. Carica le librerie richieste per eseguirle FMEval come segue:
```
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. Configura i dati per il tuo set di dati di input.
Il seguente input di esempio è composto da una sola riga di `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’input di esempio precedente contiene il testo da sintetizzare all’interno della chiave `document`. Il riferimento rispetto al quale valutare la risposta del modello si trova nella chiave `summary`. È necessario utilizzare queste chiavi all'interno della configurazione dei dati per specificare quali colonne contengono le informazioni FMEval necessarie per valutare la risposta del modello.
La configurazione dei dati deve identificare il testo che il modello deve sintetizzare in `model_input_location`. Devi identificare il valore di riferimento con `target_output_location`.
L’esempio seguente di configurazione dei dati si riferisce al precedente esempio di input, nel quale vengono specificati le colonne richieste per un’attività di sintesi testuale, il nome, l’URI (Uniform Resource Identifier) e il tipo `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"
)
```
Per ulteriori informazioni sulle informazioni delle colonne richieste per altre attività, consulta la sezione **Utilizzo di un set di dati di input personalizzato** in [Valutazione automatica del modello](clarify-foundation-model-evaluate-auto.md).
1. Configura un `ModelRunner` personalizzato come mostrato nell’esempio di codice seguente:
```
bedrock_model_runner = BedrockModelRunner(
model_id=model_id,
output='completion',
content_template='{"prompt": $prompt, "max_tokens_to_sample": 500}'
)
```
L’esempio di codice precedente specifica quanto segue:
+ `model_id`: l’ID utilizzato per specificare il modello.
+ `output`: acquisisce l’output del modello [Anthropic Claude 2](https://www.anthropic.com/index/claude-2), che restituisce la risposta in una chiave `completion`.
+ `content_template`: specifica in che modo il modello interagisce con le richieste. Il modello di configurazione di esempio viene fornito esclusivamente per spiegare l’esempio precedente e non è obbligatorio.
+ Nell’esempio `content_template` precedente, si applica quanto segue:
+ La variabile `prompt` specifica il prompt di input che acquisisce la richiesta effettuata dall’utente.
+ La variabile `max_tokens_to_sample` specifica che il numero massimo di token è `500`, per limitare la lunghezza della risposta.
Per ulteriori informazioni sui parametri che puoi specificare nella richiesta, consulta [Modelli Anthropic Claude](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html).
Il formato del parametro `content_template` dipende dagli input e dai parametri supportati dal tuo LLM. In questo tutorial, il [modello Anthropic Claude 2](https://www.anthropic.com/index/claude-2) utilizza `content_template`, riportato di seguito:
```
"content_template": "{\"prompt\": $prompt, \"max_tokens_to_sample\": 500}"
```
Un altro esempio è il [modello Falcon 7b](https://huggingface.co/tiiuae/falcon-7b) che può supportare il `content_template` seguente:
```
"content_template": "{\"inputs\": $prompt, \"parameters\":{\"max_new_tokens\": \
10, \"top_p\": 0.9, \"temperature\": 0.8}}"
```
## Esecuzione della valutazione del modello
**Definizione ed esecuzione dell’algoritmo di valutazione**
1. Definisci il tuo algoritmo di valutazione. L’esempio seguente mostra come definire un algoritmo `SummarizationAccuracy`, utilizzato per determinare l’accuratezza delle attività di sintesi testuale:
```
eval_algo = SummarizationAccuracy(SummarizationAccuracyConfig())
```
Per esempi di algoritmi che calcolano le metriche per altre attività di valutazione, consulta **Valutazione del modello** in [Utilizzo della libreria `fmeval` per eseguire una valutazione automatica](clarify-foundation-model-evaluate-auto-lib.md).
1. Esegui l’algoritmo di valutazione. L’esempio di codice seguente utilizza la configurazione dei dati definita in precedenza, oltre a `prompt_template`, che utilizza le chiavi `Human` e `Assistant`:
```
eval_output = eval_algo.evaluate(model=bedrock_model_runner,
dataset_config=config,
prompt_template="Human: $feature\n\nAssistant:\n", save=True)
```
Nell’esempio di codice precedente, `feature` contiene il prompt nel formato previsto dal modello Amazon Bedrock.
## Visualizzazione dei risultati dell’analisi
1. Analizza un report di valutazione dall’oggetto `eval_output` restituito dall’algoritmo di valutazione come descritto di seguito:
```
# parse report
print(json.dumps(eval_output, default=vars, indent=4))
```
Il comando precedente restituisce il seguente output:
```
[
{
"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’output di esempio precedente mostra i tre punteggi di accuratezza [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) e [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore), il valore `prompt_template` di input, un valore `category_score` (se è stato richiesto), gli eventuali errori e il valore `output_path`. Nella fase seguente, utilizzerai `output_path` per creare `Pandas DataFrame`.
1. Importa i risultati e leggili in un `DataFrame`, quindi collega i punteggi di accuratezza all’input del modello, all’output del modello e all’output di destinazione come descritto di seguito:
```
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
```
In questa invocazione, l’esempio di codice precedente restituisce il seguente output (contratto per brevità):
```
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 ...
...
```
L’output del modello potrebbe essere diverso dall’output di esempio precedente.
Per un taccuino che contiene gli esempi di codice forniti in questa sezione, vedete [bedrock-claude-summarization-accuracy.ipnyb.](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-summarization-accuracy.ipynb)
## Notebook aggiuntivi
La GitHub directory [fmeval](https://github.com/aws/fmeval/tree/main/examples) contiene i seguenti taccuini di esempio aggiuntivi:
+ [bedrock-claude-factual-knowledge.ipnyb](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-factual-knowledge.ipynb) — Valuta un [modello Anthropic Claude 2](https://www.anthropic.com/index/claude-2) ospitato su Amazon Bedrock per una conoscenza fattuale.
+ [byo-model-outputs.ipynb: valuta un modello Falcon 7b](https://github.com/aws/fmeval/blob/main/examples/byo-model-outputs.ipynb) [ospitato su di esso JumpStart per acquisire conoscenze fattuali, in cui è possibile inserire gli output del modello](https://huggingface.co/tiiuae/falcon-7b) anziché inviare richieste di inferenza al modello.
+ [custom\$1model\$1runner\$1chat\$1gpt.ipnyb](https://github.com/aws/fmeval/blob/main/examples/custom_model_runner_chat_gpt.ipynb): valuta un modello `ChatGPT 3.5` personalizzato ospitato su `Hugging Face` per le conoscenze fattuali.
# Risolvi gli errori durante la creazione di un processo di valutazione del modello in Amazon SageMaker AI
**Importante**
Per utilizzare SageMaker Clarify Foundation Model Evaluations (FMEval), è necessario eseguire l'aggiornamento alla nuova esperienza Studio.
A partire dal 30 novembre 2023, la precedente esperienza Amazon SageMaker Studio è ora denominata Amazon SageMaker Studio Classic. FMEval non è disponibile in Amazon SageMaker Studio Classic.
Per informazioni su come eseguire l’aggiornamento alla nuova esperienza di Studio, consulta [Migrazione da Amazon SageMaker Studio Classic](studio-updated-migrate.md). Per informazioni sull’utilizzo dell’applicazione Studio Classic, consulta [Amazon SageMaker Studio Classic](studio.md).
Se riscontri un errore durante la creazione di un processo di valutazione del modello, utilizza l’elenco seguente per risolverlo. Se hai bisogno di ulteriore assistenza, contatta uno dei [SupportoAWS](https://console.aws.amazon.com/support/)[nostri forum per sviluppatori per Amazon SageMaker AI](https://forums.aws.amazon.com/forum.jspa?forumID=285).
**Argomenti**
+ [Errore durante il caricamento dei dati da un bucket Amazon S3](#clarify-foundation-model-evaluate-troubleshooting-cors)
+ [Il processo di elaborazione non è stato completato](#clarify-foundation-model-evaluate-troubleshooting-failure)
+ [Non riesci a trovare le valutazioni dei modelli di base nella console di SageMaker intelligenza artificiale](#clarify-foundation-model-evaluate-troubleshooting-upgrade)
+ [Il tuo modello non supporta la stereotipizzazione dei prompt](#clarify-foundation-model-evaluate-troubleshooting-ps)
+ [Errori di convalida dei set di dati (umani)](#clarify-foundation-model-evaluate-troubleshooting-valid)
## Errore durante il caricamento dei dati da un bucket Amazon S3
Quando crei una valutazione del modello di fondazione, devi impostare le autorizzazioni corrette per il bucket S3 in cui archiviare l’input e l’output del modello. Se le autorizzazioni Cross-Origin Resource Sharing (CORS) non sono impostate correttamente, SageMaker AI genera il seguente errore:
Errore: impossibile inserire l'oggetto in s3: errore durante il caricamento dell'oggetto su S3Errore: impossibile inserire l'oggetto in S3: durante il tentativo di recuperare la risorsa. NetworkError
Per impostare le autorizzazioni corrette per il bucket, segui le istruzioni riportate nella sezione **Configurazione dell’ambiente** in [Creazione di un processo di valutazione automatica del modello in Studio](clarify-foundation-model-evaluate-auto-ui.md).
## Il processo di elaborazione non è stato completato
I motivi più comuni per cui il processo di elaborazione non viene completato sono:
+ [Quota insufficiente](#clarify-foundation-model-evaluate-troubleshooting-failure-quota)
+ [Memoria insufficiente](#clarify-foundation-model-evaluate-troubleshooting-failure-memory)
+ [Controllo ping non superato](#clarify-foundation-model-evaluate-troubleshooting-failure-ping)
Consulta le sezioni seguenti per informazioni sulla mitigazione dei problemi.
### Quota insufficiente
Quando esegui una valutazione del modello di base per un modello non distribuito, SageMaker Clarify distribuisce il tuo Large Language JumpStart Model (LLM) su un endpoint di intelligenza artificiale del tuo account. SageMaker Se il vostro account non dispone di una quota sufficiente per eseguire il JumpStart modello selezionato, il processo fallisce con un. `ClientError` Segui questa procedura per aumentare la tua quota:
**Richiedi un aumento delle AWS Service Quotas**
1. Recupera il nome dell’istanza, la quota corrente e la quota necessaria dal messaggio di errore visualizzato sullo schermo. Ad esempio, nell’errore seguente:
+ Il nome dell’istanza è `ml.g5.12xlarge`.
+ La quota corrente, indicata dal numero che segue `current utilization`, è `0 instances`.
+ La quota aggiuntiva richiesta, indicata dal numero che segue `request delta`, è `1 instances`.
Di seguito è riportato l’errore di esempio:
`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. Accedi Console di gestione AWS e apri la console [Service Quotas](https://console.aws.amazon.com/servicequotas/home).
1. Nel riquadro di navigazione, in **Gestisci quote**, inserisci **Amazon SageMaker AI**.
1. Scegli **Visualizza quote**.
1. Nella barra di ricerca in **Service Quotas**, inserisci il nome dell’istanza della Fase 1. Ad esempio, utilizzando le informazioni contenute nel messaggio di errore della Fase 1, immetti **ml.g5.12xlarge**.
1. Scegli il **nome della quota** che appare accanto al nome dell’istanza e termina con **per l’utilizzo dell’endpoint**. Ad esempio, utilizzando le informazioni contenute nel messaggio di errore della Fase 1, scegli **ml.g5.12xlarge per l’utilizzo dell’endpoint**.
1. Scegli **Richiedi un aumento a livello di account**.
1. In **Aumenta il valore della quota**, inserisci la quota richiesta necessaria tra le informazioni fornite nel messaggio di errore della Fase 1. Inserisci il **totale** di `current utilization` e `request delta`. Nell’errore di esempio precedente, `current utilization` è `0 Instances` e `request delta` è `1 Instances`. In questo esempio, richiedi una quota di `1` per ottenere la quota richiesta.
1. Scegli **Richiedi**.
1. Scegli **Cronologia delle richieste di quote** nel riquadro di navigazione.
1. Quando lo **stato** passa da **In sospeso** ad **Approvato**, esegui nuovamente il processo. Potrebbe essere necessario aggiornare il browser per visualizzare la modifica.
Per ulteriori informazioni sulla richiesta di un aumento della quota, consulta [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html).
### Memoria insufficiente
Se avvii una valutazione del modello di fondazione su un’istanza Amazon EC2 che non dispone di memoria sufficiente per eseguire un algoritmo di valutazione, il processo non riesce con il seguente errore:
`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.`
Per aumentare la memoria disponibile per il processo di valutazione, passa a un’istanza con più memoria. Se utilizzi l’interfaccia utente, puoi scegliere un tipo di istanza in **Configurazione del processore** nella **Fase 2**. Se esegui il tuo lavoro all'interno della console SageMaker AI, avvia un nuovo spazio utilizzando un'istanza con maggiore capacità di memoria.
Per un elenco di istanze Amazon EC2, consulta [Tipi di istanze](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes).
Per ulteriori informazioni sulle istanze con una maggiore capacità di memoria, consulta [Istanze ottimizzate per la memoria](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/memory-optimized-instances.html).
### Controllo ping non superato
In alcuni casi, il processo di valutazione del modello di base fallirà perché non ha superato un controllo di ping durante l'implementazione dell'endpoint da parte dell' SageMaker IA. Se non supera un test di ping, viene visualizzato il seguente errore:
`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 `
Se il processo genera questo errore, attendi qualche minuto ed esegui nuovamente il processo. Se l'errore persiste, contatta [AWS Support](https://console.aws.amazon.com/support/) o [AWS Developer Forums for Amazon SageMaker AI](https://forums.aws.amazon.com/forum.jspa?forumID=285).
## Non riesci a trovare le valutazioni dei modelli di base nella console di SageMaker intelligenza artificiale
Per utilizzare SageMaker Clarify Foundation Model Evaluations, è necessario eseguire l'aggiornamento alla nuova esperienza Studio. A partire dal 30 novembre 2023, la precedente esperienza Amazon SageMaker Studio è ora denominata Amazon SageMaker Studio Classic. La funzionalità di valutazione dei modelli di fondazione può essere utilizzata solo nell’esperienza aggiornata. Per informazioni su come aggiornare Studio, consulta [Migrazione da Amazon SageMaker Studio Classic](studio-updated-migrate.md).
## Il tuo modello non supporta la stereotipizzazione dei prompt
Solo alcuni JumpStart modelli supportano gli stereotipi immediati. Se si seleziona un JumpStart modello non supportato, viene visualizzato il seguente errore:
`{"evaluationMetrics":"This model does not support Prompt stereotyping evaluation. Please remove that evaluation metric or select another model that supports it."}`
Se si riceve questo errore, non è possibile utilizzare il modello selezionato in una valutazione di base. SageMaker Clarify sta attualmente lavorando per aggiornare tutti i JumpStart modelli per consentire rapide attività di stereotipizzazione in modo che possano essere utilizzati nella valutazione di un modello di base.
## Errori di convalida dei set di dati (umani)
Il set di dati dei prompt personalizzato in un processo di valutazione del modello con lavoratori umani deve essere formattato utilizzando il formato JSON Lines con l’estensione `.jsonl`.
Quando avvii un processo, ogni oggetto JSON nel set di dati dei prompt viene convalidato in modo interdipendente. Se uno degli oggetti JSON non è valido, viene visualizzato il seguente errore.
```
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.
```
Affinché un set di dati dei prompt personalizzato superi tutte le convalide, è necessario che quanto segue sia *true* per tutti gli oggetti JSON nel file JSON Lines.
+ Ogni riga nel file del set di dati dei prompt deve essere un oggetto JSON valido.
+ I caratteri speciali come le virgolette (`"`) devono essere sottoposti correttamente a escape. Ad esempio, se il prompt fosse `"Claire said to the crowd, "Bananas are the best!""`, le virgolette dovrebbero essere sottoposte a escape con `\`, quindi `"Claire said to the crowd, \"Bananas are the best!\""`.
+ Un oggetto JSON valido deve contenere almeno la coppia chiave-valore `prompt`.
+ Un file del set di dati dei prompt non può contenere più di 1.000 oggetti JSON in un singolo file.
+ Se specifichi la chiave `responses` in un *qualsiasi* oggetto JSON, questa deve essere presente in *tutti* gli oggetti JSON.
+ Il numero massimo di oggetti nella chiave `responses` è 1. Se hai risposte da più modelli che intendi confrontare, ciascuna richiederà un set di dati BYOI separato.
+ Se specifichi la chiave `responses` in un *qualsiasi* oggetto JSON, questa deve contenere anche le chiavi `modelIdentifier` e `text` e in *tutti* gli oggetti `responses`.
# Valutazione e confronto dei modelli di classificazione SageMaker JumpStart del testo di Amazon
SageMaker JumpStart L'intelligenza artificiale offre diversi modelli di classificazione del testo che classificano il testo in classi predefinite. Questi modelli gestiscono attività come l’analisi del sentiment, la classificazione degli argomenti e la moderazione dei contenuti. La scelta del modello giusto per la produzione richiede un’attenta valutazione dell’utilizzo di metriche chiave tra cui accuratezza, punteggio F1 e Coefficiente di correlazione di Matthews (MCC).
In questa guida:
+ Implementa più modelli di classificazione del testo (DistilBert e BERT) dal catalogo. JumpStart
+ Esegui valutazioni complete su set di dati bilanciati, disallineati e complessi.
+ Interpreta metriche avanzate, tra cui i punteggi Coefficiente di correlazione di Matthews (MCC) e Area sotto la curva ROC (Receiver Operating Characteristic).
+ Prendi decisioni sulla selezione dei modelli basate sui dati utilizzando framework di confronto sistematici.
+ Configura implementazioni di produzione con auto-scaling e monitoraggio. CloudWatch
Scarica il framework di valutazione completo: [JumpStart Model Evaluation Package](samples/sagemaker-text-classification-evaluation-2.zip). **Il pacchetto include i risultati pre-esecuzione con output di esempio** che ti permettono di visualizzare in anteprima il processo di valutazione e le metriche prima di implementare autonomamente i modelli.
## Prerequisiti
Prima di iniziare, assicurati di disporre di:
+ [AWS account con autorizzazioni SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html).
+ [SageMaker Accesso AI ad Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html).
+ Conoscenze base di Python.
+ Comprensione dei concetti di classificazione del testo.
Tempi e costo: 45 minuti in totale. I costi variano in base al tipo di istanza e alla durata dell'utilizzo: consulta [i prezzi di SageMaker AI](https://aws.amazon.com/sagemaker/pricing/) per le tariffe attuali.
Questo tutorial include istruzioni di step-by-step pulizia per aiutarti a rimuovere tutte le risorse ed evitare addebiti continui.
**Topics**
+ [Prerequisiti](#w2aac37c15c11)
+ [Configurazione dell’ambiente di valutazione](jumpstart-text-classification-setup.md)
+ [Selezione e implementazione dei modelli di classificazione del testo](jumpstart-text-classification-deploy.md)
+ [Valutazione e confronto delle prestazioni dei modelli](jumpstart-text-classification-evaluate.md)
+ [Interpretazione dei risultati](jumpstart-text-classification-interpret.md)
+ [Implementazione del modello su larga scala](jumpstart-text-classification-scale.md)
# Configurazione dell’ambiente di valutazione
Configura SageMaker AI Studio per accedere ai JumpStart modelli per la valutazione della classificazione del testo. Questa sezione descrive la configurazione delle autorizzazioni e i costi associati prima di implementare i modelli.
## Prerequisiti
Prima di iniziare, assicurati di avere un AWS account con autorizzazioni SageMaker AI. Per le istruzioni sulla configurazione dell'account, consulta [Configurare i prerequisiti SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html).
## Configura SageMaker AI Studio per la valutazione JumpStart del modello
Se non hai accesso a SageMaker AI Studio, consulta [Configurazione rapida](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html) per creare un dominio.
Per iniziare con il tuo progetto di classificazione del testo in SageMaker Studio:
1. Apri il pannello di controllo di SageMaker AI Studio.
1. Seleziona il tuo profilo utente.
1. Scegli **Apri Studio**.
1. Attendi il caricamento di Studio (potrebbero essere necessari 2-3 minuti al primo avvio).
1. Verifica che JumpStart appaia nel pannello di navigazione a sinistra.
## Comprensione dei costi dell' SageMaker IA
Quando utilizzi SageMaker AI Studio, devi sostenere dei costi per:
+ SageMaker Hosting di endpoint AI (varia in base al tipo e alla durata dell'istanza).
+ Archiviazione di Amazon S3 per set di dati e artefatti di modelli.
+ Runtime delle istanze Notebook (alcuni utilizzi sono coperti dal piano AWS gratuito per gli account idonei).
**Nota**
L’utilizzo dell’interfaccia Studio non comporta alcun costo aggiuntivo.
### Consigli per la gestione dei costi
Segui questi consigli per ridurre al minimo i costi durante la valutazione:
+ Utilizza le istanze predefinite specificate per i modelli DistilBERT e BERT.
+ Elimina gli endpoint immediatamente dopo la valutazione.
+ Monitora il tuo utilizzo con [Calcolatore dei prezzi AWS](https://aws.amazon.com/calculator.aws/#/addService/SageMaker).
+ Per i prezzi di archiviazione correnti, consulta [Prezzi di Amazon Simple Storage Service](https://aws.amazon.com/s3/pricing/).
**avvertimento**
Al termine del tutorial, assicurati di chiudere gli endpoint e di pulire le risorse per evitare addebiti continui.
Continua su [Selezione e implementazione dei modelli di classificazione del testo](jumpstart-text-classification-deploy.md).
# Selezione e implementazione dei modelli di classificazione del testo
Implementa due modelli di classificazione del testo per il confronto: DistilBERT Base Cased e BERT Base Uncased. Vedrai le differenze tra questi modelli e li distribuirai utilizzando la configurazione ottimale dell’istanza.
## Perché questi due modelli
Questi modelli rappresentano la decisione tipica che i clienti devono affrontare in produzione in termini di prestazioni e costi:
+ **BERT Base Uncased**: più grande e preciso, ma anche più lento e dispendioso in termini di risorse.
+ **DistilBERT Base Cased**: più piccolo, più veloce, più economico, ma potenzialmente meno preciso.
Questo confronto ti aiuta a scegliere il modello giusto per le tue esigenze specifiche.
## Informazioni sui nomi dei modelli nel catalogo
I nomi dei modelli di classificazione del testo nel catalogo includono i seguenti componenti:
+ BERT: Bidirectional Encoder Representations from Transformers.
+ L-X\$1H-Y\$1A-Z: struttura del modello, dove
+ L-X: è il numero di livelli (X).
+ H-Y: è la dimensione nascosta (Y).
+ A-Z: è il numero di teste di attenzione (Z).
+ Small/Base/Large: Dimensioni e complessità del modello.
+ Uncased/Cased: impostazione della distinzione tra lettere maiuscole e minuscole.
Esempio: `Small BERT L-2_H-128_A-2` indica un piccolo modello BERT con:
+ 2 livelli.
+ 128 unità nascoste.
+ 2 teste di attenzione.
## Accedi al catalogo dei JumpStart modelli
Passa ai modelli di classificazione del testo nel JumpStart catalogo.
1. Apri SageMaker AI Studio
1. Nel riquadro di navigazione a sinistra, scegliere **JumpStart**.
1. Nella JumpStart pagina, scegli **Hugging Face**.
1. Scegli **Classificazione del testo**.
Dovresti vedere un elenco di modelli di classificazione del testo disponibili nel catalogo, comprese le varianti DistilBERT e BERT.
## Implementazione di DistilBERT Base Cased
Implementa il modello DistilBERT utilizzando la configurazione predefinita.
1. Nell’elenco dei modelli, trova e scegli **DistilBERT Base Cased** (di distilbert).
1. Nella pagina dei dettagli del modello, mantieni il tipo di istanza predefinito.
1. Mantieni tutte le altre impostazioni predefinite e scegli **Implementa**.
1. Attendi 5-10 minuti per il completamento dell’implementazione.
1. Per verificare la corretta esecuzione dell’implementazione, vai a **Implementazioni**, quindi a **Endpoint**.
1. Verifica che lo stato dell’endpoint DistilBERT sia `InService`.
## Implementazione di BERT Base Uncased
Implementa il modello BERT per il confronto con DistilBERT.
1. Torna ai modelli di classificazione del testo Hugging Face in. JumpStart
1. Trova e scegli **BERT Base Uncased** (di google-bert).
1. Mantieni il tipo di istanza predefinito e scegli **Implementa**.
1. Per confermare entrambe le implementazioni, verifica che entrambi gli endpoint mostrino lo stato `InService` nell’elenco degli endpoint.
Entrambi i modelli appaiono nell’elenco degli endpoint con lo stato `InService`.
**Importante**
Copia e salva i nomi degli endpoint. Saranno necessari per il processo di valutazione.
## Risoluzione dei problemi
Se riscontri problemi di implementazione:
+ Per gli errori di tipo di istanza, verifica di utilizzare il tipo di istanza predefinito e non le istanze CPU come `ml.m5.large`.
+ Se non riesci a trovare i modelli, esegui la ricerca utilizzando i nomi esatti dei modelli, incluso il publisher tra parentesi.
+ In caso di implementazioni non riuscite, controlla lo stato di integrità del servizio nella tua Regione o prova un’altra Regione.
Una volta che lo stato del modello è `InService`, passa a [Valutazione e confronto delle prestazioni dei modelli](jumpstart-text-classification-evaluate.md) per valutare il modello implementato.
# Valutazione e confronto delle prestazioni dei modelli
Valuta i modelli di classificazione del testo implementati utilizzando il framework di valutazione. Il framework supporta modalità di valutazione supervisionate e non supervisionate grazie a un approccio basato su notebook.
## Utilizzo di set di dati integrati
**Consigliamo di utilizzare il set di dati di valutazione supervisionato integrato** per questo tutorial, poiché la maggior parte degli utenti non dispone di dati di valutazione etichettati. I set di dati integrati forniscono un’analisi completa delle prestazioni in diversi scenari:
+ **Set di dati bilanciati**: distribuzione equa delle classi per le prestazioni baseline.
+ **Set di dati disallineati**: classi squilibrate per i test effettivi.
+ **Set di dati complessi**: casi limite per testare la robustezza del modello.
La valutazione genera metriche chiave tra cui i punteggi di accuratezza, precisione, richiamo, punteggio F1, Coefficiente di correlazione di Matthews (MCC) e Area sotto la curva ROC con curve visive per il confronto dei modelli.
## Utilizzo di dati personalizzati
Se disponi di un set di dati etichettato, puoi sostituirlo nel notebook. Il framework si adatta automaticamente al formato dei tuoi dati e genera le stesse metriche complete.
**Formati dei dati supportati:**
+ **Formato CSV:** due colonne, `text` e `label`
+ **Formati di etichetta:** “positivo”/“negativo”, “LABEL\$10”/“LABEL\$11”, “True”/“False” o “0”/“1”
+ **Non supervisionato:** colonna `text` singola per l’analisi dell’attendibilità
## Configurazione dell’ambiente di valutazione
Crea uno JupyterLab spazio in SageMaker Amazon SageMaker Studio per eseguire il notebook di valutazione.
1. In Studio, scegli **JupyterLab**dalla schermata principale.
1. Se non disponi di uno spazio:
1. Scegli **Crea spazio**.
1. Inserisci un nome descrittivo (ad esempio, **TextModelEvaluation)**.
1. Mantieni il tipo di istanza predefinito.
1. Scegli **Esegui lo spazio**.
1. Una volta creato lo spazio, scegli **Apri JupyterLab**.
### Accesso al notebook di valutazione
Scarica il [file .zip](samples/sagemaker-text-classification-evaluation-2.zip) ed estrailo sul computer locale. Carica l'intera cartella estratta nel tuo JupyterLab spazio per iniziare a testare i tuoi modelli. Il pacchetto contiene il notebook di valutazione principale, i set di dati di esempio, i moduli Python di supporto e istruzioni dettagliate per il framework di valutazione completo.
**Nota**
Dopo aver estratto il pacchetto, consulta il file README per le istruzioni di configurazione dettagliate e una panoramica del framework.
Passa a [Interpretazione dei risultati](jumpstart-text-classification-interpret.md) per scoprire come analizzare l’output della valutazione e prendere decisioni in merito alla selezione dei modelli basate sui dati.
# Interpretazione dei risultati
Analizza le metriche di valutazione derivate dal confronto dei modelli di classificazione del testo per prendere decisioni basate sui dati per l’implementazione in produzione.
## Informazioni sulle metriche di valutazione
La valutazione fornisce diverse metriche chiave per ogni modello in tutti i set di dati:
### Accuratezza
Misura la percentuale di previsioni corrette e funziona meglio con i set di dati bilanciati. Tuttavia, può essere fuorviante con dati squilibrati e può mostrare risultati sovrastimati quando una classe è predominante.
### Precisione
Valuta la capacità del modello di evitare i falsi positivi misurando in che percentuale le previsioni positive si sono rivelate corrette. Questa metrica va da 0,0 a 1,0 (valori più alti indicano prestazioni migliori) e diventa essenziale quando i falsi positivi sono costosi.
### Recupero
Valuta l’efficacia del modello nel rilevare tutti i casi positivi misurando la percentuale di veri positivi rilevata. Va da 0,0 a 1,0 (valori più alti indicano prestazioni migliori) e diventa essenziale quando il mancato rilevamento dei positivi è costoso.
### Punteggio F1
Fornisce la media armonica di precisione e richiamo, bilanciando entrambe le metriche in un unico punteggio compreso tra 0,0 e 1,0 (valori più alti indicano prestazioni migliori).
### Coefficiente di correlazione di Matthews (MCC)
Misura la qualità complessiva della classificazione binaria e si presenta come metrica ottimale per i dati squilibrati. Va da -1,0 a 1,0 (valori più alti indicano prestazioni migliori) e 0 rappresenta un’ipotesi casuale.
### Area sotto la curva ROC (Receiver Operating Characteristic)
Valuta la precisione con cui il modello distingue le classi. Va da 0,0 a 1,0, dove 1,0 rappresenta una classificazione perfetta e 0,5 rappresenta un’ipotesi casuale.
### Tempo medio di inferenza
Misura la velocità di previsione, che diventa fondamentale per le applicazioni in tempo reale. Considera sia la velocità che la coerenza nella valutazione di questa metrica.
**Nota**
Non ti affidare esclusivamente all’accuratezza quando scegli il modello. Per set di dati squilibrati, le metriche di precisione, richiamo e MCC forniscono gli indicatori più attendibili per le prestazioni reali.
## Confronto delle prestazioni tra diversi tipi di set di dati
Il **set di dati bilanciato** mostra le prestazioni dei modelli in condizioni ideali con una rappresentazione uguale di esempi positivi e negativi. Se le prestazioni sono alte, il modello ha appreso i modelli fondamentali di classificazione del testo.
Il **set di dati disallineato** rivela in che modo i modelli gestiscono lo squilibrio di classe reale, cosa comune negli scenari di produzione.
I test per i **set di dati complessi** verificano la robustezza del modello su casi ambigui o limite che potrebbero apparire in produzione.
## Selezione del modello
Utilizza questo approccio sistematico per selezionare il modello ottimale per il tuo caso d’uso specifico.
### Definizione delle priorità aziendali
Prima di scegliere un modello, stabilisci quali sono i fattori più importanti in termini di prestazioni per il tuo caso d’uso.
1. Identifica i tuoi requisiti di accuratezza e la soglia di prestazioni minima accettabile.
1. Determina i tuoi vincoli di latenza, ad esempio se è necessaria l’elaborazione in tempo reale (<100 ms) o in batch.
1. Elabora le tue considerazioni su costi e budget per l’inferenza e il dimensionamento.
1. Analizza le caratteristiche dei dati per capire se i dati di produzione sono bilanciati, disallineati o altamente variabili.
### Quando scegliere i singoli modelli
Sulla base dei risultati della valutazione, scegli il modello che si adatta meglio al tuo caso d’uso:
+ **Scegli DistilBERT** se hai bisogno di inferenze più rapide e sufficientemente accurate, ad esempio per l’analisi del sentiment in tempo reale nei chatbot del servizio clienti, nei sistemi di moderazione dei contenuti o nelle applicazioni in cui è essenziale un tempo di risposta inferiore a 100 ms.
+ **Scegli BERT** quando la massima accuratezza è più importante della velocità, come la classificazione di documenti legali, l’analisi di testi medici o le applicazioni di conformità in cui la precisione è fondamentale e l’elaborazione in batch è accettabile.
### Assegnazione delle priorità ai set di dati di valutazione
Concentrati sui set di dati che meglio rappresentano il tuo caso d’uso reale.
1. Dai più peso al set di dati più simile ai dati del mondo reale.
1. Valuta l’importanza dei casi limite nella tua applicazione e assegna di conseguenza una priorità alle prestazioni per i set di dati complessi.
1. Bilancia l’ottimizzazione tra più scenari anziché concentrarti su un solo tipo di set di dati.
Confronta i risultati della valutazione rispetto a queste priorità per selezionare il modello che bilancia al meglio i tuoi requisiti di accuratezza, velocità e costi.
Ora che hai selezionato il tuo modello preferito, puoi passare all’implementazione in produzione. Continua su [Implementazione del modello su larga scala](jumpstart-text-classification-scale.md).
# Implementazione del modello su larga scala
Configura l'auto-scaling CloudWatch e il monitoraggio per il SageMaker tuo endpoint AI per renderlo pronto per la produzione.
## Perché il monitoraggio della produzione è importante per la classificazione del testo
I carichi di lavoro di classificazione del testo richiedono il monitoraggio perché:
+ Sono soggetti a modelli di traffico variabili con picchi di elaborazione.
+ Richiedono tempi di risposta inferiori al secondo.
+ Hanno bisogno di ottimizzare i costi attraverso il dimensionamento automatico.
## Prerequisiti
Prima di iniziare, assicurati di avere:
+ Il tuo endpoint di SageMaker intelligenza artificiale implementato nella sezione precedente.
+ Il nome del tuo endpoint (ad esempio,). jumpstart-dft-hf-tc
+ Il tuo Regione AWS (ad esempio, us-east-2).
Per la creazione o la risoluzione dei problemi degli endpoint, consulta [Inferenza in tempo reale](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html).
## Configurazione del monitoraggio in produzione
Configura CloudWatch il monitoraggio per monitorare le prestazioni del modello in produzione.
1. Nel tuo JupyterLab spazio, apri il `sagemaker_production_monitoring.ipynb` taccuino dal pacchetto di valutazione che hai caricato in precedenza.
1. Aggiorna il nome e la Regione dell’endpoint nella sezione di configurazione.
1. Per la configurazione, segui le istruzioni del notebook:
+ Dimensionamento automatico (1-10 istanze in base al traffico).
+ CloudWatch allarmi per le soglie di latenza e invocazione.
+ Dashboard di metriche per il monitoraggio visivo.
## Verifica della configurazione
Dopo aver completato le fasi del notebook, verifica di avere:
+ **Stato dell’endpoint**: `InService`.
+ **Dimensionamento automatico**: 1-10 istanze configurate.
+ **CloudWatch Allarmi: monitoraggio di 2 allarmi.**
+ **Metriche**: oltre 15 metriche registrate.
**Nota**
All’inizio, gli allarmi possono visualizzare `INSUFFICIENT_DATA`. È un comportamento normale e il campo diventerà `OK` con l’utilizzo.
## Monitoraggio dell’endpoint
Accedi al monitoraggio visivo tramite la console di AWS gestione:
+ [CloudWatch Parametri](https://console.aws.amazon.com/cloudwatch/home#metricsV2:graph=~();query=AWS/SageMaker)
+ [CloudWatch Allarmi](https://console.aws.amazon.com/cloudwatch/home#alarmsV2:)
Per ulteriori informazioni, consulta [Monitor SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-overview.html).
## Gestione dei costi e pulizia delle risorse
La configurazione di monitoraggio fornisce preziose informazioni sulla produzione, ma comporta anche AWS costi continui attraverso CloudWatch metriche, allarmi e politiche di auto-scaling. Comprendere come gestire questi costi è essenziale per operazioni economicamente convenienti. Elimina le risorse quando non sono più necessarie.
**avvertimento**
L’endpoint continua a comportare costi anche quando non elabora le richieste. Per arrestare tutti gli addebiti, è necessario eliminare l’endpoint. Per istruzioni, consulta [Eliminazione di endpoint e risorse](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html).
[Per configurazioni di monitoraggio avanzate, consulta Metrics for AI. CloudWatch SageMaker ](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-cloudwatch.html)
# Equità, spiegabilità dei modelli e rilevamento dei pregiudizi con Clarify SageMaker
Puoi usare Amazon SageMaker Clarify per comprendere l'equità e la spiegabilità dei modelli e per spiegare e rilevare errori nei tuoi modelli. Puoi configurare un processo di elaborazione SageMaker Clarify per calcolare metriche di distorsioni e attribuzioni di funzionalità e generare report per la spiegabilità del modello. SageMaker I processi di elaborazione di Clarify vengono implementati utilizzando un'immagine del contenitore Clarify specializzata. SageMaker La pagina seguente descrive come funziona SageMaker Clarify e come iniziare con un'analisi.
## Cosa sono l’equità e la spiegabilità dei modelli per le previsioni di machine learning?
I modelli di machine learning (ML) contribuiscono a prendere decisioni in diversi settori, come quello dei servizi finanziari, dell’assistenza sanitaria, dell’istruzione e delle risorse umane. Policy maker, organismi di regolamentazione e avvocati hanno cercato di sensibilizzare l’opinione pubblica sulle sfide etiche e in materia di policy poste dal machine learning e dai sistemi basati sui dati. Amazon SageMaker Clarify può aiutarti a capire perché il tuo modello di machine learning ha creato una previsione specifica e se questa distorsione influisce su questa previsione durante l'addestramento o l'inferenza. SageMaker Clarify fornisce anche strumenti che possono aiutarti a creare modelli di machine learning meno distorti e più comprensibili. SageMaker Clarify può anche generare report sulla governance dei modelli da fornire ai team di gestione dei rischi e della conformità e alle autorità di regolamentazione esterne. Con SageMaker Clarify, puoi fare quanto segue:
+ Rilevare i bias e spiegare le previsioni tramite modello.
+ Identificare i tipi di bias nei dati di preaddestramento.
+ Identificare nei dati di post-addestramento i tipi di bias che possono emergere durante l’addestramento o quando il modello è in produzione.
SageMaker Clarify aiuta a spiegare in che modo i modelli effettuano previsioni utilizzando le attribuzioni di funzionalità. Monitora anche i modelli di inferenza in produzione per rilevare derive dei bias o dell’attribuzione delle funzionalità. Queste informazioni possono aiutarti nelle aree seguenti:
+ **Normativa**: policy maker e altri organismi di regolamentazione possono avere preoccupazioni riguardo agli impatti discriminatori delle decisioni basate sugli output provenienti da modelli di ML. Ad esempio, un modello di ML può codificare i bias e influenzare una decisione automatizzata.
+ **Aziende**: i domini regolamentati possono richiedere spiegazioni attendibili sulle modalità di generazione delle previsioni dei modelli di ML. La spiegabilità dei modelli può essere particolarmente importante per i settori che dipendono dall’affidabilità, dalla sicurezza e dalla conformità. Tra questi figurano servizi finanziari, risorse umane, assistenza sanitaria e trasporti automatizzati. Ad esempio, le applicazioni per i prestiti potrebbero dover spiegare a responsabili dei prestiti, analisti e clienti in che modo i modelli di ML hanno prodotto determinate previsioni.
+ **Data science**: i Data Scientist e gli ingegneri di ML possono eseguire il debug e migliorare i modelli di ML quando riescono a determinare se un modello sta effettuando inferenze basate su caratteristiche rumorose o irrilevanti. Possono anche comprendere i limiti dei propri modelli e i tipi di errore in cui potrebbero incorrere i modelli.
Per un post sul blog che mostra come progettare e creare un modello di machine learning completo per reclami automobilistici fraudolenti che integri SageMaker Clarify in una pipeline di SageMaker intelligenza artificiale, consulta [Architect e crea l'intero ciclo di vita dell'apprendimento automatico con AWS:](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) Una demo di Amazon AI. end-to-end SageMaker Questo post di blog spiega come valutare e mitigare i bias prima e dopo l’addestramento, oltre a descrivere l’impatto delle funzionalità sulla previsione tramite modello. Il post di blog contiene link a codice di esempio per ogni attività nel ciclo di vita di ML.
### Best practice per valutare l’equità e la spiegabilità nel ciclo di vita di ML
**L’equità come processo**: i concetti di bias ed equità dipendono fortemente dall’applicazione. La misurazione del bias e la scelta delle metriche sui bias possono essere guidate da considerazioni sociali, legali e di altro tipo non tecnico. Un’adozione efficace degli approcci di ML consapevoli dell’equità prevede la creazione del consenso e una solida collaborazione tra le principali parti interessate. Questi possono includere prodotti, policy, aspetti legali, tecnici, AI/ML team, utenti finali e community.
**Equità e spiegabilità fin dalla progettazione nel ciclo di vita di ML**: tieni in considerazione l’equità e la spiegabilità in ogni fase del ciclo di vita di ML. Queste fasi includono la formazione dei problemi, la costruzione del set di dati, la selezione degli algoritmi, il processo di addestramento dei modelli, il processo di test, l’implementazione, il monitoraggio e il feedback. È importante disporre degli strumenti giusti per eseguire questa analisi. Ti consigliamo di porre le seguenti domande durante il ciclo di vita di ML:
+ Il modello incoraggia cicli di feedback che possono produrre risultati sempre più di parte?
+ Un algoritmo è una soluzione etica al problema?
+ I dati di addestramento sono rappresentativi di diversi gruppi?
+ Ci sono bias nelle etichette o nelle funzionalità?
+ I dati devono essere modificati per mitigare i bias?
+ I vincoli di equità devono essere inclusi nella funzione obiettivo?
+ Il modello è stato valutato utilizzando metriche di equità pertinenti?
+ Gli effetti sono diversi tra i vari utenti?
+ Il modello è utilizzato su una popolazione per la quale non è stato addestrato o valutato?
![\[Best practice per valutare l'equità e la spiegabilità del modello.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify-best-practices-image.png)
### Guida alle spiegazioni sull' SageMaker intelligenza artificiale e alla documentazione sui pregiudizi
I bias possono verificarsi ed essere misurati nei dati sia prima che dopo l’addestramento di un modello. SageMaker Clarify può fornire spiegazioni per le previsioni dei modelli dopo la formazione e per i modelli implementati in produzione. SageMaker Clarify può anche monitorare i modelli in produzione per rilevare eventuali variazioni nelle loro attribuzioni esplicative di base e calcolare le linee di base quando necessario. La documentazione per spiegare e rilevare i pregiudizi utilizzando Clarify è strutturata come segue: SageMaker
+ Per informazioni sulla configurazione di un processo di elaborazione per bias e spiegabilità, consulta [Configurazione di un processo di elaborazione SageMaker Clarify](clarify-processing-job-configure-parameters.md).
+ Per informazioni sul rilevamento dei bias durante la pre-elaborazione dei dati, eseguita prima che questi vengano utilizzati per addestrare un modello, consulta [Bias dei dati di preaddestramento](clarify-detect-data-bias.md).
+ Per informazioni sul rilevamento dei bias nei dati di post-addestramento e nel modello, consulta [Bias dei modelli e dei dati di post-addestramento](clarify-detect-post-training-bias.md).
+ Per informazioni sull’approccio di attribuzione delle funzionalità indipendente dal modello per spiegare le previsioni tramite modello dopo l’addestramento, consulta [Spiegabilità del modello](clarify-model-explainability.md).
+ Per informazioni sul monitoraggio della deriva dell’attribuzione delle funzionalità rispetto alla baseline specificata durante l’addestramento dei modelli, consulta [Deriva dell’attribuzione delle funzionalità per i modelli in produzione](clarify-model-monitor-feature-attribution-drift.md).
+ Per informazioni sul monitoraggio dei modelli in produzione per rilevare la deriva della baseline, consulta [Deriva dei bias per i modelli in produzione](clarify-model-monitor-bias-drift.md).
+ Per informazioni su come ottenere spiegazioni in tempo reale da un SageMaker endpoint di intelligenza artificiale, consulta. [Spiegabilità online con Clarify SageMaker](clarify-online-explainability.md)
## Come funzionano i lavori di elaborazione di SageMaker Clarify
Puoi utilizzare SageMaker Clarify per analizzare i set di dati e i modelli per verificarne la spiegabilità e gli errori. Un processo di elaborazione SageMaker Clarify utilizza il contenitore di elaborazione SageMaker Clarify per interagire con un bucket Amazon S3 contenente i set di dati di input. Puoi anche utilizzare SageMaker Clarify per analizzare un modello di cliente distribuito su un endpoint di inferenza AI. SageMaker
Il grafico seguente mostra come un processo di elaborazione SageMaker Clarify interagisce con i dati di input e, facoltativamente, con un modello del cliente. Questa interazione dipende dal tipo specifico di analisi eseguita. Il contenitore di elaborazione SageMaker Clarify ottiene il set di dati di input e la configurazione per l'analisi da un bucket S3. Per determinati tipi di analisi, inclusa l'analisi delle feature, il contenitore di elaborazione SageMaker Clarify deve inviare le richieste al contenitore del modello. Quindi recupera le previsioni del modello dalla risposta inviata dal container del modello. Successivamente, il contenitore di elaborazione SageMaker Clarify calcola e salva i risultati dell'analisi nel bucket S3.
![\[SageMaker Clarify può analizzare i dati o un modello di cliente per verificarne la spiegabilità e gli errori.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify/clarify-processing-job.png)
È possibile eseguire un processo di elaborazione SageMaker Clarify in più fasi del ciclo di vita del flusso di lavoro di apprendimento automatico. SageMaker Clarify può aiutarvi a calcolare i seguenti tipi di analisi:
+ Metriche sui bias di preaddestramento. Le metriche sui bias preaddestramento possono aiutarti a comprendere i bias presenti nei dati in modo da correggerli e addestrare il modello su un set di dati più equo. Per informazioni sulle metriche sui bias di preaddestramento, consulta [Metriche di bias pre-addestramento](clarify-measure-data-bias.md). Per eseguire un processo di analisi dei parametri di bias prima dell'addestramento, devi fornire il set di dati e un file di configurazione dell'analisi JSON a [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
+ Metriche sui bias di post-addestramento. Le metriche sui bias post-addestramento possono aiutarti a comprendere eventuali bias introdotti da un algoritmo, le scelte degli iperparametri o qualsiasi bias che non era precedentemente visibile nel flusso. Per ulteriori informazioni sulle metriche relative ai pregiudizi post-allenamento, consulta. [Metriche sui bias dei modelli e dei dati di post-addestramento](clarify-measure-post-training-bias.md) SageMaker Clarify utilizza le previsioni del modello oltre ai dati e alle etichette per identificare i pregiudizi. Per eseguire un processo di analisi dei parametri di bias post-addestramento, è necessario fornire il set di dati e un file di configurazione dell'analisi JSON. La configurazione deve includere il nome del modello o dell'endpoint.
+ I valori Shapely per la spiegabilità possono aiutarti a capire l’impatto della funzionalità sulle previsioni del tuo modello. Per ulteriori informazioni sui valori Shapley, consulta [Caratterizzazione delle attribuzioni che utilizzano i valori Shapley](clarify-shapley-values.md). Questa funzionalità richiede un modello addestrato.
+ Grafici di dipendenza parziale (PDPs), che possono aiutarvi a capire quanto cambierebbe la variabile target prevista se variassi il valore di una feature. Per ulteriori informazioni su PDPs, consulta [PDPsAnalisi dei grafici di dipendenza parziale ()](clarify-processing-job-analysis-results.md#clarify-processing-job-analysis-results-pdp) Questa funzionalità richiede un modello addestrato.
SageMaker Clarify necessita di previsioni basate su modelli per calcolare le metriche di distorsione post-allenamento e l'attribuzione delle funzionalità. *È possibile fornire un endpoint oppure SageMaker Clarify creerà un endpoint temporaneo utilizzando il nome del modello, noto anche come endpoint ombra.* Il contenitore SageMaker Clarify elimina l'endpoint shadow dopo il completamento dei calcoli. A un livello elevato, il contenitore SageMaker Clarify completa i seguenti passaggi:
1. Convalida input e parametri.
1. Crea l'endpoint shadow (se viene fornito un nome di modello).
1. Carica il set di dati di input in un frame di dati.
1. Ottiene le previsioni del modello dall'endpoint, se necessario.
1. Calcola i parametri di bias e le attribuzioni delle funzionalità.
1. Elimina l'endpoint shadow.
1. Genera i risultati dell'analisi.
Una volta completato il processo di elaborazione di SageMaker Clarify, i risultati dell'analisi verranno salvati nella posizione di output specificata nel parametro di output di elaborazione del lavoro. Questi risultati includono un file JSON con parametri di bias e attribuzioni di funzionalità globali, un report visivo e file aggiuntivi per le attribuzioni di funzionalità locali. È possibile scaricare i risultati dalla posizione di output e visualizzarli.
Per ulteriori informazioni sulle metriche dei pregiudizi, sulla spiegabilità e su come interpretarle, consulta Scopri [come Amazon SageMaker Clarify aiuta a rilevare bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias), Fairness [Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf) e il white paper [Amazon](https://pages.awscloud.com/rs/112-TZM-766/images/Amazon.AI.Fairness.and.Explainability.Whitepaper.pdf) AI Fairness and Explainability.
# Configurazione di un processo di elaborazione SageMaker Clarify
Per analizzare i dati e i modelli per verificare eventuali distorsioni e spiegabilità utilizzando SageMaker Clarify, è necessario configurare un processo di elaborazione Clarify. SageMaker Questa guida mostra come specificare il nome del set di dati di input, il nome del file di configurazione dell'analisi e la posizione di output per un processo di elaborazione. Per configurare il container di elaborazione, gli input, gli output, le risorse e altri parametri del processo, sono disponibili due opzioni. Puoi utilizzare l'`CreateProcessingJob`API SageMaker AI o utilizzare l'API SageMaker AI Python SDK, `SageMaker ClarifyProcessor`
Per informazioni sui parametri comuni a tutti i processi di elaborazione, consulta [Amazon SageMaker API Reference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp).
## Configura un processo di elaborazione SageMaker Clarify utilizzando l'API SageMaker
Le seguenti istruzioni mostrano come fornire ciascuna parte della configurazione specifica di SageMaker Clarify utilizzando l'`CreateProcessingJob`API.
1. Inserite l'Uniform Research Identifier (URI) di un'immagine del contenitore SageMaker Clarify all'interno del `AppSpecification` parametro, come mostrato nel seguente esempio di codice.
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**Nota**
L'URI deve identificare un'immagine del contenitore SageMaker Clarify preconfigurata. `ContainerEntrypoint`e non `ContainerArguments` sono supportati. Per ulteriori informazioni sulle immagini dei contenitori SageMaker Clarify, [Contenitori Clarify predefiniti SageMaker](clarify-processing-job-configure-container.md) consultate.
1. Specifica sia la configurazione per l'analisi che i parametri per il set di dati di input all'interno del parametro `ProcessingInputs`.
1. Specifica la posizione del file di configurazione dell'analisi JSON, che include i parametri per l'analisi dei bias e l'analisi della spiegabilità. Il parametro `InputName` dell'oggetto `ProcessingInput` deve essere **analysis\$1config** come mostrato nel seguente esempio di codice.
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
Per ulteriori informazioni sullo schema del file di configurazione dell’analisi, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
1. Specifica la posizione del set di dati di input. Il parametro `InputName` dell'oggetto `ProcessingInput` deve essere `dataset`. Questo parametro è facoltativo se hai fornito "dataset\$1uri" nel file di configurazione dell'analisi. Nella configurazione `S3Input` sono richiesti i seguenti valori.
1. `S3Uri` può essere un oggetto Amazon S3 o un prefisso S3.
1. `S3InputMode` deve essere di tipo **File**.
1. `S3CompressionType` deve essere di tipo `None` (il valore predefinito).
1. `S3DataDistributionType` deve essere di tipo `FullyReplicated` (il valore predefinito).
1. `S3DataType` può essere `S3Prefix` o `ManifestFile`. Per utilizzarlo`ManifestFile`, il `S3Uri` parametro deve specificare la posizione di un file manifest che segue lo schema riportato nella sezione [S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri) di riferimento all' SageMaker API. Questo file manifest deve elencare gli oggetti S3 che contengono i dati di input per il processo.
Il codice seguente mostra un esempio di configurazione di input.
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. Specifica la configurazione per l'output del processo di elaborazione all'interno del parametro `ProcessingOutputConfig`. Nella configurazione `Outputs` è richiesto un singolo oggetto `ProcessingOutput`. Per la configurazione di output sono richiesti i seguenti elementi:
1. `OutputName` deve essere **analysis\$1result**.
1. `S3Uri` deve essere un prefisso S3 per la posizione di output.
1. `S3UploadMode` deve essere impostato su **EndOfJob**.
Il seguente codice mostra un esempio di configurazione di output.
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. Specifica la configurazione `ClusterConfig` per le risorse utilizzate nel processo di elaborazione all'interno del parametro `ProcessingResources`. I seguenti parametri sono obbligatori all'interno dell'oggetto `ClusterConfig`.
1. `InstanceCount` specifica il numero di istanze di calcolo nel cluster che esegue il processo di elaborazione. Per attivare l'elaborazione distribuita, specifica un valore maggiore di `1`.
1. `InstanceType` si riferisce alle risorse che eseguono il processo di elaborazione. Poiché l'analisi SageMaker AI SHAP richiede molte risorse di calcolo, l'utilizzo di un tipo di istanza ottimizzato per il calcolo dovrebbe migliorare il tempo di esecuzione dell'analisi. Il processo di elaborazione SageMaker Clarify non utilizza. GPUs
Il seguente codice mostra un esempio di configurazione delle risorse.
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. Specifica la configurazione della rete utilizzata nel processo di elaborazione all'interno dell'oggetto `NetworkConfig`. Nella configurazione sono richiesti i seguenti valori.
1. `EnableNetworkIsolation`deve essere impostato su `False` (impostazione predefinita) in modo che SageMaker Clarify possa richiamare un endpoint, se necessario, per le previsioni.
1. Se il modello o l'endpoint che hai fornito al job SageMaker Clarify si trova all'interno di un Amazon Virtual Private Cloud (Amazon VPC), anche il job SageMaker Clarify deve trovarsi nello stesso VPC. Specificare il VPC utilizzando. [VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html) Inoltre, il VPC deve disporre di endpoint per un bucket Amazon S3, un servizio AI e un servizio SageMaker AI Runtime. SageMaker
Se è attivata l'elaborazione distribuita, è necessario consentire anche la comunicazione tra diverse istanze nello stesso processo di elaborazione. Configura una regola per il gruppo di sicurezza che consente connessioni in entrata tra i membri dello stesso gruppo di sicurezza. Per ulteriori informazioni, consulta [Offri ad Amazon SageMaker Clarify Jobs l'accesso alle risorse nel tuo Amazon VPC](clarify-vpc.md).
Il codice seguente mostra un esempio di configurazione della rete.
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. Imposta il tempo massimo di esecuzione del processo utilizzando il parametro `StoppingCondition`. Il periodo massimo di esecuzione di un job di SageMaker Clarify è di giorni o secondi. `7` `604800` Se il lavoro non può essere completato entro questo limite di tempo, verrà interrotto e non verranno forniti risultati di analisi. Ad esempio, la configurazione seguente limita il tempo massimo di esecuzione del processo a 3600 secondi.
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. Specifica un ruolo IAM per il parametro `RoleArn`. Il ruolo deve avere un rapporto di fiducia con Amazon SageMaker AI. Può essere utilizzato per eseguire le operazioni SageMaker API elencate nella tabella seguente. Ti consigliamo di utilizzare la policy gestita di Amazon SageMaker AIFull Access, che garantisce l'accesso completo all' SageMaker intelligenza artificiale. Per ulteriori informazioni su questa policy, consulta [AWS politica gestita: AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess). Se hai dubbi sulla concessione dell'accesso completo, le autorizzazioni minime richieste dipendono dall'eventuale fornitura di un modello o un nome di endpoint. L'utilizzo di un nome di endpoint consente di concedere meno autorizzazioni all'IA. SageMaker
La tabella seguente contiene le operazioni API utilizzate dal processo di elaborazione di SageMaker Clarify. **X** in **Nome modello** e **Nome endpoint** indica l'operazione API richiesta per ogni input.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
Per ulteriori informazioni sulle autorizzazioni richieste, consultare [Autorizzazioni API Amazon SageMaker AI: riferimento ad azioni, autorizzazioni e risorse](api-permissions-reference.md).
Per ulteriori informazioni sul passaggio di ruoli all' SageMaker IA, consulta. [Passaggio dei ruoli](sagemaker-roles.md#sagemaker-roles-pass-role)
Dopo aver creato le singole parti della configurazione del processo di elaborazione, combinale per configurare il processo.
## Configurare un processo di elaborazione SageMaker Clarify utilizzando l' AWS SDK per Python
Il seguente esempio di codice mostra come avviare un processo di elaborazione SageMaker Clarify utilizzando l'[AWS SDK per 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",
)
```
Per un notebook di esempio con istruzioni per eseguire un processo di elaborazione SageMaker Clarify utilizzando AWS SDK per Python, consulta [Fairness and Explainability with](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb) Clarify using SDK for Python. SageMaker AWS Qualsiasi bucket S3 utilizzato nel notebook deve trovarsi nella stessa regione dell'istanza del notebook che vi accede. AWS
## Configurare un processo di elaborazione SageMaker Clarify utilizzando l'SDK SageMaker Python
È inoltre possibile configurare un processo di elaborazione SageMaker Clarify utilizzando l'[SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)API SageMaker Python SDK. Per ulteriori informazioni, consulta [Esegui SageMaker Clarify Processing Jobs per l'analisi e la spiegabilità dei pregiudizi](clarify-processing-job-run.md).
**Topics**
+ [Contenitori Clarify predefiniti SageMaker](clarify-processing-job-configure-container.md)
+ [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md)
+ [Guida alla compatibilità di formato dei dati](clarify-processing-job-data-format.md)
# Contenitori Clarify predefiniti SageMaker
Amazon SageMaker AI fornisce immagini predefinite dei container SageMaker Clarify che includono le librerie e altre dipendenze necessarie per calcolare le metriche di distorsione e le attribuzioni di funzionalità ai fini della spiegabilità. [Queste immagini sono in grado di eseguire processi di elaborazione Clarify nel tuo account. SageMaker ](processing-job.md)
L'immagine URIs dei contenitori ha il seguente formato:
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
Esempio:
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
La tabella seguente elenca gli indirizzi per Regione AWS.
Immagini Docker per SageMaker Clarify Processing Jobs
| Region | Indirizzo dell'immagine |
| --- | --- |
| Stati Uniti orientali (Virginia settentrionale) | 205585389593.dkr. ecr.us-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Stati Uniti orientali (Ohio) | 211330385671.dkr. ecr.us-east-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Stati Uniti occidentali (California settentrionale) | 740489534195.dkr. ecr.us-west-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Stati Uniti occidentali (Oregon) | 306415355426.dkr. ecr.us-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Hong Kong) | 098760798382.dkr. ecr.ap-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Mumbai) | 452307495513.dkr. ecr.ap-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Giacarta) | 705930551576.dkr. ecr.ap-southeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Tokyo) | 377024640650.dkr. ecr.ap-northeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Seul) | 263625296855.dkr. ecr.ap-northeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Osaka) | 912233562940.dkr. ecr.ap-northeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Singapore) | 834264404009.dkr. ecr.ap-southeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Asia Pacifico (Sydney) | 007051062584.dkr. ecr.ap-southeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Canada (Centrale) | 675030665977.dkr. ecr.ca-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Francoforte) | 017069133835.dkr. ecr.eu-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Zurigo) | 730335477804.dkr. ecr.eu-central-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Irlanda) | 131013547314.dkr. ecr.eu-west-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Londra) | 440796970383.dkr. ecr.eu-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Parigi) | 341593696636dkr. ecr.eu-west-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Stoccolma) | 763603941244.dkr. ecr.eu-north-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Medio Oriente (Bahrein) | 835444307964.dkr. ecr.me-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Sud America (San Paolo) | 520018980103.dkr. ecr.sa-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Africa (Città del Capo) | 811711786498.dkr. ecr.af-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Milano) | 638885417683.dkr. ecr.eu-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Cina (Pechino) | 122526803553.dkr. ecr.cn-north-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
| Cina (Ningxia) | 122578899357.dkr. ecr.cn-northwest-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
# File di configurazione dell’analisi
Per analizzare i dati e i modelli per verificarne la spiegabilità e le distorsioni utilizzando Clarify, è necessario configurare un processo di elaborazione. SageMaker Parte della configurazione per questo processo di elaborazione include la configurazione di un file di analisi. Il file di analisi specifica i parametri per l'analisi dei bias e la spiegabilità. Per informazioni su come configurare un processo di elaborazione e un file di analisi, consulta [Configurazione di un processo di elaborazione SageMaker Clarify](clarify-processing-job-configure-parameters.md).
La presente guida descrive lo schema e i parametri per questo file di configurazione dell'analisi. Questa guida include anche esempi di file di configurazione dell’analisi per il calcolo delle metriche sui bias per un set di dati tabulare e per la generazione di spiegazioni relative a problemi di elaborazione del linguaggio naturale (NLP), visione artificiale (CV) e serie temporali (TS).
Puoi creare il file di configurazione dell'analisi o utilizzare [SageMaker Python SDK](https://sagemaker.readthedocs.io/) per generarne uno per te con l'API. [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor) La visualizzazione del contenuto del file può essere utile per comprendere la configurazione sottostante utilizzata dal job SageMaker Clarify.
**Topics**
+ [Schema per il file di configurazione dell'analisi](#clarify-processing-job-configure-schema)
+ [File di configurazione dell'analisi di esempio](#clarify-processing-job-configure-analysis-examples)
## Schema per il file di configurazione dell'analisi
La sezione seguente descrive lo schema per il file di configurazione dell'analisi, inclusi i requisiti e le descrizioni dei parametri.
### Schema per il file di configurazione dell'analisi
Il processo di elaborazione SageMaker Clarify prevede che il file di configurazione dell'analisi sia strutturato con i seguenti requisiti:
+ Il nome di input dell'elaborazione deve essere `analysis_config.`.
+ Il file di configurazione dell'analisi è in formato JSON e codificato in UTF-8.
+ Il file di configurazione dell'analisi è un oggetto Amazon S3.
È possibile specificare parametri aggiuntivi nel file di configurazione dell'analisi. La sezione seguente fornisce varie opzioni per personalizzare il processo di elaborazione di SageMaker Clarify in base al caso d'uso e ai tipi di analisi desiderati.
### Parametri per i file di configurazione dell'analisi
È possibile specificare parametri nel file di configurazione dell'analisi.
+ **version**: (facoltativo) la stringa della versione dello schema del file di configurazione dell'analisi. Se non viene fornita una versione, SageMaker Clarify utilizza l'ultima versione supportata. Attualmente la sola versione supportata è `1.0`.
+ **dataset\$1type**: il formato del set di dati. Il formato del set di dati di input può essere uno dei seguenti valori:
+ Tabulare
+ `text/csv` per CSV
+ `application/jsonlines`per il formato [SageMaker denso AI JSON Lines](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)
+ `application/json` per JSON
+ `application/x-parquet` per Apache Parquet
+ `application/x-image` per attivare la spiegabilità dei problemi di visione artificiale
+ Spiegazioni del modello di previsione delle serie temporali
+ `application/json` per JSON
+ **dataset\$1uri**: (facoltativo) l'Uniform Resource Identifier (URI) del set di dati principale. Se fornite un prefisso URI S3, il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file S3 che si trovano sotto il prefisso. È possibile fornire un prefisso URI S3 o un URI S3 a un file manifesto di immagini per problemi di visione artificiale. Se fornito, `dataset_uri` ha la precedenza sull'input del processo di elaborazione del set di dati. **Per qualsiasi tipo di formato, ad eccezione dei casi d'uso di immagini e serie temporali, il processo di elaborazione SageMaker Clarify carica il set di dati di input in un frame di dati tabulare, come set di dati tabulare.** Questo formato consente all' SageMaker intelligenza artificiale di manipolare e analizzare facilmente il set di dati di input.
+ **headers**: (facoltativo)
+ **Tabular**: un array di stringhe che contiene i nomi delle colonne di un set di dati tabulare. Se non viene fornito un valore, il processo di elaborazione SageMaker Clarify `headers` legge le intestazioni dal set di dati. Se il set di dati non ha intestazioni, il processo di elaborazione di Clarify genera automaticamente nomi segnaposto basati sull’indice delle colonne a base zero. Ad esempio, i nomi segnaposto per la prima e la seconda colonna saranno **column\$10** e **column\$11**, e così via.
**Nota**
Per convenzione, se `dataset_type` è `application/jsonlines` o `application/json`, `headers` dovrebbe contenere i seguenti nomi nell’ordine specificato:
nomi delle funzionalità
nome dell’etichetta (se `label` è specificato)
nome dell’etichetta previsto (se `predicted_label` è specificato)
Un esempio per `headers` per un tipo di set di dati `application/jsonlines` se `label` è specificato è: `["feature1","feature2","feature3","target_label"]`.
+ **Time series:** un elenco di nomi di colonne nel set di dati. Se non viene fornito, Clarify genera intestazioni da utilizzare internamente. Per i casi di spiegabilità delle serie temporali, fornisci le intestazioni nel seguente ordine:
1. id elemento
1. timestamp
1. serie temporali di destinazione
1. tutte le colonne delle serie temporali correlate
1. tutte le colonne covariate statiche
+ **label**: (facoltativo) una stringa o un indice intero a base zero. Se fornito, `label` viene utilizzato per individuare l'etichetta Ground Truth, nota anche come etichetta osservata o attributo di destinazione in un set di dati tabulare. L'etichetta Ground Truth viene utilizzata per calcolare i parametri di bias. Il valore di `label` viene specificato in base al valore del parametro `dataset_type` nel modo seguente.
+ Se `dataset_type` è **text/csv**, `label` può essere specificato in uno dei seguenti modi:
+ Un nome colonna valido
+ Un indice che si trova all'interno dell'intervallo delle colonne del set di dati
+ Se `dataset_type` è **application/parquet**, `label` deve essere un nome colonna valido.
+ In caso `dataset_type` affermativo**application/jsonlines**, `label` deve essere un'[JMESPath](https://jmespath.org/)espressione scritta per estrarre l'etichetta di verità fondamentale dal set di dati. Per convenzione, se `headers` è specificato, deve contenere il nome dell'etichetta.
+ In caso `dataset_type` **application/json** affermativo, `label` deve essere un'[JMESPath](https://jmespath.org/)espressione scritta per estrarre l'etichetta di verità fondamentale per ogni record nel set di dati. Questa JMESPath espressione deve produrre un elenco di etichette in cui i l'etichetta è correlata a quelle del record.
+ **predicted\$1label**: (facoltativo) una stringa o un indice intero a base zero. Se fornito, `predicted_label` viene utilizzato per individuare la colonna contenente l'etichetta prevista in un set di dati tabulare. L'etichetta prevista viene utilizzata per calcolare i **parametri di bias** post-addestramento. Il parametro `predicted_label` è facoltativo se il set di dati non include l'etichetta prevista. Se per il calcolo sono necessarie le etichette previste, il processo di elaborazione di SageMaker Clarify otterrà le previsioni dal modello.
Il valore di `predicted_label` viene specificato in base al valore di `dataset_type` come segue:
+ Se `dataset_type` è **text/csv**, `predicted_label` può essere specificato come segue:
+ Un nome colonna valido. Se `predicted_label_dataset_uri` è specificato, ma `predicted_label` non viene fornito, il nome dell'etichetta prevista di default è "predicted\$1label".
+ Un indice che si trova all'interno dell'intervallo delle colonne del set di dati. Se `predicted_label_dataset_uri` è specificato, l'indice viene utilizzato per individuare la colonna dell'etichetta prevista nel set di dati dell'etichetts prevista.
+ Se dataset\$1type è **application/x-parquet**, `predicted_label` deve essere un nome colonna valido.
+ Se dataset\$1type è**application/jsonlines**, `predicted_label` deve essere un'[JMESPath](https://jmespath.org/)espressione valida scritta per estrarre l'etichetta prevista dal set di dati. Per convenzione, se `headers` è specificato, deve contenere il nome dell'etichetta prevista.
+ In caso `dataset_type` affermativo**application/json**, `predicted_label` deve essere scritta un'[JMESPath](https://jmespath.org/)espressione per estrarre l'etichetta prevista per ogni record nel set di dati. L' JMESPath espressione dovrebbe produrre un elenco di etichette previste in cui i l'etichetta prevista è per loro nel record.
+ **features** — (Facoltativo) Obbligatorio per i casi non-time-series d'uso se `dataset_type` è `application/jsonlines` o`application/json`. Un'espressione JMESPath stringa scritta per individuare le funzionalità nel set di dati di input. Infatti`application/jsonlines`, verrà applicata un' JMESPath espressione a ciascuna riga per estrarre le caratteristiche di quel record. Infatti`application/json`, un' JMESPath espressione verrà applicata all'intero set di dati di input. L' JMESPath espressione dovrebbe estrarre un elenco di elenchi o un 2D array/matrix di funzionalità in cui la riga i contiene le caratteristiche correlate a tali elementi nel record. Per un `dataset_type` di `text/csv` o `application/x-parquet`, tutte le colonne, tranne le colonne dell'etichetta Ground Truth e dell'etichetta prevista, vengono assegnate automaticamente come funzionalità.
+ **predicted\$1label\$1dataset\$1uri**: (facoltativo) applicabile solo quando dataset\$1type è `text/csv`. L'URI S3 per un set di dati contenente le etichette previste utilizzate per calcolare i **parametri di bias** post-addestramento. Il processo di elaborazione di SageMaker Clarify caricherà le previsioni dall'URI fornito invece di ottenere le previsioni dal modello. In questo caso, `predicted_label` è necessario per individuare la colonna dell'etichetta prevista nel set di dati dell'etichetta prevista. Se il set di dati dell'etichetta prevista o il set di dati principale è suddiviso in più file, `joinsource_name_or_index` deve specificare una colonna identificativa per unire i due set di dati.
+ **predicted\$1label\$1headers**: (facoltativo) applicabile solo quando `predicted_label_dataset_uri` è specificato. Una matrice di stringhe contenente i nomi colonne del set di dati dell'etichetta prevista. Oltre all'intestazione dell'etichetta prevista, `predicted_label_headers` può contenere anche l'intestazione della colonna identificativa per unire il set di dati dell'etichetta prevista e il set di dati principale. Per ulteriori informazioni, consulta la descrizione del parametro `joinsource_name_or_index`.
+ **joinsource\$1name\$1or\$1index**: (facoltativo) il nome o l’indice a base zero della colonna nei set di dati tabulari da utilizzare come colonna identificativa durante l’esecuzione di un join interno. Questa colonna viene utilizzata solo come identificatore. Non viene utilizzata per altri calcoli come l'analisi di bias o l'analisi dell'attribuzione delle funzionalità. È necessario un valore di `joinsource_name_or_index` nei seguenti casi:
+ Esistono più set di dati di input e ognuno è suddiviso in più file.
+ L'elaborazione distribuita viene attivata impostando il processo di elaborazione SageMaker Clarify su un valore [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)maggiore di. `1`
+ **excluded\$1columns**: (facoltativo) una matrice di nomi o indici di colonne a base zero da escludere dall'invio al modello come input per le previsioni. L'etichetta Ground Truth e l'etichetta prevista vengono già escluse automaticamente. Questa funzionalità non è supportata per le serie temporali.
+ **probability\$1threshold**: (facoltativo) un numero a virgola mobile al di sopra del quale viene selezionata un'etichetta o un oggetto. Il valore predefinito è `0.5`. Il processo di elaborazione SageMaker Clarify si utilizza `probability_threshold` nei seguenti casi:
+ Nell'analisi dei bias post-addestramento, `probability_threshold` converte la previsione di un modello numerico (valore di probabilità o punteggio) in un'etichetta binaria, se il modello è un classificatore binario. Un punteggio superiore alla soglia viene convertito in `1`. Un punteggio uguale o inferiore alla soglia viene convertito in `0`.
+ Nei problemi di spiegabilità della visione artificiale, se model\$1type è **OBJECT\$1DETECTION**, `, probability_threshold` filtra gli oggetti con punteggi di attendibilità inferiori al valore di soglia.
+ **label\$1values\$1or\$1threshold**: (facoltativo) obbligatorio per l’analisi dei bias. Una matrice di valori delle etichette o un numero di soglia, che indica un risultato positivo per le etichette Ground Truth e prevista per i parametri di bias. Per ulteriori informazioni, consulta i valori positivi delle etichette in [Amazon SageMaker chiarisce i termini relativi a parzialità ed equità](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Se l'etichetta è numerica, la soglia viene applicata come limite inferiore per selezionare il risultato positivo. Per impostare `label_values_or_threshold` per diversi tipi di problemi, fai riferimento ai seguenti esempi:
+ Per un problema di classificazione binaria, l'etichetta ha due valori possibili, `0` e `1`. Se il valore dell'etichetta `1` è favorevole a un gruppo demografico osservato in un campione, allora `label_values_or_threshold` deve essere impostato su `[1]`.
+ Per un problema di classificazione multiclasse, l'etichetta ha tre valori possibili: **bird**, **cat** e **dog**. Se gli ultimi due definiscono un gruppo demografico favorito dai bias, allora `label_values_or_threshold` deve essere impostato su `["cat","dog"]`.
+ Per un problema di regressione, il valore dell'etichetta è continuo e va da `0` a `1`. Se un valore maggiore di `0.5` deve indicare che un campione ha un risultato positivo, allora `label_values_or_threshold` deve essere impostato su `0.5`.
+ **facet**: (facoltativo) obbligatorio per l’analisi dei bias. Una matrice di oggetti facet, composti da attributi sensibili in base ai quali viene misurato il bias. È possibile utilizzare i facet per comprendere le caratteristiche di bias del set di dati e del modello anche se il modello viene addestrato senza utilizzare attributi sensibili. Per ulteriori informazioni, consulta **Facet** in [Amazon SageMaker chiarisce i termini relativi a parzialità ed equità](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Questo oggetto facet include i seguenti campi:
+ **name\$1or\$1index**: (facoltativo) il nome o l’indice a base zero della colonna degli attributi sensibili in un set di dati tabulare. Se `facet_dataset_uri` è specificato, l'indice si riferisce al set di dati facet anziché al set di dati principale.
+ **value\$1or\$1threshold**: (facoltativo) obbligatorio se `facet` è numerico e `label_values_or_threshold` viene applicato come limite inferiore per selezionare il gruppo sensibile. Una matrice di valori facet o un numero di soglia che indica il gruppo demografico sensibile favorito dal bias. Se il tipo di dati facet è categorico e `value_or_threshold` non viene fornito, i parametri di bias vengono calcolati come un gruppo per ogni valore univoco (anziché per tutti i valori). Per impostare `value_or_threshold` per tipi di dati `facet` diversi, fai riferimento ai seguenti esempi:
+ Per un tipo di dati facet binario, la funzionalità ha due valori possibili: `0` e`1`. Se desideri calcolare i parametri di bias per ogni valore, puoi omettere `value_or_threshold` o impostarlo su una matrice vuota.
+ Per un tipo di dati facet categorico, la funzionalità ha tre valori possibili: **bird**, **cat** e **dog**. Se i primi due definiscono un gruppo demografico favorito dai bias, allora `value_or_threshold` deve essere impostato su `["bird", "cat"]`. In questo esempio, i campioni del set di dati sono suddivisi in due gruppi demografici. Il facet del gruppo avvantaggiato ha valore **bird** oppure **cat**, mentre il facet del gruppo svantaggiato ha valore **dog**.
+ Per un tipo di dati facet numerico, il valore della funzionalità è continuo e va da `0` a `1`. Ad esempio, se un valore maggiore di `0.5` deve indicare un campione come favorito, allora `value_or_threshold` deve essere impostato su. `0.5` In questo esempio, i campioni del set di dati sono suddivisi in due gruppi demografici. Il facet del gruppo avvantaggiato ha un valore maggiore di `0.5`, mentre il facet del gruppo svantaggiato ha un valore inferiore o uguale a `0.5`.
+ **group\$1variable**: (facoltativo) il nome o l’indice a base zero della colonna che indica il sottogruppo da utilizzare per la metrica sui bias [Disparità demografica condizionale (CDD)](clarify-data-bias-metric-cddl.md) o [Disparità demografica condizionale nelle etichette previste (CDDPL)](clarify-post-training-bias-metric-cddpl.md).
+ **facet\$1dataset\$1uri**: (facoltativo) applicabile solo quando dataset\$1type è `text/csv`. L'URI S3 per un set di dati contenente attributi sensibili per l'analisi dei bias. È possibile utilizzare i facet per comprendere le caratteristiche di bias del set di dati e del modello anche se il modello viene addestrato senza utilizzare attributi sensibili.
**Nota**
Se il set di dati facet o il set di dati principale è suddiviso in più file, `joinsource_name_or_index` deve specificare una colonna identificativa per unire i due set di dati. È necessario utilizzare il parametro `facet` per identificare ogni facet nel set di dati facet.
+ **facet\$1headers**: (facoltativo) applicabile solo quando è specificato `facet_dataset_uri`. Un array di stringhe che contiene i nomi delle colonne per il set di dati facet e, facoltativamente, l’intestazione della colonna identificativa per eseguire il join del set di dati facet e del set di dati principale. Consulta `joinsource_name_or_index`.
+ **time\$1series\$1data\$1config**: (facoltativo) specifica la configurazione da utilizzare per l’elaborazione dei dati di una serie temporale.
+ **item\$1id**: una stringa o un indice intero a base zero. Questo campo viene utilizzato per individuare l’ID elemento nel set di dati di input condiviso.
+ **timestamp**: una stringa o un indice intero a base zero. Questo campo viene utilizzato per individuare un timestamp nel set di dati di input condiviso.
+ **dataset\$1format**: i valori possibili sono `columns`, `item_records` o `timestamp_records`. Questo campo viene utilizzato per descrivere il formato di un set di dati JSON, che è l’unico formato supportato per la spiegabilità delle serie temporali.
+ **target\$1time\$1series** — Una JMESPath stringa o un indice intero a base zero. Questo campo viene utilizzato per individuare la serie temporale di destinazione nel set di dati di input condiviso. Se questo parametro è una stringa, tutti gli altri parametri tranne `dataset_format` devono essere stringhe o elenchi di stringhe. Se questo parametro è un numero intero, tutti gli altri parametri tranne `dataset_format` devono essere numeri interi o elenchi di numeri interi.
+ **related\$1time\$1series** — (Facoltativo) Una matrice di espressioni. JMESPath Questo campo viene utilizzato per individuare tutte le serie temporali correlate nel set di dati di input condiviso, se presenti.
+ **static\$1covariates** — (Facoltativo) Una matrice di espressioni. JMESPath Questo campo viene utilizzato per individuare tutti i campi delle covariate statiche nel set di dati di input condiviso, se presenti.
Per alcuni esempi, consulta [Esempi di configurazione dei set di dati di serie temporali](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex).
+ **methods**: un oggetto contenente uno o più metodi di analisi e i relativi parametri. Se un metodo viene omesso, non viene né utilizzato per l'analisi né riportato.
+ **pre\$1training\$1bias**: includi questo metodo se desideri calcolare i parametri di bias prima dell'addestramento. La descrizione dettagliata dei metriche è disponibile in [Metriche di bias pre-addestramento](clarify-measure-data-bias.md). L'oggetto ha i seguenti parametri:
+ **methods**: una matrice che contiene tutti i parametri di bias pre-addestramento che si desidera calcolare, inclusi nell'elenco seguente. Imposta `methods` su **all** per calcolare tutti i parametri di bias pre-addestramento. Ad esempio, la matrice `["CI", "DPL"]` calcolerà **Squilibrio di classe** e **Differenza nelle proporzioni delle etichette**.
+ `CI` per [Squilibrio di classe (CI)](clarify-bias-metric-class-imbalance.md)
+ `DPL` per [Differenza nelle proporzioni delle etichette (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ `KL` per [Divergenza Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ `JS` per [Divergenza Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ `LP` per [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md)
+ `TVD` per [Distanza di variazione totale (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ `KS` per [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ `CDDL` per [Disparità demografica condizionale (CDD)](clarify-data-bias-metric-cddl.md)
+ **post\$1training\$1bias**: includi questo metodo se desideri calcolare i parametri di bias pre-addestramento. La descrizione dettagliata dei metriche è disponibile in [Metriche sui bias dei modelli e dei dati di post-addestramento](clarify-measure-post-training-bias.md). L'oggetto `post_training_bias` ha i parametri riportati di seguito.
+ **methods**: una matrice che contiene tutti i parametri di bias post-addestramento che si desidera calcolare, inclusi nell'elenco seguente. Imposta `methods` su **all** per calcolare tutti i parametri di bias post-addestramento. Ad esempio, la matrice `["DPPL", "DI"]` calcola **Differenza nelle proporzioni positive delle etichette previste** e **Impatto disparato**. I metodi disponibili sono i seguenti.
+ `DPPL` per [Differenza nelle proporzioni positive delle etichette previste (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ `DI` per [Impatto diversificato (DI)](clarify-post-training-bias-metric-di.md)
+ `DCA` per [Differenza nell'accettazione condizionata () DCAcc](clarify-post-training-bias-metric-dcacc.md)
+ `DCR` per [Differenza nel rifiuto condizionale (DCR)](clarify-post-training-bias-metric-dcr.md)
+ `SD` per [Differenza di specificità (SD)](clarify-post-training-bias-metric-sd.md)
+ `RD` per [Differenza di richiamo (RD)](clarify-post-training-bias-metric-rd.md)
+ `DAR` per [Differenza nelle percentuali di accettazione (DAR)](clarify-post-training-bias-metric-dar.md)
+ `DRR` per [Differenza nelle percentuali di rifiuto (DRR)](clarify-post-training-bias-metric-drr.md)
+ `AD` per [Differenza di precisione (AD)](clarify-post-training-bias-metric-ad.md)
+ `TE` per [Parità di trattamento (TE)](clarify-post-training-bias-metric-te.md)
+ `CDDPL` per [Disparità demografica condizionale nelle etichette previste (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ `FT` per [Fliptest controfattuale (FT)](clarify-post-training-bias-metric-ft.md)
+ `GE` per [Entropia generalizzata (GE)](clarify-post-training-bias-metric-ge.md)
+ **shap**: includi questo metodo se desideri calcolare i valori SHAP. Il processo di elaborazione SageMaker Clarify supporta l'algoritmo Kernel SHAP. L'oggetto `shap` ha i parametri riportati di seguito.
+ **baseline**: (facoltativo) il set di dati della baseline SHAP, noto anche come set di dati in background. I requisiti aggiuntivi per il set di dati della baseline in un set di dati tabulare o in un problema di visione artificiale sono i seguenti. Per ulteriori informazioni sulle baseline SHAP, consulta [Linee di base SHAP per la spiegabilità](clarify-feature-attribute-shap-baselines.md).
+ Per un set di dati **tabulare**, `baseline` può consistere in dati della baseline locali o l'URI S3 di un file della baseline. Se non `baseline` viene fornito, il processo di elaborazione SageMaker Clarify calcola una linea di base raggruppando il set di dati di input. Di seguito sono riportati i requisiti per la baseline:
+ Il formato deve essere uguale a quello del set di dati specificato da `dataset_type`.
+ La baseline può contenere solo funzionalità che il modello può accettare come input.
+ Il set di dati della baseline può avere una o più istanze. Il numero di istanze della baseline influisce direttamente sia sulla dimensione del set di dati sintetico che sulla durata del processo.
+ Se `text_config` è specificato, il valore della baseline di una colonna di testo è una stringa utilizzata per sostituire l'unità di testo specificata da `granularity`. Ad esempio, un segnaposto comune è "[MASK]", che viene utilizzato per rappresentare una parola o una parte di testo mancante o sconosciuta.
Gli esempi seguenti mostrano come impostare dati della baseline locali per diversi parametri `dataset_type`:
+ Se `dataset_type` è `text/csv` o `application/x-parquet`, il modello accetta quattro funzionalità numeriche e la baseline ha due istanze. In questo esempio, se un record ha tutti valori di funzionalità zero e l'altro record ha tutti i valori di funzionalità uno, la baseline deve essere impostata su `[[0,0,0,0],[1,1,1,1]]`, senza alcuna intestazione.
+ Se `dataset_type` è `application/jsonlines` e `features` è la chiave per un elenco di quattro valori di funzionalità numeriche. Inoltre, in questo esempio, se la baseline ha un record di tutti i valori zero, allora `baseline` deve essere `[{"features":[0,0,0,0]}]`.
+ Se `dataset_type` è `application/json`, il set di dati `baseline` deve avere la stessa struttura e lo stesso formato del set di dati di input.
+ Per problemi di **visione artificiale**, `baseline` può essere l'URI S3 di un'immagine utilizzato per mascherare funzionalità (segmenti) dall'immagine di input. Il processo di elaborazione SageMaker Clarify carica l'immagine della maschera e la ridimensiona alla stessa risoluzione dell'immagine di input. Se non viene fornita la linea di base, il processo di elaborazione SageMaker Clarify genera un'immagine maschera di [rumore bianco](https://en.wikipedia.org/wiki/White_noise) con la stessa risoluzione dell'immagine di input.
+ **features\$1to\$1explain**: (facoltativo) una matrice di stringhe o indici a base zero di colonne di funzionalità per cui calcolare i valori SHAP. Se `features_to_explain` non viene fornito, i valori SHAP vengono calcolati per tutte le colonne delle funzionalità. Queste colonne di funzionalità non possono includere la colonna dell'etichetta o la colonna dell'etichetta prevista. Il parametro `features_to_explain` è supportato solo per set di dati tabulari con colonne numeriche e categoriche.
+ **num\$1clusters**: (facoltativo) il numero di cluster in cui è suddiviso il set di dati per calcolare il set di dati di base. Ogni cluster viene utilizzato per calcolare un'istanza della baseline. Se non `baseline` è specificato, il processo di elaborazione SageMaker Clarify tenta di calcolare il set di dati di base dividendo il set di dati tabulare in un numero ottimale di cluster tra e. `1` `12` Il numero di istanze della baseline influisce direttamente sull'esecuzione dell'analisi SHAP.
+ **num\$1samples**: (facoltativo) il numero di campioni da utilizzare nell'algoritmo SHAP del kernel. Se non `num_samples` viene fornito, il processo di elaborazione SageMaker Clarify sceglie il numero automaticamente. Il numero di campioni influisce direttamente sia sulla dimensione del set di dati sintetico che sulla durata del processo.
+ **seed**: (facoltativo) un numero intero utilizzato per inizializzare il generatore di numeri pseudo casuali nell'esplicatore SHAP per generare valori SHAP coerenti per lo stesso lavoro. Se seed non è specificato, ogni volta che viene eseguito lo stesso processo, il modello può generare valori SHAP leggermente diversi.
+ **use\$1logit**: (facoltativo) un valore booleano che indica che si desidera che la funzione logit venga applicata alle previsioni del modello. L'impostazione predefinita è `false`. Se `use_logit` è `true`, i valori SHAP vengono calcolati utilizzando i coefficienti di regressione logistica, che possono essere interpretati come rapporti log-odd.
+ **save\$1local\$1shap\$1values**: (facoltativo) un valore booleano che indica che desideri includere i valori SHAP locali di ogni record del set di dati nel risultato dell'analisi. L’impostazione predefinita è `false`.
Se il set di dati principale è suddiviso in più file o è attivata l'elaborazione distribuita, specifica anche una colonna identificativa utilizzando il parametro `joinsource_name_or_index`. La colonna identificativa e i valori SHAP locali vengono salvati nel risultato dell'analisi. In questo modo, è possibile mappare ogni record ai relativi valori SHAP locali.
+ **agg\$1method**: (facoltativo) il metodo utilizzato per aggregare i valori SHAP locali (i valori SHAP di ogni istanza) di tutte le istanze ai valori SHAP globali (i valori SHAP dell'intero set di dati). L'impostazione predefinita è `mean_abs`. I seguenti metodi possono essere utilizzati per aggregare i valori SHAP.
+ **mean\$1abs**: la media dei valori SHAP locali assoluti di tutte le istanze.
+ **mean\$1sq**: la media dei valori SHAP locali quadratici di tutte le istanze.
+ **mediana**: la mediana dei valori SHAP locali di tutte le istanze.
+ **text\$1config**: necessario per la spiegabilità dell’elaborazione del linguaggio naturale. Includi questa configurazione se desideri trattare le colonne di testo come testo e se le spiegazioni dovrebbero essere fornite per le singole unità di testo. Per un esempio di configurazione dell’analisi per la spiegabilità dell’elaborazione del linguaggio naturale, consulta [Configurazione di analisi per la spiegabilità dell'elaborazione del linguaggio naturale](#clarify-analysis-configure-nlp-example).
+ **granularità**: l'unità di granularità per l'analisi delle colonne di testo. I valori validi sono `token`, `sentence` o `paragraph`. **Ogni unità di testo è considerata una funzionalità** e i valori SHAP locali vengono calcolati per ogni unità.
+ **lingua**: la lingua delle colonne di testo. I valori validi sono **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**. Inserisci `multi-language` per una combinare più lingue.
+ **max\$1top\$1tokens**: (facoltativo) il numero massimo di token principali, in base ai valori SHAP globali. L'impostazione predefinita è `50`. È possibile che un token appaia più volte nel set di dati. Il processo di elaborazione SageMaker Clarify aggrega i valori SHAP di ciascun token, quindi seleziona i token principali in base ai rispettivi valori SHAP globali. I valori SHAP globali dei token principali selezionati sono inclusi nella sezione `global_top_shap_text` del file analysis.json.
+ Il valore SHAP locale di aggregazione.
+ **image\$1config**: necessario per la spiegabilità della visione artificiale. Includi questa configurazione se disponi di un set di dati di input composto da immagini e desideri analizzarle per verificarne la spiegabilità in un problema di visione artificiale.
+ **model\$1type**: il tipo di modello. I valori validi includono:
+ `IMAGE_CLASSIFICATION` di un modello di classificazione delle immagini
+ `OBJECT_DETECTION` di un modello per il rilevamento di oggetti
+ **max\$1objects**: applicabile solo quando model\$1type è **OBJECT\$1DETECTION**. Il numero massimo di oggetti, ordinato in base al punteggio di attendibilità, rilevato dal modello di visione artificiale. Tutti gli oggetti con un punteggio di attendibilità inferiore al massimo max\$1objects vengono filtrati. L'impostazione predefinita è `3`.
+ **context**: applicabile solo quando model\$1type è **OBJECT\$1DETECTION**. Indica se l'area intorno al riquadro di delimitazione dell'oggetto rilevato è mascherata o meno dall'immagine di base. I valori validi sono: `0` per mascherare tutto o `1` per non mascherare nulla. L'impostazione predefinita è 2.
+ **iou\$1threshold**: applicabile solo quando `model_type` è **OBJECT\$1DETECTION**. Il parametro minimo di intersezione over union (IOU) per valutare le previsioni rispetto al rilevamento originale. Un parametro IOU elevato corrisponde a una grande sovrapposizione tra la casella di rilevamento della verità prevista e della Ground Truth. L'impostazione predefinita è `0.5`.
+ **num\$1segments**: (facoltativo) un numero intero che determina il numero approssimativo di segmenti da etichettare nell'immagine di input. Ogni segmento dell'immagine è considerato una funzionalità e per ogni segmento vengono calcolati i valori SHAP locali. L'impostazione predefinita è `20`.
+ **segment\$1compactness**: (facoltativo) un numero intero che determina la forma e la dimensione dei segmenti di immagine generati dal metodo [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic). L'impostazione predefinita è `5`.
+ **pdp** — Include questo metodo per calcolare i grafici di dipendenza parziali (). PDPs Per un esempio di configurazione di analisi da generare, vedere PDPs [Calcola i grafici di dipendenza parziale () PDPs](#clarify-analysis-configure-csv-example-pdp)
+ **funzionalità**: obbligatorio se il metodo `shap` non è richiesto. Una matrice di nomi o indici di funzionalità per calcolare e tracciare grafici PDP.
+ **top\$1k\$1features**: (facoltativo) specifica il numero di funzionalità principali utilizzate per generare grafici PDP. Se non `features` viene fornito, ma il `shap` metodo è richiesto, il processo di elaborazione di SageMaker Clarify sceglie le funzionalità principali in base alle relative attribuzioni SHAP. L'impostazione predefinita è `10`.
+ **grid\$1resolution**: il numero di bucket in cui dividere l'intervallo di valori numerici. Questo specifica la granularità della griglia per i grafici PDP.
+ **asymmetric\$1shapley\$1value**: includi questo metodo per calcolare le metriche di spiegabilità per i modelli di previsione delle serie temporali. Il processo di elaborazione SageMaker Clarify supporta l'algoritmo asimmetrico dei valori Shapley. I valori asimmetrici di Shapley sono una variante del valore di Shapley senza l’assioma di simmetria. Per ulteriori informazioni, consulta [Valori asimmetrici di Shapley: integrazione delle informazioni causali nella spiegabilità indipendente dal modello](https://arxiv.org/abs/1910.06358). Utilizza questi valori per determinare in che modo le funzionalità contribuiscono al risultato della previsione. I valori asimmetrici di Shapley tengono conto delle dipendenze temporali dei dati di serie temporali che i modelli di previsione utilizzano come input.
L’algoritmo include i seguenti parametri:
+ **direction**: i tipi disponibili sono `chronological`, `anti_chronological` e `bidirectional`. La struttura temporale può essere esplorata in ordine cronologico, anticronologico o entrambi. Le spiegazioni cronologiche vengono create aggiungendo le informazioni in modo iterativo dalla prima fase in poi. Le spiegazioni anticronologiche aggiungono informazioni a partire dall’ultima fase e procedendo a ritroso. Quest’ultimo ordine può essere più adatto per i bias di novità, ad esempio per la previsione dei prezzi delle azioni.
+ **granularity**: la granularità della spiegazione da utilizzare. Di seguito vengono riportate le opzioni di granularità disponibili:
+ **timewise**: le spiegazioni `timewise` non sono costose e forniscono informazioni mirate su fasi temporali specifiche, ad esempio per capire in che misura le informazioni del n° giorno nel passato hanno contribuito alla previsione del giorno m° nel futuro. Le attribuzioni risultanti non spiegano singolarmente le covariate statiche e non fanno distinzione tra serie temporali di destinazione e correlate.
+ **fine\$1grained**: le spiegazioni `fine_grained` sono più impegnative a livello computazionale, ma forniscono una suddivisione completa di tutte le attribuzioni delle variabili di input. Il metodo calcola spiegazioni approssimative per ridurre il runtime. Per ulteriori informazioni, consulta il parametro seguente, `num_samples`.
**Nota**
Le spiegazioni `fine_grained` supportano solo l’ordine `chronological`.
+ **num\$1samples**: (facoltativo) questo argomento è obbligatorio per le spiegazioni `fine_grained`. Più elevato è il numero, più precisa è l’approssimazione. Questo numero deve adattarsi alla dimensionalità delle funzionalità di input. Una regola pratica consiste nell’impostare questa variabile su *(1 \$1 max (numero di serie temporali correlate, numero di covariate statiche))^2* se il risultato non è troppo grande.
+ **baseline** — (Facoltativo) La configurazione di base per sostituire i out-of-coalition valori per i set di dati corrispondenti (noti anche come dati di sfondo). Il frammento di codice seguente mostra un esempio di configurazione baseline.
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ Per i dati temporali come le serie temporali di destinazione o le serie temporali correlate, i tipi di valori baseline possono essere:
+ `zero`— Tutti i out-of-coalition valori vengono sostituiti con 0.0.
+ `mean`— Tutti i out-of-coalition valori vengono sostituiti con la media di una serie temporale.
+ Per le covariate statiche, una voce baseline deve essere fornita solo quando la richiesta del modello accetta valori di covariate statiche, nel qual caso questo campo è obbligatorio. La baseline deve essere fornita per ogni elemento sotto forma di elenco. Ad esempio, se hai un set di dati con due covariate statiche, la configurazione baseline potrebbe essere la seguente:
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
Nell'esempio precedente, ** e ** sono gli ID degli elementi del set di dati.
+ **report**: (facoltativo) utilizza questo oggetto per personalizzare il report di analisi. Questo parametro non è supportato per i processi di spiegazione delle serie temporali. Ci sono tre copie dello stesso report come parte del risultato dell'analisi: report Jupyter Notebook, report HTML e report PDF. L'oggetto ha i seguenti parametri:
+ **name**: nome del file di report. Ad esempio, se `name` è **MyReport**, allora i file di report sono `MyReport.ipynb`, `MyReport.html`, e `MyReport.pdf`. L'impostazione predefinita è `report`.
+ **title**: (facoltativo) stringa del titolo del report. L'impostazione predefinita è **SageMaker AI Analysis Report**.
+ **predittore**: obbligatorio se l'analisi richiede previsioni dal modello. Ad esempio, quando viene richiesto il metodo `shap`, `asymmetric_shapley_value`, `pdp` o `post_training_bias`, ma le etichette previste non vengono fornite come parte del set di dati di input. Di seguito sono riportati i parametri da utilizzare insieme a `predictor`:
+ **model\$1name: il nome** del modello di SageMaker intelligenza artificiale creato dall'API. [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) **Se specificate `model_name` al posto di endpoint\$1name, il processo di elaborazione di SageMaker Clarify crea un endpoint temporaneo con il nome del modello, noto come endpoint ombra, e ottiene le previsioni dall'endpoint.** Il processo elimina l'endpoint shadow dopo aver completato i calcoli. Se il modello è multi-modello, devi specificare il parametro `target_model`. Per ulteriori informazioni sugli endpoint multi-modello, consulta [Endpoint multi-modello](multi-model-endpoints.md).
+ **endpoint\$1name\$1prefix**: (facoltativo) un prefisso di nome personalizzato per l'endpoint shadow. Applicabile se fornisci `model_name` invece di `endpoint_name`. Ad esempio, fornisci `endpoint_name_prefix` se desideri limitare l'accesso all'endpoint in base al nome dell'endpoint. Il prefisso deve corrispondere al modello e la sua lunghezza massima è. [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName)`23` L'impostazione predefinita è `sm-clarify`.
+ **initial\$1instance\$1count**: specifica il numero di istanze dell'endpoint shadow. Obbligatorio se fornisci model\$1name anziché endpoint\$1name. Il valore di `initial_instance_count` può essere diverso da quello [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)del lavoro, ma consigliamo un rapporto 1:1.
+ **instance\$1type**: specifica il tipo di istanza dell'endpoint shadow. Obbligatorio se fornisci `model_name` invece di `endpoint_name`. Ad esempio, `instance_type` può essere impostato su "ml.m5.large". In alcuni casi, il valore specificato per `instance_type` può aiutare a ridurre il tempo di inferenza del modello. Ad esempio, per funzionare in modo efficiente, i modelli di elaborazione del linguaggio naturale e i modelli di visione artificiale richiedono in genere un tipo di istanza GPU (Graphics Processing Unit).
+ **endpoint\$1name: il nome** del tuo endpoint SageMaker AI creato dall'API. [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) Se fornito, `endpoint_name` ha la precedenza sul parametro `model_name`. L'utilizzo di un endpoint esistente riduce il tempo di bootstrap dell'endpoint shadow, ma può anche causare un aumento significativo del carico per quell'endpoint. Inoltre, alcuni metodi di analisi (come `shap` e `pdp`) generano set di dati sintetici che vengono inviati all'endpoint. Ciò può far sì che i parametri o i dati acquisiti dell'endpoint vengano contaminati da dati sintetici, che potrebbero non riflettere accuratamente l'utilizzo nel mondo reale. Per questi motivi, in genere non è consigliabile utilizzare un endpoint di produzione esistente per l'analisi di Clarify. SageMaker
+ **target\$1model** — Il valore della stringa che viene passato al TargetModel parametro dell'API AI. SageMaker [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) Necessario se il modello (specificato dal parametro model\$1name) o l'endpoint (specificato dal parametro endpoint\$1name) sono multi-modello. Per ulteriori informazioni sugli endpoint multi-modello, consulta [Endpoint multi-modello](multi-model-endpoints.md).
+ **custom\$1attributes**: (facoltativo) una stringa che consente di fornire informazioni aggiuntive su una richiesta di inferenza inviata all'endpoint. Il valore della stringa viene passato al `CustomAttributes` parametro dell' SageMaker API AI. [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)
+ **content\$1type**: il formato di input del modello da utilizzare per ottenere previsioni dall'endpoint. Se fornito, viene passato al `ContentType` parametro dell'[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ Per la spiegabilità della visione artificiale, i valori validi sono **image/jpeg**, **image/png** o **application/x-npy**. Se `content_type` non viene specificato, il valore predefinito è **image/jpeg**.
+ Per la spiegabilità della previsione delle serie temporali, il valore accettato è **application/json**.
+ Per altri tipi di spiegabilità, i valori validi sono **text/csv**, **application/jsonlines,** e **application/json**. È richiesto un valore per `content_type` se `dataset_type` è **application/x-parquet**. Altrimenti, il valore predefinito di `content_type` è quello del parametro `dataset_type`.
+ **accept\$1type**: il formato di output del modello da utilizzare per ottenere previsioni dall'endpoint. Il valore per `accept_type` viene passato al `Accept` parametro dell'[InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ Per la spiegabilità della visione artificiale, se `model_type` è "OBJECT\$1DETECTION", il valore predefinito di `accept_type` è **application/json**.
+ Per la spiegabilità della previsione delle serie temporali, il valore accettato è **application/json**.
+ Per altri tipi di spiegabilità, i valori validi sono **text/csv**, **application/jsonlines** e **application/json**. Se non viene fornito un valore per `accept_type`, il valore predefinito di `accept_type` è il valore del parametro `content_type`.
+ **content\$1template**: una stringa modello utilizzata per costruire l'input del modello dai record del set di dati. Il parametro `content_template` viene utilizzato e richiesto solo se il valore del parametro `content_type` è `application/jsonlines` o `application/json`
Quando il parametro `content_type` è `application/jsonlines`, la stringa modello deve avere un solo segnaposto, `$features`, che viene sostituito dall'elenco delle funzionalità in fase di runtime. Ad esempio, se la stringa modello è `"{\"myfeatures\":$features}"` e se un record ha tre valori di funzionalità numeriche:`1`, `2` e `3`, il record verrà inviato al modello come `{"myfeatures":[1,2,3]}` JSON Line.
Quando `content_type` è `application/json`, la stringa modello può avere un segnaposto `$record` o `records`. Se il segnaposto è `record`, un singolo record viene sostituito con un record a cui è applicata la stringa modello in `record_template`. In questo caso, al modello verrà inviato un solo record alla volta. Se il segnaposto è `$records`, i record vengono sostituiti da un elenco di record, ciascuno con una stringa modello fornita da `record_template`.
+ **record\$1template**: una stringa modello da utilizzare per costruire ogni record dell'input del modello dalle istanze del set di dati. Viene utilizzato e richiesto solo quando `content_type` è `application/json` La stringa modello può contenere:
+ Un segnaposto parametro `$features` che viene sostituito da una matrice di valori di funzionalità. Un segnaposto opzionale aggiuntivo può sostituire i nomi delle intestazioni delle colonne di funzionalità in `$feature_names`. Questo segnaposto opzionale verrà sostituito da una serie di nomi di funzionalità.
+ Esattamente un segnaposto `$features_kvp` che viene sostituito da coppie chiave-valore, nome e valore della funzionalità.
+ Una funzionalità nella configurazione `headers`. Ad esempio, il nome di una funzionalità `A`, annotato dalla sintassi del segnaposto `"${A}"` verrà sostituito dal valore della funzionalità di `A`.
Il valore di `record_template` viene utilizzato con `content_template` per costruire l'input del modello. Segue un esempio di configurazione che mostra come costruire un input del modello utilizzando contenuti e record modello.
Nel seguente esempio di codice, le intestazioni e le funzionalità sono definite come segue.
+ ``headers`:["A", "B"]`
+ ``features`:[[0,1], [3,4]]`
L'input del modello di esempio è:
```
{
"instances": [[0, 1], [3, 4]],
"feature_names": ["A", "B"]
}
```
Di seguito sono riportati come esempio i valori dei parametri `content_template` e `record_template`, per costruire l'input del modello dell'esempio precedente.
+ `content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"`
+ `record_template: "$features"`
Nel seguente esempio di codice, le intestazioni e le funzionalità sono definite come segue.
```
[
{ "A": 0, "B": 1 },
{ "A": 3, "B": 4 },
]
```
Di seguito sono riportati come esempio i valori dei parametri ` content_template` e `record_template`, per costruire l'input del modello dell'esempio precedente.
+ `content_template: "$records"`
+ `record_template: "$features_kvp"`
Segue un esempio di codice alternativo per costruire l'input del modello dell'esempio precedente.
+ `content_template: "$records"`
+ `record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"`
Nel seguente esempio di codice, le intestazioni e le funzionalità sono definite come segue.
```
{ "A": 0, "B": 1 }
```
I valori dei parametri content\$1template e record\$1template di esempio da costruire sopra: segue l'input del modello di esempio precedente.
+ `content_template: "$record"`
+ `record_template: "$features_kvp"`
Per ulteriori esempi, consulta [Richieste degli endpoint per i dati di serie temporali](clarify-processing-job-data-format-time-series-request-jsonlines.md).
+ **label** — (Facoltativo) Un indice intero o una stringa di JMESPath espressione a base zero utilizzata per estrarre le etichette previste dall'output del modello per l'analisi delle distorsioni. Se il modello è multiclasse e il parametro `label` estrae tutte le etichette previste dall'output del modello, si applica quanto segue. Questa funzionalità non è supportata per le serie temporali.
+ Il parametro `probability` è necessario per ottenere le probabilità (o i punteggi) corrispondenti dall'output del modello.
+ Viene scelta l'etichetta prevista del punteggio più alto.
Il valore di `label` viene specificato in base al valore del parametro accept\$1type, come segue.
+ Se `accept_type` è **text/csv**, allora `label` è l'indice di tutte le etichette previste nell'output del modello.
+ Se `accept_type` è **application/jsonlines** o**application/json**, allora `label` è un' JMESPath espressione che viene applicata all'output del modello per ottenere le etichette previste.
+ **label\$1headers**: (facoltativo) un array di valori che l’etichetta può assumere nel set di dati. Se viene richiesta l'analisi del bias, il parametro `probability` è necessario anche per ottenere i valori di probabilità (punteggi) corrispondenti dall'output del modello e viene scelta l'etichetta prevista del punteggio più alto. Se viene richiesta l'analisi della spiegabilità, le intestazioni delle etichette vengono utilizzate per abbellire il report di analisi. È richiesto un valore di `label_headers`, per la spiegabilità della visione artificiale. Ad esempio, per un problema di classificazione multiclasse, se l'etichetta ha tre valori possibili, **bird**, **cat** e **dog**, allora `label_headers` deve essere impostato su `["bird","cat","dog"]`.
+ **probabilità** — (Facoltativo) Un indice intero a base zero o una stringa di JMESPath espressione utilizzata per estrarre le probabilità (punteggi) per l'analisi della spiegabilità (ma non per la spiegabilità delle serie temporali) o per scegliere l'etichetta prevista per l'analisi delle distorsioni. Il valore di `probability` viene specificato in base al valore del parametro `accept_type`, come segue.
+ Se `accept_type` è **text/csv**, `probability` è l'indice delle probabilità (punteggi) nell'output del modello. Se `probability` non viene fornito, l'intero output del modello viene considerato come probabilità (punteggi).
+ Se si `accept_type` tratta di dati JSON (uno **application/jsonlines** o più**application/json**), `probability` dovrebbe essere un' JMESPathespressione utilizzata per estrarre le probabilità (punteggi) dall'output del modello.
+ **time\$1series\$1predictor\$1config:** (facoltativo) utilizzato solo per la spiegabilità delle serie temporali. Utilizzato per indicare al processore SageMaker Clarify come analizzare correttamente i dati dai dati passati come URI S3 in. `dataset_uri`
+ **previsione**: JMESPath espressione utilizzata per estrarre il risultato della previsione.
## File di configurazione dell'analisi di esempio
Le sezioni seguenti contengono esempi di file di configurazione dell’analisi per dati in formato CSV e JSON Lines, nonché per la spiegabilità dell’elaborazione del linguaggio naturale (NLP), della visione artificiale (CV) e delle serie temporali (TS).
### Configurazione di analisi per un set di dati CSV
I seguenti esempi mostrano come configurare l'analisi del bias della spiegabilità per un set di dati tabulare in formato CSV. In questi esempi, il set di dati in entrata ha quattro colonne di funzionalità e una colonna di etichette binarie, `Target`. Il contenuto del set di dati è il seguente. Un valore di etichetta pari a `1` indica un risultato positivo. Il set di dati viene fornito al job SageMaker Clarify dall'input di `dataset` elaborazione.
```
"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
...
```
Le sezioni seguenti mostrano come calcolare le metriche di distorsione prima e dopo l'allenamento, i valori SHAP e i grafici delle dipendenze parziali (PDPs) che mostrano l'importanza delle funzionalità per un set di dati in formato CSV.
#### Calcola tutti i parametri di bias pre-addestramento
Questa configurazione di esempio mostra come misurare se il set di dati del campione precedente è orientato favorevolmente verso campioni con un valore **Gender** di `0`. La seguente configurazione di analisi indica al processo di elaborazione di SageMaker Clarify di calcolare tutte le metriche di distorsione pre-allenamento per il set di dati.
```
{
"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"
}
}
}
```
#### Calcola tutti i parametri di bias post-addestramento
Puoi calcolare i parametri di bias pre-addestramento prima dell'addestramento. Tuttavia, è necessario disporre di un modello addestrato per calcolare i parametri di bias post-addestramento. L'output di esempio seguente proviene da un modello di classificazione binaria che genera dati in formato CSV. In questo output di esempio, ogni riga contiene due colonne. La prima colonna contiene l'etichetta prevista e la seconda colonna contiene il valore di probabilità per quell'etichetta.
```
0,0.028986845165491
1,0.825382471084594
...
```
Il seguente esempio di configurazione indica al processo di elaborazione SageMaker Clarify di calcolare tutte le possibili metriche di distorsione utilizzando il set di dati e le previsioni dall'output del modello. Nell'esempio, il modello viene distribuito su un endpoint AI. SageMaker `your_endpoint`
**Nota**
Nell'esempio di codice seguente, i parametri `content_type` e `accept_type` non sono impostati. Pertanto, utilizzano automaticamente il valore del parametro dataset\$1type, che è `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
}
}
```
#### Calcola i valori SHAP
Il seguente esempio di configurazione di analisi indica al processo di calcolare i valori SHAP, designando la colonna `Target` come etichette e tutte le altre colonne come funzionalità.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
In questo esempio, il parametro SHAP `baseline` è omesso e il valore del parametro `num_clusters` è `1`. Questo indica al processore SageMaker Clarify di calcolare un campione di base SHAP. In questo esempio, la probabilità è impostata su `1`. Ciò indica al processo di elaborazione SageMaker Clarify di estrarre il punteggio di probabilità dalla seconda colonna dell'output del modello (utilizzando l'indicizzazione a base zero).
#### Calcola i grafici di dipendenza parziale () PDPs
L'esempio seguente mostra come visualizzare l'importanza della `Income` feature nel report di analisi utilizzando. PDPs Il parametro report indica al processo di elaborazione di SageMaker Clarify di generare un report. Una volta completato il processo, il report generato viene salvato come report.pdf nella posizione `analysis_result`. Il parametro `grid_resolution` divide l'intervallo dei valori della funzionalità in bucket `10`. Insieme, i parametri specificati nell'esempio seguente indicano al processo di elaborazione SageMaker Clarify di generare un report contenente un grafico PDP per `Income` i segmenti sull'asse x. `10` L'asse y mostrerà l'impatto marginale di `Income` sulle predizioni.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"pdp": {
"features": ["Income"],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
},
}
```
#### Calcola sia i parametri di bias che l'importanza delle funzionalità
È possibile combinare tutti i metodi degli esempi di configurazione precedenti in un unico file di configurazione di analisi e calcolarli tutti con un unico processo. L'esempio seguente mostra una configurazione di analisi con tutte le fasi combinate.
In questo esempio, il parametro `probability` è impostato su `1` per indicare che le probabilità sono contenute nella seconda colonna (utilizzando l'indicizzazione a base zero). Tuttavia, poiché l'analisi delle distorsioni richiede un'etichetta prevista, il parametro `probability_threshold` è impostato su `0.5` per convertire il punteggio di probabilità in un'etichetta binaria. In questo esempio, il parametro `top_k_features` del metodo `pdp` dei grafici di dipendenza parziale è impostato su `2`. Ciò consente al processo di elaborazione di SageMaker Clarify di calcolare i grafici di dipendenza parziali (PDPs) per le funzionalità principali con i valori SHAP globali più elevati. `2`
```
{
"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
}
}
```
Invece di distribuire il modello su un endpoint, è possibile fornire il nome del modello di SageMaker intelligenza artificiale al processo di elaborazione Clarify utilizzando il parametro. SageMaker `model_name` Il seguente esempio mostra come specificare un modello denominato **your\$1model**. Il processo di elaborazione SageMaker Clarify creerà un endpoint shadow utilizzando la configurazione.
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### Configurazione di analisi per un set di dati JSON Lines
I seguenti esempi mostrano come configurare l'analisi del bias e l'analisi della spiegabilità per un set di dati tabulare in formato JSON Lines. In questi esempi, il set di dati in entrata contiene gli stessi dati della sezione precedente, ma sono nel formato denso SageMaker AI JSON Lines. Ogni riga è un oggetto JSON valido. La chiave "Features" si riferisce a una serie di valori di funzionalità e la chiave "Label" si riferisce all'etichetta Ground Truth. Il set di dati viene fornito al job SageMaker Clarify dall'input di elaborazione «dataset». Per ulteriori informazioni su righe JSON, consultare [Formato della richiesta 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}
...
```
Le sezioni seguenti mostrano come calcolare le metriche di distorsione prima e dopo l'allenamento, i valori SHAP e i grafici di dipendenza parziale (PDPs) che mostrano l'importanza delle funzionalità per un set di dati in formato JSON Lines.
#### Calcola i parametri di bias pre-addestramento
Specifica l'etichetta, le funzionalità, il formato e i metodi per misurare i parametri di bias pre-addestramento per un valore `Gender` di `0`. Nell'esempio seguente, il parametro `headers` fornisce innanzitutto i nomi delle funzionalità. Il nome dell'etichetta viene fornito per ultimo. Per convenzione, l'ultima intestazione è quella dell'etichetta.
Il `features` parametro è impostato sull' JMESPath espressione «Features» in modo che il processo di elaborazione di SageMaker Clarify possa estrarre la serie di funzionalità da ogni record. Il `label` parametro è impostato sull' JMESPath espressione «Label» in modo che il processo di elaborazione di SageMaker Clarify possa estrarre l'etichetta di verità fondamentale da ogni record. Utilizza un nome di facet per specificare l'attributo sensibile, come segue.
```
{
"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"
}
}
}
```
#### Calcola tutti i parametri di bias
È necessario disporre di un modello esperto per calcolare i parametri di bias post-addestramento. L'esempio seguente proviene da un modello di classificazione binaria che genera dati JSON Lines nel formato dell'esempio. Ogni riga dell'output del modello è un oggetto JSON valido. La `predicted_label` chiave si riferisce all'etichetta prevista e la `probability` chiave si riferisce al valore di probabilità.
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
È possibile distribuire il modello su un endpoint SageMaker AI denominato. `your_endpoint` Il seguente esempio di configurazione di analisi indica al processo di elaborazione di SageMaker Clarify di calcolare tutte le possibili metriche di distorsione sia per il set di dati che per il modello. In questo esempio, i parametri `content_type` e `accept_type` non sono impostati. Pertanto, utilizzano automaticamente il valore del parametro dataset\$1type, che è `application/jsonlines`. Il processo di elaborazione SageMaker Clarify utilizza il `content_template` parametro per comporre l'input del modello, sostituendo il segnaposto con una serie di funzionalità. `$features`
```
{
"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"
}
}
```
#### Calcola i valori SHAP
Poiché l'analisi SHAP non necessita di un'etichetta Ground Truth, il parametro `label` viene omesso. In questo esempio, anche il parametro `headers` è omesso. Pertanto, il processo di elaborazione SageMaker Clarify deve generare segnaposti utilizzando nomi generici come `column_0` o `column_1` per le intestazioni delle funzionalità e per l'intestazione di un'etichetta. `label0` È possibile specificare i valori per `headers` e `label`, in modo da migliorare la leggibilità del risultato dell'analisi. Poiché il parametro di probabilità è impostato su JMESPath espressione`probability`, il valore di probabilità verrà estratto dall'output del modello. Di seguito è riportato un esempio per calcolare i valori SHAP.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### Calcola i grafici di dipendenza parziali () PDPs
L'esempio seguente mostra come visualizzare l'importanza di "Income" nel PDP. In questo esempio, le intestazioni delle funzionalità non vengono fornite. Pertanto, il parametro `features` del metodo `pdp` deve utilizzare un indice a base zero per fare riferimento alla posizione della colonna di funzionalità. Il parametro `grid_resolution` divide l'intervallo dei valori della funzionalità in bucket `10`. Insieme, i parametri dell'esempio indicano al processo di elaborazione SageMaker Clarify di generare un report contenente un grafico PDP per i segmenti sull'asse x. `Income` `10` L'asse y mostrerà l'impatto marginale di `Income` sulle predizioni.
```
{
"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"
}
}
```
#### Calcola sia i parametri di bias che l'importanza delle funzionalità
È possibile combinare tutti i metodi precedenti in un unico file di configurazione di analisi e calcolarli tutti con un unico processo. L'esempio seguente mostra una configurazione di analisi con tutte le fasi combinate. In questo esempio, il parametro `probability` è impostato. Tuttavia, poiché l'analisi dei bias richiede un'etichetta prevista, il parametro `probability_threshold` è impostato su `0.5` per convertire il punteggio di probabilità in un'etichetta binaria. In questo esempio, il parametro `top_k_features` del metodo `pdp` è impostato su `2`. Ciò indica al processo di elaborazione SageMaker Clarify di calcolare le funzionalità principali `2` con i valori SHAP PDPs globali più elevati.
```
{
"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"
}
}
```
### Configurazione di analisi per un set di dati JSON
I seguenti esempi mostrano come configurare l'analisi del bias della spiegabilità per un set di dati tabulare in formato JSON. In questi esempi, il set di dati in entrata contiene gli stessi dati della sezione precedente, ma sono nel formato denso AI JSON. SageMaker Per ulteriori informazioni su righe JSON, consultare [Formato della richiesta JSONLINES](cdf-inference.md#cm-jsonlines).
L'intera richiesta di input ha una sintassi JSON valida, dove la struttura esterna è un elenco e ogni elemento è il dato di un record. All'interno di ogni record, la chiave `Features` si riferisce a una serie di valori di funzionalità e la chiave `Label` si riferisce all'etichetta Ground Truth. Il set di dati viene fornito al job SageMaker Clarify tramite l'input di elaborazione. `dataset`
```
[
{"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},
...
]
```
Le sezioni seguenti mostrano come calcolare le metriche di distorsione prima e dopo l'allenamento, i valori SHAP e i grafici delle dipendenze parziali (PDPs) che mostrano l'importanza delle funzionalità per un set di dati in formato JSON Lines.
#### Calcola i parametri di bias pre-addestramento
Specifica l'etichetta, le funzionalità, il formato e i metodi per misurare i parametri di bias pre-addestramento per un valore `Gender` di `0`. Nell'esempio seguente, il parametro `headers` fornisce innanzitutto i nomi delle funzionalità. Il nome dell'etichetta viene fornito per ultimo. Nei set di dati JSON, l'ultima intestazione è quella di etichetta.
Il `features` parametro è impostato sull'espressione che estrae una matrice o una matrice 2D. JMESPath Ogni riga di questa matrice deve contenere l'elenco di `Features` in ogni record. Il `label` parametro è impostato su JMESPath un'espressione che estrae un elenco di etichette di verità di base. Ogni elemento di questo elenco deve contenere l'etichetta di un record.
Utilizza un nome di facet per specificare l'attributo sensibile, come segue.
```
{
"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"
}
}
}
```
#### Calcola tutti i parametri di bias
È necessario disporre di un modello addestrato per calcolare i parametri di bias post-addestramento. Il seguente esempio di codice proviene da un modello di classificazione binaria che genera dati JSON nel formato dell'esempio. Nell'esempio, ogni elemento sotto `predictions` è l'output di previsione per un record. L'esempio di codice contiene la chiave `predicted_label`, che si riferisce all'etichetta prevista, e la chiave `probability`, che si riferisce al valore di probabilità.
```
{
"predictions": [
{"predicted_label":0,"probability":0.028986845165491},
{"predicted_label":1,"probability":0.825382471084594},
...
]
}
```
È possibile distribuire il modello su un endpoint SageMaker AI denominato. `your_endpoint`
Nel seguente esempio, i parametri `content_type` e `accept_type` non sono impostati. Pertanto, `content_type` e `accept_type` vengono impostati automaticamente sul valore del parametro `dataset_type`, che è `application/json`. Il processo di elaborazione di SageMaker Clarify utilizza quindi il `content_template` parametro per comporre l'input del modello.
Nell'esempio seguente, l'input del modello è composto sostituendo il segnaposto `$records` con una matrice di record. Quindi, il parametro `record_template` compone la struttura JSON di ogni record e sostituisce il segnaposto `$features` con la matrice di funzionalità di ogni record.
Il seguente esempio di configurazione di analisi indica al processo di elaborazione SageMaker Clarify di calcolare tutte le possibili metriche di distorsione sia per il set di dati che per il modello.
```
{
"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"
}
}
```
#### Calcola i valori SHAP
Non è necessario specificare un'etichetta per l'analisi SHAP. Nel seguente esempio, il parametro `headers` non è impostato. Pertanto, il processo di elaborazione SageMaker Clarify genererà segnaposti utilizzando nomi generici come `column_0` o `column_1` per le intestazioni delle funzionalità e per l'intestazione di un'etichetta. `label0` È possibile specificare i valori per `headers` e `label`, in modo da migliorare la leggibilità del risultato dell'analisi.
Nel seguente esempio di configurazione, il parametro di probabilità è impostato su un' JMESPath espressione che estrae le probabilità da ogni previsione per ogni record. Di seguito è riportato un esempio per calcolare i valori 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"
}
}
```
#### Calcola i grafici di dipendenza parziale () PDPs
L'esempio seguente mostra come visualizzare l'importanza di una funzionalità in. PDPs Nell'esempio, le intestazioni delle funzionalità non vengono fornite. Pertanto, il parametro `features` del metodo `pdp` deve utilizzare un indice a base zero per fare riferimento alla posizione della colonna di funzionalità. Il parametro `grid_resolution` divide l'intervallo dei valori della funzionalità in bucket `10`.
Insieme, i parametri dell'esempio seguente indicano al processo di elaborazione SageMaker Clarify di generare un report contenente un grafico PDP per i `10` segmenti sull'`Income`asse x. L'asse y mostra l'impatto marginale di `Income` sulle predizioni.
Il seguente esempio di configurazione mostra come visualizzare l'importanza di on. `Income` 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"
}
}
```
#### Calcola sia i parametri di bias che l'importanza delle funzionalità
Puoi combinare tutti i metodi di configurazione precedenti in un unico file di configurazione dell'analisi e calcolarli tutti in un unico processo. L'esempio seguente mostra una configurazione di analisi con tutte le fasi combinate.
In questo esempio, il parametro `probability` è impostato. Poiché l'analisi dei bias richiede un'etichetta prevista, il parametro `probability_threshold` viene impostato su `0.5`, che viene utilizzato per convertire il punteggio di probabilità in un'etichetta binaria. In questo esempio, il parametro `top_k_features` del metodo `pdp` è impostato su `2`. Questo indica al processo di elaborazione di SageMaker Clarify di calcolare le `2` funzionalità principali con PDPs i valori SHAP globali più elevati.
```
{
"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"
}
}
```
### Configurazione di analisi per la spiegabilità dell'elaborazione del linguaggio naturale
L'esempio seguente mostra un file di configurazione di analisi per il calcolo dell'importanza della funzionalità per l'elaborazione del linguaggio naturale (NLP). In questo esempio, il set di dati in entrata è un set di dati tabulare in formato CSV, con una colonna dell'etichetta binaria e due colonne di funzionalità, come mostrato in seguito. Il set di dati viene fornito al job SageMaker Clarify dal parametro di input di elaborazione. `dataset`
```
0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...
```
In questo esempio, un modello di classificazione binaria è stato addestrato sul precedente set di dati. Il modello accetta dati CSV e restituisce un singolo punteggio compreso tra `0` e `1`, come mostrato in seguito.
```
0.491656005382537
0.569582343101501
...
```
Il modello viene utilizzato per creare un modello di SageMaker intelligenza artificiale denominato «your\$1model». La seguente configurazione di analisi mostra come eseguire un'analisi di spiegabilità basata su token utilizzando il modello e il set di dati. Il parametro `text_config` attiva l'analisi della spiegabilità dell'elabroazione del linguaggio naturale. Il parametro `granularity` indica che l'analisi deve analizzare i token.
In inglese, ogni token è una parola. L'esempio seguente mostra anche come fornire un'istanza SHAP locale di base utilizzando una valutazione media di 4. Uno speciale token maschera "[MASK]" viene utilizzato per sostituire un token (parola) in "Commenti". Questo esempio utilizza anche un tipo di istanza di endpoint GPU per accelerare l'inferenza.
```
{
"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"
}
}
```
### Configurazione di analisi per la spiegabilità della visione artificiale
L'esempio seguente mostra un file di configurazione di analisi per il calcolo dell'importanza della funzionalità per la visione artificiale. In questo esempio, il set di dati di input è costituito da immagini JPEG. Il set di dati viene fornito al job SageMaker Clarify dal parametro di input di elaborazione. `dataset` L'esempio mostra come configurare un'analisi di spiegabilità utilizzando un SageMaker modello di classificazione delle immagini. In questo esempio, un modello denominato `your_cv_ic_model` è stato addestrato a classificare gli animali nelle immagini JPEG di input.
```
{
"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"]
}
}
```
Per ulteriori informazioni sulla classificazione delle immagini, consulta [Classificazione delle immagini - MXNet](image-classification.md).
In questo esempio, un [modello di rilevamento di oggetti SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html) `your_cv_od_model` viene addestrato sulle stesse immagini JPEG per identificare gli animali su di esse. Il prossimo esempio mostra come generare spiegazioni per il rilevamento di oggetti.
```
{
"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"]
}
}
```
### Configurazione dell’analisi per la spiegabilità dei modelli di previsione delle serie temporali
L’esempio seguente mostra un file di configurazione dell’analisi per il calcolo dell’importanza della funzionalità per una serie temporale (TS). In questo esempio, il set di dati in entrata è un set di dati di serie temporali in formato JSON con un set di funzionalità di covariate dinamiche e statiche. Il set di dati viene fornito al job SageMaker Clarify dal parametro di input di elaborazione del set di dati. `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
},
]
```
Le sezioni seguenti spiegano come calcolare le attribuzioni delle funzionalità per un modello di previsione con l’algoritmo con valori asimmetrici di Shapley per un set di dati JSON.
#### Calcolo delle spiegazioni per i modelli di previsione delle serie temporali
L’esempio seguente di configurazione dell’analisi mostra le opzioni utilizzate dal processo per calcolare le spiegazioni per i modelli di previsione delle serie temporali.
```
{
'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'
}
}
```
##### Configurazione della spiegabilità delle serie temporali
L’esempio precedente utilizza `asymmetric_shapley_value` in `methods` per definire gli argomenti di spiegabilità delle serie temporali come baseline, direzione, granularità e numero di campioni. I valori baseline sono impostati per tutti e tre i tipi di dati: serie temporali correlate, covariate statiche e serie temporali di destinazione. Questi campi indicano al processore SageMaker Clarify di calcolare le attribuzioni delle funzionalità per un elemento alla volta.
##### Configurazione del predittore
È possibile controllare completamente la struttura del payload inviata dal processore SageMaker Clarify utilizzando la sintassi. JMESPath Nell’esempio precedente, la configurazione `predictor` indica a Clarify di aggregare i record in `'{"instances": $records}'`, dove ogni record è definito con gli argomenti forniti per `record_template` nell’esempio. Nota che `$start_time`, `$target_time_series`, `$related_time_series` e `$static_covariates` sono token interni utilizzati per mappare i valori del set di dati ai valori delle richieste degli endpoint.
Allo stesso modo, l’attributo `forecast` in `time_series_predictor_config` viene utilizzato per estrarre la previsione del modello dalla risposta dell’endpoint. Ad esempio, la risposta in batch dell’endpoint potrebbe essere la seguente:
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
Supponiamo di specificare la seguente configurazione del predittore di serie temporali:
```
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
```
Il valore di previsione viene analizzato come descritto di seguito:
```
[
[13.4, 3.6],
[23.0, 4.7],
[3.4, 5.6]
]
```
##### Dati di configurazione
Utilizzate l'`time_series_data_config`attributo per indicare al processore SageMaker Clarify di analizzare correttamente i dati a partire dai dati passati come URI S3 in. `dataset_uri`
# Guida alla compatibilità di formato dei dati
Questa guida descrive i tipi di formato dei dati compatibili con i processi di elaborazione di SageMaker Clarify. I tipi di formato di dati supportati includono le estensioni dei file, la struttura dei dati e i requisiti o le restrizioni specifici per i set di dati tabulari, di immagini e di serie temporali. La guida mostra anche come verificare se il set di dati è conforme a questi requisiti.
Ad un livello elevato, il processo di elaborazione di SageMaker Clarify segue il modello di input-processo-output per calcolare le metriche di distorsione e le attribuzioni di funzionalità. Per i dettagli, consulta gli esempi seguenti.
L'input per il processo di elaborazione di Clarify è costituito da quanto segue: SageMaker
+ Il set di dati da analizzare.
+ La configurazione dell'analisi Per ulteriori informazioni su come configurare un’analisi, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Durante la fase di elaborazione, SageMaker Clarify calcola le metriche di distorsione e l'attribuzione delle funzionalità. Il processo di elaborazione di SageMaker Clarify completa i seguenti passaggi nel backend:
+ **Il processo di elaborazione SageMaker Clarify analizza la configurazione dell'analisi e carica il set di dati.**
+ Per calcolare i parametri di bias e le attribuzioni delle funzionalità post-addestramento, il processo richiede previsioni basate sul modello. **Il processo di elaborazione SageMaker Clarify serializza i dati e li invia come **richiesta al modello che viene distribuito su un endpoint** di inferenza in tempo reale di intelligenza artificiale. SageMaker ** **Successivamente, il processo di elaborazione di SageMaker Clarify estrae le previsioni dalla risposta.**
+ Il processo di elaborazione di SageMaker Clarify esegue l'analisi delle distorsioni e della spiegabilità, quindi produce i risultati.
Per ulteriori informazioni, consulta [Come funzionano i lavori di elaborazione di SageMaker Clarify](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works).
Il parametro utilizzato per specificare il formato dei dati dipende da dove i dati vengono utilizzati nel flusso di elaborazione, come mostrato in seguito:
+ Per un **set di dati di input**, utilizza il parametro `dataset_type` per specificare il formato o il tipo MIME.
+ Per una **richiesta** a un endpoint, utilizza il parametro `content_type` per specificare il formato.
+ Per una **risposta** a un endpoint, utilizza il parametro `accept_type` per specificare il formato.
Il set di dati di input, la richiesta e la risposta da e verso l'endpoint non richiedono lo stesso formato. Ad esempio, è possibile utilizzare un set di dati Parquet con un payload di **richiesta** CSV e un payload di **risposta** JSON Lines, date le condizioni descritte in seguito.
+ L'analisi è configurata correttamente.
+ Il modello supporta i formati di richiesta e risposta.
**Nota**
Se `accept_type` vengono forniti `content_type` o meno, il contenitore SageMaker Clarify deduce e. `content_type` `accept_type`
**Topics**
+ [Dati tabulari](clarify-processing-job-data-format-tabular.md)
+ [Requisiti dei dati delle immagini](clarify-processing-job-data-format-image.md)
+ [Dati di serie temporali](clarify-processing-job-data-format-time-series.md)
# Dati tabulari
I dati tabulari si riferiscono ai dati che possono essere caricati in un frame di dati bidimensionale. Nel frame, ogni riga rappresenta un record e ogni record ha una o più colonne. I valori all'interno di ogni cella del frame di dati possono essere di tipo numerico, categorico o testuale.
## Prerequisiti del set di dati tabulari
Prima dell'analisi, al set di dati dovrebbe aver completato tutte le fasi di pre-elaborazione necessarie. Questo include la pulizia dei dati o l’ingegneria delle funzionalità.
È possibile fornire uno o più set di dati. Se fornite più set di dati, utilizzate quanto segue per identificarli nel processo di elaborazione di SageMaker Clarify.
+ Utilizzate una configurazione [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)denominata `dataset` o di analisi `dataset_uri` per specificare il set di dati principale. Per ulteriori informazioni su `dataset_uri`, consulta l’elenco di parametri in [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
+ Utilizza il parametro `baseline` fornito nel file di configurazione dell'analisi. Il set di dati di base è necessario per l'analisi SHAP. Per ulteriori informazioni sul file di configurazione dell’analisi, inclusi gli esempi, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Questa tabella elenca i formati di dati supportati, le relative estensioni di file e i tipi MIME.
| Formato dei dati | Estensione di file | Tipo MIME |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| JSON Lines | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | "application/x-parquet" |
Le successive sezioni mostrano esempi di set di dati tabulari nei formati CSV, JSON Lines e Apache Parquet.
### Prerequisiti dei set di dati tabulari in formato CSV
[Il processo di elaborazione SageMaker Clarify è progettato per caricare file di dati CSV nel dialetto csv.excel.](https://docs.python.org/3/library/csv.html#csv.excel) Tuttavia, è sufficientemente flessibile da supportare altri terminatori di linea, tra cui `\n` e `\r`.
Per motivi di compatibilità, tutti i file di dati CSV forniti al processo di elaborazione SageMaker Clarify devono essere codificati in UTF-8.
Se il set di dati non contiene una riga di intestazione, procedi come indicato di seguito:
+ Imposta l'etichetta di configurazione dell'analisi sull'indice `0`. Questo significa che la prima colonna è l'etichetta Ground Truth.
+ Se il parametro `headers` è specificato, imposta `label` sull'intestazione della colonna dell'etichetta per indicare la posizione della colonna di etichetta. Tutte le altre colonne sono designate come funzionalità.
Di seguito è riportato un set di dati che non contiene una riga di intestazione.
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
Se i dati contengono una riga di intestazione, imposta il parametro `label` sull'indice `0`. Per indicare la posizione della colonna dell'etichetta, usa l'intestazione `Label` dell'etichetta Ground Truth. Tutte le altre colonne sono designate come funzionalità.
Di seguito è riportato un esempio di set di dati contenente una riga di intestazione.
```
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
...
```
### Prerequisiti dei set di dati tabulari in formato JSON
JSON è un formato flessibile per la rappresentazione di dati strutturati che contiene qualsiasi livello di complessità. Il supporto SageMaker Clarify per JSON non è limitato a nessun formato specifico e consente quindi formati di dati più flessibili rispetto ai set di dati nei formati CSV o JSON Lines. Questa guida mostra come impostare una configurazione di analisi per dati tabulari in formato JSON.
**Nota**
Per garantire la compatibilità, tutti i file di dati JSON forniti al processo di elaborazione SageMaker Clarify devono essere codificati in UTF-8.
Di seguito è riportato un esempio di dati di input con record che contengono una chiave di livello superiore, un elenco di funzionalità e un'etichetta.
```
[
{"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 esempio di analisi della configurazione per il precedente esempio di set di dati di input dovrebbe impostare i seguenti parametri:
+ Il `label` parametro deve utilizzare l'[JMESPath](https://jmespath.org/)espressione `[*].label` per estrarre l'etichetta di verità fondamentale per ogni record nel set di dati. L' JMESPath espressione dovrebbe produrre un elenco di etichette in cui i l'etichetta corrisponde a quella del record.
+ Il `features` parametro deve utilizzare l' JMESPathespressione `[*].features` per estrarre una serie di funzionalità per ogni record nel set di dati. L' JMESPath espressione dovrebbe produrre una matrice o una matrice 2D in cui la riga i contiene i valori delle caratteristiche corrispondenti a quelli del record.
Di seguito è riportato un esempio di dati di input con record che contiene una chiave di livello superiore e una chiave nidficata che contiene un elenco di funzionalità e un'etichetta.
```
{
"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 esempio di analisi della configurazione per il precedente esempio di set di dati di input dovrebbe impostare i seguenti parametri:
+ Il `label` parametro utilizza l'[JMESPath](https://jmespath.org/)espressione `data[*].label` per estrarre l'etichetta di verità fondamentale per ogni record del set di dati. L' JMESPath espressione dovrebbe produrre un elenco di etichette in cui i l'etichetta è per loro nel record.
+ Il `features` parametro utilizza l' JMESPath espressione `data[*].features` per estrarre la serie di funzionalità, per ogni record nel set di dati. L' JMESPath espressione dovrebbe produrre una matrice o una matrice 2D in cui la riga i contiene i valori delle caratteristiche relative al record.
### Prerequisiti dei set di dati tabulari in formato JSON Lines
JSON Lines è un formato di testo per rappresentare dati strutturati in cui ogni riga è un oggetto JSON valido. Attualmente i processi di elaborazione di SageMaker Clarify supportano solo le linee JSON in formato SageMaker AI Dense. Per conformarsi al formato richiesto, tutte le funzionalità di un record devono essere elencate in un'unica matrice JSON. Per ulteriori informazioni su righe JSON, consultare [Formato della richiesta JSONLINES](cdf-inference.md#cm-jsonlines).
**Nota**
Tutti i file di dati JSON Lines forniti al processo di elaborazione SageMaker Clarify devono essere codificati in UTF-8 per garantire la compatibilità.
Di seguito è riportato un esempio di come impostare una configurazione di analisi per un record che contiene una chiave di **livello superiore** e un **elenco** di elementi.
```
{"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}
...
```
L'analisi della configurazione per il precedente esempio di set di dati dovrebbe impostare i parametri come segue:
+ Per indicare la posizione dell'etichetta di verità fondamentale, il parametro `label` deve essere impostato sull'espressione. JMESPath `label`
+ Per indicare la posizione dell'array di caratteristiche, è `features` necessario impostare il parametro sull' JMESPath espressione`features`.
Di seguito è riportato un esempio di come impostare una configurazione di analisi per un record che contiene una **chiave di livello superiore** e una **chiave nidificata** che contiene un **elenco** di elementi.
```
{"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}}
...
```
L'analisi della configurazione per il precedente esempio di set di dati dovrebbe impostare i parametri come segue:
+ Il parametro `label` deve essere impostato sull' JMESPathespressione `data.label` per indicare la posizione dell'etichetta di verità fondamentale.
+ Il parametro `features` deve essere impostato sull' JMESPathespressione `data.features` per indicare la posizione della serie di caratteristiche.
### Prerequisiti dei set di dati tabulari in formato Parquet
[Parquet](https://parquet.apache.org/) è un formato di dati binario orientato alle colonne. Attualmente, i processi di elaborazione di SageMaker Clarify supportano il caricamento dei file di dati di Parquet solo quando il numero delle istanze di elaborazione è `1` pari a.
Poiché i processi di elaborazione SageMaker Clarify non supportano la richiesta dell'endpoint o la risposta dell'endpoint in formato Parquet, è necessario specificare il formato dei dati della richiesta dell'endpoint impostando il parametro `content_type` di configurazione dell'analisi su un formato supportato. Per ulteriori informazioni, consulta `content_type` in [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
I dati Parquet devono avere nomi di colonna formattati come stringhe. Utilizza il parametro `label` di configurazione dell'analisi per impostare il nome della colonna dell'etichetta, in modo che indichi la posizione delle etichette Ground Truth. Tutte le altre colonne sono designate come funzionalità.
# Richieste endpoint per dati tabulari
Per ottenere previsioni basate sui modelli per l'analisi delle distorsioni post-allenamento e l'analisi dell'importanza delle funzionalità, i processi di elaborazione di SageMaker Clarify serializzano i dati tabulari in byte e li inviano a un endpoint di inferenza come payload di richieste. Questi dati tabulari provengono dal set di dati di input o vengono generati. Se si tratta di dati sintetici, vengono generati dall'esplicatore per l'analisi SHAP o PDP.
Il formato dei dati di payload della richiesta deve essere specificato dal parametro `content_type` di configurazione dell'analisi. Se il parametro non viene fornito, il processo di elaborazione SageMaker Clarify utilizzerà il valore del parametro come tipo di contenuto. `dataset_type` Per ulteriori informazioni su `content_type` o `dataset_type`, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Le successive sezioni mostrano esempi di richieste endpoint nei formati CSV e JSON Lines.
## Richiesta dell'endpoint in formato CSV
Il processo di elaborazione SageMaker Clarify può serializzare i dati in formato CSV (tipo MIME:). `text/csv` La seguente tabella mostra esempi dei payload di richiesta serializzati.
| Payload di richiesta dell'endpoint (rappresentazione di stringhe) | Commenti |
| --- | --- |
| '1,2,3,4' | Record singolo (quattro funzionalità numeriche). |
| '1,2,3,4\$1n5,6,7,8' | Due record, separati da un'interruzione di riga \$1n. |
| '"Questo è un buon prodotto",5' | Record singolo (una funzionalità testuale e una numerica). |
| '"Questo è un buon prodotto",5\$1n"Pessima esperienza di acquisto",1' | Due record. |
## La richiesta dell'endpoint è in formato JSON Lines
Il processo di elaborazione SageMaker Clarify può serializzare i dati nel formato denso SageMaker AI JSON Lines (tipo MIME:). `application/jsonlines` Per ulteriori informazioni su righe JSON, consultare [Formato della richiesta JSONLINES](cdf-inference.md#cm-jsonlines).
Per trasformare i dati tabulari in dati JSON, fornisci una stringa modello al parametro `content_template` di configurazione dell'analisi. Per ulteriori informazioni su `content_template`, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md). La seguente tabella mostra esempi dei payload di richiesta serializzati.
| Payload di richiesta dell'endpoint (rappresentazione di stringhe) | Commenti |
| --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | Record singolo. In questo caso, la stringa di esempio assomiglia a`'{"data":{"features":$features}}' ` e `$features` viene sostituito dall'elenco delle funzionalità `[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' | Due record. |
| '\$1"features":["Questo è un buon prodotto",5]\$1' | Record singolo. In questo caso, la stringa di esempio assomiglia a `'{"features":$features}'` e \$1features viene sostituito dall'elenco delle funzionalità `["This is a good product",5]`. |
| '\$1"features":["Questo è un buon prodotto",5]\$1\$1n\$1"features":["Pessima esperienza di acquisto",1]\$1' | Due record. |
## La richiesta dell'endpoint è in formato JSON
Un processo di elaborazione SageMaker Clarify può serializzare i dati in strutture JSON arbitrarie (tipo MIME:). `application/json` A tale scopo, è necessario fornire una stringa di esempio al parametro `content_template` di configurazione dell'analisi. Viene utilizzato dal processo di elaborazione SageMaker Clarify per costruire la struttura JSON esterna. È inoltre necessario fornire una stringa di esempio per `record_template`, che viene utilizzata per costruire la struttura JSON di ogni record. Per ulteriori informazioni su `content_template` e `record_template`, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
**Nota**
Poiché `content_template` e `record_template` sono parametri di stringa, tutti i caratteri con virgolette doppie (`"`) che fanno parte della struttura serializzata JSON devono essere annotati come caratteri di escape nella configurazione. Ad esempio, se vuoi evitare una virgoletta doppia in Python, puoi inserire quanto segue per `content_template`.
```
"{\"data\":{\"features\":$record}}}"
```
La tabella seguente mostra esempi di payload di richieste JSON serializzate e i corrispondenti parametri `content_template` e `record_template` necessari per costruirli.
| Payload di richiesta dell'endpoint (rappresentazione di stringhe) | Commenti | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | Un singolo record alla volta. | '\$1"data":\$1"features":\$1record\$1\$1\$1' | "\$1features" |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | Record multipli con nomi di funzionalità. | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | "\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | Coppie multi-record e chiave-valore. | "\$1records" | "\$1features\$1kvp" |
| '\$1"A": 0, "B": 1\$1' | Un record alla volta e coppie chiave-valore. | "\$1record" | "\$1features\$1kvp" |
| '\$1"A": 0, "nested": \$1"B": 1\$1\$1' | In alternativa, usa il record\$1template completo per strutture arbitrarie. | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# Risposta dell'endpoint per dati tabulari
Dopo aver ricevuto la risposta di un'invocazione dell'endpoint di inferenza, il processo di elaborazione SageMaker Clarify deserializza il payload di risposta e ne estrae le previsioni. Utilizza il parametro `accept_type` di configurazione dell'analisi per specificare il formato dei dati di payload della richiesta. Se non `accept_type` viene fornito, il processo di elaborazione SageMaker Clarify utilizzerà il valore del parametro content\$1type come formato di output del modello. Per ulteriori informazioni su `accept_type`, consultare [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Le previsioni potrebbero consistere in etichette previste per l'analisi del bias o in valori di probabilità (punteggi) per l'analisi dell'importanza della funzionalità. Nella configurazione dell'analisi `predictor`, i seguenti tre parametri estraggono le previsioni.
+ Il parametro `probability` viene utilizzato per individuare i valori di probabilità (punteggi) nella risposta dell'endpoint.
+ Il parametro `label` viene utilizzato per individuare le etichette previste nella risposta dell'endpoint.
+ (Facoltativo) Il parametro `label_headers` fornisce le etichette previste per un modello multiclasse.
Le seguenti linee guida riguardano le risposte dell'endpoint nei formati CSV, JSON Lines e JSON.
## La risposta dell'endpoint è in formato CSV
Se il payload di risposta è in formato CSV (tipo MIME:`text/csv`), il processo di elaborazione SageMaker Clarify deserializza ogni riga. Quindi estrae le previsioni dai dati deserializzati utilizzando gli indici delle colonne forniti nella configurazione dell'analisi. Le righe del payload di risposta devono corrispondere ai record nel payload di richiesta.
Le seguenti tabelle forniscono esempi di dati di risposta in diversi formati e per diversi tipi di problemi. I tuoi dati possono variare rispetto a questi esempi, ammesso che le previsioni possano essere estratte in base alla configurazione dell'analisi.
Le successive sezioni mostrano esempi di risposte endpoint in formato CSV.
### La risposta dell'endpoint è in formato CSV e contiene solo la probabilità
La seguente tabella è un esempio di risposta dell'endpoint per problemi di regressione e classificazione binaria.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo. | '0.6' |
| Due record (risultati in una riga, divisi da una virgola). | '0.6,0.3' |
| Due record (risultati in due righe). | '0.6\$1n0.3' |
Nell'esempio precedente, l'endpoint emette un singolo valore di probabilità (punteggio) dell'etichetta prevista. Per estrarre le probabilità utilizzando l'indice e utilizzarle per l'analisi dell'importanza della funzionalità, imposta il parametro `probability` di configurazione dell'analisi sull'indice di colonna `0`. Queste probabilità possono essere utilizzate anche per l'analisi dei bias se vengono convertite in valori binari utilizzando il parametro `probability_threshold`. Per ulteriori informazioni su `probability_threshold`, consultare [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
La seguente tabella è un esempio di risposta dell'endpoint per problemi multiclasse.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo di un modello multiclasse (tre classi). | '0.1,0.6,0.3' |
| Due record di un modello multiclasse (tre classi) | '0.1,0.6,0.3\$1n0.2,0.5,0.3' |
Nell'esempio precedente, l'endpoint restituisce un elenco di probabilità (punteggi). Se non viene fornito alcun indice, tutti i valori vengono estratti e utilizzati per l'analisi dell'importanza della funzionalità. Se il parametro `label_headers` viene specificato. Quindi il processo di elaborazione SageMaker Clarify può selezionare l'intestazione dell'etichetta con la probabilità massima come etichetta prevista, che può essere utilizzata per l'analisi delle distorsioni. Per ulteriori informazioni su `label_headers`, consultare [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
### La risposta dell'endpoint è in formato CSV e contiene solo l'etichetta prevista
La seguente tabella è un esempio di risposta dell'endpoint per problemi di regressione e classificazione binaria.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '1' |
| Due record (risultati in una riga, divisi da una virgola). | '1,0' |
| Due record (risultati in due righe) | '1\$1n0' |
Nell'esempio precedente, l'endpoint emette l'etichetta prevista anziché un singolo valore di probabilità (punteggio). Imposta il parametro `label` della configurazione `predictor` sull'indice di colonna `0`, in modo che le etichette previste possano essere estratte utilizzando l'indice e utilizzate per l'analisi dei bias.
### La risposta dell'endpoint è in formato CSV e contiene l'etichetta prevista e la probabilità
La seguente tabella è un esempio di risposta dell'endpoint per problemi di regressione e classificazione binaria.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '1,0.6' |
| Due record | '1,0.6\$1n0,0.3' |
Nell'esempio precedente, l'endpoint emette l'etichetta prevista seguita dalla sua probabilità. Imposta il parametro `label` della configurazione `predictor` sull'indice di colonna `0` e imposta `probability` sull'indice di colonna `1` per estrarre entrambi i valori dei parametri.
### La risposta dell'endpoint è in formato CSV e contiene le etichette previste e le probabilità (multiclasse)
Un modello multiclasse addestrato da Amazon SageMaker Autopilot può essere configurato per generare la rappresentazione in formato stringa dell'elenco di etichette e probabilità previste. La tabella di esempio seguente mostra un esempio di risposta dell'endpoint da un modello configurato per emettere `predicted_label`, `probability`, `labels` e `probabilities`.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"' |
| Due record | '"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]"' |
Per l'esempio precedente, il processo di elaborazione di SageMaker Clarify può essere configurato nei seguenti modi per estrarre le previsioni.
Per l'analisi dei bias, il precedente esempio può essere configurato come indicato in seguito.
+ Imposta il parametro `label` della configurazione `predictor` su `0`, per estrarre l'etichetta prevista.
+ Imposta il parametro `2` per estrarre le etichette previste e imposta `probability` su `3`, per estrarre le probabilità corrispondenti. Il processo di elaborazione SageMaker Clarify può determinare automaticamente l'etichetta prevista identificando l'etichetta con il valore di probabilità più elevato. Facendo riferimento all'esempio precedente di un singolo record, il modello prevede tre etichette: `cat`, `dog` e `fish`, con le probabilità corrispondenti di `0.1`, `0.6` e `0.3`. In base a queste probabilità, l'etichetta prevista è `dog`, in quanto ha un valore di probabilità più elevato di `0.6`.
+ Imposta `probability` su `3` per estrarre le probabilità. Se `label_headers` viene fornito, il processo di elaborazione SageMaker Clarify può determinare automaticamente l'etichetta prevista identificando l'intestazione dell'etichetta con il valore di probabilità più elevato.
Per l'analisi dell'importanza della funzionalità, l'esempio precedente può essere configurato come segue.
+ Imposta `probability` su `3` per estrarre le probabilità di tutte le etichette previste. Quindi, verranno calcolate le attribuzioni delle funzionalità per tutte le etichette. Se il cliente non specifica `label_headers`, le etichette previste verranno utilizzate come intestazioni delle etichette nel rapporto di analisi.
## La risposta dell'endpoint è in formato JSON Lines
Se il payload di risposta è in formato JSON Lines (tipo MIME:`application/jsonlines`), il processo di elaborazione SageMaker Clarify deserializza ogni riga come JSON. Quindi estrae le previsioni dai dati deserializzati utilizzando le espressioni fornite nella configurazione dell'analisi. JMESPath Le righe del payload di risposta devono corrispondere ai record nel payload di richiesta. Le seguenti tabelle mostrano esempi dei dati di risposta in diversi formati. I tuoi dati possono variare rispetto a questi esempi, ammesso che le previsioni possano essere estratte in base alla configurazione dell'analisi.
Le successive sezioni mostrano esempi di risposte degli endpoint in formato JSON Lines.
### La risposta dell'endpoint è in formato JSON Lines e contiene solo la probabilità
La seguente tabella è un esempio di risposta dell'endpoint che restituisce solo il valore di probabilità (punteggio).
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"score":0.6\$1' |
| Due record | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' |
Per l'esempio precedente, impostate il parametro di configurazione dell'analisi sull' JMESPath espressione «score» `probability` per estrarne il valore.
### La risposta dell'endpoint è in formato JSON Lines e contiene solo l'etichetta prevista
La seguente tabella è un esempio di risposta dell'endpoint che restituisce solo l'etichetta prevista.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"prediction":1\$1' |
| Due record | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
Per l'esempio precedente, imposta il `label` parametro della configurazione del predittore su JMESPath expression`prediction`. Quindi, il processo di elaborazione di SageMaker Clarify può estrarre le etichette previste per l'analisi delle distorsioni. Per ulteriori informazioni, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
### La risposta dell'endpoint è in formato JSON Lines e contiene l'etichetta prevista e la probabilità
La seguente tabella è un esempio di risposta dell'endpoint che restituisce l'etichetta prevista e il suo punteggio.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"prediction":1,"score":0.6\$1' |
| Due record | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
Per l'esempio precedente, impostate il `label` parametro della `predictor` configurazione sull' JMESPath espressione «prediction» per estrarre le etichette previste. Imposta `probability` sull' JMESPath espressione «score» per estrarre la probabilità. Per ulteriori informazioni, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
### La risposta dell'endpoint è in formato JSON Lines e contiene le etichette previste e le probabilità (multiclasse)
La seguente tabella è un esempio di risposta dell'endpoint, ottenuta da un modello multiclasse che restituisce quanto segue:
+ Un elenco di etichette previste.
+ Le probabilità e l'etichetta prevista selezionata e la sua probabilità.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' |
| Due record | '\$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' |
Per l'esempio precedente, il processo di elaborazione di SageMaker Clarify può essere configurato in diversi modi per estrarre le previsioni.
Per l'analisi dei bias, il precedente esempio può essere configurato in **uno** dei modi descritti in seguito.
+ Imposta il `label` parametro della `predictor` configurazione sull' JMESPath espressione «predicted\$1label» per estrarre l'etichetta prevista.
+ Imposta il parametro sull' JMESPath espressione «predicted\$1labels» per estrarre le etichette previste. Imposta `probability` l' JMESPath espressione «probabilità» per estrarne le probabilità. Il job SageMaker Clarify determina automaticamente l'etichetta prevista identificando l'etichetta con il valore di probabilità più elevato.
+ Imposta `probability` l' JMESPath espressione «probabilità» per estrarne le probabilità. Se `label_headers` viene fornita, il processo di elaborazione SageMaker Clarify può determinare automaticamente l'etichetta prevista identificando l'etichetta con il valore di probabilità più elevato.
Per l'analisi dell'importanza della funzionalità, procedi come segue.
+ Imposta `probability` l' JMESPath espressione «probabilità» per estrarre le probabilità relative a tutte le etichette previste. Quindi, verranno calcolate le attribuzioni delle funzionalità per tutte le etichette.
## La risposta dell'endpoint è in formato JSON
Se il payload di risposta è in formato JSON (tipo MIME:`application/json`), il processo di elaborazione SageMaker Clarify deserializza l'intero payload come JSON. Quindi estrae le previsioni dai dati deserializzati utilizzando le espressioni fornite nella configurazione dell'analisi. JMESPath I record del payload di risposta devono corrispondere ai record nel payload di richiesta.
Le successive sezioni mostrano esempi di risposte degli endpoint in formato JSON Lines. Queste sezioni contengono tabelle con esempi dei dati di risposta in diversi formati e per diversi tipi di problemi. I tuoi dati possono variare rispetto a questi esempi, ammesso che le previsioni possano essere estratte in base alla configurazione dell'analisi.
### La risposta dell'endpoint è in formato JSON e contiene solo la probabilità
La seguente tabella è un esempio di risposta da parte di un endpoint che restituisce solo il valore di probabilità (punteggio).
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '[0.6]' |
| Due record | '[0.6,0.3]' |
Nell'esempio precedente, non vi è alcuna interruzione di riga nel payload di risposta. Un singolo oggetto JSON contiene invece un elenco di punteggi, uno per ogni record nella richiesta. Impostate il parametro `probability` di configurazione dell'analisi sull' JMESPath espressione «[\$1]» per estrarre il valore.
### La risposta dell'endpoint è in formato JSON e contiene solo l'etichetta prevista
La seguente tabella è un esempio di risposta da parte di un endpoint che restituisce solo l'etichetta prevista.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"predicted\$1labels":[1]\$1' |
| Due record | '\$1"predicted\$1labels":[1,0]\$1' |
Imposta il `label` parametro della `predictor` configurazione sull' JMESPath espressione «predicted\$1labels», quindi il processo di elaborazione SageMaker Clarify può estrarre le etichette previste per l'analisi delle distorsioni.
### La risposta dell'endpoint è in formato JSON e contiene l'etichetta prevista e la probabilità
La seguente tabella è un esempio di risposta da parte di un endpoint che restituisce l'etichetta prevista e il suo punteggio.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '\$1"predictions":[\$1"label":1,"score":0.6\$1' |
| Due record | ‘\$1"predictions":[\$1"label":1,"score":0.6\$1,\$1"label":0,"score":0.3\$1]\$1' |
Per l'esempio precedente, impostate il `label` parametro della `predictor` configurazione sull' JMESPath espressione «predictions [\$1] .label» per estrarre le etichette previste. Imposta `probability` l' JMESPath espressione «predictions [\$1] .score» per estrarre la probabilità.
### La risposta dell'endpoint è in formato JSON e contiene le etichette previste e le probabilità (multiclasse)
La seguente tabella è un esempio di risposta da parte di un endpoint, ottenuta da un modello multiclasse che restituisce quanto segue:
+ Un elenco di etichette previste.
+ Le probabilità e l'etichetta prevista selezionata e la sua probabilità.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Record singolo | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1]' |
| Due record | '[\$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]' |
Il processo di elaborazione di SageMaker Clarify può essere configurato in diversi modi per estrarre le previsioni.
Per l'analisi dei bias, il precedente esempio può essere configurato in **uno** dei modi descritti in seguito.
+ Imposta il `label` parametro della `predictor` configurazione sull' JMESPath espressione «[\$1] .predicted\$1label» per estrarre l'etichetta prevista.
+ Imposta il parametro sull' JMESPath espressione «[\$1] .predicted\$1labels» per estrarre le etichette previste. Imposta `probability` l' JMESPath espressione «[\$1] .probabilities» per estrarne le probabilità. Il processo di elaborazione SageMaker Clarify può determinare automaticamente l'etichetta prevista identificando l'etichetta con il valore di prossimità più elevato.
+ Impostate `probability` l' JMESPath espressione «[\$1] .probabilities» per estrarne le probabilità. Se `label_headers` viene fornita, il processo di elaborazione di SageMaker Clarify può determinare automaticamente l'etichetta prevista identificando l'etichetta con il valore di probabilità più elevato.
Per l'analisi dell'importanza delle caratteristiche, impostate `probability` JMESPath l'espressione «[\$1] .probabilities» per estrarre le probabilità relative a tutte le etichette previste. Quindi, verranno calcolate le attribuzioni delle funzionalità per tutte le etichette.
# Verifica preventivamente la richiesta e la risposta dell'endpoint per i dati tabulari
Ti consigliamo di distribuire il modello su un endpoint di inferenza SageMaker AI in tempo reale e di inviare richieste all'endpoint. Esamina manualmente le richieste e le risposte per assicurarti che entrambe siano conformi ai requisiti della sezione [Richieste endpoint per dati tabulari](clarify-processing-job-data-format-tabular-request.md) e della sezione [Risposta dell'endpoint per dati tabulari](clarify-processing-job-data-format-tabular-response.md). Se il container del modello supporta le richieste batch, è possibile iniziare con una singola richiesta di record e quindi provare due o più record.
I comandi seguenti mostrano come richiedere una risposta utilizzando AWS CLI. AWS CLI È preinstallato nelle istanze Studio e Notebook SageMaker . SageMaker Per installare AWS CLI, segui questa guida all'[installazione](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
```
I parametri sono definiti come segue:
+ `$ENDPOINT NAME`: il nome dell'endpoint.
+ `$CONTENT_TYPE`: il tipo MIME della richiesta (input del container del modello).
+ `$ACCEPT_TYPE`: il tipo MIME della risposta (output del container del modello).
+ `$REQUEST_DATA`: la stringa payload richiesta.
+ `$CLI_BINARY_FORMAT`: il formato del parametro di interfaccia della linea di comando (CLI). Per la AWS CLI versione 1, questo parametro deve rimanere vuoto. Per v2, questo parametro deve essere impostato su `--cli-binary-format raw-in-base64-out`.
**Nota**
AWS CLI [Per impostazione predefinita, v2 passa i parametri binari come stringhe con codifica base64.](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam)
# AWS CLI esempi v1
L'esempio nella sezione precedente riguardava la v2. AWS CLI I seguenti esempi di richieste e risposte da e verso l'endpoint utilizzano AWS CLI v1.
## Richiesta e risposta dell'endpoint in formato CSV
Nel seguente esempio di codice, la richiesta è costituita da un singolo record e la risposta è il relativo valore di 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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
0.6
```
Nel prossimo esempio di codice, la richiesta è costituita da due record e la risposta include le relative probabilità, separate da una virgola.
```
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
```
Nell'esempio di codice precedente, l'espressione `$'content'` in `--body` indica al comando di interpretare `'\n'` il contenuto come un'interruzione di riga. Segue l'output della risposta.
```
0.6,0.3
```
Nel prossimo esempio di codice, la richiesta è costituita da due record e la risposta include le relative probabilità, separate da un'interruzione di riga.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
0.6
0.3
```
Nel seguente esempio di codice, la richiesta è costituita da un singolo record e la risposta è costituita da valori di probabilità di un modello multiclasse con tre classi.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
0.1,0.6,0.3
```
Nel seguente esempio di codice, la richiesta è costituita da due record e la risposta include i loro valori di probabilità, ottenuti da un modello multiclasse con tre classi.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
0.1,0.6,0.3
0.2,0.5,0.3
```
Nel seguente esempio di codice, la richiesta è costituita da due record e la risposta include l'etichetta e la probabilità previste.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
1,0.6
0,0.3
```
Nel seguente esempio di codice, la richiesta è costituita da due record e la risposta include le intestazioni delle etichette e le probabilità.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
"['cat','dog','fish']","[0.1,0.6,0.3]"
"['cat','dog','fish']","[0.2,0.5,0.3]"
```
## Richiesta e risposta dell'endpoint in formato JSON Lines
Nel seguente esempio di codice, la richiesta è costituita da un singolo record e la risposta è il relativo valore di 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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"score":0.6}
```
Nel seguente esempio di codice, la richiesta contiene due record e la risposta include l'etichetta e la probabilità previste.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"predicted_label":1,"probability":0.6}
{"predicted_label":0,"probability":0.3}
```
Nel seguente esempio di codice, la richiesta contiene due record e la risposta include le intestazioni e le probabilità delle etichette.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}
```
## Richiesta e risposta dell'endpoint in formati misti
Nel seguente esempio di codice, la richiesta è in formato CSV e la risposta è in formato 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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"probability":0.6}
{"probability":0.3}
```
Nel seguente esempio di codice, la richiesta è in formato JSON Lines e la risposta è in formato 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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
0.6
0.3
```
Nel seguente esempio di codice, la richiesta è in formato CSV e la risposta è in formato 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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# Requisiti dei dati delle immagini
Un processo di elaborazione SageMaker Clarify fornisce supporto per spiegare le immagini. Questo argomento fornisce i requisiti di formato dei dati per i dati di immagini. Per informazioni sull’elaborazione dei dati delle immagini, consulta [Analisi dei dati delle immagini per la spiegabilità della visione artificiale](clarify-processing-job-run.md#clarify-processing-job-run-cv).
Un set di dati di immagini contiene uno o più file di immagine. Per identificare un set di dati di input per il processo di elaborazione di SageMaker Clarify, imposta un `dataset_uri` parametro di configurazione [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs)denominato `dataset` o di analisi su un prefisso URI Amazon S3 dei tuoi file di immagine.
Nella seguente tabella sono elencati i formati di immagine e le estensioni di file supportati.
| Formato di immagine | Estensione di file |
| --- | --- |
| JPEG | jpg, jpeg |
| PNG | png |
Imposta il parametro `dataset_type` di configurazione dell'analisi su **application/x-image**. Poiché il tipo non è un formato di file di immagine specifico, `content_type` verrà utilizzato per decidere il formato e l'estensione del file di immagine.
[Il processo di elaborazione SageMaker Clarify carica ogni file di immagine su un array NumPy tridimensionale per un'ulteriore elaborazione.](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) Le tre dimensioni includono altezza, larghezza e i valori RGB di ogni pixel.
## Formato di richiesta dell’endpoint
Il processo di elaborazione SageMaker Clarify converte i dati RGB non elaborati di un'immagine in un formato di immagine compatibile, come JPEG. Lo fa prima di inviare i dati all'endpoint per le previsioni. I formati di immagine supportati sono i seguenti:
| Formato dei dati | Tipo MIME | Estensione di file |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg, jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | Tutti i formati sopra elencati |
Specifica il formato dei dati di payload della richiesta, utilizzando il parametro `content_type`. Se `content_type` non viene fornito, il formato dei dati predefinito è `image/jpeg`.
## Formato di risposta dell’endpoint
Dopo aver ricevuto la risposta di una chiamata di un endpoint di inferenza, il job di elaborazione SageMaker Clarify deserializza il payload di risposta e quindi ne estrae le previsioni.
### Problema di classificazione delle immagini
Il formato dei dati di payload della risposta deve essere specificato dal parametro accept\$1type di configurazione dell'analisi. Se `accept_type` non viene fornito, il formato dei dati predefinito è `application/json`. I formati supportati sono gli stessi descritti nella sezione dei dati tabulari in **Risposta dell'endpoint per i dati tabulari**.
Vedi un [Inferenza con l'algoritmo di classificazione delle immagini](image-classification.md#IC-inference) esempio di algoritmo di classificazione delle immagini integrato nell' SageMaker intelligenza artificiale che accetta una singola immagine e quindi restituisce una serie di valori di probabilità (punteggi), ciascuno per una classe.
Come mostrato nella tabella seguente, quando il parametro `content_type` è impostato su `application/jsonlines`, la risposta è un oggetto JSON.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Immagine singola | '\$1"prediction":[0.1,0.6,0.3]\$1' |
Nell'esempio precedente, imposta il `probability` parametro sull' JMESPath espressione «previsione» per estrarre i punteggi.
Quando il parametro `content_type` è impostato su `application/json`, la risposta è un oggetto JSON, come mostrato nella seguente tabella.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Immagine singola | '[0.1,0.6,0.3]' |
Nell'esempio precedente, impostate `probability` l' JMESPath espressione «[\$1]» per estrarre tutti gli elementi dell'array. Nell'esempio precedente, [`0.1, 0.6, 0.3]` viene estratto. In alternativa, se ignori l'impostazione del parametro `probability` di configurazione, vengono estratti anche tutti gli elementi della matrice. Questo perché l'intero payload viene deserializzato come le previsioni.
### Problema di rilevamento di oggetti
La configurazione dell’analisi `accept_type` viene impostata sul valore predefinito `application/json` e l’unico formato supportato è Object Detection Inference Format. Per ulteriori informazioni sui formati della risposta, consulta [Formati della risposta](object-detection-in-formats.md#object-detection-recordio).
La seguente tabella è un esempio di risposta da parte di un endpoint che restituisce una matrice. Ogni elemento della matrice è una matrice di valori contenente l'indice di classe, il punteggio di attendibilità e le coordinate dei riquadri di delimitazione dell'oggetto rilevato.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Immagine singola (un oggetto) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| Immagine singola (due oggetti) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
La seguente tabella è un esempio di risposta da un endpoint che genera un oggetto JSON con una chiave che fa riferimento alla matrice. Imposta la configurazione di analisi `probability` sulla chiave "prediction" per estrarre i valori.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) |
| --- | --- |
| Immagine singola (un oggetto) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| Immagine singola (due oggetti) | '\$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' |
## Verifica preventivamente la richiesta e la risposta dell'endpoint per i dati di immagini
Ti consigliamo di distribuire il modello su un endpoint di inferenza in tempo reale di SageMaker intelligenza artificiale e di inviare richieste all'endpoint. Esamina manualmente le richieste e le risposte. Assicurati che entrambe siano conformi ai requisiti nella sezione **Richiesta dell'endpoint per dati di immagini** e **Risposta dell'endpoint per dati di immagini**.
Di seguito sono riportati due esempi di codice che mostrano come inviare richieste ed esaminare le risposte ai problemi di classificazione delle immagini e di rilevamento degli oggetti.
### Problema di classificazione delle immagini
L'esempio di codice seguente indica a un endpoint di leggere un file PNG e quindi lo classifica.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
[0.1,0.6,0.3]
```
### Problema di rilevamento di oggetti
L'esempio di codice seguente indica a un endpoint di leggere un file JPEG e quindi rileva gli oggetti in esso contenuti.
```
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
```
Nell'esempio di codice precedente, segue l'output della risposta.
```
{"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]]}
```
# Dati di serie temporali
I dati di serie temporali si riferiscono ai dati che possono essere caricati in un dataframe tridimensionale. Nel frame di ogni timestamp, ogni riga rappresenta un record di destinazione e ogni record di destinazione ha una o più colonne correlate. I valori all'interno di ogni cella del frame di dati possono essere di tipo numerico, categorico o testuale.
## Prerequisiti del set di dati di serie temporali
Prima dell’analisi, completa le fasi di pre-elaborazione necessarie per preparare i dati, come la pulizia dei dati o l’ingegneria delle caratteristiche. È possibile fornire uno o più set di dati. Se fornite più set di dati, utilizzate uno dei seguenti metodi per fornirli al processo di elaborazione di SageMaker Clarify:
+ Utilizzate una configurazione [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)denominata `dataset` o di analisi `dataset_uri` per specificare il set di dati principale. Per ulteriori informazioni su `dataset_uri`, consulta l’elenco di parametri in [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
+ Utilizza il parametro `baseline` fornito nel file di configurazione dell'analisi. Il set di dati baseline è necessario per `static_covariates`, se presente. Per ulteriori informazioni sul file di configurazione dell’analisi, inclusi gli esempi, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Questa tabella elenca i formati di dati supportati, le relative estensioni di file e i tipi MIME.
| Formato dei dati | Estensione di file | Tipo MIME |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
JSON è un formato flessibile che può rappresentare qualsiasi livello di complessità nei dati strutturati. Come mostrato nella tabella, SageMaker Clarify supporta i formati `item_records``timestamp_records`, e. `columns`
## Esempi di configurazione dei set di dati di serie temporali
Questa guida mostra come impostare una configurazione dell’analisi con `time_series_data_config` per i dati di serie temporali in formato JSON. Supponiamo di avere un set di dati con due elementi, ciascuno con un timestamp (t), una serie temporale di destinazione (x), due serie temporali correlate (r) e due covariate statiche (u) come descritto di seguito:
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
Puoi codificare il set di dati utilizzando `time_series_data_config` in tre modi diversi, a seconda del valore `dataset_format`. Le sezioni seguenti descrivono questi tre metodi.
### Configurazione dei dati di serie temporali: quando `dataset_format` è `columns`.
L’esempio seguente utilizza il valore `columns` per `dataset_format`. Il file JSON seguente rappresenta il set di dati precedente.
```
{
"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
}
```
Nota che gli ID elemento vengono ripetuti nel campo `ids`. La corretta implementazione di `time_series_data_config` è mostrata di seguito:
```
"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"
}
```
### Configurazione dei dati di serie temporali: quando `dataset_format` è `item_records`.
L’esempio seguente utilizza il valore `item_records` per `dataset_format`. Il seguente file JSON rappresenta il set di dati.
```
[
{
"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}
]
}
]
```
Ogni elemento è rappresentato come una voce separata nel file JSON. Il frammento seguente mostra il corrispondente `time_series_data_config` (che utilizza). 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"
}
```
### Configurazione dei dati di serie temporali: quando `dataset_format` è `timestamp_record`.
L’esempio seguente utilizza il valore `timestamp_record` per `dataset_format`. Il file JSON seguente rappresenta il set di dati precedente.
```
[
{"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},
]
```
Ogni voce del file JSON rappresenta un singolo timestamp e corrisponde a un singolo elemento. L’implementazione di `time_series_data_config` è mostrata di seguito:
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# Richieste degli endpoint per i dati di serie temporali
Un processo di elaborazione SageMaker Clarify serializza i dati in strutture JSON arbitrarie (con tipo MIME:). `application/json` A tale scopo, è necessario fornire una stringa di esempio al parametro `content_template` di configurazione dell'analisi. Viene utilizzato dal processo di elaborazione SageMaker Clarify per costruire la query JSON fornita al modello. `content_template`contiene uno o più record del set di dati. Devi anche fornire una stringa di modello per `record_template`, che viene utilizzata per costruire la struttura JSON di ogni record. Questi record vengono quindi inseriti in `content_template`. Per ulteriori informazioni su `content_type` o `dataset_type`, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
**Nota**
Poiché `content_template` e `record_template` sono parametri di stringa, tutti i caratteri con virgolette doppie (”) che fanno parte della struttura serializzata JSON devono essere annotati come caratteri di escape nella configurazione. Ad esempio, se vuoi evitare una virgoletta doppia in Python, puoi inserire il valore seguente per `content_template`.
```
'$record'
```
La tabella seguente mostra esempi di payload di richieste JSON serializzate e i corrispondenti parametri `content_template` e `record_template` necessari per costruirli.
| Caso d’uso | Payload di richiesta dell'endpoint (rappresentazione di stringhe) | content\$1template | record\$1template |
| --- | --- | --- | --- |
| Un solo record alla volta. | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| Un solo record con `$related_time_series` e `$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}'` |
| Più record | `{"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}'` |
| Più record con `$related_time_series` e `$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}'` |
# Risposta degli endpoint per i dati di serie temporali
Il processo di elaborazione SageMaker Clarify deserializza l'intero payload come JSON. Quindi estrae le previsioni dai dati deserializzati utilizzando le espressioni fornite nella configurazione di analisi. JMESPath I record del payload di risposta devono corrispondere ai record nel payload di richiesta.
La tabella seguente è un esempio di risposta da parte di un endpoint che restituisce solo il valore medio di previsione. Il valore `forecast` utilizzato nel `predictor` campo nella [configurazione dell'analisi](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters) deve essere fornito come JMESPath espressione per trovare il risultato della previsione per il processo di elaborazione.
| Payload di richiesta dell'endpoint | Payload di risposta dell'endpoint (rappresentazione di stringhe) | JMESPath espressione per la previsione nella configurazione dell'analisi |
| --- | --- | --- |
| Esempio di record singolo. Per estrarre correttamente la previsione, la configurazione deve essere `TimeSeriesModelConfig(forecast="prediction.mean")`. | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| Più record. Una risposta endpoint AWS DeepAR. | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# Controllo preventivo della richiesta e della risposta degli endpoint per i dati di serie temporali
Si consiglia di implementare il modello su un endpoint di inferenza SageMaker AI in tempo reale e di inviare richieste all'endpoint. Esamina manualmente le richieste e le risposte per verificare che entrambe siano conformi ai requisiti nelle sezioni [Richieste degli endpoint per i dati di serie temporali](clarify-processing-job-data-format-time-series-request-jsonlines.md) e [Risposta degli endpoint per i dati di serie temporali](clarify-processing-job-data-format-time-series-response-json.md). Se il container del modello supporta le richieste batch, puoi iniziare con una singola richiesta di record e quindi provare con due o più record.
I comandi seguenti mostrano come richiedere una risposta utilizzando la AWS CLI. AWS CLI È preinstallato nelle istanze Studio e Notebook. SageMaker Per installare AWS CLI, segui la guida all'[installazione](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
```
I parametri sono definiti come segue:
+ \$1ENDPOINT NAME: il nome dell’endpoint.
+ \$1CONTENT\$1TYPE: il tipo MIME della richiesta (input del container del modello).
+ \$1ACCEPT\$1TYPE: il tipo MIME della risposta (output del container del modello).
+ \$1REQUEST\$1DATA: la stringa payload richiesta.
+ \$1CLI\$1BINARY\$1FORMAT: il formato del parametro dell’interfaccia a riga di comando (CLI). Per la AWS CLI versione 1, questo parametro deve rimanere vuoto. Per v2, questo parametro deve essere impostato su `--cli-binary-format raw-in-base64-out`.
**Nota**
AWS CLI Per impostazione predefinita, v2 passa i parametri binari come stringhe con codifica base64. I seguenti esempi di richiesta e risposta da e verso l'endpoint utilizzano v1. AWS CLI
------
#### [ Example 1 ]
Nell’esempio di codice seguente, la richiesta è costituita da un solo record.
```
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
```
Il frammento seguente mostra l’output della risposta corrispondente.
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
Nell’esempio di codice seguente, la richiesta contiene due record.
```
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
```
Di seguito è riportato l’output della risposta.
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------
# Esegui SageMaker Clarify Processing Jobs per l'analisi e la spiegabilità dei pregiudizi
Per analizzare i dati e i modelli per verificare eventuali distorsioni e spiegabilità utilizzando SageMaker Clarify, è necessario configurare un processo di elaborazione Clarify. SageMaker Questa guida mostra come configurare gli input, gli output, le risorse e la configurazione dell'analisi del lavoro utilizzando l'API SageMaker Python SDK. `SageMakerClarifyProcessor`
L'API funge da wrapper di alto livello dell'API AI. SageMaker `CreateProcessingJob` Nasconde molti dei dettagli coinvolti nella configurazione di un SageMaker processo di elaborazione di Clarify. I dettagli per configurare un lavoro includono il recupero dell'URI dell'immagine del contenitore SageMaker Clarify e la generazione del file di configurazione dell'analisi. I passaggi seguenti mostrano come configurare, inizializzare e avviare un SageMaker processo di elaborazione Clarify.
**Configurate un processo di elaborazione SageMaker Clarify utilizzando l'API**
1. Definisci gli oggetti per ogni parte della configurazione del processo. Queste parti possono includere quanto segue:
+ Il set di dati di input e la posizione di output:. [DataConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.DataConfig)
+ Il modello o l'endpoint da analizzare:. [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)
+ Parametri di analisi delle distorsioni:. [BiasConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.BiasConfig)
+ SHapley Parametri di analisi Additive Explanations (SHAP):. [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)
+ Parametri asimmetrici di analisi dei valori di Shapley (solo per le serie temporali):. [AsymmetricShapleyValueConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.AsymmetricShapleyValueConfig)
Gli oggetti di configurazione per un processo di elaborazione SageMaker Clarify variano a seconda dei diversi tipi di formati di dati e casi d'uso. Nelle successive sezioni vengono forniti esempi di configurazione per i dati tabulari in formato [CSV](#clarify-processing-job-run-tabular-csv) e [JSON Lines](#clarify-processing-job-run-tabular-jsonlines), l’elaborazione del linguaggio naturale ([NLP](#clarify-processing-job-run-tabular-nlp)), [computer vision](#clarify-processing-job-run-cv) (CV) e problemi delle serie temporali (TS).
1. Crea un oggetto `SageMakerClarifyProcessor` e inizializzalo con parametri che specificano le risorse del processo. Queste risorse includono parametri come il numero di istanze di calcolo da utilizzare.
Il seguente esempio di codice mostra come creare un oggetto `SageMakerClarifyProcessor` e indicargli di utilizzare un'istanza di calcolo `ml.c4.xlarge` per eseguire l'analisi.
```
from sagemaker import clarify
clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=1,
instance_type='ml.c4.xlarge',
sagemaker_session=session,
)
```
1. Richiamate il metodo di esecuzione specifico dell'[SageMakerClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor.run)oggetto con gli oggetti di configurazione relativi al vostro caso d'uso per avviare il processo. Questi metodi di esecuzione includono i seguenti:
+ `run_pre_training_bias`
+ `run_post_training_bias`
+ `run_bias`
+ `run_explainability`
+ `run_bias_and_explainability`
Questo `SageMakerClarifyProcessor` gestisce diverse attività dietro le quinte. [Queste attività includono il recupero dell'URI (Universal Resource Identifier) dell'immagine del contenitore SageMaker Clarify, la composizione di un file di configurazione di analisi basato sugli oggetti di configurazione forniti, il caricamento del file in un bucket Amazon S3 e la configurazione del processo di elaborazione Clarify. SageMaker ](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
Le seguenti sezioni espandibili mostrano come calcolare **le metriche di bias pre-addestramento** e **post-addestramento**, **i valori SHAP** e **i grafici di dipendenza parziale** (PDPs). Le sezioni mostrano l'importanza della funzionalità per questi tipi di dati:
+ Set di dati tabulari in formato CSV o JSON Lines
+ Set di dati di elaborazione del linguaggio naturale
+ Set di dati di visione artificiale
Una guida per eseguire processi di elaborazione SageMaker Clarify paralleli con formazione distribuita utilizzando **Spark segue le sezioni** espandibili.
## Analisi dei dati tabulari in formato CSV
I seguenti esempi mostrano come configurare l'analisi dei bias e l'analisi della spiegabilità per un set di dati tabulare in formato CSV. In questi esempi, il set di dati in entrata ha quattro colonne di funzionalità e una colonna dell'etichetta binaria, `Target`. Il contenuto del set di dati è il seguente. Un valore di etichetta pari a `1` indica un risultato positivo.
```
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
...
```
Questo oggetto `DataConfig` specifica il set di dati di input e dove archiviare l'output. Il parametro `s3_data_input_path` può essere un URI di un file di set di dati o un prefisso URI Amazon S3. Se fornisci un prefisso URI S3, il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file Amazon S3 che si trovano sotto il prefisso. Il valore per `s3_output_path` deve essere un prefisso URI S3 per contenere i risultati dell'analisi. SageMaker L'intelligenza artificiale lo utilizza `s3_output_path` durante la compilazione e non può assumere un valore da un parametro, una proprietà, un'espressione o `ExecutionVariable` un parametro SageMaker AI Pipeline utilizzati durante il runtime. L'esempio di codice seguente mostra come specificare una configurazione di dati per il set di dati di input di esempio precedente.
```
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,
)
```
### Come calcolare tutte le metriche di bias pre-addestramento per un set di dati CSV
Il seguente esempio di codice mostra come configurare un oggetto `BiasConfig` per misurare il bias dell'input di esempio precedente verso esempi con un valore `Gender` di `0`.
```
bias_config = clarify.BiasConfig(
label_values_or_threshold=[1],
facet_name='Gender',
facet_values_or_threshold=[0],
)
```
Il seguente esempio di codice mostra come utilizzare un'istruzione run per avviare un processo di elaborazione SageMaker Clarify che calcola tutte le metriche di [distorsione pre-addestramento](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html) per un set di dati di input.
```
clarify_processor.run_pre_training_bias(
data_config=data_config,
data_bias_config=bias_config,
methods="all",
)
```
In alternativa, è possibile scegliere quali metriche calcolare assegnando un elenco di metriche di bias pre-addestramento al parametro metodi. [https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html)
### Come calcolare tutte le metriche di bias post-addestramento per un set di dati CSV
È possibile calcolare le metriche di bias pre-addestramento prima dell'addestramento. Tuttavia, per calcolare le [metriche di bias post-addestramento](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-post-training-bias.html), è necessario disporre di un modello addestrato. L'output di esempio seguente proviene da un modello di classificazione binaria che genera dati in formato CSV. In questo output di esempio, ogni riga contiene due colonne. La prima colonna contiene l'etichetta prevista e la seconda colonna contiene il valore di probabilità per quell'etichetta.
```
0,0.028986845165491
1,0.825382471084594
...
```
Nella configurazione di esempio seguente, l'`ModelConfig`oggetto indica al job di implementare il modello AI su un endpoint temporaneo. SageMaker L'endpoint utilizza un'istanza di inferenza `ml.m4.xlarge`. Poiché i parametri `content_type` e `accept_type` non sono impostati, utilizzano automaticamente il valore del parametro `dataset_type`, che è `text/csv`.
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
)
```
Il seguente esempio di configurazione utilizza un oggetto `ModelPredictedLabelConfig` con un indice di etichetta di `0`. Ciò indica al processo di elaborazione SageMaker Clarify di individuare l'etichetta prevista nella prima colonna dell'output del modello. Il processo di elaborazione utilizza l'indicizzazione a base zero in questo esempio.
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label=0,
)
```
In combinazione con l'esempio di configurazione precedente, il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify per calcolare tutte le metriche di distorsione post-allenamento.
```
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",
)
```
Analogamente, è possibile scegliere quali metriche calcolare assegnando un elenco di metriche di bias post-addestramento al parametro `methods`. Ad esempio, sostituisci `methods=“all”` con `methods=["DPPL", "DI"]` per calcolare solo la [differenza in proporzioni positive nelle etichette previste](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-dppl.html) e l'[impatto disparato](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-di.html).
### Come calcolare tutte le metriche di bias per un set di dati CSV
Il seguente esempio di configurazione mostra come eseguire tutte le metriche di distorsione prima e dopo l'allenamento in un unico processo di elaborazione Clarify. SageMaker
```
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",
)
```
[Per un taccuino di esempio con istruzioni su come eseguire un processo di elaborazione SageMaker Clarify in SageMaker Studio Classic per rilevare errori, consulta Fairness and Explainability with Clarify. SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)
### Come calcolare i valori SHAP per un set di dati CSV
SageMaker [Clarify fornisce attribuzioni di funzionalità utilizzando l'algoritmo KernelShap.](https://arxiv.org/abs/1705.07874) SHAPl'analisi richiede il valore o il punteggio di probabilità anziché l'etichetta prevista, quindi questo oggetto ha un indice di probabilità. `ModelPredictedLabelConfig` `1` Ciò indica al processo di elaborazione di SageMaker Clarify di estrarre il punteggio di probabilità dalla seconda colonna dell'output del modello (utilizzando l'indicizzazione a base zero).
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=1,
)
```
L'oggetto `SHAPConfig` fornisce parametri di analisi SHAP. In questo esempio, il parametro `baseline` SHAP è omesso e il valore del parametro `num_clusters` è `1`. Ciò indica al processore SageMaker Clarify di calcolare un campione di base basato sul raggruppamento del set di dati di inputSHAP. Se si desidera scegliere il set di dati di base, consultare [Linee di base SHAP per la spiegabilità](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html).
```
shap_config = clarify.SHAPConfig(
num_clusters=1,
)
```
Il seguente esempio di codice avvia un SageMaker processo di elaborazione Clarify per calcolare i valori. SHAP
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=shap_config,
)
```
Per un taccuino di esempio con istruzioni su come eseguire un processo di elaborazione SageMaker Clarify in SageMaker Studio Classic per calcolare SHAP i valori, consulta [Fairness](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb) and Explainability with Clarify. SageMaker
### Come calcolare i grafici di dipendenza parziale (PDPs) per un set di dati CSV
PDPs mostra la dipendenza della risposta della destinazione prevista da una o più funzionalità di input di interesse mantenendo costanti tutte le altre funzionalità. Una linea o una curva con pendenza verso l'alto nel PDP indica che la relazione tra la destinazione e le funzionalità di input è positiva e la pendenza indica la forza della relazione. Una linea o una curva con pendenza verso il basso indica che se una funzionalità di input diminuisce, la variabile di destinazione aumenta. In modo intuitivo, è possibile interpretare la dipendenza parziale come la risposta della variabile di destinazione a ciascuna funzionalità di input di interesse.
Il seguente esempio di configurazione riguarda l'utilizzo di un `PDPConfig` oggetto per indicare al processo di elaborazione di SageMaker Clarify di calcolare l'importanza della funzionalità. `Income`
```
pdp_config = clarify.PDPConfig(
features=["Income"],
grid_resolution=10,
)
```
Nell'esempio precedente, il parametro `grid_resolution` divide l'intervallo dei valori della funzionalità `Income` in bucket `10`. Il processo di elaborazione SageMaker Clarify PDPs genererà una `Income` suddivisione in `10` segmenti sull'asse x. L'asse y mostrerà l'impatto marginale di `Income` sulla variabile di destinazione.
Il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify da calcolare. PDPs
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=pdp_config,
)
```
Per un notebook di esempio con istruzioni su come eseguire un processo di elaborazione SageMaker Clarify in SageMaker Studio Classic per il calcoloPDPs, vedete [Explainability with SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb) - Partial Dependence Plots (PDP).
### Come calcolare entrambi i valori SHAP e PDPs per un set di dati CSV
È possibile calcolare entrambi i valori in un unico processo di elaborazione ClarifySHAP. PDPs SageMaker Nel seguente esempio di configurazione, il parametro `top_k_features` di un nuovo oggetto `PDPConfig` è impostato su `2`. Ciò indica al processo di elaborazione SageMaker Clarify di calcolare le `2` funzionalità con PDPs i valori globali più elevati. SHAP
```
shap_pdp_config = clarify.PDPConfig(
top_k_features=2,
grid_resolution=10,
)
```
Il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify per calcolare sia i valori che. SHAP PDPs
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=[shap_config, shap_pdp_config],
)
```
## Analisi dei dati tabulari in formato JSON Lines
Gli esempi seguenti mostrano come configurare l'analisi delle distorsioni e l'analisi della spiegabilità per un set di dati tabulare nel formato denso > AI JSON Lines. SageMaker Per ulteriori informazioni, consulta [Formato della richiesta JSONLINES](cdf-inference.md#cm-jsonlines). In questi esempi, il set di dati in entrata contiene gli stessi dati della sezione precedente, ma sono nel formato JSON Lines. Ogni riga è un oggetto JSON valido. Le `Features` chiave si riferiscono a una matrice di valori di funzionalità e la `Label` chiave si riferisce all'etichetta Ground Truth.
```
{"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}
...
```
Nel seguente esempio di configurazione, l'oggetto `DataConfig` specifica il set di dati di input e dove archiviare l'output.
```
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,
)
```
Nell'esempio di configurazione precedente, il parametro features è impostato sull'[JMESPath](https://jmespath.org/)espressione in `Features` modo che il processo di elaborazione SageMaker Clarify possa estrarre l'array di funzionalità da ogni record. Il `label` parametro è impostato su JMESPath expression `Label` in modo che il processo di elaborazione SageMaker Clarify possa estrarre l'etichetta di verità fondamentale da ogni record. Il parametro `s3_data_input_path` può essere un URI di un file di set di dati o un prefisso URI Amazon S3. Se fornite un prefisso URI S3, il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file S3 che si trovano sotto il prefisso. Il valore per `s3_output_path` deve essere un prefisso URI S3 per contenere i risultati dell'analisi. SageMaker L'intelligenza artificiale lo utilizza `s3_output_path` durante la compilazione e non può assumere un valore da un parametro, una proprietà, un'espressione o `ExecutionVariable` un parametro SageMaker AI Pipeline utilizzati durante il runtime.
È necessario disporre di un modello addestrato per calcolare le metriche di bias o l'importanza della funzionalità post-addestramento. L'esempio seguente proviene da un modello di classificazione binaria che genera dati JSON Lines nel formato dell'esempio. Ogni riga dell'output del modello è un oggetto JSON valido. La `predicted_label` chiave si riferisce all'etichetta prevista e la `probability` chiave si riferisce al valore di probabilità.
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
Nel seguente esempio di configurazione, un `ModelConfig` oggetto indica al processo di elaborazione SageMaker Clarify di distribuire il modello SageMaker AI su un endpoint temporaneo. L'endpoint utilizza un'istanza di inferenza `ml.m4.xlarge`.
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
content_template='{"Features":$features}',
)
```
Nell'esempio di configurazione precedente, i parametri `content_type` e `accept_type` non sono impostati. Pertanto, utilizzano automaticamente il valore del parametro `dataset_type` dell'oggetto `DataConfig`, che è `application/jsonlines`. Il processo di elaborazione SageMaker Clarify utilizza il `content_template` parametro per comporre l'input del modello sostituendo il segnaposto con una serie di funzionalità. `$features`
La configurazione di esempio seguente mostra come impostare il parametro label dell'`ModelPredictedLabelConfig`oggetto sull'espressione. JMESPath `predicted_label` Questo estrarrà l'etichetta prevista dall'output del modello.
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label='predicted_label',
)
```
La configurazione di esempio seguente mostra come impostare il `probability` parametro dell'`ModelPredictedLabelConfig`oggetto sull' JMESPathespressione`probability`. Questo estrarrà il punteggio dall'output del modello.
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
Per calcolare le metriche di bias e l'importanza delle funzionalità per i set di dati in formato JSON Lines, usa le stesse istruzioni di esecuzione e gli stessi oggetti di configurazione della sezione precedente per i set di dati CSV. È possibile eseguire un processo di elaborazione SageMaker Clarify in SageMaker Studio Classic per rilevare distorsioni e calcolare l'importanza delle funzionalità. Per le istruzioni e un taccuino di esempio, consulta [Fairness and Explainability with SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.ipynb) (JSON Lines Format).
## Analizza i dati tabulari per la spiegabilità NLP
SageMaker Clarify supporta le spiegazioni per i modelli di elaborazione del linguaggio naturale (NLP). Queste spiegazioni aiutano a capire quali sezioni di testo sono le più importanti per le previsioni dei modelli. È possibile spiegare la previsione del modello per una singola istanza del set di dati di input o le previsioni dei modelli dal set di dati di base. Per comprendere e visualizzare il comportamento di un modello, è possibile specificare più livelli di granularità. A tale scopo, definisci la lunghezza del segmento di testo, ad esempio token, frasi e paragrafi.
SageMaker La spiegabilità della PNL di Clarify è compatibile con i modelli di classificazione e regressione. Puoi anche usare SageMaker Clarify per spiegare il comportamento del tuo modello su set di dati multimodali che contengono caratteristiche testuali, categoriali o numeriche. La spiegabilità dell'NLP per i set di dati multimodali può aiutarvi a capire quanto sia importante ciascuna funzionalità per l'output del modello. SageMaker Clarify supporta 62 lingue e può gestire testo che include più lingue.
L'esempio seguente mostra un file di configurazione di analisi per il calcolo dell'importanza della funzionalità per l'NLP. In questo esempio, il set di dati in entrata è un set di dati tabulare in formato CSV, con una colonna dell'etichetta binaria e due colonne di funzionalità.
```
0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...
```
Il seguente esempio di configurazione mostra come specificare un set di dati di input in formato CSV e un percorso dei dati di output utilizzando l'oggetto `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,
)
```
Nell’esempio di configurazione precedente, il parametro `s3_data_input_path` può essere un URI di un file del set di dati o un prefisso URI Amazon S3. Se fornite un prefisso URI S3, il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file S3 che si trovano sotto il prefisso. Il valore per `s3_output_path` deve essere un prefisso URI S3 per contenere i risultati dell'analisi. SageMaker L'intelligenza artificiale lo utilizza `s3_output_path` durante la compilazione e non può assumere un valore da un parametro, una proprietà, un'espressione o `ExecutionVariable` un parametro SageMaker AI Pipeline utilizzati durante il runtime.
L'output di esempio seguente è stato creato da un modello di classificazione binaria addestrato sul set di dati di input precedente. Il modello di classificazione accetta dati CSV e restituisce un singolo punteggio compreso tra `0` e `1`.
```
0.491656005382537
0.569582343101501
...
```
L'esempio seguente mostra come configurare l'`ModelConfig`oggetto per distribuire un SageMaker modello di intelligenza artificiale. In questo esempio, un endpoint temporaneo distribuisce il modello. Questo endpoint utilizza un'istanza di inferenza `ml.g4dn.xlarge` dotata di GPU per l'inferenza accelerata.
```
nlp_model_config = clarify.ModelConfig(
model_name=your_nlp_model_name,
instance_type='ml.g4dn.xlarge',
instance_count=1,
)
```
L'esempio seguente mostra come configurare l'oggetto `ModelPredictedLabelConfig` per individuare la probabilità (punteggio) nella prima colonna con un indice di `0`.
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=0,
)
```
La configurazione SHAP di esempio seguente mostra come eseguire un'analisi di spiegabilità basata su token utilizzando un modello e un set di dati di input in lingua inglese.
```
text_config = clarify.TextConfig(
language='english',
granularity='token',
)
nlp_shap_config = clarify.SHAPConfig(
baseline=[[4, '[MASK]']],
num_samples=100,
text_config=text_config,
)
```
Nell'esempio precedente, l'oggetto `TextConfig` attiva l'analisi della spiegabilità dell'NLP. Il parametro `granularity` indica che l'analisi deve analizzare i token. In inglese, ogni token è una parola. Per altre lingue, consultate la [documentazione di SpacY per la tokenizzazione](https://spacy.io/usage/linguistic-features#tokenization), che SageMaker Clarify utilizza per l'elaborazione NLP. L'esempio precedente mostra anche come utilizzare un `Rating` medio di `4` per impostare un'istanza di base SHAP locale. Uno speciale token mascherato `[MASK]` viene utilizzato per sostituire un token (parola) in `Comments`.
Nell'esempio precedente, se l'istanza è `2,"Flavor needs work"`, imposta la linea di base su un `Rating` medio pari a `4` con la linea di base seguente.
```
4, '[MASK]'
```
Nell'esempio precedente, lo spiegatore di SageMaker Clarify esegue un'iterazione su ogni token e lo sostituisce con la maschera, come segue.
```
2,"[MASK] needs work"
4,"Flavor [MASK] work"
4,"Flavor needs [MASK]"
```
Quindi, l'esplicatore SageMaker Clarify invierà ogni riga al modello per le previsioni. In questo modo l'esplicativo impara le previsioni con e senza le parole mascherate. Lo spiegatore SageMaker Clarify utilizza quindi queste informazioni per calcolare il contributo di ciascun token.
Il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify per calcolare i valori. SHAP
```
clarify_processor.run_explainability(
data_config=nlp_data_config,
model_config=nlp_model_config,
model_scores=probability_config,
explainability_config=nlp_shap_config,
)
```
[Per un taccuino di esempio con istruzioni su come eseguire un processo di elaborazione SageMaker Clarify in SageMaker Studio Classic per l'analisi della spiegabilità NLP, vedete Explaining Text Sentiment Analysis Using Clarify. SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/text_explainability/text_explainability.ipynb)
## Analisi dei dati delle immagini per la spiegabilità della visione artificiale
SageMaker Clarify genera mappe termiche che forniscono informazioni su come i modelli di visione artificiale classificano e rilevano gli oggetti nelle immagini.
Nel seguente esempio di configurazione, il set di dati di input è costituito da immagini 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,
)
```
Nell’esempio di configurazione precedente, l’oggetto `DataConfig` contiene `s3_data_input_path` impostato su un prefisso URI S3. Il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file di immagine che si trovano sotto il prefisso. Il parametro `s3_data_input_path` può essere un URI di un file di set di dati o un prefisso URI Amazon S3. Se fornite un prefisso URI S3, il processo di elaborazione SageMaker Clarify raccoglie in modo ricorsivo tutti i file S3 che si trovano sotto il prefisso. Il valore per `s3_output_path` deve essere un prefisso URI S3 per contenere i risultati dell'analisi. SageMaker L'intelligenza artificiale lo utilizza `s3_output_path` durante la compilazione e non può assumere un valore da un parametro, una proprietà, un'espressione o `ExecutionVariable` un parametro SageMaker AI Pipeline utilizzati durante il runtime.
### Come spiegare un modello di classificazione delle immagini
Il processo di elaborazione SageMaker Clarify spiega le immagini utilizzando l'algoritmo KernelSHAP, che tratta l'immagine come una raccolta di super pixel. Dato un set di dati composto da immagini, il processo di elaborazione genera un set di dati di immagini in cui ogni immagine mostra la mappa termica dei super pixel pertinenti.
Il seguente esempio di configurazione mostra come configurare un'analisi di spiegabilità utilizzando un modello di classificazione delle immagini. SageMaker Per ulteriori informazioni, consulta [Classificazione delle immagini - 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",
)
```
Nell'esempio di configurazione precedente, un modello denominato `your_cv_ic_model` è stato addestrato a classificare gli animali nelle immagini JPEG di input. L'`ModelConfig`oggetto dell'esempio precedente indica al processo di elaborazione di SageMaker Clarify di implementare il modello di SageMaker intelligenza artificiale su un endpoint temporaneo. Per un'inferenza accelerata, l'endpoint utilizza un'istanza di inferenza `ml.p2.xlarge` dotata di GPU.
Dopo l'invio di un'immagine JPEG a un endpoint, l'endpoint la classifica e restituisce un elenco di punteggi. Ogni punteggio corrisponde a una categoria. L'oggetto `ModelPredictedLabelConfig` fornisce il nome di ogni categoria, come segue.
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
Un esempio di output per il precedente input di ['bird', 'cat', 'dog'] potrebbe essere 0,3;0,6;0,1, dove 0,3 rappresenta il punteggio di attendibilità per la classificazione di un'immagine come uccello.
La seguente configurazione SHAP di esempio mostra come generare spiegazioni per un problema di classificazione delle immagini. Utilizza un oggetto `ImageConfig` per attivare l'analisi.
```
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 Clarify estrae le funzionalità utilizzando il metodo [Simple Linear Iterative Clustering](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) (SLIC) dalla libreria scikit-learn per la segmentazione delle immagini. Nell'esempio di configurazione precedente, il parametro `model_type` indica il tipo di problema di classificazione delle immagini. Il parametro `num_segments` stima il numero approssimativo di segmenti che verranno etichettati nell'immagine di input. Il numero di segmenti viene quindi passato al parametro `n_segments` slic.
Ogni segmento dell'immagine è considerato un superpixel e per ogni segmento vengono calcolati i valori SHAP locali. Il parametro `segment_compactness` determina la forma e la dimensione dei segmenti di immagine generati dal metodo slic scikit-image. Le dimensioni e le forme dei segmenti dell'immagine vengono quindi passate al parametro `compactness` slic.
Il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify per generare mappe termiche per le immagini. I valori positivi della mappa termica mostrano che la funzionalità ha aumentato il punteggio di attendibilità del rilevamento dell'oggetto. I valori negativi indicano che la funzionalità ha ridotto il punteggio di attendibilità.
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=ic_model_config,
model_scores=ic_prediction_config,
explainability_config=ic_shap_config,
)
```
Per un taccuino di esempio che utilizza SageMaker Clarify per classificare le immagini e spiegarne la classificazione, vedete [Explaining](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) Image Classification with Clarify. SageMaker
### Come spiegare un modello di rilevamento di oggetti
Un processo di elaborazione di SageMaker Clarify può rilevare e classificare gli oggetti in un'immagine e quindi fornire una spiegazione dell'oggetto rilevato. Il processo di spiegazione è riportato di seguito.
1. Gli oggetti dell'immagine vengono prima categorizzati in una delle classi di una raccolta specificata. Ad esempio, se un modello di rilevamento di oggetti è in grado di riconoscere gatti, cani e pesci, queste tre classi fanno parte di una raccolta. Questa raccolta è specificata dal parametro `label_headers` come segue.
```
clarify.ModelPredictedLabelConfig(
label_headers=object_categories,
)
```
1. Il processo di elaborazione SageMaker Clarify produce un punteggio di confidenza per ogni oggetto. Un punteggio di attendibilità elevato indica che appartiene a una delle classi di una raccolta specificata. Il processo di elaborazione SageMaker Clarify produce anche le coordinate di un riquadro di delimitazione che delimita l'oggetto. Per ulteriori informazioni sui punteggi di attendibilità e sui riquadri di delimitazione, consulta [Formati della risposta](object-detection-in-formats.md#object-detection-recordio).
1. SageMaker Clarify fornisce quindi una spiegazione per il rilevamento di un oggetto nella scena dell'immagine. Utilizza i metodi descritti nella sezione **Come spiegare un modello di classificazione delle immagini**.
Nel seguente esempio di configurazione, un modello di rilevamento di oggetti SageMaker AI `your_cv_od_model` viene addestrato su immagini JPEG per identificare gli animali su di esse.
```
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",
)
```
L'`ModelConfig`oggetto dell'esempio di configurazione precedente indica al processo di elaborazione SageMaker Clarify di implementare il modello SageMaker AI su un endpoint temporaneo. Per un imaging accelerato, questo endpoint utilizza un'istanza di inferenza `ml.p2.xlarge` dotata di GPU.
Nella configurazione di esempio seguente, l'oggetto `ModelPredictedLabelConfig` fornisce il nome di ogni categoria per la classificazione.
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
La seguente configurazione SHAP di esempio mostra come generare spiegazioni per un rilevamento di oggetti.
```
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,
)
```
Nella configurazione di esempio precedente, l'oggetto `ImageConfig` attiva l'analisi. Il parametro `model_type` indica che il tipo di problema è il rilevamento di oggetti. Per una descrizione dettagliata degli altri parametri, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
Il seguente esempio di codice avvia un processo di elaborazione SageMaker Clarify per generare mappe termiche per le immagini. I valori positivi della mappa termica mostrano che la funzionalità ha aumentato il punteggio di attendibilità del rilevamento dell'oggetto. I valori negativi indicano che la funzionalità ha ridotto il punteggio di attendibilità.
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=od_model_config,
model_scores=od_prediction_config,
explainability_config=od_shap_config,
)
```
Per un taccuino di esempio che utilizza SageMaker Clarify per rilevare oggetti in un'immagine e spiegarne le previsioni, consulta [Explaining object detection models with Amazon SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) AI Clarify.
## Analisi delle spiegazioni per i modelli di previsione delle serie temporali
Gli esempi seguenti mostrano come configurare i dati in formato SageMaker AI JSON denso per spiegare un modello di previsione delle serie temporali. Per maggiori informazioni sulla formattazione JSON, consulta [Formato della richiesta 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
},
]
```
### Configurazione dei dati
Utilizza `TimeSeriesDataConfig` per indicare al processo di spiegabilità come analizzare correttamente i dati dal set di dati di input passato, come mostrato nella configurazione di esempio seguente:
```
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',
)
```
### Configurazione dei valori asimmetrici di Shapley
Utilizza `AsymmetricShapleyValueConfig` per definire argomenti per l’analisi della spiegazione per i modelli di previsione delle serie temporali, ad esempio la baseline, la direzione, la granularità e il numero di campioni. Sono impostati valori baseline per tutti e tre i tipi di dati: serie temporali correlate, covariate statiche e serie temporali di destinazione. La `AsymmetricShapleyValueConfig` configurazione indica al processore SageMaker Clarify come calcolare le attribuzioni delle funzionalità per un elemento alla volta. La configurazione seguente mostra un esempio di definizione di `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"
},
)
```
I valori forniti a `AsymmetricShapleyValueConfig` vengono passati alla configurazione dell’analisi come voce di `methods` con la chiave `asymmetric_shapley_value`.
### Configurazione del modello
È possibile controllare la struttura del payload inviato dal processore Clarify. SageMaker Nel seguente esempio di codice, un oggetto di `ModelConfig` configurazione indirizza un processo di previsione della spiegabilità di previsione delle serie temporali all'aggregazione dei record utilizzando la JMESPath sintassi into`'{"instances": $records}'`, dove la struttura di ogni record è definita con il seguente record\$1template. `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` Nota che `$start_time`, `$target_time_series`, `$related_time_series` e `$static_covariates` sono token interni utilizzati per mappare i valori del set di dati ai valori delle richieste degli endpoint.
```
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]'}
)
)
```
Allo stesso modo, l’attributo `forecast` in `TimeSeriesModelConfig`, passato alla configurazione dell’analisi con la chiave `time_series_predictor_config`, viene utilizzato per estrarre la previsione del modello dalla risposta dell’endpoint. Ad esempio, una risposta in batch dell’endpoint potrebbe essere la seguente:
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
Se l' JMESPath espressione fornita `forecast` è \$1'predictions [\$1] .mean [:2] '\$1\$1, il valore di previsione viene analizzato come segue:
```
[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]
```
## Come eseguire processi di elaborazione SageMaker Clarify paralleli
Quando si lavora con set di dati di grandi dimensioni, è possibile utilizzare [Apache Spark](https://spark.apache.org/) per aumentare la velocità dei processi di elaborazione di Clarify. SageMaker Spark è un motore di analisi unificato per l'elaborazione di dati su larga scala. Quando richiedi più di un'istanza per processore Clarify, SageMaker SageMaker Clarify utilizza le funzionalità di elaborazione distribuita di Spark.
Il seguente esempio di configurazione mostra come `SageMakerClarifyProcessor` creare un processore SageMaker Clarify con istanze di calcolo. `5` Per eseguire qualsiasi lavoro associato a`SageMakerClarifyProcessor`, SageMaker Clarify utilizza l'elaborazione distribuita Spark.
```
from sagemaker import clarify
spark_clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=5,
instance_type='ml.c5.xlarge',
)
```
Se impostate il `save_local_shap_values` parametro su [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)to`True`, il processo di elaborazione SageMaker Clarify salva il SHAP valore locale come file di parti multiple nella posizione di output del lavoro.
Per associare i valori SHAP locali alle istanze del set di dati di input, utilizza il parametro `joinsource` di `DataConfig`. Se aggiungi altre istanze di calcolo, ti consigliamo di aumentare anche il valore `instance_count` di [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)per l'endpoint temporaneo. In questo modo si evita che le richieste di inferenza concomitanti dei worker di Spark sovraccarichino l'endpoint. In particolare, ti consigliamo di utilizzare un rapporto di istanze. one-to-one endpoint-to-processing
# Risultati delle analisi
Al termine di un processo di elaborazione di SageMaker Clarify, è possibile scaricare i file di output per esaminarli oppure visualizzare i risultati in Studio Classic. SageMaker L'argomento seguente descrive i risultati dell'analisi generati da SageMaker Clarify, ad esempio lo schema e il report generati dall'analisi dei bias, dall'analisi SHAP, dall'analisi della spiegabilità della visione artificiale e dall'analisi dei grafici di dipendenza parziali (). PDPs Se l'analisi della configurazione contiene parametri per calcolare più analisi, i risultati vengono aggregati in un'unica analisi e in un unico file di report.
La directory di output del processo di elaborazione di SageMaker Clarify contiene i seguenti file:
+ `analysis.json`: un file che contiene le metriche di bias e l'importanza della funzionalità in formato JSON.
+ `report.ipynb`: un notebook statico che contiene codice per aiutarti a visualizzare le metriche di bias e l'importanza della funzionalità.
+ `explanations_shap/out.csv`: una directory creata che contiene file generati automaticamente in base alle configurazioni di analisi specifiche dell'utente. Ad esempio, se si attiva il parametro `save_local_shap_values`, i valori SHAP locali per istanza verranno salvati nella directory `explanations_shap`. Come altro esempio, se `analysis configuration` non contiene un valore per il parametro di base SHAP, il job di spiegabilità di SageMaker Clarify calcola una linea di base raggruppando il set di dati di input. Quindi salva la linea di base generata nella directory.
Per ulteriori informazioni, consulta le sezioni indicate di seguito.
**Topics**
+ [Analisi dei bias](#clarify-processing-job-analysis-results-bias)
+ [Analisi SHAP](#clarify-processing-job-analysis-results-shap)
+ [Analisi della spiegabilità della visione artificiale (CV)](#clarify-processing-job-analysis-results-cv)
+ [PDPsAnalisi dei grafici di dipendenza parziale ()](#clarify-processing-job-analysis-results-pdp)
+ [Valori asimmetrici di Shapley](#clarify-processing-job-analysis-results-asymmshap)
## Analisi dei bias
Amazon SageMaker Clarify utilizza la terminologia documentata in [Amazon SageMaker chiarisce i termini relativi a parzialità ed equità](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) per discutere di pregiudizi e correttezza.
### Schema per il file di analisi
Il file di analisi è in formato JSON ed è organizzato in due sezioni: metriche di bias pre-addestramento e metriche di bias post-addestramento. I parametri per le metriche di bias pre-addestramento e post-addestramento sono i seguenti.
+ **pre\$1training\$1bias\$1metrics**: parametri per le metriche di bias pre-addestramento. Per ulteriori informazioni, consultare [Metriche di bias pre-addestramento](clarify-measure-data-bias.md) e [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
+ **label**: il nome dell'etichetta ground truth definita dal parametro `label` della configurazione dell'analisi.
+ **label\$1value\$1or\$1threshold**: una stringa contenente i valori delle etichette o l'intervallo definito dal parametro `label_values_or_threshold` della configurazione dell'analisi. Ad esempio, se il valore `1` viene fornito per un problema di classificazione binaria, la stringa sarà `1`. Se vengono forniti più valori `[1,2]` per un problema multiclasse, la stringa sarà `1,2`. Se viene fornita una soglia `40` per un problema di regressione, la stringa sarà interna come `(40, 68]` in cui `68` è il valore massimo dell'etichetta nel set di dati di input.
+ **facets**: la sezione contiene diverse coppie chiave-valore, in cui la chiave corrisponde al nome del facet definito dal parametro `name_or_index` della configurazione del facet e il valore è una matrice di oggetti facet. Ciascun oggetto facet presenta i seguenti membri:
+ **value\$1or\$1threshold**: una stringa contenente i valori del facet o l'intervallo definito dal parametro `value_or_threshold` della configurazione del facet.
+ **metrics**: la sezione contiene una matrice di elementi metrica di bias e ogni elemento metrica di bias ha i seguenti attributi:
+ **name**: il nome breve della metrica di bias. Ad esempio, `CI`.
+ **description**: il nome completo della metrica di bias. Ad esempio, `Class Imbalance (CI)`.
+ **value**: il valore della metrica di bias o il valore null JSON se la metrica di bias non viene calcolata per un motivo particolare. I valori ±∞ sono rappresentati rispettivamente come stringhe `∞` e `-∞`.
+ **error**: un messaggio di errore opzionale che spiega perché la metrica di bias non è stata calcolata.
+ **post\$1training\$1bias\$1metrics**: la sezione contiene le metriche di bias post-addestramento e segue un layout e una struttura simili a quelli della sezione pre-addestramento. Per ulteriori informazioni, consulta [Metriche sui bias dei modelli e dei dati di post-addestramento](clarify-measure-post-training-bias.md).
Di seguito è riportato un esempio di configurazione dell'analisi che calcolerà le metriche di bias pre- e post-addestramento.
```
{
"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
},
...
]
}]
}
}
}
```
### Report di analisi dei bias
Il report di analisi dei bias include diverse tabelle e diagrammi che contengono spiegazioni e descrizioni dettagliate. Questi includono, a titolo esemplificativo, la distribuzione dei valori delle etichette, la distribuzione dei valori di facet, il diagramma delle prestazioni del modello di alto livello, una tabella delle metriche di bias e le relative descrizioni. Per ulteriori informazioni sulle metriche di distorsione e su come interpretarle, consulta la sezione [Scopri come Amazon SageMaker Clarify aiuta a](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/) rilevare i pregiudizi.
## Analisi SHAP
SageMaker I processi di elaborazione di Clarify utilizzano l'algoritmo Kernel SHAP per calcolare le attribuzioni delle funzionalità. Il processo di elaborazione SageMaker Clarify produce valori SHAP sia locali che globali. Questi aiutano a determinare il contributo di ciascuna funzionalità alle previsioni dei modelli. I valori SHAP locali rappresentano l'importanza della funzionalità per ogni singola istanza, mentre i valori SHAP globali aggregano i valori SHAP locali per tutte le istanze del set di dati. Per ulteriori informazioni sui valori SHAP e su come interpretarli, consulta [Caratterizzazione delle attribuzioni che utilizzano i valori Shapley](clarify-shapley-values.md).
### Schema per il file di analisi SHAP
I risultati dell'analisi SHAP globale vengono archiviati nella sezione delle spiegazioni del file di analisi, nella scheda del metodo `kernel_shap`. I diversi parametri del file di analisi SHAP sono i seguenti:
+ **explanations**: la sezione del file di analisi che contiene i risultati dell'analisi dell'importanza della funzionalità.
+ **kernal\$1shap**: la sezione del file di analisi che contiene il risultato dell'analisi SHAP globale.
+ **global\$1shap\$1values**: una sezione del file di analisi che contiene diverse coppie chiave-valore. Ogni chiave nella coppia chiave-valore rappresenta un nome di funzionalità dal set di dati di input. Ogni valore nella coppia chiave-valore corrisponde al valore SHAP globale della funzionalità. Il valore SHAP globale si ottiene aggregando i valori SHAP per istanza della funzionalità utilizzando la configurazione `agg_method`. Se la configurazione `use_logit` è attivata, il valore viene calcolato utilizzando i coefficienti di regressione logistica, che possono essere interpretati come rapporti log-odds.
+ **expected\$1value**: la previsione media del set di dati di base. Se la configurazione `use_logit` è attivata, il valore viene calcolato utilizzando i coefficienti di regressione logistica.
+ **global\$1top\$1shap\$1text**: per l’analisi della spiegabilità NLP. Una sezione del file di analisi che include un set di coppie chiave-valore. SageMaker I processi di elaborazione di Clarify aggregano i valori SHAP di ciascun token e quindi selezionano i token principali in base ai rispettivi valori SHAP globali. La configurazione `max_top_tokens` definisce il numero di token da selezionare.
Ognuno dei token principali selezionati ha una coppia chiave-valore. La chiave nella coppia chiave-valore corrisponde al nome della funzionalità testuale di un token principale. Ogni valore nella coppia chiave-valore è il valore SHAP globale del token principale. Per un esempio di coppia chiave-valore `global_top_shap_text`, consulta l’output seguente.
L’esempio seguente mostra l’output dell’analisi SHAP di un set di dati tabulare.
```
{
"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
}
}
}
}
```
L’esempio seguente mostra l’output dell’analisi SHAP di un set di dati testuale. L'output corrispondente alla colonna `Comments` è un esempio di output generato dopo l'analisi di una funzionalità testuale.
```
{
"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,
...
}
}
}
}
}
```
### Schema per il file di base generato
Quando non viene fornita una configurazione di base SHAP, il processo di elaborazione SageMaker Clarify genera un set di dati di base. SageMaker Clarify utilizza un algoritmo di clustering basato sulla distanza per generare un set di dati di base dai cluster creati dal set di dati di input. Il set di dati di base risultante viene salvato in un file CSV, che si trova in `explanations_shap/baseline.csv`. Questo file di output contiene una riga di intestazione e diverse istanze basate sul parametro `num_clusters` specificato nella configurazione dell'analisi. Il set di dati di base è costituito solo da colonne di funzionalità. L’esempio seguente mostra una baseline creata raggruppando il set di dati di input.
```
Age,Gender,Income,Occupation
35,0,2883,1
40,1,6178,2
42,0,4621,0
```
### Schema per i valori SHAP locali derivanti dall'analisi della spiegabilità dei set di dati tabulari
Per i set di dati tabulari, se viene utilizzata una singola istanza di calcolo, il processo di elaborazione SageMaker Clarify salva i valori SHAP locali in un file CSV denominato. `explanations_shap/out.csv` Se si utilizzano più istanze di calcolo, i valori SHAP locali vengono salvati in diversi file CSV nella directory `explanations_shap`.
Un file di output contenente valori SHAP locali ha una riga contenente i valori SHAP locali per ogni colonna definita dalle intestazioni. Le intestazioni seguono la convenzione di denominazione `Feature_Label`, nella quale al nome della funzionalità viene aggiunto un trattino basso, seguito dal nome della variabile di destinazione.
Per problemi multiclasse, i nomi delle funzionalità nell'intestazione variano prima, poi le etichette. Ad esempio, due funzionalità `F1, F2` e due classi `L1` e `L2`, nelle intestazioni sono `F1_L1`, `F2_L1`, `F1_L2` e `F2_L2`. Se la configurazione dell'analisi contiene un valore per il parametro `joinsource_name_or_index`, la colonna della chiave utilizzata nella join viene aggiunta alla fine del nome dell'intestazione. Ciò consente la mappatura dei valori SHAP locali alle istanze del set di dati di input. Segue un esempio di file di output contenente valori 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
...
```
### Schema per i valori SHAP locali derivanti dall'analisi della spiegabilità NLP
Per l'analisi della spiegabilità NLP, se viene utilizzata una singola istanza di calcolo, il processo di elaborazione SageMaker Clarify salva i valori SHAP locali in un file JSON Lines denominato. `explanations_shap/out.jsonl` Se si utilizzano più istanze di calcolo, i valori SHAP locali vengono salvati in diversi file JSON Lines nella directory `explanations_shap`.
Ogni file contenente valori SHAP locali ha diverse righe di dati e ogni riga è un oggetto JSON valido. L'oggetto JSON ha i seguenti attributi:
+ **explanations**: la sezione del file di analisi che contiene una matrice di spiegazioni Kernel SHAP per una singola istanza. Ciascun elemento della matrice dispone dei seguenti membri:
+ **feature\$1name**: il nome dell'intestazione delle funzionalità fornite dalla configurazione delle intestazioni.
+ **data\$1type: il tipo** di funzionalità dedotto dal processo di elaborazione di Clarify. SageMaker I valori validi per le funzionalità testuali includono `numerical`, `categorical` e `free_text` (per le funzionalità testuali).
+ **attributions**: una matrice di oggetti di attribuzione specifici per una funzionalità. Una funzionalità testuale può avere più oggetti di attribuzione, ciascuno per un'unità definita dalla configurazione `granularity`. L'oggetto attribuzione ha i seguenti membri:
+ **attribution**: una matrice di valori di probabilità specifica per classe.
+ **description**: (per le funzionalità testuali) la descrizione delle unità di testo.
+ **partial\$1text — La parte del testo** spiegata dal processo di elaborazione di Clarify. SageMaker
+ **start\$1idx**: un indice a base zero per identificare la posizione della matrice che indica l'inizio del frammento di testo parziale.
Di seguito è riportato un esempio di una singola riga di un file di valori SHAP locale, abbellita per migliorarne la leggibilità.
```
{
"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
}
}
]
}
]
}
```
### Report di analisi SHAP
Il rapporto di analisi SHAP fornisce un grafico a barre con un massimo di `10` valori SHAP globali principali. Il seguente esempio di grafico mostra i valori SHAP per le `4` funzionalità principali.
![\[Grafico a barre orizzontali dei valori SHAP globali calcolati per la variabile di destinazione delle quattro funzionalità principali.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify/shap-chart.png)
## Analisi della spiegabilità della visione artificiale (CV)
SageMaker Clarify Computer Vision Explainability utilizza un set di dati composto da immagini e tratta ogni immagine come una raccolta di super pixel. Dopo l'analisi, il processo di elaborazione di SageMaker Clarify genera un set di dati di immagini in cui ogni immagine mostra la mappa termica dei super pixel.
L'esempio seguente mostra un segno di limite di velocità di ingresso sulla sinistra e una mappa termica che mostra l'entità dei valori SHAP sulla destra. Questi valori SHAP sono stati calcolati da un modello Resnet-18 di riconoscimento delle immagini addestrato a riconoscere i [segnali stradali tedeschi](https://benchmark.ini.rub.de/gtsrb_news.html). Il set di dati German Traffic Sign Recognition Benchmark (GTSRB) è fornito nel paper [Man vs. computer: benchmarking machine learning algorithms for traffic sign recognition](https://www.sciencedirect.com/science/article/abs/pii/S0893608012000457?via%3Dihub). Nell'output di esempio, valori positivi elevati indicano che il super pixel ha una forte correlazione positiva con la previsione del modello. Valori negativi elevati indicano che il super pixel ha una forte correlazione negativa con la previsione del modello. Maggiore è il valore assoluto del valore SHAP mostrato nella mappa termica, più forte è la relazione tra il super pixel e la previsione del modello.
![\[Immagine di input del segnale del limite di velocità e mappa termica risultante dei valori SHAP da un modello Resnet-18.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify/shap_speed-limit-70.png)
Per ulteriori informazioni, consulta i taccuini di esempio [Explaining Image Classification with SageMaker Clarify e [Explaining object detection](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) models with Amazon Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb). SageMaker
## PDPsAnalisi dei grafici di dipendenza parziale ()
I grafici di dipendenza parziale mostrano la dipendenza della risposta della destinazione prevista da una serie di funzionalità di input di interesse. Queste sono marginalizzate rispetto ai valori di tutte le altre funzionalità di input e vengono chiamate funzionalità complementari. In modo intuitivo, è possibile interpretare la dipendenza parziale come la risposta della destinazione, che è attesa come una funzione di ciascuna funzionalità di input di interesse.
### Schema per il file di analisi
I valori PDP vengono archiviati nella sezione `explanations` del file di analisi nella scheda del metodo `pdp`. I parametri per `explanations` sono come riportato di seguito:
+ **explanations**: la sezione dei file di analisi che contiene i risultati dell'analisi dell'importanza della funzionalità.
+ **pdp**: la sezione del file di analisi che contiene una matrice di spiegazioni PDP per una singola istanza. Ciascun elemento della matrice dispone dei seguenti membri:
+ **feature\$1name**: il nome dell'intestazione delle funzionalità fornite dalla configurazione `headers`.
+ **data\$1type — Il tipo di** funzionalità dedotto dal processo di elaborazione di Clarify. SageMaker I valori validi per `data_type` includono valori numerici e categorici.
+ **feature\$1values**: contiene i valori presenti nella funzionalità. Se quello `data_type` dedotto da SageMaker Clarify è categorico, `feature_values` contiene tutti i valori univoci che potrebbe essere la funzionalità. Se quello `data_type` dedotto da SageMaker Clarify è numerico, `feature_values` contiene un elenco del valore centrale dei bucket generati. Il parametro `grid_resolution` determina il numero di bucket utilizzati per raggruppare i valori di colonna delle funzionalità.
+ **data\$1distribution**: una matrice di percentuali, in cui ogni valore è la percentuale di istanze contenute in un bucket. Il parametro `grid_resolution` determina il numero di bucket. I valori di colonna delle funzionalità sono raggruppati in questi bucket.
+ **model\$1predictions**: una matrice di previsioni del modello, in cui ogni elemento è una matrice di previsioni che corrisponde a una classe nell'output del modello.
**label\$1headers**: le intestazioni delle etichette fornite dalla configurazione `label_headers`.
+ **error**: un messaggio di errore generato se i valori PDP non vengono calcolati per un motivo particolare. Questo messaggio di errore sostituisce il contenuto nei campi `feature_values`, `data_distributions` e `model_predictions`.
Di seguito è riportato un output di esempio da un file di analisi contenente un risultato dell'analisi 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"]
},
...
]
}
}
```
### Report di analisi PDP
È possibile generare un report di analisi contenente un grafico PDP per ogni funzionalità. Il grafico PDP traccia `feature_values` lungo l'asse x e `model_predictions` lungo l'asse y. Per i modelli multiclasse, `model_predictions` è una matrice e ogni elemento di questa matrice corrisponde a una delle classi di previsione del modello.
Di seguito è riportato un esempio di grafico PDP per la funzionalità `Age`. Nell'output di esempio, il PDP mostra il numero di valori delle funzionalità raggruppati in bucket. Il numero di bucket è determinato da `grid_resolution`. I bucket di valori delle funzionalità vengono tracciati sulla base delle previsioni del modello. In questo esempio, i valori più alti delle funzionalità hanno gli stessi valori di previsione del modello.
![\[Grafico a linee che mostra come variano le previsioni del modello rispetto a feature_values per 10 punti univoci della griglia.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify/pdp-chart.png)
## Valori asimmetrici di Shapley
SageMaker I processi di elaborazione di Clarify utilizzano l'algoritmo di valori asimmetrico di Shapley per calcolare le attribuzioni delle spiegazioni dei modelli di previsione delle serie temporali. Questo algoritmo determina il contributo delle funzionalità di input in ogni fase temporale verso le previsioni elaborate.
### Schema per il file di analisi dei valori asimmetrici di Shapley
I risultati dei valori asimmetrici di Shapley vengono archiviati in un bucket Amazon S3. Puoi trovare la posizione di questo bucket nella sezione delle *spiegazioni* del file di analisi. Questa sezione contiene i risultati dell’analisi sull’importanza delle funzionalità. I parametri seguenti sono inclusi nel file di analisi dei valori asimmetrici di Shapley.
+ **asymmetric\$1shapley\$1value**: la sezione del file di analisi che contiene i metadati relativi ai risultati del processo di spiegazione, inclusi:
+ **explanation\$1results\$1path**: la posizione Amazon S3 con i risultati della spiegazione
+ **direction**: la configurazione fornita dall’utente per il valore di configurazione di `direction`
+ **granularity**: la configurazione fornita dall’utente per il valore di configurazione di `granularity`
Il frammento seguente mostra i parametri menzionati in precedenza in un file di analisi di esempio:
```
{
"version": "1.0",
"explanations": {
"asymmetric_shapley_value": {
"explanation_results_path": EXPLANATION_RESULTS_S3_URI,
"direction": "chronological",
"granularity": "timewise",
}
}
}
```
Le sezioni seguenti descrivono in che modo la struttura dei risultati della spiegazione dipenda dal valore di `granularity` nella configurazione.
#### Granularità temporale
Quando la granularità è `timewise`, l’output è rappresentato nella seguente struttura. Il valore `scores` rappresenta l’attribuzione per ogni timestamp. Il valore `offset` rappresenta la previsione del modello sui dati baseline e descrive il comportamento del modello quando non riceve dati.
Il frammento seguente mostra un esempio di output per un modello che effettua previsioni per due fasi temporali. Pertanto, tutte le attribuzioni sono presentate in un elenco di due elementi in cui la prima voce si riferisce alla prima fase temporale prevista.
```
{
"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à dettagliata
L’esempio seguente mostra i risultati dell’attribuzione quando la granularità è `fine_grained`. Il valore `offset` ha lo stesso significato descritto nella sezione precedente. Le attribuzioni vengono calcolate per ogni funzionalità di input in ogni timestamp di una serie temporale di destinazione e delle serie temporali correlate, se presenti, e per ogni covariata statica, se disponibile.
```
{
"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]},
]
}
```
In entrambi i casi d’uso, `timewise` e `fine-grained`, i risultati vengono archiviati in formato JSON Lines (.jsonl).
# Risolvi i problemi relativi ai processi di elaborazione di Clarify SageMaker
Se riscontrate errori nei processi di elaborazione di SageMaker Clarify, consultate i seguenti scenari per identificare il problema.
**Nota**
Il motivo dell'errore e il messaggio di uscita devono contenere messaggi descrittivi ed eccezioni, se rilevate, durante l'esecuzione. Un motivo comune degli errori è che i parametri sono mancanti o non validi. Se ricevi messaggi poco chiari, confusi o fuorvianti o non riesci a trovare una soluzione, invia un feedback.
**Topics**
+ [Il processo di elaborazione non riesce a terminare](#clarify-troubleshooting-job-fails)
+ [L'esecuzione del processo di elaborazione sta impiegando troppo tempo](#clarify-troubleshooting-job-long)
+ [Il processo di elaborazione termina senza risultati e viene visualizzato un messaggio di avviso CloudWatch](#clarify-troubleshooting-no-results-and-warning)
+ [Messaggio di errore relativo a una configurazione dell'analisi non valida](#clarify-troubleshooting-invalid-analysis-configuration)
+ [Il calcolo delle metriche di bias non riesce per alcune o tutte le metriche](#clarify-troubleshooting-bias-metric-computation-fails)
+ [Mancata corrispondenza tra la configurazione dell'analisi e l'input/output dataset/model](#clarify-troubleshooting-mismatch-analysis-config-and-data-model)
+ [Il modello restituisce Errore interno del server 500 oppure il container ritorna alle previsioni per record a causa di un errore del modello](#clarify-troubleshooting-500-internal-server-error)
+ [Ruolo di esecuzione non valido](#clarify-troubleshooting-execution-role-invalid)
+ [Impossibile scaricare i dati](#clarify-troubleshooting-data-download)
+ [Impossibile connettersi all'IA SageMaker](#clarify-troubleshooting-connection)
## Il processo di elaborazione non riesce a terminare
Se il processo di elaborazione non riesce a terminare, prova a eseguire le operazioni indicate di seguito:
+ Ispeziona i log del processo direttamente nel notebook in cui hai eseguito il processo. I log del processo si trovano nell'output della cella del notebook in cui è stata avviata l'esecuzione.
+ Controllate i log in del job. CloudWatch
+ Aggiungi la riga seguente nel tuo notebook per descrivere l'ultimo processo di elaborazione e cerca il motivo dell'errore e il messaggio di uscita:
+ `clarify_processor.jobs[-1].describe()`
+ Esegui il seguente comando AWS CLI; per descrivere il processo di elaborazione e cerca il motivo dell'errore e il messaggio di uscita:
+ `aws sagemaker describe-processing-job —processing-job-name `
## L'esecuzione del processo di elaborazione sta impiegando troppo tempo
Se l'esecuzione del processo di elaborazione impiega troppo tempo, utilizza i seguenti metodi per trovare la causa principale.
Controlla se la configurazione delle risorse è sufficiente per gestire il carico di calcolo. Per velocizzare il processo, prova quanto segue:
+ Utilizzate un tipo di istanza più grande. SageMaker Clarify interroga ripetutamente il modello e un'istanza più grande può ridurre significativamente i tempi di calcolo. Per un elenco delle istanze disponibili, delle relative dimensioni di memoria, larghezza di banda e altri dettagli sulle prestazioni, consulta i prezzi di [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/pricing/).
+ Aggiungi altre istanze. SageMaker Clarify può utilizzare più istanze per spiegare più punti dati di input in parallelo. Per abilitare il calcolo parallelo, imposta il valore `instance_count` su più di `1` quando chiami `SageMakerClarifyProcessor`. Per ulteriori informazioni, consulta [Come eseguire processi di elaborazione SageMaker Clarify paralleli](clarify-processing-job-run.md#clarify-processing-job-run-spark). Se aumenti il conteggio istanze, monitora le prestazioni dell'endpoint per controllare che sia in grado di distribuire il carico aumentato. Per ulteriori informazioni, consulta [Acquisizione di dati da endpoint in tempo reale](model-monitor-data-capture-endpoint.md).
+ Se stai calcolando valori SHapley Additive exPlanations (SHAP), riduci il parametro `num_samples` nel file di configurazione dell'analisi. Il numero di campioni influisce direttamente su quanto segue:
+ La dimensione dei set di dati sintetici inviati all'endpoint
+ Runtime processo
La riduzione del numero di campioni può anche portare a una riduzione della precisione nella stima dei valori SHAP. Per ulteriori informazioni, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
## Il processo di elaborazione termina senza risultati e viene visualizzato un messaggio di avviso CloudWatch
Se il processo di elaborazione termina ma non viene trovato alcun risultato, CloudWatch i registri generano un messaggio di avviso che indica che Signal 15 ha ricevuto, è in corso. Questo avviso indica che il processo è stato interrotto perché una richiesta del cliente ha richiamato l'`StopProcessingJob`API o che il processo è scaduto il tempo assegnato per il suo completamento. In quest'ultimo caso, controlla la durata massima nella configurazione del processo (`max_runtime_in_seconds`) e aumentala secondo necessità.
## Messaggio di errore relativo a una configurazione dell'analisi non valida
+ Se viene visualizzato il messaggio di errore Impossibile caricare la configurazione dell'analisi come JSON., ciò significa che il file di input della configurazione dell'analisi per il processo di elaborazione non contiene un oggetto JSON valido. Controlla la validità dell'oggetto JSON utilizzando un linter JSON.
+ Se viene visualizzato il messaggio di errore Errore di convalida dello schema di configurazione dell'analisi., ciò significa che il file di input della configurazione dell'analisi per il processo di elaborazione contiene campi sconosciuti o tipi non validi per alcuni valori del campo. Esamina i parametri di configurazione nel file e confrontali con i parametri elencati nel file di configurazione dell'analisi. Per ulteriori informazioni, consulta [File di configurazione dell’analisi](clarify-processing-job-configure-analysis.md).
## Il calcolo delle metriche di bias non riesce per alcune o tutte le metriche
Se ricevi uno dei seguenti messaggi di errore: Nella colonna dell'etichetta prevista non sono presenti valori delle etichette, la serie Indice previsto positivo contiene tutti valori falsi. o Il tipo di dati della serie colonna dell'etichetta prevista non è lo stesso della serie colonna dell'etichetta., prova quanto segue:
+ Controlla che venga utilizzato il set di dati corretto.
+ Controlla se la dimensione del set di dati è troppo piccola; se, ad esempio, contiene solo poche righe. Ciò può far sì che gli output del modello abbiano lo stesso valore o che il tipo di dati venga dedotto in modo errato.
+ Controlla se l'etichetta o la sfaccettatura viene considerata continua o categorica. SageMaker Clarify utilizza l'euristica per determinare il. [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)) Per quanto riguarda le metriche di distorsione successive all'allenamento, il tipo di dati restituito dal modello potrebbe non corrispondere a quello contenuto nel set di dati o SageMaker Clarify potrebbe non essere in grado di trasformarlo correttamente.
+ Nel report sui bias, dovresti vedere un valore singolo per le colonne categoriche o un intervallo per le colonne continue.
+ Ad esempio, se una colonna ha i valori 0,0 e 1,0 come float, verrà trattata come continua anche se i valori univoci sono troppo pochi.
## Mancata corrispondenza tra la configurazione dell'analisi e l'input/output dataset/model
+ Controlla che il formato della linea di base nella configurazione dell'analisi sia lo stesso del formato del set di dati.
+ Se ricevi il messaggio di errore Impossibile convertire la stringa in float., controlla che il formato sia specificato correttamente. Potrebbe anche indicare che le previsioni del modello hanno un formato diverso rispetto alla colonna dell'etichetta o potrebbe indicare che la configurazione dell'etichetta o delle probabilità non è corretta.
+ Se ricevi il messaggio di errore Impossibile localizzare il facet. oppure Le intestazioni devono contenere un'etichetta. o Le intestazioni nella configurazione non corrispondono al numero di colonne nel set di dati. o Nomi delle funzionalità non trovati., controlla che le intestazioni corrispondano alle colonne.
+ Se ricevi il messaggio di errore I dati devono contenere funzionalità., controlla il modello di contenuto per JSON Lines e confrontalo con l'esempio del set di dati, se disponibile.
## Il modello restituisce Errore interno del server 500 oppure il container ritorna alle previsioni per record a causa di un errore del modello
Se ricevi il messaggio di errore Ritorno alle previsioni per record a causa di un errore del modello., ciò potrebbe indicare che il modello non è in grado di gestire la dimensione del batch, di essere limitato o semplicemente non accetta l'input passato dal container a causa di problemi di serializzazione. È necessario esaminare CloudWatch i log dell'endpoint SageMaker AI e cercare messaggi di errore o traceback. Nei casi di limitazione dei modelli, può essere utile utilizzare un tipo di istanza diverso o aumentare il numero di istanze per l'endpoint.
## Ruolo di esecuzione non valido
Ciò indica che il ruolo fornito non è corretto o che gli mancano le autorizzazioni necessarie. Controlla il ruolo e le relative autorizzazioni utilizzati per configurare il processo di elaborazione e verifica la policy di autorizzazione e di attendibilità per il ruolo.
## Impossibile scaricare i dati
Ciò indica che non è stato possibile scaricare gli input del processo per l'avvio del processo. Controlla il nome del bucket e le autorizzazioni per il set di dati e gli input di configurazione.
## Impossibile connettersi all'IA SageMaker
Ciò indica che il lavoro non è riuscito a raggiungere gli endpoint del servizio SageMaker AI. Controlla le impostazioni di configurazione di rete per il processo di elaborazione e verifica la configurazione del cloud privato virtuale (VPC).
## Notebook di esempio
Le seguenti sezioni contengono taccuini che consentono di iniziare a utilizzare SageMaker Clarify, di utilizzarlo per attività speciali, incluse quelle all'interno di un lavoro distribuito, e per la visione artificiale.
### Nozioni di base
I seguenti taccuini di esempio mostrano come utilizzare SageMaker Clarify per iniziare con le attività di spiegabilità e distorsione dei modelli. Queste attività includono la creazione di un processo di elaborazione, l’addestramento di un modello di machine learning (ML) e il monitoraggio delle previsioni tramite modello:
+ [Spiegabilità e rilevamento delle distorsioni con Amazon SageMaker Clarify: usa SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) per creare un processo di elaborazione per rilevare distorsioni e spiegare le previsioni dei modelli.
+ [Monitoraggio della deriva dei pregiudizi e delle variazioni nell'attribuzione delle funzionalità Amazon SageMaker Clarify: utilizza SageMaker Amazon](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) Model Monitor per monitorare la deriva dei pregiudizi e la variazione dell'attribuzione delle funzionalità nel tempo.
+ Come [leggere un set di dati in formato JSON Lines in un processo di elaborazione Clarify.](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.html) SageMaker
+ [Mitigate i pregiudizi, addestrate un altro modello imparziale e inseritelo nel registro dei modelli: utilizzate [Synthetic Minority Over-sampling Technique (SMOTE)](https://arxiv.org/pdf/1106.1813.pdf) e SageMaker Clarify per mitigare i pregiudizi, addestrate un altro modello](https://github.com/aws/amazon-sagemaker-examples/blob/master/end_to_end/fraud_detection/3-mitigate-bias-train-model2-registry-e2e.ipynb), quindi inserite il nuovo modello nel registro dei modelli. Questo notebook di esempio mostra anche come inserire i nuovi artefatti del modello, inclusi dati, codice e metadati del modello, nel registro dei modelli. Questo taccuino fa parte di una serie che mostra come integrare SageMaker Clarify in una pipeline di SageMaker intelligenza artificiale descritta in [Architect e creare l'intero ciclo di vita dell'apprendimento automatico con AWS](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) un post sul blog.
### Casi speciali
I seguenti taccuini mostrano come utilizzare SageMaker Clarify per casi speciali, ad esempio all'interno del proprio contenitore e per attività di elaborazione del linguaggio naturale:
+ [Equità e spiegabilità con SageMaker Clarify (Bring Your Own Container): create il vostro modello e contenitore](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_byoc.ipynb) in grado di integrarsi con SageMaker Clarify per misurare le distorsioni e generare un rapporto di analisi della spiegabilità. Questo taccuino di esempio introduce anche i termini chiave e mostra come accedere al rapporto tramite Studio Classic. SageMaker
+ [Equità e spiegabilità con SageMaker Clarify Spark Distributed Processing: utilizzate l'elaborazione distribuita](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_spark.ipynb) per eseguire un job SageMaker Clarify che misuri la distorsione pre-addestramento di un set di dati e la distorsione post-formazione di un modello. Questo taccuino di esempio mostra anche come ottenere una spiegazione dell'importanza delle funzionalità di input sull'output del modello e accedere al rapporto di analisi della spiegabilità tramite Studio Classic. SageMaker
+ [Spiegabilità con SageMaker Clarify - Partial Dependence Plots (PDP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.html): utilizzate SageMaker Clarify per generare e accedere a un rapporto sulla spiegabilità del modello. PDPs
+ Spiegazione dell'analisi [del sentimento testuale utilizzando la spiegabilità dell'elaborazione del linguaggio naturale (NLP) di SageMaker Clarify: utilizzate Clarify per l'analisi](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/text_explainability/text_explainability.html) del sentimento testuale. SageMaker
+ Utilizza la spiegabilità della visione artificiale (CV) per la [classificazione delle immagini](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.html) e il [rilevamento degli oggetti](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.html).
È stato verificato che questi notebook funzionino in Amazon SageMaker Studio Classic. Se hai bisogno di istruzioni su come aprire un notebook in Studio Classic, consulta [Crea o apri un notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Se ti viene richiesto di scegliere un kernel, scegli **Python 3 (Data Science)**.
# Bias dei dati di preaddestramento
I bias algoritmici, la discriminazione, l'equità e gli argomenti correlati sono stati studiati in discipline come legge, politica e informatica. Un sistema informatico potrebbe essere considerato di parte se discrimina determinati individui o gruppi di individui. I modelli di machine learning alla base di queste applicazioni apprendono dai dati e questi dati potrebbero riflettere disparità o altri bias intrinseci. Ad esempio, i dati di addestramento potrebbero non avere una rappresentazione sufficiente dei vari gruppi demografici o contenere etichette di parte. I modelli di machine learning addestrati su set di dati che presentano questi bias potrebbero finire per apprenderli e quindi riprodurre o addirittura aggravare tali bias nelle loro previsioni. Il campo del machine learning offre l'opportunità di affrontare i bias rilevandoli e misurandoli in ogni fase del ciclo di vita del machine learning. Puoi utilizzare Amazon SageMaker Clarify per determinare se i dati utilizzati per i modelli di formazione codificano eventuali distorsioni.
I bias possono essere misurati prima e dopo l'addestramento e monitorati rispetto alle linee di base dopo aver distribuito i modelli sugli endpoint a scopo di inferenza. Le metriche di bias pre-addestramento sono progettate per rilevare e misurare i bias nei dati non elaborati prima che vengano utilizzati per addestrare un modello. Le metriche utilizzate sono indipendenti dal modello perché non dipendono dagli output del modello. Tuttavia, esistono diversi concetti di equità che richiedono misure distinte di bias. Amazon SageMaker Clarify fornisce parametri di distorsione per quantificare vari criteri di equità.
Per ulteriori informazioni sulle metriche di distorsione, consulta [Scopri come Amazon SageMaker Clarify aiuta a rilevare pregiudizi e misure di equità per il](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias) [Machine Learning](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf) in Finance.
## Amazon SageMaker chiarisce i termini relativi a parzialità ed equità
SageMaker Clarify utilizza la seguente terminologia per parlare di pregiudizi e correttezza.
**Funzionalità**
Una proprietà o caratteristica misurabile individuale di un fenomeno osservato, contenuta in una colonna per dati tabulari.
**Etichetta**
Funzionalità che è l'obiettivo di addestramento di un modello di machine learning. Denominata *etichetta osservata* o *risultato osservato*.
**Etichetta prevista**
L'etichetta come prevista dal modello. Chiamata anche *risultato previsto*.
**Project N.E.M.O.**
Un'entità osservata descritta dai valori delle funzionalità e dal valore dell'etichetta, contenuta in una riga per dati tabulari.
**Set di dati**
Una raccolta di campioni.
**Bias**
Uno squilibrio nei dati di addestramento o nel comportamento di previsione del modello tra diversi gruppi, come l'età o la fascia di reddito. I bias possono derivare dai dati o dall'algoritmo utilizzati per addestrare il modello. Ad esempio, se un modello di machine learning viene addestrato principalmente su dati di individui di mezza età, può essere meno accurato quando si effettuano previsioni che coinvolgono persone giovani e anziane.
**Metrica di bias**
Una funzione che restituisce valori numerici che indicano il livello di un potenziale bias.
**Report di bias**
Una raccolta di metriche di bias per un determinato set di dati o una combinazione di un set di dati e un modello.
**Valori dell'etichetta positivi**
Valori dell'etichetta favorevoli a un gruppo demografico osservati in un esempio. In altre parole, indica che un esempio ha un *risultato positivo*.
**Valori dell'etichetta negativi**
Valori dell'etichetta sfavorevoli a un gruppo demografico osservati in un esempio. In altre parole, indica che un esempio ha un *risultato negativo*.
**Variabile del gruppo**
Colonna categorica del set di dati utilizzata per formare sottogruppi per la misurazione della disparità demografica condizionata (CDD). Richiesta solo per questa metrica per quanto riguarda il paradosso di Simpson.
**Facet**
Una colonna o una funzionalità che contiene gli attributi rispetto ai quali viene misurato il bias.
**Valore del facet**
I valori delle funzionalità degli attributi che il bias potrebbe favorire o sfavorire.
**Probabilità prevista**
La probabilità, prevista dal modello, che un esempio abbia un esito positivo o negativo.
## Notebook di esempio
Amazon SageMaker Clarify fornisce il seguente notebook di esempio per il rilevamento delle distorsioni:
+ [Spiegabilità e rilevamento dei pregiudizi con Amazon SageMaker Clarify: usa SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) per creare un processo di elaborazione per rilevare distorsioni e spiegare le previsioni dei modelli con l'attribuzione di funzionalità.
È stato verificato che questo notebook funzioni solo in Amazon SageMaker Studio. Se hai bisogno di istruzioni su come aprire un notebook in Amazon SageMaker Studio, consulta[Crea o apri un notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Se ti viene richiesto di scegliere un kernel, scegli **Python 3 (Data Science)**.
**Topics**
+ [Amazon SageMaker chiarisce i termini relativi a parzialità ed equità](#clarify-bias-and-fairness-terms)
+ [Notebook di esempio](#clarify-data-bias-sample-notebooks)
+ [Metriche di bias pre-addestramento](clarify-measure-data-bias.md)
+ [Genera report per eventuali distorsioni nei dati di pre-allenamento in Studio SageMaker](clarify-data-bias-reports-ui.md)
# Metriche di bias pre-addestramento
Misurare i bias nei modelli ML è un primo passo per mitigare i bias. Ogni misura di bias corrisponde a una diversa nozione di equità. Anche la considerazione di semplici concetti di equità porta a molte misure diverse applicabili in vari contesti. Si consideri, ad esempio, l'equità rispetto all'età e, per semplicità, che le due fasce demografiche rilevanti, denominate *facet*, siano gli individui di mezza età e il resto della popolazione. Nel caso di un modello di ML per l'erogazione di prestiti, potremmo volere che i prestiti alle piccole imprese vengano emessi a un numero uguale di entrambi i gruppi demografici. Oppure, quando elaboriamo i candidati per un lavoro, potremmo voler vedere un numero uguale di membri di ogni gruppo demografico assunti. Tuttavia, questo approccio può presupporre che per questi lavori si candidino lo stesso numero di persone di entrambe le fasce d'età, quindi potremmo decidere di stabilire una condizione per il numero di candidature. Inoltre, potremmo voler considerare non se si candidi lo stesso numero di persone, ma se abbiamo lo stesso numero di candidati qualificati. In alternativa, possiamo considerare l'equità come un uguale tasso di accettazione di candidati qualificati in entrambe le fasce di età, oppure un uguale tasso di rifiuto dei candidati, o entrambi. È possibile utilizzare set di dati con proporzioni diverse di dati sugli attributi di interesse. Questo squilibrio può confondere la misura di bias scelta. I modelli potrebbero essere più accurati nella classificazione di un facet rispetto all'altro. Pertanto, è necessario scegliere metriche di bias concettualmente appropriate per l'applicazione e la situazione.
Utilizziamo la seguente notazione per discutere le metriche di bias. Il modello concettuale qui descritto riguarda la classificazione binaria, in cui gli eventi sono etichettati come aventi solo due esiti possibili nel loro spazio di esempio, indicati come positivo (con valore 1) e negativo (con valore 0). Questo framework è generalmente estensibile alla classificazione multicategoria in modo semplice o ai casi che comportano esiti con valori continui quando necessario. Nel caso della classificazione binaria, le etichette positive e negative vengono assegnate agli esiti registrati in un set di dati non elaborati per un facet favorito *a* e per un facet sfavorito *d*. Queste etichette y vengono chiamate *etichette osservate* per distinguerle dalle *etichette previste* y' che vengono assegnate da un modello di machine learning durante le fasi di addestramento o inferenza del ciclo di vita ML. Queste etichette vengono utilizzate per definire le distribuzioni di probabilità Pa(y) e Pd(y) per i rispettivi esiti facet.
+ etichette:
+ y rappresenta le n etichette osservate per gli esiti degli eventi in un set di dati di addestramento.
+ y' rappresenta le etichette previste per le n etichette osservate nel set di dati di un modello addestrato.
+ esiti:
+ Un esito positivo (con valore 1) per un esempio, come l'accettazione di un'applicazione.
+ n(1) è il numero di etichette osservate per gli esiti positivi (accettazioni).
+ n'(1) è il numero di etichette previste per gli esiti positivi (accettazioni).
+ Un esito negativo (con valore 0) per un esempio, come il rifiuto di un'applicazione.
+ n(0) è il numero di etichette osservate per gli esiti negativi (rifiuti).
+ n'(0) è il numero di etichette previste per gli esiti negativi (rifiuti).
+ valori dei facet:
+ facet *a*: il valore della caratteristica che definisce un gruppo demografico favorito dalla distorsione.
+ na è il numero di etichette osservate per il valore del facet favorito: na = na(1) \$1 na(0) è la somma delle etichette osservate positive e negative per il facet di valore *a*.
+ n'a è il numero di etichette previste per il valore del facet favorito: n'a = n'a(1) \$1 n'a(0) è la somma delle etichette previste positive e negative per il valore del facet *a*. Nota che n'a = na.
+ facet *d*: il valore della funzionalità che definisce un gruppo demografico sfavorito dalla distorsione.
+ nd è il numero di etichette osservate per il valore del facet sfavorito: nd = nd(1) \$1 nd(0) è la somma delle etichette osservate positive e negative per il valore del facet *d*.
+ n'd è il numero di etichette previste per il valore del facet sfavorito: n'd = n'd(1) \$1 n'd(0) è la somma delle etichette previste positive e negative per il valore del facet *d*. Nota che n'd = nd.
+ distribuzioni di probabilità per gli esiti degli esiti dei dati del facet con etichetta:
+ Pa(y) è la distribuzione di probabilità delle etichette osservate per il facet *a*. Per i dati con etichetta binari, questa distribuzione è data dal rapporto tra il numero di esempi nel facet *a* etichettato con esiti positivi e il numero totale, Pa(y1) = na(1)/na, e dal rapporto tra il numero di esempi con esiti negativi e il numero totale, Pa(y0) = na(0)/na.
+ Pd(y) è la distribuzione di probabilità delle etichette osservate per il facet *d*. Per i dati con etichetta binari, questa distribuzione è data dal numero di esempi nel facet *d* etichettato con esiti positivi rispetto al numero totale, Pd(y1) = nd(1)/nd, e dal rapporto tra il numero di esempi con esiti negativi e il numero totale, Pd(y0) = nd(0)/nd.
I modelli addestrati su dati di parte rispetto a disparità demografiche potrebbero apprenderle e persino aggravarle. Per identificare le distorsioni nei dati prima di spendere risorse per addestrare i modelli su di essi, SageMaker Clarify fornisce metriche di distorsione dei dati che puoi calcolare su set di dati grezzi prima dell'addestramento. Tutte le metriche pre-addestramento sono indipendenti dal modello perché non dipendono dagli output del modello e quindi sono valide per qualsiasi modello. La prima metrica di bias esamina lo squilibrio tra i facet, ma non gli esiti. Determina la misura in cui la quantità di dati di addestramento è rappresentativa tra i diversi facet, come richiesto per l'applicazione. Le restanti metriche di bias confrontano la distribuzione delle etichette degli esiti in vari modi per i facet *a* e *d* nei dati. Le metriche che analizzano i valori negativi possono rilevare bias negativi. La tabella seguente contiene una guida con istruzioni rapide e collegamenti alle metriche di bias pre-addestramento.
Metriche di bias pre-addestramento
| Metrica di bias | Description | Domanda di esempio | Interpretazione dei valori delle metriche |
| --- | --- | --- | --- |
| [Squilibrio di classe (CI)](clarify-bias-metric-class-imbalance.md) | Misura lo squilibrio nel numero di membri tra diversi valori di facet. | Potrebbero esserci bias basati sull'età dovuti alla mancanza di dati sufficienti per la fascia demografica esterna a un facet di mezza età? | Intervallo normalizzato: [-1, \$11] Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Differenza nelle proporzioni delle etichette (DPL)](clarify-data-bias-metric-true-label-imbalance.md) | Misura lo squilibrio nel numero di esiti positivi tra diversi valori di facet. | Potrebbero esserci pregiudizi basati sull'età nelle previsioni del machine learning dovuti all'etichettatura di parte dei valori dei facet nei dati? | Intervallo per etichette di facet binarie e multicategoria normalizzate: [-1, \$11] Intervallo per etichette continue: (-∞, \$1∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergenza Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md) | Misura in che misura le distribuzioni degli esiti dei diversi facet divergono l'una dall'altra entropicamente. | Quanto sono diverse le distribuzioni degli esiti delle domande di prestito per i diversi gruppi demografici? | Intervallo binario, multicategoria, continuo: [0, \$1∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergenza Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) | Misura in che misura le distribuzioni degli esiti dei diversi facet divergono l'una dall'altra entropicamente. | Quanto sono diverse le distribuzioni degli esiti delle domande di prestito per i diversi gruppi demografici? | Intervallo binario, multicategoria, continuo: [0, \$1∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md) | Misura una differenza p-norm tra diverse distribuzioni demografiche degli esiti associati a diversi facet in un set di dati. | Quanto sono diverse le distribuzioni degli esiti delle domande di prestito per i diversi gruppi demografici? | Intervallo binario, multicategoria, continuo: [0, \$1∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Distanza di variazione totale (TVD)](clarify-data-bias-metric-total-variation-distance.md) | Misura metà della differenza L1-norm tra diverse distribuzioni demografiche degli esiti associati a diversi facet in un set di dati. | Quanto sono diverse le distribuzioni degli esiti delle domande di prestito per i diversi gruppi demografici? | Intervallo per esiti binari, multicategoria e continui: [0, \$1∞) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) | Misura la massima divergenza tra gli esiti nelle distribuzioni per i diversi facet di un set di dati. | Quali esiti delle domande di ammissione all'università manifestano le maggiori disparità per gruppo demografico? | Intervallo di valori KS per esiti binari, multicategoria e continui: [0, \$11][\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Disparità demografica condizionale (CDD)](clarify-data-bias-metric-cddl.md) | Misura la disparità degli esiti tra i diversi facet nel loro insieme, ma anche tra sottogruppi. | Alcuni gruppi hanno una proporzione maggiore di rifiuti come esiti dell'ammissione all'università rispetto alla proporzione di accettazioni? | Intervallo di CDD: [-1, \$11] [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-data-bias.html) |
Per ulteriori informazioni sulle metriche di bias, consulta [Misure di equità per il machine learning nella finanza](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
**Topics**
+ [Squilibrio di classe (CI)](clarify-bias-metric-class-imbalance.md)
+ [Differenza nelle proporzioni delle etichette (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ [Divergenza Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ [Divergenza Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md)
+ [Distanza di variazione totale (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ [Disparità demografica condizionale (CDD)](clarify-data-bias-metric-cddl.md)
# Squilibrio di classe (CI)
Il bias dello squilibrio di classe (CI) si verifica quando un valore di facet *d* ha meno esempi di addestramento rispetto a un altro facet *a* del set di dati. Questo perché i modelli si adattano preferibilmente ai facet più grandi a scapito dei facet più piccoli e quindi possono comportare un errore di addestramento più elevato per il facet *d*. I modelli corrono inoltre un rischio maggiore di overfitting dei set di dati più piccoli, il che può causare un errore di test maggiore per il facet *d*. Consideriamo l'esempio in cui un modello di machine learning viene addestrato principalmente su dati di individui di mezza età (facet a); potrebbe essere meno accurato nell'effettuare previsioni che riguardano persone giovani e anziane (facet d).
La formula per la misura (normalizzata) dello squilibrio dei facet:
CI = (na - nd)/(na \$1 nd)
Dove na è il numero di membri del facet *a* e nd il numero per il facet *d*. I suoi valori variano nell'intervallo [-1, 1].
+ I valori CI positivi indicano che il facet *a* contiene più esempi di addestramento nel set di dati e un valore 1 indica che i dati contengono solo membri del facet *a*.
+ I valori di CI vicini allo zero indicano una distribuzione più equa dei membri tra i facet e un valore pari a zero indica una partizione perfettamente uguale tra i facet e rappresenta una distribuzione equilibrata degli esempi nei dati di addestramento.
+ I valori CI negativi indicano che il facet *d* contiene più esempi di addestramento nel set di dati e un valore -1 indica che i dati contengono solo membri del facet *d*.
+ I valori di CI vicini ai valori estremi di -1 o 1 sono molto squilibrati e corrono un rischio sostanziale di fare previsioni di parte.
Se si riscontra uno squilibrio significativo tra i facet, è consigliabile riequilibrare l'esempio prima di procedere all'addestramento dei modelli su di esso.
# Differenza nelle proporzioni delle etichette (DPL)
La differenza nelle proporzioni delle etichette (DPL) confronta la proporzione di esiti osservati con etichette positive per il facet *d* con la proporzione di esiti osservati con etichette positive del facet *a* in un set di dati di addestramento. Ad esempio, è possibile utilizzarla per confrontare la proporzione di individui di mezza età (facet *a*) e di altri gruppi di età (facet *d*) che hanno ricevuto l'approvazione per prestiti finanziari. I modelli di machine learning cercano di imitare il più fedelmente possibile le decisioni dei dati di addestramento. Quindi è probabile che un modello di machine learning addestrato su un set di dati con una DPL elevata rifletta lo stesso squilibrio nelle sue previsioni future.
La formula per la differenza nelle proporzioni delle etichette è la seguente:
DPL = (qa - qd)
Dove:
+ qa = na(1)/na è la proporzione del facet *a* con un valore di etichetta osservato pari a 1. Ad esempio, la proporzione di persone di mezza età che ottiene l'approvazione per i prestiti. Qui na(1) rappresenta il numero di membri del facet *a* che ottengono un esito positivo e na è il numero di membri del facet *a*.
+ qd = nd(1)/nd è la proporzione del facet *d* con un valore di etichetta osservato pari a 1. Ad esempio, la proporzione di persone non di mezza età che ottiene l'approvazione per i prestiti. Qui nd(1) rappresenta il numero di membri del facet *d* che ottengono un esito positivo e nd è il numero di membri del facet *d*.
Se la DPL è abbastanza vicina a 0, allora diciamo che la *parità demografica* è stata raggiunta.
Per le etichette di facet binarie e multicategoria, i valori DPL variano nell'intervallo (-1, 1). Per le etichette continue, impostiamo una soglia per comprimere le etichette in formato binario.
+ I valori DPL positivi indicano che il facet *a* ha una proporzione maggiore di esiti positivi rispetto al facet *d*.
+ I valori di DPL vicini allo zero indicano una proporzione più equa di esiti positivi tra i facet, mentre un valore pari a zero indica una perfetta parità demografica.
+ I valori DPL negativi indicano che il facet *d* ha una proporzione maggiore di esiti positivi rispetto al facet *a*.
Il fatto che una DPL di valore elevato sia problematica o meno varia da una situazione all'altra. In un caso problematico, una DPL di valore elevato potrebbe essere un segnale di problemi alla base dei dati. Ad esempio, un set di dati con una DPL elevata potrebbe riflettere bias o pregiudizi storici nei confronti di gruppi demografici basati sull'età che non sarebbero ideali da apprendere per un modello.
# Divergenza Kullback-Leibler (KL)
La divergenza Kullback-Leibler (KL) misura in che misura la distribuzione delle etichette osservate del facet *a*, Pa(y), diverge dalla distribuzione del facet *d*, Pd(y). È anche nota come entropia relativa di Pa(y) rispetto a Pd(y) e quantifica la quantità di informazioni perse quando si passa da Pa(y) a Pd(y).
La formula per la divergenza Kullback-Leibler è la seguente:
KL(Pa \$1\$1 Pd) = ∑yPa(y)\$1log[Pa(y)/Pd(y)]
È l'aspettativa della differenza logaritmica tra le probabilità Pa(y) e Pd(y), dove l'aspettativa è ponderata dalle probabilità Pa(y). Questa non è una distanza reale tra le distribuzioni in quanto è asimmetrica e non soddisfa la disuguaglianza triangolare. L'attuazione utilizza logaritmi naturali, fornendo KL in unità di nat. L'uso di basi logaritmiche diverse fornisce risultati proporzionali ma in unità diverse. Ad esempio, utilizzando la base 2 si ottiene KL in unità di bit.
Ad esempio, supponiamo che un gruppo di richiedenti prestiti abbia un tasso di approvazione del 30% (facet *d*) e che il tasso di approvazione per gli altri richiedenti (facet *a*) sia dell'80%. La formula Kullback-Leibler fornisce la divergenza di distribuzione delle etichette tra il facet *a* e il facet *d* nel modo seguente:
KL = 0,8\$1ln(0,8/0,3) \$1 0,2\$1ln(0,2/0,7) = 0,53
La formula contiene due termini perché in questo esempio le etichette sono binarie. Questa misura può essere applicata a più etichette oltre a quelle binarie. Ad esempio, in uno scenario di ammissione all'università, supponiamo che a un candidato possa essere assegnata una delle tre etichette di categoria: yi = \$1y0, y1, y2\$1 = \$1rifiutato, in lista d'attesa, accettato\$1.
L'intervallo di valori per la metrica KS per esiti binari, multicategoria e continui è [0, \$1∞).
+ I valori vicini allo zero indicano che gli esiti sono distribuiti in modo simile per i diversi facet.
+ I valori positivi indicano che le distribuzioni delle etichette divergono, più sono positivi e maggiore è la divergenza.
# Divergenza Jensen-Shannon (JS)
La divergenza Jensen-Shannon (JS) misura in che misura le distribuzioni delle etichette dei diversi facet divergono l'una dall'altra a livello entropico. Si basa sulla divergenza Kullback-Leibler, ma è simmetrica.
La formula per la divergenza Jensen-Shannon è la seguente:
JS = ½\$1[KL(Pa \$1\$1 P) \$1 KL(Pd \$1\$1 P)]
Dove P = ½ (Pa \$1 Pd), la distribuzione media delle etichette tra i facet *a* e *d*.
L'intervallo di valori JS per esiti binari, multicategoria e continui è [0, ln(2)).
+ I valori vicini allo zero indicano che le etichette sono distribuite in modo simile.
+ I valori positivi indicano che le distribuzioni delle etichette divergono, più sono positivi e maggiore è la divergenza.
Questa metrica indica se esiste una grande divergenza in una delle etichette tra i vari facet.
# Lp-norm (LP)
La Lp-norm (LP) misura la distanza p-norm tra le distribuzioni dei facet delle etichette osservate in un set di dati di addestramento. Questa metrica è non negativa e quindi non può rilevare il bias inverso.
La formula per Lp-norm è la seguente:
Lp(Pa, Pd) = ( ∑y\$1\$1Pa - Pd\$1\$1p)1/p
Dove la distanza p-norm tra i punti x e y è definita come segue:
Lp(x, y) = (\$1x1-y1\$1p \$1 \$1x2-y2\$1p \$1 … \$1\$1xn-yn\$1p)1/p
2-norm è la norma euclidea. Supponiamo di avere una distribuzione degli esiti con tre categorie, ad esempio yi = \$1y0, y1, y2\$1 = \$1accettato, in lista d'attesa, rifiutato\$1 in uno scenario multicategoria di ammissioni all'università. Si calcola la somma dei quadrati delle differenze tra i conteggi degli esiti per i facet *a* e *d*. La distanza euclidea risultante viene calcolata come segue:
L2(Pa, Pd) = [(na(0) - nd(0))2 \$1 (na(1) - nd(1))2 \$1 (na(2) - nd(2))2]1/2
Dove:
+ na(i) è il numero dei risultati della nesima categoria nel facet *a*: ad esempio na(0) è il numero di accettazioni del facet *a*.
+ nd(i) è il numero dei risultati della nesima categoria nel facet *d*: ad esempio nd(2) è il numero di rifiuti del facet *d*.
L'intervallo di valori LP per esiti binari, multicategoria e continui è [0, √2), dove:
+ I valori vicini allo zero indicano che le etichette sono distribuite in modo simile.
+ I valori positivi indicano che le distribuzioni delle etichette divergono, più sono positivi e maggiore è la divergenza.
# Distanza di variazione totale (TVD)
La metrica di distorsione dei dati sulla distanza di variazione totale (TVD) è pari a metà della norma L1. TVD è la più grande differenza possibile tra le distribuzioni di probabilità per i risultati delle etichette dei facet *a* e *d*. La norma L1 è la distanza di Hamming, una metrica utilizzata per confrontare due stringhe di dati binari determinando il numero minimo di sostituzioni necessarie per cambiare una stringa in un'altra. Se le stringhe dovessero essere copie l'una dell'altra, determina il numero di errori che si sono verificati durante la copia. Nel contesto del rilevamento delle distorsioni, TVD quantifica quanti risultati del facet *a* dovrebbero essere modificati per corrispondere ai risultati del facet *d*.
La formula per la distanza di variazione totale è la seguente:
TVD = ½\$1L1(Pa, Pd)
Ad esempio, supponiamo di avere una distribuzione degli esiti con tre categorie, ad esempio yi = \$1y0, y1, y2\$1 = \$1accettato, in lista d'attesa, rifiutato\$1 in uno scenario multicategoria di ammissioni all'università. Per calcolare la TVD, si prendono le differenze tra i conteggi dei facet *a* e *d* per ciascun risultato. Il risultato è illustrato di seguito.
L1(Pa, Pd) = \$1na(0) - nd(0)\$1 \$1 \$1na(1) - nd(1)\$1 \$1 \$1na(2) - nd(2)\$1
Dove:
+ na(i) è il numero dei risultati della nesima categoria nel facet *a*: ad esempio na(0) è il numero di accettazioni del facet *a*.
+ nd(i) è il numero dei risultati della nesima categoria nel facet d: ad esempio nd(2) è il numero di rifiuti del facet *d*.
L'intervallo di valori TV per esiti binari, multicategoria e continui è [0, 1), dove:
+ I valori vicini allo zero indicano che le etichette sono distribuite in modo simile.
+ I valori positivi indicano che le distribuzioni delle etichette divergono, più sono positivi e maggiore è la divergenza.
# Kolmogorov-Smirnov (KS)
La metrica di distorsione di Kolmogorov-Smirnov (KS) è uguale alla divergenza massima tra le etichette nelle distribuzioni per i facet *a* e *d* di un set di dati. Il test KS a due campioni implementato da SageMaker Clarify integra le altre misure di squilibrio delle etichette individuando l'etichetta più squilibrata.
La formula per la metrica di Kolmogorov-Smirnov è la seguente:
KS = max(\$1Pa(y) - Pd(y)\$1)
Ad esempio, supponiamo che un gruppo di candidati (facet *a*) all'università venga respinto, inserito in lista d'attesa o accettato rispettivamente al 40%, 40%, 20% e che tali tassi per gli altri candidati (facet *d*) siano del 20%, 10%, 70%. Quindi, il valore metrico di distorsione di Kolmogorov-Smirnov è il seguente:
KS = max(\$10,4-0,2\$1, \$10,4-0,1\$1, \$10,2-0,7\$1) = 0,5
Questo ci dice che la divergenza massima tra le distribuzioni dei facet è 0,5 e si verifica nei tassi di accettazione. Ci sono tre termini nell'equazione perché le etichette sono multiclasse di cardinalità tre.
L'intervallo di valori LP per esiti binari, multicategoria e continui è [0, \$11], dove:
+ I valori vicini allo zero indicano che le etichette si sono distribuite uniformemente tra i facet in tutte le categorie di esiti. Ad esempio, entrambe le parti che hanno richiesto un prestito hanno ottenuto il 50% delle accettazioni e il 50% dei rifiuti.
+ I valori vicini a uno indicano che le etichette di un risultato erano tutte riunite in un unico facet. Ad esempio, il facet *a* ha ottenuto il 100% delle accettazioni e il facet *d* non ne ha ottenuta nessuna.
+ I valori intermittenti indicano gradi relativi di massimo squilibrio delle etichette.
# Disparità demografica condizionale (CDD)
La metrica della disparità demografica (DD) determina se un facet ha una percentuale maggiore dei risultati rifiutati nel set di dati rispetto ai risultati accettati. Nel caso binario in cui ci sono due facet, ad esempio uomini e donne, che costituiscono il set di dati, quello sfavorito è denominato facet *d* e quello preferito è etichettato come facet *a*. Ad esempio, nel caso delle ammissioni all'università, se le donne candidate costituivano il 46% dei candidati respinti e costituivano solo il 32% dei candidati accettati, affermiamo che esiste una *disparità demografica* perché la percentuale di donne respinte supera quella con cui vengono accettate. In questo caso le donne candidate sono etichettate come facet *d*. Se i candidati di sesso maschile rappresentavano il 54% dei richiedenti respinti e il 68% di quelli accettati, non vi è alcuna disparità demografica per questo facet, in quanto il tasso di rifiuto è inferiore a quello di accettazione. In questo caso i richiedenti sono etichettati come facet *a*.
La formula per la disparità demografica per il facet meno favorito *d* è la seguente:
DDd = nd(0)/n(0) - nd(1)/n(1) = PdR(y0) - PdA(y1)
Dove:
+ n(0) = na(0) \$1 nd(0) è il numero totale di risultati rifiutati nel set di dati per il facet favorito *a* e il facet svantaggiato *d*.
+ n(1) = na(1) \$1 nd(1) è il numero totale di risultati accettati nel set di dati per il facet favorito *a* e il facet svantaggiato *d*.
+ PdR(y0) è la proporzione di risultati rifiutati (con valore 0) nel facet *d*.
+ PdA(y1) è la proporzione di risultati accettati (valore 1) nel facet *d*.
Per l'esempio dell'ammissione all'università, la disparità demografica per le donne è DDd = 0,46 - 0,32 = 0,14. Per gli uomini DDa = 0,54 - 0,68 = - 0,14.
Per escludere il paradosso di Simpson è necessaria una metrica di disparità demografica condizionale (CDD) che condiziona DD sugli attributi che definiscono uno strato di sottogruppi nel set di dati. Il raggruppamento può fornire informazioni sulla causa delle apparenti disparità demografiche relative ai facet meno favoriti. Il caso classico è sorto nelle ammissioni a Berkeley, in cui gli uomini sono stati accettati a un tasso complessivo più elevato rispetto alle donne. Le statistiche relative a questo caso sono state utilizzate nei calcoli di esempio di DD. Tuttavia, quando sono stati esaminati i sottogruppi dipartimentali, è stato dimostrato che le donne hanno tassi di ammissione più elevati rispetto agli uomini se condizionate dal reparto. La spiegazione è data dal fatto che le donne si erano rivolte a reparti con tassi di accettazione inferiori rispetto agli uomini. L'esame dei tassi di accettazione suddivisi per sottogruppo ha rivelato che le donne erano effettivamente accettate a un tasso più elevato rispetto agli uomini nei dipartimenti con tassi di accettazione inferiori.
La metrica CDD fornisce un'unica misura per tutte le disparità riscontrate nei sottogruppi definiti da un attributo di un set di dati calcolandone la media. È definita come la media ponderata delle disparità demografiche (DDi) per ciascuno dei sottogruppi, con ogni disparità di sottogruppo ponderata in proporzione al numero di osservazioni contenute. La formula per la disparità demografica condizionata è la seguente:
CDD = (1/n)\$1∑ini \$1DDi
Dove:
+ ∑ini = è il numero totale di osservazioni e ni è il numero di osservazioni per ciascun sottogruppo.
+ DDi = ni(0)/n(0) - ni(1)/n(1) = PiR(y0) - PiA(y1) è la disparità demografica per l'nesimo sottogruppo.
La disparità demografica per un sottogruppo (DDi) è la differenza tra la percentuale di risultati rifiutati e la percentuale di risultati accettati per ciascun sottogruppo.
L'intervallo di valori DD per i risultati binari per l'intero set di dati DDd o per i relativi sottogruppi condizionati DDi è [-1, \$11].
+ \$11: quando non vi sono rifiuti nel facet *a* o nel sottogruppo e accettazioni nel facet *d* o nel sottogruppo
+ I valori positivi indicano che esiste una disparità demografica in quanto il facet *d* o il sottogruppo ha una percentuale maggiore di risultati rifiutati nel set di dati rispetto ai risultati accettati. Più alto è il valore, meno favorito è il facet e maggiore è la disparità.
+ I valori positivi indicano che non esiste una disparità demografica in quanto il facet *d* o il sottogruppo ha una percentuale maggiore di risultati accettati nel set di dati rispetto ai risultati rifiutati. Più basso è il valore, più il facet è favorito.
+ -1: quando non vi sono rifiuti nel facet *d* o nel sottogruppo e accettazioni nel facet *a* o nel sottogruppo
Se non si condiziona alcun elemento, CDD è pari a zero se e solo se DPL ha lo stesso valore.
Questa metrica è utile per esplorare i concetti di discriminazione diretta e indiretta e di giustificazione oggettiva nelle leggi e nella giurisprudenza contro la discriminazione nell'UE e nel Regno Unito. Per ulteriori informazioni, consulta [Perché l'equità non può essere automatizzata](https://arxiv.org/abs/2005.05906). Questo documento contiene anche i dati e l'analisi pertinenti del caso di ammissione a Berkeley, che mostra come il condizionamento relativo ai sottogruppi dipartimentali del tasso di ammissione illustri il paradosso di Simpson.
# Genera report per eventuali distorsioni nei dati di pre-allenamento in Studio SageMaker
SageMaker Clarify è integrato con Amazon SageMaker Data Wrangler, che può aiutarti a identificare errori durante la preparazione dei dati senza dover scrivere il tuo codice. Data Wrangler offre una end-to-end soluzione per importare, preparare, trasformare, personalizzare e analizzare i dati con Amazon Studio. SageMaker Per una panoramica del flusso di lavoro di preparazione dei dati di Data Wrangler, consulta [Prepara i dati ML con Amazon SageMaker Data Wrangler](data-wrangler.md).
Si specificano gli attributi di interesse, come il sesso o l'età, e SageMaker Clarify esegue una serie di algoritmi per rilevare la presenza di distorsioni in tali attributi. Dopo l'esecuzione dell'algoritmo, SageMaker Clarify fornisce un rapporto visivo con una descrizione delle fonti e della gravità dei possibili pregiudizi in modo da poter pianificare le misure per mitigarli. Ad esempio, in un set di dati finanziari che contiene pochi esempi di prestiti commerciali concessi a una fascia di età rispetto ad altre, l' SageMaker intelligenza artificiale segnala lo squilibrio in modo da evitare un modello che sfavorisca quella fascia di età.
**Analisi e segnalazione di eventuali distorsioni nei dati**
Per iniziare a usare Data Wrangler consulta [Inizia a usare Data Wrangler](data-wrangler-getting-started.md).
1. In Amazon SageMaker Studio Classic, dal menu **Home** (![\[Black square icon representing a placeholder or empty image.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/studio/icons/house.png)) nel pannello di sinistra, vai al nodo **Data**, quindi scegli **Data Wrangler**. Si apre la **pagina di destinazione di Data Wrangler** in Studio Classic.
1. Scegli il pulsante **\$1 Importa dati** per creare un nuovo flusso.
1. Nella pagina del flusso, dalla scheda **Importa**, scegli Amazon S3, accedi al tuo bucket Amazon S3, trova il tuo set di dati, quindi scegli **Importa**.
1. Dopo aver importato i dati, nel grafico di flusso nella scheda **Flusso di dati**, scegli il segno **\$1** a destra del nodo **Tipi di dati**.
1. Scegli **Aggiungi analisi**.
1. Nella pagina **Crea analisi**, scegli **Report di distorsione** per il **Tipo di analisi**.
1. Configura il report di distorsione fornendo il **Nome** del report, la colonna di previsione e, se si tratta di un valore o di una soglia, la colonna da analizzare per individuare eventuali distorsioni (il facet) e la specifica del valore o della soglia.
1. Continua a configurare il report di distorsione scegliendo le metriche di distorsione.
![\[Scegli la metrica di distorsione.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify-data-wrangler-configure-bias-metrics.png)
1. Scegli **Verifica eventuali distorsioni** per generare e visualizzare il report sulle distorsioni. Scorrere per visualizzare tutti i report.
![\[Genera e visualizza il report di distorsione.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify-data-wrangler-create-bias-report.png)
1. Scegli il cursore a destra della descrizione di ogni metrica di distorsione per visualizzare la documentazione che può aiutarti a interpretare il significato dei valori delle metriche.
1. Per visualizzare un riepilogo della tabella dei valori delle metriche di distorsione, scegli l'interruttore **Tabella**. Per salvare il report, scegli **Salva** nell'angolo in basso a destra della pagina. Puoi vedere il report sul grafico di flusso nella scheda **Flusso di dati**. Fai doppio clic sul report per aprirlo.
# Bias dei modelli e dei dati di post-addestramento
L'analisi delle distorsioni post-addestramento può aiutare a rivelare distorsioni che potrebbero essere state causate da distorsioni nei dati o introdotte dagli algoritmi di classificazione e previsione. Queste analisi prendono in considerazione i dati, comprese le etichette, nonché le previsioni di un modello. Le prestazioni vengono valutate analizzando le etichette previste o confrontando le previsioni con i valori target osservati nei dati rispetto a gruppi con attributi diversi. Esistono diverse nozioni di equità, ognuna delle quali richiede metriche di distorsione diverse per essere misurata.
Esistono concetti legali di equità che potrebbero non essere facili da comprendere poiché difficili da individuare. Si riporta ad esempio il concetto statunitense di impatto diversificato che si verifica quando un gruppo, definito come facet svantaggiato *d*, subisce un effetto negativo anche quando l'approccio adottato sembra equo. Questo tipo di distorsione potrebbe non essere dovuto a un modello di machine learning, ma potrebbe comunque essere rilevabile mediante l'analisi di distorsioni post-addestramento.
Amazon SageMaker Clarify cerca di garantire un uso coerente della terminologia. Per un elenco dei termini e delle relative definizioni, consulta [Amazon SageMaker chiarisce i termini relativi a parzialità ed equità](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms).
Per ulteriori informazioni sulle metriche relative ai pregiudizi post-formazione, consulta Scopri [come Amazon SageMaker Clarify aiuta a rilevare pregiudizi](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/) e [misure di equità per il Machine](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf) Learning in Finance. .
# Metriche sui bias dei modelli e dei dati di post-addestramento
Amazon SageMaker Clarify fornisce undici dati post-formazione e metriche di distorsione dei modelli per aiutare a quantificare varie concezioni di equità. Questi concetti non possono essere soddisfatti tutti contemporaneamente e la selezione dipende dalle specifiche dei casi che comportano le potenziali distorsioni analizzate. La maggior parte di queste metriche è una combinazione di numeri presi dalle matrici di confusione di classificazione binaria per i diversi gruppi demografici. Poiché l'equità e le distorsioni possono essere definite in base a un'ampia gamma di metriche, è necessario il giudizio umano per comprendere e scegliere quali metriche sono rilevanti per il singolo caso d'uso. I clienti dovrebbero consultare le parti interessate appropriate per determinare la misura di equità appropriata per la loro applicazione.
Utilizziamo la seguente notazione per discutere le metriche di distorsione. Il modello concettuale qui descritto riguarda la classificazione binaria, in cui gli eventi sono etichettati come aventi solo due esiti possibili nel loro spazio di esempio, indicati come positivo (con valore 1) e negativo (con valore 0). Questo framework è generalmente estensibile alla classificazione multicategoria in modo semplice o ai casi che comportano esiti con valori continui quando necessario. Nel caso della classificazione binaria, le etichette positive e negative vengono assegnate agli esiti registrati in un set di dati non elaborati per un facet favorito *a* e per un facet sfavorito *d*. Queste etichette y vengono chiamate *etichette osservate* per distinguerle dalle *etichette previste* y' che vengono assegnate da un modello di machine learning durante le fasi di addestramento o inferenza del ciclo di vita ML. Queste etichette vengono utilizzate per definire le distribuzioni di probabilità Pa(y) e Pd(y) per i rispettivi esiti facet.
+ etichette:
+ y rappresenta le n etichette osservate per gli esiti degli eventi in un set di dati di addestramento.
+ y' rappresenta le etichette previste per le n etichette osservate nel set di dati di un modello addestrato.
+ esiti:
+ Un esito positivo (con valore 1) per un esempio, come l'accettazione di un'applicazione.
+ n(1) è il numero di etichette osservate per gli esiti positivi (accettazioni).
+ n'(1) è il numero di etichette previste per gli esiti positivi (accettazioni).
+ Un esito negativo (con valore 0) per un esempio, come il rifiuto di un'applicazione.
+ n(0) è il numero di etichette osservate per gli esiti negativi (rifiuti).
+ n'(0) è il numero di etichette previste per gli esiti negativi (rifiuti).
+ valori dei facet:
+ facet *a*: il valore della caratteristica che definisce un gruppo demografico favorito dalla distorsione.
+ na è il numero di etichette osservate per il valore del facet favorito: na = na(1) \$1 na(0) è la somma delle etichette osservate positive e negative per il facet di valore *a*.
+ n'a è il numero di etichette previste per il valore del facet favorito: n'a = n'a(1) \$1 n'a(0) è la somma delle etichette previste positive e negative per il valore del facet *a*. Nota che n'a = na.
+ facet *d*: il valore della funzionalità che definisce un gruppo demografico sfavorito dalla distorsione.
+ nd è il numero di etichette osservate per il valore del facet sfavorito: nd = nd(1) \$1 nd(0) è la somma delle etichette osservate positive e negative per il valore del facet *d*.
+ n'd è il numero di etichette previste per il valore del facet sfavorito: n'd = n'd(1) \$1 n'd(0) è la somma delle etichette previste positive e negative per il valore del facet *d*. Nota che n'd = nd.
+ distribuzioni di probabilità per gli esiti degli esiti dei dati del facet con etichetta:
+ Pa(y) è la distribuzione di probabilità delle etichette osservate per il facet *a*. Per i dati con etichetta binari, questa distribuzione è data dal rapporto tra il numero di esempi nel facet *a* etichettato con esiti positivi e il numero totale, Pa(y1) = na(1)/na, e dal rapporto tra il numero di esempi con esiti negativi e il numero totale, Pa(y0) = na(0)/na.
+ Pd(y) è la distribuzione di probabilità delle etichette osservate per il facet *d*. Per i dati con etichetta binari, questa distribuzione è data dal numero di esempi nel facet *d* etichettato con esiti positivi rispetto al numero totale, Pd(y1) = nd(1)/nd, e dal rapporto tra il numero di esempi con esiti negativi e il numero totale, Pd(y0) = nd(0)/nd.
La tabella seguente contiene una guida con istruzioni rapide e collegamenti alle metriche di distorsione post-addestramento.
Metriche di distorsione post-addestramento
| Metrica di distorsione post-addestramento | Description | Domanda di esempio | Interpretazione dei valori delle metriche |
| --- | --- | --- | --- |
| [Differenza nelle proporzioni positive delle etichette previste (DPPL)](clarify-post-training-bias-metric-dppl.md) | Misura la differenza nella proporzione di previsioni positive tra il facet favorito a e il facet sfavorito d. | C'è stato uno squilibrio tra i gruppi demografici nei risultati positivi previsti che potrebbe indicare distorsioni? | Intervallo per etichette di facet binarie e multicategoria normalizzate: `[-1,+1]` Intervallo per etichette continue: (-∞, \$1∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Impatto diversificato (DI)](clarify-post-training-bias-metric-di.md) | Misura il rapporto tra le proporzioni delle etichette previste per il facet favorito a e il facet sfavorito d. | C'è stato uno squilibrio tra i gruppi demografici nei risultati positivi previsti che potrebbe indicare distorsioni? | Intervallo per etichette di facet binarie, multicategoria e continue: [0,∞) Interpretazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Disparità demografica condizionale nelle etichette previste (CDDPL)](clarify-post-training-bias-metric-cddpl.md) | Misura la disparità delle etichette previste tra i facet nel loro insieme, ma anche tra i sottogruppi. | Alcuni gruppi demografici registrano una proporzione maggiore di rifiuti come esiti dell’idoneità ai prestiti rispetto alla proporzione di accettazioni? | L’intervallo di valori CDDPL per esiti binari, multicategoria e continui: `[-1, +1]` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Fliptest controfattuale (FT)](clarify-post-training-bias-metric-ft.md) | Esamina ogni membro del facet d e valuta se membri simili del facet a hanno previsioni di modello diverse. | Un gruppo di una fascia demografica per età specifica corrisponde strettamente per tutte le caratteristiche a un gruppo di età diverso, ma in media è maggiormente retribuito? | L’intervallo per etichette di facet binarie e multicategoria è [-1, \$11]. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza di precisione (AD)](clarify-post-training-bias-metric-ad.md) | Misura la differenza tra l'accuratezza della previsione per i facet favoriti e sfavoriti. | Il modello prevede le etichette con la stessa precisione per le applicazioni in tutti i gruppi demografici? | L’intervallo per etichette di facet binarie e multicategoria è [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza di richiamo (RD)](clarify-post-training-bias-metric-rd.md) | Confronta il richiamo del modello per i facet favoriti e sfavoriti. | Esiste una tendenza all'erogazione di prestiti basata sull'età dovuta al fatto che un modello prevede una maggiore capacità di richiamo per una fascia di età rispetto a un'altra? | Intervallo per la classificazione binaria e multicategoria: `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza nell'accettazione condizionata () DCAcc](clarify-post-training-bias-metric-dcacc.md) | Confronta le etichette osservate con le etichette previste da un modello. Valuta se ciò si applica a tutti i facet per quanto riguarda i risultati positivi previsti (accettazioni). | Quando si confronta una fascia di età con un'altra, i prestiti sono accettati più frequentemente o meno spesso del previsto (in base alle qualifiche)? | Intervallo per etichette di facet binarie, multicategoria e continue: (-∞, \$1∞). [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza nelle percentuali di accettazione (DAR)](clarify-post-training-bias-metric-dar.md) | Misura la differenza nei rapporti tra i risultati positivi osservati (TP) e quelli positivi previsti (TP \$1 FP) tra facet favoriti e sfavoriti. | Il modello ha la stessa precisione nella previsione delle accettazioni di prestiti per i richiedenti qualificati in tutte le fasce d'età? | L’intervallo per etichette di facet binarie, multicategoria e continue è [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza di specificità (SD)](clarify-post-training-bias-metric-sd.md) | Confronta la specificità del modello tra facet favoriti e sfavoriti. | Esiste una distorsione basata sull'età nella concessione dei prestiti perché il modello prevede una specificità maggiore per un gruppo di età rispetto a un altro? | Intervallo per la classificazione binaria e multicategoria: `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza nel rifiuto condizionale (DCR)](clarify-post-training-bias-metric-dcr.md) | Confronta le etichette osservate con le etichette previste da un modello e valuta se questa è la stessa in tutti i facet per quanto riguarda gli esiti negativi (rifiuti). | Le richieste di prestito sono state respinte più o meno rispetto a quanto previsto per una fascia di età rispetto a un'altra in base alle qualifiche? | Intervallo per etichette di facet binarie, multicategoria e continue: (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Differenza nelle percentuali di rifiuto (DRR)](clarify-post-training-bias-metric-drr.md) | Misura la differenza nei rapporti tra gli esiti negativi osservati (TN) e quelli negativi previsti (TN \$1 FN) tra i facet sfavoriti e favoriti. | Il modello ha la stessa precisione nella previsione dei rifiuti di prestiti per i richiedenti non qualificati in tutte le fasce d'età? | L’intervallo per etichette di facet binarie, multicategoria e continue è [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Parità di trattamento (TE)](clarify-post-training-bias-metric-te.md) | Misura la differenza nel rapporto tra falsi positivi e falsi negativi tra i facet favoriti e sfavoriti. | Nelle richieste di prestito, il report relativo tra falsi positivi e falsi negativi è lo stesso in tutti i dati demografici di tutte le età? | Intervallo per etichette di facet binarie e multicategoria: (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Entropia generalizzata (GE)](clarify-post-training-bias-metric-ge.md) | Misura la disuguaglianza nei benefici b assegnati a ciascun input dalle previsioni del modello. | Dei due modelli candidati per la classificazione delle richieste di prestito, uno porta a una distribuzione più disomogenea dei risultati desiderati rispetto all'altro? | Intervallo per etichette di binarie e multicategoria: (0, 0.5). GE non è definito quando il modello prevede solo falsi negativi.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
Per ulteriori informazioni sulle metriche relative alle distorsioni post-addestramento, consulta [Gruppi di misure di equità per il machine learning nella finanza](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
**Topics**
+ [Differenza nelle proporzioni positive delle etichette previste (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ [Impatto diversificato (DI)](clarify-post-training-bias-metric-di.md)
+ [Differenza nell'accettazione condizionata () DCAcc](clarify-post-training-bias-metric-dcacc.md)
+ [Differenza nel rifiuto condizionale (DCR)](clarify-post-training-bias-metric-dcr.md)
+ [Differenza di specificità (SD)](clarify-post-training-bias-metric-sd.md)
+ [Differenza di richiamo (RD)](clarify-post-training-bias-metric-rd.md)
+ [Differenza nelle percentuali di accettazione (DAR)](clarify-post-training-bias-metric-dar.md)
+ [Differenza nelle percentuali di rifiuto (DRR)](clarify-post-training-bias-metric-drr.md)
+ [Differenza di precisione (AD)](clarify-post-training-bias-metric-ad.md)
+ [Parità di trattamento (TE)](clarify-post-training-bias-metric-te.md)
+ [Disparità demografica condizionale nelle etichette previste (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ [Fliptest controfattuale (FT)](clarify-post-training-bias-metric-ft.md)
+ [Entropia generalizzata (GE)](clarify-post-training-bias-metric-ge.md)
# Differenza nelle proporzioni positive delle etichette previste (DPPL)
La differenza nelle proporzioni positive nella metrica delle etichette previste (DPPL) determina se il modello prevede i risultati in modo diverso per ogni facet. È definita come la differenza tra la proporzione di previsioni positive (y' = 1) per il facet *a* e la proporzione di previsioni positive (y' = 1) per il facet *d*. Ad esempio, se le previsioni del modello concedono prestiti al 60% di un gruppo di mezza età (facet *a*) e al 50% ad altri gruppi di età (facet *d*), il modello potrebbe essere distorto rispetto al facet *d*. In questo esempio, è necessario determinare se la differenza del 10% è rilevante ai fini di un’eventuale distorsione.
Un confronto tra DPL (Differenza nelle proporzioni delle etichette), una misura dei bias di preaddestramento, e DPPL, una misura dei bias di post-addestramento, valuta se le proporzioni iniziali di esiti positivi dei bias nel set di dati cambiano dopo l’addestramento. Se DPPL è maggiore di DPL, i bias in proporzioni positive sono aumentati dopo l’addestramento. Se DPPL è minore di DPL, il modello non ha aumentato i bias in proporzioni positive dopo l’addestramento. Il confronto tra DPL e DPPL non garantisce che il modello riduca la bias in tutte le dimensioni. Ad esempio, il modello potrebbe avere ancora dei bias se si considerano altre metriche come [Fliptest controfattuale (FT)](clarify-post-training-bias-metric-ft.md) o [Differenza di precisione (AD)](clarify-post-training-bias-metric-ad.md). Per ulteriori informazioni sul rilevamento dei pregiudizi, consulta il post del blog [Scopri come Amazon SageMaker Clarify aiuta a rilevare](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/) i pregiudizi. Per ulteriori informazioni su DPL, consulta [Differenza nelle proporzioni delle etichette (DPL)](clarify-data-bias-metric-true-label-imbalance.md).
La formula per DPPL è la seguente:
DPPL = q'a - q'd
Dove:
+ q'a = n'a(1)/na è la proporzione prevista del facet *a* che ottiene un risultato positivo di valore 1. Nel nostro esempio, si tratta della percentuale di persone di mezza età che si prevede otterrà un prestito. Qui n'a(1) rappresenta il numero di membri del facet *a* che ottengono un risultato previsto positivo di valore 1 e na il numero di membri del facet *a*.
+ q'd = n'd(1)/nd è la proporzione prevista del facet *d* che ottiene un risultato positivo di valore 1. Nel nostro esempio, si prevede che un facet di persone anziane e giovani otterrà un prestito. Qui n'd(1) rappresenta il numero di membri del facet *d* che ottengono un risultato previsto positivo e nd il numero di membri del facet *d*.
Se DPPL è sufficientemente vicino a 0, significa che la *parità demografica* post-addestramento è stata raggiunta.
Per le etichette di facet binarie e multicategoria, i valori DPL normalizzati variano nell'intervallo [-1, 1]. Per le etichette continue, i valori variano nell'intervallo (-∞, \$1∞).
+ I valori DPPL positivi indicano che il facet *a* ha una percentuale maggiore di risultati positivi previsti rispetto al facet *d*.
Questo fenomeno viene definito *distorsione positiva*.
+ I valori di DPPL vicini allo zero indicano una proporzione più equa di risultati positivi previsti tra i facet *a* e *d*, mentre un valore pari a zero indica una perfetta parità demografica.
+ I valori DPPL negativi indicano che il facet *d* ha una percentuale maggiore di risultati positivi previsti rispetto al facet *a*. Questo fenomeno viene definito *distorsione negativa*.
# Impatto diversificato (DI)
La differenza nelle proporzioni positive nella metrica prevista delle etichette può essere valutata sotto forma di report.
Il confronto delle proporzioni positive nella metrica prevista delle etichette può essere valutato sotto forma di report anziché come differenza, come avviene con [Differenza nelle proporzioni positive delle etichette previste (DPPL)](clarify-post-training-bias-metric-dppl.md). La metrica di impatto diversificato (DI) è definita come il rapporto tra la proporzione di previsioni positive (y' = 1) per il facet *d* e la proporzione di previsioni positive (y' = 1) per il facet *a*. Ad esempio, se le previsioni del modello concedono prestiti al 60% di un gruppo di mezza età (facet *a*) e al 50% di altri gruppi di età (facet *d*), allora DI = 0,5/0,6 = 0,8, il che indica una distorsione positiva e un impatto negativo sull'altra fascia di età rappresentata dal facet *d*.
La formula per il rapporto tra le proporzioni delle etichette previste è la seguente:
DI = q'd/q'a
Dove:
+ q'a = n'a(1)/na è la proporzione prevista del facet *a* che ottiene un risultato positivo di valore 1. Nel nostro esempio, si tratta della percentuale di persone di mezza età che si prevede otterrà un prestito. Qui n'a(1) rappresenta il numero di membri del facet *a* che ottengono un risultato previsto positivo e na è il numero di membri del facet *a*.
+ q'd = n'd(1)/nd è la proporzione prevista del facet *d* che ottiene un risultato positivo di valore 1. Nel nostro esempio, si prevede che un facet di persone anziane e giovani otterrà un prestito. Qui n'd(1) rappresenta il numero di membri del facet *d* che ottengono un risultato previsto positivo e nd il numero di membri del facet *d*.
Per le etichette di facet binarie, multicategoria e continue, i valori DI variano nell'intervallo [0, ∞).
+ I valori inferiori a 1 indicano che il facet *a* ha una percentuale maggiore di risultati positivi previsti rispetto al facet *d*. Questo fenomeno viene definito *distorsione positiva*.
+ Un valore pari a 1 indica una parità demografica.
+ I valori maggiori di 1 indicano che il facet *d* ha una percentuale maggiore di risultati positivi previsti rispetto al facet *a*. Questo fenomeno viene definito *distorsione negativa*.
# Differenza nell'accettazione condizionata () DCAcc
Questa metrica confronta le etichette osservate con le etichette previste da un modello e valuta se questa è la stessa in tutti i facet per quanto riguarda gli esiti positivi previsti. Questa metrica si avvicina a imitare distorsione umane poiché quantifica quanti risultati positivi in più ha previsto un modello (etichette y') per un determinato facet rispetto a quanto osservato nel set di dati di addestramento (etichette y). Ad esempio, se nel set di dati di addestramento per le domande di prestito per un gruppo di mezza età (facet *a*) si osservassero più accettazioni (un risultato positivo) rispetto a quanto previsto dal modello basato sulle qualifiche rispetto al facet contenente altre fasce di età (facet *d*), ciò potrebbe indicare una potenziale distorsione nel modo in cui i prestiti sono stati approvati a favore del gruppo di mezza età.
La formula per la differenza nell'accettazione condizionale è la seguente:
DCAcc a= c - c d
Dove:
+ ca = na(1)/ n'a(1) è il rapporto tra il numero osservato di esiti positivi del valore 1 (accettazioni) del facet *a* e il numero previsto di risultati positivi (accettazioni) per il facet *a*.
+ cd = nd(1)/ n'd(1) è il rapporto tra il numero osservato di esiti positivi del valore 1 (accettazioni) del facet *d* e il numero previsto di esiti positivi previsti (accettazioni) per il facet *d*.
La DCAcc metrica può rilevare pregiudizi sia positivi che negativi che rivelano un trattamento preferenziale basato sulle qualifiche. Considera i seguenti esempi di distorsioni basati sull'età nell'accettazione dei prestiti.
**Esempio 1: distorsione positiva**
Supponiamo di avere un set di dati composto da 100 persone di mezza età (facet *a*) e 50 persone di altre fasce d'età (facet *d*) che hanno richiesto prestiti, laddove il modello consigliasse di concedere prestiti a 60 persone del facet *a* e 30 per il facet *d*. Le proporzioni previste sono quindi imparziali rispetto alla metrica DPPL, ma le etichette osservate mostrano che a 70 elementi del facet *a* e a 20 del facet *d* sono stati concessi prestiti. In altre parole, il modello ha concesso prestiti al 17% in meno per le persone di mezza età rispetto alle etichette osservate nei dati di addestramento suggeriti (70/60 = 1,17) e ha concesso prestiti per il 33% in più ad altre fasce di età rispetto alle etichette osservate (20/30 = 0,67). Il calcolo del DCAcc valore dà quanto segue:
DCAcc = 70/60 - 20/30 = 1/2
Il valore positivo indica che esiste una potenziale distorsione nei confronti del facet *a* di mezza età con un tasso di accettazione inferiore rispetto all'altro facet *d* rispetto a quanto indicato dai dati osservati (considerati imparziali).
**Esempio 2: distorsione negativa**
Supponiamo di avere un set di dati composto da 100 persone di mezza età (facet *a*) e 50 persone di altre fasce d'età (facet *d*) che hanno richiesto prestiti, laddove il modello consigliasse di concedere prestiti a 60 persone del facet *a* e 30 per il facet *d*. Le proporzioni previste sono quindi imparziali rispetto alla metrica DPPL, ma le etichette osservate mostrano che a 50 elementi del facet *a* e a 40 del facet *d* sono stati concessi prestiti. In altre parole, il modello ha concesso prestiti al 17% in meno per le persone di mezza età rispetto alle etichette osservate nei dati di addestramento suggeriti (50/60 = 0,83) e ha concesso prestiti per il 33% in più ad altre fasce di età rispetto alle etichette osservate (40/30 = 1,33). Il calcolo del DCAcc valore dà quanto segue:
DCAcc = 50/60 - 40/30 = -1/2
Il valore negativo indica che esiste una potenziale distorsione nei confronti del facet *d* con un tasso di accettazione inferiore rispetto al facet *a* di mezza età rispetto a quanto indicato dai dati osservati (considerati imparziali).
Tieni presente che puoi utilizzarlo DCAcc per aiutarti a rilevare potenziali pregiudizi (non intenzionali) da parte di esseri umani che supervisionano le previsioni del modello in un ambiente. human-in-the-loop Supponiamo, ad esempio, che le previsioni y' fornite dal modello fossero imparziali, ma che la decisione finale venga presa da un essere umano (possibilmente con accesso a funzionalità aggiuntive) che può modificare le previsioni del modello per generare una nuova e definitiva versione di y'. L'ulteriore elaborazione da parte dell'essere umano può negare involontariamente prestiti a un numero sproporzionato da un punto di vista. DCAccpuò aiutare a rilevare tali potenziali pregiudizi.
L'intervallo di valori per le differenze nell'accettazione condizionata per le etichette del facet binarie, multicategoria e continue è (-∞, \$1∞).
+ I valori positivi si verificano quando il rapporto tra il numero di accettazioni osservato e le accettazioni previste per il facet *a* è superiore allo stesso rapporto per il facet *d*. Questi valori indicano una possibile distorsione nei confronti dei richiedenti qualificati a causa del facet *a*. Maggiore è la differenza tra i rapporti, più estrema è la distorsione apparente.
+ I valori prossimi allo zero si verificano quando il rapporto tra il numero di accettazioni osservato e le accettazioni previste per il facet *a* è simile al rapporto per il facet *d*. Questi valori indicano che i tassi di accettazione previsti sono coerenti con i valori osservati nei dati etichettati e che i richiedenti qualificati di entrambi i facet vengono accettati in modo analogo.
+ I valori negativi si verificano quando il rapporto tra il numero di accettazioni osservato e le accettazioni previste per il facet *a* è inferiore al rapporto per il facet *d*. Questi valori indicano una possibile distorsione nei confronti dei richiedenti qualificati derivante dal facet *d*. Quanto più negativa è la differenza tra i rapporti, più estrema è la distorsione apparente.
# Differenza nel rifiuto condizionale (DCR)
Questa metrica confronta le etichette osservate con le etichette previste dal modello e valuta se questa è la stessa per tutti i facet relativi agli esiti negativi (rifiuti). Questa metrica assomiglia molto alle distorsione umane, poiché quantifica quanti risultati negativi in più un modello ha concesso (etichette previste y') a un determinato facet rispetto a quanto suggerito dalle etichette nel set di dati di addestramento (etichette osservate y). Ad esempio, se per le richieste di prestito per un gruppo di mezza età (facet *a*) sono stati registrati più rifiuti (risultato negativo) rispetto a quanto previsto dal modello basato sulle qualifiche rispetto al facet contenente altre fasce di età (facet *d*), ciò potrebbe indicare una potenziale distorsione nel modo in cui i prestiti sono stati respinti, il che ha favorito il gruppo di mezza età rispetto ad altri gruppi.
La formula per la differenza nell'accettazione condizionale è la seguente:
DCR = rd - ra
Dove:
+ rd = nd(0)/ n'd(0) è il rapporto tra il numero osservato di esiti negativi di valore 0 (rifiuti) del facet *d* e il numero previsto di risultati negativi (rifiuti) per il facet *d*.
+ ra = na(0)/ n'a(0) è il rapporto tra il numero osservato di esiti negativi di valore 0 (rifiuti) del facet *a* e il numero previsto di risultati negativi di valore 0 (rifiuti) per il facet *a*.
La metrica DCR può rilevare distorsioni sia positive sia negative che rivelano un trattamento preferenziale basato sulle qualifiche. Considera i seguenti casi di distorsioni basati sull'età in merito al rifiuto dei prestiti.
**Esempio 1: distorsione positiva**
Supponiamo di avere un set di dati composto da 100 persone di mezza età (facet *a*) e 50 persone di altre fasce d'età (facet *d*) che hanno richiesto prestiti, laddove il modello consigliasse di rifiutare prestiti a 60 persone del facet *a* e 30 per il facet *d*. Le proporzioni previste sono quindi imparziali rispetto alla metrica DPPL, ma le etichette osservate mostrano che a 50 elementi del facet *a* e a 40 del facet *d* sono stati rifiutati prestiti. In altre parole, il modello ha rifiutato prestiti al 17% in più per le persone di mezza età rispetto alle etichette osservate nei dati di addestramento suggeriti (50/60 = 0,83) e ha rifiutato prestiti per il 33% in meno ad altre fasce di età rispetto alle etichette osservate (40/30 = 1,33). Il valore DCR quantifica questa differenza nel rapporto tra i tassi di rifiuto osservati e quelli previsti tra i facet. Il valore positivo indica che esiste una potenziale distorsione a favore del gruppo di mezza età con tassi di rifiuto inferiori rispetto ad altri gruppi rispetto a quanto indicato dai dati osservati (considerati imparziali).
DCR = 40/30 - 50/60 = 1/2
**Esempio 2: distorsione negativa**
Supponiamo di avere un set di dati composto da 100 persone di mezza età (facet *a*) e 50 persone di altre fasce d'età (facet *d*) che hanno richiesto prestiti, laddove il modello consigliasse di rifiutare prestiti a 60 persone del facet *a* e 30 per il facet *d*. Le proporzioni previste sono quindi imparziali rispetto alla metrica DPPL, ma le etichette osservate mostrano che a 70 elementi del facet *a* e a 20 del facet *d* sono stati rifiutati prestiti. In altre parole, il modello ha rifiutato prestiti al 17% in meno per le persone di mezza età rispetto alle etichette osservate nei dati di addestramento suggeriti (70/60 = 1,17) e ha rifiutato prestiti per il 33% in più ad altre fasce di età rispetto alle etichette osservate (20/30 = 0,67). Il valore negativo indica che esiste una potenziale distorsione a favore del facet *a* con tassi di rifiuto inferiori rispetto al facet *a* di mezza età rispetto a quella indicata dai dati osservati (considerati imparziali).
DCR = 20/30 - 70/60 = -1/2
L'intervallo di valori per le differenze nel rifiuto condizionato per le etichette del facet binarie, multicategoria e continue è (-∞, \$1∞).
+ I valori positivi si verificano quando il rapporto tra il numero di rifiuti osservato e i rifiuti previsti per il facet *d* è maggiore del rapporto per il facet *a*. Questi valori indicano una possibile distorsione nei confronti dei richiedenti qualificati a causa del facet *a*. Maggiore è il valore della metrica DCR, più estrema è la distorsione apparente.
+ I valori prossimi allo zero si verificano quando il rapporto tra il numero di rifiuti osservato e le accettazioni previste per il facet *a* è simile al rapporto per il facet *d*. Questi valori indicano che i tassi di rifiuto previsti sono coerenti con i valori osservati nei dati etichettati e che i richiedenti qualificati di entrambi i facet vengono rifiutati in modo analogo.
+ I valori negativi si verificano quando il rapporto tra il numero di rifiuti osservato e i rifiuti previsti per il facet *d* è inferiore a tale rapporto per il facet *a*. Questi valori indicano una possibile distorsione nei confronti dei richiedenti qualificati derivante dal facet *d*. Maggiore è la grandezza della metrica DCR negativa, più estrema è la distorsione apparente.
# Differenza di specificità (SD)
La differenza di specificità (SD) è la differenza di specificità tra il facet favorito *a* e il facet sfavorito *d*. La specificità misura la frequenza con cui il modello prevede correttamente un risultato negativo (y'=0). Qualsiasi differenza in queste specificità è una potenziale forma di distorsione.
La specificità è perfetta per un facet se tutti i casi y=0 sono previsti correttamente per tale facet. La specificità è maggiore quando il modello riduce al minimo i falsi positivi, un fenomeno noto come errore di tipo I. Ad esempio, la differenza tra una bassa specificità per i prestiti al facet *a*, e un’elevata specificità per la concessione di prestiti al faccet *d* è una misura della distorsione rispetto al facet *d*.
La formula seguente indica la differenza di specificità per i facet *a* e *d*.
SD = TNd/(TNd \$1 FPd) - TNa/(TNa \$1 FPa) = TNRd - TNRa
Le seguenti variabili utilizzate per calcolare la SD sono definite come segue:
+ TNd sono i veri negativi previsti per il facet *d*.
+ FPd sono i falsi positivi previsti per il facet *d*.
+ TNd sono i veri negativi previsti per il facet *a*.
+ FPd sono i falsi positivi previsti per il facet *a*.
+ TNRa = TNa/(TNa \$1 FPa) è il tasso di veri negativi, noto anche come specificità, per il facet *a*.
+ TNRd = TNd/(TNd \$1 FPd) è il tasso di veri negativi, noto anche come specificità, per il facet *d*.
Ad esempio, considera le seguenti matrici di confusione per i facet *a* e *d*.
Matrice di confusione per il facet favorito `a`
| Previsioni di classe a | Obiettivo effettivo 0 | Obiettivo effettivo 1 | Totale |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Totale | 30 | 70 | 100 |
Matrice di confusione per il facet sfavorito `d`
| Previsioni di classe d | Obiettivo effettivo 0 | Obiettivo effettivo 1 | Totale |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Totale | 23 | 27 | 50 |
Il valore della differenza di specificità è `SD = 18/(18+5) - 20/(20+10) = 0.7826 - 0.6667 = 0.1159`, il che indica una distorsione rispetto al facet *d*.
L'intervallo di valori per la differenza di specificità tra i facet *a* e *d* per la classificazione binaria e multicategoria è `[-1, +1]`. Questo parametro non è disponibile per le etichette continue. Ecco cosa implicano i diversi valori di SD:
+ I valori positivi si ottengono quando esiste una specificità maggiore per il facet *d* rispetto al facet *a*. Ciò suggerisce che il modello trova meno falsi positivi per il facet *d* rispetto al facet *a*. Un valore positivo indica una distorsione rispetto al facet *d*.
+ I valori vicini allo zero indicano che la specificità dei facet confrontati è simile. Ciò suggerisce che il modello rileva un numero simile di falsi positivi in entrambi questi facet e non è parziale.
+ I valori negativi si ottengono quando esiste una specificità maggiore per il facet *a* rispetto al facet *d*. Ciò suggerisce che il modello trova più falsi positivi per il facet *a* che per il facet *d*. Un valore negativo indica una distorsione rispetto al facet *a*.
# Differenza di richiamo (RD)
La metrica della differenza di richiamo (RD) è la differenza di richiamo del modello tra il facet favorito *a* e il facet sfavorito *d*. Qualsiasi differenza in questi richiami è una potenziale forma di distorsione. Il richiamo è il tasso di veri positivi (TPR), che misura la frequenza con cui il modello prevede correttamente i casi che dovrebbero avere un esito positivo. Il richiamo è perfetto per un facet se tutti i casi y=1 sono previsti correttamente come y'=1 per quel facet. Il richiamo è maggiore quando il modello minimizza i falsi negativi, noti come errore di tipo II. Ad esempio, quante persone appartenenti a due gruppi diversi (facet *a* e *d*) che dovrebbero avere diritto ai prestiti vengono individuate correttamente dal modello? Se il tasso di richiamo è elevato per i prestiti al facet *a*, ma basso per i prestiti al facet *d*, la differenza fornisce una misura di questa distorsione rispetto al gruppo appartenente al facet *d*.
La formula per la differenza nei tassi di richiamo per i facet *a* e *d* è la seguente:
RD = TPa/(TPa \$1 FNa) - TPd/(TPd \$1 FNd) = TPRa - TPRd
Dove:
+ TPa sono i veri positivi previsti per il facet *a*.
+ FNa sono i falsi negativi previsti per il facet *a*.
+ TPd sono i veri positivi previsti per il facet *d*.
+ FNd sono i falsi negativi previsti per il facet *d*.
+ TPRa = TPa/(TPa \$1 FNa) è il richiamo per il facet *a*, ovvero il suo tasso di veri positivi.
+ TPRd TPd/(TPd \$1 FNd) è il richiamo per il facet *d*, ovvero il suo tasso di veri positivi.
Ad esempio, considera le seguenti matrici di confusione per i facet *a* e *d*.
Matrice di confusione per il facet favorito a
| Previsioni di classe a | Obiettivo effettivo 0 | Obiettivo effettivo 1 | Totale |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Totale | 30 | 70 | 100 |
Matrice di confusione per il facet sfavorito d
| Previsioni di classe d | Obiettivo effettivo 0 | Obiettivo effettivo 1 | Totale |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Totale | 23 | 27 | 50 |
Il valore della differenza di richiamo è RD = 65/70 - 20/27 = 0,93 - 0,74 = 0,19, il che indica una distorsione rispetto al facet *d*.
L'intervallo di valori per la differenza di richiamo tra i facet *a* e *d* per la classificazione binaria e multicategoria è [-1, \$11]. Questo parametro non è disponibile per le etichette continue.
+ I valori positivi si ottengono quando il richiamo per il facet *a* è maggiore rispetto al facet *d*. Ciò suggerisce che il modello rileva più facet positivi per il facet *a* che per il facet *d*, che è una forma di distorsione.
+ I valori vicini allo zero indicano che il richiamo per i facet confrontati è simile. Ciò suggerisce che il modello rileva circa lo stesso numero di veri positivi in entrambi i facet e non è parziale.
+ I valori negativi si ottengono quando il richiamo per il facet *d* è maggiore rispetto al facet *a*. Ciò suggerisce che il modello rileva più facet positivi per il facet *d* che per il facet *a*, che è una forma di distorsione.
# Differenza nelle percentuali di accettazione (DAR)
La metrica della differenza nei tassi di accettazione (DAR) è la differenza nei rapporti tra le previsioni vere positive (TP) e quelle positive osservate (TP \$1 FP) per i facet *a* e *d*. Questa metrica misura la differenza nella precisione del modello per prevedere le accettazioni relative a questi due facet. La precisione misura la frazione di candidati qualificati dal pool di candidati qualificati identificati come tali dal modello. Se la precisione del modello per la previsione dei candidati qualificati diverge tra i facet, si tratta di una distorsione e la sua entità viene misurata dal DAR.
La formula per la differenza nei tassi di accettazione tra i facet *a* e *d* è la seguente:
DAR = TPa/(TPa \$1 FPa) - TPd/(TPd \$1 FPd)
Dove:
+ TPa sono i veri positivi previsti per il facet *a*.
+ FPa sono i falsi positivi previsti per il facet *a*.
+ TPd sono i veri positivi previsti per il facet *d*.
+ FPd sono i falsi positivi previsti per il facet *d*.
Ad esempio, supponiamo che il modello accetti 70 richiedenti di mezza età (facet *a*) per prestiti (etichette positive previste) di cui solo 35 siano effettivamente accettati (etichette positive osservate). Supponiamo inoltre che il modello accetti 100 richiedenti provenienti da altre fasce demografiche (facet *d*) per prestiti (etichette positive previste) di cui solo 40 siano effettivamente accettati (etichette positive osservate). Quindi, DAR = 35/70 - 40/100 = 0,10, il che indica una potenziale distorsione nei confronti delle persone qualificate della seconda fascia di età (facet *d*).
L’intervallo di valori per DAR per etichette di facet binarie, multicategoria e continue è [-1, \$11].
+ I valori positivi si verificano quando il rapporto tra i facet positivi previsti (accettazioni) e i risultati positivi osservati (richiedenti qualificati) per il facet *a* è maggiore dello stesso rapporto per il facet *d*. Questi valori indicano una possibile distorsione rispetto al facet sfavorito *d* causata dalla presenza di un numero relativamente maggiore di falsi positivi nel facet *d*. Maggiore è la differenza tra i rapporti, più estrema è la distorsione apparente.
+ I valori prossimi allo zero si verificano quando il rapporto tra i risultati positivi previsti (accettazioni) e i risultati positivi osservati (richiedenti qualificati) per i facet *a* e *d* presenta valori simili che indicano che le etichette osservate per i risultati positivi vengono previste con uguale precisione dal modello.
+ I valori negativi si verificano quando il rapporto tra i facet positivi previsti (accettazioni) e i risultati positivi osservati (richiedenti qualificati) per il facet *d* è maggiore del rapporto del facet *a*. Questi valori indicano una possibile distorsione nei confronti del facet favorito *a* causata dalla presenza di un numero relativamente maggiore di falsi positivi nel facet *a*. Quanto più negativa è la differenza tra i rapporti, più estrema è la distorsione apparente.
# Differenza nelle percentuali di rifiuto (DRR)
La metrica della differenza nei tassi di rifiuto (DRR) è la differenza nei rapporti tra le previsioni vere negative (TN) e quelle negative osservate (TN \$1 FN) per i facet *a* e *d*. Questa metrica misura la differenza nella precisione del modello per la previsione dei rifiuti in base a questi due facet. La precisione misura la frazione di candidati non qualificati dal pool di candidati non qualificati identificati come tali dal modello. Se la precisione del modello per prevedere i candidati non qualificati diverge tra i facet, si tratta di un errore e la sua entità viene misurata dal DRR.
La formula per la differenza nei tassi di rifiuto tra i facet *a* e *d* è la seguente:
DRR = TNd/(TNd \$1 FNd) - TNa/(TNa \$1 FNa)
I componenti della precedente equazione DRR sono i seguenti.
+ TNd sono i veri negativi previsti per il facet *d*.
+ FNd sono i falsi negativi previsti per il facet *d*.
+ TNa sono i veri negativi previsti per il facet *a*.
+ FNa sono i falsi negativi previsti per il facet *a*.
Ad esempio, supponiamo che il modello respinga 100 richiedenti (facet *a*) di mezza età per un prestito (etichetta negativa prevista) di cui 80 non sono effettivamente qualificati (etichette negative osservate). Supponiamo inoltre che il modello respinga 50 richiedenti di altra età (facet *d*) per un prestito (etichetta negativa prevista) di cui solo 40 sono effettivamente non qualificati (etichette negative osservate). Quindi, DRR = 40/50 - 80/100 = 0, e non viene indicata alcuna distorsione.
L’intervallo di valori per DRR per etichette di facet binarie, multicategoria e continue è [-1, \$11].
+ I valori positivi si verificano quando il rapporto tra i facet negativi previsti (rifiuti) e gli esiti negativi osservati (richiedenti non qualificati) per il facet *d* è maggiore dello stesso rapporto per il facet *a*. Questi valori indicano una possibile distorsione nei confronti del facet favorito *a* causata dalla presenza di un numero relativamente maggiore di falsi negativi nel facet *a*. Maggiore è la differenza tra i rapporti, più estrema è la distorsione apparente.
+ I valori prossimi allo zero si verificano quando il rapporto tra i facet negativi previsti (rifiuti) e gli esiti negativi osservati (richiedenti non qualificati) per i facet *a* e *d* ha valori simili, il che indica che le etichette osservate per gli esiti negativi vengono previste con uguale precisione dal modello.
+ I valori negativi si verificano quando il rapporto tra i facet negativi previsti (rifiuti) e gli esiti negativi osservati (richiedenti non qualificati) per il facet *a* è maggiore del rapporto del facet *d*. Questi valori indicano una possibile distorsione rispetto al facet sfavorito *d* causata dalla presenza di un numero relativamente maggiore di falsi positivi nel facet *d*. Quanto più negativa è la differenza tra i rapporti, più estrema è la distorsione apparente.
# Differenza di precisione (AD)
La metrica della differenza di precisione (AD) è la differenza tra l'accuratezza della previsione per diversi facet. Questa metrica determina se la classificazione in base al modello è più accurata per un facet rispetto all'altro. AD indica se un facet presenta una percentuale maggiore di errori di tipo I e di tipo II. Tuttavia, non è in grado di distinguere tra errori di tipo I e di tipo II. Ad esempio, il modello può avere la stessa precisione per i diversi dati demografici relativi all'età, ma gli errori possono essere principalmente falsi positivi (errori di tipo I) per un gruppo basato sull'età e principalmente falsi negativi (errori di tipo II) per l'altro.
Inoltre, se l'approvazione dei prestiti viene effettuata con una precisione molto maggiore per un gruppo demografico di mezza età (facet *a*) rispetto a un altro gruppo demografico basato sull'età (facet *d*), a una percentuale maggiore di richiedenti qualificati del secondo gruppo viene negato un prestito (FN) o a una percentuale maggiore di richiedenti non qualificati di quel gruppo viene negato un prestito (FP) o entrambi. Ciò può portare a iniquità all'interno del gruppo per il secondo gruppo, anche se la percentuale di prestiti concessi è quasi la stessa per entrambi i gruppi in base all'età, come indicato da un valore DPPL vicino allo zero.
La formula per la metrica AD è la differenza tra la precisione di previsione per il facet *a*, ACCa, meno quella per il facet *d*, ACCd:
AD = ACCa - ACCd
Dove:
+ ACCa = (TPa \$1 TNa)/(TPa \$1 TNa \$1 FPa \$1 FNa)
+ TPa sono i veri positivi previsti per il facet *a*
+ TNa sono i veri negativi previsti per il facet *a*
+ FPa sono i falsi positivi previsti per il facet *a*
+ FNa sono i falsi negativi previsti per il facet *a*
+ ACCd = (TPd \$1 TNd)/(TPd \$1 TNd \$1 FPd \$1 FNd)
+ TPd sono i veri positivi previsti per il facet *d*
+ TNd sono i veri negativi previsti per il facet *d*
+ FPd sono i falsi positivi previsti per il facet *d*
+ FNd sono i falsi negativi previsti per il facet *d*
Ad esempio, supponiamo che un modello approvi i prestiti a 70 richiedenti dal facet *a* di 100 e respinga gli altri 30. 10 non avrebbero dovuto ricevere il prestito (FPa) e 60 sono stati approvati (TPa). 20 dei rifiuti avrebbero dovuto essere approvati (FNa) e 10 sono stati correttamente respinti (TNa). La precisione per il facet *a* è la seguente:
ACCa = (60 \$1 10)/(60 \$1 10 \$1 20 \$1 10) = 0,7
Quindi, supponiamo che un modello approvi i prestiti a 50 richiedenti dal facet *d* di 100 e respinga gli altri 50. 10 non avrebbero dovuto ricevere il prestito (FPa) e 40 sono stati approvati (TPa). 40 dei rifiuti avrebbero dovuto essere approvati (FNa) e 10 sono stati correttamente respinti (TNa). La precisione per il facet *a* è determinata come segue:
ACCd = (40 \$1 10)/(40 \$1 10 \$1 40 \$1 10) = 0,5
La differenza di precisione è quindi AD = ACCa - ACCd = 0,7 - 0,5 = 0,2. Ciò indica che esiste una distorsione rispetto al facet *d* poiché la metrica è positiva.
L’intervallo di valori per AD per etichette di facet binarie e multicategoria è [-1, \$11].
+ I valori positivi si verificano quando la precisione di previsione per il facet *a* è maggiore di quella per il facet *d*. Indicano che il facet *d* risente maggiormente di una combinazione di falsi positivi (errori di tipo I) o falsi negativi (errori di tipo II). Ciò significa che esiste una potenziale distorsione nei confronti del facet sfavorito *d*.
+ I valori prossimi allo zero si verificano quando la precisione di previsione per il facet *a* è simile a quella per il facet *d*.
+ I valori negativi si verificano quando la precisione di previsione per il facet *d* è maggiore di quella per il facet *a* t. Indicano che il facet *a* risente maggiormente di una combinazione di falsi positivi (errori di tipo I) o falsi negativi (errori di tipo II). Ciò significa che esiste una distorsione nei confronti del facet favorito *a*.
# Parità di trattamento (TE)
La parità di trattamento (TE) è la differenza nel rapporto tra falsi negativi e falsi positivi tra i facet *a* e *d*. L'idea principale di questa metrica è valutare se, anche se la precisione tra i gruppi è la stessa, gli errori sono più dannosi per un gruppo rispetto a un altro. Il tasso di errore deriva dal totale dei falsi positivi e dei falsi negativi, ma la ripartizione di questi due facet può essere molto diversa. TE misura se gli errori compensano in modo simile o diverso tra i vari facet.
La formula per la parità di trattamento è la seguente:
TE = FNd/FPd - FNa/FPa
Dove:
+ FNd sono i falsi negativi previsti per il facet *d*.
+ FPd sono i falsi positivi previsti per il facet *d*.
+ FNa sono i falsi negativi previsti per il facet *a*.
+ FPa sono i falsi positivi previsti per il facet *a*.
Nota che la metrica diventa illimitata se FPa o FPd sono pari a zero.
Ad esempio, supponiamo che vi siano 100 richiedenti di prestito per il facet *a* e 50 per il facet *d*. Per il facet *a*, a 8 elementi è stato erroneamente negato un prestito (FNa) e ad altri 6 è stato erroneamente approvato (FPa). Le previsioni rimanenti erano vere, quindi TPa \$1 TNa = 86. Per il facet *d*, 5 sono stati erroneamente negati (FNd) e 2 sono stati erroneamente approvati (FPd). Le previsioni rimanenti erano vere, quindi TPd \$1 TNd = 43. Il rapporto tra falsi negativi e falsi positivi è uguale a 8/6 = 1,33 per il facet *a* e 5/2 = 2,5 per il facet *d*. Quindi, TE = 2,5 - 1,33 = 1,167, anche se entrambi i facet hanno la stessa precisione:
ACCa = (86)/(86\$1 8 \$1 6) = 0,86
ACCd = (43)/(43 \$1 5 \$1 2) = 0,86
L'intervallo di valori per le differenze nel rifiuto condizionato per le etichette del facet binarie e multicategoria è (-∞, \$1∞). La metrica TE non è definita per le etichette continue. L'interpretazione di questa metrica dipende dall'importanza relativa dei falsi positivi (errore di tipo I) e dei falsi negativi (errore di tipo II).
+ I valori positivi si verificano quando il rapporto tra falsi negativi e falsi positivi per il facet *d* è maggiore di quello per il facet *a*.
+ I valori prossimi allo zero si verificano quando il rapporto tra falsi negativi e falsi positivi per il facet *a* è simile a quello per il facet *d*.
+ I valori negativi si verificano quando il rapporto tra falsi negativi e falsi positivi per il facet *d* è inferiore a quello per il facet *a*.
**Nota**
Una versione precedente affermava che la metrica di parità del trattamento veniva calcolata come FPa / FNa - FPd / FNd anziché FNd / FPd - FNa / FPa. Comunque sia, è possibile utilizzare una delle due versioni. Per ulteriori informazioni, consulta [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à demografica condizionale nelle etichette previste (CDDPL)
La metrica della disparità demografica (DDPL) determina se il facet *d* ha una percentuale maggiore delle etichette rifiutate previste rispetto alle etichette accettate previste. Consente di confrontare la differenza tra la percentuale di rifiuto prevista e la percentuale di accettazione prevista tra i diversi facet. Questa metrica è esattamente la stessa della metrica CDD pre-addestramento, tranne per il fatto che viene calcolata in base alle etichette previste anziché a quelle osservate. Questa metrica è compresa nell'intervallo (-1,\$11).
La formula per le previsioni della disparità demografica per le etichette del facet *d* è la seguente:
DDPLd = n'd(0)/n'(0) - n'd(1)/n'(1) = PdR(y'0) - PdA(y'1)
Dove:
+ n'(0) = n'a(0) \$1 n'd(0) è il numero di etichette rifiutate previste per i facet *a* e *d*.
+ n'(1) = n'a(1) \$1 n'd(1) è il numero di etichette accettate previste per i facet *a* e *d*.
+ PdR(y'0) è la proporzione di etichette rifiutate previste (valore 0) nel facet *d*.
+ PdA(y'1) è la proporzione di etichette accettate previste (valore 1) nel facet *d*.
Per escludere il paradosso di Simpson è necessaria una metrica di disparità demografica condizionale nelle etichette previste (CDDPL) che condiziona DDPL sugli attributi che definiscono uno strato di sottogruppi nel set di dati. Il raggruppamento può fornire informazioni sulla causa delle apparenti disparità demografiche relative ai facet meno favoriti. Il caso classico è sorto nelle ammissioni a Berkeley, in cui gli uomini sono stati accettati a un tasso complessivo più elevato rispetto alle donne. Tuttavia, quando sono stati esaminati i sottogruppi dipartimentali, è stato dimostrato che le donne hanno tassi di ammissione più elevati rispetto agli uomini dal reparto. La spiegazione è data dal fatto che le donne si erano rivolte a reparti con tassi di accettazione inferiori rispetto agli uomini. L'esame dei tassi di accettazione suddivisi per sottogruppo ha rivelato che le donne erano effettivamente accettate a un tasso più elevato rispetto agli uomini nei dipartimenti con tassi di accettazione inferiori.
La metrica CDDPL fornisce un'unica misura per tutte le disparità riscontrate nei sottogruppi definiti da un attributo di un set di dati calcolandone la media. È definita come la media ponderata delle disparità demografiche nelle etichette previste (DDPLi) per ciascuno dei sottogruppi, con ogni disparità di sottogruppo ponderata in proporzione al numero di osservazioni contenute. La formula per la disparità demografica condizionata nelle etichette previste è la seguente:
CDDPL = (1/n)\$1∑ini \$1DDPLi
Dove:
+ ∑ini = è il numero totale di osservazioni e ni è il numero di osservazioni per ciascun sottogruppo.
+ DDPLi = n'i(0)/n(0) - n'i(1)/n(1) = PiR(y'0) - PiA(y'1) è la disparità demografica nelle etichette previste per sottogruppo.
La disparità demografica per un sottogruppo nelle etichette previste (DDPLi) è la differenza tra la percentuale di etichette previste rifiutate e la percentuale di etichette accettate previste per ciascun sottogruppo.
L'intervallo di valori DDPL per esiti binari, multicategoria e continui è [-1,\$11].
+ \$11: quando non esistono etichette di rifiuto previste per il facet *a* o il sottogruppo e non sono previste accettazioni per il facet *d* o il sottogruppo.
+ I valori positivi indicano che esiste una disparità demografica nelle etichette previste, poiché il facet *d* o il sottogruppo hanno una percentuale maggiore di etichette rifiutate previste rispetto alle etichette accettate previste. Più alto è il valore, maggiore è la disparità.
+ I valori vicini allo zero indicano l'assenza di disparità demografica, in media.
+ I valori negativi indicano che esiste una disparità demografica nelle etichette previste, poiché il facet *a* o il sottogruppo presenta una percentuale maggiore di etichette rifiutate previste rispetto alle etichette accettate previste. Più basso è il valore, maggiore è la disparità.
+ -1: quando non sono previste etichette di rifiuto per il facet *d* o il sottogruppo e accettazioni previste per il facet *a* o il sottogruppo.
# Fliptest controfattuale (FT)
Il fliptest è un approccio che esamina ogni membro del facet *d* e valuta se membri simili del facet *a* hanno previsioni di modello diverse. I membri del facet *a* vengono scelti comek-vicini più prossimi all'osservazione del facet *d*. Valutiamo quanti vicini più prossimi del gruppo opposto ricevono una previsione diversa, in cui la previsione capovolta può passare da positiva a negativa e viceversa.
La formula per il fliptest controfattuale è la differenza nella cardinalità di due insiemi divisa per il numero di membri del facet *d*:
FT = (F\$1 - F-)/nd
Dove:
+ F\$1 = è il numero di membri sfavoriti del facet *d* con esito sfavorevole i cui vicini più prossimi nel facet favorito *a* hanno ottenuto un esito favorevole.
+ F- = è il numero di membri sfavoriti del facet *d* con esito favorevole i cui vicini più prossimi nel facet *a* hanno ottenuto un esito sfavorevole.
+ nd è la dimensione del campione del facet *d*.
L’intervallo di valori per i fliptest controfattuale per etichette di facet binarie e multicategoria è [-1, \$11]. Per le etichette continue, impostiamo una soglia per comprimere le etichette in formato binario.
+ I valori positivi si verificano quando il numero di decisioni controfattuali sfavorevoli relative al facet *d* sfavorito supera quelle favorevoli.
+ I valori prossimi allo zero si verificano quando il numero di decisioni controfattuali sfavorevoli e favorevoli si compensa.
+ I valori negativi si verificano quando il numero di decisioni controfattuali sfavorevoli relative al facet *d* sfavorito è inferiore a quelle favorevoli.
# Entropia generalizzata (GE)
L'indice di entropia generalizzato (GE) misura la disuguaglianza in termini di beneficio `b` per l'etichetta prevista rispetto all'etichetta osservata. Un vantaggio si verifica quando si prevede un falso positivo. Un falso positivo si verifica quando un'osservazione negativa (y=0) ha una previsione positiva (y'=1). Un vantaggio si verifica anche quando le etichette osservate e previste sono le stesse, note anche come vero positivo e vero negativo. Non si ottiene alcun vantaggio quando si prevede un falso negativo. Un falso negativo si verifica quando si prevede che un'osservazione positiva (y=1) abbia un esito negativo (y'=0). Il vantaggio `b` è definito come segue.
```
b = y' - y + 1
```
Utilizzando questa definizione, un falso positivo riceve un vantaggio `b` di `2` e un falso negativo riceve un vantaggio di `0`. Sia un vero positivo sia un vero negativo ricevono un vantaggio di `1`.
La metrica GE viene calcolata sulla base del [Generalized Entropy Index](https://en.wikipedia.org/wiki/Generalized_entropy_index) (GE) con il peso `alpha` impostato su `2`. Questo peso controlla la sensibilità ai diversi valori dei benefici. Un valore più piccolo `alpha` indica una maggiore sensibilità a valori inferiori.
![\[Equazione che definisce l'indice di entropia generalizzato con il parametro alfa impostato su 2.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify-post-training-bias-metric-ge.png)
Le seguenti variabili utilizzate per calcolare GE sono definite come segue:
+ bi è il vantaggio ricevuto dal punto dati `ith`.
+ b' è la media di tutti i benefici.
GE può variare da 0 a 0,5, dove i valori pari a zero indicano l'assenza di disparità nei benefici tra tutti i punti dati. Ciò si verifica quando tutti gli input sono previsti correttamente o quando tutte le previsioni sono falsi positivi. GE non è definito quando tutte le previsioni sono falsi negativi.
**Nota**
La metrica GE non dipende dal fatto che un valore del facet sia favorito o sfavorito.
# Spiegabilità del modello
Amazon SageMaker Clarify fornisce strumenti che aiutano a spiegare come i modelli di machine learning (ML) generano previsioni. Questi strumenti possono aiutare i progettisti e gli sviluppatori di machine learning e altre parti interessate interne a comprendere le caratteristiche complessive del modello prima della distribuzione e ad eseguire il debug delle previsioni fornite dal modello dopo la sua implementazione.
+ Per ottenere spiegazioni sui set di dati e sui modelli, consulta [Equità, spiegabilità dei modelli e rilevamento dei pregiudizi con Clarify SageMaker](clarify-configure-processing-jobs.md).
+ Per ottenere spiegazioni in tempo reale da un endpoint di SageMaker intelligenza artificiale, consulta. [Spiegabilità online con Clarify SageMaker](clarify-online-explainability.md)
La trasparenza sul modo in cui i modelli di machine learning giungono alle loro previsioni è fondamentale anche per i consumatori e le autorità di regolamentazione. Devono fidarsi delle previsioni dei modelli se intendono accettare le decisioni basate su di esse. SageMaker Clarify utilizza un approccio di attribuzione delle funzionalità indipendente dal modello. È possibile utilizzarlo per capire perché un modello ha effettuato una previsione dopo l'addestramento e per fornire una spiegazione per istanza durante l'inferenza. L'implementazione include un'implementazione scalabile ed efficiente di [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf). Questo si basa sul concetto di un valore di Shapley, tratto dal campo della teoria cooperativa dei giochi, che assegna a ciascuna caratteristica un valore di importanza per una particolare previsione.
Clarify produce grafici di dipendenza parziali (PDPs) che mostrano l'effetto marginale delle caratteristiche sul risultato previsto di un modello di apprendimento automatico. La dipendenza parziale aiuta a spiegare la risposta mirata in base a una serie di funzionalità di input. Supporta inoltre la spiegabilità sia della visione artificiale (CV) che dell’elaborazione del linguaggio naturale (NLP) utilizzando lo stesso algoritmo dei valori Shapley (SHAP) utilizzato per le spiegazioni dei dati tabulari.
Qual è la funzione di una spiegazione nel contesto del machine learning? Una spiegazione può essere considerata come la risposta a una *domanda sul perché* che aiuta gli esseri umani a comprendere la causa di una previsione. Nel contesto di un modello di machine learning, potresti essere interessato a rispondere a domande come:
+ Perché il modello prevedeva un esito negativo, ad esempio il rifiuto di un prestito, per un determinato richiedente?
+ In che modo il modello fa previsioni?
+ Perché il modello ha fatto una previsione errata?
+ Quali caratteristiche hanno la maggiore influenza sul comportamento del modello?
Puoi utilizzare queste spiegazioni per verificare e soddisfare i requisiti normativi, creare fiducia nel modello, supportare il processo decisionale umano, eseguire il debug e migliorare le prestazioni del modello.
La necessità di soddisfare le esigenze di comprensione umana della natura e dei risultati dell'inferenza ML è fondamentale per il tipo di spiegazione necessaria. Ricerche nel campo della filosofia e delle scienze cognitive hanno dimostrato che le persone si preoccupano soprattutto delle spiegazioni contrastive, o delle spiegazioni del perché si è verificato un evento X invece di un altro evento Y che non si è verificato. Qui, X potrebbe essere un evento inaspettato o sorprendente accaduto e Y corrisponde a un'aspettativa basata sul loro modello mentale esistente, denominata *linea di base*. Tieni presente che, per lo stesso evento X, persone diverse potrebbero cercare spiegazioni diverse a seconda del loro punto di vista o del modello mentale Y. Nel contesto dell'intelligenza artificiale spiegabile, puoi pensare a X come l'esempio che viene spiegato e Y come una linea di base che viene in genere scelta per rappresentare un esempio non informativo o medio nel set di dati. A volte, ad esempio nel caso della modellazione ML di immagini, la linea di base potrebbe essere implicita, dove un'immagine i cui pixel sono tutti dello stesso colore può fungere da linea di base.
## Notebook di esempio
Amazon SageMaker Clarify fornisce il seguente notebook di esempio per la spiegabilità del modello:
+ [Amazon SageMaker Clarify Processing](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/index.html#sagemaker-clarify-processing): usa SageMaker Clarify per creare un processo di elaborazione per rilevare distorsioni e spiegare le previsioni dei modelli con l'attribuzione di funzionalità. Gli esempi includono l'utilizzo dei formati di dati CSV e JSON Lines, la creazione di container personalizzati e l'esecuzione di processi di elaborazione con Spark.
+ [Spiegazione della classificazione delle immagini con SageMaker Clarify — SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) fornisce informazioni dettagliate su come i modelli di visione artificiale classificano le immagini.
+ [Spiegazione dei modelli di rilevamento degli oggetti con SageMaker Clarify — SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) fornisce informazioni dettagliate su come i modelli di visione artificiale rilevano gli oggetti.
È stato verificato che questo notebook funzioni solo in Amazon SageMaker Studio. Se hai bisogno di istruzioni su come aprire un notebook in Amazon SageMaker Studio, consulta[Crea o apri un notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Se ti viene richiesto di scegliere un kernel, scegli **Python 3 (Data Science)**.
**Topics**
+ [Notebook di esempio](#clarify-model-explainability-sample-notebooks)
+ [Caratterizzazione delle attribuzioni che utilizzano i valori Shapley](clarify-shapley-values.md)
+ [Valori asimmetrici di Shapley](clarify-feature-attribute-shap-asymm.md)
+ [Linee di base SHAP per la spiegabilità](clarify-feature-attribute-shap-baselines.md)
# Caratterizzazione delle attribuzioni che utilizzano i valori Shapley
SageMaker Clarify fornisce attribuzioni di funzionalità basate sul concetto di valore [Shapley](https://en.wikipedia.org/wiki/Shapley_value). È possibile utilizzare i valori Shapley per determinare il contributo apportato da ciascuna funzionalità ai modelli di previsione. Queste attribuzioni possono essere fornite per previsioni specifiche e a livello globale per il modello nel suo insieme. Ad esempio, se hai utilizzato un modello di machine learning per le ammissioni all'università, le spiegazioni potrebbero aiutare a determinare se il punteggio GPA o il punteggio SAT fosse la caratteristica più responsabile delle previsioni del modello, e quindi puoi determinare in che misura ciascuna caratteristica fosse responsabile nel determinare una decisione di ammissione relativa a un determinato studente.
SageMaker Clarify ha preso il concetto di valori di Shapley dalla teoria dei giochi e lo ha implementato in un contesto di apprendimento automatico. Il valore Shapley fornisce un modo per quantificare il contributo di ogni giocatore a un gioco e quindi i mezzi per distribuire il guadagno totale generato da un gioco ai giocatori in base ai loro contributi. *In questo contesto di apprendimento automatico, SageMaker Clarify considera la previsione del modello su una determinata istanza come un *gioco* e le funzionalità incluse nel modello come i giocatori.* Per una prima approssimazione, si potrebbe essere tentati di determinare il contributo o l'effetto marginale di ciascuna caratteristica quantificando il risultato dell'*eliminazione* di quella caratteristica dal modello o dell'*eliminazione* di tutte le altre caratteristiche dal modello. Tuttavia, questo approccio non tiene conto del fatto che le funzionalità incluse in un modello spesso non sono indipendenti l'una dall'altra. Ad esempio, se due caratteristiche sono altamente correlate, l'eliminazione di una delle due potrebbe non alterare in modo significativo la previsione del modello.
Per risolvere queste potenziali dipendenze, il valore di Shapley richiede che venga considerato il risultato di ogni possibile combinazione (o coalizione) di caratteristiche per determinare l'importanza di ciascuna caratteristiche. Date le caratteristiche di *d*, esistono 2d combinazioni possibili di funzionalità, ciascuna corrispondente a un modello potenziale. Per determinare l'attribuzione di una determinata caratteristica *f*, considera il contributo marginale dell'inclusione di *f* in tutte le combinazioni di funzionalità (e nei modelli associati) che non contengono *f* e calcola la media. Si può dimostrare che il valore di Shapley è l’unico modo di assegnare il contributo o l'importanza di ciascuna caratteristica che soddisfa determinate proprietà desiderabili. In particolare, la somma dei valori Shapley di ciascuna caratteristiche corrisponde alla differenza tra le previsioni del modello e quelle di un modello fittizio senza caratteristiche. Tuttavia, anche per valori ragionevoli di *d*, ad esempio 50 caratteristiche, è proibitivo a livello computazionale e poco pratico addestrare 2d modelli possibili. Di conseguenza, SageMaker Clarify deve utilizzare varie tecniche di approssimazione. A tale scopo, SageMaker Clarify utilizza Shapley Additive Explanations (SHAP), che incorpora tali approssimazioni e ha ideato un'implementazione scalabile ed efficiente dell'algoritmo Kernel SHAP attraverso ottimizzazioni aggiuntive.
Per ulteriori informazioni sui valori di Shapley, vedere [Approccio unificato all'interpretazione delle previsioni dei modelli](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf).
# Valori asimmetrici di Shapley
[La soluzione di spiegazione del modello di previsione delle serie temporali SageMaker Clarify è un metodo di attribuzione delle funzionalità radicato nella teoria dei giochi cooperativi, simile nello spirito a SHAP.](https://en.wikipedia.org/wiki/Cooperative_game_theory) In particolare, Clarify utilizza [valori di gruppo in ordine casuale](http://www.library.fa.ru/files/Roth2.pdf#page=121), noti anche come [valori asimmetrici di Shapley](https://proceedings.neurips.cc/paper/2020/file/0d770c496aa3da6d2c3f2bd19e7b9d6b-Paper.pdf) nel machine learning e nella spiegabilità.
## Contesto
L’obiettivo è calcolare le attribuzioni per le funzionalità di input in un determinato modello di previsione *f*. Il modello di previsione accetta gli input seguenti:
+ Serie temporali passate *(TS di destinazione)*. Ad esempio, potrebbe trattarsi dei passeggeri ferroviari passati ogni giorno sulla tratta Parigi-Berlino, indicati con *xt*.
+ (Facoltativo) Una serie temporale covariata. Ad esempio, potrebbe trattarsi di festività e dati meteorologici, indicati con *zt* ∈ RS. Se utilizzata, la TS covariata potrebbe essere disponibile solo per le fasi temporali passate oppure anche per quelle future (incluse nel calendario delle festività).
+ (Facoltativo) Le covariate statiche, ad esempio la qualità del servizio (ad esempio, prima o seconda classe), sono indicate da *u* ∈ RE.
Le covariate statiche, le covariate dinamiche o entrambe possono essere omesse, a seconda dello scenario applicativo specifico. Dato un orizzonte di previsione K ≥ 0 (ad esempio K = 30 giorni), la previsione tramite modello può essere caratterizzata dalla formula: *f(x[1:T], z[1:T\$1K], u) = x[T\$11:T \$1K\$11]*.
Il diagramma seguente mostra una struttura delle dipendenze per un modello di previsione tipico. La previsione nel momento *t\$11* dipende dai tre tipi di input menzionati in precedenza.
![\[Struttura delle dipendenze per un modello di previsione tipico.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/clarify/clarify-forecast-dependency.png)
## Metodo
Le spiegazioni vengono calcolate eseguendo query sul modello delle serie temporali *f* su una serie di punti derivati dall’input originale. Seguendo i costrutti della teoria dei giochi, Clarify calcola la media delle differenze nelle previsioni dovute all’offuscamento (ovvero all’impostazione di un valore baseline) iterativo di parti degli input. La struttura temporale può essere esplorata in ordine cronologico, anticronologico o entrambi. Le spiegazioni cronologiche vengono create aggiungendo informazioni in modo iterativo dalla prima fase temporale, mentre per le spiegazioni anticronologiche si inizia dall’ultima fase. Quest’ultima modalità può essere più adatta per i bias di novità, ad esempio quando si prevedono i prezzi delle azioni. Una proprietà importante delle spiegazioni calcolate è che si sommano all’output del modello originale se il modello fornisce risultati deterministici.
## Attribuzioni risultanti
Le attribuzioni risultanti sono punteggi che valutano i contributi individuali di specifiche fasi temporali o funzionalità di input alla previsione finale in ogni fase temporale prevista. Clarify offre le due granularità per le spiegazioni:
+ Le spiegazioni temporali non sono costose e forniscono informazioni mirate su fasi temporali specifiche, ad esempio in che misura le informazioni del 19° giorno nel passato hanno contribuito alla previsione del 1° giorno nel futuro. Queste attribuzioni non spiegano singolarmente le covariate statiche e le spiegazioni aggregate delle serie temporali di destinazione e covariate. Le attribuzioni sono una matrice *A* in cui ogni *Atk* è l’attribuzione della fase temporale *t* rispetto alla previsione della fase temporale *T\$1k*. Nota che se il modello accetta covariate future, *t* può essere maggiore di *T*.
+ Le spiegazioni dettagliate sono più impegnative a livello computazionale e forniscono una suddivisione completa di tutte le attribuzioni delle variabili di input.
**Nota**
Le spiegazioni dettagliate supportano solo l’ordine cronologico.
Le attribuzioni risultanti sono una tripletta composta da:
+ Matrice *Ax* ∈ RT×K relativa alla serie temporale di input, dove *Atkx* è l’attribuzione di *xt* rispetto alla fase di previsione *T\$1k*
+ Tensore *Az* ∈ *RT\$1K×S×K* relativo alla serie temporale covariata, dove *Atskz* è l’attribuzione di *zts* (ad esempio, la s° TS covariata) rispetto alla fase di previsione *T\$1k*
+ Matrice *Au* ∈ RE×K relativa alle covariate statiche, dove *Aeku* è l’attribuzione di *ue* (la covariata statica e°) rispetto alla fase di previsione *T\$1k*
Indipendentemente dalla granularità, la spiegazione contiene anche un vettore di offset *B* ∈ *RK* che rappresenta il “comportamento di base” del modello quando tutti i dati sono offuscati.
# Linee di base SHAP per la spiegabilità
Le spiegazioni sono in genere contrastive, ovvero tengono conto delle deviazioni da una linea di base. Di conseguenza, per lo stesso modello di previsione, puoi aspettarti di ottenere spiegazioni diverse rispetto a linee di base diverse. Pertanto, la scelta di una linea di base è fondamentale. In un contesto di machine learning, la linea di base corrisponde a un'istanza ipotetica che può essere *non informativa* o *informativa*. Durante il calcolo dei valori di Shapley, SageMaker Clarify genera diverse nuove istanze tra la linea di base e l'istanza data, in cui l'assenza di una feature viene modellata impostando il valore della feature su quello della linea di base e la presenza di una feature viene modellata impostando il valore della feature su quello della determinata istanza. Pertanto, l'assenza di tutte le funzionalità corrisponde alla linea di base e la presenza di tutte le funzionalità corrisponde all'istanza data.
Come si possono scegliere delle buone linee di base? Spesso è preferibile selezionare una linea di base con un contenuto informativo molto basso. Ad esempio, è possibile costruire un'istanza media dal set di dati di addestramento prendendo la mediana o la media per le caratteristiche numeriche e la modalità per le caratteristiche categoriche. Per quanto riguarda l'esempio delle ammissioni all'università, potrebbe interessarti spiegare perché un determinato candidato è stato accettato rispetto alle accettazioni di base basate su un candidato medio. Se non viene fornita, una linea di base viene calcolata automaticamente da SageMaker Clarify utilizzando metodi K o prototipi K nel set di dati di input.
In alternativa, è possibile scegliere di generare spiegazioni rispetto alle linee di base informative. Per quanto riguarda lo scenario delle ammissioni all'università, potresti voler spiegare perché un determinato candidato è stato respinto rispetto ad altri candidati provenienti da contesti demografici simili. In questo caso, puoi scegliere una linea di base che rappresenti i candidati di interesse, vale a dire quelli con un background demografico simile. Pertanto, è possibile utilizzare linee di base informative per concentrare l'analisi sugli aspetti specifici di un particolare modello di previsione. È possibile isolare le funzionalità per la valutazione impostando gli attributi demografici e altre funzionalità su cui non è possibile agire con lo stesso valore dell'istanza specifica.
# SageMaker SageMaker Chiarisci la spiegabilità con AI Autopilot
Autopilot utilizza gli strumenti forniti da Amazon SageMaker Clarify per contribuire a fornire informazioni su come i modelli di machine learning (ML) effettuano previsioni. Questo report può aiutare gli ingegneri del machine learning, i product manager e altri stakeholder interni a comprendere le caratteristiche del modello. Per valutare l’attendibilità e interpretare le decisioni prese in base alle previsioni tramite modello, sia i consumer sia gli organismi di regolamentazione si affidano alla trasparenza del machine learning.
La funzionalità esplicativa di Autopilot utilizza un approccio di attribuzione delle funzionalità indipendente dal modello. Questo approccio determina il contributo delle singole funzionalità o input all'output del modello, fornendo informazioni sulla rilevanza delle diverse funzionalità. È possibile utilizzarlo per capire perché un modello ha effettuato una previsione dopo l'addestramento e per fornire una spiegazione per istanza durante l'inferenza. L’implementazione include un’implementazione scalabile di [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) (Shapley Additive Explanations). L’implementazione si basa sul concetto di valore di Shapley, tratto della teoria cooperativa dei giochi, che assegna a ciascuna funzionalità un valore di importanza per una particolare previsione.
Puoi utilizzare le spiegazioni SHAP per verificare quanto segue: controllare e soddisfare i requisiti normativi, creare fiducia nel modello, supportare il processo decisionale umano o eseguire il debug e migliorare le prestazioni del modello.
Per ulteriori informazioni sui valori e sulle baseline Shapely, consulta [Baseline SHAP per la spiegabilità](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html).
Per una guida alla documentazione di Amazon SageMaker Clarify, consulta [Guide to the SageMaker Clarify](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-fairness-and-explainability.html#clarify-fairness-and-explainability-toc) Documentation.