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

# 多模型端點的自訂容器合約
<a name="mms-container-apis"></a>

若要處理多個模型，容器必須支援一組可讓 Amazon SageMaker AI 與容器進行溝通的 API，以視需要載入、列出、取得和取消載入模型。`model_name` 會用於新的 API 集，做為金鑰輸入參數。客戶容器應使用 `model_name` 做為對應金鑰來追蹤已載入的模型。此外，`model_name` 是不透明的識別符，且未必是傳遞到 `InvokeEndpoint` API 的 `TargetModel` 參數的值。`InvokeEndpoint` 請求中的原始 `TargetModel` 值會傳遞到 API 中的容器，做為可用於記錄用途的 `X-Amzn-SageMaker-Target-Model` 標題。

**注意**  
GPU 支援執行個體的多模型端點目前僅支援 SageMaker AI 的 [NVIDIA Triton 推論伺服器容器](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)。此容器已經實作如下定義的合同。客戶可直接搭配使用此容器與多模型 GPU 端點，無需進行任何額外工作。

您可於容器為 CPU 支援的多模型端點設定下列 API。

**Topics**
+ [Load Model API](#multi-model-api-load-model)
+ [List Model API](#multi-model-api-list-model)
+ [Get Model API](#multi-model-api-get-model)
+ [Unload Model API](#multi-model-api-unload-model)
+ [調用模型 API](#multi-model-api-invoke-model)

## Load Model API
<a name="multi-model-api-load-model"></a>

指示容器將主體 `url` 欄位中現有的特定模型載入到客戶容器記憶體中，並使用獲派的 `model_name` 進行追蹤。載入模型後，容器應該已準備就緒，可使用此 `model_name` 為推斷請求提供服務。

```
POST /models HTTP/1.1
Content-Type: application/json
Accept: application/json

{
     "model_name" : "{model_name}",
     "url" : "/opt/ml/models/{model_name}/model",
}
```

**注意**  
若已載入 `model_name`，此 API 應傳回 409。凡是由於記憶體或任何其他資源不足而無法載入模型時，此 API 皆應傳回 507 HTTP 狀態碼給 SageMaker AI，接著它會發起取消載入未使用的模型以重新取得。

## List Model API
<a name="multi-model-api-list-model"></a>

傳回已載入到客戶容器的記憶體的模型清單。

```
GET /models HTTP/1.1
Accept: application/json

Response = 
{
    "models": [
        {
             "modelName" : "{model_name}",
             "modelUrl" : "/opt/ml/models/{model_name}/model",
        },
        {
            "modelName" : "{model_name}",
            "modelUrl" : "/opt/ml/models/{model_name}/model",
        },
        ....
    ]
}
```

此 API 也支援分頁。

```
GET /models HTTP/1.1
Accept: application/json

Response = 
{
    "models": [
        {
             "modelName" : "{model_name}",
             "modelUrl" : "/opt/ml/models/{model_name}/model",
        },
        {
            "modelName" : "{model_name}",
            "modelUrl" : "/opt/ml/models/{model_name}/model",
        },
        ....
    ]
}
```

SageMaker AI 不需要提供值給 `next_page_token` 即可在一開始呼叫列出模型 API。如果回應中傳回了 `nextPageToken` 欄位，則會提供該欄位做為後續 List Models 呼叫中 `next_page_token` 的值。若未傳回 `nextPageToken`，則表示沒有其他要傳回的模型。

## Get Model API
<a name="multi-model-api-get-model"></a>

這是 `model_name` 實體上的簡易讀取 API。

```
GET /models/{model_name} HTTP/1.1
Accept: application/json

{
     "modelName" : "{model_name}",
     "modelUrl" : "/opt/ml/models/{model_name}/model",
}
```

**注意**  
若未載入 `model_name`，此 API 應傳回 404。

## Unload Model API
<a name="multi-model-api-unload-model"></a>

指示 SageMaker AI 平台引導客戶容器從記憶體中取消載入模型。這會根據平台在開始載入新模型程序時的判斷，發起移出候選模型。當此 API 傳回回應時，佈建到 `model_name` 的資源應由容器重新取得。

```
DELETE /models/{model_name}
```

**注意**  
若未載入 `model_name`，此 API 應傳回 404。

## 調用模型 API
<a name="multi-model-api-invoke-model"></a>

從提供的特定 `model_name` 提出預測請求。SageMaker AI 執行時期 `InvokeEndpoint` 請求支援利用 `X-Amzn-SageMaker-Target-Model` 做為新標題，這會採用針對調用指定模型的相對路徑。SageMaker AI 系統會將 `CreateModel` API 呼叫提供的字首與模型的相對路徑加以結合，藉此建構模型的絕對路徑。

```
POST /models/{model_name}/invoke HTTP/1.1
Content-Type: ContentType
Accept: Accept
X-Amzn-SageMaker-Custom-Attributes: CustomAttributes
X-Amzn-SageMaker-Target-Model: [relativePath]/{artifactName}.tar.gz
```

**注意**  
若未載入 `model_name`，此 API 應傳回 404。

此外，在 GPU 執行個體，如 `InvokeEndpoint` 因記憶體或其他資源不足而失敗，則此 API 應將 507 HTTP 狀態碼傳回給 SageMaker AI，然後啟動卸載未使用模型以便進行回收。