运行 SageMaker Clarify 处理作业以进行偏差分析和实现可解释性 - Amazon SageMaker
如何运行并行 SageMaker Clarify 处理作业

运行 SageMaker Clarify 处理作业以进行偏差分析和实现可解释性

要使用 SageMaker Clarify 分析数据和模型的偏差和可解释性，必须配置 SageMaker Clarify 处理作业。本指南介绍如何使用 SageMaker Python SDK API SageMakerClarifyProcessor 配置作业输入、输出、资源和分析配置。

该 API 充当 SageMaker CreateProcessingJob API 的高级包装器。它隐藏了设置 SageMaker Clarify 处理作业所涉及的许多细节。设置作业的详细信息包括检索 SageMaker Clarify 容器映像 URI 和生成分析配置文件。以下步骤介绍如何配置、初始化和启动 SageMaker Clarify 处理作业。

使用 API 配置 SageMaker Clarify 处理作业

  1. 为作业配置的每个部分定义配置对象。这些部分可包括以下内容：

    对于不同类型的数据格式和使用案例，SageMaker Clarify 处理作业的配置对象各不相同。表格数据的配置示例，包括 CSV 和 JSON Lines 格式、(NLP)、computer vision (CV) 和时间序列 (TS) 问题，已在以下部分中提供。

  2. 创建 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,
)

  3. 使用适合您使用案例的配置对象调用 SageMakerClarifyProcessor 对象的特定运行方法以启动作业。这些运行方法包括：

    • run_pre_training_bias

    • run_post_training_bias

    • run_bias

    • run_explainability

    • run_bias_and_explainability

    此 SageMakerClarifyProcessor 在后台处理多项任务。这些任务包括检索 SageMaker Clarify 容器映像通用资源标识符 (URI)、根据提供的配置对象撰写分析配置文件、将文件上传到 Amazon S3 存储桶以及配置 SageMaker Clarify 处理作业。

    以下可扩展章节展示了如何计算训练前和训练后偏差指标、SHAP 值和部分依赖图 (PDPs)。这些章节显示了这些数据类型的特征重要性：

    • CSV 格式或 JSON 行格式的表格数据集

    • 自然语言处理 (NLP) 数据集

    • 计算机视觉数据集

紧接着这些可扩展章节之后是一个指南，介绍如何使用 Spark 通过分布式训练来运行并行 SageMaker Clarify 处理作业。

以下几个示例说明如何为 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 前缀，则 SageMaker Clarify 处理作业会递归收集位于该前缀下的所有 Amazon S3 文件。s3_output_path 的值应为 S3 URI 前缀以保存分析结果。SageMaker 在编译时使用 s3_output_path，而不能使用运行时使用的 SageMaker 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 语句启动 SageMaker Clarify 处理作业，该作业计算输入数据集的所有训练前偏差指标。

clarify_processor.run_pre_training_bias(
     data_config=data_config,
    data_bias_config=bias_config,
    methods="all",
)

或者，您可以通过向 methods 参数分配训练前偏差指标列表来选择要计算的指标。例如，将 methods="all" 替换为 methods=["CI", "DPL"] 会指示 SageMaker Clarify 处理器仅计算类别不平衡和标签比例差异。

如何计算 CSV 数据集的所有训练后偏差指标

您可以在训练前计算训练前偏差指标。但是，要计算训练后偏差指标，必须拥有经过训练的模型。以下示例输出来自以 CSV 格式输出数据的二进制分类模型。在此示例输出中，每行包含两列。第一列包含预测标签，第二列包含该标签的概率值。

0,0.028986845165491
1,0.825382471084594
...

在以下示例配置中，ModelConfig 对象指示作业将 SageMaker 模型部署到临时端点。该端点使用一个 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 对象。这会指示 SageMaker Clarify 处理作业在模型输出的第一列中找到预测标签。在本例中，处理作业使用零基索引。

predicted_label_config = clarify.ModelPredictedLabelConfig(
    label=0,
)

结合前面的配置示例，以下代码示例启动了 SageMaker Clarify 处理作业，以计算所有训练后偏差指标。

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"]，便可仅计算预测标签中正比例的差异和差别影响。

如何计算 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 中运行 SageMaker Clarify 处理作业以检测偏差的示例笔记本说明，请参阅 SageMaker Clarify 的公平性和可解释性。

如何计算 CSV 数据集的 SHAP 值

