翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 分析設定ファイル SageMaker Clarify を使用してデータとモデルの説明可能性とバイアスを分析するには、処理ジョブを設定する必要があります。この処理ジョブの設定の一部には、分析ファイルの設定が含まれます。分析ファイルは、バイアス分析と説明可能性のパラメータを指定します。処理ジョブと分析ファイルを設定する方法の詳細については、「[SageMaker Clarify 処理ジョブを設定する](clarify-processing-job-configure-parameters.md)」を参照してください。 このガイドでは、この分析設定ファイルのスキーマとパラメータについて説明します。このガイドには、表形式データセットのバイアスメトリクスを計算したり、自然言語処理 (NLP) やコンピュータビジョン (CV) の問題の説明を生成したりするための分析設定ファイルの例も含まれています。 分析設定ファイルを作成することも、[SageMaker Python SDK](https://sagemaker.readthedocs.io/) を使用して [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor) API でファイルを生成することもできます。ファイルの内容を表示すると、SageMaker Clarify ジョブで使用される基本設定を理解するのに役立ちます。 **Topics** + [分析設定ファイルのスキーマ](#clarify-processing-job-configure-schema) + [分析設定ファイルの例](#clarify-processing-job-configure-analysis-examples) ## 分析設定ファイルのスキーマ 以下のセクションでは、要件とパラメータの説明を含む分析設定ファイルのスキーマについて説明します。 ### 分析設定ファイルの要件 SageMaker Clarify 処理ジョブは、分析設定ファイルが以下の要件を満たすように構成されていることを前提としています。 + 処理入力名は `analysis_config.` でなければならない。 + 分析設定ファイルは JSON 形式で、UTF-8 でエンコードされている。 + 分析設定ファイルは、Amazon S3 オブジェクトである。 分析設定ファイルには追加のパラメータを指定できます。以下のセクションでは、SageMaker Clarify 処理ジョブをユースケースや必要な分析の種類に合わせて調整するためのさまざまなオプションを提示します。 ### 分析設定ファイルのパラメータ JSON 設定ファイルでは、次のパラメータを指定できます。 + **version** — (オプション) 分析設定ファイルスキーマのバージョン文字列。バージョンが指定されていない場合、SageMaker Clarify はサポートされている最新のバージョンを使用します。現在サポートされているバージョンは `1.0` のみです。 + **dataset\$1type** — データセットの形式。入力データセット形式は、次のいずれかの値になります。 + 表形式 + CSV の場合 `text/csv` + [SageMaker AI JSON Lines の高密度形式の](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines) `application/jsonlines` + JSON の場合 `application/json` + Apache Parquet の場合 `application/x-parquet` + コンピュータビジョンの問題に対する説明可能性を有効にする場合 `application/x-image` + 時系列予測モデルの説明 + JSON の場合 `application/json` + **dataset\$1uri** — (オプション) メインデータセットのユニフォームリソース識別子 (URI)。S3 URI プレフィックスを指定すると、SageMaker Clarify 処理ジョブは、プレフィクスの下にあるすべての S3 ファイルを再帰的に収集します。コンピュータビジョンの問題に対して、イメージマニフェストファイルには S3 URI プレフィックスまたは S3 URI のいずれかを指定できます。`dataset_uri` を指定すると、データセット処理ジョブの入力よりも優先されます。画像と時系列のユースケース以外のすべての形式タイプでは、SageMaker Clarify 処理ジョブは入力データセットを**表形式のデータセット**として表形式のデータフレームにロードします。この形式により、SageMaker AI は入力データセットを簡単に操作して分析できます。 + **ヘッダー** – (オプション) + **表形式:** 表形式のデータセットの列名を含む文字列の配列。`headers` の値が指定されていない場合、SageMaker Clarify 処理ジョブはデータセットからヘッダーを読み取ります。データセットにヘッダーがない場合、Clarify 処理ジョブは 0 から始まる列インデックスに基づいてプレースホルダー名を自動的に生成します。例えば、1 列目と 2 列目のプレースホルダー名は **column\$10** と **column\$11** になります。 **注記** 原則として、`dataset_type` が `application/jsonlines` または `application/json` の場合、`headers` には次の名前が順番に含まれている必要があります。 特徴量名 ラベル名 (`label` が指定されている場合) 予測ラベル名 (`predicted_label` が指定されている場合) `label` が指定されている場合の `application/jsonlines` データセットタイプの `headers` の例は、`["feature1","feature2","feature3","target_label"]` です。 + **時系列:** データセット内の列名のリスト。指定しない場合、Clarify は内部で使用するヘッダーを生成します。時系列の説明可能性の場合は、次の順序でヘッダーを指定します。 1. 項目 ID 1. timestamp 1. ターゲット時系列 1. 関連するすべての時系列列 1. すべての静的共変量列 + **label** — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、`label` はグラウンドトゥルースラベル (表形式データセットでは観測ラベルまたはターゲット属性とも呼ばれる) の位置を特定するために使用されます。グラウンドトゥルースラベルはバイアスメトリックの計算に使用されます。`label` の値は、`dataset_type` パラメータの値に応じて次のように指定されます。 + `dataset_type` が **text/csv** の場合、`label` は次のいずれかに指定できます。 + 有効な列名 + データセット列の範囲内にあるインデックス。 + `dataset_type` が **application/parquet** の場合、`label` は有効な列名でなければなりません。 + `dataset_type` が **application/jsonlines** の場合、`label` はデータセットからグラウンドトゥルースラベルを抽出するように記述された [JMESPath](https://jmespath.org/) 式でなければなりません。慣例により、`headers` を指定する場合はラベル名を含める必要があります。 + `dataset_type` が **application/json** の場合、`label` はデータセットの各レコードのからグラウンドトゥルースラベルを抽出するように記述された [JMESPath](https://jmespath.org/) 式でなければなりません。この JMESPath 式は、i 番目のラベルが i 番目のレコードに相関するラベルのリストを生成する必要があります。 + **predicted\$1label** — (オプション) 文字列または 0 から始まる整数のインデックス。指定すると、`predicted_label` は表形式データセット内の予測ラベルを含む列を検索するために使用されます。予測ラベルはトレーニング後の**バイアスメトリクス**の計算に使用されます。データセットに予測ラベルが含まれていない場合、`predicted_label` パラメータはオプションです。計算に予測ラベルが必要な場合、SageMaker Clarify 処理ジョブはモデルから予測を取得します。 `predicted_label` の値は、`dataset_type` の値に応じて次のように指定されます。 + `dataset_type` が **text/csv** の場合、`predicted_label` は次のいずれかに指定できます。 + 有効な列名 `predicted_label_dataset_uri` が指定されていても `predicted_label` が指定されていない場合、デフォルトの予測ラベル名は "predicted\$1label" になります。 + データセット列の範囲内にあるインデックス。`predicted_label_dataset_uri` が指定されている場合、インデックスは予測ラベルデータセット内の予測ラベル列を見つけるために使用されます。 + dataset\$1type が **application/x-parquet** の場合、`predicted_label` は有効な列名でなければなりません。 + dataset\$1type が **application/jsonlines** の場合、`predicted_label` はデータセットから予測ラベルを抽出するように記述された有効な [JMESPath](https://jmespath.org/) 式でなければなりません。慣例により、`headers` を指定する場合は予測ラベル名を含める必要があります。 + `dataset_type` が **application/json** の場合、`predicted_label` はデータセットの各レコードのから予測ラベルを抽出するように記述された [JMESPath](https://jmespath.org/) 式でなければなりません。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\$1label\$1dataset\$1uri** – (オプション) dataset\$1type が `text/csv` である場合にのみ適用されます。トレーニング後の**バイアスメトリクス**の計算に使用される予測ラベルを含むデータセットの S3 URI。SageMaker Clarify 処理ジョブは、モデルから予測を得る代わりに、指定された URI から予測を読み込みます。この場合、`predicted_label` は予測ラベルデータセット内の予測ラベル列を見つける必要があります。予測ラベルデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を `joinsource_name_or_index` によって指定する必要があります。 + **predicted\$1label\$1headers** – (オプション) `predicted_label_dataset_uri` が指定される場合にのみ適用されます。予測ラベルデータセットの列名が含まれている文字列の配列。予測ラベルヘッダーの他に、`predicted_label_headers` は予測ラベルデータセットとメインデータセットを結合する識別子列のヘッダーを含めることもできます。詳細については、次の `joinsource_name_or_index` パラメータの説明を参照してください。 + **joinsource\$1name\$1or\$1index** – (オプション) 内部結合を実行する際に識別子列として使用される表形式データセット内の列の名前または 0 から始まるインデックス。この列は識別子としてのみ使用されます。バイアス分析や特徴量属性分析などの他の計算には使用されません。`joinsource_name_or_index` の値は、次のような場合に必要です。 + 入力データセットが複数あり、いずれか 1 つが複数のファイルに分割される。 + 分散処理は、SageMaker Clarify 処理ジョブの [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount) を `1` より大きい値に設定することでアクティブ化される。 + **excluded\$1columns** — (オプション) 予測の入力としてモデルに送信されないようにする列の名前またはゼロから始まるインデックスの配列。グラウンドトゥルースラベルと予測ラベルは既に自動的に除外されています。この機能は、時系列ではサポートされていません。 + **probability\$1threshold** — (オプション) 浮動小数点数で、それを超えるとラベルまたはオブジェクトが選択されます。デフォルト値は `0.5` です。SageMaker Clarify 処理ジョブは次のような場合に `probability_threshold` を使用します。 + トレーニング後のバイアス分析では、`probability_threshold` はモデルが二項分類器の場合、数値モデル予測 (確率値またはスコア) をバイナリラベルに変換します。しきい値より大きいスコアは `1` に変換されます。一方、しきい値以下のスコアは `0` に変換されます。 + コンピュータビジョンの説明可能性の問題では、model\$1type が **OBJECT\$1DETECTION** の場合、`, probability_threshold`によって信頼スコアがしきい値より低いオブジェクトが検出されて除外されます。 + **label\$1values\$1or\$1threshold** – (オプション) バイアス分析の場合は必須です。ラベル値またはしきい値の配列。バイアスメトリクスに対するグラウンドトゥルースラベルと予測ラベルの肯定的な結果を示します。詳細については、「[バイアスと公平性に関する Amazon SageMaker Clarify の用語解説](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)」の「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 の用語解説](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)」の「**Facet**」を参照してください。各ファセットオブジェクトには次のフィールドが含まれます。 + **name\$1or\$1index** – (オプション) 表形式データセット内の機密属性列の名前または 0 から始まるインデックス。`facet_dataset_uri` が指定されている場合、インデックスはメインデータセットではなくファセットデータセットを参照します。 + **value\$1or\$1threshold** – (オプション) `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\$1variable** – (オプション) バイアスメトリクス [条件付き属性格差 (CDD)](clarify-data-bias-metric-cddl.md) または [予測ラベルの条件付き属性格差 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) に使用されるサブグループを示す列の名前またはゼロベースのインデックス + **facet\$1dataset\$1uri** – (オプション) dataset\$1type が `text/csv` である場合にのみ適用されます。バイアス分析用の機密属性を含むデータセットの S3 URI。機密属性を使用せずにモデルをトレーニングした場合でも、ファセットを使用してデータセットとモデルのバイアス特性を理解できます。 **注記** ファセットデータセットまたはメインデータセットが複数のファイルに分割されている場合は、2 つのデータセットを結合する識別子列を `joinsource_name_or_index` で指定する必要があります。パラメータ `facet` を使用して、ファセットデータセット内の各ファセットを識別する必要があります。 + **facet\$1headers** – (オプション) `facet_dataset_uri` が指定される場合にのみ適用されます。ファセットデータセットの列名を含む文字列の配列。必要に応じて、ファセットデータセットとメインデータセットを結合する識別子列ヘッダー。「`joinsource_name_or_index`」を参照してください。 + **time\$1series\$1data\$1config** – (オプション) 時系列のデータ処理に使用する設定を指定します。 + **item\$1id** – 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内の項目 ID を検索するために使用されます。 + **timestamp** – 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内のタイムスタンプを検索するために使用されます。 + **dataset\$1format** – 使用できる値は、`columns`、`item_records`、または `timestamp_records` です。このフィールドは、時系列の説明可能性のためにサポートされている唯一の形式である JSON データセットの形式を記述するために使用されます。 + **target\$1time\$1series** – JMESPath 文字列または 0 から始まる整数インデックス。このフィールドは、共有入力データセット内のターゲット時系列を検索するために使用されます。このパラメータが文字列の場合、`dataset_format` 以外のすべてのパラメータは文字列または文字列のリストである必要があります。このパラメータが整数の場合、`dataset_format` 以外のすべてのパラメータは整数または整数のリストである必要があります。 + **related\$1time\$1series** – (オプション) JMESPath 式の配列。このフィールドは、共有入力データセット内のすべての関連時系列 (存在する場合) を検索するために使用されます。 + **static\$1covariates** – (オプション) JMESPath 式の配列。このフィールドは、共有入力データセット内のすべての静的共変量フィールド (存在する場合) を検索するために使用されます。 例については「[時系列データセットの設定例](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex)」を参照してください。 + **methods** — 1 つ以上の分析メソッドとそのパラメータを含むオブジェクト。メソッドを省略すると、そのメソッドは分析にもレポートにも使用されません。 + **pre\$1training\$1bias** — トレーニング前のバイアスメトリクスを計算する場合は、このメソッドを含めます。メトリクスの詳細については、「[トレーニング前のバイアスメトリクス](clarify-measure-data-bias.md)」を参照してください。オブジェクトには以下のパラメータがあります。 + **methods** — 以下のリストにある計算対象となるトレーニング前のバイアスメトリクスのいずれかを含む配列。`methods` を **all** に設定すると、トレーニング前のバイアスメトリクスをすべて計算します。例えば、配列 `["CI", "DPL"]` は**クラス不均衡**と**ラベルの比率の差**を計算します。 + [クラス不均衡 (CI)](clarify-bias-metric-class-imbalance.md) 用の `CI` + [ラベルの比率の差 (DPL)](clarify-data-bias-metric-true-label-imbalance.md) 用の `DPL` + [カルバックライブラー情報量 (KL)](clarify-data-bias-metric-kl-divergence.md) 用の `KL` + [ジェンセンシャノン情報量 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) 用の `JS` + [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md) 用の `LP` + [合計変動距離 (TVD)](clarify-data-bias-metric-total-variation-distance.md) 用の `TVD` + [コルモゴロフスミルノフ (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) 用の `KS` + [条件付き属性格差 (CDD)](clarify-data-bias-metric-cddl.md) 用の `CDDL` + **pre\$1training\$1bias** — トレーニング後のバイアスメトリクスを計算する場合は、このメソッドを含めます。メトリクスの詳細については、「[トレーニング済みデータのメトリクスとモデルのバイアスのメトリクス](clarify-measure-post-training-bias.md)」を参照してください。`post_training_bias` オブジェクトには以下のパラメータがあります。 + **methods** — 以下のリストにある計算対象となるトレーニング後のバイアスメトリクスのいずれかを含む配列。`methods` を **all** に設定すると、トレーニング後のバイアスメトリクスをすべて計算します。例えば、配列 `["DPPL", "DI"]` は**予測ラベルにおける正の比率の差**と**異種影響**を計算します。使用できるメソッドは次のとおりです。 + [予測ラベルにおける正の比率の差 (DPPL)](clarify-post-training-bias-metric-dppl.md) 用の `DPPL` + [異種影響 (DI)](clarify-post-training-bias-metric-di.md) の場合は `DI` + [条件付き承認の差 (DCAcc)](clarify-post-training-bias-metric-dcacc.md) 用の `DCA` + [条件付き拒否の差 (DCR)](clarify-post-training-bias-metric-dcr.md) 用の `DCR` + [特異度差 (SD)](clarify-post-training-bias-metric-sd.md) 用の `SD` + [リコール差 (RD)](clarify-post-training-bias-metric-rd.md) 用の `RD` + [承認率の差 (DAR)](clarify-post-training-bias-metric-dar.md) 用の `DAR` + [拒否率の差 (DRR)](clarify-post-training-bias-metric-drr.md) 用の `DRR` + [精度差 (AD)](clarify-post-training-bias-metric-ad.md) 用の `AD` + [処理の同等性 (TE)](clarify-post-training-bias-metric-te.md) 用の `TE` + [予測ラベルの条件付き属性格差 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) 用の `CDDPL` + [反事実フリップテスト (FT)](clarify-post-training-bias-metric-ft.md) 用の `FT` + [一般化エントロピー (GE)](clarify-post-training-bias-metric-ge.md) 用の `GE` + **shap** — SHAP 値を計算する場合はこのメソッドを含めます。SageMaker Clarify 処理ジョブはカーネル SHAP アルゴリズムをサポートしています。`shap` オブジェクトには以下のパラメータがあります。 + **baseline** – (オプション) SHAP ベースラインデータセット。これは、バックグラウンドデータセットとも呼ばれます。表形式データセットまたはコンピュータービジョンの問題におけるベースラインデータセットのその他の要件は次のとおりです。SHAP ベースラインの詳細については、「[説明可能性のための SHAP ベースライン](clarify-feature-attribute-shap-baselines.md)」を参照してください + **表形式**データセットの場合、`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 処理ジョブは入力イメージと同じ解像度で[ホワイトノイズ](https://en.wikipedia.org/wiki/White_noise)のマスクイメージを生成します。 + **features\$1to\$1explain** — (オプション) SHAP 値を計算するための文字列配列または 0 から始まる特徴量列のインデックス。`features_to_explain` が指定されていない場合、すべての特徴量列の SHAP 値が計算されます。これらの特徴量列には、ラベル列や予測ラベル列を含めることはできません。`features_to_explain` パラメータは、数値列とカテゴリ列を含む表形式データセットでのみサポートされます。 + **num\$1clusters** — (オプション) ベースラインデータセットを計算するためにデータセットを分割するクラスターの数。各クラスターは 1 つのベースラインインスタンスの計算に使用されます。`baseline` が指定されていない場合、SageMaker Clarify 処理ジョブは、表形式データセットを `1` と `12` の間の最適な数のクラスターに分割してベースラインデータセットの計算を試みます。ベースラインインスタンスの数は SHAP 分析のランタイムに直接影響します。 + **num\$1samples** — (オプション) Kernel SHAP アルゴリズムで使用されるサンプルの数。`num_samples` が指定されていない場合、SageMaker Clarify 処理ジョブは数を自動的に選択します。サンプルの数は、合成データセットのサイズとジョブのランタイムに直接影響します。 + **seed** — (オプション) 同じジョブに対して一貫性のある SHAP 値を生成するために、SHAP Explainer 内の疑似乱数生成器を初期化するために使用される整数。シードが指定されていない場合、同じジョブが実行されるたびに、モデルから出力される SHAP 値が若干変わることがあります。 + **use\$1logit** — (オプション) ロジット関数をモデル予測に適用するかどうかを示すブール値。デフォルトは `false` です。`use_logit` が `true` の場合、SHAP 値はロジスティック回帰係数を使用して計算されます。ロジスティック回帰係数は対数オッズ比として解釈できます。 + **save\$1local\$1shap\$1values** — (オプション) データセット内の各レコードのローカル SHAP 値を分析結果に含めることを示すブール値。デフォルトは `false` です。 メインデータセットが複数のファイルに分割されているか、分散処理が有効になっている場合は、パラメータ `joinsource_name_or_index` を使用して識別子列も指定します。識別子列とローカル SHAP 値は分析結果に保存されます。これにより、各レコードをローカル SHAP 値にマッピングできます。 + **agg\$1method** — (オプション) すべてのインスタンスのローカル SHAP 値 (各インスタンスの SHAP 値) をグローバル SHAP 値 (データセット全体の SHAP 値) に集約するために使用されるメソッド。デフォルトは `mean_abs` です。以下のメソッドを使用して SHAP 値を合計できます。 + **mean\$1abs** — すべてのインスタンスのローカル SHAP 値の絶対値の平均。 + **mean\$1sq** — すべてのインスタンスのローカル SHAP 値の二乗の平均。 + **median** — すべてのインスタンスのローカル SHAP 値の中央値。 + **text\$1config** – 自然言語処理の説明可能性の場合は、必須です。テキスト列をテキストとして扱い、テキスト単位ごとに説明を提供したい場合は、この設定を含めます。自然言語処理の説明可能性の分析設定の例については、「[自然言語処理の説明可能性の分析設定](#clarify-analysis-configure-nlp-example)」を参照してください。 + **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\$1top\$1tokens** — (オプション) グローバル SHAP 値に基づく上位トークンの最大数。デフォルトは `50` です。トークンはデータセットに複数回出現する可能性があります。SageMaker Clarify 処理ジョブは、各トークンの SHAP 値を集計し、グローバル SHAP 値に基づいて上位のトークンを選択します。選択した上位トークンのグローバル SHAP 値は analysis.json ファイルの `global_top_shap_text` セクションに含まれます。 + 集約のローカル SHAP 値。 + **image\$1config** — コンピュータビジョンの説明可能性に必要です。イメージで構成されている入力データセットがあり、それらをコンピュータービジョンの問題で説明可能にするために分析したい場合は、この構成を含めます。 + **model\$1type** — モデルのタイプ。有効な値を次に示します。 + イメージ分類モデルを表す `IMAGE_CLASSIFICATION` + オブジェクト検出モデルを表す `OBJECT_DETECTION` + **max\$1objects** — model\$1type が **OBJECT\$1DETECTION** の場合にのみ適用されます。コンピュータビジョンモデルによって検出されたオブジェクトの最大数 (信頼スコア順)。信頼スコアで上位 max\$1objects よりもランクが低いオブジェクトはすべて除外されます。デフォルトは `3` です。 + **context** — model\$1type が **OBJECT\$1DETECTION** の場合にのみ適用されます。検出されたオブジェクトの境界ボックスの周囲がベースラインイメージによってマスクされているかどうかを示します。有効な値は、すべてをマスクするする場合は `0`、何もマスクしない場合は `1` です。デフォルトは 1 です。 + **iou\$1threshold** — `model_type` が **OBJECT\$1DETECTION** の場合にのみ適用されます。予測を元の検出値と照らし合わせて評価するための最小インターセクションオーバーユニオン (IOU) メトリクス。IOU メトリックが高いと、予測値検出ボックスとグラウンドトゥルース検出ボックスとの重複が大きくなります。デフォルトは `0.5` です。 + **num\$1segments** — (オプション) 入力イメージでラベル付けされるおおよそのセグメント数を決定する整数。イメージの各セグメントは特徴量と見なされ、各セグメントのローカル SHAP 値が計算されます。デフォルトは `20` です。 + **segment\$1compactness** — (オプション) [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) メソッドによって生成されるイメージセグメントの形状とサイズを決定する整数。デフォルトは `5` です。 + **pdp** – このメソッドを Partial Dependence Plot (PDP) の計算に含めます。PDP を生成するための分析構成の例については、「[部分依存プロット (PDP) を計算する](#clarify-analysis-configure-csv-example-pdp)」を参照してください。 + **features** — `shap` メソッドが要求されていない場合は必須です。PDP プロットを計算してプロットするための特徴量名またはインデックスの配列。 + **top\$1k\$1features** — (オプション) PDP プロットの生成に使用される上位の特徴量数を指定します。`features`が指定されていないが `shap` メソッドが要求されている場合、SageMaker Clarify 処理ジョブはその SHAP 属性に基づいて上位の特徴量を選択します。デフォルトは `10` です。 + **grid\$1resolution** — 数値の範囲を分割するバケットの数です。これは、PDP プロットのグリッドの粒度を指定します。 + **asymmetric\$1shapley\$1value** – 時系列予測モデルの説明可能性メトリクスを計算する場合は、このメソッドを含めます。SageMaker Clarify 処理ジョブは、非対称 Shapley 値アルゴリズムをサポートしています。非対称 Shapley 値は、対称公理を省略した Shapley 値のバリアントです。詳細については、「[Asymmetric Shapley values: incorporating causal knowledge into model-agnostic explainability](https://arxiv.org/abs/1910.06358)」を参照してください。これらの値を使用して、特徴量が予測結果にどのように貢献するかを判断します。非対称 Shapley 値は、予測モデルが入力として取る時系列データの一時的な依存関係を考慮します。 このアルゴリズムには、以下のパラメータが含まれます。 + **direction** – 使用可能なタイプは、`chronological`、`anti_chronological`、`bidirectional` です。時間構造は、時系列順、反時系列順、またはその両方でナビゲートできます。時系列の説明は、最初の時間ステップから情報を反復的に追加することによって構築されます。反時系列の説明は、最後のステップから開始して後方に移動しながら情報を追加します。株価の予測など、最新性バイアスが存在する場合は、後者の順序を使用する方が適切である可能性があります。 + **granularity** – 使用する説明の粒度。使用可能な粒度オプションは、以下のとおりです。 + **timewise** – `timewise` の説明は低コストであり、特定の時間ステップに関する情報のみを提供します。過去の n 日目の情報が将来の m 日目の予測にどの程度貢献したかを把握します。結果として得られる属性は、静的共変量を個別には説明することなく、ターゲットと関連する時系列は区別されません。結果として得られる貢献度は、静的共変量を個別に説明することはなく、ターゲットと関連する時系列は区別されません。 + **fine\$1grained** – `fine_grained` の説明は計算集約的である一方、入力変数のすべての貢献度の完全な詳細を提供します このメソッドでは、実行時間の短縮のために近似説明を計算します。詳細については、以下の「`num_samples` パラメータ」を参照してください。 **注記** `fine_grained` の説明でサポートされるのは、`chronological` の順序のみです。 + **num\$1samples** – (オプション) この引数は `fine_grained` の説明の場合は必須です。数値が高いほど、近似の精度が高くなります。この数値は、入力特徴量のディメンションに応じてスケールする必要があります。経験則としては、結果が大きすぎない場合は、この変数を *(1 \$1 max (関連する時系列の数、静的共変量の数))^2* に設定します。 + **baseline** – (オプション) 対応するデータセット (バックグラウンドデータとも呼ばれます) の非提携値を置き換えるベースライン設定。次のコードスニペットは、ベースライン設定の例を説明しています。 ``` { "related_time_series": "zero", "static_covariates": { : [0, 2], : [-1, 1] }, "target_time_series": "zero" } ``` + ターゲット時系列や関連する時系列などの時間データの場合、ベースライン値タイプは次のいずれかの値になります。 + `zero` - 非提携値はすべて 0.0 に置き換えられます。 + `mean` - 非提携値はすべて時系列の平均に置き換えられます。 + 静的共変量の場合、モデル要求が静的共変量値を取る場合にのみベースラインエントリを指定する必要があります。この場合、このフィールドは必須です。ベースラインは、すべての項目をリストとして指定する必要があります。例えば、2 つの静的共変量を持つデータセットがある場合、ベースライン設定は次のようになります。 ``` "static_covariates": { : [1, 1], : [0, 1] } ``` 上記の例では、** と ** は、データセットからの項目 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\$1name** – [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) API が作成した SageMaker AI モデルの名前。endpoint\$1name の代わりに `model_name` を指定すると、SageMaker Clarify 処理ジョブは、**シャドウエンドポイント**と呼ばれるモデル名のエフェメラルエンドポイントを作成し、エンドポイントから予測を取得します。ジョブは、計算が完了した後にシャドウエンドポイントを削除します。モデルがマルチモデルの場合は、`target_model` パラメータを指定する必要があります。マルチモデルエンドポイントの詳細については、「[マルチモデルエンドポイント](multi-model-endpoints.md)」を参照してください。 + **endpoint\$1name\$1prefix** — (オプション) シャドウエンドポイントのカスタム名プレフィックス。`endpoint_name` の代わりに `model_name` を指定した場合に適用されます。例えば、エンドポイントへのアクセスをエンドポイント名で制限する場合は `endpoint_name_prefix` を指定します。プレフィックスは [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName) パターンと一致する必要があり、最大長は `23` です。デフォルトは `sm-clarify` です。 + **initial\$1instance\$1count** - シャドウエンドポイントのインスタンス数を指定します。endpoint\$1name の代わりに model\$1name を指定する場合は必須です。`initial_instance_count` の値はジョブの [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount) と異なる場合がありますが、比率は 1:1 にすることをお勧めします。 + **instance\$1type**-シャドウエンドポイントのインスタンスタイプを指定します。`endpoint_name` の代わりに `model_name` を指定する場合は必須です。例えば、`instance_type` を "ml.m5.large" に設定できます。場合によっては、`instance_type` に指定した値がモデル推論時間の短縮に役立つことがあります。例えば、自然言語処理モデルとコンピュータービジョンモデルを効率的に実行するには、通常、グラフィックス処理装置 (GPU) インスタンスタイプが必要です。 + **endpoint\$1name** – [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) API が作成した SageMaker AI エンドポイントの名前 指定した場合、`endpoint_name` が `model_name` パラメータよりも優先されます。既存のエンドポイントを使用するとシャドウエンドポイントのブートストラップ時間が短縮されますが、そのエンドポイントの負荷が大幅に増加する可能性もあります。また、分析メソッド (`shap` やなど `pdp`) によっては、エンドポイントに送信される合成データセットを生成します。これにより、エンドポイントのメトリクスやキャプチャされたデータが、実際の使用状況を正確に反映していない合成データによって汚染される可能性があります。これらの理由から、SageMaker Clarify の分析に既存の本番用エンドポイントを使用することは一般的に推奨されません。 + **target\$1model** — SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API の TargetModel パラメータに渡される文字列値。モデル (model\$1name パラメータで指定) またはエンドポイント (endpoint\$1name パラメータで指定) が multi-model の場合に必要です。マルチモデルエンドポイントの詳細については、「[マルチモデルエンドポイント](multi-model-endpoints.md)」を参照してください。 + **custom\$1attributes** — (オプション) エンドポイントに送信される推論リクエストに関する追加情報を提供できる文字列。文字列値は、SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API の `CustomAttributes` パラメータに渡されます。 + **content\$1type** — content\$1type — エンドポイントから予測を取得するために使用されるモデル入力形式。指定されている場合は、SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) 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\$1type** — エンドポイントから予測を取得するために使用されるモデル出力形式。`accept_type` の値は、SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API の `Accept` パラメータに渡されます。 + コンピュータビジョンの説明可能性については、`model_type` が `accept_type` の場合、デフォルトは **application/json** です。 + 時系列予測の説明可能性の場合、有効な値は **application/json** です。 + 他のタイプの説明可能性については、有効な値は **text/csv**、**application/jsonlines**、**application/json** です。`accept_type` の値が指定されていない場合、`accept_type` のデフォルトは `content_type` パラメータの値になります。 + **content\$1template** — データセットレコードからモデル入力を構築するために使用されるテンプレート文字列。`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\$1template** — データセットインスタンスからモデル入力の各レコードを構築するために使用されるテンプレート文字列。これは `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\$1template パラメータ値と record\$1template パラメータ値の例: 先ほどのモデル入力例は次のとおりです。 + `content_template: "$record"` + `record_template: "$features_kvp"` その他の例については、「[時系列データのエンドポイントリクエスト](clarify-processing-job-data-format-time-series-request-jsonlines.md)」を参照してください。 + **label** – (オプション) バイアス分析向けにモデル出力から予測ラベルを抽出するために使用される 0 から始まる整数インデックスまたは JMESPath 式文字列。モデルが多クラスで、`label` パラメータがモデル出力からすべての予測ラベルを抽出する場合、以下が適用されます。この機能は、時系列ではサポートされていません。 + `probability` パラメータは、モデル出力から対応する確率 (またはスコア) を取得するために必要です。 + 最高スコアの予測ラベルが選択されます。 `label` の値は、次のように accept\$1type パラメータの値によって異なります。 + `accept_type` が **text/csv** の場合、`label` はモデル出力に含まれる予測ラベルのインデックスです。 + `accept_type` が **application/jsonlines** または **application/json** の場合、`label` は予測ラベルを取得するためにモデル出力に適用される JMESPath 式です。 + **label\$1headers** – (オプション) ラベルがデータセットに取り込むことができる値の配列。バイアス分析が必要な場合は、モデル出力から対応する確率値 (スコア) を取得するために `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\$1series\$1predictor\$1config** – (オプション) 時系列の説明可能性にのみで使用します。`dataset_uri` で S3 URI として渡されたデータからデータを適切に解析する方法を SageMaker Clarify プロセッサに指示するために使用されます。 + **forecast** – 予測結果を抽出するために使用される JMESPath 式 ## 分析設定ファイルの例 次のセクションでは、CSV 形式と JSON 行形式のデータや、自然言語処理 (NLP) とコンピュータビジョン (CV) の説明可能性の両方の分析設定ファイルの例を説明します。 ### CSV データセットの分析設定 次の例は、CSV 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットには 4 つの特徴量列と 1 つの二項ラベル列、`Target` があります。データセットの内容は以下のようになります。ラベル値 `1` は 結果は肯定的な結果を示します。データセットは `dataset` 処理入力によって SageMaker Clarify ジョブに提供されます。 ``` "Target","Age","Gender","Income","Occupation" 0,25,0,2850,2 1,36,0,6585,0 1,22,1,1759,1 0,48,0,3446,1 ... ``` 次のセクションでは、CSV 形式のデータセットの特徴量重要度を示すトレーニング前およびトレーニング後のバイアスメトリクス、SHAP 値、部分依存プロット (PDP) を計算する方法を示します。 #### トレーニング前のバイアスメトリクスをすべて計算する この設定例は、前のサンプルデータセットが、**Gender** 値が `0` のサンプルに有利に偏っているかどうかを測定する方法を示しています。以下の分析設定は、SageMaker Clarify 処理ジョブにデータセットのすべてのトレーニング前バイアスメトリクスを計算するように指示します。 ``` { "dataset_type": "text/csv", "label": "Target", "label_values_or_threshold": [1], "facet": [ { "name_or_index": "Gender", "value_or_threshold": [0] } ], "methods": { "pre_training_bias": { "methods": "all" } } } ``` #### トレーニング前のバイアスメトリクスをすべて計算する トレーニング前のバイアスメトリクスはトレーニング前に計算できます。ただし、トレーニング後のバイアスメトリクスを計算するには、トレーニング済みのモデルが必要です。次の出力例は、データを CSV 形式で出力する二項分類モデルからのものです。この出力例では、各行に 2 つの列が含まれています。1 列目には予測ラベルが含まれ、2 列目にはそのラベルの確率値が含まれます。 ``` 0,0.028986845165491 1,0.825382471084594 ... ``` 以下の設定例は、SageMaker Clarify 処理ジョブにデータセットのあらゆるトレーニング前バイアスメトリクスを計算するように指示します。この例では、モデルは SageMaker AI エンドポイント `your_endpoint` にデプロイされます。 **注記** 次のコード例では、パラメータ `content_type` と `accept_type` は設定されていません。そのため、パラメータ dataset\$1type の値、つまり `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\$1model** という名前のモデルを指定する方法を示しています。SageMaker Clarify 処理ジョブは、設定を使用してシャドウエンドポイントを作成します。 ``` { ... "predictor": { "model_name": "your_model", "initial_instance_count": 1, "instance_type": "ml.m5.large", "probability": 1 } } ``` ### JSON Lines データセットの分析設定 次の例は、JSON Lines 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、SageMaker AI JSON Lines の高密度形式になっています。各行は有効な JSON オブジェクトです。 "Features" キーは特徴量値の配列を指し、"Label" キーはグラウンドトゥルースラベルを指します。データセットは "dataset" 処理入力によって SageMaker Clarify ジョブに提供されます。JSON 行の詳細については、「[JSONLINES リクエストの形式](cdf-inference.md#cm-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} ... ``` モデルは、`your_endpoint` という名前の SageMaker AI エンドポイントにデプロイできます。以下の分析設定例は、データセットとモデルのあらゆるバイアスメトリクスを計算するよう SageMaker Clarify 処理ジョブに指示しています。この例では、`content_type` パラメータと `accept_type` パラメータは設定されていません。そのため、dataset\$1type パラメータの値、つまり `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 データセットの分析設定 次の例は、JSON 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットのデータは前のセクションと同じですが、SageMaker AI JSON の高密度形式になっています。JSON 行の詳細については、「[JSONLINES リクエストの形式](cdf-inference.md#cm-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}, ... ] } ``` モデルは、`your_endpoint` という名前の SageMaker AI エンドポイントにデプロイできます。 次の例では、パラメータ `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\$11、ラベル ヘッダーには `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\$1model」という名前の 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 画像分類モデルを使用して説明可能性分析を設定する方法を示しています。この例では、`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](image-classification.md)」を参照してください。 この例では、[SageMaker AI オブジェクト検出モデル](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html)の `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 形式の時系列データセットです。このデータセットは、処理入力パラメータ `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 プロセッサに指示します。