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á. # 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).