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

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

分析配置文件

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

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

您可以创建分析配置文件或使用 SageMaker Python SDK 通过生成一个分析配置文件SageMaker ClarifyProcessorAPI。查看文件内容有助于理解 Clarify 作业使用的底 SageMaker 层配置。

分析配置文件的架构

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

分析配置文件的要求

C SageMaker larify 处理任务要求分析配置文件按照以下要求进行构建：

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

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

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

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

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

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

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

    • 表格

      • text/csv for CSV

      • application/jsonlinesfor L SageMaker JSONines 密集格式

      • application/json for JSON

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

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

    • 时间序列预测模型解释

      • application/json for JSON

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

  • 标题-（可选）

    • 表格：包含表格数据集列名的字符串数组。如果未提供值headers，则 Clarif SageMaker y 处理作业会从数据集中读取标题。如果数据集没有标题，则 Clarify 处理作业会根据从零开始的列索引自动生成占位符名称。例如，第一列和第二列的占位符名称将是column_0column_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. 商品编号

      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必须是为从数据集中提取真实数据标签而编写的JMESPath表达式。按照惯例，如果已指定 headers，则它应包含标签名称。

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

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

    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 个记录。

  • f eatures —（可选）如果dataset_type是application/jsonlines或，则为 non-time-series用例必填项application/json。为定位输入数据集中的要素而编写的JMESPath字符串表达式。对于application/jsonlines，将对每行应用一个JMESPath表达式来提取该记录的要素。对于application/json，JMESPath表达式将应用于整个输入数据集。该JMESPath表达式应提取列表列表或二维特征数组/矩阵，其中第 i 行包含与第 i 条记录相关的特征。对于 text/csv 或 application/x-parquet 的 dataset_type，除 Ground Truth 标签列和预测标签列之外的所有列都将自动指定为特征。

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

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

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

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

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

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

  • probability_threshold -（可选）一个浮点数，超过该浮点数将选择标签或对象。默认值为 0.5。C SageMaker larify 处理任务用于probability_threshold以下情况：

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

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

  • label_values_or_threshold —（可选）是偏差分析所必需的。标签值或阈值数组，表示 Ground Truth 的阳性结果和偏差指标的预测标签。有关更多信息，请参阅中的正标签值Amazon SageMaker 澄清偏见和公平条款。如果标签是数字，则使用阈值作为下限来选择阳性结果。要针对不同的问题类型设置 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 —（可选）偏差分析所必需的。分面对象数组，由偏差测量所依据的敏感属性组成。即使在不使用敏感属性的情况下对模型进行了训练，也可以使用分面来了解数据集和模型的偏差特征。有关更多信息，请参阅中的 Facet。Amazon SageMaker 澄清偏见和公平条款每个分面对象都包含以下字段：

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

    • value_or_th reshold —（可选）如果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_variab le —（可选）列的名称或从零开始的索引，用于表示要用于偏差指标的子组或。有条件的人口差异 () CDD 预测标签中的条件人口差异 () CDDPL

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

    注意

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

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

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

    • item_id — 字符串或从零开始的整数索引。此字段用于在共享输入数据集中查找项目 ID。

    • 时间戳-字符串或从零开始的整数索引。此字段用于在共享输入数据集中查找时间戳。

    • d@@ ataset_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值，请包括此方法。Cl SageMaker arify 处理作业支持内核SHAP算法。shap 对象具有以下参数。

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

        • 对于表格数据集，baseline可以是就地基线数据，也可以是基线文件URI的 S3。如果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可以是图像的 S3URI，用于屏蔽输入图像中的特征（分段）。C SageMaker larify 处理任务加载蒙版图像并将其大小调整为与输入图像相同的分辨率。如果未提供基准，Cl SageMaker arify 处理作业会生成与输入图像相同分辨率的白噪声掩模图像。

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

      • num_clusters -（可选）为计算基准数据集而将数据集分成的集群数。每个集群用于计算一个基准实例。如果未指定，C baseline lar SageMaker ify 处理作业将尝试通过将表格数据集划分为介于1和12之间的最佳聚类数来计算基线数据集。基准实例的数量直接影响SHAP分析的运行时间。

      • num_s amples —（可选）内核SHAP算法中要使用的样本数。如果num_samples未提供，则 Cl SageMaker arify 处理任务会为您选择号码。样本数直接影响合成数据集的大小和作业运行时。

      • 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_met hod —（可选）用于将所有实例的本地SHAPSHAP值（每个实例的值）聚合为全局SHAP值（整个数据集的SHAP值）的方法。默认值为 mean_abs。以下方法可用于聚合SHAP值。

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

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

        • m edian — 所有实例的局部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_tok ens —（可选）排名靠前的代币的最大数量，基于全局值。SHAP默认值为 50。一个令牌有可能在数据集中多次出现。Cl SageMaker arify 处理任务汇总每个令牌的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。union (IOU) 指标的最小交集，用于根据原始检测来评估预测值。较高的IOU指标对应于预测的真相检测框和地面真相检测框之间存在较大的重叠。默认值为 0.5。

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

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

    • pdp — 包括此方法来计算部分依赖图 (PDPs)。有关要生成的分析配置的示例PDPs，请参见 计算部分依赖图 (PDPs)

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

      • top_k_feat ures —（可选）指定用于生成绘图的顶级要素数量。PDP如果features未提供，但请求了shap方法，则 Clarif SageMaker y 处理任务会根据其SHAP归因选择最重要的要素。默认值为 10。

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

    • asymmetric_shapley_value — 如果要计算时间序列预测模型的可解释性指标，请使用此方法。Cl SageMaker arify 处理作业支持非对称 Shapley 值算法。非对称 Shapley 值是 Shapley 值的变体，它删除了对称公理。有关更多信息，请参见非对称 Shapley 值：将因果知识整合到与模型无关的可解释性中。使用这些值来确定要素如何影响预测结果。非对称 Shapley 值考虑了预测模型作为输入的时间序列数据的时间依赖关系。

      该算法包括以下参数：

      • 方向-可用类型有chronologicalanti_chronological、和bidirectional。时间结构可以按时间顺序或反时间顺序导航，也可以两者兼而有之。按时间顺序排列的解释是通过从第一步开始迭代添加信息来构建的。反时间顺序解释添加了从上一步开始并向后移动的信息。在存在近期偏差的情况下，后一种顺序可能更合适，例如用于预测股价。

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

        • timewise — timewise 解释成本低廉，仅提供有关特定时间步长的信息，例如弄清楚过去第 n 天的信息对未来第 m 天的预测有多大贡献。由此产生的归因不能单独解释静态协变量，也不能区分目标时间序列和相关时间序列。

        • fine_graine fine_grained d — 解释的计算密集度更高，但提供了输入变量的所有属性的完整细分。该方法计算近似解释以缩短运行时间。有关更多信息，请参阅以下参数num_samples。

          注意

          fine_grained解释仅支持chronological顺序。

      • num_samp les —（可选）解释时需要使用此参数。fine_grained数字越大，近似值越精确。此数字应随输入要素的维度进行缩放。经验法则是，如果结果不太大，则将此变量设置为 (1 + max (相关时间序列数、静态协变量数)) ^2。

      • b@@ as eline —（可选）用于替换相应数据集（也称为背景数据） out-of-coalition值的基线配置。以下代码段显示了基准配置的示例：

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

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

          • zero— 所有 out-of-coalition值都替换为 0.0。

          • mean— 所有 out-of-coalition值都替换为时间序列的平均值。

        • 对于静态协变量，只有在模型请求采用静态协变量值时才应提供基线条目，在这种情况下，此字段为必填字段。应以清单形式为每个项目提供基准。例如，如果您的数据集包含两个静态协变量，则您的基准配置可能如下所示：

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

          在前面的示例中，<item_id_1> 以及 <item_id_2> 是数据集中的项目 ID。

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

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

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

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

    • model_nam e — 由创建的 SageMaker 模型的名称。CreateModelAPI如果您指定 endpoint_name model_name 而不是 endpoint_name，则 Clarify 处理作业会创建一个具有模型名称的临时端点（称为影子端点），并从该端点获取预测。 SageMaker 计算完成后，作业会删除影子端点。如果模型是多模型，则必须指定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 — 由创建的 SageMaker 终端节点的名称。CreateEndpointAPI如果提供，则 endpoint_name 优先于 model_name 参数。使用现有端点可以缩短影子端点的引导时间，但也可能导致该端点的负载显著增加。此外，某些分析方法（如 shap 和 pdp）会生成发送到端点的合成数据集。这可能会导致端点的指标或捕获的数据受到合成数据的污染，从而无法准确反映实际使用情况。出于这些原因，通常不建议使用现有的生产端点进行 Clarif SageMaker y 分析。

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

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

    • content_type - 用于从端点获取预测的模型输入格式。如果提供，则将其传递给的ContentType参数 SageMaker InvokeEndpointAPI。

      • 对于计算机视觉可解释性，有效值为 image/jpeg、image/png 或 application/x-npy。如果未提供 content_type，则默认值为 image/jpeg。

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

      • 对于其他类型的可解释性，有效值为 text/csv、application/jsonlines, 和 application/json。如果content_type是，则需要dataset_type为的值application/x-parquet。否则 content_type 默认为 dataset_type 参数的值。

    • accept_type - 模型输出格式，用于从端点获取预测。的accept_type值将传递给的Accept参数 SageMaker InvokeEndpointAPI。

      • 为了便于解释计算机视觉，如果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}"，并且记录具有三个数值特征值：13、2和，则该记录将作为 JSON Line 发送到模型{"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"]。

    • 概率-（可选）从零开始的整数索引或JMESPath表达式字符串，用于提取概率（分数）以进行可解释性分析（但不适用于时间序列可解释性），或者用于为偏差分析选择预测标签。probability 的值取决于 accept_type 参数的值，如下所示。

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

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

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

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

