Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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\_template. `'{"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` è {'predictions [\*] .mean [:2] '}}, 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