分析を設定する - Amazon SageMaker

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

分析を設定する

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

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

分析設定ファイルを作成するか、SageMaker Python SDK を使用して SageMaker ClarifyProcessorAPI を使用して生成できます。ファイルの内容を確認すると、 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/jsonlinesSageMaker JSON の場合:行/高密度フォーマット

    • JSON の場合 application/json

    • Apache Parquet の場合 application/x-parquet

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

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

  • headers — (オプション) 表形式データセットの列名を含む文字列の配列。の値が指定されていない場合、 SageMaker Clarify headers 処理ジョブはデータセットからヘッダーを読み取ります。データセットにヘッダーがない場合、 SageMaker Clarify 処理ジョブは 0 から始まる列インデックスに基づいてプレースホルダー名を自動的に生成します。例えば、1 列目と 2 列目のプレースホルダー名は column_0column_1 になります。

    注記

    慣例により、dataset_type が application/jsonlines または application/json の場合、ヘッダーには特徴量名、ラベル名 (label が指定されている場合)、予測ラベル名 (predicted_label が指定されている場合) の名前が順番に含まれている必要があります。label が指定されている場合の application/jsonlines データセットタイプの headers の例は、["feature1","feature2","feature3","target_label"] です。

  • label — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、label はグラウンドトゥルースラベル (表形式データセットでは観測ラベルまたはターゲット属性とも呼ばれる) の位置を特定するために使用されます。グラウンドトゥルースラベルはバイアスメトリックの計算に使用されます。label の値は、dataset_type パラメータの値に応じて次のように指定されます。

    • dataset_typetext/csv の場合、label は次のいずれかに指定できます。

      • 有効な列名

      • データセット列の範囲内にあるインデックス。

    • dataset_typeapplication/parquet の場合、label は有効な列名でなければなりません。

    • dataset_typeapplication/jsonlines の場合、label はデータセットからグラウンドトゥルースラベルを抽出するように記述された JMESPath 式でなければなりません。慣例により、headers を指定する場合はラベル名を含める必要があります。

    • dataset_typeapplication/json の場合、label はデータセットの各レコードのからグラウンドトゥルースラベルを抽出するように記述された JMESPath 式でなければなりません。この JMESPath 式は、i 番目のラベルが i 番目のレコードに相関するラベルのリストを生成する必要があります。

  • predicted_label — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、predicted_label は表形式データセット内の予測ラベルを含む列を検索するために使用されます。予測ラベルはトレーニング後のバイアスメトリクスの計算に使用されます。データセットに予測ラベルが含まれていない場合、predicted_label パラメータはオプションです。計算に予測ラベルが必要な場合、 SageMaker Clarify 処理ジョブはモデルから予測を取得します。

    predicted_label の値は、dataset_type の値に応じて次のように指定されます。

    • dataset_typetext/csv の場合、predicted_label は次のいずれかに指定できます。

      • 有効な列名 predicted_label_dataset_uri が指定されていても predicted_label が指定されていない場合、デフォルトの予測ラベル名は "predicted_label" になります。

      • データセット列の範囲内にあるインデックス。predicted_label_dataset_uri が指定されている場合、インデックスは予測ラベルデータセット内の予測ラベル列を見つけるために使用されます。

    • dataset_type が application/x-parquet の場合、predicted_label は有効な列名でなければなりません。

    • dataset_type が application/jsonlines の場合、predicted_label はデータセットから予測ラベルを抽出するように記述された有効な JMESPath 式でなければなりません。慣例により、headers を指定する場合は予測ラベル名を含める必要があります。

    • dataset_typeapplication/json の場合、predicted_label はデータセットの各レコードのから予測ラベルを抽出するように記述された JMESPath 式でなければなりません。JMESPath 式は、i 番目の予測ラベルが i 番目のレコードに対する予測ラベルのリストを生成する必要があります。

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

  • predicted_label_dataset_uri — データセットタイプが text/csv の場合にのみ適用されます。トレーニング後のバイアスメトリクスの計算に使用される予測ラベルを含むデータセットの S3 URI。 SageMaker Clarify 処理ジョブは、モデルから予測を取得する代わりに、指定された URI から予測を読み込みます。この場合、predicted_label は予測ラベルデータセット内の予測ラベル列を見つける必要があります。予測ラベルデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を joinsource_name_or_index によって指定する必要があります。

  • predicted_label_headerspredicted_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 偏見と公平性に関する条件を明確化ラベルが数値の場合、しきい値は肯定的な結果を選択するための下限として適用されます。さまざまな問題タイプの label_values_or_threshold を設定するには、以下の例を参照してください。

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

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

    • リグレッション問題では、ラベル値は 0 から 1 までの範囲で連続しています。0.5 よりも大きい値によってサンプルが肯定的な結果を示す場合は、label_values_or_threshold0.5 に設定する必要があります。

  • facet — バイアス分析に必要です。ファセットオブジェクトの配列。バイアスの測定対象となる機密属性で構成されます。機密属性を使用せずにモデルをトレーニングした場合でも、ファセットを使用してデータセットとモデルのバイアス特性を理解できます。詳細については、の「ファセット」を参照してください。Amazon、 SageMaker 偏見と公平性に関する条件を明確化各ファセットオブジェクトには次のフィールドが含まれます。

    • name_or_index — 表形式データセット内の機密属性列の名前または 0 から始まるインデックス。facet_dataset_uri が指定されている場合、インデックスはメインデータセットではなくファセットデータセットを参照します。

    • value_or_thresholdfacet が数値であり、機密グループを選択するための下限として label_values_or_threshold が適用される場合は必須です。ファセット値の配列またはしきい値。バイアスが影響を与える機密性の高い属性グループを示します。ファセットデータ型が分類型で value_or_threshold を指定しない場合、バイアスメトリクスは (すべての値ではなく) 一意の値ごとに 1 つのグループとして計算されます。さまざまな facet データ型に value_or_threshold をを設定するには、以下の例を参照してください。

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

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

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

  • group_variable — バイアスメトリックまたはに使用するサブグループを示す列の名前または 0 から始まるインデックス。条件付き属性格差 (CDD) 予測ラベルの条件付き属性格差 (CDDPL)

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

    注記

    ファセットデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を joinsource_name_or_index で指定する必要があります。パラメータ facet を使用して、ファセットデータセット内の各ファセットを識別する必要があります。

  • facet_headers — (facet_dataset_uri が指定されている場合のみ適用) ファセット データセットの列名と、オプションでファセット データセットとメインデータセットを結合するための識別子列ヘッダーを含む文字列の配列。joinsource_name_or_index を参照してください。

  • methods — 1 つ以上の分析メソッドとそのパラメータを含むオブジェクト。メソッドを省略すると、そのメソッドは分析にもレポートにも使用されません。

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

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

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

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

          • dataset_typeapplication/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_logittrue の場合、SHAP 値はロジスティック回帰係数を使用して計算されます。ロジスティック回帰係数は対数オッズ比として解釈できます。

      • save_local_shap_values — (オプション) データセット内の各レコードのローカル SHAP 値を分析結果に含めることを示すブール値。デフォルトは false です。

        メインデータセットが複数のファイルに分割されているか、分散処理が有効になっている場合は、パラメータ joinsource_name_or_index を使用して識別子列も指定します。識別子列とローカル SHAP 値は分析結果に保存されます。これにより、各レコードをローカル SHAP 値にマッピングできます。

      • agg_method — (オプション) すべてのインスタンスのローカル SHAP 値 (各インスタンスの SHAP 値) をグローバル SHAP 値 (データセット全体の SHAP 値) に集約するために使用されるメソッド。デフォルトは mean_abs です。以下のメソッドを使用して SHAP 値を合計できます。

        • mean_abs — すべてのインスタンスのローカル SHAP 値の絶対値の平均。

        • mean_sq — すべてのインスタンスのローカル SHAP 値の二乗の平均。

        • median — すべてのインスタンスのローカル SHAP 値の中央値。

      • text_config — 自然言語処理を説明しやすくするために必要です。テキスト列をテキストとして扱い、テキスト単位ごとに説明を提供したい場合は、この設定を含めます。自然言語処理を説明するための分析設定の例については、以下を参照してください。自然言語処理の説明可能性の分析設定

        • granularity — テキスト列の分析における粒度の単位。有効な値は tokensentence、または paragraph です。テキストの各単位は特徴量と見なされ、単位ごとにローカル SHAP 値が計算されます。

        • language — テキスト列の言語。有効な値は chinesedanishdutchenglishfrenchgermangreekitalianjapaneselithuanianmulti-languagenorwegian bokmålpolishportugueseromanianrussianspanishafrikaansalbanianarabicarmenianbasquebengalibulgariancatalancroatianczechestonianfinnishgujaratihebrewhindihungarianicelandicindonesianirishkannadakyrgyzlatvianligurianluxembourgishmacedonianmalayalammarathinepalipersiansanskritserbiansetswanasinhalaslovakslovenianswedishtagalogtamiltatarteluguthaiturkishukrainianurduvietnameseyoruba です。複数の言語を組み合わせるには multi-language と入力します。

        • max_top_tokens — (オプション) グローバル SHAP 値に基づく上位トークンの最大数。デフォルトは 50 です。トークンはデータセットに複数回出現する可能性があります。 SageMaker Clarify 処理ジョブは、各トークンの SHAP 値を集計し、グローバル SHAP 値に基づいて上位のトークンを選択します。選択した上位トークンのグローバル SHAP 値は analysis.json ファイルの global_top_shap_text セクションに含まれます。

        • 集約のローカル SHAP 値。

      • image_config — コンピュータビジョンの説明可能性に必要です。イメージで構成されている入力データセットがあり、それらをコンピュータービジョンの問題で説明可能にするために分析したい場合は、この構成を含めます。

        • model_type — モデルのタイプ。有効な値を次に示します。

          • イメージ分類モデルを表す IMAGE_CLASSIFICATION

          • オブジェクト検出モデルを表す OBJECT_DETECTION

        • max_objects — model_type が OBJECT_DETECTION の場合にのみ適用されます。コンピュータビジョンモデルによって検出されたオブジェクトの最大数 (信頼スコア順)。信頼スコアで上位 max_objects よりもランクが低いオブジェクトはすべて除外されます。デフォルトは 3 です。

        • context — model_type が OBJECT_DETECTION の場合にのみ適用されます。検出されたオブジェクトの境界ボックスの周囲がベースラインイメージによってマスクされているかどうかを示します。有効な値は、すべてをマスクするする場合は 0、何もマスクしない場合は 1 です。デフォルトは 1 です。

        • iou_thresholdmodel_typeOBJECT_DETECTION の場合にのみ適用されます。予測を元の検出値と照らし合わせて評価するための最小インターセクションオーバーユニオン (IOU) メトリクス。IOU メトリックが高いと、予測値検出ボックスとグラウンドトゥルース検出ボックスとの重複が大きくなります。デフォルトは 0.5 です。

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

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

    • pdp — 部分依存プロット (PDP) の計算にはこのメソッドを含めてください。PDP を生成するための解析構成の例については、以下を参照してください。部分依存プロット (PDP) を計算する

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

      • top_k_features — (オプション) PDP プロットの生成に使用される上位の特徴量数を指定します。shap指定されていないにもかかわらずメソッドが要求された場合、 SageMaker Clarify 処理ジョブはその SHAP 属性に基づいて上位のフィーチャを選択します。featuresデフォルトは 10 です。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      • 他のタイプの説明可能性については、有効な値は text/csvapplication/jsonlinesapplication/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 つの数値特徴量値 (123) がある場合、レコードは JSON Line {"myfeatures":[1,2,3]} としてモデルに送信されます。

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

    • record_template — データセットインスタンスからモデル入力の各レコードを構築するために使用されるテンプレート文字列。これは content_typeapplication/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_templaterecord_template のパラメータ値の例を以下に示します。

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

      • record_template: "$features"

      次のコード例では、ヘッダーと特徴量は次のように定義されています。

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

      先ほどのモデル入力例を構成する content_templaterecord_template のパラメータ値の例を以下に示します。

      • content_template: "$records"

      • record_template: "$features_kvp"

      先ほどのモデル入力例を構成するための代替コード例を以下に示します。

      • content_template: "$records"

      • record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"

      次のコード例では、ヘッダーと特徴量は次のように定義されています。

      { "A": 0, "B": 1 }

      上記で構成する content_template パラメータ値と record_template パラメータ値の例: 先ほどのモデル入力例は次のとおりです。

      • content_template: "$record"

      • record_template: "$features_kvp"

    • label — バイアス分析用のモデル出力から予測ラベルを抽出するために使用される 0 から始まる整数インデックスまたは JMESPath 式文字列。モデルが多クラスで、label パラメータがモデル出力からすべての予測ラベルを抽出する場合、以下が適用されます。

      • probability パラメータは、モデル出力から対応する確率 (またはスコア) を取得するために必要です。

      • 最高スコアの予測ラベルが選択されます。

      label の値は、次のように accept_type パラメータの値によって異なります。

      • accept_typetext/csv の場合、label はモデル出力に含まれる予測ラベルのインデックスです。

      • accept_typeapplication/jsonlines または application/json の場合、label は予測ラベルを取得するためにモデル出力に適用される JMESPath 式です。

    • label_headers — ラベルがデータセットに取り込める値の配列。バイアス分析が必要な場合は、モデル出力から対応する確率値 (スコア) を取得するために probability パラメータも必要になり、最高スコアの予測ラベルが選択されます。説明可能性分析が必要な場合は、ラベルヘッダーを使用して分析レポートを整えます。label_headers の値は、コンピュータービジョンの説明可能性のために必要です。例えば、多クラス分類の問題では、ラベルに birdcatdog の 3 つの値がある場合、label_headers["bird","cat","dog"] に設定する必要があります。

    • probability — (オプション) 説明可能性分析の確率 (スコア) の抽出や、バイアス分析用の予測ラベルの選択に使用される 0 から始まる整数インデックスまたは JMESPath 式文字列。probability の値は、次のように accept_type パラメータの値によって異なります。

      • accept_typetext/csv の場合、probability はモデル出力の確率 (スコア) のインデックスです。probability が指定されていない場合、モデル出力全体が確率 (スコア) とみなされます。

      • accept_type が JSON データ (application/jsonlines または application/json のいずれか) の場合、probability はモデル出力から確率 (スコア) を抽出するために使用される JMESPath 式でなければなりません。

