本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 配置 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]}]}
```
------