分析を設定する

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 処理ジョブを調整するさまざまなオプションについて説明します。

分析設定ファイルのパラメータ

JSON 設定ファイルでは、次のパラメータを指定できます。

• version — (オプション) 分析設定ファイルスキーマのバージョン文字列。バージョンが指定されていない場合、 SageMaker Clarify はサポートされている最新バージョンを使用します。現在サポートされているバージョンは 1.0 のみです。

• dataset_type — データセットの形式。入力データセット形式は、次のいずれかの値になります。

  • 表形式

    • CSV の場合 text/csv

    • application/jsonlines SageMaker JSON Lines の高密度形式

    • JSON の場合 application/json

    • Apache Parquet の場合 application/x-parquet

    • コンピュータビジョンの問題に対する説明可能性を有効にする場合 application/x-image

  • 時系列予測モデルの説明

    • JSON の場合 application/json

• dataset_uri — (オプション) メインデータセットのユニフォームリソース識別子 (URI)。S3 URI プレフィックスを指定すると、 SageMaker Clarify 処理ジョブはプレフィックスの下にあるすべての S3 ファイルを再帰的に収集します。コンピュータビジョンの問題に対して、イメージマニフェストファイルには S3 URI プレフィックスまたは S3 URI のいずれかを指定できます。dataset_uri を指定すると、データセット処理ジョブの入力よりも優先されます。画像と時系列のユースケースを除く任意の形式タイプの場合、 SageMaker Clarify 処理ジョブは入力データセットを表形式データセット として表形式データフレームにロードします。この形式により SageMaker 、 は入力データセットを簡単に操作および分析できます。

