分析配置文件 - Amazon SageMaker
分析配置文件的架构示例分析配置文件

分析配置文件

要使用 SageMaker Clarify 分析数据和模型的可解释性和偏差，必须配置处理作业。此处理作业的部分配置包括分析文件的配置。分析文件指定偏差分析和可解释性的参数。请参阅 配置 SageMaker Clarify 处理作业 了解如何配置处理任务和分析文件。

本指南描述了此分析配置文件的架构和参数。本指南还包括分析配置文件示例，用于计算表格数据集的偏差指标，以及生成自然语言处理 (NLP)、计算机视觉 (CV) 和时间序列 (TS) 问题的解释。

您可以创建分析配置文件，也可以使用 SageMaker Python SDK 通过 SageMaker ClarifyProcessor API 生成一个分析配置文件。查看文件内容有助于理解 SageMaker Clarify 作业使用的基础配置。

分析配置文件的架构

下一节介绍分析配置文件的架构，包括要求和参数描述。

分析配置文件的要求

SageMaker Clarify 处理作业希望分析配置文件的结构符合以下要求：

  • 处理输入名称必须是 analysis_config.

  • 分析配置文件采用 JSON 格式，并以 UTF-8 编码。

  • 分析配置文件是一个 Amazon S3 对象。

您可以在分析配置文件中指定其他参数。以下部分提供了各种选项，可根据您的使用案例和所需的分析类型量身定制 SageMaker Clarify 处理作业。

