分析設定ファイル - Amazon SageMaker
分析設定ファイルのスキーマ分析設定ファイルの例

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

分析設定ファイル

SageMaker Clarify を使用してデータやモデルの説明可能性やバイアスを分析するには、処理ジョブを設定する必要があります。この処理ジョブの設定の一部には、分析ファイルの設定が含まれます。分析ファイルは、バイアス分析と説明可能性のパラメータを指定します。処理ジョブと分析ファイルを設定する方法については、 SageMaker Clarify 処理ジョブを設定する「」を参照してください。

このガイドでは、この分析設定ファイルのスキーマとパラメータについて説明します。このガイドには、表形式のデータセットのバイアスメトリクスを計算し、自然言語処理 (NLP）、コンピュータビジョン (CV)、時系列 (TS) の問題の説明を生成するための分析設定ファイルの例も含まれています。

分析設定ファイルを作成するか、SageMaker Python SDK を使用して SageMaker ClarifyProcessor で生成できますAPI。ファイルの内容を表示すると、 SageMaker Clarify ジョブで使用される基盤となる設定を理解するのに役立ちます。

分析設定ファイルのスキーマ

以下のセクションでは、要件とパラメータの説明を含む分析設定ファイルのスキーマについて説明します。

分析設定ファイルの要件

SageMaker Clarify 処理ジョブでは、分析設定ファイルが以下の要件で構造化されることが期待されます。

  • 処理入力名は analysis_config. でなければならない。

  • 分析設定ファイルは JSON形式で、UTF-8 でエンコードされます。

  • 分析設定ファイルは、Amazon S3 オブジェクトである。

分析設定ファイルには追加のパラメータを指定できます。次のセクションでは、ユースケースと必要な分析タイプに合わせて SageMaker Clarify 処理ジョブを調整するためのさまざまなオプションを提供します。

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、 はデータセットからグラウンドトゥルースラベルを抽出するために記述されたJMESPath式labelである必要があります。慣例により、headers を指定する場合はラベル名を含める必要があります。

    • dataset_type が の場合application/json、 はデータセット内の各レコードのグラウンドトゥルースラベルを抽出するように記述されたJMESPath式labelである必要があります。このJMESPath式は、ith ラベルが ith レコードと相関するラベルのリストを生成する必要があります。

  • 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、 はデータセットから予測ラベルを抽出するために記述された有効なJMESPath式predicted_labelである必要があります。慣例により、headers を指定する場合は予測ラベル名を含める必要があります。

    • dataset_type が の場合application/json、 はデータセット内の各レコードの予測ラベルを抽出するために記述されたJMESPath式predicted_labelである必要があります。JMESPath 式は、ith 予測ラベルが ith レコード用である予測ラベルのリストを生成する必要があります。

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

  • predicted_label_dataset_uri – (オプション) dataset_type が の場合のみ該当しますtext/csv。トレーニング後のバイアスメトリクスの計算に使用される予測ラベルを含むデータセットURIの S3。 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。バイアス分析URIの機密属性を含むデータセットの S3。機密属性を使用せずにモデルをトレーニングした場合でも、ファセットを使用してデータセットとモデルのバイアス特性を理解できます。

    注記

    ファセットデータセットまたはメインデータセットが複数のファイルに分割されている場合は、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 — トレーニング前のバイアスメトリクスを計算する場合は、このメソッドを含めます。メトリクスの詳細については、「」を参照してくださいトレーニング前のバイアスメトリクス。オブジェクトには以下のパラメータがあります。

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

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

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

        • 表形式のデータセットの場合、 はインプレースベースラインデータまたはURIベースラインファイルの S3 のいずれかbaselineになります。が指定され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 データセットの構造と形式は入力データセットと同じである必要があります。

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

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

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

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

      • seed – (オプション) 同じジョブに対して一貫したSHAP値を生成するためにSHAP、説明子で擬似乱数ジェネレーターを初期化するために使用される整数。シードが指定されていない場合、同じジョブが実行されるたびに、モデルはわずかに異なる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、「」を参照してください。 部分依存プロットの計算 (PDPs）

      • 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 – によって作成された SageMaker モデルの名前CreateModelAPI。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 を指定する場合は必須です。の値はジョブInstanceCountの とは異なるinitial_instance_count場合がありますが、1:1 の比率を推奨します。

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

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

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

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

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

      • コンピューター ビジョンの説明可能性について、有効な値は、image/jpeg、image/png、または application/x-npy です。content_type を指定しない場合、デフォルト値は image/jpeg です。

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

      • 他のタイプの説明可能性については、有効な値は text/csv、application/jsonlines,、application/json です。dataset_type が の場合、 の値content_typeが必要ですapplication/x-parquet。それ以外の場合は、content_type はデフォルトで dataset_type パラメータの値になります。

    • accept_type — エンドポイントから予測を取得するために使用されるモデル出力形式。の値は、 の Acceptパラメータaccept_typeに渡されます SageMaker InvokeEndpointAPI。

      • コンピュータビジョンの説明可能性のために、 model_typeがOBJECT「_DETECTION」の場合、accept_typeデフォルトは になりますapplication/json。

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

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

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

      content_type パラメータが application/jsonlines の場合、テンプレートにはプレースホルダー $features のみを含める必要があります。これはランタイムに特徴量リストに置き換えられます。例えば、テンプレートが で"{\"myfeatures\":$features}"、レコードに 12と の 3 つの数値特徴量値がある場合3、レコードはモデルにJSON行 として送信されます{"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または ) の場合、 はモデル出力から確率 (スコア) を抽出するために使用されるJMESPath式application/jsonprobabilityである必要があります。

    • time_series_predictor_config – (オプション) 時系列の説明可能性にのみ使用されます。で S3 として渡されたデータからデータを正しく解析する方法を SageMaker Clarify プロセッサURIに指示するために使用されますdataset_uri。

      • forecast – 予測結果を抽出するために使用されるJMESPath式。

分析設定ファイルの例

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

次の例は、表形式データセットのバイアス分析と説明可能性分析を 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
...

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

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

この設定例は、前のサンプルデータセットが、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
    }
}

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

部分依存プロットの計算 (PDPs）

次の例は、 を使用して分析レポートでIncome特徴量の重要性を表示する方法を示していますPDPs。レポートパラメータは、 SageMaker Clarify 処理ジョブにレポートを生成するように指示します。ジョブが完了すると、生成されたレポートは report.pdf として analysis_result の場所に保存されます。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。次の例で指定されたパラメータは、 SageMaker Clarify 処理ジョブに、x 軸に10セグメントIncomeを持つ のPDPグラフを含むレポートを生成するように指示します。Y 軸には、予測に対する Income のわずかな影響が示されます。

{
    "dataset_type": "text/csv",
    "label": "Target",
    "methods": {
        "pdp": {
            "features": ["Income"],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    },
}

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

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

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

{
    "dataset_type": "text/csv",
    "label": "Target",
    "probability_threshold": 0.5,
    "label_values_or_threshold": [1],
    "facet": [
        {
            "name_or_index": "Gender",
            "value_or_threshold": [0]
        }
    ],
    "methods": {
        "pre_training_bias": {
            "methods": "all"
        },
        "post_training_bias": {
            "methods": "all"
        },
        "shap": {
            "num_clusters": 1
        },
        "pdp": {
            "top_k_features": 2,
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "probability": 1
    }
}

モデルをエンドポイントにデプロイする代わりに、 model_nameパラメータを使用して SageMaker モデルの名前を SageMaker Clarify 処理ジョブに提供できます。次の例は、your_model という名前のモデルを指定する方法を示しています。 SageMaker Clarify 処理ジョブは、設定を使用してシャドウエンドポイントを作成します。

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

次の例は、表形式のデータセットのバイアス分析と説明可能性分析を 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}
...

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

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

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

features パラメータは、 SageMaker Clarify 処理ジョブが各レコードから特徴量の配列を抽出できるように、JMESPath式「特徴」に設定されます。label パラメータは、 SageMaker Clarify 処理ジョブが各レコードからグラウンドトゥルースラベルを抽出できるように、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 エンドポイントにデプロイできます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"
    }
}

部分依存プロットの計算 (PDPs）

次の例は、 で「Income」の重要性を表示する方法を示していますPDP。この例では、特徴量ヘッダーは提供されていません。そのため、pdp メソッドの features パラメータでは 0 から始まるインデックスを使用して特徴量列の位置を参照する必要があります。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。この例のパラメータは、 SageMaker Clarify 処理ジョブに、x 軸に10セグメントIncomeを持つ のPDPグラフを含むレポートを生成するように指示します。Y 軸には、予測に対する Income のわずかな影響が示されます。

{
    "dataset_type": "application/jsonlines",
    "features": "Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "{\"Features\":$features}",
        "probability": "probability"
    }
}

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

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

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

次の例は、表形式データセットのバイアス分析と説明可能性分析を JSON 形式で設定する方法を示しています。これらの例では、受信データセットには前のセクションと同じデータがありますが、 SageMaker JSON高密度形式です。JSON Lines の詳細については、「」を参照してください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},
    ...
]

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

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

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