分析設定ファイルの例

次のセクションには、CSV 形式と JSON Lines 形式のデータ、および自然言語処理 (NLP) とコンピュータービジョンの説明可能性の両方の分析設定ファイルの例が含まれています。

次の例は、CSV 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットには 4 つの特徴量列と 1 つの二項ラベル列、Target があります。データセットの内容は以下のようになります。ラベル値 1 は 結果は肯定的な結果を示します。datasetデータセットは処理入力によって SageMaker Clarify ジョブに提供されます。

"Target","Age","Gender","Income","Occupation" 0,25,0,2850,2 1,36,0,6585,0 1,22,1,1759,1 0,48,0,3446,1 ...

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

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

この設定例は、前のサンプルデータセットが、Gender 値が 0 のサンプルに有利に偏っているかどうかを測定する方法を示しています。以下の分析構成は、データセットのトレーニング前のバイアスメトリクスをすべて計算するように SageMaker Clarify 処理ジョブに指示します。

{ "dataset_type": "text/csv", "label": "Target", "label_values_or_threshold": [1], "facet": [ { "name_or_index": "Gender", "value_or_threshold": [0] } ], "methods": { "pre_training_bias": { "methods": "all" } } }

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

トレーニング前のバイアスメトリクスはトレーニング前に計算できます。ただし、トレーニング後のバイアスメトリクスを計算するには、トレーニング済みのモデルが必要です。次の出力例は、データを CSV 形式で出力する二項分類モデルからのものです。この出力例では、各行に 2 つの列が含まれています。1 列目には予測ラベルが含まれ、2 列目にはそのラベルの確率値が含まれます。