• ヘッダー – (オプション）

  • 表形式： 表形式のデータセットの列名を含む文字列の配列。の値が指定されていない場合headers、 SageMaker Clarify 処理ジョブはデータセットからヘッダーを読み取ります。データセットにヘッダーがない場合、Clarify 処理ジョブはゼロベースの列インデックスに基づいてプレースホルダー名を自動的に生成します。例えば、1 列目と 2 列目のプレースホルダー名は 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. timestamp

    3. ターゲット時系列

    4. 関連するすべての時系列列

    5. すべての静的共変数列

• label — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、label はグラウンドトゥルースラベル (表形式データセットでは観測ラベルまたはターゲット属性とも呼ばれる) の位置を特定するために使用されます。グラウンドトゥルースラベルはバイアスメトリックの計算に使用されます。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 — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、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 番目のレコードに対する予測ラベルのリストを生成する必要があります。

• 機能 – (オプション) dataset_typeが application/jsonlinesまたは の場合、 non-time-series ユースケースに必要ですapplication/json。入力データセット内の特徴量を検索するために記述された JMESPath 文字列式。application/jsonlines の場合、JMESPath 式は各行に適用され、そのレコードの特徴量が抽出されます。application/json の場合、JMESPath 式は入力データセット全体に適用されます。JMESPath 式は、i 番目の行に i 番目のレコードと相関する特徴量が含まれるリストのリストまたは特徴量の 2D 配列/行列を抽出する必要があります。dataset_type が text/csv または application/x-parquet の場合、グラウンドトゥルースラベルと予測ラベル列を除くすべての列が自動的に特徴量に割り当てられます。

• predicted_label_dataset_uri – (オプション) dataset_type が の場合にのみ該当しますtext/csv。トレーニング後のバイアスメトリクスの計算に使用される予測ラベルを含むデータセットの S3 URI。 SageMaker Clarify 処理ジョブは、モデルから予測を取得するのではなく、指定された URI から予測をロードします。この場合、predicted_label は予測ラベルデータセット内の予測ラベル列を見つける必要があります。予測ラベルデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を 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 の値は、次のような場合に必要です。

  • 入力データセットが複数あり、いずれか 1 つが複数のファイルに分割される。

  • 分散処理は、 SageMaker Clarify 処理ジョブを より大きいInstanceCount値に設定することでアクティブ化されます1。

• excluded_columns — (オプション) 予測の入力としてモデルに送信されないようにする列の名前またはゼロから始まるインデックスの配列。グラウンドトゥルースラベルと予測ラベルは既に自動的に除外されています。この機能は時系列ではサポートされていません。

• probability_threshold — (オプション) 浮動小数点数で、それを超えるとラベルまたはオブジェクトが選択されます。デフォルト値は、0.5です。 SageMaker Clarify 処理ジョブprobability_thresholdは、次の場合に を使用します。

  • トレーニング後のバイアス分析では、probability_threshold はモデルが二項分類器の場合、数値モデル予測 (確率値またはスコア) をバイナリラベルに変換します。しきい値より大きいスコアは 1 に変換されます。一方、しきい値以下のスコアは 0 に変換されます。

  • コンピュータビジョンの説明可能性の問題では、model_type が OBJECT_DETECTION の場合、, probability_thresholdによって信頼スコアがしきい値より低いオブジェクトが検出されて除外されます。

• label_values_or_threshold – (オプション) バイアス分析に必要です。ラベル値またはしきい値の配列。バイアスメトリクスに対するグラウンドトゥルースラベルと予測ラベルの肯定的な結果を示します。詳細については、「」の「正のラベル値」を参照してくださいAmazon SageMaker Clarify のバイアスと公平性に関する用語。ラベルが数値の場合、しきい値は肯定的な結果を選択するための下限として適用されます。さまざまな問題タイプの label_values_or_threshold を設定するには、以下の例を参照してください。

  • 二項分類問題の場合、ラベルには 0 と 1 の 2 つの値があります。サンプルで観察された属性グループにとってラベル値 1 が好ましい場合は、label_values_or_threshold を [1] に設定する必要があります。

  • 多クラス分類問題の場合、ラベルには bird と cat と dog の 3 つの指定できる値があります。後者の 2 つでバイアスが有利に働く属性グループを定義する場合は、label_values_or_threshold を ["cat","dog"] に設定する必要があります。

  • リグレッション問題では、ラベル値は 0 から 1 までの範囲で連続しています。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 を指定しない場合、バイアスメトリクスは (すべての値ではなく) 一意の値ごとに 1 つのグループとして計算されます。さまざまな facet データ型に value_or_threshold をを設定するには、以下の例を参照してください。

    • 二項ファセットデータ型の場合、特徴量には 0 と 1 の 2 つの可能な値があります。各値のバイアスメトリクスを計算する場合は value_or_threshold を省略するか空の配列に設定できます。

    • 分類型のファセットデータ型の場合、特徴量に bird、cat、dog の 3 つの可能な値があります。最初の 2 つがバイアスが有利に働く属性グループを定義している場合、value_or_threshold を ["bird", "cat"] に設定する必要があります。この例では、データセットサンプルは、2 つの属性グループに分割されます。有利なグループのファセットは bird または cat の値を持ち、不利なグループのファセットは dog の値を持ちます。

    • 数値ファセットデータ型の場合、特徴量値は 0 から 1までの範囲で連続しています。例えば、0.5 よりも大きい値によってサンプルを優先するように指定する場合は、value_or_threshold を 0.5 に設定する必要があります。この例では、データセットサンプルは、2 つの属性グループに分割されます。有利なグループのファセットの値は 0.5 より大きく、不利なグループのファセットの値は 0.5 以下です。

• group_variable – (オプション) バイアスメトリクス または に使用されるサブグループを示す列の名前条件付き属性格差 (CDD)またはゼロベースのインデックス予測ラベルの条件付き属性格差 (CDDPL)。

• facet_dataset_uri – (オプション) dataset_type が の場合にのみ該当しますtext/csv。バイアス分析用の機密属性を含むデータセットの S3 URI。機密属性を使用せずにモデルをトレーニングした場合でも、ファセットを使用してデータセットとモデルのバイアス特性を理解できます。

  注記

  ファセットデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を 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 — 1 つ以上の分析メソッドとそのパラメータを含むオブジェクト。メソッドを省略すると、そのメソッドは分析にもレポートにも使用されません。

  • pre_training_bias — トレーニング前のバイアスメトリクスを計算する場合は、このメソッドを含めます。メトリクスの詳細については、「」を参照してくださいトレーニング前のバイアスを測定する。オブジェクトには以下のパラメータがあります。

    • methods — 以下のリストにある計算対象となるトレーニング前のバイアスメトリクスのいずれかを含む配列。methods を all に設定すると、トレーニング前のバイアスメトリクスをすべて計算します。例えば、配列 ["CI", "DPL"] はクラス不均衡とラベルの比率の差を計算します。

      • クラス不均衡 (CI) の場合は CI

      • ラベルの比率の差 (DPL) の場合は DPL

      • カルバックライブラー情報量 (KL) の場合は KL

      • ジェンセンシャノン情報量 (JS) の場合は JS

      • Lp-norm (LP) の場合は LP

      • 合計変動距離 (TVD) の場合は TVD

      • コルモゴロフスミルノフ (KS) の場合は KS

      • 条件付き属性格差 (CDD) の場合は CDDL

  • pre_training_bias — トレーニング後のバイアスメトリクスを計算する場合は、このメソッドを含めます。メトリクスの詳細については、「」を参照してくださいトレーニング後のデータとモデルのバイアスを測定する。post_training_bias オブジェクトには以下のパラメータがあります。

    • methods — 以下のリストにある計算対象となるトレーニング後のバイアスメトリクスのいずれかを含む配列。methods を all に設定すると、トレーニング後のバイアスメトリクスをすべて計算します。例えば、配列 ["DPPL", "DI"] は予測ラベルにおける正の比率の差と異種影響を計算します。使用できるメソッドは次のとおりです。

      • 予測ラベルにおける正の比率の差 (DPPL) の場合は DPPL

      • DIの 異種影響 (DI)

      • 条件付き承認の差 (DCAcc) の場合は DCA

      • 条件付き拒否の差 (DCR) の場合は DCR

      • 特異度差 (SD) の場合は SD

      • リコール差 (RD) の場合は RD

      • 承認率の差 (DAR) の場合は DAR

      • 拒否率の差 (DRR) の場合は DRR

      • 精度差 (AD) の場合は AD

      • 処理の同等性 (TE) の場合は TE

      • 予測ラベルの条件付き属性格差 (CDDPL) の場合は CDDPL

      • 反事実フリップテスト (FT) の場合は FT

      • 一般化エントロピー (GE) の場合は GE

  • shap — SHAP 値を計算する場合はこのメソッドを含めます。 SageMaker Clarify 処理ジョブは、カーネル SHAP アルゴリズムをサポートします。shap オブジェクトには以下のパラメータがあります。

    • baseline – (オプション) SHAP ベースラインデータセット。バックグラウンドデータセットとも呼ばれます。表形式データセットまたはコンピュータービジョンの問題におけるベースラインデータセットのその他の要件は次のとおりです。SHAP ベースラインの詳細については、「」を参照してください。 説明可能性のための SHAP ベースライン

      • 表形式データセットの場合、baseline はインプレースベースラインデータまたはベースラインファイルの S3 URI のいずれかになります。が指定されbaselineていない場合、 SageMaker Clarify 処理ジョブは入力データセットをクラスター化してベースラインを計算します。ベースラインには以下が必要です。

        • 形式は、dataset_type で指定されたデータセット形式と同じである必要があります。

        • ベースラインには、モデルが入力として受け入れることができる特徴量のみを含めることができます。

        • ベースラインデータセットには 1 つ以上のインスタンスを含めることができます。ベースラインインスタンスの数は、合成データセットのサイズとジョブのランタイムに直接影響します。

        • text_config が指定されている場合、テキスト列のベースライン値は、granularity で指定されたテキスト単位を置き換えるために使用される文字列です。例えば、一般的なプレースホルダーの 1 つは "[MASK]" です。これは、欠落している単語、または不明な単語やテキストを表すために使用されます。

        次の例は、さまざまな dataset_type パラメータのインプレースベースラインデータを設定する方法を示しています。

        • dataset_type が text/csv または application/x-parquet の場合、モデルは 4 つの数値特徴量を受け入れ、ベースラインには 2 つのインスタンスがあることになります。この例では、1 つのレコードにすべて 0 の特徴量値が含まれ、もう 1 つのレコードにはすべて 1 つの特徴量値が含まれている場合、ベースラインはヘッダーなしで [[0,0,0,0],[1,1,1,1]] に設定する必要があります。

        • dataset_type が application/jsonlines の場合、features が 4 つの数値特徴量値のリストの鍵となります。また、この例では、ベースラインにすべて 0 の値を含むレコードが 1 つある場合、baseline は [{"features":[0,0,0,0]}] となる必要があります。

        • dataset_type が application/json の場合、baseline データセットの構造と形式は入力データセットと同じである必要があります。

      • コンピュータービジョンの問題では、baseline は入力イメージから特徴量 (セグメント) をマスクするために使用されるイメージの S3 URI になることがあります。 SageMaker Clarify 処理ジョブはマスクイメージをロードし、入力イメージと同じ解像度にサイズ変更します。ベースラインが指定されていない場合、 SageMaker Clarify 処理ジョブは入力イメージと同じ解像度でホワイトノイズのマスクイメージを生成します。

    • features_to_explain — (オプション) SHAP 値を計算するための文字列配列または 0 から始まる特徴量列のインデックス。features_to_explain が指定されていない場合、すべての特徴量列の SHAP 値が計算されます。これらの特徴量列には、ラベル列や予測ラベル列を含めることはできません。features_to_explain パラメータは、数値列とカテゴリ列を含む表形式データセットでのみサポートされます。

    • num_clusters — (オプション) ベースラインデータセットを計算するためにデータセットを分割するクラスターの数。各クラスターは 1 つのベースラインインスタンスの計算に使用されます。が指定されていない場合、 SageMaker Clarify 処理ジョブbaselineは、表形式のデータセットを 1と の間の最適な数のクラスターに分割して、ベースラインデータセットの計算を試みます12。ベースラインインスタンスの数は SHAP 分析のランタイムに直接影響します。

    • num_samples — (オプション) Kernel SHAP アルゴリズムで使用されるサンプルの数。が指定されnum_samplesていない場合、 SageMaker Clarify 処理ジョブはユーザーに代わって番号を選択します。サンプルの数は、合成データセットのサイズとジョブのランタイムに直接影響します。

    • seed — (オプション) 同じジョブに対して一貫性のある SHAP 値を生成するために、SHAP Explainer 内の疑似乱数生成器を初期化するために使用される整数。シードが指定されていない場合、同じジョブが実行されるたびに、モデルから出力される SHAP 値が若干変わることがあります。

    • use_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 メトリックが高いと、予測値検出ボックスとグラウンドトゥルース検出ボックスとの重複が大きくなります。デフォルトは 0.5 です。

      • num_segments — (オプション) 入力イメージでラベル付けされるおおよそのセグメント数を決定する整数。イメージの各セグメントは特徴量と見なされ、各セグメントのローカル SHAP 値が計算されます。デフォルトは 20 です。

      • segment_compactness — (オプション) scikit-image slic メソッドによって生成されるイメージセグメントの形状とサイズを決定する整数。デフォルトは 5 です。

  • pdp — このメソッドを含めて、部分依存プロット (PDPs。PDPs「」を参照してください。 部分依存プロット (PDP) を計算する

    • features — shap メソッドが要求されていない場合は必須です。PDP プロットを計算してプロットするための特徴量名またはインデックスの配列。

    • top_k_features — (オプション) PDP プロットの生成に使用される上位の特徴量数を指定します。が指定されfeaturesていないが、 shapメソッドがリクエストされた場合、 SageMaker Clarify 処理ジョブは SHAP 属性に基づいて上位の機能を選択します。デフォルトは 10 です。

    • grid_resolution — 数値の範囲を分割するバケットの数です。これは、PDP プロットのグリッドの粒度を指定します。

  • asymmetric_shapley_value – 時系列予測モデルの説明可能性メトリクスを計算する場合は、このメソッドを含めます。 SageMaker Clarify 処理ジョブは、非対称 Shapley 値アルゴリズムをサポートします。非対称シェープリー値は、対称軸を削除するシェープリー値のバリアントです。詳細については、「非対称シェープリー値: 因果知識をモデルに依存しない説明可能性に組み込む」を参照してください。これらの値を使用して、特徴量が予測結果にどのように寄与するかを決定します。非対称シェープリー値は、予測モデルが入力として受け取る時系列データの時間的依存関係を考慮します。

    アルゴリズムには、次のパラメータが含まれます。

    • direction – 使用可能なタイプは、chronological、anti_chronological、および ですbidirectional。時間構造は、時系列または非時系列の順序、またはその両方でナビゲートできます。時系列の説明は、最初のステップ以降の情報を繰り返し追加することで構築されます。時系列以外の説明では、最後のステップから始まり、後退する情報が追加されます。後者の順序は、株価の予測など、最近のバイアスがある場合により適切である可能性があります。

    • 粒度 — 使用する説明粒度。使用可能な詳細度オプションは次のとおりです。

      • timewise – timewise 説明は安価で、過去の n ^日目の情報が将来の m 日目の予測にどの程度貢献したかを判断するなど、特定の時間ステップに関する情報のみを提供します。結果として得られる属性は、個別に静的な共変数を説明しず、ターゲットと関連する時系列を区別しません。

      • fine_grained – fine_grained説明は計算負荷が高くなりますが、入力変数のすべての属性の完全な内訳を提供します。メソッドはおおよその説明を計算して、ランタイムを短縮します。詳細については、次のパラメータ を参照してくださいnum_samples。

        注記

        fine_grained 説明はchronological順序のみをサポートします。

    • num_samples – (オプション) この引数はfine_grained説明に必要です。数値が大きいほど、近似精度が高くなります。この数は、入力特徴の次元に応じてスケーリングする必要があります。経験則として、結果が大きすぎない場合は、この変数を (1 + max(関連する時系列の数、静的共変数の数))^2 に設定します。

    • baseline – (オプション) 対応するデータセット (バックグラウンドデータとも呼ばれます) の 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 値は時系列の平均に置き換えられます。

      • 静的な共変数の場合、モデルリクエストが静的な共変数値を取る場合にのみベースラインエントリを指定する必要があります。その場合、このフィールドは必須です。ベースラインは、すべての項目をリストとして指定する必要があります。例えば、2 つの静的な共変数を持つデータセットがある場合、ベースライン設定は次のようになります。

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

        前の例では、<item_id_1> と <item_id_2> がデータセットの項目 ID です。

  • report — (オプション) このオブジェクトを使用して分析レポートをカスタマイズします。このパラメータは、時系列説明ジョブではサポートされていません。分析結果の一部には、Jupyter Notebook レポート、HTML レポート、PDF レポートの 3 つのコピーがあります。オブジェクトには以下のパラメータがあります。

    • name — レポートファイルのファイル名。例えば、name が MyReport の場合、レポートファイルは MyReport.ipynb、MyReport.html、MyReport.pdf です。デフォルトは report です。

    • title — (オプション) レポートのタイトル文字列。デフォルトは SageMaker Analysis Report です。

• predictor — 分析でモデルからの予測が必要な場合に必須です。例えば、shap、、pdp、または asymmetric_shapley_valuepost_training_biasメソッドがリクエストされたが、予測ラベルが入力データセットの一部として提供されていない場合です。predictor と組み合わせて使用するパラメータは次のとおりです。

  • model_name – CreateModel API によって作成された SageMaker モデルの名前。endpoint_name model_nameの代わりに を指定すると、 SageMaker Clarify 処理ジョブはシャドウエンドポイント と呼ばれるモデル名を持つエフェメラルエンドポイントを作成し、エンドポイントから予測を取得します。ジョブは、計算が完了した後にシャドウエンドポイントを削除します。モデルがマルチモデルの場合、 target_modelパラメータを指定する必要があります。マルチモデルエンドポイントの詳細については、「」を参照してください1 つのエンドポイントの背後にある 1 つのコンテナで複数のモデルをホストする。

  • endpoint_name_prefix — (オプション) シャドウエンドポイントのカスタム名プレフィックス。endpoint_name の代わりに model_name を指定した場合に適用されます。例えば、エンドポイントへのアクセスをエンドポイント名で制限する場合は endpoint_name_prefix を指定します。プレフィックスはEndpointNameパターンと一致する必要があり、最大長は です23。デフォルトは sm-clarify です。

  • initial_instance_count - シャドウエンドポイントのインスタンス数を指定します。endpoint_name の代わりに model_name を指定する場合は必須です。の値はジョブInstanceCountの とは異なるinitial_instance_count場合がありますが、1:1 の比率をお勧めします。

  • instance_type-シャドウエンドポイントのインスタンスタイプを指定します。endpoint_name の代わりに model_name を指定する場合は必須です。例えば、instance_type を "ml.m5.large" に設定できます。場合によっては、instance_type に指定した値がモデル推論時間の短縮に役立つことがあります。例えば、自然言語処理モデルとコンピュータービジョンモデルを効率的に実行するには、通常、グラフィックス処理装置 (GPU) インスタンスタイプが必要です。

  • accelerator_type — (オプション) シャドウエンドポイントにアタッチする Elastic Inference (EI) アクセラレータのタイプを指定します。accelerator_type に endpoint_name の代わりに model_name を指定した場合に適用されます。accelerator_type の値の例は ml.eia2.large です。デフォルトではアクセラレータを使用しません。

  • endpoint_name – CreateEndpoint API によって作成された SageMaker エンドポイントの名前。指定した場合、endpoint_name が model_name パラメータよりも優先されます。既存のエンドポイントを使用するとシャドウエンドポイントのブートストラップ時間が短縮されますが、そのエンドポイントの負荷が大幅に増加する可能性もあります。また、分析メソッド (shap やなど pdp) によっては、エンドポイントに送信される合成データセットを生成します。これにより、エンドポイントのメトリクスやキャプチャされたデータが、実際の使用状況を正確に反映していない合成データによって汚染される可能性があります。このような理由から、 SageMaker Clarify 分析に既存の本番エンドポイントを使用することは一般的にお勧めしません。

  • target_model – API の SageMaker InvokeEndpoint TargetModel パラメータに渡される文字列値。モデル (model_name パラメータで指定) またはエンドポイント (endpoint_name パラメータで指定) が multi-model の場合に必要です。マルチモデルエンドポイントの詳細については、「」を参照してください1 つのエンドポイントの背後にある 1 つのコンテナで複数のモデルをホストする。

  • custom_attributes — (オプション) エンドポイントに送信される推論リクエストに関する追加情報を提供できる文字列。文字列値は API の CustomAttributesパラメータに渡されます SageMaker InvokeEndpoint。

  • content_type — content_type — エンドポイントから予測を取得するために使用されるモデル入力形式。指定した場合、API の ContentTypeパラメータに渡されます SageMaker InvokeEndpoint。

    • コンピューター ビジョンの説明可能性について、有効な値は、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 — エンドポイントから予測を取得するために使用されるモデル出力形式。の値は API の Acceptパラメータaccept_typeに渡されます SageMaker InvokeEndpoint。

    • コンピュータビジョンの説明可能性については、model_type が accept_type の場合、デフォルトは application/json です。

    • 時系列予測の説明可能性の場合、有効な値は ですapplication/json。

    • 他のタイプの説明可能性については、有効な値は text/csv、application/jsonlines、application/json です。accept_type の値が指定されていない場合、accept_type のデフォルトは content_type パラメータの値になります。

  • content_template — データセットレコードからモデル入力を構築するために使用されるテンプレート文字列。content_template パラメータは、content_type パラメータの値が application/jsonlines または application/json の場合にのみ使用され、必須となります。

    content_type パラメータが application/jsonlines の場合、テンプレートにはプレースホルダー $features のみを含める必要があります。これはランタイムに特徴量リストに置き換えられます。例えば、テンプレートが "{\"myfeatures\":$features}" で、レコードに 3 つの数値特徴量値 (1、2、3) がある場合、レコードは JSON Line {"myfeatures":[1,2,3]} としてモデルに送信されます。

    content_type が application/json の場合、テンプレートにはプレースホルダー $record または records を使用できます。プレースホルダーが record の場合、1 つのレコードは record_template のテンプレートが適用されたレコードに置き換えられます。この場合、一度に 1 つのレコードだけがモデルに送信されます。プレースホルダーが $records の場合、レコードはレコードのリストに置き換えられ、各レコードには record_template が提供するテンプレートが付けられます。

  • record_template — データセットインスタンスからモデル入力の各レコードを構築するために使用されるテンプレート文字列。これは content_type が application/json の場合にのみ使用され、必須となります。テンプレート文字列には、次のいずれかが含まれる場合があります。

    • 特徴量値の配列に置き換えられるプレースホルダー $features パラメータ。$feature_names の特徴量列ヘッダー名は、追加のオプションのプレースホルダーで置き換えることができます。このオプションのプレースホルダーは、特徴量名の配列に置き換えられます。

    • キーと値のペア、つまり特徴量名と特徴量値に置き換えられる 1 つのプレースホルダー $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 の 3 つの値がある場合、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 – (オプション) 時系列の説明可能性にのみ使用されます。で S3 URI として渡されたデータからデータを正しく解析する方法を SageMaker Clarify プロセッサに指示するために使用されますdataset_uri。

    • forecast – 予測結果の抽出に使用される JMESPath 式。

分析設定ファイルの例

以下のセクションには、CSV 形式、JSON Lines 形式、自然言語処理 (NLP)、コンピュータビジョン (CV)、時系列 (TS) の説明可能性に関するデータの分析設定ファイルの例が含まれています。

CSV データセットの分析設定

次の例は、CSV 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットには 4 つの特徴量列と 1 つの二項ラベル列、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
...

次のセクションでは、CSV 形式のデータセットの特徴量重要度を示すトレーニング前およびトレーニング後のバイアスメトリクス、SHAP 値、部分依存プロット (PDP) を計算する方法を示します。

トレーニング前のバイアスメトリクスをすべて計算する

この設定例は、前のサンプルデータセットが、Gender 値が 0 のサンプルに有利に偏っているかどうかを測定する方法を示しています。次の分析設定は、データセットのトレーニング前のバイアスメトリクスをすべて計算するように 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 形式で出力する二項分類モデルからのものです。この出力例では、各行に 2 つの列が含まれています。1 列目には予測ラベルが含まれ、2 列目にはそのラベルの確率値が含まれます。

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 値を計算する

以下の分析設定例では、Target 列をラベルと指定し、その他すべての列を特徴量と指定して、SHAP 値を計算するようにジョブに指示しています。

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

この例では、SHAP baseline パラメータは省略され、num_clusters パラメータの値は 1 です。これにより、1 つの SHAP ベースラインサンプルを計算するように SageMaker Clarify プロセッサに指示します。この例では、確率は 1 に設定されています。これにより、モデル出力の 2 列目から確率スコアを抽出するように SageMaker Clarify 処理ジョブに指示します (ゼロベースのインデックス作成を使用）。

部分依存プロット (PDP) を計算する

以下の例は、PDP を使用して分析レポート上の Income 特徴量の需要度を表示する方法を示しています。レポートパラメータは、 SageMaker Clarify 処理ジョブにレポートを生成するように指示します。ジョブが完了すると、生成されたレポートは report.pdf として analysis_result の場所に保存されます。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。次の例で指定されたパラメータは、X 軸に10セグメントIncomeを持つ の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。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
    },
}

バイアスメトリクスと特徴量重要度を両方とも計算する

前の設定例のすべてのメソッドを 1 つの分析設定ファイルにまとめ、それらをすべて 1 つのジョブで計算できます。以下の例は、すべてのステップを組み合わせた分析設定を示しています。

この例では、probability パラメーターが 1 に設定され、確率が 2 番目の列に含まれていることを示します (ゼロから始まるインデックスを使用)。ただし、バイアス分析には予測ラベルが必要なため、確率スコアをバイナリ ラベルに変換するように、probability_threshold パラメーターが 0.5 に設定されています。この例では、部分依存プロット pdp メソッドの top_k_features パラメータは 2 に設定されています。これにより、 SageMaker Clarify 処理ジョブは、グローバル PDPs) を計算するように指示されます。 2