部分依存プロットの計算 (PDPs）

次の例は、 で特徴量の重要度を表示する方法を示していますPDPs。この例では、特徴量ヘッダーは指定されていません。そのため、pdp メソッドの features パラメータでは 0 から始まるインデックスを使用して特徴量列の位置を参照する必要があります。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。

次の例のパラメータは、 SageMaker Clarify 処理ジョブに、x 軸に10セグメントIncomeを持つ のPDPグラフを含むレポートを生成するように指示します。Y 軸では、予測に対する Income のわずかな影響が示されます。

次の設定例は、 Incomeで の重要性を表示する方法を示していますPDPs。

{
    "dataset_type": "application/json",
    "features": "[*].Features",
    "methods": {
        "pdp": {
            "features": [2],
            "grid_resolution": 10
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "endpoint_name": "your_endpoint",
        "content_template": "$records",
        "record_template": "{\"Features\":$features}",
        "probability": "predictions[*].probability"
    }
}

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

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

この例では、probability パラメータが設定されています。バイアス分析には予測ラベルが必要なため、probability_threshold パラメータは 0.5 に設定され、確率スコアを二項ラベルに変換するために使用されます。この例では、pdp メソッドの top_k_features パラメータは 2 に設定されています。これにより、 SageMaker Clarify 処理ジョブは、グローバルSHAP値が最も大きい上位2特徴量PDPsに対して を計算するように指示されます。

{
    "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）。この例では、受信データセットは、次のように 1 つのバイナリラベル列と 2 つの特徴量列を持つCSV形式の表形式データセットです。データセットは、dataset処理入力パラメータによって SageMaker Clarify ジョブに提供されます。

0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...

この例では、前のデータセットでバイナリ二項分類モデルをトレーニングしました。モデルはCSVデータを受け入れ、次のように 0と の間の単一のスコアを出力1します。

0.491656005382537
0.569582343101501
...

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

英語では、各トークンは単語です。次の例は、平均SHAP「評価」を 4 として使用して、インプレース「ベースライン」インスタンスを提供する方法も示しています。特別なマスクトークン「〔MASK〕」は、「コメント」のトークン (単語) を置き換えるために使用されます。この例では、GPUエンドポイントインスタンスタイプを使用して推論を高速化します。

{
    "dataset_type": "text/csv",
    "headers": ["Target","Rating","Comments"]
    "label": "Target",
    "methods": {
        "shap": {
            "text_config": {
                "granularity": "token",
                "language": "english"
            }
            "baseline": [[4,"[MASK]"]],
        }
    },
    "predictor": {
        "model_name": "your_nlp_model",
        "initial_instance_count": 1,
        "instance_type": "ml.g4dn.xlarge"
    }
}

次の例は、コンピュータービジョンの特徴量重要度を計算する分析設定ファイルを示しています。この例では、入力データセットはJPEGイメージで構成されます。データセットは、dataset処理入力パラメータによって SageMaker Clarify ジョブに提供されます。この例では、 SageMaker 画像分類モデルを使用して説明可能性分析を設定する方法を示しています。この例では、 という名前のモデルがyour_cv_ic_model、入力JPEGイメージ上の動物を分類するようにトレーニングされています。

{
    "dataset_type": "application/x-image",
    "methods": {
        "shap": {
             "image_config": {
                "model_type": "IMAGE_CLASSIFICATION",
                 "num_segments": 20,
                "segment_compactness": 10
             }
        },
        "report": {
            "name": "report"
        }
    },
    "predictor": {
        "model_name": "your_cv_ic_model",
        "initial_instance_count": 1,
        "instance_type": "ml.p2.xlarge",
        "label_headers": ["bird","cat","dog"]
    }
}

イメージ分類の詳細については、「」を参照してください画像分類 - MXNet。

この例では、SageMaker オブジェクト検出モデル your_cv_od_modelは、同じJPEGイメージでトレーニングされ、その上の動物を識別します。次の例は、オブジェクト検出モデルの説明可能性分析を設定する方法を示しています。

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

次の例は、時系列 (TS) の機能重要度を計算するための分析設定ファイルを示しています。この例では、受信データセットは、動的および静的な共変量特徴量のセットを含むJSON形式の時系列データセットです。データセットは、データセット処理入力パラメータ によって 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 つのタイプのデータすべてに設定されます。これらのフィールドは、 SageMaker Clarify プロセッサに、一度に 1 つの項目の特徴量属性を計算するように指示します。

予測子の設定

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

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

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

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

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

予測値は次のように解析されます。

[
    [13.4, 3.6],
    [23.0, 4.7],
    [3.4, 5.6]
]
データ設定

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