0,0.028986845165491 1,0.825382471084594 ...

以下の設定例では、データセットとモデル出力からの予測を使用して、考えられるすべてのバイアス指標を計算するように SageMaker Clarify 処理ジョブに指示しています。この例では、モデルはエンドポイントにデプロイされます。 SageMaker your_endpoint

注記

次のコード例では、パラメータ content_typeaccept_type は設定されていません。そのため、パラメータ dataset_type の値、つまり text/csv が自動的に使用されます。

{ "dataset_type": "text/csv", "label": "Target", "label_values_or_threshold": [1], "facet": [ { "name_or_index": "Gender", "value_or_threshold": [0] } ], "methods": { "pre_training_bias": { "methods": "all" }, "post_training_bias": { "methods": "all" } }, "predictor": { "endpoint_name": "your_endpoint", "label": 0 } }

SHAP 値を計算する

以下の分析設定例では、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 列目から (0 ベースのインデックスを使用して) 確率スコアを抽出するように指示します。

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

以下の例は、PDP を使用して分析レポート上の Income 特徴量の需要度を表示する方法を示しています。レポートパラメータは、 SageMaker Clarify 処理ジョブにレポートを生成するように指示します。ジョブが完了すると、生成されたレポートは report.pdf として analysis_result の場所に保存されます。grid_resolution パラメータは、特徴量値の範囲を 10 のバケットに分割します。次の例で指定されたパラメータを組み合わせて、X 軸にセグメントがある場合の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。Income 10Y 軸には、予測に対する 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 値が最大となる上位のフィーチャの部分依存プロット (PDP) を計算するように指示されます。2

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