您可以在分析配置文件中指定以下参数。

  • version -（可选）分析配置文件架构的版本字符串。如果未提供版本，SageMaker Clarify 将使用支持的最新版本。目前唯一支持的版本是 1.0。

  • dataset_type - 数据集的格式。输入数据集格式可以是以下任意值：

    • 表格

      • text/csv（对于 CSV）

      • application/jsonlines（对于 SageMaker JSON 行密集格式）

      • application/json（对于 JSON）

      • application/x-parquet（对于 Apache Parquet）

      • application/x-image（激活计算机视觉问题的可解释性）

    • 时间序列预测模型解释

      • application/json（对于 JSON）

  • dataset_uri -（可选）主数据集的统一资源标识符 (URI)。如果您提供 S3 URI 前缀，则 SageMaker Clarify 处理作业会递归收集位于该前缀下的所有 S3 文件。您可以为映像清单文件提供 S3 URI 前缀或 S3 URI，以解决计算机视觉问题。如果提供了 dataset_uri，它将优先于数据集处理作业输入。对于除映像和时间序列使用场景之外的任何格式类型，SageMaker Clarify 处理任务都会将输入数据集加载到表格数据框中，即表格数据集。这种格式使 SageMaker 能够轻松操作和分析输入数据集。

  • headers：（可选）

    • 表格：。包含表格数据集列名的字符串数组。如果没有为 headers 提供值，SageMaker Clarify 处理任务将从数据集读取标头。如果数据集没有标题，那么 Clarify 处理任务会根据基于零的列索引自动生成占位符名称。例如，第一列和第二列的占位符名称分别为 column_0、column_1，以此类推。

      注意

      按照惯例，如果 dataset_type 是 application/jsonlines 或 application/json，那么 headers 应依次包含以下名称：

      1. 功能名称

      2. 标签名称（如果指定了 label）

      3. 预测标签名称（如果指定了 predicted_label）

      如果已指定 label，则 application/jsonlines 数据集类型的 headers 的一个示例是：["feature1","feature2","feature3","target_label"]。

    • 时间序列：数据集中的列名列表。数据集中的列名列表。如果未提供，Clarify 将生成标题供内部使用。对于时间序列可解释性案例，按以下顺序提供标题：

      1. 项目 id

      2. 时间戳

      3. 目标时间序列

      4. 所有相关时间序列列

      5. 所有静态协变量列

  • label -（可选）字符串或零基整数索引。如果提供，则 label 用于定位 Ground Truth 标签，也称为观测标签或表格数据集中的目标属性。Ground Truth 标签用于计算偏差指标。label 的值根据 dataset_type 参数的值指定，如下所示。

    • 如果 dataset_type 为 text/csv，则 label 可以指定为以下任一项：

      • 有效的列名称

      • 位于数据集列范围内的索引

    • 如果 dataset_type 为 application/parquet，则 label 必须是有效的列名称。

    • 如果 dataset_type 为 application/jsonlines，则 label 必须是为从数据集中提取 Ground Truth 标签而编写的 JMESPath 表达式。按照惯例，如果已指定 headers，则它应包含标签名称。

    • 如果 dataset_type 为 application/json，则 label 必须是为提取数据集中每条记录的 Ground Truth 标签而编写的 JMESPath 表达式。此 JMESPath 表达式必须生成标签列表，其中第 i 个标签与第 i 条记录相关。

  • predicted_label -（可选）字符串或零基整数索引。如果提供，则 predicted_label 用于在表格数据集中定位包含预测标签的列。预测标签用于计算训练后偏差指标。如果数据集不包含预测标签，则参数 predicted_label 为可选。如果计算需要预测标签，那么 SageMaker Clarify 处理作业将从模型中获取预测。

    predicted_label 的值根据 dataset_type 的值指定，如下所示：

    • 如果 dataset_type 为 text/csv，则 predicted_label 可以指定为以下任一项：

      • 有效的列名称。如果已指定 predicted_label_dataset_uri 但未提供 predicted_label，则默认预测标签名称为“predicted_label”。

      • 位于数据集列范围内的索引。如果已指定 predicted_label_dataset_uri，则使用索引在预测标签数据集中定位预测标签列。

    • 如果 dataset_type 为 application/x-parquet，则 predicted_label 必须是有效的列名称。

    • 如果 dataset_type 为 application/jsonlines，则 predicted_label 必须是为从数据集中提取预测标签而编写的有效 JMESPath 表达式。按照惯例，如果已指定 headers，则它应包含预测标签名称。

    • 如果 dataset_type 为 application/json，则 predicted_label 必须是为提取数据集中每条记录的预测标签而编写的 JMESPath 表达式。JMESPath 表达式应生成预测标签列表，其中第 i 个预测标签用于第 i 条记录。

  • features：（可选）如果 dataset_type 是 application/jsonlines 或 application/json，则非时间序列使用场景必须使用。为在输入数据集中定位特征而编写的 JMESPath 字符串表达式。对于 application/jsonlines，将对每一行应用 JMESPath 表达式，以提取该记录的特征。对于 application/json，将对整个输入数据集应用 JMESPath 表达式。JMESPath 表达式应提取一系列列表或提取特征的二维数组/矩阵，其中第 i 行包含与第 i 条记录相关的特征。对于 text/csv 或 application/x-parquet 的 dataset_type，除 Ground Truth 标签列和预测标签列之外的所有列都将自动指定为特征。

  • predicted_label_dataset_uri：（可选）仅适用于数据集类型为 text/csv 时。数据集的 S3 URI，该数据集包含用于计算训练后偏差指标的预测标签。SageMaker Clarify 处理作业将从提供的 URI 加载预测，而不是从模型中获取预测。在这种情况下，需要 predicted_label 在预测标签数据集中找到预测标签列。如果预测标签数据集或主数据集被拆分到多个文件中，则必须通过 joinsource_name_or_index 指定标识符列来联接这两个数据集。

  • predicted_label_headers：（可选）仅在指定 predicted_label_dataset_uri 时适用。包含预测标签数据集的列名称的字符串数组。除了预测标签标题外，predicted_label_headers 还可以包含标识符列的标题以联接预测标签数据集和主数据集。有关更多信息，请参阅以下对 joinsource_name_or_index 参数的描述。

  • joinsource_name_or_index：（可选）在执行内部连接时用作标识列的表格数据集中列的名称或基于零的索引。此列仅用作标识符。它不用于任何其他计算，例如偏差分析或特征归因分析。在以下情况下，需要 joinsource_name_or_index 的值：

    • 有多个输入数据集，任何一个都拆分到多个文件中。

    • 通过将 SageMaker Clarify 处理作业 InstanceCount 设置为大于 1 的值来激活分布式处理。

  • excluded_columns -（可选）不能作为预测输入发送到模型的列名称或零基索引的数组。Ground Truth 标签和预测标签已自动排除在外。时间序列不支持此功能。

  • probability_threshold -（可选）一个浮点数，超过该浮点数将选择标签或对象。默认值为 0.5。SageMaker Clarify 处理作业在以下情况下使用 probability_threshold：

    • 在训练后的偏差分析中，如果模型是二进制分类器，则 probability_threshold 会将数值模型预测（概率值或得分）转换为二进制标签。大于阈值的得分将转换为 1；而小于或等于阈值的得分将转换为 0。

    • 在计算机视觉可解释性问题中，如果 model_type 为 OBJECT_DETECTION，则 , probability_threshold 会筛选掉检测到的置信度得分低于阈值的对象。

  • label_values_or_threshold：（可选）偏差分析所必需。标签值或阈值数组，表示 Ground Truth 的阳性结果和偏差指标的预测标签。更多信息，请参阅 Amazon SageMaker Clarify 偏差和公平性术语 中的正标签值。如果标签是数字，则使用阈值作为下限来选择阳性结果。要针对不同的问题类型设置 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 偏差和公平性术语 中的 Facet。每个分面对象都包含以下字段：

    • name_or_index：（可选）表格数据集中敏感属性列的名称或基于零的索引。如果已指定 facet_dataset_uri，则该索引是指分面数据集而不是主数据集。

    • value_or_threshold：（可选）如果 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_variable：（可选）：表示偏置指标 条件人口统计差异 (CDD) 或 预测标签中的条件人口统计差异 (CDDPL) 所用子组的列名或零基索引。

  • facet_dataset_uri：（可选）仅当数据集类型为 text/csv 时适用。数据集的 S3 URI，该数据集包含用于偏差分析的敏感属性。即使在不使用敏感属性的情况下对模型进行了训练，也可以使用分面来了解数据集和模型的偏差特征。

    注意

    如果分面数据集或主数据集被拆分到多个文件中，则必须通过 joinsource_name_or_index 指定标识符列来联接这两个数据集。必须使用参数 facet 来标识分面数据集中的每个分面。

  • facet_headers：（可选）仅在指定 facet_dataset_uri 时适用。一个字符串数组，包含分面数据集的列名，以及用于连接分面数据集和主数据集的标识符列头，参阅 joinsource_name_or_index。

  • time_series_data_config：（可选）指定用于时间序列数据处理的配置。

    • item_id：字符串或零基整数索引。该字段用于查找共享输入数据集中的项目 ID。

    • timestamp：字符串或基于零的整数索引。该字段用于定位共享输入数据集中的时间戳。

    • dataset_format：可能的值是 columns、item_records 或 timestamp_records。该字段用于描述 JSON 数据集的格式，这是时间序列可解释性唯一支持的格式。

    • target_time_series：JMESPath 字符串或基于零的整数索引。该字段用于定位共享输入数据集中的目标时间序列。如果该参数是字符串，那么除了 dataset_format 之外的所有其他参数都必须是字符串或字符串列表。如果该参数为整数，则除 dataset_format 外的所有其他参数都必须是整数或整数列表。

    • related_time_series：（可选）一个 JMESPath 表达式数组。该字段用于查找共享输入数据集中的所有相关时间序列（如果存在）。

    • static_covariates：（可选）一个 JMESPath 表达式数组。该字段用于定位共享输入数据集中的所有静态协变量字段（如果存在）。

    有关示例，请参阅时间序列数据集配置示例。

  • methods - 一个对象，其中包含一个或多个分析方法及其参数。如果省略了任何方法，则既不用于分析，也不进行报告。

    • pre_training_bias - 如果要计算训练前偏差指标，则包括此方法。指标的详细说明见 训练前偏差指标。对象具有以下参数：

    • post_training_bias - 如果要计算训练后偏差指标，则包括此方法。指标的详细说明见 训练后数据和模型偏差指标。post_training_bias 对象具有以下参数。

    • shap - 如果要计算 SHAP 值，则包括此方法。SageMaker Clarify 处理作业支持 Kernel SHAP 算法。shap 对象具有以下参数。

      • baseline：（可选）SHAP 基准数据集，也称为背景数据集。表格数据集中的基准数据集或计算机视觉问题的其他要求如下。有关 SHAP 基准线的更多信息，请参阅 SHAP 可解释性基准

        • 对于表格数据集，baseline 可以是就地基准数据，也可以是基准文件的 S3 URI。如果未提供 baseline，则 SageMaker Clarify 处理作业将通过对输入数据集进行聚类来计算基准。基准要求如下：

          • 格式必须与 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，用于屏蔽输入图像中的特征（分段）。SageMaker Clarify 处理作业加载掩码图像并将其大小调整为与输入图像相同的分辨率。如果未提供基准，SageMaker Clarify 处理作业会生成与输入图像具有相同分辨率的白噪声掩码图像。

      • features_to_explain -（可选）用于计算 SHAP 值的特征列的字符串或零基索引数组。如果未提供 features_to_explain，则计算所有特征列的 SHAP 值。这些特征列不能包括标签列或预测标签列。features_to_explain 参数仅适用于包含数值列和类别列的表格数据集。

      • num_clusters -（可选）为计算基准数据集而将数据集分成的集群数。每个集群用于计算一个基准实例。如果未指定 baseline，SageMaker Clarify 处理作业会尝试将表格数据集划分为合适数量（介于 1 和 12 之间）的集群，从而计算基准数据集。基准实例数直接影响 SHAP 分析的运行时。

      • num_samples -（可选）要在 Kernel SHAP 算法中使用的样本数。如果未提供 num_samples，则 SageMaker Clarify 处理作业会为您选择数字。样本数直接影响合成数据集的大小和作业运行时。

      • seed -（可选）一个整数，用于在 SHAP 解释器中初始化伪随机数生成器，以便为同一作业生成一致的 SHAP 值。如果未指定 seed，则每次运行同一作业时，模型输出的 SHAP 值可能会略有不同。

      • use_logit -（可选）一个布尔值，表示您希望将 logit 函数应用于模型预测。默认为 false。如果 use_logit 为 true，则使用逻辑回归系数计算 SHAP 值，这些系数可以解释为对数几率比。

      • save_local_shap_values -（可选）一个布尔值，表示您希望将数据集中每条记录的局部 SHAP 值包含在分析结果中。默认为 false。

        如果将主数据集拆分到多个文件中或已激活分布式处理，则还要使用参数 joinsource_name_or_index 指定标识符列。标识符列和局部 SHAP 值保存在分析结果中。这样，您就可以将每条记录映射到其局部 SHAP 值。

      • agg_method -（可选）该方法用于将所有实例的局部 SHAP 值（每个实例的 SHAP 值）聚合为全局 SHAP 值（整个数据集的 SHAP 值）。默认为 mean_abs。以下方法可用于聚合 SHAP 值。

        • mean_abs - 所有实例的绝对局部 SHAP 值的平均值。

        • mean_sq - 所有实例的局部 SHAP 平方值的平均值。

        • median - 所有实例的局部 SHAP 值的中位数。

      • text_config：自然语言处理可解释性所必需。如果要将文本列视为文本，则包括此配置，并且应为文本的各个单元提供解释。有关自然语言处理可解释性分析配置的示例，请参阅 自然语言处理可解释性的分析配置

        • 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_top_tokens -（可选）基于全局 SHAP 值的主要令牌的最大数量。默认为 50。一个令牌有可能在数据集中多次出现。SageMaker Clarify 处理作业聚合每个令牌的 SHAP 值，然后根据其全局 SHAP 值选择主要令牌。所选主要令牌的全局 SHAP 值包含在 analysis.json 文件的 global_top_shap_text 部分中。

        • 聚合的局部 SHAP 值。

      • image_config - 计算机视觉可解释性所必需。如果您的输入数据集由图像组成，并且您想在计算机视觉问题中分析这些图像的可解释性，则使用此配置。

        • model_type - 模型的类型。有效值包括：

          • IMAGE_CLASSIFICATION 表示图像分类模型。

          • OBJECT_DETECTION 表示对象检测模型。

        • max_objects：仅当 model_type 为 OBJECT_DETECTION 时适用。计算机视觉模型检测到的对象的最大数量（按置信度得分排序）。任何按置信度得分排名低于主要 max_objects 的对象都会被筛选掉。默认为 3。

        • context - 仅在 model_type 为 OBJECT_DETECTION 时适用。它指示检测到的对象的边界框周围区域是否被基准图像掩盖。有效的值为 0（掩盖所有内容）或 1（不掩盖任何内容）。默认值为 1。

        • iou_threshold - 仅在 model_type 为 OBJECT_DETECTION 时适用。用于根据原始检测来评估预测值的最小交并比 (IOU) 指标。IOU 指标越高，说明预测的检测框与 Ground Truth 检测框之间的重叠程度越高。默认为 0.5。

        • num_segments -（可选）一个整数，用于确定要在输入图像中标注的分段的大致数量。将图像的每个分段都视为一项特征，并计算每个分段的局部 SHAP 值。默认为 20。

        • segment_compactness -（可选）一个整数，用于确定 scikit-image slic 方法生成的图像分段的形状和大小。默认为 5。

    • pdp：包含此方法以计算局部依存图 (PDP)。有关生成 PDP 的分析配置示例，请参阅 计算部分依赖图 (PDP) 。

      • features - 如果未要求使用 shap 方法，则为必需项。用于计算和绘制 PDP 图的特征名称或索引的数组。

      • top_k_features -（可选）指定用于生成 PDP 图的主要特征的数量。如果未提供 features，但要求使用 shap 方法，则 SageMaker Clarify 处理作业会根据其 SHAP 属性选择主要特征。默认为 10。

      • grid_resolution - 要将数值范围划分成的存储桶的数量。这指定了 PDP 图的网格粒度。

    • asymmetric_shapley_value：如果要计算时间序列预测模型的可解释性指标，请使用此方法。SageMaker Clarify 处理任务支持非对称 Shapley 值算法。非对称 Shapley 值是 Shapley 值的一种变体，它放弃了对称公理。如需了解更多信息，请参阅非对称 Shapley 值：将因果知识纳入模型可解释性。使用这些值来确定功能对预测结果的影响。非对称 Shapley 值考虑了预测模型作为输入的时间序列数据的时间依赖性。

      该算法包括以下参数

      • direction：可用类型为 chronological、anti_chronological 和 bidirectional。时间结构可按时间顺序或反时间顺序浏览，或两者兼而有之。按时间顺序的解释是通过从第一个时间步骤开始迭代添加信息来建立的。反顺时针说明从最后一步开始向后添加信息。后一种阶次可能更适合存在追溯偏差的情况，例如预测股票价格。

      • granularity：要使用的解释粒度。可用的粒度选项如下所示：

        • timewise：timewise 解释成本低廉，只提供特定时间步长的信息，例如计算过去第 n 天的信息对未来第 m 天的预测有多大帮助。由此得出的归因无法单独解释静态协变量，也无法区分目标时间序列和相关时间序列。

        • fine_grained：fine_grained 解释的计算量更大，但能提供输入变量所有归因的完整细目。该方法计算近似解释，以减少运行时间。更多信息，请参阅以下参数 num_samples。

          注意

          fine_grained 解释只支持 chronological 命令。

      • num_samples：（可选）fine_grained 解释需要使用此参数。数字越大，近似值越精确。这个数字应与输入功能的维数成正比。经验法则是，如果结果不太大，可将该变量设为（1 + max（相关时间序列数，静态协变量数））^2。

      • baseline：（可选）基线配置，用于替换相应数据集的联盟外值（也称为背景数据）。下面的代码段显示了基线配置的一个示例：

        {
    "related_time_series": "zero",
    "static_covariates": {
        <item_id_1>: [0, 2],
        <item_id_2>: [-1, 1]
    },
    "target_time_series": "zero"
}

        • 对于目标时间序列或相关时间序列等时间数据，基线值类型可以是以下值之一：

          • zero：所有联盟外数值均替换为 0.0。

          • mean：用时间序列的平均值替换所有超出区间的值。

        • 对于静态协变量，只有当模型请求使用静态协变量值时才应提供基线条目，在这种情况下，该字段为必填字段。应以列表形式提供每个项目的基准线。例如，如果数据集有两个静态协变量，基线配置可以如下：

          "static_covariates": {
    <item_id_1>: [1, 1],
    <item_id_2>: [0, 1]
}

          在上例中，<item_id_1> 和 <item_id_2> 是数据集中的项目 ID。

    • report -（可选）使用此对象自定义分析报告。时间序列解释任务不支持此参数。作为分析结果的一部分，同一报告有三份副本：Jupyter 笔记本报告、HTML 报告和 PDF 报告。对象具有以下参数：

      • name - 报告文件的文件名。例如，如果 name 为 MyReport，则报告文件为 MyReport.ipynb、MyReport.html 和 MyReport.pdf。默认为 report。

      • title -（可选）报告的标题字符串。默认为 SageMaker Analysis Report。

  • predictor - 如果分析需要模型的预测结果，则为必需项。例如，当请求使用 shap、asymmetric_shapley_value、pdp 或 post_training_bias 方法，但预测标签没有作为输入数据集的一部分提供时。以下是要与 predictor 配合使用的参数：

    • model_name - 由 CreateModel API 创建的 SageMaker 模型的名称。如果您指定 model_name 而不是 endpoint_name，则 SageMaker Clarify 处理作业会创建一个带有模型名称的临时端点（称为影子端点），并从该端点获取预测。计算完成后，作业会删除影子端点。如果模型是多模型的，则必须指定 target_model 参数。有关多模型终端节点的更多信息，请参阅 多模型端点。

    • endpoint_name_prefix -（可选）影子端点的自定义名称前缀。如果您提供 model_name 而不是 endpoint_name，则适用。例如，如果要根据端点名称限制对端点的访问，则提供 endpoint_name_prefix。前缀必须与 EndpointName 模式匹配，其最大长度为 23。默认为 sm-clarify。

    • initial_instance_count - 指定影子端点的实例数。如果您提供的是 model_name 而不是 endpoint_name，则为必需项。initial_instance_count 的值可以与作业的 InstanceCount 不同，但我们建议使用 1:1 的比率。

    • instance_type - 指定影子端点的实例类型。如果您提供的是 model_name 而不是 endpoint_name，则为必需项。例如，instance_type 可以设置为“ml.m5.large”。在某些情况下，为 instance_type 指定的值有助于缩短模型推理时间。例如，为了高效运行，自然语言处理模型和计算机视觉模型通常需要图形处理单元 (GPU) 实例类型。

    • endpoint_name - 由 CreateEndpoint API 创建的 SageMaker 端点的名称。如果提供，则 endpoint_name 优先于 model_name 参数。使用现有端点可以缩短影子端点的引导时间，但也可能导致该端点的负载显著增加。此外，某些分析方法（如 shap 和 pdp）会生成发送到端点的合成数据集。这可能会导致端点的指标或捕获的数据受到合成数据的污染，从而无法准确反映实际使用情况。出于这些原因，通常不建议使用现有的生产端点进行 SageMaker Clarify 分析。

    • target_model - 传递给 SageMaker InvokeEndpoint API 的 TargetModel 参数的字符串值。如果您的模型（由 model_name 参数指定）或端点（由 endpoint_name 参数指定）为多模型，则为必需项。有关多模型终端节点的更多信息，请参阅 多模型端点。

    • custom_attributes -（可选）一个字符串，允许您提供有关提交到端点的推理请求的其他信息。字符串值将传递给 SageMaker InvokeEndpoint API 的 CustomAttributes 参数。

    • content_type - 用于从端点获取预测的模型输入格式。如果提供，则将其传递给 SageMaker InvokeEndpoint API 的 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_type - 模型输出格式，用于从端点获取预测。accept_type 的值将传递给 SageMaker InvokeEndpoint API 的 Accept 参数。

      • 对于计算机视觉可解释性，如果 model_type 为“OBJECT_DETECTION”，则 accept_type 默认为 application/json。

      • 对于时间序列预测的可解释性，有效值为 application/json。

      • 对于其他类型的可解释性，有效值为 text/csv、application/jsonlines 和 application/json。如果未提供 accept_type 的值，则 accept_type 默认为 content_type 参数的值。

    • content_template - 模板字符串，用于根据数据集记录构造模型输入。仅当 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_template - 模板字符串，用于根据数据集实例构造模型输入的每条记录。仅当 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_template 和 record_template 参数值如下。

      • content_template: "$record"

      • record_template: "$features_kvp"

      有关更多示例，请参阅时间序列数据的端点请求。

    • label：（可选）一个基于零的整数索引或 JMESPath 表达式字符串，用于从模型输出中提取预测标签，以进行偏差分析。如果模型是多类模型，并且 label 参数从模型输出中提取所有预测标签，则适用以下内容。时间序列不支持此功能。

      • 从模型输出中获取相应概率（或得分）时需要 probability 参数。

      • 选择得分最高的预测标签。

      label 的值取决于 accept_type 参数的值，如下所示。

      • 如果 accept_type 为 text/csv，则 label 是模型输出中任何预测标签的索引。

      • 如果 accept_type 为 application/jsonlines 或 application/json，则 label 是一个 JMESPath 表达式，应用于模型输出以获取预测标签。

    • label_headers：（可选）数据集中标签可取值的数组。如果要求进行偏差分析，则还需要 probability 参数才能从模型输出中获取相应的概率值（得分），并选择得分最高的预测标签。如果要求进行可解释性分析，则使用标签标题来美化分析报告。计算机视觉可解释性需要 label_headers 的值。例如，对于多类分类问题，如果标签有三个可能的值（即 bird、cat 和 dog），则 label_headers 应设置为 ["bird","cat","dog"]。

    • probability：（可选）一个基于零的整数索引或一个 JMESPath 表达式字符串，用于提取可解释性分析（但不用于时间序列可解释性）的概率（得分），或用于选择偏差分析的预测标签。probability 的值取决于 accept_type 参数的值，如下所示。

      • 如果 accept_type 为 text/csv，则 probability 为模型输出中概率（得分）的索引。如果未提供 probability，则将整个模型输出作为概率（得分）。

      • 如果 accept_type 为 JSON 数据（application/jsonlines 或 application/json），则 probability 应是一个 JMESPath 表达式，用于从模型输出中提取概率（得分）。

    • time_series_predictor_config：（可选）仅用于时间序列可解释性。用于指示 SageMaker Clarify 处理器如何从 dataset_uri 中作为 S3 URI 传递的数据中正确解析数据。

      • forecast：用于提取预测结果的 JMESPath 表达式。