示例分析配置文件

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

以下示例说明如何为格式的表格数据集配置偏见和可解释性分析。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值以及显示格式数据集特征重要性的部分依赖图 (PDPs)。CSV

计算所有训练前偏差指标

此示例配置显示如何衡量先前的示例数据集是否偏向于 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 处理作业使用数据集和模型输出中的预测来计算所有可能的偏差指标。在示例中，模型部署到 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值

以下示例分析配置指示作业计算将列指定为标签，将所有其他Target列指定为特征的SHAP值。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

在此示例中，SHAPbaseline参数被省略，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 SageMaker 处理作业生成一份报告，其中包含在 x 轴上Income有10分段的PDP图表。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 模型名称，而不必将 SageMaker 模型部署到端点。以下示例说明如何指定名为 your_model 的模型。Cl SageMaker arify 处理任务将使用配置创建一个影子端点。

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

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

计算训练前偏差指标

指定标签、特征、格式和方法，以测量 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"
        }
    }
}

计算所有偏差指标

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

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

您可以将模型部署到名为的 SageMaker 端点your_endpoint。以下示例分析配置指示 Cl SageMaker arify 处理作业计算数据集和模型的所有可能偏差指标。在本例中，未设置参数 content_type 和 accept_type。因此，它们会自动设置为使用参数 dataset_type 的值，即 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分析不需要真实情况标签，因此省略了该label参数。在本例中，也省略了 headers 参数。因此，Cl SageMaker arify 处理作业必须使用通用名称（如column_0或）column_1为功能标题和label0标签标题生成占位符。您可以为 headers 和 label 指定值，以提高分析结果的可读性。由于概率参数设置为 expr JMESPath essionprobability，因此将从模型输出中提取概率值。以下是计算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。在本例中，未提供特征标题。因此，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在这些示例中，传入的数据集与上一节的数据相同，但它们采用的是 SageMaker JSON密集格式。有关JSON线路的更多信息，请参阅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线条格式显示数据集的特征重要性。

