本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 執行 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`物件，並指示物件使用一個`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 行格式的表格式資料集
+ 自然語言處理 (NLP) 資料集
+ 電腦視覺資料集
使用 **Spark** 執行平行 SageMaker Clarify 處理任務的指南，在可展開的部分後。
## 以 CSV 格式分析表格式資料
下列範例說明如何針對 CSV 格式的表格式資料集，設定偏差分析和可解譯性分析。在這些範例中，內送資料集具有四個功能欄欄和一個二進位標籤欄`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 處理任務會以遞迴方式收集位於前置下的所有 Amazon S3 檔案。`s3_output_path`的值應為 S3 URI 前置，以保存分析結果。SageMaker AI 會在編譯時使用 `s3_output_path`，且無法取得 SageMaker AI 管道參數、屬性、運算式或 `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 資料集的所有訓練前偏差指標
下列程式碼範例說明如何設定`BiasConfig`物件，以衡量先前樣本輸入對具有`Gender`值`0`的樣本偏差。
```
bias_config = clarify.BiasConfig(
label_values_or_threshold=[1],
facet_name='Gender',
facet_values_or_threshold=[0],
)
```
下列程式碼範例說明如何使用執行陳述式來啟動 SageMaker Clarify 處理任務，該工作會運算輸入資料集的所有[訓練前偏差指標](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-measure-data-bias.html)。
```
clarify_processor.run_pre_training_bias(
data_config=data_config,
data_bias_config=bias_config,
methods="all",
)
```
或者，您也可以指派訓練前偏差指標清單給方法參數，以選擇要運算哪些指標。例如，以`methods=["CI", "DPL"]`取代`methods="all"`，指示 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 格式輸出資料。在此範例輸出中，每一列都包含兩欄。首欄包含預測標籤，第二欄包含該標籤的機率值。
```
0,0.028986845165491
1,0.825382471084594
...
```
在以下範例組態中，`ModelConfig` 物件會指示任務將 SageMaker AI 模型部署到臨時端點。端點使用一個`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,
)
```
下列組態範例使用標籤索引為`0`的`ModelPredictedLabelConfig`物件。這會指示 SageMaker Clarify 處理任務在模型輸出的首欄中找到預測標籤。在此範例中，處理任務使用從零開始的索引。
```
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=["DPPL", "DI"]`取代`methods=“all”`，僅運算[預測標籤中正值比例的差異](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 資料集的所有偏差指標
下列組態範例說明如何在一個 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 處理工作，以偵測偏差的指示範例筆記本，請參閱 [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 處理任務從模型輸出的第二欄擷取機率分數 (使用從零開始的索引)。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability=1,
)
```
`SHAPConfig`物件提供了SHAP分析參數。在此範例中，忽略 SHAP `baseline` 參數且`num_clusters` 參數的值為 `1`。這會指示 SageMaker Clarify 處理器根據叢集輸入資料集來運算一個SHAP基準範例。如果您想要選擇基準資料集，請參閱[可解釋性的SHAP基準](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 值的範例筆記本，請參閱 [SageMaker Clarify 的公平性和可解釋性](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability.ipynb)。
### 如何運算 CSV 資料集的部分相依圖 (PDPs)
PDPs說明預測目標對一個或多個感興趣的輸入功能的回應依賴，同時保持所有其他功能不變。向上傾斜線或 PDP 中的曲線表示目標與輸入功能之間的關係為正值，陡度表示關係的強度。向下傾斜的直線或曲線表示如果輸入功能減少，則目標變數會增加。直覺上，您可以將部分相依解譯為對每個感興趣的輸入功能目標變數之回應。
下列組態範例適用於使用`PDPConfig`物件指示 SageMaker Clarify 處理任務，來運算`Income`功能的重要性。
```
pdp_config = clarify.PDPConfig(
features=["Income"],
grid_resolution=10,
)
```
在先前的範例中，`grid_resolution`參數會將`Income`功能值的範圍劃分為`10`儲存貯體。SageMaker Clarify 處理任務會在 X 軸上針對`Income`產生PDPs分割為`10`區段。Y 軸將說明對目標變數的`Income`邊際影響。
下列程式碼範例會啟動要運算PDPs的 SageMaker Clarify 處理任務。
```
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 的指示，請參閱 [SageMaker Clarify 的可解釋性 - 部分相依圖 (PDP)](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/explainability_with_pdp.ipynb)。
### 如何運算和 CSV 資料集的SHAP值和PDPs
您可以在單一 SageMaker Clarify 處理任務中運算PDPs值和SHAP。在下列組態範例中，新`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 行格式分析表格式資料
下列範例說明如何以 SageMaker AI JSON 行密集格式，設定表格式資料集的偏差分析和可解釋性分析。如需更多資訊，請參閱[JSONLINES 請求格式](cdf-inference.md#cm-jsonlines)。在這些範例中，內送資料集具有與上一節相同的資料，但其採用 JSON 行格式。每行都是有效的 JSON 物件。鍵`Features`指向功能值的陣列，以及鍵`Label`指向 Ground Truth 標籤。
```
{"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 處理任務可以從每筆記錄中擷取特徵陣列。`label`參數設定為 JMESPath 運算式`Label`，以便 SageMaker Clarify 處理任務可以從每個記錄中擷取 Ground Truth 標籤。`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 管道參數、屬性、運算式或 `ExecutionVariable` 的值，這些都是在執行時期使用的。
您必須擁有訓練好的模型，才能運算訓練後的偏差指標或功能重要性。下列範例來自二進位分類模型，該模型會以範例的格式輸出 JSON 行資料。模型輸出的每一列都是有效的 JSON 物件。鍵`predicted_label`指向預測標籤，鍵`probability`指向機率值。
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
在下列組態範例中，`ModelConfig` 物件會指示 SageMaker Clarify 處理任務將 SageMaker AI 模型部署到臨時端點。端點使用一個`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`物件的標籤參數設定為 JMESPath 表達式`predicted_label`。這將從模型輸出中擷取預測標籤。
```
predicted_label_config = clarify.ModelPredictedLabelConfig(
label='predicted_label',
)
```
下面的範例組態說明如何將`ModelPredictedLabelConfig`物件的`probability`參數設定為 JMESPath 表達式`probability`。這將從模型輸出中擷取分數。
```
probability_config = clarify.ModelPredictedLabelConfig(
probability='probability',
)
```
若要運算 JSON 行格式資料集的偏差指標和功能重要性，請使用與上一節 CSV 資料集相同的執行陳述式和組態物件。您可以在 SageMaker Studio Classic 中執行 SageMaker Clarify 處理任務，以偵測偏差並計算特徵重要性。如需指示和範例筆記本，請參閱 [SageMaker Clarify 的公平性和可解釋性 (JSON 行格式)](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 格式的表格式資料集，其中包含一個二進位標籤資料欄和兩個功能資料欄。
```
0,2,"Flavor needs work"
1,3,"They taste good"
1,5,"The best"
0,1,"Taste is awful"
...
```
下列組態範例說明如何指定 CSV 格式的輸入資料集，以及使用`DataConfig`物件的輸出資料路徑。
```
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 管道參數、屬性、運算式或 `ExecutionVariable` 的值，這些都是在執行時期使用的。
下列範例輸出是根據先前以輸入資料集訓練的二進位分類模型所建立。分類模型會接受 CSV 資料，並在`0`和`1`之間輸出單一分數。
```
0.491656005382537
0.569582343101501
...
```
以下範例說明如何設定 `ModelConfig` 物件來部署 SageMaker AI 模型。在此範例中，臨時端點會部署模型。此端點使用一個配備 GPU 的`ml.g4dn.xlarge`推論執行個體來加速推論。
```
nlp_model_config = clarify.ModelConfig(
model_name=your_nlp_model_name,
instance_type='ml.g4dn.xlarge',
instance_count=1,
)
```
下面的範例說明如何設定`ModelPredictedLabelConfig`物件定位的第一欄機率 (分數) 與索引`0`。
```
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`參數指示分析應該解析權杖。在英語中，每個權杖都是一個單詞。如需其他語言，請參閱 [針對權杖化的 spaCy 文件](https://spacy.io/usage/linguistic-features#tokenization)，SageMaker Clarify 將其用於NLP 處理。先前的範例也說明如何使用`Rating`的平均值`4`來設定就地SHAP基準執行個體。特殊的遮蔽權杖 `[MASK]` 用於取代 `Comments` 中的權杖 (字)。
在先前的範例中，如果執行個體是`2,"Flavor needs work"`，請將基準設定為具有下列基準`4`的平均值`Rating`。
```
4, '[MASK]'
```
在前面的範例中，SageMaker Clarify 解譯器會逐一查看每個權杖，並以遮蔽物取代它，如下所示。
```
2,"[MASK] needs work"
4,"Flavor [MASK] work"
4,"Flavor needs [MASK]"
```
然後，SageMaker Clarify 解譯器會將每一行發送到您的模型進行預測。這樣解譯器就可以學習帶有和沒有遮蔽詞的預測。然後，SageMaker Clarify 解譯器會使用此資訊來運算每個權杖的貢獻。
下列程式碼範例會啟動 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 中執行 SageMaker Clarify 處理任務，以進行 NLP 可解釋性分析的指示，請參閱[使用 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 管道參數、屬性、運算式或 `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`推論執行個體。
將 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 使用[簡單線性疊代叢集 (SLIC)](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) 方法，從 scikit 學習庫中擷取功能進行圖像區隔。之前的組態範例`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 的範例筆記本來分類影像並說明其分類，請參閱[使用 SageMaker Clarify 說明影像分類](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-clarify/computer_vision/image_classification/explainability_image_classification.ipynb)。
### 如何解譯物件檢測模型
SageMaker Clarify 處理任務可以偵測並分類影像中的物件，然後為偵測到的物件提供說明。解譯的程序如下。
1. 影像物件首先分類為指定集合中的一個分類。例如，如果一個物件偵測模型可以識別貓，狗和魚，那麼這三個類是在一個集合。此集合由`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 模型部署到臨時端點。為了加速成像，此端點使用一個`ml.p2.xlarge`配備 GPU 的推論執行個體。
在下列範例組態中，`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 範例筆記本的來偵測影像中物件並說明其預測，請參閱[使用 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` 定義時間序列預測模型解釋分析的引數，例如基準、方向、精細程度和範例數量。所有三種類型的資料都會設定基準值：相關時間序列、靜態共變數和目標時間序列。`AsymmetricShapleyValueConfig` 組態會通知 SageMaker Clarify 處理器如何一次計算一個項目的特徵歸因。下列程式碼顯示 `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` 的值會傳遞至分析組態，做為 `methods` 中的項目，金鑰為 `asymmetric_shapley_value`。
### 模型組態
您可以控制從 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值與輸入資料集執行個體產生關聯，請使用的`joinsource`參數`DataConfig`。如果您新增更多運算執行個體，建議您同時增加臨時端點`instance_count`的 [ModelConfig](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.ModelConfig)。這樣可以防止 Spark 工作者的並行推論請求產生過多端點。具體而言，我們建議您使用端點對處理執行個體的一對一比例。