{
    "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 Lines データセットの分析設定

次の例は、JSON Lines 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、 SageMaker JSON Lines の高密度形式です。各行は有効な JSON オブジェクトです。 "Features" キーは特徴量値の配列を指し、"Label" キーはグラウンドトゥルースラベルを指します。データセットは、「データセット」処理入力によって 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}
...

次のセクションでは、JSON Lines 形式のデータセットの特徴量重要度を示すトレーニング前およびトレーニング後のバイアスメトリクス、SHAP 値、部分依存プロット (PDP) を計算する方法を示します。

トレーニング前のバイアスメトリクスを計算する

Gender 値が 0 のトレーニング前のバイアスメトリクスを測定するためのラベル、特徴量、形式、メソッドを指定します。次の例では、headers パラメータは特徴量名を最初に指定します。ラベル名は最後に指定されます。慣例により、最後のヘッダーはラベルヘッダーです。

features パラメータは JMESPath 式「特徴」に設定され、 SageMaker Clarify 処理ジョブが各レコードから特徴の配列を抽出できるようにします。label パラメータは JMESPath 式「Label」に設定され、 SageMaker Clarify 処理ジョブが各レコードからグラウンドトゥルースラベルを抽出できるようにします。次のように、ファセット名を使用して機密属性を指定します。

