本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 設定 SageMaker Clarify 處理工作
若要使用 SageMaker Clarify 分析資料和模型的偏差和可解釋性，您必須設定 SageMaker Clarify 處理工作。本指南說明如何指定處理工作的輸入資料集名稱、分析組態檔案名稱和輸出位置。若要設定處理容器、工作輸入、輸出、資源和其他參數，您有兩種選擇。您可以使用 SageMaker AI `CreateProcessingJob` API，或使用 SageMaker AI 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. 在 `AppSpecification` 參數內輸入 SageMaker Clarify 容器影像的統一研究識別碼 (URI)，如下列程式碼範例所示。
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**注意**
URI 必須識別預先建置的 SageMaker Clarify 容器影像。不支援 `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. `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. `EnableNetworkIsolation` 必須設定為 `False` (預設值)，以便 SageMaker Clarify 可以在必要時調用端點進行預測。
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 AI 服務和 SageMaker AI 執行時期服務的端點。
如果已啟用分散式處理，您還必須允許同一個處理工作中不同執行個體之間的通訊。為安全群組設定規則，允許相同安全群組成員彼此間的傳入連線。如需詳細資訊，請參閱[允許 Amazon SageMaker Clarify 任務存取您 Amazon VPC 中的資源](clarify-vpc.md)。
下列程式碼顯示網路組態的範例。
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. 使用 `StoppingCondition` 參數來設定工作執行的時間上限。SageMaker Clarify 工作可以執行的最長時間為 `7` 天或 `604800` 秒。如果工作無法在此時間限制內完成，則會停止且不會提供分析結果。例如，下列組態會將工作可執行的時間上限限制為 3600 秒。
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. 指定 `RoleArn` 參數的 IAM 角色。該角色必須與 Amazon SageMaker AI 有信任關係。它可用來執行下表所列的 SageMaker API 作業。我們建議您使用 Amazon SageMaker AI FullAccess 受管政策，授予 SageMaker AI 的完整存取權。如需此政策的詳細資訊，請參閱[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/zh_tw/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)。
取得處理工作組態的個別部分之後，將其合併以設定工作。
## 使用適用於 Python 的 AWS SDK 設定 SageMaker Clarify 處理任務
下列程式碼範例示範如何使用[適用於 Python 的AWS SDK](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",
)
```
如需使用適用於 Python 的 AWS SDK 執行 SageMaker Clarify 處理任務的說明的範例筆記本，請參閱[使用適用於 Python 的 AWS SDK 搭配 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 |
| Europe (Paris) | 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 |
| Middle East (Bahrain) | 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) 和時間序列 (TS) 問題的說明。
您可以建立分析組態檔案，或使用 [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 處理工作。
### 分析組態檔案的參數
在分析組態檔案中，您可以指定下列參數。
+ **version** — (選用) 分析組態檔案結構描述的版本字串。如果未提供版本，SageMaker Clarify 會使用最新的支援版本。目前，唯一支援的版本是 `1.0`。
+ **dataset\$1type** — 資料集的格式。輸入資料集格式可以是下列任何值：
+ 表格式
+ `text/csv` 適用於 CSV
+ `application/jsonlines` 適用於 [SageMaker AI JSON 行密集格式](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)
+ `application/json` 適用於 JSON
+ `application/x-parquet` 適用於 Apache Parquet
+ `application/x-image` 以啟動電腦視覺問題的可解釋性
+ 時間序列預測模型說明
+ `application/json` 適用於 JSON
+ **dataset\$1uri** - (選用) 主資料集的統一資源識別碼 (URI)。如果您提供 S3 URI 字首，SageMaker Clarify 處理工作會以遞迴方式收集位於字首下的所有 S3 檔案。您可以為電腦視覺問題的影像資訊清單檔案提供 S3 URI 字首或 S3 URI。如果已提供 `dataset_uri`，這會優先於處理工作輸入的資料集。對於影像以外的任何格式類型和時間序列使用案例，SageMaker Clarify 處理任務會將輸入資料集以**表格式資料集**形式載入至表格式資料框架。此格式可讓 SageMaker AI 輕鬆地操作和分析輸入資料集。
+ **標頭** - (選用)
+ **表格式** - 字串陣列，其中包含表格式資料集的資料欄名稱。如果未提供 `headers` 的值，則 SageMaker Clarify 處理任務會從資料集讀取標題。如果資料集沒有標題，則 Clarify 處理任務會根據從零開始的資料欄索引，自動產生預留位置名稱。例如，第一欄和第二欄的預留位置名稱將為 **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** — (選用) 字串或從零開始的整數索引。如果提供，`label` 用於定位 Ground Truth 標籤，也稱為表格式資料集中的觀察標籤或目標屬性。Ground Truth 標籤用於計算偏差指標。`label` 的值是根據 `dataset_type` 參數的值指定，如下所示。
+ 如果 `dataset_type` 是 **text/csv**，則 `label` 可以指定為下列任一項：
+ 有效的欄位名稱
+ 介於資料集欄位範圍內的索引
+ 如果 `dataset_type` 是 **application/parquet**，則 `label` 必須是有效的欄位名稱。
+ 如果 `dataset_type` 是 **application/jsonlines**，則 `label` 必須是寫入以從資料集中擷取 Ground Truth 標籤的 [JMESPath](https://jmespath.org/) 運算式。按照慣例，如果指定 `headers`，則其應包含標籤名稱。
+ 如果 `dataset_type` 是 **application/json**，則 `label` 必須是寫入為資料集中的每個記錄擷取 Ground Truth 標籤的 [JMESPath](https://jmespath.org/) 運算式。此 JMESPath 運算式必須產生標籤清單，其中第 i 個標籤與第 i 個記錄相互關聯。
+ **predicted\$1label** — (選用) 字串或從零開始的整數索引。如果提供，`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 個記錄。
+ **特徵** - (選用) non-time-series 使用案例需要，如果 `dataset_type` 為 `application/jsonlines` 或 `application/json` 的話。寫入以定位輸入資料集中的功能的 JMESPath 字串運算式。對於 `application/jsonlines`，JMESPath 運算式會套用至每一行，以擷取該記錄的功能。對於 `application/json`，JMESPath 運算式會套用至整個輸入資料集。JMESPath 運算式應擷取清單的清單，或功能的 2D 陣列/矩陣，其中第 i 行包含與第 i 個記錄相互關聯的功能。對於 `text/csv` 或 `application/x-parquet` 的 `dataset_type`，除了 Ground Truth 標籤和預測標籤欄以外的所有欄都會自動指定為功能。
+ **predicted\$1label\$1dataset\$1uri** - (選用) 僅適用於 dataset\$1type 為 `text/csv` 時。資料集的 S3 URI 包含用於計算訓練後**偏差指**標的預測標籤。SageMaker Clarify 處理工作將從提供的 URI 載入預測，而不是從模型取得預測。在此情況下，`predicted_label` 需要在預測標籤資料集中找到預測標籤欄位。如果預測標籤資料集或主資料集分割為多個檔案，則 `joinsource_name_or_index` 必須指定識別碼欄位以加入這兩個資料集。
+ **predicted\$1label\$1headers** - (選用) 僅在指定 `predicted_label_dataset_uri` 時適用。包含預測標籤資料集的欄位名稱的字串陣列。除了預測標籤標題，`predicted_label_headers` 也可以包含標識符欄位的標題以加入預測標籤資料集和主資料集。如需詳細資訊，請參閱參數 `joinsource_name_or_index` 的以下描述。
+ **joinsource\$1name\$1or\$1index** - (選用) 表格式資料集中資料欄的名稱或從零開始的索引，用作執行內部聯結時的識別碼欄。此欄僅用作識別碼。不用於任何其他計算，如偏差分析或功能屬性分析。在下列情況下，需要 `joinsource_name_or_index` 的值：
+ 有多個輸入資料集，而且有任何一個被分成多個檔案。
+ 透過將 SageMaker Clarify 處理工作 [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount) 設定為大於 `1` 的值來啟動分散式處理。
+ **excluded\$1columns** —(選用) 要排除不傳送至模型做為預測輸入的名稱陣列或從零開始的欄位索引。Ground Truth 標籤和預測標籤已自動排除。時間序列不支援此特徵。
+ **probability\$1threshold** — (選用) 浮點數，在此浮點數上選取一個標籤或物件。預設值為 `0.5`。SageMaker Clarify 處理工作會在下列情況下使用 `probability_threshold`：
+ 在訓練後偏差分析中，如果模型是二進位分類器，`probability_threshold` 會將數值模型預測 (機率值或分數) 轉換為二進位標籤。大於閾值的分數會轉換為 `1`。而小於或等於閾值的分數會轉換為 `0`。
+ 在電腦視覺可解釋性問題中，如果 model\$1type 是 **OBJECT\$1DETECTION**，`, probability_threshold` 會篩選掉可信度分數低於閾值的偵測到物件。
+ **label\$1values\$1or\$1threshold** - (選用) 偏差分析需要。標籤值或閾值數的陣列，表示偏差指標的 Ground Truth 和預測標籤的正面結果。如需詳細資訊，請參閱 [Amazon SageMaker Clarify 偏差和公平性條款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) 中的正標籤值。如果標籤是數值，會將閾值套用為下限以選取正面結果。若要針對不同的問題類型設定 `label_values_or_threshold`，請參閱下列範例：
+ 對於二進位分類問題，標籤有兩個可能的值 `0` 和 `1`。如果標籤值 `1` 對樣本中觀察的人口統計群組有利，則 `label_values_or_threshold` 應設定為 `[1]`。
+ 對於多類別分類問題，標籤有三個可能的值 **bird**、**cat** 和 **dog**。如果後兩項定義偏差有利的人口統計群組，則 `label_values_or_threshold` 應設定為 `["cat","dog"]`。
+ 對於迴歸問題，標籤值是連續的，範圍從 `0` 到 `1`。如果大於 `0.5` 的值應將樣本指定為具有正面結果，則 `label_values_or_threshold` 應設定為 `0.5`。
+ **facet** - (選用) 偏差分析需要。facet 物件的陣列，由用以測量偏差的敏感屬性組成。您可以使用 facet 來瞭解資料集和模型的偏差特性，即使未使用敏感屬性來訓練模型也可以。如需詳細資訊，請參閱 [Amazon SageMaker Clarify 偏差和公平性條款](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms) 中的 **Facet**。每個 facet 物件包含以下欄位：
+ **name\$1or\$1index** - (選用) 表格式資料集中敏感屬性欄的名稱或從零開始的索引。如果指定 `facet_dataset_uri`，則索引會參考 facet 資料集，而不是主資料集。
+ **value\$1or\$1threshold** - (選用) 如果 `facet` 為數值且 `label_values_or_threshold` 套用為下限以選取敏感群組，則需要此欄位。facet 值或閾值數陣列，表示偏差有利的敏感人口統計群組。如果 facet 資料類型為分類而且未提供 `value_or_threshold`，偏差指標會將每個唯一值 (而非所有值) 計算為一個群組。若要針對不同的 `facet` 資料類型設定 `value_or_threshold`，請參閱下列範例：
+ 對於二進位 facet 資料類型，功能有兩個可能的值 `0` 和 `1`。如果要計算每個值的偏差指標，則 `value_or_threshold` 可以省略或設定為空陣列。
+ 對於分類 facet 資料類型，功能有三個可能的值 **bird**、**cat** 和 **dog**。如果前兩項定義偏差有利的人口統計群組，則 `value_or_threshold` 應設定為 `["bird", "cat"]`。在此範例中，資料集範例會分割為兩個人口統計群組。有利群組中的 facet 有值 **bird** 或 **cat**，而不利群組中的 facet 有值 **dog**。
+ 對於數值 facet 資料類型，功能值是連續的，範圍從 `0` 到 `1`。例如，如果大於 `0.5` 的值應將樣本指定為有利，則 `value_or_threshold` 應設定為 `0.5`。在此範例中，資料集範例會分割為兩個人口統計群組。有利群組中的 facet 有大於 `0.5` 的值 ，而不利群組中的 facet 有小於或等於 `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。您可以使用 facet 來瞭解資料集和模型的偏差特性，即使未使用敏感屬性來訓練模型也可以。
**注意**
如果 facet 資料集或主資料集分割為多個檔案，則 `joinsource_name_or_index` 必須指定識別符欄位以加入這兩個資料集。您必須使用參數 `facet` 來識別 facet 資料集中的每個 facet。
+ **facet\$1headers** - (選用) 僅在指定 `facet_dataset_uri` 時適用。字串陣列，其中包含 facet 資料集的欄位名稱，以及可選擇性包含識別碼欄標題以加入 facet 資料集和主資料集，請參閱`joinsource_name_or_index`。
+ **time\$1series\$1data\$1config** - (選用) 指定用於時間序列資料處理的組態。
+ **item\$1id** - 字串或從零開始的整數索引。此欄位用來尋找共用輸入資料集中的項目 ID。
+ **timestamp** - 字串或從零開始的整數索引。此欄位用來尋找共用輸入資料集中的時間戳記。
+ **dataset\$1format** - 可能的值為 `columns`、`item_records` 或 `timestamp_records`。此欄位用來描述 JSON 資料集的格式，這是時間序列可解釋性支援的唯一格式。
+ **target\$1time\$1series** - JMESPath 字串或從零開始的整數索引。此欄位用來尋找共用輸入資料集中的目標時間序列。如果此參數是字串，則除 `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** — 包含一或多個分析方法及其參數的物件。如果省略任何方法，則不會用於分析和報告。
+ **pre\$1training\$1bias** — 如果您想要計算訓練前偏差指標，請包含此方法。您可以在 [訓練前偏差指標](clarify-measure-data-bias.md) 中找到指標的詳細描述。物件具有下列參數：
+ **methods** — 包含您要計算的下列清單中任何訓練前偏差指標的陣列。設定 `methods` 為 **all** 以計算所有訓練前偏差指標。例如，陣列 `["CI", "DPL"]` 將計算**類別不平衡**和**標籤的比例差異**。
+ 適用於 [類別不平衡 (CI)](clarify-bias-metric-class-imbalance.md) 的 `CI`
+ 適用於 [標籤比例的差異](clarify-data-bias-metric-true-label-imbalance.md) 的 `DPL`
+ 適用於 [Kullback-Leibler 散度 (KL)](clarify-data-bias-metric-kl-divergence.md) 的 `KL`
+ 適用於 [Jensen-Shannon 偏差 (JS)](clarify-data-bias-metric-jensen-shannon-divergence.md) 的 `JS`
+ 適用於 [L p-規範 (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`
+ **post\$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` 指定的資料集格式相同。
+ 基準只能包含模型可以接受為輸入的功能。
+ 基準資料集可以有一或多個執行個體。基準執行個體的數目會直接影響綜合資料集大小和工作執行期。
+ 如果指定 `text_config`，則文字欄的基準值是用來取代 `granularity` 指定的文字單位的字串。例如，一個常見的預留位置是 “[MASK]”，用來表示遺失或未知的單字或文字片段。
下面的範例顯示如何為不同的 `dataset_type` 參數設定就地基準資料：
+ 如果 `dataset_type` 是 `text/csv` 或 `application/x-parquet`，則模型會接受四個數值特徵，且基準有兩個執行個體。在此範例中，如果一筆記錄有所有零特徵值，而另一筆記錄有所有一特徵值，則應將基準設定為 `[[0,0,0,0],[1,1,1,1]]`，不包含任何標題。
+ 如果 `dataset_type` 是 `application/jsonlines`，`features` 為四個數值特徵值清單的金鑰。此外，在這個範例中，如果基準有一筆具所有零值的記錄，則 `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 值。如果未提供 `features_to_explain`，則會計算所有功能欄位的 SHAP 值。這些功能欄位不能包括標籤欄位或預測標籤欄位。只有具有數值和分類欄位的表格式資料集才支援`features_to_explain` 參數。
+ **num\$1clusters** — (選用) 資料集所分割成的叢集數以計算基準資料集。每個叢集都用來計算一個基準執行個體。如果未指定 `baseline`，SageMaker Clarify 處理工作會嘗試將表格式資料集分割為介於 `1` 和 `12` 之間的最佳叢集數來計算基準資料集。基準執行個體數會直接影響 SHAP 分析的執行期。
+ **num\$1samples** — (選用) 核心 SHAP 演算法中要使用的樣本數。如果未提供 `num_samples`，SageMaker Clarify 處理工作會為您選擇數量。樣本數會直接影響綜合資料集大小和工作執行期。
+ **seed** - (選用) 一個整數，用於初始化 SHAP 解釋器中的虛擬隨機數產生器，為相同工作產生一致的 SHAP 值。如果未指定 seed，則每次執行相同工作時，模型可能會輸出略有不同的 SHAP 值。
+ **use\$1logit** – (選用) 布林值，指出您要將 logit 函式套用至模型預測。預設為 `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 值的平均值。
+ **中位數**—所有執行個體的本地 SHAP 值的中位數。
+ **text\$1config** - 自然語言處理可解釋性需要。如果您要將文字欄視為文字，請包含此組態，並針對個別文字單位提供解釋。如需自然語言處理可解釋性的分析組態範例，請參閱[自然語言處理解釋性的分析組態](#clarify-analysis-configure-nlp-example)
+ **粒度**—分析文字欄的粒度單位。有效值為 `token`、`sentence` 或 `paragraph`。**文字的每個單位都被視為一個功能**，並針對每個單位運算本機 SHAP 值。
+ **語言**—文字欄的語言。有效值為 **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 值會包含在分析 .json 檔案的`global_top_shap_text`區段中。
+ 彙總的本機 SHAP 值。
+ **image\$1config**—電腦視覺解釋性需要。如果您有由映像組成的輸入資料集，並且想要在電腦視覺問題中分析這些資料集以解釋這些資料集，請包含此組態。
+ **model\$1type**—模型的類型。有效值包含：
+ 調校映像分類模型的 `IMAGE_CLASSIFICATION`。
+ 調校物件偵測模型的 `OBJECT_DETECTION`。
+ **max\$1objects** — 僅當 model\$1type 為時才適用**OBJECT\$1DETECTION**。由電腦視覺模型偵測到的最大物件數 (依可信度分數排序)。任何依可信度分數排名低於頂部 max\$1objects 的物件都會被篩選掉。預設為 `3`。
+ **context**—僅當模型類型為時適用。**OBJECT\$1DETECTION**它指示偵測到的物件邊界方框周圍區域是否被基線映像遮罩。有效值是 `0` 遮罩所有內容，或者`1`什麼都不遮罩。預設值為 1。
+ **iou\$1threshold** — 僅適用當 `model_type` 為 **OBJECT\$1DETECTION**。以原始偵測評估預測的交併比 (IOU) 計量下限。高 IOU 計量對應於預測和 Ground Truth 檢測框之間的大重疊。預設為 `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** - 包含此方法來計算部分相依性圖 (PDP)。如需產生 PDP 的分析組態範例，請參閱[運算部分相依性繪圖 (PDP)](#clarify-analysis-configure-csv-example-pdp)
+ **功能**—如果未請求該`shap`方法，則為強制性。用於運算和繪製 PDP 繪圖的功能名稱或索引陣列。
+ **top\$1k\$1features** — (選擇性) 指定用於產生 PDP 繪圖的頂層特徵數目。如果 `features` 未提供，但請求 `shap` 方法，則 SageMaker Clarify 處理任務會根據其 SHAP 屬性選擇最上層功能。預設為 `10`。
+ **grid\$1resolution**—要將數值範圍分割成的儲存貯體數目。這會指定 PDP 繪圖的格點粒度。
+ **asymmetric\$1shapley\$1value** - 如果您想要計算時間序列預測模型的可解釋性指標，請包含此方法。SageMaker Clarify 處理任務支援非對稱 Shapley 值演算法。非對稱 Shapley 值是捨棄對稱軸的 Shapley 值變體。如需詳細資訊，請參閱[非對稱 Shapley 值：將因果知識納入模型無關的可解釋性](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** - (選用) 取代對應資料集 (也稱為背景資料) out-of-coalition 值的基準組態。下列程式碼片段說明基準組態的範例。
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ 對於目標時間序列或相關時間序列等時間資料，基準值類型可以是下列其中一個值：
+ `zero` - 所有 out-of-coalition 值都會取代為 0.0。
+ `mean` - 所有 out-of-coalition 值都會取代為時間序列的平均值。
+ 對於靜態共變數，只有在模型請求接受靜態共變數值時，才應該提供基準項目，在這種情況下，需要此欄位。應為每個項目提供基準做為清單。例如，如果您有一個資料集具有兩個靜態共變數，您的基準組態可能如下：
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
在上述範例中，** 和 ** 是來自資料集的項目 ID。
+ **report** — (選用) 使用此物件可自訂分析報告。時間序列解釋任務不支援此參數。分析結果中有三份相同報告副本：Jupyter 筆記本報表、HTML 報告和 PDF 報告。此物件具有下列參數：
+ **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 模型名稱。如果您指定`model_name`而不是 endpoint\$1name，SageMaker Clarify 處理任務會建立具有模型名稱 (稱為**陰影端點**) 的暫時端點，並從端點取得預測結果。運算完成後，任務會刪除陰影端點。如果模型是多模型，則必須指定 `target_model` 參數。如需多模型端點的詳細資訊，請參閱 [多模型端點](multi-model-endpoints.md)。
+ **endpoint\$1name\$1prefix** — (選擇性) 陰影端點的自訂名稱字首。如果您提供 `model_name` 而不是 `endpoint_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**—指定陰影端點的執行個體數目。如果您提供 model\$1name 而不是 endpoint\$1name，則需要此選項。`initial_instance_count` 的值可以與任務的 [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount) 不同，但我們建議使用 1:1 的比例。
+ **instance\$1type**—指定陰影端點的執行個體類型。如果您提供 `model_name` 而不是 `endpoint_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-endpoints.md)。
+ **custom\$1attributes** — (選用) 字串可讓您提供有關提交至端點之推論請求的其他資訊。字串值會傳遞至 SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API 的 `CustomAttributes` 參數。
+ **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` 是 “OBJECT\$1DETECTION”，則 `accept_type` 預設為 **application/json**。
+ 對於時間序列預測可解釋性，有效值為 **application/json**。
+ 對於其他類型的解釋性，有效值為 **text/csv**、**application/jsonlines**和 **application/json**。如果 `accept_type` 的值未提供，則 `accept_type` 預設為 `content_type` 參數的值。
+ **content\$1template**—用於從資料集記錄建構模型輸入的範本字串。只有在 `content_type` 參數值為 `application/jsonlines` 或 `application/json` 時，才會使用且需要 `content_template` 參數。
當`content_type` 參數為時 `application/jsonlines`，範本應該只有一個預留位置 `$features`，在執行期會由功能清單取代。例如，如果範本是 `"{\"myfeatures\":$features}"`，且如果記錄具有三個數值功能值：`1`、`2` 和 `3`，則記錄將以 JSON 行的形式傳送至模型`{"myfeatures":[1,2,3]}`。
如果 `content_type` 是 `application/json`，範本則可以有預留位置 `$record` 或 `records`。如果預留位置為`record`，則會將單一記錄取代為已套用 `record_template` 的範本記錄。在此情況下，一次只會將單一記錄傳送至模型。如果預留位置為 `$records`，則記錄會由記錄清單取代，每筆記錄都有提供的範本 `record_template`。
+ **record\$1template**—一個範本字串，用於從資料集執行個體建構模型輸入的每個記錄。它僅在 `content_type` 是 `application/json` 時使用和需要。範本字串可能包含下列其中一項：
+ 由功能值陣列取代的預留位置 `$features` 參數。其他可選預留位置可以取代 `$feature_names` 中的功能欄標題名稱。此可選的預留位置將替換為功能名稱的陣列。
+ 只有一個預留位置 `$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** - (選用) 從零開始的整數索引或 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**，則 `label_headers` 應設定為 `["bird","cat","dog"]`。
+ **機率**— (選用) 從零開始的整數索引或 JMESPath 運算式字串，用於擷取機率 (分數) 以進行解釋性分析 (但不適用於時間序列可解釋性)，或選擇偏差分析的預測標籤。`probability` 的值取決於 `accept_type` 參數的值，如下所示。
+ 如果 `accept_type` 是 **text/csv**，則 `probability` 為模型輸出中機率 (分數) 的索引。如果 `probability` 未提供，則會將整個模型輸出視為機率 (分數)。
+ 如果 `accept_type` 是 JSON 資料 (**application/jsonlines** 或 **application/json**)，則 `probability` 應該是用於從模型輸出中擷取機率(分數)的 JMESPath 表達式。
+ **time\$1series\$1predictor\$1config** - (選用) 僅用於時間序列可解釋性。用來指示 SageMaker Clarify 處理器如何從 `dataset_uri` 中以 S3 URI 形式傳遞的資料正確剖析資料。
+ **forecast** – 用來擷取預測結果的 JMESPath 表達式。
## 範例分析組態檔案
以下各節包含 CSV 格式、JSON 行格式資料以及自然語言處理 (NLP)、電腦視覺 (CV) 和時間序列 (TS) 可解釋性的範例分析組態檔案。
### CSV 資料集的分析組態
以下的範例顯示如何設定 CSV 格式之表格式資料集的偏差和解釋性分析。在這些範例中，內送資料集具有四個功能資料欄，以及一個二進位標籤資料欄`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
...
```
以下各章節說明如何運算訓練前和訓練後偏差指標、SHAP 值以及部分相依性繪圖 (PDP)，以顯示 CSV 格式資料集的功能重要性。
#### 運算所有訓練前偏差指標
此範例組態顯示如何測量先前的範例資料集是否偏向 **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 格式輸出資料。在此範例輸出中，每一列都包含兩欄。第一欄包含預測標籤，第二欄則包含該標籤的機率值。
```
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 值
以下範例分析組態說明任務運算 SHAP 值，將 `Target` 欄指定為標籤，並將所有其他欄指定為功能。
```
{
"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 處理器運算一個 SHAP 基準範例。在此範例中，機率設定為 `1`。這會指示 SageMaker Clarify 處理任務從模型輸出的第二欄擷取機率分數 (使用從零開始的索引)。
#### 運算部分相依性繪圖 (PDP)
下列範例顯示如何使用 PDP 在分析報告中檢視 `Income` 功能的重要性。報告參數會指示 SageMaker Clarify 處理任務產生報告。任務完成後，產生的報告會以 report.pdf 的形式儲存至 `analysis_result` 位置。`grid_resolution` 參數會將功能值的範圍劃分為 `10` 儲存貯體。在下列範例中指定的參數一起指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 x 軸上具有 `10` 區段的 `Income` PDP 圖表的報告。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
},
}
```
#### 運算偏差指標和功能重要性
您可以將之前的組態範例中，所有方法合併為單一分析組態檔案，然後透過單一任務進行全部運算。下列範例顯示結合所有步驟的分析組態。
在此範例中，`probability` 參數設定為 `1`，指出機率包含在第二欄中 (使用從零開始的索引)。但是，由於偏差分析需要預測標籤，因此 `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 AI 模型的名稱提供給 SageMaker Clarify 處理任務，而不是將模型部署到端點。下列範例示範如何指定名為 **your\$1model** 的模型。SageMaker Clarify 處理任務將使用組態建立陰影端點。
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### JSON 行資料集的分析組態
下列範例說明如何針對 JSON 行格式的表格式資料集設定偏差分析和解釋性分析。在這些範例中，內送資料集具有與上一節相同的資料，但它們採用 SageMaker AI JSON 行密集格式。每行都是有效的 JSON 物件。主要 “特徵” 指向特徵值的陣列，主要 “標籤” 指向 Ground Truth 標籤。資料集是由 “資料集” 處理輸入提供給 SageMaker Clarify 工作。如需 JSON Lines 的詳細資訊，請參閱 [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}
...
```
下列各章節說明如何運算訓練前和訓練後偏差指標、SHAP 值，以及部分相依性繪圖 (PDP)，以 JSON 行格式顯示資料集的功能重要性。
#### 運算訓練前的偏向指標
指定標籤、功能、格式和方法，以測量 `Gender` 值為`0` 的訓練前偏差指標。在下列範例中，`headers` 參數會先提供功能名稱。標籤名稱最後提供。按照慣例，最後一個標題是標籤標題。
此 `features` 參數設定為 JMESPath 運算式 “特徵”，以便 SageMaker Clarify 處理工作可以從每個記錄中擷取特徵陣列。此 `label` 參數設定為 JMESPath 運算式 “標籤”，以便 SageMaker Clarify 處理工作可以從每個記錄中擷取 Ground Truth 標籤。使用面向名稱來指定敏感屬性，如下所示。
```
{
"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 行資料。模型輸出的每一列都是有效的 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 分析不需要 Ground Truth 標籤，因此會省略 `label` 參數。在此範例中，也會省略 `headers` 參數。因此，SageMaker Clarify 處理任務必須使用一般名稱 (例如 `column_0` 或 `column_1` 功能標題) 以及 `label0`，為標籤標題產生預留位置。您可以指定 `headers` 和 a `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 上 “收入” 的重要性。在此範例中，不會提供功能標題。因此，`pdp` 方法的 `features` 參數必須使用從零開始的索引來參考功能資料欄的位置。`grid_resolution` 參數會將功能值的範圍劃分為 `10` 儲存貯體。範例中的參數共同指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 X 軸上具有 `10` 區段的 `Income` PDP 圖表。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"
}
}
```
#### 運算偏差指標和功能重要性
您可以將所有先前的方法合併為一個分析組態檔案，然後透過單一任務來運算它們。下列範例顯示結合所有步驟的分析組態。在此範例中，已設定 `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 Lines 的詳細資訊，請參閱 [JSONLINES 請求格式](cdf-inference.md#cm-jsonlines)。
整個輸入請求是有效的 JSON，其中外部結構是一個清單，每個元素是記錄的資料。在每個記錄中，關鍵 `Features` 指向功能值的陣列，並且關鍵 `Label` 指向 Ground Truth 標籤。資料集會透過 `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},
...
]
```
下列各章節說明如何運算訓練前和訓練後偏差指標量、SHAP 值，以及部分依賴性繪圖 (PDP)，這些圖表顯示JSON 行格式的資料集的功能重要性。
#### 運算訓練前的偏向指標
指定標籤、功能、格式和方法，以測量 `Gender` 值為`0` 的訓練前偏差指標。在下列範例中，`headers` 參數會先提供功能名稱。標籤名稱最後提供。對於 JSON 資料集，最後一個標題是標籤標題。
`features` 參數設定為擷取二維陣列或矩陣的 JMESPath 運算式。此矩陣中的每一列都必須包含每筆記錄 `Features` 的清單。`label` 參數設定為 JMESPath 表達式，該表達式擷取 Ground Truth 標籤清單。此清單中的每個元素都必須包含記錄的標籤。
使用面向名稱來指定敏感屬性，如下所示。
```
{
"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`，以及 `label0`，為標籤標題產生預留位置。您可以指定 `headers` 和 a `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` 參數必須使用從零開始的索引來參考功能資料欄的位置。`grid_resolution` 參數會將功能值的範圍劃分為 `10` 儲存貯體。
下列範例中的參數共同指示 SageMaker Clarify 處理任務產生一個報告，其中包含在 x 軸上具有 `10` 區段的 `Income` PDP 圖表報告。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"
}
}
```
#### 運算偏差指標和功能重要性
您可以將所有之前的組態方法合併為單一分析組態檔案，然後透過單一任務進行運算。下列範例顯示結合所有步驟的分析組態。
在此範例中，已設定 `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 格式的表格式資料集，其中包含一個二進位標籤資料欄和兩個功能資料欄，如下所示。資料集會透過 `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` 之間輸出單一分數，如下所示。
```
0.491656005382537
0.569582343101501
...
```
該模型用於建立名為 “your\$1model” 的 SageMaker AI 模型。以下分析組態顯示如何使用模型和資料集執行權杖化的解釋性分析。此 `text_config` 參數會啟動 NLP 解釋性分析。該 `granularity` 參數指示分析應該剖析符記。
在英語中，每個符記都是一個單詞。下列範例也展示如何使用 4 的平均 “評比” 來提供就地 SHAP “基準線” 執行個體。特殊的遮罩符記 “[MASK]” 用於取代 “註解” 中的權杖 (文字)。此範例也會使用 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 值演算法來計算預測模型的特徵歸因。
#### 計算時間序列預測模型的解釋
下列範例分析組態會顯示任務用來為時間序列預測模型計算解釋的選項。
```
{
'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` 來定義時間序列可解釋性引數，例如基準、方向、精細程度和範例數量。所有三種類型的資料都會設定基準值：相關時間序列、靜態共變數和目標時間序列。這些欄位會指示 SageMaker Clarify 處理器一次計算一個項目的特徵歸因。
##### 預測器組態
您可以使用 JMESPath 語法，完全控制 SageMaker Clarify 處理器傳送的承載結構。在上述範例中，`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` 屬性指示 SageMaker Clarify 處理器從 `dataset_uri` 中以 S3 URI 形式傳遞的資料正確剖析資料。
# 資料格式相容性指南
本指南說明與 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` 參數來指定格式。
端點的輸入資料集、請求和來自端點的回應不需要相同的格式。例如，在符合下列條件的情況下，您可以使用具有 CSV **請求有效負載**和 JSON 行**回應有效負載**的 Parquet 資料集。
+ 您的分析設定正確。
+ 您的模型支援請求和回應格式。
**注意**
如果未提供 `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)
# 表格式資料
表格式資料是指可以載入到二維資料影格中的資料。在影格中，每一行代表一條記錄，每條記錄都有一個或多個資料欄。每個資料框儲存格內的值可以是數值、分類或文字資料類型。
## 表格式資料集先決條件
在進行分析之前，您的資料集應該已經套用了任何必要的預先處理步驟。這包含資料清理或功能工程。
您可以提供一或多個資料集。如果您提供多個資料集，請使用下列指令將其識別為 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 行 | JSOL | `application/jsonlines` |
| JSON | json | `application/json` |
| Parquet | parquet | “application/x-parquet” |
以下各章節顯示 CSV、JSON 行和 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`。這代表首欄是 Ground Truth 標籤。
+ 如果參數 `headers` 已設定，請將 `label` 設定為標示欄標題，以指示標籤欄的位置。所有其他資料欄都被設定為功能。
以下是不包含標題列的資料集範例。
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
如果您的資料包含標題列，請將參數 `label` 設定為 index `0`。若要指示標籤欄的位置，請使用 Ground Truth 標籤標題`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 行格式的資料集相比，允許更靈活的資料格式。本指南說明如何作為 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` 來擷取資料集中每個記錄的 Ground Truth 標籤。JMESPath 表達式應該產生一個標籤清單，其中第 i 個標籤對應於第 i 個記錄。
+ `features` 參數應該使用 JMESPath 運算式 `[*].features` 來擷取資料集中每個記錄的功能陣列。JMESPath 運算式應該產生 2D 陣列或矩陣，其中第 i 列包含對應於第 i 個記錄的功能值。
以下是包含最上層索引鍵和巢狀索引鍵的記錄的範例輸入資料，其中包含每個記錄的功能和標籤清單。
```
{
"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`來擷取資料集中每個記錄的 Ground Truth 標籤。JMesPath 表達式應該產生一個標籤清單，其中第 i 個標籤用於第 i 個記錄。
+ 此 `features` 參數會使用 JMESPath 運算式 `data[*].features`，針對資料集中的每筆記錄擷取特徵陣列。JMESPath 運算式應該產生 2D 陣列或矩陣，其中第 i 列包含第 i 個記錄的功能值。
### JSON 行格式的表格式資料集先決條件
JSON 行是一種文字格式，用於表示結構化資料，其中每一行都是一個有效的 JSON 物件。目前 SageMaker Clarify 處理任務僅支援 SageMaker AI 密集格式 JSON 行。為了符合所需的格式，記錄的所有功能都應列在單一 JSON 陣列中。如需 JSON Lines 的詳細資訊，請參閱 [JSONLINES 請求格式](cdf-inference.md#cm-jsonlines)。
**注意**
提供給 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}
...
```
先前的資料集範例組態分析應該如下設定參數：
+ 若要指示 Ground Truth 標籤的位置，應將參數 `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`，以指示 Ground Truth 標籤的位置。
+ 參數 `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` 參數設定標籤資料欄名稱名稱，以指示 Ground Truth 標籤的位置。所有其他資料欄都被設定為功能。
# 表格式資料的端點請求
為了取得訓練後偏差分析和功能重要性分析的模型預測，SageMaker Clefy 處理任務將表格式資料序列化為位元組，並將這些資料作為請求有效負載傳送至推論端點。此表格式資料可能來自輸入資料集，或產生表格式資料。如果是合成資料，其是由解釋器生成的 SHAP 分析或 PDP 分析。
請求有效負載的資料格式應該由分析組態 `content_type` 參數指定。如果未提供參數，SageMaker Clarify 處理任務將使用 `dataset_type` 參數的值作為內容類型。如需 `content_type` 或 `dataset_type` 的詳細資訊，請參閱 [分析組態檔案](clarify-processing-job-configure-analysis.md)。
以下各章節顯示 CSV 和 JSON 行格式的端點請求範例。
## CSV 格式的端點請求
SageMaker Clarify 處理任務可以將資料序列化為 CSV 格式 (MIME 類型：`text/csv`)。下列資料表顯示序列化請求有效負載範例。
| 端點請求有效負載 (字串表示) | 說明 |
| --- | --- |
| '1,2,3,4' | 單一記錄 (四個數值特徵)。 |
| '1,2,3,4\$1 n 5,6,7,8' | 兩個記錄，由分行符號 '\$1n' 分隔。 |
| '"這是一個很好的產品",5' | 單一記錄 (文字特徵和數值特徵)。 |
| '"這是一個很好的產品",5\$1n"糟糕的購物體驗",1’ | 兩個記錄。 |
## 端點請求採用 JSON 行格式
SageMaker Clarify 處理任務可以將資料序列化為 SageMaker AI JSON 行密集格式 (MIME 類型：`application/jsonlines`)。如需 JSON Lines 的詳細資訊，請參閱 [JSONLINES 請求格式](cdf-inference.md#cm-jsonlines)。
若要將表格式資料轉換作為 JSON 格式匯出 資料，請提供範本字串給分析組態 `content_template` 參數。如需有關 `content_template` 的詳細資訊，請參閱 [分析組態檔案](clarify-processing-job-configure-analysis.md)。下表顯示序列化 JSON 行請求有效負載的範例。
| 端點請求有效負載 (字串表示) | 說明 |
| --- | --- |
| '\$1"資料":\$1"功能":[1,2,3,4]\$1\$1' | 單一記錄。在這種情況下，範本看起來像 `'{"data":{"features":$features}}' `，並由功能清單 `[1,2,3,4]` 取代 `$features`。 |
| '\$1"資料":\$1"功能":[1,2,3,4]\$1\$1\$1n\$1"資料":\$1"功能":[5,6,7,8]\$1\$1' | 兩個記錄。 |
| '\$1"功能":["這是一個好產品",5]\$1' | 單一記錄。在這種情況下，範本看起來像 `'{"features":$features}'` 而 \$1features 取代為功能清單 `["This is a good product",5]`。 |
| '\$1"功能":["這是一個好產品",5]\$1\$1n\$1"功能":["不好的購物體驗",1]\$1' | 兩個記錄。 |
## 端點請求作為 JSON 格式匯出格式
SageMaker Clarify 處理任務可以將資料序列化為任意 JSON 結構 (MIME 類型：`application/json`)。若要這麼做，您必須為分析組態 `content_template` 參數提供範本字串。這是由 SageMaker Clarify 處理任務用來建構外部 JSON 結構。您也必須提供的範本字串 `record_template`，用來建構每筆記錄的 JSON 結構。如需 `content_template` 和 `record_template` 的更多相關資訊，請參閱[分析組態檔案](clarify-processing-job-configure-analysis.md)。
**注意**
因為 `content_template` AND `record_template` 是字串參數，所以屬於 JSON 序列化結構一部分的任何雙引號字元 (`"`) 都應該在組態中註記為逸出字元。例如，如果您想要在 Python 中逸出雙引號，您可以輸入以下內容 `content_template`。
```
"{\"data\":{\"features\":$record}}}"
```
下表顯示序列化 JSON 請求有效負載的範例，以及建構它們所需的對應 `content_template` 和 `record_template` 參數。
| 端點請求有效負載 (字串表示) | 說明 | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"資料":\$1"功能":[1,2,3,4]\$1\$1' | 一次單筆記錄。 | '\$1"資料":\$1"功能":\$1記錄\$1\$1\$1' | “\$1features” |
| '\$1"執行個體":[[0, 1], [3, 4]], "功能名稱": ["A", "B"]\$1' | 具有功能名稱的多重記錄。 | ‘\$1"執行個體":\$1records, "功能名稱":\$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' | 一次單一記錄和鍵值對。 | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "巢狀": \$1"B": 1\$1\$1' | 或者，對任意結構使用完全詳細資訊 record\$1template。 | "\$1record" | '\$1"A": "\$1\$1A\$1", "巢狀": \$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` 分析組態中，下列三個參數會擷取預測。
+ 該參數 `probability` 用於定位在端點回應的機率值 (分數)。
+ 該參數 `label` 用於在端點回應中定位預測標籤。
+ (選擇性) 參數 `label_headers` 提供多類別模型的預測標籤。
下列指南適用於 CSV、JSON 行和 JSON 格式的端點回應。
## 端點回應為 CSV 格式
如果回應有效負載是 CSV 格式 (MIME 類型：`text/csv`)，SageMaker Clarify 處理任務還原序列化每一列。然後，它使用分析組態中提供的欄索引，從還原序列化的資料中擷取預測。回應有效負載中的資料列必須與請求有效負載中的記錄相符。
下表提供不同格式和不同問題類型的回應資料範例。只要可以根據分析組態擷取預測，您的資料可以與這些範例有所不同。
以下各章節顯示 CSV 格式的端點回應範例。
### 端點回應為 CSV 格式，且僅包含機率
下表是迴歸和二進制分類問題的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄。 | '0.6' |
| 兩個記錄 (結果在一行中，用逗號分隔)。 | '0.6,0.3' |
| 兩個記錄 (結果在兩行中)。 | '0.6\$1n0.3' |
在先前的範例中，端點會輸出預測標籤的單一機率值 (分數)。若要使用索引擷取機率並將其用於功能重要性分析，請將分析組態參數設定為`probability`欄索引`0`。如果使用 `probability_threshold` 參數將這些機率轉換為二進位值，也可以用於偏差分析。如需 `probability_threshold` 的相關資訊，請參閱 [分析組態檔案](clarify-processing-job-configure-analysis.md)。
下表是多類別問題的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 多類模型的單一記錄 (三個類別)。 | '0.1,0.6,0.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' |
| 兩個記錄 (結果在一行中，用逗號分隔) | '1,0' |
| 兩個記錄 (結果在兩行) | '1\$1n0' |
對於先前的範例，端點輸出預測標籤而不是機率。將 `predictor` 組態的 `label` 參數設定為欄索引 `0`，以便可以使用索引擷取預測標籤並用於偏差分析。
### 端點回應為 CSV 格式，並包含預測標籤和機率
下表是迴歸和二進制分類問題的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '1,0.6' |
| 兩個記錄 | '1,0.6\$1n0,0.3' |
對於先前的範例，端點輸出預測標籤後跟其機率。將 `predictor` 組態的 `label` 參數設定為欄索引 `0`，並設定 `probability` 為欄索引 `1` 以擷取兩個參數值。
### 端點回應為 CSV 格式，並包含預測標籤和機率 (多類別)
由 Amazon SageMaker Autopilot 訓練的多類別模型容器可以設定為輸出字串表示的預測標籤及機率清單。下列範例表格顯示來自設定為輸出 `predicted_label`、`probability`、`labels` 和 `probabilities` 之模型的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '"狗",0.6,"[\$1'貓\$1', \$1'狗\$1', \$1'魚\$1']","[0.1, 0.6, 0.3]"' |
| 兩個記錄 | '"狗",0.6,"[\$1'貓\$1', \$1'狗\$1', \$1'魚\$1']","[0.1, 0.6, 0.3]"\$1n""貓",0.7,[\$1'貓\$1', \$1'狗\$1', \$1'魚\$1']","[0.7, 0.2, 0.1]"' |
對於先前的範例，可以使用下列方式設定 SageMaker Clarify 處理任務以擷取預測。
對於偏差分析，先前的範例可以設定為下列其中一項。
+ 將 `predictor` 組態的 `label` 參數設定為 `0` 以擷取預測標籤。
+ 將參數設定為 `2` 以擷取預測標籤，並設定 `probability` 為 `3` 以擷取相應的機率。SageMaker Clarify 處理任務可透過識別使用最高機率值的標籤來自動判定預測標籤。參照單一記錄的前一個範例，該模型會預測三個標籤：`cat`、`dog` 和`fish`，其對應機率為 `0.1`、`0.6` 和 `0.3`。根據這些機率，預測標籤是 `dog`，因為它具有 `0.6` 的最高機率值。
+ 設定 `probability` 為 `3`，以擷取機率。如果 `label_headers` 有提供，則 SageMaker Clarify 處理任務可以透過識別使用最高機率值的標籤標題來自動判定預測標籤。
對於功能重要性分析，先前的範例可以設定如下。
+ 設定 `probability` 為 `3` 擷取所有預測標籤的機率。然後，將為所有標示運算功能屬性。如果客戶未指定 `label_headers`，則預測標籤將用作分析報告中的標籤標題。
## 端點回應是 JSON 行格式
如果回應有效負載是 JSON 行格式(MIME 類型：`application/jsonlines`)，SageMaker Clarify 處理任務會將每一行還原序列化作為 JSON 格式匯出格式匯出。然後，它使用分析組態中提供的 JMESPath 表達式從反序列化資料中擷取預測。回應有效負載中的行必須與請求有效負載中的記錄符合。下表顯示了不同格式的回應資料的範例。只要可以根據分析組態擷取預測，您的資料可以與這些範例有所不同。
以下各章節顯示 JSON 行格式的端點回應範例。
### 端點回應採用 JSON 行格式，並且僅包含機率
下表是僅輸出機率值 (分數) 的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"分數":0.6\$1' |
| 兩個記錄 | '\$1"分數":0.6\$1\$1n\$1"分數":0.3\$1' |
對於先前的範例，將分析組態參數設定 `probability` 為 JMESPath 運算式 “score” 以擷取其值。
### 端點回應採用 JSON 行格式，且僅包含預測標籤
下表是僅輸出預測標籤的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"預測":1\$1' |
| 兩個記錄 | '\$1"預測":1\$1\$1n\$1"預測":0\$1' |
對於先前的範例，請將預測值組態的 `label` 參數設定為 JMESPath 運算式 `prediction`。然後，SageMaker Clarify 處理任務可以擷取預測標籤以進行偏差分析。如需詳細資訊，請參閱[分析組態檔案](clarify-processing-job-configure-analysis.md)。
### 端點回應是 JSON 行格式，並包含預測標籤和機率
下表是輸出預測標籤及其分數的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"預測":1,"分數":0.6\$1' |
| 兩個記錄 | '\$1"預測":1,"分數":0.6\$1\$1n\$1"預測":0,"分數分數":0.3\$1' |
對於先前的範例，將組態 `predictor` 的 `label` 參數設為 JMESPath 表達式 “prediction”，以擷取預測標籤。設定`probability`為 JMESPath 表達式 “score” 以擷取機率。如需詳細資訊，請參閱[分析組態檔案](clarify-processing-job-configure-analysis.md)。
### 端點回應採用 JSON 行格式，並包含預測標籤和機率 (多類別)
下表是來自多類別模型的端點回應範例，可輸出下列資訊：
+ 預測標籤的清單。
+ 機率，以及所選擇的預測標籤及其機率。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"predicted\$1label":"狗","機率":0.6,"predicted\$1labels":["貓","狗","魚"],"機率":[0.1,0.6,0.3]\$1' |
| 兩個記錄 | '\$1"predicted\$1label":"狗","機率":0.6,"predicted\$1labels":["貓","狗","魚"],"機率":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1label":"貓","機率":0.7,"predicted\$1labels":["貓","狗","魚"],"機率":[0.7,0.2,0.1]\$1' |
對於先前的範例，可以透過數種方式設定 SageMaker Clarify 處理任務，以擷取預測。
對於偏差分析，先前的範例可以設定為下列其中**一**項。
+ 將 `predictor` 組態的 `label` 參數設定為 JMESPath 表達式 “predicted\$1label”，以擷取預測標籤。
+ 將參數設定為 JMESPath 表達式 “predicted\$1labels” 以擷取預測標籤。設定 `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]' |
| 兩個記錄 | '[0.6,0.3]' |
在先前的範例中，回應有效負載中沒有分行符號。相反地，單一 JSON 物件包含分數清單，請求中每個記錄的各一個分數清單。將分析組態參數設定 `probability` 為 JMESPath 運算式 "[\$1]" 以擷取值。
### 端點回應作為 JSON 格式匯出格式，且僅包含預測標籤
下表是來自僅輸出預測標籤的端點回應範例。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"predicted\$1labels":[1]\$1' |
| 兩個記錄 | '\$1"predicted\$1labels":[1,0]\$1' |
將 `predictor` 組態的 `label` 參數設定為 JMESPath 運算式 “predicted\$1labels”，然後 SageMaker Clarify 處理工作可以擷取預測標籤以進行偏差分析。
### 端點回應是 JSON 格式，並包含預測標籤和機率
下表是來自端點的範例回應，該端點會輸出預測標籤及其分數。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '\$1"預測":[\$1"標籤":1,"分數":0.6\$1' |
| 兩個記錄 | ‘\$1"預測":[\$1"標籤":1,"分數":0.6\$1,\$1"標籤":0,"分數":0.3\$1]\$1' |
對於先前的範例，將組態 `predictor` 的 `label` 參數設定為 JmesPath 表達式 “predictions[\$1].label”，以擷取預測標籤。設定 `probability` 為 JMESPath 表達式 “predictions[\$1].score” 以擷取機率。
### 端點回應採用 JSON 格式，並包含預測標籤和機率 (多類別)
下表是來自端點的範例回應，來自多類別模型的回應，該模型會輸出以下內容：
+ 預測標籤的清單。
+ 機率，以及所選擇的預測標籤及其機率。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一記錄 | '[\$1"predicted\$1label":"狗","機率":0.6,"predicted\$1labels":["貓","狗","魚"],"機率":[0.1,0.6,0.3]\$1]' |
| 兩個記錄 | '[\$1"predicted\$1label":"狗","機率":0.6,"predicted\$1labels":["貓","狗","魚"],"機率":[0.1,0.6,0.3]\$1,\$1"predicted\$1label":"貓","機率":0.7,"predicted\$1labels":["貓","狗","魚"],"機率":[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) 區段中的需求。如果您的模型容器支援批次請求，您可以從單一記錄請求開始，然後嘗試兩個或更多記錄。
下列命令顯示如何使用請求回應 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) 參數的格式。對於 AWS CLI v1，此參數應保持空白。對於第 2 版，此參數應設定為 `--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 範例
上一節中的範例適用於 AWS CLI v2。下列來自端點的請求和回應範例使用 AWS CLI 第 1 版。
## CSV 格式的端點請求和回應
在下列程式碼範例中，請求包含單一記錄，而回應就是其機率值。
```
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
```
在下列程式碼範例中，請求包含兩筆記錄，而回應會包含其機率 (以逗號分隔)。
```
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
```
在下列程式碼範例中，請求包含兩筆記錄，回應會包含其機率，並以分行符號分隔。
```
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
```
在下列程式碼範例中，請求包含單一記錄，而回應是來自包含三個類別之多類別模型的機率值。
```
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
```
在下列程式碼範例中，請求包含兩筆記錄，而回應會包含來自包含三個類別之多類別模型的機率值。
```
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
```
在下列程式碼範例中，請求包含兩筆記錄，而回應包含預測標籤和機率。
```
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
```
在下列程式碼範例中，請求包含兩筆記錄，而回應則包含標籤標題和機率。
```
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 行格式的端點請求和回應
在下列程式碼範例中，請求包含單一記錄，而回應就是其機率值。
```
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}
```
在下列程式碼範例中，請求包含兩筆記錄，而回應包含預測標籤和機率。
```
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}
```
在下列程式碼範例中，請求包含兩筆記錄，而回應包含標籤標題和機率。
```
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 行格式。
```
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 行格式，而回應是 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)。
映像資料集包含一或多個映像檔案。若要識別 SageMaker Clarify 處理任務的輸入資料集，請將名為 `dataset` 的 [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs) 或分析組態 `dataset_uri` 參數設定為您映像檔案的 Amazon S3 URI 字首。
支援的映像檔案格式和副檔名列於下表中。
| 映像格式 | 副檔名 |
| --- | --- |
| JPEG | jpg、jpeg |
| PNG | png |
將分析組態 `dataset_type` 參數設定為 **application/x-image**。由於該類型不是特定的映像檔案格式，因此 `content_type` 將用於決定映像檔案格式和副檔名。
SageMaker Clarify 處理任務會將每個映像檔載入至三維 [NumPy 陣列](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html)，以便進一步處理。這三個維度包含每個像素的高度、寬度和 RGB 值。
## 端點請求格式
SageMaker Clarify 處理任務會將映像的原始 RGB 資料轉換為相容的映像格式，例如 JPEG。它在將資料發送到端點進行預測之前執行此操作。支援的映像格式如下。
| 資料格式 | MIME 類型 | 副檔名 |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg、jpeg |
| PNG | `image/png` | png |
| NPY | `application/x-npy` | 以上全部 |
使用分析組態參數 `content_type` 指定請求有效負載的資料格式。如果 `content_type` 未提供，資料格式預設為 `image/jpeg`。
## 端點回應格式
在收到推論端點調用的回應後，SageMaker Clarify 處理任務還原序列化回應有效負載，然後從中擷取預測。
### 映像分類問題
回應有效負載的資料格式應由分析組態參數 accept\$1type 指定。如果 `accept_type` 未提供，資料格式預設為 `application/json`。支援的格式與表格式資料區段中**表格式資料的端點回應**中所述的格式相同。
如需 SageMaker AI 內建影像分類演算法的範例，請參閱 [使用影像分類演算法進行推論](image-classification.md#IC-inference)，該演算法會接受單一影像，然後傳回一系列機率值 (分數)，每個機率值代表一個類別。
如下表所示，當 `content_type` 參數設定為 `application/jsonlines` 時，回應作為 JSON 格式匯出物件。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單張映像 | '\$1"預測":[0.1,0.6,0.3]\$1' |
在先前的範例中，將 `probability` 參數設定為 JMESPath 表達式 “prediction” 以擷取分數。
當 `content_type` 設定為 `application/json` 時，回應為 JSON 物件，如下表所示。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單張映像 | '[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)。
下表是來自輸出陣列之端點的範例回應。陣列的每個元素都是值陣列，其中包含類別索引、可信度分數，以及偵測到物件的邊界框座標。
| 端點請求有效負載 | 端點回應有效負載 (字串表示) |
| --- | --- |
| 單一映像 (一個物件) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| 單一映像 (兩個物件) | '[[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"預測":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| 單一映像 (兩個物件) | '\$1"預測":[[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 即時推論端點，然後將請求傳送到端點。手動檢查請求和回應。請確定兩者都符合**端點映像資料請求**區段和**映像資料的端點回應**區段中的需求。
以下是兩個程式碼範例，示範如何傳送請求，以及如何檢查映像分類和物件偵測問題的回應。
### 映像分類問題
下列範例程式碼會指示端點讀取 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]]}
```
# 時間序列資料
時間序列資料是指可以載入到二維資料框架中的資料。在框架的每個時間戳記中，每一列代表一筆目標記錄，而每一筆目標記錄都有一個或多個相關資料欄。每個資料框儲存格內的值可以是數值、分類或文字資料類型。
## 時間序列資料集先決條件
在分析之前，請完成必要的預先處理步驟以準備您的資料，例如資料清除或特徵工程。您可以提供一或多個資料集。如果您提供多個資料集，請使用下列其中一個方法，將它們提供給 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)、兩個相關時間序列 (r)，以及兩個靜態共變數 (u)，如下所示：
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
您可以採取三種不同的方法使用 `time_series_data_config` 來編碼資料集，取決於 `dataset_format`。下列幾節會描述每一種方法。
### `dataset_format` 為 `columns` 時的時間序列資料組態
以下範例會將 `columns` 值用於 `dataset_format`。下列 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` 時的時間序列資料組態
以下範例會將 `item_records` 值用於 `dataset_format`。下列 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` 時的時間序列資料組態
以下範例會將 `timestamp_record` 值用於 `dataset_format`。下列 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` 包含來自您資料集的一筆記錄或多筆記錄。您也必須提供 `record_template` 的範本字串，用來建構每筆記錄的 JSON 結構。這些記錄接著會插入至 `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 表達式 |
| --- | --- | --- |
| 單一記錄範例。組態應該是 `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) 參數的格式。對於 AWS CLI v1，此參數應保持空白。對於第 2 版，此參數應設定為 `--cli-binary-format raw-in-base64-out`。
**注意**
AWS CLI v2 預設會以 base64 編碼字串的形式傳遞二進位參數。下列進出端點的請求和回應範例使用 AWS CLI v1。
------
#### [ 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 ]
在下列程式碼範例中，請求包含兩筆記錄。
```
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]}]}
```
------