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á. # Explicabilidade on-line com Clarify SageMaker Este guia mostra como configurar a explicabilidade on-line com SageMaker o Clarify. Com os endpoints de [inferência em tempo real](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html) de SageMaker IA, você pode analisar a explicabilidade em tempo real, continuamente. A função de explicabilidade on-line se encaixa na parte **Deploy to production** do fluxo de trabalho do [Amazon SageMaker AI Machine Learning](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-mlconcepts.html). ## Como funciona a explicabilidade on-line do Clarify O gráfico a seguir mostra a arquitetura de SageMaker IA para hospedar um endpoint que atende a solicitações de explicabilidade. Ele descreve as interações entre um endpoint, o contêiner do modelo e o explicador do SageMaker Clarify. ![\[SageMaker Arquitetura de IA mostrando a hospedagem de um endpoint que atende a solicitações de explicabilidade sob demanda.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/DeveloperGuideArchitecture.png) Veja como funciona a explicabilidade on-line do Clarify. O aplicativo envia uma `InvokeEndpoint` solicitação no estilo REST para o SageMaker AI Runtime Service. O serviço encaminha essa solicitação para um endpoint de SageMaker IA para obter previsões e explicações. Em seguida, o serviço recebe a resposta do endpoint. Por fim, o serviço envia a resposta de volta para a aplicação. Para aumentar a disponibilidade do endpoint, a SageMaker IA tenta distribuir automaticamente as instâncias do endpoint em várias zonas de disponibilidade, de acordo com a contagem de instâncias na configuração do endpoint. Em uma instância de endpoint, após uma nova solicitação de explicabilidade, o explicador do SageMaker Clarify chama o contêiner do modelo para fazer previsões. Em seguida, ele calcula e retorna as atribuições do atributo. Aqui estão as quatro etapas para criar um endpoint que usa a explicabilidade on-line do SageMaker Clarify: 1. [Verifique se seu modelo de SageMaker IA pré-treinado é compatível com a explicabilidade on-line seguindo as etapas de pré-verificação.](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html) 1. [Crie uma configuração de endpoint com a configuração](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html) SageMaker explicativa do Clarify usando a API. `CreateEndpointConfig` 1. [Crie um endpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) e forneça a configuração do endpoint para a SageMaker IA usando a `CreateEndpoint` API. O serviço inicia a instância de cálculo de ML e implanta o modelo conforme especificado na configuração. 1. [Invoque o endpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html): depois que o endpoint estiver em serviço, chame a API SageMaker AI Runtime `InvokeEndpoint` para enviar solicitações ao endpoint. O endpoint então retorna explicações e predições. # Verifique previamente o recipiente modelo Esta seção mostra como verificar previamente a compatibilidade das entradas e saídas do contêiner do modelo antes de configurar um endpoint. O SageMaker explicador do Clarify é **independente do modelo**, mas tem requisitos para entrada e saída do contêiner do modelo. **nota** Você pode aumentar a eficiência configurando seu contêiner para oferecer compatibilidade com solicitações em lote, que oferecem apoio a dois ou mais registros em uma única solicitação. Por exemplo, um único registro é uma única linha de dados CSV ou uma única linha de dados de linhas JSON. SageMaker O Clarify tentará enviar primeiro um pequeno lote de registros para o contêiner do modelo, antes de retornar às solicitações de registro único. ## Entrada de contêiner de modelo ------ #### [ CSV ] O contêiner do modelo é compatível com entrada em CSV com o tipo MIME: `text/csv`. A tabela a seguir mostra exemplos de entradas compatíveis com o SageMaker Clarify. | Entrada de contêiner do modelo (representação de string) | Comentários | | --- | --- | | '1,2,3,4' | Registro único que usa 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 que contém um atributo de texto e um atributo numérico. | | '"Este é um bom produto",5\$1n"Experiência de compra ruim",1' | Dois registros. | ------ #### [ JSON Lines ] SageMaker O AI também suporta entrada no [formato denso de linhas JSON](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines) com o tipo MIME:`application/jsonlines`, conforme mostrado na tabela a seguir. | Entrada de contêiner de modelo | Comentários | | --- | --- | | '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | Registro único; uma lista de recursos pode ser extraída por JMESPath expressão`data.features`. | | '\$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; uma lista de recursos pode ser extraída por JMESPath expressão`features`. | | '\$1"features":["Este é um bom produto",5]\$1\$1n\$1"features":["Experiência de compra ruim",1]\$1' | Dois registros. | ------ ## Entrada de contêiner de modelo A saída do contêiner do modelo também deve estar no formato denso CSV ou JSON Lines. Além disso, o contêiner do modelo deve incluir as probabilidades dos registros de entrada, que o SageMaker Clarify usa para calcular as atribuições de recursos. Os exemplos de dados a seguir são para saídas de contêiner de modelo no **formato CSV**. ------ #### [ Probability only ] Para problemas de regressão e classificação binária, o contêiner do modelo gera um único valor de probabilidade (pontuação) do rótulo previsto. Essas probabilidades podem ser extraídas usando o índice da coluna 0. Para problemas de várias classes, o contêiner do modelo gera uma lista de probabilidades (pontuações). Para problemas de várias classes, se nenhum índice for fornecido, todos os valores serão extraídos. | Entrada de contêiner de modelo | Saída do contêiner do modelo (representação de string) | | --- | --- | | Registro único | '0.6' | | Dois registros (resultados em uma linha) | '0.6,0.3' | | Dois registros (resultados em duas linhas) | '0.6\$1n0.3' | | 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' | ------ #### [ Predicted label and probabilities ] O contêiner do modelo gera o rótulo previsto seguido por sua probabilidade no **formato CSV**. As probabilidades podem ser extraídas usando o índice `1`. | Entrada de contêiner de modelo | Entrada de contêiner de modelo | | --- | --- | | Registro único | '1,0.6' | | Dois registros | '1,0.6\$1n0,0.3' | ------ #### [ Predicted labels header and probabilities ] Um contêiner de modelo multiclasse treinado pelo Autopilot pode ser configurado para gerar **a representação em sequência** da lista de rótulos e probabilidades previstos no formato **CSV**. No exemplo a seguir, as probabilidades podem ser extraídas por índice `1`. Os cabeçalhos dos rótulos podem ser extraídos pelo índice `1` e os cabeçalhos dos rótulos podem ser extraídos usando o índice `0`. | Entrada de contêiner de modelo | Entrada de contêiner de modelo | | --- | --- | | Registro único | '"[\$1'gato\$1',\$1'cachorro\$1',\$1'peixe\$1']","[0.1,0.6,0.3]"' | | Dois registros | '"[\$1'gato\$1',\$1'cachorro\$1',\$1'peixe\$1']", "[0.1,0.6,0.3]"\$1n"[\$1'gato\$1',\$1'cachorro\$1',\$1'peixe\$1']","[0.2,0.5,0.3]"' | ------ Os exemplos de dados a seguir são para saídas de contêineres de modelos no formato **JSON Lines**. ------ #### [ Probability only ] Neste exemplo, o contêiner do modelo gera a probabilidade que pode ser extraída pela expressão [https://jmespath.org/](https://jmespath.org/) no formato `score` **JSON Lines**. | Entrada de contêiner de modelo | Entrada de contêiner de modelo | | --- | --- | | Registro único | '\$1"score":0.6\$1' | | Dois registros | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' | ------ #### [ Predicted label and probabilities ] Neste exemplo, um contêiner de modelo multiclasse gera uma lista de cabeçalhos de rótulos junto com uma lista de probabilidades no formato **JSON Lines.** As probabilidades podem ser extraídas pela `JMESPath` expressão `probability` e os cabeçalhos dos rótulos podem ser extraídos pela expressão `JMESPath` `predicted labels`. | Entrada de contêiner de modelo | Entrada de contêiner de modelo | | --- | --- | | Registro único | '\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.1,0.6,0.3]\$1' | | Dois registros | '\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.2,0.5,0.3]\$1' | ------ #### [ Predicted labels header and probabilities ] Neste exemplo, um contêiner de modelo multiclasse gera uma lista de cabeçalhos e probabilidades de rótulos no formato **JSON Lines**. As probabilidades podem ser extraídas pela `JMESPath` expressão `probability` e os cabeçalhos dos rótulos podem ser extraídos pela expressão `JMESPath` `predicted labels`. | Entrada de contêiner de modelo | Entrada de contêiner de modelo | | --- | --- | | Registro único | '\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.1,0.6,0.3]\$1' | | Dois registros | '\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["gato","cachorro","peixe"],"probabilities":[0.2,0.5,0.3]\$1' | ------ ## Validação de contêiner 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 (entradas do contêiner do modelo) e as respostas (saídas do contêiner do modelo) para garantir que ambas estejam em conformidade com os requisitos na seção **Entrada do contêiner do modelo** e na seção **Saída do contêiner do modelo**. 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 Classic e SageMaker Notebook. Se você precisar 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 [v2 passa parâmetros binários como strings codificadas em base64 padrão.](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam) Os exemplos a seguir usam AWS CLI v1: ------ #### [ Request and response in CSV format ] + 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 ``` Saída: `0.6` + A solicitação consiste em dois registros, e a resposta inclui suas probabilidades, e o modelo separa as probabilidades por uma vírgula. A `$'content'` expressão no `--body` diz ao comando para interpretar `\n` o conteúdo como uma quebra de linha. ``` 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 ``` Saída: `0.6,0.3` + A solicitação consiste em dois registros, a resposta inclui suas probabilidades e o modelo separa as probabilidades com 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 ``` Saída: `0.6` `0.3` + A solicitação consiste em um único registro e a resposta são valores de probabilidade (modelo multiclasse, 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 ``` Saída: `0.1,0.6,0.3` + A solicitação consiste em dois registros e a resposta inclui seus valores de probabilidade (modelo multiclasse, 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 ``` Saída: `0.1,0.6,0.3` `0.2,0.5,0.3` + 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 ``` Saída: `1,0.6` `0,0.3` + A solicitação consiste em dois registros e a resposta inclui cabeçalhos e probabilidades dos rótulos. ``` 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 ``` Saída: `"['cat','dog','fish']","[0.1,0.6,0.3]"` `"['cat','dog','fish']","[0.2,0.5,0.3]"` ------ #### [ Request and response in JSON Lines format ] + 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 ``` Saída: `{"score":0.6}` + 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 ``` Saída: `{"predicted_label":1,"probability":0.6}` `{"predicted_label":0,"probability":0.3}` + A solicitação contém dois registros e a resposta inclui cabeçalhos e probabilidades dos rótulos. ``` 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 ``` Saída: `{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}` `{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}` ------ #### [ Request and response in different formats ] + 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 ``` Saída: `{"probability":0.6}` `{"probability":0.3}` + 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 ``` Saída: `0.6` `0.3` ------ Depois que as validações forem concluídas, [exclua](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html) o endpoint de teste. # Configurar e criar um endpoint Crie uma nova configuração de endpoint para se adequar ao seu modelo e use essa configuração para criar o endpoint. Você pode usar o contêiner de modelo validado na [etapa de pré-verificação](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html) para criar um endpoint e ativar o recurso de explicabilidade on-line do SageMaker Clarify. Use o `sagemaker_client` objeto para criar um endpoint usando a [CreateEndpointConfig](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateEndpointConfig.html)API. Defina o membro `ClarifyExplainerConfig` dentro do `ExplainerConfig` parâmetro da seguinte forma: ``` sagemaker_client.create_endpoint_config( EndpointConfigName='name-of-your-endpoint-config', ExplainerConfig={ 'ClarifyExplainerConfig': { 'EnableExplanations': '`true`', 'InferenceConfig': { ... }, 'ShapConfig': { ... } }, }, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': 'name-of-your-model', 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }] ... ) sagemaker_client.create_endpoint( EndpointName='name-of-your-endpoint', EndpointConfigName='name-of-your-endpoint-config' ) ``` A primeira chamada para o objeto `sagemaker_client` cria uma nova configuração de endpoint com o atributo de explicabilidade ativado. A segunda chamada usa a configuração do endpoint para iniciar o endpoint. **nota** Você também pode hospedar vários modelos em um contêiner atrás de um [endpoint multimodelo de inferência em tempo real de SageMaker IA](https://docs.aws.amazon.com/sagemaker/latest/dg/multi-model-endpoints.html) e configurar a explicabilidade on-line com o Clarify. SageMaker # A expressão `EnableExplanations` O `EnableExplanations` parâmetro é uma string de expressão booleana [https://jmespath.org/](https://jmespath.org/). Ele é avaliado para **cada registro** na solicitação de explicabilidade. Se esse parâmetro for avaliado como **verdadeiro**, o registro será explicado. Se esse parâmetro for avaliado **como falso**, as explicações não serão geradas. SageMaker O Clarify desserializa a saída do contêiner do modelo para cada registro em uma estrutura de dados compatível com JSON e, em seguida, usa o `EnableExplanations` parâmetro para avaliar os dados. **Observações** Há duas opções para registros, dependendo do formato da saída do contêiner do modelo. Se a saída do contêiner do modelo estiver no formato CSV, um registro será carregado como uma matriz JSON. Se a saída do contêiner do modelo estiver no formato JSON Lines, um registro será carregado como um objeto JSON. O `EnableExplanations` parâmetro é uma JMESPath expressão que pode ser passada durante as `CreateEndpointConfig` operações `InvokeEndpoint` ou. Se a JMESPath expressão que você forneceu não for válida, a criação do endpoint falhará. Se a expressão for válida, mas o resultado da avaliação da expressão for inesperado, o endpoint será criado com sucesso, mas um erro será gerado quando o endpoint for invocado. Teste sua expressão `EnableExplanations` usando a API `InvokeEndpoint` e, em seguida, aplique-a à configuração do endpoint. A seguir estão alguns exemplos de expressão `EnableExplanations` válida. Nos exemplos, uma JMESPath expressão inclui um literal usando caracteres de crase. Por exemplo, ``true`` significa verdadeiro. | Expressão (representação de string) | Saída do contêiner do modelo (representação de string) | Resultado da avaliação (booleano) | Significado | | --- | --- | --- | --- | | '`true`' | (N/D) | Verdadeiro | Ative a explicabilidade on-line incondicionalmente. | | '`false`' | (N/D) | Falso | Desative a explicabilidade on-line incondicionalmente. | | '[1]>`0.5`' | '1,0.6' | Verdadeiro | Para cada registro, o contêiner do modelo gera seu rótulo e probabilidade previstos. Explica um registro se sua probabilidade (no índice 1) for maior que 0,5. | | 'probability>`0.5`' | '\$1"predicted\$1label":1,"probability":0.6\$1' | Verdadeiro | Para cada registro, o contêiner do modelo gera dados JSON. Explique um registro se sua probabilidade for maior que 0,5. | | '\$1contains(probabilities[:-1], max(probabilities))' | '\$1"probabilities": [0.4, 0.1, 0.4], "labels":["gato","cachorro","peixe"]\$1' | Falso | Para um modelo multiclasse: explica um registro se seu rótulo previsto (a classe que tem o valor máximo de probabilidade) for a última classe. Literalmente, a expressão significa que o valor máximo da probabilidade não está na lista de probabilidades, excluindo a última. | # Conjuntos de dados sintéticos SageMaker O Clarify usa o algoritmo Kernel SHAP. Com base em um registro (também chamado de amostra ou instância) e na configuração SHAP, o explicador primeiro gera um conjunto de dados sintético. SageMaker Em seguida, o Clarify consulta o contêiner do modelo para obter as previsões do conjunto de dados e, em seguida, computa e retorna as atribuições do recurso. O tamanho do conjunto de dados sintéticos afeta o runtime do explicador Clarify. Conjuntos de dados sintéticos maiores levam mais tempo para obter as predições de modelo do que conjuntos menores. O tamanho do conjunto de dados sintéticos é determinado pela seguinte fórmula: ``` Synthetic dataset size = SHAP baseline size * n_samples ``` O tamanho da linha de base do SHAP é o número de registros nos dados da linha de base do SHAP. Essas informações são retiradas do `ShapBaselineConfig`. O tamanho de `n_samples` é definido pelo parâmetro `NumberOfSamples` na configuração do explicador e pelo número de atributos. Se o número de atributos for `n_features`, então `n_samples` é o seguinte: ``` n_samples = MIN(NumberOfSamples, 2^n_features - 2) ``` O seguinte mostra `n_samples` se não `NumberOfSamples` é fornecido: ``` n_samples = MIN(2*n_features + 2^11, 2^n_features - 2) ``` Por exemplo, um registro tabular com 10 atributos tem um tamanho de linha de base SHAP de 1. Se não `NumberOfSamples` for fornecido, o conjunto de dados sintético contém 1.022 registros. Se o registro tiver 20 atributos, o conjunto de dados sintético conterá 2.088 registros. Para problemas de PNL, `n_features` é igual ao número de atributos não textuais mais o número de unidades de texto. **nota** A API `InvokeEndpoint` tem um limite de tempo limite de solicitação. Se o conjunto de dados sintéticos for muito grande, o explicador pode não conseguir concluir o cálculo dentro desse limite. Se necessário, use as informações anteriores para entender e reduzir o tamanho da linha de base do SHAP e `NumberOfSamples`. Se o contêiner do modelo estiver configurado para lidar com solicitações em lote, você também poderá ajustar o valor de `MaxRecordCount`. # Invocar o endpoint Depois que o endpoint estiver em execução, use a [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)API SageMaker AI Runtime no serviço SageMaker AI Runtime para enviar solicitações ou invocar o endpoint. Em resposta, as solicitações são tratadas como solicitações de explicabilidade pelo explicador do SageMaker Clarify. **nota** Para chamar um endpoint, escolha uma das seguintes opções: Para obter instruções sobre como usar o Boto3 ou AWS CLI para invocar um endpoint, consulte. [Invocar modelos para inferência em tempo real](realtime-endpoints-test-endpoints.md) [Para usar o SageMaker SDK para Python para invocar um endpoint, consulte a API Predictor.](https://sagemaker.readthedocs.io/en/stable/api/inference/predictors.html) ## Solicitação A API `InvokeEndpoint` tem um parâmetro opcional `EnableExplanations`, que é mapeado para o cabeçalho `X-Amzn-SageMaker-Enable-Explanations` HTTP. Se esse parâmetro for fornecido, ele substituirá o parâmetro `EnableExplanations` do `ClarifyExplainerConfig`. **nota** Os parâmetros `ContentType` e `Accept` da API `InvokeEndpoint` são necessários. Os formatos compatíveis incluem o tipo MIME `text/csv` e `application/jsonlines`. Use o `sagemaker_runtime_client` para enviar uma solicitação ao endpoint, da seguinte forma: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName='name-of-your-endpoint', EnableExplanations='`true`', ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', # single record (of four numerical features) ) ``` Para endpoints multimodelo, passe um parâmetro adicional `TargetModel` na solicitação do exemplo anterior para especificar a qual modelo direcionar no endpoint. O endpoint multimodelo carrega dinamicamente os modelos de destino conforme necessário. Para obter mais informações sobre endpoints multimodelo, consulte [Endpoints multimodelo](multi-model-endpoints.md). Consulte o [caderno de amostra SageMaker Clarify Online Explicability on Multimodel Endpoint](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular_multi_model_endpoint/multi_model_xgboost_with_online_explainability.ipynb) para obter um exemplo de como configurar e invocar vários modelos de destino a partir de um único endpoint. ## Resposta Se o endpoint for criado com `ExplainerConfig`, um novo esquema de resposta será usado. Esse novo esquema é diferente e não é compatível com um endpoint que não tem o parâmetro fornecido `ExplainerConfig`. O tipo MIME da resposta é `application/json`, e a carga útil da resposta pode ser decodificada de bytes UTF-8 para um objeto JSON. Veja a seguir que os membros desse objeto JSON são os seguintes: + `version`: a versão do esquema de resposta em formato de string. Por exemplo, .`1.0` + `predictions`: as predições que a solicitação faz são as seguintes: + `content_type`: o tipo MIME das predições, referindo-se à `ContentType` da resposta do contêiner do modelo. + `data`: a sequência de dados de predições fornecida como carga útil da resposta do contêiner do modelo para a solicitação. + `label_headers`: os cabeçalhos do rótulo do parâmetro `LabelHeaders`. Isso é fornecido na configuração do explicador ou na saída do contêiner do modelo. + `explanations`: as explicações fornecidas na carga útil da solicitação. Se nenhum registro for explicado, esse membro retornará o objeto vazio `{}`. + + `kernel_shap`: uma chave que se refere a uma matriz de explicações do Kernel SHAP para cada registro na solicitação. Se um registro não for explicado, a explicação correspondente será `null`. O elemento `kernel_shap` tem os seguintes membros: + `feature_header`: o nome do cabeçalho dos atributos fornecidos pelo parâmetro `FeatureHeaders` na configuração do explicador `ExplainerConfig`. + `feature_type`: o tipo de atributo inferido pelo explicador ou fornecido no parâmetro `FeatureTypes` no `ExplainerConfig`. Esse elemento só está disponível para problemas de explicabilidade da PNL. + `attributions`: uma matriz de objetos de atribuição. Os atributos de texto podem ter vários objetos de atribuição, cada um para uma unidade. O objeto de atribuição tem os seguintes membros: + `attribution`: uma lista de valores de probabilidade, fornecida para cada classe. + `description`: a descrição das unidades de texto, disponível somente para problemas de explicabilidade da PNL. + `partial_text`: a parte do texto explicada pelo explicador. + `start_idx`: um índice baseado em zero para identificar a localização da matriz no início do fragmento de texto parcial. # Exemplos de código: SDK para Python Esta seção fornece um exemplo de código para criar e invocar um endpoint que usa a explicabilidade on-line do SageMaker Clarify. Estes exemplos de código usam o [SDK AWS para Python](https://aws.amazon.com/sdk-for-python/). ## Dados tabulares O exemplo a seguir usa dados tabulares e um modelo de SageMaker IA chamado`model_name`. Neste exemplo, o contêiner do modelo aceita dados no formato CSV e cada registro tem quatro atributos numéricos. Nessa configuração mínima, **somente para fins de demonstração**, os dados da linha de base do SHAP são definidos como zero. Consulte [Linhas de base do SHAP para explicabilidade](clarify-feature-attribute-shap-baselines.md) para saber como escolher valores mais apropriados para `ShapBaseline`. Configure o endpoint da seguinte maneira: ``` endpoint_config_name = 'tabular_explainer_endpoint_config' response = sagemaker_client.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }], ExplainerConfig={ 'ClarifyExplainerConfig': { 'ShapConfig': { 'ShapBaselineConfig': { 'ShapBaseline': '0,0,0,0', }, }, }, }, ) ``` Use a configuração do endpoint para criar um endpoint, como segue: ``` endpoint_name = 'tabular_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` Use a API `DescribeEndpoint` para inspecionar o progresso da criação de um endpoint, da seguinte forma: ``` response = sagemaker_client.describe_endpoint( EndpointName=endpoint_name, ) response['EndpointStatus'] ``` Depois que o status do endpoint for "InService“, invoque o endpoint com um registro de teste, da seguinte forma: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', ) ``` **nota** No exemplo de código anterior, para endpoints multimodelo, passe um parâmetro adicional `TargetModel` na solicitação para especificar qual modelo deve ser direcionado ao endpoint. Suponha que a resposta tenha um código de status 200 (sem erro) e carregue o corpo da resposta da seguinte forma: ``` import codecs import json json.load(codecs.getreader('utf-8')(response['Body'])) ``` A ação padrão para o endpoint é explicar o registro. Veja a seguir um exemplo de saída no objeto JSON retornado. ``` { "version": "1.0", "predictions": { "content_type": "text/csv; charset=utf-8", "data": "0.0006380207487381" }, "explanations": { "kernel_shap": [ [ { "attributions": [ { "attribution": [-0.00433456] } ] }, { "attributions": [ { "attribution": [-0.005369821] } ] }, { "attributions": [ { "attribution": [0.007917749] } ] }, { "attributions": [ { "attribution": [-0.00261214] } ] } ] ] } } ``` Use o parâmetro `EnableExplanations` para habilitar explicações sob demanda, da seguinte forma: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', EnableExplanations='[0]>`0.8`', ) ``` **nota** No exemplo de código anterior, para endpoints multimodelo, passe um parâmetro adicional `TargetModel` na solicitação para especificar qual modelo deve ser direcionado ao endpoint. Neste exemplo, o valor de predição é menor que o valor limite de `0.8`, portanto, o registro não é explicado: ``` { "version": "1.0", "predictions": { "content_type": "text/csv; charset=utf-8", "data": "0.6380207487381995" }, "explanations": {} } ``` Use ferramentas de visualização para ajudar a interpretar as explicações retornadas. A imagem a seguir mostra como os gráficos SHAP podem ser usados para entender como cada atributo contribui para a predição. O valor base no diagrama, também chamado de valor esperado, é a média das predições do conjunto de dados de treinamento. Os atributos que aumentam o valor esperado são vermelhos e os atributos que reduzem o valor esperado são azuis. Consulte o [layout da força aditiva SHAP](https://shap.readthedocs.io/en/latest/generated/shap.plots.force.html) para obter informações adicionais. ![\[Exemplo de gráfico SHAP, que pode ser usado para entender como cada atributo contribui para a predição.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/force-plot.png) Veja o [exemplo completo de caderno de notas para dados tabulares](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular/tabular_online_explainability_with_sagemaker_clarify.ipynb). ## Dados de texto Esta seção fornece um exemplo de código para criar e invocar um endpoint de explicabilidade on-line para dados de texto. O exemplo de código usa SDK para Python. O exemplo a seguir usa dados de texto e um modelo de SageMaker IA chamado`model_name`. Neste exemplo, o contêiner do modelo aceita dados no formato CSV, e cada registro é uma única string. ``` endpoint_config_name = 'text_explainer_endpoint_config' response = sagemaker_client.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }], ExplainerConfig={ 'ClarifyExplainerConfig': { 'InferenceConfig': { 'FeatureTypes': ['text'], 'MaxRecordCount': 100, }, 'ShapConfig': { 'ShapBaselineConfig': { 'ShapBaseline': '""', }, 'TextConfig': { 'Granularity': 'token', 'Language': 'en', }, 'NumberOfSamples': 100, }, }, }, ) ``` + `ShapBaseline`: um token especial reservado para processamento de linguagem natural (PLN). + `FeatureTypes`: identifica o atributo como texto. Se esse parâmetro não for fornecido, o explicador tentará inferir o tipo de atributo. + `TextConfig`: especifica a unidade de granularidade e o idioma para a análise dos atributos de texto. Neste exemplo, o idioma é inglês e granularidade `token` significa uma palavra em um texto em inglês. + `NumberOfSamples`: um limite para definir os limites superiores do tamanho do conjunto de dados sintéticos. + `MaxRecordCount`: o número máximo de registros em uma solicitação que o recipiente modelo pode processar. Esse parâmetro está definido para estabilizar o performance. Use a configuração de endpoint para criar o endpoint, como segue: ``` endpoint_name = 'text_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` Depois que o status do endpoint se tornar `InService`, invoque o endpoint. O seguinte exemplo de código usa um registro de teste da seguinte forma: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='"This is a good product"', ) ``` Se a solicitação for concluída com êxito, o corpo da resposta retornará um objeto JSON válido semelhante ao seguinte: ``` { "version": "1.0", "predictions": { "content_type": "text/csv", "data": "0.9766594\n" }, "explanations": { "kernel_shap": [ [ { "attributions": [ { "attribution": [ -0.007270948666666712 ], "description": { "partial_text": "This", "start_idx": 0 } }, { "attribution": [ -0.018199033666666628 ], "description": { "partial_text": "is", "start_idx": 5 } }, { "attribution": [ 0.01970993241666666 ], "description": { "partial_text": "a", "start_idx": 8 } }, { "attribution": [ 0.1253469515833334 ], "description": { "partial_text": "good", "start_idx": 10 } }, { "attribution": [ 0.03291143366666657 ], "description": { "partial_text": "product", "start_idx": 15 } } ], "feature_type": "text" } ] ] } } ``` Use ferramentas de visualização para ajudar a interpretar as atribuições de texto retornadas. A imagem a seguir mostra como o utilitário de visualização captum pode ser usado para entender como cada palavra contribui para a predição. Quanto maior a saturação da cor, maior a importância dada à palavra. Neste exemplo, uma cor vermelha brilhante altamente saturada indica uma forte contribuição negativa. Uma cor verde altamente saturada indica uma forte contribuição positiva. A cor branca indica que a palavra tem uma contribuição neutra. Consulte a biblioteca [captum](https://github.com/pytorch/captum) para obter informações adicionais sobre como analisar e renderizar as atribuições. ![\[Utilitário de visualização Captum usado para entender como cada palavra contribui para a predição.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/clarify/word-importance.png) Veja o [exemplo completo do caderno de notas para dados de texto](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/natural_language_processing/nlp_online_explainability_with_sagemaker_clarify.ipynb). # Guia de solução de problemas Se você encontrar erros ao usar a explicabilidade on-line do SageMaker Clarify, consulte os tópicos desta seção. **`InvokeEndpoint`A API falha com o erro “: ReadTimeoutError Tempo limite de leitura no endpoint...”** Esse erro significa que a solicitação não pôde ser concluída dentro do limite de tempo de 60 segundos definido pelo tempo limite da [solicitação](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html). Para reduzir a latência da solicitação, tente o seguinte: + Ajuste o performance do modelo durante a inferência. Por exemplo, [o SageMaker AI Neo](https://aws.amazon.com/sagemaker/neo/) pode otimizar modelos para inferência. + Permita que o contêiner do modelo processe solicitações em lote. + Use um `MaxRecordCount` maior para reduzir o número de chamadas do explicador para o contêiner do modelo. Isso reduzirá a latência e a sobrecarga da rede. + Use um tipo de instância que tenha mais recursos alocados. Como alternativa, atribua mais instâncias ao endpoint para ajudar a equilibrar a carga. + Reduza o número de registros em uma única solicitação `InvokeEndpoint`. + Reduza o número de registros nos dados da linha de base. + Use um valor `NumberOfSamples` menor para reduzir o tamanho do conjunto de dados sintético. Para obter mais informações sobre como o número de amostras afeta o seu conjunto de dados sintéticos, consulte [Conjuntos de dados sintéticos](clarify-online-explainability-create-endpoint-synthetic.md).