计算训练前偏差指标

指定标签、特征、格式和方法，以测量 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},
        ...
    ]
}

您可以将模型部署到名为的 SageMaker 端点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_m SageMaker odel” 的模型。以下分析配置说明了如何使用模型和数据集运行按令牌分类的可解释性分析。该text_config参数激活可NLP解释性分析。granularity 参数表示分析应解析令牌。

在英语中，每个令牌都是一个单词。以下示例还展示了如何使用平均 SHAP “评级” 为 4 来提供就地的 “基准” 实例。特殊的掩码标记 “[MASK]” 用于替换 “评论” 中的标记（单词）。此示例还使用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格式为一组动态和静态协变量特征。数据集由数据集处理输入参数提供给 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'
    }
}
时间序列可解释性配置

前面的示例使用asymmetric_shapley_valuemethods来定义时间序列可解释性参数，例如基线、方向、粒度和样本数。为所有三种类型的数据设置基准值：相关时间序列、静态协变量和目标时间序列。这些字段指示 Clar SageMaker ify 处理器一次计算一件商品的特征归因。

预测器配置

您可以使用JMESPath语法完全控制 Clarify 处理 SageMaker 器发送的有效载荷结构。在前面的示例中，predictor配置指示 Clarify 将记录聚合到'{"instances": $records}'，其中每条记录都是使用示例record_template中给出的参数定义的。请注意，$start_time、$target_time_series$related_time_series、和$static_covariates是用于将数据集值映射到端点请求值的内部标记。

同样，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]}
    ]
}

假设您指定了以下时间序列预测器配置：

'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