SageMaker Clarify 使用 KernelSHAP 算法提供特征归因。SHAP 分析需要概率值或得分而不是预测标签，因此，此 ModelPredictedLabelConfig 对象具有概率索引 1。这指示 SageMaker Clarify 处理作业从模型输出的第二列中提取概率得分（使用零基索引）。

probability_config = clarify.ModelPredictedLabelConfig(
    probability=1,
)

SHAPConfig 对象提供 SHAP 分析参数。在本例中，省略了 SHAP baseline 参数，并且 num_clusters 参数的值为 1。这指示 SageMaker Clarify 处理器基于对输入数据集的聚类来计算一个 SHAP 基准样本。如果要选择基准数据集，请参阅 SHAP 可解释性基准。

shap_config = clarify.SHAPConfig(
    num_clusters=1,
)

以下代码示例启动 SageMaker Clarify 处理作业来计算 SHAP 值。

clarify_processor.run_explainability(
    data_config=data_config,
    model_config=model_config,
    model_scores=probability_config,
    explainability_config=shap_config,
)

有关如何在 SageMaker Studio Classic 中运行 SageMaker Clarify 处理作业以计算 SHAP 值的示例笔记本说明，请参阅 SageMaker Clarify 的公平性和可解释性。

如何计算 CSV 数据集的部分依赖图 (PDPs)

PDPs 显示了在所有其他特征保持不变的情况下，预测的目标响应对一个或多个相关输入特征的依赖性。PDP 中的向上倾斜线或曲线表示目标特征和输入特征之间的关系为正相关，陡度表示关系的强度。向下倾斜线或曲线表示如果输入特征减少，目标变量就会增加。直观地说，您可以将部分依赖性解释为目标变量对每个相关输入特征的响应。

以下配置示例用于使用 PDPConfig 对象指示 SageMaker Clarify 处理作业计算 Income 特征的重要性。

pdp_config = clarify.PDPConfig(
    features=["Income"],
    grid_resolution=10,
)

在前面的示例中，grid_resolution 参数将 Income 特征值的范围划分为多个 10 存储桶。SageMaker Clarify 处理作业将生成在 x 轴上拆分为多个 10 分段的 Income 的 PDPs。y 轴将显示 Income 对目标变量的边际影响。

以下代码示例启动 SageMaker Clarify 处理作业来计算 PDPs。

clarify_processor.run_explainability(
    data_config=data_config,
    model_config=model_config,
    model_scores=probability_config,
    explainability_config=pdp_config,
)

有关如何在 SageMaker Studio Classic 中运行 SageMaker Clarify 处理作业以计算 PDPs 的示例笔记本说明，请参阅 SageMaker Clarify 的可解释性 - 部分相关图 (PDP)。

如何同时计算 CSV 数据集的 SHAP 值和 PDPs

您可以在单个 SageMaker Clarify 处理作业中同时计算 SHAP 值和 PDPs。在以下配置示例中，新 PDPConfig 对象的 top_k_features 参数设置为 2。这指示 SageMaker Clarify 处理作业为具有最大全局 SHAP 值的 2 项特征计算 PDPs。

shap_pdp_config = clarify.PDPConfig(
    top_k_features=2,
    grid_resolution=10,
)

以下代码示例启动 SageMaker Clarify 处理作业来计算 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],
)

以下几个示例说明如何为 >SageMaker JSON 行密集格式的表格数据集配置偏差分析和可解释性分析。参阅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,
)

在前面的配置示例中，功能参数被设置为 JMESPath 表达式 Features，这样 SageMaker Clarify 处理任务就能从每条记录中提取功能数组。label 参数设置为 JMESPath 表达式 Label，这样 SageMaker Clarify 处理作业就可以从每条记录中提取 Ground Truth 标签。s3_data_input_path 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 SageMaker Clarify 处理作业会递归收集位于该前缀下的所有 S3 文件。s3_output_path 的值应为 S3 URI 前缀以保存分析结果。SageMaker 在编译时使用 s3_output_path，而不能使用运行时使用的 SageMaker Pipeline 参数、属性、表达式或 ExecutionVariable 的值。

您必须拥有经过训练的模型，才能计算训练后偏差指标或特征重要性。以下示例来自二进制分类模型，该模型以示例的格式输出 JSON 行数据。模型输出的每一行都是一个有效的 JSON 对象。键 predicted_label 指向预测标签，键 probability 指向概率值。