{
    "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 Lines データを出力する二項分類モデルからのものです。モデル出力の各行は有効な JSON オブジェクトです。キー predicted_label は予測ラベルを指し、キー probability は確率値を指します。

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

モデルを という名前の SageMaker エンドポイントにデプロイできますyour_endpoint。次の分析設定の例では、データセットとモデルの両方について考えられるすべてのバイアスメトリクスを計算するように 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 分析にはグラウンドトゥルースラベルが必要ないため、label パラメータは省略されます。この例では、headers パラメータも省略されています。したがって、 SageMaker Clarify 処理ジョブは、特徴量ヘッダーcolumn_1には column_0や などの汎用名を使用し、ラベルヘッダー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 パラメータでは 0 から始まるインデックスを使用して特徴量列の位置を参照する必要があります。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。この例のパラメータは、X 軸に10セグメントIncomeがある の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。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"
    }
}

バイアスメトリクスと特徴量重要度を両方とも計算する

これまでのすべてのメソッドを 1 つの分析設定ファイルにまとめて、1 つのジョブですべてを計算できます。以下の例は、すべてのステップを組み合わせた分析設定を示しています。この例では、probability パラメータが設定されています。ただし、バイアス分析には予測ラベルが必要なため、probability_threshold パラメータは確率スコアをバイナリラベルに変換するように 0.5 に設定されています。この例では、pdp メソッドの top_k_features パラメータは 2 に設定されています。これにより、 SageMaker Clarify 処理ジョブは、グローバル PDPs を計算するように指示されます。 2

