本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 能批次轉換的自訂推論程式碼
<a name="your-algorithms-batch-code"></a>

本節說明 Amazon SageMaker AI 如何與執行您自有的推論程式碼以進行批次轉換的 Docker 容器互動。請運用本文資訊來撰寫推論程式碼和建立 Docker 映像。

**Topics**
+ [SageMaker AI 執行推論映像的方式](#your-algorithms-batch-code-run-image)
+ [SageMaker AI 載入模型成品的方式](#your-algorithms-batch-code-load-artifacts)
+ [容器處理請求的方式](#your-algorithms-batch-code-how-containe-serves-requests)
+ [容器對推論請求應有的回應方式](#your-algorithms-batch-code-how-containers-should-respond-to-inferences)
+ [容器對運作狀態檢查 (Ping) 請求應有的回應方式](#your-algorithms-batch-algo-ping-requests)

## SageMaker AI 執行推論映像的方式
<a name="your-algorithms-batch-code-run-image"></a>

欲設定容器做為可執行檔來執行，請使用 Dockerfile 的 `ENTRYPOINT` 指示。注意下列事項：
+ 對於批次轉換，SageMaker AI 會代表您調用模型。SageMaker AI 用下列方式執行容器：

  ```
  docker run image serve
  ```

  批次轉換的輸入必須採用可以分割成較小檔案以利平行處理的格式。這些格式包括 CSV、[JSON](https://www.json.org/json-en.html)、[JSON 行](https://jsonlines.org/)、[TFRecord](https://www.tensorflow.org/tutorials/load_data/tfrecord) 和 [RecordIO](https://mesos.apache.org/documentation/latest/recordio/)。

  SageMaker AI 在映像名稱後指定 `serve` 引數，藉此覆寫容器中預設的 `CMD` 陳述式。您在 Dockerfile 中搭配 `CMD` 指令提供的引數，會被 `serve` 引數覆寫。

   
+ 建議使用 `ENTRYPOINT` 指示的 `exec` 格式：

  ```
  ENTRYPOINT ["executable", "param1", "param2"]
  ```

  例如：

  ```
  ENTRYPOINT ["python", "k_means_inference.py"]
  ```

   
+ SageMaker AI 會在您的容器上設定於 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) 和 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) 中指定的環境變數。此外會填入以下環境變數：
  + 容器執行批次轉換時，`SAGEMAKER_BATCH` 設定為 `true`。
  + `SAGEMAKER_MAX_PAYLOAD_IN_MB` 設定為透過 HTTP 傳送到容器的承載最大大小。
  + 容器一次呼叫收到一筆記錄以調用時，`SAGEMAKER_BATCH_STRATEGY` 會設定為 `SINGLE_RECORD`；但當容器收到承載能接受的記錄數量上限時，其會設定為 `MULTI_RECORD`。
  + `SAGEMAKER_MAX_CONCURRENT_TRANSFORMS` 設為 `/invocations` 請求可同時開啟的數量上限。
**注意**  
最後三個環境變數來自使用者發出的 API 呼叫。如果使用者不設定其值，就不傳遞。在這種情況下，會使用預設值或演算法請求的值 (回應 `/execution-parameters`)。
+ 如果您計劃在模型推論中使用 GPU 裝置 (在您的 `CreateTransformJob` 請求中指定以 GPU 為基礎的機器學習 (ML) 運算執行個體)，請確保您的容器與 nvidia-docker 相容。請勿將 NVIDIA 驅動程式與映像整合成套件。如需 nvidia-docker 的詳細資訊，請參閱 [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker)。

   
+ 您無法將 `init` 初始設定式作為 SageMaker AI 容器的進入點使用，因為訓練和服務引數會混淆該設定式。

  

## SageMaker AI 載入模型成品的方式
<a name="your-algorithms-batch-code-load-artifacts"></a>

在 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) 請求中，容器定義包含 `ModelDataUrl` 參數，該參數可識別出儲存模型成品的 Amazon S3 位置。使用 SageMaker AI 執行推論時，其使用此資訊來決定從哪裡複製模型成品。其會將成品複製到 Docker 容器的 `/opt/ml/model` 目錄內，以供您的推論程式碼使用。

`ModelDataUrl` 參數必須指向 tar.gz 檔案。否則，SageMaker AI 無法下載檔案。如果您在 SageMaker AI 中訓練模型，其會將成品作為單一壓縮 tar 檔案儲存在 Amazon S3 中。如果您在另一個架構中訓練模型，則需要將模型成品以壓縮的 tar 檔案形式存放在 Amazon S3 中。SageMaker AI 會在批次轉換任工作開始之前將此 tar 檔案解壓縮，並將其儲存在容器中的 `/opt/ml/model` 目錄。

## 容器處理請求的方式
<a name="your-algorithms-batch-code-how-containe-serves-requests"></a>

容器必須實作一個 Web 伺服器，用以在 8080 連接埠上回應調用和 ping。對於批次轉換，您可以選擇設定演算法來實作執行參數請求，以提供動態執行期組態給 SageMaker AI。SageMaker AI 使用下列端點：
+ `ping` — 用於定期檢查容器的運作狀態。SageMaker AI 會等待成功 ping 請求的 HTTP `200` 狀態碼和空內文，然後才傳送調用請求。您可以使用 ping 請求來將模型載入到記憶體，以便在傳送調用請求時產生推論。
+ (選用) `execution-parameters` — 允許演算法在執行期為工作提供最佳的調校參數。根據容器可用的記憶體和 CPU，演算法會為工作選擇適當的 `MaxConcurrentTransforms`、`BatchStrategy` 和 `MaxPayloadInMB` 值。

呼叫調用請求之前，SageMaker AI 會嘗試調用執行參數請求。建立批次轉換工作時，您可以提供 `MaxConcurrentTransforms`、`BatchStrategy` 和 `MaxPayloadInMB` 參數的值。SageMaker AI 使用此優先順序來決定這些參數的值：

1. 您建立 `CreateTransformJob` 請求時提供的參數值。

1. SageMaker AI 調用執行參數端點時，模型容器傳回的值。

1. 下表列出的預設參數值。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/your-algorithms-batch-code.html)

`GET` 執行參數請求的回應是 JSON 物件，具有 `MaxConcurrentTransforms`、`BatchStrategy` 和 `MaxPayloadInMB` 參數的索引鍵。這是有效回應的範例：

```
{
“MaxConcurrentTransforms”: 8,
“BatchStrategy": "MULTI_RECORD",
"MaxPayloadInMB": 6
}
```

## 容器對推論請求應有的回應方式
<a name="your-algorithms-batch-code-how-containers-should-respond-to-inferences"></a>

為了獲得推論，Amazon Sagemaker AI 會傳送一個 POST 請求到推論容器。POST 請求內文包含來自 Amazon S3 的資料。Amazon SageMaker AI 將請求傳遞至容器，再從容器傳回推論結果，將回應中的資料儲存到 Amazon S3。

為了接收推論請求，容器必須擁有可以監聽 8080 連接埠的 Web 伺服器，且需接受對 `/invocations` 端點的 POST 請求。可透過 `[ModelClientConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelClientConfig.html)` 設定推論請求逾時和重試次數上限。

## 容器對運作狀態檢查 (Ping) 請求應有的回應方式
<a name="your-algorithms-batch-algo-ping-requests"></a>

容器上最簡單的請求是以 HTTP 200 狀態碼和空內文做為回應。這是通知 SageMaker AI，容器已準備好可在 `/invocations` 端點接受推論請求。

雖然容器的最低標準是傳回靜態的 200，容器開發人員也能運用此功能來進行更加深入的檢查。`/ping` 嘗試的請求逾時為 2 秒。