示例分析配置文件

以下章节包含 CSV 格式、JSON Lines 格式以及自然语言处理 (NLP)、计算机视觉 (CV) 和时间序列 (TS) 可解释性数据的分析配置文件示例。

以下几个示例说明如何为 CSV 格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集有四个特征列和一个二进制标签列 Target。数据集的内容如下所示。标签值为 1 表示结果为阳性。数据集由 dataset 处理输入提供给 SageMaker Clarify 作业。

"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 格式数据集特征重要性的部分依赖图 (PDP)。

计算所有训练前偏差指标

此示例配置显示如何衡量先前的示例数据集是否偏向于 0 值为 Gender 的样本。以下分析配置指示 SageMaker Clarify 处理作业计算数据集的所有训练前偏差指标。

{
    "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
...

以下配置示例指示 SageMaker Clarify 处理作业使用数据集和模型输出中的预测来计算所有可能的偏差指标。在该示例中，模型部署到 SageMaker 端点 your_endpoint。

注意

在以下示例代码中，未设置参数 content_type 和 accept_type。因此，它们会自动使用参数 dataset_type 的值，即 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。这指示 SageMaker Clarify 处理器计算一个 SHAP 基准样本。在本例中，概率设置为 1。这指示 SageMaker Clarify 处理作业从模型输出的第二列中提取概率得分（使用零基索引）。

计算部分依赖图 (PDP)

以下示例说明如何使用 PDP 在分析报告中查看 Income 特征的重要性。报告参数指示 SageMaker Clarify 处理作业生成报告。作业完成后，生成的报告将以 report.pdf 形式保存到 analysis_result 位置。grid_resolution 参数将特征值的范围划分为多个 10 存储桶。下面示例中指定的参数共同指示 SageMaker Clarify 处理作业生成一份报告，其中包含 Income 的 PDP 图，x 轴上有 10 个分段。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。这指示 SageMaker Clarify 处理作业计算具有最大全局 SHAP 值的前 2 项特征的部分依赖图 (PDP)。

{
    "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 参数向 SageMaker Clarify 处理作业提供 SageMaker 模型的名称，而不是将模型部署到端点。以下示例说明如何指定名为 your_model 的模型。SageMaker Clarify 处理作业将使用该配置创建一个影子端点。

{
     ...
    "predictor": {
        "model_name": "your_model",
        "initial_instance_count": 1,
        "instance_type": "ml.m5.large",
        "probability": 1
    }
}

以下几个示例说明如何为 JSON 行格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集与上一节的数据相同，但采用 SageMaker JSON 行密集格式。每行都是一个有效的 JSON 对象。键 "Features" 指向特征值数组，键 "Label" 指向 Ground Truth 标签。数据集由“dataset”处理输入提供给 SageMaker Clarify 作业。有关 JSON 行的更多信息，请参阅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 值以及显示 JSON 行格式数据集特征重要性的部分依赖图 (PDP)。

计算训练前偏差指标

指定标签、特征、格式和方法，以测量 Gender 值为 0 的训练前偏差指标。在以下示例中，headers 参数首先提供特征名称。最后提供标签名称。按照惯例，最后一个标题是标签标题。

features 参数设置为 JMESPath 表达式 "Features"，这样 SageMaker Clarify 处理作业就可以从每条记录中提取特征数组。label 参数设置为 JMESPath 表达式 "Label"，这样 SageMaker Clarify 处理作业就可以从每条记录中提取 Ground Truth 标签。使用分面名称来指定敏感属性，如下所示。

{
    "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}
...

可以将模型部署到名为 your_endpoint 的 SageMaker 端点。以下示例分析配置指示 SageMaker Clarify 处理作业计算数据集和模型的所有可能的偏差指标。在本例中，未设置参数 content_type 和 accept_type。因此，它们会自动设置为使用参数 dataset_type 的值，即 application/jsonlines。SageMaker Clarify 处理作业使用 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 参数。因此，SageMaker Clarify 处理作业必须使用通用名称（如 column_0 或 column_1）为特征标题生成占位符，使用 label0 为标签标题生成占位符。您可以为 headers 和 label 指定值，以提高分析结果的可读性。由于概率参数设置为 JMESPath 表达式 probability，因此将从模型输出中提取概率值。以下是计算 SHAP 值的示例。

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

计算部分依赖图 (PDP)

以下示例说明如何查看 PDP 上“Income”的重要性。在本例中，未提供特征标题。因此，pdp 方法的 features 参数必须使用零基索引来引用特征列的位置。grid_resolution 参数将特征值的范围划分为多个 10 存储桶。示例中的参数共同指示 SageMaker Clarify 处理作业生成一份报告，其中包含 Income 的 PDP 图，x 轴上有 10 个分段。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。这指示 SageMaker Clarify 处理作业计算具有最大全局 SHAP 值的前 2 项特征的 PDP。

{
    "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 格式的表格数据集配置偏差分析和可解释性分析。在这些示例中，传入的数据集与上一节的数据相同，但采用 SageMaker JSON 密集格式。有关 JSON 行的更多信息，请参阅JSONLINES 请求格式。

整个输入请求都是有效的 JSON，其中外部结构是一个列表，每个元素都是一条记录的数据。在每条记录中，键 Features 指向特征值数组，键 Label 指向 Ground Truth 标签。数据集由 dataset 处理输入提供给 SageMaker Clarify 作业。

[
    {"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 值以及显示 JSON 行格式数据集特征重要性的部分依赖图 (PDP)。

计算训练前偏差指标

指定标签、特征、格式和方法，以测量 Gender 值为 0 的训练前偏差指标。在以下示例中，headers 参数首先提供特征名称。最后提供标签名称。对于 JSON 数据集，最后一个标题是标签标题。

features 参数设置为提取二维数组或矩阵的 JMESPath 表达式。此矩阵中的每一行都必须包含每条记录的 Features 列表。label 参数设置为提取 Ground Truth 标签列表的 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},
        ...
    ]
}

可以将模型部署到名为 your_endpoint 的 SageMaker 端点。

在以下示例中，未设置参数 content_type 和 accept_type。因此，content_type 和 accept_type 会自动设置为使用参数 dataset_type 的值，即 application/json。然后，SageMaker Clarify 处理作业使用 content_template 参数来组成模型输入。

在以下示例中，通过将 $records 占位符替换为记录数组来组成模型输入。然后，record_template 参数组成每条记录的 JSON 结构，并将 $features 占位符替换为每条记录的特征数组。

以下示例分析配置指示 SageMaker Clarify 处理作业计算数据集和模型的所有可能的偏差指标。

{
    "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 参数。因此，SageMaker Clarify 处理作业将使用通用名称（如 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"
    }
}

计算部分依赖图 (PDP)

以下示例演示了如何在 PDP 中查看特征重要性。在该示例中，未提供特征标题。因此，pdp 方法的 features 参数必须使用零基索引来引用特征列的位置。grid_resolution 参数将特征值的范围划分为多个 10 存储桶。

以下示例中的参数共同指示 SageMaker Clarify 处理作业生成一份报告，其中包含 Income 的 PDP 图，x 轴上有 10 个分段。y 轴显示 Income 对预测的边际影响。

以下配置示例说明如何查看 PDP 上 Income 的重要性。

{
    "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。这指示 SageMaker Clarify 处理作业计算具有最大全局 SHAP 值的前 2 项特征的 PDP。

{
    "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_model”的 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。

在本例中，SageMaker 对象检测模型 (your_cv_od_model) 在相同的 JPEG 图像上进行训练，以识别图像上的动物。以下示例说明了如何为对象检测模型配置可解释性分析。

{
    "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 格式的时间序列数据集，包含一组动态和静态协变量功能。数据集由数据集处理输入参数 dataset_uri 提供给 SageMaker Clarify 作业。

[
    {
        "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 来定义时间序列可解释性参数，如基线、方向、粒度和样本数。基线值是为所有三类数据设定的：相关时间序列、静态协变量和目标时间序列。这些字段指示 SageMaker Clarify 处理器一次计算一个项目的功能属性。

预测器配置

您可以使用 JMESPath 语法完全控制 SageMaker Clarify 处理器发送的有效载荷结构。在上例中，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 属性指示 SageMaker Clarify 处理器从作为 dataset_uri 中 S3 URI 传递的数据中正确解析数据。