配置分析 - Amazon SageMaker
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

配置分析

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

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

您可以创建分析配置文件,也可以使用 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(激活计算机视觉问题的可解释性)

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

  • headers -(可选)包含表格数据集列名称在内的字符串数组。如果未提供 headers 的值,则 SageMaker Clarify 处理作业会从该数据集读取标题。如果该数据集没有标题,则 SageMaker Clarify 处理作业将根据零基列索引自动生成占位符名称。例如,第一列和第二列的占位符名称将分别是 column_0column_1

    注意

    按照惯例,如果 dataset_type 为 application/jsonlinesapplication/json,则 headers 应按顺序包含以下名称:特征名称、标签名称(如果已指定 label)和预测的标签名称(如果已指定 predicted_label)。如果已指定 label,则 application/jsonlines 数据集类型的 headers 的一个示例是:["feature1","feature2","feature3","target_label"]

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

    • 如果 dataset_typetext/csv,则 label 可以指定为以下任一项:

      • 有效的列名称

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

    • 如果 dataset_typeapplication/parquet,则 label 必须是有效的列名称。

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

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

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

    predicted_label 的值根据 dataset_type 的值指定,如下所示:

    • 如果 dataset_typetext/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_typeapplication/json,则 predicted_label 必须是为提取数据集中每条记录的预测标签而编写的 JMESPath 表达式。JMESPath 表达式应生成预测标签列表,其中第 i 个预测标签用于第 i 条记录。

  • features - 如果 dataset_type 为 application/jsonlinesapplication/json,则为必需项。为在输入数据集中定位特征而编写的 JMESPath 字符串表达式。对于 application/jsonlines,将对每一行应用 JMESPath 表达式,以提取该记录的特征。对于 application/json,将对整个输入数据集应用 JMESPath 表达式。JMESPath 表达式应提取一系列列表或提取特征的二维数组/矩阵,其中第 i 行包含与第 i 条记录相关的特征。对于 text/csvapplication/x-parquetdataset_type,除 Ground Truth 标签列和预测标签列之外的所有列都将自动指定为特征。

  • predicted_label_dataset_uri - 仅在 dataset_type 为 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,请参阅以下示例:

    • 对于二进制分类问题,标签有两个可能的值:01。如果标签值 1 对在样本中观测到的人口统计群体有利,则 label_values_or_threshold 应设置为 [1]

    • 对于多类分类问题,标签有三个可能的值:birdcatdog。如果后两者定义了偏差有利的人口统计群体,则 label_values_or_threshold 应设置为 ["cat","dog"]

    • 对于回归问题,标签值是连续的,范围从 01。如果一个大于 0.5 的值应将样本指定为具有阳性结果,则 label_values_or_threshold 应设置为 0.5

  • facet - 偏差分析所必需。分面对象数组,由偏差测量所依据的敏感属性组成。即使在不使用敏感属性的情况下对模型进行了训练,也可以使用分面来了解数据集和模型的偏差特征。有关更多信息,请参阅 Amazon SageMaker Clarify 偏差和公平性术语中的分面。每个分面对象都包含以下字段:

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

    • value_or_threshold - 如果 facet 是数字且 label_values_or_threshold 用作选择敏感组的下限,则为必需项。分面值或阈值数组,表示偏差有利的敏感人口统计群体。如果分面数据类型为分类且未提供 value_or_threshold,则以每个唯一值(而不是所有值)为一组来计算偏差指标。要针对不同的 facet 数据类型设置 value_or_threshold,请参阅以下示例:

      • 对于二进制分面数据类型,特征有两个可能的值:01。如果要计算每个值的偏差指标,则 value_or_threshold 可以省略或设置为空数组。

      • 对于分类分面数据类型,特征有三个可能的值:birdcatdog。如果前两者定义了偏差有利的人口统计群体,则 value_or_threshold 应设置为 ["bird", "cat"]。在本例中,数据集样本分为两个人口统计群体。优势群体的分面具有 birdcat 值,而劣势群体的分面具有 dog 值。

      • 对于数值分面数据类型,特征值是连续的,范围从 01。例如,如果一个大于 0.5 的值应将样本指定为有利样本,则 value_or_threshold 应设置为 0.5。在本例中,数据集样本分为两个人口统计群体。优势群体中的分面具有大于 0.5 的值,而劣势群体中的分面具有小于或等于 0.5 的值。

  • group_variable - 列的名称或零基索引,该列指示用于偏差指标条件人口统计差异 (CDD) 或预测标签中的条件人口统计差异 (CDDPL) 的子组。

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

    注意

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

  • facet_headers -(仅在已指定 facet_dataset_uri 时适用)字符串数组,这些字符串包含分面数据集的列名称,以及(可选)用于联接分面数据集和主数据集的标识符列标题,请参阅 joinsource_name_or_index

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

    • pre_training_bias - 如果要计算训练前偏差指标,则包括此方法。可以在测量训练前偏差中找到指标的详细描述。对象具有以下参数:

    • post_training_bias - 如果要计算训练后偏差指标,则包括此方法。可以在测量训练后偏差中找到指标的详细描述。post_training_bias 对象具有以下参数。

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

      • baseline -(可选)SHAP 基准数据集,也称为背景数据集。表格数据集中的基准数据集或计算机视觉问题的其他要求如下。

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

          • 格式必须与 dataset_type 指定的数据集格式相同。

          • 基准只能包含模型可以接受为输入的特征。

          • 基准数据集可以有一个或多个实例。基准实例的数量直接影响合成数据集的大小和作业运行时。

          • 如果已指定 text_config,则文本列的基准值是一个字符串,用于替换由 granularity 指定的文本单元。例如,一个常见的占位符是“[MASK]”,它用于表示缺失或未知的单词或文本段。

          以下示例演示了如何为不同 dataset_type 参数设置就地基准数据:

          • 如果 dataset_typetext/csvapplication/x-parquet,则模型接受四个数值特征,并且基准有两个实例。在本例中,如果一条记录的特征值全部为零,而另一条记录的特征值全部为一,则基准应设置为 [[0,0,0,0],[1,1,1,1]],不带任何标题。

          • 如果 dataset_typeapplication/jsonlines,则 features 是四个数值特征值列表的关键。此外,在本例中,如果基准有一条全部为零值的记录,则 baseline 应为 [{"features":[0,0,0,0]}]

          • 如果 dataset_typeapplication/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 处理作业会尝试将表格数据集划分为合适数量(介于 112 之间)的集群,从而计算基准数据集。基准实例数直接影响 SHAP 分析的运行时。

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

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

      • use_logit -(可选)一个布尔值,表示您希望将 logit 函数应用于模型预测。默认值为 false。如果 use_logittrue,则使用逻辑回归系数计算 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 - 用于文本列分析的粒度单位。有效值为 tokensentenceparagraph每个文本单元都视为一个特征,并计算每个单元的局部 SHAP 值。

        • language - 文本列的语言。有效值为 chinesedanishdutchenglishfrenchgermangreekitalianjapaneselithuanianmulti-languagenorwegian bokmålpolishportugueseromanianrussianspanishafrikaansalbanianarabicarmenianbasquebengalibulgariancatalancroatianczechestonianfinnishgujaratihebrewhindihungarianicelandicindonesianirishkannadakyrgyzlatvianligurianluxembourgishmacedonianmalayalammarathinepalipersiansanskritserbiansetswanasinhalaslovakslovenianswedishtagalogtamiltatarteluguthaiturkishukrainianurduvietnameseyoruba。输入 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_typeOBJECT_DETECTION 时适用。用于根据原始检测来评估预测值的最小交并比 (IOU) 指标。IOU 指标越高,说明预测的检测框与 Ground Truth 检测框之间的重叠程度越高。默认值为 0.5

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

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

    • pdp - 包括此方法来计算部分依赖图 (PDP)。

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

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

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

    • report -(可选)使用此对象自定义分析报告。作为分析结果的一部分,同一报告有三份副本:Jupyter 笔记本报告、HTML 报告和 PDF 报告。对象具有以下参数:

      • name - 报告文件的文件名。例如,如果 nameMyReport,则报告文件为 MyReport.ipynbMyReport.htmlMyReport.pdf。默认值为 report

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

  • predictor - 如果分析需要模型的预测结果,则为必需项。例如,当要求使用 shappdppost_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) 实例类型。

    • accelerator_type -(可选)指定要附加到影子端点的 Elastic Inference (EI) 加速器的类型。如果您为 accelerator_type 提供 model_name 而不是 endpoint_name,则适用。accelerator_type 的示例值为 ml.eia2.large。默认情况下不使用加速器。

    • endpoint_name - 由 CreateEndpoint API 创建的 SageMaker 端点的名称。如果提供,则 endpoint_name 优先于 model_name 参数。使用现有端点可以缩短影子端点的引导时间,但也可能导致该端点的负载显著增加。此外,某些分析方法(如 shappdp)会生成发送到端点的合成数据集。这可能会导致端点的指标或捕获的数据受到合成数据的污染,从而无法准确反映实际使用情况。出于这些原因,通常不建议使用现有的生产端点进行 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/jpegimage/pngapplication/x-npy。如果未提供 content_type,则默认值为 image/jpeg

      • 对于其他类型的可解释性,有效值为 text/csvapplication/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

      • 对于其他类型的可解释性,有效值为 text/csvapplication/jsonlinesapplication/json。如果未提供 accept_type 的值,则 accept_type 默认为 content_type 参数的值。

    • content_template - 模板字符串,用于根据数据集记录构造模型输入。仅当 content_type 参数的值为 application/jsonlinesapplication/json 时,才需要使用参数 content_template

      content_type 参数为 application/jsonlines 时,模板应只有一个占位符(即 $features),该占位符将在运行时被特征列表替换。例如,如果模板是 "{\"myfeatures\":$features}",并且如果某条记录有三个数字特征值(123),则该记录将作为 JSON 行 {"myfeatures":[1,2,3]} 发送到模型。

      content_typeapplication/json 时,模板可以有占位符 $recordrecords。如果占位符为 record,则单条记录将被替换为一条应用了 record_template 中模板的记录。在这种情况下,一次只能向模型发送一条记录。如果占位符为 $records,则记录将替换为记录列表,每条记录都有一个由 record_template 提供的模板。

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

      • content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"

      • record_template: "$features"

      在以下代码示例中,标题和特征定义如下。

      [ { "A": 0, "B": 1 }, { "A": 3, "B": 4 }, ]

      用于构造前述示例模型输入的示例 content_templaterecord_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_typetext/csv,则 label 是模型输出中任何预测标签的索引。

      • 如果 accept_typeapplication/jsonlinesapplication/json,则 label 是一个 JMESPath 表达式,应用于模型输出以获取预测标签。

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

    • probability -(可选)零基整数索引或 JMESPath 表达式字符串,用于提取概率(分数)以进行可解释性分析,或用于选择预测标签以进行偏差分析。probability 的值取决于 accept_type 参数的值,如下所示。

      • 如果 accept_typetext/csv,则 probability 为模型输出中概率(分数)的索引。如果未提供 probability,则将整个模型输出作为概率(分数)。

      • 如果 accept_type 为 JSON 数据(application/jsonlinesapplication/json),则 probability 应是一个 JMESPath 表达式,用于从模型输出中提取概率(分数)。

示例分析配置文件

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

以下几个示例说明如何为 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" } } } Com

计算所有训练后偏差指标

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

0,0.028986845165491 1,0.825382471084594 ...

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

注意

在以下示例代码中,未设置参数 content_typeaccept_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 作业。

{"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_typeaccept_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_0column_1)为特征标题生成占位符,使用 label0 为标签标题生成占位符。您可以为 headerslabel 指定值,以提高分析结果的可读性。由于概率参数设置为 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,其中外部结构是一个列表,每个元素都是一条记录的数据。在每条记录中,键 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_typeaccept_type。因此,content_typeaccept_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_0column_1)为特征标题生成占位符,使用 label0 为标签标题生成占位符。您可以为 headerslabel 指定值,以提高分析结果的可读性。

在以下配置示例中,概率参数设置为 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 数据,并输出一个介于 01 之间的分数,如下所示。

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"] } }

在本例中,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"] } }