本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 程式碼範例：Python 的 SDK
本節提供範例程式碼，以建立及調用使用 SageMaker Clarify 線上可解釋性的端點。這些程式碼範例使用[適用於 Python 的AWS SDK。](https://aws.amazon.com/sdk-for-python/)
## 表格式資料
下列範例使用表格式資料及稱為 `model_name` 的 SageMaker AI 模型。在此範例中，模型容器接受 CSV 格式的資料，每筆記錄都有四個數字特徵。在此最小組態中，**僅用於示範目的**，SHAP 基準資料設定為零。請參閱[用於可解釋性的 SHAP 基準](clarify-feature-attribute-shap-baselines.md)以了解如何為`ShapBaseline`選擇更適當的值。
設定端點，如下所示：
```
endpoint_config_name = 'tabular_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
EndpointConfigName=endpoint_config_name,
ProductionVariants=[{
'VariantName': 'AllTraffic',
'ModelName': model_name,
'InitialInstanceCount': 1,
'InstanceType': 'ml.m5.xlarge',
}],
ExplainerConfig={
'ClarifyExplainerConfig': {
'ShapConfig': {
'ShapBaselineConfig': {
'ShapBaseline': '0,0,0,0',
},
},
},
},
)
```
使用端點組態建立端點，如下所示：
```
endpoint_name = 'tabular_explainer_endpoint'
response = sagemaker_client.create_endpoint(
EndpointName=endpoint_name,
EndpointConfigName=endpoint_config_name,
)
```
使用 `DescribeEndpoint` API 來檢查建立端點的進度，如下所示：
```
response = sagemaker_client.describe_endpoint(
EndpointName=endpoint_name,
)
response['EndpointStatus']
```
端點狀態為 “”InService” 之後，請使用測試記錄調用端點，如下所示：
```
response = sagemaker_runtime_client.invoke_endpoint(
EndpointName=endpoint_name,
ContentType='text/csv',
Accept='text/csv',
Body='1,2,3,4',
)
```
**注意**
在先前的程式碼範例中，對於多模型端點，請在請求中傳遞其他 `TargetModel` 參數，以指定端點的目標模型。
假設回應的狀態碼為 200 (無錯誤)，並載入回應主體，如下所示：
```
import codecs
import json
json.load(codecs.getreader('utf-8')(response['Body']))
```
端點的預設動作是解釋記錄。以下顯示傳回的 JSON 物件中的範例輸出。
```
{
"version": "1.0",
"predictions": {
"content_type": "text/csv; charset=utf-8",
"data": "0.0006380207487381"
},
"explanations": {
"kernel_shap": [
[
{
"attributions": [
{
"attribution": [-0.00433456]
}
]
},
{
"attributions": [
{
"attribution": [-0.005369821]
}
]
},
{
"attributions": [
{
"attribution": [0.007917749]
}
]
},
{
"attributions": [
{
"attribution": [-0.00261214]
}
]
}
]
]
}
}
```
使用 `EnableExplanations` 參數來啟用隨選解釋，如下所示：
```
response = sagemaker_runtime_client.invoke_endpoint(
EndpointName=endpoint_name,
ContentType='text/csv',
Accept='text/csv',
Body='1,2,3,4',
EnableExplanations='[0]>`0.8`',
)
```
**注意**
在先前的程式碼範例中，對於多模型端點，請在請求中傳遞其他 `TargetModel` 參數，以指定端點的目標模型。
在此範例中，預測值小於 `0.8` 的臨界值，因此不解釋該記錄：
```
{
"version": "1.0",
"predictions": {
"content_type": "text/csv; charset=utf-8",
"data": "0.6380207487381995"
},
"explanations": {}
}
```
使用視覺化工具來協助解譯傳回的解釋。下列影像顯示如何使用 SHAP 圖來瞭解每個特徵對預測做出的貢獻。圖表上的基礎值，也稱為預期值，是訓練資料集的平均預測。使期望值升高的特徵為紅色，使期望值降低的特徵為藍色。如需其他資訊，請參閱 [SHAP 附加力配置](https://shap.readthedocs.io/en/latest/generated/shap.plots.force.html)。
![\[範例 SHAP 圖，可用來了解每個功能對預測的貢獻。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/clarify/force-plot.png)
如需表格式資料，請參閱[完整範例筆記本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular/tabular_online_explainability_with_sagemaker_clarify.ipynb)。
## 文字資料
本節提供一個程式碼範例，用於建立及調用文字資料的線上可解釋性端點。此程式碼範例使用適用於 Python 的 SDK。
下列範例使用文字資料及名為 `model_name` 的 SageMaker AI 模型。在此範例中，模型容器會接受 CSV 格式的資料，而且每筆記錄都是單一字串。
```
endpoint_config_name = 'text_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
EndpointConfigName=endpoint_config_name,
ProductionVariants=[{
'VariantName': 'AllTraffic',
'ModelName': model_name,
'InitialInstanceCount': 1,
'InstanceType': 'ml.m5.xlarge',
}],
ExplainerConfig={
'ClarifyExplainerConfig': {
'InferenceConfig': {
'FeatureTypes': ['text'],
'MaxRecordCount': 100,
},
'ShapConfig': {
'ShapBaselineConfig': {
'ShapBaseline': '""',
},
'TextConfig': {
'Granularity': 'token',
'Language': 'en',
},
'NumberOfSamples': 100,
},
},
},
)
```
+ `ShapBaseline`：保留用於自然語言處理 (NLP) 處理的特殊記號。
+ `FeatureTypes`：將特徵識別為文字。如果未提供此參數，解釋器將嘗試推斷特徵類型。
+ `TextConfig`：指定文字特徵分析的細微性及語言單位。在此範例中，語言為英文，而細微性 `token` 表示英文文字中的單字。
+ `NumberOfSamples`：設置綜合資料集大小上限的限制。
+ `MaxRecordCount`：模型容器可以處理的請求中記錄的最大數目。設定此參數是為了穩定效能。
使用端點組態建立端點，如下所示：
```
endpoint_name = 'text_explainer_endpoint'
response = sagemaker_client.create_endpoint(
EndpointName=endpoint_name,
EndpointConfigName=endpoint_config_name,
)
```
端點狀態變為 `InService` 後，調用端點。下列程式碼範例使用測試記錄，如下所示：
```
response = sagemaker_runtime_client.invoke_endpoint(
EndpointName=endpoint_name,
ContentType='text/csv',
Accept='text/csv',
Body='"This is a good product"',
)
```
如果請求成功完成，則回應主體將返回類似以下內容的有效 JSON 物件：
```
{
"version": "1.0",
"predictions": {
"content_type": "text/csv",
"data": "0.9766594\n"
},
"explanations": {
"kernel_shap": [
[
{
"attributions": [
{
"attribution": [
-0.007270948666666712
],
"description": {
"partial_text": "This",
"start_idx": 0
}
},
{
"attribution": [
-0.018199033666666628
],
"description": {
"partial_text": "is",
"start_idx": 5
}
},
{
"attribution": [
0.01970993241666666
],
"description": {
"partial_text": "a",
"start_idx": 8
}
},
{
"attribution": [
0.1253469515833334
],
"description": {
"partial_text": "good",
"start_idx": 10
}
},
{
"attribution": [
0.03291143366666657
],
"description": {
"partial_text": "product",
"start_idx": 15
}
}
],
"feature_type": "text"
}
]
]
}
}
```
使用視覺化工具幫助解釋傳回的文字屬性。下列影像顯示如何使用 captum 視覺化公用程式來瞭解每個單字對預測的貢獻。色彩飽和度越高，此單字的重要性越高。在此範例中，高度飽和的亮紅色表示強烈的負面貢獻。高度飽和的綠色表示強烈的正面貢獻。白色表示該單字具有中性的貢獻。如需有關解析及轉譯屬性的其他資訊，請參閱 [captum](https://github.com/pytorch/captum) 程式庫。
![\[Captum 視覺化公用程式用於瞭解每個單字如何對預測做出貢獻。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/clarify/word-importance.png)
如需文字資料，請參閱[完整範例筆記本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/natural_language_processing/nlp_online_explainability_with_sagemaker_clarify.ipynb)。