As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Execute trabalhos de processamento do SageMaker Clarify para análise de viés e explicabilidade
Para analisar seus dados e modelos em busca de viés e explicabilidade usando o SageMaker Clarify, você deve configurar um trabalho de processamento do SageMaker Clarify. Este guia mostra como configurar as entradas, saídas, recursos e análise do trabalho usando a API SageMaker Python SDK. `SageMakerClarifyProcessor`
A API atua como um invólucro de alto nível da API de SageMaker IA`CreateProcessingJob`. Ele oculta muitos dos detalhes envolvidos na configuração de um trabalho de processamento do SageMaker Clarify. Os detalhes para configurar um trabalho incluem a recuperação do URI da imagem do contêiner SageMaker Clarify e a geração do arquivo de configuração de análise. As etapas a seguir mostram como configurar, inicializar e iniciar uma tarefa de processamento do SageMaker Clarify.
**Configurar um trabalho de processamento do SageMaker Clarify usando a API**
1. Defina os objetos de configuração para cada parte da configuração do trabalho. Essas partes podem incluir o seguinte:
+ O conjunto de dados de entrada e o local de saída: [DataConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.DataConfig).
+ O modelo ou ponto final a ser analisado: [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig).
+ Parâmetros de análise de viés: [BiasConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.BiasConfig).
+ SHapley Parâmetros de análise de explicações aditivas (SHAP):. [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)
+ Parâmetros assimétricos de análise do valor de Shapley (somente para séries temporais):. [AsymmetricShapleyValueConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.AsymmetricShapleyValueConfig)
Os objetos de configuração de uma tarefa de processamento do SageMaker Clarify variam de acordo com os diferentes tipos de formatos de dados e casos de uso. Exemplos de configuração para dados tabulares em formato [CSV](#clarify-processing-job-run-tabular-csv) e [JSON Lines](#clarify-processing-job-run-tabular-jsonlines), problemas de processamento de linguagem natural ([NLP](#clarify-processing-job-run-tabular-nlp)), [computer vision](#clarify-processing-job-run-cv) (CV) e séries temporais (TS) são fornecidos nas seções a seguir.
1. Crie um objeto `SageMakerClarifyProcessor` e inicialize-o com parâmetros que especificam os recursos do trabalho. Esses recursos incluem parâmetros como o número de instâncias de computação a serem usadas.
O exemplo de código a seguir mostra como criar um objeto `SageMakerClarifyProcessor` e instruí-lo a usar uma instância de computação `ml.c4.xlarge` para fazer a análise.
```
from sagemaker import clarify
clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=1,
instance_type='ml.c4.xlarge',
sagemaker_session=session,
)
```
1. Chame o método de execução específico do [SageMakerClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor.run)objeto com os objetos de configuração do seu caso de uso para iniciar o trabalho. Esses métodos de execução incluem o seguinte:
+ `run_pre_training_bias`
+ `run_post_training_bias`
+ `run_bias`
+ `run_explainability`
+ `run_bias_and_explainability`
Esse `SageMakerClarifyProcessor` lida com várias tarefas nos bastidores. Essas tarefas incluem recuperar o identificador universal de recursos (URI) da imagem do contêiner do SageMaker Clarify, compor um arquivo de configuração de análise com base nos objetos de configuração fornecidos, carregar o arquivo em um bucket do Amazon S3 e [configurar](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html) o trabalho de processamento do Clarify. SageMaker
As seções expansíveis a seguir mostram como calcular **métricas de desvio pré-treinamento** e **pós-treinamento**, **valores SHAP** e **gráficos de dependência parcial** (PDPs). As seções mostram a importância dos atributos desses tipos de dados:
+ Conjuntos de dados tabulares em formato CSV ou formato JSON Lines.
+ Conjuntos de dados de processamento de linguagem natural (PLN)
+ Conjuntos de dados de visão computacional
Um guia para executar trabalhos paralelos de processamento do SageMaker Clarify com treinamento distribuído usando o **Spark** segue as seções expansíveis.
## Analisar dados tabulares no formato CSV
Os exemplos a seguir mostram como configurar a análise de desvio e a análise de explicabilidade para um conjunto de dados tabular no formato CSV. Nesses exemplos, o conjunto de dados de entrada tem quatro colunas de atributos e uma coluna de rótulo binário, `Target`. O conteúdo do conjunto de dados é o seguinte: O valor do rótulo `1` indica um resultado 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
...
```
Esse objeto `DataConfig` especifica o conjunto de dados de entrada e onde armazenar a saída. O parâmetro `s3_data_input_path` pode ser um URI de um arquivo de conjunto de dados ou um prefixo de URI do Amazon S3. Se você fornecer um prefixo de URI do S3, o trabalho de processamento do SageMaker Clarify coletará recursivamente todos os arquivos do Amazon S3 localizados sob o prefixo. O valor de `s3_output_path` deve ser um prefixo de URI S3 para manter os resultados da análise. SageMaker A IA usa o `s3_output_path` durante a compilação e não pode assumir o valor de um parâmetro, propriedade, expressão ou do SageMaker AI Pipeline`ExecutionVariable`, que são usados durante o tempo de execução. O exemplo de código a seguir mostra como especificar uma configuração de dados para a amostra de conjunto de dados de entrada anterior.
```
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,
)
```
### Como calcular todas as métricas de desvio pré-treinamento para um conjunto de dados CSV
O exemplo de código a seguir mostra como configurar um `BiasConfig` objeto para medir o desvio da entrada da amostra anterior em relação a amostras com um valor `0` de `Gender`.
```
bias_config = clarify.BiasConfig(
label_values_or_threshold=[1],
facet_name='{{Gender}}',
facet_values_or_threshold=[0],
)
```
O exemplo de código a seguir mostra como usar uma instrução de execução para iniciar um trabalho de processamento do SageMaker Clarify que calcula todas as [métricas de viés pré-treinamento](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html) para um conjunto de dados de entrada.
```
clarify_processor.run_pre_training_bias(
data_config=data_config,
data_bias_config=bias_config,
methods="all",
)
```
Como alternativa, você pode escolher quais métricas calcular atribuindo uma lista de métricas de desvio pré-treinamento ao parâmetro métodos. Por exemplo, a substituição `methods="all"` por `methods=["CI", "DPL"]` instrui o Processador SageMaker Clarify a calcular somente o [desequilíbrio de classes](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html) e a [diferença nas proporções](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-data-bias-metric-true-label-imbalance.html) dos rótulos.
### Como calcular todas as métricas de desvio pós-treinamento para um conjunto de dados CSV
Você pode calcular as métricas de desvio pré-treinamento antes do treinamento. No entanto, para calcular as [métricas de desvio pós-treinamento](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-post-training-bias.html), você deve ter um modelo treinado. O exemplo de saída a seguir é de um modelo de classificação binária que gera dados no formato CSV. Neste exemplo de saída, cada linha contém duas colunas. A primeira coluna contém o rótulo previsto e a segunda coluna contém o valor de probabilidade desse rótulo.
```
0,0.028986845165491
1,0.825382471084594
...
```
No exemplo de configuração a seguir, o `ModelConfig` objeto instrui o trabalho a implantar o modelo de SageMaker IA em um endpoint temporário. O endpoint usa uma instância de inferência `ml.m4.xlarge`. Como os parâmetros `content_type` e não `accept_type` estão definidos, eles usam automaticamente o valor do parâmetro `dataset_type`, que é `text/csv`.
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
)
```
O exemplo de configuração a seguir usa um objeto `ModelPredictedLabelConfig` com um índice de rótulo de `0`. Isso instrui o trabalho de processamento do SageMaker Clarify a localizar o rótulo previsto na primeira coluna da saída do modelo. O trabalho de processamento usa indexação com base em zero neste exemplo.
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label=0,
)
```
Combinado com o exemplo de configuração anterior, o exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para calcular todas as métricas de viés pós-treinamento.
```
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",
)
```
Da mesma forma, você pode escolher quais métricas calcular atribuindo uma lista de métricas de desvio pós-treinamento ao parâmetro `methods`. Como exemplo, substituir `methods=“all”` por `methods=["DPPL", "DI"]` para calcular somente a [diferença nas proporções positivas em rótulos previstos](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-dppl.html) e o [impacto díspar](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-di.html).
### Como calcular todas as métricas de desvio para um conjunto de dados CSV
O exemplo de configuração a seguir mostra como executar todas as métricas de viés pré-treinamento e pós-treinamento em uma tarefa de processamento do SageMaker Clarify.
```
clarify_processor.run_bias(
data_config=data_config,
bias_config=bias_config,
model_config=model_config,
model_predicted_label_config=predicted_label_config,
pre_training_methods="all",
post_training_methods="all",
)
```
Para ver um exemplo de caderno com instruções sobre como executar uma tarefa de processamento do SageMaker Clarify no SageMaker Studio Classic para detectar preconceitos, consulte [Imparcialidade e explicabilidade](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb) com o Clarify. SageMaker
### Como calcular valores SHAP para um conjunto de dados CSV
SageMaker O Clarify fornece atribuições de recursos usando o algoritmo [KernelShap](https://arxiv.org/abs/1705.07874). SHAPa análise requer o valor de probabilidade ou pontuação em vez do rótulo previsto, portanto, esse `ModelPredictedLabelConfig` objeto tem índice de probabilidade`1`. Isso instrui o trabalho de processamento do SageMaker Clarify a extrair a pontuação de probabilidade da segunda coluna da saída do modelo (usando indexação baseada em zero).
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=1,
)
```
O objeto `SHAPConfig` fornece parâmetros de análise SHAP. Neste exemplo, o parâmetro de `baseline` do SHAP é omitido e o valor do parâmetro `num_clusters` é `1`. Isso instrui o Processador do SageMaker Clarify a calcular uma amostra de linha de base com SHAP base no agrupamento do conjunto de dados de entrada. Se você quiser escolher o conjunto de dados de linha de base, consulte [Linhas de base do SHAP para explicabilidade](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html).
```
shap_config = clarify.SHAPConfig(
num_clusters=1,
)
```
O exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para calcular SHAP valores.
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=shap_config,
)
```
Para ver um exemplo de caderno com instruções sobre como executar uma tarefa de processamento do SageMaker Clarify no SageMaker Studio Classic para calcular SHAP valores, consulte [Imparcialidade e explicabilidade](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb) com o Clarify. SageMaker
### Como calcular gráficos de dependência parcial (PDPs) para um conjunto de dados CSV
O PDPs mostra a dependência da resposta alvo prevista em uma ou mais atributos de entrada de interesse, mantendo todos os outros atributos constantes. Uma linha ascendente, ou curva no PDP, indica que a relação entre o alvo e os atributos de entrada é positiva, e a inclinação indica a força da relação. Uma linha ou curva descendente indica que, se um atributo de entrada diminuir, a variável alvo aumentará. Intuitivamente, você pode interpretar a dependência parcial como a resposta da variável alvo a cada atributo de entrada de interesse.
O exemplo de configuração a seguir é para usar um `PDPConfig` objeto para instruir o trabalho de processamento do SageMaker Clarify a calcular a importância do `Income` recurso.
```
pdp_config = clarify.PDPConfig(
features=["Income"],
grid_resolution=10,
)
```
No exemplo anterior, o parâmetro `grid_resolution` dividia o intervalo dos valores do atributo `Income` em buckets `10`. O trabalho de processamento do SageMaker Clarify PDPs gerará a `Income` divisão em `10` segmentos no eixo x. O eixo y mostrará o impacto marginal de `Income` na variável alvo.
O exemplo de código a seguir inicia uma tarefa de processamento do SageMaker Clarify para computação. PDPs
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=pdp_config,
)
```
Para ver um exemplo de notebook com instruções sobre como executar uma tarefa de processamento do SageMaker Clarify no SageMaker Studio Classic para computaçãoPDPs, consulte [Explicabilidade com o SageMaker Clarify - Gráficos de dependência parcial](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb) (PDP).
### Como calcular os valores SHAP e PDPs para um conjunto de dados CSV
Você pode calcular os dois SHAP valores PDPs em um único trabalho de processamento do SageMaker Clarify. No exemplo de configuração a seguir, o parâmetro `top_k_features` de um novo objeto `PDPConfig` é definido como `2`. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular PDPs os `2` recursos que têm os maiores valores globaisSHAP.
```
shap_pdp_config = clarify.PDPConfig(
top_k_features=2,
grid_resolution=10,
)
```
O exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para calcular os SHAP valores e. PDPs
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=[shap_config, shap_pdp_config],
)
```
## Analisar dados tabulares no formato linhas JSON
Os exemplos a seguir mostram como configurar a análise de viés e a análise de explicabilidade para um conjunto de dados tabular no formato denso > SageMaker AI JSON Lines. Consulte [Formato da solicitação JSONLINES](cdf-inference.md#cm-jsonlines) para obter mais informações. Nesses exemplos, o conjunto de dados de entrada tem os mesmos dados da seção anterior, mas eles estão no formato JSON Lines. Cada linha é um objeto JSON válido. A chave `Features` se refere a uma matriz de valores de atributos, e a chave `Label` se refere ao rótulo de veracidade.
```
{"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}
...
```
No exemplo de configuração a seguir, o objeto `DataConfig` especifica o conjunto de dados de entrada e onde armazenar a saída.
```
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,
)
```
No exemplo de configuração anterior, o parâmetro features é definido como a [JMESPath](https://jmespath.org/)expressão `Features` para que a tarefa de processamento do SageMaker Clarify possa extrair a matriz de recursos de cada registro. O `label` parâmetro é definido como JMESPath expressão `Label` para que o trabalho de processamento do SageMaker Clarify possa extrair o rótulo de verdade fundamental de cada registro. O parâmetro `s3_data_input_path` pode ser um URI de um arquivo de conjunto de dados ou um prefixo de URI do Amazon S3. Se você fornecer um prefixo de URI do S3, o trabalho de processamento do SageMaker Clarify coletará recursivamente todos os arquivos do S3 localizados abaixo do prefixo. O valor de `s3_output_path` deve ser um prefixo de URI S3 para manter os resultados da análise. SageMaker A IA usa o `s3_output_path` durante a compilação e não pode assumir o valor de um parâmetro, propriedade, expressão ou do SageMaker AI Pipeline`ExecutionVariable`, que são usados durante o tempo de execução.
Você deve ter um modelo treinado para calcular as métricas de desvio pós-treinamento ou a importância do atributo. O exemplo a seguir é de um modelo de classificação binária que gera dados de linhas JSON no formato do exemplo. Cada linha da saída do modelo é um objeto JSON válido. A chave `predicted_label` refere-se ao rótulo previsto e a chave `probability` refere-se ao valor da probabilidade.
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
No exemplo de configuração a seguir, um `ModelConfig` objeto instrui o trabalho de processamento do SageMaker Clarify a implantar o modelo de SageMaker IA em um endpoint temporário. O endpoint usa uma instância de inferência `ml.m4.xlarge`.
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
content_template='{"Features":$features}',
)
```
No exemplo de configuração anterior, os parâmetros `content_type` e `accept_type` não estão definidos. Portanto, eles usam automaticamente o valor do parâmetro `dataset_type` do objeto `DataConfig`, que é `application/jsonlines`. O trabalho de processamento do SageMaker Clarify usa o `content_template` parâmetro para compor a entrada do modelo substituindo o `$features` espaço reservado por uma matriz de recursos.
O exemplo de configuração a seguir mostra como definir o parâmetro label do `ModelPredictedLabelConfig` objeto para a JMESPath expressão`predicted_label`. Isso extrairá o rótulo previsto da saída do modelo.
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label='predicted_label',
)
```
O exemplo de configuração a seguir mostra como definir o `probability` parâmetro do `ModelPredictedLabelConfig` objeto para a JMESPath expressão`probability`. Isso extrairá a pontuação da saída do modelo.
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
Para calcular as métricas de desvio e a importância dos atributos para conjuntos de dados no formato linhas JSON, use as mesmas instruções de execução e objetos de configuração da seção anterior para conjuntos de dados CSV. Você pode executar uma tarefa de processamento do SageMaker Clarify no SageMaker Studio Classic para detectar tendências e calcular a importância do recurso. Para obter instruções e um exemplo de caderno, consulte [Imparcialidade e explicabilidade com o SageMaker Clarify (formato de linhas JSON](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.ipynb)).
## Analisar dados tabulares para explicabilidade da PNL
SageMaker O Clarify oferece suporte a explicações para modelos de processamento de linguagem natural (PNL). Essas explicações ajudam você a entender quais seções do texto são as mais importantes para as predições do seu modelo. Você pode explicar a predição de modelo para uma única instância do conjunto de dados de entrada ou as predições de modelo a partir do conjunto de dados da linha de base. Para entender e visualizar o comportamento de um modelo, você pode especificar vários níveis de granularidade. Para fazer isso, defina o tamanho do segmento de texto, como seus tokens, frases e parágrafos.
SageMaker Esclareça que a explicabilidade da PNL é compatível com os modelos de classificação e regressão. Você também pode usar o SageMaker Clarify para explicar o comportamento do seu modelo em conjuntos de dados multimodais que contêm texto, características categóricas ou numéricas. A explicabilidade da PNL para conjuntos de dados multimodais pode ajudá-lo a entender a importância de cada recurso para a saída do modelo. SageMaker O Clarify suporta 62 idiomas e pode lidar com texto que inclui vários idiomas.
O exemplo a seguir mostra um arquivo de configuração de análise para o cálculo da importância do atributo para a PNL. Neste exemplo, o conjunto de dados de entrada é um conjunto de dados tabular no formato CSV, com uma coluna de rótulo binária e duas colunas de atributos.
```
0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...
```
O exemplo de configuração a seguir mostra como especificar um conjunto de dados de entrada no formato CSV e o caminho dos dados de saída usando o objeto `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,
)
```
No exemplo de configuração anterior, o parâmetro `s3_data_input_path` pode ser um URI de um arquivo de conjunto de dados ou um prefixo de URI do Amazon S3. Se você fornecer um prefixo de URI do S3, o trabalho de processamento do SageMaker Clarify coletará recursivamente todos os arquivos do S3 localizados abaixo do prefixo. O valor de `s3_output_path` deve ser um prefixo de URI S3 para manter os resultados da análise. SageMaker A IA usa o `s3_output_path` durante a compilação e não pode assumir o valor de um parâmetro, propriedade, expressão ou do SageMaker AI Pipeline`ExecutionVariable`, que são usados durante o tempo de execução.
O exemplo de saída a seguir foi criado a partir de um modelo de classificação binária treinado no conjunto de dados de entrada anterior. O modelo de classificação aceita dados CSV e gera uma única pontuação entre `0` e `1`.
```
0.491656005382537
0.569582343101501
...
```
O exemplo a seguir mostra como configurar o `ModelConfig` objeto para implantar um modelo de SageMaker IA. Neste exemplo, um endpoint efêmero implanta o modelo. Esse endpoint usa uma instância de inferência `ml.g4dn.xlarge` equipada com uma GPU, para inferência acelerada.
```
nlp_model_config = clarify.ModelConfig(
model_name=your_nlp_model_name,
instance_type='ml.g4dn.xlarge',
instance_count=1,
)
```
O exemplo a seguir mostra como configurar o objeto `ModelPredictedLabelConfig` para localizar a probabilidade (pontuação) na primeira coluna com um índice de `0`.
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=0,
)
```
O exemplo de configuração SHAP a seguir mostra como executar uma análise de explicabilidade por token usando um modelo e um conjunto de dados de entrada no idioma inglês.
```
text_config = clarify.TextConfig(
language='english',
granularity='token',
)
nlp_shap_config = clarify.SHAPConfig(
baseline=[[4, '[MASK]']],
num_samples=100,
text_config=text_config,
)
```
No exemplo anterior, o objeto `TextConfig` ativava a análise de explicabilidade da PNL. O parâmetro `granularity` indica que a análise deve analisar os tokens. Em inglês, cada token é uma palavra. Para outras linguagens, consulte a [documentação do SpacY para tokenização](https://spacy.io/usage/linguistic-features#tokenization), que o SageMaker Clarify usa para processamento de NLP. O exemplo anterior também mostra como usar uma média `Rating` de `4` para definir uma instância de linha de base SHAP no local. Um token de máscara especial `[MASK]` é usado para substituir um token (palavra) em `Comments`.
No exemplo anterior, se a instância for `2,"Flavor needs work"`, defina a linha de base como uma média `Rating` de `4` com a linha de base a seguir.
```
4, '[MASK]'
```
No exemplo anterior, o explicador do SageMaker Clarify percorre cada token e o substitui pela máscara, da seguinte maneira.
```
2,"[MASK] needs work"
4,"Flavor [MASK] work"
4,"Flavor needs [MASK]"
```
Em seguida, o SageMaker explicador do Clarify enviará cada linha ao seu modelo para fazer previsões. Isso é para que o explicador aprenda as predições com e sem as palavras mascaradas. O SageMaker explicador do Clarify então usa essas informações para calcular a contribuição de cada token.
O exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para calcular SHAP valores.
```
clarify_processor.run_explainability(
data_config=nlp_data_config,
model_config=nlp_model_config,
model_scores=probability_config,
explainability_config=nlp_shap_config,
)
```
Para ver um exemplo de caderno com instruções sobre como executar uma tarefa de processamento do SageMaker Clarify no SageMaker Studio Classic para análise de explicabilidade da PNL, consulte [Explicando a análise de sentimentos de texto usando](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/text_explainability/text_explainability.ipynb) o Clarify. SageMaker
## Analise os dados da imagem para explicabilidade da visão computacional
SageMaker O Clarify gera mapas de calor que fornecem informações sobre como seus modelos de visão computacional classificam e detectam objetos em suas imagens.
No exemplo de configuração a seguir, o conjunto de dados de entrada consiste em imagens 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,
)
```
No exemplo de configuração anterior, o objeto `DataConfig` contém um conjunto `s3_data_input_path` para um prefixo de URI do Amazon S3. A tarefa de processamento do SageMaker Clarify coleta recursivamente todos os arquivos de imagem localizados sob o prefixo. O parâmetro `s3_data_input_path` pode ser um URI de um arquivo de conjunto de dados ou um prefixo de URI do Amazon S3. Se você fornecer um prefixo de URI do S3, o trabalho de processamento do SageMaker Clarify coletará recursivamente todos os arquivos do S3 localizados abaixo do prefixo. O valor de `s3_output_path` deve ser um prefixo de URI S3 para manter os resultados da análise. SageMaker A IA usa o `s3_output_path` durante a compilação e não pode assumir o valor de um parâmetro, propriedade, expressão ou do SageMaker AI Pipeline`ExecutionVariable`, que são usados durante o tempo de execução.
### Como explicar um modelo de classificação de imagens
O trabalho de processamento do SageMaker Clarify explica as imagens usando o algoritmo KernelShap, que trata a imagem como uma coleção de superpixels. Dado um conjunto de dados que consiste em imagens, o trabalho de processamento gera um conjunto de dados de imagens em que cada imagem mostra o mapa de calor dos superpixels relevantes.
O exemplo de configuração a seguir mostra como configurar uma análise de explicabilidade usando um modelo de classificação de SageMaker imagens. Consulte [Classificação de imagens - MXNet](image-classification.md) para obter mais informações.
```
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",
)
```
No exemplo de configuração anterior, um modelo chamado `your_cv_ic_model` foi treinado para classificar os animais nas imagens JPEG de entrada. O `ModelConfig` objeto no exemplo anterior instrui o trabalho de processamento do SageMaker Clarify a implantar o modelo de SageMaker IA em um endpoint temporário. Para inferência acelerada, o endpoint usa uma instância de inferência `ml.p2.xlarge` equipada com uma GPU.
Depois que uma imagem JPEG é enviada para um endpoint, o endpoint a classifica e retorna uma lista de pontuações. Cada pontuação refere-se a uma categoria. O objeto`ModelPredictedLabelConfig` fornece o nome de cada categoria da seguinte forma:
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
Um exemplo de saída para a entrada anterior de ['bird','cat','dog'] poderia ser 0,3, 0,6, 0,1, onde 0,3 representa a pontuação de confiança para classificar uma imagem como um pássaro.
O exemplo de configuração SHAP a seguir mostra como gerar explicações para um problema de classificação de imagens. Ele usa um objeto `ImageConfig` para ativar a análise.
```
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 O Clarify extrai recursos usando o método [Simple Linear Iterative Clustering (SLIC)](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) da biblioteca scikit-learn para segmentação de imagens. O exemplo de configuração anterior, o parâmetro `model_type`, indica o tipo de problema de classificação da imagem. O parâmetro `num_segments` estima quantos segmentos aproximados serão rotulados na imagem de entrada. Então, o número de segmentos é passado para o parâmetro slic `n_segments`.
Cada segmento da imagem é considerado um superpixel e os valores SHAP locais são calculados para cada segmento. O parâmetro `segment_compactness` determina a forma e o tamanho dos segmentos da imagem que são gerados pelo método scikit-image slic. Os tamanhos e formas dos segmentos da imagem são então passados para o parâmetro slic `compactness`.
O exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para gerar mapas de calor para suas imagens. Valores positivos do mapa de calor mostram que o atributo aumentou a pontuação de confiança na detecção do objeto. Valores negativos indicam que o atributo diminuiu a pontuação de confiança.
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=ic_model_config,
model_scores=ic_prediction_config,
explainability_config=ic_shap_config,
)
```
Para um exemplo de caderno que usa o SageMaker Clarify para classificar imagens e explicar sua classificação, consulte [Explicando a classificação de imagens com o SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb).
### Como explicar um modelo de detecção de objetos
Um trabalho de processamento do SageMaker Clarify pode detectar e classificar objetos em uma imagem e, em seguida, fornecer uma explicação para o objeto detectado. O processo de explicação ocorre da seguinte forma:
1. Os objetos de imagem são primeiro categorizados em uma das classes em uma coleção especificada. Por exemplo, se um modelo de detecção de objetos pode reconhecer gatos, cachorros e peixes, essas três classes estão em uma coleção. Essa coleção é especificada pelo parâmetro `label_headers` da seguinte forma:
```
clarify.ModelPredictedLabelConfig(
label_headers=object_categories,
)
```
1. O trabalho de processamento do SageMaker Clarify produz uma pontuação de confiança para cada objeto. Uma pontuação de confiança alta indica que ela pertence a uma das classes em uma coleção especificada. O trabalho de processamento do SageMaker Clarify também produz as coordenadas de uma caixa delimitadora que delimita o objeto. Para obter mais informações sobre pontuações de confiança e caixas delimitadoras, consulte [Formatos de resposta](object-detection-in-formats.md#object-detection-recordio).
1. SageMaker Clarify então fornece uma explicação para a detecção de um objeto na cena da imagem. Ele usa os métodos descritos na seção **Como explicar um modelo de classificação de imagens**.
No exemplo de configuração a seguir, um modelo de detecção de objetos de SageMaker IA `your_cv_od_model` é treinado em imagens JPEG para identificar os animais nelas.
```
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",
)
```
O `ModelConfig` objeto no exemplo de configuração anterior instrui o trabalho de processamento do SageMaker Clarify a implantar o modelo de SageMaker IA em um endpoint temporário. Para a criação de imagem acelerada, este endpoint usa uma instância de inferência `ml.p2.xlarge` equipada com uma GPU.
No exemplo de configuração a seguir, o objeto `ModelPredictedLabelConfig` fornece o nome de cada categoria para classificação.
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
O exemplo de configuração SHAP a seguir mostra como gerar explicações para uma detecção de objetos.
```
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,
)
```
No exemplo de configuração anterior, o objeto `ImageConfig` ativava a análise. O parâmetro `model_type` indica que o tipo de problema é a detecção de objetos. Para uma descrição detalhada dos outros parâmetros, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
O exemplo de código a seguir inicia um trabalho de processamento do SageMaker Clarify para gerar mapas de calor para suas imagens. Valores positivos do mapa de calor mostram que o atributo aumentou a pontuação de confiança na detecção do objeto. Valores negativos indicam que o atributo diminuiu a pontuação de confiança.
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=od_model_config,
model_scores=od_prediction_config,
explainability_config=od_shap_config,
)
```
Para ver um exemplo de caderno que usa o SageMaker Clarify para detectar objetos em uma imagem e explicar suas previsões, consulte [Explicando modelos de detecção de objetos com o Amazon SageMaker AI Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb).
## Analisar explicações para modelos de previsão de séries temporais
Os exemplos a seguir mostram como configurar dados no formato denso SageMaker AI JSON para explicar um modelo de previsão de séries temporais. Para obter mais informações sobre a formatação de JSON, consulte [Formato da solicitação 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
},
]
```
### Configuração de dados
Use `TimeSeriesDataConfig` para que seu trabalho de explicabilidade interprete os dados corretamente a partir do conjunto de dados de entrada passado, conforme mostrado no exemplo de configuração a seguir:
```
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',
)
```
### Configuração de valor assimétrico de Shapley
Use `AsymmetricShapleyValueConfig` para definir argumentos para a análise da explicação do modelo de previsão de séries temporais, como linha de base, direção, granularidade e número de amostras. Os valores da linha de base são definidos para todos os três tipos de dados: séries temporais relacionadas, covariáveis estáticas e séries temporais de destino. A `AsymmetricShapleyValueConfig` configuração informa ao processador do SageMaker Clarify como calcular as atribuições de recursos para um item por vez. A configuração a seguir mostra um exemplo de definição de `AsymmetricShapleyValueConfig`.
```
asymmetric_shapley_value_config = AsymmetricShapleyValueConfig(
direction="chronological",
granularity="fine-grained",
num_samples=10,
baseline={
"related_time_series": "zero",
"static_covariates": {
"item1": [0, 0], "item2": [0, 0]
},
"target_time_series": "zero"
},
)
```
Os valores que você fornece ao `AsymmetricShapleyValueConfig` são passados para a configuração de análise como uma entrada em `methods` com a chave `asymmetric_shapley_value`.
### Configuração do modelo
Você pode controlar a estrutura da carga enviada pelo processador SageMaker Clarify. No exemplo de código a seguir, um objeto de `ModelConfig` configuração direciona um trabalho de explicabilidade de previsão de séries temporais para agregar registros usando a JMESPath sintaxe em`'{"instances": $records}'`, em que a estrutura de cada registro é definida com o seguinte record\_template. `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` Observe que `$start_time`, `$target_time_series`, `$related_time_series` e `$static_covariates` são tokens internos usados para mapear valores de conjuntos de dados para valores de solicitação de 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]'}
)
)
```
Da mesma forma, o atributo `forecast` em `TimeSeriesModelConfig`, passado para a configuração de análise com a chave `time_series_predictor_config`, é usado para extrair a predição de modelo da resposta do endpoint. Por exemplo, um exemplo de resposta em lote de endpoint pode ser:
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
Se a JMESPath expressão fornecida `forecast` for {'predictions [\*] .mean [:2] '}}, o valor da previsão será analisado da seguinte forma:
```
[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]
```
## Como executar trabalhos paralelos de processamento do SageMaker Clarify
Ao trabalhar com grandes conjuntos de dados, você pode usar o [Apache Spark](https://spark.apache.org/) para aumentar a velocidade dos trabalhos de processamento do SageMaker Clarify. O Spark é um mecanismo de analytics unificado para processamento de dados em grande escala. Quando você solicita mais de uma instância por processador do SageMaker Clarify, o SageMaker Clarify usa os recursos de computação distribuída do Spark.
O exemplo de configuração a seguir mostra como usar `SageMakerClarifyProcessor` para criar um processador SageMaker Clarify com instâncias `5` computacionais. Para executar qualquer tarefa associada ao`SageMakerClarifyProcessor`, SageMaker esclareça usando o processamento distribuído do Spark.
```
from sagemaker import clarify
spark_clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=5,
instance_type='ml.c5.xlarge',
)
```
Se você definir o `save_local_shap_values` parâmetro de [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)para`True`, a tarefa de processamento do SageMaker Clarify salvará o SHAP valor local como vários arquivos de peças no local de saída da tarefa.
Para associar os valores SHAP locais às instâncias do conjunto de dados de entrada, use o parâmetro `joinsource` de `DataConfig`. Se você adicionar mais instâncias de computação, recomendamos que você também aumente o `instance_count` of [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)para o endpoint temporário. Isso evita que as solicitações simultâneas de inferência dos operadores do Spark sobrecarreguem o endpoint. Especificamente, recomendamos que você use uma one-to-one proporção de endpoint-to-processing instâncias.