{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...

在以下配置示例中，ModelConfig 对象指示 SageMaker Clarify 处理作业将 SageMaker 模型部署到临时端点。该端点使用一个 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。SageMaker Clarify 处理作业使用 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 Classic 中运行 SageMaker Clarify 处理作业，以检测偏差并计算功能重要性。有关说明和笔记本示例，请参阅 SageMaker Clarify 的公平性和可解释性（JSON 行格式）。

SageMaker Clarify 支持自然语言处理 (NLP) 模型的解释。这些解释可帮助您了解文本的哪些部分对模型预测非常重要。您可以解释输入数据集单个实例的模型预测，也可以解释来自基准数据集的模型预测。要了解和可视化模型的行为，可以指定多个粒度级别。为此，请定义文本段的长度，例如其令牌、句子、段落。

SageMaker Clarify NLP 可解释性与分类模型和回归模型均兼容。您还可以使用 SageMaker Clarify 来解释模型在包含文本、分类或数值特征的多模态数据集上的行为。多模态数据集的 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 前缀，则 SageMaker Clarify 处理作业会递归收集位于该前缀下的所有 S3 文件。s3_output_path 的值应为 S3 URI 前缀以保存分析结果。SageMaker 在编译时使用 s3_output_path，而不能使用运行时使用的 SageMaker Pipeline 参数、属性、表达式或 ExecutionVariable 的值。

以下示例输出是根据使用先前输入数据集训练的二进制分类模型创建的。分类模型接受 CSV 数据，并输出一个介于 0 和 1 之间的得分。

0.491656005382537
0.569582343101501
...

以下示例说明了如何配置 ModelConfig 对象以部署 SageMaker 模型。在本例中，一个临时端点部署了该模型。此端点使用一个配备 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 文档，SageMaker Clarify 使用该文档进行 NLP 处理。前面的示例还说明了如何使用平均值为 4 的 Rating 来设置就地 SHAP 基准实例。使用特殊的掩码令牌 [MASK] 来替换 Comments 中的令牌（单词）。

在前面的示例中，如果实例为 2,"Flavor needs work"，则使用以下基准将基准设置为平均 Rating 为 4。

4, '[MASK]'

在前面的示例中，SageMaker Clarify 解释器会遍历每个令牌，并将其替换为掩码，如下所示。

2,"[MASK] needs work"

4,"Flavor [MASK] work"

4,"Flavor needs [MASK]"

然后，SageMaker Clarify 解释器会将每行发送到您的模型用于进行预测。这样，解释器就可以在遮蔽和不遮蔽单词的情况下学习预测。然后，SageMaker Clarify 解释器使用这些信息来计算每个令牌的贡献。

以下代码示例启动 SageMaker Clarify 处理作业来计算 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 中运行 SageMaker Clarify 处理作业以进行自然语言处理可解释性分析的示例笔记本和说明，请参阅使用 SageMaker Clarify 解释文本情感分析。

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。SageMaker Clarify 处理作业以递归方式收集位于该前缀下的所有图像文件。s3_data_input_path 参数既可以是数据集文件的 URI，也可以是 Amazon S3 URI 前缀。如果您提供 S3 URI 前缀，则 SageMaker Clarify 处理作业会递归收集位于该前缀下的所有 S3 文件。s3_output_path 的值应为 S3 URI 前缀以保存分析结果。SageMaker 在编译时使用 s3_output_path，而不能使用运行时使用的 SageMaker Pipeline 参数、属性、表达式或 ExecutionVariable 的值。

如何解释图像分类模型

SageMaker Clarify 处理作业使用 KernelSHAP 算法解释图像，该算法将图像视为超像素集合。给定一个由图像组成的数据集，处理作业会输出一个图像数据集，其中每张图像都显示相关超像素的热图。

以下配置示例说明了如何使用 SageMaker 图像分类模型配置可解释性分析。请参阅图像分类 – MXNet了解更多信息。

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 对象指示 SageMaker Clarify 处理作业将 SageMaker 模型部署到临时端点。为了加速推理，该端点使用一个配备 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) 方法提取特征进行图像分割。前面的配置示例（model_type 参数）表示图像分类问题的类型。参数 num_segments 估算大约在输入图像中标注多少个分段。然后将分段数传递给 slic n_segments 参数。