モデルをエンドポイントにデプロイする代わりに、パラメーターを使用して Clarify SageMaker 処理ジョブにモデルの名前を指定できます。 SageMaker model_name次の例は、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 dense 形式になっています。各行は有効な JSON オブジェクトです。 "Features" キーは特徴量値の配列を指し、"Label" キーはグラウンドトゥルースラベルを指します。データセットは「データセット」処理入力によって SageMaker Clarify ジョブに提供されます。JSON 行の詳細については、「JSONLINES リクエストの形式」を参照してください。

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

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

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

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

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 your_endpoint以下の分析構成例では、 SageMaker Clarify 処理ジョブに、データセットとモデルの両方で発生する可能性のあるすべてのバイアス指標を計算するように指示しています。この例では、content_type パラメータと accept_type パラメータは設定されていません。そのため、dataset_type パラメータの値、つまり application/jsonlines を使用するように自動的に設定されます。 SageMaker Clarify 処理ジョブは、$featuresプレースホルダーをフィーチャの配列に置き換えることで、content_templateパラメーターを使用してモデル入力を構成します。

{ "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_0column_1フィーチャヘッダーやラベルヘッダーなどの一般的な名前を使用してプレースホルダーを生成する必要があります。label0headerslabel の値を指定すると分析結果が読みやすくなります。確率パラメータは 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 軸にセグメントがある場合の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。Income 10Y 軸には、予測に対する 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 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、JSON デンス形式になっています。 SageMaker JSON 行の詳細については、「JSONLINES リクエストの形式」を参照してください。

入力リクエスト全体は有効な JSON で、外部構造はリストであり、各要素はレコードのデータです。各レコード内で、Features キーは特徴量値の配列を指し、Label キーはグラウンドトゥルースラベルを指します。datasetデータセットは処理入力によって SageMaker Clarify ジョブに提供されます。

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

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

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

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

features パラメータは 2D 配列または行列を抽出する JMESPath 式に設定されます。この行列の各行には、各レコードの Features のリストが含まれている必要があります。label パラメータは、グラウンドトゥルースラベルのリストを抽出する JMESPath 式に設定されます。このリストの各要素には、レコードのラベルが含まれている必要があります。

次のように、ファセット名を使用して機密属性を指定します。

{ "dataset_type": "application/json", "headers": ["Age","Gender","Income","Occupation","Target"], "label": "[*].Label", "features": "[*].Features", "label_values_or_threshold": [1], "facet": [ { "name_or_index": "Gender", "value_or_threshold": [0] } ], "methods": { "pre_training_bias": { "methods": "all" } } }

すべてのバイアスメトリクスを計算する

トレーニング後のバイアスメトリクスを計算するには、トレーニング済みのモデルが必要です。次のコード例は、JSON データを例の形式で出力する二項分類モデルからのものです。この例では、predictions の下の各要素がレコードの予測出力です。サンプルコードには予測されたラベルを指す predicted_label キーと、確率値を指す probability キーが含まれています。

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

SageMaker your_endpointモデルはという名前のエンドポイントにデプロイできます。

次の例では、パラメータ content_typeaccept_type は設定されていません。そのため、content_typeaccept_type は、パラメーター dataset_type の値 (application/json) を使用するように自動的に設定されます。次に、 SageMaker Clarify content_template 処理ジョブはパラメータを使用してモデル入力を構成します。

以下の例では、$records プレースホルダーをレコードの配列に置き換えてモデル入力を構成しています。次に、record_template パラメータによって各レコードの JSON 構造が構成され、$features プレースホルダーが各レコードの特徴量配列に置き換えられます。

以下の分析構成例では、 SageMaker Clarify 処理ジョブに、データセットとモデルの両方で発生する可能性のあるすべてのバイアスメトリクスを計算するように指示しています。

{ "dataset_type": "application/json", "headers": ["Age","Gender","Income","Occupation","Target"], "label": "[*].Label", "features": "[*].Features", "label_values_or_threshold": [1], "facet": [ { "name_or_index": "Gender", "value_or_threshold": [0] } ], "methods": { "pre_training_bias": { "methods": "all" }, "post_training_bias": { "methods": "all" } }, "predictor": { "endpoint_name": "your_endpoint", "content_template": "$records", "record_template": "{\"Features\":$features}", "label": "predictions[*].predicted_label" } }

SHAP 値を計算する

SHAP 分析にはラベルを指定する必要はありません。次の例では、headers パラメータは指定されていません。そのため、 SageMaker Clarify 処理ジョブは、column_0column_1フィーチャヘッダーやラベルヘッダーなどの一般的な名前を使用してプレースホルダーを生成します。label0headerslabel の値を指定すると分析結果が読みやすくなります。

次の設定例では、各レコードの各予測から確率を抽出する 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 軸にセグメントがある場合の PDP グラフを含むレポートを生成するように SageMaker Clarify 処理ジョブに指示します。Income 10Y 軸では、予測に対する 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 つの特徴量列があります。データセットは、処理入力パラメータによって SageMaker Clarify ジョブに提供されます。dataset

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

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

0.491656005382537 0.569582343101501 ...

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

英語では、各トークンは単語です。次の例は、平均 "Rating" を 4 にしてインプレイスの SHAP の "baseline" インスタンスを提供する方法も示しています。特別なマスクトークン "[MASK]" は、"Comments" 内のトークン (単語) を置き換えるために使用します。この例では GPU エンドポイントインスタンスタイプも使用して推論を高速化しています。

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

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

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

画像分類の詳細については、を参照してください画像分類 - MXNet

この例では、同じ JPEG SageMaker 画像を使って物体検出モデルを学習させ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"] } }