本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Clarify 进行公平性、模型可解释性和偏见检测 SageMaker
您可以使用 Amazon SageMaker Clarify 来了解公平性和模型的可解释性，并解释和检测模型中的偏差。您可以配置 Clari SageMaker fy 处理作业来计算偏差指标和特征归因，并生成模型可解释性报告。 SageMaker 澄清处理任务是使用专门 SageMaker 的 Clarify 容器镜像实现的。下一页介绍了 Cl SageMaker arify 的工作原理以及如何开始分析。
## 什么是机器学习预测的公平性和模型可解释性？
机器学习 (ML) 模型有助于在金融服务、医疗保健、教育和人力资源等领域做出决策。策略制定者、监管者和倡导者提高了对人工智能和数据驱动系统带来的道德和策略挑战的认识。Ama SageMaker zon Clarify 可以帮助您了解您的机器学习模型做出特定预测的原因，以及这种偏见是否会影响训练或推理期间的预测。 SageMaker Clarify 还提供了可以帮助您构建偏见更少、更易于理解的机器学习模型的工具。 SageMaker Clarify 还可以生成模型治理报告，您可以将其提供给风险和合规团队以及外部监管机构。使用 C SageMaker larify，您可以执行以下操作：
+ 检测模型预测中的偏差并帮助解释。
+ 识别预训练数据中的偏差类型。
+ 识别训练后数据中的偏差类型，这些偏差可能在训练过程中或模型投入生产时出现。
SageMaker Clarify 有助于解释您的模型如何使用特征归因进行预测。它还可以监控正在生产的推理模型，以发现偏差和功能归因漂移。这些信息可以在以下方面为您提供帮助：
+ **监管** - 策略制定者和其他监管者可能会担心使用 ML 模型输出的决策会产生歧视性影响。例如，人工智能模型可能会编码偏见并影响自动决策。
+ **商业**：监管领域可能需要对 ML 模型如何进行预测做出可靠的解释。对于依赖可靠性、安全性和合规性的行业来说，模型的可解释性可能尤为重要。这些领域包括金融服务、人力资源、医疗保健和自动运输。例如，贷款应用程序可能需要向贷款人员、预测人员和客户解释 ML 模型是如何做出某些预测的。
+ **数据科学**：当数据科学家和 ML 工程师能够确定模型是否根据噪声或无关功能进行推断时，他们就能调试和改进 ML 模型。他们还可以了解其模型的局限性以及模型可能遇到的故障模式。
有关展示如何为欺诈性汽车索赔设计和构建完整的机器学习模型的博客文章，该模型将Clarify集成 SageMaker 到 SageMaker 人工智能管道中，请查看[架构师并通过以下方式构建完整的机器学习生命周期 AWS： end-to-endAmazon A SageMaker I](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) 演示。本博文将讨论如何评测和减轻训练前和训练后的偏差，以及功能对模型预测的影响。博文中包含 ML 生命周期中每个任务的示例代码链接。
### 评估 ML 生命周期中公平性和可解释性的最佳做法
**公平是一个过程**：偏见和公平的概念取决于它们的应用。偏差的测量和偏差指标的选择可能受社会、法律和其他非技术因素的影响。要成功采用具有公平意识的多边借贷方法，就必须在主要利益相关方之间达成共识并开展合作。这些可能包括产品、政策、法律、工程、 AI/ML 团队、最终用户和社区。
**在人工智能生命周期中设计公平性和可解释性**：在人工智能生命周期的每个阶段都要考虑公平性和可解释性。这些阶段包括问题形成、数据集构建、算法选择、模型训练过程、测试过程、部署以及监控和反馈。重要的是要有正确的工具来进行这种分析。我们建议在 ML 生命周期内提出以下问题：
+ 这种模式是否会鼓励产生越来越不公平结果的反馈循环？
+ 算法是解决问题的道德方案吗？
+ 训练数据是否代表不同群体？
+ 标签或功能是否存在偏见？
+ 是否需要修改数据以减少偏差？
+ 目标函数中是否需要包含公平约束条件？
+ 是否使用相关的公平性指标对模型进行了评估？
+ 对不同用户的影响是否不平等？
+ 是否在未经训练或评估的人群中部署了模型？
![\[评估公平性和模型可解释性过程的最佳实践。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify-best-practices-image.png)
### SageMaker 人工智能解释和偏见文档指南
在训练模型之前和之后，数据中都可能出现偏差并对其进行测量。 SageMaker Clarify 可以为训练后的模型预测以及部署到生产环境的模型提供解释。 SageMaker Clarify 还可以监控生产中的模型的基线解释性归因是否存在任何偏差，并在需要时计算基线。使用 SageMaker Clarify 解释和检测偏见的文档结构如下：
+ 有关设置偏差和可解释性处理任务的信息，请参阅 [配置 Clari SageMaker fy 处理 Job](clarify-processing-job-configure-parameters.md)。
+ 有关在用于训练模型之前检测预处理数据偏差的信息，请参阅 [训练前数据偏差](clarify-detect-data-bias.md)。
+ 有关检测训练后数据和模型偏差的信息，请参阅 [训练后数据和模型偏差](clarify-detect-post-training-bias.md)。
+ 有关解释训练后模型预测的模型无关功能归因方法的信息，请参阅 [模型可解释性](clarify-model-explainability.md)。
+ 有关监测功能贡献偏离模型训练期间建立的基线的信息，请参阅 [生产中模型的功能归属漂移](clarify-model-monitor-feature-attribution-drift.md)。
+ 有关监测正在生产的基线漂移模型的信息，请参阅 [生产中模型的偏压飘移](clarify-model-monitor-bias-drift.md)。
+ 有关从 SageMaker AI 终端节点实时获取解释的信息，请参阅[使用 Clarify 进行在线解释 SageMaker](clarify-online-explainability.md)。
## SageMaker 澄清处理任务的工作原理
您可以使用 Cl SageMaker arify 来分析数据集和模型的可解释性和偏差。Cl SageMaker arify 处理任务使用 Cl SageMaker arify 处理容器与包含您的输入数据集的 Amazon S3 存储桶进行交互。您还可以使用 Cl SageMaker arify 来分析部署到 A SageMaker I 推理端点的客户模型。
下图显示了 Clari SageMaker fy 处理任务如何与您的输入数据交互，也可以与客户模型进行交互。这种交互取决于所执行的特定分析类型。Cl SageMaker arify 处理容器从 S3 存储桶获取用于分析的输入数据集和配置。对于某些分析类型，包括特征分析，Clar SageMaker ify 处理容器必须向模型容器发送请求。然后，它从模型容器发送的响应中检索模型预测。之后，Clari SageMaker fy 处理容器进行计算并将分析结果保存到 S3 存储桶中。
![\[SageMaker Clarify 可以分析您的数据或客户模型的可解释性和偏见。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/clarify-processing-job.png)
您可以在机器学习工作流程生命周期的多个阶段运行 Clarify 处理作业。 SageMaker SageMaker Clarify 可以帮助您计算以下分析类型：
+ 训练前的偏差指标。这些指标可以帮助您了解数据中的偏差，从而解决偏差问题，并在更公平的数据集上训练模型。有关预训练偏差指标的信息，请参阅 [训练前偏差指标](clarify-measure-data-bias.md)。要运行一项作业以分析训练前偏差指标，必须向 [分析配置文件](clarify-processing-job-configure-analysis.md) 提供数据集和 JSON 分析配置文件。
+ 训练后偏差指标。这些指标可帮助您了解算法、超参数选择引入的任何偏差，或流程早期不明显的任何偏差。有关训练后偏差指标的更多信息，请参阅[训练后数据和模型偏差指标](clarify-measure-post-training-bias.md)。 SageMaker 除了数据和标签之外，Clarify 还使用模型预测来识别偏差。要运行一项作业以分析训练后偏差指标，必须提供数据集和 JSON 分析配置文件。配置应包括模型或端点名称。
+ Shapley 值，它可以帮助您了解功能对模型预测结果的影响。有关 Shapley 值的更多信息，请参阅 [使用 Shapley 值的特征归因](clarify-shapley-values.md)。此特征需要经过训练的模型。
+ 部分依赖图 (PDPs)，它可以帮助您了解如果改变一个特征的值，预测的目标变量将发生多大变化。有关更多信息 PDPs，请参阅[部分依赖图 (PDPs) 分析](clarify-processing-job-analysis-results.md#clarify-processing-job-analysis-results-pdp)此功能需要经过训练的模型。
SageMaker Clarify 需要模型预测来计算训练后的偏差指标和特征归因。*您可以提供端点，否则 C SageMaker larify 将使用您的模型名称（也称为影子端点）创建一个临时端点。*计算完成后， SageMaker Clarify 容器会删除影子端点。简而言之，Clari SageMaker fy 容器完成了以下步骤：
1. 验证输入和参数。
1. 创建影子端点（如果提供了模型名称）。
1. 将输入数据集加载到数据框中。
1. 如有必要，从端点获取模型预测。
1. 计算偏差指标和特征归因。
1. 删除影子端点。
1. 生成分析结果。
Cl SageMaker arify 处理作业完成后，分析结果将保存在您在作业的处理输出参数中指定的输出位置。这些结果包括 JSON 文件（其中包含偏差指标和全局特征归因）、可视化报告以及用于局部特征归因的其他文件。您可以从输出位置下载结果并进行查看。
有关偏见指标、可解释性以及如何解释这些指标的更多信息，请参阅[了解 Ama SageMaker zon Clarify 如何帮助检测偏见](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias)、[金融领域机器学习的公平衡](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)量标准以及 A [mazon AI 公平性与可解释性白皮](https://pages.awscloud.com/rs/112-TZM-766/images/Amazon.AI.Fairness.and.Explainability.Whitepaper.pdf)书。
# 配置 Clari SageMaker fy 处理 Job
要使用 SageMaker Clarify 分析您的数据和模型的偏差和可解释性，您必须配置 Clarify 处理 SageMaker 作业。本指南介绍如何为处理作业指定输入数据集名称、分析配置文件名称和输出位置。有两种选项可用于配置处理容器、作业输入、输出、资源和其他参数。你可以使用 SageMaker A `CreateProcessingJob` I API，也可以使用 AI Python SDK API`SageMaker ClarifyProcessor`， SageMaker
有关所有处理任务的通用参数的信息，请参阅 [Amazon SageMaker API 参考](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp)。
## 使用 SageMaker API 配置 SageMaker Clarify 处理作业
以下说明说明如何使用 `CreateProcessingJob` API 提供 Clarify 特定配置的每个部分。 SageMaker
1. 在`AppSpecification`参数中输入 Clarify 容器 SageMaker 图像的统一研究标识符 (URI)，如以下代码示例所示。
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**注意**
URI 必须标识预先构建的 Clarify SageMaker 容器镜像。 `ContainerEntrypoint`并且`ContainerArguments`不受支持。有关 Clarify SageMaker 容器镜像的更多信息，请参阅[预建的 SageMaker 澄清容器](clarify-processing-job-configure-container.md)。
1. 在 `ProcessingInputs` 参数中指定分析配置和输入数据集参数。
1. 指定 JSON 分析配置文件的位置，该文件包含用于偏差分析和可解释性分析的参数。`ProcessingInput` 对象的 `InputName` 参数必须是 **analysis\$1config**，如以下代码示例所示。
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
有关分析配置文件模式的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
1. 指定输入数据集的位置。`ProcessingInput` 对象的 `InputName` 参数必须是 `dataset`。如果您在分析配置文件中提供了“dataset\$1uri”，则此参数为可选。`S3Input` 配置中需要以下值。
1. `S3Uri` 可以是 Amazon S3 对象或 S3 前缀。
1. `S3InputMode` 必须是类型 **File**。
1. `S3CompressionType` 必须是类型 `None`（默认值）。
1. `S3DataDistributionType` 必须是类型 `FullyReplicated`（默认值）。
1. `S3DataType` 可以是 `S3Prefix` 或 `ManifestFile`。要使用`ManifestFile`，`S3Uri`参数应指定清单文件的位置，该文件位于 “ SageMaker API 参考” 部分 [S3](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri) Uri 中的架构之后。此清单文件必须列出包含作业输入数据的 S3 对象。
以下代码显示了输入配置的示例。
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. 在 `ProcessingOutputConfig` 参数中指定处理作业输出的配置。`Outputs` 配置中需要单个 `ProcessingOutput` 对象。输出配置的要求如下：
1. `OutputName` 必须是 **analysis\$1result**。
1. `S3Uri` 必须是输出位置的 S3 前缀。
1. `S3UploadMode` 必须设置为 **EndOfJob**。
以下代码显示了输出配置的示例。
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. 在 `ProcessingResources` 参数中为处理作业中使用的资源指定配置 `ClusterConfig`。`ClusterConfig` 对象内部需要以下参数。
1. `InstanceCount` 指定集群中运行处理作业的计算实例的数量。请指定一个大于 `1` 的值，以激活分布式处理。
1. `InstanceType` 是指运行处理作业的资源。由于 SageMaker AI SHAP 分析是计算密集型的，因此使用针对计算进行了优化的实例类型应该可以缩短分析的运行时间。“ SageMaker 澄清” 处理作业不使用 GPUs。
以下代码显示了资源配置的示例。
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. 在 `NetworkConfig` 对象中指定处理作业中使用的网络配置。配置中需要以下值。
1. `EnableNetworkIsolation`必须设置为`False`（默认），这样 Cl SageMaker arify 才能在必要时调用端点进行预测。
1. 如果您提供给 Clarify 任务的模型或终端节点位于亚马逊虚拟私有云（亚马逊 VPC）中，则 Clarify 任务也必须位于同一 VPC 中。 SageMaker SageMaker 使用指定 VPC [VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html)。此外，VPC 必须具有指向 Amazon S3 存储桶、 SageMaker AI 服务和 A SageMaker I 运行时服务的终端节点。
如果激活了分布式处理，则还必须允许同一处理作业中的不同实例之间进行通信。请为您的安全组配置规则，以允许同一安全组的成员之间实现入站连接。有关更多信息，请参阅 [让 Amazon SageMaker Clarify Jobs 访问您的亚马逊 VPC 中的资源](clarify-vpc.md)。
以下代码显示了网络配置的示例。
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. 使用 `StoppingCondition` 参数设置作业运行的最长时间。Clarify SageMaker 作业可以运行的最长时间为`7`几天或`604800`几秒。如果无法在此时限内完成作业，则作业将停止，并且不会提供任何分析结果。例如，以下配置将作业的最长运行时间限制为 3600 秒。
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. 为 `RoleArn` 参数指定 IAM 角色。该角色必须与 Amazon A SageMaker I 建立信任关系。它可用于执行下表中列出 SageMaker 的 API 操作。我们建议使用 Amazon A SageMaker AIFull ccess 托管策略，该策略授予对 SageMaker AI 的完全访问权限。有关此策略的更多信息，请参阅[AWS 托管策略： AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess)。如果您对授予完全访问权限有疑虑，则所需的最低权限取决于您提供的是模型还是端点名称。使用终端节点名称可以向 SageMaker AI 授予更少的权限。
下表包含 Clarify 处理任务使用 SageMaker 的 API 操作。**模型名称**和**端点名称**下的 **X** 注明了每个输入所需的 API 操作。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
有关所需权限的更多信息，请参阅[Amazon SageMaker AI API 权限：操作、权限和资源参考](api-permissions-reference.md)。
有关向 SageMaker AI 传递角色的更多信息，请参阅[传递角色](sagemaker-roles.md#sagemaker-roles-pass-role)。
获得处理作业配置的各个部分后，将它们组合起来配置作业。
## 使用适用于 Python 的 AWS SDK 配置 Clarify 处理作业 SageMaker
以下代码示例展示了如何使用适用于 [Python 的 SageMaker AWS 软件开发工具包启动 Clarify](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",
)
```
有关使用适用于 Python 的 SDK 运行 Clarif SageMaker y 处理作业的说明的示例笔记本，请参阅使用 AWS 适用于 Python 的 SD [AWS K 使用 Clarify SageMaker 实现公平性和可解释性](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb)。笔记本中使用的任何 S3 存储桶都必须与访问该存储桶的笔记本实例位于同一 AWS 区域。
## 使用 SageMaker Python 软件开发工具包配置 Clarify 处理作业 SageMaker
你也可以使用 SageMaker Python SDK API [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)中的 Clarify 处理作业。 SageMaker 有关更多信息，请参阅 [运行 Cl SageMaker arify 处理作业以实现偏见分析和可解释性](clarify-processing-job-run.md)。
**Topics**
+ [预建的 SageMaker 澄清容器](clarify-processing-job-configure-container.md)
+ [分析配置文件](clarify-processing-job-configure-analysis.md)
+ [数据格式兼容性指南](clarify-processing-job-data-format.md)
# 预建的 SageMaker 澄清容器
Amazon SageMaker AI 提供了预构建 SageMaker 的 Clarify 容器镜像，其中包括计算偏差指标和功能归因所需的库和其他依赖项，以便于解释。这些图片能够在您的账户中运行 SageMaker C [larify 处理任务](processing-job.md)。
容 URIs 器的图像采用以下形式：
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
例如：
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
下表列出了按地址排列的地址 AWS 区域。
用于 SageMaker 澄清处理任务的 Docker 镜像
| Region | 映像地址 |
| --- | --- |
| 美国东部（弗吉尼亚州北部） | 205585389593.dkr。ecr.us-east-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 美国东部（俄亥俄州） | 211330385671.dkr。ecr.us-east-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 美国西部（北加利福尼亚） | 740489534195.dkr。ecr.us-west-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 美国西部（俄勒冈州） | 306415355426.dkr。ecr.us-west-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（香港） | 098760798382.dkr。ecr.ap-east-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（孟买） | 452307495513.dkr。ecr.ap-south-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（雅加达） | 705930551576.dkr。ecr.ap-southeast-3.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（东京） | 377024640650.dkr。ecr.ap-northeast-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（首尔） | 263625296855.dkr。ecr.ap-northeast-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（大阪） | 912233562940.dkr。ecr.ap-northeast-3.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（新加坡） | 834264404009.dkr。ecr.ap-southeast-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 亚太地区（悉尼） | 007051062584.dkr。ecr.ap-southeast-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 加拿大（中部） | 675030665977.dkr。ecr.ca-central-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（法兰克福） | 017069133835.dkr。ecr.eu-central-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲（苏黎世） | 730335477804.dkr。ecr.eu-central-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（爱尔兰） | 131013547314.dkr。ecr.eu-west-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（伦敦） | 440796970383.dkr。ecr.eu-west-2.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（巴黎） | 341593696636.dkr。ecr.eu-west-3.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（斯德哥尔摩） | 763603941244.dkr。ecr.eu-north-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 中东（巴林） | 835444307964.dkr。ecr.me-south-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 南美洲（圣保罗） | 520018980103.dkr。ecr.sa-east-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 非洲（开普敦） | 811711786498.dkr。ecr.af-south-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 欧洲地区（米兰） | 638885417683.dkr。ecr.eu-south-1.amazonaws.com /: 1.0 sagemaker-clarify-processing |
| 中国（北京） | 122526803553.dkr。ecr.cn-north-1.amazonaws.com .cn/: 1.0 sagemaker-clarify-processing |
| 中国（宁夏） | 122578899357.dkr。ecr.cn-northwest-1.amazonaws.com .cn/: 1.0 sagemaker-clarify-processing |
# 分析配置文件
要使用 Clarify 分析数据和模型的可解释性和偏 SageMaker 差，必须配置处理作业。此处理作业的部分配置包括分析文件的配置。分析文件指定偏差分析和可解释性的参数。请参阅 [配置 Clari SageMaker fy 处理 Job](clarify-processing-job-configure-parameters.md) 了解如何配置处理任务和分析文件。
本指南描述了此分析配置文件的架构和参数。本指南还包括分析配置文件示例，用于计算表格数据集的偏差指标，以及生成自然语言处理 (NLP)、计算机视觉 (CV) 和时间序列 (TS) 问题的解释。
您可以创建分析配置文件，也可以使用 [SageMaker Python SDK [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)](https://sagemaker.readthedocs.io/)通过 API 为你生成一个配置文件。查看文件内容有助于理解 Clarify 作业使用的底 SageMaker 层配置。
**Topics**
+ [分析配置文件的架构](#clarify-processing-job-configure-schema)
+ [示例分析配置文件](#clarify-processing-job-configure-analysis-examples)
## 分析配置文件的架构
下一节介绍分析配置文件的架构，包括要求和参数描述。
### 分析配置文件的要求
C SageMaker larify 处理任务要求分析配置文件按照以下要求进行构建：
+ 处理输入名称必须是 `analysis_config.`
+ 分析配置文件采用 JSON 格式，并以 UTF-8 编码。
+ 分析配置文件是一个 Amazon S3 对象。
您可以在分析配置文件中指定其他参数。以下部分提供了各种选项，可根据您的用例和所需的分析类型量身定制 Clarify 处理作业。 SageMaker
### 分析配置文件的参数
您可以在分析配置文件中指定以下参数。
+ **version** -（可选）分析配置文件架构的版本字符串。如果未提供版本，Clari SageMaker fy 将使用支持的最新版本。目前唯一支持的版本是 `1.0`。
+ **dataset\$1type** - 数据集的格式。输入数据集格式可以是以下任意值：
+ 表格
+ `text/csv`（对于 CSV）
+ `application/jsonlines`适用于 [SageMaker AI 的 JSON 线密集格式](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)
+ `application/json`（对于 JSON）
+ `application/x-parquet`（对于 Apache Parquet）
+ `application/x-image`（激活计算机视觉问题的可解释性）
+ 时间序列预测模型解释
+ `application/json`（对于 JSON）
+ **dataset\$1uri** -（可选）主数据集的统一资源标识符 (URI)。如果您提供 S3 URI 前缀，则 Clarif SageMaker y 处理任务会以递归方式收集位于该前缀下的所有 S3 文件。您可以为映像清单文件提供 S3 URI 前缀或 S3 URI，以解决计算机视觉问题。如果提供了 `dataset_uri`，它将优先于数据集处理作业输入。对于除图像和时间序列用例之外的任何格式类型，Clarify 处理作业会将输入数据集作为表格数据集加载到**表格**数据框中。 SageMaker 这种格式允许 SageMaker AI 轻松操作和分析输入数据集。
+ **headers**：（可选）
+ **表格：**。包含表格数据集列名的字符串数组。如果未提供值`headers`，则 Clarif SageMaker y 处理作业会从数据集中读取标题。如果数据集没有标题，那么 Clarify 处理任务会根据基于零的列索引自动生成占位符名称。例如，第一列和第二列的占位符名称分别为 **column\$10**、**column\$11**，以此类推。
**注意**
按照惯例，如果 `dataset_type` 是 `application/jsonlines` 或 `application/json`，那么 `headers` 应依次包含以下名称：
功能名称
标签名称（如果指定了 `label`）
预测标签名称（如果指定了 `predicted_label`）
如果已指定 `label`，则 `application/jsonlines` 数据集类型的 `headers` 的一个示例是：`["feature1","feature2","feature3","target_label"]`。
+ **时间序列：**数据集中的列名列表。数据集中的列名列表。如果未提供，Clarify 将生成标题供内部使用。对于时间序列可解释性案例，按以下顺序提供标题：
1. 项目 id
1. timestamp
1. 目标时间序列
1. 所有相关时间序列列
1. 所有静态协变量列
+ **label** -（可选）字符串或零基整数索引。如果提供，则 `label` 用于定位 Ground Truth 标签，也称为观测标签或表格数据集中的目标属性。Ground Truth 标签用于计算偏差指标。`label` 的值根据 `dataset_type` 参数的值指定，如下所示。
+ 如果 `dataset_type` 为 **text/csv**，则 `label` 可以指定为以下任一项：
+ 有效的列名称
+ 位于数据集列范围内的索引
+ 如果 `dataset_type` 为 **application/parquet**，则 `label` 必须是有效的列名称。
+ 如果`dataset_type`是**application/jsonlines**，则`label`必须是为从数据集中提取真实数据标签而编写的[JMESPath](https://jmespath.org/)表达式。按照惯例，如果已指定 `headers`，则它应包含标签名称。
+ 如果`dataset_type`是**application/json**，则`label`必须是为提取数据集中每条记录的基本真相标签而编写的[JMESPath](https://jmespath.org/)表达式。此 JMESPath 表达式必须生成标签列表，其中第 i 个标签与第 i 条记录相关。
+ **predicted\$1label** -（可选）字符串或零基整数索引。如果提供，则 `predicted_label` 用于在表格数据集中定位包含预测标签的列。预测标签用于计算训练后**偏差指标**。如果数据集不包含预测标签，则参数 `predicted_label` 为可选。如果计算需要预测标签，则 Clarif SageMaker y 处理作业将从模型中获得预测。
`predicted_label` 的值根据 `dataset_type` 的值指定，如下所示：
+ 如果 `dataset_type` 为 **text/csv**，则 `predicted_label` 可以指定为以下任一项：
+ 有效的列名称。如果已指定 `predicted_label_dataset_uri` 但未提供 `predicted_label`，则默认预测标签名称为“predicted\$1label”。
+ 位于数据集列范围内的索引。如果已指定 `predicted_label_dataset_uri`，则使用索引在预测标签数据集中定位预测标签列。
+ 如果 dataset\$1type 为 **application/x-parquet**，则 `predicted_label` 必须是有效的列名称。
+ 如果 dataset\$1type 为**application/jsonlines**，则`predicted_label`必须是为从数据集中提取预测标签而编写的有效[JMESPath](https://jmespath.org/)表达式。按照惯例，如果已指定 `headers`，则它应包含预测标签名称。
+ 如果`dataset_type`是**application/json**，则`predicted_label`必须是为提取数据集中每条记录的预测标签而编写的[JMESPath](https://jmespath.org/)表达式。该 JMESPath 表达式应生成预测标签列表，其中第 i 个预测标签用于第 i 个记录。
+ **f** eatures —（可选）如果`dataset_type`是`application/jsonlines`或，则为 non-time-series用例必填项`application/json`。为定位输入数据集中的要素而编写的 JMESPath 字符串表达式。对于`application/jsonlines`，将对每行应用一个 JMESPath 表达式来提取该记录的要素。对于`application/json`， JMESPath 表达式将应用于整个输入数据集。该 JMESPath 表达式应提取列表列表或 2D array/matrix 要素列表，其中第 i 行包含与第 i 条记录相关的要素。对于 `text/csv` 或 `application/x-parquet` 的 `dataset_type`，除 Ground Truth 标签列和预测标签列之外的所有列都将自动指定为特征。
+ **predicted\$1label\$1dataset\$1uri**：（可选）仅适用于数据集类型为 `text/csv` 时。数据集的 S3 URI，该数据集包含用于计算训练后**偏差指标**的预测标签。C SageMaker larify 处理任务将从提供的 URI 加载预测，而不是从模型中获取预测。在这种情况下，需要 `predicted_label` 在预测标签数据集中找到预测标签列。如果预测标签数据集或主数据集被拆分到多个文件中，则必须通过 `joinsource_name_or_index` 指定标识符列来联接这两个数据集。
+ **predicted\$1label\$1headers**：（可选）仅在指定 `predicted_label_dataset_uri` 时适用。包含预测标签数据集的列名称的字符串数组。除了预测标签标题外，`predicted_label_headers` 还可以包含标识符列的标题以联接预测标签数据集和主数据集。有关更多信息，请参阅以下对 `joinsource_name_or_index` 参数的描述。
+ **joinsource\$1name\$1or\$1index**：（可选）在执行内部连接时用作标识列的表格数据集中列的名称或基于零的索引。此列仅用作标识符。它不用于任何其他计算，例如偏差分析或特征归因分析。在以下情况下，需要 `joinsource_name_or_index` 的值：
+ 有多个输入数据集，任何一个都拆分到多个文件中。
+ 通过将 Clarify 处理作业设置为大于的值[InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)来激活分布式处理`1`。 SageMaker
+ **excluded\$1columns** -（可选）不能作为预测输入发送到模型的列名称或零基索引的数组。Ground Truth 标签和预测标签已自动排除在外。时间序列不支持此功能。
+ **probability\$1threshold** -（可选）一个浮点数，超过该浮点数将选择标签或对象。默认值为 `0.5`。C SageMaker larify 处理任务用于`probability_threshold`以下情况：
+ 在训练后的偏差分析中，如果模型是二进制分类器，则 `probability_threshold` 会将数值模型预测（概率值或得分）转换为二进制标签。大于阈值的得分将转换为 `1`；而小于或等于阈值的得分将转换为 `0`。
+ 在计算机视觉可解释性问题中，如果 model\$1type 为 **OBJECT\$1DETECTION**，则 `, probability_threshold` 会筛选掉检测到的置信度得分低于阈值的对象。
+ **label\$1values\$1or\$1threshold**：（可选）偏差分析所必需。标签值或阈值数组，表示 Ground Truth 的阳性结果和偏差指标的预测标签。更多信息，请参阅 [Amazon SageMaker 澄清偏见和公平条款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) 中的正标签值。如果标签是数字，则使用阈值作为下限来选择阳性结果。要针对不同的问题类型设置 `label_values_or_threshold`，请参阅以下示例：
+ 对于二进制分类问题，标签有两个可能的值：`0` 和 `1`。如果标签值 `1` 对在样本中观测到的人口统计群体有利，则 `label_values_or_threshold` 应设置为 `[1]`。
+ 对于多类分类问题，标签有三个可能的值：**bird**、**cat** 和 **dog**。如果后两者定义了偏差有利的人口统计群体，则 `label_values_or_threshold` 应设置为 `["cat","dog"]`。
+ 对于回归问题，标签值是连续的，范围从 `0` 到 `1`。如果一个大于 `0.5` 的值应将样本指定为具有阳性结果，则 `label_values_or_threshold` 应设置为 `0.5`。
+ **facet**：（可选）偏差分析所需的参数。分面对象数组，由偏差测量所依据的敏感属性组成。即使在不使用敏感属性的情况下对模型进行了训练，也可以使用分面来了解数据集和模型的偏差特征。更多信息，请参阅 [Amazon SageMaker 澄清偏见和公平条款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) 中的 **Facet**。每个分面对象都包含以下字段：
+ **name\$1or\$1index**：（可选）表格数据集中敏感属性列的名称或基于零的索引。如果已指定 `facet_dataset_uri`，则该索引是指分面数据集而不是主数据集。
+ **value\$1or\$1threshold**：（可选）如果 `facet` 为数字且 `label_values_or_threshold` 被用作选择敏感组的下限，则为必填项。） 分面值或阈值数组，表示偏差有利的敏感人口统计群体。如果分面数据类型为分类且未提供 `value_or_threshold`，则以每个唯一值（而不是所有值）为一组来计算偏差指标。要针对不同的 `facet` 数据类型设置 `value_or_threshold`，请参阅以下示例：
+ 对于二进制分面数据类型，特征有两个可能的值：`0` 和 `1`。如果要计算每个值的偏差指标，则 `value_or_threshold` 可以省略或设置为空数组。
+ 对于分类分面数据类型，特征有三个可能的值：**bird**、**cat** 和 **dog**。如果前两者定义了偏差有利的人口统计群体，则 `value_or_threshold` 应设置为 `["bird", "cat"]`。在本例中，数据集样本分为两个人口统计群体。优势群体的分面具有 **bird** 或 **cat** 值，而劣势群体的分面具有 **dog** 值。
+ 对于数值分面数据类型，特征值是连续的，范围从 `0` 到 `1`。例如，如果一个大于 `0.5` 的值应将样本指定为有利样本，则 `value_or_threshold` 应设置为 `0.5`。在本例中，数据集样本分为两个人口统计群体。优势群体中的分面具有大于 `0.5` 的值，而劣势群体中的分面具有小于或等于 `0.5` 的值。
+ **group\$1variable**：（可选）：表示偏置指标 [条件人口统计差异 (CDD)](clarify-data-bias-metric-cddl.md) 或 [预测标签中的条件人口统计差异 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) 所用子组的列名或零基索引。
+ **facet\$1dataset\$1uri**：（可选）仅当数据集类型为 `text/csv` 时适用。数据集的 S3 URI，该数据集包含用于偏差分析的敏感属性。即使在不使用敏感属性的情况下对模型进行了训练，也可以使用分面来了解数据集和模型的偏差特征。
**注意**
如果分面数据集或主数据集被拆分到多个文件中，则必须通过 `joinsource_name_or_index` 指定标识符列来联接这两个数据集。必须使用参数 `facet` 来标识分面数据集中的每个分面。
+ **facet\$1headers**：（可选）仅在指定 `facet_dataset_uri` 时适用。一个字符串数组，包含分面数据集的列名，以及用于连接分面数据集和主数据集的标识符列头，参阅 `joinsource_name_or_index`。
+ **time\$1series\$1data\$1config**：（可选）指定用于时间序列数据处理的配置。
+ **item\$1id**：字符串或零基整数索引。该字段用于查找共享输入数据集中的项目 ID。
+ **timestamp**：字符串或基于零的整数索引。该字段用于定位共享输入数据集中的时间戳。
+ **dataset\$1format**：可能的值是 `columns`、`item_records` 或 `timestamp_records`。该字段用于描述 JSON 数据集的格式，这是时间序列可解释性唯一支持的格式。
+ **target\$1time\$1series** — JMESPath 字符串或从零开始的整数索引。该字段用于定位共享输入数据集中的目标时间序列。如果该参数是字符串，那么除了 `dataset_format` 之外的所有其他参数都必须是字符串或字符串列表。如果该参数为整数，则除 `dataset_format` 外的所有其他参数都必须是整数或整数列表。
+ **related\$1time\$1series** —（可选）一个表达式数组。 JMESPath 该字段用于查找共享输入数据集中的所有相关时间序列（如果存在）。
+ **static\$1covariates** —（可选）一个表达式数组。 JMESPath 该字段用于定位共享输入数据集中的所有静态协变量字段（如果存在）。
有关示例，请参阅 [时间序列数据集配置示例](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex)。
+ **methods** - 一个对象，其中包含一个或多个分析方法及其参数。如果省略了任何方法，则既不用于分析，也不进行报告。
+ **pre\$1training\$1bias** - 如果要计算训练前偏差指标，则包括此方法。指标的详细说明见 [训练前偏差指标](clarify-measure-data-bias.md)。对象具有以下参数：
+ **methods** - 一个数组，其中包含以下列表中您要计算的任何训练前偏差指标。将 `methods` 设置为 **all** 可计算所有训练前偏差指标。例如，数组 `["CI", "DPL"]` 将计算**类别不平衡**和**标签比例差异**。
+ [类别不平衡 (CI)](clarify-bias-metric-class-imbalance.md) 的 `CI`
+ [标签比例差异 (DPL)](clarify-data-bias-metric-true-label-imbalance.md) 的 `DPL`
+ [Kullback-Leibler 分歧 (KL)](clarify-data-bias-metric-kl-divergence.md) 的 `KL`
+ [Jensen-Shannon 分歧 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) 的 `JS`
+ [Lp-范数 (LP)](clarify-data-bias-metric-lp-norm.md) 的 `LP`
+ [总变差距离 (TVD)](clarify-data-bias-metric-total-variation-distance.md) 的 `TVD`
+ [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) 的 `KS`
+ [条件人口统计差异 (CDD)](clarify-data-bias-metric-cddl.md) 的 `CDDL`
+ **post\$1training\$1bias** - 如果要计算训练后偏差指标，则包括此方法。指标的详细说明见 [训练后数据和模型偏差指标](clarify-measure-post-training-bias.md)。`post_training_bias` 对象具有以下参数。
+ **methods** - 一个数组，其中包含以下列表中您要计算的任何训练后偏差指标。将 `methods` 设置为 **all** 可计算所有训练后偏差指标。例如，数组 `["DPPL", "DI"]` 计算**预测标签中正比例的差异**和**差别影响**。可用的方法如下所示。
+ [预测标签中正比例的差异 (DPPL)](clarify-post-training-bias-metric-dppl.md) 的 `DPPL`
+ [差别影响 (DI)](clarify-post-training-bias-metric-di.md) 的 `DI`
+ [有条件录取的差异 (DCAcc)](clarify-post-training-bias-metric-dcacc.md) 的 `DCA`
+ [有条件拒绝差异 (DCR)](clarify-post-training-bias-metric-dcr.md) 的 `DCR`
+ [特异性差异 (SD)](clarify-post-training-bias-metric-sd.md) 的 `SD`
+ [查全率差异 (RD)](clarify-post-training-bias-metric-rd.md) 的 `RD`
+ [接受率差异 (DAR)](clarify-post-training-bias-metric-dar.md) 的 `DAR`
+ [拒绝率差异 (DRR)](clarify-post-training-bias-metric-drr.md) 的 `DRR`
+ [准确率差异 (AD)](clarify-post-training-bias-metric-ad.md) 的 `AD`
+ [平等对待 (TE)](clarify-post-training-bias-metric-te.md) 的 `TE`
+ [预测标签中的条件人口统计差异 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) 的 `CDDPL`
+ [反事实翻转测试 (FT)](clarify-post-training-bias-metric-ft.md) 的 `FT`
+ [广义熵 (GE)](clarify-post-training-bias-metric-ge.md) 的 `GE`
+ **shap** - 如果要计算 SHAP 值，则包括此方法。Cl SageMaker arify 处理作业支持内核 SHAP 算法。`shap` 对象具有以下参数。
+ **baseline**：（可选）SHAP 基准数据集，也称为背景数据集。表格数据集中的基准数据集或计算机视觉问题的其他要求如下。有关 SHAP 基准线的更多信息，请参阅 [SHAP 可解释性基准](clarify-feature-attribute-shap-baselines.md)
+ 对于**表格**数据集，`baseline` 可以是就地基准数据，也可以是基准文件的 S3 URI。如果`baseline`未提供，则 Clari SageMaker fy 处理作业通过对输入数据集进行聚类来计算基线。基准要求如下：
+ 格式必须与 `dataset_type` 指定的数据集格式相同。
+ 基准只能包含模型可以接受为输入的特征。
+ 基准数据集可以有一个或多个实例。基准实例的数量直接影响合成数据集的大小和作业运行时。
+ 如果已指定 `text_config`，则文本列的基准值是一个字符串，用于替换由 `granularity` 指定的文本单元。例如，一个常见的占位符是“[MASK]”，它用于表示缺失或未知的单词或文本段。
以下示例演示了如何为不同 `dataset_type` 参数设置就地基准数据：
+ 如果 `dataset_type` 为 `text/csv` 或 `application/x-parquet`，则模型接受四个数值特征，并且基准有两个实例。在本例中，如果一条记录的特征值全部为零，而另一条记录的特征值全部为一，则基准应设置为 `[[0,0,0,0],[1,1,1,1]]`，不带任何标题。
+ 如果 `dataset_type` 为 `application/jsonlines`，则 `features` 是四个数值特征值列表的关键。此外，在本例中，如果基准有一条全部为零值的记录，则 `baseline` 应为 `[{"features":[0,0,0,0]}]`。
+ 如果 `dataset_type` 为 `application/json`，则 `baseline` 数据集的结构和格式应与输入数据集相同。
+ 对于**计算机视觉**问题，`baseline` 可以是图像的 S3 URI，用于屏蔽输入图像中的特征（分段）。C SageMaker larify 处理任务加载蒙版图像并将其大小调整为与输入图像相同的分辨率。如果未提供基准，Cl SageMaker arify 处理作业会生成与输入图像相同分辨率的[白噪声](https://en.wikipedia.org/wiki/White_noise)掩模图像。
+ **features\$1to\$1explain** -（可选）用于计算 SHAP 值的特征列的字符串或零基索引数组。如果未提供 `features_to_explain`，则计算所有特征列的 SHAP 值。这些特征列不能包括标签列或预测标签列。`features_to_explain` 参数仅适用于包含数值列和类别列的表格数据集。
+ **num\$1clusters** -（可选）为计算基准数据集而将数据集分成的集群数。每个集群用于计算一个基准实例。如果未指定，C `baseline` lar SageMaker ify 处理作业将尝试通过将表格数据集划分为介于`1`和`12`之间的最佳聚类数来计算基线数据集。基准实例数直接影响 SHAP 分析的运行时。
+ **num\$1samples** -（可选）要在 Kernel SHAP 算法中使用的样本数。如果`num_samples`未提供，则 Cl SageMaker arify 处理任务会为您选择号码。样本数直接影响合成数据集的大小和作业运行时。
+ **seed** -（可选）一个整数，用于在 SHAP 解释器中初始化伪随机数生成器，以便为同一作业生成一致的 SHAP 值。如果未指定 seed，则每次运行同一作业时，模型输出的 SHAP 值可能会略有不同。
+ **use\$1logit** -（可选）一个布尔值，表示您希望将 logit 函数应用于模型预测。默认值为 `false`。如果 `use_logit` 为 `true`，则使用逻辑回归系数计算 SHAP 值，这些系数可以解释为对数几率比。
+ **save\$1local\$1shap\$1values** -（可选）一个布尔值，表示您希望将数据集中每条记录的局部 SHAP 值包含在分析结果中。默认值为 `false`。
如果将主数据集拆分到多个文件中或已激活分布式处理，则还要使用参数 `joinsource_name_or_index` 指定标识符列。标识符列和局部 SHAP 值保存在分析结果中。这样，您就可以将每条记录映射到其局部 SHAP 值。
+ **agg\$1method** -（可选）该方法用于将所有实例的局部 SHAP 值（每个实例的 SHAP 值）聚合为全局 SHAP 值（整个数据集的 SHAP 值）。默认值为 `mean_abs`。以下方法可用于聚合 SHAP 值。
+ **mean\$1abs** - 所有实例的绝对局部 SHAP 值的平均值。
+ **mean\$1sq** - 所有实例的局部 SHAP 平方值的平均值。
+ **median** - 所有实例的局部 SHAP 值的中位数。
+ **text\$1config**：自然语言处理可解释性所必需。如果要将文本列视为文本，则包括此配置，并且应为文本的各个单元提供解释。有关自然语言处理可解释性分析配置的示例，请参阅 [自然语言处理可解释性的分析配置](#clarify-analysis-configure-nlp-example)
+ **granularity** - 用于文本列分析的粒度单位。有效值为 `token`、`sentence` 或 `paragraph`。**每个文本单元都视为一个特征**，并计算每个单元的局部 SHAP 值。
+ **language** - 文本列的语言。有效值为 **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**。输入 `multi-language` 可混合使用多种语言。
+ **max\$1top\$1tokens** -（可选）基于全局 SHAP 值的主要令牌的最大数量。默认值为 `50`。一个令牌有可能在数据集中多次出现。Cl SageMaker arify 处理任务汇总每个令牌的 SHAP 值，然后根据其全局 SHAP 值选择排名靠前的代币。所选主要令牌的全局 SHAP 值包含在 analysis.json 文件的 `global_top_shap_text` 部分中。
+ 聚合的局部 SHAP 值。
+ **image\$1config** - 计算机视觉可解释性所必需。如果您的输入数据集由图像组成，并且您想在计算机视觉问题中分析这些图像的可解释性，则使用此配置。
+ **model\$1type** - 模型的类型。有效值包括：
+ `IMAGE_CLASSIFICATION` 表示图像分类模型。
+ `OBJECT_DETECTION` 表示对象检测模型。
+ **max\$1objects**：仅当 model\$1type 为 **OBJECT\$1DETECTION** 时适用。计算机视觉模型检测到的对象的最大数量（按置信度得分排序）。任何按置信度得分排名低于主要 max\$1objects 的对象都会被筛选掉。默认值为 `3`。
+ **context** - 仅在 model\$1type 为 **OBJECT\$1DETECTION** 时适用。它指示检测到的对象的边界框周围区域是否被基准图像掩盖。有效的值为 `0`（掩盖所有内容）或 `1`（不掩盖任何内容）。默认值为 1。
+ **iou\$1threshold** - 仅在 `model_type` 为 **OBJECT\$1DETECTION** 时适用。用于根据原始检测来评估预测值的最小交并比 (IOU) 指标。IOU 指标越高，说明预测的检测框与 Ground Truth 检测框之间的重叠程度越高。默认值为 `0.5`。
+ **num\$1segments** -（可选）一个整数，用于确定要在输入图像中标注的分段的大致数量。将图像的每个分段都视为一项特征，并计算每个分段的局部 SHAP 值。默认值为 `20`。
+ **segment\$1compactness** -（可选）一个整数，用于确定 [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) 方法生成的图像分段的形状和大小。默认值为 `5`。
+ **pdp** — 包括此方法来计算部分依赖图 (PDPs)。有关要生成的分析配置的示例 PDPs，请参见 [计算部分依赖图 (PDPs)](#clarify-analysis-configure-csv-example-pdp)
+ **features** - 如果未要求使用 `shap` 方法，则为必需项。用于计算和绘制 PDP 图的特征名称或索引的数组。
+ **top\$1k\$1features** -（可选）指定用于生成 PDP 图的主要特征的数量。如果`features`未提供，但请求了`shap`方法，则 Clarif SageMaker y 处理任务会根据其 SHAP 属性选择最重要的功能。默认值为 `10`。
+ **grid\$1resolution** - 要将数值范围划分成的存储桶的数量。这指定了 PDP 图的网格粒度。
+ **asymmetric\$1shapley\$1value**：如果要计算时间序列预测模型的可解释性指标，请使用此方法。Cl SageMaker arify 处理作业支持非对称 Shapley 值算法。非对称 Shapley 值是 Shapley 值的一种变体，它放弃了对称公理。如需了解更多信息，请参阅[非对称 Shapley 值：将因果知识纳入模型可解释性](https://arxiv.org/abs/1910.06358)。使用这些值来确定功能对预测结果的影响。非对称 Shapley 值考虑了预测模型作为输入的时间序列数据的时间依赖性。
该算法包括以下参数
+ **direction**：可用类型为 `chronological`、`anti_chronological` 和 `bidirectional`。时间结构可按时间顺序或反时间顺序浏览，或两者兼而有之。按时间顺序的解释是通过从第一个时间步骤开始迭代添加信息来建立的。反顺时针说明从最后一步开始向后添加信息。后一种阶次可能更适合存在追溯偏差的情况，例如预测股票价格。
+ **granularity**：要使用的解释粒度。可用的粒度选项如下所示：
+ **timewise**：`timewise` 解释成本低廉，只提供特定时间步长的信息，例如计算过去第 n 天的信息对未来第 m 天的预测有多大帮助。由此得出的归因无法单独解释静态协变量，也无法区分目标时间序列和相关时间序列。
+ **fine\$1grained**：`fine_grained` 解释的计算量更大，但能提供输入变量所有归因的完整细目。该方法计算近似解释，以减少运行时间。更多信息，请参阅以下参数 `num_samples`。
**注意**
`fine_grained` 解释只支持 `chronological` 命令。
+ **num\$1samples**：（可选）`fine_grained` 解释需要使用此参数。数字越大，近似值越精确。这个数字应与输入功能的维数成正比。经验法则是，如果结果不太大，可将该变量设为*（1 \$1 max（相关时间序列数，静态协变量数））^2*。
+ b@@ **as** eline —（可选）用于替换相应数据集（也称为背景数据） out-of-coalition值的基线配置。下面的代码段显示了基线配置的一个示例：
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ 对于目标时间序列或相关时间序列等时间数据，基线值类型可以是以下值之一：
+ `zero`— 所有 out-of-coalition值都替换为 0.0。
+ `mean`— 所有 out-of-coalition值都替换为时间序列的平均值。
+ 对于静态协变量，只有当模型请求使用静态协变量值时才应提供基线条目，在这种情况下，该字段为必填字段。应以列表形式提供每个项目的基准线。例如，如果数据集有两个静态协变量，基线配置可以如下：
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
在前面的示例中，**和**是数据集中的项目 ID。
+ **report** -（可选）使用此对象自定义分析报告。时间序列解释任务不支持此参数。作为分析结果的一部分，同一报告有三份副本：Jupyter 笔记本报告、HTML 报告和 PDF 报告。对象具有以下参数：
+ **name** - 报告文件的文件名。例如，如果 `name` 为 **MyReport**，则报告文件为 `MyReport.ipynb`、`MyReport.html` 和 `MyReport.pdf`。默认值为 `report`。
+ **title** -（可选）报告的标题字符串。默认值为 **SageMaker AI Analysis Report**。
+ **predictor** - 如果分析需要模型的预测结果，则为必需项。例如，当请求使用 `shap`、`asymmetric_shapley_value`、`pdp` 或 `post_training_bias` 方法，但预测标签没有作为输入数据集的一部分提供时。以下是要与 `predictor` 配合使用的参数：
+ **model\$1nam** e — 由 API 创建的 SageMaker AI 模型的名称。[CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)如果您指定 endpoint\$1name `model_name` 而不是 endpoint\$1name，则 Clarify 处理作业会创建一个具有模型名称的临时端点（称为**影子端点），并从该端点**获取预测。 SageMaker 计算完成后，作业会删除影子端点。如果模型是多模型的，则必须指定 `target_model` 参数。有关多模型终端节点的更多信息，请参阅 [多模型端点](multi-model-endpoints.md)。
+ **endpoint\$1name\$1prefix** -（可选）影子端点的自定义名称前缀。如果您提供 `model_name` 而不是 `endpoint_name`，则适用。例如，如果要根据端点名称限制对端点的访问，则提供 `endpoint_name_prefix`。前缀必须与[EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName)模式匹配，其最大长度为`23`。默认值为 `sm-clarify`。
+ **initial\$1instance\$1count** - 指定影子端点的实例数。如果您提供的是 model\$1name 而不是 endpoint\$1name，则为必需项。的值`initial_instance_count`可能与任务[InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)的值不同，但我们建议使用 1:1 的比例。
+ **instance\$1type** - 指定影子端点的实例类型。如果您提供的是 `model_name` 而不是 `endpoint_name`，则为必需项。例如，`instance_type` 可以设置为“ml.m5.large”。在某些情况下，为 `instance_type` 指定的值有助于缩短模型推理时间。例如，为了高效运行，自然语言处理模型和计算机视觉模型通常需要图形处理单元 (GPU) 实例类型。
+ **endpoint\$1nam** e — API 创建的 SageMaker AI 终端节点的名称。[CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)如果提供，则 `endpoint_name` 优先于 `model_name` 参数。使用现有端点可以缩短影子端点的引导时间，但也可能导致该端点的负载显著增加。此外，某些分析方法（如 `shap` 和 `pdp`）会生成发送到端点的合成数据集。这可能会导致端点的指标或捕获的数据受到合成数据的污染，从而无法准确反映实际使用情况。出于这些原因，通常不建议使用现有的生产端点进行 Clarif SageMaker y 分析。
+ **target\$1model** — 传递给 AI AP SageMaker I TargetModel [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)参数的字符串值。如果您的模型（由 model\$1name 参数指定）或端点（由 endpoint\$1name 参数指定）为多模型，则为必需项。有关多模型终端节点的更多信息，请参阅 [多模型端点](multi-model-endpoints.md)。
+ **custom\$1attributes** -（可选）一个字符串，允许您提供有关提交到端点的推理请求的其他信息。字符串值将传递给 SageMaker A [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)I API 的`CustomAttributes`参数。
+ **content\$1type** - 用于从端点获取预测的模型输入格式。如果提供，则将其传递给 A [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)I AP SageMaker I 的`ContentType`参数。
+ 对于计算机视觉可解释性，有效值为 **image/jpeg**、**image/png** 或 **application/x-npy**。如果未提供 `content_type`，则默认值为 **image/jpeg**。
+ 对于时间序列预测的可解释性，有效值为 **application/json**。
+ 对于其他类型的可解释性，有效值为 **text/csv**、**application/jsonlines,** 和 **application/json**。如果 `dataset_type` 为 **application/x-parquet**，则需要为 `content_type` 赋值。否则 `content_type` 默认为 `dataset_type` 参数的值。
+ **accept\$1type** - 模型输出格式，用于从端点获取预测。的`accept_type`值将传递给 SageMaker A [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax)I API 的`Accept`参数。
+ 对于计算机视觉可解释性，如果 `model_type` 为“OBJECT\$1DETECTION”，则 `accept_type` 默认为 **application/json**。
+ 对于时间序列预测的可解释性，有效值为 **application/json**。
+ 对于其他类型的可解释性，有效值为 **text/csv**、**application/jsonlines** 和 **application/json**。如果未提供 `accept_type` 的值，则 `accept_type` 默认为 `content_type` 参数的值。
+ **content\$1template** - 模板字符串，用于根据数据集记录构造模型输入。仅当 `content_type` 参数的值为 `application/jsonlines` 或 `application/json` 时，才需要使用参数 `content_template`。
当 `content_type` 参数为 `application/jsonlines` 时，模板应只有一个占位符（即 `$features`），该占位符将在运行时被特征列表替换。例如，如果模板是 `"{\"myfeatures\":$features}"`，并且如果某条记录有三个数字特征值（`1`、`2` 和 `3`），则该记录将作为 JSON 行 `{"myfeatures":[1,2,3]}` 发送到模型。
当 `content_type` 为 `application/json` 时，模板可以有占位符 `$record` 或 `records`。如果占位符为 `record`，则单条记录将被替换为一条应用了 `record_template` 中模板的记录。在这种情况下，一次只能向模型发送一条记录。如果占位符为 `$records`，则记录将替换为记录列表，每条记录都有一个由 `record_template` 提供的模板。
+ **record\$1template** - 模板字符串，用于根据数据集实例构造模型输入的每条记录。仅当 `content_type` 为 `application/json` 时，才需要和使用它。该模板字符串可能包含以下项之一：
+ 由特征值数组替换的占位符 `$features` 参数。附加的可选占位符可以替换 `$feature_names` 中的特征列标题名称。此可选占位符将替换为特征名称数组。
+ 正好是一个由键值对、特征名称和特征值替换的占位符 `$features_kvp`。
+ `headers` 配置中的一项特征。例如，用占位符语法 `"${A}"` 表示的特征名称 `A` 将替换为 `A` 的特征值。
`record_template` 的值将与 `content_template` 一起使用，以构造模型输入。下面的配置示例展示了如何使用内容和记录模板来构造模型输入。
在以下代码示例中，标题和特征定义如下。
+ ``headers`:["A", "B"]`
+ ``features`:[[0,1], [3,4]]`
示例模型输入如下所示。
```
{
"instances": [[0, 1], [3, 4]],
"feature_names": ["A", "B"]
}
```
用于构造前述示例模型输入的示例 `content_template` 和 `record_template` 参数值如下。
+ `content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"`
+ `record_template: "$features"`
在以下代码示例中，标题和特征定义如下。
```
[
{ "A": 0, "B": 1 },
{ "A": 3, "B": 4 },
]
```
用于构造前述示例模型输入的示例 ` content_template` 和 `record_template` 参数值如下。
+ `content_template: "$records"`
+ `record_template: "$features_kvp"`
用于构造前述示例模型输入的另一个代码示例如下。
+ `content_template: "$records"`
+ `record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"`
在以下代码示例中，标题和特征定义如下。
```
{ "A": 0, "B": 1 }
```
用于构造前述示例模型输入的示例 content\$1template 和 record\$1template 参数值如下。
+ `content_template: "$record"`
+ `record_template: "$features_kvp"`
有关更多示例，请参阅[时间序列数据的端点请求](clarify-processing-job-data-format-time-series-request-jsonlines.md)。
+ **label** —（可选）从零开始的整数索引或 JMESPath 表达式字符串，用于从模型输出中提取预测标签以进行偏差分析。如果模型是多类模型，并且 `label` 参数从模型输出中提取所有预测标签，则适用以下内容。时间序列不支持此功能。
+ 从模型输出中获取相应概率（或得分）时需要 `probability` 参数。
+ 选择得分最高的预测标签。
`label` 的值取决于 accept\$1type 参数的值，如下所示。
+ 如果 `accept_type` 为 **text/csv**，则 `label` 是模型输出中任何预测标签的索引。
+ 如果`accept_type`为**application/jsonlines**或**application/json**，`label`则为应用于模型输出以获取预测标签的 JMESPath 表达式。
+ **label\$1headers**：（可选）数据集中标签可取值的数组。如果要求进行偏差分析，则还需要 `probability` 参数才能从模型输出中获取相应的概率值（得分），并选择得分最高的预测标签。如果要求进行可解释性分析，则使用标签标题来美化分析报告。计算机视觉可解释性需要 `label_headers` 的值。例如，对于多类分类问题，如果标签有三个可能的值（即 **bird**、**cat** 和 **dog**），则 `label_headers` 应设置为 `["bird","cat","dog"]`。
+ **概率**-（可选）从零开始的整数索引或 JMESPath 表达式字符串，用于提取概率（分数）以进行可解释性分析（但不适用于时间序列可解释性），或者用于为偏差分析选择预测标签。`probability` 的值取决于 `accept_type` 参数的值，如下所示。
+ 如果 `accept_type` 为 **text/csv**，则 `probability` 为模型输出中概率（得分）的索引。如果未提供 `probability`，则将整个模型输出作为概率（得分）。
+ 如果`accept_type`是 JSON 数据（要**application/jsonlines**么是**application/json**），则`probability`应是一个用于从模型输出中提取概率（分数）的 JMESPath表达式。
+ **time\$1series\$1predictor\$1config**：（可选）仅用于时间序列可解释性。用于指示 Clari SageMaker fy 处理器如何从作为 S3 URI 传递的数据中正确解析数据。`dataset_uri`
+ **预测**-用于提取预测结果的 JMESPath 表达式。
## 示例分析配置文件
以下章节包含 CSV 格式、JSON Lines 格式以及自然语言处理 (NLP)、计算机视觉 (CV) 和时间序列 (TS) 可解释性数据的分析配置文件示例。
### CSV 数据集的分析配置
以下几个示例说明如何为 CSV 格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集有四个特征列和一个二进制标签列 `Target`。数据集的内容如下所示。标签值为 `1` 表示结果为阳性。数据集由`dataset`处理输入提供给 C SageMaker larify 作业。
```
"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
...
```
以下各节介绍如何计算训练前和训练后的偏差指标、SHAP 值以及显示特征重要性的 CSV 格式数据集特征重要性的部分依赖图 (PDPs)。
#### 计算所有训练前偏差指标
此示例配置显示如何衡量先前的示例数据集是否偏向于 `0` 值为 **Gender** 的样本。以下分析配置指示 Clar SageMaker ify 处理作业计算数据集的所有预训练偏差指标。
```
{
"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"
}
}
}
```
#### 计算所有训练后偏差指标
您可以在训练前计算训练前偏差指标。但是，必须拥有经过训练的模型，才能计算训练后偏差指标。以下示例输出来自以 CSV 格式输出数据的二进制分类模型。在此示例输出中，每行包含两列。第一列包含预测标签，第二列包含该标签的概率值。
```
0,0.028986845165491
1,0.825382471084594
...
```
以下配置示例指示 Clar SageMaker ify 处理作业使用数据集和模型输出中的预测来计算所有可能的偏差指标。在示例中，模型部署到 A SageMaker I 终端节点`your_endpoint`。
**注意**
在以下示例代码中，未设置参数 `content_type` 和 `accept_type`。因此，它们会自动使用参数 dataset\$1type 的值，即 `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
}
}
```
#### 计算 SHAP 值
以下示例分析配置指示作业计算 SHAP 值，将 `Target` 列指定为标签，将所有其他列指定为特征。
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
在本例中，省略了 SHAP `baseline` 参数，并且 `num_clusters` 参数的值为 `1`。这指示 Clari SageMaker fy 处理器计算一个 SHAP 基线样本。在本例中，概率设置为 `1`。这指示 Cl SageMaker arify 处理作业从模型输出的第二列中提取概率分数（使用从零开始的索引）。
#### 计算部分依赖图 (PDPs)
以下示例说明如何使用在分析报告中查看该`Income`功能的重要性 PDPs。报告参数指示 Clar SageMaker ify 处理任务生成报告。作业完成后，生成的报告将以 report.pdf 形式保存到 `analysis_result` 位置。`grid_resolution` 参数将特征值的范围划分为多个 `10` 存储桶。以下示例中指定的参数共同指示 Clarify 处理作业生成一份报告，其中包含 X 轴上`Income`有`10`分段的 PDP 图表。 SageMaker y 轴将显示 `Income` 对预测的边际影响。
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"pdp": {
"features": ["Income"],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
},
}
```
#### 计算偏差指标和特征重要性
您可以将前述配置示例中的所有方法合并到一个分析配置文件中，并通过一个作业进行计算。以下示例显示了合并所有步骤的分析配置。
在本例中，`probability` 参数设置为 `1`，表示概率包含在第二列中（使用零基索引）。但是，由于偏差分析需要预测标签，因此将 `probability_threshold` 参数设置为 `0.5` 以将概率得分转换为二进制标签。在本例中，部分依赖图 `pdp` 方法的 `top_k_features` 参数设置为 `2`。这指示 Cl SageMaker arify 处理作业为全局 SHAP 值最大的顶级`2`特征计算部分依赖图 (PDPs)。
```
{
"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
}
}
```
您可以使用`model_name`参数向 Clarify 处理任务提供 SageMaker AI 模型的名称，而不必将模型部署到终端节点。 SageMaker 以下示例说明如何指定名为 **your\$1model** 的模型。Cl SageMaker arify 处理任务将使用配置创建一个影子端点。
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### JSON 行数据集的分析配置
以下几个示例说明如何为 JSON 行格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集与上一节的数据相同，但它们采用 SageMaker AI JSON Lines 密集格式。每行都是一个有效的 JSON 对象。键 "Features" 指向特征值数组，键 "Label" 指向 Ground Truth 标签。数据集由 “数据集” 处理输入提供给 Clarify 作业。 SageMaker 有关 JSON 行的更多信息，请参阅[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}
...
```
以下各节介绍如何计算训练前和训练后的偏差指标、SHAP 值和部分依赖图 (PDPs)，这些图显示了 JSON Lines 格式的数据集的特征重要性。
#### 计算训练前偏差指标
指定标签、特征、格式和方法，以测量 `Gender` 值为 `0` 的训练前偏差指标。在以下示例中，`headers` 参数首先提供特征名称。最后提供标签名称。按照惯例，最后一个标题是标签标题。
该`features`参数设置为 JMESPath 表达式 “Features”，这样 Clarify 处理作业就可以从每条记录中提取特征数组。 SageMaker 该`label`参数设置为 JMESPath 表达式 “标签”，这样 Clari SageMaker fy 处理作业就可以从每条记录中提取真实情况标签。使用分面名称来指定敏感属性，如下所示。
```
{
"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"
}
}
}
```
#### 计算所有偏差指标
必须拥有经过训练的模型，才能计算训练后偏差指标。以下示例来自二进制分类模型，该模型以示例的格式输出 JSON 行数据。模型输出的每一行都是一个有效的 JSON 对象。键 `predicted_label` 指向预测标签，键 `probability` 指向概率值。
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
您可以将模型部署到名为的 A SageMaker I 终端节点`your_endpoint`。以下示例分析配置指示 Cl SageMaker arify 处理作业计算数据集和模型的所有可能偏差指标。在本例中，未设置参数 `content_type` 和 `accept_type`。因此，它们会自动设置为使用参数 dataset\$1type 的值，即 `application/jsonlines`。Cl SageMaker arify 处理作业使用`content_template`参数来组成模型输入，方法是将`$features`占位符替换为特征数组。
```
{
"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"
}
}
```
#### 计算 SHAP 值
由于 SHAP 分析不需要 Ground Truth 标签，因此省略了 `label` 参数。在本例中，也省略了 `headers` 参数。因此，Cl SageMaker arify 处理作业必须使用通用名称（如`column_0`或）`column_1`为功能标题和`label0`标签标题生成占位符。您可以为 `headers` 和 `label` 指定值，以提高分析结果的可读性。由于概率参数设置为 expr JMESPath ession`probability`，因此将从模型输出中提取概率值。以下是计算 SHAP 值的示例。
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### 计算部分依赖图 () PDPs
以下示例说明如何查看 PDP 上“Income”的重要性。在本例中，未提供特征标题。因此，`pdp` 方法的 `features` 参数必须使用零基索引来引用特征列的位置。`grid_resolution` 参数将特征值的范围划分为多个 `10` 存储桶。示例中的参数共同指示 Clarify SageMaker 处理作业生成一份报告，其中包含 x 轴上`Income`有`10`分段的 PDP 图表。y 轴将显示 `Income` 对预测的边际影响。
```
{
"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"
}
}
```
#### 计算偏差指标和特征重要性
您可以将之前的所有方法合并到一个分析配置文件中，并通过一个作业进行计算。以下示例显示了合并所有步骤的分析配置。在本例中，已设置 `probability` 参数。但由于偏差分析需要预测标签，因此将 `probability_threshold` 参数设置为 `0.5` 以将概率得分转换为二进制标签。在本例中，`pdp` 方法的 `top_k_features` 参数设置为 `2`。这指示 Cl SageMaker arify 处理作业计算 PDPs 具有最大全局 SHAP 值的顶级`2`特征。
```
{
"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"
}
}
```
### JSON 数据集的分析配置
以下几个示例说明如何为 JSON 格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集与上一节的数据相同，但它们采用 SageMaker AI JSON 密集格式。有关 JSON 行的更多信息，请参阅[JSONLINES 请求格式](cdf-inference.md#cm-jsonlines)。
整个输入请求都是有效的 JSON，其中外部结构是一个列表，每个元素都是一条记录的数据。在每条记录中，键 `Features` 指向特征值数组，键 `Label` 指向 Ground Truth 标签。数据集由`dataset`处理输入提供给 C SageMaker larify 作业。
```
[
{"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},
...
]
```
以下各节介绍如何计算训练前和训练后的偏差指标、SHAP 值和部分依赖图 (PDPs)，这些指标以 JSON Lines 格式显示数据集的特征重要性。
#### 计算训练前偏差指标
指定标签、特征、格式和方法，以测量 `Gender` 值为 `0` 的训练前偏差指标。在以下示例中，`headers` 参数首先提供特征名称。最后提供标签名称。对于 JSON 数据集，最后一个标题是标签标题。
`features`参数设置为提取 2D 数组或矩阵的 JMESPath 表达式。此矩阵中的每一行都必须包含每条记录的 `Features` 列表。该`label`参数设置为提取基本真相标签列表的 JMESPath 表达式。此列表中的每个元素都必须包含一条记录的标签。
使用分面名称来指定敏感属性，如下所示。
```
{
"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"
}
}
}
```
#### 计算所有偏差指标
必须拥有经过训练的模型，才能计算训练后偏差指标。以下代码示例来自二进制分类模型，该模型以示例的格式输出 JSON 数据。在该示例中，`predictions` 下的每个元素都是一条记录的预测输出。示例代码包含指向预测标签的键 `predicted_label` 和指向概率值的键 `probability`。
```
{
"predictions": [
{"predicted_label":0,"probability":0.028986845165491},
{"predicted_label":1,"probability":0.825382471084594},
...
]
}
```
您可以将模型部署到名为的 A SageMaker I 终端节点`your_endpoint`。
在以下示例中，未设置参数 `content_type` 和 `accept_type`。因此，`content_type` 和 `accept_type` 会自动设置为使用参数 `dataset_type` 的值，即 `application/json`。然后， SageMaker Clarify 处理作业使用`content_template`参数来撰写模型输入。
在以下示例中，通过将 `$records` 占位符替换为记录数组来组成模型输入。然后，`record_template` 参数组成每条记录的 JSON 结构，并将 `$features` 占位符替换为每条记录的特征数组。
以下示例分析配置指示 Cl SageMaker arify 处理作业计算数据集和模型的所有可能偏差指标。
```
{
"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"
}
}
```
#### 计算 SHAP 值
您无需为 SHAP 分析指定标签。在以下示例中，未指定 `headers` 参数。因此，Cl SageMaker arify 处理作业将使用通用名称（如`column_0`或）`column_1`为功能标题和`label0`标签标题生成占位符。您可以为 `headers` 和 `label` 指定值，以提高分析结果的可读性。
在以下配置示例中，概率参数设置为一个 JMESPath 表达式，该表达式从每条记录的每个预测中提取概率。以下是计算 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"
}
}
```
#### 计算部分依赖图 (PDPs)
以下示例向您展示了如何在中查看特征重要性 PDPs。在该示例中，未提供特征标题。因此，`pdp` 方法的 `features` 参数必须使用零基索引来引用特征列的位置。`grid_resolution` 参数将特征值的范围划分为多个 `10` 存储桶。
以下示例中的参数共同指示 Clarify 处理 SageMaker 作业生成一份报告，其中包含 X 轴上`Income`有`10`分段的 PDP 图表。y 轴显示 `Income` 对预测的边际影响。
以下配置示例显示了如何查看 `Income` on 的重要性 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"
}
}
```
#### 计算偏差指标和特征重要性
您可以将之前的所有配置方法合并到一个分析配置文件中，并通过一个作业进行计算。以下示例显示了合并所有步骤的分析配置。
在本例中，已设置 `probability` 参数。由于偏差分析需要预测标签，因此将 `probability_threshold` 参数设置为 `0.5`，用于将概率得分转换为二进制标签。在本例中，`pdp` 方法的 `top_k_features` 参数设置为 `2`。这指示 Cl SageMaker arify 处理作业计算 PDPs 具有最大全局 SHAP 值的顶级`2`特征。
```
{
"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"
}
}
```
### 自然语言处理可解释性的分析配置
以下示例显示了一个分析配置文件，该文件用于计算特征对自然语言处理 (NLP) 的重要性。在本例中，传入的数据集是 CSV 格式的表格数据集，包含一个二进制标签列和两个特征列，如下所示。数据集由`dataset`处理输入参数提供 SageMaker 给 Clarify 作业。
```
0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...
```
在本例中，在先前的数据集上训练了一个二进制分类模型。该模型接受 CSV 数据，并输出一个介于 `0` 和 `1` 之间的得分，如下所示。
```
0.491656005382537
0.569582343101501
...
```
该模型用于创建名为 “your\$1model” SageMaker 的人工智能模型。以下分析配置说明了如何使用模型和数据集运行按令牌分类的可解释性分析。`text_config` 参数激活 NLP 可解释性分析。`granularity` 参数表示分析应解析令牌。
在英语中，每个令牌都是一个单词。以下示例还说明了如何使用平均值为 4 的“Rating”提供就地 SHAP“baseline”实例。使用特殊的掩码令牌“[MASK]”来替换“Comments”中的令牌（单词）。此示例还使用 GPU 端点实例类型来加快推理速度。
```
{
"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"
}
}
```
### 计算机视觉可解释性的分析配置
以下示例显示了一个分析配置文件，该文件用于计算特征对计算机视觉的重要性。在本例中，输入数据集由 JPEG 图像组成。数据集由`dataset`处理输入参数提供 SageMaker 给 Clarify 作业。该示例说明如何使用 SageMaker 图像分类模型配置可解释性分析。在该示例中，一个名为 `your_cv_ic_model` 的模型经过训练，可对输入 JPEG 图像上的动物进行分类。
```
{
"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"]
}
}
```
有关映像分类的更多信息，请参阅 [图像分类- MXNet](image-classification.md)。
在此示例中，在相同`your_cv_od_model`的 JPEG 图像上训练[SageMaker 人工智能物体检测模型](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html)，以识别其上的动物。以下示例说明了如何为对象检测模型配置可解释性分析。
```
{
"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"]
}
}
```
### 时间序列预测模型可解释性的分析配置
下面的示例显示了计算时间序列 (TS) 功能重要性的分析配置文件。在本例中，输入数据集是一个 JSON 格式的时间序列数据集，包含一组动态和静态协变量功能。数据集由数据集处理输入参数提供给 Clarify 作业`dataset_uri`。 SageMaker
```
[
{
"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
},
]
```
下文将介绍如何使用非对称 Shapley 值算法计算 JSON 数据集预测模型的功能属性。
#### 计算时间序列预测模型的解释
下面的分析配置示例显示了用于计算时间序列预测模型解释的作业选项。
```
{
'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'
}
}
```
##### 时间序列可解释性配置
上例使用 `methods` 中的 `asymmetric_shapley_value` 来定义时间序列可解释性参数，如基线、方向、粒度和样本数。基线值是为所有三类数据设定的：相关时间序列、静态协变量和目标时间序列。这些字段指示 Clar SageMaker ify 处理器一次计算一件商品的特征归因。
##### 预测器配置
您可以使用 JMESPath 语法完全控制 Clarify 处理 SageMaker 器发送的有效载荷结构。在上例中，`predictor` 配置指示 Clarify 将记录聚合到 `'{"instances": $records}'` 中，每条记录都使用示例中为 `record_template` 提供的参数定义。请注意，`$start_time`、`$target_time_series`、`$related_time_series` 和 `$static_covariates` 是内部标记，用于将数据集值映射到端点请求值。
同样，`time_series_predictor_config` 中的属性 `forecast` 用于从端点响应中提取模型预测。例如，您的端点批处理响应可以如下：
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
假设您指定了以下时间序列预测器配置：
```
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
```
预测值解析如下：
```
[
[13.4, 3.6],
[23.0, 4.7],
[3.4, 5.6]
]
```
##### 数据配置
使用`time_series_data_config`属性指示 Clarif SageMaker y 处理器从作为 S3 URI 传递的数据中正确解析数据。`dataset_uri`
# 数据格式兼容性指南
本指南描述了与 Clarify 处理作业兼容的数据格式类型。 SageMaker 支持的数据格式类型包括文件扩展名、数据结构，以及对表格、映像和时间序列数据集的具体要求或限制。本指南还介绍如何检查您的数据集是否符合这些要求。
总体而言，Clarif SageMaker y 处理作业遵循输入-过程-输出模型来计算偏差指标和特征归因。有关详细信息，请参阅以下示例。
Clarif SageMaker y 处理作业的输入包括以下内容：
+ 要分析的数据集。
+ 分析配置。有关如何配置分析的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
在处理阶段，Clari SageMaker fy 会计算偏差指标和特征归因。C SageMaker larify 处理任务在后端完成以下步骤：
+ Cl SageMaker arify 处理任务解析您的分析配置并加载您的**数据集**。
+ 要计算训练后偏差指标和特征归因，该作业需要从模型中进行模型预测。**Cl SageMaker arify 处理任务会序列化您的数据，并将其作为**请求**发送到部署在 A SageMaker I 实时推理端点上的模型。**之后，Clari SageMaker fy 处理任务会从**响应**中提取预测。
+ C SageMaker larify 处理作业执行偏差和可解释性分析，然后输出结果。
有关更多信息，请参阅 [SageMaker 澄清处理任务的工作原理](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works)。
用于指定数据格式的参数取决于在处理流程中使用数据的位置，如下所示：
+ 对于**输入数据集**，请使用 `dataset_type` 参数指定格式或 MIME 类型。
+ 对于向端点发出的**请求**，请使用 `content_type` 参数指定格式。
+ 对于来自端点的**响应**，请使用 `accept_type` 参数指定格式。
输入数据集、向端点发出的请求以及来自端点的响应无需采用相同格式。例如，在满足以下条件的情况下，您可以使用带有 CSV **请求**负载和 JSON 行**响应**负载的 Parquet 数据集。
+ 您的分析得到正确配置。
+ 您的模型支持请求和响应格式。
**注意**
如果未提供`content_type`或`accept_type`未提供，则 Clarif SageMaker y 容器会推断出`content_type`和。`accept_type`
**Topics**
+ [表格数据](clarify-processing-job-data-format-tabular.md)
+ [映像数据要求](clarify-processing-job-data-format-image.md)
+ [时间序列数据](clarify-processing-job-data-format-time-series.md)
# 表格数据
表格数据是指可以加载到二维数据框中的数据。在数据框中，每行代表一条记录，每条记录都有一列或多列。每个数据框单元格内的值可以是数字、分类或文本数据类型。
## 表格数据集先决条件
在分析之前，您的数据集应该已经应用了任何必要的预处理步骤。这包括数据清理或特征工程。
您可以提供一个或多个数据集。如果您提供多个数据集，请使用以下方法在 Clarify 处理任务中 SageMaker 对其进行识别。
+ 使用[ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)命名配置`dataset`或分析配置`dataset_uri`来指定主数据集。有关 `dataset_uri` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md) 中的参数列表。
+ 使用分析配置文件中提供的 `baseline` 参数。SHAP 分析需要基准数据集。有关分析配置文件的更多信息（包括示例），请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
下表列出了支持的数据格式、其文件扩展名和 MIME 类型。
| 数据格式 | 文件扩展名 | MIME 类型 |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| JSON 行 | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | “application/x-parquet” |
以下几节介绍了 CSV、JSON 行和 Apache Parquet 格式的表格数据集示例。
### CSV 格式的表格数据集先决条件
Cl SageMaker arify 处理任务旨在加载 cs [v.excel 方言中的 CS](https://docs.python.org/3/library/csv.html#csv.excel) V 数据文件。但是它足够灵活，可以支持其他行终止符，包括 `\n` 和 `\r`。
为了兼容起见，提供给 Clarify 处理任务的 SageMaker 所有 CSV 数据文件都必须采用 UTF-8 编码。
如果您的数据集不包含标题行，请执行以下操作：
+ 将分析配置标签设置为索引 `0`。这意味着第一列是 Ground Truth 标签。
+ 如果设置了参数 `headers`，则将 `label` 设置为标签列标题以指示标签列的位置。所有其他列都指定为特征。
以下是不包含标题行的数据集示例。
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
如果您的数据包含标题行，请将参数 `label` 设置为索引 `0`。要指示标签列的位置，请使用 Ground Truth 标签标题 `Label`。所有其他列都指定为特征。
以下是包含标题行的数据集示例。
```
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
...
```
### JSON 格式的表格数据集先决条件
JSON 是一种灵活的格式，用于表示包含任何复杂程度的结构化数据。Cl SageMaker arify 对 JSON 的支持不限于任何特定格式，因此与 CSV 或 JSON 行格式的数据集相比，允许更灵活的数据格式。本指南介绍如何为 JSON 格式的表格数据设置分析配置。
**注意**
为确保兼容性，提供给 Clarify 处理任务的 SageMaker 所有 JSON 数据文件都必须采用 UTF-8 编码。
以下是输入数据的示例，其记录包含顶层键、特征列表和标签。
```
[
{"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},
...
]
```
先前输入示例数据集的示例配置分析应设置以下参数：
+ 该`label`参数应使用[JMESPath](https://jmespath.org/)表达式`[*].label`来提取数据集中每条记录的基本真相标签。该 JMESPath 表达式应生成标签列表，其中第 i 个标签对应于第 i 条记录。
+ `features`参数应使用 JMESPath表达式`[*].features`为数据集中的每条记录提取特征数组。该 JMESPath 表达式应生成一个二维数组或矩阵，其中第 i 行包含与第 i 条记录对应的特征值。
以下是输入数据的示例，其记录包含顶层键和嵌套键，嵌套键包含每条记录的特征和标签列表。
```
{
"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}}
]
}
```
先前输入示例数据集的示例配置分析应设置以下参数：
+ 该`label`参数使用[JMESPath](https://jmespath.org/)表达式`data[*].label`提取数据集中每条记录的真实情况标签。该 JMESPath 表达式应生成标签列表，其中第 i 个标签用于第 i 个记录。
+ 该`features`参数使用 JMESPath 表达式`data[*].features`为数据集中的每条记录提取要素数组。该 JMESPath 表达式应生成一个 2D 数组或矩阵，其中第 i 行包含第 i 条记录的特征值。
### JSON 行格式的表格数据集先决条件
JSON 行是一种用于表示结构化数据的文本格式，其中每行都是有效的 JSON 对象。目前 C SageMaker larify 处理作业仅支持 SageMaker AI 密集格式 JSON 行。为符合格式要求，一条记录的所有特征都应列在一个 JSON 数组中。有关 JSON 行的更多信息，请参阅[JSONLINES 请求格式](cdf-inference.md#cm-jsonlines)。
**注意**
为确保兼容性，提供给 Clarify 处理 SageMaker 任务的所有 JSON Lines 数据文件都必须采用 UTF-8 编码。
以下示例说明如何为包含**顶层键**和元素**列表**的记录设置分析配置。
```
{"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}
...
```
先前数据集示例的配置分析应按以下方式设置参数：
+ 要指示真实情况标签的位置，`label`应将参数设置为 JMESPath 表达式`label`。
+ 要指示要素数组的位置，`features`应将参数设置为 JMESPath 表达式`features`。
以下示例说明如何为包含**顶层键**和**嵌套键**（其中包含元素**列表**）的记录设置分析配置。
```
{"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}}
...
```
先前数据集示例的配置分析应按以下方式设置参数：
+ `label`应将参数设置为 JMESPath表达式`data.label`，以指示真实情况标签的位置。
+ `features`应将参数设置为 JMESPath表达式`data.features`以指示要素数组的位置。
### Parquet 格式的表格数据集先决条件
[Parquet](https://parquet.apache.org/) 是一种列式二进制数据格式。目前，Cl SageMaker arify 处理作业仅在处理实例数为时才支持加载 Parquet 数据文件`1`。
由于 SageMaker Clarify 处理作业不支持 Parquet 格式的端点请求或端点响应，因此您必须通过将分析配置参数设置为支持的格式`content_type`来指定端点请求的数据格式。有关更多信息，请参阅[分析配置文件](clarify-processing-job-configure-analysis.md)中的`content_type`。
Parquet 数据的列名必须格式化为字符串。使用分析配置 `label` 参数设置标签列名称以指示 Ground Truth 标签的位置。所有其他列都指定为特征。
# 表格数据的端点请求
为了获得训练后偏差分析和特征重要性分析的模型预测， SageMaker Clarify 处理作业将表格数据序列化为字节，并将其作为请求有效载荷发送到推理端点。此表格数据要么来自输入数据集，要么是生成的。如果是合成数据，则由解释者生成，用于 SHAP 分析或 PDP 分析。
请求负载的数据格式应由分析配置 `content_type` 参数指定。如果未提供该参数，则 Cl SageMaker arify 处理作业将使用该`dataset_type`参数的值作为内容类型。有关 `content_type` 或 `dataset_type` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
以下几节介绍了 CSV 和 JSON 行格式的端点请求示例。
## CSV 格式的端点请求
Cl SageMaker arify 处理任务可以将数据序列化为 CSV 格式（MIME 类型:`text/csv`）。下表列出了序列化请求负载的示例。
| 端点请求负载（字符串表示形式） | 评论 |
| --- | --- |
| '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 行格式
Cl SageMaker arify 处理任务可以将数据序列化为 SageMaker AI JSON Lines 密集格式（MIME 类型:`application/jsonlines`）。有关 JSON 行的更多信息，请参阅[JSONLINES 请求格式](cdf-inference.md#cm-jsonlines)。
要将表格数据转换为 JSON 数据，请为分析配置 `content_template` 参数提供模板字符串。有关 `content_template` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。下表列出了序列化 JSON 行请求负载的示例。
| 端点请求负载（字符串表示形式） | 评论 |
| --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 单条记录。在本例中，模板看起来像 `'{"data":{"features":$features}}' `，并且 `$features` 替换为特征列表 `[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' | 两个记录。 |
| '\$1"features":["This is a good product",5]\$1' | 单条记录。在本例中，模板看起来像 `'{"features":$features}'`，并且 \$1features 替换为特征列表 `["This is a good product",5]`。 |
| '\$1"features":["This is a good product",5]\$1\$1n\$1"features":["Bad shopping experience",1]\$1' | 两个记录。 |
## 端点请求采用 JSON 格式
Cl SageMaker arify 处理任务可以将数据序列化为任意 JSON 结构（MIME 类型:`application/json`）。为此，必须为分析配置 `content_template` 参数提供模板字符串。Clarify 处理 SageMaker 任务使用它来构造外部 JSON 结构。您还必须为 `record_template` 提供模板字符串，用于为每条记录构建 JSON 结构。有关 `content_template` 和 `record_template` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
**注意**
由于 `content_template` 和 `record_template` 都是字符串参数，因此 JSON 序列化结构中的任何双引号字符 (`"`) 都应在配置中注明为转义字符。例如，如果要在 Python 中对双引号进行转义，可以在 `content_template` 中输入以下内容。
```
"{\"data\":{\"features\":$record}}}"
```
下表列出了序列化 JSON 请求负载的示例，以及构造这些负载所需的相应 `content_template` 和 `record_template` 参数。
| 端点请求负载（字符串表示形式） | 评论 | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 一次单条记录。 | '\$1"data":\$1"features":\$1record\$1\$1\$1' | “\$1features” |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | 带有特征名称的多条记录。 | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | “\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | 多条记录，以及键值对。 | “\$1records" | “\$1features\$1kvp" |
| ‘\$1"A": 0, "B": 1\$1' | 一次单条记录，以及键值对。 | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "nested": \$1"B": 1\$1\$1' | 或者，对任意结构使用详细的 record\$1template。 | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# 表格数据的端点响应
在 Cl SageMaker arify 处理作业收到推理端点调用的响应后，它会反序列化响应有效负载并从中提取预测。使用分析配置 `accept_type` 参数指定响应负载的数据格式。如果未提供，则 C `accept_type` lari SageMaker fy 处理作业将使用 content\$1type 参数的值作为模型输出格式。有关 `accept_type`的更多信息，请参阅[分析配置文件](clarify-processing-job-configure-analysis.md)。
预测可以由用于偏差分析的预测标签或用于特征重要性分析的概率值（得分）组成。在 `predictor` 分析配置中，以下三个参数提取预测。
+ 参数 `probability` 用于定位端点响应中的概率值（得分）。
+ 参数 `label` 用于在端点响应中定位预测标签。
+ （可选）参数 `label_headers` 提供多类模型的预测标签。
以下准则适用于 CSV、JSON 行和 JSON 格式的端点响应。
## 端点响应采用 CSV 格式
如果响应负载采用 CSV 格式（MIME 类型:`text/csv`），则 Clarify 处理 SageMaker 任务会反序列化每行。然后，它使用分析配置中提供的列索引，从反序列化数据中提取预测。响应负载中的行必须与请求负载中的记录相匹配。
下表提供了不同格式和不同问题类型的响应数据的示例。只要可以根据分析配置提取预测，您的数据就可以与这些示例不同。
以下几节介绍了 CSV 格式的端点响应示例。
### 端点响应采用 CSV 格式，仅包含概率
下表是回归和二进制分类问题的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单条记录。 | '0.6' |
| 两条记录（结果位于一行，用逗号分隔）。 | '0.6,0.3' |
| 两条记录（结果分为两行）。 | '0.6\$1n0.3' |
在前面的示例中，端点输出预测标签的单个概率值（得分）。要使用索引提取概率并将其用于特征重要性分析，请将分析配置参数 `probability` 设置为列索引 `0`。如果使用 `probability_threshold` 参数将这些概率转换为二进制值，则也可以将这些概率用于偏差分析。有关 `probability_threshold`的更多信息，请参阅[分析配置文件](clarify-processing-job-configure-analysis.md)。
下表是多类问题的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 多类模型（三个类）的单条记录。 | '0.1,0.6,0.3' |
| 多类模型（三个类）的两条记录。 | '0.1,0.6,0.3\$1n0.2,0.5,0.3' |
在前面的示例中，端点输出概率（得分）列表。如果未提供索引，则会提取所有值并将其用于特征重要性分析。如果提供了分析配置参数 `label_headers`，然后， SageMaker Clarify 处理作业可以选择最大概率的标签标题作为预测标签，该标签可用于偏差分析。有关 `label_headers`的更多信息，请参阅[分析配置文件](clarify-processing-job-configure-analysis.md)。
### 端点响应采用 CSV 格式，仅包含预测标签
下表是回归和二进制分类问题的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单条记录 | '1' |
| 两条记录（结果位于一行，用逗号分隔） | '1,0' |
| 两条记录（结果分为两行） | '1\$1n0' |
在前面的示例中，端点输出预测标签而不是概率。将 `predictor` 配置的 `label` 参数设置为列索引 `0`，这样就可以使用索引提取预测标签并用于偏差分析。
### 端点响应采用 CSV 格式，包含预测标签和概率
下表是回归和二进制分类问题的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '1,0.6' |
| 两条记录 | '1,0.6\$1n0,0.3' |
在前面的示例中，端点先输出预测标签，然后输出其概率。将 `predictor` 配置的 `label` 参数设置为列索引 `0`，并将 `probability` 设置为列索引 `1` 以提取两个参数值。
### 端点响应采用 CSV 格式，包含预测标签和概率（多类）
可以将由 Amazon A SageMaker utopilot 训练的多类模型配置为输出预测标签和概率列表的字符串表示形式。以下示例表显示了一个来自模型的示例端点响应，该模型配置为输出 `predicted_label`、`probability`、`labels` 和 `probabilities`。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"' |
| 两个记录 | '"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]"' |
在前面的示例中，可以通过以下方式配置 Clarify 处理作业来提取预测值。 SageMaker
要进行偏差分析，可以将前面的示例配置为以下方式之一。
+ 将 `predictor` 配置的 `label` 参数设置为 `0`，以提取预测标签。
+ 将参数设置为 `2` 以提取预测标签，将 `probability` 设置为 `3` 以提取相应的概率。Clarify 处理作业可以通过识别概率值最高的标签来自动确定预测的标签。 SageMaker 参照前面的单条记录示例，该模型预测了三个标签：`cat`、`dog` 和 `fish`，对应的概率为 `0.1`、`0.6` 和 `0.3`。基于这些概率，预测标签为 `dog`，因为它的概率值最高，为 `0.6`。
+ 将 `probability` 设置为 `3` 以提取概率。如果`label_headers`提供，则 Clar SageMaker ify 处理作业可以通过识别概率值最高的标签标题来自动确定预测的标签。
要进行特征重要性分析，可以按以下方式配置前面的示例。
+ 将 `probability` 设置为 `3` 以提取所有预测标签的概率。然后，将计算所有标签的特征归因。如果客户未指定 `label_headers`，则预测标签将在分析报告中用作标签标题。
## 端点响应采用 JSON 行格式
如果响应负载采用 JSON 行格式（MIME 类型:`application/jsonlines`），则 Clarify 处理任务会 SageMaker 将每行反序列化为 JSON。然后，它使用分析配置中提供的 JMESPath 表达式从反序列化数据中提取预测。响应负载中的行必须与请求负载中的记录相匹配。下表显示了不同格式的响应数据的示例。只要可以根据分析配置提取预测，您的数据就可以与这些示例不同。
以下几节介绍了 JSON 行格式的端点响应示例。
### 端点响应采用 JSON 行格式，仅包含概率
下表是仅输出概率值（得分）的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"score":0.6\$1' |
| 两个记录 | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' |
在前面的示例中，将分析配置参数设置`probability`为 JMESPath 表达式 “score” 以提取其值。
### 端点响应采用 JSON 行格式，仅包含预测标签
下表是仅输出预测标签的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"prediction":1\$1' |
| 两个记录 | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
在前面的示例中，将预测变量配置的`label`参数设置为 expression JMESPath 。`prediction`然后，Cl SageMaker arify 处理任务可以提取预测的标签进行偏差分析。有关更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
### 端点响应采用 JSON 行格式，包含预测标签和概率
下表是输出预测标签及其得分的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"prediction":1,"score":0.6\$1' |
| 两个记录 | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
对于前面的示例，将`predictor`配置的`label`参数设置为 JMESPath 表达式 “预测” 以提取预测的标签。设置`probability`为 JMESPath 表达式 “分数” 以提取概率。有关更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
### 端点响应采用 JSON 行格式，包含预测标签和概率（多类）
下表是多类模型的端点响应示例，其输出如下：
+ 预测标签列表。
+ 概率，以及所选的预测标签及其概率。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' |
| 两个记录 | '\$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' |
在前面的示例中 SageMaker ，可以通过多种方式配置 Clarify 处理作业以提取预测。
要进行偏差分析，可以将前面的示例配置为以下方式**之一**。
+ 将`predictor`配置的`label`参数设置为 JMESPath 表达式 “predicted\$1label” 以提取预测的标签。
+ 将参数设置为 JMESPath 表达式 “predicted\$1labels” 以提取预测的标签。设置`probability`为 JMESPath 表达式 “概率” 以提取其概率。Cl SageMaker arify 作业通过识别概率值最高的标签来自动确定预测的标签。
+ 设置`probability`为 JMESPath 表达式 “概率” 以提取其概率。如果`label_headers`提供，则 Clar SageMaker ify 处理作业可以通过识别概率值最高的标签来自动确定预测的标签。
要进行特征重要性分析，请执行以下操作。
+ 设置`probability`为 JMESPath 表达式 “概率” 以提取所有预测标签的概率。然后，将计算所有标签的特征归因。
## 端点响应采用 JSON 格式
如果响应负载采用 JSON 格式（MIME 类型:`application/json`），则 Clarify 处理任务会 SageMaker 将整个有效负载反序列化为 JSON。然后，它使用分析配置中提供的 JMESPath 表达式从反序列化数据中提取预测。响应负载中的记录必须与请求负载中的记录相匹配。
以下几节介绍了 JSON 格式的端点响应示例。这几节包含一些表格，表中提供了不同格式和不同问题类型的响应数据的示例。只要可以根据分析配置提取预测，您的数据就可以与这些示例不同。
### 端点响应采用 JSON 格式，仅包含概率
下表是仅输出概率值（得分）的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '[0.6]' |
| 两个记录 | '[0.6,0.3]' |
在前面的示例中，响应负载中没有换行符，而是有一个 JSON 对象，其中包含一个得分列表，请求中的每条记录对应一个得分。将分析配置参数设置`probability`为 JMESPath 表达式 “[\$1]” 以提取值。
### 端点响应采用 JSON 格式，仅包含预测标签
下表是仅输出预测标签的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"predicted\$1labels":[1]\$1' |
| 两个记录 | '\$1"predicted\$1labels":[1,0]\$1' |
将`predictor`配置的`label`参数设置为 JMESPath 表达式 “predicted\$1labels”，然后 Clarif SageMaker y 处理作业可以提取预测的标签进行偏差分析。
### 端点响应采用 JSON 格式，包含预测标签和概率
下表是输出预测标签及其得分的端点响应示例。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '\$1"predictions":[\$1"label":1,"score":0.6\$1' |
| 两个记录 | ‘\$1"predictions":[\$1"label":1,"score":0.6\$1,\$1"label":0,"score":0.3\$1]\$1' |
在前面的示例中，将`predictor`配置的`label`参数设置为 JMESPath 表达式 “预测 [\$1] .label” 以提取预测的标签。设置`probability`为 JMESPath 表达式 “预测 [\$1] .score” 以提取概率。
### 端点响应采用 JSON 格式，包含预测标签和概率（多类）
下表是多类模型的端点响应示例，其输出如下：
+ 预测标签列表。
+ 概率，以及所选的预测标签及其概率。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个记录 | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1]' |
| 两个记录 | '[\$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]' |
可以通过多种方式配置 Clarify 处理作业以提取预测。 SageMaker
要进行偏差分析，可以将前面的示例配置为以下方式**之一**。
+ 将`predictor`配置的`label`参数设置为 JMESPath 表达式 “[\$1] .predicted\$1label” 以提取预测的标签。
+ 将参数设置为 JMESPath 表达式 “[\$1] .predicted\$1labels” 以提取预测的标签。设置`probability`为 JMESPath 表达式 “[\$1] .probercilities” 以提取其概率。Cl SageMaker arify 处理任务可以通过识别具有最高邻近值的标签来自动确定预测的标签。
+ 设置`probability`为 JMESPath 表达式 “[\$1] .probercilities” 以提取其概率。如果`label_headers`提供，则 Clar SageMaker ify 处理作业可以通过识别概率值最高的标签来自动确定预测的标签。
要进行特征重要性分析，`probability`请设置为 JMESPath 表达式 “[\$1] .probercilities” 以提取所有预测标签的概率。然后，将计算所有标签的特征归因。
# 预先检查表格数据的端点请求和响应
我们建议您将模型部署到 A SageMaker I 实时推理终端节点，然后向该终端节点发送请求。手动检查请求和响应，确保两者都符合[表格数据的端点请求](clarify-processing-job-data-format-tabular-request.md)部分和[表格数据的端点响应](clarify-processing-job-data-format-tabular-response.md)部分的要求。如果您的模型容器支持批处理请求，则可以从单个记录请求开始，然后尝试两条或更多记录。
以下命令显示如何使用 AWS CLI请求响应。已预先安装在 SageMaker Studio 和 SageMaker 笔记本实例中。 AWS CLI 要安装 AWS CLI，请按照本[安装指南](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
```
参数已定义，如下所示。
+ `$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 示例
上一节中的示例适用于 AWS CLI v2。以下发送到端点的请求示例和来自端点的响应示例使用 AWS CLI v1。
## CSV 格式的端点请求和响应
在以下代码示例中，请求由一条记录组成，响应是其概率值。
```
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
```
在以下代码示例中，请求由两条记录组成，响应包括其概率，这些概率用逗号分隔。
```
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
```
在前面的代码示例中，`--body` 中的 `$'content'` 表达式告诉命令将内容中的 `'\n'` 解释为换行符。响应输出如下。
```
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]"
```
## JSON 行格式的端点请求和响应
在以下代码示例中，请求由一条记录组成，响应是其概率值。
```
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]}
```
## 混合格式的端点请求和响应
在以下代码示例中，请求采用 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
```
在以下代码示例中，请求采用 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
```
在前面的代码示例中，响应输出如下。
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# 映像数据要求
SageMaker 澄清处理作业为解释图像提供支持。本主题提供对图像数据的数据格式要求。有关处理映像数据的信息，请参阅 [分析图像数据以实现计算机视觉可解释性](clarify-processing-job-run.md#clarify-processing-job-run-cv)。
图像数据集包含一个或多个图像文件。要识别 Clarify SageMaker 处理任务的输入数据集，请将[ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs)命名`dataset`或分析配置`dataset_uri`参数设置为图像文件的 Amazon S3 URI 前缀。
下表列出了支持的图像文件格式和文件扩展名。
| 图像格式 | 文件扩展名 |
| --- | --- |
| JPEG | jpg、jpeg |
| PNG | png |
将分析配置 `dataset_type` 参数设置为 **application/x-image**。由于该类型不是特定的图像文件格式，因此将使用 `content_type` 来决定图像文件的格式和扩展名。
Cl SageMaker arify 处理任务将每个图像文件加载到三维[NumPy数组](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html)中以进行进一步处理。这三个维度包括每个像素的高度、宽度和 RGB 值。
## 端点请求格式
Cl SageMaker arify 处理任务将图像的原始 RGB 数据转换为兼容的图像格式，例如 JPEG。它会在将数据发送到端点进行预测之前执行此操作。支持的图像格式如下。
| 数据格式 | MIME 类型 | 文件扩展名 |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg、jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | 以上全部 |
使用分析配置参数 `content_type` 指定请求负载的数据格式。如果未提供 `content_type`，则数据格式默认为 `image/jpeg`。
## 端点响应格式
收到推理端点调用的响应后，Clarify 处理任务会 SageMaker 反序列化响应有效负载，然后从中提取预测。
### 图像分类问题
响应负载的数据格式应由分析配置参数 accept\$1type 指定。如果未提供 `accept_type`，则数据格式默认为 `application/json`。支持的格式与表格数据部分中**表格数据的端点响应**中描述的格式相同。
[使用图像分类算法进行推理](image-classification.md#IC-inference)有关 SageMaker 人工智能内置图像分类算法的示例，该算法接受单个图像，然后返回一个概率值（分数）数组，每个概率值对应一个类别。
如下表所示，当 `content_type` 参数设置为 `application/jsonlines` 时，响应将是一个 JSON 对象。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个图像 | '\$1"prediction":[0.1,0.6,0.3]\$1' |
在前面的示例中，将`probability`参数设置为 JMESPath 表达式 “预测” 以提取分数。
将 `content_type` 设置为 `application/json` 时，响应将是一个 JSON 对象，如下表所示。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个图像 | '[0.1,0.6,0.3]' |
在前面的示例中，设置`probability`为 JMESPath 表达式 “[\$1]” 以提取数组的所有元素。在前面的示例中，提取了 [`0.1, 0.6, 0.3]`。或者，如果跳过设置 `probability` 配置参数，则还会提取数组的所有元素。这是因为整个负载都被反序列化为预测。
### 对象检测问题
分析配置 `accept_type` 默认为 `application/json`，唯一支持的格式是对象检测推理格式。有关响应格式的更多信息，请参阅 [响应格式](object-detection-in-formats.md#object-detection-recordio)。
下表是输出数组的端点响应示例。数组的每个元素都是一个值数组，其中包含检测到的对象的类索引、置信度得分和边界框坐标。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个图像（一个对象） | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| 单个图像（两个对象） | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
下表是输出 JSON 对象（其中的键指向数组）的端点响应示例。将分析配置 `probability` 设置为键 "prediction" 以提取值。
| 端点请求负载 | 端点响应负载（字符串表示形式） |
| --- | --- |
| 单个图像（一个对象） | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| 单个图像（两个对象） | '\$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' |
## 预先检查图像数据的端点请求和响应
我们建议您将模型部署到 A SageMaker I 实时推理终端节点，然后向该终端节点发送请求。手动检查请求和响应。确保两者都符合**图像数据的端点请求**部分和**图像数据的端点响应**部分中的要求。
以下两个代码示例说明了如何发送请求并检查图像分类问题和对象检测问题的响应。
### 图像分类问题
以下示例代码指示端点读取 PNG 文件，然后对其进行分类。
```
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
```
在前面的代码示例中，响应输出如下。
```
[0.1,0.6,0.3]
```
### 对象检测问题
以下示例代码指示端点读取 JPEG 文件，然后检测其中的对象。
```
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
```
在前面的代码示例中，响应输出如下。
```
{"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]]}
```
# 时间序列数据
时间序列数据是指可载入三维数据框架的数据。在框架中，每个时间戳的每一行都代表一条目标记录，而每条目标记录都有一个或多个相关列。每个数据框单元格内的值可以是数字、分类或文本数据类型。
## 时间序列数据集的先决条件
在分析之前，完成必要的预处理步骤来准备数据，如数据清理或特征工程。您可以提供一个或多个数据集。如果您提供多个数据集，请使用以下方法之一将其提供给 Clarif SageMaker y 处理作业：
+ 使用[ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html)命名配置`dataset`或分析配置`dataset_uri`来指定主数据集。有关 `dataset_uri` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md) 中的参数列表。
+ 使用分析配置文件中提供的 `baseline` 参数。如果存在，`static_covariates` 需要基线数据集。有关分析配置文件的更多信息（包括示例），请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
下表列出了支持的数据格式、其文件扩展名和 MIME 类型。
| 数据格式 | 文件扩展名 | MIME 类型 |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
JSON 是一种灵活的格式，可以表示结构化数据的任何复杂程度。如表所示，Clar SageMaker ify 支持格式`item_records``timestamp_records`、和`columns`。
## 时间序列数据集配置示例
本节将向您展示如何使用 `time_series_data_config` 为 JSON 格式的时间序列数据设置分析配置。假设有一个数据集，其中包含两个项目，每个项目都有一个时间戳 (t)、目标时间序列 (x)、两个相关时间序列 (r) 和两个静态协变量 (u)，具体如下：
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
根据 `dataset_format` 的不同，您可以用三种不同的方式使用 `time_series_data_config` 对数据集进行编码。下文将介绍每种方法。
### 当 `dataset_format` 为 `columns` 时的时间序列数据配置
下面的示例使用了 `dataset_format` 的 `columns` 值。下面的 JSON 文件代表了前面的数据集。
```
{
"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
}
```
请注意，`ids` 字段中的项目 ID 是重复的。`time_series_data_config` 的正确实现如下所示：
```
"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"
}
```
### 当 `dataset_format` 为 `item_records` 时的时间序列数据配置
下面的示例使用了 `dataset_format` 的 `item_records` 值。下面的 JSON 文件代表了数据集。
```
[
{
"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}
]
}
]
```
每个项目在 JSON 中都表示为一个单独的条目。以下片段显示了相应的`time_series_data_config`（使用 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"
}
```
### 当 `dataset_format` 为 `timestamp_record` 时的时间序列数据配置
下面的示例使用了 `dataset_format` 的 `timestamp_record` 值。下面的 JSON 文件代表了前面的数据集。
```
[
{"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},
]
```
JSON 的每个条目代表一个时间戳，并对应一个项目。实施 `time_series_data_config` 如下所示：
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# 时间序列数据的端点请求
Cl SageMaker arify 处理任务将数据序列化为任意 JSON 结构（MIME 类型:`application/json`）。为此，必须为分析配置 `content_template` 参数提供模板字符串。Clarify 处理 SageMaker 任务使用它来构造提供给您的模型的 JSON 查询。 `content_template`包含数据集中的一条或多条记录。您还必须为 `record_template` 提供模板字符串，用于构建每条记录的 JSON 结构。然后将这些记录插入 `content_template`。有关 `content_type` 或 `dataset_type` 的更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
**注意**
由于 `content_template` 和 `record_template` 是字符串参数，所以 JSON 序列化结构中任何属于该结构的双引号字符（“）都应该在您的配置中作为转义字符来处理。例如，如果要在 Python 中转义双引号，可以为 `content_template` 输入以下值：
```
'$record'
```
下表列出了序列化 JSON 请求有效载荷的示例，以及构建它们所需的相应 `content_template` 和 `record_template` 参数。
| 使用案例 | 端点请求负载（字符串表示形式） | content\$1template | record\$1template |
| --- | --- | --- | --- |
| 每次单条记录 | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| 带 `$related_time_series` 和 `$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}'` |
| 多条记录 | `{"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}'` |
| 带 `$related_time_series` 和 `$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}'` |
# 时间序列数据的端点响应
Clar SageMaker ify 处理任务将整个有效负载反序列化为 JSON。然后，它使用分析配置中提供的 JMESPath 表达式从反序列化数据中提取预测。响应负载中的记录必须与请求负载中的记录相匹配。
下表是一个只输出平均预测值的端点响应示例。[分析配置](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters)中`predictor`字段中`forecast`使用的值应作为 JMESPath 表达式提供，以查找处理作业的预测结果。
| 端点请求负载 | 端点响应负载（字符串表示形式） | JMESPath 分析配置中的预测表达式 |
| --- | --- | --- |
| 单条记录示例。配置应为 `TimeSeriesModelConfig(forecast="prediction.mean")`，以便正确提取预测结果。 | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| 多条记录。 AWS DeepAR 端点响应。 | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# 预先检查时间序列数据的端点请求和响应
建议您将模型部署到 A SageMaker I 实时推理终端节点并向该终端节点发送请求。手动检查请求和响应，确保两者都符合 [时间序列数据的端点请求](clarify-processing-job-data-format-time-series-request-jsonlines.md) 和 [时间序列数据的端点响应](clarify-processing-job-data-format-time-series-response-json.md) 部分的要求。如果您的模型容器支持批量请求，您可以从单个记录请求开始，然后尝试两个或更多记录。
以下命令演示了如何使用 AWS CLI请求响应。已预先安装在 Studio 和 SageMaker 笔记本实例中。 AWS CLI 要安装 AWS CLI，请按照[安装指南](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
```
参数已定义，如下所示：
+ \$1ENDPOINT NAME：端点名称。
+ \$1CONTENT\$1TYPE：请求的 MIME 类型（模型容器输入）。
+ \$1ACCEPT\$1TYPE：响应（模型容器输出）的 MIME 类型。
+ \$1REQUEST\$1DATA：请求的有效载荷字符串。
+ \$1CLI\$1BINARY\$1FORMAT：命令行界面 (CLI) 参数的格式。对于 AWS CLI v1，此参数应保留为空。对于 v2，此参数应设置为 `--cli-binary-format raw-in-base64-out`。
**注意**
AWS CLI 默认情况下，v2 将二进制参数作为 base64 编码的字符串传递。以下往返终端节点的请求和响应示例使用 AWS CLI v1。
------
#### [ Example 1 ]
在以下代码示例中，请求由单个记录组成。
```
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
```
以下代码片段展示了相应的响应输出。
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
在下面的代码示例中，请求包含两条记录。
```
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
```
响应输出如下：
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------
# 运行 Cl SageMaker arify 处理作业以实现偏见分析和可解释性
要使用 SageMaker Clarify 分析您的数据和模型的偏差和可解释性，您必须配置 Clarify 处理 SageMaker 作业。本指南介绍如何使用 SageMaker Python SDK API 配置任务输入、输出、资源和分析配置`SageMakerClarifyProcessor`。
该 API 充当 AI `CreateProcessingJob` AP SageMaker I 的高级封装器。它隐藏了设置 Clarify 处理任务所涉及的 SageMaker 许多细节。设置作业的详细信息包括检索 Clarify SageMaker 容器镜像 URI 和生成分析配置文件。以下步骤向您展示如何配置、初始化和启动 Clarif SageMaker y 处理作业。
**使用 API 配置 SageMaker Clarify 处理作业**
1. 为作业配置的每个部分定义配置对象。这些部分可包括以下内容：
+ 输入数据集和输出位置:[DataConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.DataConfig).
+ 要分析的模型或终点:[ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig).
+ 偏差分析参数:[BiasConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.BiasConfig).
+ SHapley 加法解释 (SHAP) 分析参数:[SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig).
+ 非对称 Shapley 值分析参数（仅适用于时间序列）：。[AsymmetricShapleyValueConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.AsymmetricShapleyValueConfig)
Clarify SageMaker 处理作业的配置对象因数据格式和用例的不同类型而异。表格数据的配置示例，包括 [CSV](#clarify-processing-job-run-tabular-csv) 和 [JSON Lines](#clarify-processing-job-run-tabular-jsonlines) 格式、([NLP](#clarify-processing-job-run-tabular-nlp))、[computer vision](#clarify-processing-job-run-cv) (CV) 和时间序列 (TS) 问题，已在以下部分中提供。
1. 创建 `SageMakerClarifyProcessor` 对象并使用指定作业资源的参数对其进行初始化。这些资源包括要使用的计算实例数量等参数。
以下代码示例演示如何创建 `SageMakerClarifyProcessor` 对象并指示其使用一个 `ml.c4.xlarge` 计算实例进行分析。
```
from sagemaker import clarify
clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=1,
instance_type='ml.c4.xlarge',
sagemaker_session=session,
)
```
1. 使用您的用例的配置[SageMakerClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor.run)对象调用对象的特定运行方法以启动作业。这些运行方法包括：
+ `run_pre_training_bias`
+ `run_post_training_bias`
+ `run_bias`
+ `run_explainability`
+ `run_bias_and_explainability`
此 `SageMakerClarifyProcessor` 在后台处理多项任务。这些任务包括检索 Clarify 容器镜像通用资源标识符 (URI)、根据提供的配置对象撰写分析配置文件、将文件上传到 Amazon S3 存储桶以及[配置 Clarify 处理](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)任务。 SageMaker SageMaker
以下可扩展章节展示了如何计算**训练前**和**训练后偏差指标**、**SHAP 值**和**部分依赖图** (PDPs)。这些章节显示了这些数据类型的特征重要性：
+ CSV 格式或 JSON 行格式的表格数据集
+ 自然语言处理 (NLP) 数据集
+ 计算机视觉数据集
可扩展部分提供了使用 **Spark** 通过分布式训练运行 parallel Clarify 处理作业的指南。 SageMaker
## 分析 CSV 格式的表格数据
以下几个示例说明如何为 CSV 格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集有四个特征列和一个二进制标签列 `Target`。数据集的内容如下所示。标签值为 `1` 表示结果为阳性。
```
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
...
```
此 `DataConfig` 对象指定输入数据集以及输出的存储位置。`s3_data_input_path` 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 Clarif SageMaker y 处理任务会以递归方式收集位于该前缀下的所有 Amazon S3 文件。的值`s3_output_path`应为 S3 URI 前缀以保存分析结果。 SageMaker AI 在编译`s3_output_path`时使用，不能取运行时使用的 A SageMaker I Pipeline 参数、属性`ExecutionVariable`、表达式或的值。以下代码示例说明如何为前述示例输入数据集指定数据配置。
```
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,
)
```
### 如何计算 CSV 数据集的所有训练前偏差指标
以下代码示例说明如何配置 `BiasConfig` 对象，以测量前述示例输入对 `Gender` 值为 `0` 的样本的偏差。
```
bias_config = clarify.BiasConfig(
label_values_or_threshold=[1],
facet_name='Gender',
facet_values_or_threshold=[0],
)
```
以下代码示例说明如何使用 run 语句启动 Clarify 处理作业，该作业计算输入数据集的所有[预训练偏差指标](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html)。 SageMaker
```
clarify_processor.run_pre_training_bias(
data_config=data_config,
data_bias_config=bias_config,
methods="all",
)
```
或者，您可以通过向 methods 参数分配训练前偏差指标列表来选择要计算的指标。例如，`methods="all"`替换为`methods=["CI", "DPL"]`会指示 Cl SageMaker arify 处理器仅计算[类别不平衡](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html)和[标签比例差异](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-data-bias-metric-true-label-imbalance.html)。
### 如何计算 CSV 数据集的所有训练后偏差指标
您可以在训练前计算训练前偏差指标。但是，要计算[训练后偏差指标](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-post-training-bias.html)，必须拥有经过训练的模型。以下示例输出来自以 CSV 格式输出数据的二进制分类模型。在此示例输出中，每行包含两列。第一列包含预测标签，第二列包含该标签的概率值。
```
0,0.028986845165491
1,0.825382471084594
...
```
在以下示例配置中，`ModelConfig`对象指示作业将 SageMaker AI 模型部署到临时端点。该端点使用一个 `ml.m4.xlarge` 推理实例。由于未设置参数 `content_type` 和 `accept_type`，因此它们会自动使用参数 `dataset_type` 的值，即 `text/csv`。
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
)
```
以下配置示例使用标签索引为 `0` 的 `ModelPredictedLabelConfig` 对象。这会指示 C SageMaker larify 处理作业在模型输出的第一列中找到预测的标签。在本例中，处理作业使用零基索引。
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label=0,
)
```
结合前面的配置示例，以下代码示例启动了 Clarif SageMaker y 处理作业，以计算训练后的所有偏差指标。
```
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",
)
```
同样，您可以通过向 `methods` 参数分配训练后偏差指标列表来选择要计算的指标。例如，将 `methods=“all”` 替换为 `methods=["DPPL", "DI"]`，便可仅计算[预测标签中正比例的差异](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-dppl.html)和[差别影响](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-di.html)。
### 如何计算 CSV 数据集的所有偏差指标
以下配置示例显示了如何在一个 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",
)
```
有关如何在 SageMaker Studio Classic 中运行 Clari SageMaker fy 处理作业以检测偏见的说明的示例笔记本，请参阅使用 Clarify 实现[公平性和可 SageMaker 解释性](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)。
### 如何计算 CSV 数据集的 SHAP 值
SageMaker Clarify 使用 [Kernel](https://arxiv.org/abs/1705.07874) sHap 算法提供特征归因。 SHAP分析需要概率值或分数而不是预测标签，因此此`ModelPredictedLabelConfig`对象具有概率指数`1`。这指示 Cl SageMaker arify 处理作业从模型输出的第二列中提取概率分数（使用从零开始的索引）。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=1,
)
```
`SHAPConfig` 对象提供 SHAP 分析参数。在本例中，省略了 SHAP `baseline` 参数，并且 `num_clusters` 参数的值为 `1`。这指示 Clari SageMaker fy 处理器根据对输入数据集进行聚类计算一个SHAP基线样本。如果要选择基准数据集，请参阅 [SHAP 可解释性基准](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html)。
```
shap_config = clarify.SHAPConfig(
num_clusters=1,
)
```
以下代码示例启动 Clari SageMaker fy 处理任务来计算SHAP值。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=shap_config,
)
```
有关如何在 SageMaker Studio Classic 中运行 Clari SageMaker fy 处理作业以计算SHAP值的说明的示例笔记本，请参阅使用 Clarify 实现[公平性和可 SageMaker 解释性](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)。
### 如何计算 CSV 数据集的部分依赖图 (PDPs)
PDPs 显示了在所有其他特征保持不变的情况下，预测的目标响应对一个或多个相关输入特征的依赖性。PDP 中的向上倾斜线或曲线表示目标特征和输入特征之间的关系为正相关，陡度表示关系的强度。向下倾斜线或曲线表示如果输入特征减少，目标变量就会增加。直观地说，您可以将部分依赖性解释为目标变量对每个相关输入特征的响应。
以下配置示例用于使用`PDPConfig`对象指示 Clari SageMaker fy 处理作业计算该`Income`功能的重要性。
```
pdp_config = clarify.PDPConfig(
features=["Income"],
grid_resolution=10,
)
```
在前面的示例中，`grid_resolution` 参数将 `Income` 特征值的范围划分为多个 `10` 存储桶。Cl SageMaker arify 处理作业将生成PDPs，用于在 x 轴上`Income`拆分为多个分`10`段。y 轴将显示 `Income` 对目标变量的边际影响。
以下代码示例启动 Clari SageMaker fy 处理任务进行计算PDPs。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=pdp_config,
)
```
有关如何在 SageMaker Studio Classic 中运行 Clarify 处理作业进行计算的说明的示例笔记本PDPs，请参阅使用 Clarify [进行 SageMaker 可解释性——部分依赖图 (PDP)](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb)。 SageMaker
### 如何同时计算 CSV 数据集的 SHAP 值和 PDPs
您可以在单个 SageMaker Clarify 处理作业PDPs中计算这两个SHAP值。在以下配置示例中，新 `PDPConfig` 对象的 `top_k_features` 参数设置为 `2`。这会指示 C SageMaker larify 处理作业计算PDPs具有最大全局SHAP值`2`的特征。
```
shap_pdp_config = clarify.PDPConfig(
top_k_features=2,
grid_resolution=10,
)
```
以下代码示例启动 Clar SageMaker ify 处理任务来计算两个SHAP值和PDPs。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=[shap_config, shap_pdp_config],
)
```
## 分析 JSON 行格式的表格数据
以下示例说明如何为 > SageMaker AI JSON Lines 密集格式的表格数据集配置偏见分析和可解释性分析。请参阅[JSONLINES 请求格式](cdf-inference.md#cm-jsonlines)了解更多信息。在这些示例中，传入的数据集与上一节的数据相同，但采用 JSON 行格式。每行都是一个有效的 JSON 对象。键 `Features` 指向特征值数组，键 `Label` 指向 Ground Truth 标签。
```
{"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}
...
```
在以下配置示例中，`DataConfig` 对象指定了输入数据集以及输出的存储位置。
```
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,
)
```
在前面的配置示例中，将 features 参数设置为[JMESPath](https://jmespath.org/)表达式，`Features`这样 Clarify 处理作业就可以从每条记录中提取特征数组。 SageMaker 该`label`参数设置为 expr JMESPath ession，`Label`这样 Clarify 处理作业就可以从每条记录中提取基本真相标签。 SageMaker `s3_data_input_path` 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 Clarif SageMaker y 处理任务会以递归方式收集位于该前缀下的所有 S3 文件。的值`s3_output_path`应为 S3 URI 前缀以保存分析结果。 SageMaker AI 在编译`s3_output_path`时使用，不能取运行时使用的 A SageMaker I Pipeline 参数、属性`ExecutionVariable`、表达式或的值。
您必须拥有经过训练的模型，才能计算训练后偏差指标或特征重要性。以下示例来自二进制分类模型，该模型以示例的格式输出 JSON 行数据。模型输出的每一行都是一个有效的 JSON 对象。键 `predicted_label` 指向预测标签，键 `probability` 指向概率值。
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
在以下配置示例中，`ModelConfig`对象指示 Clari SageMaker fy 处理任务将 SageMaker AI 模型部署到临时端点。该端点使用一个 `ml.m4.xlarge` 推理实例。
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
content_template='{"Features":$features}',
)
```
在前面的配置示例中，未设置参数 `content_type` 和 `accept_type`。因此，它们会自动使用 `DataConfig` 对象的 `dataset_type` 参数的值，即 `application/jsonlines`。Cl SageMaker arify 处理作业使用`content_template`参数通过将`$features`占位符替换为特征数组来组成模型输入。
以下示例配置显示如何将`ModelPredictedLabelConfig`对象的标签参数设置为 JMESPath 表达式`predicted_label`。这将从模型输出中提取预测标签。
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label='predicted_label',
)
```
以下示例配置显示如何将`ModelPredictedLabelConfig`对象的`probability`参数设置为 JMESPath表达式`probability`。这将从模型输出中提取得分。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
要计算 JSON 行格式数据集的偏差指标和特征重要性，请对 CSV 数据集使用与上一节相同的 run 语句和配置对象。您可以在 SageMaker Studio C SageMaker lassic 中运行 Clarify 处理作业来检测偏差并计算特征重要性。有关说明和笔记本示例，请参阅[使用 SageMaker Clarify 实现公平性和可解释性（JSON 行格式](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.ipynb)）。
## 分析表格数据以实现 NLP 可解释性
SageMaker Clarify 支持对自然语言处理 (NLP) 模型的解释。这些解释可帮助您了解文本的哪些部分对模型预测非常重要。您可以解释输入数据集单个实例的模型预测，也可以解释来自基准数据集的模型预测。要了解和可视化模型的行为，可以指定多个粒度级别。为此，请定义文本段的长度，例如其令牌、句子、段落。
SageMaker 澄清自然语言处理的可解释性与分类和回归模型兼容。您还可以使用 Clar SageMaker ify 来解释模型在包含文本、类别或数值特征的多模态数据集上的行为。多模态数据集的 NLP 可解释性可以帮助您了解每个特征对模型输出的重要性。 SageMaker Clarify 支持 62 种语言，可以处理包含多种语言的文本。
以下示例显示了一个用于计算特征对 NLP 重要性的分析配置文件。在本例中，传入的数据集是 CSV 格式的表格数据集，包含一个二进制标签列和两个特征列。
```
0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...
```
以下配置示例说明了如何使用 `DataConfig` 对象指定 CSV 格式的输入数据集和输出数据路径。
```
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,
)
```
在前面的配置示例中，`s3_data_input_path` 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 Clarif SageMaker y 处理任务会以递归方式收集位于该前缀下的所有 S3 文件。的值`s3_output_path`应为 S3 URI 前缀以保存分析结果。 SageMaker AI 在编译`s3_output_path`时使用，不能取运行时使用的 A SageMaker I Pipeline 参数、属性`ExecutionVariable`、表达式或的值。
以下示例输出是根据使用先前输入数据集训练的二进制分类模型创建的。分类模型接受 CSV 数据，并输出一个介于 `0` 和 `1` 之间的得分。
```
0.491656005382537
0.569582343101501
...
```
以下示例说明如何配置`ModelConfig`对象以部署 A SageMaker I 模型。在本例中，一个临时端点部署了该模型。此端点使用一个配备 GPU 的 `ml.g4dn.xlarge` 推理实例来加速推理。
```
nlp_model_config = clarify.ModelConfig(
model_name=your_nlp_model_name,
instance_type='ml.g4dn.xlarge',
instance_count=1,
)
```
以下示例说明了如何配置 `ModelPredictedLabelConfig` 对象，以定位索引为 `0` 的第一列中的概率（得分）。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=0,
)
```
以下示例 SHAP 配置说明了如何使用一个模型和一个英语输入数据集运行按令牌分类的可解释性分析。
```
text_config = clarify.TextConfig(
language='english',
granularity='token',
)
nlp_shap_config = clarify.SHAPConfig(
baseline=[[4, '[MASK]']],
num_samples=100,
text_config=text_config,
)
```
在前面的示例中，`TextConfig` 对象激活 NLP 可解释性分析。`granularity` 参数表示分析应解析令牌。在英语中，每个令牌都是一个单词。有关其他语言，请参阅 [SpaCy 标记化文档，Clar](https://spacy.io/usage/linguistic-features#tokenization) ify 使用该文档进行 SageMaker 自然语言处理。前面的示例还说明了如何使用平均值为 `4` 的 `Rating` 来设置就地 SHAP 基准实例。使用特殊的掩码令牌 `[MASK]` 来替换 `Comments` 中的令牌（单词）。
在前面的示例中，如果实例为 `2,"Flavor needs work"`，则使用以下基准将基准设置为平均 `Rating` 为 `4`。
```
4, '[MASK]'
```
在前面的示例中，Clar SageMaker ify 解释器遍历每个标记，并将其替换为掩码，如下所示。
```
2,"[MASK] needs work"
4,"Flavor [MASK] work"
4,"Flavor needs [MASK]"
```
然后，Cl SageMaker arify 解释器会将每行发送到您的模型进行预测。这样，解释器就可以在遮蔽和不遮蔽单词的情况下学习预测。然后， SageMaker Clarify 解释器使用这些信息来计算每个代币的贡献。
以下代码示例启动 Clari SageMaker fy 处理任务来计算SHAP值。
```
clarify_processor.run_explainability(
data_config=nlp_data_config,
model_config=nlp_model_config,
model_scores=probability_config,
explainability_config=nlp_shap_config,
)
```
有关如何在 SageMaker Studio Classic 中运行 Clarify 处理作业进行自然语言处理可解释性分析的示例笔记本，请参阅使用 Clarify [解释文本情感分析](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/text_explainability/text_explainability.ipynb)。 SageMaker SageMaker
## 分析图像数据以实现计算机视觉可解释性
SageMaker Clarify 会生成热图，深入了解您的计算机视觉模型如何对图像中的物体进行分类和检测。
在以下配置示例中，输入数据集由 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,
)
```
在前面的配置示例中，`DataConfig` 对象包含一个设置为 Amazon S3 URI 前缀的 `s3_data_input_path`。Cl SageMaker arify 处理作业以递归方式收集位于前缀下的所有图像文件。`s3_data_input_path` 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 Clarif SageMaker y 处理任务会以递归方式收集位于该前缀下的所有 S3 文件。的值`s3_output_path`应为 S3 URI 前缀以保存分析结果。 SageMaker AI 在编译`s3_output_path`时使用，不能取运行时使用的 A SageMaker I Pipeline 参数、属性`ExecutionVariable`、表达式或的值。
### 如何解释图像分类模型
Cl SageMaker arify 处理作业使用 KernelsHap 算法解释图像，该算法将图像视为超级像素的集合。给定一个由图像组成的数据集，处理作业会输出一个图像数据集，其中每张图像都显示相关超像素的热图。
以下配置示例说明如何使用 SageMaker 图像分类模型配置可解释性分析。请参阅[图像分类- MXNet](image-classification.md)了解更多信息。
```
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",
)
```
在前面的配置示例中，一个名为 `your_cv_ic_model` 的模型经过训练，可对输入 JPEG 图像上的动物进行分类。上一个示例中的`ModelConfig`对象指示 Clari SageMaker fy 处理任务将 SageMaker AI 模型部署到临时端点。为了加速推理，该端点使用一个配备 GPU 的 `ml.p2.xlarge` 推理实例。
将 JPEG 映像发送到端点后，该端点会对其进行分类并返回得分列表。每个得分都对应一个类别。`ModelPredictedLabelConfig` 对象提供了每个类别的名称，如下所示。
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
之前输入 ['bird','cat','dog'] 的输出示例为 0.3,0.6,0.1，其中 0.3 代表将映像分类为鸟类的置信度得分。
以下示例 SHAP 配置说明了如何生成图像分类问题的解释。它使用 `ImageConfig` 对象来激活分析。
```
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 Clarify 使用 scikit-learn 库中的[简单线性迭代聚类 (SLIC)](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) 方法提取特征，用于图像分割。前面的配置示例（`model_type` 参数）表示图像分类问题的类型。参数 `num_segments` 估算大约在输入图像中标注多少个分段。然后将分段数传递给 slic `n_segments` 参数。
将图像的每个分段都视为一个超像素，并计算每个分段的局部 SHAP 值。参数 `segment_compactness` 确定由 scikit-image slic 方法生成的图像分段的形状和大小。然后将图像分段的大小和形状传递给 slic `compactness` 参数。
以下代码示例启动 Clar SageMaker ify 处理作业，为您的图像生成热图。正热图值表明该特征提高了检测对象的置信度得分。负值表示该特征降低了置信度得分。
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=ic_model_config,
model_scores=ic_prediction_config,
explainability_config=ic_shap_config,
)
```
有关使用 Clarify 对 SageMaker 图像进行分类并解释其分类的示例笔记本，请参阅使用 Clarify [解释图像分类](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb)。 SageMaker
### 如何解释对象检测模型
Cl SageMaker arify 处理作业可以检测图像中的物体并对其进行分类，然后为检测到的物体提供解释。解释过程如下。
1. 图像对象首先被归类为指定集合中的一个类。例如，如果对象检测模型可以识别猫、狗和鱼，那么这三个类位于一个集合中。此集合由 `label_headers` 参数指定，如下所示。
```
clarify.ModelPredictedLabelConfig(
label_headers=object_categories,
)
```
1. Cl SageMaker arify 处理作业会为每个对象生成置信度分数。高置信度得分表示它属于指定集合中的一个类。C SageMaker larify 处理作业还会生成用于分隔对象的边界框的坐标。有关置信度得分和边界框的更多信息，请参阅[响应格式](object-detection-in-formats.md#object-detection-recordio)。
1. SageMaker 然后，Clarify 解释了在图像场景中检测物体的情况。它使用**如何解释图像分类模型**部分中描述的方法。
在以下配置示例中，在 JPEG 图像上训练 SageMaker AI 对象检测模型`your_cv_od_model`，以识别图像上的动物。
```
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",
)
```
前面配置示例中的`ModelConfig`对象指示 Clari SageMaker fy 处理任务将 SageMaker AI 模型部署到临时端点。为了加速成像，此端点使用一个配备 GPU 的 `ml.p2.xlarge` 推理实例。
在以下示例配置中，`ModelPredictedLabelConfig` 对象提供了每个类别的名称用于进行分类。
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
以下示例 SHAP 配置说明了如何生成对象检测的解释。
```
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,
)
```
在前面的示例配置中，`ImageConfig` 对象激活分析。`model_type` 参数表示问题类型为对象检测。有关其他参数的详细说明，请参阅[分析配置文件](clarify-processing-job-configure-analysis.md)。
以下代码示例启动 Clar SageMaker ify 处理作业，为您的图像生成热图。正热图值表明该特征提高了检测对象的置信度得分。负值表示该特征降低了置信度得分。
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=od_model_config,
model_scores=od_prediction_config,
explainability_config=od_shap_config,
)
```
有关使用 SageMaker Clarify 检测图像中的物体并解释其预测的示例笔记本，请参阅使用 [Amazon A SageMaker I Clarify 解释物体检测模型](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb)。
## 分析时间序列预测模型的解释
以下示例展示了如何配置 SageMaker AI JSON 密集格式的数据以解释时间序列预测模型。有关 JSON 格式化的更多信息，请参阅 [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
},
]
```
### 数据配置
如下面的配置示例所示，使用 `TimeSeriesDataConfig` 可以向可解释性任务传达如何正确解析输入数据集中的数据：
```
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',
)
```
### 非对称 Shapley 值配置
使用 `AsymmetricShapleyValueConfig` 为时间序列预测模型解释分析定义参数，如基线、方向、粒度和样本数。为所有三类数据设定基准值：相关时间序列、静态协变量和目标时间序列。该`AsymmetricShapleyValueConfig`配置告知 Cl SageMaker arify 处理器如何一次计算一个项目的特征属性。下面的配置显示了 `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"
},
)
```
您为 `AsymmetricShapleyValueConfig` 提供的值将作为 `methods` 中的条目传递给分析配置，键为 `asymmetric_shapley_value`。
### 模型配置
您可以控制从 Clarify 处理器发送的 SageMaker 有效载荷的结构。在以下代码示例中，`ModelConfig`配置对象指示时间序列预测可解释性作业使用 JMESPath 语法将`'{"instances": $records}'`记录聚合到中，其中每条记录的结构都是使用以下 record\$1template 定义的。`'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'`请注意，`$start_time`、`$target_time_series`、`$related_time_series` 和 `$static_covariates` 是内部标记，用于将数据集值映射到端点请求值。
```
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]'}
)
)
```
同样，`TimeSeriesModelConfig` 中的属性 `forecast`（以关键字 `time_series_predictor_config` 传递给分析配置）用于从端点响应中提取模型预测。例如，端点批量响应的示例如下：
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
如果提供的 JMESPath 表达式`forecast`是 \$1'预测 [\$1] .mean [: 2] '\$1\$1，则预测值解析如下：
```
[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]
```
## 如何运行 parallel Clar SageMaker ify 处理作业
处理大型数据集时，你可以使用 [Apache Spark](https://spark.apache.org/) 来提高 Clarify 处理 SageMaker 作业的速度。Spark 是用于大规模数据处理的统一分析引擎。当你为每 SageMaker 个 Clarify 处理器请求多个实例时，Cl SageMaker arify 会使用 Spark 的分布式计算功能。
以下配置示例显示了`SageMakerClarifyProcessor`如何使用创建带有`5`计算实例的 Cl SageMaker arify 处理器。要运行任何与关联的作业`SageMakerClarifyProcessor`，请使用 Spark 分布式处理进行 SageMaker 澄清。
```
from sagemaker import clarify
spark_clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=5,
instance_type='ml.c5.xlarge',
)
```
如果将的`save_local_shap_values`参数设置[SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)为`True`，Clari SageMaker fy 处理作业会将本地SHAP值作为多个零件文件保存到作业输出位置。
要将局部 SHAP 值与输入数据集实例相关联，请使用 `DataConfig` 的 `joinsource` 参数。如果您添加更多计算实例，我们建议您同时增加临时终端节点[ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)的。`instance_count`这可防止 Spark 工作线程的并发推理请求让端点不堪重负。具体而言，我们建议您使用一定 one-to-one比例的 endpoint-to-processing实例数。
# 分析结果
C SageMaker larify 处理作业完成后，您可以下载输出文件进行检查，也可以在 SageMaker Studio Classic 中对结果进行可视化。以下主题介绍了 Clarify 生成的分析结果，例如由偏差分析、SHAP 分析、计算机视觉可解释性分析和部分依赖图 () PDPs 分析生成的架构和报告。 SageMaker 如果配置分析包含用于计算多个分析的参数，则结果将聚合到一个分析和一个报告文件中。
C SageMaker larify 处理作业输出目录包含以下文件：
+ `analysis.json` - 一个文件，其中包含 JSON 格式的偏差指标和特征重要性。
+ `report.ipynb` - 一个静态笔记本，其中包含有助于可视化偏差指标和特征重要性的代码。
+ `explanations_shap/out.csv` - 根据您的特定分析配置创建的目录，其中包含自动生成的文件。例如，如果激活 `save_local_shap_values` 参数，则每个实例的局部 SHAP 值将保存到 `explanations_shap` 目录。再举一个例子，如果您`analysis configuration`不包含 SHAP 基线参数的值，Clarify 可解释性作业将 SageMaker 通过对输入数据集进行聚类来计算基线。然后，它会将生成的基准保存到该目录。
有关更多详细信息，请参阅以下章节。
**Topics**
+ [偏差分析](#clarify-processing-job-analysis-results-bias)
+ [SHAP 分析](#clarify-processing-job-analysis-results-shap)
+ [计算机视觉 (CV) 可解释性分析](#clarify-processing-job-analysis-results-cv)
+ [部分依赖图 (PDPs) 分析](#clarify-processing-job-analysis-results-pdp)
+ [非对称 Shapley 值](#clarify-processing-job-analysis-results-asymmshap)
## 偏差分析
Amaz SageMaker on Clarify 使用中记录的术语[Amazon SageMaker 澄清偏见和公平条款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)来讨论偏见和公平性。
### 分析文件的架构
分析文件采用 JSON 格式，分为两部分：训练前偏差指标和训练后偏差指标。训练前和训练后偏差指标的参数如下。
+ **pre\$1training\$1bias\$1metrics** - 训练前偏差指标的参数。有关更多信息，请参阅[训练前偏差指标](clarify-measure-data-bias.md)和[分析配置文件](clarify-processing-job-configure-analysis.md)。
+ **label** - 由分析配置的 `label` 参数定义的 Ground Truth 标签名称。
+ **label\$1value\$1or\$1threshold** - 一个字符串，其中包含由分析配置的 `label_values_or_threshold` 参数定义的标签值或间隔。例如，如果为二进制分类问题提供了值 `1`，则字符串将是 `1`。如果为多类问题提供了多个值 `[1,2]`，则字符串将是 `1,2`。如果为回归问题提供了阈值 `40`，则字符串将是内部字符串，比如 `(40, 68]`，其中 `68` 是输入数据集中标签的最大值。
+ **facets** - 该部分包含多个键值对，其中键对应于分面配置的 `name_or_index` 参数定义的分面名称，值是分面对象数组。每个分面对象都具有以下成员：
+ **value\$1or\$1threshold** - 一个字符串，其中包含由分面配置的 `value_or_threshold` 参数定义的分面值或区间。
+ **metrics** - 该部分包含偏差指标元素数组，每个偏差指标元素都具有以下属性：
+ **name** - 偏差指标的简称。例如 `CI`。
+ **description** - 偏差指标的全名。例如 `Class Imbalance (CI)`。
+ **value** - 偏差指标值，如果出于特定原因未计算偏差指标，则为 JSON null 值。值 ±∞ 分别表示为字符串 `∞` 和 `-∞`。
+ **error** - 一条可选的错误消息，解释了未计算偏差指标的原因。
+ **post\$1training\$1bias\$1metrics** - 该部分包含训练后偏差指标，其布局和结构与训练前部分类似。有关更多信息，请参阅 [训练后数据和模型偏差指标](clarify-measure-post-training-bias.md)。
以下是将计算训练前和训练后偏差指标的分析配置示例。
```
{
"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
},
...
]
}]
}
}
}
```
### 偏差分析报告
偏差分析报告包括几个表格和图表，其中包含详细的解释和描述。这包括但不限于标签值分布、分面值分布、高级模型性能图、偏差指标表及其描述。有关偏见指标及其解释方法的更多信息，请参阅[了解 Amazon Clarify SageMaker 如何帮助检测偏见](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)。
## SHAP 分析
SageMaker 澄清处理作业使用内核 SHAP 算法来计算特征归因。Cl SageMaker arity 处理任务会生成本地和全局 SHAP 值。它们有助于确定每项特征对模型预测的贡献。局部 SHAP 值表示每个实例的特征重要性，而全局 SHAP 值则聚合数据集中所有实例的局部 SHAP 值。有关 SHAP 值及其解析方法的更多信息，请参阅[使用 Shapley 值的特征归因](clarify-shapley-values.md)。
### SHAP 分析文件的架构
全局 SHAP 分析结果存储在分析文件的解释部分，置于 `kernel_shap` 方法之下。SHAP 分析文件的不同参数如下所示：
+ **explanations** - 分析文件中包含特征重要性分析结果的部分。
+ **kernal\$1shap** - 分析文件中包含全局 SHAP 分析结果的部分。
+ **global\$1shap\$1values** - 分析文件中包含多个键值对的部分。键值对中的每个键都代表输入数据集中的一个特征名称。键值对中的每个值都对应于该特征的全局 SHAP 值。全局 SHAP 值是通过使用 `agg_method` 配置聚合特征的每个实例 SHAP 值来获得的。如果 `use_logit` 配置激活，则使用逻辑回归系数计算该值，这些系数可以解释为对数几率比。
+ **expected\$1value** - 基准数据集的平均预测值。如果 `use_logit` 配置激活，则使用逻辑回归系数计算该值。
+ **global\$1top\$1shap\$1text**：用于 NLP 可解释性分析。分析文件中包含一组键值对的部分。 SageMaker 澄清处理任务汇总每个令牌的 SHAP 值，然后根据其全局 SHAP 值选择排名靠前的代币。`max_top_tokens` 配置定义了要选择的令牌数量。
每个选定的主要令牌都有一个键值对。键值对中的键对应于主要令牌的文本特征名称。键值对中的每个值都是主要令牌的全局 SHAP 值。有关 `global_top_shap_text` 键值对的示例，请参阅以下输出。
下面的示例显示了 SHAP 分析表格数据集的输出结果。
```
{
"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
}
}
}
}
```
下面的示例显示了 SHAP 分析文本数据集的输出结果。与 `Comments` 列对应的输出是在分析文本特征后生成的输出示例。
```
{
"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,
...
}
}
}
}
}
```
### 生成的基准文件的架构
如果未提供 SHAP 基线配置，则 Clarif SageMaker y 处理作业会生成基线数据集。 SageMaker Clarify 使用基于距离的聚类算法，根据输入数据集创建的聚类生成基线数据集。生成的基准数据集保存在 CSV 文件中，位于 `explanations_shap/baseline.csv`。此输出文件包含一个标题行和几个实例，这些实例基于分析配置中指定的 `num_clusters` 参数。基准数据集仅包含特征列。下面的示例显示了通过对输入数据集进行集群而创建的基线。
```
Age,Gender,Income,Occupation
35,0,2883,1
40,1,6178,2
42,0,4621,0
```
### 表格数据集可解释性分析中局部 SHAP 值的架构
对于表格数据集，如果使用单个计算实例，Clarify 处理作业会将本地 SHAP 值保存到名为的 CSV 文件中。 SageMaker `explanations_shap/out.csv`如果使用多个计算实例，则局部 SHAP 值将保存到 `explanations_shap` 目录中的多个 CSV 文件。
包含局部 SHAP 值的输出文件中有一行包含标题定义的每列的局部 SHAP 值。标题遵循 `Feature_Label` 命名约定，即特征名称后面加下划线，后跟目标变量的名称。
对于多类问题，标题中的特征名称会先变化，然后是标签。例如，有两项特征 `F1, F2` 和两个类 `L1` 和 `L2`，那么在标题中显示为 `F1_L1`、`F2_L1`、`F1_L2` 和 `F2_L2`。如果分析配置包含 `joinsource_name_or_index` 参数的值，则联接中使用的键列将附加到标题名称的末尾。这允许将局部 SHAP 值映射到输入数据集的实例。以下是包含 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
...
```
### NLP 可解释性分析中局部 SHAP 值的架构
对于 NLP 可解释性分析，如果使用单个计算实例，Clarify 处理任务会将本 SageMaker 地 SHAP 值保存到名为的 JSON Lines 文件中。`explanations_shap/out.jsonl`如果使用多个计算实例，则局部 SHAP 值将保存到 `explanations_shap` 目录中的多个 JSON 行文件。
每个包含局部 SHAP 值的文件都有几行数据，每行都是一个有效的 JSON 对象。JSON 对象具有以下属性：
+ **explanations** - 分析文件中包含单个实例 Kernel SHAP 解释数组的部分。数组中的每个元素都具有以下成员：
+ **feature\$1name** - 标题配置提供的特征的标题名称。
+ **data\$1type** — Clarify 处理作业推断出的要素类型 SageMaker 。文本特征的有效值包括 `numerical`、`categorical` 和 `free_text`（适用于文本特征）。
+ **attributions** - 特定于特征的归因对象数组。一个文本特征可以有多个归因对象，每个对象对应一个由 `granularity` 配置定义的单元。归因对象具有以下成员：
+ **attribution** - 特定于类的概率值数组。
+ **description** -（适用于文本特征）文本单元的描述。
+ p@@ **artial\$1text** — 由 SageMaker 澄清处理任务解释的文本部分。
+ **start\$1idx** - 一个零基索引，用于标识表示部分文本片段开头的数组位置。
以下是局部 SHAP 值文件中单行的示例，为提高可读性而进行了美化。
```
{
"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
}
}
]
}
]
}
```
### SHAP 分析报告
SHAP 分析报告提供了一张条形图，图中最多有 `10` 个主要全局 SHAP 值。以下图表示例显示了 `4` 项主要特征的 SHAP 值。
![\[针对四项主要特征的目标变量计算出的全局 SHAP 值的水平条形图。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/shap-chart.png)
## 计算机视觉 (CV) 可解释性分析
SageMaker Clarity 计算机视觉可解释性采用由图像组成的数据集，并将每张图像视为超级像素的集合。分析后，Cl SageMaker arify 处理作业会输出一个图像数据集，其中每张图像都显示超级像素的热图。
以下示例在左侧显示了输入限速标志，右侧的热图显示了 SHAP 值的大小。这些 SHAP 值是通过图像识别 Resnet-18 模型计算得出，该模型经过训练可以识别[德国交通标志](https://benchmark.ini.rub.de/gtsrb_news.html)。[Man vs. computer: Benchmarking machine learning algorithms for traffic sign recognition](https://www.sciencedirect.com/science/article/abs/pii/S0893608012000457?via%3Dihub)（人与计算机：用于识别交通标志的机器学习算法基准测试）一文中提供了德国交通标志识别基准 (GTSRB) 数据集。在示例输出中，较大的正值表明超像素与模型预测的正相关性较强。较大的负值表明超像素与模型预测的负相关性较强。热图中显示的 SHAP 值的绝对值越大，超像素与模型预测之间的关系就越强。
![\[Resnet-18 模型中限速标志的输入图像和生成的 SHAP 值热图。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/shap_speed-limit-70.png)
有关更多信息，请参阅 “使用 Clarify [解释图片分类” 和 “使用 SageMaker ](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) [Amazon SageMaker Clarify 解释物体检测模型](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb)” 示例笔记本。
## 部分依赖图 (PDPs) 分析
部分依赖图显示预测的目标响应对一组相关输入特征的依赖性。这些特征在所有其他输入特征值的基础上进行边缘化，被称为补充特征。直观地说，您可以将部分依赖性解释为目标响应，它是每个相关输入特征的预期函数。
### 分析文件的架构
PDP 值存储在分析文件 `explanations` 部分的 `pdp` 方法下。`explanations` 的参数设置如下所示：
+ **explanations** - 分析文件中包含特征重要性分析结果的部分。
+ **pdp** - 分析文件中包含单个实例的 PDP 解释数组的部分。数组的每个元素都具有以下成员：
+ **feature\$1name** - `headers` 配置提供的特征的标题名称。
+ **data\$1type** — Clarify 处理作业推断出的要素类型 SageMaker 。`data_type` 的有效值包括数值和分类。
+ **feature\$1values** - 包含特征中存在的值。如果 Clarif SageMaker y 的`data_type`推断是分类的，则`feature_values`包含该特征可能具有的所有唯一值。如果 Clarify `data_type` SageMaker 推断的值是数值，则`feature_values`包含生成的存储桶的中心值列表。`grid_resolution` 参数确定用于对特征列值进行分组的存储桶数量。
+ **data\$1distribution** - 百分比数组，其中每个值都是存储桶所包含的实例的百分比。`grid_resolution` 参数决定了存储桶数量。特征列值分组到这些存储桶中。
+ **model\$1predictions** - 模型预测数组，其中数组的每个元素都是一个预测数组，对应于模型输出中的一个类。
**label\$1headers** - `label_headers` 配置提供的标签标题。
+ **error** - 如果由于特定原因未计算 PDP 值，则会生成一条错误消息。此错误消息替换 `feature_values`、`data_distributions` 和 `model_predictions` 字段中包含的内容。
以下是包含 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"]
},
...
]
}
}
```
### PDP 分析报告
您可以生成包含每项特征的 PDP 图表的分析报告。PDP 图表沿 x 轴绘制 `feature_values`，沿 y 轴绘制 `model_predictions`。对于多类模型，`model_predictions` 是一个数组，该数组的每个元素都对应于一个模型预测类。
以下是特征 `Age` 的 PDP 图表示例。在示例输出中，PDP 显示了分组到存储桶中的特征值的数量。存储桶的数量由 `grid_resolution` 决定。根据模型预测绘制特征值存储桶。在本例中，较高的特征值具有相同的模型预测值。
![\[折线图显示 10 个唯一网格点的模型预测值随 feature_values 的变化情况。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/pdp-chart.png)
## 非对称 Shapley 值
SageMaker 澄清处理作业使用非对称 Shapley 值算法来计算时间序列预测模型解释属性。该算法可确定每个时间步长的输入功能对预测结果的贡献。
### 非对称 Shapley 值分析文件的模式
非对称 Shapley 值结果存储在 Amazon S3 存储桶中。您可以在分析文件的*解释*部分找到该存储桶的位置。本节包含功能重要性分析结果。非对称 Shapley 值分析文件中包含以下参数。
+ **asymmetric\$1shapley\$1value**：分析文件中包含解释作业结果元数据的部分，包括以下内容：
+ **explanation\$1results\$1path**：含有解释结果的 Amazon S3 位置
+ **方向**：用户为 `direction` 的配置值提供的配置
+ **粒度**：用户为 `granularity` 的配置值提供的配置。
下面的代码段显示了分析文件示例中前面提到的参数：
```
{
"version": "1.0",
"explanations": {
"asymmetric_shapley_value": {
"explanation_results_path": EXPLANATION_RESULTS_S3_URI,
"direction": "chronological",
"granularity": "timewise",
}
}
}
```
下文将介绍解释结果结构如何取决于配置中的 `granularity` 值。
#### 时间粒度
当粒度为 `timewise` 时，输出将以如下结构表示。`scores` 值表示每个时间戳的归属。`offset` 值代表模型对基线数据的预测，描述了模型在没有接收到数据时的行为。
下面的代码段显示了一个模型的输出示例，该模型对两个时间步长进行预测。因此，所有归因都是由两个元素组成的列表，其中第一个元素指的是第一个预测时间步长。
```
{
"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]},
]
}
```
#### 精细
下面的示例演示了粒度为 `fine_grained` 时的归因结果。`offset` 值的含义与上一节所述相同。对目标时间序列和相关时间序列（如果有）的每个时间戳的每个输入功能，以及每个静态协变量（如果有），都要计算归因。
```
{
"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]},
]
}
```
对于 `timewise` 和 `fine-grained` 使用场景，结果均以 JSON Lines (.jsonl) 格式存储。
# 对 SageMaker 澄清处理任务进行故障排除
如果您在使用 Clari SageMaker fy 处理作业时遇到故障，请查阅以下场景以帮助确定问题。
**注意**
失败原因和退出消息旨在包含描述性消息和运行期间遇到的异常（如果遇到异常）。错误的常见原因是参数缺失或无效。如果遇到不清楚、令人困惑或误导性消息，或者找不到解决方案，请提交反馈。
**Topics**
+ [处理作业无法完成](#clarify-troubleshooting-job-fails)
+ [处理作业运行时间过长](#clarify-troubleshooting-job-long)
+ [处理作业已完成，但没有结果，您会收到一条 CloudWatch 警告消息](#clarify-troubleshooting-no-results-and-warning)
+ [无效分析配置的错误消息](#clarify-troubleshooting-invalid-analysis-configuration)
+ [多个或所有指标的偏差指标计算失败](#clarify-troubleshooting-bias-metric-computation-fails)
+ [分析配置和 dataset/model 输入/输出不匹配](#clarify-troubleshooting-mismatch-analysis-config-and-data-model)
+ [模型返回“500 内部服务器错误”，或者由于模型错误，容器会回退到按记录预测](#clarify-troubleshooting-500-internal-server-error)
+ [执行角色无效](#clarify-troubleshooting-execution-role-invalid)
+ [无法下载数据](#clarify-troubleshooting-data-download)
+ [无法连接到 SageMaker AI](#clarify-troubleshooting-connection)
## 处理作业无法完成
如果处理作业无法完成，您可以尝试以下方法：
+ 直接在运行作业的笔记本中查看作业日志。作业日志位于您启动运行的笔记本单元的输出中。
+ 检查作业登录信息 CloudWatch。
+ 在笔记本中添加以下行以描述上次处理作业，并查找失败原因和退出消息：
+ `clarify_processor.jobs[-1].describe()`
+ 运行以下 AWS CLI; 命令来描述处理任务并查找失败原因和退出消息：
+ `aws sagemaker describe-processing-job —processing-job-name `
## 处理作业运行时间过长
如果处理作业运行时间过长，请使用以下方法查找根本原因。
检查资源配置是否足以处理计算负载。要加快作业速度，请尝试以下操作：
+ 使用更大的实例类型。 SageMaker Clarify 反复查询模型，更大的实例可以显著缩短计算时间。有关可用实例及其内存大小、带宽和其他性能详情的列表，请参阅 [Amazon A SageMaker I 定价](https://aws.amazon.com/sagemaker/pricing/)。
+ 添加更多实例。 SageMaker Clarify 可以使用多个实例并行解释多个输入数据点。要启用并行计算，请在调用 `SageMakerClarifyProcessor` 时将 `instance_count` 设置为大于 `1`。有关更多信息，请参阅 [如何运行 parallel Clar SageMaker ify 处理作业](clarify-processing-job-run.md#clarify-processing-job-run-spark)。如果您增加实例数量，请监控端点的性能，以检查其是否可以部署增加的负载。有关更多信息，请参阅 [从实时端点捕获数据](model-monitor-data-capture-endpoint.md)。
+ 如果要计算 SHapley Additive exPlanations (SHAP) 值，请减少分析配置文件中的 `num_samples` 参数。样本数量直接影响以下方面：
+ 发送到端点的合成数据集的大小
+ 作业运行时间
减少样本数量也会降低 SHAP 值估算的准确性。有关更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
## 处理作业已完成，但没有结果，您会收到一条 CloudWatch 警告消息
如果处理作业已完成但未找到任何结果，则 CloudWatch 日志会生成一条警告消息，显示 S ignal 15 已收到，正在清理。 此警告表示任务已停止，要么是因为客户请求调用了 `StopProcessingJob` API，要么是因为任务已用完分配的完成时间。如果是后一种情况，请在作业配置 (`max_runtime_in_seconds`) 中检查最大运行时间，然后根据需要增加运行时间。
## 无效分析配置的错误消息
+ 如果您收到错误消息无法以 JSON 格式加载分析配置。，这意味着处理作业的分析配置输入文件不包含有效的 JSON 对象。使用 JSON linter 检查 JSON 对象的有效性。
+ 如果您收到错误消息分析配置架构验证错误。，这意味着处理作业的分析配置输入文件包含未知字段或某些字段值的类型无效。查看文件中的配置参数，并与分析配置文件中列出的参数进行核对。有关更多信息，请参阅 [分析配置文件](clarify-processing-job-configure-analysis.md)。
## 多个或所有指标的偏差指标计算失败
如果您收到错误消息预测标签列中没有标签值，正预测索引系列包含所有错误值。或预测标签列系列数据类型与标签列系列不同。之一，请尝试以下操作：
+ 检查使用的数据集是否正确。
+ 检查数据集是否过小；例如，它是否只包含几行。这可能会导致模型输出具有相同的值或数据类型推断错误。
+ 检查标签或刻面是被视为连续的还是分类的。 SageMaker Clarify 使用启发式方法来确定. [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)) 对于训练后的偏差指标，模型返回的数据类型可能与数据集中的数据类型不匹配，或者 SageMaker Clarify 可能无法对其进行正确转换。
+ 在偏差报告中，对于分类列，您应该看到单个值；对于连续列，您应该看到一个区间。
+ 例如，如果一列的值为 0.0 和 1.0（浮点数），即使唯一值太少，也会被视为连续值。
## 分析配置和 dataset/model 输入/输出不匹配
+ 检查分析配置中的基准格式是否与数据集格式相同。
+ 如果您收到错误消息无法将字符串转换为浮点数。，请检查格式是否正确。它还可能表明模型预测的格式与标签列不同，或者可能表明标签或概率的配置不正确。
+ 如果您收到错误消息无法找到分面。、标题必须包含标签。、配置中的标题与数据集中的列数不匹配。或未找到特征名称。，请检查标题是否与列匹配。
+ 如果您收到错误消息数据必须包含特征。，请查看 JSON 行的内容模板并将其与数据集样本（如果有）进行比较。
## 模型返回“500 内部服务器错误”，或者由于模型错误，容器会回退到按记录预测
如果您收到错误消息由于模型错误而回退到按记录预测。，这可能表明模型无法处理批次大小，或被节流，或只是由于序列化问题而不接受容器传递的输入。您应该查看 SageMaker AI 端点的 CloudWatch 日志，并查找错误消息或回溯。对于模型节流情况，使用不同的实例类型或增加端点的实例数量可能会有所帮助。
## 执行角色无效
这表明提供的角色不正确或缺少所需权限。检查用于配置处理任务的角色及其权限，并验证该角色的权限和信任策略。
## 无法下载数据
这表明无法下载作业输入以启动作业。检查数据集和配置输入的存储桶名称和权限。
## 无法连接到 SageMaker AI
这表示任务无法到达 SageMaker AI 服务端点。检查处理作业的网络配置设置并验证虚拟私有云 (VPC) 配置。
## 示例笔记本
以下各节包含笔记本，可帮助您开始使用 C SageMaker larify，将其用于特殊任务（包括分布式作业中的任务）以及计算机视觉。
### 开始使用
以下示例笔记本展示了如何使用 Clar SageMaker ify 开始执行可解释性和模型偏差任务。这些任务包括创建处理作业、训练机器学习 (ML) 模型和监控模型预测：
+ 使用 [Ama SageMaker zon Clarify 进行可解释性和偏见检测](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) — 使用 SageMaker Clarify 创建处理任务来检测偏见并解释模型预测。
+ [监控偏见漂移和特征归因偏差 Amazon Cl SageMaker arif](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) y — 使用 Amazon SageMaker 模型监视器监控偏差和特征归因偏差随时间推移而发生的偏差偏移和特
+ 如何[将 JSON 行格式的数据集读](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.html)入 Clarif SageMaker y 处理作业。
+ [缓解偏差，训练另一个无偏模型，然后将其放入模型注册表中](https://github.com/aws/amazon-sagemaker-examples/blob/master/end_to_end/fraud_detection/3-mitigate-bias-train-model2-registry-e2e.ipynb) — 使用[合成少数过度采样技术 (SMOTE)](https://arxiv.org/pdf/1106.1813.pdf) 和 SageMaker Clarify 来缓解偏差，训练另一个模型，然后将新模型放入模型注册表中。该示例笔记本还展示了如何将新模型构件（包括数据、代码和模型元数据）放入模型注册表。本笔记本是该系列文章的一部分，该系列展示了如何将 Clarify 集成 SageMaker 到 A [rchitect 中描述的 SageMaker AI 管道中，并通过 AWS博客文章构建完整的机器学习生命周期](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/)。
### 特殊情况
以下笔记本向您展示了如何使用 Clari SageMaker fy 来处理特殊情况，包括在您自己的容器内以及执行自然语言处理任务：
+ [使用 SageMaker Clarify（自带容器）实现公平性和可解释性 — 构建自己的模型和容器](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_byoc.ipynb)，这些模型和容器可以与 SageMaker Clarify 集成，以衡量偏差并生成可解释性分析报告。本示例笔记本还介绍了关键术语，并向您展示了如何通过 SageMaker Studio Classic 访问报告。
+ Clarify [Spark 分布式处理的公平性和可解释性](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_spark.ipynb) — 使用分布式处理来运行 Clarify 作业，该作业可测量数据集的训练前偏差和模型的训练后偏差。 SageMaker SageMaker 本示例笔记本还向您展示了如何获取模型输出中输入特征重要性的解释，以及如何通过 SageMaker Studio Classic 访问可解释性分析报告。
+ 使用 Clarif@@ [y SageMaker 进行可解释性——部分依赖图 (PDP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.html) — 使用 Clarif SageMaker y 生成 PDPs 和访问模型可解释性报告。
+ [使用 C SageMaker larify 自然语言处理 (NLP) 可解释性解释文本情感分析](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/text_explainability/text_explainability.html) — 使用 Clarify 进行 SageMaker 文本情感分析。
+ 利用计算机视觉 (CV) 的可解释性进行[映像分类](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.html)和[对象检测](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.html)。
这些笔记本电脑已经过验证，可以在亚马逊 SageMaker Studio Classic 中运行。如果您需要了解如何在 Studio Classic 中打开笔记本，请参阅 [创建或打开 Amazon SageMaker Studio 经典笔记本电脑](notebooks-create-open.md)。如果系统提示您选择内核，请选择 **Python 3 (Data Science)**。
# 训练前数据偏差
算法偏差、歧视、公平性和相关主题的研究涉及法律、政策和计算机科学等多个学科。如果计算机系统歧视某些个人或群体，则可能被视为有偏差。为这些应用程序提供支持的机器学习模型从数据中学习，这些数据可能反映出差异或其他固有偏差。例如，训练数据可能无法充分代表各种人口统计群体，或者可能包含有偏差的标签。在表现出这些偏差的数据集上训练的机器学习模型最终可能会学习这些偏差，然后在预测中重现甚至加剧这些偏差。机器学习领域通过在机器学习生命周期的每个阶段检测和衡量偏差，提供了一个解决偏差的机会。您可以使用 Amazon C SageMaker larify 来确定用于训练模型的数据是否对任何偏差进行编码
可以在训练前和训练后衡量偏差，并可在将模型部署到端点进行推理后，根据基准进行监控。训练前偏差指标旨在检测和衡量原始数据中的偏差，然后再将这些数据用于训练模型。所使用的指标与模型无关，因为它们不依赖于任何模型输出。然而，不同的公平概念需要不同的偏差衡量标准。Amaz SageMaker on Clarify 提供了偏见指标来量化各种公平标准。
有关偏见指标的更多信息，请参阅[了解 Amazon Clari SageMaker fy 如何帮助检测金融领域机器学习的偏见](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias)[和公平衡](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)量标准。
## Amazon SageMaker 澄清偏见和公平条款
SageMaker Clarify 使用以下术语来讨论偏见和公平。
**功能**
所观察到现象的单个可测量属性或特征，包含在表格数据的一列中。
**标签**
作为机器学习模型训练目标的特征。称为*观测标签*或*观测结果*。
**预测标签**
模型预测的标签。也称为*预测结果*。
**样本**
观测到的实体，由特征值和标签值描述，包含在表格数据的一行中。
**数据集**
样本集合。
**偏差**
不同群体（如年龄或收入阶层）的训练数据或模型预测行为的不平衡。偏差可能由用于训练模型的数据或算法产生。例如，如果一个机器学习模型主要是根据中年人的数据进行训练，那么在对年轻人和老年人进行预测时，其准确性可能会降低。
**偏差指标**
返回表示潜在偏差程度的数值的函数。
**偏差报告**
给定数据集的偏差指标集合，或数据集和模型的组合。
**阳性标签值**
在样本中观测到的有利于人口统计群体的标签值。换句话说，将样本指定为*阳性结果*。
**阴性标签值**
在样本中观测到的不利人口统计群体的标签值。换句话说，将样本指定为*阴性结果*。
**组变量**
数据集的分类列，该数据集用于形成子组以测量条件人口统计差异 (CDD)。仅在有关辛普森悖论的这一指标中需要。
**分面**
包含测量偏差所依据的属性的列或特征。
**分面值**
偏差可能有利或不利的属性的特征值。
**预测概率**
模型预测的样本出现阳性或阴性结果的概率。
## 示例笔记本
Amaz SageMaker on Clarify 提供了以下用于偏见检测的笔记本示例：
+ 使用 [Ama SageMaker zon Clarify 进行可解释性和偏见检测](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) — 使用 SageMaker Clarify 创建处理任务，用于检测偏差并使用特征归因解释模型预测。
本笔记本经过验证，只能在 Amazon SageMaker Studio 中运行。如果您需要有关如何在 Amazon SageMaker Studio 中打开笔记本的说明，请参阅[创建或打开 Amazon SageMaker Studio 经典笔记本电脑](notebooks-create-open.md)。如果系统提示您选择内核，请选择 **Python 3 (Data Science)**。
**Topics**
+ [Amazon SageMaker 澄清偏见和公平条款](#clarify-bias-and-fairness-terms)
+ [示例笔记本](#clarify-data-bias-sample-notebooks)
+ [训练前偏差指标](clarify-measure-data-bias.md)
+ [在 Studio 中生成训练前数据偏差报告 SageMaker](clarify-data-bias-reports-ui.md)
# 训练前偏差指标
衡量机器学习模型中的偏差是减少偏差的第一步。每种偏差衡量标准都对应于不同的公平概念。即使考虑简单的公平概念，也会导致许多不同的衡量标准适用于各种背景的情况。例如，考虑年龄方面的公平性，为了简单起见，中年和其他年龄组是两个相关的人口统计，称为*分面*。就贷款的机器学习模型而言，我们可能希望向两种人口统计中的同等数量的人发放小企业贷款。或者，在处理求职者时，我们可能希望看到每种人口统计中都有同等数量的人被录用。不过，这种方法可能会假定两个年龄组申请这些工作的人数相等，因此我们可能希望对申请人数设定条件。此外，我们要考虑的可能不是申请人数是否相等，而是我们是否有同等数量的合格申请人。或者，我们可以认为公平是指两个年龄组的合格申请人的录取率相同，和/或申请人的拒绝率相同。您可以使用相关属性数据比例不同的数据集。这种不平衡可能会混淆您选择的偏差衡量标准。这些模型对一个分面的分类可能比对另一分面的分类更准确。因此，您需要选择在概念上适合应用和情况的偏差指标。
我们使用以下表示法来讨论偏差指标。此处描述的概念模型适用于二进制分类，即事件被标记为在其样本空间中只有两种可能的结果，分别称为阳性结果（值为 1）和阴性结果（值为 0）。这一框架通常可以直接扩展到多类别分类，或在需要时扩展到涉及持续有价值结果的情况。在二进制分类的情况下，分别为原始数据集中记录的结果中的有利分面 *a* 和不利分面 *d* 分配阳性标签和阴性标签。这些标签 y 称为*观测标签*，以区别于机器学习模型在机器学习生命周期的训练或推理阶段分配的*预测标签* y'。这些标签用于定义各自分面结果的概率分布 Pa(y) 和 Pd(y)。
+ 标签：
+ y 表示训练数据集中观测到的事件结果的 n 个标签。
+ y' 表示经过训练的模型对数据集中 n 个观测标签的预测标签。
+ 结果：
+ 样本的阳性结果（值为 1），例如申请被接受。
+ n(1) 是阳性结果（接受）的观测标签数量。
+ n'(1) 是阳性结果（接受）的预测标签数量。
+ 样本的阴性结果（值为 0），例如申请被拒绝。
+ n(0) 是阴性结果（拒绝）的观测标签数量。
+ n'(0) 是阴性结果（拒绝）的预测标签数量。
+ 分面值：
+ 分面 *a* - 定义偏差有利的人口统计的特征值。
+ na 是有利分面值的观测标签数：na = na(1) \$1 na(0) 分面值 *a* 的阳性和阴性观测标签之和。
+ n'a 是有利分面值的预测标签数：n'a = n'a(1) \$1 n'a(0) 分面值 *a* 的阳性和阴性预测结果标签之和。请注意，n'a = na。
+ 分面 *d* - 定义偏差不利的人口统计的特征值。
+ nd 是不利分面值的观测标签数：nd = nd(1) \$1 nd(0) 分面值 *d* 的阳性和阴性观测标签之和。
+ n'd 是不利分面值的预测标签数：n'd = n'd(1) \$1 n'd(0) 分面值 *d* 的阳性和阴性预测标签之和。请注意，n'd = nd。
+ 标注的分面数据结果的概率分布：
+ Pa(y) 是分面 *a* 的观测标签的概率分布。对于二进制标注的数据，该分布由分面 *a* 中标注为阳性结果的样本数与总样本数之比 Pa(y1) = na(1)/ na，以及标注为阴性结果的样本数与总样本数之比 Pa(y0) = na(0)/ na 得出。
+ Pd(y) 是分面 *d* 的观测标签的概率分布。对于二进制标注的数据，该分布由分面 *d* 中标注为阳性结果的样本数与总样本数之比 Pd(y1) = nd(1)/ nd，以及标注为阴性结果的样本数与总样本数之比 Pd(y0) = nd(0)/ nd 得出。
根据人口统计差异偏差数据训练的模型可能会学习甚至加剧这些差异。为了在花费资源训练模型之前识别数据中的偏差， SageMaker Clarify 提供了数据偏差指标，您可以在训练前对原始数据集进行计算。所有预训练指标都与模型无关，因为它们不依赖于模型输出，因此对任何模型都有效。第一个偏差指标检查分面不平衡，但不检查结果。它根据应用的需要，确定训练数据量在不同分面的代表性程度。其余的偏差指标以不同方式比较了数据中分面 *a* 和分面 *d* 的结果标签分布情况。在负值范围内的指标可以检测到阴性偏差。下表包含快速指导的备忘单以及指向训练前偏差指标的链接。
训练前偏差指标
| 偏差指标 | 说明 | 示例问题 | 解析指标值 |
| --- | --- | --- | --- |
| [类别不平衡 (CI)](clarify-bias-metric-class-imbalance.md) | 衡量不同分面值之间成员数量的不平衡。 | 由于没有足够的中年分面以外的人口统计数据，是否会出现基于年龄的偏差？ | 标准化范围：[-1,\$11] 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [标签比例差异 (DPL)](clarify-data-bias-metric-true-label-imbalance.md) | 衡量不同分面值之间阳性结果的不平衡性。 | 由于数据中分面值的标注存在偏差，ML 预测中是否存在基于年龄的偏差？ | 标准化二进制和多类别分面标签的范围：[-1,\$11] 连续标签的范围：(-∞, \$1∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Kullback-Leibler 分歧 (KL)](clarify-data-bias-metric-kl-divergence.md) | 衡量不同分面的结果分布在熵上的彼此差异程度。 | 不同人口统计群体的贷款申请结果分布有何不同？ | 二进制、多类别、连续结果的范围：[0, \$1∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Jensen-Shannon 分歧 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) | 衡量不同分面的结果分布在熵上的彼此差异程度。 | 不同人口统计群体的贷款申请结果分布有何不同？ | 二进制、多类别、连续结果的范围：[0, \$1∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Lp-范数 (LP)](clarify-data-bias-metric-lp-norm.md) | 衡量数据集中不同分面相关结果的不同人口统计分布之间的 p-范数差异。 | 不同人口统计群体的贷款申请结果分布有何不同？ | 二进制、多类别、连续结果的范围：[0, \$1∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [总变差距离 (TVD)](clarify-data-bias-metric-total-variation-distance.md) | 衡量数据集中不同分面相关结果的不同人口统计分布之间的 L1-范数差异的一半。 | 不同人口统计群体的贷款申请结果分布有何不同？ | 二进制、多类别和连续结果的范围：[0, \$1∞) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) | 衡量数据集中不同分面的分布结果之间的最大差异。 | 按人口统计群体划分，哪些大学申请结果的差异最大？ | 二进制、多类别和连续结果的 KS 值范围：[0,\$11][\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [条件人口统计差异 (CDD)](clarify-data-bias-metric-cddl.md) | 从整体上衡量不同分面的结果差异，同时也按子组进行衡量。 | 某些群体在大学录取结果中被拒绝的比例是否高于其被录取的比例？ | CDD 的范围：[-1, \$11] [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-data-bias.html) |
有关偏差指标的更多信息，请参阅[金融领域机器学习的公平性衡量标准](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)。
**Topics**
+ [类别不平衡 (CI)](clarify-bias-metric-class-imbalance.md)
+ [标签比例差异 (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ [Kullback-Leibler 分歧 (KL)](clarify-data-bias-metric-kl-divergence.md)
+ [Jensen-Shannon 分歧 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ [Lp-范数 (LP)](clarify-data-bias-metric-lp-norm.md)
+ [总变差距离 (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ [Kolmogorov-Smirnov (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ [条件人口统计差异 (CDD)](clarify-data-bias-metric-cddl.md)
# 类别不平衡 (CI)
当数据集中一个分面值 *d* 比另一个分面值 *a* 的训练样本少时，就会出现类别不平衡 (CI) 偏差。这是因为模型会优先拟合较大的分面，而忽略较小的分面，因此会导致分面 *d* 的训练误差增大。模型对较小数据集过度拟合的风险也较高，这会导致分面 *d* 的测试误差增大。举个例子，如果机器学习模型主要根据中年人（分面 a）的数据进行训练，那么在做出涉及年轻人和老年人（分面 d）的预测时，其准确性可能会降低。
（标准化）分面不平衡的衡量公式：
CI = (na - nd)/(na \$1 nd)
其中 na 是分面 *a* 的成员数，nd 是分面 *d* 的成员数。它的值范围在 [-1, 1] 区间内。
+ 正 CI 值表示分面 *a* 在数据集中有更多的训练样本，值为 1 表示数据仅包含分面 *a* 的成员。
+ 接近零的 CI 值表示各分面之间的成员分布更加均衡，值为零表示各分面之间完全等分，表明训练数据中样本分布均衡。
+ 负 CI 值表示分面 *d* 在数据集中有更多的训练样本，值为 -1 表示数据仅包含分面 *d* 的成员。
+ 如果 CI 值接近 -1 或 1 这两个极值，则表示非常不平衡，很有可能导致预测结果有偏差。
如果发现各分面之间存在明显的不平衡，则对样本进行模型训练之前，可能需要重新平衡样本。
# 标签比例差异 (DPL)
标签比例差异 (DPL) 将训练数据集中分面 *d* 带有阳性标签的观测结果比例与分面 *a* 带有阳性标签的观测结果比例进行比较。例如，可以用它来比较中年人（分面 *a*）和其他年龄组的人（分面 *d*）获准获得金融贷款的比例。机器学习模型会尽可能地模仿训练数据的决策。因此，根据具有高 DPL 的数据集训练的机器学习模型很可能会在未来的预测中反映出同样的不平衡。
标签比例差异的公式如下：
DPL = (qa - qd)
其中：
+ qa = na(1)/na 是观测标签值为 1 的分面 *a* 的比例。例如，获得贷款批准的中年人口比例。这里 na(1) 表示分面 *a* 中获得阳性结果的成员数，na 表示分面 *a* 的成员数。
+ qd = nd(1)/nd 是观测标签值为 1 的分面 *d* 的比例。例如，获得贷款批准的中年人群以外人口的比例。这里 nd(1) 表示分面 *d* 中获得阳性结果的成员数，nd 表示分面 *d* 的成员数。
如果 DPL 足够接近于 0，那么我们就可以说已经实现了*人口统计均等*。
对于二进制和多类别分面标签，DPL 值的范围在区间 (-1, 1) 内。对于连续标签，我们设置了一个阈值，将标签折叠为二进制标签。
+ 正 DPL 值表示与分面 *d* 相比，分面 *a* 的阳性结果比例更高。
+ DPL 值接近于零表示各分面之间的阳性结果比例更加均等，而值为零则表示完全的人口统计均等。
+ 负 DPL 值表示与分面 *a* 相比，分面 *d* 的阳性结果比例更高。
高 DPL 是否有问题因情况而异。在有问题的情况下，高 DPL 可能是数据中存在潜在问题的信号。例如，具有高 DPL 的数据集可能反映了历史偏差或对不同年龄人口统计群体的偏见，这对模型的学习是不可取的。
# Kullback-Leibler 分歧 (KL)
Kullback-Leibler 分歧 (KL) 衡量分面 *a* 的观测标签分布 Pa(y) 与分面 *d* 的观测标签分布 Pd(y) 有多大偏差。它也称为 Pa(y) 相对于 Pd(y) 的相对熵，它量化了从 Pa(y) 移动到 Pd(y) 时丢失的信息量。
Kullback-Leibler 分歧的公式如下：
KL(Pa \$1\$1 Pd) = ∑yPa(y)\$1log[Pa(y)/Pd(y)]
它是对概率 Pa(y) 和 Pd(y) 之间对数差的期望，其中期望值由概率 Pa(y) 加权。这不是分布之间的真正距离，因为它是不对称的，不满足三角形不等式。该实现使用自然对数，得出以奈特为单位的 KL。使用不同的对数基数可以得到成比例的结果，但单位不同。例如，使用基数 2 可以得出以位为单位的 KL。
例如，假设一组贷款申请人（分面 *d*）的批准率为 30%，而其他申请人（分面 *a*）的批准率为 80%。Kullback-Leibler 公式给出了分面 *a* 与分面 *d* 的标签分布差异，如下所示：
KL = 0.8\$1ln(0.8/0.3) \$1 0.2\$1ln(0.2/0.7) = 0.53
此处的公式中有两个项，因为在本例中，标签是二进制的。除二进制标签外，此衡量标准还可应用于多个标签。例如，在大学录取场景中，假设可能为申请人分配三个类别标签之一：yi = \$1y0, y1, y2\$1 = \$1拒绝, 候补, 录取\$1。
二进制、多类别和连续结果的 KL 指标的值范围为 [0, \$1∞)。
+ 接近零的值意味着不同分面的结果分布情况相似。
+ 正值表示标签分布存在差异，正值越大，差异就越大。
# Jensen-Shannon 分歧 (JS)
Jensen-Shannon 分歧 (JS) 衡量不同分面的标签分布之间的相互偏离程度。它基于 Kullback-Leibler 分歧，但具有对称性。
Jensen-Shannon 分歧的公式如下：
JS = ½\$1[KL(Pa \$1\$1 P) \$1 KL(Pd \$1\$1 P)]
其中 P = ½( Pa \$1 Pd )，即分面 *a* 和 *d* 的平均标签分布情况。
二进制、多类别、连续结果的 JS 值范围为 [0, ln(2))。
+ 接近零的值意味着标签的分布情况相似。
+ 正值表示标签分布存在差异，正值越大，差异就越大。
该指标指示某个标签在各分面之间是否存在较大差异。
# Lp-范数 (LP)
Lp-范数 (LP) 衡量训练数据集中观测标签的分面分布之间的 p-范数距离。该指标为非负值，因此无法检测到反向偏差。
Lp-范数的公式如下：
Lp(Pa, Pd) = ( ∑y\$1\$1Pa - Pd\$1\$1p)1/p
其中，点 x 和 y 之间的 p-范数距离定义如下：
Lp(x, y) = (\$1x1-y1\$1p \$1 \$1x2-y2\$1p \$1 … \$1\$1xn-yn\$1p)1/p
2-范数是欧几里得范数。假设结果分布有三个类别，例如，在大学录取多类别场景中，yi = \$1y0, y1, y2\$1 = \$1录取, 候补, 拒绝\$1。取分面 *a* 和 *d* 的结果计数之差的平方和。由此得出的欧几里得距离计算如下：
L2(Pa, Pd) = [(na(0) - nd(0))2 \$1 (na(1) - nd(1))2 \$1 (na(2) - nd(2))2]1/2
其中：
+ na(i) 是分面 *a* 中第 i 个类别结果的数量：例如 na(0) 是分面 *a* 的接受次数。
+ nd(i) 是分面 *d* 中第 i 个类别结果的数量：例如 nd(2) 是分面 *d* 的拒绝次数。
二进制、多类别和连续结果的 LP 值范围为 [0, √2)，其中：
+ 接近零的值意味着标签的分布情况相似。
+ 正值表示标签分布存在差异，正值越大，差异就越大。
# 总变差距离 (TVD)
总变差距离数据偏差指标 (TVD) 是 L1-范数的一半。TVD 是分面 *a* 和分面 *d* 标签结果的概率分布之间可能存在的最大差异。L1-范数是汉明距离，该指标用于通过确定将一个字符串更改为另一个字符串所需的最小替换次数来比较两个二进制数据字符串。如果字符串是彼此的副本，它将确定复制时发生错误的次数。在偏差检测的背景下，TVD 量化了为与分面 *d* 中的结果相匹配而必须更改分面 *a* 中的结果数量。
总变差距离的公式如下：
TVD = ½\$1L1(Pa, Pd)
例如，在大学录取多类别场景中，假设结果分布有三个类别，yi = \$1y0, y1, y2\$1 = \$1录取, 候补, 拒绝\$1。您可以利用每个结果的分面 *a* 和分面 *d* 的计数之差计算 TVD。结果如下：
L1(Pa, Pd) = \$1na(0) - nd(0)\$1 \$1 \$1na(1) - nd(1)\$1 \$1 \$1na(2) - nd(2)\$1
其中：
+ na(i) 是分面 *a* 中第 i 个类别结果的数量：例如 na(0) 是分面 *a* 的接受次数。
+ nd(i) 是分面 d 中第 i 个类别结果的数量：例如 nd(2) 是分面 *d* 的拒绝次数。
二进制、多类别和连续结果的 TVD 值范围为 [0, 1)，其中：
+ 接近零的值意味着标签的分布情况相似。
+ 正值表示标签分布存在差异，正值越大，差异就越大。
# Kolmogorov-Smirnov (KS)
Kolmogorov-Smirnov 偏差指标 (KS) 等于数据集的分面 *a* 和分面 *d* 分布中标签之间的最大差异。Clarify实施的双样本KS测试通过 SageMaker 找到最不平衡的标签来补充其他标签失衡的衡量标准。
Kolmogorov-Smirnov 指标的公式如下：
KS = max(\$1Pa(y) - Pd(y)\$1)
例如，假设一组大学申请人（分面 *a*）被拒绝、列入候补名单或被录取的比率分别为 40%、40% 和 20%，而其他申请人（分面 *d*）的这些比率分别为 20%、10% 和 70%，则 Kolmogorov-Smirnov 偏差指标值如下所示：
KS = max(\$10.4-0.2\$1, \$10.4-0.1\$1, \$10.2-0.7\$1) = 0.5
这表明分面分布之间的最大差异为 0.5，并且出现在接受率中。等式中有三个项，因为标签是基数为三的多类。
二进制、多类别和连续结果的 LP 值范围为 [0, \$11]，其中：
+ 接近零的值表示标签在所有结果类别的各分面之间均匀分布。例如，申请贷款的两个分面分别获得了 50% 的接受率和 50% 的拒绝率。
+ 接近一的值表示一个结果的标签都集中在一个分面。例如，分面 *a* 获得了 100% 的接受率，而分面 *d* 的接受率为零。
+ 间歇值表示最大标签不平衡的相对程度。
# 条件人口统计差异 (CDD)
人口统计差异 (DD) 决定了某一分面在数据集中被拒绝结果的比例是否高于被接受结果的比例。在有两个分面（例如男性和女性）构成数据集的二进制情况下，不利分面被标注为分面 *d*，有利分面被标注为分面 *a*。例如，在大学录取场景中，如果女性申请人占被拒绝申请人的 46%，而只占被录取申请人的 32%，我们就会说这是一种*人口统计差异*，因为女性被拒绝的比率超过了她们被录取的比率。在这种情况下，女性申请人被标注为分面 *d*。如果男性申请人占被拒绝申请人的 54%，占被录取申请人的 68%，那么这一分面就不存在人口统计差异，因为拒绝率低于录取率。在这种情况下，男性申请人被标注为分面 *a*。
较不利分面 *d* 的人口统计差异公式如下：
DDd = nd(0)/n(0) - nd(1)/n(1) = PdR(y0) - PdA(y1)
其中：
+ n(0) = na(0) \$1 nd(0) 是数据集中有利分面 *a* 和不利分面 *d* 的被拒绝结果总数。
+ n(1) = na(1) \$1 nd(1) 是数据集中有利分面 *a* 和不利分面 *d* 的被接受结果总数。
+ PdR(y0) 是分面 *d* 中被拒绝结果（值为 0）的比例。
+ PdA(y1) 是分面 *d* 中被接受结果（值为 1）的比例。
以大学录取为例，女性的人口统计差异为 DDd = 0.46 - 0.32 = 0.14。男性则为 DDa = 0.54 - 0.68 = - 0.14。
为了排除辛普森悖论，需要使用条件人口统计差异 (CDD) 指标，该指标根据数据集上定义子组层次的属性来限制 DD。通过重新分组，可以深入了解较不利分面出现明显人口统计差异的原因。经典案例是伯克利大学招生案例，该大学的男性录取率总体上高于女性。DD 的示例计算中使用了该案例的统计数据。但研究院系子组后，我们发现，在某些院系，女性的录取率高于男性。对此的解释是，女性申请的院系比男性申请的院系的录取率低。研究子组录取率后发现，在录取率较低的院系中，女性的录取率实际上高于男性。
CDD 指标通过对数据集的某一属性所定义的子组中发现的所有差异进行平均，从而给出一个单一的衡量标准。它被定义为每个子组的人口统计差异 (DDi) 的加权平均值，每个子组的差异根据所含观测值的数量按比例加权。条件人口统计差异公式如下：
CDD = (1/n)\$1∑ini \$1DDi
其中：
+ ∑ini = n 是观测值的总数，ni 是每个子组的观测值数。
+ DDi = ni(0)/n(0) - ni(1)/n(1) = PiR(y0) - PiA(y1) 是第 i 个子组的人口统计差异。
子组 (DDi) 的人口统计差异是每个子组被拒绝结果的比例与被接受结果的比例之间的差异。
整个数据集 DDd 或其条件化子组 DDi 的二进制结果的 DD 值范围为 [-1, \$11]。
+ \$11：当分面 *a* 或子组中拒绝率为零且分面 *d* 或子组中接受率为零时
+ 正值表示存在人口统计差异，因为分面 *d* 或子组在数据集中被拒绝结果的比例高于被接受结果的比例。值越高，该分面就越不利，差异也越大。
+ 负值表示不存在人口统计差异，因为分面 *d* 或子组在数据集中被接受结果的比例高于被拒绝结果的比例。值越低，该分面就越有利。
+ -1：当分面 *d* 或子组中的拒绝率为零且分面 *a* 或子组中接受率为零时
如果不附加任何条件，那么当且仅当 DPL 为零时，CDD 才为零。
该指标有助于探讨直接和间接歧视的概念，以及欧盟和英国非歧视法和判例中的客观理由的概念。有关更多信息，请参阅 [Why Fairness Cannot Be Automated](https://arxiv.org/abs/2005.05906)（为何无法自动实现公平）。这篇论文还包含伯克利招生案例的相关数据和分析，该案例介绍了以院系录取率子组为条件如何说明辛普森悖论。
# 在 Studio 中生成训练前数据偏差报告 SageMaker
SageMaker Clarify 与 Amazon SageMaker Data Wrangler 集成，它可以帮助您在数据准备过程中识别偏见，而无需自己编写代码。Data Wrangler 提供了一种使用 Amazon Studio 导入、准备、转换、特征化和分析数据的 end-to-end解决方案。 SageMaker 有关 Data Wrangler 数据准备工作流的概述，请参阅[使用 Amazon Data Wrangler 准备机器学习 SageMaker 数据](data-wrangler.md)。
您可以指定感兴趣的属性，例如性别或年龄，Clar SageMaker ify 会运行一组算法来检测这些属性中是否存在偏差。算法运行后，Cl SageMaker arify 会提供一份可视化报告，其中描述了可能存在的偏见的来源和严重程度，以便您可以计划缓解措施。例如，在一个金融数据集中，与其他年龄组相比，向一个年龄组提供的商业贷款的例子很少， SageMaker 人工智能会标记这种不平衡，这样你就可以避免使用不利于该年龄组的模型。
**分析和报告数据偏差**
要开始使用 Data Wrangler，请参阅 [开始使用 Data Wrangler](data-wrangler-getting-started.md)。
1. 在 Amazon SageMaker Studio Classic 中，从左侧面板的 “**主页**” (![\[Black square icon representing a placeholder or empty image.\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/studio/icons/house.png)) 菜单中导航到 “**数据**” 节点，然后选择 D **ata Wrang** ler。这将在 Studio Classic 中打开 **Data Wrangler 登录页面**。
1. 选择 **\$1 导入数据**按钮以创建新流程。
1. 在流程页面中，从**导入**选项卡中选择 Amazon S3，导航到您的 Amazon S3 存储桶，找到您的数据集，然后选择**导入**。
1. 导入数据后，在**数据流**选项卡的流图上，选择**数据类型**节点右侧的 **\$1** 符号。
1. 选择**添加分析**。
1. 在**创建分析**页面上，为**分析类型**选择**偏差报告**。
1. 通过提供报告**名称**、要预测的列以及它是值还是阈值、要分析偏差的列（分面）以及它是值还是阈值，配置偏差报告。
1. 通过选择偏差指标继续配置偏差报告。
![\[选择偏差指标。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify-data-wrangler-configure-bias-metrics.png)
1. 选择**检查偏差**以生成并查看偏差报告。向下滚动以查看所有报告。
![\[生成并查看偏差报告。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify-data-wrangler-create-bias-report.png)
1. 选择每个偏差指标描述右侧的插入符号，查看可帮助您解释指标值重要性的文档。
1. 要查看偏差指标值的表格摘要，请选择**表格**开关。要保存报告，请选择页面右下角的**保存**。您可以在**数据流**选项卡的流图上查看报告。双击报告将其打开。
# 训练后数据和模型偏差
训练后偏差分析有助于揭示可能由数据中偏差或由分类和预测算法引入的偏差所引起的偏差。这些分析考虑了数据（包括标签）和模型的预测。您可以通过分析预测标签，或者针对具有不同属性的组，通过将预测值与数据中观测到的目标值进行比较，来评估性能。公平有不同的概念，每种概念都需要不同的偏差指标来衡量。
有些关于公平的法律概念可能不容易理解，因为它们难以检测到。例如，在美国，差别影响概念是指，即使所采取的方法看似公平，但某个群体（称为较不利的分面 *d*）仍会受到不利影响。这种偏差可能不是由机器学习模型引起，但仍可通过训练后偏差分析检测到。
Ama SageMaker zon Clarify 努力确保术语的使用一致。有关术语及其定义的列表，请参阅 [Amazon SageMaker 澄清偏见和公平条款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)。
有关训练后偏见指标的更多信息，请参阅[了解 Amazon Clari SageMaker fy 如何帮助检测金融领域机器学习的偏见](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)[和公平措施](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)。 。
# 训练后数据和模型偏差指标
Amaz SageMaker on Clarify 提供了 11 个训练后数据和模型偏差指标，以帮助量化各种公平概念。这些概念不可能同时得到满足，如何选择取决于所分析的涉及潜在偏差案例的具体情况。这些指标大多是从不同人口统计群体的二进制分类混淆矩阵中提取的数字的组合。由于公平性和偏差可通过多种指标来定义，因此需要人为判断来理解和选择哪些指标与个别使用案例相关，客户应咨询相应的利益相关者，以确定其应用的适当公平性衡量标准。
我们使用以下表示法来讨论偏差指标。此处描述的概念模型适用于二进制分类，即事件被标记为在其样本空间中只有两种可能的结果，分别称为阳性结果（值为 1）和阴性结果（值为 0）。这一框架通常可以直接扩展到多类别分类，或在需要时扩展到涉及持续有价值结果的情况。在二进制分类的情况下，分别为原始数据集中记录的结果中的有利分面 *a* 和不利分面 *d* 分配阳性标签和阴性标签。这些标签 y 称为*观测标签*，以区别于机器学习模型在机器学习生命周期的训练或推理阶段分配的*预测标签* y'。这些标签用于定义各自分面结果的概率分布 Pa(y) 和 Pd(y)。
+ 标签：
+ y 表示训练数据集中观测到的事件结果的 n 个标签。
+ y' 表示经过训练的模型对数据集中 n 个观测标签的预测标签。
+ 结果：
+ 样本的阳性结果（值为 1），例如申请被接受。
+ n(1) 是阳性结果（接受）的观测标签数量。
+ n'(1) 是阳性结果（接受）的预测标签数量。
+ 样本的阴性结果（值为 0），例如申请被拒绝。
+ n(0) 是阴性结果（拒绝）的观测标签数量。
+ n'(0) 是阴性结果（拒绝）的预测标签数量。
+ 分面值：
+ 分面 *a* - 定义偏差有利的人口统计的特征值。
+ na 是有利分面值的观测标签数：na = na(1) \$1 na(0) 分面值 *a* 的阳性和阴性观测标签之和。
+ n'a 是有利分面值的预测标签数：n'a = n'a(1) \$1 n'a(0) 分面值 *a* 的阳性和阴性预测结果标签之和。请注意，n'a = na。
+ 分面 *d* - 定义偏差不利的人口统计的特征值。
+ nd 是不利分面值的观测标签数：nd = nd(1) \$1 nd(0) 分面值 *d* 的阳性和阴性观测标签之和。
+ n'd 是不利分面值的预测标签数：n'd = n'd(1) \$1 n'd(0) 分面值 *d* 的阳性和阴性预测标签之和。请注意，n'd = nd。
+ 标注的分面数据结果的概率分布：
+ Pa(y) 是分面 *a* 的观测标签的概率分布。对于二进制标注的数据，该分布由分面 *a* 中标注为阳性结果的样本数与总样本数之比 Pa(y1) = na(1)/ na，以及标注为阴性结果的样本数与总样本数之比 Pa(y0) = na(0)/ na 得出。
+ Pd(y) 是分面 *d* 的观测标签的概率分布。对于二进制标注的数据，该分布由分面 *d* 中标注为阳性结果的样本数与总样本数之比 Pd(y1) = nd(1)/ nd，以及标注为阴性结果的样本数与总样本数之比 Pd(y0) = nd(0)/ nd 得出。
下表包含快速指导的备忘单以及指向训练后偏差指标的链接。
训练后偏差指标
| 训练后偏差指标 | 说明 | 示例问题 | 解析指标值 |
| --- | --- | --- | --- |
| [预测标签中正比例的差异 (DPPL)](clarify-post-training-bias-metric-dppl.md) | 衡量有利分面 a 和不利分面 d 之间阳性预测值比例的差异。 | 在预测的阳性结果中，各人口统计群体之间是否存在可能表明偏差的不平衡？ | 标准化二进制和多类别分面标签的范围：`[-1,+1]` 连续标签的范围：(-∞, \$1∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [差别影响 (DI)](clarify-post-training-bias-metric-di.md) | 测量有利分面 a 和不利分面 d 的预测标签比例之比。 | 在预测的阳性结果中，各人口统计群体之间是否存在可能表明偏差的不平衡？ | 标准化二进制、多类别分面和连续标签的范围：[0,∞) 解释： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [预测标签中的条件人口统计差异 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) | 从整体上衡量各分面的预测标签差异，同时也按子组进行衡量。 | 某些人口统计群体在贷款申请结果中被拒绝的比例是否高于其被接受的比例？ | 二进制、多类别和连续结果的 CDDPL 值范围：`[-1, +1]` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [反事实翻转测试 (FT)](clarify-post-training-bias-metric-ft.md) | 检查分面 d 的每个成员并评估分面 a 的相似成员是否具有不同的模型预测。 | 某一特定年龄段的人群是否与另一年龄段的人群在所有特征上都非常接近，但平均收入却更高？ | 二进制和多类别分面标签的范围为 [-1, \$11]。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [准确率差异 (AD)](clarify-post-training-bias-metric-ad.md) | 衡量有利和不利分面的预测准确率之间的差异。 | 该模型对所有人口统计群体应用的标签预测是否同样准确？ | 二进制和多类别分面标签的范围为 [-1, \$11]。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [查全率差异 (RD)](clarify-post-training-bias-metric-rd.md) | 比较模型对有利和不利分面的查全率。 | 模型对某个年龄组的查全率高于另一年龄组，这是否会造成基于年龄的贷款偏差？ | 二进制和多类别分类的范围：`[-1, +1]`。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [有条件录取的差异 (DCAcc)](clarify-post-training-bias-metric-dcacc.md) | 将观测标签与模型预测的标签进行比较。评估各分面的预测阳性结果（接受）是否相同。 | 在将一个年龄组与另一个年龄组进行比较时，接受贷款的频率是高于还是低于预测值（基于资格条件）？ | 二进制、多类别分面和连续标签的范围：(-∞, \$1∞)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [接受率差异 (DAR)](clarify-post-training-bias-metric-dar.md) | 衡量有利和不利分面在观测的阳性结果 (TP) 与预测的阳性结果 (TP \$1 FP) 之比方面的差异。 | 该模型在预测各年龄组合格申请人的贷款接受情况时是否具有同等精度？ | 二进制、多类别分面和连续标签的范围为 [-1, \$11]。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [特异性差异 (SD)](clarify-post-training-bias-metric-sd.md) | 比较模型对有利和不利分面的特异性。 | 模型预测某个年龄组的特异性高于另一年龄组，这是否会造成基于年龄的贷款偏差？ | 二进制和多类别分类的范围：`[-1, +1]`。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [有条件拒绝差异 (DCR)](clarify-post-training-bias-metric-dcr.md) | 将观测标签与模型预测标签进行比较，并评估各分面的阴性结果（拒绝）是否相同。 | 一个年龄组与另一年龄组相比，基于资格条件预测的贷款申请被拒绝的次数是多还是少？ | 二进制、多类别分面和连续标签的范围：(-∞, \$1∞)。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [拒绝率差异 (DRR)](clarify-post-training-bias-metric-drr.md) | 衡量不利和有利分面在观测的阴性结果 (TN) 与预测的阴性结果 (TN \$1 FN) 之比方面的差异。 | 该模型在预测各年龄组不合格申请人的贷款拒绝情况时是否具有同等精度？ | 二进制、多类别分面和连续标签的范围为 [-1, \$11]。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [平等对待 (TE)](clarify-post-training-bias-metric-te.md) | 衡量有利和不利分面在假阳性与假阴性之比方面的差异。 | 在贷款申请中，所有年龄段人口的假阳性与假阴性的相对比率是否相同？ | 二进制和多类别分面标签的范围：(-∞, \$1∞)。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [广义熵 (GE)](clarify-post-training-bias-metric-ge.md) | 衡量模型预测中分配给每项输入的权益 b 的不平等程度。 | 在贷款申请分类的两个候选模型中，一个模型是否比另一个模型导致预期结果的分布更不均衡？ | 二进制和多类别标签的范围：(0, 0.5)。当模型仅预测假阴性时，GE 的定义不明确。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
有关训练后偏差指标的更多信息，请参阅[金融领域机器学习的公平性衡量标准系列](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)。
**Topics**
+ [预测标签中正比例的差异 (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ [差别影响 (DI)](clarify-post-training-bias-metric-di.md)
+ [有条件录取的差异 (DCAcc)](clarify-post-training-bias-metric-dcacc.md)
+ [有条件拒绝差异 (DCR)](clarify-post-training-bias-metric-dcr.md)
+ [特异性差异 (SD)](clarify-post-training-bias-metric-sd.md)
+ [查全率差异 (RD)](clarify-post-training-bias-metric-rd.md)
+ [接受率差异 (DAR)](clarify-post-training-bias-metric-dar.md)
+ [拒绝率差异 (DRR)](clarify-post-training-bias-metric-drr.md)
+ [准确率差异 (AD)](clarify-post-training-bias-metric-ad.md)
+ [平等对待 (TE)](clarify-post-training-bias-metric-te.md)
+ [预测标签中的条件人口统计差异 (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ [反事实翻转测试 (FT)](clarify-post-training-bias-metric-ft.md)
+ [广义熵 (GE)](clarify-post-training-bias-metric-ge.md)
# 预测标签中正比例的差异 (DPPL)
预测标签中正比例的差异 (DPPL) 指标可确定模型对每个分面的结果预测是否不同。其定义是分面 *a* 的阳性预测值 (y’ = 1) 比例与分面 *d* 的阳性预测值 (y’ = 1) 比例之差。例如，如果模型预测向 60% 的中年组（分面 *a*）和 50% 的其他年龄组（分面 *d*）发放贷款，则可能存在不利于分面 *d* 的偏差。在本例中，您必须确定这 10% 的差异是否对偏差案例有实质性影响。
标签比例差异 (DPL) 是衡量训练前偏差的指标，而 DPPL 则是衡量训练后偏差的指标，两者的比较可以评测数据集中最初存在的正比例偏差在训练后是否发生了变化。如果 DPPL 大于 DPL，那么训练后正比例的偏差就会增加。如果 DPPL 小于 DPL，则说明模型在训练后没有增加正比例偏差。将 DPL 与 DPPL 进行比较并不能保证该模型在所有方面都能减少偏差。例如，在考虑 [反事实翻转测试 (FT)](clarify-post-training-bias-metric-ft.md) 或 [准确率差异 (AD)](clarify-post-training-bias-metric-ad.md) 等其他指标时，模型可能仍然存在偏差。有关偏见检测的更多信息，请参阅博客文章[了解 Amazon Clarif SageMaker y 如何帮助检测偏见](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)。有关 DPL 的更多信息，请参阅 [标签比例差异 (DPL)](clarify-data-bias-metric-true-label-imbalance.md)。
DPPL 的计算公式为：
DPPL = q'a - q'd
其中：
+ q'a = n'a(1)/na 是分面 *a* 中得到值为 1 的阳性结果的预测比例。在我们的例子中，是预计获得贷款的中年组分面的比例。这里 n'a(1) 表示分面 *a* 中获得值为 1 的阳性预测结果的成员数，na 表示分面 *a* 的成员数。
+ q'd = n'd(1)/nd 是分面 *d* 中获得值为 1 的阳性结果的预测比例。在我们的例子中，有一部分老年人和年轻人预计会获得贷款。这里 n'd(1) 表示分面 *d* 中获得阳性预测结果的成员数，nd 表示分面 *d* 的成员数。
如果 DPPL 足够接近于 0，则表示已经实现了训练后*人口统计均等*。
对于二进制和多类别分面标签，标准化 DPL 值范围在 [-1, 1] 区间内。对于连续标签，值在区间 (-∞, \$1∞) 内变化。
+ 正 DPPL 值表示与分面 *d* 相比，分面 *a* 的预测阳性结果比例更高。
这称为*正偏差*。
+ DPPL 值接近于零表示分面 *a* 和分面 *d* 之间的预测阳性结果比例更加均等，而值为零则表示完全的人口统计均等。
+ 负 DPPL 值表示与分面 *a* 相比，分面 *d* 的预测阳性结果比例更高。这称为*负偏差*。
# 差别影响 (DI)
预测标签中正比例的差异指标可通过比率的形式来评估。
预测标签中正比例的比较指标可通过比率的形式来评估，而不是像[预测标签中正比例的差异 (DPPL)](clarify-post-training-bias-metric-dppl.md) 那样用差值来评估。差别影响 (DI) 指标定义为分面 *d* 的阳性预测值 (y' = 1) 比例与分面 *a* 的阳性预测值 (y' = 1) 比例之比。例如，如果模型预测向 60% 的中年组（分面 *a*）和 50% 的其他年龄组（分面 *d*）发放贷款，则 DI = .5/.6 = 0.8，这表明存在正偏差，并对分面 *d* 所代表的其他年龄组产生不利影响。
预测标签比例比率的公式：
DI = q'd/q'a
其中：
+ q'a = n'a(1)/na 是分面 *a* 中得到值为 1 的阳性结果的预测比例。在我们的例子中，是预计获得贷款的中年组分面的比例。这里 n'a(1) 表示分面 *a* 中获得阳性预测结果的成员数，na 表示分面 *a* 的成员数。
+ q'd = n'd(1)/nd 是分面 *d* 中获得值为 1 的阳性结果的预测比例。在我们的例子中，有一部分老年人和年轻人预计会获得贷款。这里 n'd(1) 表示分面 *d* 中获得阳性预测结果的成员数，nd 表示分面 *d* 的成员数。
对于二进制、多类别分面和连续标签，DI 值的范围在 [0, ∞) 区间内。
+ 值小于 1 表示分面 *a* 的预测阳性结果比例高于分面 *d*。这称为*正偏差*。
+ 值为 1 表示人口统计均等。
+ 值大于 1 表示分面 *d* 的预测阳性结果比例高于分面 *a*。这称为*负偏差*。
# 有条件录取的差异 (DCAcc)
该指标将观测标签与模型预测标签进行比较，并评估各分面的预测阳性结果是否相同。该指标接近于模仿人类的偏差，因为它量化了与训练数据集中观测的结果（标签 y）相比，模型对某个分面预测的阳性结果（标签 y'）多了多少。例如，如果与包含其他年龄组的分面（分面 *d*）相比，在训练数据集中观测的中年组（分面 *a*）贷款申请的接受率（阳性结果）高于基于资格条件的模型预测值，则可能表明贷款批准方式上存在有利于中年组的潜在偏差。
有条件接受差异的公式：
DCAcc = c a-c d
其中：
+ ca = na(1)/ n'a(1) 是分面 *a* 中值为 1（接受）的观测阳性结果数与分面 *a* 的预测阳性结果（接受）数之比。
+ cd = nd(1)/ n'd(1) 是分面 *d* 中值为 1（接受）的观测阳性结果数与分面 *d* 的预测阳性结果（接受）数之比。
该 DCAcc 指标可以捕捉正面和负面的偏见，这些偏见揭示了基于资格的优惠待遇。请考虑以下在贷款接受方面存在基于年龄的偏差的示例。
**示例 1：正偏差**
假设我们的数据集有 100 名中年人（分面 *a*）和 50 名来自其他年龄组的人（分面 *d*）申请贷款，其中模型建议向分面 *a* 中的 60 人和分面 *d* 中的 30 人发放贷款。因此，就 DPPL 指标而言，预测的比例无偏差，但观测标签显示，分面 *a* 中的 70 人和分面 *d* 中的 20 人获得了贷款。换句话说，该模型向中年组分面发放贷款的人数比训练数据中建议的观测标签少 17% (70/60 = 1.17)，向其他年龄组发放贷款的人数比建议的观测标签多 33% (20/30 = 0.67)。该 DCAcc 值的计算结果如下：
DCAcc = 70/60-20/30 = 1/2
正值表示存在对中年组分面 *a* 的潜在偏差，与另一分面 *d* 相比，接受率低于观测数据（视为无偏差）所指示的值。
**示例 2：负偏差**
假设我们的数据集有 100 名中年人（分面 *a*）和 50 名来自其他年龄组的人（分面 *d*）申请贷款，其中模型建议向分面 *a* 中的 60 人和分面 *d* 中的 30 人发放贷款。因此，就 DPPL 指标而言，预测的比例无偏差，但观测标签显示，分面 *a* 中的 50 人和分面 *d* 中的 40 人获得了贷款。换句话说，该模型向中年组分面发放贷款的人数比训练数据中建议的观测标签少 17% (50/60 = 0.83)，向其他年龄组发放贷款的人数比建议的观测标签多 33% (40/30 = 1.33)。该 DCAcc 值的计算结果如下：
DCAcc = 50/60-40/30 = -1/2
负值表示存在不利于分面 *d* 的潜在偏差，与中年组分面 *a* 相比，接受率低于观测数据（视为无偏差）所指示的值。
请注意，您可以使用 DCAcc 来帮助您检测人类在环境中监督模型预测的潜在（非故意的）偏差。 human-in-the-loop例如，假设模型的预测 y' 无偏差，但最终决策由人类做出（可能还可以访问其他特征），该人可以修改模型预测以生成新的最终版 y'。从一个方面来看，人为的额外处理可能会无意中拒绝向不成比例的人提供贷款。 DCAcc可以帮助发现此类潜在的偏见。
二进制、多类别分面和连续标签的有条件接受差异的值范围为 (-∞, \$1∞)。
+ 当分面 *a* 的观测接受次数与预测接受次数之比高于分面 *d* 的这一比率时，就会出现正值。这些值表示可能存在不利于分面 *a* 中合格申请人的偏差。比率的差异越大，表观偏差就越严重。
+ 当分面 *a* 的观测接受次数与预测接受次数之比类似于分面 *d* 的这一比率时，就会出现接近零的值。这些值表示预测的接受率与标签数据中的观测值一致，并且两个分面的合格申请人被接受的情况相似。
+ 当分面 *a* 的观测接受次数与预测接受次数之比低于分面 *d* 的这一比率时，就会出现负值。这些值表示可能存在不利于分面 *d* 中合格申请人的偏差。比率的差异越负，表观偏差就越严重。
# 有条件拒绝差异 (DCR)
该指标将观测标签与模型预测标签进行比较，并评估各分面的阴性结果（拒绝）是否相同。该指标接近于模仿人类的偏差，因为它量化了与训练数据集中标签建议值（观测标签 y）相比，模型对某个分面赋予的阴性结果（预测标签 y'）多了多少。例如，如果与包含其他年龄组的分面（分面 *d*）相比，观测的中年组（分面 *a*）贷款申请被拒绝（阴性结果）的次数多于模型基于资格条件预测的值，则可能表明在拒绝贷款的方式上存在潜在偏差，中年组比其他组更有利。
有条件接受差异的公式：
DCR = rd - ra
其中：
+ rd = nd(0)/ n'd(0) 是分面 *d* 中值为 0 的观测阴性结果（拒绝）数与分面 *d* 的预测阴性结果（拒绝）数之比。
+ ra = na(0)/ n'a(0) 是分面 *a* 中值为 0 的观测阴性结果（拒绝）数与分面 *a* 的预测阴性结果（拒绝）数之比。
DCR 指标既能反映正偏差，也能反映负偏差，这些偏差揭示了基于资格条件的优先处理。请考虑以下在贷款拒绝方面存在基于年龄的偏差的示例。
**示例 1：正偏差**
假设我们的数据集有 100 名中年人（分面 *a*）和 50 名来自其他年龄组的人（分面 *d*）申请贷款，其中模型建议拒绝向分面 *a* 中的 60 人和分面 *d* 中的 30 人发放贷款。因此，根据 DPPL 指标，预测的比例无偏差，但观测标签显示，分面 *a* 中的 50 人和分面 *d* 中的 40 人被拒绝。换句话说，该模型拒绝向中年组分面发放贷款的人数比训练数据中建议的观测标签多 17% (50/60 = 0.83)，拒绝向其他年龄组发放贷款的人数比建议的观测标签少 33% (40/30 = 1.33)。DCR 值量化了各分面之间在观测到的拒绝率与预测的拒绝率之比方面的这种差异。正值表示存在有利于中年组的潜在偏差，与其他组相比，拒绝率低于观测数据（视为无偏差）所指示的值。
DCR = 40/30 - 50/60 = 1/2
**示例 2：负偏差**
假设我们的数据集有 100 名中年人（分面 *a*）和 50 名来自其他年龄组的人（分面 *d*）申请贷款，其中模型建议拒绝向分面 *a* 中的 60 人和分面 *d* 中的 30 人发放贷款。因此，根据 DPPL 指标，预测的比例无偏差，但观测标签显示，分面 *a* 中的 70 人和分面 *d* 中的 20 人被拒绝。换句话说，该模型拒绝向中年组分面发放贷款的人数比训练数据中建议的观测标签少 17% (70/60 = 1.17)，拒绝向其他年龄组发放贷款的人数比建议的观测标签多 33% (20/30 = 0.67)。负值表示存在有利于分面 *a* 的潜在偏差，与中年组分面 *d* 相比，拒绝率低于观测数据（视为无偏差）所指示的值。
DCR = 20/30 - 70/60 = -1/2
二进制、多类别分面和连续标签的有条件拒绝差异的值范围为 (-∞, \$1∞)。
+ 当分面 *d* 的观测拒绝次数与预测拒绝次数之比高于分面 *a* 的这一比率时，就会出现正值。这些值表示可能存在不利于分面 *a* 中合格申请人的偏差。DCR 指标值越大，表观偏差就越严重。
+ 当分面 *a* 的观测拒绝次数与预测拒绝次数之比类似于分面 *d* 的这一比率时，就会出现接近零的值。这些值表示预测的拒绝率与标签数据中的观测值一致，并且两个分面的合格申请人被拒绝的情况相似。
+ 当分面 *d* 的观测拒绝次数与预测拒绝次数之比低于分面 *a* 的这一比率时，就会出现负值。这些值表示可能存在不利于分面 *d* 中合格申请人的偏差。负 DCR 指标的幅度越大，表观偏差就越严重。
# 特异性差异 (SD)
特异性差异 (SD) 是有利分面 *a* 和不利分面 *d* 之间的特异性差异。特异性衡量模型正确预测阴性结果 (y'=0) 的频率。这些特异性的任何差异都是一种潜在的偏差。
如果某一分面的所有 y=0 案例都正确预测，则该分面的特异性是完美的。当模型尽可能地减少假阳性（即 I 型错误）时，特异性就会更高。例如，向分面 *a* 提供贷款的低特异性与向分面 *d* 提供贷款的高特异性之间的差异是衡量不利于分面 *d* 的偏差的一项指标。
以下公式用于计算分面 *a* 和 *d* 的特异性差异。
SD = TNd/(TNd \$1 FPd) - TNa/(TNa \$1 FPa) = TNRd - TNRa
用于计算 SD 的变量定义如下：
+ TNd 是分面 *d* 的真阴性预测值。
+ FPd 是分面 *d* 的假阳性预测值。
+ TNd 是分面 *a* 的真阴性预测值。
+ FPd 是分面 *a* 的假阳性预测值。
+ TNRa = TNa/(TNa \$1 FPa) 是分面 *a* 的真阴性率，也称为特异性。
+ TNRd = TNd/(TNd \$1 FPd) 是分面 *d* 的真阴性率，也称为特异性。
例如，考虑分面 *a* 和 *d* 的以下混淆矩阵。
有利分面 `a` 的混淆矩阵
| 类 a 预测 | 实际结果 0 | 实际结果 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
不利分面 `d` 的混淆矩阵
| 类 d 预测 | 实际结果 0 | 实际结果 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
特异性差异值为 `SD = 18/(18+5) - 20/(20+10) = 0.7826 - 0.6667 = 0.1159`，表示存在不利于分面 *d* 的偏差。
对于二进制和多类别分类，分面 *a* 和 *d* 之间的特异性差异值范围为 `[-1, +1]`。此指标对连续标签不可用。以下是不同 SD 值的含义：
+ 当分面 *d* 的特异性高于分面 *a* 时，就会获得正值。这表明该模型发现分面 *d* 的假阳性少于分面 *a* 的假阳性。正值表示存在不利于分面 *d* 的偏差。
+ 接近零的值表示所比较的分面的特异性相似。这表明该模型在这两个分面发现的假阳性数量相似，没有偏差。
+ 当分面 *a* 的特异性高于分面 *d* 时，就会获得负值。这表明该模型发现分面 *a* 的假阳性多于分面 *d* 的假阳性。负值表示存在不利于分面 *a* 的偏差。
# 查全率差异 (RD)
查全率差异 (RD) 指标是模型在有利分面 *a* 和不利分面 *d* 之间的查全率差异。这些查全率的任何差异都是一种潜在的偏差。查全率是真阳性率 (TPR)，用于衡量模型正确预测应得到阳性结果的案例的频率。如果某一分面的所有 y=1 案例都正确预测为 y'=1，则该分面的查全率是完美的。当模型尽可能地减少假阴性（即 II 型错误）时，查全率会更高。例如，模型正确检测了两个不同组（分面 *a* 和 *d*）中有多少人本应有资格获得贷款？ 如果向分面 *a* 提供贷款的查全率高，而向分面 *d* 提供贷款的查全率低，那么差异就可用来衡量这种不利于分面 *d* 中组的偏差。
分面 *a* 和 *d* 查全率差异的公式：
RD = TPa/(TPa \$1 FNa) - TPd/(TPd \$1 FNd) = TPRa - TPRd
其中：
+ TPa 是分面 *a* 的真阳性预测值。
+ FNa 是分面 *a* 的假阴性预测值。
+ TPd 是分面 *d* 的真阳性预测值。
+ FNd 是分面 *d* 的假阴性预测值。
+ TPRa = TPa/(TPa \$1 FNa) 是分面 *a* 的查全率或其真阳性率。
+ TPRd TPd/(TPd \$1 FNd) 是分面 *d* 的查全率或其真阳性率。
例如，考虑分面 *a* 和 *d* 的以下混淆矩阵。
有利分面 a 的混淆矩阵
| 类 a 预测 | 实际结果 0 | 实际结果 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
不利分面 d 的混淆矩阵
| 类 d 预测 | 实际结果 0 | 实际结果 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
查全率差异值为 RD = 65/70 - 20/27 = 0.93 - 0.74 = 0.19，这表明存在不利于分面 *d* 的偏差。
对于二进制和多类别分类，分面 *a* 和 *d* 之间的查全率差异值范围为 [-1, \$11]。此指标对连续标签不可用。
+ 当分面 *a* 的查全率高于分面 *d* 时，就会获得正值。这表明该模型发现分面 *a* 的真阳性多于分面 *d* 的真阳性，这是一种形式的偏差。
+ 接近零的值表示所比较的分面的查全率相似。这表明该模型在这两个分面发现的真阳性数量大致相同，没有偏差。
+ 当分面 *d* 的查全率高于分面 *a* 时，就会获得负值。这表明该模型发现分面 *d* 的真阳性多于分面 *a* 的真阳性，这是一种形式的偏差。
# 接受率差异 (DAR)
接受率差异 (DAR) 指标是分面 *a* 和 *d* 的真阳性 (TP) 预测值与观测到的阳性值 (TP \$1 FP) 之比的差值。该指标衡量了模型对这两个分面的接受率的预测精度差异。精度衡量的是模型从合格候选人库中识别出的合格候选人的比例。如果模型对合格申请人的预测精度在不同分面之间存在差异，这就是偏差，其大小由 DAR 来衡量。
分面 *a* 和 *d* 之间接受率差异的公式：
DAR = TPa/(TPa \$1 FPa) - TPd/(TPd \$1 FPd)
其中：
+ TPa 是分面 *a* 的真阳性预测值。
+ FPa 是分面 *a* 的假阳性预测值。
+ TPd 是分面 *d* 的真阳性预测值。
+ FPd 是分面 *d* 的假阳性预测值。
例如，假设该模型接受 70 名中年申请人（分面 *a*）申请贷款（预测阳性标签），其中只有 35 人实际被接受（观测阳性标签）。还假设该模型接受来自其他年龄人群（分面 *d*）的 100 名申请人申请贷款（预测阳性标签），其中只有 40 人实际被接受（观测阳性标签）。那么 DAR = 35/70 - 40/100 = 0.10，这表明存在不利于第二个年龄组（分面 *d*）合格人群的潜在偏差。
二进制、多类别分面和连续标签的 DAR 值范围为 [-1, \$11]。
+ 当分面 *a* 的预测阳性结果（接受）与观测阳性结果（合格申请人）之比大于分面 *d* 的这一比率时，就会出现正值。这些值表示由于分面 *d* 中出现相对较多的假阳性，因此可能存在不利于不利分面 *d* 的偏差。比率的差异越大，表观偏差就越严重。
+ 当分面 *a* 和 *d* 的预测阳性结果（接受）与观测阳性结果（合格申请人）之比具有相似的值时，就会出现接近零的值，这表明模型以同样的精度预测阳性结果的观测标签。
+ 当分面 *d* 的预测阳性结果（接受）与观测阳性结果（合格申请人）之比大于分面 *a* 的这一比率时，就会出现负值。这些值表示由于分面 *a* 中出现相对较多的假阳性，因此可能存在不利于有利分面 *a* 的偏差。比率的差异越负，表观偏差就越严重。
# 拒绝率差异 (DRR)
拒绝率差异 (DRR) 指标是分面 *a* 和 *d* 的真阴性 (TN) 预测结果与观测阴性结果 (TN \$1 FN) 之比的差异。该指标衡量了模型对这两个分面的拒绝率的预测精度差异。精度衡量的是模型从不合格候选人库中识别出的不合格候选人的比例。如果模型对不合格申请人的预测精度在不同分面之间存在差异，这就是偏差，其大小由 DRR 来衡量。
分面 *a* 和 *d* 之间拒绝率差异的公式：
DRR = TNd/(TNd \$1 FNd) - TNa/(TNa \$1 FNa)
前述 DRR 等式的分量如下所示。
+ TNd 是分面 *d* 的真阴性预测值。
+ FNd 是分面 *d* 的假阴性预测值。
+ TPa 是分面 *a* 的真阴性预测值。
+ FNa 是分面 *a* 的假阴性预测值。
例如，假设该模型拒绝了 100 名中年贷款申请人（分面 *a*）（预测阴性标签），其中 80 人实际上不合格（观测阴性标签）。还假设该模型拒绝来自其他年龄人群（分面 *d*）的 50 名申请人申请贷款（预测阴性标签），其中只有 40 人实际上不合格（观测阴性标签）。那么 DRR = 40/50 - 80/100 = 0，表明没有偏差。
二进制、多类别分面和连续标签的 DRR 值范围为 [-1, \$11]。
+ 当分面 *d* 的预测阴性结果（拒绝）与观测阴性结果（不合格申请人）之比大于分面 *a* 的这一比率时，就会出现正值。这些值表示由于分面 *a* 中出现相对较多的假阴性，因此可能存在不利于有利分面 *a* 的偏差。比率的差异越大，表观偏差就越严重。
+ 当分面 *a* 和 *d* 的预测阴性结果（拒绝）与观测阴性结果（不合格申请人）之比具有相似的值时，就会出现接近零的值，这表明模型以同样的精度预测阴性结果的观测标签。
+ 当分面 *a* 的预测阴性结果（拒绝）与观测阴性结果（不合格申请人）之比大于分面 *d* 的这一比率时，就会出现负值。这些值表示由于分面 *d* 中出现相对较多的假阳性，因此可能存在不利于不利分面 *d* 的偏差。比率的差异越负，表观偏差就越严重。
# 准确率差异 (AD)
准确率差异 (AD) 指标是不同分面的预测准确率之间的差异。该指标确定模型对一个分面的分类是否比另一个分面更准确。AD 表示某一分面是否会产生更大比例的 I 型和 II 型错误。但它无法区分 I 型和 II 型错误。例如，模型对不同年龄人口的准确率可能相同，但对一个年龄组的错误可能主要是假阳性（I 型错误），而对另一年龄组的错误可能主要是假阴性（II 型错误）。
另外，如果对中年人口（分面 *a*）的贷款审批准确率远高于对另一年龄段人口（分面 *d*）的贷款审批准确率，那么要么第二组中更大比例的合格申请人被拒绝发放贷款 (FN)，要么该组中更大比例的不合格申请人获得贷款 (FP)，要么两者兼而有之。这可能会导致第二组的组内不公平，即使两个年龄组的贷款发放比例几乎相同，这表现为 DPPL 值接近于零。
AD 指标的计算公式为分面 *a* 的预测准确率 (ACCa) 减去分面 *d* 的预测准确率 (ACCd)：
AD = ACCa - ACCd
其中：
+ ACCa = (TPa \$1 TNa)/(TPa \$1 TNa \$1 FPa \$1 FNa)
+ TPa 是分面 *a* 的真阳性预测值
+ TNa 是分面 *a* 的真阴性预测值
+ FPa 是分面 *a* 的假阳性预测值
+ FNa 是分面 *a* 的假阴性预测值
+ ACCd = (TPd \$1 TNd)/(TPd \$1 TNd \$1 FPd \$1 FNd)
+ TPd 是分面 *d* 的真阳性预测值
+ TNd 是分面 *d* 的真阴性预测值
+ FPd 是分面 *d* 的假阳性预测值
+ FNd 是分面 *d* 的假阴性预测值
例如，假设一个模型向分面 *a* 的 100 名申请人中的 70 名批准发放贷款，而拒绝了另外 30 名申请人。10 名申请人不应该获得批准 (FPa)，而 60 名申请人本应获得批准 (TPa)。被拒绝的申请人中有 20 人本应获得批准 (FNa)，10 人被正确拒绝 (TNa)。分面 *a* 的准确率如下：
ACCa = (60 \$1 10)/(60 \$1 10 \$1 20 \$1 10) = 0.7
接下来，假设一个模型向分面 *d* 的 100 名申请人中的 50 名批准发放贷款，而拒绝了另外 50 名申请人。10 名申请人不应该获得批准 (FPa)，而 40 名申请人本应获得批准 (TPa)。被拒绝的申请人中有 40 人本应获得批准 (FNa)，10 人被正确拒绝 (TNa)。分面 *a* 的准确率如下：
ACCd= (40 \$1 10)/(40 \$1 10 \$1 40 \$1 10) = 0.5
因此，准确率差异为 AD = ACCa - ACCd = 0.7 - 0.5 = 0.2。这表明存在不利于分面 *d* 的偏差，因为该指标为正值。
二进制和多类别分面标签的 AD 值范围为 [-1, \$11]。
+ 当分面 *a* 的预测准确率高于分面 *d* 的预测准确率时，就会出现正值。这意味着分面 *d* 更容易受到假阳性（I 型错误）或假阴性（II 型错误）的某种组合的影响。这意味着存在不利于不利分面 *d* 的潜在偏差。
+ 当分面 *a* 的预测准确率与分面 *d* 的预测准确率相似时，就会出现接近零的值。
+ 当分面 *d* 的预测准确率高于分面 *a* 的预测准确率时，就会出现负值。这意味着分面 *a* 更容易受到假阳性（I 型错误）或假阴性（II 型错误）的某种组合的影响。这意味着存在不利于有利分面 *a* 的偏差。
# 平等对待 (TE)
平等对待 (TE) 是指分面 *a* 和分面 *d* 之间假阴性与假阳性比率之差。该指标的主要理念是评估即使各组的准确率相同，错误对一组的伤害是否比另一组更大？ 错误率来自假阳性和假阴性的总和，但对于不同的分面，这两者的细分可能大不相同。TE 衡量错误在各分面的补偿方式是相似还是不同。
平等对待的公式：
TE = FNd/FPd - FNa/FPa
其中：
+ FNd 是分面 *d* 的假阴性预测值。
+ FPd 是分面 *d* 的假阳性预测值。
+ FNa 是分面 *a* 的假阴性预测值。
+ FPa 是分面 *a* 的假阳性预测值。
请注意，如果 FPa 或 FPd 为零，该指标就会变成无界。
例如，假设有 100 名贷款申请人来自分面 *a*，有 50 名贷款申请人来自分面 *d*。就分面 *a* 而言，有 8 人被错误地拒绝贷款 (FNa)，另有 6 人被错误地批准贷款 (FPa)。其余的预测均正确，那么 TPa \$1 TNa = 86。对于分面 *d*，有 5 人被错误地拒绝 (FNd)，有 2 人被错误地批准 (FPd)。其余的预测均正确，那么 TPd \$1 TNd = 43。分面 *a* 的假阴性与假阳性之比等于 8/6 = 1.33，分面 *d* 的假阴性与假阳性之比等于 5/2 = 2.5。因此，TE = 2.5 - 1.33 = 1.167，尽管两个分面的准确率相同：
ACCa = (86)/(86\$1 8 \$1 6) = 0.86
ACCd = (43)/(43 \$1 5 \$1 2) = 0.86
二进制和多类别分面标签的有条件拒绝差异的值范围为 (-∞, \$1∞)。未为连续标签定义 TE 指标。对该指标的解释取决于假阳性（I 型错误）和假阴性（II 型错误）的相对重要性。
+ 当分面 *d* 的假阴性与假阳性之比大于分面 *a* 的假阴性与假阳性之比时，就会出现正值。
+ 当分面 *a* 的假阴性与假阳性之比和分面 *d* 的假阴性与假阳性之比相似时，就会出现接近零的值。
+ 当分面 *d* 的假阴性与假阳性之比小于分面 *a* 的假阴性与假阳性之比时，就会出现负值。
**注意**
先前的版本指出，平等对待指标的计算公式是 FPa / FNa - FPd / FNd，而不是 FNd / FPd - FNa / FPa。这两个版本都可以使用。有关更多信息，请参阅 [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)。
# 预测标签中的条件人口统计差异 (CDDPL)
人口统计差异 (DDPL) 指标用于确定分面 *d* 中预测拒绝标签比例是否大于预测接受标签比例。它可以比较不同分面的预测拒绝比例和预测接受比例的差异。该指标与训练前 CDD 指标完全相同，只不过它是根据预测标签而不是观测标签进行计算。该指标的范围是 (-1,\$11)。
分面 *d* 标签的人口统计差异预测公式如下：
DDPLd = n'd(0)/n'(0) - n'd(1)/n'(1) = PdR(y'0) - PdA(y'1)
其中：
+ n'(0) = n'a(0) \$1 n'd(0) 是分面 *a* 和 *d* 的预测拒绝标签数。
+ n'(1) = n'a(1) \$1 n'd(1) 是分面 *a* 和 *d* 的预测接受标签数。
+ PdR(y'0) 是分面 *d* 中预测拒绝标签（值 0）的比例。
+ PdA(y'1) 是分面 *d* 中预测接受标签（值 1）的比例。
为了排除辛普森悖论，需要使用预测标签中的条件人口统计差异 (CDDPL) 指标，该指标根据数据集上定义子组层次的属性来限制 DDPL。通过重新分组，可以深入了解较不利分面出现明显人口统计差异的原因。经典案例是伯克利大学招生案例，该大学的男性录取率总体上高于女性。但研究院系子组后，我们发现，在某些院系，女性的录取率高于男性。对此的解释是，女性申请的院系比男性申请的院系的录取率低。研究子组录取率后发现，在录取率较低的院系中，女性的录取率实际上高于男性。
CDDPL 指标通过对数据集的某一属性所定义的子组中发现的所有差异进行平均，从而给出一个单一的衡量标准。它被定义为每个子组的预测标签中的人口统计差异 (DDPLi) 的加权平均值，每个子组的差异根据所含观测值的数量按比例加权。预测标签中的条件人口统计差异的公式如下：
CDDPL = (1/n)\$1∑ini \$1DDPLi
其中：
+ ∑ini = n 是观测值的总数，ni 是每个子组的观测值数。
+ DDPLi = n'i(0)/n(0) - n'i(1)/n(1) = PiR(y'0) - PiA(y'1) 是该子组的预测标签中的人口统计差异。
因此，子组的预测标签中的人口统计差异 (DDPLi) 是每个子组的预测拒绝标签比例与预测接受标签比例之间的差异。
二进制、多类别和连续结果的 DDPL 值范围为 [-1,\$11]。
+ \$11：当分面 *a* 或子组没有预测拒绝标签且分面 *d* 或子组没有预测接受标签时。
+ 正值表示预测标签中存在人口统计差异，因为分面 *d* 或子组的预测拒绝标签比例高于预测接受标签比例。值越大，差异就越大。
+ 接近零的值表示平均而言没有人口统计差异。
+ 负值表示预测标签中存在人口统计差异，因为分面 *a* 或子组的预测拒绝标签比例高于预测接受标签比例。值越小，差异就越大。
+ -1：当分面 *d* 或子组没有预测拒绝标签且分面 *a* 或子组没有预测接受标签时。
# 反事实翻转测试 (FT)
翻转测试是一种检查分面 *d* 的每个成员并评估分面 *a* 的相似成员是否具有不同模型预测的方法。分面 *a* 的成员被选为分面 *d* 中观测值的 k 最近邻。我们评估有多少对立组的最近邻得到了不同的预测，其中翻转的预测可以从正变为负，反之亦然。
反事实翻转测试的公式是两个集合的基数之差除以分面 *d* 的成员数：
FT = (F\$1 - F-)/nd
其中：
+ F\$1 是具有不利结果的不利分面 *d* 的成员数，这些成员在有利分面 *a* 中的最近邻获得了有利结果。
+ F- 是具有有利结果的不利分面 *d* 的成员数，这些成员在有利分面 *a* 中的最近邻获得了不利结果。
+ nd 是分面 *d* 的样本量。
二进制和多类别分面标签的反事实翻转测试的值范围为 [-1, \$11]。对于连续标签，我们设置了一个阈值，将标签折叠为二进制标签。
+ 当不利分面 *d* 的不利反事实翻转测试决策数量超过有利决策的数量时，就会出现正值。
+ 当不利和有利反事实翻转测试决策的数量达到平衡时，就会出现接近零的值。
+ 当不利分面 *d* 的不利反事实翻转测试决策数量少于有利决策的数量时，就会出现负值。
# 广义熵 (GE)
广义熵指数 (GE) 衡量预测标签与观测标签相比在权益 `b` 上的不平等程度。当预测到假阳性结果时，就会获得权益。当阴性观测值 (y=0) 的预测结果为阳性 (y'=1) 时，就会出现假阳性。当观测标签和预测标签相同（也称为真阳性和真阴性）时，也会获得权益。当预测到假阴性时，不会获得任何权益。当预测到阳性观测值 (y=1) 的结果为阴性 (y'=0) 时，就会出现假阴性。权益 `b` 定义如下。
```
b = y' - y + 1
```
根据此定义，假阳性获得值为 `2` 的权益 `b`，而假阴性获得值为 `0` 的权益。真阳性和真阴性都将获得值为 `1` 的权益。
GE 指标按照[广义熵指数](https://en.wikipedia.org/wiki/Generalized_entropy_index) (GE) 计算，权重 `alpha` 设置为 `2`。此权重控制对不同权益值的敏感度。`alpha` 越小，对较小值的敏感度就越高。
![\[定义广义熵指数的等式，alpha 参数设置为 2。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify-post-training-bias-metric-ge.png)
用于计算 GE 的变量定义如下：
+ bi 是 `ith` 数据点获得的权益。
+ b' 是所有权益的平均值。
GE 的范围为 0 到 0.5，值为零表示所有数据点的权益没有不平等现象。当所有输入都正确预测时，或者当所有预测均为假阳性时，就会发生这种情况。当所有预测均为假阴性时，GE 的定义不明确。
**注意**
GE 指标并不取决于某个分面值是有利还是不利。
# 模型可解释性
Ama SageMaker zon Clarify 提供的工具可以帮助解释机器学习 (ML) 模型是如何进行预测的。这些工具可以帮助机器学习建模人员和开发人员以及其他内部利益相关者在部署前从整体上了解模型特征，并在部署后调试模型提供的预测。
+ 要获取数据集和模型的解释，请参阅 [使用 Clarify 进行公平性、模型可解释性和偏见检测 SageMaker](clarify-configure-processing-jobs.md)。
+ 要从 SageMaker AI 终端节点实时获取解释，请参阅[使用 Clarify 进行在线解释 SageMaker](clarify-online-explainability.md)。
对于消费者和监管机构来说，有关机器学习模型如何得出预测结果的透明度也至关重要。如果他们要接受基于模型的决策，他们就需要信任模型预测。 SageMaker Clarify 使用与模型无关的特征归因方法。您可以利用它来了解模型在训练后做出预测的原因，并在推理过程中按实例提供解释。实施工作包括对 [SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) 进行高效且可扩展的实施。这种方法基于合作博弈论领域的 Shapley 值概念，即为每个特征分配一个特定预测的重要性值。
Clarify 生成部分依赖图 (PDPs)，显示特征对机器学习模型预测结果的边际效应。部分依赖有助于解释给定一组输入特征的目标响应。它还支持计算机视觉 (CV) 和自然语言处理 (NLP) 的可解释性，使用与表格数据解释相同的 Shapley 值 (SHAP) 算法。
在机器学习环境中，解释的作用是什么？ 解释可以认为是对*为什么问题* 的回答，该问题有助于人们了解预测的原因。在机器学习模型环境中，您可能有兴趣回答以下问题：
+ 为什么模型预测结果为阴性，例如给定申请人的贷款被拒绝？
+ 模型如何做出预测？
+ 为什么模型做出了错误的预测？
+ 哪些特征对模型行为的影响最大？
您可以将解释用于审计目的和满足监管要求，在模型中建立信任，支持人工决策，以及用于调试和提高模型性能。
需要满足人类了解机器学习推理的性质和结果的要求，这是进行必要解释的关键所在。哲学和认知科学学科的研究表明，人们尤其关注对比性解释，即解释为什么发生了 X 事件而不是其他没有发生的 Y 事件。在这里，X 可能是发生的意想不到或令人惊讶的事件，Y 对应的是基于他们现有心理模型的预期，称为*基准*。请注意，对于同一事件 X，不同的人可能会根据其观点或心理模型 Y 寻求不同的解释。在可解释 AI 的背景下，您可以将 X 视为被解释的示例，将 Y 视为基准，基准通常被选来代表数据集中的非信息示例或平均示例。有时，例如在对图像进行机器学习建模时，基准可能是隐式的，像素颜色相同的图像可作为基准。
## 示例笔记本
SageMaker 为了便于解释模型，Amazon Clarify 提供了以下示例笔记本：
+ [Amaz SageMaker on Cl](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/index.html#sagemaker-clarify-processing) arify P SageMaker rocessing — 使用 Clarify 创建处理任务，用于检测偏差并使用特征归因解释模型预测。示例包括使用 CSV 和 JSON 行数据格式、自带容器以及使用 Spark 运行处理作业。
+ [使用 Clarif SageMaker y 解释图像 SageMaker 分类](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) — Clarify 可让您深入了解计算机视觉模型如何对图像进行分类。
+ [使用 Clarify — SageMaker Clar SageMaker ify 解释物](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb)体检测模型，让你深入了解计算机视觉模型如何检测物体。
本笔记本经过验证，只能在 Amazon SageMaker Studio 中运行。如果您需要有关如何在 Amazon SageMaker Studio 中打开笔记本的说明，请参阅[创建或打开 Amazon SageMaker Studio 经典笔记本电脑](notebooks-create-open.md)。如果系统提示您选择内核，请选择 **Python 3 (Data Science)**。
**Topics**
+ [示例笔记本](#clarify-model-explainability-sample-notebooks)
+ [使用 Shapley 值的特征归因](clarify-shapley-values.md)
+ [非对称 Shapley 值](clarify-feature-attribute-shap-asymm.md)
+ [SHAP 可解释性基准](clarify-feature-attribute-shap-baselines.md)
# 使用 Shapley 值的特征归因
SageMaker Clarify 根据 [Shaple](https://en.wikipedia.org/wiki/Shapley_value) y 值的概念提供功能归因。您可以使用 Shapley 值来确定每项特征对模型预测的贡献。可以为特定的预测提供这些归因，也可以在全局层面为整个模型提供这些归因。例如，如果您在大学录取场景中使用一个机器学习模型，那么解释有助于确定对模型预测最有帮助的特征是 GPA 还是 SAT 得分，然后您就可以确定在做出某个学生的录取决定时每项特征所起的作用。
SageMaker Clarify从博弈论中汲取了Shapley价值观的概念，并将其部署在机器学习环境中。Shapley 值提供了一种量化每个玩家对游戏的贡献的方法，从而提供了一种根据玩家的贡献将游戏产生的总收益分配给玩家的方法。在这种机器学习环境中， SageMaker Clarify 将模型在给定实例上的预测视为*游戏*，将模型中包含的特征视为*玩家*。对于第一近似值，您可能想通过量化从模型中*删除* 该特征或从模型中*删除* 所有其他特征的结果，来确定每项特征的边际贡献或效果。然而，这种方法没有考虑到模型中包含的特征往往不是相互独立的。例如，如果两项特征高度相关，删除其中任一特征可能都不会对模型预测产生重大影响。
为了处理这些潜在的依赖关系，Shapley 值要求必须考虑每种可能的特征组合（或联合）的结果，以确定每项特征的重要性。给定 *d* 项特征，就有 2d 种这样的可能特征组合，每种组合对应一个潜在模型。要确定给定特征 *f* 的归因，请考虑在所有不包含 *f* 的特征组合（和关联模型）中包含 *f* 的边际贡献，然后取平均值。可以看出，Shapley 值是分配满足某些理想属性的每项特征的贡献或重要性的唯一方式。具体而言，每项特征的 Shapley 值之和对应于模型预测值和无特征虚拟模型预测值之差。然而，即使对于合理的 *d* 值（比如 50 项特征），要训练 2d 个可能的模型，在计算上也是非常困难和不切实际的。因此，Cl SageMaker arify 需要使用各种近似技术。为此，Clari SageMaker fy使用了Shapley加法解释（SHAP），它结合了这样的近似值，并通过额外的优化设计了内核SHAP算法的可扩展且高效的实现。
有关 Shapley 值的更多信息，请参阅 [A Unified Approach to Interpreting Model Predictions](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf)（解释模型预测的统一方法）。
# 非对称 Shapley 值
Cl SageMaker arify 时间序列预测模型解释解决方案是一种植根于[合作博弈论](https://en.wikipedia.org/wiki/Cooperative_game_theory)的特征归因方法，其精神与 SHAP 类似。具体来说，Clarify 使用[随机顺序组值](http://www.library.fa.ru/files/Roth2.pdf#page=121)，在机器学习和可解释性方面也被称为[非对称 Shapley 值](https://proceedings.neurips.cc/paper/2020/file/0d770c496aa3da6d2c3f2bd19e7b9d6b-Paper.pdf)。
## 背景
目标是计算输入功能对给定预测模型 *f* 的归因。预测模型需要以下输入：
+ 过去时间序列*（目标 TS）*。例如，这可以是巴黎-柏林线路上过去每天的火车乘客人数，用 *xt* 表示。
+ (可选）协变量时间序列。例如，这可以是节日和天气数据，用 *zt* ∈ RS 表示。在使用时，协变量 TS 可以只适用于过去的时间步长，也可以适用于未来的时间步长（包括在节日日历中）。
+ (可选）静态协变量，如服务质量（如一等座或二等座），用 *u* ∈ RE 表示。
根据具体的应用场景，可以省略静态协变量、动态协变量或两者。在预测范围 K≥0 的情况下（例如 K=30 天），模型预测可用公式表征：*f(x[1:T], z[1:T\$1K], u) = x[T\$11:T \$1K\$11]*。
下图显示了一个典型预测模型的依赖关系结构。时间 *t\$11* 的预测取决于前面提到的三类输入。
![\[典型预测模型的依赖结构。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/clarify/clarify-forecast-dependency.png)
## 方法
解释是通过查询时间序列模型 *f* 中由原始输入推导出的一系列点来计算的。按照博弈论的结构，Clarify 通过反复混淆（即设置为基线值）部分输入来平均预测结果的差异。时间结构可以按时间顺序或反时间顺序浏览，或两者兼而有之。按时间顺序的解释是从第一个时间步骤开始迭代添加信息，而反时间顺序的解释则是从最后一个步骤开始。后一种模式可能更适用于存在追溯偏差的情况，例如预测股票价格。计算解释的一个重要特性是，如果模型提供确定性输出，它们与原始模型输出相加。
## 结果归因
结果归因是标记特定时间步或输入功能对每个预测时间步的最终预测的单独贡献的得分。Clarify 提供了以下两种粒度的解释：
+ 分时解释成本低廉，只提供特定时间步骤的信息，例如过去第 19 天的信息对未来第 1 天的预测有多大帮助。这些归因不能单独解释静态协变量，也不能综合解释目标和协变量的时间序列。归因是一个 *A* 矩阵，其中每个 *Atk* 是时间步长 *t* 对时间步长 *T\$1k* 预测的归因。请注意，如果模型接受未来协变量，*t* 可以大于 *T*。
+ 精细解释的计算量更大，可提供输入变量所有归因的完整细目。
**注意**
精细解释只支持时间顺序。
由此得出的归因是由以下内容组成的三联体：
+ 与输入时间序列相关的矩阵 *Ax* ∈ RT×K 其中，*Atkx* 是 *xt* 对预测步骤 *T\$1k* 的归因。
+ 张量 *Az* ∈ *RT\$1K×S×K* 与协变时间序列相关，其中 *Atskz* 是 *zts*（即......协变 TS）对预测步骤 *T\$1k* 的归因。
+ 与静态协变量相关的矩阵 *Au* ∈ RE×K，其中 *Aeku* 是 *ue*（伦理静态协变量）对预测步骤 *T\$1k* 的归因。
无论粒度如何，解释还包含一个偏移向量 *B* ∈ *RK*，它代表了所有数据被混淆时模型的“基本行为”。
# SHAP 可解释性基准
解释通常是对比性的（也就是说，它们解释了与基准的偏差）。因此，对于同一个模型预测，不同的基准会有不同的解释。因此，基准的选择至关重要。在机器学习环境中，基准对应于一个假设的实例，该实例既可能是*非信息性*，也可能是*信息性*。在计算 Shapley 值的过程中， SageMaker Clarify 会在基线和给定实例之间生成几个新实例，其中特征的缺失是通过将特征值设置为基线值来建模的，通过将特征值设置为给定实例的特征值来建模特征的存在。因此，不存在所有特征时对应基准，存在所有特征时对应给定实例。
如何选择合适的基准？ 通常，最好选择信息含量非常低的基准。例如，可以通过取数值特征的中位数或平均值以及类别特征的模式，根据训练数据集来构造平均实例。在大学录取的例子中，您可能有兴趣解释为什么某个申请人会被录取，而不是基于平均申请人的基准进行录取。如果未提供，则由 SageMaker Clarify 在输入数据集中使用 K-means 或 K-prototype 自动计算基线。
或者，您可以选择生成有关信息性基准的说明。在大学录取场景中，您可能需要解释为什么某个申请人会被拒绝，而其他具有相似人口统计背景的申请人未被拒绝。在这种情况下，您可以选择一个能代表相关申请人的基准，即人口统计背景相似的申请人。因此，您可以使用信息性基准来集中分析特定模型预测的特定方面。您可以通过将人口统计属性和其他无法执行的特征设置为与给定实例中的值相同，从而分离出这些特征以进行评估。