分析設定ファイル

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 処理ジョブをユースケースや必要な分析の種類に合わせて調整するためのさまざまなオプションを提示します。

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

version — (オプション) 分析設定ファイルスキーマのバージョン文字列。バージョンが指定されていない場合、SageMaker Clarify はサポートされている最新のバージョンを使用します。現在サポートされているバージョンは 1.0 のみです。
dataset_type — データセットの形式。入力データセット形式は、次のいずれかの値になります。
- 表形式
  - CSV の場合 text/csv
  - application/jsonlines SageMaker AI 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 AI は入力データセットを簡単に操作および分析できます。
ヘッダー – (オプション)
- 表形式: 表形式のデータセットの列名を含む文字列の配列。headers の値が指定されていない場合、SageMaker Clarify 処理ジョブはデータセットからヘッダーを読み取ります。データセットにヘッダーがない場合、Clarify 処理ジョブは 0 から始まる列インデックスに基づいてプレースホルダー名を自動的に生成します。例えば、1 列目と 2 列目のプレースホルダー名は column_0 と column_1 になります。
  注記
  原則として、dataset_type が application/jsonlines または application/json の場合、headers には次の名前が順番に含まれている必要があります。
  特徴量名
  ラベル名 (label が指定されている場合)
  予測ラベル名 (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 または 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 – (オプション) 内部結合を実行する際に識別子列として使用される表形式データセット内の列の名前または 0 から始まるインデックス。この列は識別子としてのみ使用されます。バイアス分析や特徴量属性分析などの他の計算には使用されません。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 の用語解説」の「positive label values」を参照してください。ラベルが数値の場合、しきい値は肯定的な結果を選択するための下限として適用されます。さまざまな問題タイプの 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 の用語解説」の「Facet」を参照してください。各ファセットオブジェクトには次のフィールドが含まれます。
- name_or_index – (オプション) 表形式データセット内の機密属性列の名前または 0 から始まるインデックス。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 – 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内の項目 ID を検索するために使用されます。
- timestamp – 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内のタイムスタンプを検索するために使用されます。
- dataset_format – 使用できる値は、columns、item_records、または timestamp_records です。このフィールドは、時系列の説明可能性のためにサポートされている唯一の形式である JSON データセットの形式を記述するために使用されます。
- target_time_series – JMESPath 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内のターゲット時系列を検索するために使用されます。このパラメータが文字列の場合、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 つのベースラインインスタンスの計算に使用されます。baseline が指定されていない場合、SageMaker Clarify 処理ジョブは、表形式データセットを 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 – このメソッドを Partial Dependence Plot (PDP) の計算に含めます。PDP を生成するための分析構成の例については、「部分依存プロット (PDP) を計算する」を参照してください。
  - features — shap メソッドが要求されていない場合は必須です。PDP プロットを計算してプロットするための特徴量名またはインデックスの配列。
  - top_k_features — (オプション) PDP プロットの生成に使用される上位の特徴量数を指定します。featuresが指定されていないが shap メソッドが要求されている場合、SageMaker Clarify 処理ジョブはその SHAP 属性に基づいて上位の特徴量を選択します。デフォルトは 10 です。
  - grid_resolution — 数値の範囲を分割するバケットの数です。これは、PDP プロットのグリッドの粒度を指定します。
- asymmetric_shapley_value – 時系列予測モデルの説明可能性メトリクスを計算する場合は、このメソッドを含めます。SageMaker Clarify 処理ジョブは、非対称 Shapley 値アルゴリズムをサポートしています。非対称 Shapley 値は、対称公理を省略した Shapley 値のバリアントです。詳細については、「Asymmetric Shapley values: incorporating causal knowledge into model-agnostic explainability」を参照してください。これらの値を使用して、特徴量が予測結果にどのように貢献するかを判断します。非対称 Shapley 値は、予測モデルが入力として取る時系列データの一時的な依存関係を考慮します。
  
  このアルゴリズムには、以下のパラメータが含まれます。
  - direction – 使用可能なタイプは、chronological、anti_chronological、bidirectional です。時間構造は、時系列順、反時系列順、またはその両方でナビゲートできます。時系列の説明は、最初の時間ステップから情報を反復的に追加することによって構築されます。反時系列の説明は、最後のステップから開始して後方に移動しながら情報を追加します。株価の予測など、最新性バイアスが存在する場合は、後者の順序を使用する方が適切である可能性があります。
  - granularity – 使用する説明の粒度。使用可能な粒度オプションは、以下のとおりです。
    
    timewise – timewise の説明は低コストであり、特定の時間ステップに関する情報のみを提供します。過去の n 日目の情報が将来の m 日目の予測にどの程度貢献したかを把握します。結果として得られる属性は、静的共変量を個別には説明することなく、ターゲットと関連する時系列は区別されません。結果として得られる貢献度は、静的共変量を個別に説明することはなく、ターゲットと関連する時系列は区別されません。
    fine_grained – fine_grained の説明は計算集約的である一方、入力変数のすべての貢献度の完全な詳細を提供しますこのメソッドでは、実行時間の短縮のために近似説明を計算します。詳細については、以下の「num_samples パラメータ」を参照してください。
    
    注記
    fine_grained の説明でサポートされるのは、chronological の順序のみです。
  - num_samples – (オプション) この引数は fine_grained の説明の場合は必須です。数値が高いほど、近似の精度が高くなります。この数値は、入力特徴量のディメンションに応じてスケールする必要があります。経験則としては、結果が大きすぎない場合は、この変数を (1 + max (関連する時系列の数、静的共変量の数))^2 に設定します。
  - baseline – (オプション) 対応するデータセット (バックグラウンドデータとも呼ばれます) の非提携値を置き換えるベースライン設定。次のコードスニペットは、ベースライン設定の例を説明しています。
    
    { "related_time_series": "zero", "static_covariates": { <item_id_1>: [0, 2], <item_id_2>: [-1, 1] }, "target_time_series": "zero" }
    
    ターゲット時系列や関連する時系列などの時間データの場合、ベースライン値タイプは次のいずれかの値になります。
    
    zero - 非提携値はすべて 0.0 に置き換えられます。
    mean - 非提携値はすべて時系列の平均に置き換えられます。
    静的共変量の場合、モデル要求が静的共変量値を取る場合にのみベースラインエントリを指定する必要があります。この場合、このフィールドは必須です。ベースラインは、すべての項目をリストとして指定する必要があります。例えば、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 AI Analysis Report です。
predictor — 分析でモデルからの予測が必要な場合に必須です。例えば、shap メソッド、asymmetric_shapley_value メソッド、pdp メソッド、または post_training_bias メソッドが求められているのに、予測ラベルが入力データセットの一部として提供されていない場合などです。predictor と組み合わせて使用するパラメータは次のとおりです。
- model_name – CreateModel API によって作成された SageMaker AI モデルの名前。endpoint_name の代わりに model_name を指定すると、SageMaker Clarify 処理ジョブは、シャドウエンドポイントと呼ばれるモデル名のエフェメラルエンドポイントを作成し、エンドポイントから予測を取得します。ジョブは、計算が完了した後にシャドウエンドポイントを削除します。モデルがマルチモデルの場合は、target_model パラメータを指定する必要があります。マルチモデルエンドポイントの詳細については、「マルチモデルエンドポイント」を参照してください。
- endpoint_name_prefix — (オプション) シャドウエンドポイントのカスタム名プレフィックス。endpoint_name の代わりに model_name を指定した場合に適用されます。例えば、エンドポイントへのアクセスをエンドポイント名で制限する場合は endpoint_name_prefix を指定します。プレフィックスは EndpointName パターンと一致する必要があり、最大長は 23 です。デフォルトは sm-clarify です。
- initial_instance_count - シャドウエンドポイントのインスタンス数を指定します。endpoint_name の代わりに model_name を指定する場合は必須です。initial_instance_count の値はジョブの InstanceCount と異なる場合がありますが、比率は 1:1 にすることをお勧めします。
- instance_type-シャドウエンドポイントのインスタンスタイプを指定します。endpoint_name の代わりに model_name を指定する場合は必須です。例えば、instance_type を "ml.m5.large" に設定できます。場合によっては、instance_type に指定した値がモデル推論時間の短縮に役立つことがあります。例えば、自然言語処理モデルとコンピュータービジョンモデルを効率的に実行するには、通常、グラフィックス処理装置 (GPU) インスタンスタイプが必要です。
- endpoint_name – CreateEndpoint API によって作成された SageMaker AI エンドポイントの名前。指定した場合、endpoint_name が model_name パラメータよりも優先されます。既存のエンドポイントを使用するとシャドウエンドポイントのブートストラップ時間が短縮されますが、そのエンドポイントの負荷が大幅に増加する可能性もあります。また、分析メソッド (shap やなど pdp) によっては、エンドポイントに送信される合成データセットを生成します。これにより、エンドポイントのメトリクスやキャプチャされたデータが、実際の使用状況を正確に反映していない合成データによって汚染される可能性があります。これらの理由から、SageMaker Clarify の分析に既存の本番用エンドポイントを使用することは一般的に推奨されません。
- target_model – SageMaker AI InvokeEndpoint API の TargetModel パラメータに渡される文字列値。モデル (model_name パラメータで指定) またはエンドポイント (endpoint_name パラメータで指定) が multi-model の場合に必要です。マルチモデルエンドポイントの詳細については、「マルチモデルエンドポイント」を参照してください。
- custom_attributes — (オプション) エンドポイントに送信される推論リクエストに関する追加情報を提供できる文字列。文字列値は、SageMaker AI InvokeEndpoint API の CustomAttributesパラメータに渡されます。
- content_type — content_type — エンドポイントから予測を取得するために使用されるモデル入力形式。指定した場合、SageMaker AI InvokeEndpoint API の ContentTypeパラメータに渡されます。
  - コンピュータービジョンの説明可能性について、有効な値は、image/jpeg、image/png、または application/x-npy です。content_type を指定しない場合、デフォルト値は image/jpeg です。
  - 時系列予測の説明可能性の場合、有効な値は application/json です。
  - 他のタイプの説明可能性については、有効な値は text/csv、application/jsonlines,、application/json です。dataset_type が application/x-parquet の場合、content_type の値が必要です。それ以外の場合は、content_type はデフォルトで dataset_type パラメータの値になります。
- accept_type — エンドポイントから予測を取得するために使用されるモデル出力形式。の値は、SageMaker AI InvokeEndpoint API の Acceptパラメータaccept_typeに渡されます。
  - コンピュータビジョンの説明可能性については、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 – (オプション) バイアス分析向けにモデル出力から予測ラベルを抽出するために使用される 0 から始まる整数インデックスまたは 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"] に設定する必要があります。
- probability – (オプション) 説明可能性分析 (時系列説明可能性以外) の確率 (スコア) を抽出するため、またはバイアス分析の予測ラベルを選択するために使用される、 0 から始まる整数インデックスまたは JMESPath 式文字列。probability の値は、次のように accept_type パラメータの値によって異なります。
  - accept_type が text/csv の場合、probability はモデル出力の確率 (スコア) のインデックスです。probability が指定されていない場合、モデル出力全体が確率 (スコア) とみなされます。
  - accept_type が JSON データ (application/jsonlines または application/json のいずれか) の場合、probability はモデル出力から確率 (スコア) を抽出するために使用される JMESPath 式でなければなりません。
- time_series_predictor_config – (オプション) 時系列の説明可能性にのみで使用します。dataset_uri で S3 URI として渡されたデータからデータを適切に解析する方法を SageMaker Clarify プロセッサに指示するために使用されます。
  - forecast – 予測結果を抽出するために使用される JMESPath 式

分析設定ファイルの例

次のセクションでは、CSV 形式と JSON 行形式のデータや、自然言語処理 (NLP) とコンピュータビジョン (CV) の説明可能性の両方の分析設定ファイルの例を説明します。

次の例は、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 AI エンドポイントにデプロイされます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 です。これにより、SageMaker Clarify プロセッサが 1 つの SHAP ベースラインサンプルを計算するように指示されます。この例では、確率は 1 に設定されています。これにより、SageMaker Clarify 処理ジョブは、モデル出力の 2 列目から確率スコアを (ゼロから始まるインデックス化を使用して) 抽出するように指示されます。

部分依存プロット (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 処理ジョブは、グローバル 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 AI モデルの名前を指定できます。次の例は、your_model という名前のモデルを指定する方法を示しています。SageMaker Clarify 処理ジョブは、設定を使用してシャドウエンドポイントを作成します。


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

次の例は、JSON Lines 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、SageMaker AI JSON Lines の高密度形式です。各行は有効な JSON オブジェクトです。 "Features" キーは特徴量値の配列を指し、"Label" キーはグラウンドトゥルースラベルを指します。データセットは "dataset" 処理入力によって SageMaker Clarify ジョブに提供されます。JSON 行の詳細については、「JSONLINES リクエストの形式」を参照してください。


{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...

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

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

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

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


{
    "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 AI エンドポイントにデプロイできます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_0 や column_1、ラベルヘッダーに label0 などの一般的な名前を使用してプレースホルダーを生成する必要があります。headers と label の値を指定すると分析結果が読みやすくなります。確率パラメータは JMESPath 式 probability に設定されているため、確率値はモデル出力から抽出されます。以下は、SHAP 値を計算する例です。


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

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

次の例は、PDP で "Income" の需要度を表示する方法を示しています。この例では、特徴量ヘッダーは提供されていません。そのため、pdp メソッドの features パラメータでは 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 処理ジョブは、グローバル 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 AI 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},
    ...
]

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

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 AI エンドポイントにデプロイできます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_0 や column_1、column_1、ラベルヘッダーには label0 などの一般的な名前を使用してプレースホルダーを生成します。headers と label の値を指定すると分析結果が読みやすくなります。

次の設定例では、各レコードの各予測から確率を抽出する JMESPath 式に確率パラメータを設定しています。以下は、SHAP 値を計算する例です。


{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "shap": {
            "num_clusters": 1
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

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

次の例は、PDP で特徴量重要度を表示する方法を示しています。この例では、特徴量ヘッダーは指定されていません。そのため、pdp メソッドの features パラメータでは 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 処理ジョブは、グローバル 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 形式の表形式データセットで、次のように 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 AI モデルを作成するために使用されます。以下の分析設定は、モデルとデータセットを使用してトークン単位の説明可能性分析を実行する方法を示しています。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 AI イメージ分類モデルを使用して説明可能性分析を設定する方法を示します。この例では、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 AI オブジェクト検出モデルは、同じ JPEG イメージでyour_cv_od_modelトレーニングされ、動物を識別します。次の例は、オブジェクト検出モデルの説明可能性分析を設定する方法を示しています。


{
    "dataset_type": "application/x-image",
    "probability_threshold": 0.5,
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "OBJECT_DETECTION",
                 "max_objects": 3,
                "context": 1.0,
                "iou_threshold": 0.5,
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_od_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

次の例は、時系列 (TS) の特徴量の重要度を計算するための分析構成ファイルを説明しています。この例の受信データセットは、動的および静的な共変量特徴量のセットを含む JSON 形式の時系列データセットです。このデータセットは、処理入力パラメータ dataset_uri が SageMaker Clarify ジョブに提供します。


[
    {
        "item_id": "item1",
        "timestamp": "2019-09-11",
        "target_value": 47650.3,
        "dynamic_feature_1": 0.4576,
        "dynamic_feature_2": 0.2164,
        "dynamic_feature_3": 0.1906,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item1",
        "timestamp": "2019-09-12",
        "target_value": 47380.3,
        "dynamic_feature_1": 0.4839,
        "dynamic_feature_2": 0.2274,
        "dynamic_feature_3": 0.1889,
        "static_feature_1": 3,
        "static_feature_2": 4
    },
    {
        "item_id": "item2",
        "timestamp": "2020-04-23",
        "target_value": 35601.4,
        "dynamic_feature_1": 0.5264,
        "dynamic_feature_2": 0.3838,
        "dynamic_feature_3": 0.4604,
        "static_feature_1": 1,
        "static_feature_2": 2
    },
]

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

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

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


{
    '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 つのタイプのデータすべてについて設定されます。このようなフィールドは、SageMaker Clarify プロセッサに、一度に 1 つの項目の Feature Attribution を計算するように指示します。

予測子の設定

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

同様に、time_series_predictor_config の貢献度 forecast は、エンドポイント応答からモデル予測を抽出するために使用されます。例えば、エンドポイントのバッチ応答は次のようになります。


{
    "predictions": [
        {"mean": [13.4, 3.6, 1.0]}, 
        {"mean": [23.0, 4.7, 3.0]}, 
        {"mean": [3.4, 5.6, 2.0]}
    ]
}

次の時系列予測子設定を指定するとします。


'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}

予測値は次のとおり解析されます。


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

データの設定

time_series_data_config 属性を使用して、dataset_uri で S3 URI として渡されたデータからデータを適切に解析するように SageMaker Clarify プロセッサに指示します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

SageMaker Clarify コンテナ

データ形式互換性ガイド