将图像的每个分段都视为一个超像素，并计算每个分段的局部 SHAP 值。参数 segment_compactness 确定由 scikit-image slic 方法生成的图像分段的形状和大小。然后将图像分段的大小和形状传递给 slic compactness 参数。

以下代码示例启动 SageMaker Clarify 处理作业来为您的图像生成热图。正热图值表明该特征提高了检测对象的置信度得分。负值表示该特征降低了置信度得分。

clarify_processor.run_explainability(
    data_config=cv_data_config,
    model_config=ic_model_config,
    model_scores=ic_prediction_config,
    explainability_config=ic_shap_config,
)

有关使用 SageMaker Clarify 对图像进行分类并解释其分类的示例笔记本，请参阅使用 SageMaker Clarify 解释图像分类。

如何解释对象检测模型

SageMaker Clarify 处理作业可以检测图像中的对象并对其进行分类，然后为检测到的对象提供解释。解释过程如下。

  1. 图像对象首先被归类为指定集合中的一个类。例如，如果对象检测模型可以识别猫、狗和鱼，那么这三个类位于一个集合中。此集合由 label_headers 参数指定，如下所示。

    clarify.ModelPredictedLabelConfig(

label_headers=object_categories,

)

  2. SageMaker Clarify 处理作业会为每个对象生成置信度得分。高置信度得分表示它属于指定集合中的一个类。SageMaker Clarify 处理作业还会生成用于分隔对象的边界框的坐标。有关置信度得分和边界框的更多信息，请参阅响应格式。

  3. 然后，SageMaker Clarify 会对图像场景中的对象检测进行解释。它使用如何解释图像分类模型部分中描述的方法。

在以下配置示例中，SageMaker 对象检测模型 your_cv_od_model 在 JPEG 图像上进行训练，以识别图像上的动物。

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 对象指示 SageMaker Clarify 处理作业将 SageMaker 模型部署到临时端点。为了加速成像，此端点使用一个配备 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 参数表示问题类型为对象检测。有关其他参数的详细说明，请参阅分析配置文件。

以下代码示例启动 SageMaker Clarify 处理作业来为您的图像生成热图。正热图值表明该特征提高了检测对象的置信度得分。负值表示该特征降低了置信度得分。

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 SageMaker Clarify 解释对象检测模型。

以下示例展示了如何配置 SageMaker JSON 密集格式的数据，以解释时间序列预测模型。有关 JSON 格式化的更多信息，请参阅 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 配置通知 SageMaker Clarify 处理器如何一次计算一个项目的功能属性。下面的配置显示了 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。

模型配置

您可以控制从 SageMaker Clarify 处理器发送的有效载荷的结构。在下面的代码示例中，ModelConfig 配置对象指示时间序列预测可解释性作业使用 JMESPath 语法将记录聚合到 '{"instances": $records}' 中。其中，每条记录的结构由以下记录模板 '{"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]}
    ]
}

如果为 forecast 提供的 JMESPath 表达式为 {'predictions[*].mean[:2]'}}，则预测值解析如下：

[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]

如何运行并行 SageMaker Clarify 处理作业

处理大型数据集时，可以使用 Apache Spark 来提高 SageMaker Clarify 处理作业的速度。Spark 是用于大规模数据处理的统一分析引擎。当为每个 SageMaker Clarify 处理器请求多个实例时，SageMaker Clarify 会使用 Spark 的分布式计算功能。

以下配置示例说明了如何使用 SageMakerClarifyProcessor 创建带有 5 计算实例的 SageMaker Clarify 处理器。SageMaker Clarify 使用 Spark 分布式处理来运行任何与 SageMakerClarifyProcessor 关联的作业。

from sagemaker import clarify

spark_clarify_processor = clarify.SageMakerClarifyProcessor(
    role=role,
    instance_count=5,
    instance_type='ml.c5.xlarge',
)

如果将 SHAPConfig 的 save_local_shap_values 参数设置为 True，则 SageMaker Clarify 处理作业会将局部 SHAP 值作为分段文件保存到作业输出位置。

要将局部 SHAP 值与输入数据集实例相关联，请使用 DataConfig 的 joinsource 参数。如果要添加更多计算实例，建议还增加临时端点的 ModelConfig 的 instance_count。这可防止 Spark 工作线程的并发推理请求让端点不堪重负。具体而言，我们建议端点实例与处理实例数量之比为 1:1。