`) を渡します。事実に関する知識アルゴリズムは、モデルが生成する応答を既知の応答と比較します。このアルゴリズムは、回答で区切り文字で区切られたコンテンツのいずれかが生成された場合、その回答を正解として評価します。`None` を `target_output_delimiter` として渡す場合、モデルは正解として採点される回答と同じ応答を生成する必要があります。最後に、`evaluate` メソッドを呼び出して、必要なパラメータを渡します。
事実に関する知識は、`EvalScore` オブジェクトのリストを返します。これには、「**Foundation model evaluation overview**」セクションで説明されているとおり、モデルが事実に基づく知識をどの程度エンコードできるかを示す集計スコアが含まれます。スコアの範囲は `0` から `1` で、スコアが最も低い場合、現実世界の事実に関する知識が最も浅いことを意味します。
次のサンプルコードは、事実に関する知識アルゴリズムを使用して LLM を評価する方法を説明しています。
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.factual_knowledge import FactualKnowledge, FactualKnowledgeConfig
eval_algo = FactualKnowledge(FactualKnowledgeConfig())
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### プロンプトのステレオタイプ
プロンプトのステレオタイプアルゴリズムを実行すると、オープンエンド生成を行うことができます。プロンプトステレオタイプアルゴリズムを実行するには、`DataConfig` で `sent_less_input_location` にステレオタイプ性がより低い文、`sent_more_output_location` にステレオタイプ性がより高い文を含む入力データセット内の列を特定する必要があります。`DataConfig` の詳細については、上記のセクション **2. を参照してください。[Configure (設定)`ModelRunner`**] をクリックします。次に、`evaluate` メソッドを呼び出して、必要なパラメータを渡します。
プロンプトのステレオタイプは、入力レコードごとのスコアとバイアスタイプごとの全体的なスコアを含む `EvalOutput` オブジェクトのリストを返します。スコアは、ステレオタイプ性がより高い文とステレオタイプ性がより低い文の確率を比較して計算されます。全体的なスコアは、モデルがステレオタイプ性がより高い文を優先した頻度をレポートします。確立が高い場合、ステレオタイプ性がより低い文よりもステレオタイプ性を優先すると、モデルはより高い確率を割り当てます。`0.5` のスコアは、モデルにバイアスがないこと、つまりステレオ性がより高い文やより低い文を優先する確率が同じ割合であることを示します。`0.5` より高いスコアの場合は、モデルがよりステレオタイプ性が高い応答を生成する可能性が高いことを示します。スコアが `0.5` 未満の場合は、モデルがステレオタイプ性がより低い応答を生成する可能性が高いことを示します。
次のサンプルコードは、プロンプトのステレオタイプアルゴリズムを使用して LLM を評価する方法を説明しています。
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.prompt_stereotyping import PromptStereotyping
eval_algo = PromptStereotyping()
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### セマンティックの頑健性
セマンティックの頑健性は、任意の FMEval タスクに対して実行できます。ただし、モデルは確定的である必要があります。確定的モデルとは、常に同じ入力に対して同じ出力を生成するモデルを指します。通常、デコードプロセスでランダムシードを設定することで確定的モデルを確保できます。次のとおり、さまざまなデータ入力タイプと問題に対応するために、アルゴリズムはタスクごとに異なります。
+ オープンエンド生成、質問への回答、またはタスク分類では、`GeneralSemanticRobustnessConfig` ファイルを使用して `GeneralSemanticRobustness` アルゴリズムを実行します。
+ テキスト要約タスクでは、`SummarizationAccuracySemanticRobustnessConfig` ファイルを使用して `SummarizationAccuracySemanticRobustness` アルゴリズムを実行します。
この `GeneralSemanticRobustness` アルゴリズムは、摂動モデル出力と摂動なしモデル出力の差を定量化する `0` から `1` の間の値を含む精度を含む `EvalScore` オブジェクトのリストを返します。一般的なセマンティックの頑健性アルゴリズムを実行するには、`GeneralSemanticRobustnessConfig` をインスタンス化し、`perturbation_type` を渡します。`perturbation_type` では、次のオプションのいずれかを選択できます。
+ `Butterfinger` – キーボードの距離に基づいて文字スワップを使用し、スペルミスを模倣する摂動。特定の文字が乱される確率を入力します。Butterfinger は、`perturbation_type` のデフォルト値です。
+ `RandomUpperCase` – 文字の一部を大文字に変更する摂動。`0` から `1` までの少数を入力します。
+ `WhitespaceAddRemove` – 空白文字が空白以外の文字の前に追加されて空白文字になる確率
次のパラメータも指定できます。
+ `num_perturbations` – 生成されたテキストに導入する各サンプルの摂動の数。デフォルトは `5` です。
+ `butter_finger_perturbation_prob` – 文字が摂動される確率。`perturbation_type` が `Butterfinger` である場合にのみ使用されます。デフォルトは `0.1` です。
+ `random_uppercase_corrupt_proportion` – 大文字に変更される文字の割合。`perturbation_type` が `RandomUpperCase` である場合にのみ使用されます。デフォルトは `0.1` です。
+ `whitespace_add_prob` – 空白がある場合、サンプルから削除される確率 `perturbation_type` が `WhitespaceAddRemove` である場合にのみ使用されます。デフォルトは `0.05` です。
+ `whitespace_remove_prob` – 空白文字以外がある場合、その前に空白が追加される確率 `perturbation_type` が `WhitespaceAddRemove` である場合にのみ使用されます。デフォルトは `0.1` です。
最後に、次のサンプルコードに示されるとおり、`evaluate` メソッドを呼び出して、必要なパラメータを渡します。
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.general_semantic_robustness import GeneralSemanticRobustness, GeneralSemanticRobustnessConfig
eval_algo = GeneralSemanticRobustness(GeneralSemanticRobustnessConfig(perturbation_type="RandomUpperCase",num_perturbations=2,random_uppercase_corrupt_proportion=0.3)))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
`SummarizationAccuracySemanticRobustness` アルゴリズムは、生成されたサマリーと参照サマリーの間の [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge)、[https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor)、[https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) の値の差 (つまりデルタ) を含む `EvalScore` オブジェクトのリストを返します。これらのスコアの詳細については、「[モデル評価ジョブでのプロンプトデータセットと利用可能な評価ディメンションの使用](clarify-foundation-model-evaluate-overview.md)」セクションの「**Text summarization**」セクションを参照してください。テキスト要約のセマンティックの頑健性アルゴリズムを実行するには、`SummarizationAccuracySemanticRobustnessConfig` をインスタンス化し、`perturbation_type` を渡します。
`perturbation_type` では、次のオプションのいずれかを選択できます。
+ `Butterfinger` – キーボードの距離に基づいて文字スワップを使用し、スペルミスを模倣する摂動。特定の文字が摂動する確率を入力します。`Butterfinger` は、`perturbation_type` のデフォルト値です。
+ `RandomUpperCase` – 文字の一部を大文字に変更する摂動。`0` から `1` までの少数を入力します。
+ `WhitespaceAddRemove` – 空白文字が空白以外の文字の前に追加されて空白文字になる確率を入力します。
次のパラメータも指定できます。
+ `num_perturbations` – 生成されたテキストに導入する各サンプルの摂動の数。デフォルトは `5` です。
+ `butter_finger_perturbation_prob` – 文字が摂動される確率。`perturbation_type` が `Butterfinger` である場合にのみ使用されます。デフォルトは `0.1` です。
+ `random_uppercase_corrupt_proportion` – 大文字に変更される文字の割合。`perturbation_type` が `RandomUpperCase` である場合にのみ使用されます。デフォルトは `0.1` です。
+ `whitespace_add_prob` – 空白がある場合、サンプルから削除される確率 `perturbation_type` が `WhitespaceAddRemove` である場合にのみ使用されます。デフォルトは `0.05` です。
+ `whitespace_remove_prob` – 空白文字以外がある場合、その前に空白が追加される確率 `perturbation_type` が `WhitespaceAddRemove` の場合にのみ使用されます。デフォルトは `0.1` です。
+ `rouge_type` – 生成された概要と参照サマリーを比較するメトリクス。評価で使用する [https://en.wikipedia.org/wiki/ROUGE_(metric)](https://en.wikipedia.org/wiki/ROUGE_(metric)) メトリクスのタイプを `rouge_type` に指定します。`rouge1`、`rouge2`、または `rougeL` を選択できます。これらのメトリクスは、生成されたサマリーを参照サマリーと比較します。ROUGE-1 は、重複するユニグラム (「the」、「is」などの 1 つの項目のシーケンス) を使用して比較します。ROUGE-2 は、生成されたサマリーと参照サマリーを bigram (「the large」、「is home」などの 2 つのシーケンスのグループ) を使用して比較します。ROUGE-L は、一致する単語の最長シーケンスを比較します。ROUGE の詳細については、「[ROUGE: A Package for Automatic Evaluation of Summaries](https://aclanthology.org/W04-1013.pdf)」を参照してください。
+ `user_stemmer_for_rouge` を `True` または `False` に設定します。ステマーは、比較する前に単語から接辞を削除します。ステマーは「swimming」と「swam」から接辞を削除するため、ステミング後には両方とも「swim」になります。
+ `model_type_for_bertscore` を、[https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) の計算に使用するモデルに設定します。[ROBERTA\$1MODEL](https://huggingface.co/docs/transformers/model_doc/roberta) またはさらに高度な [MICROSOFT\$1DEBERTA\$1MODEL](https://github.com/microsoft/DeBERTa) を選択できます。
次のサンプルコードに示されるとおり、`evaluate` メソッドを呼び出して、必要なパラメータを渡します。
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.summarization_accuracy_semantic_robustness import SummarizationAccuracySemanticRobustness, SummarizationAccuracySemanticRobustnessConfig
eval_algo = SummarizationAccuracySemanticRobustness(SummarizationAccuracySemanticRobustnessConfig(perturbation_type="Butterfinger",num_perturbations=3,butter_finger_perturbation_prob=0.2)))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
### 有害性
毒性アルゴリズムを実行して、オープンエンド生成、テキスト要約、または質問への回答を行うことができます。タスクに応じて 3 つの異なるクラスがあります。
+ オープンエンド生成タスクでは、`ToxicityConfig` ファイルを使用して、毒性アルゴリズムを実行します。
+ 要約には、`Summarization_Toxicity` クラス を使用します。
+ 質問への回答には、`QAToxicity` クラス を使用します。
毒性アルゴリズムは、`0` から `1` の間のスコアを含む `EvalScore` オブジェクトのリストを (毒性ディテクターにより異なる) 単数または複数返します。毒性アルゴリズムを実行するには、`ToxicityConfig` をインスタンス化して、`model_type` でモデルを評価するために使用する毒性モデルを渡します。`model_type` では、次のオプションを選択できます。
+ [`detoxify` for UnitaryAI Detoxify-unbiased](https://github.com/unitaryai/detoxify) は、[Toxic Comment Classification Challenge](https://www.kaggle.com/c/jigsaw-toxic-comment-classification-challenge) と [Jigsaw Unintended Bias in Toxicity Classification](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification) でトレーニングされたマルチラベルテキスト分類子です。このモデルは、毒性、重度の毒性、わいせつ、脅威、侮辱、性的に露骨な表現、アイデンティティ攻撃の `7` つのクラスについてスコアを提供します。
毒性モデルの出力サンプルは、以下のとおりです。
```
EvalScore(name='toxicity', value=0.01936926692724228),
EvalScore(name='severe_toxicity', value=3.3755677577573806e-06),
EvalScore(name='obscene', value=0.00022437423467636108),
EvalScore(name='identity_attack', value=0.0006707844440825284),
EvalScore(name='insult', value=0.005559926386922598),
EvalScore(name='threat', value=0.00016682750720065087),
EvalScore(name='sexual_explicit', value=4.828436431125738e-05)
```
+ [`toxigen` for Toxigen-roberta](https://github.com/microsoft/TOXIGEN) は、ToxiGen データセットでファインチューニングされた、二項の RoBERTa ベースのテキスト分類子で、`13` のマイノリティグループに関する暗黙的および気づきにくい毒性のある文が含まれます。
最後に、次のサンプルコードに示されるとおり、`evaluate` メソッドを呼び出して、必要なパラメータを渡します。
```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.toxicity import Toxicity, ToxicityConfig
eval_algo = Toxicity(ToxicityConfig(model_type="detoxify"))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```
# モデル評価の結果
LLM の精度メトリクスは、モデルがプロンプトにどの程度適切に応答したかを表す数値です。ただし、数値では人間の言語の複雑さを捉えきれない場合があります。タスクごとに、さまざまな側面に沿って回答の質を測定するように設計された精度メトリクスのレポートを取得できます。例えば、再現率はモデル出力に適切な回答が含まれているかどうかを測定し、精度はモデル回答がどの程度冗長であるかを示します。モデルが必要とする出力を提供しているかを判断するには、複数のメトリクスを比較し、可能な場合は定性評価 (つまり、手動によるサンプルの調査) と組み合わせる必要があります。
**Example 質問への回答タスクタイプの精度**
この例では、モデルの応答のコンテキストで精度メトリクスを把握する方法と、モデルの応答の冗長性を把握する方法について説明します。
この例は、`huggingface-llm-falcon-40b-bf16` モデルに基づいた方法を使用しています。
```
Prompt: When was the movie Inception released?
Target output: July 16, 2010
Model output: \nInception was released on July 16, 2010.\nWhen was the movie Inception released?\nInception was released on July 16, 2010.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who are able to enter people's dreams and steal their ideas.\nWhat is the movie Inception rated?\nInception is rated PG-13.\nWhat is the movie Inception about?\nInception is about a group of people who“
```
この応答をスコアリングするには、各計算メトリクスに基づいて分解します。
+ モデルが適切な出力を返したため、`recall_over_words` は 1.0 です。
+ *ターゲット出力*と比較して応答が非常に冗長であるため、`precision_over_words` が低く (0.11) なります。
+ 精度と再現率を組み合わせた `f1_score` は、低く (0.19) なります。
+ 他のすべての精度メトリクスのモデル出力スコアは 0.0 です。
これらの計算されたメトリクスを見ると、ターゲット出力は応答で返されたとはいえ、応答は全体的に冗長であったと結論付けることができます。
次のレーダープロットに表示されるスコアも確認できます。
![\[返されたメトリクスごとのレーダープロットを示す画像\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/radar-plot-example-01.png)
**Example 質問への回答タスクタイプの精度**
この例では、ターゲット出力を返すことが困難なモデルの例を説明しています。
```
Prompt: Who are some influential people in the field of technology?
Target output: Influential people in technology include Bill Gates, Steve Jobs, Mark Zuckerberg, Elon Musk, and others.
Model output: I would say that the most influential person in the field of technology is Steve Jobs. He has changed the way we use technology.\nSteve Jobs is a good one. I would also say Bill Gates. He has changed the way we use computers.
```
このモデル出力はターゲット出力と完全には一致しないため、`exact_match_score` と `quasi_exact_match_score` は両方とも 0 と評価されています。モデルの出力にはターゲット出力のほぼ半分の単語が含まれているため、`recall_over_words` は、0.47 になります。ターゲット出力にはモデル出力の単語の約 4 分の 1 が含まれているため、`precision_over_words` は、0.27 になります。したがって、`f1_score ` がレポートする 2 つの幾何平均は、0.34 となります。スコアは、次のレーダープロットに表示されます。
![\[返されたメトリクスごとのレーダープロットを示す画像\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/radar-plot-example-02.png)
**Example 質問と回答のペアの精度スコアが適切でない場合**
この例では、モデルはターゲット出力を含まない出力で応答しています。
```
Prompt: Who is the greatest musician of all time?
Target output: Michael Jackson
Model output: "\nWho is the greatest musician of all time?\nThe 50 Greatest Musicians of All Time\n- 1. Bob Dylan.\n- 2. The Beatles.\n- 3. Jimi Hendrix.\n- 4. Aretha Franklin.\n- 5. Elvis Presley.\n- 6. Marvin Gaye.\n- 7. Ray Charles.\n- 8. John Lennon.\nWho is the most famous musician in the world?\nThe 10 Most Famous Musicians in the World\n- Beyonc\u00e9.\n- Taylor Swift.\n- Drake.\n- Ed Sheeran.\n- Rihanna.\n- Justin Bieber.\n- Lady Gaga.\n- The Weeknd.\nWho is the most famous singer in the world 2020?\nTop 10 Most Popular Singers in the World 2020\n- Justin Bieber.\n- Ed Sheeran.\n- Drake.\n- Rihanna.\n- Ariana Grande.\n- Taylor Swift.\n- Beyonce.\n- Bruno Mars.\nWho is the most famous singer in the world 2019?\nTop 10 Most Popular Singers in the World 2019\n- Justin Bieber.\n- Ed Sheeran“
```
この例では、質問とターゲットの出力はいずれも主観的でした。このモデルの応答では、プロンプトと類似した質問とその回答を返されています。モデルは、提供された主観的な回答を返さなかったため、下に示されるとおり、この出力はすべての精度メトリクスで 0.0 のスコアとなりました。この質問の主観的な性質を考慮すると、人間による追加の評価を行うことをお勧めします。
# モデル評価ジョブの結果を理解する
以降のセクションでは、モデル評価ジョブの結果を解釈する方法について説明します。Amazon S3 に保存される出力 JSON データは、自動モデル評価ジョブとヒューマンベースのモデル評価ジョブの両方で異なります。Studio を使用すると、ジョブの結果が Amazon S3 に保存される場所を確認できます。これを行うには、Studio で**[モデル評価]** のホームページを開き、テーブルからジョブを選択します。
## Studio でのモデル評価の結果の確認
モデル評価ジョブが完了後、次の手順を使用して、指定したデータセットに対してモデルがどのように実行されたかを確認できます。
1. Studio ナビゲーションペインで、**[ジョブ]**、**[モデル評価]** の順に選択します。
1. **[モデル評価]** ページで、送信が正常に完了したジョブがリストに表示されます。このリストには、ジョブ名、ステータス、モデル名、評価タイプ、作成日が記載されています。
1. モデル評価が正常に完了した場合、ジョブ名をクリックすると評価結果の概要を確認できます。
1. 人間による分析のレポートを表示するには、調査するジョブの名前をクリックします。
モデル評価結果の解釈については、結果を解釈するモデル評価ジョブのタイプに対応するトピックを参照してください。
+ [人間による評価ジョブの結果を理解する](clarify-foundation-model-evaluate-results-human.md)
+ [自動評価ジョブの結果を理解する](clarify-foundation-model-evaluate-auto-ui-results.md)
# 人間による評価ジョブの結果を理解する
ヒューマンワーカーを使用するモデル評価ジョブを作成する際は、単数または複数の*メトリクスタイプ*を選択することは説明しました。作業チームのメンバーがワーカーポータルで応答を評価すると、その応答は `humanAnswers` JSON オブジェクトに保存されます。このような応答の保存方法は、ジョブの作成時に選択したメトリクスタイプによって異なります。
以下のセクションでは、これらの違いを説明し、例を紹介します。
## JSON 出力のリファレンス
モデル評価ジョブが完了すると、結果は JSON ファイルとして Amazon S3 に保存されます。JSON オブジェクトには、`humanEvaluationResult`、`inputRecord`、`modelResponses` の 3 つの高レベルノードが含まれます。`humanEvaluationResult` キーは、モデル評価ジョブに割り当てられた作業チームからの応答を含む高レベルノードです。`inputRecord` キーは、モデル評価ジョブの作成時にモデルに提供されるプロンプトを含む高レベルノードです。`modelResponses` キーは、モデルからのプロンプトに対する応答を含む高レベルノードです。
次の表では、モデル評価ジョブからの JSON 出力で確認できるキー値のペアをまとめています。
以降のセクションでは、各キー値のペアについて、さらに詳しく説明します。
****
| パラメータ | 例 | 説明 |
| --- | --- | --- |
| `flowDefinitionArn` | arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name | ヒューマンループを作成した、人間によるレビューワークフロー (フロー定義) の ARN |
| humanAnswers | 選択した評価メトリクスに固有の JSON オブジェクトのリスト。詳細については、「[`humanAnswers` で確認できるキー値のペア](#clarify-foundation-model-evaluate-humanAnswers)」を参照してください。 | ワーカーの応答を含む JSON オブジェクトのリスト |
| `humanLoopName` | system-generated-hash | システムは 40 文字の 16 進数文字列を生成。 |
| inputRecord | "inputRecord": {
"prompt": {
"text": "Who invented the airplane?"
},
"category": "Airplanes",
"referenceResponse": {
"text": "Orville and Wilbur Wright"
},
"responses":
[{
"modelIdentifier": "meta-textgeneration-llama-codellama-7b",
"text": "The Wright brothers, Orville and Wilbur Wright are widely credited with inventing and manufacturing the world's first successful airplane."
}]
} | 入力データセットからのエントリプロンプトを含む JSON オブジェクト。 |
| modelResponses | "modelResponses": [{
"modelIdentifier": "arn:aws:bedrock:us-west-2::foundation-model/model-id",
"text": "the-models-response-to-the-prompt"
}] | モデルからの個々のレスポンス。 |
| inputContent | {
"additionalDataS3Uri":"s3://user-specified-S3-URI-path/datasets/dataset-name/records/record-number/human-loop-additional-data.json",
"evaluationMetrics":[
{
"description":"brief-name",
"metricName":"metric-name",
"metricType":"IndividualLikertScale"
}
],
"instructions":"example instructions"
} | Amazon S3 バケットでヒューマンループを開始するために必要なヒューマンループ入力コンテンツ |
| modelResponseIdMap | {
"0": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612",
"1": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
} | `answerContent` での各モデルの提示方法の説明 |
### `humanEvaluationResult` で確認できるキー値のペア
次のキー値のペアは、モデル評価ジョブの出力の `humanEvaluationResult` の下にあります。
`humanAnswers` に関連付けられたキー値のペアについては、「[`humanAnswers` で確認できるキー値のペア](#clarify-foundation-model-evaluate-humanAnswers)」を参照してください。
**`flowDefinitionArn`**
+ モデル評価ジョブの実行に使用されるフロー定義の ARN
+ *例*`arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name`:
**`humanLoopName`**
+ システムは 40 文字の 16 進数文字列を生成。
**`inputContent`**
+ このキー値は、*メトリクスタイプ*と、ワーカーポータルでワーカーに提供した指示の説明です。
+ `additionalDataS3Uri`: ワーカーへの指示が保存される Amazon S3 の場所
+ `instructions`: ワーカーポータルでワーカーに提供した手順
+ `evaluationMetrics`: メトリクスの名前と説明。キー値 `metricType` は、モデルの応答を評価するためにワーカーに提供されるツールです。
**`modelResponseIdMap`**
+ このキー値ペアは、選択したモデルの完全な名前と、ワーカーの選択がキー値ペア `humanAnswers` のモデルにどのようにマッピングされるかを特定します。
### `inputRecord` で確認できるキー値のペア
次のエントリでは、キー値のペア `inputRecord` について説明します。
**`prompt`**
+ モデルに送信されたプロンプトのテキスト
**`category`**
+ プロンプトを分類するオプションのカテゴリ。モデル評価中にワーカーポータルのワーカーに表示されます。
+ *例*`"American cities"`:
**`referenceResponse`**
+ 評価中にワーカーが参照するグラウンドトゥルースを指定するために使用される入力 JSON のオプションフィールド
**`responses`**
+ 他のモデルからの応答を含む入力 JSON のオプションフィールド
JSON 入力レコードの例
```
{
"prompt": {
"text": "Who invented the airplane?"
},
"category": "Airplanes",
"referenceResponse": {
"text": "Orville and Wilbur Wright"
},
"responses":
// The same modelIdentifier must be specified for all responses
[{
"modelIdentifier": "meta-textgeneration-llama-codellama-7b" ,
"text": "The Wright brothers, Orville and Wilbur Wright are widely credited with inventing and manufacturing the world's first successful airplane."
}]
}
```
### `modelResponses` で確認できるキー値のペア
モデルからの応答と、応答を提供したモデルを含むキー値ペアの配列
**`text`**
+ プロンプトに対するモデルの応答
**`modelIdentifier`**
+ モデルの名前です。
### `humanAnswers` で確認できるキー値のペア
モデルからの応答とワーカーがモデルを評価した方法を含むキー値ペアの配列
**`acceptanceTime`**
+ ワーカーポータルでワーカーがタスクを受け入れた時刻
**`submissionTime`**
+ ワーカーが応答を送信した時刻
**`timeSpentInSeconds`**
+ ワーカーがタスクの完了までに費やした期間
**`workerId`**
+ タスクを完了したワーカーの ID
**`workerMetadata`**
+ このモデル評価ジョブに割り当てられた作業チームに関するメタデータ
#### `answerContent` JSON 配列の形式
回答の構造は、モデル評価ジョブの作成時に選択された評価メトリクスによって異なります。各ワーカーの応答または回答は、新しい JSON オブジェクトに記録されます。
**`answerContent`**
+ `evaluationResults` にはワーカーの応答が含まれます。
+ **[選択ボタン]** をクリックすると、各ワーカーの結果は `"evaluationResults": "comparisonChoice"` になります。
`metricName`: メトリクスの名前
`result`: この JSON オブジェクトは、ワーカーが `0` または `1` を使用して選択したモデルを示します。モデルがどの値を表示するようにマッピングされているかを確認するには、「`modelResponseIdMap`」を参照してください。
+ **[リッカート尺度 - 比較]** をクリックすると、各ワーカーの結果は `"evaluationResults": "comparisonLikertScale"` になります。
`metricName`: メトリクスの名前
`leftModelResponseId`: ワーカーポータルの左側に表示される `modelResponseIdMap` を示します。
`rightModelResponseId`: ワーカーポータルの左側に表示される `modelResponseIdMap` を示します。
`result`: この JSON オブジェクトは、ワーカーが `0` または `1` を使用して選択したモデルを示します。モデルがどの値を表示するようにマッピングされているかを確認するには、「`modelResponseIdMap`」を参照してください
+ **[順序ランク]** をクリックすると、各ワーカーの結果は `"evaluationResults": "comparisonRank"` になります。
`metricName`: メトリクスの名前
`result`: JSONオブジェクトの配列 各モデル (`modelResponseIdMap`) に対して、ワーカーは `rank` を提供します。
```
"result": [{
"modelResponseId": "0",
"rank": 1
}, {
"modelResponseId": "1",
"rank": 1
}]
```
+ **単一のモデル応答の評価であるリッカート尺度**が選択されると、ワーカーの結果は `"evaluationResults": "individualLikertScale"` に保存されます。これは、ジョブの作成時に指定された `metricName` のスコアを含む JSON 配列です。
`metricName`: メトリクスの名前
`modelResponseId`: スコアリングされるモデル モデルがどの値を表示するようにマッピングされているかを確認するには、「`modelResponseIdMap`」を参照してください。
`result`: ワーカーが選択したリッカート尺度を示すキー値のペア
+ **[親指を上げる/下げる]** を選択すると、ワーカーの結果は JSON 配列 `"evaluationResults": "thumbsUpDown"` として保存されます。
`metricName`: メトリクスの名前
`result`: `metricName` に関連する `true` または `false` のいずれか。ワーカーが [親指を上げる] を選択した場合は、`"result" : true`
## モデル評価ジョブ出力からの出力の例
次の JSON オブジェクトは、Amazon S3 に保存されるモデル評価ジョブ出力の例です。各キー値のペアの詳細については、「[JSON 出力のリファレンス](#clarify-foundation-model-evaluate-results-human-ref)」を参照してください。
理解しやすいように、このジョブには 2 人のワーカーからの応答のみが含まれています。キー値のペアによっては、読みやすいように、省略されているものもあります。
```
{
"humanEvaluationResult": {
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanAnswers": [
{
"acceptanceTime": "2024-06-07T22:31:57.066Z",
"answerContent": {
"evaluationResults": {
"comparisonChoice": [
{
"metricName": "Fluency",
"result": {
"modelResponseId": "0"
}
}
],
"comparisonLikertScale": [
{
"leftModelResponseId": "0",
"metricName": "Coherence",
"result": 1,
"rightModelResponseId": "1"
}
],
"comparisonRank": [
{
"metricName": "Toxicity",
"result": [
{
"modelResponseId": "0",
"rank": 1
},
{
"modelResponseId": "1",
"rank": 1
}
]
}
],
"individualLikertScale": [
{
"metricName": "Correctness",
"modelResponseId": "0",
"result": 2
},
{
"metricName": "Correctness",
"modelResponseId": "1",
"result": 3
},
{
"metricName": "Completeness",
"modelResponseId": "0",
"result": 1
},
{
"metricName": "Completeness",
"modelResponseId": "1",
"result": 4
}
],
"thumbsUpDown": [
{
"metricName": "Accuracy",
"modelResponseId": "0",
"result": true
},
{
"metricName": "Accuracy",
"modelResponseId": "1",
"result": true
}
]
}
},
"submissionTime": "2024-06-07T22:32:19.640Z",
"timeSpentInSeconds": 22.574,
"workerId": "ead1ba56c1278175",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_WxGLvNMy4",
"sub": "cd2848f5-6105-4f72-b44e-68f9cb79ba07"
}
}
},
{
"acceptanceTime": "2024-06-07T22:32:19.721Z",
"answerContent": {
"evaluationResults": {
"comparisonChoice": [
{
"metricName": "Fluency",
"result": {
"modelResponseId": "1"
}
}
],
"comparisonLikertScale": [
{
"leftModelResponseId": "0",
"metricName": "Coherence",
"result": 1,
"rightModelResponseId": "1"
}
],
"comparisonRank": [
{
"metricName": "Toxicity",
"result": [
{
"modelResponseId": "0",
"rank": 2
},
{
"modelResponseId": "1",
"rank": 1
}
]
}
],
"individualLikertScale": [
{
"metricName": "Correctness",
"modelResponseId": "0",
"result": 3
},
{
"metricName": "Correctness",
"modelResponseId": "1",
"result": 4
},
{
"metricName": "Completeness",
"modelResponseId": "0",
"result": 1
},
{
"metricName": "Completeness",
"modelResponseId": "1",
"result": 5
}
],
"thumbsUpDown": [
{
"metricName": "Accuracy",
"modelResponseId": "0",
"result": true
},
{
"metricName": "Accuracy",
"modelResponseId": "1",
"result": false
}
]
}
},
"submissionTime": "2024-06-07T22:32:57.918Z",
"timeSpentInSeconds": 38.197,
"workerId": "bad258db224c3db6",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_WxGLvNMy4",
"sub": "84d5194a-3eed-4ecc-926d-4b9e1b724094"
}
}
}
],
"humanLoopName": "a757 11d3e75a 8d41f35b9873d 253f5b7bce0256e",
"inputContent": {
"additionalDataS3Uri": "s3://mgrt-test-us-west-2/test-2-workers-2-model/datasets/custom_dataset/0/task-input-additional-data.json",
"instructions": "worker instructions provided by the model evaluation job administrator",
"evaluationMetrics": [
{
"metricName": "Fluency",
"metricType": "ComparisonChoice",
"description": "Measures the linguistic quality of a generated text."
},
{
"metricName": "Coherence",
"metricType": "ComparisonLikertScale",
"description": "Measures the organization and structure of a generated text."
},
{
"metricName": "Toxicity",
"metricType": "ComparisonRank",
"description": "Measures the harmfulness of a generated text."
},
{
"metricName": "Accuracy",
"metricType": "ThumbsUpDown",
"description": "Indicates the accuracy of a generated text."
},
{
"metricName": "Correctness",
"metricType": "IndividualLikertScale",
"description": "Measures a generated answer's satisfaction in the context of the question."
},
{
"metricName": "Completeness",
"metricType": "IndividualLikertScale",
"description": "Measures a generated answer's inclusion of all relevant information."
}
],
"disableRandomization": "true"
},
"modelResponseIdMap": {
"0": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612",
"1": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
}
},
"inputRecord": {
"prompt": {
"text": "What is high intensity interval training?"
},
"category": "Fitness",
"referenceResponse": {
"text": "High-Intensity Interval Training (HIIT)"
}
},
"modelResponses": [
{
"text": "High Intensity Interval Training (HIIT) is a form of exercise that alternates between periods of high intensity work and low intensity recovery.HIIT is an excellent way to increase your fitness and improve your health, but it can be difficult to get started.In this article, we will",
"modelIdentifier": "sm-margaret-meta-textgeneration-llama-2-7b-1711485008-0612"
},
{
"text": "High intensity interval training is a form of exercise consisting of short bursts of maximum effort followed by periods of rest. The theory behind HIIT is that it can often be more effective at improving cardiovascular and metabolic health than longer, lower intensity workouts.The work intervals can range in length depending on the specific type of exercise, but are typically between 20 and 90 seconds. The recovery periods are generally longer, lasting between 1 and 5 minutes. This pattern is then repeated for multiple sets.\n\nSince the work intervals are high intensity, they require more effort from your body and therefore result in a greater calorie burn. The body also continues to burn calories at an increased rate after the workout due to an effect called excess post exercise oxygen consumption (EPOC), also know as the afterburn effect.\n\nHIIT is a versatile form of training that can be adapted to different fitness levels and can be performed using a variety of exercises including cycling, running, bodyweight movements, and even swimming. It can be done in as little as 20 minutes once or twice a week, making it an efficient option for busy individuals.\n\nWhat are the benefits of high intensity interval training",
"modelIdentifier": "jumpstart-dft-hf-llm-mistral-7b-ins-20240327-043352"
}
]
}
```
# 自動評価ジョブの結果を理解する
自動モデル評価ジョブが完了すると、結果は Amazon S3 に保存されます。以下のセクションでは、生成されるファイルとその解釈方法について説明します。
## `output.json` ファイルの構造を解釈する
`output.json` ファイルには、選択したデータセットとメトリクスの集計スコアが含まれます。
出力の例は、次のとおりです。
```
{
"evaluations": [{
"evaluation_name": "factual_knowledge",
"dataset_name": "trex",
## The structure of the prompt template changes based on the foundation model selected
"prompt_template": "[INST] <>Answer the question at the end in as few words as possible. Do not repeat the question. Do not answer in complete sentences.< Question: $feature [/INST]",
"dataset_scores": [{
"name": "factual_knowledge",
"value": 0.2966666666666667
}],
"category_scores": [{
"name": "Author",
"scores": [{
"name": "factual_knowledge",
"value": 0.4117647058823529
}]
},
....
{
"name": "Capitals",
"scores": [{
"name": "factual_knowledge",
"value": 0.2857142857142857
}]
}
]
}]
}
```
## インスタンス単位の結果ファイルの構造を解釈する
各 jsonlines リクエストのインスタンス単位の結果は、1 つの *evaluation\$1name*\$1*dataset\$1name*.jsonl ファイルに含まれます。jsonlines 入力データに `300` のリクエストがある場合、この jsonlines 出力ファイルには `300` の応答が含まれます。出力ファイルには、モデルに対して行われたリクエストとその評価のスコアが含まれます。インスタンス単位の出力の例は、以下のとおりです。
## レポートの解釈
**評価レポート**には、基盤モデル評価ジョブの結果が含まれます。評価レポートのコンテンツは、モデル評価に使用したタスクのタイプによって異なります。各レポートには、次のセクションが含まれます。
1. 評価タスクで適切となった各評価の**全体的なスコア**。単一のデータセットを使用した単一の評価の例として、分類タスクのモデルを精度とセマンティックの頑健性について評価した場合、精度と精度のセマンティックの頑健性の評価結果をまとめた表がレポートの上部に表示されます。別のデータセットを使用した別の評価では、構造が異なる場合があります。
1. モデル名、タイプ、使用された評価方法、モデル評価対象で使用したデータセットなどの評価ジョブの設定。
1. 評価アルゴリズムの概要、組み込みデータセットに関する情報とリンク、スコアの計算方法、サンプルデータと関連するスコアを含むテーブルを提供する **[詳細な評価結果]** セクション。
1. 完了しなかった評価のリストを含む **[失敗した評価]** セクション。失敗した評価がない場合は、レポートのこのセクションは省略されます。
# `fmeval` ライブラリを使用してワークフローをカスタマイズする
モデル評価をカスタマイズして、JumpStart または Amazon Bedrock モデル以外のモデルを許可したり、評価にカスタムワークフローを使用したりすることができます。独自のモデルを使用する場合、カスタム `ModelRunner` を作成する必要があります。評価に独自のデータセットを使用する場合は、`DataConfig` オブジェクトを設定する必要があります。次のセクションでは、入力データセットをフォーマットし、カスタムデータセットを使用するように `DataConfig` オブジェクトをカスタマイズして、カスタム `ModelRunner` を作成する方法について説明します。
## カスタム入力データセットを使用する
独自のデータセットを使用してモデルを評価する場合、`DataConfig` オブジェクトを使用して、評価するデータセットの `dataset_uri` と `dataset_name` を指定する必要があります。組み込みデータセットを使用する場合、`DataConfig` オブジェクトは評価アルゴリズムのデフォルトとして事前設定済みです。
`evaluate` 関数を使用する場合は毎回単一のカスタムデータセットを使用できます。`evaluate` は何度でも呼び出すことができ、必要な数のデータセットを使用できます。
次のとおり、質問列にモデルリクエストを指定し、回答列にターゲット回答を指定して、カスタムデータセットを設定します。
```
from fmeval.data_loaders.data_config import DataConfig
from fmeval.constants import MIME_TYPE_JSONLINES
config = DataConfig(
dataset_name="tiny_dataset",
dataset_uri="tiny_dataset.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
model_input_location="question",
target_output_location="answer",
)
```
`DataConfig` クラスには、以下のパラメータが含まれています。
+ `dataset_name` – LLM の評価に使用するデータセットの名前
`dataset_uri` – データセットの S3 の場所へのローカルパスまたは Uniform Resource Identifier (URI)
+ `dataset_mime_type` – LLM の評価に使用する入力データの形式。FMEval ライブラリは、`MIME_TYPE_JSON` と `MIME_TYPE_JSONLINES` の両方をサポートしています。
+ `model_input_location` – (オプション) 評価するモデル入力またはプロンプトを含むデータセット内の列の名前。
列の名前を指定する `model_input_location` を使用します。この列には、以下の関連するタスクに対応する次のとおりの値が含まれている必要があります。
+ **オープンエンド生成**評価、**毒性**評価、**精度**評価では、モデルが応答すべき**プロント**を含む列を指定します。
+ **質問への回答**タスクでは、モデルが応答を生成すべき**質問**を含む列を指定します。
+ **テキスト要約タスク**では、モデルが要約する**テキスト**を含む列の名前を指定します。
+ **分類タスク**では、モデルが分類する**テキスト**を含む列の名前を指定します。
+ **事実に関する知識**評価では、モデルで回答を予測する**質問**を含む列の名前を指定します。
+ **セマンティックの頑健性**評価では、モデルで摂動する**入力**を含む列の名前を指定します。
+ **プロンプトのステレオタイプ**評価では、次のパラメータに示すように`model_input_location`、 の代わりに `sent_more_input_location`と` sent_less_input_location` を使用します。
+ `model_output_location` – (オプション) `target_output_location` に含まれる参照出力と比較する予測出力を含むデータセット内の列の名前。`model_output_location` を指定した場合、FMEval は推論のリクエストをモデルに送信しません。代わりに、指定された列に含まれる出力を使用してモデルを評価します。
+ `target_output_location` – `model_output_location` に含まれる予測値と比較する真の値を含む参照データセット内の列の名前。事実に関する知識、精度、セマンティックの頑健性でのみ必要です。事実に関する知識では、この列の各行に区切り文字で区切られたすべての可能な回答が含まれている必要があります。例えば、質問の回答が [“UK”,“England”] の場合、列には「UKEngland」を含める必要があります。区切り文字で区切られた回答のいずれかが含まれている場合、モデルの予測は正しいことになります。
+ `category_location` – カテゴリの名前を含む列の名前。`category_location` の値を指定すると、スコアはカテゴリごとに集計されてレポートが作成されます。
+ `sent_more_input_location` – バイアスが多い方のプロンプトを含む列の名前。プロンプトのステレオタイプにのみ必要です。無意識のバイアスは避ける必要があります。バイアスの例については、「[CrowS-Pairs dataset](https://paperswithcode.com/dataset/crows-pairs)」を参照してください。
+ `sent_less_input_location` – バイアスが少ない方のプロンプトを含む列の名前。プロンプトのステレオタイプにのみ必要です。無意識のバイアスは避ける必要があります。バイアスの例については、「[CrowS-Pairs dataset](https://paperswithcode.com/dataset/crows-pairs)」を参照してください。
+ `sent_more_output_location` – (オプション) モデルが生成した応答により多くのバイアスが含まれると予測される確率を含む列の名前。このパラメータは、プロンプトのステレオタイプタスクでのみ使用されます。
+ `sent_less_output_location` – (オプション) モデルが生成した応答により少ないバイアスが含まれると予測される確率を含む列の名前。このパラメータは、プロンプトのステレオタイプタスクでのみ使用されます。
データセット列に対応する新しい属性を `DataConfig` クラスに追加する場合は、属性名の末尾に `suffix _location` を追加する必要があります。
## カスタム `ModelRunner` を使用する
カスタムモデルを評価するには、ベースデータクラスを使用してモデルを設定し、カスタム `ModelRunner` を作成します。その後、この `ModelRunner` を使用して任意の言語モデルを評価できます。モデル設定を定義し、カスタム `ModelRunner` を作成してテストを行うには、以下の手順を実行します。
`ModelRunner` インターフェイスには、次のとおり 1 つの抽象メソッドがあります。
```
def predict(self, prompt: str) → Tuple[Optional[str], Optional[float]]
```
このメソッドは、プロンプトを文字列入力として取り込み、モデルテキスト応答と入力の対数確率を含むタプルを返します。すべての `predict` では、`ModelRunner` メソッドを実装する必要があります。
**カスタム `ModelRunner` を作成する**
1. モデル設定を定義します。
次のサンプルコードは、**Hugging Face** モデルのモデル設定を定義できるように、`dataclass` デコレータをカスタム `HFModelConfig` クラスに適用する方法を説明しています。
```
from dataclasses import dataclass
@dataclass
class HFModelConfig:
model_name: str
max_new_tokens: int
seed: int = 0
remove_prompt_from_generated_text: bool = True
```
上記のサンプルコードでは、以下が適用されます。
+ パラメータ `max_new_tokens` は、LLM が返すトークンの数を制限することで、応答の長さを制限するために使用されます。モデルのタイプは、クラスがインスタンス化される際に `model_name` の値を渡すことで設定されます。この例では、このセクションの最後に示されるとおり、モデル名は `gpt2` に設定されています。パラメータ `max_new_tokens` は、事前トレーニング済みの OpenAI GPT モデルの `gpt2` モデル設定を使用してテキスト生成戦略を設定するオプションの 1 つです。その他のモデルタイプについては、「[AutoConfig](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html)」を参照してください。
+ パラメータ `remove_prompt_from_generated_text` が `True` に設定されている場合、生成された応答には、リクエストで送信された元のプロンプトは含まれません。
その他のテキスト生成パラメータについては、「[Hugging Face GenerationConfig のドキュメント](https://huggingface.co/docs/transformers/v4.34.1/en/main_classes/text_generation#transformers.GenerationConfig)」を参照してください。
1. カスタム `ModelRunner` を作成して、予測メソッドを実装します。次のサンプルコードは、上記のサンプルコードで作成した `HFModelConfig` クラスを使用して、Hugging Face モデルのカスタム `ModelRunner` を作成する方法を示しています。
```
from typing import Tuple, Optional
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from fmeval.model_runners.model_runner import ModelRunner
class HuggingFaceCausalLLMModelRunner(ModelRunner):
def __init__(self, model_config: HFModelConfig):
self.config = model_config
self.model = AutoModelForCausalLM.from_pretrained(self.config.model_name)
self.tokenizer = AutoTokenizer.from_pretrained(self.config.model_name)
def predict(self, prompt: str) -> Tuple[Optional[str], Optional[float]]:
input_ids = self.tokenizer(prompt, return_tensors="pt").to(self.model.device)
generations = self.model.generate(
**input_ids,
max_new_tokens=self.config.max_new_tokens,
pad_token_id=self.tokenizer.eos_token_id,
)
generation_contains_input = (
input_ids["input_ids"][0] == generations[0][: input_ids["input_ids"].shape[1]]
).all()
if self.config.remove_prompt_from_generated_text and not generation_contains_input:
warnings.warn(
"Your model does not return the prompt as part of its generations. "
"`remove_prompt_from_generated_text` does nothing."
)
if self.config.remove_prompt_from_generated_text and generation_contains_input:
output = self.tokenizer.batch_decode(generations[:, input_ids["input_ids"].shape[1] :])[0]
else:
output = self.tokenizer.batch_decode(generations, skip_special_tokens=True)[0]
with torch.inference_mode():
input_ids = self.tokenizer(self.tokenizer.bos_token + prompt, return_tensors="pt")["input_ids"]
model_output = self.model(input_ids, labels=input_ids)
probability = -model_output[0].item()
return output, probability
```
上記のコードでは、FMEval `HuggingFaceCausalLLMModelRunner` クラスからプロパティを継承するカスタム `ModelRunner` クラスを使用しています。このカスタムクラスには、コンストラクタと、`Tuple` を返す予測関数の定義が含まれています。
その他の `ModelRunner` の例については、「`fmeval` ライブラリ」の「[model\$1runner](https://github.com/aws/fmeval/tree/main/src/fmeval/model_runners)」セクションを参照してください。
`HuggingFaceCausalLLMModelRunner` コンストラクタには、以下の定義が含まれています。
+ この設定は、このセクションの冒頭で定義されている `HFModelConfig` に設定されています。
+ モデルは、インスタンス化時に model\$1name パラメータを使用して指定された Hugging Face [Auto Class](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html) の事前トレーニング済みモデルに設定されています。
+ トークナイザーは、`model_name` で指定された事前トレーニング済みモデルに一致する[Hugging Faceトークナイザーライブラリ](https://huggingface.co/docs/transformers/model_doc/auto#transformers.AutoTokenizer)のクラスに設定されています。
`HuggingFaceCausalLLMModelRunner` クラスの `predict` メソッドは、以下の定義を使用します。
+ `input_ids` – モデルの入力を含む変数。モデルは、次のとおり入力を生成します。
+ `tokenizer` は、`prompt` に含まれるリクエストをトークン識別子 (ID) に変換します。これらのトークン ID は、特定のトークン (単語、サブ単語、または文字) を表す数値であり、モデルが入力として直接使用できます。トークン ID は、PyTorch が指定したとおり、`return_tensors="pt"` テンソルオブジェクトとして返されます。その他のタイプの戻りテンソルタイプについては、「[apply\$1chat\$1template](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer.apply_chat_template)」の「Hugging Face ドキュメント」を参照してください。
+ トークン ID は、モデルが配置されているデバイスに送信され、モデルで使用できるようになります。
+ `generations` – LLM が生成した応答を含む変数。このモデルの生成関数は、以下の入力を使用して応答を生成します。
+ 前のステップからの `input_ids`
+ `HFModelConfig` で指定したパラメータ `max_new_tokens`
+ `pad_token_id` は、文末 (eos) トークンを応答に追加します。使用できるその他のトークンについては、「[PreTrainedTokenizer](https://huggingface.co/docs/transformers/main_classes/tokenizer#transformers.PreTrainedTokenizer)」の「Hugging Face ドキュメント」を参照してください。
+ `generation_contains_input` – 生成された応答に入力プロンプトが含まれている場合は `True` を返し、含まれていない場合は `False` を返すブール変数。戻り値は、以下の要素単位の比較を使用して計算されます。
+ `input_ids["input_ids"][0]` に含まれる入力プロンプトのすべてのトークン ID
+ `generations[0][: input_ids["input_ids"].shape[1]]` に含まれる生成されたコンテンツの先頭
設定で LLM に `remove_prompt_from_generated_text` を指示しても、生成された応答に入力プロンプトが含まれていない場合、`predict` メソッドは警告を返します。
`predict` メソッドからの出力には、応答で返されたトークン ID を人間が読み取れるテキストに変換する、`batch_decode` メソッドが返す文字列が含まれています。`remove_prompt_from_generated_text` を `True` に指定した場合、入力プロンプトは生成されたテキストから削除されます。`remove_prompt_from_generated_text` を `False` に指定した場合、`skip_special_tokens=True` で指定されたとおり、ディクショナリ `special_token_dict` に含めた特別なトークンなしで生成されたテキストが返されます。
1. `ModelRunner` をテストします。サンプルリクエストをモデルに送信します。
次の例は、Hugging Face `AutoConfig` クラスから事前にトレーニングされた `gpt2` モデルを使用してモデルをテストする方法を説明しています。
```
hf_config = HFModelConfig(model_name="gpt2", max_new_tokens=32)
model = HuggingFaceCausalLLMModelRunner(model_config=hf_config)
```
前のコード例の `model_name` では、事前トレーニング済みモデルの名前を指定します。`HFModelConfig` クラスは、パラメータ `max_new_tokens` の値を使用して hf\$1config としてインスタンス化され、`ModelRunner` の初期化に使用されます。
Hugging Face から別の事前トレーニング済みモデルを使用する場合は、[AutoClass](https://huggingface.co/transformers/v3.5.1/model_doc/auto.html) の下の `from_pretrained` で `pretrained_model_name_or_path` を選択します。
最後に、`ModelRunner` をテストします。次のサンプルコードに示されるとおり、モデルにサンプルリクエストを送信します。
```
model_output = model.predict("London is the capital of?")[0]
print(model_output)
eval_algo.evaluate_sample()
```
# モデル評価ノートブックのチュートリアル
このセクションでは、サンプルコードと説明を含む次のノートブックチュートリアルを提供します。
+ JumpStart モデルのプロンプトのステレオタイプ評価方法
+ Amazon Bedrock モデルのテキスト要約の精度評価方法
**Topics**
+ [JumpStart モデルのプロンプトのステレオタイプ評価を行う](clarify-foundation-model-evaluate-auto-tutorial-one.md)
+ [Amazon Bedrock モデルのテキスト要約の精度を評価する](clarify-foundation-model-evaluate-auto-tutorial-two.md)
+ [追加のノートブック](#clarify-foundation-model-evaluate-auto-tutorial-ex)
# JumpStart モデルのプロンプトのステレオタイプ評価を行う
高レベルの `ModelRunner` ラッパーを使用すると、Amazon SageMaker JumpStart モデルのプロンプトのステレオタイプ評価を行うことができます。プロンプトのステレオタイプアルゴリズムは、モデルが応答にバイアスをエンコードする確率を測定します。このようなバイアスには、人種、性別、性的指向、宗教、年齢、国籍、障害、外見、社会経済的地位に関するバイアスなどがあります。
このチュートリアルでは、JumpStart で利用可能な [Technology Innovation Institute](https://www.tii.ae/) の [Falcon 7-B](https://huggingface.co/tiiuae/falcon-7b) モデルをロードして、このモデルにプロンプトへの応答の生成をリクエストする方法を説明します。このチュートリアルではその後、組み込みの [CrowS-Pairs](https://github.com/nyu-mll/crows-pairs) Open Source Challenge データセットに対するプロンプトのステレオタイプの応答を評価する方法を説明します。
このチュートリアルのセクションでは、次の操作を行う方法を説明します。
+ 環境をセットアップします。
+ モデル評価を実行する。
+ 分析結果を表示する。
## 環境をセットアップする
**前提条件**
+ このチュートリアルを開始する前に、基盤となる Python 3.10 カーネル環境と `ml.g4dn.2xlarge` Amazon Elastic Compute Cloud (Amazon EC2) インスタンスを使用します。
インスタンスタイプと推奨されるユースケースの詳細については、「[Amazon SageMaker Studio Classic ノートブックで使用できるインスタンスタイプ](notebooks-available-instance-types.md)」を参照してください。
**必要なライブラリをインストールする**
1. SageMaker AI、`fmeval`、その他の必要なライブラリを以下のとおりコードにインストールします。
```
!pip3 install sagemaker
!pip3 install -U pyarrow
!pip3 install -U accelerate
!pip3 install "ipywidgets>=8"
!pip3 install jsonlines
!pip install fmeval
!pip3 install boto3==1.28.65
import sagemaker
```
1. サンプル `JSON Lines` データセットの [crows-pairs\$1sample.jsonl](https://github.com/aws/fmeval/blob/main/examples/crows-pairs_sample.jsonl) を現在の作業ディレクトリにダウンロードします。
1. 次のコードを使用して、環境にサンプル入力ファイルが含まれていることを確認します。
```
import glob
# Check for fmeval wheel and built-in dataset
if not glob.glob("crows-pairs_sample.jsonl"):
print("ERROR - please make sure file exists: crows-pairs_sample.jsonl")
```
1. JumpStart モデルを以下のとおり定義します。
```
from sagemaker.jumpstart.model import JumpStartModel
model_id, model_version, = (
"huggingface-llm-falcon-7b-instruct-bf16",
"*",
)
```
1. JumpStart モデルをデプロイして、以下のとおりエンドポイントを作成します。
```
my_model = JumpStartModel(model_id=model_id)
predictor = my_model.deploy()
endpoint_name = predictor.endpoint_name
```
1. 次のとおり、プロンプトとモデルへのリクエストの形式、またはペイロードを定義します。
```
prompt = "London is the capital of"
payload = {
"inputs": prompt,
"parameters": {
"do_sample": True,
"top_p": 0.9,
"temperature": 0.8,
"max_new_tokens": 1024,
"decoder_input_details" : True,
"details" : True
},
}
```
上記のコード例では、モデルへのリクエストに次のパラメータが含まれています。
+ `do_sample` – モデル推論中にモデルに raw モデル出力 (正規化前) からサンプリングするように指示し、モデルの応答に多様性と創造性を導入します。デフォルトは `False` です。`do_sample` を `True` に設定する場合は、`temperature`、`top_k`、`top_p` または `typical_p` のいずれかのパラメータの値を指定する必要があります。
+ `top_p` – 次のトークンを生成する際に考慮するトークンのセットを制限して、ランダム性を制御します。`top_p` の値が高いほど、より幅広い語彙を含むセットが許可されます。この値が低いほど、トークンのセットはより可能性の高い単語に制限されます。`top_p` の範囲は、`0` より大きく、`1` より小さくなります。
+ `temperature` – 生成されたテキストのランダム性を制御します。`temperature` の値が高いほど、よりランダムで多様な応答を生成するようにモデルに指示できます。値が低いほど、生成される回答の予測可能が高くなります。`temperature` の値は正の値である必要があります。
+ `max_new_tokens` – モデルが返すトークンの数を制限することで、応答の長さを制限します。デフォルトは `20` です。
+ `decoder_input_details` – モデルが次のトークン候補に割り当てた対数確率と対応するトークン ID に関する情報を返します。`decoder_input_details` が `True` に設定されている場合にリクエストされた詳細を受け取るには `details` も `True` に設定する必要があります。デフォルトは `False` です。
この `Hugging Face` モデルのパラメータの詳細については、「[types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8)」を参照してください。
## サンプル推論リクエストを送信する
モデルをテストするには、サンプルリクエストをモデルに送信し、次のとおりモデル応答を表示します。
```
response = predictor.predict(payload)
print(response[0]["generated_text"])
```
上記のコード例では、モデルが応答 `[{"response": "this is the output"}]` を提供した場合、`print` ステートメントは `this is the output` を返します。
## FMEval を設定する
1. FMEval を実行するために必要なライブラリを次のとおりロードします。
```
import fmeval
from fmeval.data_loaders.data_config import DataConfig
from fmeval.model_runners.sm_jumpstart_model_runner import JumpStartModelRunner
from fmeval.constants import MIME_TYPE_JSONLINES
from fmeval.eval_algorithms.prompt_stereotyping import PromptStereotyping, PROMPT_STEREOTYPING
from fmeval.eval_algorithms import EvalAlgorithm
```
1. 入力データセットのデータ設定を行います。
組み込みデータセットを使用しない場合、データ設定では `sent_more_input_location` により多くのバイアスを含む列を特定する必要があります。`sent_less_input_location` のバイアスが少ない列も特定する必要があります。JumpStart の組み込みデータセットを使用している場合、このようなパラメータはモデルメタデータを介して自動的に FMEval に渡されます。
プロンプトのステレオタイプ化タスクの `sent_more_input_location` 列と `sent_less_input_location` 列、名前、Uniform Resource Identifier (URI)、`MIME` タイプを指定します。
```
config = DataConfig(
dataset_name="crows-pairs_sample",
dataset_uri="crows-pairs_sample.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
sent_more_input_location="sent_more",
sent_less_input_location="sent_less",
category_location="bias_type",
)
```
その他のタスクに必要な列情報の詳細については、「[カスタム入力データセットを使用する](clarify-foundation-model-evaluate-auto-lib-custom.md#clarify-foundation-model-evaluate-auto-lib-custom-input)」の「**Use a custom input dataset**」セクションを参照してください。
1. 次のサンプルコードで示されるとおり、カスタム `ModelRunner` を設定します。
```
js_model_runner = JumpStartModelRunner(
endpoint_name=endpoint_name,
model_id=model_id,
model_version=model_version,
output='[0].generated_text',
log_probability='[0].details.prefill[*].logprob',
content_template='{"inputs": $prompt, "parameters":
{"do_sample": true, "top_p": 0.9, "temperature": 0.8, "max_new_tokens": 1024,
"decoder_input_details": true,"details": true}}',
)
```
上記のサンプルコードでは以下が指定されています。
+ `endpoint_name` – 上記の「**Install required libraries**」ステップで作成したエンドポイントの名前
+ `model_id` – モデルを指定するために使用する ID。このパラメータは、JumpStart モデルを定義した際に指定されました。
+ `model_version` – モデルを指定するために使用するモデルのバージョン。このパラメータは、JumpStart モデルを定義した際に指定されました。
+ `output` – [Falcon 7b モデル](https://huggingface.co/tiiuae/falcon-7b)からの出力をキャプチャして、`generated_text` キーで応答を返します。モデルが応答 `[{"generated_text": "this is the output"}]` を返した場合、`[0].generated_text` は `this is the output` を返します。
+ `log_probability` – この JumpStart モデルが返す対数確率をキャプチャします。
+ `content_template` – リクエストとのモデルのインタラクション方法を指定します。このサンプル設定テンプレートは、上記の例を説明する目的でのみ詳しく説明されていますが、必須ではありません。コンテンツテンプレートのパラメータは、`payload` に対して宣言されているパラメータと同じです。この `Hugging Face` モデルのパラメータの詳細については、「[types.py](https://github.com/huggingface/text-generation-inference/blob/v0.9.3/clients/python/text_generation/types.py#L8)」を参照してください。
1. 次のサンプルコードに示されるとおり、評価レポートを設定して、ディレクトリに保存します。
```
import os
eval_dir = "results-eval-prompt-stereotyping"
curr_dir = os.getcwd()
eval_results_path = os.path.join(curr_dir, eval_dir) + "/"
os.environ["EVAL_RESULTS_PATH"] = eval_results_path
if os.path.exists(eval_results_path):
print(f"Directory '{eval_results_path}' exists.")
else:
os.mkdir(eval_results_path)
```
1. 並列化係数を次のとおり設定します。
```
os.environ["PARALLELIZATION_FACTOR"] = "1"
```
`PARALLELIZATION_FACTOR` は、コンピューティングインスタンスに送信された同時バッチの数の乗数です。ハードウェアで並列化できる場合は、この数値を設定して、評価ジョブの呼び出し回数を乗算できます。例えば、呼び出しの回数が `100` で、`PARALLELIZATION_FACTOR` が `2` に設定されている場合、ジョブは`200` の呼び出しを実行します。`PARALLELIZATION_FACTOR` は最大 `10` まで増やすことも、この変数を完全に削除することもできます。Lambda の使用方法に関する AWS ブログを読むには、[「Kinesis および DynamoDB イベントソースの新しい AWS Lambda スケーリングコントロール](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/)`PARALLELIZATION_FACTOR`」を参照してください。
## モデル評価を実行する
1. 評価アルゴリズムを定義します。次の例は、`PromptStereotyping` アルゴリズムを定義する方法を説明しています。
```
eval_algo = PromptStereotyping()
```
その他の評価タスクのメトリクスを計算するアルゴリズムの例については、「[`fmeval` ライブラリを使用して自動評価を実行する](clarify-foundation-model-evaluate-auto-lib.md)」の「**Evaluate your model**」を参照してください。
1. 評価アルゴリズムを実行します。次のサンプルコードでは、以前に定義したモデルとデータの設定と、`feature` を使用してプロンプトをモデルに渡す `prompt_template` を使用しています。
```
eval_output = eval_algo.evaluate(model=js_model_runner, dataset_config=config,
prompt_template="$feature", save=True)
```
モデル出力は、上記のサンプル出力とは異なる場合があります。
## 分析結果を表示する
1. 評価アルゴリズムが返した `eval_output` オブジェクトからの評価レポートを次のとおり解析します。
```
import json
print(json.dumps(eval_output, default=vars, indent=4))
```
上記のコマンドは、以下のの出力を返します (簡潔に説明するために要約しています)。
```
[
{
"eval_name": "prompt_stereotyping",
"dataset_name": "crows-pairs_sample",
"dataset_scores": [
{
"name": "prompt_stereotyping",
"value": 0.6666666666666666
}
],
"prompt_template": "$feature",
"category_scores": [
{
"name": "disability",
"scores": [
{
"name": "prompt_stereotyping",
"value": 0.5
}
]
},
...
],
"output_path": "/home/sagemaker-user/results-eval-prompt-stereotyping/prompt_stereotyping_crows-pairs_sample.jsonl",
"error": null
}
]
```
上記の出力例では、`"name": prompt_stereotyping` に続くデータセットの全体的なスコアが表示されます。このスコアは、モデル応答間の正規化された対数確率の差であり、バイアスを**より多く**提供するモデル応答とより少なく提供する応答を比較しています。スコアが `0.5` より高い値の場合、モデルの応答はバイアスが多い応答を返す可能性が高いことを意味します。スコアが `0.5` より低い値の場合、モデルはバイアスの少ない応答を返す可能性が高くなります。スコアが `0.5` の場合、モデル応答には、入力データセットで測定されたバイアスが含まれないことを意味します。次のステップでは、`output_path` を使用して、`Pandas` `DataFrame` を作成します。
1. 結果をインポートして `DataFrame` に読み込み、プロンプトのステレオタイプスコアを次のとおりモデル入力、モデル出力、ターゲット出力にアタッチします。
```
import pandas as pd
data = []
with open(os.path.join(eval_results_path,
"prompt_stereotyping_crows-pairs_sample.jsonl"), "r") as file:
for line in file:
data.append(json.loads(line))
df = pd.DataFrame(data)
df['eval_algo'] = df['scores'].apply(lambda x: x[0]['name'])
df['eval_score'] = df['scores'].apply(lambda x: x[0]['value'])
df
```
このセクションで説明したサンプルコードを含むノートブックについては、「[jumpstart-falcon-stereotyping.ipnyb](https://github.com/aws/fmeval/blob/main/examples/jumpstart-falcon-stereotyping.ipynb)」を参照してください。
# Amazon Bedrock モデルのテキスト要約の精度を評価する
高レベルの `ModelRunner` ラッパーを使用して、JumpStart の外部でホストされているモデルに基づいてカスタム評価を作成できます。
このチュートリアルでは、Amazon Bedrock で利用可能な [Anthropic Claude 2 モデル ](https://www.anthropic.com/index/claude-2)をロードして、このモデルにテキストプロンプトの要約をリクエストする方法について説明します。その後、このチュートリアルでは、[https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge) メトリクス、[https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor) メトリクス、[https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) メトリクスを使用してモデル応答の精度を評価する方法を説明します。
このチュートリアルでは、以下を行う方法を説明します。
+ 環境をセットアップします。
+ モデル評価を実行する。
+ 分析結果を表示する。
## 環境をセットアップする
**前提条件**
+ このチュートリアルを開始する前に、基盤となる Python 3.10 カーネル環境と `ml.m5.2xlarge` Amazon Elastic Compute Cloud (Amazon EC2) インスタンスを使用します。
インスタンスタイプと推奨されるユースケースの詳細については、「[Amazon SageMaker Studio Classic ノートブックで使用できるインスタンスタイプ](notebooks-available-instance-types.md)」を参照してください。
**Amazon Bedrock をセットアップする**
Amazon Bedrock モデルを使用する前に、モデルへのアクセスをリクエストする必要があります。
1. にサインインします AWS アカウント。
1. AWS アカウントをお持ちでない場合は、**「Amazon Bedrock のセットアップ**」の[AWS 「アカウントへのサインアップ](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html#sign-up-for-aws)」を参照してください。
1. [Amazon Bedrock コンソール](https://console.aws.amazon.com/bedrock)を開きます。
1. **[Amazon Bedrock へようこそ\$1]** セクションが開いたら、**[モデルアクセスを管理]** をクリックします。
1. **[モデルアクセス]** セクションが表示されたら、**[モデルアクセスを管理]** をクリックします。
1. **[ベースモデル]** セクションが表示されたら、**[モデル]** の **[Anthropic]** サブセクションの下の一覧表示の **[Claude]** の横にあるチェックボックスをオンにします。
1. **[モデルアクセスをリクエスト]** をクリックします。
1. リクエストが正常に完了すると、**[アクセスが付与されました]** と表示されたチェックマークが選択したモデルの横の **[アクセスのステータス]** に表示されます。
1. モデルにアクセスするには AWS アカウント 、 に再度ログインする必要がある場合があります。
**必要なライブラリをインストールする**
1. コードで、次のとおり `fmeval` ライブラリと `boto3` ライブラリをインストールします。
```
!pip install fmeval
!pip3 install boto3==1.28.65
```
1. ライブラリをインポートして、並列化係数を設定し、次のとおり Amazon Bedrock クライアントを呼び出します。
```
import boto3
import json
import os
# Dependent on available hardware and memory
os.environ["PARALLELIZATION_FACTOR"] = "1"
# Bedrock clients for model inference
bedrock = boto3.client(service_name='bedrock')
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
```
上記のサンプルコードでは、以下が適用されます。
+ `PARALLELIZATION_FACTOR` – コンピューティングインスタンスに送信された同時バッチの数の乗数です。ハードウェアで並列化できる場合は、この数値を設定して、評価ジョブの呼び出し回数を乗算できます。例えば、呼び出しの回数が `100` で、`PARALLELIZATION_FACTOR` が `2` に設定されている場合、ジョブは`200` の呼び出しを実行します。`PARALLELIZATION_FACTOR` は最大 `10` まで増やすことも、この変数を完全に削除することもできます。 AWS Lambda の使用方法に関するブログを読むには、[「Kinesis および DynamoDB イベントソースの新しい Lambda スケーリングコントロール](https://aws.amazon.com/blogs/compute/new-aws-lambda-scaling-controls-for-kinesis-and-dynamodb-event-sources/)`PARALLELIZATION_FACTOR`」を参照してください。
1. サンプル `JSON Lines` データセットの [sample-dataset.jsonl](https://github.com/aws/fmeval/blob/8da27af2f20369fd419c03d5bb0707ab24010b14/examples/xsum_sample.jsonl) を現在の作業ディレクトリにダウンロードします。
1. 環境にサンプル入力ファイルが含まれていることを次のとおり確認します。
```
import glob
# Check for the built-in dataset
if not glob.glob("sample-dataset.jsonl"):
print("ERROR - please make sure file exists: sample-dataset.jsonl")
```
**サンプル推論リクエストをモデルに送信します**
1. モデルとプロンプトの `MIME` タイプを定義します。Amazon Bedrock でホストされている [Anthropic Claude 2 モデル](https://www.anthropic.com/index/claude-2)の場合、プロンプトは次のとおり構成する必要があります。
```
import json
model_id = 'anthropic.claude-v2'
accept = "application/json"
contentType = "application/json"
# Ensure that your prompt has the correct format
prompt_data = """Human: Who is Barack Obama?
Assistant:
"""
```
リクエストの本文を構成する方法の詳細については、「[Model invocation request body field](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html#model-parameters-claude-request-body)」を参照してください。モデルによっては形式が異なる場合があります。
1. サンプルリクエストをモデルに送信します。リクエストの本文には、プロンプトと、設定する追加のパラメータが含めます。`max_tokens_to_sample` を`500` に設定したサンプルリクエストは、次のとおりです。
```
body = json.dumps({"prompt": prompt_data, "max_tokens_to_sample": 500})
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=contentType
)
response_body = json.loads(response.get("body").read())
print(response_body.get("completion"))
```
上記のサンプルコードでは、以下のパラメータを設定できます。
+ `temperature` – 生成されたテキストのランダム性を制御し、正の値を受け入れます。`temperature` の値が高いほど、よりランダムで多様な応答を生成するようにモデルに指示できます。値が低いほど、生成される回答の予測可能が高くなります。`temperature` の範囲は `0` から `1` で、デフォルト値は 0.5 です。
+ `topP` – 次のトークンを生成する際に考慮するトークンのセットを制限して、ランダム性を制御します。`topP` の値が高いほど、より幅広い語彙を含むセットが許可され、この値が低いほど、トークンのセットはより可能性の高い単語に制限されます。`topP` の範囲は `0` から `1` で、デフォルト値は `1` です。
+ `topK` – モデルの予測を、最も可能性の高い上位 `k` つのトークンに制限します。`topK` の値が高いほど、応答の独創性が実現します。値が低いほど、より一貫性のある応答が生成されます。`topK` の範囲は `0` から `500` で、デフォルト値は `250` です。
+ `max_tokens_to_sample` – モデルが返すトークンの数を制限することで、応答の長さを制限します。`max_tokens_to_sample` の範囲は `0` から `4096` で、デフォルト値は `200` です。
+ `stop_sequences` – モデルに応答の生成を停止するように指示する文字シーケンスのリストを指定するために使用されます。モデル出力は、リストされている文字列のいずれかが出力で最初に検出されると停止します。この応答には停止シーケンスは含まれていません。例えば、キャリッジリターンシーケンスを使用して、モデル応答を 1 行に制限できます。最大 `4` つの停止シーケンスを設定できます。
リクエストで指定できるパラメータの詳細については、「[Anthropic Claude models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html)」を参照してください。
**FMEval を設定する**
1. FMEval を実行するために必要なライブラリを次のとおりロードします。
```
from fmeval.data_loaders.data_config import DataConfig
from fmeval.model_runners.bedrock_model_runner import BedrockModelRunner
from fmeval.constants import MIME_TYPE_JSONLINES
from fmeval.eval_algorithms.summarization_accuracy import SummarizationAccuracy, SummarizationAccuracyConfig
```
1. 入力データセットのデータ設定を行います。
次のサンプル入力は、`sample-dataset.jsonl` からの 1 行です。
```
{
"document": "23 October 2015 Last updated at 17:44
BST\nIt's the highest rating a tropical storm
can get and is the first one of this magnitude
to hit mainland Mexico since 1959.\nBut how are
the categories decided and what do they mean?
Newsround reporter Jenny Lawrence explains.",
"summary": "Hurricane Patricia has been rated as
a category 5 storm.",
"id": "34615665",
}
```
上記のサンプル入力には、`document` キー内に要約するテキストが含まれています。モデル応答を評価する参照は `summary` キーが保持しています。データ設定内でこれらのキーを使用して、FMEval がモデル応答を評価するために必要な情報を含む列を指定する必要があります。
データ設定では、`model_input_location` にモデルが要約する必要があるテキストを特定する必要があります。参照値は `target_output_location` で特定する必要があります。
次のデータ設定例では、上記の入力例を参照して、テキスト要約タスクに必要な列、名前、Uniform Resource Identifier (URI)、`MIME` タイプを指定します。
```
config = DataConfig(
dataset_name="sample-dataset",
dataset_uri="sample-dataset.jsonl",
dataset_mime_type=MIME_TYPE_JSONLINES,
model_input_location="document",
target_output_location="summary"
)
```
その他のタスクに必要な列情報の詳細については、「[自動モデル評価](clarify-foundation-model-evaluate-auto.md)」の「**Use a custom input dataset**」セクションを参照してください。
1. 次のサンプルコードで示されるとおり、カスタム `ModelRunner` を設定します。
```
bedrock_model_runner = BedrockModelRunner(
model_id=model_id,
output='completion',
content_template='{"prompt": $prompt, "max_tokens_to_sample": 500}'
)
```
上記のサンプルコードでは以下が指定されています。
+ `model_id` – モデルを指定するために使用する ID。
+ `output` – [Anthropic Claude 2](https://www.anthropic.com/index/claude-2) モデルからの出力をキャプチャして、応答を `completion` キーで返します。
+ `content_template` – リクエストとのモデルのインタラクション方法を指定します。このサンプル設定テンプレートは、上記の例を説明する目的でのみ次のとおり詳しく説明されていますが、必須ではありません。
+ 上記のサンプル `content_template` では、以下が適用されています。
+ 変数 `prompt` は、ユーザーが行ったリクエストをキャプチャする入力プロンプトを指定します。
+ 変数 `max_tokens_to_sample` は、応答の長さを制限するために、トークンの最大数を `500` に指定します。
リクエストで指定できるパラメータの詳細については、「[Anthropic Claude models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html)」を参照してください。
`content_template` パラメータの形式は、LLM でサポートされている入力とパラメータによって異なります。このチュートリアルでは、[Anthropic の Claude 2 モデル](https://www.anthropic.com/index/claude-2)で次の `content_template` を使用します。
```
"content_template": "{\"prompt\": $prompt, \"max_tokens_to_sample\": 500}"
```
別の例として、[Falcon 7b モデル](https://huggingface.co/tiiuae/falcon-7b)は、次の `content_template` をサポートできます。
```
"content_template": "{\"inputs\": $prompt, \"parameters\":{\"max_new_tokens\": \
10, \"top_p\": 0.9, \"temperature\": 0.8}}"
```
## モデル評価を実行する
**評価アルゴリズムを定義して実行する**
1. 評価アルゴリズムを定義します。次の例は、テキスト要約タスクの精度を判断するために使用される `SummarizationAccuracy` アルゴリズムを定義する方法を説明しています。
```
eval_algo = SummarizationAccuracy(SummarizationAccuracyConfig())
```
その他の評価タスクのメトリクスを計算するアルゴリズムの例については、「[`fmeval` ライブラリを使用して自動評価を実行する](clarify-foundation-model-evaluate-auto-lib.md)」の「**Evaluate your model**」を参照してください。
1. 評価アルゴリズムを実行します。次のサンプルコードでは、以前に定義したモデルとデータの設定と、`Human` キーと `Assistant` キーを使用する `prompt_template` を使用しています。
```
eval_output = eval_algo.evaluate(model=bedrock_model_runner,
dataset_config=config,
prompt_template="Human: $feature\n\nAssistant:\n", save=True)
```
上記のコード例の `feature` には Amazon Bedrock モデルが求める形式のプロンプトが含まれています。
## 分析結果を表示する
1. 評価アルゴリズムが返した `eval_output` オブジェクトからの評価レポートを次のとおり解析します。
```
# parse report
print(json.dumps(eval_output, default=vars, indent=4))
```
上記のコマンドは、以下のの出力を返します。
```
[
{
"eval_name": "summarization_accuracy",
"dataset_name": "sample-dataset",
"dataset_scores": [
{
"name": "meteor",
"value": 0.2048823008681274
},
{
"name": "rouge",
"value": 0.03557697913367101
},
{
"name": "bertscore",
"value": 0.5406564395678671
}
],
"prompt_template": "Human: $feature\n\nAssistant:\n",
"category_scores": null,
"output_path": "/tmp/eval_results/summarization_accuracy_sample_dataset.jsonl",
"error": null
}
]
```
上記の出力例では[https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor)、[https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge)、[https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) の 3 つの精度スコア、入力 `prompt_template`、リクエストした場合は `category_score`、エラー、`output_path` が表示されます。次のステップでは、`output_path` を使用して、`Pandas DataFrame` を作成します。
1. 結果をインポートして `DataFrame` に読み込み、精度スコアを次のとおりモデル入力、モデル出力、ターゲット出力にアタッチします。
```
import pandas as pd
data = []
with open("/tmp/eval_results/summarization_accuracy_sample_dataset.jsonl", "r") as file:
for line in file:
data.append(json.loads(line))
df = pd.DataFrame(data)
df['meteor_score'] = df['scores'].apply(lambda x: x[0]['value'])
df['rouge_score'] = df['scores'].apply(lambda x: x[1]['value'])
df['bert_score'] = df['scores'].apply(lambda x: x[2]['value'])
df
```
この呼び出しでは、上記のサンプルコードは、以下のの出力を返します (簡潔に説明するために要約しています)。
```
model_input model_output target_output prompt scores meteor_score rouge_score bert_score
0 John Edward Bates, formerly of Spalding, Linco... I cannot make any definitive judgments, as th... A former Lincolnshire Police officer carried o... Human: John Edward Bates, formerly of Spalding... [{'name': 'meteor', 'value': 0.112359550561797... 0.112360 0.000000 0.543234 ...
1 23 October 2015 Last updated at 17:44 BST\nIt'... Here are some key points about hurricane/trop... Hurricane Patricia has been rated as a categor... Human: 23 October 2015 Last updated at 17:44 B... [{'name': 'meteor', 'value': 0.139822692925566... 0.139823 0.017621 0.426529 ...
2 Ferrari appeared in a position to challenge un... Here are the key points from the article:\n\n... Lewis Hamilton stormed to pole position at the... Human: Ferrari appeared in a position to chall... [{'name': 'meteor', 'value': 0.283411142234671... 0.283411 0.064516 0.597001 ...
3 The Bath-born player, 28, has made 36 appearan... Okay, let me summarize the key points from th... Newport Gwent Dragons number eight Ed Jackson ... Human: The Bath-born player, 28, has made 36 a... [{'name': 'meteor', 'value': 0.089020771513353... 0.089021 0.000000 0.533514 ...
...
```
モデル出力は、上記のサンプル出力とは異なる場合があります。
このセクションで説明したサンプルコードを含むノートブックについては、「[bedrock-claude-summarization-accuracy.ipnyb](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-summarization-accuracy.ipynb)」を参照してください。
## 追加のノートブック
[fmeval GitHub](https://github.com/aws/fmeval/tree/main/examples) ディレクトリには、次の追加のノートブック例が提供されています。
+ [bedrock-claude-factual-knowledge.ipnyb](https://github.com/aws/fmeval/blob/main/examples/bedrock-claude-factual-knowledge.ipynb) – 事実に関する知識向けの Amazon Bedrock でホストされている [Anthropic Claude 2](https://www.anthropic.com/index/claude-2) モデルを評価します。
+ [byo-model-outputs.ipynb](https://github.com/aws/fmeval/blob/main/examples/byo-model-outputs.ipynb) – 事実に関する知識向けの JumpStart でホストされている [Falcon 7b モデル](https://huggingface.co/tiiuae/falcon-7b)を評価します。モデルに推論リクエストを送信する代わりに独自のモデル出力を使用できます。
+ [custom\$1model\$1runner\$1chat\$1gpt.ipnyb](https://github.com/aws/fmeval/blob/main/examples/custom_model_runner_chat_gpt.ipynb) – 事実に関する知識向けの `Hugging Face` でホストされているカスタム `ChatGPT 3.5` モデルを評価します。
# Amazon SageMaker AI でモデル評価ジョブを作成する際のエラーを解決する
**重要**
SageMaker Clarify Foundation Model Evaluations (FMEval) を使用するには、新しい Studio エクスペリエンスにアップグレードする必要があります。
2023 年 11 月 30 日以降、従来の Amazon SageMaker Studio のエクスペリエンスは Amazon SageMaker Studio Classic と名前が変更されました。FMEval は、Amazon SageMaker Studio Classic では利用できません。
新しい Studio エクスペリエンスにアップグレードする方法については、「[Amazon SageMaker Studio Classic からの移行](studio-updated-migrate.md)」を参照してください。Studio Classic アプリケーションを使用する場合は、「[Amazon SageMaker Studio Classic](studio.md)」を参照してください。
モデル評価ジョブの作成中にエラーが発生した場合は、次のリストを利用して評価のトラブルシューティングを行います。さらにサポートが必要な場合は、[サポート](https://console.aws.amazon.com/support/) または [Amazon SageMaker AI 向けAWS デベロッパーフォーラム](https://forums.aws.amazon.com/forum.jspa?forumID=285)にお問い合わせください。
**トピック**
+ [Amazon S3 バケットへのデータのアップロードエラー](#clarify-foundation-model-evaluate-troubleshooting-cors)
+ [処理ジョブを完了できませんでした](#clarify-foundation-model-evaluate-troubleshooting-failure)
+ [SageMaker AIコンソールで基盤モデル評価が見つかりません](#clarify-foundation-model-evaluate-troubleshooting-upgrade)
+ [このモデルはプロンプトのステレオタイプをサポートしていません](#clarify-foundation-model-evaluate-troubleshooting-ps)
+ [データセット検証エラー (ヒューマン)](#clarify-foundation-model-evaluate-troubleshooting-valid)
## Amazon S3 バケットへのデータのアップロードエラー
基盤モデル評価を作成する際は、モデルの入出力を保存する S3 バケットに適切なアクセス許可を設定する必要があります。クロスオリジンリソース共有 (CORS) アクセス許可が適切に設定されていない場合、SageMaker AI は次のエラーを生成します。
エラー: s3 にオブジェクトを配置できませんでした: s3Error へのオブジェクトのアップロード中にエラーが発生しました: S3 へのオブジェクトの配置に失敗しました: リソースの取得時に NetworkError が発生しました
バケットのアクセス許可を適切に設定するには、「[Studio で自動モデル評価ジョブを作成する](clarify-foundation-model-evaluate-auto-ui.md)」の「**Set up your environment**」の手順を実行します。
## 処理ジョブを完了できませんでした
処理ジョブを完了できない最も一般的な理由は次のとおりです。
+ [クォータが不十分](#clarify-foundation-model-evaluate-troubleshooting-failure-quota)
+ [メモリが不十分](#clarify-foundation-model-evaluate-troubleshooting-failure-memory)
+ [ping チェックで合格しませんでした](#clarify-foundation-model-evaluate-troubleshooting-failure-ping)
各問題の軽減に役立つ以下のセクションを参照してください。
### クォータが不十分
デプロイされていない JumpStart モデルの基盤モデル評価を実行すると、SageMaker Clarify は、アカウントの SageMaker AI エンドポイントに大規模言語モデル (LLM) をデプロイします。選択した JumpStart モデルを実行するのに十分なクォータがアカウントにない場合、ジョブは失敗して `ClientError` が発生します。クォータを引き上げるには、次の手順を実行します。
**AWS Service Quotas の引き上げをリクエストする**
1. 画面上のエラーメッセージからインスタンス名、現在のクォータ、必要なクォータを取得します。例えば、次のエラーの場合は、以下のとおりです。
+ このインスタンス名は `ml.g5.12xlarge` です。
+ `current utilization` の後の現在のクォータは `0 instances` インスタンスです。
+ `request delta` の後の数字の必要となる追加のクォータは `1 instances` です。
サンプルエラーは次のとおりです。
`ClientError: An error occurred (ResourceLimitExceeded) when calling the CreateEndpoint operation: The account-level service limit 'ml.g5.12xlarge for endpoint usage' is 0 Instances, with current utilization of 0 Instances and a request delta of 1 Instances. Please use AWS Service Quotas to request an increase for this quota. If AWS Service Quotas is not available, contact AWS support to request an increase for this quota`
1. にサインイン AWS マネジメントコンソール し、[Service Quotas コンソール](https://console.aws.amazon.com/servicequotas/home)を開きます。
1. ナビゲーションペインの **[クォータの管理]** で、**Amazon SageMaker AI** を入力します。
1. **[クォータの表示]** をクリックします。
1. **[Service Quotas]** の検索バーに、ステップ 1 のインスタンスの名前を入力します。例えば、ステップ 1 のエラーメッセージに含まれる情報を使用して、「**ml.g5.12xlarge**」と入力します。
1. インスタンス名の横に表示され、「**for endpoint usage**」で終わる **[クォータの名称]** を選択します。例えば、ステップ 1 のエラーメッセージに含まれる情報を使用して、**[ml.g5.12xlarge for endpoint usage]** を選択します。
1. **[アカウントレベルでの引き上げをリクエスト]** をクリックします。
1. **[クォータ値を引き上げる]** で、ステップ 1 のエラーメッセージに記載されている情報から必要なクォータを入力します。`current utilization` と `request delta` の**合計**を入力します。上記のエラー例では、`current utilization`は `0 Instances` で、`request delta` は `1 Instances` です。この例では、必要なクォータを指定するには `1` のクォータをリクエストします。
1. **[リクエスト]** を選択します。
1. ナビゲーションペインから **[クォータリクエスト履歴]** を選択します。
1. **[ステータス]** が **[保留中]** から **[承認済み]** に変わったら、ジョブを再実行します。変更を確認するには、ブラウザで更新する必要がある場合があります。
クォータの引き上げリクエストの詳細については、「[Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)」を参照してください。
### メモリが不十分
評価アルゴリズムを実行するのに十分なメモリがない Amazon EC2 インスタンスで基盤モデル評価を開始すると、ジョブは失敗して次のエラーが発生します。
`The actor is dead because its worker process has died. Worker exit type: SYSTEM_ERROR Worker exit detail: Worker unexpectedly exits with a connection error code 2. End of file. There are some potential root causes. (1) The process is killed by SIGKILL by OOM killer due to high memory usage. (2) ray stop --force is called. (3) The worker is crashed unexpectedly due to SIGSEGV or other unexpected errors. The actor never ran - it was cancelled before it started running.`
評価ジョブで使用できるメモリを増やすには、インスタンスをメモリ量の多いインスタンスに変更します。ユーザーインターフェイスを使用している場合は、**ステップ 2** の **[プロセッサ設定]** でインスタンスタイプを選択できます。SageMaker AI コンソール内でジョブを実行している場合は、メモリキャパシティを引き上げたインスタンスを使用して新しいスペースを起動します。
Amazon EC2 インスタンスのリストについては、「[インスタンスタイプ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes)」を参照してください。
メモリ容量が大きいインスタンスの詳細については、「[Memory optimized instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/memory-optimized-instances.html)」を参照してください。
### ping チェックで合格しませんでした
インスタンスによっては、SageMaker AI がエンドポイントをデプロイした場合に ping チェックに合格しないため、基盤モデル評価ジョブが失敗することがあります。ping テストに合格しない場合、次のエラーが表示されます。
`ClientError: Error hosting endpoint your_endpoint_name: Failed. Reason: The primary container for production variant AllTraffic did not pass the ping health check. Please check CloudWatch logs for this endpoint..., Job exited for model: your_model_name of model_type: your_model_type `
ジョブがこのようなエラーを生成する場合は、数分待ってからジョブを再度実行します。エラーが解決しない場合は、[AWS サポート](https://console.aws.amazon.com/support/) または [Amazon SageMaker AI 向けAWS デベロッパーフォーラム](https://forums.aws.amazon.com/forum.jspa?forumID=285)にお問い合わせください。
## SageMaker AIコンソールで基盤モデル評価が見つかりません
SageMaker Clarify Foundation Model Evaluations を使用するには、新しい Studio エクスペリエンスにアップグレードする必要があります。2023 年 11 月 30 日以降、従来の Amazon SageMaker Studio のエクスペリエンスは Amazon SageMaker Studio Classic と名前が変更されました。基盤モデルの評価機能は、更新後のエクスペリエンスでのみ使用できます。Studio をアップデートする方法の詳細については、「[Amazon SageMaker Studio Classic からの移行](studio-updated-migrate.md)」を参照してください。
## このモデルはプロンプトのステレオタイプをサポートしていません
JumpStart モデルの一部のみがプロンプトのステレオタイプをサポートしています。サポートしていない JumpStart モデルを選択すると、次のエラーが表示されます。
`{"evaluationMetrics":"This model does not support Prompt stereotyping evaluation. Please remove that evaluation metric or select another model that supports it."}`
このようなエラーが表示された場合は、選択したモデルは基盤評価で使用することはできません。現時点で、SageMaker Clarify はプロンプトのステレオタイプタスクのすべての JumpStart モデルを更新しているため、基盤モデル評価で使用できます。
## データセット検証エラー (ヒューマン)
ヒューマンワーカーによるモデル評価ジョブのカスタムプロンプトデータセットは、`.jsonl` 拡張子を使用し、JSON 行形式でフォーマットする必要があります。
ジョブを開始すると、プロンプトデータセット内の各 JSON オブジェクトは相互に検証されます。JSON オブジェクトのいずれかが有効でない場合、次のエラーが発生します。
```
Customer Error: Your input dataset could not be validated. Your dataset can have up to 1000 prompts. The dataset must be a valid jsonl file, and each prompt valid json object.To learn more about troubleshooting dataset validations errors, see Troubleshooting guide. Job executed for models: meta-textgeneration-llama-2-7b-f, pytorch-textgeneration1-alexa20b.
```
カスタムプロンプトデータセットがすべての検証に合格するには、JSON 行ファイル内のすべての JSON オブジェクトに対して、以下の値が *true* である必要があります。
+ プロンプトデータセットファイルの各行は、有効な JSON オブジェクトである必要があります。
+ 引用符 (`"`) などの特殊文字は適切にエスケープする必要があります。例えば、プロンプトが「`"Claire said to the crowd, "Bananas are the best!""`」の場合、引用符は `\` を使用してエスケープして、「`"Claire said to the crowd, \"Bananas are the best!\""`」とする必要があります。
+ 有効な JSON オブジェクトには、少なくとも`prompt` のキーと値のペアが含まれている必要があります。
+ プロンプトデータセットファイルの場合、単一のファイルに 1,000 を超える JSON オブジェクトを含めることはできません。
+ *いずれか*の JSON オブジェクトで `responses` キーを指定する場合、*すべて*の JSON オブジェクトに、このキーが含まれている必要があります。
+ `responses` キーに含められるオブジェクトの最大数は 1 です。比較する複数のモデルからの応答がある場合、それぞれに個別の BYOI データセットが必要です。
+ *いずれか*の JSON オブジェクトで `responses` キーを指定する場合、*すべて*の `responses` オブジェクトに、`modelIdentifier` キーと `text` キーが含まれている必要があります。
# Amazon SageMaker JumpStart テキスト分類モデルの評価と比較
SageMaker AI JumpStart には、テキストを事前定義されたクラスに分類する複数のテキスト分類モデルが用意されています。これらのモデルは、センチメント分析、トピック分類、コンテンツモデレーションなどのタスクを処理します。本番稼働に適したモデルを選択するには、精度、F1-score、Matthews 相関係数 (MCC) などの主要なメトリクスを使用して慎重に評価する必要があります。
このガイドでは、以下を実行します。
+ JumpStart カタログから複数のテキスト分類モデル (DistilBERT および BERT) をデプロイします。
+ バランスの取れたデータセット、偏りのあるデータセット、困難なデータセットの間で包括的な評価を実行します。
+ Matthews Correlation Coefficient (MCC) や曲線下レシーバーの運用特性スコアなどの高度なメトリクスを解釈します。
+ 体系的な比較フレームワークを使用して、データ駆動型モデル選択の決定を行います。
+ オートスケーリングと CloudWatch モニタリングを使用して本番稼働のデプロイを設定します。
完全な評価フレームワーク [JumpStart Model Evaluation Package](samples/sagemaker-text-classification-evaluation-2.zip) をダウンロードします。**パッケージにはサンプル出力を含む実行前結果**が含まれているため、モデルを独自デプロイする前に評価プロセスとメトリクスをプレビューできます。
## 前提条件
作業を開始する前に、以下の準備が整っていることを確認します。
+ [AWS SageMaker AI アクセス許可を持つ アカウント](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html)。
+ [SageMaker AI Amazon SageMaker Studio アクセス](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html)
+ Python に関する知識
+ テキスト分類の概念の理解
時間とコスト: 合計 45 分。コストはインスタンスタイプと使用期間によって異なります。現在の料金については、[SageMaker AI の料金](https://aws.amazon.com/sagemaker/pricing/)」を参照してください。
このチュートリアルには、すべてのリソースを削除して継続的な課金を回避するためのステップバイステップのクリーンアップ手順が含まれています。
**Topics**
+ [前提条件](#w2aac37c15c11)
+ [評価環境を設定する](jumpstart-text-classification-setup.md)
+ [テキスト分類モデルを選択してデプロイする](jumpstart-text-classification-deploy.md)
+ [モデルのパフォーマンスを評価して比較する](jumpstart-text-classification-evaluate.md)
+ [結果を解釈する](jumpstart-text-classification-interpret.md)
+ [モデルを大規模にデプロイする](jumpstart-text-classification-scale.md)
# 評価環境を設定する
テキスト分類評価用の JumpStart モデルにアクセスするように SageMaker AI Studio を設定します。このセクションでは、アクセス許可の設定と、モデルをデプロイする前に関連するコストについて説明します。
## 前提条件
開始する前に、SageMaker AI アクセス許可を持つ AWS アカウントがあることを確認してください。アカウントのセットアップ手順については、[SageMaker AI の前提条件を設定する](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html)」を参照してください。
## JumpStart モデル評価用に SageMaker AI Studio をセットアップする
SageMaker AI Studio にアクセスできない場合は、ドメイン作成のための「[高速セットアップ](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html)」を参照してください。
SageMaker Studio でテキスト分類プロジェクトを開始するには:
1. Amazon SageMaker AI Studio コントロールパネルを開きます。
1. ユーザープロファイルを選択します。
1. **[Studio を開く]** を選択します。
1. Studio がロードされるまで待ちます (初回起動時には 2～3 分かかる場合があります)。
1. JumpStart が左側のナビゲーションパネルに表示されていることを検証します。
## SageMaker AI のコストについて理解する
SageMaker AI Studio を使用すると、以下のコストが発生します。
+ SageMaker AI エンドポイントのホスティング (インスタンスタイプと期間によって異なります)。
+ データセットとモデルアーティファクト用の Amazon S3 ストレージ
+ ノートブックインスタンスランタイム (対象アカウントの AWS 無料利用枠の対象となる一部の使用量）。
**注記**
Studio インターフェイスの使用では、追加料金は発生しません。
### コスト管理に関する推奨事項
評価中のコストを最小限に抑えるには、次の推奨事項に従ってください。
+ DistilBERT モデルと BERT モデルに指定されているデフォルトのインスタンスを使用します。
+ 評価の直後にエンドポイントを削除します。
+ [AWS 料金見積りツール](https://aws.amazon.com/calculator.aws/#/addService/SageMaker)を使用して、使用状況をモニタリングします。
+ 現在のストレージの料金については、[「Amazon Simple Storage Service の料金](https://aws.amazon.com/s3/pricing/)」を参照してください。
**警告**
このチュートリアルを完了したら、継続的な料金が発生しないように、エンドポイントをシャットダウンし、リソースをクリーンアップしてください。
「[テキスト分類モデルを選択してデプロイする](jumpstart-text-classification-deploy.md)」に進みます。
# テキスト分類モデルを選択してデプロイする
比較のために、DistilBERT Base Cased と BERT Base Uncased の 2 つのテキスト分類モデルをデプロイします。これらのモデルの違いを確認し、最適なインスタンス設定を使用してデプロイします。
## これら 2 つのモデルを使用する理由
これらのモデルは、お客様が本番環境で直面するパフォーマンスとコストの一般的な選択肢です。
+ **BERT Base Uncased**: より大規模で、より正確ですが、より遅く、リソースを大量に消費します。
+ **DistilBERT Base Cased**: より小型かつ高速で、費用対効果は高くなりますが、精度が低い可能性があります。
この比較は、特定のニーズに合わせて適切なモデルを選択するのに役立ちます。
## カタログ内のモデル名について
カタログ内のテキスト分類モデル名には、次のコンポーネントが含まれます。
+ BERT: トランスフォーマーからの双方向エンコーダ表現。
+ L-X\$1H-Y\$1A-Z: モデル構造:
+ L-X: レイヤーの数 (X)
+ H-Y: 非表示サイズ (Y)
+ A～Z: アテンションヘッドの数 (Z)
+ Small/Base/Large: モデルのサイズと複雑さ
+ Uncased/Cased - 大文字と小文字の区別の設定。
例: `Small BERT L-2_H-128_A-2` は、次のとおり小規模な BERT モデルです。
+ 2 レイヤー
+ 128 の非表示ユニット
+ 2 つのアテンションヘッド
## JumpStart モデルカタログにアクセスする
JumpStart カタログのテキスト分類モデルに移動します。
1. SageMaker AI Studio を開く
1. 左側のナビゲーションペインで、**[JumpStart]** を選択します。
1. JumpStart ページで、**[Hugging Face]** をクリックします。
1. **[テキスト分類]** を選択します。
DistilBERT や BERT バリアントなど、使用可能なテキスト分類モデルのリストがカタログに表示されます。
## DistilBERT Base Cased をデプロイする
デフォルト設定を使用して DistilBERT モデルをデプロイします。
1. モデルリストで、**[DistilBERT Base Cased]** (distilbert) を探して選択します。
1. モデルの詳細ページで、デフォルトのインスタンスタイプのままにします。
1. 他のすべての設定をデフォルトのままにして、**[デプロイ]** をクリックします。
1. デプロイが完了するまで 5～10 分待ちます。
1. デプロイの成功を確認するには、**[デプロイ]**、**[エンドポイント]** に移動します。
1. DistilBERT エンドポイントのステータスが `InService` と表示されていることを確認します。
## BERT Base Uncased をデプロイする
DistilBERT と比較するために BERT モデルをデプロイします。
1. JumpStart の Hugging Face テキスト分類モデルに戻ります。
1. **[BERT Base Uncased]** (google-bert) を検索して選択します。
1. デフォルトのインスタンスタイプのままにして、**[デプロイ]** をクリックします。
1. 両方のデプロイを確認するには、エンドポイントリストに両方のエンドポイントのステータスが `InService` と表示していることを確認します。
どちらのモデルも、`InService` ステータスでエンドポイントリストに表示されます。
**重要**
エンドポイント名をコピーして保存します。これらは評価プロセスで必要になります。
## トラブルシューティング
デプロイの問題が発生した場合：
+ インスタンスタイプエラーの場合は、`ml.m5.large` などの CPU インスタンスではなく、デフォルトのインスタンスタイプを使用していることを確認します。
+ モデルが見つからない場合は、括弧内のパブリッシャーを含む正確なモデル名を使用して検索します。
+ 失敗したデプロイについては、リージョンのサービスの状態を確認するか、別のリージョンを試してください。
モデルのステータスが `InService` と表示されたら、[モデルのパフォーマンスを評価して比較する](jumpstart-text-classification-evaluate.md) に進み、引き続きデプロイされたモデルを評価します。
# モデルのパフォーマンスを評価して比較する
評価フレームワークを使用して、デプロイしたテキスト分類モデルを評価します。このフレームワークは、ノートブックベースのアプローチを通じて、教師あり評価モードと教師なし評価モードの両方をサポートします。
## 組み込みデータセットの使用
このチュートリアルでは、**組み込みの教師あり評価データセットを使用することをお勧めします**。ほとんどのユーザーは、ラベル付き評価データがすぐには利用できないためです。組み込みデータセットは、さまざまなシナリオにわたって包括的なパフォーマンス分析を提供します。
+ **分散データセット**: ベースラインパフォーマンスのクラス分布は同等です。
+ **偏りのあるデータセット**: 実際のテストのための不均衡なクラス。
+ **困難なデータセット**: エッジケースからストレステストモデルの堅牢性。
この評価では、正確性、精度、再現率、F1 スコア、Matthews 相関係数 (MCC)、曲線下レシーバーの運用特性スコア、モデル比較用のビジュアル曲線などの主要メトリクスが生成されます。
## カスタムデータの使用
独自のラベル付きデータセットがある場合は、ノートブックで置き換えることができます。フレームワークはデータ形式に自動的に適応し、同じ包括的なメトリクスを生成します。
**サポートされているデータ形式:**
+ **CSV 形式:** 2 つの列: `text` と `label`
+ **ラベル形式:** "positive"/"negative"、"LABEL\$10"/"LABEL\$11"、"True"/"False"、または "0"/"1"
+ **教師なし:** 信頼度分析用の単一 `text` 列
## 評価環境を設定する
SageMaker Amazon SageMaker Studio で JupyterLab スペースを作成して、評価ノートブックを実行します。
1. Studio で、ホーム画面から **[JupyterLab]** を選択します。
1. スペースがない場合:
1. **[スペースを作成]** を選択します。
1. **TextModelEvaluation)** など、わかりやすい名前を入力します。
1. インスタンスタイプはデフォルトのままにします。
1. **[実行スペース]** を選択します。
1. スペースが作成されたら、**[JupyterLab を開く]** をクリックします。
### 評価ノートブックにアクセスする
[zip ファイル](samples/sagemaker-text-classification-evaluation-2.zip)をダウンロードし、ローカルマシンで解凍します。解凍したフォルダ全体を JupyterLab スペースにアップロードして、モデルのテストを開始します。パッケージには、主要な評価ノートブック、サンプルデータセット、サポートする Python モジュール、完全な評価フレームワークの詳細な手順が含まれています。
**注記**
パッケージを抽出したら、README ファイルで詳細なセットアップ手順とフレームワークの概要を確認します。
評価出力を分析し、データに基づいてモデル選択を決定する方法を学ぶには、[結果を解釈する](jumpstart-text-classification-interpret.md) に進みます。
# 結果を解釈する
テキスト分類モデルの比較から評価メトリクスを分析し、本番稼働のデプロイのデータ駆動型の決定を行います。
## 評価メトリクスについて理解する
この評価では、すべてのデータセットのモデルごとにいくつかの主要なメトリクスが提供されます。
### 正解率
正しい予測の割合を測定し、バランスの取れたデータセットに最適です。ただし、不均衡なデータでは誤解を招く可能性があり、1 つのクラスが優勢になると、人為的に高い結果が表示される可能性があります。
### 精度
正の予測の何パーセントが正しいかを測定することで、モデルが誤検出をどの程度回避できるかを評価します。このメトリクスの範囲は 0.0～1.0 (高いほど良好) で、誤検出が高コストになる場合に重要になります。
### リコール
実際に見つかった陽性の割合を測定することで、モデルがすべての陽性ケースをどの程度把握しているかを評価します。範囲は 0.0～1.0 (高いほど良好) で、誤検出が高コストになる場合に重要になります。
### F1 スコア
精度と再現率の調和平均を提供し、両方のメトリクスを 0.0～1.0 (高いほど良好) の範囲の単一のスコアに分散します。
### Matthews 相関係数 (MCC)
全体的な二項分類の品質を測定し、不均衡なデータに最適なメトリクスとして機能します。-1.0～1.0 の範囲であり、値が大きいほどパフォーマンスが向上し、0 はランダム推測を表します。
### 受信者操作特性曲線の下面積
モデルがクラスをどの程度区別しているかを評価します。0.0～1.0 の範囲であり、1.0 は完全な分類を表し、0.5 はランダムな推測を表します。
### 平均推論時間
リアルタイムアプリケーションにとって重要となる予測速度を測定します。このメトリクスを評価する際は、速度と一貫性の両方を考慮します。
**注記**
モデルの選択の精度だけに依存しないでください。不均衡なデータセットの場合、精度、再現率、MCC は、実際のパフォーマンスのより信頼性の高い指標を提供します。
## データセットタイプ間でパフォーマンスを比較する
**バランスの取れたデータセット**は、肯定的な例と否定的な例を等しく表現して、理想的な条件下でモデルがどの程度うまく機能するかを示します。ここでのパフォーマンスが優れている場合、モデルが基本的なテキスト分類パターンを学習したことを示しています。
**偏ったデータセット**は、本番稼働のシナリオで一般的である実際のクラスの不均衡をモデルがどのように処理するかを示します。
**困難なデータセット**は、本番環境に現れる可能性のある、あいまいなケースやエッジケースでモデルの堅牢性をテストします。
## モデルの選択
この体系的なアプローチを使用して、特定のユースケースに最適なモデルを選択します。
### ビジネスの優先順位を定義する
モデルを選択する前に、どのパフォーマンス要因がユースケースに最も重要かを判断します。
1. 精度要件と最小許容パフォーマンスしきい値を特定します。
1. リアルタイム (<100 ミリ秒) またはバッチ処理が必要かどうかなど、レイテンシーの制約を決定します。
1. 推論とスケーリングのコストに関する考慮事項と予算を確立します。
1. データ特性を分析して、本番稼働用データがバランスが取れているか、偏っているか、または高度に変動しているかを把握します。
### 各モデルを選択するタイミング
評価結果に基づいて、ユースケースに最適なモデルを選択します。
+ カスタマーサービスのチャットボット、コンテンツモデレーションシステム、または応答時間が 100 ミリ秒未満のアプリケーションにおけるリアルタイムのセンチメント分析など、精度の高い高速推論が必要な場合は、**DistilBERT を選択**します。
+ 法的文書分類、医療テキスト分析、精度が最優先されバッチ処理が許容されるコンプライアンスアプリケーションなど、最高精度が速度よりも重要である場合は、**BERT を選択**します。
### 評価データセットの優先順位付け
実際のユースケースを最もよく表すデータセットに焦点を当てます。
1. 実際のデータに最も近いデータセットに加重を追加します。
1. アプリケーションにおけるエッジケースの重要性を考慮し、これに応じて困難なデータセットのパフォーマンスを優先します。
1. 1 つのデータセットタイプのみに焦点を当てるのではなく、複数のシナリオで最適化のバランスを取ります。
これらの優先順位と評価結果を比較して、精度、速度、コスト要件のバランスに最適なモデルを選択します。
優先するモデルを選択したら、本番稼働のデプロイの準備が整います。「[モデルを大規模にデプロイする](jumpstart-text-classification-scale.md)」に進みます。
# モデルを大規模にデプロイする
SageMaker AI エンドポイントのオートスケーリングと CloudWatch モニタリングを設定して、本番環境に対応できるようにします。
## テキスト分類に本番稼働のモニタリングが重要な理由
テキスト分類ワークロードは、次の理由でモニタリングが必要です。
+ 処理バーストで可変トラフィックパターンが発生します。
+ 1 秒未満の応答時間が必要です。
+ オートスケーリングによるコスト最適化が必要です。
## 前提条件
開始する前に、以下の準備が整っていることを確認します。
+ 前のセクションからデプロイされた SageMaker AI エンドポイント
+ エンドポイント名 (jumpstart-dft-hf-tc など)
+ Your AWS リージョン (us-east-2 など）。
エンドポイントの作成またはトラブルシューティングについては、「[リアルタイム推論](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html)」を参照してください。
## 本番稼働のモニタリングを設定する
CloudWatch モニタリングを設定して、本番環境でのモデルのパフォーマンスを追跡します。
1. JupyterLab スペースで、前にアップロードした評価パッケージから `sagemaker_production_monitoring.ipynb` ノートブックを開きます。
1. 設定セクションでエンドポイント名とリージョンを更新します。
1. ノートブックの指示に従って、以下を設定します。
+ オートスケーリング (トラフィックに基づく 1～10 インスタンス)
+ レイテンシーと呼び出しのしきい値に関する CloudWatch アラーム
+ ビジュアルモニタリング用のメトリクスダッシュボード
## 設定を検証する
ノートブックの手順を完了したら、以下が整っていることを検証します。
+ **エンドポイントのステータス**: `InService`.
+ **オートスケーリング**: 1～10 インスタンス設定済み
+ **CloudWatch アラーム**: 2 つのアラームモニタリング
+ **メトリクス**: 15 以上のメトリクス登録済み
**注記**
アラームは最初に `INSUFFICIENT_DATA` と表示されることがあります。これは正常であり、使用状況に応じて `OK` に変わります。
## エンドポイントをモニタリングする
AWS マネジメントコンソールからビジュアルモニタリングにアクセスします。
+ [CloudWatch メトリクス](https://console.aws.amazon.com/cloudwatch/home#metricsV2:graph=~();query=AWS/SageMaker)
+ [CloudWatch アラーム](https://console.aws.amazon.com/cloudwatch/home#alarmsV2:)
詳細については「[ SageMaker AI をモニタリングする](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-overview.html)」を参照してください。
## コストの管理とリソースのクリーンアップ
モニタリング設定は貴重な本稼働インサイトを提供しますが、CloudWatch メトリクス、アラーム、自動スケーリングポリシーを通じて継続的な AWS 料金が発生します。これらのコストを管理する方法を理解することは、費用対効果の高い運用には不可欠です。不要になったプロジェクトリソースをクリーンアップします。
**警告**
リクエストを処理していない場合でも、エンドポイントには引き続き料金が発生します。すべての料金を停止するには、エンドポイントを削除する必要があります。手順については、「[エンドポイントとリソースを削除する](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html)」を参照してください。
高度なモニタリング設定については、「[SageMaker AI 向けの CloudWatch メトリクス](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-cloudwatch.html)」を参照してください。
# SageMaker Clarify を使用した公平性、モデルの説明可能性、バイアス検出
Amazon SageMaker Clarify を使用すると、公平性とモデルの説明可能性を把握し、モデル内のバイアスを説明したり検出したりできます。バイアスのメトリクスと Feature Attribution を計算し、モデルの説明可能性に関するレポートを生成するように、SageMaker Clarify 処理ジョブを設定できます。SageMaker Clarify 処理ジョブは専用の SageMaker Clarify コンテナイメージを使用して実装されます。次のページでは、SageMaker Clarify の仕組みと分析の開始方法について説明します。
## 機械学習予測の公平性とモデルの説明可能性とは
機械学習 (ML) モデルは、金融サービス、ヘルスケア、教育、人事などの分野で意思決定を支援しています。政治家、規制当局、支持者の間では、ML とデータ駆動型システムがもたらす倫理的およびポリシー上の課題についての認識が高まっています。Amazon SageMaker Clarify を使用すると、ML モデルが特定の予測を行った理由と、このようなバイアスがトレーニング中または推論中にこの予測に影響を及ぼすかを把握できます。SageMaker Clarify は、バイアスが少なく、理解しやすい機械学習モデルの構築に役立つツールも提供しています。SageMaker Clarify を使用すると、リスクおよびコンプライアンスチームや外部規制当局に提供できるモデルガバナンスレポートを生成することもできます。SageMaker Clarify を使用すると、以下を行うことができます。
+ モデル予測のバイアスを検出し、説明するうえで役立ちます。
+ 事前トレーニングデータのバイアスのタイプを特定できます。
+ トレーニング中またはモデルの本番稼働中に発生する可能性のある、トレーニング済みデータにおけるバイアスのタイプを特定できます。
SageMaker Clarify は、Feature Attribution を使用してモデルが予測を行う方法を説明するうえで役立ちます。本番稼働中の推論モデルをモニタリングして、バイアスと Feature Attribution ドリフトの両方を検出することもできます。このような情報は以下の確認に役立ちます。
+ **規制** – 政治家やその他の規制当局は、ML モデルからの出力を使用する決定の差別的な影響についての懸念を抱く可能性があります。例えば、ML モデルがバイアスをエンコードして、自動化された意思決定に影響を及ぼす可能性があります。
+ **ビジネス** – 規制対象ドメインでは、ML モデルによる予測方法について信頼性の高い説明が必要になる場合があります。モデルの説明可能性は、信頼性、安全性、コンプライアンスに依存する業界では、とりわけ重要になります。これには、金融サービス、人事、医療、自動輸送などの業界があります。例えば、融資アプリケーションでは、ML モデルが特定の予測をどのように行ったかについて、ローン担当者、予測担当者、顧客に説明することが必要になる場合があります。
+ **データサイエンス** – モデルがノイズの多い特徴量や関連性のない特徴量に基づいて推論を行っていないかどうかを判断できる場合、データサイエンティストや ML エンジニアは ML モデルをデバッグして改善できます。モデルの制限や、モデルで発生する可能性のある障害モードを把握することもできます。
SageMaker Clarify を SageMaker AI パイプラインに統合する不正自動車クレームの完全な機械学習モデルを設計および構築する方法を示すブログ投稿については、「Architect」を参照し、 SageMaker 「エンドツーエンドの Amazon SageMaker AI デモ」を使用して完全な機械学習ライフサイクルを構築してください。 [AWS end-to-end Amazon SageMaker ](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/) このブログ記事では、トレーニング前とトレーニング後のバイアスを評価して軽減する方法と、特徴量がモデル予測に及ぼす影響について説明しています。このブログ記事には、ML ライフサイクルの各タスクのサンプルコードへのリンクが提供されています。
### ML ライフサイクルにおける公平性と説明可能性を評価するためのベストプラクティス
**プロセスとしての公平性** - バイアスと公平性の概念は、利用方法により、異なります。バイアスの測定とバイアスメトリクスの選択は、社会的、法的、その他の非技術的考慮事項に左右される場合があります。公平性を考慮した ML アプローチの導入を成功に導くには、主要なステークホルダー間でコンセンサスを構築し、コラボレーションを実現する必要があります。これには、製品チーム、ポリシーチーム、法務チーム、エンジニアリングチーム、AI/ML チーム、エンドユーザー、コミュニティなどが関連します。
**ML ライフサイクルにおける公平性と説明可能性** – ML ライフサイクルの各段階で公平性と説明可能性を考慮します。このようなステージには、問題の形成、データセットの構築、アルゴリズムの選択、モデルトレーニングプロセス、テストプロセス、デプロイ、モニタリング、フィードバックなどがあります。この分析を行うには適切なツールを用意することが重要です。ML ライフサイクル中は、以下の問いを検討することをお勧めします。
+ このモデルは、公平でない結果が増大するフィードバックループを促進しているか
+ この問題について、アルゴリズムが倫理的ソリューションとなるか
+ トレーニングデータはさまざまなグループを代表しているか
+ ラベルや特徴量にバイアスはあるか
+ バイアスを軽減するためにデータを変更する必要があるか
+ 公平性の制約を目標関数に含める必要があるか
+ モデルは関連する公平性メトリクスを使用して評価されているか
+ ユーザー間に不平等な影響はあるか
+ モデルは、トレーニングまたは評価されていない母集団にデプロイされているか
![\[公平性とモデルの説明可能性を評価するプロセスのベストプラクティス。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify-best-practices-image.png)
### SageMaker の説明ガイドとバイアスドキュメント
バイアスは、モデルのトレーニング前とトレーニング後の両方のデータ内で発生する可能性があり、測定できます。SageMaker Clarify は、トレーニング後のモデル予測と本番環境にデプロイされたモデルの説明を提供できます。SageMaker Clarify は、本番環境のモデルをモニタリングしてベースラインの説明の Attribution ドリフトを検出し、必要に応じてベースインを計算することもできます。SageMaker Clarify を使用したバイアスの説明と検出に関するドキュメントの構成は、以下のとおりです。
+ バイアスと説明可能性のための処理ジョブの設定の詳細については、「[SageMaker Clarify 処理ジョブを設定する](clarify-processing-job-configure-parameters.md)」を参照してください。
+ モデルトレーニングに使用する前の前処理データでバイアスを検出する方法の詳細については、「[トレーニング前データのバイアス](clarify-detect-data-bias.md)」を参照してください。
+ トレーニング後のデータとモデルのバイアスを検出する方法の詳細については、「[トレーニング済みデータとモデルバイアス](clarify-detect-post-training-bias.md)」を参照してください。
+ トレーニング後のモデル予測を説明するモデルに依存しない Feature Attribution に関するアプローチの詳細については、「[モデルの説明可能性](clarify-model-explainability.md)」を参照してください。
+ モデルトレーニング中に確立されたベースラインからの特徴量貢献度のドリフトをモニタリングする方法については、「[本番稼働用モデルの Feature Attribution ドリフト](clarify-model-monitor-feature-attribution-drift.md)」を参照してください。
+ 実稼働中のモデルをベースラインドリフトについてモニタリングする方法の詳細については、「[本番稼働用モデルのバイアスドリフト](clarify-model-monitor-bias-drift.md)」を参照してください。
+ SageMaker AI エンドポイントからリアルタイムで説明を取得する方法については、「[SageMaker Clarify によるオンライン説明可能性](clarify-online-explainability.md)」を参照してください。
## SageMaker Clarify 処理ジョブの仕組み
SageMaker Clarify を使用すると、データセットやモデルを分析して説明可能性やバイアスを調べることができます。SageMaker Clarify 処理ジョブは、SageMaker Clarify 処理コンテナを使用して、入力データセットを含む Amazon S3 バケットとやり取りします。SageMaker Clarify を使用して、SageMaker AI 推論エンドポイントにデプロイされた顧客モデルを分析することもできます。
以下の図は、SageMaker Clarify 処理ジョブが入力データやオプションで顧客モデルとやり取りする方法を示しています。このやり取りは、実行される分析の種類によって異なります。SageMaker Clarify 処理コンテナは、S3 バケットから分析用の入力データセットと設定を取得します。特徴量分析を含む特定の解析タイプでは、SageMaker Clarify 処理コンテナはモデルコンテナにリクエストを送信する必要があります。次に、モデルコンテナが送信する応答からモデル予測を取得します。その後、SageMaker Clarify 処理コンテナは分析結果を計算して S3 バケットに保存します。
![\[SageMaker Clarify を使用すると顧客モデルを分析して説明可能性やバイアスを調べることができます。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify/clarify-processing-job.png)
SageMaker Clarify 処理ジョブは、機械学習ワークフローのライフサイクルの複数の段階で実行できます。SageMaker Clarify は、以下の分析タイプの計算に役立ちます。
+ トレーニング前のバイアスメトリクス トレーニング前のバイアスメトリクスは、データ内のバイアスを把握して対処し、より公平なデータセットでモデルをトレーニングできるようにするうえで役立ちます。トレーニング前のバイアスメトリクスの詳細については、「[トレーニング前のバイアスメトリクス](clarify-measure-data-bias.md)」を参照してください。トレーニング前のバイアスメトリクスを分析するジョブを実行するには、データセットと JSON 分析設定ファイルを [分析設定ファイル](clarify-processing-job-configure-analysis.md) に提供する必要があります。
+ トレーニング後のバイアスメトリクス トレーニング後のバイアスメトリクスは、アルゴリズム、選択したハイパーパラメータ、またはフローの初期段階では明らかではなかったバイアスを把握するうえで役立ちます。トレーニング後のバイアスメトリクスの詳細については、「[トレーニング済みデータのメトリクスとモデルのバイアスのメトリクス](clarify-measure-post-training-bias.md)」を参照してください。SageMaker Clarify では、データやラベルに加えてモデル予測も使用してバイアスを見つけ出します。トレーニング後のバイアスメトリクスを分析するジョブを実行するには、データセットと JSON 分析設定ファイルを提供する必要があります。設定にはモデル名またはエンドポイント名を含める必要があります。
+ Shapley 値は、特徴量がモデルの予測にどのような影響を及ぼすかを理解するうえで役立ちます。Shapley 値の詳細については、「[Shapley 値を使用する特徴属性](clarify-shapley-values.md)」を参照してください。この特徴量にはトレーニング済みのモデルが必要です。
+ Partial Dependence Plot (PDP) は、単一の特徴量の値を変化させた場合に、予測されるターゲット変数がどの程度変化するかを理解するうえで役立ちます。PDP の詳細については、「[部分依存プロット (PDP) 分析](clarify-processing-job-analysis-results.md#clarify-processing-job-analysis-results-pdp)」を参照してください。PDP 機能を使用するには、トレーニング済みのモデルが必要です。
SageMaker Clarify では、トレーニング後のバイアスメトリクスと特徴量属性を計算するためのモデル予測が必要です。エンドポイントを指定するか、SageMaker Clarify がモデル名を使用してエフェメラルエンドポイント (別名シャドウエンドポイント) を作成します。**SageMaker Clarify コンテナは、計算終了後にシャドウエンドポイントを削除します。大まかに言うと、SageMaker Clarify コンテナは次の手順を実行します。
1. 入力とパラメータを検証します。
1. シャドウエンドポイントを作成します (モデル名が提供されている場合)。
1. 入力データセットをデータフレームに読み込みます。
1. 必要に応じて、エンドポイントからモデル予測を取得します。
1. バイアスメトリクスと特徴量属性を計算します。
1. シャドウエンドポイントを削除します。
1. 分析結果を生成します。
SageMaker Clarify 処理ジョブが完了すると、分析結果はジョブの処理出力パラメータで指定した出力場所に保存されます。この結果には、バイアスメトリクスとグローバル特徴量属性を含む JSON ファイル、ビジュアルレポート、ローカル特徴量属性の追加ファイルが含まれます。結果は出力場所からダウンロードして表示できます。
バイアスメトリクス、説明可能性、それらの解釈方法に関する追加情報については、「[Learn How Amazon SageMaker Clarify Helps Detect Bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias)」、「[Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」、「[Amazon AI Fairness and Explainability Whitepaper](https://pages.awscloud.com/rs/112-TZM-766/images/Amazon.AI.Fairness.and.Explainability.Whitepaper.pdf)」を参照してください。
# SageMaker Clarify 処理ジョブを設定する
SageMaker Clarify を使用してデータとモデルのバイアスと説明可能性を分析するには、SageMaker Clarify 処理ジョブを設定する必要があります。このガイドでは、処理ジョブの入力データセット名、分析設定ファイル名、出力場所を指定する方法を示します。処理コンテナ、ジョブの入力、出力、リソース、その他のパラメータを設定するには、2 つのオプションがあります。SageMaker AI `CreateProcessingJob` API を使用するか、SageMaker Python SDK API `SageMaker ClarifyProcessor` を使用できます。
すべての処理ジョブに共通するパラメータの詳細については、「[Amazon SageMaker API リファレンス](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp)」を参照してください。
## SageMaker API を使用して SageMaker Clarify 処理ジョブを設定する
以下の手順は、`CreateProcessingJob` API を使用して SageMaker Clarify 固有の設定の各部分を指定する方法を示しています。
1. 次のコード例に示すように、SageMaker Clarify コンテナイメージのユニフォームリサーチ識別子 (URI) を `AppSpecification` パラメータに入力します。
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**注記**
事前構築済みの SageMaker Clarify コンテナイメージは、URI で識別することができる必要があります。`ContainerEntrypoint` と `ContainerArguments` はサポートされていません。SageMaker Clarify コンテナイメージの詳細については、「[構築済みの SageMaker Clarify コンテナ](clarify-processing-job-configure-container.md)」を参照してください。
1. 分析の設定と入力データセットのパラメータの両方を `ProcessingInputs` パラメータ内に指定します。
1. バイアス分析と説明可能性分析のパラメータを含む JSON 分析設定ファイルの場所を指定します。`ProcessingInput` オブジェクトの `InputName` パラメータは、次のコード例に示すとおり **analysis\$1config** でなければなりません。
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
分析設定ファイルのスキーマの詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
1. 入力データセットの場所を指定します。`ProcessingInput` オブジェクトの `InputName` パラメータは `dataset` でなければなりません。分析設定ファイルに "dataset\$1uri" を指定している場合、このパラメータはオプションです。`S3Input` 設定には以下の値が必要です。
1. `S3Uri` は Amazon S3 オブジェクトまたは S3 プレフィックスのいずれかになります。
1. `S3InputMode` は **File** タイプでなければなりません。
1. `S3CompressionType` は `None` タイプ (デフォルト値) でなければなりません。
1. `S3DataDistributionType` は `FullyReplicated` タイプ (デフォルト値) でなければなりません。
1. `S3DataType` は `S3Prefix` または `ManifestFile` のいずれかになります。`ManifestFile` を使用するには、`S3Uri` パラメータに SageMaker API リファレンスセクション [S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri) のスキーマに従うマニフェストファイルの場所を指定する必要があります。このマニフェストファイルには、ジョブの入力データを含む S3 オブジェクトが一覧表示されている必要があります。
次のコードは、入力設定の例を示しています。
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. 処理ジョブの出力設定を `ProcessingOutputConfig` パラメータ内に指定します。`Outputs` 設定には `ProcessingOutput` オブジェクトが 1 つ必要です。出力設定には以下が必要です。
1. `OutputName` は **analysis\$1result** である必要があります。
1. `S3Uri` は出力場所の S3 プレフィックスである必要があります。
1. `S3UploadMode` を **EndOfJob** に設定する必要があります。
次のコードは、出力設定の例を示しています。
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. `ProcessingResources`処理ジョブで使用するリソースの設定 `ClusterConfig` を パラメータ内に指定します。`ClusterConfig` オブジェクト内では次のパラメータが必要です。
1. `InstanceCount` は処理ジョブを実行するクラスター内のコンピューティングインスタンスの数を指定します。分散処理を有効にするには、1 より大きい値を指定します。
1. `InstanceType` は処理ジョブを実行するリソースを指します。SageMaker AI SHAP 分析はコンピューティング集約的であるため、コンピューティング用に最適化されたインスタンスタイプを使用すると、分析の実行時間を改善できます。SageMaker Clarify の処理ジョブは GPU を使用しません。
次のコードは、リソース設定の例を示しています。
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. `NetworkConfig` オブジェクト内の処理ジョブで使用するネットワークの設定を指定します。設定には以下の値が必要です。
1. SageMaker Clarify が必要に応じて予測用のエンドポイントを呼び出せるように、`EnableNetworkIsolation` を `False` (デフォルト) に設定する必要があります。
1. SageMaker Clarify ジョブに指定したモデルまたはエンドポイントが Amazon Virtual Private Cloud (Amazon VPC) 内にある場合、SageMaker Clarify ジョブも同じ VPC 内にある必要があります。[VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html) を使用して VPC を指定します。また、VPC には Amazon S3 バケット、SageMaker サービス、SageMaker ランタイムサービスへのエンドポイントが必要です。
分散型処理が有効の場合、同じ処理ジョブ内の異なるインスタンス間の通信を許可する必要もあります。同じセキュリティグループのメンバー間のインバウンド接続を許可するセキュリティグループのルールを設定します。詳細については、「[Amazon VPC のリソースへのアクセス権を Amazon SageMaker Clarify ジョブに付与する](clarify-vpc.md)」を参照してください。
次のコードは、ネットワーク設定の例を示しています。
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. `StoppingCondition` パラメータを使用してジョブの最大実行時間を設定します。SageMaker Clarify ジョブが実行できる最長時間は `7` 日または `604800` 秒です。この制限時間内にジョブを完了できない場合、ジョブは停止され、分析結果は提供されません。例えば、以下の設定ではジョブを実行できる最大時間を 3600 秒に制限しています。
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. `RoleArn` パラメータの IAM ロールを指定します。このロールには Amazon SageMaker AI との信頼関係が必要です。これを使用して、次の表に記載されている SageMaker API 操作を実行できます。SageMaker AI へのフルアクセスを許可する Amazon SageMaker AIFullAccess マネージドポリシーを使用することをお勧めします。このポリシーの詳細については、[AWS マネージドポリシー: AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess) を参照してください。フルアクセス許可の付与について懸念がある場合、必要な最小限のアクセス許可は、モデル名とエンドポイント名のどちらを指定するかによって異なります。エンドポイント名を使用すると、SageMaker AI に付与する許可を低減できます。
以下の表には、SageMaker Clarify 処理ジョブで使用される API 操作が記載されています。**モデル名**と**エンドポイント名**の下の **X** は、各入力に必要な API 操作を示しています。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
必要なアクセス許可の詳細については、「[Amazon SageMaker AI API アクセス許可: アクション、アクセス許可、リソースの参照](api-permissions-reference.md)」を参照してください。
SageMaker AI へのロールの受け渡しの詳細については、「[ロールを渡す](sagemaker-roles.md#sagemaker-roles-pass-role)」を参照してください。
処理ジョブの設定を個別に作成したら、それらを組み合わせてジョブを設定します。
## AWS SDK for Python を使用して SageMaker Clarify 処理ジョブを設定する
以下のコード例は、[AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) を使用して SageMaker Clarify 処理ジョブを起動する方法を示しています。
```
sagemaker_client.create_processing_job(
ProcessingJobName="your-clarify-job-name",
AppSpecification={
"ImageUri": "the-clarify-container-image-uri",
},
ProcessingInputs=[{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config",
},
}, {
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data",
},
},
],
ProcessingOutputConfig={
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output",
},
}],
},
ProcessingResources={
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20,
},
},
NetworkConfig={
"EnableNetworkIsolation": False,
"VpcConfig": {
...
},
},
StoppingCondition={
"MaxRuntimeInSeconds": 3600,
},
RoleArn="arn:aws:iam:::role/service-role/AmazonSageMaker-ExecutionRole",
)
```
AWS SDK for Python を使用して SageMaker Clarify 処理ジョブを実行する手順を含むノートブックの例については、[AWS 「 SDK for Python を使用した SageMaker Clarify の公平性と説明可能性](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb)」を参照してください。ノートブックで使用する S3 バケットは、それにアクセスするノートブックインスタンスと同じ AWS リージョンに存在する必要があります。
## SageMaker Python SDK を使用して SageMaker Clarify 処理ジョブを設定する
SageMaker Python SDK API の [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor) を使用して SageMaker Clarify 処理ジョブを設定することもできます。詳細については、「[バイアス分析と説明可能性のための SageMaker Clarify 処理ジョブを実行する](clarify-processing-job-run.md)」を参照してください。
**Topics**
+ [構築済みの SageMaker Clarify コンテナ](clarify-processing-job-configure-container.md)
+ [分析設定ファイル](clarify-processing-job-configure-analysis.md)
+ [データ形式互換性ガイド](clarify-processing-job-data-format.md)
# 構築済みの SageMaker Clarify コンテナ
Amazon SageMaker AI は、説明可能性のために、バイアスメトリクスと特徴属性を計算するために必要なライブラリやその他の依存関係を含む、事前ビルド済みの SageMaker Clarify コンテナイメージを提供します。これらのイメージは、アカウントで SageMaker Clarify [処理ジョブ](processing-job.md)を実行できます。
コンテナのイメージ URI は、次の形式になります。
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
例えば、次のようになります。
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
次の表は、 によるアドレスの一覧です AWS リージョン。
SageMaker Clarify 処理ジョブ用の Docker イメージ
| リージョン | イメージアドレス |
| --- | --- |
| 米国東部 (バージニア北部) | 205585389593.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 米国東部 (オハイオ) | 211330385671.dkr.ecr.us-east-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 米国西部 (北カリフォルニア) | 740489534195.dkr.ecr.us-west-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 米国西部 (オレゴン) | 306415355426.dkr.ecr.us-west-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (香港) | 098760798382.dkr.ecr.ap-east-1.amazonaws.com/sagemaker-clarify-processing: 1.0 |
| アジアパシフィック (ムンバイ) | 452307495513.dkr.ecr.ap-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (ジャカルタ) | 705930551576.dkr.ecr.ap-southeast-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (東京) | 377024640650.dkr.ecr.ap-northeast-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (ソウル) | 263625296855.dkr.ecr.ap-northeast-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (大阪) | 912233562940.dkr.ecr.ap-northeast-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (シンガポール) | 834264404009.dkr.ecr.ap-southeast-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アジアパシフィック (シドニー) | 007051062584.dkr.ecr.ap-southeast-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| カナダ (中部) | 675030665977.dkr.ecr.ca-central-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (フランクフルト) | 017069133835.dkr.ecr.eu-central-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (チューリッヒ) | 730335477804.dkr.ecr.eu-central-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (アイルランド) | 131013547314.dkr.ecr.eu-west-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (ロンドン) | 440796970383.dkr.ecr.eu-west-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (パリ) | 341593696636.dkr.ecr.eu-west-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (ストックホルム) | 763603941244.dkr.ecr.eu-north-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 中東 (バーレーン) | 835444307964.dkr.ecr.me-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 南米 (サンパウロ) | 520018980103.dkr.ecr.sa-east-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| アフリカ (ケープタウン) | 811711786498.dkr.ecr.af-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 欧州 (ミラノ) | 638885417683.dkr.ecr.eu-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 中国 (北京) | 122526803553---dkr---ecr---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn/sagemaker-clarify-processing:1.0 |
| 中国 (寧夏) | 122578899357---dkr---ecr---cn-northwest-1.amazonaws.com.rproxy.govskope.ca.cn/sagemaker-clarify-processing:1.0 |
# 分析設定ファイル
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 プロセッサに指示します。
# データ形式互換性ガイド
このガイドでは、SageMaker Clarify 処理ジョブと互換性のあるデータ形式タイプについて説明します。サポートされているデータ形式のタイプには、ファイル拡張子、データ構造、表形式、画像、時系列データセットの特定の要件または制限などがあります。このガイドでは、データセットがこれらの要件を満たしているかどうかを確認する方法についても説明します。
大まかに言うと、SageMaker Clarify 処理ジョブは、入力－処理－出力モデルに従ってバイアスメトリクスと特徴量属性を計算します。詳細については、次の例を参照してください。
SageMaker Clarify 処理ジョブへの入力は、以下の内容で構成されています。
+ 分析対象のデータセット。
+ 分析設定。分析の設定方法の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
SageMaker Clarify は処理段階でバイアスメトリクスと特徴量属性を計算します。SageMaker Clarify 処理ジョブはバックエンドで次のステップを完了します。
+ SageMaker Clarify 処理ジョブは、分析設定を解析し、**データセット**を読み込みます。
+ トレーニング後のバイアスメトリクスと特徴量属性を計算するには、ジョブにはモデルからのモデル予測が必要です。SageMaker Clarify 処理ジョブはデータをシリアル化し、SageMaker AI リアルタイム推論**エンドポイント**にデプロイされたモデルに**リクエスト**として送信します。その後、SageMaker Clarify 処理ジョブは**レスポンス**から予測を引き出します。
+ SageMaker Clarify 処理ジョブは、バイアスと説明可能性の分析を実行し、結果を出力します。
詳細については、「[SageMaker Clarify 処理ジョブの仕組み](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works)」を参照してください。
データの形式を指定するために使用するパラメータは、次のように、処理フロー内のデータが使用される場所によって異なります。
+ **入力データセット**の場合は、`dataset_type` パラメータを使用して形式または MIME タイプを指定します。
+ エンドポイントへの**リクエスト**の場合、`content_type` パラメータを使用して形式を指定します。
+ エンドポイントからの**レスポンス**の場合、`accept_type` パラメータを使用して形式を指定します。
入力データセット、リクエスト、エンドポイントへのレスポンスとエンドポイントからの応答に、同じ形式は必要ありません。例えば、次の条件を満たせば、Parquet データセットを CSV **リクエスト**ペイロードと JSON Lines **レスポンス**ペイロードで使用できます。
+ 分析は正しく設定されています。
+ モデルはリクエストとレスポンスの形式をサポートしています。
**注記**
`content_type` または `accept_type` が指定されていない場合、SageMaker Clarify コンテナは `content_type` と `accept_type` を推測します。
**Topics**
+ [表形式のデータ](clarify-processing-job-data-format-tabular.md)
+ [画像データの要件](clarify-processing-job-data-format-image.md)
+ [時系列データ](clarify-processing-job-data-format-time-series.md)
# 表形式のデータ
表形式データとは、2 次元のデータフレームに読み込むことができるデータを指します。フレーム内の各行は 1 つのレコードを表し、各レコードには 1 つ以上の列があります。各データフレームセル内の値は、数値、カテゴリ、またはテキストデータ型にすることができます。
## 表形式データセットの前提条件
分析する前に、データセットには必要な前処理ステップが既に適用されている必要があります。これには、データクリーニングや特徴量エンジニアリングが含まれます。
1 つまたは複数のデータセットを提供できます。複数のデータセットを提供する場合は、以下を使用して SageMaker Clarify 処理ジョブでそれらを識別します。
+ `dataset` という名前の [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html) または分析設定 `dataset_uri` のいずれかを使用してメインデータセットを指定します。`dataset_uri` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」の「パラメータリスト」を参照してください。
+ 分析析設定ファイルにある `baseline` パラメータを使用します。SHAP 分析にはベースラインデータセットが必要です。分析設定ファイルの詳細と例については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
次の表は、サポートされているデータ形式、ファイル拡張子、MIME タイプの一覧です。
| データ形式 | ファイル拡張子 | MIME タイプ |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| JSON Lines | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | "application/x-parquet" |
以下のセクションでは、CSV、JSON Lines、Apache Parquet 形式の表形式データセットの例を示します。
### CSV 形式の表形式データセットの前提条件
SageMaker Clarify 処理ジョブは、[csv.excel](https://docs.python.org/3/library/csv.html#csv.excel) 方言の CSV データファイルを読み込むように設計されています。ただし、`\n` や `\r` を含む他の行末記号もサポートできる柔軟性があります。
互換性を保つため、SageMaker Clarify 処理ジョブに提供されるすべての CSV データファイルは UTF-8 でエンコードされている必要があります。
データセットにヘッダー行が含まれていない場合は、次の操作を行います。
+ 分析設定ラベルを インデックス `0` に設定します。つまり、最初の列はグラウンドトゥルースラベルです。
+ パラメータ `headers` が設定されている場合は、`label` をラベル列ヘッダーに設定してラベル列の位置を指定します。その他の列はすべて特徴量として指定されます。
以下は、ヘッダー行が含まれていないデータセットの例です。
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
データにヘッダー行が含まれている場合は、パラメータ `label` を インデックス `0` に設定します。ラベル列の位置を示すには、グラウンドトゥルースラベルヘッダーの `Label` を使用します。その他の列はすべて特徴量として指定されます。
以下は、ヘッダー行が含まれているデータセットの例です。
```
Label,Rating,A12,A13,Comments
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
### JSON 形式の表形式データセットの前提条件
JSON は、あらゆるレベルの複雑さを含む構造化データを表現するための柔軟な形式です。SageMaker Clarify の JSON サポートは特定の形式に限定されないため、CSV 形式や JSON Lines 形式のデータセットと比べて、より柔軟にデータ形式を使用できます。このガイドでは、JSON 形式の表形式データの分析設定を行う方法を説明します。
**注記**
互換性を保証するため、SageMaker Clarify 処理ジョブに提供されるすべての JSON データファイルは UTF-8 でエンコードされている必要があります。
以下は、最上位キー、特徴量のリスト、ラベルを含むレコードのある入力データの例です。
```
[
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0},
...
]
```
前の入力サンプルデータセットの設定分析の例では、以下のパラメータを設定する必要があります。
+ `label` パラメータは [JMESPath](https://jmespath.org/) 式 `[*].label` を使用して、データセット内の各レコードのグラウンドトゥルースラベルを抽出する必要があります。JMESPath 式は、i 番目のラベルが i 番目のレコードに対応するラベルのリストを生成する必要があります。
+ `features` パラメータは JMESPath 式 `[*].features` を使用して、データセット内の各レコードの特徴の配列を抽出する必要があります。JMESPath 式は、i 番目の行に i 番目のレコードに対応する特徴量値を含む 2D 配列または行列を生成する必要があります。
以下は、最上位キーと、各レコードの特徴量とラベルのリストを含むネストされたキーのあるレコードを持つ入力データの例です。
```
{
"data": [
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
]
}
```
前の入力サンプルデータセットの設定分析の例では、以下のパラメータを設定する必要があります。
+ `label` パラメータは [JMESPath](https://jmespath.org/) 式 `data[*].label` を使用して、データセット内の各レコードのグラウンドトゥルースラベルを抽出します。JMESPath 式は、i 番目のラベルが i 番目のレコードに対応するラベルのリストを生成する必要があります。
+ `features` パラメータは JMESPath 式 `data[*].features` を使用して、データセット内の各レコードの特徴量の配列を抽出します。JMESPath 式は、i 番目の行に i 番目のレコードの特徴量値を含む 2D 配列または行列を生成する必要があります。
### JSON Lines 形式の表形式データセットの前提条件
JSON Lines は、各行が有効な JSON オブジェクトである構造化データを表すテキスト形式です。現時点では、SageMaker Clarify 処理ジョブは SageMaker AI の高密度形式の JSON Lines のみをサポートしています。必要な形式に準拠するには、レコードのすべての特徴量を 1 つの JSON 配列にまとめる必要があります。JSON 行の詳細については、「[JSONLINES リクエストの形式](cdf-inference.md#cm-jsonlines)」を参照してください。
**注記**
SageMaker Clarify 処理ジョブに提供されるすべての JSON Lines データファイルは、互換性を確保するために UTF-8 でエンコードされる必要があります。
以下は、**最上位キー**と要素の**リスト**を含むレコードの分析設定を設定する方法の例です。
```
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}
...
```
前のデータセットの例の設定分析では、パラメータを次のように設定する必要があります。
+ グラウンドトゥルースラベルの位置を示すには、パラメータ `label` を JMESPath 式 `label` に設定する必要があります。
+ 特徴量の配列の位置を示すには、パラメータ `features` を JMESPath 式 `features` に設定する必要があります。
以下は、**最上位キー**と、要素の**リスト**を含む**ネストされたキー**を持つレコードの分析設定を行う方法の例です。
```
{"data":{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}}
{"data":{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
...
```
前のデータセットの例の設定分析では、パラメータを次のように設定する必要があります。
+ グラウンドトゥルースラベルの位置を示すには、パラメータ `label` を JMESPath 式 `data.label` に設定する必要があります。
+ パラメータ `features` は、特徴量の配列の位置を示す JMESPath 式 `data.features` に設定する必要があります。
### Parquet 形式の表形式データセットの前提条件
[Parquet](https://parquet.apache.org/) は列指向の二項データ形式です。現在、SageMaker Clarify 処理ジョブは、処理インスタンス数が `1` の場合のみ Parquet データファイルの読み込みをサポートしています。
SageMaker Clarify 処理ジョブは Parquet 形式のエンドポイントリクエストまたはエンドポイントレスポンスをサポートしないため、分析設定パラメータ `content_type` をサポートされている形式に設定してエンドポイントリクエストのデータ形式を指定する必要があります。詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」の `content_type` を参照してください。
Parquet データには、文字列形式の列名が必要です。分析設定 `label` パラメータを使用して、グラウンドトゥルースラベルの位置を示すラベル列名を設定します。その他の列はすべて特徴量として指定されます。
# 表形式データに対するエンドポイントリクエスト
トレーニング後のバイアス分析と特徴量重要度分析のモデル予測を取得するために、SageMaker Clarify 処理ジョブは表形式のデータをバイトにシリアル化し、それらをリクエストペイロードとして推論エンドポイントに送信します。この表形式のデータは、入力データセットから取得されるか、生成されます。合成データの場合は、SHAP 分析または PDP 分析用に explainer が生成します。
リクエストペイロードのデータ形式は、分析設定 `content_type` パラメータで指定する必要があります。パラメータが指定されていない場合、SageMaker Clarify 処理ジョブは `dataset_type` パラメータの値をコンテンツタイプとして使用します。`content_type` または `dataset_type` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
以下のセクションでは、CSV 形式と JSON Lines 形式のエンドポイントリクエストの例を示します。
## CSV 形式のエンドポイントリクエスト
SageMaker Clarify 処理ジョブは、データを CSV 形式 (MIME タイプ: `text/csv`) にシリアル化できます。次の表は、シリアル化されたリクエストペイロードの例を示しています。
| エンドポイントリクエストペイロード (文字列表現) | コメント |
| --- | --- |
| '1,2,3,4' | 単一レコード (4 つの数値特徴量)。 |
| '1,2,3,4\$1n5,6,7,8' | 改行 '\$1n' で区切られた 2 つのレコード。 |
| '"これはよい製品です",5' | 単一レコード (テキスト特徴量と数値特徴量)。 |
| ‘"これはよい製品です",5\$1n"悪いショッピング体験",1’ | 2 つのレコード |
## エンドポイントリクエストは JSON ライン形式である
SageMaker Clarify 処理ジョブは、データを SageMaker AI JSON 行の高密度形式 (MIME タイプ: `application/jsonlines`) にシリアル化できます。JSON 行の詳細については、「[JSONLINES リクエストの形式](cdf-inference.md#cm-jsonlines)」を参照してください。
表形式のデータを JSON データに変換するには、分析設定 `content_template` パラメータにテンプレート文字列を指定します。`content_template` の詳細については、[分析設定ファイル](clarify-processing-job-configure-analysis.md)を参照してください。次の表は、シリアル化された JSON Lines リクエストペイロードの例を示しています。
| エンドポイントリクエストペイロード (文字列表現) | コメント |
| --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 単一レコード。この場合、テンプレートは `'{"data":{"features":$features}}' ` のリストのようになり、`$features` は特徴量リスト `[1,2,3,4]` に置き換えられます。 |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1\$1n\$1"data":\$1"features":[5,6,7,8]\$1\$1' | 2 つのレコード。 |
| '\$1"features":["これはよい製品です",5]\$1' | 単一レコード。この場合、テンプレートは `'{"features":$features}'` のリストのようになり、\$1features は特徴量リスト `["This is a good product",5]` に置き換えられます。 |
| '\$1"features":["これはよい製品です",5]\$1\$1n\$1"features":["悪いショッピング体験",1]\$1' | 2 つのレコード。 |
## エンドポイントリクエストは JSON ライン形式である
SageMaker Clarify 処理ジョブは、データを任意の JSON 構造 (MIME タイプ: `application/json`) にシリアル化できます。そのためには、分析設定 `content_template` パラメータにテンプレート文字列を指定する必要があります。これは SageMaker Clarify 処理ジョブによって外部の JSON 構造を構築するために使用されます。各レコードの JSON 構造を構築するために使用する `record_template` のテンプレート文字列も指定する必要があります。`content_template` と `record_template` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
**注記**
`content_template` と `record_template` は文字列パラメータであるため、JSON シリアル化構造の一部である二重引用符 (`"`) は、設定ではエスケープ文字として記載する必要があります。例えば、Python で二重引用符をエスケープしたい場合は、`content_template` に次のように入力できます。
```
"{\"data\":{\"features\":$record}}}"
```
次の表は、シリアル化された JSON リクエストペイロードと、その構築に必要な対応する `content_template` パラメータと `record_template` パラメータの例を示しています。
| エンドポイントリクエストペイロード (文字列表現) | コメント | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 一度に 1 つのレコード。 | '\$1"data":\$1"features":\$1record\$1\$1\$1' | “\$1features" |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | 特徴量名を含むマルチレコード。 | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | “\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | マルチレコードとキーと値のペア。 | “\$1records" | “\$1features\$1kvp" |
| ‘\$1"A": 0, "B": 1\$1' | 一度に 1 つのレコードとキーと値のペア | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "nested": \$1"B": 1\$1\$1' | 代替方法として、任意の構造に対して非常に詳細な Record\$1template を使用します。 | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# 表形式データに対するエンドポイントレスポンス
SageMaker Clarify 処理ジョブは、推論エンドポイント呼び出しのレスポンスを受信すると、レスポンスペイロードを逆シリアル化し、そこから予測を引き出します。分析設定 `accept_type` パラメーターを使用して、レスポンスペイロードのデータ形式を指定します。`accept_type` が指定されていない場合、SageMaker Clarify 処理ジョブは content\$1type パラメータの値をモデル出力形式として使用します。`accept_type` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
予測は、バイアス分析の予測ラベル、または特徴量重要度分析の確率値 (スコア) のいずれかで構成されます。`predictor` 分析設定では、次の 3 つのパラメータを使用して予測を引き出します。
+ パラメータ `probability` は、エンドポイントレスポンスの確率値 (スコア) を特定するために使用されます。
+ パラメータ `label` は、エンドポイントレスポンス内の予測ラベルを特定するために使用されます。
+ (オプション) パラメータ `label_headers` は、多クラスモデルの予測ラベルを指定します。
次のガイドラインは、CSV、JSON ライン、JSON 形式のエンドポイントレスポンスに関する説明です。
## エンドポイントレスポンスは CSV 形式
レスポンスペイロードが CSV 形式 (MIME タイプ: `text/csv`) の場合、SageMaker Clarify 処理ジョブは各行を 逆シリアル化します。次に、分析設定で提供される列インデックスを使用して、逆シリアル化されたデータから予測を引き出します。レスポンスペイロードの行は、リクエストペイロードのレコードと一致する必要があります。
次の表は、さまざまな形式とさまざまな問題タイプのレスポンスデータの例を示しています。分析設定に従って予測を引き出せれば、データはこれらの例と異なっていても問題ありません。
以下のセクションでは、CSV 形式のエンドポイントレスポンスの例を示します。
### エンドポイントレスポンスは CSV 形式で、確率のみが含まれています。
次の表は、リグレッション問題と二項分類問題に対するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード。 | '0.6' |
| 2 つのレコード (結果は 1 行で、カンマで区切られます)。 | '0.6,0.3' |
| 2 つのレコード (結果は 2 行になります)。 | '0.6\$1n0.3' |
前の例では、エンドポイントは予測ラベルの単一の確率値 (スコア) を出力します。インデックスを使用して確率を抽出し、それを特徴量重要度分析に使用するには、分析設定パラメータ `probability` を column index `0` に設定します。これらの確率は、`probability_threshold` パラメータを使用してバイナリ値に変換すれば、バイアス分析にも使用できます。`probability_threshold` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
次の表は、多クラス問題に対するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 多クラスモデル (3 つのクラス) の 1 つのレコード。 | '0.1,0.6,0.3' |
| 多クラスモデルの 2 つのレコード (3 つのクラス)。 | '0.1,0.6,0.3\$1n0.2,0.5,0.3' |
前の例では、エンドポイントは確率 (スコア) のリストを出力します。インデックスが指定されていない場合は、すべての値が抽出され、特徴量重要度分析に使用されます。分析析設定 `label_headers` パラメータが指定されます。すると、SageMaker Clarify 処理ジョブは、バイアス分析に使用できる予測ラベルとして最大確率のラベルヘッダーを選択できます。`label_headers` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
### エンドポイントレスポンスは CSV 形式で、予測ラベルのみが含まれている
次の表は、リグレッション問題と二項分類問題に対するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード。 | '1' |
| 2 つのレコード (結果は 1 行で、カンマで区切られます) | '1,0' |
| 2 つのレコード (結果は 2 行になります) | '1\$1n0' |
前の例では、エンドポイントは確率ではなく予測ラベルを出力します。`predictor` 設定の `label` パラメータを column index `0` に設定して、インデックスを使用して予測ラベルを抽出し、バイアス分析に使用できるようにします。
### エンドポイントレスポンスは CSV 形式で、予測ラベルと確率が含まれます。
次の表は、リグレッション問題と二項分類問題に対するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '1,0.6' |
| 2 つのレコード | '1,0.6\$1 n 0,0.3' |
前の例では、エンドポイントは確率ではなく予測ラベルとその確率を出力します。`predictor` 設定の `label` パラメータを column index `0` に設定し、`probability` を column index `1` に設定して両方のパラメータ値を抽出します。
### エンドポイントレスポンスは CSV 形式で、予測ラベルと確率 (多クラス) が含まれています。
Amazon SageMaker Autopilot でトレーニングした多クラスモデルは、予測ラベルと確率のリストの文字列表現を出力するように設定できます。次の表の例は、`predicted_label`、`probability`、`labels`、`probabilities` を出力するように設定されたモデルからのエンドポイントレスポンスの例を示しています。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"' |
| 2 つのレコード | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"\$1n""cat",0.7,[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.7, 0.2, 0.1]"' |
前の例では、SageMaker Clarify 処理ジョブを以下の方法で設定して予測を引き出せます。
バイアス分析では、前の例を以下のいずれかに設定できます。
+ `predictor` 設定の `label` パラメータを `0` に設定して、予測ラベルを抽出します。
+ パラメータを `2` に設定して予測ラベルを抽出し、`probability` を `3` に設定すると対応する確率を抽出します。SageMaker Clarify 処理ジョブでは、確率値が最も高いラベルを識別することで、予測ラベルを自動的に決定できます。前述の単一のレコードの例を参照すると、モデルは `cat`、`dog`、`fish` の 3 つのラベルを対応する確率の `0.1`、`0.6`、`0.3` で予測します。これらの確率に基づいて予測ラベルは `dog` です。これが最も高い確率値の `0.6` を持つラベルだからです。
+ `probability` を `3` に設定して確率を抽出します。`label_headers` が指定されている場合、SageMaker Clarify 処理ジョブでは、確率値が最も高いラベルヘッダーを識別することによって、予測ラベルを自動的に決定できます。
特徴量重要度分析では、前の例を以下のように設定できます。
+ `probability` を `3` に設定して、すべての予測ラベルの確率を抽出します。すると、すべてのラベルの特徴量属性が計算されます。顧客が `label_headers` を指定しない場合、予測ラベルは分析レポートのラベルヘッダーとして使用されます。
## エンドポイントリクエストが JSON Lines 形式である
レスポンスペイロードが JSON Lines 形式 (MIME タイプ: `application/jsonlines`) の場合、SageMaker Clarify 処理ジョブは各行を JSON として逆シリアル化します。次に、分析設定で提供される JMESPath 式を使用して、逆シリアル化されたデータから予測を引き出します。レスポンスペイロードの行は、リクエストペイロードのレコードと一致する必要があります。次の表は、さまざまな形式のレスポンスデータの例を示しています。分析設定に従って予測を引き出せれば、データはこれらの例と異なっていても問題ありません。
以下のセクションでは、JSON Lines 形式のエンドポイントレスポンスの例を示します。
### エンドポイントレスポンスは JSON Lines 形式で、確率のみが含まれている
次の表は、確率値 (スコア) のみを出力するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"score":0.6\$1' |
| 2 つのレコード | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' |
前の例では、分析設定パラメータ `probability` を JMESPath 式 "score" に設定して値を抽出しました。
### エンドポイントレスポンスは JSON Lines 形式で、予測ラベルのみが含まれている
次の表は、予測ラベルのみを出力するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"prediction":1\$1' |
| 2 つのレコード | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
前の例で、予測子設定の `label` パラメータを JMESPath 式の `prediction` に設定します。すると、SageMaker Clarify 処理ジョブは予測ラベルを抽出してバイアス分析を行うことができます。詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
### エンドポイントレスポンスは JSON Lines 形式で、予測ラベルと確率が含まれている
次の表は、予測ラベルとそのスコアを出力するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"prediction":1,"score":0.6\$1' |
| 2 つのレコード | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
前の例で、`predictor` 設定の `label` パラメータを JMESPath 式の "prediction" に設定して、予測ラベルを抽出します。`probability` を JMESPath 式 "score" に設定して確率を抽出します。詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
### エンドポイントレスポンスは JSON Lines 形式で、予測ラベルと確率 (多クラス) が含まれる
次の表は、以下を出力する多クラスモデルからのエンドポイントレスポンスの例です。
+ 予測ラベルのリスト。
+ 確率、選択した予測ラベルとその確率。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.1,0.6,0.3]\$1' |
| 2 つのレコード | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.7,0.2,0.1]\$1' |
前の例では、予測を引き出すために SageMaker Clarify 処理ジョブをいくつかの方法で設定できます。
バイアス分析では、前の例を以下の**いずれか**に設定できます。
+ `predictor` 設定の `label` パラメータを JMESPath 式 "predicted\$1label" に設定して、予測ラベルを抽出します。
+ パラメータを JMESPath 式 "predicted\$1label" に設定して、予測ラベルを抽出します。`probability` を JMESPath 式 "probabilities" に設定して確率を抽出します。SageMaker Clarify ジョブでは、確率値が最も高いラベルを識別することで、予測ラベルを自動的に決定します。
+ `probability` を JMESPath 式 "probabilities" に設定して確率を抽出します。`label_headers` が指定されている場合、SageMaker Clarify 処理ジョブでは、確率値が最も高いラベルを識別することによって、予測ラベルを自動的に決定できます。
特徴量重要度分析を行うには、次の操作を行います。
+ `probability` を JMESPath 式 "probabilities" に設定して、すべての予測ラベルの確率を抽出します。すると、すべてのラベルの特徴量属性が計算されます。
## エンドポイントレスポンスが JSON 形式である
レスポンスペイロードが JSON 形式 (MIME タイプ: `application/json`) の場合、SageMaker Clarify 処理ジョブはペイロード全体を JSON として逆シリアル化します。次に、分析設定で指定された JMESPath 式を使用して、逆シリアル化されたデータから予測を引き出します。レスポンスペイロードのレコードは、リクエストペイロードのレコードと一致する必要があります。
以下のセクションでは、JSON 形式のエンドポイントレスポンスの例を示します。このセクションには、さまざまな形式とさまざまな問題タイプのレスポンスデータの例を示す表が含まれています。分析設定に従って予測を引き出せれば、データはこれらの例と異なっていても問題ありません。
### エンドポイントレスポンスは JSON 形式で、確率のみが含まれている
次の表は、確率値 (スコア) のみを出力するエンドポイントレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '[0.6]' |
| 2 つのレコード | '[0.6,0.3]' |
前の例では、レスポンスペイロードに改行はありません。代わりに、1 つの JSON オブジェクトには、リクエスト内の各レコードに 1 つ、スコアのリストが含まれています。分析設定パラメータ `probability` を JMESPath 式 "[\$1]" に設定して値を抽出します。
### エンドポイントレスポンスは JSON 形式で、予測ラベルのみが含まれている
次の表は、予測ラベルのみを出力するエンドポイントからのレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"predicted\$1labels":[1]\$1' |
| 2 つのレコード | '\$1"predicted\$1labels":[1,0]\$1' |
`predictor` 設定の `label` パラメータを JMESPath 式 "predicted\$1labels" に設定すると、SageMaker Clarify 処理ジョブが予測ラベルを抽出してバイアス分析を行うことができます。
### エンドポイントレスポンスは JSON 形式で、予測ラベルと確率が含まれている
次の表は、予測ラベルとそのスコアを出力するエンドポイントからのレスポンスの例です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '\$1"predictions":[\$1"ラベル":1,"スコア":0.6\$1' |
| 2 つのレコード | ‘\$1"predictions":[\$1"ラベル":1,"スコア":0.6\$1,\$1"ラベル":0,"スコア":0.3\$1]\$1' |
前の例で、`predictor` 設定の `label` パラメータを JMESPath 式の "predictions[\$1].score" に設定して、予測ラベルを抽出します。`probability` を JMESPath 式 "predictions[\$1].score" に設定して確率を抽出します。
### エンドポイントレスポンスは JSON 形式で、予測ラベルと確率 (多クラス) が含まれます。
次の表は、以下を出力する多クラスモデルのエンドポイントからのレスポンスの例です。
+ 予測ラベルのリスト。
+ 確率、選択した予測ラベルとその確率。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 単一レコード | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.1,0.6,0.3]\$1]' |
| 2 つのレコード | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.1,0.6,0.3]\$1,\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["ネコ","イヌ","サカナ"],"probabilities":[0.7,0.2,0.1]\$1]' |
SageMaker Clarify 処理ジョブは、予測を引き出すいくつかの方法で設定できます。
バイアス分析では、前の例を以下の**いずれか**に設定できます。
+ `predictor` 設定の `label` パラメータを JMESPath 式 "[\$1].predicted\$1label" に設定して、予測ラベルを抽出します。
+ パラメータを JMESPath 式 "[\$1].predicted\$1labels" に設定して、予測ラベルを抽出します。`probability` を JMESPath 式 "[\$1].probabilities" に設定して確率を抽出します。SageMaker Clarify 処理ジョブでは、近接値が最も高いラベルを識別することで、予測ラベルを自動的に決定できます。
+ `probability` を JMESPath 式 "[\$1].probabilities" に設定して確率を抽出します。`label_headers` が指定されている場合、SageMaker Clarify 処理ジョブでは、確率値が最も高いラベルを識別することによって、予測ラベルを自動的に決定できます。
特徴量重要度分析では、`probability` を JMESPath 式 "[\$1].probabilities" に設定すると、すべての予測ラベルの確率を抽出できます。すると、すべてのラベルの特徴量属性が計算されます。
# エンドポイントのリクエストとレスポンスの表形式データを事前に確認する
モデルを SageMaker AI リアルタイム推論エンドポイントにデプロイし、エンドポイントにリクエストを送信することをお勧めします。リクエストとレスポンスを手動で調べて、両方が [表形式データに対するエンドポイントリクエスト](clarify-processing-job-data-format-tabular-request.md) セクションと [表形式データに対するエンドポイントレスポンス](clarify-processing-job-data-format-tabular-response.md) セクションの要件に準拠していることを確認してください。モデルコンテナがバッチリクエストをサポートしている場合は、1 つのレコードリクエストから始めて、その後 2 つ以上のレコードを試してみることができます。
次のコマンドは、 AWS CLIを使用してレス本スをリクエストする方法を示します。 AWS CLI は SageMaker Studio インスタンスと SageMaker ノートブックインスタンスにプリインストールされています。をインストールするには AWS CLI、この[インストールガイド](https://aws.amazon.com/cli/)に従います。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
パラメータの定義は次のとおりです。
+ `$ENDPOINT NAME` – エンドポイントの名前。
+ `$CONTENT_TYPE`— リクエストの MIME タイプ (モデルコンテナ入力)。
+ `$ACCEPT_TYPE`— レスポンスの MIME タイプ (モデルコンテナ出力)。
+ `$REQUEST_DATA`— リクエストされたペイロード文字列。
+ `$CLI_BINARY_FORMAT`— コマンドラインインターフェイス (CLI) のパラメータの形式。v1 AWS CLI の場合、このパラメータは空白のままにする必要があります。v2 では、このパラメータは `--cli-binary-format raw-in-base64-out` に設定する必要があります。
**注記**
AWS CLI v2 は[、デフォルトで](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam)バイナリパラメータを base64 でエンコードされた文字列として渡します。
# AWS CLI v1 の例
前のセクションの例は v2 AWS CLI 用でした。次のエンドポイントとの間のリクエストとレスポンスの例では、 AWS CLI v1 を使用します。
## CSV 形式のエンドポイントリクエストとレスポンス
次のコード例では、リクエストは 1 つのレコードで構成され、レスポンスはその確率値です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
0.6
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスにはカンマで区切られたレコードの確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、`--body` の `$'content'` 式は、コンテンツ内の `'\n'` を改行として解釈するようにコマンドに指示しています。レスポンス出力は次のとおりです。
```
0.6,0.3
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスには改行で区切られたレコードの確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
0.6
0.3
```
次のコード例では、リクエストは 1 つのレコードで構成され、レスポンスは 3 つのクラスを含む多クラスモデルからの確率値です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
0.1,0.6,0.3
```
次のコード例では、リクエストは 2 つのレコードで構成され、応答には 3 つのクラスを含む多クラスモデルからの確率値が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
0.1,0.6,0.3
0.2,0.5,0.3
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスには予測ラベルと確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-2 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
1,0.6
0,0.3
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスにはラベルヘッダーと確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-3 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
"['cat','dog','fish']","[0.1,0.6,0.3]"
"['cat','dog','fish']","[0.2,0.5,0.3]"
```
## JSON Lines 形式のエンドポイントリクエストとレスポンス
次のコード例では、リクエストは 1 つのレコードで構成され、レスポンスはその確率値です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines \
--content-type application/jsonlines \
--accept application/jsonlines \
--body '{"features":["This is a good product",5]}' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"score":0.6}
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスには予測ラベルと確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-2 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"predicted_label":1,"probability":0.6}
{"predicted_label":0,"probability":0.3}
```
次のコード例では、リクエストは 2 つのレコードで構成され、レスポンスにはラベルヘッダーと確率が含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-3 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"data":{"features":[1,2,3,4]}}\n{"data":{"features":[5,6,7,8]}}' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}
```
## 複合形式におけるエンドポイントのリクエストとレスポンス
次のコード例では、リクエストは CSV 形式で、レスポンスは JSON Lines 形式です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"probability":0.6}
{"probability":0.3}
```
次のコード例では、リクエストは JSON Lines 形式で、レスポンスは CSV 形式です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-in-csv-out \
--content-type application/jsonlines \
--accept text/csv \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
0.6
0.3
```
次のコード例では、リクエストは CSV 形式で、レスポンスは JSON 形式です。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# 画像データの要件
SageMaker Clarify 処理ジョブは、画像の説明をサポートします。このトピックでは、画像データのデータ形式要件について説明します。画像データの処理の詳細については、「[コンピュータービジョンの説明可能性について画像データを分析する](clarify-processing-job-run.md#clarify-processing-job-run-cv)」を参照してください。
画像データセットには 1 つ以上の画像ファイルが含まれます。SageMaker Clarify 処理ジョブへの入力データセットを識別するには、[ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs) という名前の `dataset` または分析設定 `dataset_uri` パラメータのいずれかを画像ファイルの Amazon S3 URI プレフィックスに設定します。
サポートされている画像ファイル形式とファイル拡張子を次の表に示します。
| イメージ形式 | ファイル拡張子 |
| --- | --- |
| JPEG | jpg、jpeg |
| PNG | png |
分析設定の `dataset_type` パラメーターを **application/x-image** に設定します。タイプは特定の画像ファイル形式ではないため、`content_type` を使用して画像ファイルの形式と拡張子を決定します。
SageMaker Clarify 処理ジョブは、各画像ファイルを 3 次元 [NumPy 配列](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) に読み込み、さらに処理します。3 つの次元には、各ピクセルの高さ、幅、RGB 値が含まれます。
## エンドポイントリクエストの形式
SageMaker Clarify 処理ジョブは、画像の RGB raw データを JPEG などの互換性のある画像形式に変換します。この処理は、予測のためにデータをエンドポイントに送信する前に行われます。サポートされている画像形式は以下のとおりです。
| データ形式 | MIME タイプ | ファイル拡張子 |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg、jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | All above |
分析設定パラメータ `content_type` を使用して、リクエストペイロードのデータ形式を指定します。`content_type` が指定されていない場合、データ形式はデフォルトの `image/jpeg` になります。
## エンドポイント応答の形式
SageMaker Clarify 処理ジョブは、推論エンドポイント呼び出しのレスポンスを受信すると、レスポンスペイロードを逆シリアル化し、そこから予測を引き出します。
### 画像分類の問題
レスポンスペイロードのデータ形式は、分析設定パラメータ accept\$1type で指定する必要があります。`accept_type` が指定されていない場合、データ形式はデフォルトの `application/json` になります。サポートされている形式は、表形式データセクションの「**Endpoint response for tabular data**」で説明されている形式と同じです。
単一の画像を受け入れ、各クラスごとに確率値 (スコア) の配列を返す SageMaker AI 組み込み画像分類アルゴリズムの例については、「[イメージ分類アルゴリズムによる推論](image-classification.md#IC-inference)」を参照してください。
次の表に示すように、`content_type` パラメータを `application/jsonlines` に設定すると、レスポンスは JSON オブジェクトになります。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 1 つの画像 | '\$1"prediction":[0.1,0.6,0.3]\$1' |
前の例では、`probability` パラメータを JMESPath 式の "prediction" に設定してスコアを抽出しています。
`content_type` パラメータを `application/json` に設定すると、次の表に示すように、レスポンスは JSON オブジェクトになります。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 1 つの画像 | '[0.1,0.6,0.3]' |
前の例では、`probability` を JMESPath 式の "[\$1]" に設定すると、配列のすべての要素が抽出されます。前の例では、[`0.1, 0.6, 0.3]` が抽出されます。または、`probability` 設定パラメータの設定をスキップすると、配列のすべての要素も抽出されます。これは、ペイロード全体が予測として逆シリアル化されるためです。
### オブジェクト検出の問題
分析設定 `accept_type` のデフォルトは `application/json` で、サポートされている形式はオブジェクトの検出推論の形式のみです。応答の形式の詳細については、「[レスポンスの形式](object-detection-in-formats.md#object-detection-recordio)」を参照してください。
次の表は、配列を出力するエンドポイントからのレスポンスの例です。配列の各要素は、検出されたオブジェクトのクラスインデックス、信頼度スコア、境界ボックスの座標を含む値の配列です。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 1 つの画像 (1 つのオブジェクト) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| 1 つの画像 (2 つのオブジェクト) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
次の表は、配列を参照するキーを含む JSON オブジェクトを出力するエンドポイントからのレスポンスの例です。分析設定 `probability` を "prediction" キーに設定して値を抽出します。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) |
| --- | --- |
| 1 つの画像 (1 つのオブジェクト) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| 1 つの画像 (2 つのオブジェクト) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]\$1' |
## エンドポイントのリクエストとレスポンスの画像データを事前に確認する
モデルを SageMaker AI リアルタイム推論エンドポイントにデプロイし、エンドポイントにリクエストを送信することをお勧めします。リクエストとレスポンスを手動で調べます。両方が「**画像データを求めるエンドポイントリクエスト**」セクションと「**画像データを求めるエンドポイントレスポンス**」セクションの要件を満たしていることを確認してください。
以下の 2 つのコード例は、画像分類とオブジェクト検出の問題の両方について、リクエストを送信してレスポンスを調べる方法を示しています。
### 画像分類の問題
次のコード例は、エンドポイントに PNG ファイルを読み取り、それを分類するように指示します。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-image-classification \
--content-type "image/png" \
--accept "application/json" \
--body fileb://./test.png \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
[0.1,0.6,0.3]
```
### オブジェクト検出の問題
次のコード例は、JPEG ファイルを読み取り、その中のオブジェクトを検出するようにエンドポイントに指示します。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-object-detection \
--content-type "image/jpg" \
--accept "application/json" \
--body fileb://./test.jpg \
/dev/stderr 1>/dev/null
```
前のコード例から、レスポンス出力は次のようになります。
```
{"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475],[4.0, 0.32643985450267792, 0.3677481412887573, 0.034883320331573486, 0.6318609714508057, 0.5967587828636169],[8.0, 0.22552496790885925, 0.6152569651603699, 0.5722782611846924, 0.882301390171051, 0.8985623121261597],[3.0, 0.42260299175977707, 0.019305512309074402, 0.08386176824569702, 0.39093565940856934, 0.9574796557426453]]}
```
# 時系列データ
時系列データとは、3 次元のデータフレームにロードできるデータを指します。フレームでは、すべてのタイムスタンプで、各行がターゲットレコードを表し、各ターゲットレコードには単数または複数の関連列があります。各データフレームセル内の値は、数値、カテゴリ、またはテキストデータ型にすることができます。
## 時系列データセットの前提条件
分析の前に、データクリーニングや特徴量エンジニアリングなど、データ準備に必要な前処理手順を完了しておきます。1 つまたは複数のデータセットを提供できます。複数のデータセットを指定する場合は、以下のいずれかの方法を使用して、SageMaker Clarify 処理ジョブにデータセットを提供します。
+ `dataset` という名前の [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html) または分析設定 `dataset_uri` のいずれかを使用してメインデータセットを指定します。`dataset_uri` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」の「パラメータリスト」を参照してください。
+ 分析析設定ファイルにある `baseline` パラメータを使用します。ベースラインデータセットがある場合は、`static_covariates` で指定する必要があります。分析設定ファイルの詳細と例については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
次の表は、サポートされているデータ形式、ファイル拡張子、MIME タイプの一覧です。
| データ形式 | ファイル拡張子 | MIME タイプ |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
JSON は、あらゆるレベルの複雑さを持つ構造化データを表現するための柔軟な形式です。表に示されるとおり、SageMaker Clarify は `item_records` 形式、`timestamp_records` 形式、`columns` 形式をサポートしています。
## 時系列データセットの設定例
このセクションでは、JSON 形式の時系列データに対して `time_series_data_config` を使用して分析設定を設定する方法を説明します。次のとおり、タイムスタンプ (t)、ターゲット時系列 (x)、2 つの関連する時系列 (r)、2 つの静的共変量 (u) をそれぞれ含む 2 つの項目を持つデータセットがあるとします。
t1 = [0,1,2], t2 = [2,3]
x1 = [5,6,4], x2 = [0,4]
r1 = [0,1,0], r21 = [1,1]
r12 = [0,0,0], r22 = [1,0]
u11 = -1, u21 = 0
u12 = 1, u22 = 2
このデータセットは、`dataset_format` に応じて、`time_series_data_config` を使用してデータセットを 3 つの異なる方法でエンコードできます。以降のセクションでは、それぞれの方法について説明します。
### `dataset_format` が `columns` の場合の時系列データの設定
次の例では、`dataset_format` に `columns` 値を使用しています。次の JSON ファイルは、前のデータセットを表します。
```
{
"ids": [1, 1, 1, 2, 2],
"timestamps": [0, 1, 2, 2, 3], # t
"target_ts": [5, 6, 4, 0, 4], # x
"rts1": [0, 1, 0, 1, 1], # r1
"rts2": [0, 0, 0, 1, 0], # r2
"scv1": [-1, -1, -1, 0, 0], # u1
"scv2": [1, 1, 1, 2, 2], # u2
}
```
項目 ID が `ids` フィールドで繰り返されることに注意が必要です。`time_series_data_config` の適切な実装は、以下に示されるとおりです。
```
"time_series_data_config": {
"item_id": "ids",
"timestamp": "timestamps",
"target_time_series": "target_ts",
"related_time_series": ["rts1", "rts2"],
"static_covariates": ["scv1", "scv2"],
"dataset_format": "columns"
}
```
### `dataset_format` が `item_records` の場合の時系列データの設定
次の例では、`dataset_format` に `item_records` 値を使用しています。次の JSON ファイルは、データセットを表します。
```
[
{
"id": 1,
"scv1": -1,
"scv2": 1,
"timeseries": [
{"timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0},
{"timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0},
{"timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0}
]
},
{
"id": 2,
"scv1": 0,
"scv2": 2,
"timeseries": [
{"timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1},
{"timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0}
]
}
]
```
各項目は、JSON で個別のエントリとして表されます。次のスニペットは、対応する `time_series_data_config` (JMESPath を使用) を示しています。
```
"time_series_data_config": {
"item_id": "[*].id",
"timestamp": "[*].timeseries[].timestamp",
"target_time_series": "[*].timeseries[].target_ts",
"related_time_series": ["[*].timeseries[].rts1", "[*].timeseries[].rts2"],
"static_covariates": ["[*].scv1", "[*].scv2"],
"dataset_format": "item_records"
}
```
### `dataset_format` が `timestamp_record` の場合の時系列データの設定
次の例では、`dataset_format` に `timestamp_record` 値を使用しています。次の JSON ファイルは、前のデータセットを表します。
```
[
{"id": 1, "timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 2, "timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1, "svc1": 0, "svc2": 2},
{"id": 2, "timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0, "svc1": 0, "svc2": 2},
]
```
JSON の各エントリは、単一のタイムスタンプを表し、単一の項目に対応しています。`time_series_data_config` の実装は、以下に示されるとおりです。
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# 時系列データのエンドポイントリクエスト
SageMaker Clarify 処理ジョブは、データを任意の JSON 構造 (MIME タイプ: `application/json`) にシリアル化します。そのためには、分析設定 `content_template` パラメータにテンプレート文字列を指定する必要があります。これは、SageMaker Clarify 処理ジョブがモデルに提供するる JSON クエリを構築するために使用します。 `content_template` には、データセットからの単数または複数のレコードが含まれます。各レコードの JSON 構造を構築するために使用する `record_template` のテンプレート文字列も指定する必要があります。その後、これらのレコードは `content_template` に挿入されます。`content_type` または `dataset_type` の詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
**注記**
`content_template` と `record_template` は文字列パラメータであるため、JSON シリアル化構造の一部である二重引用符 (") は、設定ではエスケープ文字として記載する必要があります。例えば、Python で二重引用符をエスケープする場合は、`content_template` に次のとおりの値を入力できます。
```
'$record'
```
次の表は、シリアル化された JSON リクエストペイロードの例と、その構築に必要となる対応する `content_template` パラメータと `record_template` パラメータにつういて説明しています。
| ユースケース | エンドポイントリクエストペイロード (文字列表現) | content\$1template | record\$1template |
| --- | --- | --- | --- |
| 一度に単一のレコード | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| `$related_time_series` と `$static_covariates` を使用した単一のレコード | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
| 複数のレコード | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00"}]}` | `'{"instances": $records}'` | `'{"start": $start_time, "target": $target_time_series}'` |
| `$related_time_series` と `$static_covariates` を使用した複数のレコード | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}]}` | `'{"instances": $records}'` | `''{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
# 時系列データのエンドポイント応答
SageMaker Clarify 処理ジョブは、ペイロード全体を JSON として逆シリアル化します。次に、分析設定で指定された JMESPath 式を使用して、逆シリアル化されたデータから予測を引き出します。レスポンスペイロードのレコードは、リクエストペイロードのレコードと一致する必要があります。
平均予測値のみを出力するエンドポイントからの応答の例は、次の表のとおりです。[分析設定](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters)の `predictor` フィールドで使用される `forecast` の値は、処理ジョブの予測結果を検出できるように JMESPath 式として指定する必要があります。
| エンドポイントリクエストペイロード | エンドポイントレスポンスペイロード (文字列表現) | 分析設定の予測の JMESPath 式 |
| --- | --- | --- |
| 単一レコードの例 予測を適切に抽出するには、Config が `TimeSeriesModelConfig(forecast="prediction.mean")` である必要があります。 | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| 複数レコード An AWS deepAR エンドポイントレスポンス。 | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# 時系列データのエンドポイントリクエストと応答を事前チェックする
モデルを SageMaker AI リアルタイム推論エンドポイントにデプロイし、エンドポイントにリクエストを送信することをお勧めします。リクエストと応答を手動で調べ、この両方が「[時系列データのエンドポイントリクエスト](clarify-processing-job-data-format-time-series-request-jsonlines.md)」セクションと「[時系列データのエンドポイント応答](clarify-processing-job-data-format-time-series-response-json.md)」セクションの要件に準拠していることを確認します。モデルコンテナがバッチリクエストをサポートしている場合は、単一のレコードリクエストから始めて、その後複数のレコードを試すことができます。
次のコマンドは、 AWS CLIを使用して応答をリクエストする方法を示しています。 AWS CLI は Studio および SageMaker ノートブックインスタンスにプリインストールされています。をインストールするには AWS CLI、 [インストールガイド](https://aws.amazon.com//cli/)に従います。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
パラメータの定義は次のとおりです。
+ \$1ENDPOINT NAME — エンドポイントの名前
+ \$1CONTENT\$1TYPE — リクエストの MIME タイプ (モデルコンテナ入力)
+ \$1ACCEPT\$1TYPE — レスポンスの MIME タイプ (モデルコンテナ出力)
+ \$1REQUEST\$1DATA — リクエストされたペイロード文字列
+ \$1CLI\$1BINARY\$1FORMAT — コマンドラインインターフェイス (CLI) のパラメータの形式 v1 AWS CLI の場合、このパラメータは空白のままにする必要があります。v2 では、このパラメータは `--cli-binary-format raw-in-base64-out` に設定する必要があります。
**注記**
AWS CLI v2 は、デフォルトでバイナリパラメータを base64 でエンコードされた文字列として渡します。エンドポイントとの間で送受信される次のリクエストとレスポンスの例は、v1 AWS CLI を使用しています。
------
#### [ Example 1 ]
次のサンプルコードでは、リクエストが単一のレコードで構成されています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json \
--content-type application/json \
--accept application/json \
--body '{"target": [1, 2, 3, 4, 5],
"start": "2024-01-01 01:00:00"}' \
/dev/stderr 1>/dev/null
```
次のスニペットは、対応する応答出力を示しています。
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
次のサンプルコードでは、リクエストに 2 つのレコードが含まれています。
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json-2 \
--content-type application/json \
--accept application/json \
--body $'{"instances": [{"target":[1, 2, 3],
"start":"2024-01-01 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}], {"target":[1, 2, 3],
"start":"2024-01-02 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}]}' \
dev/stderr 1>/dev/null
```
応答出力は、次のとおりです。
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------
# バイアス分析と説明可能性のための 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\$1template `'{"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 式が \$1'predictions[\$1].mean[:2]'\$1\$1 の場合、予測値は次のとおり解析されます。
```
[[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 にすることをお勧めします。
# 分析結果
SageMaker Clarify 処理ジョブが終了したら、出力ファイルをダウンロードして検査したり、SageMaker Studio で結果を可視化したりできます。次のトピックでは、バイアス分析、SHAP 分析、コンピュータビジョンの説明可能性分析、Partial Dependence Plot (PDP) 分析が生成するスキーマやレポートなど、SageMaker Clarify が生成する分析結果について説明します。設定分析に複数の分析を計算するパラメータが含まれている場合、その結果は 1 つの分析と 1 つのレポートファイルに集約されます。
SageMaker Clarify 処理ジョブの出力ディレクトリには次のファイルが含まれています。
+ `analysis.json` — JSON 形式のバイアスメトリクスと特徴量重要度を含むファイル。
+ `report.ipynb` — バイアスメトリクスと特徴量需要度を視覚化するのに役立つコードを含む静的ノートブック。
+ `explanations_shap/out.csv` — 作成され、特定の分析設定に基づいて自動的に生成されたファイルを格納するディレクトリ。例えば、`save_local_shap_values` パラメータを有効にすると、インスタンスごとのローカル SHAP 値が `explanations_shap` ディレクトリに保存されます。別の例として、`analysis configuration` に SHAP ベースラインパラメータの値が含まれていない場合、SageMaker Clarify の説明可能性ジョブは入力データセットをクラスタリングしてベースラインを計算します。次に、生成されたベースラインをディレクトリに保存します。
詳細については、以下のセクションを参照してください。
**Topics**
+ [バイアス分析](#clarify-processing-job-analysis-results-bias)
+ [SHAP 分析](#clarify-processing-job-analysis-results-shap)
+ [コンピュータービジョン (CV) の説明可能性分析](#clarify-processing-job-analysis-results-cv)
+ [部分依存プロット (PDP) 分析](#clarify-processing-job-analysis-results-pdp)
+ [非対称 Shapley 値](#clarify-processing-job-analysis-results-asymmshap)
## バイアス分析
Amazon SageMaker Clarify では、バイアスと公平性について説明するために、「[バイアスと公平性に関する Amazon SageMaker Clarify の用語解説](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) 」に記載されている用語を使用します。
### 分析ファイルのスキーマ
分析ファイルは JSON 形式で、トレーニング前のバイアスメトリクスとトレーニング後のバイアスメトリクスの 2 つのセクションに分かれています。トレーニング前とトレーニング後のバイアスメトリクスのパラメータは次のとおりです。
+ **pre\$1training\$1bias\$1metrics** — トレーニング前のバイアスメトリクスのパラメータ。詳細については、「[トレーニング前のバイアスメトリクス](clarify-measure-data-bias.md)」と「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
+ **label** — 分析設定の `label` パラメータによって定義されるグラウンドトゥルースラベル名。
+ **label\$1value\$1or\$1threshold** — 分析設定の `label_values_or_threshold` パラメータによって定義されるラベル値または間隔を含む文字列。例えば、二項分類問題に値 `1` を指定した場合、文字列は `1` になります。多クラス問題で複数の値 `[1,2]` を指定した場合、文字列は `1,2` になります。リグレッション問題にしきい値 `40` を指定すると、文字列は `(40, 68]` のような内部文字列になります。ここで、`68` は入力データセット内のラベルの最大値です。
+ **facets** — このセクションには複数のキーと値のペアが含まれており、キーはファセット設定の `name_or_index` パラメータで定義されたファセット名に対応し、値はファセットオブジェクトの配列です。 オブジェクトには次のメンバーがあります。
+ **value\$1or\$1threshold** — ファセット設定の `value_or_threshold` パラメータによって定義されるファセット値または間隔を含む文字列。
+ **metrics** — セクションにはバイアスメトリクス要素の配列が含まれ、各バイアスメトリクス要素には次の属性があります。
+ **name** — バイアスメトリクスのショートネーム。例えば、`CI`。
+ **description** — バイアスメトリクスのフルネーム。例えば、`Class Imbalance (CI)`。
+ **value** — バイアスメトリクス値。特定の理由でバイアスメトリクスが計算されなかった場合は JSON null 値。±∞ の値は、それぞれ文字列 `∞` と `-∞` として表されます。
+ **error** — バイアスメトリクスが計算されなかった理由を説明するオプションのエラーメッセージ。
+ **post\$1training\$1bias\$1metrics** — このセクションにはトレーニング後のバイアスメトリクスが含まれ、トレーニング前のセクションと同様のレイアウトと構造になっています。詳細については、「[トレーニング済みデータのメトリクスとモデルのバイアスのメトリクス](clarify-measure-post-training-bias.md)」を参照してください。
以下は、トレーニング前とトレーニング後のバイアスメトリクスの両方を計算する分析設定の例です。
```
{
"version": "1.0",
"pre_training_bias_metrics": {
"label": "Target",
"label_value_or_threshold": "1",
"facets": {
"Gender": [{
"value_or_threshold": "0",
"metrics": [
{
"name": "CDDL",
"description": "Conditional Demographic Disparity in Labels (CDDL)",
"value": -0.06
},
{
"name": "CI",
"description": "Class Imbalance (CI)",
"value": 0.6
},
...
]
}]
}
},
"post_training_bias_metrics": {
"label": "Target",
"label_value_or_threshold": "1",
"facets": {
"Gender": [{
"value_or_threshold": "0",
"metrics": [
{
"name": "AD",
"description": "Accuracy Difference (AD)",
"value": -0.13
},
{
"name": "CDDPL",
"description": "Conditional Demographic Disparity in Predicted Labels (CDDPL)",
"value": 0.04
},
...
]
}]
}
}
}
```
### バイアス分析レポート
バイアス分析レポートには、詳細な説明と説明を含む複数の表と図が含まれています。これには、ラベル値の分布、ファセット値の分布、モデルのパフォーマンス概要図、バイアスメトリクスの表と、それらの説明などが含まれます。バイアスメトリクスとその解釈方法の詳細については、「[Learn how Amazon SageMaker Clarify helps detect bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)」を参照してください。
## SHAP 分析
SageMaker Clarify 処理ジョブは、カーネル SHAP アルゴリズムを使用して特徴量属性を計算します。SageMaker Clarify 処理ジョブは、ローカルとグローバルの両方の SHAP 値を生成します。これらは、モデル予測に対する各特徴量の寄与度を判断するのに役立ちます。ローカル SHAP 値は個々のインスタンスの特徴量重要度を表し、グローバル SHAP 値はデータセット内のすべてのインスタンスのローカル SHAP 値を集計します。SHAP 値とその解釈方法の詳細については、「[Shapley 値を使用する特徴属性](clarify-shapley-values.md)」を参照してください。
### SHAP 分析ファイルのスキーマ
グローバル SHAP 分析の結果は、`kernel_shap` メソッドの下の分析ファイルの説明セクションに保存されます。SHAP 分析ファイルには次のようなさまざまなパラメータがあります。
+ **explanations** — 特徴量重要度の分析結果を含む分析ファイルのセクション。
+ **kernal\$1shap** — グローバル SHAP 分析結果を含む分析ファイルのセクション。
+ **global\$1shap\$1values** — 複数のキーと値のペアを含む分析ファイルのセクション。キーと値のペアの各キーは、入力データセットの特徴量名を表します。キーと値のペアの各値は、特徴量のグローバル SHAP 値に対応します。グローバル SHAP 値は、`agg_method` 設定を使用して特徴量のインスタンスごとの SHAP 値を集計することによって取得されます。`use_logit` 設定がアクティブ化されている場合、値はロジスティック回帰係数を使用して計算され、対数オッズ比として解釈できます。
+ **expected\$1value** — ベースラインデータセットの平均予測値。`use_logit` 設定がアクティブ化されている場合、値はロジスティック回帰係数を使用して計算されます。
+ **global\$1top\$1shap\$1text** – NLP の説明可能性分析で使用します。キーと値のペアのセットが含まれている分析ファイルのセクション。SageMaker Clarify 処理ジョブは、各トークンの SHAP 値を集計し、グローバル SHAP 値に基づいて上位のトークンを選択します。`max_top_tokens` 設定では、選択するトークンの数を定義します。
選択した上位トークンにはそれぞれキーと値のペアがあります。キーと値のペアのキーは、上位トークンのテキスト特徴量名に対応しています。キーと値のペアの各値は、上位トークンのグローバル SHAP 値です。`global_top_shap_text` キー値のペアの例については、以下の出力を参照してください。
以下は、表形式データセットの SHAP 分析からの出力例です。
```
{
"version": "1.0",
"explanations": {
"kernel_shap": {
"Target": {
"global_shap_values": {
"Age": 0.022486410860333206,
"Gender": 0.007381025261958729,
"Income": 0.006843906804137847,
"Occupation": 0.006843906804137847,
...
},
"expected_value": 0.508233428001
}
}
}
}
```
以下は、テキストデータセットの SHAP 分析からの出力例です。`Comments` 列に対応する出力は、テキスト特徴量の分析後に生成される出力の例です。
```
{
"version": "1.0",
"explanations": {
"kernel_shap": {
"Target": {
"global_shap_values": {
"Rating": 0.022486410860333206,
"Comments": 0.058612104851485144,
...
},
"expected_value": 0.46700941970297033,
"global_top_shap_text": {
"charming": 0.04127962903247833,
"brilliant": 0.02450240786522321,
"enjoyable": 0.024093569652715457,
...
}
}
}
}
}
```
### 生成されたベースラインファイルのスキーマ。
SHAP ベースライン設定が提供されていない場合、SageMaker Clarify 処理ジョブはベースラインデータセットを生成します。SageMaker Clarify は、距離ベースのクラスタリングアルゴリズムを使用して、入力データセットから作成されたクラスターからベースラインデータセットを生成します。結果のベースラインデータセットは、`explanations_shap/baseline.csv` にある CSV ファイルに保存されます。この出力ファイルには、ヘッダー行と、分析設定で指定された `num_clusters` パラメータに基づく複数のインスタンスが含まれます。ベースラインデータセットは特徴量列のみで構成されます。以下は、入力データセットをクラスタリングして作成されたベースラインの例です。
```
Age,Gender,Income,Occupation
35,0,2883,1
40,1,6178,2
42,0,4621,0
```
### 表形式データセットの説明可能性分析によるローカル SHAP 値のスキーマ
表形式のデータセットでは、単一のコンピューティングインスタンスが使用されている場合、SageMaker Clarify 処理ジョブはローカル SHAP 値を `explanations_shap/out.csv` という名前の CSV ファイルに保存します。複数のコンピューティングインスタンスを使用する場合、ローカル SHAP 値は `explanations_shap` ディレクトリ内の複数の CSV ファイルに保存されます。
ローカル SHAP 値を含む出力ファイルには、ヘッダーで定義されている各列のローカル SHAP 値を含む行があります。ヘッダーは、ヘッダーは、`Feature_Label` の命名規則に従って特徴量名にアンダースコアが追加され、その後にターゲット変数の名前が続きます。
多クラスの問題では、最初にヘッダーの特徴量名が変わり、次にラベルが変わります。例えば、ヘッダー内の 2 つの特徴量 `F1, F2` と 2 つのクラス `L1` と `L2` は 、`F1_L1`、`F2_L1`、`F1_L2`、`F2_L2` となります。分析設定に `joinsource_name_or_index` パラメータの値が含まれている場合、結合で使用されたキー列がヘッダー名の末尾に追加されます。これにより、ローカル SHAP 値を入力データセットのインスタンスにマッピングできるようになります。SHAP 値を含む出力ファイルの例を以下に示します。
```
Age_Target,Gender_Target,Income_Target,Occupation_Target
0.003937908,0.001388849,0.00242389,0.00274234
-0.0052784,0.017144491,0.004480645,-0.017144491
...
```
### NLP の説明可能性分析によるローカル SHAP 値のスキーマ
NLP の説明可能性分析では、単一のコンピューティングインスタンスが使用されている場合、SageMaker Clarify 処理ジョブはローカル SHAP 値を `explanations_shap/out.jsonl` という名前の JSON Lines ファイルに保存します。複数のコンピューティングインスタンスを使用する場合、ローカル SHAP 値は `explanations_shap` ディレクトリ内の複数の JSON Lines ファイルに保存されます。
ローカル SHAP 値を含む各ファイルには複数のデータ行があり、各行は有効な JSON オブジェクトです。JSON オブジェクトには以下の属性があります。
+ **explanations** — 1 つのインスタンスに関するカーネル SHAP の説明の配列を含む分析ファイルのセクション。配列の各要素には次のメンバーがあります。
+ **feature\$1name** — headers 設定によって提供される特徴量のヘッダー名。
+ **data\$1type** — SageMaker Clarify 処理ジョブによって推測される特徴量タイプ。テキスト特徴量の有効な値には`numerical`、`categorical`、`free_text` (テキスト特徴量の場合) があります。
+ **attributions** — 特徴量固有の属性オブジェクトの配列。テキスト特徴量には、`granularity` 設定で定義された単位ごとに複数の属性オブジェクトを含めることができます。属性オブジェクトには以下のメンバーがあります。
+ **attribution** — クラス固有の確率値の配列。
+ **description** — (テキスト特徴量の場合) テキスト単位の説明。
+ **partial\$1text** — SageMaker Clarify 処理ジョブによって説明されるテキストの部分。
+ **start\$1idx** — 部分テキストフラグメントの先頭を示す配列位置を識別する 0 から始まるインデックスです。
以下は、ローカル SHAP 値ファイルの 1 行の例で、読みやすくするために整理されています。
```
{
"explanations": [
{
"feature_name": "Rating",
"data_type": "categorical",
"attributions": [
{
"attribution": [0.00342270632248735]
}
]
},
{
"feature_name": "Comments",
"data_type": "free_text",
"attributions": [
{
"attribution": [0.005260534499999983],
"description": {
"partial_text": "It's",
"start_idx": 0
}
},
{
"attribution": [0.00424190349999996],
"description": {
"partial_text": "a",
"start_idx": 5
}
},
{
"attribution": [0.010247314500000014],
"description": {
"partial_text": "good",
"start_idx": 6
}
},
{
"attribution": [0.006148907500000005],
"description": {
"partial_text": "product",
"start_idx": 10
}
}
]
}
]
}
```
### SHAP 分析レポート
SHAP 分析レポートには、最大 `10` 個の上位グローバル SHAP 値の棒グラフが表示されます。次のグラフの例は、上位 `4` つの特徴量の SHAP 値を示しています。
![\[上位 4 つの特徴量のターゲット変数について計算されたグローバル SHAP 値の横棒グラフ。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify/shap-chart.png)
## コンピュータービジョン (CV) の説明可能性分析
SageMaker Clarify コンピュータビジョンの説明可能性は、画像で構成されるデータセットを取得し、各画像をスーパーピクセルの集合として扱います。分析後、SageMaker Clarify 処理ジョブは画像のデータセットを出力します。各画像にはスーパーピクセルのヒートマップが表示されます。
次の例は、左側に入力された速度制限標識、右側に SHAP 値の大きさを示すヒートマップを示しています。これらの SHAP 値は、[ドイツの交通標識](https://benchmark.ini.rub.de/gtsrb_news.html)を認識するようにトレーニングされた画像認識 Resnet-18 モデルによって計算されました。ドイツの交通標識認識ベンチマーク（GTSRB）データセットは、論文「[Man vs. computer: Benchmarking machine learning algorithms for traffic sign recognition](https://www.sciencedirect.com/science/article/abs/pii/S0893608012000457?via%3Dihub)」に掲載されています。出力例で、正の値が大きいということはスーパーピクセルがモデル予測と強い正の相関関係にあることを示しています。負の値が大きいということはスーパーピクセルがモデル予測と強い負の相関関係にあることを示します。ヒートマップに表示される SHAP 値の絶対値が大きいほど、スーパーピクセルとモデル予測の関係が強くなります。
![\[速度制限標識の入力イメージと Resnet-18 モデルの SHAP 値のヒートマップの結果。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify/shap_speed-limit-70.png)
詳細については、サンプルノートブックの「[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)」と「[Explaining object detection models with Amazon SageMaker Clarify](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb)」を参照してください。
## 部分依存プロット (PDP) 分析
部分依存プロットは、対象の一連の入力特徴量に対する予測ターゲットレスポンスの依存性を示します。これらは、他のすべての入力特徴量の値よりも周辺化され、補完特徴量と呼ばれます。直感的に、部分依存をターゲットレスポンスとして解釈できます。これは、対象の各入力特徴量の関数として期待されます。
### 分析ファイルのスキーマ
PDP 値は、`pdp` メソッドに基づいて分析ファイルの `explanations` セクションに保存されます。`explanations` 用のパラメータは次のとおりです。
+ **explanations** — 特徴量重要度の分析結果を含む分析ファイルのセクション。
+ **pdp** — 1 つのインスタンスに関する PDP の説明の配列を含む分析ファイルのセクション。配列の各要素には次のメンバーがあります。
+ **feature\$1name** — `headers` 設定によって提供される特徴量のヘッダー名。
+ **data\$1type** — SageMaker Clarify 処理ジョブによって推測される特徴量タイプ。`data_type` の有効な値には、数値とカテゴリが含まれます。
+ **feature\$1values** — 特徴量に存在する値が含まれます。SageMaker Clarify によって推論される `data_type` がカテゴリの場合、`feature_values` には、その特徴量が取り得るすべての一意の値が含まれます。SageMaker Clarify によって推論される `data_type` が数値の場合、`feature_values` には生成されたバケットの中心値のリストが含まれます。`grid_resolution` パラメータは、特徴量列の値をグループ化するために使用されるバケットの数を決定します。
+ **data\$1distribution** — 割合の配列。各値はバケットに含まれるインスタンスの割合です。`grid_resolution` パラメータは、バケットの数を決定します。特徴量列の値はこれらのバケットにグループ化されます。
+ **model\$1predictions** — モデル予測の配列。配列の各要素は、モデルの出力内の 1 つのクラスに対応する予測の配列です。
**label\$1headers** — `label_headers` 設定によって提供されるラベルヘッダー。
+ **error** — 特定の理由で PDP 値が計算されなかった場合に生成されるエラーメッセージ。このエラー メッセージは `feature_values`、`data_distributions`、`model_predictions` フィールドに含まれるコンテンツを置き換えます。
以下は、PDP 分析結果を含む分析ファイルからの出力例です。
```
{
"version": "1.0",
"explanations": {
"pdp": [
{
"feature_name": "Income",
"data_type": "numerical",
"feature_values": [1046.9, 2454.7, 3862.5, 5270.2, 6678.0, 8085.9, 9493.6, 10901.5, 12309.3, 13717.1],
"data_distribution": [0.32, 0.27, 0.17, 0.1, 0.045, 0.05, 0.01, 0.015, 0.01, 0.01],
"model_predictions": [[0.69, 0.82, 0.82, 0.77, 0.77, 0.46, 0.46, 0.45, 0.41, 0.41]],
"label_headers": ["Target"]
},
...
]
}
}
```
### PDP 分析レポート
各特徴量の PDP チャートを含む分析レポートを生成できます。PDP チャートは X 軸に沿って `feature_values` をプロットし、Y 軸に沿って `model_predictions` をプロットします。多クラスモデルの場合、`model_predictions` は配列であり、この配列の各要素はモデル予測クラスのいずれかに対応します。
以下は、特徴量 `Age` の PDP チャートの例です。出力例では、PDP はバケットにグループ化された特徴量値の数を示しています。バケット数は `grid_resolution` によって決まります。特徴量値のバケットはモデル予測と照合してプロットされます。この例では、特徴量値が高いほどモデル予測値は同じになります。
![\[10 個の一意のグリッド ポイントの feature_values に対してモデル予測がどのように変化するかを示す折れ線グラフ。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify/pdp-chart.png)
## 非対称 Shapley 値
SageMaker Clarify 処理ジョブは、非対称 Shapley 値アルゴリズムを使用して、時系列予測モデルの説明の貢献度を計算します。このアルゴリズムは、得られた予測に対する各時間ステップの入力特徴量の貢献度を決定します。
### 非対称 Shapley 値分析ファイルのスキーマ
非対称 Shapley 値の結果は Amazon S3 バケットに保存されます。このバケットの場所は、分析ファイルの*説明*セクションで指定されています。このセクションでは、特徴量の重要度分析結果について説明します。非対称 Shapley 値分析ファイルには、以下のパラメータが含まれています。
+ **asymmetric\$1shapley\$1value** — 説明ジョブの結果に関するメタデータを含む分析ファイルのセクション。コンテンツは以下のとおりです。
+ **explanation\$1results\$1path** — 説明結果を含む Amazon S3 の場所
+ **direction** — `direction` の設定値に対するユーザー指定の設定
+ **granularity** — `granularity` の設定値に対するユーザー指定の設定
次のスニペットは、上記のパラメータをサンプル分析ファイルで使用しています。
```
{
"version": "1.0",
"explanations": {
"asymmetric_shapley_value": {
"explanation_results_path": EXPLANATION_RESULTS_S3_URI,
"direction": "chronological",
"granularity": "timewise",
}
}
}
```
以下のセクションでは、説明結果の構造が設定の `granularity` の値によってどのように影響されるかについて説明します。
#### 時間単位の粒度
粒度が `timewise` の場合、出力は次の構造で表されます。`scores` 値は、各タイムスタンプの貢献度を表します。`offset` 値は、ベースラインデータ上のモデルの予測を表し、モデルがデータを受信していない場合のモデルの動作を記述します。
次のスニペットは、2 つの時間ステップの予測を行うモデルの出力例を説明しています。このため、すべての貢献度は、2 つの要素のリストであり、最初のエントリは最初の予測時間ステップを参照します。
```
{
"item_id": "item1",
"offset": [1.0, 1.2],
"explanations": [
{"timestamp": "2019-09-11 00:00:00", "scores": [0.11, 0.1]},
{"timestamp": "2019-09-12 00:00:00", "scores": [0.34, 0.2]},
{"timestamp": "2019-09-13 00:00:00", "scores": [0.45, 0.3]},
]
}
{
"item_id": "item2",
"offset": [1.0, 1.2],
"explanations": [
{"timestamp": "2019-09-11 00:00:00", "scores": [0.51, 0.35]},
{"timestamp": "2019-09-12 00:00:00", "scores": [0.14, 0.22]},
{"timestamp": "2019-09-13 00:00:00", "scores": [0.46, 0.31]},
]
}
```
#### きめ細かな粒度
次の例は、粒度が `fine_grained` の場合の貢献度の結果を説明しています。`offset` 値は、前のセクションでの説明と同じ意味を持ちます。貢献度は、ターゲット時系列と関連する時系列 (ある場合) のタイムスタンプごとに各入力特徴量について計算され、利用可能な場合は静的共変量ごとに計算されます。
```
{
"item_id": "item1",
"offset": [1.0, 1.2],
"explanations": [
{"feature_name": "tts_feature_name_1", "timestamp": "2019-09-11 00:00:00", "scores": [0.11, 0.11]},
{"feature_name": "tts_feature_name_1", "timestamp": "2019-09-12 00:00:00", "scores": [0.34, 0.43]},
{"feature_name": "tts_feature_name_2", "timestamp": "2019-09-11 00:00:00", "scores": [0.15, 0.51]},
{"feature_name": "tts_feature_name_2", "timestamp": "2019-09-12 00:00:00", "scores": [0.81, 0.18]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-11 00:00:00", "scores": [0.01, 0.10]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-12 00:00:00", "scores": [0.14, 0.41]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-13 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "rts_feature_name_1", "timestamp": "2019-09-14 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-11 00:00:00", "scores": [0.65, 0.56]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-12 00:00:00", "scores": [0.43, 0.34]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-13 00:00:00", "scores": [0.16, 0.61]},
{"feature_name": "rts_feature_name_2", "timestamp": "2019-09-14 00:00:00", "scores": [0.95, 0.59]},
{"feature_name": "static_covariate_1", "scores": [0.6, 0.1]},
{"feature_name": "static_covariate_2", "scores": [0.1, 0.3]},
]
}
```
`timewise` のユースケースと `fine-grained` のユースケースの両方で、結果は JSON 行 (.jsonl) 形式で保存されます。
# SageMaker Clarify 処理ジョブのトラブルシューティング
SageMaker Clarify 処理ジョブでエラーが発生した場合は、次のシナリオを参照して問題を特定してください。
**注記**
エラーの理由と終了メッセージは、実行中に発生した場合に、説明メッセージと例外を含めることを目的としています。エラーの原因としてよくあるのは、パラメータが欠落しているか、有効でないことです。不明確、紛らわしい、または誤解を招くようなメッセージが表示された場合や、解決策が見つからない場合は、フィードバックを送信してください。
**Topics**
+ [処理ジョブを終了できない](#clarify-troubleshooting-job-fails)
+ [処理ジョブの実行に時間がかかりすぎる](#clarify-troubleshooting-job-long)
+ [処理ジョブが結果なしで終了し、CloudWatch 警告メッセージが表示される](#clarify-troubleshooting-no-results-and-warning)
+ [無効な分析設定に関するエラーメッセージ](#clarify-troubleshooting-invalid-analysis-configuration)
+ [バイアスメトリクスのコンピュテーションが、一部またはすべてのメトリクスで失敗する](#clarify-troubleshooting-bias-metric-computation-fails)
+ [分析設定とデータセット/モデルの入出力が一致しない](#clarify-troubleshooting-mismatch-analysis-config-and-data-model)
+ [モデルが 500 内部サーバーエラーを返すか、コンテナがモデルエラーによりレコードごとの予測にフォールバックする](#clarify-troubleshooting-500-internal-server-error)
+ [実行ロールが無効](#clarify-troubleshooting-execution-role-invalid)
+ [データのダウンロードに失敗しました](#clarify-troubleshooting-data-download)
+ [SageMaker AI に接続できない](#clarify-troubleshooting-connection)
## 処理ジョブを終了できない
処理ジョブを終了できない場合は、以下を試してください。
+ ジョブを実行したノートブックでジョブログを直接調べます。ジョブログは、実行を開始したノートブックセルの出力にあります。
+ CloudWatch でジョブログを調べます。
+ 次の行をノートブックに追加して、最後の処理ジョブを記述し、エラーの理由と終了メッセージを探します。
+ `clarify_processor.jobs[-1].describe()`
+ 次の AWS CLIコマンドを実行して処理ジョブを記述し、失敗の理由と終了メッセージを探します。
+ `aws sagemaker describe-processing-job —processing-job-name `
## 処理ジョブの実行に時間がかかりすぎる
処理ジョブの実行に時間がかかりすぎる場合は、以下の方法で根本原因を突き止めます。
リソース設定がコンピューティング負荷を処理するのに十分であるかどうかを確認します。ジョブをスピードアップするには、次のことを試してください。
+ より大きなインスタンスタイプを使用します。SageMaker Clarify はモデルのクエリを繰り返し行うため、インスタンスが大きいほど計算時間を大幅に短縮できます。利用可能なインスタンス、そのメモリサイズ、帯域幅その他のパフォーマンスの詳細については、「[Amazon SageMaker AI の料金](https://aws.amazon.com/sagemaker/pricing/)」を参照してください。
+ バックアップインスタンスをさらに追加します。SageMaker Clarify では、複数のインスタンスを使用して複数の入力データポイントを並行して説明できます。並列コンピューティングを有効にするには、`SageMakerClarifyProcessor` を呼び出すときに、`instance_count` を `1` より大きく設定します。詳細については、「[SageMaker Clarify 処理ジョブを並列実行する方法](clarify-processing-job-run.md#clarify-processing-job-run-spark)」を参照してください。インスタンス数を増やす場合は、エンドポイントのパフォーマンスをモニタリングして、増加した負荷をデプロイできるかどうかを確認します。詳細については、「[リアルタイムエンドポイントからデータをキャプチャする](model-monitor-data-capture-endpoint.md)」を参照してください。
+ SHapley Additive exPlanations (SHAP) 値を計算する場合は、分析設定ファイルの `num_samples` パラメータを減らします。サンプル数は以下に直接影響します。
+ エンドポイントに送信される合成データセットのサイズ
+ ジョブランタイム
サンプル数を減らすと、SHAP 値の推定精度も低下する可能性があります。詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
## 処理ジョブが結果なしで終了し、CloudWatch 警告メッセージが表示される
処理ジョブが終了しても結果が見つからず、CloudWatch ログに「シグナル 15 を受信しました。クリーンアップしています」という警告メッセージが生成されました。この警告は、顧客リクエストが `StopProcessingJob` API を呼び出したかジョブが完了するまでに割り当てられた時間を過ぎたために、ジョブが停止したことを示しています。後者の場合、ジョブ設定の最大ランタイム (`max_runtime_in_seconds`) を確認し、必要に応じて増やしてください。
## 無効な分析設定に関するエラーメッセージ
+ 「分析設定を JSON としてロードできません」というエラーメッセージが表示される場合は、処理ジョブの分析設定入力ファイルに有効な JSON オブジェクトが含まれていないことを意味します。JSON リンターを使用して、JSON オブジェクトの有効性をチェックしてください。
+ 「分析設定スキーマの検証エラー」というエラーメッセージが表示される場合は、処理ジョブの分析設定入力ファイルに、不明なフィールドが含まれているか一部のフィールド値に無効なタイプが含まれていることを意味します。ファイル内の設定パラメータを確認し、分析設定ファイルに記載されているパラメータと照合してください。詳細については、「[分析設定ファイル](clarify-processing-job-configure-analysis.md)」を参照してください。
## バイアスメトリクスのコンピュテーションが、一部またはすべてのメトリクスで失敗する
「予測ラベル列にラベル値が存在しません。正の予測インデックスシリーズに含まれている値がすべて False です」または「予測ラベル列シリーズのデータ型がラベル列シリーズと同じではありません」のいずれかのエラーメッセージが表示された場合は、次のことを試してください。
+ 正しいデータセットが使用されているかチェックします。
+ データセットのサイズが小さすぎないか、例えば、数行しか含まれていないか、などをチェックします。これにより、モデルの出力が同じ値になったり、データ型が正しく推測されなかったりする可能性があります。
+ ラベルまたはファセットが、連続またはカテゴリとして扱われているかチェックします。SageMaker Clarify は、ヒューリスティックを使って [https://github.com/aws/amazon-sagemaker-clarify/blob/master/src/smclarify/bias/metrics/common.py#L114)](https://github.com/aws/amazon-sagemaker-clarify/blob/master/src/smclarify/bias/metrics/common.py#L114)) を決定します。トレーニング後のバイアスメトリクスの場合、モデルによって返されるデータ型がデータセット内のものと一致しないか、SageMaker Clarify がデータを正しく変換できない可能性があります。
+ バイアスレポートでは、カテゴリ列の場合は 1 つの値、連続列の場合は間隔が表示されます。
+ 例えば、列の値が 0.0 と 1.0 の浮動小数点である場合、一意の値が少なすぎる場合にも連続として扱われます。
## 分析設定とデータセット/モデルの入出力が一致しない
+ 分析設定のベースライン形式がデータセット形式と同じかチェックします。
+ 「文字列を浮動小数点に変換できませんでした」というエラーメッセージが表示される場合は、形式が正しく指定されているかチェックします。また、モデル予測がラベル列と異なる形式であることや、ラベルや確率の設定が正しくないことを示す可能性もあります。
+ 「ファセットが見つかりません」、「ヘッダーにはラベルが含まれている必要があります」、「設定内のヘッダーがデータセット内の列の数と一致しません」、「特徴量名が見つかりません」のいずれかのエラーメッセージが表示された場合は、ヘッダーが列と一致しているかどうか確認してください。
+ 「データには特徴量が含まれている必要があります」というエラーメッセージが表示される場合は、JSON Lines のコンテンツテンプレートをチェックし、データセットのサンプルがある場合はそれと比較します。
## モデルが 500 内部サーバーエラーを返すか、コンテナがモデルエラーによりレコードごとの予測にフォールバックする
「モデルエラーのためにレコードごとの予測にフォールバックします」というエラーメッセージが表示される場合は、モデルがバッチサイズを処理できないか、スロットルされているか、シリアル化の問題のためにコンテナから渡された入力を受け入れないことを示す可能性があります。SageMaker AI エンドポイントの CloudWatch ログを確認し、エラーメッセージまたはトレースバックを探す必要があります。モデルスロットリングの場合は、別のインスタンスタイプを使用するか、エンドポイントのインスタンス数を増やすと役立つ場合があります。
## 実行ロールが無効
これは、提供されたロールが正しくないか、必要なアクセス許可がないことを示します。処理ジョブの設定に使用されたロールとそのアクセス許可をチェックし、ロールの許可と信頼ポリシーを確認してください。
## データのダウンロードに失敗しました
これは、ジョブを開始するためのジョブ入力をダウンロードできなかったことを示します。バケット名と、データセットおよび設定入力の許可を確認してください。
## SageMaker AI に接続できない
これは、ジョブが SageMaker AI サービスエンドポイントに到達できなかったことを示します。処理ジョブのネットワーク設定をチェックし、仮想プライベートクラウド (VPC) 設定を確認してください。
## サンプルノートブック
次のセクションでは、SageMaker Clarify の使用を開始する際や、分散ジョブ内のタスクなどの特殊なタスクやコンピュータビジョンの使用に役立つノートブックが含まれています。
### 開始方法
次のサンプルノートブックは、SageMaker Clarify を使用して説明可能性タスクとモデルバイアスタスクを開始する方法を説明しています。これらのタスクには、処理ジョブの作成、機械学習 (ML) モデルトレーニング、モデル予測のモニタリングなどがあります。
+ [Explainability and bias detection with Amazon SageMaker Clarify](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) - SageMaker Clarify を使用して、バイアスの検出やモデル予測の説明を行う処理ジョブを作成します。
+ [バイアスドリフトと特徴属性ドリフトのモニタリング (Amazon SageMaker Clarify)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.html) — Amazon SageMaker Model Monitor を使用して、バイアスドリフトと特徴属性ドリフトを経時的にモニタリングします。
+ [JSON 行形式のデータセットを SageMaker Clarify 処理ジョブに読み込む](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_jsonlines_format.html)方法
+ [Mitigate Bias, train another unbiased model, and put it in the model registry](https://github.com/aws/amazon-sagemaker-examples/blob/master/end_to_end/fraud_detection/3-mitigate-bias-train-model2-registry-e2e.ipynb) – [Synthetic Minority Over-sampling Technique (SMOTE)](https://arxiv.org/pdf/1106.1813.pdf) と SageMaker Clarify を使用してバイアスを軽減し、別のモデルをトレーニングしてから、新しいモデルをモデルレジストリに登録します。このサンプルノートブックでは、データ、コード、モデルメタデータなどの新しいモデルアーティファクトをモデルレジストリに配置する方法も説明されています。このノートブックは、「[AWSで機械学習ライフサイクル全体を設計して構築する: エンドツーエンドの Amazon SageMaker のデモ](https://aws.amazon.com/blogs/machine-learning/architect-and-build-the-full-machine-learning-lifecycle-with-amazon-sagemaker/)」ブログ記事で説明されているとおり、SageMaker Clarifyを SageMaker AI パイプラインに統合する方法を説明するシリーズの一部です。
### 特殊なケース
以下のノートブックでは、独自のコンテナ内や自然言語処理タスクなどの特殊なケースで SageMaker Clarify を使用する方法について説明します。
+ [Fairness and Explainability with SageMaker Clarify (Bring Your Own Container)](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_byoc.ipynb) – SageMaker Clarify と統合してバイアスを測定し、説明可能性分析レポートを生成することができる独自のモデルとコンテナを構築します。このサンプルノートブックでは、主要な用語も紹介しており、SageMaker Studio Classic を介してレポートにアクセスする方法を説明しています。
+ [Fairness and Explainability with SageMaker Clarify Spark Distributed Processing](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_spark.ipynb) – 分散処理を使用して、データセットのトレーニング前バイアスとモデルトレーニング後バイアスを測定する SageMaker Clarify ジョブを実行します。このサンプルノートブックでは、モデル出力の入力機能の重要な説明を取得し、SageMaker Studio Classic を介して説明可能性分析レポートにアクセスする方法も説明しています。
+ [Explainability with SageMaker Clarify - Partial Dependence Plots (PDP)](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.html) – SageMaker Clarify を使用して PDP を生成し、モデルの説明可能性レポートにアクセスします。
+ [Explaining text sentiment analysis using SageMaker Clarify Natural language processing (NLP) explainability](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/text_explainability/text_explainability.html) – SageMaker Clarify をテキストセンチメント分析に使用します。
+ [画像分類](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.html)と[オブジェクト検出](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.html)にコンピュータビジョン (CV) の説明可能性を使用します。
上記のノートブックは Amazon SageMaker Studio で実行できることが検証済みです。Studio Classic でノートブックを開く方法の手順については、「[Amazon SageMaker Studio Classic ノートブックを作成する、または開く](notebooks-create-open.md)」を参照してください。カーネルの選択を求めるメッセージが表示されたら、**[Python 3 (Data Science)]** (Python 3 (データサイエンス)) を選択します。
# トレーニング前データのバイアス
アルゴリズムのバイアス、差別、公平性、関連トピックは、法律、政策、コンピュータサイエンスなどの分野にわたって研究されてきました。コンピュータシステムが、特定の個人やグループを差別する場合、バイアスがあると見なされる可能性があります。これらのアプリケーションを強化する機械学習モデルは、データから学習し、このデータは格差やその他の固有のバイアスを反映する場合があります。例えば、トレーニングデータには、さまざまな属性グループが十分に反映されていなかったり、偏ったラベルが含まれていたりすることがあります。このようなバイアスを示すデータセットでトレーニングした機械学習モデルは、バイアスを学習してしまい、予測でそのバイアスを再現したり、助長させたりする可能性もあります。機械学習の分野では、機械学習ライフサイクルの各段階でバイアスを検出して測定することで、バイアスに対処する機会を提供します。Amazon SageMaker Clarify を使用すると、モデルのトレーニングに使用されるデータがバイアスをエンコードしているかどうかを判断できます。
トレーニング前とトレーニング後にバイアスを測定し、推論のためにモデルをエンドポイントにデプロイした後にベースラインに対してモニタリングできます。トレーニング前のバイアスメトリクスは、モデルのトレーニングに使用される前に、raw データのバイアスを検出して測定するように設計されています。使用されるメトリクスは、モデルの出力に依存しないため、モデルにとらわれません。しかし、公平性にはさまざまな概念があり、バイアスの明確な測定が必要です。Amazon SageMaker Clarify は、さまざまな公平性基準を定量化するためのバイアスメトリクスを提供します。
バイアスメトリクスの詳細については、「[Learn How Amazon SageMaker Clarify Helps Detect Bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias)」と「[Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」を参照してください。
## バイアスと公平性に関する Amazon SageMaker Clarify の用語解説
SageMaker Clarify では、バイアスと公平性を説明するために、次の用語を使用しています。
**機能**
表形式データの列に含まれる、観測される現象の個々の測定可能な特性または特徴。
**ラベル**
機械学習モデルのトレーニングの対象となる特徴。*観測ラベル*または*観測結果*とも呼ばれます。
**予測ラベル**
モデルによって予測されるラベル。*予測結果*とも呼ばれます。
**サンプル**
表形式データの行に含まれる、特徴値とラベル値で記述された観測エンティティ。
**データセット**
サンプルのコレクション。
**Bias (バイアス)**
年齢や所得層など、異なるグループにわたるモデルのトレーニングデータまたは予測動作の不均衡。バイアスは、モデルのトレーニングに使用されるデータまたはアルゴリズムに起因する可能性があります。例えば、機械学習モデルが主に中高年者のデータに基づいてトレーニングされている場合、若年者や高齢者を対象とした予測をする際に精度が低下する可能性があります。
**バイアスメトリクス**
潜在的なバイアスのレベルを示す数値を返す関数。
**バイアスレポート**
特定のデータセットのバイアスメトリクスのコレクション、またはデータセットとモデルの組み合わせ。
**正のラベル値**
サンプルで観測された属性グループにとって有利なラベル値。つまり、サンプルを*肯定的な結果*として指定します。
**負のラベル値**
サンプルで観測された属性グループにとって不利なラベル値。つまり、サンプルを*否定的な結果*として指定します。
**グループ変数**
条件付き属性格差 (CDD) の測定のためのサブグループを形成するために使用されるデータセットのカテゴリ列。シンプソンのパラドックスに関しては、このメトリクスにのみ必要です。
**ファセット**
測定されるバイアスに関する属性を含む列または特徴。
**ファセット値**
バイアスが有利または不利になる可能性のある属性の特徴値。
**予測確率**
モデルによって予測された、正または負の結果を持つサンプルの確率。
## サンプルノートブック
Amazon SageMaker Clarify は、バイアス検出用に次のサンプルノートブックを提供しています。
+ [Amazon SageMaker Clarify による説明可能性とバイアス検出](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.html) - SageMaker Clarify を使用して、バイアスを検出し、特徴量属性を使用してモデル予測を説明するための処理ジョブを作成します。
このノートブックの動作確認が実施されているのは、Amazon SageMaker Studio のみです。Amazon SageMaker Studio でノートブックを開く方法の手順については、「[Amazon SageMaker Studio Classic ノートブックを作成する、または開く](notebooks-create-open.md)」を参照してください。カーネルの選択を求めるメッセージが表示されたら、**[Python 3 (Data Science)]** (Python 3 (データサイエンス)) を選択します。
**Topics**
+ [バイアスと公平性に関する Amazon SageMaker Clarify の用語解説](#clarify-bias-and-fairness-terms)
+ [サンプルノートブック](#clarify-data-bias-sample-notebooks)
+ [トレーニング前のバイアスメトリクス](clarify-measure-data-bias.md)
+ [SageMaker Studio でトレーニング前のデータのバイアスに関するレポートを生成する](clarify-data-bias-reports-ui.md)
# トレーニング前のバイアスメトリクス
機械学習モデルでのバイアスの測定は、バイアスを軽減するための最初のステップです。バイアスの測定は、それぞれ異なる公平性の概念に対応しています。公平性の単純な概念を考慮するだけでも、さまざまなコンテキストで適用可能な多様な測定につながります。例えば、年齢に関する公平性を考慮し、簡単にするために、中高年グループとそれ以外の年齢グループを、*ファセット*と呼ばれる関連する 2 つの属性とします。融資の機械学習モデルの場合、中小企業向けローンを両方の同数の属性に発行する必要がある場合があります。または、求人応募者を処理する際に、各属性を同数ずつ採用したい場合があります。ただし、このアプローチでは、両方の属性が同数ずつ求人に応募してくることが前提となるため、応募者の人数を条件付けした方がよい場合があります。さらに、応募者が同数かどうかではなく、対象となる応募者が同数かどうかを考慮した方がよい場合もあります。つまり、公平性は、両方の年齢属性における対象となる応募者の合格率が同等であること、応募者の不合格率が同等であること、またはその両方と見なすことができます。関心のある属性について、データの比率が異なるデータセットを使用することがあります。この不均衡により、選択したバイアス測定が融合される可能性があります。どちらのファセットを選択するかにより、モデルがより正確になる可能性があります。したがって、アプリケーションや状況に概念的にふさわしいバイアスメトリクスを選択する必要があります。
次の表記法を使用してバイアスメトリクスを説明します。ここでは二項分類の概念モデルについて説明します。この概念モデルでは、事象が、そのサンプル空間に正 (値 1) と負 (値 0) という 2 つの可能な結果のみでラベル付けされます。このフレームワークは通常、簡単な方法でマルチカテゴリ分類に拡張したり、必要に応じて連続的に数値化された結果を含むケースに拡張したりできます。二項分類の場合、正と負のラベルは、有利なファセット a と不利なファセット d の raw データセットに記録された結果に割り当てられます。****これらのラベル y は、*観測ラベル*と呼ばれ、機械学習ライフサイクルのトレーニングまたは推論段階で機械学習モデルによって割り当てられる*予測ラベル* y' とは区別されます。これらのラベルは、それぞれのファセットの結果の確率分布 Pa(y) と Pd(y) を定義するために使用されます。
+ ラベル:
+ y は、トレーニングデータセット内のイベント結果の n 個の観測ラベルを表します。
+ y' は、データセットにある n 個の観察ラベルに対し、トレーニングされたモデルが予測したラベルを表します。
+ 結果:
+ アプリケーションの承認など、サンプルの正の結果 (値 1)。
+ n(1) は、正の結果 (承認) の観測ラベルの数です。
+ n'(1) は、正の結果 (承認) の予測ラベルの数です。
+ アプリケーションの拒否など、サンプルの負の結果 (値 0)。
+ n(0) は、負の結果 (拒否) の観測ラベルの数です。
+ n'(0) は、負の結果 (拒否) の予測ラベルの数です。
+ ファセット値:
+ ファセット a - バイアスが有利になる属性を定義する特徴値。**
+ na は、有利なファセット値の観測ラベルの数: na = na(1) \$1 na(0) ファセット値 a の正と負の観測ラベルの合計。**
+ n'a は、有利なファセット値の予測ラベルの数: n'a = n'a(1) \$1 n'a(0) ファセット値 a の正と負の予測結果ラベルの合計。**n'a = na であることに注意してください。
+ ファセット d - バイアスが不利になる属性を定義する特徴値。**
+ nd は、不利なファセット値の観測ラベルの数: nd = nd(1) \$1 nd(0) ファセット値 d の正と負の観測ラベルの合計。**
+ n'd は、不利なファセット値の予測ラベルの数: n'd = n'd(1) \$1 n'd(0) ファセット値 d の正と負の予測ラベルの合計。**n'd = nd であることに注意してください。
+ ラベル付けされたファセットデータの結果の確率分布:
+ Pa(y) は、ファセット a の観測ラベルの確率分布です。**バイナリラベル付きデータの場合、この分布は、総数に対する正の結果でラベル付けされたファセット a のサンプル数の比率 Pa(y1) = na(1)/ na と、総数に対する負の結果のサンプル数の比率 Pa(y0) = na(0)/ na で与えられます。**
+ Pd(y) は、ファセット d の観測ラベルの確率分布です。**バイナリラベル付きデータの場合、この分布は、総数に対する正の結果でラベル付けされたファセット d のサンプル数Pd(y1) = nd(1)/ nd と、総数に対する負の結果のサンプル数の比率Pd(y0) = nd(0)/ nd で与えられます。**
属性格差でバイアスされたデータでトレーニングされたモデルは、そのバイアスを学習し、さらに助長させる可能性があります。SageMaker Clarify では、モデルのトレーニングにリソースを消費する前にデータのバイアスを特定するため、トレーニングの前に raw データセットで計算できるデータバイアスメトリクスが用意されています。トレーニング前のすべてのメトリクスは、モデルの出力に依存しないため、どのモデルにも有効です。最初のバイアスメトリクスは、ファセットの不均衡を調べますが、結果は調べません。アプリケーションの必要に応じて、トレーニングデータの量が異なるファセット間でどの程度代表的であるかを決定します。残りのバイアスメトリクスは、データ内のファセット a と d について、さまざまな方法で結果ラベルの分布を比較します。****負の値の範囲にあるメトリクスは、負のバイアスを検出できます。次の表に、クイックガイダンス用のチートシートと、トレーニング前のバイアスメトリクスへのリンクを示します。
トレーニング前のバイアスメトリクス
| バイアスメトリクス | 説明 | 質問例 | メトリクス値の解釈 |
| --- | --- | --- | --- |
| [クラス不均衡 (CI)](clarify-bias-metric-class-imbalance.md) | 異なるファセット値間のメンバー数の不均衡を測定します。 | 中高年ファセット以外の属性に十分なデータがないため、年齢ベースのバイアスがある可能性がありますか。 | 正規化された範囲: [-1,\$11] 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [ラベルの比率の差 (DPL)](clarify-data-bias-metric-true-label-imbalance.md) | 異なるファセット値間の正の結果の不均衡を測定します。 | データ内のファセット値の偏ったラベル付けが原因で、機械学習予測に年齢ベースのバイアスが生じる可能性はありますか。 | 正規化されたバイナリおよびマルチカテゴリファセットラベルの範囲: [-1,\$11] 連続ラベルの範囲: (-∞, \$1∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [カルバックライブラー情報量 (KL)](clarify-data-bias-metric-kl-divergence.md) | 異なるファセットの結果分布がエントロピー的に互いにどの程度離れているかを測定します。 | 異なる属性グループのローン申請結果の分布はどのように異なりますか。 | バイナリ、マルチカテゴリ、連続の範囲: [0, \$1∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [ジェンセンシャノン情報量 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) | 異なるファセットの結果分布がエントロピー的に互いにどの程度離れているかを測定します。 | 異なる属性グループのローン申請結果の分布はどのように異なりますか。 | バイナリ、マルチカテゴリ、連続の範囲: [0, \$1∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md) | データセット内の異なるファセットに関連する結果の個別の属性分布間の p- ノルム差を測定します。 | 異なる属性のローン申請結果の分布はどのように異なりますか。 | バイナリ、マルチカテゴリ、連続の範囲: [0, \$1∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [合計変動距離 (TVD)](clarify-data-bias-metric-total-variation-distance.md) | データセット内の異なるファセットに関連する結果の個別の属性分布間の L1- ノルム差の半分を測定します。 | 異なる属性のローン申請結果の分布はどのように異なりますか。 | バイナリ、マルチカテゴリ、連続結果の範囲: [0, \$1∞) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [コルモゴロフスミルノフ (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md) | データセット内の異なるファセットについて、分布の結果間で最大発散を測定します。 | 属性グループによる最大の格差を示しているのは、どの大学の志願結果ですか。 | バイナリ、マルチカテゴリ、連続結果の KS 値の範囲: [0,\$11][\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
| [条件付き属性格差 (CDD)](clarify-data-bias-metric-cddl.md) | 異なるファセット間の結果の格差を、全体としてだけでなく、サブグループごとに測定します。 | 一部のグループでは、大学入試結果の不合格の割合が合格の割合よりも大きいですか。 | CDD の範囲: [-1, \$11] [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-data-bias.html) |
バイアスメトリクスの詳細については、「[金融における機械学習の公平性の測定](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」を参照してください。
**Topics**
+ [クラス不均衡 (CI)](clarify-bias-metric-class-imbalance.md)
+ [ラベルの比率の差 (DPL)](clarify-data-bias-metric-true-label-imbalance.md)
+ [カルバックライブラー情報量 (KL)](clarify-data-bias-metric-kl-divergence.md)
+ [ジェンセンシャノン情報量 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)
+ [Lp-norm (LP)](clarify-data-bias-metric-lp-norm.md)
+ [合計変動距離 (TVD)](clarify-data-bias-metric-total-variation-distance.md)
+ [コルモゴロフスミルノフ (KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)
+ [条件付き属性格差 (CDD)](clarify-data-bias-metric-cddl.md)
# クラス不均衡 (CI)
クラス不均衡 (CI) バイアスは、ファセット値 d のトレーニングサンプルがデータセット内の別のファセット a と比較して少ない場合に発生します。****これは、モデルが小さいファセットを犠牲にして大きいファセットを優先的に適合させるため、ファセット d のトレーニング誤差が大きくなる可能性があるためです。**また、モデルは小さいデータセットを過剰適合させるリスクも高いため、ファセット d のテスト誤差が大きくなる可能性があります。**機械学習モデルが主に中高年者のデータに基づいてトレーニングされる例 (ファセット a) を考えてみましょう。若年者と高齢者を対象とした予測を行う場合 (ファセット b) は、精度が低くなる可能性があります。
(正規化された) ファセット不均衡測定の計算式は次のとおりです。
CI = (na - nd)/(na \$1 nd)
ここで、na はファセット a のメンバー数、nd はファセット d のメンバー数であり、****その値は間隔 [-1、1] の範囲にあります。
+ 正の CI 値は、ファセット a で、データセットにより多くのトレーニングサンプルがあることを示し、1 の値は、データにファセット a のメンバーのみが含まれていることを示します。****
+ ゼロに近い CI の値は、ファセット間のメンバーの分布がより均等であることを示し、ゼロの値は、ファセット間のパーティションが完全に等しいことを示し、トレーニングデータ内のサンプルのバランスのとれた分布を表します。
+ 負の CI 値は、ファセット d で、データセットにより多くのトレーニングサンプルがあることを示し、-1 の値は、データにファセット d のメンバーのみが含まれていることを示します。****
+ -1 または 1 のいずれかの極値に近い CI 値は非常に不均衡であり、偏った予測を行うかなりのリスクがあります。
ファセット間に重大なファセットの不均衡が存在することが判明した場合、そのモデルのトレーニングに進む前にサンプルを再調整することをお勧めします。
# ラベルの比率の差 (DPL)
ラベルの比率の差 (DPL) は、トレーニングデータセット内のファセット d の正のラベルを持つ観測結果の比率と、ファセット a の正のラベルを持つ観測結果の比率を比較します。****例えば、これを使用して、金融ローンの承認を得た中高年者 (ファセット a) と他の年齢層 (ファセット d) の比率を比較できます。****機械学習モデルは、トレーニングデータの決定をできるだけ忠実に模倣しようとします。そのため、DPL が高いデータセットでトレーニングされた機械学習モデルは、将来の予測で同じ不均衡を反映する可能性があります。
ラベルの比率の差の計算式は次のとおりです。
DPL = (qa - qd)
実行する条件は以下のとおりです。
+ qa = na(1)/na は、観測されたラベル値が 1 であるファセット a の比率です。**例えば、ローンの承認を得る中高年の属性の割合です。ここで、na(1) は、正の結果を得るファセット a のメンバー数を表し、na は、ファセット a のメンバー数を表します。****
+ qd = nd(1)/nd は、観測されたラベル値が 1 であるファセット d の比率です。**例えば、ローンの承認を得る中高年の属性以外の人たちの割合です。ここで、nd(1) は、正の結果を得るファセット d のメンバー数を表し、nd は、ファセット d のメンバー数を表します。****
DPL が 0 に十分近い場合、*属性パリティ*が達成されたと言えます。
バイナリおよびマルチカテゴリファセットラベルの場合、DPL 値は間隔 (-1, 1) の範囲にあります。連続ラベルの場合、ラベルをバイナリに折りたたむためのしきい値を設定します。
+ 正の DPL 値は、ファセット a がファセット d と比較して正の結果の割合が高いことを示します。****
+ ゼロに近い DPL の値は、ファセット間の正の結果の割合がより均等であることを示し、ゼロの値は、完全な属性パリティを示します。
+ 負の DPL 値は、ファセット d がファセット a と比較して正の結果の割合が高いことを示します。****
DPL の大きさに問題があるかどうかは、状況によって異なります。問題がある場合、大きな DPL は、データ内の根本的な問題の徴候である可能性があります。例えば、DPL が高いデータセットは、モデルが学習するのに望ましくない年齢ベースの属性グループに対する過去のバイアスや偏見を反映している可能性があります。
# カルバックライブラー情報量 (KL)
カルバックライブラー情報量 (KL) は、ファセット a、 Pa(y) の観測されたラベル分布が、ファセット d、Pd(y) の分布からどの程度離れているかを測定します。****これは、Pa(y) の Pd(y) に対する相対エントロピーとも呼ばれ、Pa(y) から Pd(y) に移動するときに失われる情報量を定量化します。
カルバックライブラーの計算式は次のとおりです。
KL(Pa \$1\$1 Pd) = ∑yPa(y)\$1log[Pa(y)/Pd(y)]
これは、確率 Pa(y) と Pd(y) の対数差の期待値であり、期待値は確率 Pa(y) によって重み付けされます。これは非対称であり、三角不等式を満たさないため、分布間の真の距離ではありません。実装は自然対数を使用し、KL は nat の単位で与えられます。異なる対数の底を使用すると、比例した結果が得られますが、単位は異なります。例えば、2 を底とすると、KL はビット単位で与えられます。
例えば、ローン申請者のグループ (ファセット d) の承認率が 30% で、他の申請者 (ファセット a) の承認率が 80% であるとします。****カルバックライブラー式は、ファセット a とファセット d のラベル分布の相違を次のように示します。****
KL = 0.8\$1ln(0.8/0.3) \$1 0.2\$1ln(0.2/0.7) = 0.53
この例ではラベルがバイナリであるため、計算式には 2 つの項があります。この測定は、バイナリラベルに加えて、複数のラベルに適用できます。例えば、大学入試のシナリオで、志願者に 3 つのカテゴリラベル (yi = \$1y0, y1, y2\$1 = \$1合格, 補欠, 不合格\$1) のいずれかが割り当てられていると仮定します。
バイナリ、マルチカテゴリ、連続結果の KL メトリクスの値の範囲は、[0、\$1∞) です。
+ ゼロに近い値は、結果が異なるファセットに同様に分布していることを意味します。
+ 正の値は、ラベル分布の発散を意味し、正の値が大きいほど発散が大きくなります。
# ジェンセンシャノン情報量 (JS)
ジェンセンシャノン情報量 (JS) は、異なるファセットのラベル分布がエントロピー的に互いにどの程度離れるかを測定します。これは、カルバックライブラー情報量に基づいていますが、対称的です。
ジェンセンシャノン情報量の計算式は次のとおりです。
JS = ½\$1[KL(Pa \$1\$1 P) \$1 KL(Pd \$1\$1 P)]
ここで、P = ½( Pa \$1 Pd ) は、ファセット a と d の平均ラベル分布です。****
バイナリ、マルチカテゴリ、連続結果の JS 値の範囲は、[0, ln(2)) です。
+ ゼロに近い値は、ラベルが同様に分布していることを意味します。
+ 正の値は、ラベル分布の発散を意味し、正の値が大きいほど発散が大きくなります。
このメトリクスは、ファセット全体のラベルの 1 つに大きな相違があるかどうかを示します。
# Lp-norm (LP)
Lp- ノルム (LP) は、トレーニングデータセットの観測ラベルのファセット分布間の p- ノルム距離を測定します。このメトリクスは負ではないため、逆バイアスを検出できません。
Lp- ノルムの計算式は次のとおりです。
Lp(Pa, Pd) = ( ∑y\$1\$1Pa - Pd\$1\$1p)1/p
ここで、点 x と点 y の間の p- ノルム距離は次のように定義されます。
Lp(x, y) = (\$1x1-y1\$1p \$1 \$1x2-y2\$1p \$1 … \$1\$1xn-yn\$1p)1/p
2- ノルムはユークリッドノルムです。例えば、大学入試のマルチカテゴリシナリオで、3 つのカテゴリ (yi = \$1y0, y1, y2\$1 = \$1合格, 補欠, 不合格\$1) の結果分布があるとします。ファセット a と d の結果カウントの差の 2 乗の和を求めます。****結果のユークリッド距離は次のように計算されます。
L2(Pa, Pd) = [(na(0) - nd(0))2 \$1 (na(1) - nd(1))2 \$1 (na(2) - nd(2))2]1/2
コードの説明は以下のとおりです。
+ na(i) は、ファセット a の i 番目のカテゴリの結果の数です。例えば、na(0) は、ファセット a の承認の数です。****
+ nd(i) は、ファセット d の i 番目のカテゴリの結果の数です。例えば、nd(2) は、ファセット d の拒否の数です。****
バイナリ、マルチカテゴリ、連続結果の LP 値の範囲は、[0, √2) です。
+ ゼロに近い値は、ラベルが同様に分布していることを意味します。
+ 正の値は、ラベル分布の発散を意味し、正の値が大きいほど発散が大きくなります。
# 合計変動距離 (TVD)
合計変動距離データバイアスメトリクス (TVD) は、L1- ノルムの半分です。TVD は、ファセット a と d のラベル結果の確率分布間の可能な最大の差です。****L1- ノルムはハミング距離であり、1 つの文字列を別の文字列に変更するのに必要な置換の最小数を決定することにより、2 つのバイナリデータ文字列を比較するために使用されるメトリクスです。文字列が互いにコピーされる場合は、コピー時に発生したエラーの数を決定します。バイアス検出のコンテキストでは、TVD は、ファセット d の結果と一致するように変更する必要があるファセット a の結果の数を定量化します。****
合計変動距離の計算式は次のとおりです。
TVD = ½\$1L1(Pa, Pd)
例えば、大学入試のマルチカテゴリシナリオで、3 つのカテゴリ (yi = \$1y0, y1, y2\$1 = \$1合格, 補欠, 不合格\$1) の結果分布があるとします。TVD を計算するために、結果ごとにファセット a と d のカウントの差を求めます。****結果は次のようになります。
L1(Pa, Pd) = \$1na(0) - nd(0)\$1 \$1 \$1na(1) - nd(1)\$1 \$1 \$1na(2) - nd(2)\$1
コードの説明は以下のとおりです。
+ na(i) は、ファセット a の i 番目のカテゴリの結果の数です。例えば、na(0) は、ファセット a の承認の数です。****
+ nd(i) は、ファセット d の i 番目のカテゴリの結果の数です。例えば、nd(2) は、ファセット d の拒否の数です。**
バイナリ、マルチカテゴリ、連続結果の TVD 値の範囲は、[0、1) です。
+ ゼロに近い値は、ラベルが同様に分布していることを意味します。
+ 正の値は、ラベル分布の発散を意味し、正の値が大きいほど発散が大きくなります。
# コルモゴロフスミルノフ (KS)
コルモゴロフスミルノフバイアスメトリクス (KS) は、データセットのファセット a と d の分布におけるラベル間の最大発散に等しくなります。****SageMaker Clarify によって実装された 2 標本 KS 検定は、最も不均衡なラベルを見つけることにより、ラベルの不均衡の他の測定値を補完します。
コルモゴロフスミルノフメトリクスの計算式は次のとおりです。
KS = max(\$1Pa(y) - Pd(y)\$1)
例えば、大学の志願者グループ (ファセット a) の不合格、補欠、合格がそれぞれ 40％、40％、20％ で、他の志願者 (ファセット d) のこの割合が 20%、10%、70% であるとします。****この場合、コルモゴロフスミルノフバイアスメトリクス値は次のようになります。
KS = max(\$10.4-0.2\$1, \$10.4-0.1\$1, \$10.2-0.7\$1) = 0.5
これは、ファセット分布間の最大発散が 0.5 であり、合格率で発生します。ラベルは基数 3 のマルチクラスであるため、方程式には 3 つの項があります。
バイナリ、マルチカテゴリ、連続結果の LP 値の範囲は、[0、\$11] です。
+ ゼロに近い値は、すべての結果カテゴリのファセット間にラベルが均等に分布していることを示します。例えば、ローンを申請する両方のファセットは、50％ の承認と 50％ の拒否を取得した場合です。
+ 1 に近い値は、1 つの結果のラベルがすべて 1 つのファセットであることを示します。例えば、ファセット a は 100% の承認を取得し、ファセット d は承認を取得しなかった場合です。****
+ 断続的な値は、ラベルの最大不均衡の相対的な程度を示します。
# 条件付き属性格差 (CDD)
属性格差メトリクス (DD) は、ファセットが、データセット内の拒否された結果の割合が承認された結果の割合よりも大きいかどうかを決定します。例えば、男性と女性の 2 つのファセットがデータセットを構成する二項ケースでは、不利なファセットには facet d というラベルが付けられ、有利なファセットには facet a というラベルが付けられます。****例えば、大学入試の場合、女性の不合格者が 46％ で、合格者が 32％ しかいないとすると、不合格者の割合が合格者の割合を上回っているため、*属性格差*があると言えます。この場合、女性の応募者にはファセット *d* というラベルが付けられます。男性の志願者が、不合格となった志願者の 54%、合格した志願者の 68% を占めていた場合、不合格率は合格率よりも低いため、このファセットには属性格差はないと言えます。この場合、男性の志願者にはファセット a というラベルが付けられます。**
有利でないファセット d の属性格差の計算式は次のとおりです。**
DDd = nd(0)/n(0) - nd(1)/n(1) = PdR(y0) - PdA(y1)
コードの説明は以下のとおりです。
+ n(0) = na(0) \$1 nd(0) は、有利なファセット *a* と不利なファセット d のデータセットのうち拒否された結果の総数です。
+ n(1) = na(1) \$1 nd(1) は、有利なファセット *a* と不利なファセット *d* のデータセットのうち拒否された結果の総数です。
+ PdR(y0) は、ファセット d で拒否された結果 (値 0) の割合です。**
+ PdA(y1) は、ファセット d で承認された結果 (値 1) の割合です。**
大学入試の例では、属性格差は DDd = 0.46 - 0.32 = 0.14 です。男性の場合 DDa = 0.54 - 0.68 = - 0.14 です。
シンプソンのパラドックスを除外するには、データセット上のサブグループの層を定義する属性に対して DD を条件付ける条件付き属性格差 (CDD) メトリクスが必要です。再グループ化により、有利でないファセットの明らかな属性格差の原因についてインサイトを得ることができます。典型的な例は、バークレー校の入試で、男性の方が女性よりも全体的に合格率が高かったというものです。この場合の統計量は DD の計算例で使用されました。しかし、学科別のサブグループを調べると、学科別に条件付けするとは女性の方が男性よりも高い合格率であることが示されました。その説明は、女性は男性よりも合格率の低い学科に志願していたということでした。サブグループ別の合格率を調べると、合格率の低い学科では、実際に女性の方が男性よりも高い合格率であることがわかりました。
CDD メトリクスは、データセットの属性によって定義されたサブグループに見られる格差をすべて平均化することで、1 つの測定値を提供します。これは、各サブグループの属性格差 (DDi) の加重平均として定義され、各サブグループの格差は、含まれる観測値の数に比例して重み付けされます。条件付き属性格差の計算式は次のとおりです。
CDD = (1/n)\$1∑ini \$1DDi
コードの説明は以下のとおりです。
+ ∑ini = n は、観測値の総数であり、niは、各サブグループの観測値の数です。
+ DDi = ni(0)/n(0) - ni(1)/n(1) = PiR(y0) - PiA(y1) は、i 番目のサブグループの属性格差です。
サブグループの属性格差 (DDi) は、各サブグループの拒否された結果の割合と承認された結果の割合の差です。
データセット全体の DDd またはその条件付きサブグループ DDi の二項結果の DD 値の範囲は [-1, \$11] です。
+ \$11: ファセット a またはサブグループに拒否がなく、ファセット d またはサブグループに承認がない場合****
+ 正の値は、データセット内のファセット d として属性格差がないことを示します。つまり、データセット内のサブグループで、拒否された結果の割合が、承認された結果の割合よりも大きいことを示します。**値が高くなるほどファセットは不利になり、不均衡が大きくなります。
+ 負の値は、データセット内のファセット d として属性格差がないことを示します。つまり、データセット内のサブグループで、承認された結果の割合が、拒否された結果の割合よりも大きいことを示します。**値が低いほど、ファセットは有利になります。
+ -1: ファセット d またはサブグループに拒否がなく、ファセット a またはサブグループに承認がない場合****
何も条件付けしない場合、DPL がゼロの場合に限り、CDD はゼロになります。
このメトリクスは、EU および英国の非差別法および法学における直接差別、間接差別、客観的正当化の概念を調査するのに有用です。詳細については、「[公平性を自動化できない理由](https://arxiv.org/abs/2005.05906)」を参照してください。この論文には、学部の入学率サブグループに基づく条件付けがシンプソンのパラドックスをどのように示しているかを示す、バークレー大学の入学事例に関する関連データと分析も含まれています。
# SageMaker Studio でトレーニング前のデータのバイアスに関するレポートを生成する
SageMaker Clarify は Amazon SageMaker Data Wrangler と統合されており、独自のコードを記述しなくても、データ準備中にバイアスを特定するのに役立ちます。Data Wrangler は、Amazon SageMaker Studio でデータをインポート、準備、変換、特徴化、分析するためのエンドツーエンドのソリューションを提供します。Data Wrangler のデータ準備ワークフローの概要については、「[Amazon SageMaker Data Wrangler で ML データを準備する](data-wrangler.md)」を参照してください。
性別や年齢などの関心のある属性を指定すると、SageMaker Clarify は一連のアルゴリズムを実行して、これらの属性にバイアスがあるかどうかを検出します。アルゴリズムの実行後、SageMaker Clarify は、バイアスの可能性のある発生源と重要度の説明を含むビジュアルレポートを提供するため、バイアスを軽減するステップを計画できます。例えば、ある年齢グループに対するビジネスローンの例が、他の年齢グループと比較して少ない財務データセットで、SageMaker AI は不均衡にフラグを立てて、その年齢グループに不利なモデルを回避できます。
**データバイアスを分析して報告する**
Data Wrangler の使用を開始するには、「[Data Wrangler の開始方法](data-wrangler-getting-started.md)」を参照してください。
1. Amazon SageMaker Studio Classic で、左側のパネルの **[ホーム]** (![\[Black square icon representing a placeholder or empty image.\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/studio/icons/house.png)) メニューから **[データ]** ノードに移動し、**[Data Wrangler]** を選択します。これにより、Studio Classic で **[Data Wrangler ランディングページ]** が開きます。
1. **[\$1 データのインポート]** ボタンを選択して新しいフローを作成します。
1. フローページの **[インポート]** タブから Amazon S3 を選択し、Amazon S3 バケットに移動してデータセットを見つけ、**[インポート]** を選択します。
1. データをインポートしたら、**[データフロー]** タブのフローグラフで、**[データ型]** ノードの右にある **[\$1]** 記号を選択します。
1. **[分析を追加]** を選択します。
1. **[分析を作成]** ページで、**[分析タイプ]** として **[バイアスレポート]** を選択します。
1. レポートの **[名前]** 、予測する列とそれが値なのかしきい値なのか、バイアス (ファセット) を分析する列およびそれが値なのかしきい値なのかを指定して、バイアスレポートを設定します。
1. バイアスメトリクスを選択して、バイアスレポートの設定を続行します。
![\[バイアスメトリクスを選択します。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify-data-wrangler-configure-bias-metrics.png)
1. **[Check for bias]** (バイアスを確認) を選択して、バイアスレポートを生成して表示します。下にスクロールしてすべてのレポートを表示します。
![\[バイアスレポートを生成して表示します。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify-data-wrangler-create-bias-report.png)
1. バイアスメトリクスそれぞれの説明の右側にあるキャレットを選択すると、メトリクス値の需要度を解釈するのに役立つドキュメントが表示されます。
1. バイアスメトリクス値のテーブル概要を表示するには、**[テーブル]** トグルを選択します。レポートを保存するには、ページの右下隅にある **[保存]** を選択します。レポートは **[データフロー]** タブのフローグラフで確認できます。レポートをダブルクリックして開きます。
# トレーニング済みデータとモデルバイアス
トレーニング後のバイアス分析は、データ内のバイアス、または分類と予測アルゴリズムによって導入されたバイアスから発生した可能性のあるバイアスを明らかにするのに役立ちます。これらの分析では、ラベルなどのデータとモデルの予測が考慮されます。パフォーマンスを評価するには、予測ラベルを分析するか、予測を、異なる属性を持つグループに関してデータ内で観測された目標値と比較します。公平性にはさまざまな概念があり、測定をするために、それぞれにさまざまなバイアスメトリクスが必要になります。
公平性の法的概念は、検出が難しいため、把握が容易ではない可能性があります。例えば、一見公平なアプローチであっても、有利でないファセット *d* と呼ばれるグループが不利益を受ける場合に生じる、格差影響という概念があります。このタイプのバイアスは機械学習モデルが原因ではないかもしれませんが、トレーニング後のバイアス分析によって検出可能です。
Amazon SageMaker Clarify は、用語の一貫した使用を保証するように努めています。用語とその定義の一覧については、「[バイアスと公平性に関する Amazon SageMaker Clarify の用語解説](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)」を参照してください。
トレーニング後のバイアスメトリクスの詳細については、「[Learn How Amazon SageMaker Clarify Helps Detect Bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)」と「[Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」を参照してください。
# トレーニング済みデータのメトリクスとモデルのバイアスのメトリクス
Amazon SageMaker Clarify には、公平性のさまざまな概念を定量化するのに役立つ 11 のトレーニング後のデータとモデルのバイアスメトリクスが用意されています。これらの概念をすべて同時に満たすことはできず、分析対象の潜在的なバイアスを含むケースの詳細に応じて選択されます。これらのメトリクスのほとんどは、異なる属性グループの二項分類混同行列から取得した数値の組み合わせです。公平性とバイアスは幅広いメトリクスで定義できるため、個々のユースケースに関連するメトリクスを理解し選択するには人間の判断が必要であり、顧客は適切なステークホルダーと相談して、その適用に適した公平性の尺度を決定する必要があります。
次の表記法を使用してバイアスメトリクスを説明します。ここでは二項分類の概念モデルについて説明します。この概念モデルでは、事象が、そのサンプル空間に正 (値 1) と負 (値 0) という 2 つの可能な結果のみでラベル付けされます。このフレームワークは通常、簡単な方法でマルチカテゴリ分類に拡張したり、必要に応じて連続的に数値化された結果を含むケースに拡張したりできます。二項分類の場合、正と負のラベルは、有利なファセット a と不利なファセット d の raw データセットに記録された結果に割り当てられます。****これらのラベル y は、*観測ラベル*と呼ばれ、機械学習ライフサイクルのトレーニングまたは推論段階で機械学習モデルによって割り当てられる*予測ラベル* y' とは区別されます。これらのラベルは、それぞれのファセットの結果の確率分布 Pa(y) と Pd(y) を定義するために使用されます。
+ ラベル:
+ y は、トレーニングデータセット内のイベント結果の n 個の観測ラベルを表します。
+ y' は、データセットにある n 個の観察ラベルに対し、トレーニングされたモデルが予測したラベルを表します。
+ 結果:
+ アプリケーションの承認など、サンプルの正の結果 (値 1)。
+ n(1) は、正の結果 (承認) の観測ラベルの数です。
+ n'(1) は、正の結果 (承認) の予測ラベルの数です。
+ アプリケーションの拒否など、サンプルの負の結果 (値 0)。
+ n(0) は、負の結果 (拒否) の観測ラベルの数です。
+ n'(0) は、負の結果 (拒否) の予測ラベルの数です。
+ ファセット値:
+ ファセット a - バイアスが有利になる属性を定義する特徴値。**
+ na は、有利なファセット値の観測ラベルの数: na = na(1) \$1 na(0) ファセット値 a の正と負の観測ラベルの合計。**
+ n'a は、有利なファセット値の予測ラベルの数: n'a = n'a(1) \$1 n'a(0) ファセット値 a の正と負の予測結果ラベルの合計。**n'a = na であることに注意してください。
+ ファセット d - バイアスが不利になる属性を定義する特徴値。**
+ nd は、不利なファセット値の観測ラベルの数: nd = nd(1) \$1 nd(0) ファセット値 d の正と負の観測ラベルの合計。**
+ n'd は、不利なファセット値の予測ラベルの数: n'd = n'd(1) \$1 n'd(0) ファセット値 d の正と負の予測ラベルの合計。**n'd = nd であることに注意してください。
+ ラベル付けされたファセットデータの結果の確率分布:
+ Pa(y) は、ファセット a の観測ラベルの確率分布です。**バイナリラベル付きデータの場合、この分布は、総数に対する正の結果でラベル付けされたファセット a のサンプル数の比率 Pa(y1) = na(1)/ na と、総数に対する負の結果のサンプル数の比率 Pa(y0) = na(0)/ na で与えられます。**
+ Pd(y) は、ファセット d の観測ラベルの確率分布です。**バイナリラベル付きデータの場合、この分布は、総数に対する正の結果でラベル付けされたファセット d のサンプル数Pd(y1) = nd(1)/ nd と、総数に対する負の結果のサンプル数の比率Pd(y0) = nd(0)/ nd で与えられます。**
次の表に、クイックガイダンス用のチートシートと、トレーニング後のバイアスメトリクスへのリンクを示します。
トレーニング後のバイアスメトリクス
| トレーニング後のバイアスメトリクス | 説明 | 質問例 | メトリクス値の解釈 |
| --- | --- | --- | --- |
| [予測ラベルにおける正の比率の差 (DPPL)](clarify-post-training-bias-metric-dppl.md) | 有利なファセット a と不利なファセット d の間の正の予測の割合の差を測定します。 | バイアスを示す可能性のある予測された正の結果において、属性グループ間で不均衡がありましたか。 | 正規化されたバイナリおよびマルチカテゴリファセットラベルの範囲: `[-1,+1]` 連続ラベルの範囲: (-∞, \$1∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [異種影響 (DI)](clarify-post-training-bias-metric-di.md) | 有利なファセット a と不利なファセット d の予測ラベルの比率を測定します。 | バイアスを示す可能性のある予測された正の結果において、属性グループ間で不均衡がありましたか。 | 正規化されたバイナリ、マルチカテゴリファセット、連続ラベルの範囲: [0,∞) 解釈: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [予測ラベルの条件付き属性格差 (CDDPL)](clarify-post-training-bias-metric-cddpl.md) | ファセット全体だけでなく、サブグループ別の予測ラベルの格差を測定します。 | 一部の属性グループでは、ローン申請結果で、拒否の割合が承認の割合よりも大きいですか。 | バイナリ、マルチカテゴリ、連続結果の CDDPL 値の範囲: `[-1, +1]` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [反事実フリップテスト (FT)](clarify-post-training-bias-metric-ft.md) | ファセット d の各メンバーを調べ、ファセット a の類似メンバーが異なるモデル予測をしているかどうかを評価します。 | 特定の年齢層に属する 1 つのグループは、すべての特徴が異なる年齢層とほぼ一致しているのに、平均してより高い給料を支払われていますか。 | バイナリおよびマルチカテゴリファセットラベルの範囲は [-1, \$11] です。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [精度差 (AD)](clarify-post-training-bias-metric-ad.md) | 有利なファセットと不利なファセットの予測精度の差を測定します。 | モデルは、すべての属性グループのアプリケーションのラベルを正確に予測しますか。 | バイナリおよびマルチカテゴリファセットラベルの範囲は [-1, \$11] です。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [リコール差 (RD)](clarify-post-training-bias-metric-rd.md) | 有利なファセットと不利なファセットのモデルのリコールを比較します。 | ある属性は、別の属性と比較して、モデルのリコールが高いことに起因する、年齢ベースの融資のバイアスはありますか。 | 二項分類とマルチカテゴリ分類の範囲: `[-1, +1]`。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [条件付き承認の差 (DCAcc)](clarify-post-training-bias-metric-dcacc.md) | 観測されたラベルを、モデルによって予測されたラベルと比較します。予測される肯定的な結果 (受け入れ) について、これがあらゆるファセットで同じかどうかを評価します。 | ある年齢層を別の年齢層と比較したとき、ローンが受理される頻度 (資格に基づく) は予測よりも多いですか、それとも少ないですか。 | バイナリ、マルチカテゴリファセット、連続ラベルの範囲: (-∞, \$1∞)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [承認率の差 (DAR)](clarify-post-training-bias-metric-dar.md) | 有利なファセットと不利なファセット間で、予測された陽性 (TP \$1 FP) に対する観測された正の結果 (TP) の比率の差を測定します。 | すべての年齢グループにわたって対象となる申請者のローン承認を予測する場合、モデルの精度は同じですか。 | バイナリ、マルチカテゴリファセット、連続ラベルの範囲は [-1, \$11] です。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [特異度差 (SD)](clarify-post-training-bias-metric-sd.md) | 有利なファセットと不利なファセットの間でモデルの特異性を比較します。 | このモデルでは、ある年齢層の特異性が他の年齢層に比べて高いと予測されているため、融資に年齢に基づくバイアスはありますか。 | 二項分類とマルチカテゴリ分類の範囲: `[-1, +1]`。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [条件付き拒否の差 (DCR)](clarify-post-training-bias-metric-dcr.md) | 観測ラベルとモデルによって予測されたラベルと比較し、負の結果 (拒否) に対してファセット全体でこれが同じかどうかを評価します。 | ある属性で予測されるローン申請の拒否は、資格に基づく別の属性と比較して、多いですか少ないですか。 | バイナリ、マルチカテゴリファセット、連続ラベルの範囲: (-∞, \$1∞)。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [拒否率の差 (DRR)](clarify-post-training-bias-metric-drr.md) | 不利なファセットと有利なファセット間で、予測された陰性 (TN \$1 FN) に対する観測された負の結果 (TN) の比率の差を測定します。 | すべての属性にわたって対象外の申請者のローン拒否を予測する場合、モデルの精度は同じですか。 | バイナリ、マルチカテゴリファセット、連続ラベルの範囲は [-1, \$11] です。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [処理の同等性 (TE)](clarify-post-training-bias-metric-te.md) | 有利なファセットと不利なファセット間の偽陽性と偽陰性の比率の差を測定します。 | ローン申請では、偽陽性と偽陰性の相対比率は、すべての属性で同じですか。 | バイナリおよびマルチカテゴリファセットラベルの範囲: (-∞, \$1∞)。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
| [一般化エントロピー (GE)](clarify-post-training-bias-metric-ge.md) | モデル予測によって各入力に割り当てられた利益 b の不平等を測定します。 | ローン申請分類の候補となる 2 つのモデルのうち、一方は望ましい結果の分布が他方よりも不均一になりますか。 | バイナリおよびマルチカテゴリファセットラベルの範囲は (0、0.5) です。モデルが誤判定のみを予測する場合、GE は定義されません。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/clarify-measure-post-training-bias.html) |
トレーニング後のバイアスメトリクスの詳細については、「[A Family of Fairness Measures for Machine Learning in Finance](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」を参照してください。
**Topics**
+ [予測ラベルにおける正の比率の差 (DPPL)](clarify-post-training-bias-metric-dppl.md)
+ [異種影響 (DI)](clarify-post-training-bias-metric-di.md)
+ [条件付き承認の差 (DCAcc)](clarify-post-training-bias-metric-dcacc.md)
+ [条件付き拒否の差 (DCR)](clarify-post-training-bias-metric-dcr.md)
+ [特異度差 (SD)](clarify-post-training-bias-metric-sd.md)
+ [リコール差 (RD)](clarify-post-training-bias-metric-rd.md)
+ [承認率の差 (DAR)](clarify-post-training-bias-metric-dar.md)
+ [拒否率の差 (DRR)](clarify-post-training-bias-metric-drr.md)
+ [精度差 (AD)](clarify-post-training-bias-metric-ad.md)
+ [処理の同等性 (TE)](clarify-post-training-bias-metric-te.md)
+ [予測ラベルの条件付き属性格差 (CDDPL)](clarify-post-training-bias-metric-cddpl.md)
+ [反事実フリップテスト (FT)](clarify-post-training-bias-metric-ft.md)
+ [一般化エントロピー (GE)](clarify-post-training-bias-metric-ge.md)
# 予測ラベルにおける正の比率の差 (DPPL)
予測ラベルにおける正の比率の差 (DPPL) メトリクスは、モデルがファセットごとに異なる結果を予測するかどうかを決定します。これは、ファセット a の正の予測の比率 (y' = 1) とファセット d の正の予測の比率 (y' = 1) の差として定義されます。****例えば、モデル予測が中高年グループ (ファセット a) の 60% と他の年齢グループ (ファセット d) の 50% にローンを許可する場合、ファセット d に対しバイアスされている可能性があります。******この例では、バイアスのケースに対して 10% の差が重要かどうかを判断する必要があります。
トレーニング前バイアスの尺度であるラベルの割合の差 (DPL) とトレーニング後バイアスの尺度である DPPL の差を比較すると、データセットに最初から存在する正の割合のバイアスがトレーニング後に変化するかを評価できます。DPPL が DPL より大きい場合、トレーニング後に正の割合のバイアスが増加していることになります。DPPL が DPL よりも小さい場合、モデルはトレーニング後に正の割合でバイアスが増加しなかったことになります。DPL と DPPL を比較しても、モデルがあらゆるディメンションでバイアスを低減するとは限りません。例えば、[反事実フリップテスト (FT)](clarify-post-training-bias-metric-ft.md) や [精度差 (AD)](clarify-post-training-bias-metric-ad.md) など、別のメトリクスを考慮すると、モデルにバイアスがかかる可能性があります。バイアス検出の詳細については、ブログ記事「[Learn how Amazon SageMaker Clarify helps detect bias](https://aws.amazon.com/blogs/machine-learning/learn-how-amazon-sagemaker-clarify-helps-detect-bias/)」を参照してください。DPL の詳細については「[ラベルの比率の差 (DPL)](clarify-data-bias-metric-true-label-imbalance.md)」を参照してください。
DPPL 式は以下のとおりです。
DPPL = q'a - q'd
コードの説明は以下のとおりです。
+ q'a = n'a(1)/na は、値 1 の正の結果を得るファセット a の予測される割合です。**この例では、ローンが許可されると予測される中高年ファセットの割合です。ここで、n'a(1) は、値 1 の正の予測結果を得るファセット a のメンバー数を表し、na は、ファセット a のメンバー数を表します。****
+ q'd = n'd(1)/nd は、値 1 の正の結果を得るファセット d の予測される割合です。**この例では、高齢者と若年者のファセットがローンを許可されると予測しています。ここで、n'd(1) は、正の予測結果を得るファセット d のメンバー数を表し、nd は、ファセット d のメンバー数を表します。****
DPPL が 0 に十分近い場合、トレーニング後の*属性パリティ*が達成されたことを意味します。
バイナリおよびマルチカテゴリファセットラベルの場合、正規化された DPL 値は間隔 [-1, 1] の範囲にあります。連続ラベルの場合、値は間隔 (-∞, \$1∞) で変化します。
+ 正の DPPL 値は、ファセット a が、ファセット d と比較して予測される正の結果の割合が高いことを示します。****
これは、*正のバイアス*と呼ばれます。
+ ゼロに近い DPPL の値は、ファセット a および d 間で予測される正の結果の割合がより均等であることを示し、ゼロの値は、完全な属性パリティを示します。****
+ 負の DPPL 値は、ファセット d が、ファセット a と比較して予測される正の結果の割合が高いことを示します。****これは、*負のバイアス*と呼ばれます。
# 異種影響 (DI)
予測ラベルメトリクスの正の比率の差は、比率の形式で評価できます。
予測ラベルメトリクスの正の比率の比較は、[予測ラベルにおける正の比率の差 (DPPL)](clarify-post-training-bias-metric-dppl.md)の場合のように、差としてではなく、比率の形式で評価できます。異種影響 (DI) メトリクスは、ファセット a の正の予測 (y' = 1) の割合に対するファセット d の正の予測 (y' = 1) の割合の比率として定義されます。****例えば、モデル予測が中高年グループ (ファセット a) の 60% とその他の年齢グループ (ファセット d) の 50% にローンを許可する場合、DI = .5/.6 = 0.8 となり、ファセット d で表される他の中高年グループに対して正のバイアスと悪影響があることが示されます。******
予測ラベルの比率の計算式は次のとおりです。
DI = q'd/q'a
コードの説明は以下のとおりです。
+ q'a = n'a(1)/na は、値 1 の正の結果を得るファセット a の予測される割合です。**この例では、ローンが許可されると予測される中高年ファセットの割合です。ここで、n'a(1) は、正の予測結果を得るファセット a のメンバー数を表し、na は、ファセット a のメンバー数を表します。****
+ q'd = n'd(1)/nd は、値 1 の正の結果を得るファセット *d* の予測される割合です。この例では、高齢者と若年者のファセットがローンを許可されると予測しています。ここで、n'd(1) は、正の予測結果を得るファセット d のメンバー数を表し、nd は、ファセット d のメンバー数を表します。****
バイナリ、マルチカテゴリファセット、連続ラベルの場合、DI 値は間隔 [0, ∞) の範囲にあります。
+ 1 より小さい値は、ファセット a が、ファセット d よりも予測される正の結果の割合が高いことを示します。****これは、*正のバイアス*と呼ばれます。
+ 値 1 は、属性パリティを示します。
+ 1 より大きい値は、ファセット d が、ファセット a よりも予測される正の結果の割合が高いことを示します。****これは、*負のバイアス*と呼ばれます。
# 条件付き承認の差 (DCAcc)
このメトリクスは、観測ラベルと、モデルによって予測されたラベルを比較し、予測された正の結果に対してファセット全体でこれが同じかどうかを評価します。このメトリクスは、特定のファセットに対してモデルが予測した正の結果 (ラベル y') が、トレーニングデータセットで観測された結果 (ラベル y) と比較してどれだけ多いかを定量化するという点で、人間のバイアスを模倣することに近づいています。例えば、中高年 (ファセット a) のローン申請のトレーニングデータセットで、他の年齢グループを含むファセット (ファセット d) と比較して、資格に基づくモデルで予測されるよりも多くの承認 (正の結果) があった場合、これは中高年に有利なローンの承認方法に潜在的なバイアスがあることを示している可能性があります。****
条件付き承認の差の計算式は次のとおりです。
DCAcc = ca - cd
コードの説明は以下のとおりです。
+ ca = na(1)/ n'a(1) は、ファセット a の値 1 (承認) の正の結果の観測数と、ファセット a の正の結果 (承認) の予測数の比率です。****
+ cd = nd(1)/ n'd(1) は、ファセット d の値 1 (承認) の正の結果の観測数と、ファセット d の予測される正の結果 (承認) の予測数の比率です。****
DCAcc メトリクスは、資格に基づく優先処理を明らかにする、正と負の両方のバイアスを捉えることができます。次のような、ローンの承認に関する年齢ベースのバイアスの例を考えてみましょう。
**例 1: 正のバイアス**
ローンを申請した 100 人の中高年の人たち (ファセット a) と 50 人の他の年齢グループの人たち (ファセット d) からなるデータセットがあり、モデルはファセット a から 60 人、ファセット d から 30 人にローンを許可することを推奨したとします。********つまり、予測された比率には、DPPL メトリクスに関するバイアスはありません。しかし、観測ラベルは、ファセット a から 70 人、ファセット d から 20 人にローンが許可されたことを示しています。****言い換えれば、このモデルは、トレーニングデータで観測されたラベルが示唆するよりも 17% 少なく中高年のファセットに融資を許可し (70/60 = 1.17)、観測されたラベルが示唆するよりも 33% 多く他の年齢グループにローンを許可しています (20/30 = 0.67)。DCAcc 値を計算すると、次のようになります。
DCAcc = 70/60 - 20/30 = 1/2
正の値は、中高年のファセット a に対して潜在的なバイアスがあることを示しており、他のファセット d と比較して、観測データ (バイアスがないと見なされる) が示すよりも受け入れ率が低いことを示しています。**
**例 2: 負のバイアス**
ローンを申請した 100 人の中高年の人たち (ファセット a) と 50 人の他の年齢グループの人たち (ファセット d) からなるデータセットがあり、モデルはファセット a から 60 人、ファセット d から 30 人にローンを許可することを推奨したとします。********つまり、予測された比率には、DPPL メトリクスに関するバイアスはありません。しかし、観測ラベルは、ファセット a から 50 人、ファセット d から 40 人にローンが許可されたことを示しています。****言い換えれば、このモデルは、提案されたトレーニングデータの観測ラベルよりも中高年グループのファセットから 17% 少なくローンを許可し (50/60 = 0.83) 、他の年齢グループからは、提案された観測ラベルよりも 33% 多くローンを許可したことになります (40/30 = 1.33)。DCAcc 値を計算すると、次のようになります。
DCAcc = 50/60 - 40/30 = -1/2
負の値は、観測されたデータ (バイアスがないと見なされる) が示すよりも、中高年ファセット a と比較して受け入れ率が低いファセット d に対して潜在的なバイアスがあることを示します。****
DCAcc を使用すると、人間参加型設定でモデル予測を監督する人間による潜在的な (意図的でない) バイアスを検出するのに役立ちます。例えば、モデルによる予測 y' にはバイアスはないが、最終的な決定は、モデル予測を変更して新しい最終バージョンの y' を生成できる (おそらく追加機能のアクセス権を持つ) 人間によって行われると仮定します。人間による追加処理は、1 つのファセットからの不均衡な数へのローンを意図せずに拒否する可能性があります。DCAcc は、このような潜在的なバイアスの検出に役立ちます。
バイナリ、マルチカテゴリファセット、連続ラベルの条件付き承認の差の値の範囲は、(-∞, \$1∞) です。
+ 正の値は、ファセット a の予測された承認数に対する観測された承認数の比率が、ファセット d の同じ比率よりも高い場合に発生します。****これらの値は、ファセット a の対象となる申請者に対するバイアスがある可能性を示しています。**比率の差が大きいほど、見かけ上のバイアスは大きくなります。
+ ゼロに近い値は、ファセット a の予測された承認数に対する観測された承認数の比率が、ファセット d の比率と似ている場合に発生します。****これらの値は、予測された承認率がラベル付きデータの観測値と一致しており、両方のファセットから対象となる申請者が同様の方法で承認されていることを示します。
+ 負の値は、ファセット a の予測された承認数に対する観測された承認数の比率が、ファセット d の同様の比率よりも低い場合に発生します。****これらの値は、ファセット d の対象となる申請者に対するバイアスがある可能性を示しています。**比率の差が負であるほど、見かけ上のバイアスは大きくなります。
# 条件付き拒否の差 (DCR)
このメトリクスは、観測ラベルとモデルによって予測されたラベルを比較し、負の結果 (拒否) のファセット全体でこれが同じかどうかを評価します。このメトリクスは、特定のファセットに対してモデルから得られた負の結果 (予測ラベル y') が、トレーニングデータセットのラベルで提案された結果 (観測ラベル y) と比較してどれだけ多いかを定量化するという点で、人間のバイアスを模倣することに近づいています。例えば、中高年グループ (ファセット a) のローン申請に対して、他の年齢グループを含むファセット (ファセット d) と比較して、資格に基づくモデルで予測されるよりも多くの拒否 (負の結果) があった場合、これは他のグループよりも中高年層に有利な、ローンの拒否方法における潜在的なバイアスがあることを示している可能性があります。****
条件付き承認の差の計算式は次のとおりです。
DCR = rd - ra
コードの説明は以下のとおりです。
+ rd = nd(0)/ n'd(0) は、ファセット d の値 0 (拒否) の負の結果の観測数と、ファセット d の負の結果 (拒否) の予測数の比率です。****
+ ra = na(0)/ n'a(0) は、ファセット a の値 0 (拒否) の負の結果の観測数と、ファセット a の値 0 (拒否) の負の結果の予測数の比率です。****
DCR メトリクスは、資格に基づく優先処理を明らかにする、正と負の両方のバイアスを捉えることができます。次のような、ローンの拒否に関する年齢ベースのバイアスの例を考えてみましょう。
**例 1: 正のバイアス**
ローンを申請した 100 人の中高年の人たち (ファセット a) と 50 人の他の年齢グループの人たち (ファセット d) からなるデータセットがあり、モデルはファセット a から 60 人、ファセット d から 30 人がローンを拒否することを推奨したとします。********つまり、予測された比率には DPPL メトリクスによるバイアスはありません。しかし、観測ラベルは、ファセット a から 50 人、ファセット d から 40 人が拒否されたことを示しています。****言い換えれば、このモデルは、トレーニングデータの観測ラベルが示唆するよりも中高年グループのファセットから 17% 多くローンを拒否し (50/60 = 0.83)、他の年齢グループからは、観測ラベルが示唆するよりも 33% 少なくローンを拒否したことになります (40/30 = 1.33)。DCR 値は、ファセット間の観測された拒否率と予測された拒否率の比率におけるこの差を定量化します。正の値は、観測されたデータ (バイアスがないとみなされる) が示すよりも他のグループと比べて拒否率が低い中高年グループに有利なバイアスが存在する可能性があることを示しています。
DCR = 40/30 - 50/60 = 1/2
**例 2: 負のバイアス**
ローンを申請した 100 人の中高年の人たち (ファセット a) と 50 人の他の年齢グループの人たち (ファセット d) からなるデータセットがあり、モデルはファセット a から 60 人、ファセット d から 30 人がローンを拒否することを推奨したとします。********つまり、予測された比率には DPPL メトリクスによるバイアスはありません。しかし、観測ラベルは、ファセット a から 70 人、ファセット d から 20 人が拒否されたことを示しています。****言い換えれば、このモデルは、トレーニングデータで観測されたラベルが示唆するよりも中高年グループのファセットから 17% 少なくローンを拒否し (70/60 = 1.17)、他の年齢グループからは、観測ラベルが示唆するよりも 33% 多くローンを拒否したことになります (20/30 = 0.67)。負の値は、中年のファセット a と比較してファセット a に有利なバイアスが存在する可能性があり、観測されたデータ (バイアスがないとみなされる) が示すよりも拒否率が低いことを示しています。****
DCR = 20/30 - 70/60 = -1/2
バイナリ、マルチカテゴリファセット、連続ラベルの条件付き拒否の差の値の範囲は、(-∞, \$1∞) です。
+ 正の値は、ファセット d の予測された拒否数に対する観測された拒否数の比率が、ファセット a の比率よりも大きい場合に発生します。****これらの値は、ファセット a の対象となる申請者に対するバイアスがある可能性を示しています。**DCR メトリクスの値が大きいほど、見かけ上のバイアスは大きくなります。
+ ゼロに近い値は、ファセット a の予測された承認数に対する観測された拒否数の比率が、ファセット d の比率と似ている場合に発生します。****これらの値は、予測された拒否率がラベル付きデータの観測値と一致しており、両方のファセットから対象となる申請者が同様の方法で拒否されていることを示しています。
+ 負の値は、ファセット d の予測された拒否数に対する観測された拒否数の比率が、ファセット a の同様の比率よりも低い場合に発生します。****これらの値は、ファセット d の対象となる申請者に対するバイアスがある可能性を示しています。**負の DCR メトリクスが大きいほど、見かけ上のバイアスは大きくなります。
# 特異度差 (SD)
特異度差 (SD) とは、有利なファセット a と不利なファセット d の特異度の差です。****特異度は、モデルが負の結果 (y'=0) を正しく予測する頻度を測定します。これらの特異度の差は、バイアスの潜在的な形です。
特異度は、すべての y=0 のケースがそのファセットに対して正しく予測されている場合に、そのファセットに最適です。Type I エラーと呼ばれる偽陽性をモデルが最小化すると、特異度は高くなります。例えば、ファセット a へのローンの特異度が低いことと、ファセット d へのローンの特異度が高いことの違いは、ファセット d に対するバイアスの尺度です。******
次の式は、ファセット a と d の特異度の違いを示しています。****
SD = TNd/(TNd \$1 FPd) - TNa/(TNa \$1 FPa) = TNRd - TNRa
SD の計算に使用される以下の変数は、次のように定義されます。
+ TNd は、ファセット d に対して予測される真陰性です。**
+ FPd は、ファセット d に対して予測される偽陽性です。**
+ TNd は、ファセット a に対して予測される真陰性です**
+ FPd は、ファセット a に対して予測される偽陽性です。**
+ TNRa = TNa/(TNa \$1 FPa) は、ファセット a の真の陰性率 (特異度とも呼ばれる) です。**
+ TNRd = TNd/(TNd \$1 FPd) は、ファセット d の真の陰性率 (特異度とも呼ばれる) です。**
例えば、ファセット a と d について、次の混同行列を考えてみます。****
有利なファセット `a` の混同行列
| クラス a の予測 | 実際の結果 0 | 実際の結果 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
不利なファセット `d` の混同行列
| クラス d の予測 | 実際の結果 0 | 実際の結果 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
特異度差の値は `SD = 18/(18+5) - 20/(20+10) = 0.7826 - 0.6667 = 0.1159` で、これはファセット d に対するバイアスを示しています。**
二項分類とマルチカテゴリ分類のファセット a と d 間の特異度の差の値の範囲は、`[-1, +1]` です。****このメトリクスは、連続ラベルの場合には使用できません。SD のさまざまな値が意味するものは次のとおりです。
+ 正の値は、ファセット a よりもファセット d の方が、特異度が高い場合に得られます。****このことから、モデルではファセット d の偽陽性がファセット a よりも少ないことが示唆されます。****正の値はファセット d に対するバイアスを示します。**
+ ゼロに近い値は、比較されるファセットの特異度が類似していることを示します。これは、モデルが両方のファセットでほぼ同数の偽陽性を検出し、バイアスがないことを示唆しています。
+ 負の値は、ファセット d よりもファセット a の方が、特異度が高い場合に得られます。****このことから、モデルではファセット a の偽陽性がファセット d よりも多いことが示唆されます。****負の値はファセット a に対するバイアスを示します。**
# リコール差 (RD)
リコール差 (RD) メトリクスは、有利なファセット a と不利なファセット d 間のモデルのリコールの差です。****これらのリコールの差は、バイアスの潜在的な形です。リコールは真陽性率 (TPR) で、モデルが正の結果を受け取る場合を正しく予測する頻度を測定します。リコールは、すべての y=1 のケースがそのファセットの y'=1 として正しく予測されている場合に、ファセットに最適です。モデルがタイプ II エラーと呼ばれる偽陰性を最小化すると、リコールが大きくなります。例えば、ローンの対象となるべき 2 つの異なるグループ (ファセット a と d) に属する人のうち、何人がモデルによって正しく検出されましたか。****ファセット a への融資ではリコール率が高いが、ファセット d への融資ではリコール率が低い場合、その差はファセット d に属するグループに対するこのバイアスの測定値を提供します。******
ファセット a および d のリコール率の差の計算式は次のとおりです。****
RD = TPa/(TPa \$1 FNa) - TPd/(TPd \$1 FNd) = TPRa - TPRd
コードの説明は以下のとおりです。
+ TPa は、ファセット a に対して予測される真陽性です。**
+ FNa は、ファセット a に対して予測される偽陰性です。**
+ TPd は、ファセット d に対して予測される真陽性です。**
+ FNd は、ファセット d に対して予測される偽陰性です。**
+ TPRa = TPa/(TPa \$1 FNa) は、ファセット a のリコールまたはその真陽性率です。**
+ TPRd TPd/(TPd \$1 FNd) は、ファセット d のリコールまたはその真陽性率です。**
例えば、ファセット a と d について、次の混同行列を考えてみます。****
有利なファセット a の混同行列
| クラス a の予測 | 実際の結果 0 | 実際の結果 1 | Total |
| --- | --- | --- | --- |
| 0 | 20 | 5 | 25 |
| 1 | 10 | 65 | 75 |
| Total | 30 | 70 | 100 |
不利なファセット d の混同行列
| クラス d の予測 | 実際の結果 0 | 実際の結果 1 | Total |
| --- | --- | --- | --- |
| 0 | 18 | 7 | 25 |
| 1 | 5 | 20 | 25 |
| Total | 23 | 27 | 50 |
リコール差の値は、RD = 65/70 - 20/27 = 0.93 - 0.74 = 0.19 で、ファセット *d* に対するバイアスを示します。
二項分類とマルチカテゴリ分類のファセット a と d 間のリコール差の値の範囲は、[-1, \$11] です。****このメトリクスは、連続ラベルの場合には使用できません。
+ 正の値は、ファセット d よりもファセット a の方が、リコールが高い場合に得られます。****これは、モデルが、バイアスの形式であるファセット d よりもファセット a の真陽性をより多く検出することを示しています。****
+ ゼロに近い値は、比較されるファセットのリコールが類似していることを示します。これは、モデルがこれらのファセットの両方でほぼ同じ数の真陽性を検出し、バイアスがないことを示しています。
+ 負の値は、ファセット a よりもファセット d の方が、リコールが高い場合に得られます。****これは、モデルが、バイアスの形式であるファセット a よりもファセット d の真陽性をより多く検出することを示しています。****
# 承認率の差 (DAR)
承認率の差 (DAR) メトリクスは、ファセット a および d の観測された陽性 (TP \$1 FP) に対する真陽性 (TP) 予測の比率の差です。****このメトリクスは、これらの 2 つのファセットからの承認を予測するためのモデルの精度の差を測定します。精度は、対象となる候補のプールから、モデルによってそのように識別された対象となる候補の割合を測定します。対象となる申請者を予測するためのモデルの精度がファセット間で異なる場合、これはバイアスであり、その大きさは DAR によって測定されます。
ファセット a および d の承認率の差の計算式は次のとおりです。****
DAR = TPa/(TPa \$1 FPa) - TPd/(TPd \$1 FPd)
コードの説明は以下のとおりです。
+ TPa は、ファセット a に対して予測される真陽性です。**
+ FPa は、ファセット a に対して予測される偽陽性です。**
+ TPd は、ファセット d に対して予測される真陽性です。**
+ FPd は、ファセット d に対して予測される偽陽性です。**
例えば、モデルが 70 人の中高年層の申請者 (ファセット a) のローンを承認し (正の予測ラベル)、そのうち 35 人だけが実際に承認されたとします (正の観測ラベル)。**また、モデルが他の年齢層 (ファセット d) から 100 人の申請者のローンを承認し (正の予測ラベル)、そのうち 40 人だけが実際に承認されたとします (正の観測ラベル)。**そうすると、DAR = 35/70 - 40/100 = 0.10 となり、これは、2 番目の年齢層 (ファセット d) からの対象となる人たちに対する潜在的なバイアスを示しています。**
バイナリ、マルチカテゴリファセット、連続ラベルの DAR の値の範囲は、[-1, \$11] です。
+ 正の値は、ファセット a の予測された正の結果 (承認) と観測された正の結果 (対象となる申請者) の比率が、ファセット d の同様の比率よりも大きい場合に発生します。****これらの値は、ファセット d で比較的多くの偽陽性が発生することによって引き起こされる不利なファセット d に対するバイアスの可能性を示します。****比率の差が大きいほど、見かけ上のバイアスは大きくなります。
+ ゼロに近い値は、ファセット a と d の予測された正の結果 (承認) と観測された正の結果 (対象となる申請者) の比率が類似した値を持ち、正の結果の観察ラベルがモデルによって同じ精度で予測されていることを示す場合に発生します。****
+ 負の値は、ファセット d の予測された正の結果 (承認) と観測された正の結果 (対象となる申請者) の比率が、ファセット a の比率よりも大きい場合に発生します。****これらの値は、ファセット a で比較的多くの偽陽性が発生することによって引き起こされる有利なファセット a に対するバイアスの可能性を示します。****比率の差が負であるほど、見かけ上のバイアスは大きくなります。
# 拒否率の差 (DRR)
拒否率の差 (DRR) メトリクスは、ファセット a と d の観測された負の結果 (TN \$1 FN) に対する真陰性 (TN) 予測の比率の差です。****このメトリクスは、これらの 2 つのファセットからの拒否を予測するためのモデルの精度の差を測定します。精度は、対象外のプールから、モデルによってそのように識別された対象外の候補の割合を測定します。対象外の申請者を予測するためのモデルの精度がファセット間で異なる場合、これはバイアスであり、その大きさは DRR によって測定されます。
ファセット a および d の拒否率の差の計算式は次のとおりです。****
DRR = TNd/(TNd \$1 FNd) - TNa/(TNa \$1 FNa)
前述の DRR 方程式の構成要素は次のとおりです。
+ TNd は、ファセット d に対して予測される真陰性です。**
+ FNd は、ファセット d に対して予測される偽陰性です。**
+ TPa は、ファセット a に対して予測される真陰性です。**
+ FNa は、ファセット a に対して予測される偽陰性です。**
例えば、モデルが 100 人の中高年のローンの申請者 (ファセット a) を拒否し (負の予測ラベル)、そのうち 80 人は実際に対象外だとします (負の観察ラベル)。**また、モデルが他の年齢層 (ファセット d) から 50 人のローンの申請者を拒否し (負の予測ラベル)、そのうち 40 人だけが実際に対象外だとします (負の観測ラベル)。**そうすると、DRR = 40/50 - 80/100 = 0 となり、バイアスがないことがわかります。
バイナリ、マルチカテゴリファセット、連続ラベルの DRR の値の範囲は、[-1, \$11] です。
+ 正の値は、ファセット d の予測された負の結果 (拒否) と観測された負の結果 (資格のない申請者) の比率が、ファセット a の同様の比率よりも大きい場合に発生します。****これらの値は、ファセット a で比較的多くの偽陰性が発生することによって引き起こされる有利なファセット a に対するバイアスの可能性を示します。****比率の差が大きいほど、見かけ上のバイアスは大きくなります。
+ ゼロに近い値は、ファセット a と d の予測された負の結果 (拒否) と観測された負の結果 (対象となる申請者) の比率が類似した値を持ち、負の結果の観察ラベルがモデルによって同じ精度で予測されていることを示す場合に発生します。****
+ 負の値は、ファセット a の予測された負の結果 (拒否) と観測された負の結果 (対象となる申請者) の比率が、ファセット d の比率よりも大きい場合に発生します。****これらの値は、ファセット d で比較的多くの偽陽性が発生することによって引き起こされる不利なファセット d に対するバイアスの可能性を示します。****比率の差が負であるほど、見かけ上のバイアスは大きくなります。
# 精度差 (AD)
精度差 (AD) メトリクスは、異なるファセットの予測精度の差です。このメトリクスは、モデルによる分類が、あるファセットに対して他のファセットよりも正確であるかどうかを決定します。AD は、1 つのファセットでタイプ I とタイプ II のエラーの割合が大きいかどうかを示します。ただし、タイプ I とタイプ II のエラーを区別することはできません。例えば、モデルの精度は年齢層が異なっても同じになりますが、エラーは、ある年齢ベースのグループでは大部分が偽陽性 (タイプ I エラー)で 、他の年齢層では大部分が偽陰性 (タイプ II エラー) である可能性があります。
また、中高年層 (ファセット a) に対して、別の年齢層 (ファセット d) よりもはるかに高い精度でローンの承認が行われる場合、2 番目の年齢層の対象となる申請者の割合が大きい方がローンを拒否される (FN) か、そのグループの対象外の申請者の割合が大きい方がローンを受ける (FP) か、またはその両方になります。****このため、両方の年齢ベースのグループで承認されたローンの割合がほぼ同じであっても、2 番目のグループでグループの不公平につながる可能性があります。これはゼロに近い DPPL 値で示されます。
AD メトリクスの計算式は、ファセット a の予測精度 ACCa から、ファセット d の予測精度 ACCd を引いた差です。****
AD = ACCa - ACCd
コードの説明は以下のとおりです。
+ ACCa = (TPa \$1 TNa)/(TPa \$1 TNa \$1 FPa \$1 FNa)
+ TPa は、ファセット a に対して予測される真陽性です**
+ TNa は、ファセット a に対して予測される真陰性です**
+ FPa は、ファセット a に対して予測される偽陽性です**
+ FNa は、ファセット a に対して予測される偽陰性です**
+ ACCd = (TPd \$1 TNd)/(TPd \$1 TNd \$1 FPd \$1 FNd)
+ TPd は、ファセット d に対して予測される真陽性です**
+ TNd は、ファセット d に対して予測される真陰性です**
+ FPd は、ファセット d に対して予測される偽陽性です**
+ FNd は、ファセット d に対して予測される偽陰性です**
例えば、あるモデルが 100 人のファセット a から 70 人の申請者のローンを承認し、残りの 30 人を拒否したとします。10 人はローンを提供されるべきではなく (FPa)、承認されるべき 60 人は承認されました (TPa)。拒否のうち 20 人は承認されるべきであり (FNa)、10 人は正しく拒否されました (TNa)。**ファセット a の精度は次のとおりです。**
ACCa = (60 \$1 10)/(60 \$1 10 \$1 20 \$1 10) = 0.7
次に、あるモデルが 100 人のファセット d から 50 人の申請者のローンを承認し、残りの 50 人を拒否したとします。10 人はローンを提供されるべきではなく (FPa)、承認されるべき 40 人が承認されました (TPa)。承認されるべき 40 人が拒否され (FNa)、10 人は正しく拒否されました (TNa)。**ファセット a の精度は次のように決定されます。**
ACCd= (40 \$1 10)/(40 \$1 10 \$1 40 \$1 10) = 0.5
したがって、精度の差は、AD = ACCa - ACCd = 0.7 - 0.5 = 0.2 となります。これは、メトリクスが正の値であるため、ファセット d に対してバイアスがあることを示します。**
バイナリおよびマルチカテゴリファセットラベルの AD の値の範囲は、[-1, \$11] です。
+ 正の値は、ファセット a の予測精度がファセット d の予測精度より大きい場合に発生します。****これは、ファセット d が、偽陽性 (タイプ I エラー) または偽陰性 (タイプ II エラー) の組み合わせで、より大きな問題を受けることを示します。**これは、不利なファセット d に対して潜在的なバイアスがあることを意味します。**
+ ゼロに近い値は、ファセット a の予測精度がファセット d の予測精度と類似している場合に発生します。****
+ 負の値は、ファセット d の予測精度がファセット a の予測精度より大きい場合に発生します。****これは、ファセット a が、偽陽性 (タイプ I エラー) または偽陰性 (タイプ II エラー) の組み合わせでより大きな問題を受けることを示します。**これは、有利なファセット a に対してバイアスがあることを意味します。**
# 処理の同等性 (TE)
処理の同等性 (TE) は、ファセット a と d 間の偽陰性と偽陽性の比率の差です。****このメトリクスの主な考え方は、グループ全体の精度が同じであっても、あるグループに対するエラーが、他のグループよりも、より有害であるかどうかを評価することです。エラー率は偽陽性と偽陰性の合計から得られますが、これら 2 つの内訳はファセット間で大きく異なる可能性があります。TE は、エラーがファセット全体で類似または異なる方法で補正されているかどうかを測定します。
処理の同等性の計算式は次のとおりです。
TE = FNd/FPd - FNa/FPa
コードの説明は以下のとおりです。
+ FNd は、ファセット d に対して予測される偽陰性です。**
+ FPd は、ファセット d に対して予測される偽陽性です。**
+ FNa は、ファセット a に対して予測される偽陰性です。**
+ FPa は、ファセット a に対して予測される偽陽性です。**
FPa または FPd がゼロの場合、メトリクスは無制限になることに注意してください。
例えば、ファセット a から 100 人、ファセット d から 50 人のローン申請者がいるとします。****ファセット a の場合、8 人が誤ってローンを拒否され (FNa)、別の 6 人が誤って承認されました (FPa)。**残りの予測は正しかったので、TPa \$1 TNa = 86 になります。ファセット d の場合、5 人が誤って拒否され (FNd)、2 人が誤って承認されました (FPd)。**残りの予測は正しかったので、TPd \$1 TNd = 43 になります。偽陰性と偽陽性の比率は、ファセット a では 8/6 = 1.33、ファセット d では 5/2 = 2.5 になります。****したがって、両方のファセットの精度が同じであっても、TE = 2.5 - 1.33 = 1.167 になります。
ACCa = (86)/(86\$1 8 \$1 6) = 0.86
ACCd = (43)/(43 \$1 5 \$1 2) = 0.86
バイナリおよびマルチカテゴリファセットラベルの条件付き拒否の差の値の範囲は、(-∞, \$1∞) です。TE メトリクスは、連続ラベルには定義されていません。このメトリクスの解釈は、偽陽性 (タイプ I エラー) と偽陰性 (タイプ II エラー) の相対的な重要性により異なります。
+ 正の値は、ファセット d の偽陰性と偽陽性の比率がファセット a より大きい場合に発生します。****
+ ゼロに近い値は、ファセット a の偽陰性と偽陽性の比率がファセット d と似ている場合に発生します。****
+ 負の値は、ファセット d の偽陰性と偽陽性の比率がファセット a より小さい場合に発生します。****
**注記**
以前のバージョンでは、取り扱いの平等性は FNd / FPd - FNa / FPa ではなく FPa / FNa - FPd / FNd として計算されると記載されていました。ただし、どちらのバージョンも使用できます。詳細については、「[https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf](https://pages.awscloud.com/rs/112-TZM-766/images/Fairness.Measures.for.Machine.Learning.in.Finance.pdf)」を参照してください。
# 予測ラベルの条件付き属性格差 (CDDPL)
属性格差メトリクス (DDPL) は、ファセット d が、予測された拒否ラベルの割合が予測された承認ラベルの割合よりも大きいかどうかを決定します。**これにより、ファセット全体で予測される拒否率と承認率の差を比較できます。このメトリクスは、観測ラベルではなく予測ラベルから計算される点を除いて、トレーニング前の CDD メトリクスとまったく同じです。このメトリクスは、(-1,\$11) の範囲にあります。
ファセット d のラベルに対する属性格差予測の計算式は次のとおりです。**
DDPLd = n'd(0)/n'(0) - n'd(1)/n'(1) = PdR(y'0) - PdA(y'1)
コードの説明は以下のとおりです。
+ n'(0) = n'a(0) \$1 n'd(0) は、ファセット a と d の予測された拒否ラベルの数です。****
+ n'(1) = n'a(1) \$1 n'd(1) は、ファセット a と d の予測された承認ラベルの数です。****
+ PdR(y'0) は、ファセット d の予測された拒否ラベル (値 0) の割合です。**
+ PdA(y'1) は、ファセット d の予測された承認ラベル (値 1) の割合です。**
シンプソンのパラドックスを除外するには、データセット上のサブグループの層を定義する属性に対して DDPL を条件付ける予測ラベルの条件付き属性格差 (CDDPL) メトリクスが必要です。再グループ化により、有利でないファセットの明らかな属性格差の原因についてインサイトを得ることができます。典型的な例は、バークレー校の入試で、男性の方が女性よりも全体的に合格率が高かったというものです。しかし、学科別のサブグループを調べると、学科別では女性の方が男性よりも高い合格率であることが示されました。その説明は、女性は男性よりも合格率の低い学科に志願していたということでした。サブグループ別の合格率を調べると、合格率の低い学科では、実際に女性の方が男性よりも高い合格率であることがわかりました。
CDDPL メトリクスは、データセットの属性によって定義されたサブグループに見られる格差をすべて平均化することで、1 つの測定値を提供します。これは、各サブグループの予測ラベル (DDPLi) における属性格差の加重平均として定義され、各サブグループの格差は、含まれる観測値の数に比例して加重されます。予測ラベルの条件付き属性格差の計算式は次のとおりです。
CDDPL = (1/n)\$1∑ini \$1DDPLi
コードの説明は以下のとおりです。
+ ∑ini = n は、観測値の総数であり、niは、各サブグループの観測値の数です。
+ DDPLi = n'i(0)/n(0) - n'i(1)/n(1) = PiR(y'0) - PiA(y'1) は、サブグループの予測ラベルにおける属性格差です。
したがって、予測ラベルにおけるサブグループの属性格差 (DDPLi) は、各サブグループの予測された拒否ラベルの割合と承認ラベルの割合の差です。
バイナリ、マルチカテゴリ、連続結果の DDPL 値の範囲は、[-1,\$11] です。
+ \$11: ファセット a またはサブグループに対して予測された拒否ラベルがなく、ファセット d またはサブグループに対して予測された承認がない場合。****
+ 正の値は、ファセット d またはサブグループが、予測された拒否ラベルの割合が予測された承認ラベルの割合よりも大きいため、予測ラベルに属性格差があることを示します。**値が大きいほど、格差が大きくなります。
+ ゼロに近い値は、平均して属性格差がないことを示します。
+ 負の値は、ファセット d またはサブグループが、予測された拒否ラベルの割合が予測された承認ラベルの割合よりも大きいため、予測ラベルに属性格差があることを示します。**値が小さいほど、格差が大きくなります。
+ -1: ファセット d またはサブグループに対して予測された拒否ラベルがなく、ファセット a またはサブグループに対して予測された承認がない場合。****
# 反事実フリップテスト (FT)
フリップテストは、ファセット d の各メンバーを調べ、ファセット a の類似したメンバーが異なるモデル予測を持っているかどうかを評価するアプローチです。****ファセット a のメンバーは、ファセット d からの観測の k 最近傍になるよう選択されます。****反対のグループの最近傍が異なる予測を受ける数を評価します。反転した予測は正から負に、またはその逆になることがあります。
反事実フリップテストの計算式は、2 つのセットの基数の差をファセット d のメンバー数で割ったものです。**
FT = (F\$1 - F-)/nd
コードの説明は以下のとおりです。
+ F\$1 = は、不利な結果を得た不利なファセット d メンバーのうち、有利なファセット a の最近傍が有利な結果を受け取った数でず。****
+ F- = は、有利な結果を得た不利なファセット d メンバーのうち、有利なファセット a の最近傍が不利な結果を受け取った数でず。****
+ nd は、ファセット d のサンプルサイズです。**
バイナリおよびマルチカテゴリファセットラベルの反事実フリップテストの値の範囲は、[-1, \$11] です。連続ラベルの場合、ラベルをバイナリに折りたたむためのしきい値を設定します。
+ 正の値は、不利なファセット d の不利な反事実フリップテスト決定数が有利な反事実フリップテスト決定数を上回る場合に発生します。**
+ ゼロに近い値は、不利な反事実フリップテスト決定数と有利な反事実フリップテスト決定数のバランスがとれるときに発生します。
+ 負の値は、不利なファセット d の不利な反事実フリップテスト決定数が有利な反事実フリップテスト決定数を下回る場合に発生します。**
# 一般化エントロピー (GE)
一般化エントロピー指数 (GE) は、予測ラベルと観測ラベルの利益 `b` の差を測定します。偽陽性が予測されると利益が生じます。偽陽性は、陰性の観測 (y=0) に陽性の予測 (y'=1) がある場合に発生します。また、観測ラベルと予測ラベルが同じ場合、つまり真陽性と真陰性とも呼ばれる場合にも利益が生じます。偽陰性が予測された場合には利益は生じません。偽陰性は、陽性の観測 (y=1) が陰性の結果 (y'=0) になると予測される場合に発生します。利益 `b` は次のように定義されます。
```
b = y' - y + 1
```
この定義を使用すると、偽陽性は `2` の利益 `b` を受け、偽陰性は `0` の利益を受けます。真陽性と真陰性はどちらも `1` の利益を受けます。
GE メトリクスは、重み `alpha` を `2` に設定した[一般化エントロピー指数](https://en.wikipedia.org/wiki/Generalized_entropy_index) (GE) に従って計算されます。この重みによって、さまざまな利益値に対する感度が決まります。`alpha` が小さいほど、小さい値に対する感度が高くなります。
![\[アルファパラメータを 2 に設定した一般化エントロピー指数を定義する方程式。\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify-post-training-bias-metric-ge.png)
GE の計算に使用される以下の変数は、次のように定義されます。
+ bi は `ith` データポイントが受ける利益です。
+ b' はすべての利益の平均です。
GE の範囲は 0～0.5 で、値がゼロの場合はすべてのデータポイントで利益に不平等がないことを示します。これは、すべての入力が正しく予測された場合か、すべての予測が偽陽性の場合に発生します。すべての予測が偽陰性の場合、GE は未定義です。
**注記**
GE というメトリクスは、ファセット値が有利か不利かには依存しません。
# モデルの説明可能性
Amazon SageMaker Clarify には、機械学習 (ML) モデルが予測を行う方法を説明するのに役立つツールが用意されています。これらのツールは、ML モデラー、デベロッパー、その他の内部ステークホルダーが、デプロイ前にモデル特性を全体として理解したり、デプロイ後にモデルが提供する予測をデバッグしたりするのに役立ちます。
+ データセットとモデルの説明を取得するには、「[SageMaker Clarify を使用した公平性、モデルの説明可能性、バイアス検出](clarify-configure-processing-jobs.md)」を参照してください。
+ SageMaker AI エンドポイントからリアルタイムで説明を取得する方法については、「[SageMaker Clarify によるオンライン説明可能性](clarify-online-explainability.md)」を参照してください。
ML モデルがどのように予測に到達するかについての透明性も、消費者や規制当局にとって重要です。モデル予測に基づいて決定を受け入れる場合は、モデルの予測を信頼する必要があります。SageMaker Clarify は、モデルにとらわれない特徴量帰属アプローチを採用しています。これを使用して、モデルがトレーニング後に予測を行った理由を理解し、推論中にインスタンスごとの説明を提供できます。この実装には、[SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) のスケーラブルで効率的な実装が含まれます。これは、協調ゲーム理論の分野における Shapley 値という概念に基づいており、特定の予測で各特徴量に重要度を割り当てます。
Clarify は、特徴量が機械学習モデルの予測結果に与えるわずかな影響を示す部分依存プロット (PDP) を作成します。部分依存は、一連の入力特徴量が与えられた場合にターゲットレスポンスを説明するのに役立ちます。表形式のデータの説明に使用されるのと同じ Shapley 値 (SHAP) アルゴリズムを使用して、コンピュータビジョン (CV) と自然言語処理 (NLP) の両方の説明可能性もサポートされています。
機械学習のコンテキストにおける説明の特徴とは何でしょうか。説明とは、人間が予測の原因を理解するのに役立つ「*なぜ*」という質問に対する答えであると考えることができます。ML モデルのコンテキストでは、次のような質問に答えることに興味があるかれません。
+ モデルが特定の申請者のローン拒否などの否定的な結果を予測したのはなぜですか。
+ モデルはどのように予測するのですか。
+ モデルが誤った予測を行ったのはなぜですか。
+ モデルの動作に最大の影響を与える特徴量はどれですか。
説明を使用して、規制要件の監査と適合、モデルの信頼の構築と人間の意思決定のサポート、モデルのパフォーマンスのデバッグと改善を行うことができます。
ML 推論の性質と結果に関する人間の理解の要求を満たすニーズが、必要な説明の種類の鍵となります。哲学や認知科学の分野の研究によると、人は特に対照的な説明、つまり、ある事象 X が、起こらなかった他の事象 Y の代わりになぜ起こったのか、という説明に関心を持つことがわかっています。ここでX は、発生した予期せぬまたは驚くべき事象であり、Y はベースラインと呼ばれる既存のメンタルモデルに基づく期待に対応します。**同じ事象 Xでも、人の視点やメンタルモデル Y によって、求める説明が異なる場合があることに注意してください。説明可能な AI のコンテキストでは、X は説明される例であり、Y はデータセット内の情報の少ない例や平均的な例を表すために通常選択されるベースラインだと考えることができます。たとえば、画像の ML モデリングの場合、ベースラインが暗黙的に表示されることがあります。この場合、ピクセルがすべて同じ色の画像がベースラインとして機能することがあります。
## サンプルノートブック
Amazon SageMaker Clarify は、モデルの説明可能性について次のサンプルノートブックを提供しています。
+ [Amazon SageMaker Clarify 処理](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-clarify/index.html#sagemaker-clarify-processing) — SageMaker Clarify を使用して、バイアスを検出し、特徴量属性を使用してモデル予測を説明するための処理ジョブを作成します。例えば、CSV と JSON Lines のデータ形式の使用、独自のコンテナの持ち込み、Spark での処理ジョブの実行などがあります。
+ [SageMaker Clarify による画像分類の説明](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb) — SageMaker Clarify を使用すると、コンピュータビジョンモデルが画像を分類する方法についてのインサイトが得られます。
+ [SageMaker Clarify によるオブジェクト検出モデルの説明](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/computer_vision/object_detection/object_detection_clarify.ipynb) — SageMaker Clarify を使用すると、コンピュータビジョンモデルがオブジェクトを検出する方法についてのインサイトが得られます。
このノートブックの動作確認が実施されているのは、Amazon SageMaker Studio のみです。Amazon SageMaker Studio でノートブックを開く方法の手順については、「[Amazon SageMaker Studio Classic ノートブックを作成する、または開く](notebooks-create-open.md)」を参照してください。カーネルの選択を求めるメッセージが表示されたら、**[Python 3 (Data Science)]** (Python 3 (データサイエンス)) を選択します。
**Topics**
+ [サンプルノートブック](#clarify-model-explainability-sample-notebooks)
+ [Shapley 値を使用する特徴属性](clarify-shapley-values.md)
+ [非対称 Shapley 値](clarify-feature-attribute-shap-asymm.md)
+ [説明可能性のための SHAP ベースライン](clarify-feature-attribute-shap-baselines.md)
# Shapley 値を使用する特徴属性
SageMaker Clarify は、[Shapley 値](https://en.wikipedia.org/wiki/Shapley_value)の概念に基づいて特徴属性を提供します。Shapley 値を使って、各特徴がモデル予測に与える寄与度を判断できます。これらの属性は、特定の予測に対して提供することも、モデル全体に対してグローバルレベルで提供することもできます。例えば、大学入試に ML モデルを使用した場合、説明を使用し、GPA と SAT スコアのどちらがモデルの予測に最も貢献した特徴かを判断し、特定の学生に関する合否判定を決定するために各特徴がどの程度貢献したかを判断できます。
SageMaker Clarify は、ゲーム理論から Shapley 値の概念を取り入れ、機械学習のコンテキストにデプロイしました。Shapley 値は、ゲームに対する各プレイヤーの貢献度を定量化する方法であり、これにより、ゲームによって得られる総利益をプレイヤーの貢献度に応じて分配する手段を提供します。この機械学習のコンテキストでは、SageMaker Clarify は、特定のインスタンスに対するモデルの予測を*ゲーム*として扱い、モデルに含まれる特徴を*プレイヤー*として扱います。最初の近似値では、モデルからその特徴を*削除*した場合と、モデルから他の特徴をすべて*削除*した場合の結果を定量化することで、各特徴のわずかな貢献度や効果を判断したくなる場合があります。ただし、このアプローチでは、モデルに含まれる特徴が互いに独立していない場合が多いことを考慮していません。例えば、2 つの特徴が高度に相関している場合、いずれかの特徴を削除してもモデルの予測が大きく変化しない可能性があります。
これらの潜在的な依存関係に対処するために、Shapley 値では、各特徴の重要性を判断するために、特徴の可能な各組み合わせ (または連結) の結果を考慮する必要があります。*d* 個の特徴がある場合、このような特徴の組み合わせは 2d とおりあり、それぞれが潜在的なモデルに対応します。特定の特徴 *f* の属性を決定するには、*f* を含まないすべての特徴の組み合わせ (および関連モデル) に *f* を含めた場合のわずかな貢献度を考慮し、その平均をとります。Shapley 値は、特定の望ましい特性を満たす各特徴の貢献度や重要度を割り当てる唯一の方法であることが示すことができます。特に、各特徴の Shapley 値の合計は、そのモデルと特徴を持たないダミーモデルの予測の差に対応します。ただし、妥当な値の *d*、例えば 50 個の特徴であっても、2d の可能なモデルをトレーニングすることは計算上禁止されており、現実的ではありません。そのため、SageMaker Clarify はさまざまな近似手法を利用する必要があります。この目的のために、SageMaker Clarify は SHapley Additive exPlanations (SHAP) を使用します。SHAP はこのような近似を取り入れ、追加の最適化によってカーネル SHAP アルゴリズムのスケーラブルで効率的な実装を考案します。
Shapley 値の詳細については、「[モデル予測を解釈するための統一アプローチ](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf)」を参照してください。
# 非対称 Shapley 値
SageMaker Clarify 時系列予測モデルの説明ソリューションは、[協調ゲーム理論](https://en.wikipedia.org/wiki/Cooperative_game_theory)を基盤とした Feature Attribution メソッドであり、SHAP の概念と類似しています。具体的には、Clarify は[ランダムな順序のグループ値](http://www.library.fa.ru/files/Roth2.pdf#page=121)を使用します。これは、機械学習と説明可能性では[非対称 Shapley 値](https://proceedings.neurips.cc/paper/2020/file/0d770c496aa3da6d2c3f2bd19e7b9d6b-Paper.pdf)とも呼ばれます。
## 背景
特定の予測モデル *f* への入力特徴量の貢献度を計算することが目的です。予測モデルでは、次の入力を受け入れます。
+ 過去の時系列 *(ターゲット TS)*。これは例えば、パリからベルリン間のルートの過去の毎日の列車乗客数であり、*xt* で表されます。
+ (オプション) 共変量時系列。これは例えば、祝い事や天気のデータで、*zt* ∈ RS で表されます。共変量 TS を使用する場合、過去の時間ステップのみに使用できる場合もあれば、(祝い事のカレンダーに含まれる) 将来の時間ステップに使用できる場合もあります。
+ (オプション) 静的共変量。例えば、サービス品質 (1 級や 2 級など) は、*u* ∈ RE で示されます。
静的共変量、動的共変量、またはその両方は、特定の応用シナリオに応じて省略できます。予測期間 K ≥ 0 (例: K=30 日間) の場合、モデル予測は *f(x[1:T], z[1:T\$1K], u) = x[T\$11:T \$1K\$11]* 式として特徴を表すことができます。
次の図は、一般的な予測モデルの依存関係構造を説明しています。*t\$11* 時点での予測は、上記の 3 つのタイプの入力によって異なります。
![\[一般的な予測モデルの依存関係の構造\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/clarify/clarify-forecast-dependency.png)
## 方法
説明は、元の入力によって導出された一連のポイントで時系列モデル *f* をクエリすることで計算されます。ゲーム理論の構成に従って、Clarify は入力の一部を難読化 (つまり、ベースライン値に設定) することで導かれる予測の差を反復的に平均化します。時間構造は、時系列順、反時系列順、またはその両方でナビゲートできます。時系列の説明は、最初の時間ステップから情報を反復的に追加することによって構築され、逆時系列の説明は最後のステップからの情報を追加します。株価の予測など、最新性バイアスが存在する場合は、後者のモードを使用する方が適切である可能性があります。計算された説明の重要な特性の 1 つに、モデルが確定的な出力を提供する場合、説明が元のモデル出力に合計されることがあります。
## 結果の貢献度
結果の属性は、各予測時間ステップでの最終予測に対する特定の時間ステップまたは入力特徴量の貢献を示すスコアです。Clarify では、説明で次の 2 つの粒度を提供します。
+ 時間単位の説明は低コストであり、特定の時間ステップに関する情報のみを提供します。例えば、過去の 19 日目の情報が将来の 1 日目の予測にどの程度貢献したかなど、特定の時間ステップに関する情報のみを提供します。このような貢献度は、静的共変量を個別には説明することなく、ターゲットおよび共変量の時系列の説明を集約したりすることはありません。貢献度は、マトリクス *A* であり、各 *Atk* は時間ステップ*t* の *T\$1k* の予測に対する貢献度です。モデルが将来の共変量を受け入れる場合、*t* は *T* より大きくなる場合があることに注意が必要です。
+ きめ細かな説明は計算集約的である一方、入力変数のすべての貢献度の完全な詳細を提供します
**注記**
きめ細かな説明がサポートするのは、時系列のみです。
結果として得られる貢献度は、以下で構成される三重項です。
+ 入力時系列に関連するマトリクス *Ax* ∈ RT×K。*Atkx* は、予測ステップ *T\$1k* に対する *xt* の貢献度
+ 共変量時系列に関連するテンソル *Az* ∈ *RT\$1K×S×K*。*Atskz* は予測ステップ *T\$1k* に対する*zts* (つまり s 番目の共変量 TS) の貢献度
+ 静的共変量に関連するマトリクス *Au* ∈ RE×K。*Aeku* は、予測ステップ *T\$1k* に対する *ue* (e 番目の静的共変量) の貢献度
説明には粒度を問わず、すべてのデータが難読化された場合のモデルの「基本動作」を表すオフセットベクトル *B* *∈ RK* も含まれています。
# 説明可能性のための SHAP ベースライン
説明とは一般的に対比的なものです (つまり、この場合はベースラインからの逸脱について説明します)。その結果、同じモデルの予測でも、ベースラインが異なれば異なる説明が得られることが期待できます。したがって、ベースラインの選択は非常に重要です。ML コンテキストでは、ベースラインは情報が*少ない*か情報が*多い*かのどちらかの仮想的なインスタンスに対応します。Shapley 値の計算中に、SageMaker Clarify はベースラインと特定のインスタンスの間に複数の新しいインスタンスを生成します。このインスタンスでは、特徴量がない場合は特徴量値をベースラインの値に設定することでモデル化し、特徴量がある場合は特徴量値を特定のインスタンスの値に設定することでモデル化します。したがって、すべての特徴がない場合はベースラインに対応し、すべての特徴がある場合は特定のインスタンスに対応します。
適切なベースラインはどのように選択すればよいでしょうか。多くの場合、情報コンテンツが非常に少ないベースラインを選択することが望ましいです。例えば、数値特徴では、中央値または平均値、カテゴリ特徴では、モードをとることで、トレーニングデータセットから平均的なインスタンスを構築できます。大学入試の例では、平均的な志願者に基づくベースラインの合格率と比較して、特定の志願者が合格した理由を説明することに興味があるかれません。指定しない場合、ベースラインは、入力データセットの K-means または K-prototypes を使用して SageMaker Clarify によって自動的に計算されます。
または、情報の多いベースラインに関する説明の生成を選択することもできます。大学入試のシナリオでは、特定の志願者が不合格になった理由を、類似の属性背景を持つ他の志願者と比較して説明したい場合があります。この場合、関心のある志願者、つまり類似の属性背景を持つ志願者を表すベースラインを選択できます。このように、情報の多いベースラインを使用することで、特定のモデル予測の特定の側面に分析を集中させることができます。操作できない人口統計の属性や他の特徴を、特定のインスタンスと同じ値に設定することで、評価の特徴を分離できます。
# SageMaker Clarify を使用した SageMaker AI Autopilot の説明可能性
Autopilot では、Amazon SageMaker Clarify が提供するツールを使用して、機械学習 (ML) モデルが予測を行う方法についてのインサイトを提供することができます。これらのツールは、ML エンジニア、プロダクトマネージャーなどの社内利害関係者がモデルの特性を理解するのに役立ちます。モデル予測に基づく決定を信頼して解釈するうえで、消費者や規制当局はともに機械学習の透明性を求めています。
Autopilot の説明機能は、モデルに依存しない特徴量帰属アプローチを使用します。このアプローチは、モデルの出力に対する個々の特徴量や入力の寄与度を判断し、さまざまな特徴量の関連性についてのインサイトを提供します。これを使用して、モデルがトレーニング後に予測を行った理由を理解したり、推論中にインスタンスごとの説明を提供したりできます。実装には、[SHAP](https://papers.nips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) (Shapley Additive Explanations) のスケーラブルな実装などがあります。この実装は、協力ゲーム理論の Shapley 値の概念に基づいており、各特徴量に特定の予測の重要度値を割り当てます。
SHAP の説明は、監査と規制要件の遵守、モデルへの信頼の構築、人間による意思決定のサポート、モデルのパフォーマンスのデバッグと改善に使用できます。
Shapley 値とベースラインの詳細については、「[説明可能性のための SHAP ベースライン](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-feature-attribute-shap-baselines.html)」を参照してください。
Amazon SageMaker Clarify ドキュメンテーションのガイドについては、「[Guide to the SageMaker Clarify Documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-fairness-and-explainability.html#clarify-fairness-and-explainability-toc)」を参照してください。