{
    "dataset_type": "application/jsonlines",
    "headers": ["Age","Gender","Income","Occupation","Target"],
    "label": "Label",
    "features": "Features",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

JSON データセットの分析設定

次の例は、JSON 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、 SageMaker JSON 高密度形式です。JSON 行の詳細については、「JSONLINES リクエスト形式」を参照してください。

入力リクエスト全体は有効な JSON で、外部構造はリストであり、各要素はレコードのデータです。各レコード内で、Features キーは特徴量値の配列を指し、Label キーはグラウンドトゥルースラベルを指します。データセットは、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},
    ...
]

次のセクションでは、JSON Lines 形式のデータセットの特徴量重要度を示すトレーニング前およびトレーニング後のバイアスメトリクス、SHAP 値、部分依存プロット (PDP) を計算する方法を示します。

トレーニング前のバイアスメトリクスを計算する

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 プレースホルダーが各レコードの特徴量配列に置き換えられます。

次の分析設定の例では、データセットとモデルの両方について考えられるすべてのバイアスメトリクスを計算するように 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_1には column_0や などの汎用名を使用し、ラベルヘッダー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 パラメータでは 0 から始まるインデックスを使用して特徴量列の位置を参照する必要があります。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。

次の例のパラメータは、X 軸に10セグメントIncomeを持つ の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。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"
    }
}

