翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# バイアス分析と説明可能性のための SageMaker Clarify 処理ジョブを実行する
SageMaker Clarify を使用してデータとモデルのバイアスと説明可能性を分析するには、SageMaker Clarify 処理ジョブを設定する必要があります。このガイドでは、SageMaker Python SDK API `SageMakerClarifyProcessor` を使用してジョブの入力、出力、リソース、分析設定を設定する方法を説明します。
この API は SageMaker AI `CreateProcessingJob` API の高レベルのラッパーとして機能します。SageMaker Clarify 処理ジョブの設定に関連する詳細の多くが隠されています。ジョブの設定の詳細には、SageMaker Clarify コンテナイメージ URI の取得と分析設定ファイルの生成が含まれます。以下の手順は SageMaker Clarify 処理ジョブを設定、初期化、起動する方法を示しています。
**API を使用して SageMaker Clarify 処理ジョブを設定する**
1. ジョブ設定の各部分の設定オブジェクトを定義します。これらの部分には、以下が含まれます。
+ 入力データセットと出力場所: [DataConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.DataConfig)。
+ 分析対象のモデルまたはエンドポイント: [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)。
+ バイアス分析パラメータ: [BiasConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.BiasConfig)。
+ SHapley Additive exPlanations (SHAP) 分析パラメーター: [SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig)。
+ 非対称 Shapley 値分析パラメータ (時系列のみ): [AsymmetricShapleyValueConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.AsymmetricShapleyValueConfig)
SageMaker Clarify 処理ジョブの設定オブジェクトは、データ形式やユースケースの種類によって異なります。次のセクションでは、[CSV](#clarify-processing-job-run-tabular-csv) 形式と [JSON Lines](#clarify-processing-job-run-tabular-jsonlines) 形式の表形式データ、自然言語処理 ([NLP](#clarify-processing-job-run-tabular-nlp))、[computer vision](#clarify-processing-job-run-cv) (CV)、時系列 (TS) の問題の設定例を説明します。
1. `SageMakerClarifyProcessor` オブジェクトを作成し、ジョブリソースを指定するパラメータで初期化します。これらのリソースには、使用するコンピューティングインスタンスの数などのパラメータが含まれます。
以下のコード例は、`SageMakerClarifyProcessor` オブジェクトを作成し、1 つの `ml.c4.xlarge` コンピューティングインスタンスを使用して分析を行うように指示する方法を示しています。
```
from sagemaker import clarify
clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=1,
instance_type='ml.c4.xlarge',
sagemaker_session=session,
)
```
1. [SageMakerClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor.run) オブジェクトの特定の実行メソッドをユースケースの設定オブジェクトとともに呼び出して、ジョブを起動します。これらの実行メソッドには、次のものがあります。
+ `run_pre_training_bias`
+ `run_post_training_bias`
+ `run_bias`
+ `run_explainability`
+ `run_bias_and_explainability`
この `SageMakerClarifyProcessor` がバックグラウンドでいくつかのタスクを処理します。これらのタスクには、SageMaker Clarify コンテナイメージのユニバーサルリソース識別子 (URI) の取得、提供された設定オブジェクトに基づく分析設定ファイルの作成、Amazon S3 バケットへのファイルのアップロード、[SageMaker Clarify 処理ジョブの設定](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)があります。
以下の展開可能なセクションでは、**トレーニング前**と**トレーニング後のバイアスメトリクス**、**SHAP 値**、**部分依存プロット** (PDPs) を計算する方法を示しています。各セクションでは、以下のデータ型における特徴量重要度を示しています。
+ CSV 形式または JSON Lines 形式の表形式データセット
+ 自然言語処理 (NLP) データセット
+ コンピュータービジョンデータセット
**Spark** を使用して分散トレーニングで SageMaker Clarify 処理ジョブを並行して実行するためのガイドは、展開可能なセクションの後にあります。
## CSV 形式の表形式データを設定する
次の例は、CSV 形式の表形式データセットのバイアス分析と説明可能性分析を設定する方法を示しています。これらの例では、受信データセットには 4 つの特徴量列と 1 つの二項ラベル列、`Target` があります データセットの内容は以下のようになります。ラベル値 `1` は 結果は肯定的な結果を示します。
```
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
...
```
この `DataConfig` オブジェクトは、入力データセットと出力の保存場所を指定します。`s3_data_input_path` パラメータは、データセットファイルの URI または Amazon S3 URI プレフィックスのいずれかになります。S3 URI プレフィックスを指定すると、SageMaker Clarify 処理ジョブは、プレフィクスの下にあるすべての S3 ファイルを再帰的に収集します。`s3_output_path` の値は、分析結果を格納するための S3 URI プレフィックスである必要があります。SageMaker AI はコンパイル中に `s3_output_path` を使用します。実行時に使用される SageMaker AI Pipeline パラメータ、プロパティ、式、または `ExecutionVariable` の値は取得できません。次のコード例は、前のサンプル入力データセットのデータ設定を指定する方法を示しています。
```
data_config = clarify.DataConfig(
s3_data_input_path=dataset_s3_uri,
dataset_type='text/csv',
headers=[{{'Target', 'Age', 'Gender', 'Income', 'Occupation'}}],
label='Target',
s3_output_path=clarify_job_output_s3_uri,
)
```
### CSV データセットのトレーニング前のバイアスメトリクスをすべて計算する方法
次のコードサンプルは、`Gender` 値が `0` のサンプルに対する前のサンプル入力のバイアスを測定するように `BiasConfig` オブジェクトを設定する方法を示しています。
```
bias_config = clarify.BiasConfig(
label_values_or_threshold=[1],
facet_name='{{Gender}}',
facet_values_or_threshold=[0],
)
```
以下のコード例は、run ステートメントを使用して、入力データセットのすべての[トレーニング前バイアスメトリクス](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html)を計算する SageMaker Clarify 処理ジョブを起動する方法を示しています。
```
clarify_processor.run_pre_training_bias(
data_config=data_config,
data_bias_config=bias_config,
methods="all",
)
```
または、トレーニング前のバイアス指標のリストをメソッドパラメータに割り当てて、計算するメトリクスを選択することもできます。例えば、`methods="all"` を `methods=["CI", "DPL"]` に置き換えると、SageMaker Clarify プロセッサは[クラスの不均衡](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-bias-metric-class-imbalance.html)と[ラベルの比率の差](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-data-bias-metric-true-label-imbalance.html)のみを計算するように指示されます。
### CSV データセットのトレーニング前バイアスメトリクスをすべて計算する方法
トレーニング前のバイアスメトリクスはトレーニング前に計算できます。ただし、[トレーニング後のバイアスメトリクス](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-post-training-bias.html)を計算するには、トレーニング済みのモデルが必要です。次の出力例は、データを CSV 形式で出力する二項分類モデルからのものです。この出力例では、各行に 2 つの列が含まれています。1 列目には予測ラベルが含まれ、2 列目にはそのラベルの確率値が含まれます。
```
0,0.028986845165491
1,0.825382471084594
...
```
次の設定例では、`ModelConfig` オブジェクトはジョブに SageMaker AI モデルをエフェメラルエンドポイントにデプロイするように指示します。エンドポイントは 1 つの `ml.m4.xlarge` 推論インスタンスを使用します。パラメータ `content_type` と `accept_type` は設定されていないため、自動的にパラメータ `dataset_type` の値、つまり `text/csv` が使用されます。
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
)
```
次の設定例では、ラベルインデックスが `ModelPredictedLabelConfig` の `0` オブジェクトを使用しています。これにより、SageMaker Clarify 処理ジョブは、モデル出力の最初の列で予測ラベルを検索するように指示されます。この例では、処理ジョブは 0 から始まるインデックスを使用しています。
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label=0,
)
```
前の設定例と組み合わせると、次のコード例は SageMaker Clarify 処理ジョブを起動して、トレーニング後のすべてのバイアスメトリクスを計算します。
```
clarify_processor.run_post_training_bias(
data_config=data_config,
data_bias_config=bias_config,
model_config=model_config,
model_predicted_label_config=predicted_label_config,
methods="all",
)
```
同様に、トレーニング後のバイアスメトリクスのリストを `methods` パラメータに割り当てて、計算するメトリクスを選択することもできます。例えば、`methods=“all”` を `methods=["DPPL", "DI"]` に置き換えると、[予測ラベルの正の割合の差](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-dppl.html)と[異種の影響](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-post-training-bias-metric-di.html)のみを計算します。
### CSV データセットのバイアスメトリクスをすべて計算する方法
以下の設定例は、1 つの SageMaker Clarify 処理ジョブでトレーニング前とトレーニング後のバイアスメトリクスをすべて実行する方法を示しています。
```
clarify_processor.run_bias(
data_config=data_config,
bias_config=bias_config,
model_config=model_config,
model_predicted_label_config=predicted_label_config,
pre_training_methods="all",
post_training_methods="all",
)
```
SageMaker Studio Classic で SageMaker Clarify 処理ジョブを実行してバイアスを検出する方法を説明したサンプルノートブックについては、「[Fairness and Explainability with SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)」を参照してください。
### CSV データセットの SHAP 値を計算する方法
SageMaker Clarify は [KernelSHAP アルゴリズム](https://arxiv.org/abs/1705.07874)を使用して特徴量の属性を提供します。SHAP 分析には予測ラベルの代わりに確率値またはスコアが必要なため、この `ModelPredictedLabelConfig` オブジェクトには確率インデックス `1` があります。これにより、SageMaker Clarify 処理ジョブは、モデル出力の 2 列目から確率スコアを (ゼロから始まるインデックス化を使用して) 抽出するように指示されます。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=1,
)
```
`SHAPConfig` オブジェクトは SHAP 分析パラメータを提供します。この例では、SHAP `baseline` パラメータは省略され、`num_clusters` パラメータの値は `1` です。これにより、SageMaker Clarify プロセッサは、入力データセットのクラスタリングに基づいて 1 つの SHAP ベースラインサンプルを計算するように指示します。ベースラインデータセットを選択する場合は、「[SHAP Baselines for Explainability](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html)」を参照してください。
```
shap_config = clarify.SHAPConfig(
num_clusters=1,
)
```
次のコード例は、SageMaker Clarify 処理ジョブを起動して SHAP 値を計算します。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=shap_config,
)
```
SageMaker Studio Classic で SageMaker Clarify 処理ジョブを実行して SHAP 値を計算する方法を説明したサンプルノートブックについては、「[Fairness and Explainability with SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)」を参照してください。
### CSV データセットの部分依存プロット (PDPs) を計算する方法
PDPs はその他すべての特徴量を一定に保ちながら、予測されるターゲットレスポンスが対象となる 1 つ以上の入力特徴量に依存することを示します。PDP における上向きの傾斜線または曲線は、ターゲット特徴量と入力特徴量の関係が正であることを示し、急勾配は関係の強さを示します。下向きの線または曲線は、入力特徴量が減少するとターゲット変数が増加することを示します。直感的に、部分依存を対象となる各入力特徴量に対するターゲット変数のレスポンスとして解釈できます。
以下の設定例は、`PDPConfig` オブジェクトを使用して SageMaker Clarify 処理ジョブに `Income` 特徴量の重要度を計算するように指示するためのものです。
```
pdp_config = clarify.PDPConfig(
features=["Income"],
grid_resolution=10,
)
```
前の例では、`grid_resolution` パラメータは `Income` 特徴量値の範囲を `10` バケットに分割しています。SageMaker Clarify 処理ジョブは、X 軸上で `10` セグメントに分割された `Income` の PDPs を生成します。Y 軸には、ターゲット変数に対する `Income` のわずかな影響が示されます。
次のコード例では、SageMaker Clarify 処理ジョブを起動して PDPs を計算します。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=pdp_config,
)
```
SageMaker Studio Classic で SageMaker Clarify 処理ジョブを実行して PDPs を計算する方法を説明したサンプルノートブックについては、「[Explainability with SageMaker Clarify - Partial Dependence Plots (PDP)](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb)」を参照してください。
### CSV データセットの SHAP 値と PDPs の両方を計算する方法
1 つの SageMaker Clarify 処理ジョブで SHAP 値と PDPs の両方を計算できます。以下の設定例では、新しい `PDPConfig` オブジェクトの `top_k_features` パラメータが `2` に設定されています。これにより、SageMaker Clarify 処理ジョブは、グローバル SHAP 値が最大である `2` つの特徴量の PDPs を計算するように指示されます。
```
shap_pdp_config = clarify.PDPConfig(
top_k_features=2,
grid_resolution=10,
)
```
次のコード例は、SageMaker Clarify 処理ジョブを起動して SHAP 値と PDPs の両方を計算します。
```
clarify_processor.run_explainability(
data_config=data_config,
model_config=model_config,
model_scores=probability_config,
explainability_config=[shap_config, shap_pdp_config],
)
```
## JSON Lines 形式の表形式データを設定する
次の例は、SageMaker AI JSON Lines の高密度形式の表形式データセットに対してバイアス分析と説明可能性分析を設定する方法を示しています。詳細については「[JSONLINES リクエストの形式](cdf-inference.md#cm-jsonlines)」を参照してください。これらの例では、受信データセットのデータは前のセクションと同じですが、JSON Lines 形式になっています。各行は有効な JSON オブジェクトです。`Features` キーは特徴量値の配列を指し、`Label` キーはグラウンドトゥルースラベルを指します。
```
{"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}
...
```
次の設定例では、`DataConfig` オブジェクトは入力データセットと出力を保存する場所を指定します。
```
data_config = clarify.DataConfig(
s3_data_input_path=jsonl_dataset_s3_uri,
dataset_type='application/jsonlines',
headers=['Age', 'Gender', 'Income', 'Occupation', 'Target'],
label='Label',
features='Features',
s3_output_path=clarify_job_output_s3_uri,
)
```
上記の設定例では、特徴量パラメータが [JMESPath](https://jmespath.org/) 式 `Features` に設定されているため、SageMaker Clarify 処理ジョブは各レコードから特徴量の配列を抽出できます。SageMaker Clarify 処理ジョブが各レコードからグラウンドトゥルースラベルを抽出できるように、`label` パラメータは JMESPath 式の `Label` に設定されます。`s3_data_input_path` パラメータは、データセットファイルの URI または Amazon S3 URI プレフィックスのいずれかになります。S3 URI プレフィックスを指定すると、SageMaker Clarify 処理ジョブは、プレフィクスの下にあるすべての S3 ファイルを再帰的に収集します。`s3_output_path` の値は、分析結果を格納するための S3 URI プレフィックスである必要があります。SageMaker AI はコンパイル中に `s3_output_path` を使用します。実行時に使用される SageMaker AI Pipeline パラメータ、プロパティ、式、または `ExecutionVariable` の値は取得できません。
トレーニング後のバイアスメトリクスまたは特徴量重要度を計算するには、トレーニング済みのモデルが必要です。次の例は、この例の形式で JSON Lines データを出力する二項分類モデルからのものです。モデル出力の各行は有効な JSON オブジェクトです。キー `predicted_label` は予測ラベルを指し、キー `probability` は確率値を指します。
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
以下の設定例では、`ModelConfig` オブジェクトが SageMaker Clarify 処理ジョブに SageMaker AI モデルをエフェメラルエンドポイントにデプロイするように指示しています。エンドポイントは 1 つの `ml.m4.xlarge` 推論インスタンスを使用します。
```
model_config = clarify.ModelConfig(
model_name=your_model,
instance_type='ml.m4.xlarge',
instance_count=1,
content_template='{"Features":$features}',
)
```
前の設定例では、パラメータ `content_type` と `accept_type` は設定されていません。そのため、`DataConfig` オブジェクトの `dataset_type` パラメータの値、つまり `application/jsonlines` が自動的に使用されます。SageMaker Clarify 処理ジョブは、`content_template` パラメータを使用して `$features` プレースホルダーを特徴量の配列に置き換えることでモデル入力を構成します。
以下の設定例は、`ModelPredictedLabelConfig` オブジェクトの label パラメータを JMESPath 式の `predicted_label` に設定する方法を示しています。これにより、モデルの出力から予測ラベルが抽出されます。
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label='predicted_label',
)
```
以下の設定例は、`ModelPredictedLabelConfig` オブジェクトの `probability` パラメータを JMESPath 式の `probability` に設定する方法を示しています。これにより、モデル出力からスコアが抽出されます。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
JSON Lines 形式のデータセットのバイアスメトリクスと特徴量重要度を計算するには、CSV データセットの前のセクションと同じ run ステートメントと設定オブジェクトを使用します。SageMaker Studio Classic で SageMaker Clarify 処理ジョブを実行すると、バイアスを検出して特徴量の重要度を計算できます。手順とノートブックの例については、「[Fairness and Explainability with SageMaker Clarify (JSON Lines Format)](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.ipynb)」を参照してください。
## NLP の説明可能性について表形式のデータを分析する
SageMaker Clarify は自然言語処理 (NLP) モデルの説明をサポートします。これらの説明は、テキストのどのセクションがモデル予測にとって最も重要かを理解するのに役立ちます。入力データセットの単一インスタンスのモデル予測、またはベースラインデータセットからのモデル予測のいずれかを説明できます。モデルの動作を理解して視覚化するために、複数の粒度レベルを指定できます。そのためには、テキストセグメントの長さ (トークン、センテンス、パラグラフなど) を定義します。
SageMaker Clarify の NLP の説明可能性は、分類モデルとリグレッションモデルの両方に対応しています。SageMaker Clarify を使用して、テキスト、カテゴリ、または数値の特徴量を含むマルチモーダルデータセットでのモデルの動作を説明することもできます。マルチモーダルデータセットに対する NLP の説明可能性は、各特徴量がモデルの出力にとってどれほど重要かを理解するのに役立ちます。SageMaker Clarify は 62 の言語に対応しており、複数の言語を含むテキストを処理できます。
次の例は、NLP の特徴量重要度を計算する分析設定ファイルを示しています。この例では、受信データセットは CSV 形式の表形式データセットで、1 つの二項ラベル列と 2 つの特徴量列があります。
```
0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...
```
次の設定例は、`DataConfig` オブジェクトを使用して CSV 形式の入力データセットと出力データパスを指定する方法を示しています。
```
nlp_data_config = clarify.DataConfig(
s3_data_input_path=nlp_dataset_s3_uri,
dataset_type='text/csv',
headers=['Target', 'Rating', 'Comments'],
label='Target',
s3_output_path=clarify_job_output_s3_uri,
)
```
上記の設定例では、`s3_data_input_path` パラメータデータセットファイルの URI または Amazon S3 URI プレフィックスのいずれかになります。S3 URI プレフィックスを指定すると、SageMaker Clarify 処理ジョブは、プレフィクスの下にあるすべての S3 ファイルを再帰的に収集します。`s3_output_path` の値は、分析結果を格納するための S3 URI プレフィックスである必要があります。SageMaker AI はコンパイル中に `s3_output_path` を使用します。実行時に使用される SageMaker AI Pipeline パラメータ、プロパティ、式、または `ExecutionVariable` の値は取得できません。
次の出力例は、前の入力データセットでトレーニングされた二項分類モデルから作成されたものです。分類モデルは CSV データを受け入れ、`0` と `1` の間の 1 つのスコアを出力します。
```
0.491656005382537
0.569582343101501
...
```
次の例は、SageMaker AI モデルを展開するように `ModelConfig` オブジェクトを設定する方法を示しています。この例では、エフェメラルエンドポイントがモデルをデプロイします。このエンドポイントは GPU を備えた `ml.g4dn.xlarge` 推論インスタンスを 1 つ使用して、推論を高速化します。
```
nlp_model_config = clarify.ModelConfig(
model_name=your_nlp_model_name,
instance_type='ml.g4dn.xlarge',
instance_count=1,
)
```
次の例は、インデックス `0` の最初の列に確率 (スコア) を配置するように `ModelPredictedLabelConfig` オブジェクトを設定する方法を示しています。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=0,
)
```
以下の SHAP 設定の例は、英語のモデルとデータセットを使用してトークンごとの説明可能性分析を実行する方法を示しています。
```
text_config = clarify.TextConfig(
language='english',
granularity='token',
)
nlp_shap_config = clarify.SHAPConfig(
baseline=[[4, '[MASK]']],
num_samples=100,
text_config=text_config,
)
```
前の例では、`TextConfig` オブジェクトが NLP 説明可能性分析を有効にします。`granularity` パラメータは、分析がトークンを解析する必要があることを示します。英語では、各トークンは単語です。その他の言語については、SageMaker Clarify が NLP 処理に使用している「[トークン化に関する spaCy のドキュメント](https://spacy.io/usage/linguistic-features#tokenization)」を参照してください。前の例では平均 `Rating` `4` を使用してインプレースの SHAP ベースラインインスタンスを設定する方法も示しています。特別なマスクトークン `[MASK]` は、`Comments` 内のトークン (単語) を置き換えるために使用します。
前の例では、インスタンスが`2,"Flavor needs work"` の場合、次のベースラインを使用してベースラインを平均 `Rating` `4` に設定します。
```
4, '[MASK]'
```
前の例では、SageMaker Clarify の explainer は各トークンを反復処理し、次のようにマスクに置き換えます。
```
2,"[MASK] needs work"
4,"Flavor [MASK] work"
4,"Flavor needs [MASK]"
```
次に、SageMaker Clarify の explainer が各行をモデルに送信して予測を行います。これは、explainer がマスクされた単語の有無にかかわらず予測を学習できるようにするためです。次に、SageMaker Clarify の explainer は、この情報を使用して各トークンの寄与度を計算します。
次のコード例は、SageMaker Clarify 処理ジョブを起動して SHAP 値を計算します。
```
clarify_processor.run_explainability(
data_config=nlp_data_config,
model_config=nlp_model_config,
model_scores=probability_config,
explainability_config=nlp_shap_config,
)
```
SageMaker Studio Classic で NLP 説明可能性分析のために SageMaker Clarify 処理ジョブを実行する方法を説明したサンプルノートブックについては、「[Explaining Text Sentiment Analysis Using SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/text_explainability/text_explainability.ipynb)」を参照してください。
## コンピュータービジョンの説明可能性について画像データを分析する
SageMaker Clarify は、コンピュータビジョンモデルが画像内のオブジェクトを分類して検出する方法についてのインサイトを提供するヒートマップを生成します。
次の設定の例では、入力データセットは JPEG 画像で構成されています。
```
cv_data_config = clarify.DataConfig(
s3_data_input_path=cv_dataset_s3_uri,
dataset_type="application/x-image",
s3_output_path=clarify_job_output_s3_uri,
)
```
上記の設定例では、`DataConfig` オブジェクトに Amazon S3 URI プレフィックスが指定された `s3_data_input_path` が含まれています。 SageMaker Clarify 処理ジョブはそのプレフィックスの下にあるすべての画像ファイルを再帰的に収集します。`s3_data_input_path` パラメータは、データセットファイルの URI または Amazon S3 URI プレフィックスのいずれかになります。S3 URI プレフィックスを指定すると、SageMaker Clarify 処理ジョブは、プレフィクスの下にあるすべての S3 ファイルを再帰的に収集します。`s3_output_path` の値は、分析結果を格納するための S3 URI プレフィックスである必要があります。SageMaker AI はコンパイル中に `s3_output_path` を使用します。実行時に使用される SageMaker AI Pipeline パラメータ、プロパティ、式、または `ExecutionVariable` の値は取得できません。
### 画像分類モデルの説明方法
SageMaker Clarify 処理ジョブは、KernelSHAP アルゴリズムを使用して画像を説明します。このアルゴリズムは、画像をスーパーピクセルの集合として扱います。画像で構成されるデータセットを指定すると、処理ジョブは画像のデータセットを出力します。各画像には、関連するスーパーピクセルのヒートマップが表示されます。
次の設定例は、SageMaker 画像分類モデルを使用して説明可能性分析を設定する方法を示しています。詳細については「[画像分類 - MXNet](image-classification.md)」を参照してください。
```
ic_model_config = clarify.ModelConfig(
model_name=your_cv_ic_model,
instance_type="ml.p2.xlarge",
instance_count=1,
content_type="image/jpeg",
accept_type="application/json",
)
```
前の設定例では、`your_cv_ic_model` という名前のモデルが、入力 JPEG 画像上の動物を分類するようにトレーニングされています。上記の例では、`ModelConfig` オブジェクトが SageMaker Clarify 処理ジョブに SageMaker AI モデルをエフェメラルエンドポイントにデプロイするように指示しています。エンドポイントは推論を高速化するために、GPU を備えた `ml.p2.xlarge` 推論インスタンスを 1 つ使用します。
JPEG 画像をエンドポイントに送信すると、エンドポイントはそれを分類してスコアのリストを返します。各スコアはカテゴリ用です。`ModelPredictedLabelConfig` オブジェクトは、次のように各カテゴリの名前を提供します。
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
先ほど入力した ['トリ', 'ネコ', 'イヌ'] の出力例は 0.3,0.6,0.1 です。0.3 は画像をトリとして分類する際の信頼度スコアを表します。
次の SHAP 設定例は、画像分類問題の説明を生成する方法を示しています。この方法では `ImageConfig` オブジェクトを使用して分析を開始します。
```
ic_image_config = clarify.ImageConfig(
model_type="IMAGE_CLASSIFICATION",
num_segments=20,
segment_compactness=5,
)
ic_shap_config = clarify.SHAPConfig(
num_samples=100,
image_config=ic_image_config,
)
```
SageMaker Clarify は、scikit-learn ライブラリから[単純線形反復クラスタリング (SLIC)](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) メソッドを使用して画像セグメンテーション用の特徴量を抽出します。先ほどの設定例である `model_type` パラメータは、画像分類問題のタイプを示しています。パラメータ `num_segments` は、入力画像でラベル付けされるおおよそのセグメント数を推定します。次に、セグメント数が slic `n_segments` パラメータに渡されます。
画像の各セグメントはスーパーピクセルと見なされ、各セグメントのローカル SHAP 値が計算されます。パラメータ `segment_compactness` は scikit-image slic メソッドによって生成される画像セグメントの形状とサイズを決定します。次に、画像セグメントのサイズと形状が slic `compactness` パラメータに渡されます。
次のコード例では、SageMaker Clarify 処理ジョブを起動して画像のヒートマップを生成します。ヒート マップの値が正の場合は、その特徴量がオブジェクト検出の信頼度スコアを高めたことを示しています。負の値は、その特徴量によって信頼度スコアが低下したことを示します。
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=ic_model_config,
model_scores=ic_prediction_config,
explainability_config=ic_shap_config,
)
```
SageMaker Clarify を使用して画像を分類し、その分類を説明するサンプルノートブックについては、「[Explaining Image Classification with SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb)」を参照してください。
### オブジェクト検出モデルを説明する方法
SageMaker Clarify 処理ジョブは、画像内のオブジェクトを検出して分類し、検出されたオブジェクトについて説明することができます。説明のプロセスは以下のとおりです。
1. 画像オブジェクトはまず、指定されたコレクション内のクラスのいずれかに分類されます。例えば、オブジェクト検出モデルがネコ、イヌ、サカナを認識できる場合、これらの 3 つのクラスはコレクションに含まれます。このコレクションは、`label_headers` パラメータによって次のように指定されます。
```
clarify.ModelPredictedLabelConfig(
label_headers=object_categories,
)
```
1. SageMaker Clarify 処理ジョブは、各オブジェクトの信頼スコアを生成します。信頼度スコアが高い場合は、そのオブジェクトが指定されたコレクション内のいずれかのクラスに属していることを示します。SageMaker Clarify 処理ジョブは、オブジェクトを区切る境界ボックスの座標も生成します。信頼スコアと境界ボックスの詳細については、「[レスポンスの形式](object-detection-in-formats.md#object-detection-recordio)」を参照してください。
1. 次に、SageMaker Clarify は画像シーン内のオブジェクトの検出についての説明を表示します。「**画像分類モデルの説明方法**」セクションで説明されている方法が使われます。
次の設定例では、SageMaker AI オブジェクト検出モデルの `your_cv_od_model` を JPEG 画像で画像上の動物を識別するようトレーニングしています。
```
od_model_config = clarify.ModelConfig(
model_name=your_cv_ic_model,
instance_type="ml.p2.xlarge",
instance_count=1,
content_type="image/jpeg",
accept_type="application/json",
)
```
上記の設定例では、`ModelConfig` オブジェクトが SageMaker Clarify 処理ジョブに SageMaker AI モデルをエフェメラルエンドポイントにデプロイするように指示しています。このエンドポイントはイメージングを高速化するために、GPU を備えた `ml.p2.xlarge` 推論インスタンスを 1 つ使用します。
次の設定例では、`ModelPredictedLabelConfig` オブジェクトが分類用の各カテゴリの名前を提供します。
```
ic_prediction_config = clarify.ModelPredictedLabelConfig(
label_headers=['bird', 'cat', 'dog'],
)
```
次の SHAP 設定例は、オブジェクト検出の説明を生成する方法を示しています。
```
od_image_config = clarify.ImageConfig(
model_type="OBJECT_DETECTION",
num_segments=20,
segment_compactness=5,
max_objects=5,
iou_threshold=0.5,
context=1.0,
)
od_shap_config = clarify.SHAPConfig(
num_samples=100,
image_config=image_config,
)
```
前の設定例では、`ImageConfig` オブジェクトが分析を有効にします。`model_type` パラメータは、問題のタイプがオブジェクト検出であることを示しています。その他のパラメータの詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
次のコード例では、SageMaker Clarify 処理ジョブを起動して画像のヒートマップを生成します。ヒート マップの値が正の場合は、その特徴量がオブジェクト検出の信頼度スコアを高めたことを示しています。負の値は、その特徴量によって信頼度スコアが低下したことを示します。
```
clarify_processor.run_explainability(
data_config=cv_data_config,
model_config=od_model_config,
model_scores=od_prediction_config,
explainability_config=od_shap_config,
)
```
SageMaker Clarify を使用して画像内のオブジェクトを検出し、その予測を説明するサンプルノートブックについては、「[Explaining object detection models with Amazon SageMaker AI Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb)」を参照してください。
## 時系列予測モデルの説明を分析する
次の例は、時系列予測モデルを説明するために SageMaker AI JSON 高密度形式でデータを設定する方法を紹介しています。JSON 形式の詳細については、「[JSON リクエストの形式](cdf-inference.md#cm-json)」を参照してください。
```
[
{
"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
},
]
```
### データの設定
次の設定例で示されるとおり、`TimeSeriesDataConfig` を使用すると、渡された入力データセットからデータを適切に解析する方法を説明可能性ジョブに伝達できます。
```
time_series_data_config = clarify.TimeSeriesDataConfig(
target_time_series='[].target_value',
item_id='[].item_id',
timestamp='[].timestamp',
related_time_series=['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
static_covariates=['[].static_feature_1', '[].static_feature_2'],
dataset_format='timestamp_records',
)
```
### 非対称 Shapley 値の設定
`AsymmetricShapleyValueConfig` を使用して、ベースライン、方向、粒度、サンプル数などの時系列予測モデル説明分析の引数を定義します。ベースライン値は、関連する時系列、静的共変量、ターゲット時系列の 3 つのタイプのデータすべてについて設定されます。`AsymmetricShapleyValueConfig` 設定は、SageMaker Clarify プロセッサに、一度に 1 つの項目の Feature Attribution を計算する方法を通知します。次の設定は、`AsymmetricShapleyValueConfig` の定義の例です。
```
asymmetric_shapley_value_config = AsymmetricShapleyValueConfig(
direction="chronological",
granularity="fine-grained",
num_samples=10,
baseline={
"related_time_series": "zero",
"static_covariates": {
"item1": [0, 0], "item2": [0, 0]
},
"target_time_series": "zero"
},
)
```
`AsymmetricShapleyValueConfig` に指定した値は、キー `asymmetric_shapley_value` を持つ `methods` のエントリとして分析設定に渡されます。
### モデルの設定
SageMaker Clarify プロセッサから送信されるペイロードの構造は制御できます。次のコードサンプルでは、`ModelConfig` 設定オブジェクトが時系列予測の説明可能性ジョブに、JMESPath 構文を使用してレコードを `'{"instances": $records}'` に集約するように指示します。各レコードの構造は、次の record\_template `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` で定義されます。`$start_time`、`$target_time_series`、`$related_time_series`、`$static_covariates` は、データセット値をエンドポイントリクエスト値にマッピングするために使用される内部トークンであることに注意が必要です。
```
model_config = clarify.ModelConfig(
model_name={{your_model}},
instance_type='ml.m4.xlarge',
instance_count=1,
record_template='{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}',
content_template='{"instances": $records}',,
time_series_model_config=TimeSeriesModelConfig(
forecast={'forecast': 'predictions[*].mean[:2]'}
)
)
```
同様に、`TimeSeriesModelConfig` の属性 `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]}
]
}
```
`forecast` に指定された JMESPath 式が {'predictions[\*].mean[:2]'}} の場合、予測値は次のとおり解析されます。
```
[[13.4, 3.6], [23.0, 4.7], [3.4, 5.6]]
```
## SageMaker Clarify 処理ジョブを並列実行する方法
大規模なデータセットを扱う場合、[Apache Spark](https://spark.apache.org/) を使用して SageMaker Clarify の処理ジョブの速度を上げることができます。Spark は、大規模データ処理のための統合分析エンジンです。SageMaker Clarify プロセッサごとに複数のインスタンスをリクエストすると、SageMaker Clarify は Spark の分散コンピューティング機能を使用します。
次の設定例は、`SageMakerClarifyProcessor` を使用して `5` つのコンピューティングインスタンスを持つ SageMaker Clarify プロセッサを作成する方法を示しています。`SageMakerClarifyProcessor` に関連付けられたジョブを実行するには、SageMaker Clarify は Spark 分散処理を使用します。
```
from sagemaker import clarify
spark_clarify_processor = clarify.SageMakerClarifyProcessor(
role=role,
instance_count=5,
instance_type='ml.c5.xlarge',
)
```
[SHAPConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SHAPConfig) の `save_local_shap_values` パラメータを `True` に設定すると、SageMaker Clarify 処理ジョブはローカル SHAP 値を複数のパーツファイルとしてジョブの出力場所に保存します。
ローカル SHAP 値を入力データセットインスタンスに関連付けるには、`DataConfig` の `joinsource` パラメータを使用します。コンピューティング インスタンスをさらに追加する場合は、エフェメラルエンドポイントの [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig) の `instance_count` も増やすことをお勧めします。これにより、Spark ワーカーの同時推論リクエストがエンドポイントに過剰な負荷をかけることを防ぎます。具体的には、エンドポイントと処理インスタンスの比率を 1 対 1 にすることをお勧めします。