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á.
# Imparcialidade, explicabilidade do modelo e detecção de viés com o Clarify SageMaker
Você pode usar o Amazon SageMaker Clarify para entender a imparcialidade e a explicabilidade do modelo e para explicar e detectar preconceitos em seus modelos. Você pode configurar um trabalho de processamento do SageMaker Clarify para calcular métricas de viés e atribuições de recursos e gerar relatórios para explicar o modelo. SageMaker Os trabalhos de processamento do Clarify são implementados usando uma imagem de contêiner especializada do SageMaker Clarify. A página a seguir descreve como o SageMaker Clarify funciona e como começar com uma análise.
## O que é imparcialidade e explicabilidade do modelo para predições de machine learning?
Modelos de machine learning (ML) estão ajudando a tomar decisões em domínios, como serviços financeiros, saúde, educação e recursos humanos. Políticos, reguladores e defensores levantaram conscientização sobre os desafios éticos e políticos impostos pelo ML e pelos sistemas baseados em dados. O Amazon SageMaker Clarify pode ajudar você a entender por que seu modelo de ML fez uma previsão específica e se esse viés afeta essa previsão durante o treinamento ou a inferência. SageMaker O Clarify também fornece ferramentas que podem ajudá-lo a criar modelos de aprendizado de máquina menos tendenciosos e mais compreensíveis. SageMaker O Clarify também pode gerar modelos de relatórios de governança que você pode fornecer às equipes de risco e conformidade e aos reguladores externos. Com o SageMaker Clarify, você pode fazer o seguinte:
+ Detectar desvio e ajudar a explicar suas predições de modelo.
+ Identificar os tipos de desvio nos dados de pré-treinamento.
+ Identificar vários tipos de vieses nos dados de pós-treinamento que podem surgir durante o treinamento do modelo ou quando o modelo estiver em produção.
SageMaker O Clarify ajuda a explicar como seus modelos fazem previsões usando atribuições de recursos. Ele também monitora os modelos de inferência que estão em produção para desvios de atribuição de atributos e vieses. As informações podem ajudar nas seguintes áreas:
+ **Regulatória**: Os formuladores de políticas e outros reguladores podem se preocupar com os impactos discriminatórios das decisões que usam resultados de modelos de ML. Por exemplo, um modelo de ML pode codificar preconceitos e influenciar uma decisão automatizada.
+ **Negócios**: Os domínios regulamentados podem precisar de explicações confiáveis sobre como os modelos de ML fazem predições. A explicabilidade do modelo pode ser particularmente importante para setores que dependem de confiabilidade, segurança e conformidade. Isso pode incluir serviços financeiros, recursos humanos, assistência médica e transporte automatizado. Por exemplo, as aplicações de empréstimo podem precisar fornecer explicações sobre como os modelos de ML fizeram determinadas predições para agentes de crédito, analistas e clientes.
+ **Ciência de dados:** cientistas de dados e engenheiros de ML podem depurar e melhorar modelos de ML quando podem determinar se um modelo está fazendo inferências com base em atributos inconsistentes ou irrelevantes. Eles também podem entender as limitações de seus modelos e as falhas que seus modelos podem ter.
Para uma postagem no blog que mostra como arquitetar e criar um modelo completo de aprendizado de máquina para reclamações fraudulentas de automóveis que integre o SageMaker Clarify a um pipeline de SageMaker IA, consulte o [Architect e crie o ciclo de vida completo do aprendizado de máquina com: AWS Uma](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) demonstração da Amazon AI. end-to-end SageMaker A postagem discute como avaliar e corrigir vieses antes e depois do treinamento, além de explicar como os atributos impactam a predição de modelo. Ela contém links para exemplos de código para cada tarefa no ciclo de vida do ML.
### Melhores práticas para avaliar a imparcialidade e a explicabilidade no ciclo de vida de ML
**Imparcialidade como processo**: As noções de desvio e imparcialidade dependem da aplicação. A medição do desvio e a escolha das métricas de desvio podem ser orientadas por considerações sociais, legais e coisas não técnicas. A adoção bem-sucedida de abordagens de ML conscientes inclui criar consenso e alcançar a colaboração entre as principais partes interessadas. Isso pode incluir produtos, políticas, questões jurídicas, de engenharia, AI/ML equipes, usuários finais e comunidades.
**Imparcialidade e explicabilidade por design no ciclo de vida de ML**: Considere a imparcialidade e a explicabilidade durante cada estágio do ciclo de vida do ML. Esses estágios incluem formação de problemas, construção de conjuntos de dados, seleção de algoritmos, processo de treinamento de modelos, processo de teste, implantação e monitoramento, além do feedback. É importante ter as ferramentas certas para fazer essa análise. Recomendamos fazer as seguintes perguntas durante o ciclo de vida de ML:
+ O modelo incentiva ciclos de feedback que podem produzir resultados cada vez mais injustos?
+ Um algoritmo é uma solução ética para o problema?
+ Os dados de treinamento possuem representatividade?
+ Há preconceitos nos rótulos ou nos atributos?
+ Os dados precisam ser modificados para mitigar o desvio?
+ As restrições de imparcialidade precisam ser incluídas na função objetiva?
+ O modelo foi avaliado com métricas imparciais relevantes?
+ Existem efeitos desiguais entre os usuários?
+ O modelo foi apresentado a uma população para a qual não foi treinado ou avaliado?
![\[Melhores práticas para o processo de avaliação da equidade e da explicabilidade do modelo.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify-best-practices-image.png)
### Guia para explicações sobre SageMaker IA e documentação sobre preconceitos
O desvio pode ocorrer e ser avaliado nos dados antes e depois do treinamento do modelo. SageMaker O Clarify pode fornecer explicações para as previsões do modelo após o treinamento e para os modelos implantados na produção. SageMaker O Clarify também pode monitorar modelos em produção para detectar qualquer variação em suas atribuições explicativas de linha de base e calcular linhas de base quando necessário. A documentação para explicar e detectar preconceitos usando o SageMaker Clarify está estruturada da seguinte forma:
+ Para obter informações sobre como configurar um trabalho de processamento para desvio e explicabilidade, consulte [Configurar um SageMaker Clarify Processing Job](clarify-processing-job-configure-parameters.md).
+ Para obter informações sobre a detecção de desvio no pré-processamento de dados antes de serem usados para treinar um modelo, consulte [Desvio nos dados de pré-treinamento](clarify-detect-data-bias.md).
+ Para obter informações sobre a detecção de desvio no pós-treinamento de dados do modelo, consulte [Dados de pós-treinamento e desvio do modelo](clarify-detect-post-training-bias.md).
+ Para obter informações sobre a abordagem de atribuição de atributos para explicar as predições de modelo dele após o treinamento, consulte [Explicabilidade do modelo](clarify-model-explainability.md).
+ Para obter informações sobre o monitoramento do desvio das contribuições dos atributos em relação à linha de base que foi estabelecida durante o treinamento de modelo, consulte [Desvio de atribuição de atributos para modelos em produção](clarify-model-monitor-feature-attribution-drift.md).
+ Para obter informações sobre o monitoramento de modelos que estão em produção para o desvio da linha de base, consulte [Desvio de polarização para modelos em produção](clarify-model-monitor-bias-drift.md).
+ Para obter informações sobre como obter explicações em tempo real de um endpoint de SageMaker IA, consulte. [Explicabilidade on-line com Clarify SageMaker](clarify-online-explainability.md)
## Como funcionam os trabalhos de processamento do SageMaker Clarify
Você pode usar o SageMaker Clarify para analisar seus conjuntos de dados e modelos quanto à explicabilidade e ao viés. Um trabalho de processamento do SageMaker Clarify usa o contêiner de processamento do SageMaker Clarify para interagir com um bucket do Amazon S3 contendo seus conjuntos de dados de entrada. Você também pode usar o SageMaker Clarify para analisar um modelo de cliente implantado em um endpoint de inferência de SageMaker IA.
O gráfico a seguir mostra como uma tarefa de processamento do SageMaker Clarify interage com seus dados de entrada e, opcionalmente, com um modelo de cliente. Essa interação depende do tipo específico de análise que está sendo realizada. O contêiner de processamento SageMaker Clarify obtém o conjunto de dados de entrada e a configuração para análise de um bucket S3. Para determinados tipos de análise, incluindo análise de recursos, o contêiner de processamento do SageMaker Clarify deve enviar solicitações ao contêiner modelo. Em seguida, ele recupera as predições de modelo a partir da resposta que o contêiner do modelo envia. Depois disso, o contêiner de processamento do SageMaker Clarify calcula e salva os resultados da análise no bucket do S3.
![\[SageMaker O Clarify pode analisar seus dados ou um modelo de cliente em busca de explicabilidade e viés.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/clarify-processing-job.png)
Você pode executar uma tarefa de processamento do SageMaker Clarify em vários estágios do ciclo de vida do fluxo de trabalho de aprendizado de máquina. SageMaker O Clarify pode ajudá-lo a calcular os seguintes tipos de análise:
+ Métricas de desvio pré-treinamento. As métricas podem ajudá-lo a entender vieses em seus dados para que você possa abordá-los e treinar seu modelo em um conjunto de dados mais justo. Consulte [Métricas de desvio pré-treinamento](clarify-measure-data-bias.md) para obter informações sobre métricas de desvio pré-treinamento. Para executar um trabalho de análise de métricas de desvio pré-treinamento, você deve fornecer o conjunto de dados e um arquivo de configuração de análise JSON para [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
+ Métricas de desvio do pós-treinamento. As métricas podem ajudá-lo a entender qualquer desvio introduzido por um algoritmo, escolhas de hiperparâmetros ou qualquer desvio que não tenha sido aparente no início do fluxo. Para obter mais informações sobre métricas de viés pós-treinamento, consulte[Métricas de dados pós-treinamento e desvio do modelo](clarify-measure-post-training-bias.md). SageMaker O Clarify usa as previsões do modelo, além dos dados e rótulos, para identificar o viés. Para executar um trabalho de análise de métricas de desvio pós-treinamento, você deve fornecer o conjunto de dados e um arquivo de configuração de análise JSON. A configuração deve incluir o nome do modelo ou do endpoint.
+ Valores Shapley, que podem ajudá-lo a entender o impacto que seu atributo tem sobre o que seu modelo prevê. Para obter mais informações sobre valores Shapley, consulte [Atributos de atributos que usam valores de Shapley](clarify-shapley-values.md). Esse atributo exige um modelo treinado.
+ Gráficos de dependência parcial (PDPs), que podem ajudá-lo a entender o quanto sua variável-alvo prevista mudaria se você variasse o valor de um recurso. Para obter mais informações sobre PDPs, consulte [Análise de gráficos de dependência parcial (PDPs)](clarify-processing-job-analysis-results.md#clarify-processing-job-analysis-results-pdp) Esse recurso requer um modelo treinado.
SageMaker Esclareça as previsões do modelo de necessidades para calcular métricas de viés pós-treinamento e atribuições de recursos. *Você pode fornecer um endpoint ou o SageMaker Clarify criará um endpoint efêmero usando o nome do seu modelo, também conhecido como endpoint sombra.* O contêiner SageMaker Clarify exclui o endpoint de sombra após a conclusão dos cálculos. Em um nível alto, o contêiner SageMaker Clarify conclui as seguintes etapas:
1. Validação de entradas e parâmetros.
1. Criação do endpoint de sombra (se um nome de modelo for fornecido).
1. Carregamento do conjunto de dados de entrada em um quadro de dados.
1. Obtenção das predições de modelo a partir do endpoint, se necessário.
1. Cálculo das métricas de desvio e atribuições de atributos.
1. Exclusão do endpoint de sombra.
1. Geração dos resultados da análise.
Depois que a tarefa de processamento do SageMaker Clarify for concluída, os resultados da análise serão salvos no local de saída que você especificou no parâmetro de saída de processamento da tarefa. Esses resultados incluem um arquivo JSON com métricas de desvio e atribuições de atributos globais, um relatório visual e arquivos adicionais para atribuições de atributos locais. Você pode baixar os resultados do local de saída e visualizá-los.
Para obter informações adicionais sobre métricas de viés, explicabilidade e como interpretá-las, consulte [Saiba como o Amazon SageMaker Clarify ajuda a detectar preconceitos](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 o whitepaper [Amazon AI Fairness](https://pages.awscloud.com/rs/112-TZM-766/images/Amazon.AI.Fairness.and.Explainability.Whitepaper.pdf) and Explainability.
# Configurar um SageMaker Clarify Processing Job
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 especificar o nome do conjunto de dados de entrada, o nome do arquivo de configuração de análise e o local de saída para um trabalho de processamento. Para configurar o contêiner de processamento, entradas, saídas, recursos e outros parâmetros de trabalhos, você tem duas opções. Você pode usar a `CreateProcessingJob` API SageMaker AI ou usar a API SageMaker AI Python SDK, `SageMaker ClarifyProcessor`
Para obter informações sobre parâmetros que são comuns a todos os trabalhos de processamento, consulte [Amazon SageMaker API Reference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp).
## Configurar um trabalho de processamento do SageMaker Clarify usando a SageMaker API
As instruções a seguir mostram como fornecer cada parte da configuração específica do SageMaker Clarify usando a `CreateProcessingJob` API.
1. Insira o identificador uniforme de pesquisa (URI) de uma imagem do contêiner SageMaker Clarify dentro do `AppSpecification` parâmetro, conforme mostrado no exemplo de código a seguir.
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**nota**
O URI deve identificar uma imagem pré-criada do contêiner SageMaker Clarify. `ContainerEntrypoint`e não `ContainerArguments` são compatíveis. Para obter mais informações sobre imagens de contêiner do SageMaker Clarify, consulte[Contêineres SageMaker Clarify pré-construídos](clarify-processing-job-configure-container.md).
1. Especifique a configuração para sua análise e os parâmetros para seu conjunto de dados de entrada dentro do parâmetro `ProcessingInputs`.
1. Especifique a localização do arquivo de configuração de análise JSON, que inclui os parâmetros para análise de desvio e análise de explicabilidade. O parâmetro `InputName` do objeto `ProcessingInput` deve ser **analysis\$1config**, conforme mostrado no exemplo de código a seguir.
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
Para obter mais informações sobre o esquema do arquivo de configuração da análise, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
1. Especifique o local do conjunto de dados de entrada. O parâmetro `InputName` do objeto `ProcessingInput` deve ser `dataset`. Esse parâmetro é opcional se você tiver fornecido o “dataset\$1uri” no arquivo de configuração da análise. Os valores a seguir são obrigatórios na configuração `S3Input`.
1. `S3Uri` pode ser um objeto do Amazon S3 ou um prefixo do S3.
1. `S3InputMode` deve ser do tipo **File**.
1. `S3CompressionType` deve ser do tipo `None` (o valor padrão).
1. `S3DataDistributionType` deve ser do tipo `FullyReplicated` (o valor padrão).
1. `S3DataType` pode ser `S3Prefix` ou `ManifestFile`. Para ser usado`ManifestFile`, o `S3Uri` parâmetro deve especificar a localização de um arquivo de manifesto que segue o esquema da seção Referência da SageMaker API [S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri). Esse arquivo manifesto deve listar os objetos do S3 que contêm os dados de entrada para o trabalho.
O código a seguir mostra um exemplo de configuração da entrada.
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. Especifique a configuração para a saída do trabalho de processamento dentro do parâmetro `ProcessingOutputConfig`. É necessário um único objeto `ProcessingOutput` na configuração `Outputs`. Os dados a seguir são obrigatórios na configuração de saída:
1. `OutputName` deve ser **analysis\$1result**.
1. `S3Uri` deve ser um prefixo do S3 para o local de saída.
1. `S3UploadMode` deve ser definido como **EndOfJob**.
O código a seguir mostra um exemplo de configuração de saída.
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. Especifique a configuração `ClusterConfig` dos recursos que você usa em seu trabalho de processamento dentro do parâmetro `ProcessingResources`. Os seguintes parâmetros são obrigatórios dentro do objeto `ClusterConfig`:
1. `InstanceCount` especifica o número de instâncias de computação no cluster que executa o trabalho de processamento. Especifique um valor maior que `1` para ativar o processamento distribuído.
1. `InstanceType` refere-se aos recursos que executam seu trabalho de processamento. Como a análise do SageMaker AI SHAP exige muita computação, o uso de um tipo de instância otimizado para computação deve melhorar o tempo de execução da análise. A tarefa de processamento do SageMaker Clarify não usa GPUs.
O código a seguir mostra um exemplo de configuração de recursos.
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. Especifique a configuração da rede que você usa em seu trabalho de processamento dentro do objeto `NetworkConfig`. Os valores a seguir são obrigatórios na configuração.
1. `EnableNetworkIsolation`deve ser definido como `False` (padrão) para que o SageMaker Clarify possa invocar um endpoint, se necessário, para previsões.
1. Se o modelo ou endpoint que você forneceu para o trabalho do SageMaker Clarify estiver dentro de uma Amazon Virtual Private Cloud (Amazon VPC), o trabalho SageMaker do Clarify também deverá estar na mesma VPC. Especifique a VPC usando. [VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html) Além disso, a VPC deve ter endpoints para um bucket Amazon S3, serviço de IA e serviço SageMaker AI Runtime. SageMaker
Se o processamento distribuído estiver ativado, você precisará permitir a comunicação entre as diferentes instâncias no mesmo trabalho de processamento. Configure uma regra para seu grupo de segurança que permita conexões de entrada entre membros do mesmo grupo de segurança. Para obter mais informações, consulte [Dê ao Amazon SageMaker Clarify Jobs acesso aos recursos em sua Amazon VPC](clarify-vpc.md).
O código a seguir mostra um exemplo de uma configuração de rede.
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. Defina o tempo máximo em que o trabalho será executado usando o parâmetro `StoppingCondition`. O tempo máximo que uma tarefa do SageMaker Clarify pode ser executada é de `7` dias ou `604800` segundos. Se o trabalho não puder ser concluído dentro desse prazo, ele será interrompido e nenhum resultado de análise será fornecido. Como exemplo, a configuração a seguir limita o tempo máximo que o trabalho pode ser executado a 3600 segundos.
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. Especifique um perfil do IAM para o parâmetro `RoleArn`. A função deve ter uma relação de confiança com a Amazon SageMaker AI. Ele pode ser usado para realizar as operações de SageMaker API listadas na tabela a seguir. Recomendamos usar a política gerenciada do Amazon SageMaker AIFull Access, que concede acesso total à SageMaker IA. Para obter mais informações sobre essa política, consulte [AWS política gerenciada: AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess). Se você tiver dúvidas sobre a concessão de acesso total, as permissões mínimas necessárias dependerão de você fornecer um modelo ou um nome de endpoint. Usar um nome de endpoint permite conceder menos permissões à SageMaker IA.
A tabela a seguir contém as operações de API usadas pela tarefa de processamento do SageMaker Clarify. Um **X** abaixo do **nome do modelo** e do **nome do endpoint** indica a operação de API que é necessária para cada entrada.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
Para obter mais informações sobre as permissões necessárias, consulte [Permissões da API Amazon SageMaker AI: referência de ações, permissões e recursos](api-permissions-reference.md).
Para obter mais informações sobre a transferência de funções para a SageMaker IA, consulte[Perfis de aprovação](sagemaker-roles.md#sagemaker-roles-pass-role).
Depois de configurar as partes individuais do trabalho de processamento, combine-as para configurar o trabalho.
## Configurar uma tarefa de processamento do SageMaker Clarify usando o AWS SDK para Python
O exemplo de código a seguir mostra como iniciar uma tarefa de processamento do SageMaker Clarify usando o [AWS SDK para 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",
)
```
Para ver um exemplo de notebook com instruções para executar uma tarefa de processamento do SageMaker Clarify usando o AWS SDK para Python, [consulte Imparcialidade e explicabilidade com o SageMaker Clarify](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb) usando o SDK for Python. AWS Qualquer bucket do S3 usado no notebook deve estar na mesma AWS região da instância do notebook que o acessa.
## Configurar uma tarefa de processamento do SageMaker Clarify usando o SDK do SageMaker Python
Você também pode configurar uma tarefa de processamento do SageMaker Clarify usando a [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)API do SDK do SageMaker Python. Para obter mais informações, consulte [Execute trabalhos de processamento do SageMaker Clarify para análise de viés e explicabilidade](clarify-processing-job-run.md).
**Topics**
+ [Contêineres SageMaker Clarify pré-construídos](clarify-processing-job-configure-container.md)
+ [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md)
+ [Guia de compatibilidade de formato de dados](clarify-processing-job-data-format.md)
# Contêineres SageMaker Clarify pré-construídos
A Amazon SageMaker AI fornece imagens de contêiner pré-criadas do SageMaker Clarify que incluem as bibliotecas e outras dependências necessárias para calcular métricas de viés e atribuições de recursos para fins de explicabilidade. Essas imagens são capazes de executar [trabalhos de processamento](processing-job.md) do SageMaker Clarify em sua conta.
A imagem URIs dos contêineres está no seguinte formato:
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
Por exemplo:
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
A tabela a seguir lista os endereços por Região da AWS.
Imagens do Docker para trabalhos de processamento do SageMaker Clarify
| Região | Endereço da imagem |
| --- | --- |
| Leste dos EUA (Norte da Virgínia) | 205585389593.dkr. ecr.us-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Leste dos EUA (Ohio) | 211330385671.dkr. ecr.us-east-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Oeste dos EUA (N. da Califórnia) | 740489534195.dkr. ecr.us-west-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Oeste dos EUA (Oregon) | 306415355426.dkr. ecr.us-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Hong Kong) | 098760798382.dkr. ecr.ap-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Mumbai) | 452307495513.dkr. ecr.ap-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Jacarta) | 705930551576.dkr. ecr.ap-southeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Tóquio) | 377024640650.dkr. ecr.ap-northeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Seul) | 263625296855.dkr. ecr.ap-northeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Osaka) | 912233562940.dkr. ecr.ap-northeast-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Singapura) | 834264404009.dkr. ecr.ap-southeast-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Ásia-Pacífico (Sydney) | 007051062584.dkr. ecr.ap-southeast-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Canadá (Central) | 675030665977.dkr. ecr.ca-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Frankfurt) | 017069133835.dkr. ecr.eu-central-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Zurique) | 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 (Londres) | 440796970383.dkr. ecr.eu-west-2.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Paris) | 341593696636.dkr. ecr.eu-west-3.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Estocolmo) | 763603941244.dkr. ecr.eu-north-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Oriente Médio (Bahrein) | 835444307964.dkr. ecr.me-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| América do Sul (São Paulo) | 520018980103.dkr. ecr.sa-east-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| África (Cidade do Cabo) | 811711786498.dkr. ecr.af-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| Europa (Milão) | 638885417683.dkr. ecr.eu-south-1.amazonaws.com /:1.0 sagemaker-clarify-processing |
| China (Pequim) | 122526803553.dkr. ecr.cn-north-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
| China (Ningxia) | 122578899357.dkr. ecr.cn-northwest-1.amazonaws.com .cn/:1.0 sagemaker-clarify-processing |
# Arquivos de configuração de análise
Para analisar seus dados e modelos quanto à explicabilidade e ao viés usando o SageMaker Clarify, você deve configurar uma tarefa de processamento. Parte da configuração desse trabalho de processamento inclui a configuração de um arquivo de análise. O arquivo de análise especifica os parâmetros para análise de desvio e explicabilidade. Consulte [Configurar um SageMaker Clarify Processing Job](clarify-processing-job-configure-parameters.md) para saber como configurar um trabalho de processamento e um arquivo de análise.
Este guia descreve o esquema e os parâmetros desse arquivo de configuração de análise. O guia também inclui exemplos de arquivos de configuração de análise para calcular métricas de desvio para um conjunto de dados tabular e gerar explicações para problemas de processamento de linguagem natural (PLN), visão computacional (CV) e séries temporais (TS).
Você pode criar o arquivo de configuração de análise ou usar o [SDK do SageMaker Python](https://sagemaker.readthedocs.io/) para gerar um para você com a API. [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor) A visualização do conteúdo do arquivo pode ser útil para entender a configuração subjacente usada pela tarefa do SageMaker Clarify.
**Topics**
+ [Esquema para o arquivo de configuração de análise](#clarify-processing-job-configure-schema)
+ [Exemplo de arquivos de configuração de análise](#clarify-processing-job-configure-analysis-examples)
## Esquema para o arquivo de configuração de análise
A seção a seguir descreve o esquema do arquivo de configuração de análise, incluindo requisitos e descrições dos parâmetros.
### Requisitos para o arquivo de configuração de análise
O trabalho de processamento do SageMaker Clarify espera que o arquivo de configuração da análise seja estruturado com os seguintes requisitos:
+ O nome da entrada de processamento deve ser `analysis_config.`
+ O arquivo de configuração de análise está no formato JSON e codificado em UTF-8.
+ O arquivo de configuração de análise é um objeto do Amazon S3.
Você pode especificar parâmetros adicionais no arquivo de configuração da análise. A seção a seguir fornece várias opções para personalizar a tarefa de processamento do SageMaker Clarify para seu caso de uso e tipos de análise desejados.
### Parâmetros para arquivos de configuração de análise
No arquivo de configuração da análise, é possível especificar parâmetros a seguir.
+ **versão**: (Opcional) A string de versão do esquema do arquivo de configuração de análise. Se uma versão não for fornecida, o SageMaker Clarify usará a versão mais recente compatível. Atualmente, a única versão compatível é `1.0`.
+ **dataset\$1type**: O formato do conjunto de dados. O formato do conjunto de dados de entrada pode ser qualquer um dos seguintes valores:
+ Tabular
+ `text/csv` para CSV
+ `application/jsonlines`para formato [denso de linhas SageMaker AI JSON](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)
+ `application/json` para JSON
+ `application/x-parquet` para Apache Parquet
+ `application/x-image` para ativar a explicabilidade para problemas de visão computacional
+ Explicações do modelo de previsão de séries temporais
+ `application/json` para JSON
+ **dataset\$1uri**: (Opcional) O identificador de recursos uniforme (URI) do conjunto de dados principal. 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. Você pode fornecer um prefixo de URI do S3 ou URI do S3 para um arquivo manifesto de imagem para problemas de visão computacional. Se o `dataset_uri` for fornecido, ele terá precedência sobre a entrada do trabalho de processamento do conjunto de dados. Para qualquer tipo de formato, exceto casos de uso de imagens e séries temporais, o trabalho de processamento do SageMaker Clarify carrega o conjunto de dados de entrada em um quadro de dados tabular, como um conjunto de dados **tabular**. Esse formato permite que a SageMaker IA manipule e analise facilmente o conjunto de dados de entrada.
+ **headers**: (Opcional)
+ **Tabular:** uma matriz de strings contendo os nomes das colunas de um conjunto de dados tabular. Se um valor não for fornecido`headers`, o trabalho de processamento do SageMaker Clarify lê os cabeçalhos do conjunto de dados. Se o conjunto de dados não tiver cabeçalhos, o trabalho de processamento do Clarify gerará automaticamente nomes para espaços reservados baseados no índice de coluna com base em zero. Por exemplo, os nomes dos espaços reservados para a primeira e a segunda colunas serão **column\$10** e **column\$11**.
**nota**
Por convenção, se `dataset_type` for `application/jsonlines` ou `application/json`, então `headers` deve conter os seguintes nomes em ordem:
nomes de atributo
nome do rótulo (se `label` for especificado)
nome do rótulo previsto (se `predicted_label` for especificado)
Um exemplo de `headers` para um tipo de conjunto de dados `application/jsonlines`, se o `label` for especificado, é: `["feature1","feature2","feature3","target_label"]`.
+ **Time series:** uma lista de nomes de colunas no conjunto de dados. Se isso não for fornecido, o Clarify gera cabeçalhos para uso interno. Para casos de explicabilidade de séries temporais, forneça cabeçalhos na seguinte ordem:
1. ID do item
1. timestamp
1. séries temporais de destino
1. todas as colunas de séries temporais relacionadas
1. todas as colunas de covariáveis estáticas
+ **label**: (Opcional) Uma string ou um índice inteiro baseado em zero. Se fornecido, o `label` é usado para localizar o rótulo de veracidade, também conhecido como rótulo observado ou atributo de destino em um conjunto de dados tabular. O rótulo de veracidade é usado para calcular métricas de desvio. O valor para `label` é especificado de acordo com o valor do parâmetro `dataset_type` da seguinte forma:
+ Se `dataset_type` for **text/csv**, o `label` pode ser especificado como uma das seguintes opções:
+ Um nome de coluna válido
+ Um índice que está dentro do intervalo de colunas do conjunto de dados
+ Se `dataset_type` for **application/parquet**, o `label` deve ser um nome de coluna válido.
+ Se `dataset_type` for**application/jsonlines**, `label` deve ser uma [JMESPath](https://jmespath.org/)expressão escrita para extrair o rótulo de verdade fundamental do conjunto de dados. Por convenção, se `headers` for especificado, ele deverá conter o nome do rótulo.
+ Se `dataset_type` for**application/json**, `label` deve ser uma [JMESPath](https://jmespath.org/)expressão escrita para extrair o rótulo de verdade fundamental para cada registro no conjunto de dados. Essa JMESPath expressão deve produzir uma lista de rótulos em que o i the label se correlaciona com o i no registro.
+ **predicted\$1label**: (Opcional) Uma string ou um índice inteiro baseado em zero. Se fornecido, o `predicted_label` é usado para localizar a coluna que contém o rótulo previsto em um conjunto de dados tabular. O rótulo previsto é usado para calcular **métricas de desvio** pós-treinamento. O parâmetro `predicted_label` é opcional se o conjunto de dados não incluir o rótulo previsto. Se rótulos previstos forem necessários para o cálculo, o trabalho de processamento do SageMaker Clarify obterá previsões do modelo.
O valor para `predicted_label` é especificado de acordo com o valor do `dataset_type` da seguinte forma:
+ Se `dataset_type` for **text/csv**, o `predicted_label` pode ser especificado como uma das seguintes opções:
+ Um nome de coluna válido. Se o `predicted_label_dataset_uri` for especificado, mas o `predicted_label` não for fornecido, o nome padrão do rótulo previsto será “predicted\$1label”.
+ Um índice que está dentro do intervalo de colunas do conjunto de dados. Se o `predicted_label_dataset_uri` for especificado, o índice será usado para localizar a coluna do rótulo previsto no conjunto de dados do rótulo previsto.
+ Se o dataset\$1type for **application/x-parquet**, o `predicted_label` deve ser um nome de coluna válido.
+ Se dataset\$1type for**application/jsonlines**, `predicted_label` deverá ser uma [JMESPath](https://jmespath.org/)expressão válida escrita para extrair o rótulo previsto do conjunto de dados. Por convenção, se o `headers` for especificado, ele deverá conter o nome do rótulo previsto.
+ Se `dataset_type` for**application/json**, `predicted_label` deve ser uma [JMESPath](https://jmespath.org/)expressão escrita para extrair o rótulo previsto para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma lista de rótulos previstos em que o rótulo previsto é para eles no registro.
+ **recursos** — (Opcional) Obrigatório para casos de non-time-series uso se `dataset_type` for `application/jsonlines` ou`application/json`. Uma expressão de JMESPath string escrita para localizar os recursos no conjunto de dados de entrada. Pois`application/jsonlines`, uma JMESPath expressão será aplicada a cada linha para extrair os recursos desse registro. Pois`application/json`, uma JMESPath expressão será aplicada a todo o conjunto de dados de entrada. A JMESPath expressão deve extrair uma lista de listas ou um 2D array/matrix de recursos em que a linha i contém os recursos que se correlacionam aos no registro. Para um `dataset_type` de `text/csv` ou `application/x-parquet`, todas as colunas, exceto as colunas do rótulo de veracidade e do rótulo previsto, são automaticamente atribuídas como atributos.
+ **predicted\$1label\$1dataset\$1uri**: (opcional) aplicável somente quando dataset\$1type for `text/csv`. O URI do S3 para um conjunto de dados contendo rótulos previstos usados para calcular **métricas de desvio** pós-treinamento. O trabalho de processamento do SageMaker Clarify carregará as previsões do URI fornecido em vez de obter previsões do modelo. Nesse caso, o `predicted_label` é obrigatório para localizar a coluna do rótulo previsto no conjunto de dados do rótulo previsto. Se o conjunto de dados do rótulo previsto ou o conjunto de dados principal estiver dividido em vários arquivos, uma coluna identificadora deverá ser especificada por `joinsource_name_or_index` para unir os dois conjuntos de dados.
+ **predicted\$1label\$1headers**: (opcional) aplicável somente quando `predicted_label_dataset_uri` for especificado. Uma matriz de strings contendo os nomes de colunas do conjunto de dados do rótulo previsto. Além do cabeçalho do rótulo previsto, o `predicted_label_headers` também pode conter o cabeçalho da coluna identificadora para unir o conjunto de dados do rótulo previsto e o conjunto de dados principal. Para obter mais informações, consulte a descrição do parâmetro `joinsource_name_or_index` a seguir.
+ **joinsource\$1name\$1or\$1index**: (opcional) o nome ou índice baseado em zero da coluna em conjuntos de dados tabulares a ser usado como uma coluna identificadora ao realizar uma junção interna. Essa coluna é usada somente como um identificador. Ela não é usada para nenhum outro cálculo, como análise de desvio ou análise de atribuição de atributos. Um valor para o `joinsource_name_or_index` é necessário nos seguintes casos:
+ Existem vários conjuntos de dados de entrada e qualquer um é dividido em vários arquivos.
+ O processamento distribuído é ativado definindo a tarefa de processamento do SageMaker Clarify [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)com um valor maior que `1` o.
+ **excluded\$1columns**: (opcional) uma matriz de nomes ou índices de colunas baseados em zero a serem excluídos do envio ao modelo como entrada para predições. O rótulo de veracidade e o rótulo previsto já foram excluídos automaticamente. Esse atributo não é compatível com séries temporais.
+ **probability\$1threshold**: (opcional) um número de ponto flutuante acima do qual um rótulo ou objeto é selecionado. O valor padrão é `0.5`. A tarefa de processamento do SageMaker Clarify é usada `probability_threshold` nos seguintes casos:
+ Na análise de desvio pós-treinamento, o `probability_threshold` converte uma predição de modelo numérico (valor ou pontuação de probabilidade) em um rótulo binário, se o modelo for um classificador binário. Uma pontuação maior que o limite é convertida em `1`. Por outro lado, uma pontuação menor ou igual ao limite é convertida em `0`.
+ Em problemas de explicabilidade de visão computacional, se o model\$1type for **OBJECT\$1DETECTION**, o `, probability_threshold` filtra objetos detectados com pontuações de confiança inferiores ao valor limite.
+ **label\$1values\$1or\$1threshold**: (opcional) obrigatório para análise de vieses. Uma matriz de valores de rótulo ou um número limite, que indicam um resultado positivo para rótulos de veracidade e previstos para métricas de desvio. Para obter mais informações, consulte valores de rótulos positivos em [A Amazon SageMaker esclarece os termos de preconceito e imparcialidade](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Se o rótulo for numérico, o limite será aplicado como limite inferior para selecionar o resultado positivo. Para definir `label_values_or_threshold` para diferentes tipos de problema, consulte os seguintes exemplos:
+ Para um problema de classificação binária, o rótulo tem dois valores possíveis, `0` e `1`. Se o valor do rótulo `1` for favorável a um grupo demográfico observado em uma amostra, então o `label_values_or_threshold` deverá ser definido como `[1]`.
+ Para um problema de classificação multiclasse, o rótulo tem três valores possíveis, **bird**, **cat** e **dog**. Se os dois últimos definirem um grupo demográfico que o desvio favorece, então o `label_values_or_threshold` deve ser definido como `["cat","dog"]`.
+ Para um problema de regressão, o valor do rótulo é contínuo, variando de `0` a `1`. Se um valor maior do que `0.5` designar uma amostra como tendo um resultado positivo, então o `label_values_or_threshold` deve ser definido como `0.5`.
+ **facet**: (opcional) obrigatório para análise de vieses. Uma matriz de objetos facetários, que são compostos por atributos confidenciais contra os quais o desvio é medido. Você pode usar facetas para entender as características de desvio do seu conjunto de dados e modelo, mesmo que seu modelo seja treinado sem usar atributos confidenciais. Para mais informações, consulte **Facetas** em [A Amazon SageMaker esclarece os termos de preconceito e imparcialidade](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms). Cada objeto de faceta inclui os seguintes campos:
+ **name\$1or\$1index**: (Opcional) O nome ou índice baseado em zero da coluna de atributos confidenciais em um conjunto de dados tabular. Se o `facet_dataset_uri` for especificado, o índice se referirá ao conjunto de dados da faceta em vez do conjunto de dados principal.
+ **value\$1or\$1threshold**: (Opcional) Obrigatório se `facet` for numérico e o `label_values_or_threshold` for aplicado como limite inferior para selecionar o grupo sensível. Uma matriz de valores facetários ou um número limite, que indica o grupo demográfico confidencial que o desvio favorece. Se o tipo de dados da faceta for categórico e o `value_or_threshold` não for fornecido, as métricas de desvio serão calculadas como um grupo para cada valor exclusivo (em vez de todos os valores). Para definir o `value_or_threshold` para diferentes tipos de problemas de `facet`, consulte os seguintes exemplos:
+ Para um tipo de dados de faceta binária, o atributo tem dois valores possíveis, `0` e `1`. Se você quiser calcular as métricas de desvio para cada valor, então o `value_or_threshold` pode ser omitido ou definido como uma matriz vazia.
+ Para um tipo de dados de faceta categórica, o atributo tem três valores possíveis, **bird**, **cat** e **dog**. Se os dois primeiros definirem um grupo demográfico que o desvio favorece, então o `value_or_threshold` deve ser definido como `["bird", "cat"]`. Neste exemplo, as amostras do conjunto de dados são divididas em dois grupos demográficos. A faceta do grupo favorecido tem valor **bird** ou **cat**, enquanto a faceta do grupo desfavorecido tem valor **dog**.
+ Para um tipo de dados de faceta numérica, o valor do atributo é contínuo, variando de `0` a `1`. Por exemplo, se um valor maior do que `0.5` designar uma amostra como favorecida, então o `value_or_threshold` deve ser definido como `0.5`. Neste exemplo, as amostras do conjunto de dados são divididas em dois grupos demográficos. A faceta do grupo favorecido tem valor superior a `0.5`, enquanto a faceta do grupo desfavorecido tem valor inferior ou igual a `0.5`.
+ **group\$1variable**: (Opcional) O nome ou índice baseado em zero da coluna que indica o subgrupo a ser usado para a métrica de desvio [Disparidade demográfica condicional (CDD)](clarify-data-bias-metric-cddl.md) ou [Disparidade demográfica condicional em rótulos previstos (CDDPL)](clarify-post-training-bias-metric-cddpl.md).
+ **facet\$1dataset\$1uri**: (Opcional) Aplicável somente quando o dataset\$1type for `text/csv`. O URI do S3 para um conjunto de dados contendo atributos confidenciais para análise de desvio. Você pode usar facetas para entender as características de desvio do seu conjunto de dados e modelo, mesmo que seu modelo seja treinado sem usar atributos confidenciais.
**nota**
Se o conjunto de dados da faceta ou o conjunto de dados principal estiver dividido em vários arquivos, uma coluna identificadora deverá ser especificada por `joinsource_name_or_index` para unir os dois conjuntos de dados. Você deve usar o parâmetro `facet` para identificar cada faceta no conjunto de dados da faceta.
+ **facet\$1headers**: (Opcional) Aplicável somente quando `facet_dataset_uri` for especificado. Uma matriz de strings contendo nomes de colunas para o conjunto de dados da faceta e, opcionalmente, o cabeçalho da coluna identificadora para unir o conjunto de dados da faceta e o conjunto de dados principal, consulte `joinsource_name_or_index`.
+ **time\$1series\$1data\$1config**: (Opcional) Especifica a configuração a ser usada para processamento de dados de uma série temporal.
+ **item\$1id**: Uma string ou um índice inteiro baseado em zero. Esse campo é usado para localizar um ID de item no conjunto de dados de entrada compartilhado.
+ **timestamp**: Uma string ou um índice inteiro baseado em zero. Esse campo é usado para localizar um registro de data/hora no conjunto de dados de entrada compartilhado.
+ **dataset\$1format**: Os valores possíveis são `columns`, `item_records` ou `timestamp_records`. Esse campo é usado para descrever o formato de um conjunto de dados JSON, que é o único formato compatível com a explicabilidade de séries temporais.
+ **target\$1time\$1series** — Uma JMESPath string ou um índice inteiro baseado em zero. Esse campo é usado para localizar a série temporal de destino no conjunto de dados de entrada compartilhado. Se esse parâmetro for uma string, todos os outros parâmetros, exceto `dataset_format`, deverão ser strings ou listas de strings. Se esse parâmetro for um número inteiro, todos os outros parâmetros, exceto `dataset_format`, deverão ser números inteiros ou listas de números inteiros.
+ **related\$1time\$1series** — (Opcional) Uma matriz de expressões. JMESPath Esse campo é usado para localizar todas as séries temporais relacionadas no conjunto de dados de entrada compartilhado, se houver.
+ **static\$1covariates** — (Opcional) Uma matriz de expressões. JMESPath Esse campo é usado para localizar todos os campos de covariáveis estáticas no conjunto de dados de entrada compartilhado, se presentes.
Para obter exemplos, consulte [Exemplos de configuração de conjuntos de dados de séries temporais](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex).
+ **methods**: Um objeto contendo um ou mais métodos de análise e seus parâmetros. Se algum método for omitido, ele não será usado para análise nem relatado.
+ **pre\$1training\$1bias**: Inclua esse método se quiser calcular métricas de desvio pré-treinamento. A descrição detalhada das métricas pode ser encontrada em [Métricas de desvio pré-treinamento](clarify-measure-data-bias.md). O objeto tem os seguintes parâmetros:
+ **methods**: Uma matriz que contém qualquer uma das métricas de desvio pré-treinamento da lista a seguir que você deseja calcular. Defina o `methods` como **all** para calcular todas as métricas de desvio pré-treinamento. Como exemplo, a matriz `["CI", "DPL"]` calculará o **desequilíbrio de classes** e a **diferença nas proporções dos rótulos**.
+ `CI` para [Desequilíbrio de classes (CI)](clarify-bias-metric-class-imbalance.md)
+ `DPL` para [Diferença nas proporções dos rótulos (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ `KL` para [Divergência de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ `JS` para [Divergência de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ `LP` para [Norma Lp (LP)](clarify-data-bias-metric-lp-norm.md)
+ `TVD` para [Distância de variação total (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ `KS` para [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ `CDDL` para [Disparidade demográfica condicional (CDD)](clarify-data-bias-metric-cddl.md)
+ **post\$1training\$1bias**: Inclua esse método se quiser calcular métricas de desvio pós-treinamento. A descrição detalhada das métricas pode ser encontrada em [Métricas de dados pós-treinamento e desvio do modelo](clarify-measure-post-training-bias.md). O objeto `post_training_bias` tem os parâmetros a seguir.
+ **methods**: Uma matriz que contém qualquer uma das métricas de desvio pós-treinamento da lista a seguir que você deseja calcular. Defina o `methods` como **all** para calcular todas as métricas de desvio pós-treinamento. Como exemplo, a matriz `["DPPL", "DI"]` calcula a **diferença nas proporções positivas nos rótulos previstos** e o **impacto díspar**. Os métodos disponíveis são os seguintes:
+ `DPPL` para [Diferença nas proporções positivas nos rótulos previstos (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ `DI` para [Impacto díspar (DI)](clarify-post-training-bias-metric-di.md)
+ `DCA` para [Diferença na aceitação condicional () DCAcc](clarify-post-training-bias-metric-dcacc.md)
+ `DCR` para [Diferença na rejeição condicional (DCR)](clarify-post-training-bias-metric-dcr.md)
+ `SD` para [Diferença de especificidade (SD)](clarify-post-training-bias-metric-sd.md)
+ `RD` para [Diferença de recordação (RD)](clarify-post-training-bias-metric-rd.md)
+ `DAR` para [Diferença nas taxas de aceitação (DAR)](clarify-post-training-bias-metric-dar.md)
+ `DRR` para [Diferença nas taxas de rejeição (DRR)](clarify-post-training-bias-metric-drr.md)
+ `AD` para [Diferença de precisão (AD)](clarify-post-training-bias-metric-ad.md)
+ `TE` para [Igualdade de tratamento (TE)](clarify-post-training-bias-metric-te.md)
+ `CDDPL` para [Disparidade demográfica condicional em rótulos previstos (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ `FT` para [Teste de inversão contrafactual (FT)](clarify-post-training-bias-metric-ft.md)
+ `GE` para [Entropia generalizada (GE)](clarify-post-training-bias-metric-ge.md)
+ **shap**: Inclua esse método se quiser calcular valores SHAP. O trabalho de processamento do SageMaker Clarify oferece suporte ao algoritmo Kernel SHAP. O objeto `shap` tem os parâmetros a seguir.
+ **baseline**: (Opcional) O conjunto de dados de linha de base do SHAP, também conhecido como conjunto de dados em segundo plano. Os requisitos adicionais para o conjunto de dados de linha de base em um conjunto de dados tabular ou problema de visão computacional são os seguintes: Para obter mais informações sobre as linhas de base do SHAP, consulte [Linhas de base do SHAP para explicabilidade](clarify-feature-attribute-shap-baselines.md).
+ Para um conjunto de dados **tabular**, a `baseline` pode ser os dados de linha de base no local ou o URI do S3 de um arquivo de linha de base. Se não `baseline` for fornecido, o trabalho de processamento do SageMaker Clarify calcula uma linha de base agrupando o conjunto de dados de entrada. O seguinte é exigido da linha de base:
+ O formato deve ser igual ao formato do conjunto de dados especificado pelo `dataset_type`.
+ A linha de base só pode conter atributos que o modelo possa aceitar como entrada.
+ O conjunto de dados de linha de base pode ter uma ou mais instâncias. O número de instâncias de linha de base afeta diretamente o tamanho do conjunto de dados sintéticos e o runtime do trabalho.
+ Se a `text_config` for especificada, o valor da linha de base de uma coluna de texto será uma string usada para substituir a unidade de texto especificada por `granularity`. Por exemplo, um espaço reservado comum é "[MASK]", que é usado para representar uma palavra ou trecho de texto ausente ou desconhecido.
Os seguintes exemplos mostram como definir dados de linha de base no local para diferentes parâmetros `dataset_type`:
+ Se o `dataset_type` for `text/csv` ou `application/x-parquet`, o modelo aceitará quatro atributos numéricos e a linha de base terá duas instâncias. Neste exemplo, se um registro tiver todos os valores de atributo como zero e o outro registro tiver todos os valores de atributo como um, a linha de base deverá ser definida como `[[0,0,0,0],[1,1,1,1]]`, sem nenhum cabeçalho.
+ Se o `dataset_type` for `application/jsonlines`, `features` é a chave para uma lista de quatro valores de atributos numéricos. Além disso, neste exemplo, se a linha de base tiver um registro de todos os valores como zero, então a `baseline` deverá ser `[{"features":[0,0,0,0]}]`.
+ Se `dataset_type` for `application/json`, o conjunto de dados `baseline` deverá ter a mesma estrutura e formato do conjunto de dados de entrada.
+ Para problemas de **visão computacional**, a `baseline` pode ser o URI do S3 de uma imagem usada para mascarar atributos (segmentos) da imagem de entrada. A tarefa de processamento do SageMaker Clarify carrega a imagem da máscara e a redimensiona para a mesma resolução da imagem de entrada. Se a linha de base não for fornecida, o trabalho de processamento do SageMaker Clarify gerará uma imagem de máscara de [ruído branco](https://en.wikipedia.org/wiki/White_noise) na mesma resolução da imagem de entrada.
+ **features\$1to\$1explain**: (Opcional) Uma matriz de strings ou índices baseados em zero de colunas de atributos para calcular valores de SHAP. Se `features_to_explain` não for fornecido, os valores SHAP serão calculados para todas as colunas de atributos. Essas colunas de atributos não podem incluir a coluna de rótulo ou a coluna de rótulo previsto. O parâmetro `features_to_explain` só é compatível com conjuntos de dados tabulares com colunas numéricas e categóricas.
+ **num\$1clusters**: (Opcional) O número de clusters em que o conjunto de dados é dividido para calcular o conjunto de dados de linha de base. Cada cluster é usado para calcular uma instância de linha de base. Se não `baseline` for especificado, o trabalho de processamento do SageMaker Clarify tentará calcular o conjunto de dados de linha de base dividindo o conjunto de dados tabular em um número ideal de clusters entre e. `1` `12` O número de instâncias de linha de base afeta diretamente o runtime da análise SHAP.
+ **num\$1samples**: (Opcional) O número de amostras a serem usadas no algoritmo SHAP do Kernel. Se não `num_samples` for fornecido, o trabalho de processamento do SageMaker Clarify escolherá o número para você. O número de amostras afeta diretamente o tamanho do conjunto de dados sintéticos e o runtime do trabalho.
+ **seed**: (Opcional) Um número inteiro usado para inicializar o gerador de números pseudo-aleatórios no explicador SHAP para gerar valores SHAP consistentes para o mesmo trabalho. Se a semente não for especificada, toda vez que o mesmo trabalho for executado, o modelo poderá gerar valores SHAP ligeiramente diferentes.
+ **use\$1logit**: (Opcional) Valor boleano para indicar se a função logit deve ser aplicada às predições de modelo. O padrão é `false`. Se o `use_logit` for `true`, os valores SHAP serão calculados usando os coeficientes de regressão logística, que podem ser interpretados como razões logarítmicas.
+ **save\$1local\$1shap\$1values**: (Opcional) Um valor booleano que indica que você deseja que os valores SHAP locais de cada registro no conjunto de dados sejam incluídos no resultado da análise. Padronizado como `false`.
Se o conjunto de dados principal estiver dividido em vários arquivos ou o processamento distribuído estiver ativado, especifique também uma coluna identificadora usando o parâmetro `joinsource_name_or_index`. A coluna identificadora e os valores SHAP locais serão salvos no resultado da análise. Dessa forma, você poderá mapear cada registro para seus valores SHAP locais.
+ **agg\$1method**: (Opcional) O método utilizado para agregar os valores locais de SHAP (os valores SHAP para cada instância) de todas as instâncias aos valores globais de SHAP (os valores SHAP para todo o conjunto de dados). Padronizado como `mean_abs`. Os métodos a seguir podem ser usados para agregar valores SHAP.
+ **mean\$1abs**: A média dos valores SHAP locais absolutos de todas as instâncias.
+ **mean\$1abs**: A média dos valores locais de SHAP ao quadrado de todas as instâncias.
+ **mediana**: A média dos valores SHAP locais de todas as instâncias.
+ **text\$1config**: Obrigatório para a explicabilidade do processamento de linguagem natural. Inclua esta configuração se desejar tratar as colunas de texto como texto, e explicações devem ser fornecidas para unidades individuais de texto. Para obter um exemplo de uma configuração de análise para explicabilidade do processamento de linguagem natural, consulte [Configuração de análise para explicabilidade do processamento de linguagem natural](#clarify-analysis-configure-nlp-example)
+ **granularidade**: A unidade de granularidade para a análise de colunas de texto. Os valores válidos são `token`, `sentence` ou `paragraph`. **Cada unidade de texto é considerada um atributo** e os valores SHAP locais são calculados para cada unidade.
+ **idioma**: O idioma das colunas de texto. Os valores válidos são **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**. Insira `multi-language` para obter uma combinação de vários idiomas.
+ **max\$1top\$1tokens**: (Opcional) O número máximo dos principais tokens, com base nos valores globais SHAP. Padronizado como `50`. É possível que um token apareça várias vezes no conjunto de dados. O trabalho de processamento do SageMaker Clarify agrega os valores de SHAP de cada token e, em seguida, seleciona os principais tokens com base em seus valores globais de SHAP. Os valores globais SHAP dos principais tokens selecionados estão incluídos na seção `global_top_shap_text` do arquivo analysis.json.
+ O valor SHAP local da agregação.
+ **image\$1config**: Obrigatório para a explicabilidade da visão computacional. Inclua esta configuração se você tiver um conjunto de dados de entrada composto por imagens e desejar analisá-las para explicabilidade em um problema de visão computacional.
+ **model\$1type**: O tipo do modelo. Os valores válidos são:
+ `IMAGE_CLASSIFICATION` para um modelo de classificação de imagens.
+ `OBJECT_DETECTION` para um modelo de detecção de objetos.
+ **max\$1objects**: Aplicável somente quando model\$1type é **OBJECT\$1DETECTION**. O número máximo de objetos, ordenado pela pontuação de confiança, detectado pelo modelo de visão computacional. Todos os objetos classificados abaixo dos max\$1objects superiores por pontuação de confiança são filtrados. Padronizado como `3`.
+ **context**: Aplicável somente quando model\$1type é **OBJECT\$1DETECTION**. Isso indica se a área ao redor da caixa delimitadora do objeto detectado está mascarada pela imagem de referência ou não. Os valores válidos são `0` para mascarar tudo ou `1` para não mascarar nada. Padronizado como 1.
+ **iou\$1threshold**: Aplicável somente quando `model_type` é **OBJECT\$1DETECTION**. A métrica mínima de interseção sobre união (IOU) para avaliar as predições em relação à detecção original. Uma métrica de IOU alta corresponde a uma grande sobreposição entre a caixa de detecção prevista e a caixa de detecção real (ground truth). Padronizado como `0.5`.
+ **num\$1segments**: (Opcional) Um número inteiro que determina a quantidade aproximada de segmentos a serem rotulados na imagem de entrada. Cada segmento da imagem é considerado um atributo, e valores locais de SHAP são calculados para cada segmento. Padronizado como `20`.
+ **segment\$1compactness**: (Opcional) Um número inteiro que determina a forma e o tamanho dos segmentos de imagem gerados pelo [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic). Padronizado como `5`.
+ **pdp** — Inclua esse método para calcular gráficos de dependência parcial (). PDPs Para obter um exemplo de uma configuração de análise a ser gerada PDPs, consulte [Calcule gráficos de dependência parcial () PDPs](#clarify-analysis-configure-csv-example-pdp)
+ **atributos**: Obrigatório se o método `shap` não for solicitado. Uma variedade de nomes de atributos ou índices para calcular e traçar gráficos PDP.
+ **top\$1k\$1features**: (Opcional) Especifica o número dos principais atributos usados para gerar gráficos PDP. Se não `features` for fornecido, mas o `shap` método for solicitado, o trabalho de processamento do SageMaker Clarify escolherá os principais recursos com base em suas atribuições SHAP. Padronizado como `10`.
+ **grid\$1resolution**: O número de buckets nos quais dividir o intervalo de valores numéricos. Isso especifica a granularidade da grade para os gráficos PDP.
+ **asymmetric\$1shapley\$1value**: Inclua esse método se quiser calcular métricas de explicabilidade para modelos de previsão de séries temporais. O trabalho de processamento do SageMaker Clarify suporta o algoritmo de valores assimétricos de Shapley. Os valores assimétricos de Shapley são uma variante do valor de Shapley que eliminam o axioma da simetria. Para obter mais informações, consulte [Valores assimétricos de Shapley: como incorporar conhecimento causal à explicabilidade independente do modelo](https://arxiv.org/abs/1910.06358). Use esses valores para determinar como os atributos contribuem para o resultado da previsão. Os valores assimétricos de Shapley levam em consideração as dependências temporais dos dados de séries temporais que os modelos de previsão usam como entrada.
O algoritmo inclui os seguintes parâmetros:
+ **direction**: Os tipos disponíveis são `chronological`, `anti_chronological` e `bidirectional`. A estrutura temporal pode ser navegada em ordem cronológica, anticronológica ou ambas. As explicações cronológicas são criadas adicionando informações de forma iterativa desde a primeira etapa. As explicações anticronológicas adicionam informações a partir da última etapa e retrocedendo. A última ordem pode ser mais apropriada na presença de desvio de recenticidade, como para prever os preços de ações.
+ **granularity**: O detalhamento da explicação a ser usado. As opções de detalhamento disponíveis são as seguintes:
+ **timewise**: as explicações de `timewise` são econômicas e fornecem informações apenas sobre intervalos de tempo específicos, como descobrir o quanto as informações do enésimo dia no passado contribuíram para a previsão de tal dia no futuro. As atribuições resultantes não explicam as covariáveis estáticas individualmente e não diferenciam entre séries temporais alvo e relacionadas.
+ **fine\$1grained**: As explicações de `fine_grained` são computacionalmente mais intensivas, mas fornecem uma análise completa de todas as atribuições das variáveis de entrada. O método calcula explicações aproximadas para reduzir o runtime. Para obter mais informações, consulte o parâmetro `num_samples`.
**nota**
As explicações de `fine_grained` são compatíveis apenas com a ordem `chronological`.
+ **num\$1samples**: (Opcional) Esse argumento é necessário para explicações de `fine_grained`. Quanto maior o número, mais precisa é a aproximação. O número deve escalar com a dimensionalidade dos atributos de entrada. Uma regra prática é definir essa variável como *(1 \$1 max(número de séries temporais relacionadas, número de covariáveis estáticas))^2* se o resultado não for muito grande.
+ **baseline** — (Opcional) A configuração da linha de base para substituir out-of-coalition os valores dos conjuntos de dados correspondentes (também conhecidos como dados de segundo plano). O trecho de código a seguir mostra um exemplo de configuração de linha de base:
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ Para dados temporais, como séries temporais de destino ou séries temporais relacionadas, os tipos de valores da linha de base podem ser um dos seguintes valores:
+ `zero`— Todos os out-of-coalition valores são substituídos por 0,0.
+ `mean`— Todos os out-of-coalition valores são substituídos pela média de uma série temporal.
+ Para covariáveis estáticas, uma entrada de linha de base só deve ser fornecida quando a solicitação do modelo usa valores de covariáveis estáticas. Nesse caso, esse campo é obrigatório. A linha de base deve ser fornecida para cada item como uma lista. Por exemplo, se você tiver um conjunto de dados com duas covariáveis estáticas, sua configuração de linha de base pode ser a seguinte:
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
No exemplo anterior, ** e ** são os IDs dos itens do conjunto de dados.
+ **report**: (Opcional) Use este objeto para personalizar o relatório de análise. Esse parâmetro não é compatível com trabalhos de explicação de séries temporais. Existem três cópias do mesmo relatório como parte do resultado da análise: relatório do caderno Jupyter, relatório HTML e relatório PDF. O objeto tem os seguintes parâmetros:
+ **name**: Nome do arquivo dos arquivos de relatório. Por exemplo, se `name` for **MyReport**, os arquivos de relatório serão `MyReport.ipynb`, `MyReport.html` e `MyReport.pdf`. Padronizado como `report`.
+ **title**: (Opcional) String do título para o relatório. Padronizado como **SageMaker AI Analysis Report**.
+ **preditor**: Obrigatório se a análise exigir predições de modelo. Por exemplo, quando o método `shap`, `asymmetric_shapley_value`, `pdp` ou `post_training_bias` é solicitado, mas os rótulos previstos não são fornecidos como parte do conjunto de dados de entrada. A seguir estão os parâmetros a serem usados em conjunto com`predictor`:
+ **model\$1name** — O nome do seu modelo de SageMaker IA criado pela [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)API. Se você especificar `model_name` em vez de endpoint\$1name, o trabalho de processamento do SageMaker Clarify cria um endpoint efêmero com o nome do modelo, conhecido como endpoint **sombra, e obtém previsões do endpoint**. O trabalho exclui o endpoint de sombra após a conclusão dos cálculos. Se o modelo for multimodelo, então o parâmetro `target_model` deve ser especificado. Para obter mais informações sobre endpoints multimodelo, consulte [Endpoints multimodelo](multi-model-endpoints.md).
+ **endpoint\$1name\$1prefix**: (Opcional) Um prefixo de nome personalizado para o endpoint de sombra. Aplicável se você fornecer `model_name` em vez de `endpoint_name`. Por exemplo, forneça `endpoint_name_prefix` se você deseja restringir o acesso ao endpoint pelo nome do endpoint. O prefixo deve corresponder ao [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName)padrão e seu comprimento máximo é`23`. Padronizado como `sm-clarify`.
+ **initial\$1instance\$1count**: Especifica o número de instâncias do endpoint sombra. Obrigatório se você fornecer model\$1name em vez de endpoint\$1name. O valor para `initial_instance_count` pode ser diferente do valor [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)do trabalho, mas recomendamos uma proporção de 1:1.
+ **instance\$1type**: Especifica o tipo de instância para o endpoint sombra. Obrigatório se você fornecer `model_name` em vez de `endpoint_name`. Por exemplo, `instance_type` pode ser definido como “ml.m5.large”. Em alguns casos, o valor especificado para `instance_type` pode ajudar a reduzir o tempo de inferência do modelo. Por exemplo, para funcionar com eficiência, os modelos de processamento de linguagem natural e os Modelos de visão computadorizada normalmente exigem um tipo de instância de unidade de processamento gráfico (GPU).
+ **endpoint\$1name — O nome** do seu endpoint de SageMaker IA criado pela API. [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) Se fornecido, `endpoint_name` tem precedência sobre o parâmetro `model_name`. Usar um endpoint existente reduz o tempo de inicialização do shadow endpoint, mas também pode causar um aumento significativo na carga desse endpoint. Além disso, alguns métodos de análise (como `shap` e `pdp`) geram conjuntos de dados sintéticos que são enviados para o endpoint. Isso pode fazer com que as métricas do endpoint ou os dados capturados sejam contaminados por dados sintéticos, que podem não refletir com precisão o uso no mundo real. Por esses motivos, geralmente não é recomendável usar um endpoint de produção existente para a análise do SageMaker Clarify.
+ **target\$1model** — O valor da string que é passado para o TargetModel parâmetro da API de SageMaker IA [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax). Obrigatório se o seu modelo (especificado pelo parâmetro model\$1name) ou endpoint (especificado pelo parâmetro endpoint\$1name) for multimodelo. Para obter mais informações sobre endpoints multimodelo, consulte [Endpoints multimodelo](multi-model-endpoints.md).
+ **custom\$1attributes**: (Opcional) Uma string que permite fornecer informações adicionais sobre uma solicitação de inferência enviada ao endpoint. O valor da string é passado para o `CustomAttributes` parâmetro da [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ **content\$1type**: content\$1type: O formato de entrada do modelo a ser usado para obter predições do endpoint. Se fornecido, ele é passado para o `ContentType` parâmetro da [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API de SageMaker IA.
+ Para explicabilidade por visão computacional, os valores válidos são **image/jpeg**, **image/png** ou **application/x-npy**. Se `content_type` não for fornecido, o valor padrão será **image/jpeg**.
+ Para explicabilidade da previsão de séries temporais, o valor válido é **application/json**.
+ Para outros tipos de explicabilidade, os valores válidos são **text/csv**, **application/jsonlines,** e **application/json**. Um valor para `content_type` é necessário se `dataset_type` for **application/x-parquet**. Caso contrário, `content_type` assume o valor do parâmetro `dataset_type`.
+ **accept\$1type**: O formato da saída do modelo a ser usado para obter predições do endpoint. O valor de `accept_type` é passado para o `Accept` parâmetro da [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)API SageMaker AI.
+ Para explicabilidade da visão computacional, se `model_type` for "OBJECT\$1DETECTION", então `accept_type` será padronizado como **application/json**.
+ Para explicabilidade da previsão de séries temporais, o valor válido é **application/json**.
+ Para outros tipos de explicabilidade, os valores válidos são **text/csv**, **application/jsonlines** e **application/json**. Se um valor para `accept_type` não for fornecido, `accept_type` assume como padrão o valor do parâmetro `content_type`.
+ **content\$1template**: Uma string de modelo usada para construir a entrada do modelo a partir dos registros do conjunto de dados. O parâmetro `content_template` só será usado e obrigatório se o valor do parâmetro `content_type` for `application/jsonlines` ou `application/json`.
Quando o parâmetro `content_type` for `application/jsonlines`, o modelo deverá ter apenas um espaço reservado, `$features`, que é substituído por uma lista de atributos em runtime. Por exemplo, se o modelo for `"{\"myfeatures\":$features}"`, e se um registro tiver três valores de atributo numérico: `1`, `2` e `3`, então o registro será enviado ao modelo como Linha JSON `{"myfeatures":[1,2,3]}`.
Quando `content_type` estiver `application/json`, o modelo pode ter espaço reservado `$record` ou `records`. Se o espaço reservado for `record`, um único registro será substituído por um registro que tenha o modelo `record_template` aplicado a ele. Nesse caso, somente um único registro será enviado ao modelo por vez. Se o espaço reservado for `$records`, os registros serão substituídos por uma lista de registros, cada um com um modelo fornecido por `record_template`.
+ **record\$1template**: Uma sequência de modelos a ser usada para construir cada registro da entrada do modelo a partir de instâncias do conjunto de dados. Ele só é usado e exigido quando `content_type` é `application/json`. A string do modelo pode conter um dos seguintes:
+ Um parâmetro `$features` de espaço reservado que é substituído por uma matriz de valores de atributos. Um espaço reservado opcional adicional pode substituir os nomes dos cabeçalhos das colunas de atributos em `$feature_names`. Este espaço reservado opcional será substituído por uma variedade de nomes de atributos.
+ Exatamente um espaço reservado `$features_kvp` que é substituído pelos pares de valores-chave, nome do atributo e valor do atributo.
+ Um atributo na `headers` configuração. Por exemplo, um nome de atributo `A`, indicado pela sintaxe do espaço reservado `"${A}"`, será substituído pelo valor do atributo para `A`.
O valor de `record_template` é usado com `content_template` para construir a entrada do modelo. Segue um exemplo de configuração que mostra como construir uma entrada de modelo usando um modelo de conteúdo e registro.
No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:
+ ``headers`:["A", "B"]`
+ ``features`:[[0,1], [3,4]]`
A entrada do modelo de exemplo é a seguinte:
```
{
"instances": [[0, 1], [3, 4]],
"feature_names": ["A", "B"]
}
```
Seguem os valores do exemplo `content_template` e dos parâmetros `record_template` para construir a entrada do modelo de exemplo anterior.
+ `content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"`
+ `record_template: "$features"`
No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:
```
[
{ "A": 0, "B": 1 },
{ "A": 3, "B": 4 },
]
```
Seguem os valores do exemplo ` content_template` e dos parâmetros `record_template` para construir a entrada do modelo de exemplo anterior.
+ `content_template: "$records"`
+ `record_template: "$features_kvp"`
Segue um exemplo de código alternativo para construir o exemplo anterior de entrada do modelo.
+ `content_template: "$records"`
+ `record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"`
No exemplo de código a seguir, os cabeçalhos e atributos são definidos da seguinte maneira:
```
{ "A": 0, "B": 1 }
```
Os valores dos parâmetros content\$1template e record\$1template de exemplo a serem construídos acima: a entrada do modelo de exemplo anterior segue.
+ `content_template: "$record"`
+ `record_template: "$features_kvp"`
Para obter mais exemplos, consulte [Solicitações de endpoint para dados de séries temporais](clarify-processing-job-data-format-time-series-request-jsonlines.md).
+ **label** — (Opcional) Um índice inteiro baseado em zero ou uma string de JMESPath expressão usada para extrair rótulos previstos da saída do modelo para análise de viés. Se o modelo for multiclasse e o parâmetro `label` extrair todos os rótulos previstos da saída do modelo, o seguinte se aplica: Esse atributo não é compatível com séries temporais.
+ O parâmetro `probability` é necessário para obter as probabilidades (ou pontuações) correspondentes da saída do modelo.
+ O rótulo previsto da pontuação mais alta é escolhido.
O valor de `label` depende do valor do parâmetro accept\$1type conforme a seguir.
+ Se `accept_type` for **text/csv**, então `label` é o índice de quaisquer rótulos previstos na saída do modelo.
+ Se `accept_type` for **application/jsonlines** ou**application/json**, então `label` é uma JMESPath expressão aplicada à saída do modelo para obter os rótulos previstos.
+ **label\$1headers**: (Opcional) Uma matriz de valores que o rótulo pode usar no conjunto de dados. Se a análise de tendências for solicitada, o parâmetro `probability` também será necessário para obter os valores de probabilidade (pontuações) correspondentes da saída do modelo, e o rótulo previsto da pontuação mais alta será escolhido. Se a análise de explicabilidade for solicitada, os cabeçalhos das etiquetas serão usados para embelezar o relatório de análise. É necessário um valor `label_headers` para para a explicabilidade da visão computacional. Por exemplo, para um problema de classificação multiclasse, se o rótulo tiver três valores possíveis, **bird**, **cat** e **dog**, então `label_headers` deve ser definido como `["bird","cat","dog"]`.
+ **probabilidade** — (Opcional) Um índice inteiro baseado em zero ou uma string de JMESPath expressão usada para extrair probabilidades (pontuações) para análise de explicabilidade (mas não para explicabilidade de séries temporais) ou para escolher o rótulo previsto para análise de viés. O valor de `probability` depende do valor do parâmetro `accept_type` 9737accept\$1type conforme a seguir.
+ Se `accept_type` for **text/csv**, `probability` é o índice das probabilidades (pontuações) na saída do modelo. Se `probability` não for fornecido, toda a saída do modelo é considerada como probabilidades (pontuações).
+ Se `accept_type` forem dados JSON (**application/jsonlines**ou**application/json**), `probability` deve ser uma JMESPath expressão usada para extrair as probabilidades (pontuações) da saída do modelo.
+ **time\$1series\$1predictor\$1config**: (Opcional) Usado somente para explicabilidade de séries temporais. Usado para instruir o processador do SageMaker Clarify a analisar dados corretamente a partir dos dados transmitidos como um URI do S3. `dataset_uri`
+ **previsão** — Uma JMESPath expressão usada para extrair o resultado da previsão.
## Exemplo de arquivos de configuração de análise
As seções a seguir contêm exemplos de arquivos de configuração de análise para dados em formato CSV, formato JSON Lines e para processamento de linguagem natural (PLN), visão computacional (CV) e explicabilidade de séries temporais (TS).
### Configuração de análise para um conjunto de dados CSV
Os exemplos a seguir mostram como configurar a análise de polarização e explicabilidade para um conjunto de dados tabular em 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. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada `dataset` de processamento.
```
"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
...
```
As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) mostrando a importância do recurso para um conjunto de dados no formato CSV.
#### Calcular todas as métricas de tendências do pré-treinamento
Este exemplo de configuração mostra como medir se o conjunto de dados de amostra anterior está favoravelmente inclinado para amostras com um **Gender** valor de `0`. A configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés pré-treinamento para o conjunto de dados.
```
{
"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"
}
}
}
```
#### Calcular todas as métricas de tendências do pós-treinamento
Você pode calcular as métricas de desvio pré-treinamento antes do treinamento. No entanto, para calcular as métricas de desvio do pós-treinamento, 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
...
```
O exemplo de configuração a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis usando o conjunto de dados e as previsões da saída do modelo. No exemplo, o modelo é implantado em um endpoint `your_endpoint` de SageMaker IA.
**nota**
No código de exemplo a seguir, o parâmetro `content_type` e não `accept_type` estão definidos. Portanto, eles usam automaticamente o valor do parâmetro dataset\$1type, que é `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
}
}
```
#### Calcular os valores SHAP
O exemplo de configuração de análise a seguir instrui o trabalho a calcular os valores SHAP designando a `Target` coluna como rótulos e todas as outras colunas como atributos.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
Neste exemplo, o parâmetro de `baseline` do SHAP é omitido e o valor do parâmetro `num_clusters` é `1`. Isso instrui o processador SageMaker Clarify a calcular uma amostra de linha de base do SHAP. Neste exemplo, a probabilidade é definida como `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).
#### Calcule gráficos de dependência parcial () PDPs
O exemplo a seguir mostra como visualizar a importância do `Income` recurso no relatório de análise usando PDPs. O parâmetro do relatório instrui o trabalho de processamento do SageMaker Clarify a gerar um relatório. Após a conclusão do trabalho, o relatório gerado é salvo como report.pdf no `analysis_result` local. O parâmetro `grid_resolution` dividia o intervalo dos valores do atributo em `10` buckets . Juntos, os parâmetros especificados no exemplo a seguir instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP `Income` com `10` segmentos no eixo x. O eixo y mostrará o impacto marginal de `Income` nas predições.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"pdp": {
"features": ["Income"],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
},
}
```
#### Calcular as métricas de desvio e a importância do atributo
Você pode combinar todos os métodos dos exemplos de configuração anteriores em um único arquivo de configuração de análise e calculá-los todos em um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas.
Neste exemplo, o parâmetro `probability` é definido `1` para indicar que as probabilidades estão contidas na segunda coluna (usando indexação baseada em zero). No entanto, como a análise de desvio precisa de um rótulo previsto, o parâmetro `probability_threshold` é definido `0.5` para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro `top_k_features` do método `pdp` de gráficos de dependência parcial é definido como `2`. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular gráficos de dependência parcial (PDPs) para os principais `2` recursos com os maiores valores globais de SHAP.
```
{
"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
}
}
```
Em vez de implantar o modelo em um endpoint, você pode fornecer o nome do seu modelo de SageMaker IA ao trabalho de processamento do SageMaker Clarify usando o `model_name` parâmetro. O exemplo a seguir mostra como especificar um modelo chamado **your\$1model**. O trabalho de processamento do SageMaker Clarify criará um endpoint paralelo usando a configuração.
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### Configuração de análise para um conjunto de dados Linhas JSON
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 JSON Lines. Nesses exemplos, o conjunto de dados de entrada tem os mesmos dados da seção anterior, mas eles estão no formato denso SageMaker AI JSON Lines. Cada linha é um objeto JSON válido. A chave "Recursos" se refere a uma matriz de valores de atributos, e a chave "Rótulo" aponta para o rótulo de veracidade. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada de processamento do “conjunto de dados”. Para obter mais informações sobre linhas JSON, consulte [Formato da solicitação 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}
...
```
As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) mostrando a importância do recurso para um conjunto de dados no formato JSON Lines.
#### Calcular as métricas de desvio pré-treinamento
Especifique o rótulo, os atributos, o formato e os métodos para medir as métricas de desvio antes do treinamento em um `Gender` valor de `0`. No exemplo a seguir, o parâmetro `headers` fornece primeiro os nomes dos atributos. O nome do rótulo é fornecido por último. Por convenção, o último cabeçalho é o cabeçalho do rótulo.
O `features` parâmetro é definido com a JMESPath expressão “Recursos” para que o trabalho de processamento do SageMaker Clarify possa extrair a matriz de recursos de cada registro. O `label` parâmetro é definido como a JMESPath expressão “Label” para que a tarefa de processamento do SageMaker Clarify possa extrair o rótulo de verdade fundamental de cada registro. Use um nome de faceta para especificar o atributo sigiloso, da seguinte forma:
```
{
"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"
}
}
}
```
#### Calcular todas as métricas de desvio
Você deve ter um modelo treinado para calcular as métricas de desvio pós-treinamento. 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}
...
```
Você pode implantar o modelo em um endpoint de SageMaker IA chamado`your_endpoint`. O exemplo de configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis para o conjunto de dados e o modelo. No exemplo, os parâmetros `content_type` e `accept_type` não estão incluídos. Portanto, eles são configurados automaticamente para usar o valor do parâmetro dataset\$1type, 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.
```
{
"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"
}
}
```
#### Calcular os valores SHAP
Como a análise SHAP não precisa de um rótulo de veracidade fundamental, o parâmetro `label` é omitido. Neste exemplo, o parâmetro `headers` também é omitido. Portanto, a tarefa de processamento do SageMaker Clarify deve gerar espaços reservados usando nomes genéricos, como `column_0` ou `column_1` para cabeçalhos de recursos, e `label0` para um cabeçalho de rótulo. Você pode especificar valores para `headers` e para um `label` melhorar a legibilidade do resultado da análise. Como o parâmetro de probabilidade está definido como JMESPath expressão`probability`, o valor da probabilidade será extraído da saída do modelo. Veja a seguir um exemplo do cálculo dos valores SHAP.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### Calcule gráficos de dependência parcial () PDPs
O exemplo a seguir mostra como visualizar a importância de “Renda” no PDP. Neste exemplo, os cabeçalhos dos atributos não são fornecidos. Portanto, o parâmetro `features` do método `pdp` deve usar índice baseado em zero para se referir à localização da coluna de atributos. O parâmetro `grid_resolution` dividia o intervalo dos valores do atributo em `10` buckets . Juntos, os parâmetros no exemplo instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP `Income` com `10` segmentos no eixo x. O eixo y mostrará o impacto marginal de `Income` nas predições.
```
{
"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"
}
}
```
#### Calcular as métricas de desvio e a importância do atributo
Você pode combinar todos os métodos anteriores em um único arquivo de configuração de análise e calculá-los todos em um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas. Neste exemplo, o parâmetro `probability` está definido. Mas como a análise de desvio precisa de um rótulo previsto, o parâmetro `probability_threshold` é definido como `0.5` para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro `top_k_features` do método `pdp` é definido como `2`. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular PDPs os principais `2` recursos com os maiores valores globais de SHAP.
```
{
"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"
}
}
```
### Configuração de análise para um conjunto de dados JSON
Os exemplos a seguir mostram como configurar a análise de desvio e explicabilidade para um conjunto de dados tabular no formato JSON. Nesses exemplos, o conjunto de dados de entrada tem os mesmos dados da seção anterior, mas eles estão no formato denso SageMaker AI JSON. Para obter mais informações sobre linhas JSON, consulte [Formato da solicitação JSONLINES](cdf-inference.md#cm-jsonlines).
Toda a solicitação de entrada é um JSON válido, em que a estrutura externa é uma lista e cada elemento é o dado de um registro. Em cada registro, a chave `Features` se refere a uma matriz de valores de atributos, e a chave `Label` se refere ao rótulo de veracidade. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pela entrada `dataset` de processamento.
```
[
{"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},
...
]
```
As seções a seguir mostram como calcular métricas de viés pré-treinamento e pós-treinamento, valores de SHAP e gráficos de dependência parcial (PDPs) que mostram a importância do recurso para um conjunto de dados no formato JSON Lines.
#### Calcular as métricas de desvio pré-treinamento
Especifique o rótulo, os atributos, o formato e os métodos para medir as métricas de desvio antes do treinamento em um `Gender` valor de `0`. No exemplo a seguir, o parâmetro `headers` fornece primeiro os nomes dos atributos. O nome do rótulo é fornecido por último. Para conjuntos de dados JSON, o último cabeçalho é o cabeçalho do rótulo.
O `features` parâmetro é definido como a JMESPath expressão que extrai uma matriz ou matriz 2D. Cada linha nessa matriz deve conter a lista de `Features` para cada registro. O `label` parâmetro é definido como uma JMESPath expressão que extrai uma lista de rótulos de verdade básica. Cada elemento dessa lista deve conter o rótulo de um registro.
Use um nome de faceta para especificar o atributo sigiloso, da seguinte forma:
```
{
"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"
}
}
}
```
#### Calcular todas as métricas de desvio
Você deve ter um modelo treinado para calcular as métricas de desvio pós-treinamento. O exemplo de código a seguir é de um modelo de classificação binária que gera dados JSON no formato do exemplo. No exemplo, cada elemento abaixo `predictions` é a saída de predição de um registro. A chave `predicted_label` refere-se ao rótulo previsto e a chave `probability` refere-se ao valor da probabilidade.
```
{
"predictions": [
{"predicted_label":0,"probability":0.028986845165491},
{"predicted_label":1,"probability":0.825382471084594},
...
]
}
```
Você pode implantar o modelo em um endpoint de SageMaker IA chamado`your_endpoint`.
No exemplo a seguir, os parâmetros `content_type` e `accept_type` não estão definidos. Portanto, `content_type` e `accept_type` são automaticamente configurados para usar o valor do parâmetro `dataset_type`, que é `application/json`. Em seguida, o trabalho de processamento do SageMaker Clarify usa o `content_template` parâmetro para compor a entrada do modelo.
No exemplo a seguir, a entrada do modelo é composta pela substituição do `$records` espaço reservado por uma matriz de registros. Em seguida, o parâmetro `record_template` compõe a estrutura JSON de cada registro e substitui o `$features` espaço reservado pela matriz de atributos de cada registro.
O exemplo de configuração de análise a seguir instrui o trabalho de processamento do SageMaker Clarify a calcular todas as métricas de viés possíveis para o conjunto de dados e o modelo.
```
{
"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"
}
}
```
#### Calcular os valores SHAP
Não é necessário especificar um rótulo para a análise SHAP. No exemplo a seguir, o parâmetro `headers` não está especificado. Portanto, o trabalho de processamento do SageMaker Clarify gerará espaços reservados usando nomes genéricos como `column_0` ou `column_1` para cabeçalhos de recursos e `label0` para um cabeçalho de rótulo. Você pode especificar valores para `headers` e para um `label` melhorar a legibilidade do resultado da análise.
No exemplo de configuração a seguir, o parâmetro de probabilidade é definido como uma JMESPath expressão que extrai as probabilidades de cada predição para cada registro. Veja a seguir um exemplo do cálculo dos valores 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"
}
}
```
#### Calcule gráficos de dependência parcial () PDPs
O exemplo a seguir mostra como visualizar a importância de um recurso no PDPs. No exemplo, os cabeçalhos dos atributos não são fornecidos. Portanto, o parâmetro `features` do método `pdp` deve usar índice baseado em zero para se referir à localização da coluna de atributos. O parâmetro `grid_resolution` dividia o intervalo dos valores do atributo em `10` buckets .
Juntos, os parâmetros no exemplo a seguir instruem o trabalho de processamento do SageMaker Clarify a gerar um relatório contendo um gráfico PDP `Income` com `10` segmentos no eixo x. O eixo y mostra o impacto marginal de `Income` nas predições.
O exemplo de configuração a seguir mostra como visualizar a importância de `Income` ativado 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"
}
}
```
#### Calcular as métricas de desvio e a importância do atributo
Você pode combinar todos os métodos de configuração anteriores em um único arquivo de configuração de análise e calculá-los todos com um único trabalho. O exemplo a seguir mostra uma configuração de análise com todas as etapas combinadas.
Neste exemplo, o parâmetro `probability` está definido. Como a análise de desvio precisa de um rótulo previsto, o `probability_threshold` parâmetro é definido como `0.5`, que é usado para converter a pontuação de probabilidade em um rótulo binário. Neste exemplo, o parâmetro `top_k_features` do método `pdp` é definido como `2`. Isso instrui o trabalho de processamento do SageMaker Clarify a calcular PDPs os principais `2` recursos com os maiores valores globais de SHAP.
```
{
"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"
}
}
```
### Configuração de análise para explicabilidade do processamento de linguagem natural
O exemplo a seguir mostra um arquivo de configuração de análise para calcular a importância do atributo para processamento de linguagem natural (PLN). Neste exemplo, o conjunto de dados de entrada é um conjunto de dados tabular em formato CSV, com uma coluna de rótulo binário e duas colunas de atributos, como segue. O conjunto de dados é fornecido à tarefa do SageMaker Clarify pelo parâmetro `dataset` de entrada de processamento.
```
0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...
```
Neste exemplo, um modelo de classificação binária foi treinado no conjunto de dados anterior. O modelo aceita dados CSV e gera uma única pontuação entre `0` e `1`, como segue.
```
0.491656005382537
0.569582343101501
...
```
O modelo é usado para criar um modelo de SageMaker IA chamado “your\$1model”. A configuração de análise a seguir mostra como executar uma análise de explicabilidade baseada em token usando o modelo e o conjunto de dados. O parâmetro `text_config` ativa 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. O exemplo a seguir também mostra como fornecer uma instância de "linha de base" SHAP no local usando uma "Classificação" média de 4. Um token de máscara especial "[MASK]" é usado para substituir um token (palavra) em "Comentários". Este exemplo também usa um tipo de instância de endpoint de GPU para acelerar a inferência.
```
{
"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"
}
}
```
### Configuração de análise para explicabilidade de visão computacional
O exemplo a seguir mostra a importância de um atributo de computação de arquivo de configuração de análise para visão computacional. Neste exemplo, o conjunto de dados de entrada consiste em imagens JPEG. O conjunto de dados é fornecido à tarefa do SageMaker Clarify pelo parâmetro `dataset` de entrada de processamento. O exemplo mostra como configurar uma análise de explicabilidade usando um modelo de classificação de SageMaker imagens. No exemplo, um modelo denominado `your_cv_ic_model` foi treinado para classificar os animais nas imagens JPEG de entrada.
```
{
"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"]
}
}
```
Para obter mais informações sobre classificação de imagem, consulte [Classificação de imagens - MXNet](image-classification.md).
Neste exemplo, um [modelo de detecção de objetos de SageMaker IA](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html) `your_cv_od_model` é treinado nas mesmas imagens JPEG para identificar os animais nelas. O exemplo a seguir mostra como configurar uma análise de explicabilidade para o modelo de detecção de objetos.
```
{
"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"]
}
}
```
### Configuração de análise para explicabilidade do modelo de previsão de séries temporais
O exemplo a seguir mostra um arquivo de configuração de análise para o cálculo da importância do atributo para uma série temporal (TS). No exemplo, o conjunto de dados de entrada é um conjunto de dados de série temporal no formato JSON com um conjunto de atributos de covariáveis dinâmicas e estáticas. O conjunto de dados é fornecido ao trabalho do SageMaker Clarify pelo parâmetro de entrada de processamento do conjunto de dados. `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
},
]
```
As seções a seguir explicam como calcular atribuições de atributos para um modelo de previsão com o algoritmo de valores assimétricos de Shapley para um conjunto de dados JSON.
#### Calcular as explicações para modelos de previsão de séries temporais
O exemplo de configuração de análise a seguir exibe as opções usadas pelo trabalho para calcular as explicações dos modelos de previsão de séries temporais.
```
{
'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'
}
}
```
##### Configuração de explicabilidade de séries temporais
O exemplo anterior usa `asymmetric_shapley_value` in `methods` para definir os argumentos de explicabilidade da série temporal, 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. Esses campos instruem o processador do SageMaker Clarify a calcular as atribuições de recursos para um item por vez.
##### Configuração do preditor
Você pode controlar totalmente a estrutura de carga que o processador SageMaker Clarify envia usando a JMESPath sintaxe. No exemplo anterior, a configuração `predictor` instrui o Clarify a agregar registros em `'{"instances": $records}'`, onde cada registro é definido com os argumentos fornecidos para `record_template` no exemplo. 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.
Da mesma forma, o atributo `forecast` em `time_series_predictor_config` é usado para extrair a predição de modelo da resposta do endpoint. Por exemplo, a resposta em lote do 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]}
]
}
```
Suponha que você especifique a seguinte configuração do preditor de séries temporais:
```
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
```
O valor da previsão é interpretado da seguinte forma:
```
[
[13.4, 3.6],
[23.0, 4.7],
[3.4, 5.6]
]
```
##### Dados de configuração
Use o `time_series_data_config` atributo para instruir o processador do SageMaker Clarify a analisar os dados corretamente a partir dos dados transmitidos como um URI do S3. `dataset_uri`
# Guia de compatibilidade de formato de dados
Este guia descreve os tipos de formato de dados que são compatíveis com as tarefas de processamento do SageMaker Clarify. Os tipos de formato de dados compatíveis incluem extensões de arquivo, estrutura de dados e requisitos ou restrições específicas para conjuntos de dados tabulares, de imagem e de séries temporais. Este guia também mostra como verificar se seu conjunto de dados está em conformidade com esses requisitos.
Em um alto nível, o trabalho de processamento do SageMaker Clarify segue o modelo de entrada-processo-saída para calcular métricas de viés e atribuições de recursos. Consulte os exemplos a seguir para obter detalhes.
A entrada para a tarefa de processamento do SageMaker Clarify consiste no seguinte:
+ O conjunto de dados a ser analisado.
+ O configuração de análise Para obter mais informações sobre como configurar uma análise, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
Durante o estágio de processamento, o SageMaker Clarify calcula métricas de viés e atribuições de recursos. O trabalho de processamento do SageMaker Clarify conclui as seguintes etapas no back-end:
+ O trabalho de processamento do SageMaker Clarify analisa sua configuração de análise e carrega seu **conjunto** de dados.
+ Para calcular métricas de desvio pós-treinamento e atribuições de atributos, o trabalho exige predições de modelo do seu modelo. **O trabalho de processamento do SageMaker Clarify serializa seus dados e os envia como uma **solicitação** ao seu modelo, que é implantado em um endpoint de inferência de SageMaker IA em tempo real.** **Depois disso, o trabalho de processamento do SageMaker Clarify extrai previsões da resposta.**
+ O trabalho de processamento do SageMaker Clarify executa a análise de viés e explicabilidade e, em seguida, gera os resultados.
Para obter mais informações, consulte [Como funcionam os trabalhos de processamento do SageMaker Clarify](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works).
O parâmetro usado para especificar o formato dos dados depende de onde os dados são usados no fluxo de processamento, como segue:
+ Para um **conjunto de dados de entrada**, use o parâmetro `dataset_type` para especificar o formato ou o tipo MIME.
+ Para uma **solicitação** para um endpoint, use o parâmetro `content_type` para especificar o formato.
+ Para uma **solicitação** para um endpoint, use o parâmetro `accept_type`para especificar o formato.
O conjunto de dados de entrada, a solicitação e a resposta de e para o endpoint não exigem o mesmo formato. Por exemplo, você pode usar um conjunto de dados do Parquet com uma carga útil da solicitação**** CSV e uma carga útil da resposta**** de linhas JSON de acordo com as seguintes condições:
+ Sua análise está configurada corretamente.
+ Seu modelo oferece apoio aos formatos de solicitação e resposta.
**nota**
Se `content_type` ou não `accept_type` forem fornecidos, o contêiner SageMaker Clarify `content_type` infere o e. `accept_type`
**Topics**
+ [Dados tabulares](clarify-processing-job-data-format-tabular.md)
+ [Requisitos de dados de imagens](clarify-processing-job-data-format-image.md)
+ [Dados de séries temporais](clarify-processing-job-data-format-time-series.md)
# Dados tabulares
Dados tabulares referem-se a dados que podem ser carregados em um quadro de dados bidimensional. No quadro, cada linha representa um registro e cada registro tem uma ou mais colunas. Os valores em cada célula do quadro de dados podem ser de tipos de dados numéricos, categóricos ou de texto.
## Pré-requisitos do conjunto de dados tabular
Antes da análise, seu conjunto de dados deveria ter todas as etapas de pré-processamento necessárias já aplicadas. Isso inclui limpeza de dados ou engenharia de atributos.
Você pode fornecer um ou vários conjuntos de dados. Se você fornecer vários conjuntos de dados, use o seguinte para identificá-los na tarefa de processamento do SageMaker Clarify.
+ Use uma configuração [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)nomeada `dataset` ou de análise `dataset_uri` para especificar o conjunto de dados principal. Para obter mais informações sobre `dataset_uri`, consulte a lista de parâmetros em [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
+ Use o parâmetro `baseline` fornecido no arquivo de configuração da análise. O conjunto de dados de linha de base é necessário para a análise SHAP. Para obter mais informações sobre o arquivo de configuração de análise, incluindo exemplos, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
A tabela a seguir lista os formatos de dados compatíveis, suas extensões de arquivo e tipos de MIME.
| Formato de dados | Extensão do arquivo | Tipo MIME |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| Linhas JSON | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | "application/x-parquet" |
As seções a seguir mostram exemplos de conjuntos de dados tabulares nos formatos CSV, JSON Lines e Apache Parquet.
### Pré-requisitos de conjunto de dados tabulares em formato CSV
A tarefa de processamento do SageMaker Clarify foi projetada para carregar arquivos de dados CSV no dialeto [csv.excel](https://docs.python.org/3/library/csv.html#csv.excel). No entanto, é flexível o suficiente para compatibilidade com outros terminadores de linha, incluindo `\n` e `\r`.
Para compatibilidade, todos os arquivos de dados CSV fornecidos para a tarefa de processamento do SageMaker Clarify devem ser codificados em UTF-8.
Se o conjunto de dados não conter uma linha de cabeçalho, faça o seguinte:
+ Defina o rótulo de configuração da análise para indexar `0`. Isso significa que a primeira coluna é o rótulo de veracidade.
+ Se o parâmetro `headers` estiver definido, `label` defina o cabeçalho da coluna do rótulo para indicar a localização da coluna do rótulo. Todas as outras colunas são designadas como atributos.
A seguir está um exemplo de um conjunto de dados que não contém uma linha de cabeçalho.
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
Se seus dados contiverem uma linha de cabeçalho, defina o parâmetro `label` para indexar `0`. Para indicar a localização da coluna do rótulo, use o cabeçalho do rótulo de veracidade `Label`. Todas as outras colunas são designadas como atributos.
A seguir está um exemplo de um conjunto de dados que contém uma linha de cabeçalho.
```
Label,Rating,A12,A13,Comments
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
### Pré-requisitos de conjunto de dados tabulares em formato JSON
O JSON é um formato flexível para representar dados estruturados que contêm qualquer nível de complexidade. O suporte do SageMaker Clarify para JSON não está restrito a nenhum formato específico e, portanto, permite formatos de dados mais flexíveis em comparação com conjuntos de dados nos formatos CSV ou JSON Lines. Este guia mostra como definir uma configuração de análise para dados tabulares no formato JSON.
**nota**
Para garantir a compatibilidade, todos os arquivos de dados JSON fornecidos para a tarefa de processamento do SageMaker Clarify devem ser codificados em UTF-8.
Veja a seguir exemplos de dados de entrada com registros que contêm uma chave de nível superior, uma lista de atributos e um rótulo.
```
[
{"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},
...
]
```
Um exemplo de análise de configuração para o conjunto de dados de exemplo de entrada anterior deve definir os seguintes parâmetros:
+ O `label` parâmetro deve usar a [JMESPath](https://jmespath.org/)expressão `[*].label` para extrair o rótulo de verdade fundamental para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma lista de rótulos em que o i the label corresponda ao i the record.
+ O `features` parâmetro deve usar a JMESPath expressão `[*].features` para extrair uma matriz de recursos para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma matriz ou matriz 2D em que a i th linha contém os valores do recurso correspondente ao i th registro.
A seguir estão exemplos de dados de entrada com registros que contêm uma chave de nível superior e uma chave aninhada que contém uma lista de atributos e rótulos para cada registro.
```
{
"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}}
]
}
```
Um exemplo de análise de configuração para o conjunto de dados de exemplo de entrada anterior deve definir os seguintes parâmetros:
+ O `label` parâmetro usa a [JMESPath](https://jmespath.org/)expressão `data[*].label` para extrair o rótulo de verdade fundamental para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma lista de rótulos em que o rótulo é para eles no registro.
+ O `features` parâmetro usa a JMESPath expressão `data[*].features` para extrair a matriz de recursos para cada registro no conjunto de dados. A JMESPath expressão deve produzir uma matriz ou matriz 2D em que a i th linha contém os valores de recurso para o i th registro.
### Pré-requisitos de conjunto de dados tabulares em Formato JSON Lines
Linhas JSON é um formato de texto para representar dados estruturados em que cada linha é um objeto JSON válido. Atualmente, os trabalhos de processamento do SageMaker Clarify são compatíveis apenas com linhas JSON de formato denso SageMaker AI. Para estar em conformidade com o formato exigido, todos os atributos de um registro devem ser listados em uma única matriz JSON. Para obter mais informações sobre linhas JSON, consulte [Formato da solicitação JSONLINES](cdf-inference.md#cm-jsonlines).
**nota**
Todos os arquivos de dados de linhas JSON fornecidos para a tarefa de processamento do SageMaker Clarify devem ser codificados em UTF-8 para garantir a compatibilidade.
A seguir está um exemplo de como definir uma configuração de análise para um registro que contém uma **chave de nível superior** e uma **lista** de elementos.
```
{"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}
...
```
A análise de configuração do exemplo de conjunto de dados anterior deve definir os parâmetros da seguinte forma:
+ Para indicar a localização do rótulo de verdade fundamental, o parâmetro `label` deve ser definido como a JMESPath expressão`label`.
+ Para indicar a localização da matriz de recursos, o parâmetro `features` deve ser definido como a JMESPath expressão`features`.
Veja a seguir um exemplo de como definir uma configuração de análise para um registro que contém uma **chave de nível superior** e uma **chave aninhada** que contém uma **lista** de elementos.
```
{"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}}
...
```
A análise de configuração do exemplo de conjunto de dados anterior deve definir os parâmetros da seguinte forma:
+ O parâmetro `label` deve ser definido como a JMESPath expressão `data.label` para indicar a localização do rótulo de verdade fundamental.
+ O parâmetro `features` deve ser definido como a JMESPath expressão `data.features` para indicar a localização da matriz de recursos.
### Pré-requisitos de conjunto de dados tabulares em formato Parquet
O [Parquet](https://parquet.apache.org/) é um formato de dados binários orientado por colunas. Atualmente, os trabalhos de processamento do SageMaker Clarify oferecem suporte ao carregamento de arquivos de dados do Parquet somente quando a contagem de instâncias de processamento é`1`.
Como os trabalhos de processamento do SageMaker Clarify não oferecem suporte à solicitação do endpoint ou à resposta do endpoint no formato Parquet, você deve especificar o formato de dados da solicitação do endpoint definindo o parâmetro de configuração da análise `content_type` para um formato compatível. Para obter mais informações, consulte `content_type` em [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
Os dados do Parquet devem ter nomes das colunas formatados como cadeias de caracteres. Use o parâmetro `label` de configuração de análise para definir o nome da coluna do rótulo para indicar a localização dos rótulos verdadeiros fundamentais. Todas as outras colunas são designadas como atributos.
# Solicitações de endpoint para dados tabulares
Para obter previsões de modelo para análise de viés pós-treinamento e análise de importância de recursos, os trabalhos de processamento do SageMaker Clarify serializam os dados tabulares em bytes e os enviam para um endpoint de inferência como carga útil de solicitação. Esses dados tabulares são provenientes do conjunto de dados de entrada ou são gerados. Se forem dados sintéticos, eles são gerados pelo explicador para análise SHAP ou análise PDP.
O formato de dados da carga útil da solicitação deve ser especificado pelo parâmetro `content_type` de configuração da análise. Se o parâmetro não for fornecido, o trabalho de processamento do SageMaker Clarify usará o valor do `dataset_type` parâmetro como o tipo de conteúdo. Para obter mais informações sobre `content_type` ou `dataset_type`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
As seções a seguir mostram exemplos de solicitações de endpoint nos formatos CSV e JSON Lines.
## Solicitação de endpoint no formato CSV
A tarefa de processamento do SageMaker Clarify pode serializar dados no formato CSV (tipo MIME:). `text/csv` A tabela a seguir mostra exemplos das cargas úteis de solicitações serializadas.
| Carga útil da solicitação de endpoint (representação de string) | Comentários |
| --- | --- |
| '1,2,3,4' | Registro único (quatro atributos numéricos). |
| '1,2,3,4\$1n5,6,7,8' | Dois registros, separados por quebra de linha '\$1n'. |
| '"Este é um bom produto” ,5' | Registro único (um atributo de texto e um atributo numérico). |
| '"Este é um bom produto” ,5\$1n“Experiência de compra ruim” ,1' | Dois registros. |
## A solicitação do endpoint está no formato JSON Lines
O trabalho de processamento do SageMaker Clarify pode serializar dados no formato denso SageMaker AI JSON Lines (tipo MIME:). `application/jsonlines` Para obter mais informações sobre linhas JSON, consulte [Formato da solicitação JSONLINES](cdf-inference.md#cm-jsonlines).
Para transformar dados tabulares em dados JSON, forneça uma string de modelo para o parâmetro `content_template` de configuração da análise. Para obter mais informações sobre o `content_template`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md). A tabela a seguir mostra exemplos de cargas úteis da solicitação de linhas JSON serializadas.
| Carga útil da solicitação de endpoint (representação de string) | Comentários |
| --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | Registro único Nesse caso, o modelo se parece `'{"data":{"features":$features}}' ` e `$features` é substituído pela lista de atributos `[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' | Dois registros. |
| '\$1"features":["Este é um bom produto",5]\$1' | Registro único Neste caso, o modelo se parece com `'{"features":$features}'` e \$1features é substituído pela lista de atributos `["This is a good product",5]`. |
| '\$1"features":["Este é um bom produto",5]\$1\$1n\$1"features":["Experiência de compra ruim",1]\$1' | Dois registros. |
## A solicitação de endpoint está no formato JSON
Um trabalho de processamento do SageMaker Clarify pode serializar dados em estruturas JSON arbitrárias (tipo MIME:). `application/json` Para fazer isso, você deve fornecer uma string de modelo para o `content_template` parâmetro de configuração da análise. Isso é usado pelo trabalho de processamento do SageMaker Clarify para construir a estrutura JSON externa. Você também deve fornecer uma string de modelo para `record_template`, que é usada para construir a estrutura JSON para cada registro. Para obter mais informações sobre `content_template` e `record_template`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
**nota**
Como `content_template` e `record_template` são parâmetros de string, qualquer caractere de aspa dupla (`"`) que faça parte da estrutura serializada do JSON deve ser anotado como um caractere de escape em sua configuração. Por exemplo, se você quiser escapar de uma aspa dupla em Python, você pode digitar o seguinte para `content_template`:
```
"{\"data\":{\"features\":$record}}}"
```
A tabela a seguir mostra exemplos de cargas úteis de solicitações JSON serializadas e os parâmetros `content_template` e `record_template` correspondentes necessários para construí-las.
| Carga útil da solicitação de endpoint (representação de string) | Comentários | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | Um único registro por vez. | '\$1"data":\$1"features":\$1record\$1\$1\$1' | “\$1features" |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | Vários registros com nomes de atributos. | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | “\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | Vários registros e pares de chave-valor. | “\$1records" | “\$1features\$1kvp" |
| ‘\$1"A": 0, "B": 1\$1' | Um único registro por vez e pares de chave-valor. | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "nested": \$1"B": 1\$1\$1' | Como alternativa, use o record\$1template totalmente detalhado para estruturas arbitrárias. | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# Resposta de endpoint para dados tabulares
Depois que o trabalho de processamento do SageMaker Clarify recebe a resposta de uma invocação de endpoint de inferência, ele desserializa a carga útil da resposta e extrai previsões dela. Use o parâmetro `accept_type` de configuração de análise para especificar o formato de dados da carga útil da resposta. Se não `accept_type` for fornecido, o trabalho de processamento do SageMaker Clarify usará o valor do parâmetro content\$1type como formato de saída do modelo. Para saber mais sobre o `accept_type`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
As predições podem consistir em rótulos previstos para análise de desvio ou valores de probabilidade (pontuações) para análise de importância do atributo. Na configuração da análise `predictor`, os três parâmetros a seguir extraem as predições.
+ O parâmetro `probability` é usado para localizar os valores de probabilidade (pontuações) na resposta do endpoint.
+ O parâmetro `label` é usado para localizar os rótulos previstos na resposta do endpoint.
+ (Opcional) O parâmetro `label_headers` fornece os rótulos previstos para um modelo multiclasse.
As diretrizes a seguir se referem às respostas de endpoints nos formatos CSV, JSON Lines e JSON.
## O Endpoint Response está em formato CSV
Se a carga de resposta estiver no formato CSV (tipo MIME:`text/csv`), a tarefa de processamento do SageMaker Clarify desserializará cada linha. Em seguida, ele extrai as predições dos dados desserializados usando os índices de coluna fornecidos na configuração da análise. As linhas na carga útil da resposta devem corresponder aos registros na carga útil da solicitação.
As tabelas a seguir fornecem exemplos de dados de resposta em diferentes formatos e para diferentes tipos de problemas. Seus dados podem variar desses exemplos, desde que as predições possam ser extraídas de acordo com a configuração da análise.
As seções a seguir mostram exemplos de respostas de endpoint em formatos CSV.
### A resposta do endpoint está no formato CSV e contém apenas probabilidade
A tabela a seguir é um exemplo de resposta de endpoint para problemas de regressão e classificação binária.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '0.6' |
| Dois registros (resultados em uma linha, divididos por vírgula). | '0.6,0.3' |
| Dois registros (resultados em duas linhas) | '0.6\$1n0.3' |
Para o exemplo anterior, o endpoint gera um único valor de probabilidade (pontuação) do rótulo previsto. Para extrair probabilidades usando o índice e usá-las para análise da importância do atributo, defina o parâmetro `probability` de configuração da análise como índice da coluna `0`. Essas probabilidades também podem ser usadas para análise de desvio se forem convertidas em valor binário usando o parâmetro `probability_threshold`. Para saber mais sobre o `probability_threshold`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
A tabela a seguir é um exemplo de resposta de endpoint para um problema multiclasse.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único de um modelo multiclasse (três classes). | '0.1,0.6,0.3' |
| Dois registros de um modelo multiclasse (três classes). | '0.1,0.6,0.3\$1n0.2,0.5,0.3' |
Para o exemplo anterior, o endpoint gera uma lista de probabilidades (pontuações). Se nenhum índice for fornecido, todos os valores serão extraídos e usados para análise de importância do atributo. Se o parâmetro de configuração de análise `label_headers` for fornecido. Em seguida, o trabalho de processamento do SageMaker Clarify pode selecionar o cabeçalho do rótulo com a probabilidade máxima como o rótulo previsto, que pode ser usado para análise de viés. Para saber mais sobre o `label_headers`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
### A resposta do endpoint está no formato CSV e contém apenas o rótulo previsto
A tabela a seguir é um exemplo de resposta de endpoint para problemas de regressão e classificação binária.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '1' |
| Dois registros (resultados em uma linha, divididos por vírgula). | '1,0' |
| Dois registros (resultados em duas linhas) | '1\$1n0' |
Para o exemplo anterior, o endpoint gera o rótulo previsto em vez da probabilidade. Defina o parâmetro `label` da configuração `predictor` para o índice da coluna `0` para que os rótulos previstos possam ser extraídos usando o índice e usados para análise de polarização.
### A resposta do endpoint está no formato CSV e contém rótulo e probabilidade previstos
A tabela a seguir é um exemplo de resposta de endpoint para problemas de regressão e classificação binária.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '1,0.6' |
| Dois registros | '1,0.6\$1n0,0.3' |
Para o exemplo anterior, o endpoint gera o rótulo previsto seguido por sua probabilidade. Defina o `label` parâmetro da `predictor` configuração como índice `0` da coluna e `probability` defina como índice da coluna `1` para extrair os dois valores do parâmetro.
### A resposta do endpoint está no formato CSV e contém rótulos e probabilidades previstas (multiclasse)
Um modelo multiclasse treinado pelo Amazon SageMaker Autopilot pode ser configurado para gerar a representação em sequência da lista de rótulos e probabilidades previstos. A tabela de exemplo a seguir mostra um exemplo de resposta de endpoint de um modelo configurado para gerar `predicted_label`, `probability`, `labels` e `probabilities`.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"' |
| Dois registros | '"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]"' |
No exemplo anterior, o trabalho de processamento do SageMaker Clarify pode ser configurado das seguintes maneiras para extrair as previsões.
Para análise de desvio, o exemplo anterior pode ser configurado como um dos seguintes:
+ Defina o parâmetro `label` da configuração `predictor` como `0` para extrair o rótulo previsto.
+ Defina o parâmetro para `2` extrair os rótulos previstos e `probability` defina como `3` para extrair as probabilidades correspondentes. O trabalho de processamento do SageMaker Clarify pode determinar automaticamente o rótulo previsto identificando o rótulo com o maior valor de probabilidade. Referindo-se ao exemplo anterior de um único registro, o modelo prevê três rótulos: `cat`, `dog` e `fish`, com probabilidades correspondentes de `0.1`, `0.6` e `0.3`. Com base nessas probabilidades, o rótulo previsto é `dog`, pois tem o maior valor de probabilidade de `0.6`.
+ Defina `probability` como `3` para extrair as probabilidades. Se `label_headers` for fornecido, o trabalho de processamento do SageMaker Clarify poderá determinar automaticamente o rótulo previsto identificando o cabeçalho do rótulo com o maior valor de probabilidade.
Para análise da importância do atributo, o exemplo anterior pode ser configurado da seguinte forma:
+ Defina `probability` para `3` extrair as probabilidades de todos os rótulos previstos. Em seguida, as atribuições de atributos serão computadas para todos os rótulos. Se o cliente não especificar `label_headers`, as etiquetas previstas serão usadas como cabeçalhos de etiquetas no relatório de análise.
## A resposta do endpoint está no formato JSON Lines
Se a carga de resposta estiver no formato JSON Lines (tipo MIME:`application/jsonlines`), a tarefa de processamento do SageMaker Clarify desserializará cada linha como JSON. Em seguida, ele extrai as previsões dos dados desserializados usando JMESPath expressões fornecidas na configuração da análise. As linhas na carga útil daresposta devem corresponder aos registros na carga útil da solicitação. As tabelas a seguir mostram exemplos de dados de resposta em diferentes formatos. Seus dados podem variar desses exemplos, desde que as predições possam ser extraídas de acordo com a configuração da análise.
As seções a seguir mostram exemplos de respostas de endpoint em formato JSON Lines.
### A resposta do endpoint está no formato JSON Lines e contém apenas probabilidade
A tabela a seguir é um exemplo de resposta de endpoint que gera apenas o valor de probabilidade (pontuação).
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"score":0.6\$1' |
| Dois registros | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' |
Para o exemplo anterior, defina o parâmetro de configuração de análise `probability` como JMESPath expressão “pontuação” para extrair seu valor.
### A resposta do endpoint está no formato JSON Lines e contém apenas o rótulo previsto
A tabela a seguir é um exemplo de resposta de endpoint que gera apenas o rótulo previsto.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"prediction":1\$1' |
| Dois registros | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
Para o exemplo anterior, defina o `label` parâmetro da configuração do preditor como JMESPath expressão`prediction`. Em seguida, o trabalho de processamento do SageMaker Clarify pode extrair os rótulos previstos para análise de viés. Para obter mais informações, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
### A resposta do endpoint está no formato JSON Lines e contém rótulo e probabilidade previstos
A tabela a seguir é um exemplo de resposta de endpoint que gera o rótulo previsto e sua pontuação.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"prediction":1,"score":0.6\$1' |
| Dois registros | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
No exemplo anterior, defina o `label` parâmetro da `predictor` configuração como JMESPath expressão “previsão” para extrair os rótulos previstos. `probability`Defina a JMESPath expressão “pontuação” para extrair a probabilidade. Para obter mais informações, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
### A resposta do endpoint está no formato JSON Lines e contém rótulos e probabilidades previstas (multiclasse)
A tabela a seguir é um exemplo de resposta de endpoint de um modelo multiclasse que gera o seguinte:
+ Uma lista de rótulos previstos.
+ Probabilidades e o rótulo previsto selecionado e sua probabilidade.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' |
| Dois registros | '\$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' |
No exemplo anterior, a tarefa de processamento do SageMaker Clarify pode ser configurada de várias maneiras para extrair as previsões.
Para análise de desvio, o exemplo anterior pode ser configurado como **um** dos seguintes:
+ Defina o `label` parâmetro da `predictor` configuração para a JMESPath expressão “predicted\$1label” para extrair o rótulo previsto.
+ Defina o parâmetro como a JMESPath expressão “predicted\$1labels” para extrair os rótulos previstos. `probability`Defina a JMESPath expressão “probabilidades” para extrair suas probabilidades. A tarefa SageMaker Clarify determina automaticamente o rótulo previsto identificando o rótulo com o maior valor de probabilidade.
+ `probability`Defina a JMESPath expressão “probabilidades” para extrair suas probabilidades. Se `label_headers` for fornecido, o trabalho de processamento do SageMaker Clarify poderá determinar automaticamente o rótulo previsto identificando o rótulo com o maior valor de probabilidade.
Para analisar a importância do atributo, faça o seguinte:
+ `probability`Defina a JMESPath expressão “probabilidades” para extrair suas probabilidades de todos os rótulos previstos. Em seguida, as atribuições de atributos serão computadas para todos os rótulos.
## A resposta do endpoint está no formato JSON
Se a carga de resposta estiver no formato JSON (tipo MIME:`application/json`), a tarefa de processamento do SageMaker Clarify desserializará toda a carga como JSON. Em seguida, ele extrai as previsões dos dados desserializados usando JMESPath expressões fornecidas na configuração da análise. Os registros na carga útil da resposta devem corresponder aos registros na carga útil da solicitação.
As seções a seguir mostram exemplos de respostas de endpoint em formatos JSON. As tabelas a seguir fornecem exemplos de dados de resposta em diferentes formatos e para diferentes tipos de problemas. Seus dados podem variar desses exemplos, desde que as predições possam ser extraídas de acordo com a configuração da análise.
### A resposta do endpoint está no formato JSON e contém apenas probabilidade
A tabela a seguir é um exemplo de resposta de um endpoint que gera apenas o valor de probabilidade (pontuação).
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '[0.6]' |
| Dois registros | '[0.6,0.3]' |
No exemplo anterior, não há quebra de linha na carga útil da resposta. Em vez disso, um único objeto JSON contém uma lista de pontuações, uma para cada registro na solicitação. Defina o parâmetro de configuração da análise `probability` para a JMESPath expressão “[\$1]” para extrair o valor.
### A resposta do endpoint está no formato JSON Lines e contém apenas o rótulo previsto
A tabela a seguir é um exemplo de resposta de um endpoint que gera apenas o rótulo previsto.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"predicted\$1labels":[1]\$1' |
| Dois registros | '\$1"predicted\$1labels":[1,0]\$1' |
Defina o `label` parâmetro da `predictor` configuração para a JMESPath expressão “predicted\$1labels” e, em seguida, o trabalho de processamento do SageMaker Clarify poderá extrair os rótulos previstos para análise de viés.
### A resposta do endpoint está no formato JSON e contém rótulo e probabilidade previstos
A tabela a seguir é um exemplo de resposta de endpoint que gera o rótulo previsto e sua pontuação.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '\$1"predictions":[\$1"label":1,"score":0.6\$1' |
| Dois registros | ‘\$1"predictions":[\$1"label":1,"score":0.6\$1,\$1"label":0,"score":0.3\$1]\$1' |
No exemplo anterior, defina o `label` parâmetro da `predictor` configuração para a JMESPath expressão “predictions [\$1] .label” para extrair os rótulos previstos. `probability`Defina a JMESPath expressão “predictions [\$1] .score” para extrair a probabilidade.
### A resposta do endpoint está no formato JSON e contém rótulos e probabilidades previstas (multiclasse)
A tabela a seguir é um exemplo de resposta de um endpoint de um modelo multiclasse que gera o seguinte:
+ Uma lista de rótulos previstos.
+ Probabilidades e o rótulo previsto selecionado e sua probabilidade.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Registro único | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1]' |
| Dois registros | '[\$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]' |
O trabalho de processamento do SageMaker Clarify pode ser configurado de várias maneiras para extrair as previsões.
Para análise de desvio, o exemplo anterior pode ser configurado como **um** dos seguintes:
+ Defina o `label` parâmetro da `predictor` configuração para a JMESPath expressão “[\$1] .predicted\$1label” para extrair o rótulo previsto.
+ Defina o parâmetro como a JMESPath expressão “[\$1] .predicted\$1labels” para extrair os rótulos previstos. `probability`Defina a JMESPath expressão “[\$1] .probabilidades” para extrair suas probabilidades. O trabalho de processamento do SageMaker Clarify pode determinar automaticamente a etiqueta prevista identificando a etiqueta com o maior valor de proximidade.
+ `probability`Defina a JMESPath expressão “[\$1] .probabilidades” para extrair suas probabilidades. Se `label_headers` for fornecido, o trabalho de processamento do SageMaker Clarify poderá determinar automaticamente o rótulo previsto identificando o rótulo com o maior valor de probabilidade.
Para análise da importância do recurso, `probability` defina a JMESPath expressão “[\$1] .probabilidades” para extrair suas probabilidades de todos os rótulos previstos. Em seguida, as atribuições de atributos serão computadas para todos os rótulos.
# Verifique previamente a solicitação e resposta do endpoint para dados tabulares
Recomendamos que você implante seu modelo em um endpoint de inferência de SageMaker IA em tempo real e envie solicitações para o endpoint. Examine manualmente as solicitações e respostas para garantir que ambas estejam em conformidade com os requisitos da seção [Solicitações de endpoint para dados tabulares](clarify-processing-job-data-format-tabular-request.md) e da seção [Resposta de endpoint para dados tabulares](clarify-processing-job-data-format-tabular-response.md). Se o seu contêiner de modelo oferecer compatibilidade com solicitações em lote, você poderá começar com uma única solicitação de registro e, em seguida, tentar dois ou mais registros.
Os comandos a seguir mostram como solicitar uma resposta usando o AWS CLI. O AWS CLI vem pré-instalado nas instâncias SageMaker Studio e SageMaker Notebook. Para instalar o AWS CLI, siga este [guia de instalação](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
```
Os parâmetros são definidos da seguinte forma:
+ `$ENDPOINT NAME` - O nome do endpoint.
+ `$CONTENT_TYPE`: O tipo MIME da solicitação (entrada do contêiner do modelo).
+ `$ACCEPT_TYPE`: O tipo MIME da resposta (saída do contêiner do modelo).
+ `$REQUEST_DATA`: A string de carga útil solicitada.
+ `$CLI_BINARY_FORMAT`: o formato do parâmetro da interface da linha de comando (CLI). Para AWS CLI v1, esse parâmetro deve permanecer em branco. Para v2, esse parâmetro deve ser definido como `--cli-binary-format raw-in-base64-out`.
**nota**
AWS CLI [A v2 passa parâmetros binários como strings codificadas em base64 por padrão.](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam)
# AWS CLI exemplos de v1
O exemplo na seção anterior foi para a AWS CLI v2. Os exemplos de solicitação e resposta a seguir de e para o endpoint usam AWS CLI v1.
## Solicitação e resposta de endpoint em formato CSV
No exemplo de código a seguir, a solicitação consiste em um único registro e a resposta é seu valor de probabilidade.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
0.6
```
No exemplo de código a seguir, a solicitação consiste em dois registros e a resposta inclui suas probabilidades, que são separadas por uma vírgula.
```
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
```
No exemplo de código anterior, a `$'content'` expressão no `--body` diz ao comando para interpretar `'\n'` no conteúdo como uma quebra de linha. Segue o resultado da resposta.
```
0.6,0.3
```
No exemplo de código a seguir, a solicitação consiste em dois registros, a resposta inclui suas probabilidades, separadas por uma quebra de linha.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
0.6
0.3
```
No exemplo de código a seguir, a solicitação consiste em um único registro e a resposta são valores de probabilidade de um modelo multiclasse contendo três classes.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
0.1,0.6,0.3
```
No exemplo de código a seguir, a solicitação consiste em dois registros e a resposta inclui seus valores de probabilidade de um modelo multiclasse contendo três classes.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
0.1,0.6,0.3
0.2,0.5,0.3
```
No exemplo de código a seguir, a solicitação consiste em dois registros e a resposta inclui rótulo e probabilidade previstos.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
1,0.6
0,0.3
```
No exemplo de código a seguir, a solicitação consiste em dois registros e a resposta inclui cabeçalhos de rótulos e probabilidades.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
"['cat','dog','fish']","[0.1,0.6,0.3]"
"['cat','dog','fish']","[0.2,0.5,0.3]"
```
## Solicitação e resposta de endpoint em formato JSON Lines
No exemplo de código a seguir, a solicitação consiste em um único registro e a resposta é seu valor de probabilidade.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"score":0.6}
```
No exemplo de código a seguir, a solicitação contém dois registros e a resposta inclui rótulo e probabilidade previstos.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"predicted_label":1,"probability":0.6}
{"predicted_label":0,"probability":0.3}
```
No exemplo de código a seguir, a solicitação contém dois registros e a resposta inclui cabeçalhos de rótulos e probabilidades.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}
```
## Solicitação e resposta do endpoint em formatos mistos
No exemplo de código a seguir, a solicitação está no formato CSV e a resposta está no 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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"probability":0.6}
{"probability":0.3}
```
No exemplo de código a seguir, a solicitação está no formato JSON Lines e a resposta está no 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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
0.6
0.3
```
No exemplo de código a seguir, a solicitação está no formato CSV e a resposta está no 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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# Requisitos de dados de imagens
Um trabalho de processamento do SageMaker Clarify fornece suporte para explicar imagens. Este tópico fornece os requisitos de formato de dados para dados de imagem. Para obter mais informações sobre o processamento de dados de imagem, consulte [Analise os dados da imagem para explicabilidade da visão computacional](clarify-processing-job-run.md#clarify-processing-job-run-cv).
Um conjunto de dados de imagem contém um ou mais arquivos de imagem. Para identificar um conjunto de dados de entrada para o trabalho de processamento do SageMaker Clarify, defina um `dataset_uri` parâmetro de configuração [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs)nomeado `dataset` ou de análise como um prefixo URI do Amazon S3 dos seus arquivos de imagem.
Os formatos de arquivo de imagem e extensões de arquivo compatíveis estão listados na tabela a seguir.
| Formato de imagem | Extensão do arquivo |
| --- | --- |
| JPEG | jpg, jpeg |
| PNG | png |
Configure o parâmetro `dataset_type` da análise para o valor **application/x-image**. Como o tipo não é um formato de arquivo de imagem específico, `content_type` ele será usado para decidir o formato e a extensão do arquivo de imagem.
O trabalho de processamento do SageMaker Clarify carrega cada arquivo de imagem em uma [NumPymatriz](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) tridimensional para processamento adicional. As três dimensões incluem altura, largura e valores RGB de cada pixel.
## Formato de solicitação do endpoint
O trabalho de processamento do SageMaker Clarify converte os dados RGB brutos de uma imagem em um formato de imagem compatível, como JPEG. Ele faz isso antes de enviar os dados ao endpoint para predições. Os formatos de imagem compatíveis são os seguintes:
| Formatos de dados | Tipo MIME | Extensão do arquivo |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg, jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | Todas acima |
Especifique o formato de dados da carga útil da solicitação usando o parâmetro de configuração de análise `content_type`. Se o `content_type` não for fornecido, o formato de dados será padronizado como `image/jpeg`.
## Formato de resposta do endpoint
Ao receber a resposta de uma invocação de endpoint de inferência, o trabalho de processamento do SageMaker Clarify desserializa a carga útil da resposta e, em seguida, extrai as previsões dela.
### Problema de classificação de imagem
O formato de dados da carga útil da resposta deve ser especificado pelo parâmetro de configuração de análise accept\$1type. Se `accept_type` não for fornecido, o formato de dados será padronizado como `application/json`. Os formatos compatíveis são os mesmos descritos na **resposta do Endpoint para dados tabulares na seção de dados** tabulares.
Veja um [Inferência com o algoritmo de classificação de imagens](image-classification.md#IC-inference) exemplo de um algoritmo de classificação de imagens integrado com SageMaker IA que aceita uma única imagem e, em seguida, retorna uma matriz de valores de probabilidade (pontuações), cada um para uma classe.
Conforme mostrado na tabela a seguir, quando o parâmetro `content_type` é definido como `application/jsonlines`, a resposta é um objeto JSON.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Imagem única | '\$1"prediction":[0.1,0.6,0.3]\$1' |
No exemplo anterior, defina o `probability` parâmetro como JMESPath expressão “previsão” para extrair as pontuações.
Conforme mostrado na tabela a seguir, quando o parâmetro `content_type` é definido como `application/json`, a resposta é um objeto JSON.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Imagem única | '[0.1,0.6,0.3]' |
No exemplo anterior, `probability` defina a JMESPath expressão “[\$1]” para extrair todos os elementos da matriz. No exemplo anterior, [`0.1, 0.6, 0.3]` é extraído. Alternativamente, se você pular a configuração do parâmetro de configuração `probability`, todos os elementos da matriz também serão extraídos. Isso ocorre porque toda a carga útil é desserializada como as predições.
### Problema de detecção de objetos
A configuração de análise `accept_type` tem o padrão `application/json`, e o único formato compatível é o Object Detection Inference Format. Para obter mais informações sobre os formatos de resposta, consulte [Formatos de resposta](object-detection-in-formats.md#object-detection-recordio).
A tabela a seguir é um exemplo de resposta de um terminal que gera uma matriz. Cada elemento da matriz é uma matriz de valores contendo o índice da classe, a pontuação de confiança e as coordenadas da caixa delimitadora do objeto detectado.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Imagem única (um objeto) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| Imagem única (dois objetos) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
A tabela a seguir é um exemplo de resposta de um endpoint que gera um objeto JSON com uma chave referente à matriz. Defina a configuração da análise `probability` com a chave “predição” para extrair os valores.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) |
| --- | --- |
| Imagem única (um objeto) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| Imagem única (dois objetos) | '\$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' |
## Verifique previamente a solicitação e a resposta do endpoint para dados de imagem
Recomendamos que você implante seu modelo em um endpoint de inferência de SageMaker IA em tempo real e envie solicitações para o endpoint. Examine manualmente as solicitações e respostas. Certifique-se de que ambos estejam em conformidade com os requisitos na seção **Solicitação do Endpoint para dados de imagem** e **Resposta do Endpoint para dados de imagem**.
A seguir estão dois exemplos de código que mostram como enviar solicitações e examinar as respostas para problemas de classificação de imagens e detecção de objetos.
### Problema de classificação de imagem
O código de exemplo a seguir instrui um endpoint a ler um arquivo PNG e depois classificá-lo.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
[0.1,0.6,0.3]
```
### Problema de detecção de objetos
O código de exemplo a seguir instrui um endpoint a ler um arquivo JPEG e, em seguida, detectar os objetos nele contidos.
```
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
```
A partir do exemplo de código anterior, segue a saída da resposta.
```
{"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]]}
```
# Dados de séries temporais
Os dados de séries temporais são dados que podem ser carregados em um quadro de dados tridimensional. No quadro, em cada “timestamp”, cada linha representa um registro de destino e, cada registro de destino, tem uma ou mais colunas. Os valores em cada célula do quadro de dados podem ser de tipos de dados numéricos, categóricos ou de texto.
## Pré-requisitos do conjunto de dados de séries temporais
Antes da análise, conclua as etapas de pré-processamento necessárias para preparar seus dados, como limpeza de dados ou engenharia de atributos. Você pode fornecer um ou vários conjuntos de dados. Se você fornecer vários conjuntos de dados, use um dos métodos a seguir para fornecê-los à tarefa de processamento do SageMaker Clarify:
+ Use uma configuração [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)nomeada `dataset` ou de análise `dataset_uri` para especificar o conjunto de dados principal. Para obter mais informações sobre `dataset_uri`, consulte a lista de parâmetros em [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
+ Use o parâmetro `baseline` fornecido no arquivo de configuração da análise. O conjunto de dados de linha de base é necessário para `static_covariates`, se estiver presente. Para obter mais informações sobre o arquivo de configuração de análise, incluindo exemplos, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
A tabela a seguir lista os formatos de dados compatíveis, suas extensões de arquivo e tipos de MIME.
| Formato de dados | Extensão do arquivo | Tipo MIME |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
O JSON é um formato flexível que pode representar qualquer nível de complexidade em seus dados estruturados. Conforme mostrado na tabela, o SageMaker Clarify oferece suporte aos formatos `item_records``timestamp_records`, `columns` e.
## Exemplos de configuração de conjuntos de dados de séries temporais
Esta seção mostra como definir uma configuração de análise usando `time_series_data_config` para dados de séries temporais no formato JSON. Suponha que você tenha um conjunto de dados com dois itens, cada um com um carimbo de data/hora (t), uma série temporal de destino (x), duas séries temporais relacionadas (r) e duas covariáveis estáticas (u), da seguinte forma:
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
Você pode codificar o conjunto de dados usando `time_series_data_config` de três maneiras diferentes, dependendo do `dataset_format`. As seções a seguir descrevem cada método.
### Configuração de dados de séries temporais quando `dataset_format` for `columns`
O exemplo a seguir usa o valor `columns` para `dataset_format`. O arquivo JSON a seguir representa o conjunto de dados anterior.
```
{
"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
}
```
Observe que os IDs dos itens são repetidos no campo `ids`. A implementação correta do `time_series_data_config` é mostrada a seguir:
```
"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"
}
```
### Configuração de dados de séries temporais quando `dataset_format` for `item_records`
O exemplo a seguir usa o valor `item_records` para `dataset_format`. O arquivo JSON a seguir representa o conjunto de dados.
```
[
{
"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}
]
}
]
```
Cada item é representado como uma entrada separada no JSON. O trecho a seguir mostra o correspondente `time_series_data_config` (que usa 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"
}
```
### Configuração de dados de séries temporais quando `dataset_format` for `timestamp_record`
O exemplo a seguir usa o valor `timestamp_record` para `dataset_format`. O arquivo JSON a seguir representa o conjunto de dados anterior.
```
[
{"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},
]
```
Cada entrada do JSON representa um único registro de data/hora e corresponde a um único item. A implementação de `time_series_data_config` é mostrada da seguinte forma:
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# Solicitações de endpoint para dados de séries temporais
Um trabalho de processamento do SageMaker Clarify serializa os dados em estruturas JSON arbitrárias (com o tipo MIME:). `application/json` Para fazer isso, você deve fornecer uma string de modelo para o `content_template` parâmetro de configuração da análise. Isso é usado pelo trabalho de processamento do SageMaker Clarify para criar a consulta JSON fornecida ao seu modelo. `content_template`contém um registro ou vários registros do seu conjunto de dados. Você também deve fornecer uma string de modelo para `record_template`, que é usada para construir a estrutura JSON de cada registro. Esses registros são, então, inseridos em `content_template`. Para obter mais informações sobre `content_type` ou `dataset_type`, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
**nota**
Como `content_template` e `record_template` são parâmetros de string, qualquer caractere de aspa dupla (") que faça parte da estrutura serializada do JSON deve ser anotado como um caractere de escape em sua configuração. Por exemplo, se você quiser escapar uma aspa dupla em Python, você pode inserir o seguinte valor para `content_template`:
```
'$record'
```
A tabela a seguir mostra exemplos de cargas úteis de solicitações JSON serializadas e os parâmetros `content_template` e `record_template` correspondentes que são necessários para a construção.
| Caso de uso | Carga útil da solicitação de endpoint (representação de string) | content\$1template | record\$1template |
| --- | --- | --- | --- |
| Um único registro por vez | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| Registro único com `$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}'` |
| Vários registros | `{"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}'` |
| Vários registros com `$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}'` |
# Resposta do endpoint para dados de séries temporais
O trabalho de processamento do SageMaker Clarify desserializa toda a carga como JSON. Em seguida, ele extrai as previsões dos dados desserializados usando JMESPath expressões fornecidas na configuração da análise. Os registros na carga útil da resposta devem corresponder aos registros na carga útil da solicitação.
A tabela a seguir é um exemplo de resposta de um endpoint que gera apenas o valor médio da predição. O valor de `forecast` usado no `predictor` campo na [configuração da análise](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters) deve ser fornecido como uma JMESPath expressão para encontrar o resultado da previsão para o trabalho de processamento.
| Carga útil da solicitação de endpoint | Carga útil da resposta do endpoint (representação de string) | JMESPath expressão para previsão na configuração de análise |
| --- | --- | --- |
| Exemplo de registro único. Configuração deve ser `TimeSeriesModelConfig(forecast="prediction.mean")` para extrair a predição corretamente. | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| Para vários registros. Uma resposta de endpoint AWS DeepAR. | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# Verifique previamente a solicitação e a resposta do endpoint para dados de séries temporais
É recomendável implantar seu modelo em um endpoint de inferência de SageMaker IA em tempo real e enviar solicitações para o endpoint. Examine manualmente as solicitações e respostas para garantir que ambas estejam em conformidade com os requisitos das seções [Solicitações de endpoint para dados de séries temporais](clarify-processing-job-data-format-time-series-request-jsonlines.md) e [Resposta do endpoint para dados de séries temporais](clarify-processing-job-data-format-time-series-response-json.md). Se o seu contêiner de modelo oferecer compatibilidade com solicitações em lote, você poderá começar com uma única solicitação de registro e, em seguida, tentar dois ou mais registros.
Os comandos a seguir demonstram como solicitar uma resposta usando a AWS CLI. O AWS CLI vem pré-instalado nas instâncias Studio e SageMaker Notebook. Para instalar o AWS CLI, siga o [guia de instalação](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
```
Os parâmetros são definidos da seguinte forma:
+ \$1ENDPOINT NAME: o nome do endpoint.
+ \$1CONTENT\$1TYPE: o tipo MIME da solicitação (entrada do contêiner do modelo).
+ \$1ACCEPT\$1TYPE: o tipo MIME da resposta (saída do contêiner do modelo).
+ \$1REQUEST\$1DATA: a string de carga útil solicitada.
+ \$1CLI\$1BINARY\$1FORMAT: o formato do parâmetro da interface de linha de comandos (CLI). Para AWS CLI v1, esse parâmetro deve permanecer em branco. Para v2, esse parâmetro deve ser definido como `--cli-binary-format raw-in-base64-out`.
**nota**
AWS CLI A v2 passa parâmetros binários como strings codificadas em base64 por padrão. Os exemplos de solicitação e resposta a seguir de e para o endpoint usam AWS CLI v1.
------
#### [ Example 1 ]
No exemplo de código a seguir, a solicitação consiste de um único registro.
```
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
```
O trecho a seguir mostra a saída correspondente da resposta.
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
No exemplo de código a seguir, a solicitação contém dois registros.
```
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
```
A seguir, está a saída resultante:
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------
# 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 para 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 ou pontuação de probabilidade 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 a 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 uma amostra 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\$1template. `'{"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 \$1'predictions [\$1] .mean [:2] '\$1\$1, 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.
# Resultados da análise
Depois que um trabalho de processamento do SageMaker Clarify for concluído, você poderá baixar os arquivos de saída para inspecioná-los ou visualizar os resultados no SageMaker Studio Classic. O tópico a seguir descreve os resultados da análise gerados pelo SageMaker Clarify, como o esquema e o relatório gerados pela análise de viés, análise SHAP, análise de explicabilidade por visão computacional e análise de gráficos de dependência parcial (). PDPs Se a análise de configuração contiver parâmetros para calcular várias análises, os resultados serão agregados em uma análise e um arquivo de relatório.
O diretório de saída da tarefa de processamento do SageMaker Clarify contém os seguintes arquivos:
+ `analysis.json`: Um arquivo que contém métricas de desvio e importância do atributo no formato JSON.
+ `report.ipynb`: Um caderno estático que contém código para ajudá-lo a visualizar métricas de desvio e a importância dos atributos.
+ `explanations_shap/out.csv`: Um diretório que é criado e contém arquivos gerados automaticamente com base em suas configurações de análise específicas. Por exemplo, se você ativar o parâmetro `save_local_shap_values`, os valores de SHAP locais por instância serão salvos no diretório `explanations_shap`. Como outro exemplo, se você `analysis configuration` não contiver um valor para o parâmetro de linha de base do SHAP, o trabalho de explicabilidade do SageMaker Clarify calculará uma linha de base agrupando o conjunto de dados de entrada. Em seguida, ele salvará a linha de base gerada no diretório.
Para obter mais informações, consulte as seções a seguir.
**Topics**
+ [Análise de desvio](#clarify-processing-job-analysis-results-bias)
+ [Análise de SHAP](#clarify-processing-job-analysis-results-shap)
+ [Análise de explicabilidade da visão computacional (CV)](#clarify-processing-job-analysis-results-cv)
+ [Análise de gráficos de dependência parcial (PDPs)](#clarify-processing-job-analysis-results-pdp)
+ [Valores assimétricos de Shapley](#clarify-processing-job-analysis-results-asymmshap)
## Análise de desvio
O Amazon SageMaker Clarify usa a terminologia documentada em [A Amazon SageMaker esclarece os termos de preconceito e imparcialidade](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) para discutir preconceitos e justiça.
### Esquema para o arquivo de análise
O arquivo de análise está no formato JSON e é organizado em duas seções: métricas de desvio pré-treinamento e métricas de desvio pós-treinamento. Os parâmetros para métricas de desvio pré-treinamento e pós-treinamento são os seguintes:
+ **pre\$1training\$1bias\$1metrics**: Parâmetros para métricas de desvio pré-treinamento. Para obter mais informações, consulte [Métricas de desvio pré-treinamento](clarify-measure-data-bias.md) e [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
+ **label**: O nome do rótulo de veracidade definido pelo parâmetro `label` da configuração da análise.
+ **label\$1value\$1or\$1threshold**: Uma string contendo os valores do rótulo ou o intervalo definido pelo parâmetro `label_values_or_threshold` da configuração de análise. Por exemplo, se o valor `1` for fornecido para o problema de classificação binária, a string será `1`. Se vários valores `[1,2]` forem fornecidos para o problema de várias classes, a string será `1,2`. Se um limite `40` for fornecido para o problema de regressão, a string será interna, como `(40, 68]`, em que `68` é o valor máximo do rótulo no conjunto de dados de entrada.
+ **facets**: A seção contém vários pares de valores-chave, em que a chave corresponde ao nome da faceta definido pelo parâmetro `name_or_index` da configuração da faceta e o valor é uma matriz de objetos de faceta. Cada objeto de faceta tem os seguintes membros:
+ **value\$1or\$1threshold**: Uma string contendo os valores da faceta ou o intervalo definido pelo parâmetro `value_or_threshold` da configuração da faceta.
+ **metrics**: A seção contém uma matriz de elementos métricos de desvio, e cada elemento métrico de desvio tem os seguintes atributos:
+ **name**: O nome abreviado da métrica de desvio. Por exemplo, `CI`.
+ **description**: O nome completo da métrica de desvio. Por exemplo, `Class Imbalance (CI)`.
+ **value**: O valor da métrica de desvio ou valor JSON nulo se a métrica de desvio não for calculada por um motivo específico. Os valores ±∞ são representados como strings `∞` e `-∞`, respectivamente.
+ **error**: Uma mensagem de erro opcional que explica por que a métrica de desvio não foi calculada.
+ **post\$1training\$1bias\$1metrics**: A seção contém as métricas de desvio pós-treinamento e segue um layout e uma estrutura semelhantes aos da seção de pré-treinamento. Para obter mais informações, consulte [Métricas de dados pós-treinamento e desvio do modelo](clarify-measure-post-training-bias.md).
Veja a seguir um exemplo de uma configuração de análise que calculará as métricas de desvio pré-treinamento e pós-treinamento.
```
{
"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
},
...
]
}]
}
}
}
```
### Relatório de análise de desvio
O relatório de análise de desvio inclui várias tabelas e diagramas que contêm explicações e descrições detalhadas. Isso inclui, entre outros, a distribuição dos valores do rótulo, a distribuição dos valores das facetas, o diagrama de performance do modelo de alto nível, uma tabela de métricas de desvio e suas descrições. Para obter mais informações sobre métricas de viés e como interpretá-las, consulte [Saiba como o Amazon SageMaker Clarify ajuda a detectar preconceitos](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/).
## Análise de SHAP
SageMaker Os trabalhos de processamento do Clarify usam o algoritmo Kernel SHAP para calcular as atribuições de recursos. O trabalho de processamento do SageMaker Clarify produz valores SHAP locais e globais. Isso ajuda a determinar a contribuição de cada atributo para as predições de modelo. Os valores de SHAP locais representam a importância do atributo para cada instância individual, enquanto os valores de SHAP globais agregam os valores de SHAP locais em todas as instâncias no conjunto de dados. Para obter mais informações sobre valores de SHAP e como interpretá-los, consulte [Atributos de atributos que usam valores de Shapley](clarify-shapley-values.md).
### Esquema para o arquivo de análise de SHAP
Os resultados da análise do SHAP globais são armazenados na seção de explicações do arquivo de análise, sob o método `kernel_shap`. Os diferentes parâmetros do arquivo de análise de SHAP são os seguintes:
+ **explanations**: A seção do arquivo de análise que contém os resultados da análise de importância do atributo.
+ **kernal\$1shap**: A seção do arquivo de análise que contém o resultado da análise do SHAP globais.
+ **global\$1shap\$1values**: Uma seção do arquivo de análise que contém vários pares de valores-chave. Cada chave no par de valores-chave representa um nome de atributo do conjunto de dados de entrada. Cada valor no par de valores-chave corresponde ao valor de SHAP global do atributo. O valor de SHAP global é obtido agregando os valores de SHAP por instância do atributo usando a configuração `agg_method`. Se a configuração `use_logit` estiver ativada, o valor será calculado usando os coeficientes de regressão logística, que podem ser interpretados como razões logarítmicas.
+ **expected\$1value**: A predição média do conjunto de dados da linha de base. Se a configuração `use_logit` estiver ativada, o valor será calculado usando os coeficientes de regressão logística.
+ **global\$1top\$1shap\$1text**: Usado para análise de explicabilidade da PLN. Uma seção do arquivo de análise que inclui um conjunto de pares de valores-chave. SageMaker Os trabalhos de processamento do Clarify agregam os valores de SHAP de cada token e, em seguida, selecionam os principais tokens com base em seus valores globais de SHAP. A configuração `max_top_tokens` define o número de tokens a serem selecionados.
Cada um dos principais tokens selecionados tem um par de valores-chave. A chave no par de valores-chave corresponde ao nome do atributo de texto do token principal. Cada valor no par de valores-chave são os valores de SHAP globais do token principal. Para obter um exemplo de um par de valor-chave `global_top_shap_text`, consulte a saída a seguir.
O exemplo a seguir mostra a saída da análise de SHAP de um conjunto de dados tabular.
```
{
"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
}
}
}
}
```
O exemplo a seguir mostra a saída da análise de SHAP de um conjunto de dados de texto. A saída correspondente à coluna `Comments` é um exemplo de saída gerada após a análise de um atributo de texto.
```
{
"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,
...
}
}
}
}
}
```
### Esquema para o arquivo de linha de base gerado
Quando uma configuração de linha de base do SHAP não é fornecida, o trabalho de processamento do SageMaker Clarify gera um conjunto de dados de linha de base. SageMaker O Clarify usa um algoritmo de agrupamento baseado em distância para gerar um conjunto de dados de linha de base a partir de clusters criados a partir do conjunto de dados de entrada. O conjunto de dados da linha de base resultante é salvo em um arquivo CSV, localizado em `explanations_shap/baseline.csv`. Esse arquivo de saída contém uma linha de cabeçalho e várias instâncias com base no parâmetro `num_clusters` especificado na configuração da análise. O conjunto de dados de linha de base consiste apenas em colunas de atributos. O exemplo a seguir mostra uma linha de base criada pelo agrupamento do conjunto de dados de entrada.
```
Age,Gender,Income,Occupation
35,0,2883,1
40,1,6178,2
42,0,4621,0
```
### Esquema para valores de SHAP locais da análise de explicabilidade do conjunto de dados tabular
Para conjuntos de dados tabulares, se uma única instância de computação for usada, a tarefa de processamento do SageMaker Clarify salva os valores SHAP locais em um arquivo CSV chamado. `explanations_shap/out.csv` Se você usar várias instâncias de computação, os valores de SHAP locais serão salvos em vários arquivos CSV no diretório `explanations_shap`.
Um arquivo de saída contendo valores de SHAP locais tem uma linha contendo os valores de SHAP locais de cada coluna definida pelos cabeçalhos. Os cabeçalhos seguem a convenção de nomenclatura do `Feature_Label`, em que o nome do atributo é anexado por um sublinhado, seguido pelo nome da variável de destino.
Para problemas de várias classes, os nomes dos atributos no cabeçalho variam primeiro, depois os rótulos. Por exemplo, dois atributos `F1, F2` e duas classes `L1` e `L2` nos cabeçalhos são `F1_L1`, `F2_L1`, `F1_L2` e `F2_L2`. Se a configuração de análise contiver um valor para o parâmetro `joinsource_name_or_index`, a coluna-chave usada na junção será anexada ao final do nome do cabeçalho. Isso permite o mapeamento dos valores de SHAP locais para instâncias do conjunto de dados de entrada. Veja a seguir um exemplo de arquivo de saída contendo valores de 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
...
```
### Esquema para valores de SHAP locais da análise de explicabilidade do PLN
Para análise de explicabilidade da PNL, se uma única instância de computação for usada, a tarefa de processamento do SageMaker Clarify salva os valores SHAP locais em um arquivo JSON Lines chamado. `explanations_shap/out.jsonl` Se você usar várias instâncias de computação, os valores SHAP locais serão salvos em vários arquivos de linhas JSON no diretório `explanations_shap`.
Cada arquivo contendo valores de SHAP locais tem várias linhas de dados, e cada linha é um objeto JSON válido. O objeto JSON tem os seguintes atributos:
+ **explanations**: A seção do arquivo de análise que contém uma matriz de explicações do SHAP do Kernel para uma única instância. Cada elemento da matriz tem os seguintes membros:
+ **feature\$1name**: O nome do cabeçalho dos atributos fornecidos pela configuração dos cabeçalhos.
+ **data\$1type** — O tipo de recurso inferido pela tarefa de processamento do SageMaker Clarify. Os valores válidos para atributos de texto incluem `numerical`, `categorical` e `free_text` (para atributos de texto).
+ **attributions**: Uma matriz específica de um atributo de objetos de atribuição. Um atributo de texto pode ter vários objetos de atribuição, cada um para uma unidade definida pela configuração `granularity`. O objeto de atribuição tem os seguintes membros:
+ **attribution**: Uma matriz específica de classes de valores de probabilidade.
+ **description**: (Para atributos de texto) A descrição das unidades de texto.
+ **partial\$1text** — A parte do texto explicada pela tarefa de processamento do SageMaker Clarify.
+ **start\$1idx**: Um índice baseado em zero para identificar a localização da matriz que indica o início do fragmento parcial do texto.
Veja a seguir um exemplo de uma única linha de um arquivo de valores de SHAP local, embelezada para melhorar sua legibilidade.
```
{
"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
}
}
]
}
]
}
```
### Relatório de análise de SHAP
O relatório de análise do SHAP fornece um gráfico de barras com o máximo dos `10` principais valores globais do SHAP. O exemplo de gráfico a seguir mostra os valores de SHAP para os `4` principais atributos.
![\[Gráfico de barras horizontais dos valores globais de SHAP calculados para a variável alvo dos quatro principais atributos.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/shap-chart.png)
## Análise de explicabilidade da visão computacional (CV)
SageMaker A explicabilidade da visão computacional do Clarify usa um conjunto de dados que consiste em imagens e trata cada imagem como uma coleção de superpixels. Após a análise, o trabalho de processamento do SageMaker Clarify gera um conjunto de dados de imagens em que cada imagem mostra o mapa de calor dos superpixels.
O exemplo a seguir mostra um sinal de limite de velocidade de entrada à esquerda e um mapa de calor mostra a magnitude dos valores de SHAP à direita. Esses valores de SHAP foram calculados por um modelo Resnet-18 de reconhecimento de imagem treinado para reconhecer [sinais de trânsito alemães](https://benchmark.ini.rub.de/gtsrb_news.html). O conjunto de dados de Referência alemã de reconhecimento de sinais de trânsito (GTSRB) é fornecido no artigo [avaliação comparativa de algoritmos de machine learning para reconhecimento de sinais de trânsito](https://www.sciencedirect.com/science/article/abs/pii/S0893608012000457?via%3Dihub). Na saída do exemplo, valores positivos grandes indicam que o superpixel tem uma forte correlação positiva com a predição de modelo. Valores negativos grandes indicam que o superpixel tem uma forte correlação negativa com a predição de modelo. Quanto maior o valor absoluto do valor de SHAP mostrado no mapa de calor, mais forte é a relação entre o superpixel e a predição de modelo.
![\[Imagem de entrada do sinal de limite de velocidade e do mapa de calor resultante dos valores de SHAP de um modelo Resnet-18.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/shap_speed-limit-70.png)
Para obter mais informações, consulte os exemplos de cadernos que [explicam 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) e [Explicando os modelos de detecção de objetos com o Amazon SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb).
## Análise de gráficos de dependência parcial (PDPs)
Os gráficos de dependência parcial mostram a dependência da resposta alvo prevista em um conjunto de atributos de entrada de interesse. Eles são marginalizados em relação aos valores de todos os outros atributos de entrada e são chamados de atributos do complemento. Intuitivamente, você pode interpretar a dependência parcial como a resposta alvo, que é esperada como uma função para cada atributo de entrada de interesse.
### Esquema para o arquivo de análise
Os valores do PDP são armazenados na seção `explanations` do arquivo de análise sob o método `pdp`. Os parâmetros para `explanations` são o seguinte:
+ **explanations**: A seção dos arquivos de análise que contêm os resultados da análise de importância do atributo.
+ **pdp**: A seção do arquivo de análise que contém uma matriz de explicações do PDP para uma única instância. Cada elemento da matriz tem os seguintes membros:
+ **feature\$1name**: O nome do cabeçalho dos atributos fornecidos pela configuração dos `headers`.
+ **data\$1type** — O tipo de recurso inferido pela tarefa de processamento do SageMaker Clarify. Os valores válidos para `data_type` incluem valores numéricos e categóricos.
+ **feature\$1values**: Contém os valores presentes no atributo. Se o `data_type` inferido pelo SageMaker Clarify for categórico, `feature_values` conterá todos os valores exclusivos que o recurso poderia ter. Se o `data_type` inferido pelo SageMaker Clarify for numérico, `feature_values` conterá uma lista do valor central dos compartimentos gerados. O parâmetro `grid_resolution` determina o número de buckets usados para agrupar os valores da coluna de atributos.
+ **data\$1distribution**: Uma matriz de porcentagens, em que cada valor é a porcentagem de instâncias que um bucket contém. O parâmetro `grid_resolution` determina o número de buckets. Os valores da coluna de atributos são agrupados nesses buckets.
+ **model\$1predictions**: Uma matriz de predições de modelo, em que cada elemento da matriz é uma matriz de predições que corresponde a uma classe na saída do modelo.
**label\$1headers**: Os cabeçalhos dos rótulos fornecidos pela configuração `label_headers`.
+ **error**: Uma mensagem de erro gerada se os valores do PDP não forem calculados por um motivo específico. Essa mensagem de erro substitui o conteúdo contido nos campos `feature_values`, `data_distributions` e`model_predictions`.
Veja a seguir um exemplo de saída de um arquivo de análise contendo um resultado de análise do 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"]
},
...
]
}
}
```
### Relatório de análise do PDP
Você pode gerar um relatório de análise contendo um gráfico do PDP para cada atributo. O gráfico do PDP traça `feature_values` ao longo do eixo x e traça `model_predictions` ao longo do eixo y. Para modelos de várias classes, `model_predictions` é uma matriz, e cada elemento dessa matriz corresponde a uma das classes de predição de modelo.
A seguir está um exemplo de gráfico do PDP para o atributo `Age`. No exemplo de saída, o PDP mostra o número de valores de atributos que são agrupados nos buckets. O número de buckets é determinado por `grid_resolution`. Os buckets de valores de atributos são representados de acordo com as predições de modelo. Neste exemplo, os valores mais altos do atributo têm os mesmos valores de predição de modelo.
![\[Gráfico de linhas mostrando como as predições de modelo variam de acordo com feature_values para 10 pontos de grade exclusivos.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/pdp-chart.png)
## Valores assimétricos de Shapley
SageMaker Os trabalhos de processamento do Clarify usam o algoritmo de valor de Shapley assimétrico para calcular as atribuições de explicação do modelo de previsão de séries temporais. Esse algoritmo determina a contribuição dos atributos de entrada em cada intervalo temporal até às predições feitas.
### Esquema para o arquivo de análise de valores assimétricos de Shapley
Os resultados do valor assimétrico de Shapley são armazenados em um bucket do Amazon S3. Você pode encontrar a localização desse bucket na seção de *explicações* do arquivo de análise. A seção contém os resultados da análise de importância do atributo. Os parâmetros a seguir estão incluídos no arquivo de análise de valores assimétricos de Shapley.
+ **asymmetric\$1shapley\$1value**: A seção do arquivo de análise que contém metadados sobre os resultados do trabalho de explicação, incluindo o seguinte:
+ **explanation\$1results\$1path**: A localização do Amazon S3 com os resultados da explicação
+ **direction**: A configuração fornecida pelo usuário para o valor de configuração de `direction`
+ **granularity**: A configuração fornecida pelo usuário para o valor de configuração de `granularity`
O trecho a seguir mostra os parâmetros mencionados anteriormente em um exemplo de arquivo de análise:
```
{
"version": "1.0",
"explanations": {
"asymmetric_shapley_value": {
"explanation_results_path": EXPLANATION_RESULTS_S3_URI,
"direction": "chronological",
"granularity": "timewise",
}
}
}
```
As seções a seguir descrevem como a estrutura dos resultados da explicação depende do valor de `granularity` na configuração.
#### Granularidade de tempo
Quando a granularidade for `timewise`, a saída é representada na estrutura a seguir. O valor `scores` representa a atribuição de cada registro de data e hora. O valor `offset` representa a predição de modelo sobre os dados da linha de base e descreve o comportamento dele quando ele não recebe dados.
O trecho a seguir mostra um exemplo de saída para um modelo que faz predições para dois intervalos de tempo. Portanto, todas as atribuições são uma lista de dois elementos em que a primeira entrada se refere ao primeiro intervalo de tempo previsto.
```
{
"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]},
]
}
```
#### Granularidade refinada
O exemplo a seguir demonstra os resultados da atribuição quando a granularidade é `fine_grained` O valor `offset` tem o mesmo significado descrito na seção anterior. As atribuições são calculadas para cada atributo de entrada em cada timestamp para uma série temporal de destino e uma série temporal relacionada, se houver, e para cada covariável estática, se disponível.
```
{
"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]},
]
}
```
Para os casos de uso de `timewise` e `fine-grained`, os resultados são armazenados no formato JSON Lines (.jsonl).
# Solucionar problemas de tarefas de processamento do SageMaker Clarify
Se você encontrar falhas nas tarefas de processamento do SageMaker Clarify, consulte os cenários a seguir para ajudar a identificar o problema.
**nota**
O motivo da falha e a mensagem de saída devem conter mensagens descritivas e exceções, se encontradas, durante a execução. Um motivo comum para erros é a ausência ou a invalidade dos parâmetros. Se você encontrar mensagens pouco claras, confusas ou enganosas ou não conseguir encontrar uma solução, envie um comentário.
**Topics**
+ [Falha na conclusão do trabalho de processamento](#clarify-troubleshooting-job-fails)
+ [O trabalho de processamento está demorando muito para ser executado](#clarify-troubleshooting-job-long)
+ [O trabalho de processamento termina sem resultados e você recebe uma CloudWatch mensagem de aviso](#clarify-troubleshooting-no-results-and-warning)
+ [Mensagem de erro para configuração de análise inválida](#clarify-troubleshooting-invalid-analysis-configuration)
+ [O cálculo da métrica de desvio falha em várias ou em todas as métricas](#clarify-troubleshooting-bias-metric-computation-fails)
+ [Incompatibilidade entre a configuração da análise e a entrada/saída dataset/model](#clarify-troubleshooting-mismatch-analysis-config-and-data-model)
+ [O modelo retornar 500 erros internos do servidor ou o contêiner volta às predições por registro devido a um erro do modelo](#clarify-troubleshooting-500-internal-server-error)
+ [O perfil de execução é inválido](#clarify-troubleshooting-execution-role-invalid)
+ [Falha ao baixar dados](#clarify-troubleshooting-data-download)
+ [Não foi possível conectar-se à SageMaker IA](#clarify-troubleshooting-connection)
## Falha na conclusão do trabalho de processamento
Se o trabalho de processamento não for concluído, você pode tentar o seguinte:
+ Inspecione os logs de trabalho diretamente no caderno em que você executou o trabalho. Os logs de trabalho estão localizados na saída da célula do caderno em que você iniciou a execução.
+ Inspecione os registros do trabalho. CloudWatch
+ Adicione a seguinte linha em seu caderno para descrever o último trabalho de processamento e procurar o motivo da falha e a mensagem de saída:
+ `clarify_processor.jobs[-1].describe()`
+ Execute o seguinte comando AWS CLI; para descrever o trabalho de processamento e procurar o motivo da falha e a mensagem de saída:
+ `aws sagemaker describe-processing-job —processing-job-name `
## O trabalho de processamento está demorando muito para ser executado
Se seu trabalho de processamento estiver demorando muito para ser executado, use as seguintes formas para encontrar a causa raiz:
Verifique se a configuração do recurso é suficiente para lidar com sua carga de computação. Para acelerar seu trabalho, experimente o seguinte:
+ Use um tipo de instância maior. SageMaker Esclareça as consultas repetidas do modelo, e uma instância maior pode reduzir significativamente seu tempo de computação. Para obter uma lista das instâncias disponíveis, seus tamanhos de memória, largura de banda e outros detalhes de desempenho, consulte [Amazon SageMaker AI Pricing](https://aws.amazon.com/sagemaker/pricing/).
+ Adicione mais instâncias. SageMaker O Clarify pode usar várias instâncias para explicar vários pontos de dados de entrada em paralelo. Para habilitar a computação paralela, defina seu `instance_count` para mais do que `1` quando você chamar o `SageMakerClarifyProcessor`. Para obter mais informações, consulte [Como executar trabalhos paralelos de processamento do SageMaker Clarify](clarify-processing-job-run.md#clarify-processing-job-run-spark). Se você aumentar sua contagem de instâncias, monitore o desempenho do seu endpoint para verificar se ele pode implantar o aumento da carga. Para obter mais informações, consulte [Capturar dados do endpoint em tempo real](model-monitor-data-capture-endpoint.md).
+ Se você estiver computando valores SHapley Additive exPlanations (SHAP), reduza o parâmetro `num_samples` em seu arquivo de configuração de análise. O número de amostras afeta diretamente o seguinte:
+ O tamanho dos conjuntos de dados sintéticos que são enviados ao seu endpoint
+ Tempo de execução do trabalho
Reduzir o número de amostras também pode levar à redução da precisão na estimativa dos valores de SHAP. Para obter mais informações, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
## O trabalho de processamento termina sem resultados e você recebe uma CloudWatch mensagem de aviso
Se o trabalho de processamento for concluído, mas nenhum resultado for encontrado, os CloudWatch registros produzirão uma mensagem de aviso que diz Sinal 15 recebido, limpando. Esse aviso indica que o trabalho foi interrompido devido a uma solicitação do cliente chamada `StopProcessingJob` API ou porque o trabalho esgotou o tempo previsto para sua conclusão. No último caso, verifique o runtime máximo na configuração do trabalho (`max_runtime_in_seconds`) e aumente-o conforme necessário.
## Mensagem de erro para configuração de análise inválida
+ Se você receber a mensagem de erro Não é possível carregar a configuração de análise como JSON, significa que o arquivo de entrada de configuração de análise para o trabalho de processamento não contém um objeto JSON válido. Verifique a validade do objeto JSON usando um linter JSON.
+ Se você receber a mensagem de erro Erro de validação do esquema de configuração da análise, significa que o arquivo de entrada de configuração de análise para o trabalho de processamento contém campos desconhecidos ou tipos inválidos para alguns valores de campo. Revise os parâmetros de configuração no arquivo e faça uma verificação cruzada com os parâmetros listados no arquivo de configuração da análise. Para obter mais informações, consulte [Arquivos de configuração de análise](clarify-processing-job-configure-analysis.md).
## O cálculo da métrica de desvio falha em várias ou em todas as métricas
Se você receber uma das seguintes mensagens de erro Nenhum valor de rótulo está presente na coluna de rótulo previsto, a série de índices previstos positivos contém todos os valores falsos. ou O tipo de dados da série da coluna de rótulo previsto não é o mesmo da série da coluna de rótulo., tente o seguinte:
+ Verifique se o conjunto de dados correto está sendo usado.
+ Verifique se o tamanho do conjunto de dados é muito pequeno; se, por exemplo, ele contém apenas algumas linhas. Isso pode fazer com que as saídas do modelo tenham o mesmo valor ou que o tipo de dados seja inferido incorretamente.
+ Verifique se o rótulo ou a faceta são tratados como contínuos ou categóricos. SageMaker O Clarify usa heurísticas para determinar o. [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)) Para métricas de viés pós-treinamento, o tipo de dados retornado pelo modelo pode não corresponder ao que está no conjunto de dados ou o SageMaker Clarify pode não conseguir transformá-lo corretamente.
+ No relatório de desvios, você deve ver um valor único para colunas categóricas ou um intervalo para colunas contínuas.
+ Por exemplo, se uma coluna tiver valores 0,0 e 1,0 como flutuantes, ela será tratada como contínua mesmo que haja poucos valores exclusivos.
## Incompatibilidade entre a configuração da análise e a entrada/saída dataset/model
+ Verifique se o formato da linha de base na configuração da análise é o mesmo do conjunto de dados.
+ Se você receber a mensagem de erro Não foi possível converter a string em flutuante., verifique se o formato está especificado corretamente. Também pode indicar que as predições de modelo têm um formato diferente da coluna do rótulo ou pode indicar que a configuração do rótulo ou das probabilidades está incorreta.
+ Se você receber a mensagem de erro Não foi possível localizar a faceta., Os cabeçalhos devem conter um rótulo., Os cabeçalhos na configuração não correspondem ao número de colunas no conjunto de dados. ou Nomes de atributos não encontrados., verifique se os cabeçalhos correspondem às colunas.
+ Se você receber a mensagem de erro, Os dados devem conter atributos., verifique o modelo de conteúdo para linhas JSON e compare-o com a amostra do conjunto de dados, se disponível.
## O modelo retornar 500 erros internos do servidor ou o contêiner volta às predições por registro devido a um erro do modelo
Se você receber a mensagem de erro, Fallback para a predição por registro devido a um erro do modelo., pode indicar que o modelo não consegue lidar com o tamanho do lote, ser limitado ou simplesmente não aceita a entrada passada pelo contêiner devido a problemas de serialização. Você deve revisar os CloudWatch registros do endpoint de SageMaker IA e procurar mensagens de erro ou rastreamentos. Para casos de controle de utilização de modelos, pode ser útil usar um tipo de instância diferente ou aumentar o número de instâncias para o endpoint.
## O perfil de execução é inválido
Isso indica que o perfil fornecido está incorreto ou não tem as permissões necessárias. Verifique o perfil e suas permissões que foram usadas para configurar o trabalho de processamento e verifique a permissão e a política de confiança do perfil.
## Falha ao baixar dados
Isso indica que as entradas do trabalho não puderam ser baixadas para que o trabalho fosse iniciado. Verifique o nome do bucket e as permissões do conjunto de dados e das entradas de configuração.
## Não foi possível conectar-se à SageMaker IA
Isso indica que o trabalho não conseguiu alcançar os pontos finais do serviço de SageMaker IA. Verifique as configurações de rede para o trabalho de processamento e verifique a configuração da nuvem privada virtual (VPC).
## Cadernos de amostra
As seções a seguir contêm cadernos para ajudá-lo a começar a usar o SageMaker Clarify, para usá-lo para tarefas especiais, incluindo aquelas dentro de um trabalho distribuído, e para visão computacional.
### Introdução
Os exemplos de cadernos a seguir mostram como usar o SageMaker Clarify para começar com tarefas de explicabilidade e viés de modelo. As tarefas incluem a criação de um trabalho de processamento, o treinamento de um modelo de machine learning (ML) e o monitoramento de predições de modelo:
+ [Explicabilidade e detecção de viés com o Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) — Use o SageMaker Clarify para criar um trabalho de processamento para detectar viés e explicar as previsões do modelo.
+ [Monitorando o desvio de viés e o desvio de atribuição de recursos Amazon Clarify SageMaker — Use o Amazon](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) SageMaker Model Monitor para monitorar o desvio de viés e o desvio de atribuição de recursos ao longo do tempo.
+ Como [ler um conjunto de dados no formato JSON Lines em](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.html) um trabalho de processamento do SageMaker Clarify.
+ [Mitigue o viés, treine outro modelo imparcial e coloque-o no registro do modelo — Use a](https://github.com/aws/amazon-sagemaker-examples/blob/master/end_to_end/fraud_detection/3-mitigate-bias-train-model2-registry-e2e.ipynb) [Synthetic Minority Oversampling Technique (SMOTE)](https://arxiv.org/pdf/1106.1813.pdf) e o SageMaker Clarify para mitigar o viés, treine outro modelo e, em seguida, coloque o novo modelo no registro do modelo. O caderno de amostra também mostra como colocar os novos artefatos do modelo, incluindo dados, código e metadados do modelo, no registro. Este caderno faz parte de uma série que mostra como integrar o SageMaker Clarify a um pipeline de SageMaker IA descrito no [Architect e criar o ciclo de vida completo do aprendizado de máquina com](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) uma AWS postagem no blog.
### Casos especiais
Os cadernos a seguir mostram como usar o SageMaker Clarify para casos especiais, inclusive dentro de seu próprio contêiner e para tarefas de processamento de linguagem natural:
+ [Imparcialidade e explicabilidade com o SageMaker Clarify (traga seu próprio contêiner)](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_byoc.ipynb) — Crie seu próprio modelo e contêiner que possam ser integrados ao SageMaker Clarify para medir o viés e gerar um relatório de análise de explicabilidade. Este exemplo de caderno também apresenta os principais termos e mostra como acessar o relatório por meio do SageMaker Studio Classic.
+ [Imparcialidade e explicabilidade com o processamento distribuído do SageMaker Clarify Spark — Use o processamento distribuído](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_spark.ipynb) para executar uma tarefa do SageMaker Clarify que mede o viés pré-treinamento de um conjunto de dados e o viés pós-treinamento de um modelo. Este exemplo de caderno também mostra como obter uma explicação sobre a importância dos recursos de entrada na saída do modelo e acessar o relatório de análise de explicabilidade por meio do SageMaker Studio Classic.
+ [Explicabilidade com SageMaker Clarify — Gráficos de dependência parcial (PDP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.html) — Use o SageMaker Clarify para gerar PDPs e acessar um modelo de relatório de explicabilidade.
+ [Explicando a análise de sentimentos de texto usando a explicabilidade do processamento de linguagem natural (PNL) do SageMaker Clarify — Use o SageMaker Clarify para análise de sentimentos de texto](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/text_explainability/text_explainability.html).
+ Use a explicabilidade da visão computacional (CV) para [classificação de imagens](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.html) e [detecção de objetos](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.html).
Verificou-se que esses notebooks são executados no Amazon SageMaker Studio Classic. Se você precisar de instruções sobre como abrir um caderno no Studio Classic, consulte [Crie ou abra um notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Caso seja solicitado que você escolha um kernel, escolha **Python 3 (Ciência de dados)**.
# Desvio nos dados de pré-treinamento
Desvio algorítmico, discriminação, equidade e tópicos relacionados foram estudados em várias disciplinas, como direito, política e ciência da computação. Um sistema de computador pode ser considerado tendencioso se discriminar certos indivíduos ou grupos de indivíduos. Os modelos de machine learning que alimentam esses aplicações aprendem com os dados e esses dados podem refletir disparidades ou outros vieses inerentes. Por exemplo, os dados de treinamento podem não ter representação suficiente de vários grupos demográficos ou conter rótulos tendenciosos. Os modelos de machine learning treinados em conjuntos de dados que exibem esses vieses podem acabar aprendendo-os e, em seguida, reproduzir ou até mesmo exacerbar esses vieses em suas predições. O campo do machine learning oferece uma oportunidade de lidar com vieses detectando-os e medindo-os em cada estágio do ciclo de vida do ML. Você pode usar o Amazon SageMaker Clarify para determinar se os dados usados para modelos de treinamento codificam algum viés
O desvio pode ser medido antes e após o treinamento e monitorado em relação às linhas de base após a implantação de modelos em endpoints para inferência. As métricas de desvio pré-treinamento são projetadas para detectar e medir o desvio nos dados brutos antes de serem usados para treinar um modelo. As métricas usadas são independentes do modelo porque não dependem de nenhuma saída do modelo. No entanto, existem diferentes conceitos de equidade que exigem medidas distintas de desvios. O Amazon SageMaker Clarify fornece métricas de preconceito para quantificar vários critérios de imparcialidade.
Para obter informações adicionais sobre métricas de viés, consulte [Saiba como o Amazon SageMaker Clarify ajuda a detectar medidas tendenciosas](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias) [e imparciais para o Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
## A Amazon SageMaker esclarece os termos de preconceito e imparcialidade
SageMaker O Clarify usa a seguinte terminologia para discutir preconceitos e imparcialidade.
**Recurso**
Uma propriedade individual mensurável ou característica de um fenômeno que está sendo observado, contida em uma coluna para dados tabulares.
**Rótulo**
Recurso que é o alvo para treinar um modelo de machine learning. Referido como *rótulo observado* ou *resultado observado*.
**Rótulo previsto**
O rótulo conforme previsto pelo modelo. Também conhecido como *resultado previsto*.
**Amostra**
Uma entidade observada descrita por valores de atributo e valores de rótulo, contida em uma linha para dados tabulares.
**Conjunto de dados**
Uma coleção de amostras.
**Desvio**
Um desequilíbrio nos dados de treinamento ou no comportamento de predição de modelo em diferentes grupos, como idade ou faixa de renda. Os vieses podem resultar dos dados ou do algoritmo usado para treinar seu modelo. Por exemplo, se um modelo de ML for treinado principalmente com dados de indivíduos de meia idade, ele pode ser menos preciso ao fazer predições envolvendo pessoas mais jovens e mais velhas.
**Métrica de desvio**
Uma função que retorna valores numéricos indicando o nível de um desvio potencial.
**Relatório de desvio**
Uma coleção de métricas de desvio para um determinado conjunto de dados ou uma combinação de um conjunto de dados e um modelo.
**Valores positivos do rótulo**
Valores do rótulo que são favoráveis a um grupo demográfico observado em uma amostra. Em outras palavras, designa uma amostra como tendo um *resultado positivo*.
**Valores negativos do rótulo**
Valores do rótulo que são desfavoráveis a um grupo demográfico observado em uma amostra. Em outras palavras, designa uma amostra como tendo um *resultado negativo*.
**Variável de grupo**
Coluna categórica do conjunto de dados usada para formar subgrupos para a medição da Disparidade demográfica condicional (CDD). Obrigatória somente para essa métrica em relação ao paradoxo de Simpson.
**Faceta**
Uma coluna ou atributo que contém os atributos com relação aos quais o desvio é medido.
**Valor da faceta**
Os valores de atributo dos atributos dos quais o desvio pode favorecer ou desfavorecer.
**Probabilidade prevista**
A probabilidade, conforme prevista pelo modelo, de uma amostra ter um resultado positivo ou negativo.
## Cadernos de exemplo
O Amazon SageMaker Clarify fornece o seguinte exemplo de caderno para detecção de viés:
+ [Explicabilidade e detecção de viés com o Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) — Use o SageMaker Clarify para criar um trabalho de processamento para detectar vieses e explicar as previsões do modelo com atribuições de recursos.
Este notebook foi verificado para ser executado somente no Amazon SageMaker Studio. Se você precisar de instruções sobre como abrir um notebook no Amazon SageMaker Studio, consulte[Crie ou abra um notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Caso seja solicitado que você escolha um kernel, escolha **Python 3 (Ciência de dados)**.
**Topics**
+ [A Amazon SageMaker esclarece os termos de preconceito e imparcialidade](#clarify-bias-and-fairness-terms)
+ [Cadernos de exemplo](#clarify-data-bias-sample-notebooks)
+ [Métricas de desvio pré-treinamento](clarify-measure-data-bias.md)
+ [Gere relatórios de viés nos dados de pré-treinamento no Studio SageMaker](clarify-data-bias-reports-ui.md)
# Métricas de desvio pré-treinamento
Medir o desvio em modelos de ML é o primeiro passo para mitigar o desvio. Cada medida de desvio corresponde a uma noção diferente de equidade. Até mesmo considerar conceitos simples de equidade leva a muitas medidas diferentes aplicáveis em vários contextos. Por exemplo, considere a equidade em relação à idade e, para simplificar, que a meia-idade e o restante das faixas etárias são os dois grupos demográficos relevantes, chamados de *facetas*. No caso de um modelo de ML para empréstimos, podemos querer que empréstimos para pequenas empresas sejam emitidos para números iguais de ambos os grupos demográficos. Ou, ao processar candidatos a emprego, talvez queiramos ver números iguais de membros de cada grupo demográfico contratado. No entanto, essa abordagem pode presumir que números iguais de ambas as faixas etárias se aplicam a esses empregos, portanto, podemos querer condicionar o número de candidatos. Além disso, podemos considerar não se números iguais se candidatam, mas se temos um número igual de candidatos qualificados. Ou podemos considerar a equidade como uma taxa de aceitação igual de candidatos qualificados em ambas as faixas etárias, ou uma taxa igual de rejeição de candidatos, ou ambas. Você pode usar conjuntos de dados com diferentes proporções de dados sobre os atributos de interesse. Esse desequilíbrio pode confundir a medida de desvio que você escolher. Os modelos podem ser mais precisos na classificação de uma faceta do que na outra. Portanto, você precisa escolher métricas de desvio que sejam conceitualmente apropriadas para a aplicação e a situação.
Usamos a notação a seguir para debater as métricas de desvio. O modelo conceitual descrito aqui é para classificação binária, em que os eventos são rotulados como tendo apenas dois resultados possíveis em seu espaço amostral, chamados de positivos (com valor 1) e negativos (com valor 0). Esse framework geralmente é extensível à classificação multicategórica de forma direta ou a casos que envolvem resultados contínuos valiosos, quando necessário. No caso da classificação binária, rótulos positivos e negativos são atribuídos aos resultados registrados em um conjunto de dados bruto para uma faceta favorecida *a* e para uma faceta desfavorecida *d*. Esses rótulos y são chamados de *rótulos observados* para diferenciá-los dos *rótulos previstos* y' que são atribuídos por um modelo de machine learning durante os estágios de treinamento ou inferências do ciclo de vida do ML. Esses rótulos são usados para definir distribuições de probabilidade Pa(y) e Pd(y) para seus respectivos resultados facetários.
+ rótulos:
+ y representa os n rótulos observados para resultados de eventos em um conjunto de dados de treinamento.
+ y' representa os rótulos previstos para os n rótulos observados no conjunto de dados por um modelo treinado.
+ resultados:
+ Um resultado positivo (com valor 1) para uma amostra, como a aceitação de uma candidatura.
+ n(1) é o número de rótulos observados para resultados positivos (aceitações).
+ n'(1) é o número de rótulos previstos para resultados positivos (aceitações).
+ Um resultado negativo (com valor 0) para uma amostra, como uma rejeição de candidatura.
+ n(0) é o número de rótulos observados para resultados negativos (rejeições).
+ n'(0) é o número de rótulos previstos para resultados negativos (rejeições).
+ valores da faceta:
+ faceta *a*: O valor do atributo que define um grupo demográfico que o desvio favorece.
+ na é o número de rótulos observados para o valor da faceta favorecido: na = na(1) \$1 na(0) a soma dos rótulos observados positivos e negativos para a faceta de valor *a*.
+ n'a é o número de rótulos previstos para o valor da faceta favorecido: n'a = n'a(1) \$1 n'a(0) a soma dos rótulos de resultados previstos positivos e negativos para a faceta de valor *a*. Observe que n'a = na.
+ faceta *d*: O valor do atributo que define um grupo demográfico que o desvio desfavorece.
+ nd é o número de rótulos observados para o valor da faceta desfavorecido: nd = nd(1) \$1 nd(0) a soma dos rótulos observados positivos e negativos para a faceta de valor *d*.
+ n'd é o número de rótulos previstos para o valor da faceta desfavorecido: n'd = n'd(1) \$1 n'd(0) a soma dos rótulos previstos positivos e negativos para a faceta de valor *d*. Observe que n'd = nd.
+ distribuições de probabilidade para resultados dos resultados dos dados facetários rotulados:
+ Pa(y) é a distribuição de probabilidade dos rótulos observados para a faceta *a*. Para dados binários rotulados, essa distribuição é dada pela razão entre o número de amostras na faceta *a* rotulada com resultados positivos e o número total, Pa(y1) = na(1)/ na, e a razão entre o número de amostras com resultados negativos e o número total, Pa(y0) = na(0)/ na.
+ Pd(y) é a distribuição de probabilidade dos rótulos observados para a faceta *d*. Para dados binários rotulados, essa distribuição é dada pelo número de amostras na faceta *d* rotulada com resultados positivos e o número total, Pd(y1) = nd(1)/ nd, e a razão entre o número de amostras com resultados negativos e o número total, Pd(y0) = nd(0)/ nd.
Modelos treinados em dados tendenciosos por disparidades demográficas podem aprendê-las e até mesmo exacerbá-las. Para identificar o viés nos dados antes de gastar recursos para treinar modelos neles, o SageMaker Clarify fornece métricas de distorção de dados que você pode calcular em conjuntos de dados brutos antes do treinamento. Todas as métricas de pré-treinamento são independentes do modelo porque não dependem dos resultados do modelo e, portanto, são válidas para qualquer modelo. A primeira métrica de desvio examina o desequilíbrio facetário, mas não os resultados. Ela determina até que ponto a quantidade de dados de treinamento é representativa em diferentes facetas, conforme desejado para a aplicação. As métricas de desvio restantes comparam a distribuição dos rótulos de resultados de várias maneiras para as facetas *a* e *d* nos dados. As métricas que variam acima dos valores negativos podem detectar desvios negativos. A tabela a seguir contém uma folha de dicas para orientação rápida e links para as métricas de desvio de pré-treinamento.
Métricas de desvio pré-treinamento
| Métrica de desvio | Description | Exemplo de pergunta | Interpretar valores de métricas |
| --- | --- | --- | --- |
| [Desequilíbrio de classes (CI)](clarify-bias-metric-class-imbalance.md) | Mede o desequilíbrio no número de membros entre diferentes valores de faceta. | Pode haver desvios baseados na idade devido à falta de dados demográficos fora de uma faceta de meia-idade? | Intervalo normalizado: [-1, \$11] Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Diferença nas proporções dos rótulos (DPL)](clarify-data-bias-metric-true-label-imbalance.md) | Mede o desequilíbrio nos resultados positivos entre diferentes valores de faceta. | Pode haver desvios com base na idade nas predições de ML devido à rotulagem tendenciosa dos valores das facetas nos dados? | Intervalo para rótulos de facetas binários e multicategóricos normalizados: [-1, \$11] Intervalo para rótulos contínuos: (-∞, \$1∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergência de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md) | Mede o quanto as distribuições de resultados de diferentes facetas divergem entre si entropicamente. | Quão diferentes são as distribuições dos resultados dos pedidos de empréstimo para diferentes grupos demográficos? | Intervalo para binário, multicategórico, contínuo: [0, \$1∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Divergência de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) | Mede o quanto as distribuições de resultados de diferentes facetas divergem entre si entropicamente. | Quão diferentes são as distribuições dos resultados dos pedidos de empréstimo para diferentes grupos demográficos? | Intervalo para binário, multicategórico, contínuo: [0, \$1∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Norma Lp (LP)](clarify-data-bias-metric-lp-norm.md) | Mede a diferença da norma p entre distribuições demográficas distintas dos resultados associados a diferentes facetas em um conjunto de dados. | Quão diferentes são as distribuições dos resultados dos pedidos de empréstimo para diferentes grupos demográficos? | Intervalo para binário, multicategórico, contínuo: [0, \$1∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Distância de variação total (TVD)](clarify-data-bias-metric-total-variation-distance.md) | Mede metade da diferença da norma L1 entre distribuições demográficas distintas dos resultados associados a diferentes facetas em um conjunto de dados. | Quão diferentes são as distribuições dos resultados dos pedidos de empréstimo para diferentes grupos demográficos? | Intervalo para resultados binários, multicategóricos, contínuos: [0, \$1∞) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) | Mede a divergência máxima entre os resultados nas distribuições para diferentes facetas em um conjunto de dados. | Quais resultados de candidatura em faculdades manifestam as maiores disparidades por grupo demográfico? | Intervalo de valores de KS para resultados binários, multicategóricos e contínuos: [0, \$11][\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Disparidade demográfica condicional (CDD)](clarify-data-bias-metric-cddl.md) | Mede a disparidade de resultados entre diferentes facetas como um todo, mas também por subgrupos. | Alguns grupos têm uma proporção maior de rejeições nos resultados de admissão na faculdade do que a proporção de aceitações? | Intervalo de CDD: [-1, \$11] [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-data-bias.html) |
Para obter informações adicionais sobre métricas de desvio, consulte [Medidas de equidade para Machine Learning em finanças](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
**Topics**
+ [Desequilíbrio de classes (CI)](clarify-bias-metric-class-imbalance.md)
+ [Diferença nas proporções dos rótulos (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ [Divergência de Kullback-Leibler (KL)](clarify-data-bias-metric-kl-divergence.md)
+ [Divergência de Jensen-Shannon (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ [Norma Lp (LP)](clarify-data-bias-metric-lp-norm.md)
+ [Distância de variação total (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ [Disparidade demográfica condicional (CDD)](clarify-data-bias-metric-cddl.md)
# Desequilíbrio de classes (CI)
O desvio de desequilíbrio de classes (CI) ocorre quando um valor de faceta *d* tem menos amostras de treinamento quando comparado com outra faceta *a* no conjunto de dados. Isso ocorre porque os modelos se ajustam preferencialmente às facetas maiores em detrimento das facetas menores e, portanto, podem resultar em um maior erro de treinamento para a faceta *d*. Os modelos também correm maior risco de sobreajustar os conjuntos de dados menores, o que pode causar um erro de teste maior para a faceta *d*. Considere o exemplo em que um modelo de machine learning é treinado principalmente com dados de indivíduos de meia idade (faceta a). Ele pode ser menos preciso ao fazer predições envolvendo pessoas mais jovens e mais velhas (faceta d).
Fórmula para a medida de desequilíbrio facetário (normalizada):
CI = (na - nd)/(na \$1 nd)
Onde na é o número de membros da faceta *a* e nd o número da faceta *d*. Seus valores variam ao longo do intervalo [-1, 1].
+ Valores positivos de CI indicam que a faceta *a* tem mais amostras de treinamento no conjunto de dados e um valor de 1 indica que os dados contêm apenas membros da faceta *a*.
+ Valores de CI próximos de zero indicam uma distribuição mais uniforme de membros entre facetas e um valor de zero indica uma partição perfeitamente igual entre facetas e representa uma distribuição equilibrada de amostras nos dados de treinamento.
+ Valores negativos de CI indicam que a faceta *d* tem mais amostras de treinamento no conjunto de dados e um valor de -1 indica que os dados contêm apenas membros da faceta *d*.
+ Os valores de CI próximos a qualquer um dos valores extremos de -1 ou 1 estão muito desequilibrados e correm um risco substancial de fazer predições tendenciosas.
Se for constatado que existe um desequilíbrio significativo entre as facetas, você deve reequilibrar a amostra antes de continuar treinando modelos nela.
# Diferença nas proporções dos rótulos (DPL)
A diferença nas proporções de rótulos (DPL) compara a proporção de resultados observados com rótulos positivos para a faceta *d* com a proporção de resultados observados com rótulos positivos da faceta *a* em um conjunto de dados de treinamento. Por exemplo, você pode usá-la para comparar a proporção de indivíduos de meia idade (faceta *a*) e outras faixas etárias (faceta *d*) aprovados para empréstimos financeiros. Os modelos de machine learning tentam imitar as decisões de dados de treinamento da forma mais próxima possível. Portanto, um modelo de machine learning treinado em um conjunto de dados com uma alta DPL provavelmente refletirá o mesmo desequilíbrio em suas predições futuras.
A fórmula para a diferença nas proporções dos rótulos é a seguinte:
DPL = (qa - qd)
Em que:
+ qa = na(1)/na é a proporção da faceta *a* que tem um valor de rótulo observado de 1. Por exemplo, a proporção de um grupo demográfico de meia idade que recebe aprovação para empréstimos. Aqui, na(1) representa o número de membros da faceta *a* que obtêm um resultado positivo e na é o número de membros da faceta *a*.
+ qd = nd(1)/nd é a proporção da faceta *d* que tem um valor de rótulo observado de 1. Por exemplo, a proporção de pessoas fora do grupo demográfico de meia idade que recebe aprovação para empréstimos. Aqui, nd(1) representa o número de membros da faceta *d* que obtêm um resultado positivo e nd é o número de membros da faceta *d*.
Se a DPL estiver próxima o suficiente de 0, dizemos que a *paridade demográfica* foi alcançada.
Para rótulos de facetas binários e multicategóricos, os valores de DPL variam ao longo do intervalo (-1, 1). Para rótulos contínuos, definimos um limite para reduzir os rótulos para binários.
+ Valores positivos de DPL indicam que a faceta *a* tem uma proporção maior de resultados positivos quando comparada com a faceta *d*.
+ Valores de DPL próximos de zero indicam uma proporção mais uniforme de resultados positivos entre as facetas e um valor de zero indica paridade demográfica perfeita.
+ Valores negativos de DPL indicam que a faceta *d* tem uma proporção maior de resultados positivos quando comparada com a faceta *a*.
O fato de uma alta magnitude de DPL ser problemática varia de uma situação para outra. Em um caso problemático, uma DPL de alta magnitude pode ser um sinal de problemas subjacentes nos dados. Por exemplo, um conjunto de dados com alta DPL pode refletir desvios históricos ou preconceitos contra grupos demográficos baseados na idade que seriam indesejáveis para um modelo aprender.
# Divergência de Kullback-Leibler (KL)
A divergência de Kullback-Leibler (KL) mede o quanto a distribuição observada do rótulo da faceta *a*, Pa(y) diverge da distribuição da faceta *d*, Pd(y). Também é conhecida como entropia relativa de Pa(y) em relação a Pd(y) e quantifica a quantidade de informação perdida ao passar de Pa(y) para Pd(y).
A fórmula para a divergência de Kullback-Leibler é a seguinte:
KL(Pa \$1\$1 Pd) = ∑yPa(y)\$1log[Pa(y)/Pd(y)]
É a expectativa da diferença logarítmica entre as probabilidades Pa(y) e Pd(y), onde a expectativa é ponderada pelas probabilidades Pa(y). Essa não é uma distância real entre as distribuições, pois é assimétrica e não satisfaz a desigualdade triangular. A implementação usa logaritmos naturais, fornecendo KL em unidades de nats. O uso de bases logarítmicas diferentes fornece resultados proporcionais, mas em unidades diferentes. Por exemplo, usar a base 2 fornece KL em unidades de bits.
Por exemplo, suponha que um grupo de solicitantes de empréstimos tenha uma taxa de aprovação de 30% (faceta *d*) e que a taxa de aprovação de outros solicitantes (faceta *a*) seja de 80%. A fórmula de Kullback-Leibler fornece a divergência de distribuição de rótulos da faceta *a* da faceta *d* da seguinte forma:
KL = 0,8\$1ln(0,8/0,3) \$1 0,2\$1ln(0,2/0,7) = 0,53
Há dois termos na fórmula aqui porque os rótulos são binários neste exemplo. Essa medida pode ser aplicada a vários rótulos, além dos binários. Por exemplo, em um cenário de admissão em faculdades, suponha que um candidato possa receber um dos três rótulos de categoria: yi = \$1y0, y1, y2\$1 = \$1rejeitado, em lista de espera, aceito\$1.
Intervalo de valores da métrica KS para resultados binários, multicategóricos e contínuos: [0, \$1∞).
+ Valores próximos de zero significam que os resultados são distribuídos de forma semelhante para as diferentes facetas.
+ Valores positivos significam que as distribuições dos rótulos divergem; quanto mais positivas, maior a divergência.
# Divergência de Jensen-Shannon (JS)
A divergência de Jensen-Shannon (JS) mede o quanto as distribuições de rótulos de diferentes facetas divergem entre si entropicamente. Ela é baseada na divergência de Kullback-Leibler, mas é simétrica.
A fórmula para a divergência de Jensen-Shannon é a seguinte:
JS = ½\$1[KL(Pa \$1\$1 P) \$1 KL(Pd \$1\$1 P)]
Onde P = ½ (Pa \$1 Pd), a distribuição média do rótulo nas facetas *a* e *d*.
O intervalo de valores da JS para resultados binários, multicategóricos e contínuos é [0, ln(2)).
+ Valores próximos de zero significam que os rótulos estão distribuídos de forma semelhante.
+ Valores positivos significam que as distribuições dos rótulos divergem; quanto mais positivas, maior a divergência.
Essa métrica indica se há uma grande divergência em um dos rótulos entre as facetas.
# Norma Lp (LP)
A norma Lp (LP) mede a distância da norma p entre as distribuições de facetas dos rótulos observados em um conjunto de dados de treinamento. Essa métrica não é negativa e, portanto, não pode detectar desvios reversos.
A fórmula para a norma Lp é a seguinte:
Lp(Pa, Pd) = (∑y\$1\$1Pa - Pd\$1\$1p)1/p
Onde a distância da norma p entre os pontos x e y é definida da seguinte forma:
Lp(x, y) = (\$1x1-y1\$1p \$1 \$1x2-y2\$1p \$1 … \$1\$1xn-yn\$1p)1/p
A norma 2 é a norma euclidiana. Suponha que você tenha uma distribuição de resultados com três categorias, por exemplo, yi = \$1y0, y1, y2\$1 = \$1aceito, na lista de espera, rejeitado\$1 em um cenário multicategórico de admissões em faculdades. Você obtém a soma dos quadrados das diferenças entre as contagens de resultados para as facetas *a* e *d*. A distância euclidiana resultante é calculada da seguinte forma:
L2(Pa, Pd) = [(na(0) - nd(0))2 \$1 (na(1) - nd(1))2 \$1 (na(2) - nd(2))2]1/2
Em que:
+ Númeroa(i) é o número dos resultados da i-ésima categoria na faceta *a*: por exemplo, na(0) é o número de aceitações da faceta *a*.
+ nd(i) é o número dos resultados da i-ésima categoria na faceta *d*: por exemplo, nd(2) é o número de rejeições da faceta *d*.
O intervalo de valores de LP para resultados binários, multicategóricos e contínuos é [0, √2), onde:
+ Valores próximos de zero significam que os rótulos estão distribuídos de forma semelhante.
+ Valores positivos significam que as distribuições dos rótulos divergem; quanto mais positivas, maior a divergência.
# Distância de variação total (TVD)
A métrica de polarização de dados da distância de variação total (TVD) é metade da norma L1. O TVD é a maior diferença possível entre as distribuições de probabilidade para resultados de rótulos das facetas *a* e *d*. A 1 norma L é a distância de Hamming, uma métrica usada para comparar duas strings de dados binários determinando o número mínimo de substituições necessárias para alterar uma sequência para outra. Se as strings fossem cópias umas das outras, isso determinaria a quantidade de erros que ocorreram durante a cópia. No contexto de detecção de desvio, o TVD quantifica quantos resultados na faceta *a* precisariam ser alterados para corresponder aos resultados na faceta *d*.
A fórmula para a distância de variação total é a seguinte:
TVD = ½\$1L1(Pa, Pd)
Por exemplo, suponha que você tenha uma distribuição de resultados com três categorias, yi = \$1y0, y1, y2\$1 = \$1aceito, na lista de espera, rejeitado\$1 em um cenário multicategórico de admissões em faculdades. Você usa as diferenças entre as contagens das facetas *a* e *d* para cada resultado para calcular o TVD. O resultado é o seguinte:
L1(Pa, Pd) = \$1na(0) - nd(0)\$1 \$1 \$1na(1) - nd(1)\$1 \$1 \$1na(2) - nd(2)\$1
Em que:
+ Númeroa(i) é o número dos resultados da i-ésima categoria na faceta *a*: por exemplo, na(0) é o número de aceitações da faceta *a*.
+ nd(i) é o número dos resultados da i-ésima categoria na faceta d: por exemplo, nd(2) é o número de rejeições da faceta *d*.
O intervalo de valores de TVD para resultados binários, multicategóricos e contínuos é [0, 1), onde:
+ Valores próximos de zero significam que os rótulos estão distribuídos de forma semelhante.
+ Valores positivos significam que as distribuições dos rótulos divergem; quanto mais positivas, maior a divergência.
# Kolmogorov-Smirnov (KS)
A métrica de desvio de Kolmogorov-Smirnov (KS) é igual à divergência máxima entre os rótulos nas distribuições das facetas *a* e *d* de um conjunto de dados. O teste KS de duas amostras implementado pela SageMaker Clarify complementa as outras medidas de desequilíbrio do rótulo ao encontrar o rótulo mais desequilibrado.
A fórmula para a métrica de Kolmogorov-Smirnov é a seguinte:
KS = máx(\$1Pa(y) - Pd(y)\$1)
Por exemplo, suponha que um grupo de candidatos (faceta *a*) à faculdade seja rejeitado, na lista de espera ou aceito em 40%, 40%, 20%, respectivamente, e que essas taxas para outros candidatos (faceta *d*) sejam 20%, 10%, 70%. Então, o valor métrico de desvio de Kolmogorov-Smirnov é o seguinte:
KS = máximo (\$10,4-0,2\$1, \$10,4-0,1\$1, \$10,2-0,7\$1) = 0,5
Isso nos diz que a divergência máxima entre as distribuições de facetas é 0,5 e ocorre nas taxas de aceitação. Há três termos na equação porque os rótulos são multiclasse de cardinalidade três.
O intervalo de valores de LP para resultados binários, multicategóricos e contínuos é [0, \$11], onde:
+ Valores próximos de zero indicam que os rótulos foram distribuídos uniformemente entre as facetas em todas as categorias de resultados. Por exemplo, ambas as facetas que pediram um empréstimo obtiveram 50% das aceitações e 50% das rejeições.
+ Valores próximos a um indicam que os rótulos de uma categoria estavam todos em uma faceta. Por exemplo, a faceta *a* obteve 100% das aceitações e a faceta *d* não obteve nenhuma.
+ Valores intermitentes indicam graus relativos de desequilíbrio máximo do rótulo.
# Disparidade demográfica condicional (CDD)
A métrica de disparidade demográfica (DD) determina se uma faceta tem uma proporção maior de resultados rejeitados no conjunto de dados do que de resultados aceitos. No caso binário em que há duas facetas, homens e mulheres, por exemplo, que constituem o conjunto de dados, a desfavorecida é rotulada como faceta *d* e a favorita é rotulada como faceta *a*. Por exemplo, no caso de admissões em faculdades, se as candidatas (mulheres) representassem 46% dos candidatos rejeitados e representassem apenas 32% dos candidatos aceitos, afirmamos que há *disparidade demográfica* porque a taxa de rejeição de mulheres excede a taxa de aceitação. As candidatas mulheres são rotuladas como faceta *d* neste caso. Se os candidatos (homens) representavam 54% dos candidatos rejeitados e 68% dos candidatos aceitos, então não há uma disparidade demográfica para essa faceta, pois a taxa de rejeição é menor que a taxa de aceitação. Os candidatos (homens) são rotulados como faceta *d* neste caso.
A fórmula para a disparidade demográfica para a faceta *d* menos favorecida é a seguinte:
DDd = nd(0)/n(0) - nd(1)/n(1) = PdR(y0) - PdA(y1)
Em que:
+ n(0) = na(0) \$1 nd(0) é o número total de resultados rejeitados no conjunto de dados para a faceta favorecida *a* e a faceta desfavorecida *d*.
+ n(1) = na(1) \$1 nd(1) é o número total de resultados aceitos no conjunto de dados para a faceta favorecida *a* e a faceta desfavorecida *d*.
+ PdR(y0) é a proporção de resultados rejeitados (com valor 0) na faceta *d*.
+ PdA(y1) é a proporção de resultados aceitos (valor 1) na faceta *d*.
Para o exemplo de admissão na faculdade, a disparidade demográfica para mulheres é DDd = 0,46 - 0,32 = 0,14. Para homens DDa = 0,54 - 0,68 = - 0,14.
Uma métrica de disparidade demográfica condicional (CDD) que condiciona DD em atributos que definem um estrato de subgrupos no conjunto de dados é necessária para descartar o paradoxo de Simpson. O reagrupamento pode fornecer insights sobre a causa das aparentes disparidades demográficas nas facetas menos favorecidas. O caso clássico surgiu no caso de admissões em Berkeley, onde os homens foram aceitos com uma taxa geral mais alta do que as mulheres. As estatísticas desse caso foram usadas nos cálculos de exemplo de DD. No entanto, quando os subgrupos departamentais foram examinados, as mulheres demonstraram ter taxas de admissão mais altas do que os homens quando condicionadas pelo departamento. A explicação foi que as mulheres se inscreveram em departamentos com taxas de aceitação mais baixas do que os homens. O exame das taxas de aceitação subagrupadas revelou que as mulheres foram realmente aceitas em uma taxa mais alta do que os homens nos departamentos com taxas de aceitação mais baixas.
A métrica CDD fornece uma medida única para todas as disparidades encontradas nos subgrupos definidos por um atributo de um conjunto de dados por meio da média deles. É definida como a média ponderada das disparidades demográficas (DDi) para cada um dos subgrupos, com cada disparidade de subgrupo ponderada em proporção ao número de observações contidas. A fórmula para a disparidade demográfica condicional é a seguinte:
CDD = (1/n)\$1∑ini \$1DDi
Em que:
+ ∑ini = n é o número total de observações e ni é o número de observações para cada subgrupo.
+ DDi = ni(0)/n(0) - ni(1)/n(1) = PiR(y0) - PiA(y1) é a disparidade demográfica para o i-ésimo subgrupo.
A disparidade demográfica de um subgrupo (DDi) é a diferença entre a proporção de resultados rejeitados e a proporção de resultados aceitos para cada subgrupo.
O intervalo de valores de DD para resultados binários para o conjunto de dados completo DDd ou para seus subgrupos condicionalizados DDi é [-1, \$11].
+ \$11: quando não há rejeições na faceta *a* ou subgrupo e nenhuma aceitação na faceta *d* ou subgrupo
+ Valores positivos indicam que há uma disparidade demográfica, pois a faceta *d* ou subgrupo tem uma proporção maior dos resultados rejeitados no conjunto de dados do que dos resultados aceitos. Quanto maior o valor, menos favorece a faceta e maior a disparidade.
+ Valores negativos indicam que não há uma disparidade demográfica, pois a faceta *d* ou subgrupo tem uma proporção maior dos resultados aceitos no conjunto de dados do que dos resultados rejeitados. Quanto menor o valor, mais favorecida é a faceta.
+ -1: quando não há rejeições na faceta *d* ou subgrupo e nenhuma aceitação na faceta *a* ou subgrupo
Se você não condicionar nada, o CDD será zero se e somente se o DPL for zero.
Essa métrica é útil para explorar os conceitos de discriminação direta e indireta e de justificativa objetiva na legislação e jurisprudência de não discriminação da UE e do Reino Unido. Para obter informações adicionais, consulte [Por que a imparcialidade não pode ser automatizada](https://arxiv.org/abs/2005.05906). Este documento também contém dados e análises relevantes do caso de admissões em Berkeley, que mostram como a condicionalização em subgrupos de taxas de admissão departamental ilustra o paradoxo de Simpson.
# Gere relatórios de viés nos dados de pré-treinamento no Studio SageMaker
SageMaker O Clarify é integrado ao Amazon SageMaker Data Wrangler, o que pode ajudá-lo a identificar preconceitos durante a preparação dos dados sem precisar escrever seu próprio código. O Data Wrangler fornece uma end-to-end solução para importar, preparar, transformar, caracterizar e analisar dados com o Amazon Studio. SageMaker Para obter uma visão geral do fluxo de trabalho de preparação de dados do Data Wrangler, consulte [Prepare dados de ML com o Amazon SageMaker Data Wrangler](data-wrangler.md).
Você especifica atributos de interesse, como sexo ou idade, e o SageMaker Clarify executa um conjunto de algoritmos para detectar a presença de viés nesses atributos. Depois que o algoritmo é executado, o SageMaker Clarify fornece um relatório visual com uma descrição das fontes e da gravidade do possível viés para que você possa planejar as etapas de mitigação. Por exemplo, em um conjunto de dados financeiros que contém alguns exemplos de empréstimos comerciais para uma faixa etária em comparação com outras, a SageMaker IA sinaliza o desequilíbrio para que você possa evitar um modelo que desfavoreça essa faixa etária.
**Para analisar e relatar o desvio dos dados**
Para começar a usar o Data Wrangler, consulte [Conceitos básicos do Data Wrangler](data-wrangler-getting-started.md).
1. No Amazon SageMaker Studio Classic, no menu **Home** (![\[Black square icon representing a placeholder or empty image.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/studio/icons/house.png)) no painel esquerdo, navegue até o nó **Data** e escolha **Data Wrangler**. Isso abre a **página inicial do Data Wrangler** no Studio Classic.
1. Escolha o botão **\$1 Importar dados** para criar um novo fluxo.
1. Na sua página de fluxo, na guia **Importar**, escolha Amazon S3, navegue até seu bucket do Amazon S3, encontre seu conjunto de dados e escolha **Importar**.
1. Após importar seus dados, no gráfico de fluxo na guia **Fluxo de dados**, escolha o sinal **\$1** à direita do nó **Tipos de dados**.
1. Escolha **Adicionar análise**.
1. Na página **Criar análise**, escolha **Relatório de Desvio** para o **tipo de análise**.
1. Configure o relatório de desvio fornecendo um **nome** do relatório, a coluna a ser prevista e se é um valor ou limite, a coluna a ser analisada quanto ao desvio (a faceta) e se é um valor ou limite.
1. Continue configurando o relatório de desvio escolhendo as métricas de desvio.
![\[Escolha a métrica de desvio.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify-data-wrangler-configure-bias-metrics.png)
1. Escolha **Verificar desvio** para gerar e visualizar o relatório de desvio. Role para baixo para visualizar todos os relatórios.
![\[Gere e visualize o relatório de desvio.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify-data-wrangler-create-bias-report.png)
1. Escolha o cursor à direita da descrição de cada métrica de desvio para ver a documentação que pode ajudar você a interpretar a importância dos valores métricos.
1. Para visualizar um resumo da tabela dos valores da métrica de desvio, escolha a opção **Tabela**. Para salvar o relatório, escolha **Salvar** no canto inferior direito da página. Você pode ver o relatório no gráfico de fluxo na guia **Fluxo de dados**. Clique duas vezes no relatório para abri-lo.
# Dados de pós-treinamento e desvio do modelo
A análise de desvio pós-treinamento pode ajudar a revelar desvios que podem ter emanado de desvios nos dados ou de desvios introduzidos pelos algoritmos de classificação e predição. Essas análises levam em consideração os dados, incluindo os rótulos e as predições de um modelo. Você avalia o desempenho analisando rótulos previstos ou comparando as predições com os valores-alvo observados nos dados em relação a grupos com atributos diferentes. Há diferentes noções de equidade, cada uma exigindo diferentes métricas de desvio para medir.
Há conceitos jurídicos de equidade que podem não ser fáceis de capturar porque são difíceis de detectar. Por exemplo, o conceito americano de impacto díspar que ocorre quando um grupo, chamado de faceta *d* menos favorecida, experimenta um efeito adverso mesmo quando a abordagem adotada parece ser justa. Esse tipo de desvio pode não ser devido a um modelo de machine learning, mas ainda pode ser detectado pela análise de desvio pós-treinamento.
O Amazon SageMaker Clarify tenta garantir o uso consistente da terminologia. Para obter uma lista de termos e suas definições, consulte [A Amazon SageMaker esclarece os termos de preconceito e imparcialidade](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms).
Para obter informações adicionais sobre métricas de viés pós-treinamento, consulte [Saiba como o Amazon SageMaker Clarify ajuda a detectar medidas tendenciosas](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/) [e imparciais para o Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf). .
# Métricas de dados pós-treinamento e desvio do modelo
O Amazon SageMaker Clarify fornece onze dados pós-treinamento e métricas de viés de modelos para ajudar a quantificar várias concepções de justiça. Esses conceitos não podem ser todos satisfeitos simultaneamente e a seleção depende das especificidades dos casos envolvendo possíveis desvios que estão sendo analisados. A maioria dessas métricas é uma combinação dos números retirados das matrizes de confusão de classificação binária para os diferentes grupos demográficos. Como a equidade e o desvio podem ser definidos por uma ampla variedade de métricas, é necessário o julgamento humano para entender e escolher quais métricas são relevantes para o caso de uso individual, e os clientes devem consultar as partes interessadas apropriadas para determinar a medida apropriada de equidade para sua aplicação.
Usamos a notação a seguir para debater as métricas de desvio. O modelo conceitual descrito aqui é para classificação binária, em que os eventos são rotulados como tendo apenas dois resultados possíveis em seu espaço amostral, chamados de positivos (com valor 1) e negativos (com valor 0). Esse framework geralmente é extensível à classificação multicategórica de forma direta ou a casos que envolvem resultados contínuos valiosos, quando necessário. No caso da classificação binária, rótulos positivos e negativos são atribuídos aos resultados registrados em um conjunto de dados bruto para uma faceta favorecida *a* e para uma faceta desfavorecida *d*. Esses rótulos y são chamados de *rótulos observados* para diferenciá-los dos *rótulos previstos* y' que são atribuídos por um modelo de machine learning durante os estágios de treinamento ou inferências do ciclo de vida do ML. Esses rótulos são usados para definir distribuições de probabilidade Pa(y) e Pd(y) para seus respectivos resultados facetários.
+ rótulos:
+ y representa os n rótulos observados para resultados de eventos em um conjunto de dados de treinamento.
+ y' representa os rótulos previstos para os n rótulos observados no conjunto de dados por um modelo treinado.
+ resultados:
+ Um resultado positivo (com valor 1) para uma amostra, como a aceitação de uma candidatura.
+ n(1) é o número de rótulos observados para resultados positivos (aceitações).
+ n'(1) é o número de rótulos previstos para resultados positivos (aceitações).
+ Um resultado negativo (com valor 0) para uma amostra, como uma rejeição de candidatura.
+ n(0) é o número de rótulos observados para resultados negativos (rejeições).
+ n'(0) é o número de rótulos previstos para resultados negativos (rejeições).
+ valores da faceta:
+ faceta *a*: O valor do atributo que define um grupo demográfico que o desvio favorece.
+ na é o número de rótulos observados para o valor da faceta favorecido: na = na(1) \$1 na(0) a soma dos rótulos observados positivos e negativos para a faceta de valor *a*.
+ n'a é o número de rótulos previstos para o valor da faceta favorecido: n'a = n'a(1) \$1 n'a(0) a soma dos rótulos de resultados previstos positivos e negativos para a faceta de valor *a*. Observe que n'a = na.
+ faceta *d*: O valor do atributo que define um grupo demográfico que o desvio desfavorece.
+ nd é o número de rótulos observados para o valor da faceta desfavorecido: nd = nd(1) \$1 nd(0) a soma dos rótulos observados positivos e negativos para a faceta de valor *d*.
+ n'd é o número de rótulos previstos para o valor da faceta desfavorecido: n'd = n'd(1) \$1 n'd(0) a soma dos rótulos previstos positivos e negativos para a faceta de valor *d*. Observe que n'd = nd.
+ distribuições de probabilidade para resultados dos resultados dos dados facetários rotulados:
+ Pa(y) é a distribuição de probabilidade dos rótulos observados para a faceta *a*. Para dados binários rotulados, essa distribuição é dada pela razão entre o número de amostras na faceta *a* rotulada com resultados positivos e o número total, Pa(y1) = na(1)/ na, e a razão entre o número de amostras com resultados negativos e o número total, Pa(y0) = na(0)/ na.
+ Pd(y) é a distribuição de probabilidade dos rótulos observados para a faceta *d*. Para dados binários rotulados, essa distribuição é dada pelo número de amostras na faceta *d* rotulada com resultados positivos e o número total, Pd(y1) = nd(1)/ nd, e a razão entre o número de amostras com resultados negativos e o número total, Pd(y0) = nd(0)/ nd.
A tabela a seguir contém uma folha de dicas para orientação rápida e links para as métricas de desvio pós-treinamento.
Métricas de desvio pós-treinamento
| Métrica de desvio pós-treinamento | Description | Exemplo de pergunta | Interpretar valores de métricas |
| --- | --- | --- | --- |
| [Diferença nas proporções positivas nos rótulos previstos (DPPL)](clarify-post-training-bias-metric-dppl.md) | Mede a diferença na proporção de predições positivas entre a faceta favorecida a e a faceta desfavorecida d. | Houve um desequilíbrio entre os grupos demográficos nos resultados positivos previstos que possa indicar desvio? | Intervalo para rótulos de facetas binários e multicategóricos normalizados: `[-1,+1]` Intervalo para rótulos contínuos: (-∞, \$1∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Impacto díspar (DI)](clarify-post-training-bias-metric-di.md) | Mede a proporção das proporções dos rótulos previstos para a faceta favorecida a e a faceta desfavorecida d. | Houve um desequilíbrio entre os grupos demográficos nos resultados positivos previstos que possa indicar desvio? | Intervalo para rótulos de facetas binários normalizados, contínuos e multicategóricos: [0,∞) Interpretação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Disparidade demográfica condicional em rótulos previstos (CDDPL)](clarify-post-training-bias-metric-cddpl.md) | Mede a disparidade de rótulos previstos entre diferentes facetas como um todo, mas também por subgrupos. | Alguns grupos demográficos têm uma proporção maior de rejeições nos resultados de pedido de empréstimo do que a proporção de aceitações? | Intervalo de valores de CDDPL para resultados binários, multicategóricos e contínuos: `[-1, +1]` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Teste de inversão contrafactual (FT)](clarify-post-training-bias-metric-ft.md) | Examina cada membro da faceta d e avalia se membros semelhantes da faceta a têm predições de modelos diferentes. | Um grupo de uma faixa etária específica corresponde estreitamente em todas os atributos a uma faixa etária diferente, mas paga mais, em média? | O intervalo para rótulos binários e de facetas multicategóricas é [-1, \$11]. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença de precisão (AD)](clarify-post-training-bias-metric-ad.md) | Mede a diferença entre a precisão da predição para as facetas favorecidas e desfavorecidas. | O modelo prevê rótulos com a mesma precisão para aplicações em todos os grupos demográficos? | O intervalo para rótulos binários e de facetas multicategóricas é [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença de recordação (RD)](clarify-post-training-bias-metric-rd.md) | Compara a recordação do modelo quanto às facetas favorecidas e desfavorecidas. | Existe um desvio baseado na idade nos empréstimos devido a um modelo com maior recordação para uma faixa etária em comparação com outra? | Intervalo para classificação binária e multicategórica: `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença na aceitação condicional () DCAcc](clarify-post-training-bias-metric-dcacc.md) | Compara os rótulos observados com os rótulos previstos por um modelo. Avalia se isso é o mesmo em todas as facetas para resultados positivos previstos (aceitações). | Ao comparar uma faixa etária com outra, os empréstimos são aceitos com mais ou menos frequência do que o previsto (baseado nas qualificações)? | O intervalo para rótulos binários, contínuos e de facetas multicategóricas: (-∞, \$1∞). [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença nas taxas de aceitação (DAR)](clarify-post-training-bias-metric-dar.md) | Mede a diferença nas proporções entre os resultados positivos observados (TP) e os positivos previstos (TP \$1 FP) entre as facetas favorecidas e desfavorecidas. | O modelo tem a mesma precisão ao prever aceitações de empréstimos para candidatos qualificados em todas as faixas etárias? | O intervalo para rótulos binários, contínuos e de faceta multicategórica é [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença de especificidade (SD)](clarify-post-training-bias-metric-sd.md) | Compara a especificidade do modelo entre facetas favorecidas e desfavorecidas. | Existe um desvio baseado na idade nos empréstimos porque o modelo prevê uma maior especificidade para uma faixa etária em comparação com outra? | Intervalo para classificação binária e multicategorial: `[-1, +1]`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença na rejeição condicional (DCR)](clarify-post-training-bias-metric-dcr.md) | Compara os rótulos observados com os rótulos previstos por um modelo e avalia se isso é o mesmo em todas as facetas para resultados negativos (rejeições). | Há mais ou menos rejeições para pedidos de empréstimo do que o previsto para uma faixa etária em comparação com outra baseado nas qualificações? | O intervalo para rótulos binários, contínuos e de facetas multicategóricas: (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Diferença nas taxas de rejeição (DRR)](clarify-post-training-bias-metric-drr.md) | Mede a diferença nas proporções entre os resultados negativos observados (TN) e os negativos previstos (TN \$1 FN) entre as facetas desfavorecidas e favorecidas. | O modelo tem a mesma precisão ao prever rejeições de empréstimos para candidatos não qualificados em todas as faixas etárias? | O intervalo para rótulos binários, contínuos e de faceta multicategórica é [-1, \$11].[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Igualdade de tratamento (TE)](clarify-post-training-bias-metric-te.md) | Mede a diferença na proporção de falso-positivos e falso-negativos entre as facetas favorecidas e desfavorecidas. | Em pedidos de empréstimo, a proporção relativa de falso-positivos para falso-negativos é a mesma em todas as faixas etárias? | O intervalo para rótulos binários e de facetas multicategóricas: (-∞, \$1∞).[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [Entropia generalizada (GE)](clarify-post-training-bias-metric-ge.md) | Mede a desigualdade nos benefícios b atribuídos a cada entrada pelas predições de modelo. | Dos dois modelos de candidatos para classificação de pedido de empréstimo, um leva a uma distribuição irregular dos resultados desejados do que o outro? | O intervalo para rótulos binários e multicategóricos: (0, 0.5). A GE é indefinida quando o modelo prevê somente falso-negativos.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
Para obter informações adicionais sobre métricas de desvio pós-treinamento, consulte [Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf).
**Topics**
+ [Diferença nas proporções positivas nos rótulos previstos (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ [Impacto díspar (DI)](clarify-post-training-bias-metric-di.md)
+ [Diferença na aceitação condicional () DCAcc](clarify-post-training-bias-metric-dcacc.md)
+ [Diferença na rejeição condicional (DCR)](clarify-post-training-bias-metric-dcr.md)
+ [Diferença de especificidade (SD)](clarify-post-training-bias-metric-sd.md)
+ [Diferença de recordação (RD)](clarify-post-training-bias-metric-rd.md)
+ [Diferença nas taxas de aceitação (DAR)](clarify-post-training-bias-metric-dar.md)
+ [Diferença nas taxas de rejeição (DRR)](clarify-post-training-bias-metric-drr.md)
+ [Diferença de precisão (AD)](clarify-post-training-bias-metric-ad.md)
+ [Igualdade de tratamento (TE)](clarify-post-training-bias-metric-te.md)
+ [Disparidade demográfica condicional em rótulos previstos (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ [Teste de inversão contrafactual (FT)](clarify-post-training-bias-metric-ft.md)
+ [Entropia generalizada (GE)](clarify-post-training-bias-metric-ge.md)
# Diferença nas proporções positivas nos rótulos previstos (DPPL)
A diferença nas proporções positivas na métrica de rótulos previstos (DPPL) determina se o modelo prevê resultados de forma diferente para cada faceta. É definido como a diferença entre a proporção de predições positivas (y' = 1) para a faceta *a* e a proporção de predições positivas (y' = 1) para a faceta *d*. Por exemplo, se as predições de modelo concederem empréstimos a 60% de um grupo de meia-idade (faceta *a*) e 50% de outras faixas etárias (faceta *d*), ele pode ser tendencioso contra a faceta *d*. Neste exemplo, você deve determinar se a diferença de 10% é relevante para um caso de desvio.
Uma comparação da diferença nas proporções dos rótulos (DPL), uma medida do desvio no pré-treinamento, com o DPPL, uma medida do desvio no pós-treinamento, avalia se o desvio em proporções positivas, que está inicialmente presente no conjunto de dados, muda após o treinamento. Se o DPPL for maior que o DPL, o desvio em proporções positivas aumentou após o treinamento. Se o DPPL for menor que o DPL, o modelo não teve aumento no desvio em proporções positivas após o treinamento. A comparação do DPL com o DPPL não garante que o modelo reduza o desvio em todas as dimensões. Por exemplo, o modelo ainda pode ser tendencioso ao considerar outras métricas, como [Teste de inversão contrafactual (FT)](clarify-post-training-bias-metric-ft.md) ou [Diferença de precisão (AD)](clarify-post-training-bias-metric-ad.md). Para obter mais informações sobre a detecção de preconceitos, consulte a postagem do blog [Saiba como o Amazon SageMaker Clarify ajuda a detectar preconceitos](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/). Consulte [Diferença nas proporções dos rótulos (DPL)](clarify-data-bias-metric-true-label-imbalance.md) para mais informações sobre DPL.
A fórmula do DPPL é:
DPPL = q'a - q'd
Em que:
+ q'a = n'a(1)/na é a proporção prevista da faceta *a* que obtém um resultado positivo de valor 1. Em nosso exemplo, a proporção de uma faceta de meia-idade prevista para a concessão de um empréstimo. Aqui, n'a(1) representa o número de membros da faceta *a* que obtêm um resultado positivo previsto de valor 1 e na é o número de membros da faceta *a*.
+ q'd = n'd(1)/nd é a proporção prevista da faceta *d* que obtém um resultado positivo de valor 1. Em nosso exemplo, uma faceta de pessoas mais velhas e mais jovens previu a concessão de um empréstimo. Aqui, n'd(1) representa o número de membros da faceta *d* que obtêm um resultado positivo previsto e nd é o número de membros da faceta *d*.
Se o DPPL estiver próximo o suficiente de 0, isso significa que a *paridade demográfica* pós-treinamento foi alcançada.
Para rótulos de facetas binárias e multicategóricas, os valores de DPL variam ao longo do intervalo [-1, 1]. Para rótulos contínuos, os valores variam ao longo do intervalo (-∞, \$1∞).
+ Valores positivos de DPPL indicam que a faceta *a* tem uma proporção maior de resultados positivos quando comparada com a faceta *d*.
Isso é conhecido como *desvio positivo*.
+ Valores de DPPL próximos de zero indicam uma proporção mais igual de resultados positivos previstos entre as facetas *a* e *d* e um valor de zero indica paridade demográfica perfeita.
+ Valores negativos de DPPL indicam que a faceta *d* tem uma proporção maior de resultados positivos quando comparada com a faceta *a*. Isso é conhecido como *desvio negativo*.
# Impacto díspar (DI)
A diferença nas proporções positivas na métrica de rótulos previstos pode ser avaliada na forma de uma proporção.
A comparação de proporções positivas na métrica de rótulos previstos pode ser avaliada na forma de uma proporção em vez de como uma diferença, como acontece com o [Diferença nas proporções positivas nos rótulos previstos (DPPL)](clarify-post-training-bias-metric-dppl.md). A métrica de impacto díspar (DI) é definida como a razão da proporção de predições positivas (y’ = 1) para a faceta *d* sobre a proporção de predições positivas (y’ = 1) para a faceta *a*. Por exemplo, se as predições de modelo concederem empréstimos a 60% de um grupo de meia-idade (faceta *a*) e 50% de outras faixas etárias (faceta *d*), então DI = 0,5/0,6 = 0,8, o que indica um desvio positivo e um impacto adverso no outro grupo etário representado pela faceta *d*.
A fórmula para a diferença das proporções dos rótulos previstos:
DI = q'd/q'a
Em que:
+ q'a = n'a(1)/na é a proporção prevista da faceta *a* que obtém um resultado positivo de valor 1. Em nosso exemplo, a proporção de uma faceta de meia-idade prevista para a concessão de um empréstimo. Aqui, n'a(1) representa o número de membros da faceta *a* que obtêm um resultado positivo previsto e na é o número de membros da faceta *a*.
+ q'd = n'd(1)/nd é a proporção prevista da faceta *d* que obtém um resultado positivo de valor 1. Em nosso exemplo, uma faceta de pessoas mais velhas e mais jovens previu a concessão de um empréstimo. Aqui, n'd(1) representa o número de membros da faceta *d* que obtêm um resultado positivo previsto e nd é o número de membros da faceta *d*.
Para rótulos binários, contínuos e de facetas multicategóricas, os valores de DI variam ao longo do intervalo [0, ∞).
+ Valores menores que 1 indicam que a faceta *a* tem uma proporção maior de resultados positivos previstos do que a faceta *d*. Isso é conhecido como *desvio positivo*.
+ Um valor de 1 indica uma paridade demográfica.
+ Valores maiores que 1 indicam que a faceta *d* tem uma proporção maior de resultados positivos previstos do que a faceta *a*. Isso é conhecido como *desvio negativo*.
# Diferença na aceitação condicional () DCAcc
Essa métrica compara os rótulos observados com os rótulos previstos pelo modelo e avalia se isso é o mesmo em todas as facetas para resultados positivos previstos. Essa métrica quase imita o desvio humano, pois quantifica quantos resultados positivos a mais um modelo previu (rótulos y’) para uma determinada faceta em comparação com o que foi observado no conjunto de dados de treinamento (rótulos y). Por exemplo, se houvesse mais aceitações (um resultado positivo) observadas no conjunto de dados de treinamento para pedidos de empréstimo de um grupo de meia-idade (faceta *a*) do que o previsto pelo modelo baseado nas qualificações em comparação com a faceta contendo outras faixas etárias (faceta *d*), isso pode indicar um desvio potencial na forma como os empréstimos foram aprovados em favor do grupo de meia-idade.
A fórmula da diferença na aceitação condicional:
DCAcc = c a - c d
Em que:
+ ca = na(1)/ n'a(1) é a proporção entre o número observado de resultados positivos de valor 1 (aceitações) da faceta *a* e o número previsto de resultados positivos (aceitações) para a faceta *a*.
+ cd = nd(1)/ n'd(1) é a proporção entre o número observado de resultados positivos de valor 1 (aceitações) da faceta *d* e o número previsto de resultados positivos (aceitações) para a faceta *a*.
A DCAcc métrica pode capturar vieses positivos e negativos que revelam tratamento preferencial com base nas qualificações. Considere os seguintes exemplos de preconceito baseado na idade na aceitação de empréstimos:
**Exemplo 1: desvio positivo**
Suponha que tenhamos um conjunto de dados de 100 pessoas de meia-idade (faceta *a*) e 50 pessoas de outras faixas etárias (faceta *d*) que pediram empréstimos, onde o modelo recomendou que 60 da faceta *a* e 30 da faceta *d* recebessem empréstimos. Portanto, as proporções previstas são imparciais em relação à métrica DPPL, mas os rótulos observados mostram que 70 da faceta *a* e 20 da faceta *d* foram concedidos empréstimos. Em outras palavras, o modelo concedeu empréstimos a 17% menos para a faceta de meia-idade do que os rótulos observados nos dados de treinamento sugeridos (70/60 = 1,17) e concedeu empréstimos a 33% a mais para outras faixas etárias do que os rótulos observados sugeriram (20/30 = 0,67). O cálculo do DCAcc valor fornece o seguinte:
DCAcc = 70/60 - 20/30 = 1/2
O valor positivo indica que há um desvio potencial contra a faceta *a* de meia-idade com uma taxa de aceitação menor em comparação com a outra faceta *d* do que os dados observados (considerados imparciais) indicam ser o caso.
**Exemplo 2: desvio negativo**
Suponha que tenhamos um conjunto de dados de 100 pessoas de meia-idade (faceta *a*) e 50 pessoas de outras faixas etárias (faceta *d*) que pediram empréstimos, onde o modelo recomendou que 60 da faceta *a* e 30 da faceta *d* recebessem empréstimos. Portanto, as proporções previstas são imparciais em relação à métrica DPPL, mas os rótulos observados mostram que 50 da faceta *a* e 40 da faceta *d* foram concedidos empréstimos. Em outras palavras, o modelo concedeu empréstimos a 17% menos para faceta de meia-idade do que os rótulos observados nos dados de treinamento sugeridos (50/60 = 0,83) e concedeu empréstimos a 33% mais para outras faixas etárias que os rótulos observados sugeriram (40/30 = 1,33). O cálculo do DCAcc valor fornece o seguinte:
DCAcc = 50/60 - 40/30 = -1/2
O valor negativo indica que há um desvio potencial contra a faceta *d* com uma taxa de aceitação menor em comparação com a faceta *a* de meia-idade do que os dados observados (considerados imparciais) indicam ser o caso.
Observe que você pode usar DCAcc para ajudá-lo a detectar possíveis vieses (não intencionais) de humanos que supervisionam as previsões do modelo em um ambiente. human-in-the-loop Suponha, por exemplo, que as predições y' do modelo foram imparciais, mas a eventual decisão é tomada por um humano (possivelmente com acesso a atributos adicionais) que pode alterar as predições de modelo para gerar uma versão nova e final de y'. O processamento adicional pelo ser humano pode, sem querer, negar empréstimos a um número desproporcional de uma faceta. DCAccpode ajudar a detectar esses possíveis preconceitos.
O intervalo de valores para diferenças na aceitação condicional para rótulos binários, contínuos e de faceta multicategórica é (-∞, \$1∞).
+ Valores positivos ocorrem quando a razão do número observado de aceitações em comparação com as aceitações previstas para a faceta *a* é maior do que a mesma razão para a faceta *d*. Esses valores indicam um possível desvio contra os candidatos qualificados da faceta *a*. Quanto maior a diferença das proporções, mais extremo é o desvio aparente.
+ Valores próximos de zero ocorrem quando a proporção do número observado de aceitações em comparação com as aceitações previstas para a faceta *a* é semelhante à proporção para a faceta *d*. Esses valores indicam que as taxas de aceitação previstas são consistentes com os valores observados nos dados rotulados e que candidatos qualificados de ambas as facetas estão sendo aceitos de forma semelhante.
+ Valores negativos ocorrem quando a razão do número observado de aceitações em comparação com as aceitações previstas para a faceta *a* é menor do que a proporção para a faceta *d*. Esses valores indicam um possível desvio contra os candidatos qualificados da faceta *d*. Quanto mais negativa for a diferença nas proporções, mais extremo será o desvio aparente.
# Diferença na rejeição condicional (DCR)
Essa métrica compara os rótulos observados com os rótulos previstos pelo modelo e avalia se isso é o mesmo em todas as facetas para resultados negativos (rejeições). Essa métrica quase imita o desvio humano, pois quantifica quantos resultados negativos a mais um modelo concedeu (rótulos previstos y’) a uma determinada faceta em comparação com o que foi sugerido pelos rótulos no conjunto de dados de treinamento (rótulos observados y). Por exemplo, se houvesse mais rejeições observadas (um resultado negativo) para pedidos de empréstimo para um grupo de meia-idade (faceta *a*) do que o previsto pelo modelo baseado em qualificações em comparação com a faceta contendo outras faixas etárias (faceta *d*), isso pode indicar um desvio potencial na forma como os empréstimos foram rejeitados, favorecendo o grupo de meia-idade em relação a outros grupos.
A fórmula da diferença na aceitação condicional:
DCR = rd - ra
Em que:
+ rd = nd(0)/ n'd(0) é a razão entre o número observado de resultados negativos de valor 0 (rejeições) da faceta *d* e o número previsto de resultados negativos (rejeições) para a faceta *d*.
+ ra = na(0)/ n'a(0) é a razão entre o número observado de resultados negativos de valor 0 (rejeições) da faceta *a* e o número previsto de resultados negativos de valor 0 (rejeições) para a faceta *a*.
A métrica DCR pode capturar desvios positivos e negativos que revelam tratamento preferencial baseado nas qualificações. Considere as seguintes instâncias de desvio baseado na idade na aceitação de empréstimos:
**Exemplo 1: desvio positivo**
Suponha que tenhamos um conjunto de dados de 100 pessoas de meia-idade (faceta *a*) e 50 pessoas de outras faixas etárias (faceta *d*) que solicitaram empréstimos, onde o modelo recomendou que 60 da faceta *a* e 30 da faceta *d*fossem rejeitadas para empréstimos. Portanto, as proporções previstas são imparciais pela métrica DPPL, mas os rótulos observados mostram que 50 da faceta *a* e 40 da faceta *d* foram rejeitados. Em outras palavras, o modelo rejeitou 17% mais empréstimos da faceta de meia-idade do que os rótulos observados nos dados de treinamento sugeridos (50/60 = 0,83) e rejeitou 33% menos empréstimos do que outras faixas etárias do que os rótulos observados sugeriram (40/30 = 1,33). O valor de DCR quantifica essa diferença na proporção das taxas de rejeição observadas e previstas entre as facetas. O valor positivo indica que há um desvio potencial que favorece o grupo de meia-idade com taxas de rejeição mais baixas em comparação com outros grupos do que os dados observados (considerados imparciais) indicam ser o caso.
DCR = 40/30 - 50/60 = 1/2
**Exemplo 2: desvio negativo**
Suponha que tenhamos um conjunto de dados de 100 pessoas de meia-idade (faceta *a*) e 50 pessoas de outras faixas etárias (faceta *d*) que solicitaram empréstimos, onde o modelo recomendou que 60 da faceta *a* e 30 da faceta *d*fossem rejeitadas para empréstimos. Portanto, as proporções previstas são imparciais pela métrica DPPL, mas os rótulos observados mostram que 70 da faceta *a* e 20 da faceta *d* foram rejeitados. Em outras palavras, o modelo rejeitou 17% menos empréstimos da faceta de meia-idade do que os rótulos observados nos dados de treinamento sugeridos (70/60 = 1,17) e rejeitou 33% mais empréstimos do que outras faixas etárias do que os rótulos observados sugeriram (20/30 = 0,67). O valor negativo indica que há um desvio potencial que favorece a faceta *a* com taxas de rejeição mais baixas em comparação com a faceta *a* de meia-idade do que os dados observados (considerados imparciais) indicam ser o caso.
DCR = 20/30 - 70/60 = -1/2
O intervalo de valores para diferenças na rejeição condicional para rótulos binários, contínuos e de faceta multicategórica é (-∞, \$1∞).
+ Valores positivos ocorrem quando a razão do número observado de rejeições em comparação com as rejeições previstas para a faceta *d* é maior do que a razão para a faceta *a*. Esses valores indicam um possível desvio contra os candidatos qualificados da faceta *a*. Quanto maior o valor da métrica DCR, mais extremo será o desvio aparente.
+ Valores próximos de zero ocorrem quando a proporção do número observado de rejeições em comparação com as aceitações previstas para a faceta *a* é similar à proporção para a faceta *d*. Esses valores indicam que as taxas de rejeições previstas são consistentes com os valores observados nos dados rotulados e que candidatos qualificados de ambas as facetas estão sendo rejeitados de forma semelhante.
+ Valores negativos ocorrem quando a proporção do número observado de rejeições em comparação às rejeições previstas para a faceta *d* é menor que a faceta *a* da proporção. Esses valores indicam um possível desvio contra os candidatos qualificados da faceta *d*. Quanto maior a magnitude da métrica de DCR negativa, mais extremo será o desvio aparente.
# Diferença de especificidade (SD)
A diferença de especificidade (SD) é a diferença na especificidade entre a faceta favorecida *a* e a faceta desfavorecida *d*. A especificidade mede a frequência com que o modelo prevê corretamente um resultado negativo (y'=0). Qualquer diferença nessas especificidades é uma forma potencial de desvio.
A especificidade é perfeita para uma faceta se todos os casos y=0 forem previstos corretamente para essa faceta. A especificidade é maior quando o modelo minimiza os falso-positivos, conhecidos como erro do Tipo I. Por exemplo, a diferença entre uma baixa especificidade para emprestar para a faceta *a* e a alta especificidade para emprestar para a faceta *d*, é uma medida de desvio em relação à faceta *d*.
A fórmula a seguir é para a diferença na especificidade das facetas *a* e *d*.
SD = TNd/(TNd \$1 FPd) - TNa/(TNa \$1 FPa) = TNRd - TNRa
As seguintes variáveis usadas para calcular a SD são definidas da seguinte forma:
+ TNd são os negativos verdadeiros previstos para a faceta *d*.
+ FPd são os falso-positivos previstos para a faceta *d*.
+ TNd são os negativos verdadeiros previstos para a faceta *a*.
+ FPd são os falso-positivos previstos para a faceta *a*.
+ TNRa = TNa/(TNa \$1 FPa) é a taxa negativa verdadeira, também conhecida como especificidade, para a faceta *a*.
+ TNRd = TNd/(TNd \$1 FPd) é a taxa negativa verdadeira, também conhecida como especificidade, para a faceta *d*.
Por exemplo, considere as seguintes matrizes de confusão para as facetas *a* e *d*:
Matriz de confusão para a faceta `a` favorecida
| Previsões de classe a | Resultado real 0 | Resultado real 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
Matriz de confusão para a faceta `d` desfavorecida
| Previsões de classe d | Resultado real 0 | Resultado real 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
O valor da diferença de especificidade é `SD = 18/(18+5) - 20/(20+10) = 0.7826 - 0.6667 = 0.1159`, o que indica um desvio contra a faceta *d*.
O intervalo de valores para a diferença de especificidade entre as facetas *a* e *d* para classificação binária e multicategórica é `[-1, +1]`. Esta métrica não está disponível para o caso de rótulos contínuos. Aqui está o que os diferentes valores de SD implicam:
+ Valores positivos são obtidos quando há maior especificidade para a faceta *d* do que para a faceta *a*. Isso sugere que o modelo encontra menos falso-positivos para a faceta *d* do que para a faceta *a*. Um valor positivo indica um desvio em relação à faceta *d*.
+ Valores próximos de zero indicam que a especificidade das facetas que estão sendo comparadas é semelhante. Isso sugere que o modelo encontra um número semelhante de falso-positivos em ambas as facetas e não é tendencioso.
+ Valores positivos são obtidos quando há maior especificidade para a faceta *a* do que para a faceta *d*. Isso sugere que o modelo encontra mais falso-positivos para a faceta *a* do que para a faceta *d*. Um valor negativo indica um desvio em relação à faceta *a*.
# Diferença de recordação (RD)
A métrica de diferença de recordação (RD) é a diferença na recordação do modelo entre a faceta favorecida *a* e a faceta desfavorecida *d*. Qualquer diferença nessas recordações é uma forma potencial de desvio. A recordação é a taxa positivo verdadeira (TPR), que mede com que frequência o modelo prevê corretamente os casos que devem receber um resultado positivo. A recordação é perfeita para uma faceta se todos os casos y=1 forem corretamente previstos como y’=1 para essa faceta. A recordação é maior quando o modelo minimiza os falso-negativos, conhecidos como erro do Tipo II. Por exemplo, quantas pessoas em dois grupos diferentes (facetas *a* e *d*) que deveriam se qualificar para empréstimos são detectadas corretamente pelo modelo? Se a taxa de recordação for alta para empréstimos para a faceta *a*, mas baixa para empréstimos para a faceta *d*, a diferença fornece uma medida desse desvio em relação ao grupo pertencente à faceta *d*.
A fórmula para a diferença nas taxas de recordação das facetas *a* e *d*:
RD = TPa/(TPa \$1 FNa) - TPd/(TPd \$1 FNd) = TPRa - TPRd
Em que:
+ TPa são os positivos verdadeiros previstos para a faceta *a*.
+ FNa são os falso-negativos previstos para a faceta *a*.
+ TPd são os positivos verdadeiros previstos para a faceta *d*.
+ FNd são os falso-negativos previstos para a faceta *d*.
+ TPR a = TPa/(TPa \$1 FNa) é a recordação da faceta *a*, ou sua taxa positiva verdadeira.
+ TPRd TPd/(TPd \$1 FNd) é a recordação da faceta *d*, ou sua taxa positiva verdadeira.
Por exemplo, considere as seguintes matrizes de confusão para as facetas *a* e *d*:
Matriz de confusão para a faceta a favorecida
| Previsões de classe a | Resultado real 0 | Resultado real 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
Matriz de confusão para a faceta d desfavorecida
| Previsões de classe d | Resultado real 0 | Resultado real 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
O valor da diferença de recordação é RD = 65/70 - 20/27 = 0,93 - 0,74 = 0,19, o que indica um desvio contra a faceta *d*.
O intervalo de valores para a diferença de recordação entre as facetas *a* e *d* para classificação binária e multicategórica é [-1, \$11]. Esta métrica não está disponível para o caso de rótulos contínuos.
+ Valores positivos são obtidos quando há maior recordação para a faceta *a* do que para a faceta *d*. Isso sugere que o modelo encontra mais positivos verdadeiros para a faceta *a* do que para a faceta *d*, que é uma forma de desvio.
+ Valores próximos de zero indicam que a recordação das facetas sendo comparadas é semelhante. Isso sugere que o modelo encontra aproximadamente o mesmo número de positivos verdadeiros em ambas as facetas e não é tendencioso.
+ Valores negativos são obtidos quando há maior recordação para a faceta *d* do que para a faceta *a*. Isso sugere que o modelo encontra mais positivos verdadeiros para a faceta *d* do que para a faceta *a*, que é uma forma de desvio.
# Diferença nas taxas de aceitação (DAR)
A diferença na métrica das taxas de aceitação (DAR) é a diferença nas proporções entre as predições positivas verdadeiras (TP) e as positivas observadas (TP \$1 FP) para as facetas *a* e *d*. Essa métrica mede a diferença na precisão do modelo para prever as aceitações dessas duas facetas. A precisão mede a fração de candidatos qualificados do conjunto de candidatos qualificados identificados como tal pelo modelo. Se a precisão do modelo para prever candidatos qualificados diverge entre as facetas, isso é um desvio e sua magnitude é medida pela DAR.
A fórmula para a diferença nas taxas de aceitação entre as facetas *a* e *d*:
DAR = TPa/(TPa \$1 FPa) - TPd/(TPd \$1 FPd)
Em que:
+ TPa são os positivos verdadeiros previstos para a faceta *a*.
+ FPa são os falso-positivos previstos para a faceta *a*.
+ TPd são os positivos verdadeiros previstos para a faceta *d*.
+ FPd são os falso-positivos previstos para a faceta *d*.
Por exemplo, suponha que o modelo aceite 70 candidatos de meia-idade (faceta *a*) para um empréstimo (rótulos positivos previstos), dos quais apenas 35 são realmente aceitos (rótulos positivos observados). Suponha também que o modelo aceite 100 candidatos de outras faixas etárias (faceta *d*) para um empréstimo (rótulos positivos previstos), dos quais apenas 40 são realmente aceitos (rótulos positivos observados). Então DAR = 35/70 - 40/100 = 0,10, o que indica um desvio potencial contra pessoas qualificadas da segunda faixa etária (faceta *d*).
O intervalo de valores para DAR para rótulos binários, contínuos e de facetas multicategóricas é [-1, \$11].
+ Valores positivos ocorrem quando a razão entre os positivos previstos (aceitações) e os resultados positivos observados (candidatos qualificados) para a faceta *a* é maior que a mesma proporção para a faceta *d*. Esses valores indicam um possível desvio contra a faceta desfavorecida *d* causada pela ocorrência de relativamente mais falso-positivos na faceta *d*. Quanto maior a diferença nas proporções, mais extremo é o desvio aparente.
+ Valores próximos de zero ocorrem quando a proporção entre os positivos previstos (aceitações) e os resultados positivos observados (candidatos qualificados) para as facetas *a* e *d* têm valores semelhantes, indicando que os rótulos observados para resultados positivos estão sendo previstos com igual precisão pelo modelo.
+ Valores negativos ocorrem quando a razão entre os positivos previstos (aceitações) e os resultados positivos observados (candidatos qualificados) para a faceta *d* é maior do que a mesma proporção para a faceta *a*. Esses valores indicam um possível desvio contra a faceta favorecida *a* causado pela ocorrência de relativamente mais falso-positivos na faceta *a*. Quanto mais negativa for a diferença nas proporções, mais extremo será o desvio aparente.
# Diferença nas taxas de rejeição (DRR)
A diferença na métrica das taxas de rejeição (DRR) é a diferença nas proporções da predições negativas verdadeiras (TN) em relação às negativas observadas (TN \$1 FN) para as facetas *a* e *d*. Essa métrica mede a diferença na precisão do modelo para prever as rejeições dessas duas facetas. A precisão mede a fração de candidatos não qualificados do conjunto de candidatos não qualificados que são identificados como tal pelo modelo. Se a precisão do modelo para prever candidatos não qualificados diverge entre as facetas, isso é um desvio e sua magnitude é medida pelo DRR.
A fórmula para a diferença nas taxas de rejeição entre as facetas *a* e *d*:
DRR = TNd/(TNd \$1 FNd) - TNa/(TNa \$1 FNa)
Os componentes da equação DRR anterior são os seguintes:
+ TNd são os negativos verdadeiros previstos para a faceta *d*.
+ FNd são os falso-negativos previstos para a faceta *d*.
+ TPa são os negativos verdadeiros previstos para a faceta *a*.
+ FNa são os falso-negativos previstos para a faceta *a*.
Por exemplo, suponha que o modelo rejeite 100 candidatos de meia-idade (faceta *a*) para um empréstimo (rótulos negativos previstos), dos quais 80 são, na verdade, não qualificados (rótulos negativos observados). Suponha também que o modelo rejeite 50 candidatos de outras faixas etárias (faceta *d*) para um empréstimo (rótulos negativos previstos), dos quais apenas 40 são realmente não qualificados (rótulos negativos observados). Então DRR = 40/50 - 80/100 = 0, portanto, nenhum desvio é indicado.
O intervalo de valores para DRR para rótulos binários, contínuos e de facetas multicategóricas é [-1, \$11].
+ Valores positivos ocorrem quando a proporção entre os negativos previstos (rejeições) em relação aos resultados negativos observados (candidatos não qualificados) para a faceta *d* é maior do que a mesma proporção para a faceta *a*. Esses valores indicam um possível desvio contra a faceta favorecida *a* causado pela ocorrência de relativamente mais falso-negativos na faceta *a*. Quanto maior a diferença nas proporções, mais extremo é o desvio aparente.
+ Valores próximos de zero ocorrem quando a razão entre os negativos previstos (rejeições) e os resultados negativos observados (candidatos não qualificados) para as facetas*a* e *d* têm valores semelhantes, indicando que os rótulos observados para resultados negativos estão sendo previstos com igual precisão pelo modelo.
+ Valores negativos ocorrem quando a proporção entre os negativos previstos (rejeições) e os resultados negativos observados (candidatos não qualificados) para a faceta *a* é maior do que a faceta*d* da proporção. Esses valores indicam um possível desvio contra a faceta desfavorecida *d* causada pela ocorrência de relativamente mais falso-positivos na faceta *d*. Quanto mais negativa for a diferença nas proporções, mais extremo será o desvio aparente.
# Diferença de precisão (AD)
A métrica de diferença de precisão (AD) é a diferença entre a precisão da predição para diferentes facetas. Essa métrica determina se a classificação pelo modelo é mais precisa para uma faceta do que para a outra. A AD indica se uma faceta incorre em uma proporção maior de erros do Tipo I e do Tipo II. Mas ela não consegue diferenciar entre erros do Tipo I e do Tipo II. Por exemplo, o modelo pode ter a mesma precisão para diferentes faixas etárias, mas os erros podem ser principalmente falso-positivos (erros do Tipo I) para um grupo baseado na idade e principalmente falso-negativos (erros do Tipo II) para o outro.
Além disso, se as aprovações de empréstimos forem feitas com muito mais precisão para um grupo demográfico de meia-idade (faceta *a*) do que para outro grupo demográfico baseado na idade (faceta *d*), uma proporção maior de candidatos qualificados no segundo grupo terá seu empréstimo negado (FN) ou uma proporção maior de candidatos não qualificados desse grupo obterão um empréstimo (FP) ou ambos. Isso pode levar à injustiça dentro do grupo para o segundo grupo, mesmo que a proporção de empréstimos concedidos seja quase a mesma para ambos os grupos baseado na idade, o que é indicado por um valor de DPPL próximo de zero.
A fórmula da métrica AD é a diferença entre a precisão da predição para a faceta *a*, ACCa, menos a da faceta *d*, ACCd:
AD = ACCa - ACCd
Em que:
+ ACCa = (TPa \$1 TNa)/(TPa \$1 TNa \$1 FPa \$1 FNa)
+ TPa são os positivos verdadeiros previstos para a faceta *a*
+ TNa são os negativos verdadeiros previstos para a faceta *a*
+ FPa são os falso-positivos previstos para a faceta *a*
+ FNa são os falso-negativos previstos para a faceta *a*
+ ACCd = (TPd \$1 TNd)/(TPd \$1 TNd \$1 FPd \$1 FNd)
+ TPd são os positivos verdadeiros previstos para a faceta *d*
+ TNd são os negativos verdadeiros previstos para a faceta *d*
+ FPd são os falso-positivos previstos para a faceta *d*
+ FNd são os falso-negativos previstos para a faceta *d*
Por exemplo, suponha que um modelo aprove empréstimos para 70 candidatos da faceta *a* de 100 e rejeite os outros 30. 10 não deveriam ter recebido o empréstimo (FPa) e 60 foram aprovados, o que deveria ter sido (TPa). 20 das rejeições deveriam ter sido aprovadas (FNa) e 10 foram rejeitadas corretamente (TNa). A precisão da faceta *a* é a seguinte:
ACCa = (60 \$1 10)/(60 \$1 10 \$1 20 \$1 10) = 0,7
Em seguida, suponha que um modelo aprove empréstimos para 50 candidatos da faceta *d* de 100 e rejeite os outros 50. 10 não deveriam ter recebido o empréstimo (FPa) e 40 foram aprovados, o que deveria ter sido (TPa). 40 das rejeições deveriam ter sido aprovadas (FNa) e 10 foram rejeitadas corretamente (TNa). A precisão da faceta *a* é determinada conforme a seguir:
ACCd = (40 \$1 10)/(40 \$1 10 \$1 40 \$1 10) = 0,5
A diferença de precisão é, portanto, AD = ACCa - ACCd = 0,7 - 0,5 = 0,2. Isso indica que há um desvio em relação à faceta *d*, pois a métrica é positiva.
O intervalo de valores do AD para rótulos binários e de facetas multicategóricas é [-1, \$11].
+ Valores positivos ocorrem quando a precisão da predição para a faceta *a* é maior do do que para a faceta *d*. Isso significa que a faceta *d* sofre mais com alguma combinação de falso-positivos (erros do Tipo I) ou falso-negativos (erros do Tipo II). Isso significa que há um desvio potencial contra a faceta *d* desfavorecida.
+ Valores próximos de zero ocorrem quando a precisão da predição para a faceta *a* é semelhante à da faceta *d*.
+ Valores negativos ocorrem quando a precisão da predição para a faceta *d* é maior do que para a faceta *a* t. Isso significa que a faceta *a* sofre mais com alguma combinação de falso-positivos (erros do Tipo I) ou falso-negativos (erros do Tipo II). Isso significa que há um desvio contra a faceta *a* favorecida.
# Igualdade de tratamento (TE)
A igualdade de tratamento (TE) é a diferença na proporção de falso-negativos para falso-positivos entre as facetas *a* e *d*. A ideia principal dessa métrica é avaliar se, mesmo que a precisão entre os grupos seja a mesma, os erros são mais prejudiciais a um grupo do que a outro? A taxa de erro vem do total de falso-positivos e falso-negativos, mas o detalhamento desses dois pode ser muito diferente pelas facetas. O TE mede se os erros estão compensando de forma semelhante ou diferente em todas as facetas.
A fórmula da igualdade de tratamento:
TE = FNd/FPd - FNa/FPa
Em que:
+ FNd são os falso-negativos previstos para a faceta *d*.
+ FPd são os falso-positivos previstos para a faceta *d*.
+ FNa são os falso-negativos previstos para a faceta *a*.
+ FPa são os falso-positivos previstos para a faceta *a*.
Observe que a métrica se torna ilimitada se FPa ou FPd for zero.
Por exemplo, suponha que haja 100 pessoas pedindo empréstimos da faceta *a* e 50 da faceta *d*. Para a faceta *a*, 8 tiveram um empréstimo negado erroneamente (FNa) e outros 6 foram aprovados erroneamente (FPa). As predições restantes eram verdadeiras, então TPa \$1 TNa = 86. Para a faceta *d*, 5 foram negadas erroneamente (FNd) e 2 foram aprovadas erroneamente (FPd). As predições restantes eram verdadeiras, então TPd \$1 TNd = 43. A proporção de falso-negativos para falso-positivos é igual a 8/6 = 1,33 para a faceta *a* e 5/2 = 2,5 para a faceta *d*. Portanto, TE = 2,5 - 1,33 = 1,167, embora ambas as facetas tenham a mesma precisão:
ACCa = (86)/(86\$1 8 \$1 6) = 0,86
ACCd = (43)/(43 \$1 5 \$1 2) = 0,86
O intervalo de valores para diferenças na rejeição condicional para rótulos binários e de facetas multicategóricas é (-∞, \$1∞). A métrica TE não está definida para rótulos contínuos. A interpretação dessa métrica depende da importância relativa de falso-positivos (erro do tipo I) e dos falso-negativos (erro do tipo II).
+ Valores positivos ocorrem quando a proporção de falso-negativos para falso-positivos da faceta *d* é maior que da faceta *a*.
+ Valores próximos de zero ocorrem quando a proporção de falso-negativos e falso-positivos para a faceta *a* é semelhante à da faceta *d*.
+ Valores negativos ocorrem quando a proporção de falso-negativos para falso-positivos da faceta *d* é menor que da faceta *a*.
**nota**
Uma versão anterior afirmava que a métrica de Igualdade de Tratamento é calculada como FPa / FNa - FPd / FNd em vez de FNd / FPd - FNa / FPa. Embora qualquer uma das versões possa ser usada. Para obter mais informações, consulte [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).
# Disparidade demográfica condicional em rótulos previstos (CDDPL)
A métrica de disparidade demográfica (DDPL) determina se a faceta *d* tem uma proporção maior de rótulos rejeitados previstos do que dos rótulos aceitos previstos. Ele permite uma comparação da diferença na proporção de rejeição prevista e na proporção de aceitação prevista pelas facetas. Essa métrica é exatamente igual à métrica CDD de pré-treinamento, exceto que é calculada com base nos rótulos previstos em vez dos observados. Essa métrica está no intervalo (-1,\$11).
A fórmula para as predições de disparidade demográfica para rótulos da faceta *d* é a seguinte:
DDPLd = n'd(0)/n'(0) - n'd(1)/n'(1) = PdR(y'0) - PdA(y'1)
Em que:
+ n'(0) = n'a(0) \$1 n'd(0) é o número previsto de rótulos rejeitados para as facetas *a* e *d*.
+ n'(1) = n'a(1) \$1 n'd(1) é o número de rótulos aceitos previstos para as facetas *a* e *d*.
+ PdR(y'0) é a proporção de rótulos rejeitados previstos (valor 0) na faceta *d*.
+ PdA(y'1) é a proporção de rótulos aceitos previstos (valor 1) na faceta *d*.
Uma métrica de disparidade demográfica condicional em rótulos previstos (CDDPL) que condiciona o DDPL a atributos que definem um estrato de subgrupos no conjunto de dados é necessária para descartar o paradoxo de Simpson. O reagrupamento pode fornecer insights sobre a causa das aparentes disparidades demográficas nas facetas menos favorecidas. O caso clássico surgiu no caso de admissões em Berkeley, onde os homens foram aceitos com uma taxa geral mais alta do que as mulheres. Mas quando os subgrupos departamentais foram examinados, foi demonstrado que as mulheres tinham taxas de admissão mais altas do que os homens por departamento. A explicação foi que as mulheres se inscreveram em departamentos com taxas de aceitação mais baixas do que os homens. O exame das taxas de aceitação de subgrupos revelou que as mulheres foram realmente aceitas em uma taxa mais alta do que os homens nos departamentos com taxas de aceitação mais baixas.
A métrica CDDPL fornece uma medida única para todas as disparidades encontradas nos subgrupos definidos por um atributo de um conjunto de dados por meio da média deles. É definido como a média ponderada das disparidades demográficas nos rótulos previstos (DDPLi) para cada um dos subgrupos, com cada disparidade de subgrupo ponderada na proporção ao número de observações contidas. A fórmula para a disparidade demográfica condicional nos rótulos previstos é a seguinte:
CDDPL = (1/n)\$1∑ini \$1DDPLi
Em que:
+ ∑ini = n é o número total de observações e ni é o número de observações para cada subgrupo.
+ DDPLi = n'i(0)/n(0) - n'i(1)/n(1) = PiR(y'0) - PiA(y'1) é a disparidade demográfica nos rótulos previstos para o subgrupo.
Portanto, a disparidade demográfica de um subgrupo em rótulos previstos (DDPLi) é a diferença entre a proporção de rótulos rejeitados previstos e a proporção de rótulos aceitos previstos para cada subgrupo.
O intervalo de valores de DDPL para resultados binários, multicategóricos e contínuos é [-1, \$11].
+ \$11: quando não há rótulos de rejeição prevista para a faceta *a* ou subgrupo e nenhuma aceitação prevista na faceta *d* ou subgrupo.
+ Valores positivos indicam que há uma disparidade demográfica nos rótulos previstos, pois a faceta *d* ou subgrupo tem uma proporção maior dos rótulos rejeitados previstos do que dos rótulos aceitos previstos. Quanto maior o valor, maior será a disparidade.
+ Valores próximos de zero indicam que não há disparidade demográfica na média.
+ Valores negativos indicam que há uma disparidade demográfica nos rótulos previstos, pois a faceta *a* ou subgrupo tem uma proporção maior de rótulos rejeitados previstos do que de rótulos aceitos previstos. Quanto menor o valor, maior a disparidade.
+ -1: quando não há lapelas de rejeição previstas para a faceta *d* ou subgrupo e nenhuma aceitação prevista para a faceta *a* ou subgrupo.
# Teste de inversão contrafactual (FT)
O teste de inversão é uma abordagem que analisa cada membro da faceta *d* e avalia se membros semelhantes da faceta *a* têm predições de modelo diferentes. Os membros da faceta *a* são escolhidos para serem vizinhos k mais próximos da observação da faceta *d*. Avaliamos quantos vizinhos mais próximos do grupo oposto recebem uma predição diferente, em que a predição invertida pode ir de positiva para negativa e vice-versa.
A fórmula para o teste de inversão contrafactual é a diferença na cardinalidade de dois conjuntos dividida pelo número de membros da faceta *d*:
FT = (F\$1 - F-)/nd
Em que:
+ F\$1 = é o número de membros desfavorecidos da faceta *d* com um resultado desfavorável cujos vizinhos mais próximos na faceta *a* favorecida receberam um resultado favorável.
+ F- = é o número de membros desfavorecidos da faceta *d* com um resultado favorável cujos vizinhos mais próximos na faceta *a* favorecida receberam um resultado desfavorável.
+ nd é o tamanho da amostra da faceta *d*.
O intervalo de valores para o teste de inversão contrafactual para rótulos de facetas binários e multicategoriais é [-1, \$11]. Para rótulos contínuos, definimos um limite para reduzir os rótulos para binários.
+ Valores positivos ocorrem quando o número de decisões contrafactuais desfavoráveis para a faceta desfavorecida *d* excede as favoráveis.
+ Valores próximos de zero ocorrem quando o número de decisões contrafactuais desfavoráveis e favoráveis do teste de inversão se equilibra.
+ Valores negativos ocorrem quando o número de decisões contrafactuais desfavoráveis do teste de inversão para a faceta desfavorecida *d* é menor do que as favoráveis.
# Entropia generalizada (GE)
O índice de entropia generalizada (GE) mede a desigualdade no benefício `b` do rótulo previsto em comparação com o rótulo observado. Um benefício ocorre quando um falso-positivo é previsto. Um falso-positivo ocorre quando uma observação negativa (y=0) tem uma predição positiva (y'=1). Um benefício também ocorre quando os rótulos observados e previstos são os mesmos, também conhecidos como positivo verdadeiro e negativo verdadeiro. Nenhum benefício ocorre quando um falso-negativo é previsto. Um falso-negativo ocorre quando se prevê que uma observação positiva (y=1) tenha um resultado negativo (y'=0). O benefício `b` é definido da seguinte forma:
```
b = y' - y + 1
```
Usando essa definição, um falso-positivo recebe um benefício `b` de `2`, e um falso-negativo recebe um benefício do `0`. Tanto um positivo verdadeiro quanto um negativo verdadeiro recebem o benefício do `1`.
A métrica GE é calculada seguindo o [Índice de Entropia Generalizada](https://en.wikipedia.org/wiki/Generalized_entropy_index) (GE) com o peso `alpha` definido como `2`. Esse peso controla a sensibilidade a diferentes valores de benefícios. Um `alpha` menor significa uma maior sensibilidade a valores menores.
![\[Equação que define o índice de entropia generalizado com o parâmetro alfa definido como 2.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify-post-training-bias-metric-ge.png)
As seguintes variáveis usadas para calcular a GE são definidas da seguinte forma:
+ bi é o benefício recebido pelo ponto de dados `ith`.
+ b' é a média de todos os benefícios.
A GE pode variar de 0 a 0,5, onde valores de zero indicam que não há desigualdade nos benefícios em todos os pontos de dados. Isso ocorre quando todas as entradas são previstas corretamente ou quando todas as predições são falso-positivos. A GE é indefinida quando todas as predições são falso-negativos.
**nota**
A métrica GE não depende de um valor de faceta ser favorecido ou desfavorecido.
# Explicabilidade do modelo
O Amazon SageMaker Clarify fornece ferramentas para ajudar a explicar como os modelos de aprendizado de máquina (ML) fazem previsões. Essas ferramentas podem ajudar modeladores e desenvolvedores de ML e outras partes interessadas internas a entender as características do modelo como um todo antes da implantação e a depurar as predições fornecidas pelo modelo após a implantação.
+ Para obter explicações sobre seus conjuntos de dados e modelos, consulte [Imparcialidade, explicabilidade do modelo e detecção de viés com o Clarify SageMaker](clarify-configure-processing-jobs.md).
+ Para obter explicações em tempo real a partir de um endpoint de SageMaker IA, consulte. [Explicabilidade on-line com Clarify SageMaker](clarify-online-explainability.md)
A transparência sobre como os modelos de ML chegam às suas predições também é fundamental para consumidores e reguladores. Eles precisam confiar nas previsões do modelo se quiserem aceitar as decisões baseadas nelas. SageMaker O Clarify usa uma abordagem de atribuição de recursos independente do modelo. Você pode usar isso para entender por que um modelo fez uma predição após o treinamento e para fornecer uma explicação por instância durante a inferência. A implementação inclui uma implementação escalável e eficiente do [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf). Isso se baseia no conceito de um valor de Shapley, do campo da teoria dos jogos cooperativos, que atribui a cada atributo um valor de importância para uma predição específica.
O Clarify produz gráficos de dependência parcial (PDPs) que mostram o efeito marginal que as características têm no resultado previsto de um modelo de aprendizado de máquina. A dependência parcial ajuda a explicar a resposta do alvo, dado um conjunto de atributos de entrada. Também oferece apoio à explicabilidade da visão computacional (CV) e do processamento de linguagem natural (PLN) usando o mesmo algoritmo de valores de Shapley (SHAP) utilizado para explicações de dados tabulares.
Qual é a função de uma explicação no contexto do machine learning? Uma explicação pode ser considerada a resposta a uma *pergunta por que*, que ajuda os humanos a entender a causa de uma predição. No contexto de um modelo de ML, talvez você esteja interessado em responder perguntas como:
+ Por que o modelo previu um resultado negativo, como a rejeição de um empréstimo para um determinado candidato?
+ Como o modelo faz predições?
+ Por que o modelo fez uma predição incorreta?
+ Quais atributos têm a maior influência no comportamento do modelo?
Você pode usar essas explicações para auditar e atender aos requisitos regulatórios, estabelecer confiança no modelo, apoiar a tomada de decisões humanas e depurar e melhorar o desempenho do modelo.
A necessidade de satisfazer as demandas de compreensão humana sobre a natureza e os resultados da inferência de ML é fundamental para o tipo de explicação necessária. Pesquisas de disciplinas de filosofia e ciências cognitivas mostraram que as pessoas se preocupam especialmente com explicações contrastivas ou explicações do tipo por que um evento X aconteceu em vez de algum outro evento Y que não ocorreu. Aqui, X pode ser um evento inesperado ou surpreendente que aconteceu e Y corresponde a uma expectativa baseado no seu modelo mental existente, conhecido como *linha de base*. Observe que, para o mesmo evento X, pessoas diferentes podem buscar explicações diferentes, dependendo de seu ponto de vista ou modelo mental Y. No contexto da inteligência artificial explicável, você pode pensar em X como o exemplo que está sendo explicado e em Y como uma linha de base que normalmente é escolhida para representar um exemplo não informativo ou médio no conjunto de dados. Às vezes, por exemplo, no caso da modelagem de imagens em ML, a linha de base pode estar implícita, enquanto uma imagem cujos pixels são todos da mesma cor pode servir como linha de base.
## Cadernos de exemplo
O Amazon SageMaker Clarify fornece o seguinte exemplo de caderno para explicabilidade do modelo:
+ [Amazon SageMaker Clarify Processing](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/index.html#sagemaker-clarify-processing) — Use o SageMaker Clarify para criar um trabalho de processamento para detectar viés e explicar as previsões do modelo com atribuições de recursos. Os exemplos incluem usar formatos de dados CSV e Linhas JSON, trazer seu próprio contêiner e executar trabalhos de processamento com o Spark.
+ [Explicando a classificação de imagens com SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) o SageMaker Clarify — O Clarify fornece informações sobre como seus modelos de visão computacional classificam as imagens.
+ [Explicando os modelos de detecção de objetos com SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) o SageMaker Clarify — O Clarify fornece informações sobre como seus modelos de visão computacional detectam objetos.
Este notebook foi verificado para ser executado somente no Amazon SageMaker Studio. Se você precisar de instruções sobre como abrir um notebook no Amazon SageMaker Studio, consulte[Crie ou abra um notebook Amazon SageMaker Studio Classic](notebooks-create-open.md). Caso seja solicitado que você escolha um kernel, escolha **Python 3 (Ciência de dados)**.
**Topics**
+ [Cadernos de exemplo](#clarify-model-explainability-sample-notebooks)
+ [Atributos de atributos que usam valores de Shapley](clarify-shapley-values.md)
+ [Valores assimétricos de Shapley](clarify-feature-attribute-shap-asymm.md)
+ [Linhas de base do SHAP para explicabilidade](clarify-feature-attribute-shap-baselines.md)
# Atributos de atributos que usam valores de Shapley
SageMaker O Clarify fornece atribuições de recursos com base no conceito de valor de [Shapley](https://en.wikipedia.org/wiki/Shapley_value). Você pode usar os valores de Shapley para determinar a contribuição de cada atributo para as predições de modelo. Essas atribuições podem ser fornecidas para predições específicas e em nível global para o modelo como um todo. Por exemplo, se você usou um modelo de ML para admissões em faculdades, as explicações poderiam ajudar a determinar se a pontuação do GPA ou do SAT foi o atributo mais responsável pelas predições de modelo e, então, você pode determinar a responsabilidade de cada atributo por determinar uma decisão de admissão sobre um determinado estudante.
SageMaker A Clarify pegou o conceito dos valores de Shapley da teoria dos jogos e o implantou em um contexto de aprendizado de máquina. O valor de Shapley fornece uma maneira de quantificar a contribuição de cada jogador para um jogo e, portanto, os meios de distribuir o ganho total gerado por um jogo para seus jogadores baseado em suas contribuições. Nesse contexto de aprendizado de máquina, o SageMaker Clarify trata a previsão do modelo em uma determinada instância como o *jogo* e os recursos incluídos no modelo como os *jogadores*. Para uma primeira aproximação, você pode ficar tentado a determinar a contribuição ou o efeito marginal de cada atributo quantificando o resultado do *descarte* desse atributo do modelo ou o *descarte* de todos os outros atributos do modelo. No entanto, essa abordagem não leva em conta que os atributos incluídos em um modelo geralmente não são independentes uns dos outros. Por exemplo, se dois atributos estiverem altamente correlacionados, o descarte de qualquer um dos atributos pode não alterar significativamente a predição de modelo.
Para lidar com essas possíveis dependências, o valor de Shapley exige que o resultado de cada combinação (ou coalizão) possível de atributos seja considerado para determinar a importância de cada atributo. Dados os atributos de *d*, existem 2d dessas combinações de atributos possíveis, cada uma correspondendo a um modelo potencial. Para determinar a atribuição de um determinado atributo *f*, considere a contribuição marginal de incluir *f* em todas as combinações de atributos (e modelos associados) que não contêm *f* e calcule a média. Pode-se mostrar que o valor de Shapley é a maneira única de atribuir a contribuição ou importância de cada atributo que satisfaz certos atributos desejáveis. Em particular, a soma dos valores de Shapley de cada atributo corresponde à diferença entre as predições de modelo e um modelo fictício sem atributos. No entanto, mesmo para valores razoáveis de *d*, digamos 50 atributos, é computacionalmente proibitivo e impraticável treinar 2d modelos possíveis. Como resultado, o SageMaker Clarify precisa fazer uso de várias técnicas de aproximação. Para isso, a SageMaker Clarify usa Shapley Additive Explanations (SHAP), que incorpora essas aproximações e desenvolveu uma implementação escalável e eficiente do algoritmo Kernel SHAP por meio de otimizações adicionais.
Para obter informações adicionais sobre os valores de Shapley, consulte [A Unified Approach to Interpreting Model Predictions](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) (Uma abordagem unificada para interpretar as predições de modelo).
# Valores assimétricos de Shapley
A solução de explicação do modelo de previsão de séries temporais SageMaker Clarify é um método de atribuição de recursos baseado na [teoria dos jogos cooperativos](https://en.wikipedia.org/wiki/Cooperative_game_theory), semelhante em espírito ao SHAP. Especificamente, o Clarify usa [valores de grupos de ordem aleatória](http://www.library.fa.ru/files/Roth2.pdf#page=121), também conhecidos como [valores assimétricos de Shapley](https://proceedings.neurips.cc/paper/2020/file/0d770c496aa3da6d2c3f2bd19e7b9d6b-Paper.pdf) em machine learning e explicabilidade.
## Contexto
O objetivo é calcular as atribuições dos atributos de entrada de um determinado modelo de previsão *f*. O modelo de previsão recebe as seguintes entradas:
+ Série temporal passada *(TS de destino)*. Por exemplo, pode ser os passageiros de trem diários do passado na rota Paris-Berlim, indicada por *xt*.
+ (Opcional) Uma série temporal covariável. Por exemplo, podem ser festividades e dados meteorológicos, indicados por *zt* ∈ RS. Quando usada, a covariável TS pode estar disponível apenas para intervalos de tempos passados ou também para os futuros (incluídos no calendário festivo).
+ (Opcional) Covariáveis estáticas, como qualidade de serviço (como 1ª ou 2ª classe), indicadas por *u* ∈ RE.
Covariáveis estáticas, covariáveis dinâmicas ou ambas podem ser omitidas, dependendo do cenário de aplicação específico. Dado um horizonte de predição K ≥ 0 (por exemplo, K = 30 dias), a predição de modelo pode ser caracterizada pela fórmula: *f(x[1:T], z[1:T\$1K], u) = x[T\$11:T \$1K\$11]*.
O diagrama a seguir mostra uma estrutura de dependência para um modelo de previsão típico. A predição no tempo *t\$11* depende dos três tipos de entradas mencionados anteriormente.
![\[Estrutura de dependência para um modelo de previsão típico.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/clarify-forecast-dependency.png)
## Método
As explicações são calculadas consultando o modelo de série temporal *f* em uma série de pontos derivados da entrada original. Seguindo os constructos teóricas dos jogos, o Clarify calcula a média das diferenças nas predições conduzidas pela ofuscação (ou seja, pela definição de um valor básico) de partes das entradas de forma iterativa. A estrutura temporal pode ser navegada em ordem cronológica, anticronológica ou ambas. As explicações cronológicas são criadas adicionando informações iterativamente do primeiro intervalo de tempo, enquanto anticronológicas a partir do último. O último modo pode ser mais apropriado na presença de desvio de recência, como na previsão dos preços de ações. Uma propriedade importante das explicações computadas é que elas somam a saída do modelo original se o modelo fornecer saídas determinísticas.
## Atribuições resultantes
As atribuições resultantes são pontuações que marcam contribuições individuais de intervalos de tempo específicos ou atributos de entrada para a previsão final em cada intervalo de tempo previsto. O Clarify oferece as duas granularidades a seguir para explicações:
+ As explicações temporais são econômicas e fornecem informações apenas sobre intervalos de tempo específicos, como o quanto as informações do 19º dia no passado contribuíram para a previsão do 1.º dia no futuro. Essas atribuições não explicam as covariáveis estáticas individualmente e as explicações agregadas das séries temporais covariáveis e de destino. As atribuições são uma matriz *A* em que cada *Atk* é a atribuição do intervalo de tempo *t* para a previsão do intervalo de tempo *T\$1k*. Observe que, se o modelo aceitar covariáveis futuras, *t* pode ser maior que *T*.
+ Explicações refinadas são mais intensivas em termos computacionais e fornecem uma análise completa de todas as atribuições das variáveis de entrada.
**nota**
Explicações refinadas são compatíveis com apenas a ordem cronológica.
As atribuições resultantes são um trio composto pelo seguinte:
+ Matriz *Ax* ∈ RT×K relacionada à série temporal de entrada, em que *Atkx* é a atribuição de *xt* para a previsão de *T\$1k*
+ Tensor *Au* ∈ RE×K relacionado à série temporal de covariável, em que *Atskz* é a atribuição de *zts* (ou seja, a sétima covariável TS) para a previsão de *T\$1k*
+ Matriz *Au* ∈ RE×K relacionada às covariáveis estáticas, em que *Aeku* é a atribuição de *ue* (a oitava covariável estática) para a previsão de *T\$1k*
Independentemente da granularidade, a explicação também contém um vetor de deslocamento *B* ∈ *RK* que representa o “comportamento básico” do modelo quando todos os dados são ofuscados.
# Linhas de base do SHAP para explicabilidade
As explicações são tipicamente contrastivas (ou seja, elas explicam os desvios de uma linha de base). Como resultado, para a mesma predição de modelo, você pode esperar obter explicações diferentes com relação a diferentes linhas de base. Portanto, sua escolha de uma linha de base é crucial. Em um contexto de ML, a linha de base corresponde a uma instância hipotética que pode ser *não informativa* ou *informativa*. Durante o cálculo dos valores de Shapley, o SageMaker Clarify gera várias novas instâncias entre a linha de base e a instância especificada, nas quais a ausência de um recurso é modelada definindo o valor do recurso como aquele da linha de base e a presença de um recurso é modelada definindo o valor do recurso como aquele da instância específica. Assim, a ausência de todos os atributos corresponde à linha de base e a presença de todos os atributos corresponde à instância dada.
Como você pode escolher boas linhas de base? Frequentemente, é desejável selecionar uma linha de base com conteúdo de informação muito baixo. Por exemplo, você pode criar uma instância média a partir do conjunto de dados de treinamento usando a mediana ou a média para atributos numéricos e o modo para atributos categóricos. Para o exemplo de admissões em faculdades, talvez você esteja interessado em explicar por que um determinado candidato foi aceito em comparação com as aceitações das linhas de base baseado em um candidato médio. Se não for fornecida, uma linha de base é calculada automaticamente pelo SageMaker Clarify usando K-means ou K-protótipos no conjunto de dados de entrada.
Você também pode optar por gerar explicações com relação às linhas de base informativas. Para o cenário de admissão em faculdades, talvez você queira explicar por que um determinado candidato foi rejeitado em comparação com outros candidatos de origens demográficas semelhantes. Nesse caso, você pode escolher uma linha de base que represente os candidatos de interesse, ou seja, aqueles com antecedentes demográficos semelhantes. Assim, você pode usar linhas de base informativas para concentrar a análise nos aspectos específicos da predição de um modelo específico. Você pode isolar os atributos para avaliação ao definir atributos demográficos e outros atributos sobre os quais você não pode agir com o mesmo valor de uma determinada instância.