バイアスメトリクスと特徴量重要度を両方とも計算する

これまでのすべてのメソッドを 1 つの分析設定ファイルにまとめて、1 つのジョブですべてを計算できます。以下の例は、すべてのステップを組み合わせた分析設定を示しています。

この例では、probability パラメータが設定されています。バイアス分析には予測ラベルが必要なため、probability_threshold パラメータは 0.5 に設定され、確率スコアを二項ラベルに変換するために使用されます。この例では、pdp メソッドの top_k_features パラメータは 2 に設定されています。これにより、 SageMaker Clarify 処理ジョブは、グローバル PDPs を計算するように指示されます。 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 形式の表形式データセットで、次のように 1 つの二項ラベル列と 2 つの特徴量列があります。データセットは、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 の間の 1 つのスコアを出力します。

0.491656005382537
0.569582343101501
...

モデルは、「your_model」という名前の SageMaker モデルを作成するために使用されます。以下の分析設定は、モデルとデータセットを使用してトークン単位の説明可能性分析を実行する方法を示しています。text_config パラメータは NLP 説明可能性分析を有効にします。granularity パラメータは、分析がトークンを解析する必要があることを示します。

英語では、各トークンは単語です。次の例は、平均 "Rating" を 4 にしてインプレイスの 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 形式の時系列データセットです。データセットは、データセット処理入力パラメータ によって SageMaker Clarify ジョブに提供されますdataset_uri。

