本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 預先檢查模型容器 本節說明如何在設定端點之前預先檢查模型容器輸入及輸出的相容性。SageMaker Clarify 解釋器與**模型無關**，但它對模型容器輸入及輸出有要求。 **注意** 您可以將容器設定為支援批次請求 (在單一請求支援兩個或多個記錄)，藉此提高效率。例如，單筆記錄是單行 CSV 資料，或單行 JSON Lines 資料。SageMaker Clarify 會先嘗試將一個小批次的記錄傳送至模型容器，然後再傳回單筆記錄請求。 ## 模型容器輸入 ------ #### [ CSV ] 模型容器支援使用 MIME 類型為 CSV 格式的輸入：`text/csv`。下表顯示 SageMaker Clarify 支援的範例輸入。 | 模型容器輸入 (字串表示) | 說明 | | --- | --- | | '1,2,3,4' | 使用四個數字特徵的單筆記錄。 | | '1,2,3,4\$1n5,6,7,8' | 兩個記錄，由分行符號 '\$1n' 分隔。 | | '"這是一個好產品",5' | 包含文字特徵與數字特徵的單筆記錄。 | | ‘"這是一個好產品",5\$1n"糟糕的購物體驗",1' | 兩個記錄。 | ------ #### [ JSON Lines ] SageMaker AI 也支援使用 MIME 類型：`application/jsonlines` 的 [JSON Lines 集格式](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)輸入，如下表所示。 | 模型容器輸入 | 說明 | | --- | --- | | '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 單筆記錄；可以透過 JMESPath 運算式 `data.features` 提取特徵清單。 | | '\$1"data":\$1"features":[1,2,3,4]\$1\$1\$1n\$1"data":\$1"features":[5,6,7,8]\$1\$1' | 兩個記錄。 | | '\$1"features":["這是一個好產品",5]\$1' | 單筆記錄；可以透過 JMESPath 運算式 `features` 提取特徵清單。 | | '\$1"features":["這是一個好產品",5]\$1\$1n\$1"features":["糟糕的購物體驗",1]\$1' | 兩筆記錄。 | ------ ## 模型容器輸出 您的模型容器輸出也應採用 CSV 或 JSON Lines 密集格式。此外，模型容器應包含輸入記錄的機率，SageMaker Clarify 使用這些記錄來計算特徵屬性。 下列資料範例適用於 **CSV 格式**的模型容器輸出。 ------ #### [ Probability only ] 對於迴歸及二進制分類問題，模型容器輸出預測標籤的單個機率值 (分數)。可以使用列索引 0 來提取這些機率。對於多類問題，模型容器輸出機率 (分數) 清單。對於多類問題，如果未提供索引，則提取所有值。 | 模型容器輸入 | 模型容器輸出 (字串表示) | | --- | --- | | 單筆記錄 | '0.6' | | 兩筆記錄 (結果在一行) | '0.6,0.3' | | 兩筆記錄 (結果分為兩行) | '0.6\$1n0.3' | | 多類模型的單筆記錄 (三個類別) | '0.1,0.6,0.3' | | 多類模型的兩筆記錄 (三個類別) | '0.1,0.6,0.3\$1n0.2,0.5,0.3' | ------ #### [ Predicted label and probabilities ] 模型容器以 **CSV** 格式輸出預測標籤及其機率。可以使用索引 `1` 提取機率。 | 模型容器輸入 | 模型容器輸出 | | --- | --- | | 單筆記錄 | '1,0.6' | | 兩個記錄 | '1,0.6\$1n0,0.3' | ------ #### [ Predicted labels header and probabilities ] 由 Autopilot 訓練的多類別模型容器可以設定為以 **CSV** 格式輸出預測標籤及機率清單的**字串表示**形式。在下列範例中，可以透過索引 `1` 提取機率。標籤頭可以透過索引提取 `1`，並且可以使用索引 `0` 提取標籤頭。 | 模型容器輸入 | 模型容器輸出 | | --- | --- | | 單筆記錄 | '"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.1,0.6,0.3]"' | | 兩筆記錄 | '"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.1,0.6,0.3]"\$1n"[\$1'cat\$1',\$1'dog\$1',\$1'fish\$1']","[0.2,0.5,0.3]"' | ------ 下列資料範例適用於 **JSON Lines** 格式的模型容器輸出。 ------ #### [ Probability only ] 在此範例中，模型容器以 **JSON Lines** 格式輸出可由 [https://jmespath.org/](https://jmespath.org/) 運算式 `score` 提取的機率。 | 模型容器輸入 | 模型容器輸出 | | --- | --- | | 單筆記錄 | '\$1"分數":0.6\$1' | | 兩個記錄 | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' | ------ #### [ Predicted label and probabilities ] 在此範例中，多類別模型容器會輸出標籤標題清單，以及 **JSON Lines** 格式的機率清單。機率可以透過 `JMESPath` 運算式提取 `probability`，標籤頭可以透過 `JMESPath` 運算式提取 `predicted labels`。 | 模型容器輸入 | 模型容器輸出 | | --- | --- | | 單筆記錄 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' | | 兩筆記錄 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]\$1' | ------ #### [ Predicted labels header and probabilities ] 在此範例中，多類別模型容器會以 **JSON Lines** 格式輸出標籤標題及機率清單。機率可以透過 `JMESPath` 運算式提取 `probability`，標籤頭可以透過 `JMESPath` 運算式提取 `predicted labels`。 | 模型容器輸入 | 模型容器輸出 | | --- | --- | | 單筆記錄 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' | | 兩筆記錄 | '\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]\$1' | ------ ## 模型容器驗證 我們建議您將模型部署到 SageMaker AI 即時推論端點，然後將請求傳送到端點。手動檢查請求 (模型容器輸入) 及回應 (模型容器輸出)，以確保兩者都符合**模型容器輸入**部分與**模型容器輸出**部分中的需求。如果您的模型容器支援批次請求，您可以從單筆記錄請求開始，然後嘗試兩個或更多記錄。 下列命令顯示如何使用請求回應 AWS CLI。 AWS CLI 已預先安裝在 SageMaker Studio Classic 與 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 預設會將二進位參數傳遞為 base64 編碼字串[https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam)。 下列範例使用 AWS CLI v1： ------ #### [ Request and response in CSV format ] + 請求由單筆記錄組成，回應是其機率值。 ``` 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` + 請求由兩筆記錄組成，回應包括其機率，並且模型用逗號分隔機率。`--body` 中的 `$'content'` 運算式告訴命令將內容中的 `\n` 解釋為分行符號。 ``` 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 ``` 輸出： `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]"` ------ #### [ Request and response in JSON Lines format ] + 請求由單筆記錄組成，回應是其機率值。 ``` 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]}` ------ #### [ Request and response in different formats ] + 請求採用 CSV 格式，回應採用 JSON Lines 格式： ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-in-jsonlines-out \ --content-type text/csv \ --accept application/jsonlines \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` 輸出： `{"probability":0.6}` `{"probability":0.3}` + 請求採用 JSON Lines 格式，回應採用 CSV 格式： ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-jsonlines-in-csv-out \ --content-type application/jsonlines \ --accept text/csv \ --body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \ /dev/stderr 1>/dev/null ``` 輸出： `0.6` `0.3` ------ 驗證完成後，[刪除](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html)測試端點。