本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Clarify 进行在线解释 SageMaker 在线解释能力 本指南介绍如何使用 Clarify 配置在线可 SageMaker 解释性。借 SageMaker 助 AI [实时推理](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html)端点，您可以实时、持续地分析可解释性。在线可解释性功能适合 A [mazon A SageMaker I Machine Learning](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-mlconcepts.html) 工作流程的 “**部署到生产**环境” 部分。 ## Clarify 在线解释能力的工作方式 工作方式 下图描述了用于托管提供可解释性请求的端点的 SageMaker AI 架构。它描绘了端点、模型容器和 Clarify 解释器之间的相互作用。 SageMaker ![\[SageMaker 人工智能架构显示托管一个为按需解释性请求提供服务的终端节点。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/DeveloperGuideArchitecture.png) 下面介绍 Clarify 在线解释能力的工作原理。应用程序向 A SageMaker I 运行时服务发送 REST 样式的`InvokeEndpoint`请求。该服务将此请求路由到 A SageMaker I 终端节点以获取预测和解释。然后，该服务会收到来自端点的响应。最后，该服务会将响应发送回应用程序。 为了提高终端节点的可用性， SageMaker AI 会自动尝试根据终端节点配置中的实例数量在多个可用区中分配终端节点实例。在端点实例上，根据新的可解释性请求，Clarify 解释 SageMaker 器会调用模型容器进行预测。然后，解释器会计算并返回特征归因。 以下是创建使用 SageMaker Clarify 在线可解释性的端点的四个步骤： 1. [按照预检查步骤检查您的预先训练的 SageMaker AI 模型是否与在线可解释性兼容。](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html) 1. 使用 [API 创建带有 Clari SageMaker fy 解释器配置的`CreateEndpointConfig`端点](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html)配置。 1. 使用 AP@@ [I 创建终端](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)节点并向 SageMaker A `CreateEndpoint` I 提供终端节点配置。该服务会启动 ML 计算实例，并按照配置中的规定部署模型。 1. [调用终端节点](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)：终端节点投入使用后，调用 SageMaker AI 运行时 API `InvokeEndpoint` 向终端节点发送请求。然后，端点返回解释和预测。 # 预检查模型容器 本节介绍如何在配置端点之前预先检查模型容器输入和输出的兼容性。Cl SageMaker arify 解释器与**模型无关**，但它对模型容器的输入和输出有要求。 **注意** 您可以通过将容器配置为支持批处理请求来提高效率，批处理请求支持在单个请求中包含两个或多个记录。例如，一个记录是单行 CSV 数据或一行 JSON 行数据。 SageMaker Clarify 将尝试先将一小批记录发送到模型容器，然后再回退到单个记录请求。 ## 模型容器输入 ------ #### [ CSV ] 模型容器支持 MIME 类型为 `text/csv` 的 CSV 格式输入。下表显示了 Clarify 支持的 SageMaker 示例输入。 | 模型容器输入（字符串表示） | 评论 | | --- | --- | | '1,2,3,4' | 使用四个数字特征的单个记录。 | | '1,2,3,4\$1n5,6,7,8' | 两条记录，用换行符“\$1n”分隔。 | | '"This is a good product",5' | 包含文本特征和数字特征的单个记录。 | | ‘"This is a good product",5\$1n"Bad shopping experience",1' | 两个记录。 | ------ #### [ JSON Lines ] SageMaker AI 还支持以 [JSON 行密集格式](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)输入，MIME 类型为:`application/jsonlines`，如下表所示。 | 模型容器输入 | 评论 | | --- | --- | | '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 单条记录；可以通过 JMESPath 表达式提取特征列表`data.features`。 | | '\$1"data":\$1"features":[1,2,3,4]\$1\$1\$1n\$1"data":\$1"features":[5,6,7,8]\$1\$1' | 两个记录。 | | '\$1"features":["This is a good product",5]\$1' | 单条记录；可以通过 JMESPath 表达式提取特征列表`features`。 | | '\$1"features":["This is a good product",5]\$1\$1n\$1"features":["Bad shopping experience",1]\$1' | 两个记录。 | ------ ## 模型容器输出 您的模型容器输出也应采用 CSV 或 JSON 行密集格式。此外，模型容器应包括输入记录的概率，Clarify 使用这些 SageMaker 概率来计算要素属性。 以下数据示例适用于 **CSV 格式**的模型容器输出。 ------ #### [ Probability only ] 对于回归和二进制分类问题，模型容器输出预测标签的单个概率值（分数）。可以使用列索引 0 提取这些概率。对于多分类问题，模型容器会输出概率（分数）列表。对于多分类问题，如果未提供索引，则提取所有值。 | 模型容器输入 | 模型容器输出（字符串表示） | | --- | --- | | 单个记录 | '0.6' | | 两个记录（结果位于一行） | '0.6,0.3' | | 两个记录（结果分为两行） | '0.6\$1n0.3' | | 多分类模型的单个记录（三个分类） | '0.1,0.6,0.3' | | 多分类模型的两个记录（三个分类） | '0.1,0.6,0.3\$1n0.2,0.5,0.3' | ------ #### [ Predicted label and probabilities ] 模型容器以 **CSV** 格式输出预测标签，然后输出其概率。可以使用索引 `1` 提取概率。 | 模型容器输入 | 模型容器输出 | | --- | --- | | 单个记录 | '1,0.6' | | 两条记录 | '1,0.6\$1n0,0.3' | ------ #### [ Predicted labels header and probabilities ] 可以将由 Autopilot 训练的多分类模型容器配置为以 **CSV** 格式输出预测标签和概率列表的**字符串表示形式**。在下面的示例中，可以通过索引 `1` 提取概率。标签标头可以按索引 `1` 提取，而标签标题可以使用索引 `0` 提取。 | 模型容器输入 | 模型容器输出 | | --- | --- | | 单个记录 | '"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.1,0.6,0.3]"' | | 两个记录 | '"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.1,0.6,0.3]"\$1n"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.2,0.5,0.3]"' | ------ 以下数据示例适用于 **JSON 行**格式的模型容器输出。 ------ #### [ Probability only ] 在此示例中，模型容器会输出可通过 **JSON 行**格式的 [https://jmespath.org/](https://jmespath.org/) 表达式 `score` 提取的概率。 | 模型容器输入 | 模型容器输出 | | --- | --- | | 单个记录 | '\$1"score":0.6\$1' | | 两个记录 | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' | ------ #### [ Predicted label and probabilities ] 在此示例中，多分类模型容器会以 **JSON 行**格式输出标签标头列表以及概率列表。概率可以通过 `JMESPath` 表达式 `probability` 提取，并且标签标头可以通过 `JMESPath` 表达式 `predicted labels` 提取。 | 模型容器输入 | 模型容器输出 | | --- | --- | | 单个记录 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' | | 两个记录 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]\$1' | ------ #### [ Predicted labels header and probabilities ] 在此示例中，多分类模型容器会以 **JSON 行**格式输出标签标头和概率的列表。概率可以通过 `JMESPath` 表达式 `probability` 提取，并且标签标头可以通过 `JMESPath` 表达式 `predicted labels` 提取。 | 模型容器输入 | 模型容器输出 | | --- | --- | | 单个记录 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' | | 两个记录 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]\$1' | ------ ## 模型容器验证 我们建议您将模型部署到 A SageMaker I 实时推理终端节点，然后向该终端节点发送请求。手动检查申请（模型容器输入）和响应（模型容器输出），确保两者都符合**模型容器输入**部分和**模型容器输出**部分中的要求。如果您的模型容器支持批处理请求，则可以从单个记录请求开始，然后尝试两个或更多记录。 以下命令显示如何使用 AWS CLI请求响应。已预先安装在 SageMaker Studio Classic 和 SageMaker 笔记本实例中。 AWS CLI 如果您需要安装，请按照本[安装指南](https://aws.amazon.com/cli/)进行操作。 AWS 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 ``` 参数定义如下： + `$ENDPOINT NAME`：端点的名称。 + `$CONTENT_TYPE`：请求的 MIME 类型（模型容器输入）。 + `$ACCEPT_TYPE`：响应的 MIME 类型（模型容器输出）。 + `$REQUEST_DATA`：请求的负载字符串。 + `$CLI_BINARY_FORMAT`：命令行界面 (CLI) 参数的格式。对于 AWS CLI v1，此参数应保留为空。对于 v2，此参数应设置为 `--cli-binary-format raw-in-base64-out`。 **注意** AWS CLI [v2 默认将二进制参数作为 base64 编码的字符串传递。](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam) 以下示例使用 AWS CLI v1： ------ #### [ Request and response in CSV format ] + 请求由单个记录组成，而响应是其概率值。 ``` 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 ``` 输出： `0.6` + 请求由两个记录组成，响应包括其概率，模型用逗号分隔概率。`--body` 中的 `$'content'` 表达式告诉命令将内容中的 `\n` 解释为换行符。 ``` 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 ``` 输出： `0.6,0.3` + 请求由两个记录组成，响应包括其概率，模型用换行符分隔概率。 ``` 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 ``` 输出： `0.6` `0.3` + 请求由单个记录组成，响应为概率值（多分类模型，三个分类）。 ``` 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 ``` 输出： `0.1,0.6,0.3` + 请求由两个记录组成，响应包括其概率值（多分类模型，三个分类）。 ``` 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 ``` 输出： `0.1,0.6,0.3` `0.2,0.5,0.3` + 请求由两个记录组成，响应包括预测标签和概率。 ``` 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 ``` 输出： `1,0.6` `0,0.3` + 请求由两个记录组成，响应包括标签标头和概率。 ``` 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 ``` 输出： `"['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 ] + 请求由单个记录组成，而响应是其概率值。 ``` 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 ``` 输出： `{"score":0.6}` + 请求包含两个记录，响应包括预测标签和概率。 ``` 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 ``` 输出： `{"predicted_label":1,"probability":0.6}` `{"predicted_label":0,"probability":0.3}` + 请求包含两个记录，响应包括标签标头和概率。 ``` 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 ``` 输出： `{"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 ] + 请求采用 CSV 格式，响应采用 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 ``` 输出： `{"probability":0.6}` `{"probability":0.3}` + 请求采用 JSON 行格式，响应采用 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 ``` 输出： `0.6` `0.3` ------ 验证完成后，[删除](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html)测试端点。 # 配置和创建端点 配置和创建端点 创建适合您的模型的新端点配置，然后使用此配置创建端点。您可以使用在[预检查步骤](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html)中验证的模型容器来创建端点并启用 Clarify 在线 SageMaker 可解释性功能。 使用`sagemaker_client`对象通过 [CreateEndpointConfig](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateEndpointConfig.html)API 创建终端节点。按照如下方式，在 `ExplainerConfig` 参数内设置成员 `ClarifyExplainerConfig`： ``` 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' ) ``` 第一次调用 `sagemaker_client` 对象时，会创建一个启用解释功能的新端点配置。第二个调用会使用端点配置来启动端点。 **注意** 您还可以在[SageMaker 人工智能实时推理多模型端点后面的一个容器中托管多个模型](https://docs.aws.amazon.com/sagemaker/latest/dg/multi-model-endpoints.html)，并使用 Clarify 配置在线可解释性。 SageMaker # `EnableExplanations` 表达式 `EnableExplanations` 参数是一个 [https://jmespath.org/](https://jmespath.org/) 布尔表达式字符串。它会针对解释能力请求中的**每个记录**进行评估。如果该参数的计算结果为 **true**，则将对记录进行解释。如果该参数的计算结果为 **false**，则不会生成解释。 SageMaker Clarify 将每条记录的模型容器输出反序列化为兼容 JSON 的数据结构，然后使用`EnableExplanations`参数来评估数据。 **注意** 根据模型容器输出的格式，有两个记录选项。 如果模型容器输出采用 CSV 格式，则记录将以 JSON 数组的形式加载。 如果模型容器输出采用 JSON 行格式，则记录将以 JSON 对象的形式加载。 `EnableExplanations`参数是一个可以在`InvokeEndpoint`或`CreateEndpointConfig`操作期间传递的 JMESPath 表达式。如果您提供的 JMESPath 表达式无效，则端点创建将失败。如果该表达式有效，但表达式计算出现意外结果，则端点将成功创建，但是调用端点时会出现错误。使用 `InvokeEndpoint` API 测试 `EnableExplanations` 表达式，然后将该表达式应用于端点配置。 下面是有效 `EnableExplanations` 表达式的一些示例。在示例中， JMESPath 表达式使用反引号字符括住文字。例如，``true`` 表示 true。 | 表达式（字符串表示） | 模型容器输出（字符串表示） | 计算结果（布尔值） | 含义 | | --- | --- | --- | --- | | '`true`' | （不适用） | True | 无条件激活在线解释能力。 | | '`false`' | （不适用） | False | 无条件地停用在线解释能力。 | | '[1]>`0.5`' | '1,0.6' | True | 对于每个记录，模型容器都会输出其预测标签和概率。解释一个记录的概率（在索引 1 处）是否大于 0.5。 | | 'probability>`0.5`' | '\$1"predicted\$1label":1,"probability":0.6\$1' | True | 对于每个记录，模型容器都会输出 JSON 数据。解释一个记录的概率是否大于 0.5。 | | '\$1contains(probabilities[:-1], max(probabilities))' | '\$1"probabilities": [0.4, 0.1, 0.4], "labels":["cat","dog","fish"]\$1' | False | 对于多分类模型：解释一个记录的预测标签（具有最大概率值的分类）是否为最后一个分类。从字面看，该表达式意味着最大概率值不在排除最后一个概率的概率列表中。 | # 合成数据集 SageMaker Clarify 使用内核 SHAP 算法。给定记录（也称为样本或实例）和 SHAP 配置，解释器首先生成合成数据集。 SageMaker 然后，Clarify 在模型容器中查询数据集的预测，然后计算并返回特征属性。合成数据集的大小会对 Clarify 解释器的运行时间产生影响。与较小的合成数据集相比，较大的合成数据集需要更长时间来获得模型预测。 合成数据集的大小可以通过以下公式确定： ``` Synthetic dataset size = SHAP baseline size * n_samples ``` SHAP 基线大小是 SHAP 基线数据中的记录数。此信息提取自 `ShapBaselineConfig`。 `n_samples` 的大小由解释器配置中的参数 `NumberOfSamples` 和特征数量设置。如果特征数量为 `n_features`，则 `n_samples` 如下： ``` n_samples = MIN(NumberOfSamples, 2^n_features - 2) ``` 如果未提供 `NumberOfSamples`，则下面会显示 `n_samples`。 ``` n_samples = MIN(2*n_features + 2^11, 2^n_features - 2) ``` 例如，对于包含 10 个特征的表记录，SHAP 基线大小为 1。如果未提供 `NumberOfSamples`，则合成数据集包含 1022 个记录。如果记录有 20 个特征，则合成数据集包含 2088 个记录。 对于 NLP 问题，`n_features` 等于非文本特征的数量加上文本单元的数量。 **注意** `InvokeEndpoint` API 存在请求超时限制。如果合成数据集太大，解释器可能无法在此时间限制内完成计算。如有必要，请使用前面的信息来理解和减小 SHAP 基线大小和 `NumberOfSamples`。如果您的模型容器设置为处理批处理请求，则您也可以调整 `MaxRecordCount` 的值。 # 调用端点 终端节点运行后，使用 SageMaker AI 运行时服务中的 A [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)I 运行时 API 向终端节点发送请求或调用该终端节点。 SageMaker 作为响应，Clarify 解释员将这些请求作为可解释性请求处理 SageMaker 。 **注意** 要调用端点，请选择以下选项之一： 有关使用 Boto3 或调用终端节点 AWS CLI 的说明，请参阅。[调用模型进行实时推理](realtime-endpoints-test-endpoints.md) 要使用 SageMaker 适用于 Python 的开发工具包调用端点，请参阅[预测器](https://sagemaker.readthedocs.io/en/stable/api/inference/predictors.html) API。 ## 请求 `InvokeEndpoint` API 有一个可选参数 `EnableExplanations`，该参数映射到 HTTP 标头 `X-Amzn-SageMaker-Enable-Explanations`。如果提供了此参数，则将覆盖 `ClarifyExplainerConfig` 的 `EnableExplanations` 参数。 **注意** `InvokeEndpoint` API 的 `ContentType` 和 `Accept` 参数是必需的。支持的格式包括 MIME 类型 `text/csv` 和 `application/jsonlines`。 使用 `sagemaker_runtime_client` 向端点发送请求，如下所示： ``` 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) ) ``` 对于多模型终端节点，请在上一个示例请求中传递一个附加的 `TargetModel` 参数，指定将哪个模型作为端点目标。多模型端点会根据需要动态地加载目标模型。有关多模型终端节点的更多信息，请参阅 [多模型端点](multi-model-endpoints.md)。有关如何从单个[端点设置和调用多个目标模型的示例，请参阅 Clarify Online Explainability on Multi-Model 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)。SageMaker ## 响应 如果使用 `ExplainerConfig` 创建端点，则使用新的响应架构。这个新的架构与缺少提供的 `ExplainerConfig` 参数的端点不同，并且不兼容。 响应的 MIME 类型为 `application/json`，响应负载可以从 UTF-8 字节解码为 JSON 对象。此 JSON 对象的成员如下所示： + `version`：字符串格式的响应架构版本。例如 `1.0`。 + `predictions`：该请求做出的预测如下： + `content_type`：预测的 MIME 类型，指的是模型容器响应的 `ContentType`。 + `data`：作为请求模型容器响应的负载进行传递的预测数据字符串。 + `label_headers`：`LabelHeaders` 参数中的标签标头。这在解释器配置或模型容器输出中提供。 + `explanations`：请求负载中提供的解释。如果没有解释任何记录，则此成员返回空对象 `{}`。 + + `kernel_shap`：一个键，该键引用请求中每个记录的 Kernel SHAP 解释数组。如果没有对某个记录做出解释，则相应的解释是 `null`。 `kernel_shap` 元素具有以下成员： + `feature_header`：解释器配置 `ExplainerConfig` 中的 `FeatureHeaders` 参数提供的特征的标头名称。 + `feature_type`：由解释器推断的特征类型，或者在 `ExplainerConfig` 中的 `FeatureTypes` 参数提供的特征类型。此元素仅适用于 NLP 解释能力问题。 + `attributions`：一个归因对象数组。文本特征可以有多个归因对象，每个对象用于一个单元。归因对象具有以下成员： + `attribution`：为每个分类给出的概率值列表。 + `description`：文本单元的描述，仅适用于 NLP 解释能力问题。 + `partial_text`：解释器做出解释的文本部分。 + `start_idx`：从零开始的索引，用于标识部分文本片段开头的数组位置。 # 代码示例：SDK for Python 本节提供了创建和调用使用 SageMaker Clarify 在线可解释性的端点的示例代码。这些代码示例使用 [AWS SDK for Python](https://aws.amazon.com/sdk-for-python/)。 ## 表格数据 以下示例使用表格数据和名`model_name`为的 A SageMaker I 模型。在本示例中，模型容器接受 CSV 格式的数据，并且每个记录都有四个数字特征。在此最低配置中，SHAP 基线数据设置为零，**这只是为了演示目的**。请参阅 [SHAP 可解释性基准](clarify-feature-attribute-shap-baselines.md)，了解如何为 `ShapBaseline` 选择更合适的值。 按照下面的方式配置端点： ``` 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', }, }, }, }, ) ``` 使用端点配置创建端点，如下所示： ``` endpoint_name = 'tabular_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` 使用 `DescribeEndpoint` API 检查端点创建进度，如下所示： ``` response = sagemaker_client.describe_endpoint( EndpointName=endpoint_name, ) response['EndpointStatus'] ``` 在终端节点状态为 InService “” 后，使用测试记录调用终端节点，如下所示： ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', ) ``` **注意** 在上一个代码示例中，对于多模型端点，请在请求中传递一个附加的 `TargetModel` 参数，指定将哪个模型作为端点目标。 假设响应的状态代码为 200（无错误），并按以下方式加载响应正文： ``` import codecs import json json.load(codecs.getreader('utf-8')(response['Body'])) ``` 端点的默认操作是解释记录。下面显示了所返回的 JSON 对象中的示例输出。 ``` { "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] } ] } ] ] } } ``` 使用 `EnableExplanations` 参数启用按需解释功能，如下所示： ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', EnableExplanations='[0]>`0.8`', ) ``` **注意** 在上一个代码示例中，对于多模型端点，请在请求中传递一个附加的 `TargetModel` 参数，指定将哪个模型作为端点目标。 在本示例中，预测值小于阈值 `0.8`，因此不解释该记录： ``` { "version": "1.0", "predictions": { "content_type": "text/csv; charset=utf-8", "data": "0.6380207487381995" }, "explanations": {} } ``` 使用可视化工具来协助说明所返回的解释。下图显示了如何使用 SHAP 图表来理解每个特征对预测的贡献。图表上的基值（也称为预期值）是训练数据集的平均预测值。将预期值推高的特征显示为红色，将预期值推低的特征显示为蓝色。有关更多信息，请参阅 [SHAP 附加力布局](https://shap.readthedocs.io/en/latest/generated/shap.plots.force.html)。 ![\[可用于了解每个特征对预测贡献的 SHAP 图示例。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/force-plot.png) 请参阅[有关表格数据的完整示例笔记本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular/tabular_online_explainability_with_sagemaker_clarify.ipynb)。 ## 文本数据 此部分提供了一个代码示例，用于创建和调用文本数据的在线解释能力端点。本示例代码使用 SDK for Python。 以下示例使用文本数据和名为的 SageMaker AI 模型`model_name`。在此示例中，模型容器接受 CSV 格式的数据，并且每个记录都是一个字符串。 ``` 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`：为自然语言处理 (NLP) 处理保留的特殊令牌。 + `FeatureTypes`：将特征标识为文本。如果未提供此参数，解释器将尝试推断特征类型。 + `TextConfig`：指定文本特征分析的粒度单位和语言。在本示例中，语言为英语，粒度 `token` 表示英语文本中的一个单词。 + `NumberOfSamples`：用于设置合成数据集的大小上限的限制。 + `MaxRecordCount`：请求中可由模型容器处理的最大记录数。设置此参数是为了提供稳定的性能。 使用端点配置创建端点，如下所示： ``` endpoint_name = 'text_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` 在端点状态变为 `InService` 后，调用该端点。下面的代码示例使用测试记录，如下所示： ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='"This is a good product"', ) ``` 如果请求成功完成，响应正文将返回一个类似于如下内容的有效 JSON 对象： ``` { "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" } ] ] } } ``` 使用可视化工具来协助说明所返回的文本归因。下图显示了如何使用 captum 可视化实用程序来理解每个单词对预测的贡献。色彩饱和度越高，赋予单词的重要性就越高。在本示例中，高饱和度的亮红色表示强烈的负面共享。高饱和度的绿色表示强烈的积极贡献。白色表示单词的贡献是中性的。有关解析和渲染归因的更多信息，请参阅 [captum](https://github.com/pytorch/captum) 库。 ![\[使用 Captum 可视化实用程序可以理解每个单词对预测的影响。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/word-importance.png) 请参阅[有关文本数据的完整示例笔记本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/natural_language_processing/nlp_online_explainability_with_sagemaker_clarify.ipynb)。 # 故障排除指南 如果您在使用 Clarif SageMaker y 在线可解释性时遇到错误，请查阅本节的主题。 **`InvokeEndpoint`API 失败并显示错误 “: 端点读取ReadTimeoutError超时...”** 此错误表示无法在[请求超时](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)设置的 60 秒时间限制内完成请求。 要减少请求延迟，请尝试以下操作： + 优化模型在推理期间的性能。例如， SageMaker AI [Neo](https://aws.amazon.com/sagemaker/neo/) 可以优化模型以进行推理。 + 允许模型容器处理批处理请求。 + 使用更大的 `MaxRecordCount` 值可以减少从解释器发送到模型容器的调用次数。这将减少网络延迟和开销。 + 使用分配有更多资源的实例类型。此外，可以为端点分配更多实例来协助平衡负载。 + 减少单个 `InvokeEndpoint` 请求中的记录数。 + 减少基准数据中的记录数。 + 使用较小的 `NumberOfSamples` 值来减小合成数据集的大小。有关示例数量如何影响合成数据集的更多信息，请参阅 [合成数据集](clarify-online-explainability-create-endpoint-synthetic.md)。