[
    {
        "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
    },
]

以下のセクションでは、JSON データセットの非対称 Shapley 値アルゴリズムを使用して予測モデルの特徴量属性を計算する方法について説明します。

時系列予測モデルの説明を計算する

次の分析設定の例では、時系列予測モデルの説明を計算するためにジョブで使用されるオプションを表示します。

{
    '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で を使用して、ベースライン、方向、粒度、サンプル数などの時系列の説明可能性引数を定義します。ベースライン値は、関連する時系列、静的共変数、ターゲット時系列の 3 種類のデータすべてに設定されます。これらのフィールドは、一度に 1 つの項目の特徴量属性を計算するように SageMaker Clarify プロセッサに指示します。

予測子の設定

SageMaker Clarify プロセッサが JMESPath 構文を使用して送信するペイロード構造を完全に制御できます。前の例では、 predictor 設定はレコードを に集約するように Clarify '{"instances": $records}' に指示します。各レコードは、この例record_templateで に指定された引数で定義されます。$start_time、$target_time_series、、 $static_covariatesは$related_time_series、データセット値をエンドポイントリクエスト値にマッピングするために使用される内部トークンであることに注意してください。

同様に、 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 属性を使用して、 で S3 URI として渡されたデータからデータを正しく解析するように SageMaker Clarify プロセッサに指示しますdataset_uri。