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

# 即時推論


 即時推論非常適合滿足您即時、互動式、低延遲需要的推論工作負載。您可以將模型部署到 SageMaker AI 託管服務，並取得可用於推論的端點。這些端點是完全受管且支援自動調度資源 (請參閱[Amazon SageMaker AI 模型的自動擴展](endpoint-auto-scaling.md))。

**Topics**
+ [

# 部署用於即時推論的模型
](realtime-endpoints-deploy-models.md)
+ [

# 調用模型以進行即時推論
](realtime-endpoints-test-endpoints.md)
+ [

# 端點
](realtime-endpoints-manage.md)
+ [

# 託管選項
](realtime-endpoints-options.md)
+ [

# Amazon SageMaker AI 模型的自動擴展
](endpoint-auto-scaling.md)
+ [

# 執行個體存放區磁碟區
](host-instance-storage.md)
+ [

# 驗證生產環境中的模型
](model-validation.md)
+ [

# SageMaker Clarify 線上可解釋性
](clarify-online-explainability.md)
+ [

# 使用轉接器推論元件微調模型
](realtime-endpoints-adapt.md)

# 部署用於即時推論的模型
部署模型

**重要**  
允許 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 建立 Amazon SageMaker 資源的自訂 IAM 政策也必須授予許可，才能將標籤新增至這些資源。需要將標籤新增至資源的許可，因為 Studio 和 Studio Classic 會自動標記它們建立的任何資源。如果 IAM 政策允許 Studio 和 Studio Classic 建立資源，但不允許標記，則在嘗試建立資源時可能會發生 "AccessDenied" 錯誤。如需詳細資訊，請參閱[提供標記 SageMaker AI 資源的許可](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
提供許可來建立 SageMaker 資源的 [AWS Amazon SageMaker AI 的 受管政策](security-iam-awsmanpol.md) 已包含建立這些資源時新增標籤的許可。

有數個選項可以使用 SageMaker AI 託管服務部署模型。您可以使用 SageMaker Studio 以互動方式部署模型。或者，您可以使用 AWS SDK 以程式設計方式部署模型，例如 SageMaker Python SDK 或 SDK for Python (Boto3)。您也可以使用 部署 AWS CLI。

## 開始之前


在您部署 SageMaker AI 模型之前，請先找出並記下以下內容：
+ Amazon S3 AWS 區域 儲存貯體所在的
+ 儲存模型成品的 Amazon S3 URI 路徑
+ 適用於 SageMaker AI 的 IAM 角色
+ 自訂映像的 Docker Amazon ECR URI 登錄檔路徑，其中包含推論程式碼，或 支援和 的內建 Docker 映像架構和版本 AWS

 如需每個 中 AWS 服務 可用的清單 AWS 區域，請參閱[區域地圖和邊緣網路](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。如需如何建立 IAM 角色的相關資訊，請參閱[建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。

**重要**  
儲存模型成品的 Amazon S3 儲存貯體，必須位在您建立模型的相同 AWS 區域 。

## 與多個模型共享資源使用率
共享資源使用率

您可以使用 Amazon SageMaker AI 將一個或多個模型部署至端點。多個模型共用端點時，也會共用在該處託管的資源，例如 ML 運算執行個體、CPU 和加速器。部署多個模型到端點的最靈活方是將每個模型定義為*推論元件*。

### 推論元件


推論元件是 SageMaker AI 託管物件，可以用來將模型部署到端點。在推論元件設定中，您可以指定模型、端點，以及模型如何利用端點託管的資源。若要指定模型，您可以指定 SageMaker AI 模型物件，也可以直接指定模型成品和影像。

在設定中，您可以自訂所需 CPU 核心、加速器和記憶體配置給模型的方式，以最佳化資源使用率。您可以將多個推論元件部署到端點，其中每個推論元件包含一個模型，以及該模型的資源使用率需求。

部署推論元件之後，您可以在 SageMaker API 中使用 InvokeEndpoint 動作時直接調用相關聯的模型。

推論元件具有以下優點：

**彈性**  
推論元件會從端點本身分離託管模型的詳細資訊。這麼一來，您可以更靈活地控制模型的託管方式和端點提供該模型的方式。您可以在相同的基礎架構上託管多個模型，也可以根據需求從端點新增或移除模型。您可以獨立更新每個模型。

**可擴展性**  
您可以指定每個模型要託管的複本數量，也可以設定複本數量下限，以確保模型能夠載入您處理請求時所需的數量。您可以將任何推論元件複本縮減為零，讓其他複本有向上擴展的空間。

當您透過以下方式部署模型時，SageMaker AI 會將模型封裝為推論元件：
+ SageMaker Studio Classic。
+ 部署模型物件的 SageMaker Python SDK (您在其中將端點類型設為 `EndpointType.INFERENCE_COMPONENT_BASED`)。
+  適用於 Python (Boto3) 的 AWS SDK 定義您部署到端點的`InferenceComponent`物件。

## 透過 SageMaker Studio 部署模型
透過 Studio 進行部署

請完成以下步驟，透過 SageMaker Studio 以互動方式建立和部署模型。如需進一步瞭解 Studio，請參閱 [Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio.html) 文件。如需更多多種部署案例演練，請參閱部落格[使用 Amazon SageMaker AI 輕鬆套件和部署傳統 ML 模型和 LLM – 第 2 部分](https://aws.amazon.com/blogs/machine-learning/package-and-deploy-classical-ml-and-llms-easily-with-amazon-sagemaker-part-2-interactive-user-experiences-in-sagemaker-studio/)。

### 準備您的成品和許可


在 SageMaker Studio 中建立模型之前，請先完成本區段。

您可以透過兩種方式，在 Studio 中納入成品和建立模型：

1. 您可以先準備好預先封裝的 `tar.gz` 封存，其中應包含模型成品、任何自訂推論程式碼，以及 `requirements.txt` 檔案中列出的任何相依項目。

1. SageMaker AI 可以幫您封裝成品。您只需要在 `requirements.txt` 檔案中納入原始模型成品和任何相依項目，SageMaker AI 可以為您提供預設推論程式碼；或者您可以使用自己的自訂推論程式碼覆寫預設程式碼。針對這種方式，SageMaker AI 支援下列架構：PyTorch、XGBoost。

除了攜帶您的模型、您的 AWS Identity and Access Management (IAM) 角色和 Docker 容器 （或 SageMaker AI 具有預先建置容器的所需架構和版本），您還必須授予透過 SageMaker AI Studio 建立和部署模型的許可。

您應該將 [AmazonSageMakerFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html) 政策連接到您的 IAM 角色，以便您存取 SageMaker AI 和其他相關服務。若要查看 Studio 中執行個體類型的價格，您還必須連接 [AWS PriceListServiceFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSPriceListServiceFullAccess.html) 政策；或者如果您不想連接整個政策 (具體來說是 `pricing:GetProducts` 動作)。

如果您在建立模型時選擇上傳模型成品或上傳範例承載檔案以取得推論建議，則您必須建立 Amazon S3 儲存貯體。儲存貯體名稱的字首必須是 `SageMaker AI`。或者也可以是 SageMaker AI 的替代大寫：`Sagemaker` 或 `sagemaker`。

建議您使用儲存貯體命名慣例 `sagemaker-{Region}-{accountID}`。此儲存貯體會用來存放您上傳的成品。

建立儲存貯體之後，請將下列 CORS (跨來源資源共用) 政策連接至儲存貯體：

```
[
    {
        "AllowedHeaders": ["*"],
        "ExposeHeaders": ["Etag"],
        "AllowedMethods": ["PUT", "POST"],
        "AllowedOrigins": ['https://*.sagemaker.aws'],
    }
]
```

您可以透過以下任一方式，將 CORS 政策連接至 Amazon S3 儲存貯體：
+ 透過 Amazon S3 主控台的[編輯跨來源資源共用 (CORS)](https://s3.console.aws.amazon.com/s3/bucket/bucket-name/property/cors/edit) 頁面
+ 使用 Amazon S3 API [PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html)
+ 使用 put-bucket-cors AWS CLI 命令：

  ```
  aws s3api put-bucket-cors --bucket="..." --cors-configuration="..."
  ```

### 建立可部署模型


在此步驟中，您可以提供成品和其他規格，例如所需的容器和架構、任何自訂推論程式碼和網路設定，在 SageMaker AI 中建立可部署的模型版本。

請執行以下動作，在 SageMaker Studio 中建立可部署模型：

1. 開啟您的 SageMaker Studio 應用程式。

1. 在左側導覽窗格中選擇 **Models (模型)**。

1. 選擇**可部署模型**索引標籤。

1. 在**可部署模型**頁面上，選擇**建立**。

1. 在**建立可部署模型**頁面上的**模型名稱**欄位中，輸入模型的名稱。

在**建立可部署模型**頁面上還有一些需要填寫的區段。

**容器定義**區段如下螢幕擷取畫面：

![\[在 Studio 中建立模型的容器定義區段螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-container-definition.png)


**請在**容器定義**區段中，執行下列動作：**

1. 在**容器類型**中，如果您要使用 SageMaker AI 受管容器，請選取**預先建置的容器**，如果您有自己的容器，請選取**使用自有容器**。

1. 如果您選取**預先建置的容器**，請選取您要使用的**容器架構**、**架構版本**和**硬體類型**。

1. 如果您選取**使用自有容器**，請輸入**容器影像的 ECR 路徑**的 Amazon ECR 路徑。

接著填寫**成品**區段，請參考如下螢幕擷取畫面：

![\[在 Studio 中建立模型的成品區段螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-artifacts-section.png)


**請在**成品**區段中，執行下列動作：**

1. 如果您使用 SageMaker AI 所支援的架構 (PyTorch 或 XGBoost) 來封裝模型成品，則您可以在**成品**選擇**上傳成品**選項。您可以透過這個選項直接指定原始模型成品、您擁有的任何自訂推論程式碼，以及您的 requirements.txt 檔案，而 SageMaker AI 會幫您封裝封存。請執行下列操作：

   1. 在**成品**選取**上傳成品**以繼續提供您的檔案。如果您已經有包含模型檔案、推論程式碼和 `requirements.txt` 檔案的 `tar.gz` 封存，請選取**預先封裝成品的輸入 S3 URI**。

   1. 如果您選擇上傳成品，則請在 **S3 儲存貯體**輸入您希望 SageMaker AI 在封裝成品之後存放成品的儲存貯體 Amazon S3 路徑。然後，請完成下列步驟。

   1. 在**上傳模型成品**上傳您的模型檔案。

   1. 針對**推論程式碼**，如果您要使用 SageMaker AI 提供的預設程式碼來提供推論，請選取**使用預設推論程式碼**。否則請選取**上傳自訂推論程式碼**，使用您自有的推論程式碼。

   1. 針對**上傳 requirements.txt**，請上傳文字檔案，其中列出您想在執行時期安裝的任何相依項目。

1. 如果您未使用 SageMaker AI 支援的架構來封裝模型成品，Studio 會顯示**預先封裝成品**選項，您必須提供已封裝為 `tar.gz` 封存的所有成品。請執行下列操作：

   1. 針對**預先封裝的成品**，如果您的 `tar.gz` 封存已上傳至 Amazon S3，請選取**預先封裝模型成品的輸入 S3 URI**。如果您想將封存直接上傳至 SageMaker AI，請選取**上傳預先封裝的模型成品**。

   1. 如果您選取**預先封裝模型成品的輸入 S3 URI**，請輸入 **S3 URI** 的封存 Amazon S3 路徑。否則請從本機電腦選取並上傳封存。

下一部分是**安全性**，其螢幕擷取畫面如下：

![\[在 Studio 中建立模型的安全性區段螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-security-section.png)


**請針對**安全性**區段執行以下動作：**

1. 針對 **IAM 角色**輸入 IAM 角色的 ARN。

1. (選用) 針對**虛擬私有雲端 (VPC)**，您可以選取一個 Amazon VPC 來存放模型組態和成品。

1. (選用) 如果您想限制容器的網際網路存取，請開啟**網路隔離**。

最後，您可以填寫**進階選項**區段，其螢幕擷取畫面如下：

![\[在 Studio 中建立模型的進階選項區段螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-advanced-options.png)


**(選用) 請在**進階選項**區段中，執行下列動作：**

1. 如果您想在建立模型之後在模型上執行 Amazon SageMaker Inference Recommender 任務，請開啟**自訂執行個體建議**。推論建議程式是一項功能，可以為您提供最佳化推論效能和成本的建議執行個體類型。您可以在準備部署模型時檢視這些執行個體建議。

1. 在**新增環境變數**中，輸入容器的環境變數做為鍵值組。

1. 在**標籤**中，輸入任何標籤做為鍵值組。

1. 完成模型和容器組態後，選擇**建立可部署模型**。

現在，您在 SageMaker Studio 中應該已經擁有準備好進行部署的模型。

### 部署模型


最後，請將您在上一個步驟中設定的模型部署到 HTTPS 端點。您可以將一個或多個模型部署到端點。

**模型和端點相容性**  
模型和端點必須具有以下相同設定值，才能將模型部署至端點：  
IAM 角色
Amazon VPC，包括其子網路和安全群組
網路隔離 (啟用或停用)
Studio 會透過以下方式，防止您將模型部署至不相容的端點：  
如果您嘗試將模型部署到新端點，SageMaker AI 會使用相容的初始設定來設定端點。如果您因變更這些設定而導致不相容，Studio 會顯示警示並防止部署。
如果您嘗試部署到現有端點且該端點不相容，Studio 會顯示警示並防止部署。
如果您嘗試將多個模型新增至部署，Studio 會防止您部署彼此不相容的模型。
當 Studio 顯示模型和端點不相容的警示時，您可以選擇在警示中**檢視詳細資訊**，查看哪些設定不相容。

其中一種部署模型的方法是在 Studio 中執行下列動作：

1. 開啟您的 SageMaker Studio 應用程式。

1. 在左側導覽窗格中選擇 **Models (模型)**。

1. 在**模型**頁面上，從 SageMaker AI 模型清單中選取一個或多個模型。

1. 選擇**部署**。

1. 針對**端點名稱**，開啟下拉式功能表。您可以選取現有端點，也可以建立要部署模型的新端點。

1. 針對**執行個體類型**，選取您要用於端點的執行個體類型。如果您先前已經為模型執行推論建議程式任務，您的建議執行個體類型會顯示在**建議**標題下的清單中。否則您會看到可能適合您模型的**潛在執行個體**。
**JumpStart 的執行個體類型相容性**  
如果您要部署 JumpStart 模型，Studio 只會顯示模型所支援的執行個體類型。

1. 針對**初始執行個體數量**，輸入您要為端點佈建的執行個體初始數量。

1. 針對**執行個體數量上限**，指定端點擴展時可佈建的執行個體數量上限，以因應流量提升。

1. 如果您要部署的模型是從模型中樞最常使用的 JumpStart LLM 之一，則執行個體類型和執行個體數量欄位後會顯示**替代組態**選項。

   對於最熱門的 JumpStart LLM， AWS 具有預先標記的執行個體類型，可最佳化成本或效能。 LLMs 這份資料可以協助您決定要用於部署 LLM 的執行個體類型。選擇**替代組態**以開啟包含預先標記資料的對話方塊。該面板外觀如下螢幕擷取畫面：  
![\[替代組態方塊的螢幕擷取畫面\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-jumpstart-alternate-configurations.png)

   請在**替代組態**方塊中，執行下列動作：

   1. 選取執行個體類型。您可以選擇**每小時成本**或**最佳效能**，查看最佳化指定模型的成本或效能的執行個體類型。您也可以選擇**其他支援的執行個體**，查看與 JumpStart 模型相容的其他執行個體類型。請注意，在此處選取的執行個體類型會覆寫步驟 6 中指定的任何先前執行個體。

   1. (選用) 開啟**自訂所選組態**，以指定**總記號數量上限** (記號數量上限，即輸入記號和模型產生的輸出總和)、**輸入記號長度上限** (每個請求輸入的記號數量上限) 和**並行請求上限** (模型一次可處理的請求數量上限)。

   1. 選擇**選取**，確認您的執行個體類型和組態設定。

1. **模型**欄位應該已填入您要部署的模型名稱。您可以選擇**新增模型**，將更多模型新增至部署。請針對您新增的每個模型，填寫下列欄位：

   1. 針對 **CPU 核心數量**，輸入您要專用於模型使用的 CPU 核心。

   1. 針對**複本數量下限**，輸入您在任何時間要在端點上託管的最少模型複本數量。

   1. 針對 **CPU 記憶體下限 (MB)**，輸入模型所需的記憶體數量下限 (以 MB 為單位)。

   1. 針對 **CPU 記憶體上限 (MB)**，輸入您允許模型使用的記憶體數量上限 (以 MB 為單位)。

1. (選用) 請在**進階選項**中，執行下列動作：

   1. 針對 **IAM 角色**，使用預設 SageMaker AI IAM 執行角色，或指定具所需許可的自有角色。請注意，此 IAM 角色必須與您在建立可部署模型時指定的角色相同。

   1. 針對**虛擬私有雲端 (VPC)**，您可以指定要負責託管端點的 VPC。

   1. 針對**加密 KMS 金鑰**，選取 AWS KMS 金鑰來加密連接至託管端點之 ML 運算執行個體的儲存磁碟區上的資料。

   1. 開啟**網路隔離**，限制容器的網際網路存取。

   1. 針對**逾時組態**，輸入**模型資料下載逾時 (秒)** 和**容器啟動運作狀態檢查逾時 (秒)** 欄位的值。這些值會決定 SageMaker AI 分別可以將模型下載至容器和啟動容器的時間上限。

   1. 在**標籤**中，輸入任何標籤做為鍵值組。
**注意**  
SageMaker AI 會使用與您部署的模型相容的初始值來設定 IAM 角色、VPC 和網路隔離設定。如果您因變更這些設定而導致不相容，Studio 會顯示警示並防止部署。

設定選項後，頁面應該如下螢幕擷取畫面。

![\[Studio 中部署模型頁面的螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-deploy-realtime-model-2.png)


設定部署後，選擇**部署**以建立端點並部署模型。

## 使用 Python SDK 部署模型
使用 Python 進行部署

您可以透過 SageMaker Python SDK，以兩種方式建置模型。第一個方式是從 `Model` 或 `ModelBuilder` 類別建立模型物件。如果您使用 `Model` 類別建立 `Model` 物件，您需要指定模型套件或推論程式碼 (取決於您的模型伺服器)、處理用戶端和伺服器之間資料序列化和還原序列化的指令碼，以及要上傳到 Amazon S3 供使用的任何相依項目。第二個方式是使用提供模型成品或推論程式碼的 `ModelBuilder`。`ModelBuilder` 會自動擷取您的相依項目、推論所需序列化和還原序列化函數，並封裝您的相依項目以建立 `Model` 物件。如需 `ModelBuilder` 的相關資訊，請參閱 [使用 ModelBuilder 在 Amazon SageMaker AI 建立模型](how-it-works-modelbuilder-creation.md)。

下一個部分將說明兩種建立模型和部署模型物件的方法。

### 設定


以下是準備模型部署程序的範例。過程中會匯入必要的程式庫，並定義尋找模型成品的 S3 URL。

------
#### [ SageMaker Python SDK ]

**Example 匯入陳述式**  
以下範例會從 SageMaker Python SDK、SDK for Python (Boto3) 和 Python 標準程式庫匯入模組。這些模組能有效協助您部署模型，而這些模型也會用於後續的其他範例。  

```
import boto3
from datetime import datetime
from sagemaker.compute_resource_requirements.resource_requirements import ResourceRequirements
from sagemaker.predictor import Predictor
from sagemaker.enums import EndpointType
from sagemaker.model import Model
from sagemaker.session import Session
```

------
#### [ boto3 inference components ]

**Example 匯入陳述式**  
以下範例會從 SDK for Python (Boto3) 和 Python 標準程式庫匯入模組。這些模組能有效協助您部署模型，而這些模型也會用於後續的其他範例。  

```
import boto3
import botocore
import sys
import time
```

------
#### [ boto3 models (without inference components) ]

**Example 匯入陳述式**  
以下範例會從 SDK for Python (Boto3) 和 Python 標準程式庫匯入模組。這些模組能有效協助您部署模型，而這些模型也會用於後續的其他範例。  

```
import boto3
import botocore
import datetime
from time import gmtime, strftime
```

------

**Example 模型成品 URL**  
下列程式碼會建置範例 Amazon S3 URL。URL 會在 Amazon S3 儲存貯體中找到預先訓練模型的模型成品。  

```
# Create a variable w/ the model S3 URL

# The name of your S3 bucket:
s3_bucket = "amzn-s3-demo-bucket"
# The directory within your S3 bucket your model is stored in:
bucket_prefix = "sagemaker/model/path"
# The file name of your model artifact:
model_filename = "my-model-artifact.tar.gz"
# Relative S3 path:
model_s3_key = f"{bucket_prefix}/"+model_filename
# Combine bucket name, model file name, and relate S3 path to create S3 model URL:
model_url = f"s3://{s3_bucket}/{model_s3_key}"
```
完整的 Amazon S3 URL 會存放在變數 `model_url` 中，該變數會用於以下範例。

### 概觀


您可以透過 SageMaker Python SDK 或 SDK for Python (Boto3)，以多種方式部署模型。以下各部分將摘要說明各種方式的步驟。以下範例將示範這些步驟。

------
#### [ SageMaker Python SDK ]

您可以透過 SageMaker Python SDK，以下列任一方式建置模型：
+ **從 `Model` 類別建立模型物件** – 您必須指定模型套件或推論程式碼 (取決於您的模型伺服器)、處理用戶端和伺服器之間資料序列化和還原序列化的指令碼，以及要上傳到 Amazon S3 供使用的任何相依項目。
+ **從 `ModelBuilder` 類別建立模型物件** – 請提供模型成品或推論程式碼，`ModelBuilder` 會自動擷取相依項目、推論所需序列化和還原序列化函數，並封裝您的相依項目以建立 `Model` 物件。

  如需 `ModelBuilder` 的相關資訊，請參閱 [使用 ModelBuilder 在 Amazon SageMaker AI 建立模型](how-it-works-modelbuilder-creation.md)。您也可以參閱部落格[使用 SageMaker AI 輕鬆套件和部署傳統 ML 模型和 LLM – 第 1 部分](https://aws.amazon.com/blogs/machine-learning/package-and-deploy-classical-ml-and-llms-easily-with-amazon-sagemaker-part-1-pysdk-improvements/)，瞭解更多資訊。

以下範例將說明兩種建立模型和部署模型物件的方法。若要使用這些方式部署模型，請完成下列步驟：

1. 使用 `ResourceRequirements` 物件定義要配置給模型的端點資源。

1. 從 `Model` 或 `ModelBuilder` 類別建立模型物件。`ResourceRequirements` 物件是在模型設定中指定的。

1. 使用 `Model` 物件的 `deploy` 方法，將模型部署至端點。

------
#### [ boto3 inference components ]

以下範例說明如何將模型指派給推論元件，然後將推論元件部署至端點。若要使用這個方式部署模型，請完成下列步驟：

1. (選用) 使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_model.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_model.html) 方式建立 SageMaker AI 模型物件。

1. 建立端點組態物件來設定端點。若要建立一個端點，請使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint_config.html#create-endpoint-config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint_config.html#create-endpoint-config) 方式。

1. 使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html) 方式建立端點，並在請求中提供您建立的端點組態。

1. 使用 `create_inference_component` 方式建立推論元件。請在設定中執行下列任一動作來指定模型：
   + 指定 SageMaker AI 模型物件
   + 指定模型影像 URI 和 S3 URL

   您也可以將端點資源配置給模型。您可以建立推論元件，以將模型部署到端點。您可以建立多個推論元件，將多個模型部署到端點 (每個模型一個推論元件)。

------
#### [ boto3 models (without inference components) ]

以下範例說明如何建立模型物件，然後將模型部署到端點。若要使用這個方式部署模型，請完成下列步驟：

1. 使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_model.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_model.html) 方式建立 SageMaker AI 模型。

1. 建立端點組態物件來設定端點。若要建立一個端點，請使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint_config.html#create-endpoint-config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint_config.html#create-endpoint-config) 方式。請在端點組態中，將模型物件指派給生產變體。

1. 使用 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html) 方式建立端點。在請求中提供您建立的端點組態。

   建立端點時，SageMaker AI 會佈建端點資源，並將模型部署到端點。

------

### 設定


以下範例會設定將模型部署至端點所需的資源。

------
#### [ SageMaker Python SDK ]

以下範例會指派端點資源給具有 `ResourceRequirements` 物件的模型。這些資源包括 CPU 核心、加速器和記憶體。然後，範例會從 `Model` 類別建立模型物件。或者，您可以執行個體化 [ModelBuilder](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-modelbuilder-creation.html) 類別並執行 `build`，以建立模型物件；範例也會說明此方式。`ModelBuilder` 會提供模型封裝的統一界面，且會在此執行個體中準備大型模型部署的模型。此範例會利用 `ModelBuilder` 來建構 Hugging Face 模型。(您也可以傳遞 JumpStart 模型)。建置模型後，您可以在模型物件中指定資源需求。請在下一個步驟中使用此物件將模型部署至端點。

```
resources = ResourceRequirements(
    requests = {
        "num_cpus": 2,  # Number of CPU cores required:
        "num_accelerators": 1, # Number of accelerators required
        "memory": 8192,  # Minimum memory required in Mb (required)
        "copies": 1,
    },
    limits = {},
)

now = datetime.now()
dt_string = now.strftime("%d-%m-%Y-%H-%M-%S")
model_name = "my-sm-model"+dt_string

# build your model with Model class
model = Model(
    name = "model-name",
    image_uri = "image-uri",
    model_data = model_url,
    role = "arn:aws:iam::111122223333:role/service-role/role-name",
    resources = resources,
    predictor_cls = Predictor,
)
                        
# Alternate mechanism using ModelBuilder
# uncomment the following section to use ModelBuilder
/*
model_builder = ModelBuilder(
    model="<HuggingFace-ID>", # like "meta-llama/Llama-2-7b-hf"
    schema_builder=SchemaBuilder(sample_input,sample_output),
    env_vars={ "HUGGING_FACE_HUB_TOKEN": "<HuggingFace_token>}" }
)

# build your Model object
model = model_builder.build()

# create a unique name from string 'mb-inference-component'
model.model_name = unique_name_from_base("mb-inference-component")

# assign resources to your model
model.resources = resources
*/
```

------
#### [ boto3 inference components ]

以下範例會以 `create_endpoint_config` 方式設定端點。您可以在建立端點時將此組態指派給端點。請在組態中定義一個或多個生產變體。您可以針對每個變體選擇您希望 Amazon SageMaker AI 佈建的執行個體類型，並啟用受管執行個體擴展。

```
endpoint_config_name = "endpoint-config-name"
endpoint_name = "endpoint-name"
inference_component_name = "inference-component-name"
variant_name = "variant-name"

sagemaker_client.create_endpoint_config(
    EndpointConfigName = endpoint_config_name,
    ExecutionRoleArn = "arn:aws:iam::111122223333:role/service-role/role-name",
    ProductionVariants = [
        {
            "VariantName": variant_name,
            "InstanceType": "ml.p4d.24xlarge",
            "InitialInstanceCount": 1,
            "ManagedInstanceScaling": {
                "Status": "ENABLED",
                "MinInstanceCount": 1,
                "MaxInstanceCount": 2,
            },
        }
    ],
)
```

------
#### [ boto3 models (without inference components) ]

**Example 模型定義**  
以下範例使用 適用於 Python (Boto3) 的 AWS SDK中的 `create_model` 方式來定義 SageMaker AI 模型。  

```
model_name = "model-name"

create_model_response = sagemaker_client.create_model(
    ModelName = model_name,
    ExecutionRoleArn = "arn:aws:iam::111122223333:role/service-role/role-name",
    PrimaryContainer = {
        "Image": "image-uri",
        "ModelDataUrl": model_url,
    }
)
```
此範例會指定下列項目：  
+ `ModelName`：模型的名稱 (在這個範例中，它的儲存名稱是名為 `model_name` 的字串變數)。
+ `ExecutionRoleArn`：Amazon SageMaker AI 可扮演之 IAM 角色的 Amazon Resource Name (ARN)；該角色可存取模型成品和 Docker 映像檔，然後在機器學習 (ML) 運算執行個體上部署，或是用於批次轉換工作。
+ `PrimaryContainer`：主要 Docker 映像檔的位置，包含推論程式碼、關聯成品，以及推論程式碼在部署模型以進行預測時使用的自訂環境地圖。

**Example 端點組態**  
以下範例會以 `create_endpoint_config` 方式設定端點。Amazon SageMaker AI 會使用此組態部署模型。在組態中，您可以識別一個或多個使用 `create_model` 方式建立的模型，以部署您希望 Amazon SageMaker AI 佈建的資源。  

```
endpoint_config_response = sagemaker_client.create_endpoint_config(
    EndpointConfigName = "endpoint-config-name", 
    # List of ProductionVariant objects, one for each model that you want to host at this endpoint:
    ProductionVariants = [
        {
            "VariantName": "variant-name", # The name of the production variant.
            "ModelName": model_name, 
            "InstanceType": "ml.p4d.24xlarge",
            "InitialInstanceCount": 1 # Number of instances to launch initially.
        }
    ]
)
```
此範例會指定 `ProductionVariants` 欄位的下列金鑰：  
+ `VariantName`：生產變體的名稱。
+ `ModelName`：您要託管的模型名稱。這是您在建立模型時指定的名稱。
+ `InstanceType`：運算執行個體類型。如需支援的運算執行個體類型，以及每個執行個體類型的定價清單，請參閱 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProductionVariant.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProductionVariant.html) 和 [SageMaker AI 定價](https://aws.amazon.com/sagemaker/pricing/)中的 `InstanceType` 欄位。

------

### 部署


下列範例會將模型部署至端點。

------
#### [ SageMaker Python SDK ]

下列範例使用模型物件的 `deploy` 方式，將模型部署到即時的 HTTPS 端點。如果您指定了模型建立和部署的 `resources` 引數值，則會優先採用您為部署指定的資源。

```
predictor = model.deploy(
    initial_instance_count = 1,
    instance_type = "ml.p4d.24xlarge", 
    endpoint_type = EndpointType.INFERENCE_COMPONENT_BASED,
    resources = resources,
)
```

針對 `instance_type` 欄位，範例會指定模型的 Amazon EC2 執行個體類型名稱。針對 `initial_instance_count` 欄位，則會指定要在其中執行端點的執行個體初始數量。

下列程式碼範例說明另一個情況：您將模型部署到端點，然後將另一個模型部署到同一個端點。在這個情況下，您必須向兩個模型的 `deploy` 方式提供相同的端點名稱。

```
# Deploy the model to inference-component-based endpoint
falcon_predictor = falcon_model.deploy(
    initial_instance_count = 1,
    instance_type = "ml.p4d.24xlarge", 
    endpoint_type = EndpointType.INFERENCE_COMPONENT_BASED,
    endpoint_name = "<endpoint_name>"
    resources = resources,
)

# Deploy another model to the same inference-component-based endpoint
llama2_predictor = llama2_model.deploy( # resources already set inside llama2_model
    endpoint_type = EndpointType.INFERENCE_COMPONENT_BASED,
    endpoint_name = "<endpoint_name>"  # same endpoint name as for falcon model
)
```

------
#### [ boto3 inference components ]

有端點組態之後，請使用 [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html) 方式來建立端點。端點名稱在帳戶中 AWS 區域 AWS 的 內必須是唯一的。

以下範例會使用請求中指定的端點組態建立端點。Amazon SageMaker AI 會使用端點來佈建資源。

```
sagemaker_client.create_endpoint(
    EndpointName = endpoint_name,
    EndpointConfigName = endpoint_config_name,
)
```

建立端點之後，您可以建立推論元件來部署一個或多個模型。下列範例使用 `create_inference_component` 方式建立一個模型。

```
sagemaker_client.create_inference_component(
    InferenceComponentName = inference_component_name,
    EndpointName = endpoint_name,
    VariantName = variant_name,
    Specification = {
        "Container": {
            "Image": "image-uri",
            "ArtifactUrl": model_url,
        },
        "ComputeResourceRequirements": {
            "NumberOfCpuCoresRequired": 1, 
            "MinMemoryRequiredInMb": 1024
        }
    },
    RuntimeConfig = {"CopyCount": 2}
)
```

------
#### [ boto3 models (without inference components) ]

**Example deployment**  

將端點組態提供給 SageMaker AI。此服務便會啟動組態所指定的機器學習 (ML) 運算執行個體，接著進行模型部署。

有模型和端點組態之後，請使用 [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker/client/create_endpoint.html) 方式來建立端點。端點名稱在帳戶中 AWS 區域 AWS 的 內必須是唯一的。

以下範例會使用請求中指定的端點組態建立端點。Amazon SageMaker AI 使用端點來佈建資源和部署模型。

```
create_endpoint_response = sagemaker_client.create_endpoint(
    # The endpoint name must be unique within an AWS Region in your AWS account:
    EndpointName = "endpoint-name"
    # The name of the endpoint configuration associated with this endpoint:
    EndpointConfigName = "endpoint-config-name")
```

------

## 使用 部署模型 AWS CLI
使用 部署 AWS CLI

您可以使用 將模型部署至端點 AWS CLI。

### 概觀


當您使用 部署模型時 AWS CLI，您可以使用或不使用推論元件來部署模型。以下各部分將摘要說明用來執行兩種方式的命令。以下範例將示範這些命令。

------
#### [ With inference components ]

若要使用推論元件來部署模型，請執行下列動作：

1. (選用) 使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model.html) 命令建立模型。

1. 建立端點組態來設定端點。若要建立一個端點，請執行 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html) 命令。

1. 使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html) 命令建立端點。請在命令內文中指定您建立的端點組態。

1. 使用 `create-inference-component` 命令建立推論元件。請在設定中執行下列任一動作來指定模型：
   + 指定 SageMaker AI 模型物件
   + 指定模型影像 URI 和 S3 URL

   您也可以將端點資源配置給模型。您可以建立推論元件，以將模型部署到端點。您可以建立多個推論元件，將多個模型部署到端點 (每個模型一個推論元件)。

------
#### [ Without inference components ]

若要在不使用推論元件的情況下部署模型，請執行下列動作：

1. 使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model.html) 命令建立 SageMaker AI 模型。

1. 建立端點組態物件來設定端點。若要建立一個端點，請使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html) 命令。請在端點組態中，將模型物件指派給生產變體。

1. 使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html) 命令建立端點。請在命令內文中指定您建立的端點組態。

   建立端點時，SageMaker AI 會佈建端點資源，並將模型部署到端點。

------

### 設定


以下範例會設定將模型部署至端點所需的資源。

------
#### [ With inference components ]

**Example create-endpoint-config 命令**  
下列範例使用 [create-endpoint-config](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html) 命令來建立端點組態。  

```
aws sagemaker create-endpoint-config \
--endpoint-config-name endpoint-config-name \
--execution-role-arn arn:aws:iam::111122223333:role/service-role/role-name\
--production-variants file://production-variants.json
```
在此範例中，檔案 `production-variants.json` 使用以下 JSON 定義生產變體：  

```
[
    {
        "VariantName": "variant-name",
        "ModelName": "model-name",
        "InstanceType": "ml.p4d.24xlarge",
        "InitialInstanceCount": 1
    }
]
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "EndpointConfigArn": "arn:aws:sagemaker:us-west-2:111122223333:endpoint-config/endpoint-config-name"
}
```

------
#### [ Without inference components ]

**Example create-model 命令**  
下列範例使用 [create-model](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-model.html) 命令建立模型。  

```
aws sagemaker create-model \
--model-name model-name \
--execution-role-arn arn:aws:iam::111122223333:role/service-role/role-name \
--primary-container "{ \"Image\": \"image-uri\", \"ModelDataUrl\": \"model-s3-url\"}"
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "ModelArn": "arn:aws:sagemaker:us-west-2:111122223333:model/model-name"
}
```

**Example create-endpoint-config 命令**  
下列範例使用 [create-endpoint-config](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint-config.html) 命令來建立端點組態。  

```
aws sagemaker create-endpoint-config \
--endpoint-config-name endpoint-config-name \
--production-variants file://production-variants.json
```
在此範例中，檔案 `production-variants.json` 使用以下 JSON 定義生產變體：  

```
[
    {
        "VariantName": "variant-name",
        "ModelName": "model-name",
        "InstanceType": "ml.p4d.24xlarge",
        "InitialInstanceCount": 1
    }
]
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "EndpointConfigArn": "arn:aws:sagemaker:us-west-2:111122223333:endpoint-config/endpoint-config-name"
}
```

------

### 部署


下列範例會將模型部署至端點。

------
#### [ With inference components ]

**Example create-endpoint 命令**  
下列範例使用 [create-endpoint](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html) 命令來建立端點。  

```
aws sagemaker create-endpoint \
--endpoint-name endpoint-name \
--endpoint-config-name endpoint-config-name
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "EndpointArn": "arn:aws:sagemaker:us-west-2:111122223333:endpoint/endpoint-name"
}
```

**Example create-inference-component 命令**  
下列範例使用 create-inference-component 命令建立推論元件。  

```
aws sagemaker create-inference-component \
--inference-component-name inference-component-name \
--endpoint-name endpoint-name \
--variant-name variant-name \
--specification file://specification.json \
--runtime-config "{\"CopyCount\": 2}"
```
在此範例中，`specification.json` 檔案使用以下 JSON 定義容器和運算資源：  

```
{
    "Container": {
        "Image": "image-uri",
        "ArtifactUrl": "model-s3-url"
    },
    "ComputeResourceRequirements": {
        "NumberOfCpuCoresRequired": 1,
        "MinMemoryRequiredInMb": 1024
    }
}
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "InferenceComponentArn": "arn:aws:sagemaker:us-west-2:111122223333:inference-component/inference-component-name"
}
```

------
#### [ Without inference components ]

**Example create-endpoint 命令**  
下列範例使用 [create-endpoint](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/create-endpoint.html) 命令來建立端點。  

```
aws sagemaker create-endpoint \
--endpoint-name endpoint-name \
--endpoint-config-name endpoint-config-name
```
如果命令成功， 會以您建立之資源的 ARN AWS CLI 回應。  

```
{
    "EndpointArn": "arn:aws:sagemaker:us-west-2:111122223333:endpoint/endpoint-name"
}
```

------

# 調用模型以進行即時推論
調用模型

使用 Amazon SageMaker AI 將模型部署到端點後，您可以傳送推論請求來與模型互動。若要將推論請求傳送至模型，您可以調用負責託管該模型的端點。您可以使用 Amazon SageMaker Studio、 AWS SDK 或 AWS CLI來調用端點。

## 使用 Amazon SageMaker Studio 調用您的模型
使用 Studio Classic 進行調用

將模型部署至端點後，您可以透過 Amazon SageMaker Studio 檢視端點，並傳送單一推論請求來測試端點。

**注意**  
SageMaker AI 僅支援針對即時端點在 Studio 進行端點測試。

**將測試推論請求傳送至您的端點**

1. 啟動 Amazon SageMaker Studio。

1. 在左側導覽窗格中選擇**部署**。

1. 從下拉式清單中，選擇**端點**。

1. 依名稱尋找您的端點，然後在資料表中選擇名稱。**端點**面板中列出的端點名稱是在部署模型時所定義的。Studio工作區會在新索引標籤中開啟**端點**頁面。

1. 選擇**測試推論**索引標籤。

1. 針對**測試選項**選取以下任一選項：

   1. 選取**測試範例請求**，以立即將請求傳送至端點。使用 **JSON 編輯器**，以 JSON 格式提供範例資料，然後選擇**傳送請求**，將請求提交至端點。提交請求之後，Studio 會在 JSON 編輯器右側的卡片中顯示推論輸出。

   1. 選取**使用 Python SDK 範例程式碼**，檢視傳送請求至端點的程式碼。接著，從**範例推論請求**區段複製程式碼範例，並從測試環境執行程式碼。

卡片頂端會顯示傳送至端點的請求類型 (僅接受 JSON)。卡片會顯示下列欄位：
+ **狀態** — 會顯示以下其中一項狀態類型：
  + `Success` — 請求已成功。
  + `Failed` — 請求失敗。回應會顯示在 **Failure Reason** (失敗原因) 底下。
  + `Pending` — 當推論請求處於待處理時，狀態會顯示旋轉的圓形圖示。
+ **執行長度** — 調用所花費的時間 (結束時間減去開始時間)，以毫秒為單位。
+ **請求時間** — 自發送請求以來已過了多少分鐘。
+ **結果時間** — 自傳回結果後已過了多少分鐘。

## 使用 叫用您的模型 適用於 Python (Boto3) 的 AWS SDK
使用適用於 Python 的 SDK (Boto3) 調用

如果您想要在應用程式程式碼中叫用模型端點，您可以使用其中一個 AWS SDKs，包括 適用於 Python (Boto3) 的 AWS SDK。若要使用此 SDK 調用您的端點，請使用下列其中一種 Python 方法：
+ `invoke_endpoint` — 將推論請求傳送至模型端點，並傳回模型產生的回應。

  此方法會傳回推論承載，以作為模型完成生成後的一個回應。如需更多資訊，請參閱*適用於 Python 的AWS SDK (Boto3) API 參考*中的 [invoke\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime/client/invoke_endpoint.html)。
+ `invoke_endpoint_with_response_stream` — 將推論請求傳送至模型端點，並在模型產生推論時以累加方式串流回應。

  透過這種方法，應用程式會在回應的某部分可用時即接收到該回應部分。如需更多資訊，請參閱*適用於 Python 的AWS SDK (Boto3) API 參考*中的 [invoke\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime/client/invoke_endpoint.html)。

  只能使用此方法來調用支援推論串流的模型。

您必須先啟用 SageMaker AI 執行時期用戶端，並且指定端點名稱，才能在應用程式程式碼中使用這些方法。下列範例會針對隨後其餘範例設定用戶端和端點：

```
import boto3

sagemaker_runtime = boto3.client(
    "sagemaker-runtime", region_name='aws_region')

endpoint_name='endpoint-name'
```

### 調用以取得推論回應


下列範例會使用 `invoke_endpoint` 方法透過 適用於 Python (Boto3) 的 AWS SDK來調用端點：

```
# Gets inference from the model hosted at the specified endpoint:
response = sagemaker_runtime.invoke_endpoint(
    EndpointName=endpoint_name, 
    Body=bytes('{"features": ["This is great!"]}', 'utf-8')
    )

# Decodes and prints the response body:
print(response['Body'].read().decode('utf-8'))
```

此範例在 `Body` 欄位中提供輸入資料，供 SageMaker AI 傳遞至模型。此資料的格式必須與用於訓練的格式相同。此範例會將回應指派至 `response` 變數。

`response` 變數可讓您存取 HTTP 狀態、已部署模型的名稱以及其他欄位。下列程式碼片段會列印 HTTP 狀態程式碼：

```
print(response["HTTPStatusCode"])
```

### 調用以串流推論回應


如果您部署了支援推論串流的模型，您可以調用模型來接收其推論承載作為串流的部分。模型會在模型產生這些部分時累加地交付這些部分。當應用程式收到推論串流時，應用程式不需要等待模型產生整個回應承載。相反地，應用程式會在可用時接收部分回應。

藉由在應用程式中使用推論串流，您可以建立互動，讓使用者認為推論速度很快，因為他們會立即取得第一部分。您可以實作串流以支援快速互動體驗，例如聊天機器人、虛擬助理和音樂產生器。例如，您可以建立一個聊天機器人，以累加方式顯示由大型語言模型 (LLM) 產生的文字。

若要取得推論串流，您可以使用 `invoke_endpoint_with_response_stream` 方法。在回應內文中，SDK 提供了一個 `EventStream` 物件，它會將推論作為一系列 `PayloadPart` 物件來提供。

**Example 推論串流**  
下列為 `PayloadPart` 物件串流的範例。  

```
{'PayloadPart': {'Bytes': b'{"outputs": [" a"]}\n'}}
{'PayloadPart': {'Bytes': b'{"outputs": [" challenging"]}\n'}}
{'PayloadPart': {'Bytes': b'{"outputs": [" problem"]}\n'}}
. . .
```
在每個承載部分中，`Bytes` 欄位會提供來自模型的推論回應之一部分。此部分可以是模型產生的任何內容類型，例如文字、影像或音訊資料。在此範例中，這些部分是 JSON 物件，其中包含來自 LLM 的生成文字。  
通常，承載部分包含來自模型的離散資料區塊。在此範例中，離散區塊是整個 JSON 物件。有時候，回應會將區塊拆分為多個承載部分，或者將多個區塊合併為一個承載部分。下列範例會顯示 JSON 格式的資料區塊，這些資料分割為兩個承載部分：  

```
{'PayloadPart': {'Bytes': b'{"outputs": '}}
{'PayloadPart': {'Bytes': b'[" problem"]}\n'}}
```
當您撰寫處理推論串流的應用程式程式碼時，請包含處理這些偶爾分割和組合資料的邏輯。作為一種策略，您可以編寫代碼來串連應用程式接收承載部分的 `Bytes` 內容。透過在此處串連 JSON 資料範例，您可以將資料合併為以換行符號分隔的 JSON 主體。接著，您的程式碼可透過剖析每行上的整個 JSON 物件來處理串流。  
下列範例會顯示當您串連 `Bytes` 範例內容時所建立的以換行符號分隔之 JSON：  

```
{"outputs": [" a"]}
{"outputs": [" challenging"]}
{"outputs": [" problem"]}
. . .
```

**Example 處理推論串流的程式碼**  

下列範例 Python 類別 (`SmrInferenceStream`) 示範如何處理以 JSON 格式傳送文字資料的推論串流：

```
import io
import json

# Example class that processes an inference stream:
class SmrInferenceStream:
    
    def __init__(self, sagemaker_runtime, endpoint_name):
        self.sagemaker_runtime = sagemaker_runtime
        self.endpoint_name = endpoint_name
        # A buffered I/O stream to combine the payload parts:
        self.buff = io.BytesIO() 
        self.read_pos = 0
        
    def stream_inference(self, request_body):
        # Gets a streaming inference response 
        # from the specified model endpoint:
        response = self.sagemaker_runtime\
            .invoke_endpoint_with_response_stream(
                EndpointName=self.endpoint_name, 
                Body=json.dumps(request_body), 
                ContentType="application/json"
        )
        # Gets the EventStream object returned by the SDK:
        event_stream = response['Body']
        for event in event_stream:
            # Passes the contents of each payload part
            # to be concatenated:
            self._write(event['PayloadPart']['Bytes'])
            # Iterates over lines to parse whole JSON objects:
            for line in self._readlines():
                resp = json.loads(line)
                part = resp.get("outputs")[0]
                # Returns parts incrementally:
                yield part
    
    # Writes to the buffer to concatenate the contents of the parts:
    def _write(self, content):
        self.buff.seek(0, io.SEEK_END)
        self.buff.write(content)

    # The JSON objects in buffer end with '\n'.
    # This method reads lines to yield a series of JSON objects:
    def _readlines(self):
        self.buff.seek(self.read_pos)
        for line in self.buff.readlines():
            self.read_pos += len(line)
            yield line[:-1]
```

此範例會執行下列動作來處理推論串流：
+ 啟用 SageMaker AI 執行時期用戶端並命名模型端點。取得推論串流之前，端點託管的模型必須支援推論串流。
+ 在範例 `stream_inference` 方法中，接收請求內文並將其傳遞給 SDK 的 `invoke_endpoint_with_response_stream` 方法。
+ 迭代 SDK 傳回的 `EventStream` 物件中之每個事件。
+ 從每個事件中，取得 `PayloadPart` 物件中 `Bytes` 物件的內容。
+ 在範例 `_write` 方法中，寫入緩衝區以串連 `Bytes` 物件的內容。合併的內容會形成以換行符號分隔的 JSON 主體。
+ 使用範例 `_readlines` 方法來獲取可迭代的一系列 JSON 物件。
+ 在每個 JSON 物件中，您都會取得一段推論。
+ 使用 `yield` 表達式，以累加方式傳回片段。

下列範例會建立並使用 `SmrInferenceStream` 物件：

```
request_body = {"inputs": ["Large model inference is"],
                "parameters": {"max_new_tokens": 100,
                               "enable_sampling": "true"}}
smr_inference_stream = SmrInferenceStream(
    sagemaker_runtime, endpoint_name)
stream = smr_inference_stream.stream_inference(request_body)
for part in stream:
    print(part, end='')
```

此範例會將請求內容傳遞給 `stream_inference` 方法。它會不斷回應以印出推論串流傳回的每個部分。

此範例假設位於指定端點的模型是產生文字的 LLM。此範例的輸出是以累加方式列印的文字產生內文：

```
a challenging problem in machine learning. The goal is to . . .
```

## 使用 叫用您的模型 AWS CLI
使用 叫用 AWS CLI

您可以使用 AWS Command Line Interface () 執行命令來叫用模型端點AWS CLI。 AWS CLI 支援使用 `invoke-endpoint` 命令的標準推論請求，並支援使用 `invoke-endpoint-async` 命令的非同步推論請求。

**注意**  
 AWS CLI 不支援串流推論請求。

下列範例會使用 `invoke-endpoint` 命令，將推論請求傳送至模型端點：

```
aws sagemaker-runtime invoke-endpoint \
    --endpoint-name endpoint_name \
    --body fileb://$file_name \
    output_file.txt
```

請針對 `--endpoint-name` 參數提供您在建立端點時為端點指定的名稱。請針對 `--body` 參數提供要傳遞至模型之 SageMaker AI 的輸入資料。資料的格式必須與用於訓練的格式相同。此範例顯示如何將二進位資料傳送至您的端點。

如需將檔案內容傳遞至 參數`fileb://`時何時使用 `file://` 的詳細資訊 AWS CLI，請參閱[本機檔案參數的最佳實務](https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/)。

若要取得更多資訊，並查看您可以傳遞的其他參數，請參閱 *AWS CLI 命令推論*中的 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker-runtime/invoke-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker-runtime/invoke-endpoint.html)。

如果 `invoke-endpoint` 命令成功，它會傳回類似以下的回應：

```
{
    "ContentType": "<content_type>; charset=utf-8",
    "InvokedProductionVariant": "<Variant>"
}
```

如果命令未成功，請檢查輸入承載的格式是否正確。

檢查檔案輸出檔案來檢視調用的輸出 (在此範例中為 `output_file.txt`)。

```
more output_file.txt
```

## 使用適用於 Python 的 AWS SDK 叫用您的模型
使用適用於 Python 的 AWS SDK 叫用

### 叫用 以雙向串流推論請求和回應


如果您想要在應用程式程式碼中調用模型端點以支援雙向串流，您可以使用[新的適用於 Python 的實驗性 SDK](https://github.com/awslabs/aws-sdk-python)，其支援雙向串流功能，並支援 HTTP/2。此 SDK 可讓您在用戶端應用程式與 SageMaker 端點之間進行即時雙向通訊，讓您可以在模型產生推論請求的同時接收串流回應。這對於用戶端和伺服器都需要透過持久性連線持續交換資料的互動式應用程式特別有用。

**注意**  
新的實驗性 SDK 與標準 Boto3 SDK 不同，並支援資料交換的持久性雙向連線。使用實驗性 Python 開發套件時，我們強烈建議對任何非實驗性使用案例嚴格鎖定開發套件版本。

若要使用雙向串流叫用您的端點，請使用 `invoke_endpoint_with_bidirectional_stream`方法。此方法會建立持久性連線，可讓您將多個承載區塊串流至模型，同時在模型處理資料時即時接收回應。在您明確關閉輸入串流或端點關閉連線之前，連線會保持開啟狀態，最多支援 30 分鐘的連線時間。

### 先決條件


在應用程式程式碼中使用雙向串流之前，您必須：

1. 安裝實驗性 SageMaker 執行期 HTTP/2 SDK

1. 為您的 SageMaker 執行期用戶端設定 AWS 登入資料

1. 部署支援雙向串流到 SageMaker 端點的模型

### 設定雙向串流用戶端


下列範例示範如何初始化雙向串流所需的元件：

```
from sagemaker_runtime_http2.client import SageMakerRuntimeHTTP2Client
from sagemaker_runtime_http2.config import Config, HTTPAuthSchemeResolver
from smithy_aws_core.identity import EnvironmentCredentialsResolver
from smithy_aws_core.auth.sigv4 import SigV4AuthScheme

# Configuration
AWS_REGION = "us-west-2"
BIDI_ENDPOINT = f"https://runtime.sagemaker.{AWS_REGION}.amazonaws.com:8443"
ENDPOINT_NAME = "your-endpoint-name"

# Initialize the client configuration
config = Config(
    endpoint_uri=BIDI_ENDPOINT,
    region=AWS_REGION,
    aws_credentials_identity_resolver=EnvironmentCredentialsResolver(),
    auth_scheme_resolver=HTTPAuthSchemeResolver(),
    auth_schemes={"aws.auth#sigv4": SigV4AuthScheme(service="sagemaker")}
)

# Create the SageMaker Runtime HTTP/2 client
client = SageMakerRuntimeHTTP2Client(config=config)
```

### 完成雙向串流用戶端


下列範例示範如何建立雙向串流用戶端，將多個文字承載傳送至 SageMaker 端點，並即時處理回應：

```
import asyncio
import logging
from sagemaker_runtime_http2.client import SageMakerRuntimeHTTP2Client
from sagemaker_runtime_http2.config import Config, HTTPAuthSchemeResolver
from sagemaker_runtime_http2.models import (
    InvokeEndpointWithBidirectionalStreamInput, 
    RequestStreamEventPayloadPart, 
    RequestPayloadPart
)
from smithy_aws_core.identity import EnvironmentCredentialsResolver
from smithy_aws_core.auth.sigv4 import SigV4AuthScheme

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class SageMakerBidirectionalClient:
    
    def __init__(self, endpoint_name, region="us-west-2"):
        self.endpoint_name = endpoint_name
        self.region = region
        self.client = None
        self.stream = None
        self.response_task = None
        self.is_active = False
        
    def _initialize_client(self):
        bidi_endpoint = f"runtime.sagemaker.{self.region}.amazonaws.com:8443"
        config = Config(
            endpoint_uri=bidi_endpoint,
            region=self.region,
            aws_credentials_identity_resolver=EnvironmentCredentialsResolver(),
            auth_scheme_resolver=HTTPAuthSchemeResolver(),
            auth_schemes={"aws.auth#sigv4": SigV4AuthScheme(service="sagemaker")}
        )
        self.client = SageMakerRuntimeHTTP2Client(config=config)
    
    async def start_session(self):
        """Establish a bidirectional streaming connection with the endpoint."""
        if not self.client:
            self._initialize_client()
            
        logger.info(f"Starting session with endpoint: {self.endpoint_name}")
        self.stream = await self.client.invoke_endpoint_with_bidirectional_stream(
            InvokeEndpointWithBidirectionalStreamInput(endpoint_name=self.endpoint_name)
        )
        self.is_active = True
        
        # Start processing responses concurrently
        self.response_task = asyncio.create_task(self._process_responses())
    
    async def send_message(self, message):
        """Send a single message to the endpoint."""
        if not self.is_active:
            raise RuntimeError("Session not active. Call start_session() first.")
            
        logger.info(f"Sending message: {message}")
        payload = RequestPayloadPart(bytes_=message.encode('utf-8'))
        event = RequestStreamEventPayloadPart(value=payload)
        await self.stream.input_stream.send(event)
    
    async def send_multiple_messages(self, messages, delay=1.0):
        """Send multiple messages with a delay between each."""
        for message in messages:
            await self.send_message(message)
            await asyncio.sleep(delay)
    
    async def end_session(self):
        """Close the bidirectional streaming connection."""
        if not self.is_active:
            return
            
        await self.stream.input_stream.close()
        self.is_active = False
        logger.info("Stream closed")
        
        # Cancel the response processing task
        if self.response_task and not self.response_task.done():
            self.response_task.cancel()
    
    async def _process_responses(self):
        """Process incoming responses from the endpoint."""
        try:
            output = await self.stream.await_output()
            output_stream = output[1]
            
            while self.is_active:
                result = await output_stream.receive()
                
                if result is None:
                    logger.info("No more responses")
                    break
                
                if result.value and result.value.bytes_:
                    response_data = result.value.bytes_.decode('utf-8')
                    logger.info(f"Received: {response_data}")
                    
        except Exception as e:
            logger.error(f"Error processing responses: {e}")

# Example usage
async def run_bidirectional_client():
    client = SageMakerBidirectionalClient(endpoint_name="your-endpoint-name")
    
    try:
        # Start the session
        await client.start_session()
        
        # Send multiple messages
        messages = [
            "I need help with", 
            "my account balance", 
            "I can help with that", 
            "and recent charges"
        ]
        await client.send_multiple_messages(messages)
        
        # Wait for responses to be processed
        await asyncio.sleep(2)
        
        # End the session
        await client.end_session()
        logger.info("Session ended successfully")
        
    except Exception as e:
        logger.error(f"Client error: {e}")
        await client.end_session()

if __name__ == "__main__":
    asyncio.run(run_bidirectional_client())
```

用戶端會使用連接埠 8443 上的區域端點 URI 初始化 SageMaker 執行期 HTTP/2 用戶端，這是雙向串流連線所需的。start\$1`session()` 方法會呼叫 `invoke_endpoint_with_bidirectional_stream()` 來建立持久性連線，並建立非同步任務來同時處理傳入的回應。

`send_event()` 方法會將承載資料包裝在適當的請求物件中，並透過輸入串流傳送，同時`_process_responses()`方法會在端點到達時持續接聽和處理來自端點的回應。這種雙向方法可啟用即時互動，其中傳送請求和接收回應都會同時透過相同的連線進行。

# 端點


將模型部署到端點之後，您可能會想檢視和管理端點。您可以使用 SageMaker AI 來檢視端點的狀態和詳細資訊、檢查指標和日誌以監控端點的效能，或者更新部署到端點的模型等。

以下部分說明如何在 Amazon SageMaker Studio 或 AWS 管理主控台 內管理端點。

下一頁說明如何使用 Amazon SageMaker AI 主控台或 SageMaker Studio 以互動方式檢視和變更端點。

**Topics**
+ [

# 在 SageMaker Studio 中檢視端點詳細資訊
](manage-endpoints-studio.md)
+ [

# 在 SageMaker AI 主控台檢視端點詳細資訊
](manage-endpoints-console.md)

# 在 SageMaker Studio 中檢視端點詳細資訊


您可以在 Amazon SageMaker Studio 中檢視和管理 SageMaker AI 託管端點。若要進一步了解 Studio，請參閱 [Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio.html)。

若要在 SageMaker Studio 中尋找端點清單，請執行下列動作：

1. 開啟 Studio 應用程式。

1. 在左側導覽窗格中選擇**部署**。

1. 從下拉式功能表中選擇**端點**。

接著會開啟**端點**頁面，其中列出所有 SageMaker AI 託管端點。您可以在此頁面上查看端點及其**狀態**。您也可以建立新端點、編輯現有端點或刪除端點。

若要查看特定端點的詳細資訊，請從清單中選擇端點。您可以在端點的詳細資訊頁面上取得資訊摘要，如下螢幕擷取畫面。

![\[端點主頁的螢幕擷取畫面，其中顯示 Studio 中端點詳細資訊的摘要。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-endpoint-details-page.png)


每個端點詳細資訊頁面都包含下列索引標籤的資訊：

# 檢視變體或模型


**變體**索引標籤 (如果您的端點部署多個模型，其也稱為**模型**索引標籤) 會顯示目前部署至端點的[模型變體](https://docs.aws.amazon.com/sagemaker/latest/dg/model-ab-testing.html)或模型清單。以下螢幕擷取畫面顯示部署多個模型的端點的概觀和**模型**區段。

![\[端點主頁的螢幕擷取畫面，其中顯示部署多個模型。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-goldfinch-multi-model-endpoint.png)


您可以新增或編輯每個變體或模型的設定。您也可以選取變體並啟用預設的自動擴展政策，之後您可以在**自動擴展**索引標籤中編輯該政策。

# 檢視設定


您可以在**設定**索引標籤上檢視端點的相關聯 AWS IAM 角色、用於加密的 AWS KMS 金鑰 (如適用)、VPC 名稱，以及網路隔離設定。

# 測試推論


您可以在**測試推論**索引標籤上，將測試推論請求傳送至部署的模型。如果您想驗證端點是否按照預期回應請求，這是個有效的測試方式。

若要測試推論，請執行下列動作：

1. 在模型的**測試推論**索引標籤上，選擇下列任一選項：

   1. 如果您想測試端點並透過 Studio 介面接收回應，請選取**輸入請求內文**。

   1. 如果您想複製可用來從本機環境調用端點並以程式設計方式接收回應的 適用於 Python (Boto3) 的 AWS SDK 範例，請選取**複製範例程式碼 (Python)**。

1. 針對**模型**，選取您要在端點上測試的模型。

1. 如果您選擇 Studio 介面測試方式，您也可以從下拉式功能表選擇您要的回應**內容類型**。

設定請求後，您可以選擇**傳送請求** (透過 Studio 介面接收回應) 或**複製**以複製 Python 範例。

如果您透過 Studio 介面接收回應，畫面會如下螢幕擷取畫面。

![\[Studio 端點上成功推論測試請求的螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/endpoint-test-inference.png)


# 自動調整規模


您可以在**自動擴展**索引標籤上檢視針對端點上託管的模型所設定的任何自動擴展政策。以下螢幕擷取畫面顯示**自動擴展**索引標籤。

![\[自動擴展索引標籤的螢幕擷取畫面，其中顯示一個作用中政策。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/inference/studio-endpoint-autoscaling.png)


您可以選擇**編輯擴展**來變更任何政策，並開啟或關閉預設的自動擴展政策。

若要進一步了解即時端點的自動擴展，請參閱[自動擴展 Amazon SageMaker AI 模型](https://docs.aws.amazon.com/sagemaker/latest/dg/endpoint-auto-scaling.html)。如果您不確定如何為端點設定自動擴展政策，您可以透過[推論建議程式自動擴展建議任務](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-recommender-autoscaling.html)，取得自動擴展政策的建議。

# 在 SageMaker AI 主控台檢視端點詳細資訊


若要在 SageMaker AI 主控台檢視端點，請執行下列動作：

1. 前往位在 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 的 SageMaker AI 主控台。

1. 在左側導覽窗格中，選擇**推論**。

1. 從下拉式清單中，選擇**端點**。

1. 在**端點**頁面，選擇您的端點。

端點詳細資訊頁面應會開啟，並顯示已為您的端點收集的端點和指標摘要。

以下部分說明端點詳細資訊頁面上的索引標籤。

# 端點監控


建立 SageMaker AI 託管端點後，您可以使用 Amazon CloudWatch 監控端點，由 Amazon CloudWatch 收集原始資料，並將該資料處理成近乎即時的可讀取指標。使用這些指標，您可以存取歷史資訊，並更加了解端點的執行狀況。如需更多資訊，請參閱 *[Amazon CloudWatch 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*。

您可以從端點詳細資訊頁面的**監控**索引標籤，檢視從端點收集的 CloudWatch 指標資料。

**監控**索引標籤包含下列區段：
+ **操作指標**：查看用於追蹤端點資源使用率的指標，例如 CPU 利用率和記憶體使用率。
+ **調用指標**：檢視追蹤傳送到端點的 `InvokeEndpoint` 請求數量、運作狀態和狀態的指標，例如調用模型錯誤和模型延遲。
+ **運作狀態指標**：檢視追蹤端點整體運作狀態的指標，例如調用失敗和通知失敗。

如需每個指標的詳細說明，請參閱[使用 CloudWatch 監控 SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/monitoring-cloudwatch.html)。

下列螢幕擷取畫面顯示無伺服器端點的**操作指標**區段。

![\[端點詳細資訊頁面的操作指標區段中的指標圖螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/hosting-operational-metrics.png)




您可以針對指定區段中的指標調整要追蹤的**期間**和**統計資料**，以及要檢視指標資料的時間長度。您也可以選擇**新增小工具**，在每個區段的檢視中新增和移除指標小工具。在**新增小工具**對話方塊中，您可以選取並取消選取要查看的指標。

可用的指標可能取決於您的端點類型。例如，無伺服器端點具有一些無法用於即時端點的指標。如需端點類型的特定指標資訊，請參閱以下頁面：
+ [監控無伺服器端點](https://docs.aws.amazon.com/sagemaker/latest/dg/serverless-endpoints-monitoring.html)
+ [監控非同步端點](https://docs.aws.amazon.com/sagemaker/latest/dg/async-inference-monitor.html)
+ [多模型端點部署的 CW 指標](https://docs.aws.amazon.com/sagemaker/latest/dg/multi-model-endpoint-cloudwatch-metrics.html)
+ [推論管道日誌和指標](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipeline-logs-metrics.html)

# 設定


您可以選擇**設定**索引標籤來檢視有關端點的其他資訊，例如資料擷取設定、端點組態和標籤。

# 建立和檢視警示


在端點詳細資訊頁面的**警示**索引標籤上，您可以檢視和建立簡單的靜態閾值指標警示，並在其中指定指標的閾值。如果指標違反閾值，警示就會進入 `ALARM` 狀態。如需有關 CloudWatch 警示的詳細資訊，請參閱[使用 Amazon CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。

在**端點摘要**區段中，您可以檢視**警示**欄位，告訴您端點上目前有多少警示處於啟用狀態。

若要檢視處於該 `ALARM` 狀態的警示，請選擇**警示**索引標籤。**警示**索引標籤顯示端點警示的完整清單，以及其狀態和條件的詳細資訊。下列螢幕擷取畫面顯示此區段中已針對端點設定的警示清單。

![\[端點詳細資訊頁面上的警示索引標籤螢幕擷取畫面，顯示 CloudWatch 警示清單。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/hosting-alarms-tab.png)


警示狀態可以是 `In alarm`、`OK`，或者 `Insufficient data` (如果收集的指標資料不足)。

若要為您的端點建立新警示，請執行以下動作：

1. 在**警示**索引標籤中，選擇**建立警示**。

1. **建立警示**頁面隨即開啟。對於 **Alarm name** (警示名稱)，輸入警示的名稱。

1. (選用) 輸入警示的說明。

1. 對於**指標**，選擇您要追蹤的警示的 CloudWatch 指標。

1. 對於**變體名稱**，選擇您要監視的端點模型變體。

1. 對於**統計資料**，選擇所選指標的其中一個可用統計資料。

1. 對於**期間**，選擇用於計算每個統計資料值的時段。例如，如果您選擇平均值統計資料和 5 分鐘的期間，則警示監控的每個資料點就是每 5 分鐘間隔的指標資料點平均值。

1. 對於**評估期間**，請輸入您要在評估是否進入警示狀態時要考量警示的資料點數量。

1. 對於**條件**，選擇您要用於警示閾值的條件。

1. 對於**閾值**，輸入所需的閾值。

1. (選用) 對於**通知**，您可以選擇**新增通知**來建立或指定在警示狀態變更時接收通知的 Amazon SNS 主題。

1. 選擇 **Create alarm** (建立警示)。

建立警示後，您可以隨時返回**警示**索引標籤來檢視其狀態。您也可以從此區段選取警示，然後選取**編輯**或**刪除**。

# 託管選項


下列主題說明可用的 SageMaker AI 即時託管選項，以及如何設定、調用和刪除每個託管選項。

**Topics**
+ [

# 單一模型端點
](realtime-single-model.md)
+ [

# 多模型端點
](multi-model-endpoints.md)
+ [

# 多容器端點
](multi-container-endpoints.md)
+ [

# Amazon SageMaker AI 中的推論管道
](inference-pipelines.md)
+ [

# 刪除端點和資源
](realtime-endpoints-delete-resources.md)

# 單一模型端點


您可以使用 Amazon SageMaker Studio、適用於 Python (Boto3) 的 AWS SDK、SageMaker Python SDK 或 AWS CLI，建立、更新和刪除託管單一模型的即時推論端點。如需程序和程式碼範例，請參閱[部署用於即時推論的模型](realtime-endpoints-deploy-models.md)。

# 多模型端點


多模型端點提供可擴展且經濟實惠的解決方案，而且可以部署大量模型。其運用相同資源機群及共享服務容器來託管所有模型。相較於使用單一模型端點，這能改善端點使用率，藉此降低託管成本。同時也能降低部署開銷，因為 Amazon SageMaker AI 會管理記憶體內部的模型載入，並根據端點流量模式擴展模型。

下圖顯示多模型端點與單一模型端點的運作方式。

![\[圖表顯示多模型端點與單一模型端點各自託管模型的方式。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/multi-model-endpoints-diagram.png)


多模型端點非常適合託管大量模型，這些模型在共用服務容器採用相同機器學習 (ML) 架構。如您混合經常存取及不常存取的模型，則多模型端點可利用有效率的方式為此流量提供服務，運用更少資源並節省更多成本。您的應用程式應能容忍偶爾發生的冷啟動相關延遲處罰，這會在調用不常使用的模型時發生。

多模型端點支援託管 CPU 與 GPU 支援的模型。藉由採用 GPU 支援的模型，您可透過增加端點及其基礎加速運算執行個體的使用量來降低模型部署成本。

多模型端點也能支援跨模型記憶體資源的時間共享。這最適合用於模型大小和調用延遲相當類似的情況。在這種情況下，多模型端點可有效地在所有模型中使用執行個體。如果您的模型有明顯較高的每秒交易次數 (TPS) 或延遲需求，建議您將模型託管於專用端點。

您可利用具有下列特徵的多模型端點：
+ [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-services-overview.html) VPCs
+ [自動擴展](multi-model-endpoints-autoscaling.md)
+ [序列推論管道](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipelines.html) (但推論管道僅能包含單一啟用多模型功能的容器)
+ A/B 測試

您可以使用 適用於 Python (Boto) 的 AWS SDK 或 SageMaker AI 主控台來建立多模型端點。對於 CPU 支援的多模型端點，您可整合[多模型伺服器](https://github.com/awslabs/multi-model-server)程式庫來建立搭配自訂建置容器的端點。

**Topics**
+ [

## 多模型端點的運作方式
](#how-multi-model-endpoints-work)
+ [

## 多模型端點的範例筆記本
](#multi-model-endpoint-sample-notebooks)
+ [

# 支援的多模型端點適用演算法、架構與執行個體
](multi-model-support.md)
+ [

# 多模型端點部署的執行個體建議
](multi-model-endpoint-instance.md)
+ [

# 建立多模型端點
](create-multi-model-endpoint.md)
+ [

# 調用多模型端點
](invoke-multi-model-endpoint.md)
+ [

# 新增或移除模型
](add-models-to-endpoint.md)
+ [

# 為 SageMaker AI 多模型端點建置自有容器
](build-multi-model-build-container.md)
+ [

# 多模型端點安全
](multi-model-endpoint-security.md)
+ [

# 多模型端點部署的 CloudWatch 指標
](multi-model-endpoint-cloudwatch-metrics.md)
+ [

# 設定 SageMaker AI 多模型端點模型快取行為
](multi-model-caching.md)
+ [

# 為多模型端點部署設定自動擴展政策
](multi-model-endpoints-autoscaling.md)

## 多模型端點的運作方式
Amazon SageMaker AI 多模型端點的運作方式

 SageMaker AI 會管理託管於容器記憶體中的多模型端點上的模型生命週期。在建立端點時，不是從 Amazon S3 儲存貯體將所有模型下載到容器，而是於調用模型時，由 SageMaker AI 動態載入及快取。當 SageMaker AI 收到特定模型的調用請求時，會執行以下操作：

1. 路由請求至端點後方單一執行個體。

1. 將模型從 S3 儲存貯體下載到該執行個體的儲存磁碟區。

1. 載入模型至該加速運算執行個體的容器記憶體 (CPU 或 GPU，視您擁有 CPU 或 GPU 支援的執行個體而定)。如模型已載入容器記憶體，則由於 SageMaker AI 不需要下載及載入模型，因此其調用速度會更快。

SageMaker AI 會繼續將模型的請求路由到已載入模型的執行個體。但是，如果模型收到許多調用請求，且多模型端點具有其他執行個體，則 SageMaker AI 會將部分請求路由傳送到另一個執行個體以因應流量。如果模型尚未載入第二個執行個體，則模型會下載到該執行個體的儲存磁碟區，並載入容器的記憶體中。

當執行個體的記憶體使用率很高，且 SageMaker AI 需要將另一個模型載入記憶體時，便會從該執行個體的容器卸載未使用的模型，以確保有足夠的記憶體來載入模型。卸載的模型會留在執行個體的儲存磁碟區上，稍後可以載入容器的記憶體，而無須從 S3 儲存貯體再次下載。如果執行個體的儲存磁碟區達到其容量，則 SageMaker AI 會從儲存磁碟區刪除任何未使用的模型。

若要刪除模型，請停止傳送請求，並從 S3 儲存貯體中刪除模型。SageMaker AI 可在服務容器提供多模型端點功能。將模型新增到多模型端點或從中刪除模型時，並不需要更新端點本身。若要新增模型，請將模型上傳到 S3 儲存貯體並進行調用。您不需要變更程式碼也能使用。

**注意**  
當您更新多模型端點時，隨著多模型端點的智慧路由適應流量模式，端點的初始調用請求可能經歷較高延遲。但在其了解流量模式之後，您即可針對最常用模型體驗低延遲情況。較少使用的模型可能產生部分冷啟動延遲，這是由於模型會動態載入至執行個體。

## 多模型端點的範例筆記本
範例筆記本

若要進一步了解如何使用多模型端點，可嘗試下列範例筆記本：
+ 採用 CPU 支援執行個體的多模型端點範例：
  + [多模型端點 XGBoost 範例筆記本](https://sagemaker-examples.readthedocs.io/en/latest/advanced_functionality/multi_model_xgboost_home_value/xgboost_multi_model_endpoint_home_value.html) - 此筆記本說明如何部署多個 XGBoost 模型至單一端點。
  + [多模型端點 BYOC 範例筆記本](https://sagemaker-examples.readthedocs.io/en/latest/advanced_functionality/multi_model_bring_your_own/multi_model_endpoint_bring_your_own.html) - 此筆記本說明如何設定及部署客戶容器來支援 SageMaker AI 的多模型端點。
+ 採用 GPU 支援執行個體的多模型端點範例：
  + [運用 Amazon SageMaker AI 多模型端點 (MME) 在 GPU 執行多個深度學習模型](https://github.com/aws/amazon-sagemaker-examples/blob/main/multi-model-endpoints/mme-on-gpu/cv/resnet50_mme_with_gpu.ipynb) - 此筆記本說明如何運用 NVIDIA Triton 推論容器部署 ResNet-50 模型至多模型端點。

如需說明了解如何建立及存取 Jupyter 筆記本執行個體，並用以執行先前 SageMaker AI 的範例，請參閱[Amazon SageMaker 筆記本執行個體](nbi.md)。在建立並開啟筆記本執行個體之後，請選擇 **SageMaker AI 範例**索引標籤，查看所有 SageMaker AI 範例的清單。多模型端點筆記本位於 **ADVANCED FUNCTIONALITY** (進階功能) 區段。若要開啟筆記本，請選擇其 **Use** (使用) 標籤，然後選擇 **Create copy** (建立複本)。

如需有關多模型端點使用案例的詳細資訊，請參閱下列部落格與資源：
+ 影片：[在 SageMaker AI 託管數千個模型](https://www.youtube.com/watch?v=XqCNTWmHsLc&t=751s)
+ 影片：[適用 SaaS 的 SageMaker AI ML](https://www.youtube.com/watch?v=BytpYlJ3vsQ)
+ 部落格：[如何擴展多租戶 SaaS 使用案例的機器學習推論](https://aws.amazon.com/blogs/machine-learning/how-to-scale-machine-learning-inference-for-multi-tenant-saas-use-cases/)
+ 案例研究：[Veeva Systems](https://aws.amazon.com/partners/success/advanced-clinical-veeva/)

# 支援的多模型端點適用演算法、架構與執行個體


如需資訊了解可搭配多模型端點使用的演算法、架構與執行個體類型，請參閱下列各節。

## 對於採用 CPU 支援執行個體的多模型端點，支援的演算法、架構與執行個體


下列演算法與架構的推論容器支援多模型端點：
+ [XGBoost 演算法搭配 Amazon SageMaker AI](xgboost.md)
+ [K 近鄰 (k-NN) 演算法](k-nearest-neighbors.md)
+ [線性學習程式演算法](linear-learner.md)
+ [隨機分割森林 (RCF) 演算法](randomcutforest.md)
+ [使用 TensorFlow 搭配 Amazon SageMaker AI 的資源](tf.md)
+ [使用 Scikit-learn 搭配 Amazon SageMaker AI 的資源](sklearn.md)
+ [使用 Apache MXNet 搭配 Amazon SageMaker AI 的資源](mxnet.md)
+ [使用 PyTorch 搭配 Amazon SageMaker AI 的資源](pytorch.md)

若要使用其他任何架構或演算法，請使用 SageMaker AI 推論工具組來建置支援多模型端點的容器。如需相關資訊，請參閱[為 SageMaker AI 多模型端點建置自有容器](build-multi-model-build-container.md)。

多模型端點支援所有 CPU 執行個體類型。

## 對於採用 GPU 支援執行個體的多模型端點，支援的演算法、架構與執行個體


透過 [SageMaker AI Triton 推論伺服器](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)支援在多模型端點託管多個 GPU 支援的模型。這支援所有主要的推論架構，如 NVIDIA® TensorRT™、PyTorch、MXNet、Python、ONNX、XGBoost、scikit-learn、RandomForest、 OpenVINO、自訂 C\$1\$1 等等。

若要採用任何其他架構或演算法，您可利用 Python 或 C \$1\$1 的 Triton 後端編寫模型邏輯並為任何自訂模型提供服務。在伺服器準備就緒之後，您即可開始在單一端點後方部署數百個深度學習模型。

多模型端點支援下列 GPU 執行個體類型：


| 執行個體系列 | 執行個體類型 | vCPUs | 每個 vCPU 的記憶體 GiB | GPU | 記憶體 | 
| --- | --- | --- | --- | --- | --- | 
| p2 | ml.p2.xlarge | 4 | 15.25 | 1 | 12 | 
| p3 | ml.p3.2xlarge | 8 | 7.62 | 1 | 16 | 
| g5 | ml.g5.xlarge | 4 | 4 | 1 | 24 | 
| g5 | ml.g5.2xlarge | 8 | 4 | 1 | 24 | 
| g5 | ml.g5.4xlarge | 16 | 4 | 1 | 24 | 
| g5 | ml.g5.8xlarge | 32 | 4 | 1 | 24 | 
| g5 | ml.g5.16xlarge | 64 | 4 | 1 | 24 | 
| g4dn | ml.g4dn.xlarge | 4 | 4 | 1 | 16 | 
| g4dn | ml.g4dn.2xlarge | 8 | 4 | 1 | 16 | 
| g4dn | ml.g4dn.4xlarge | 16 | 4 | 1 | 16 | 
| g4dn | ml.g4dn.8xlarge | 32 | 4 | 1 | 16 | 
| g4dn | ml.g4dn.16xlarge | 64 | 4 | 1 | 16 | 

# 多模型端點部署的執行個體建議


在選取多模型端點的 SageMaker AI 機器學習 (ML) 執行個體類型時，有一些需要考量的項目：
+ 為需要服務的所有模型佈建足夠的 [Amazon Elastic Block Store (Amazon EBS)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html) 容量。
+ 在效能 (將冷啟動次數減到最少) 與成本 (請勿過度佈建執行個體容量) 之間取得平衡。如需 SageMaker AI 為端點與多模型端點之各種執行個體類型連接的儲存磁碟區大小的相關資訊，請參閱[執行個體存放區磁碟區](host-instance-storage.md)。
+ 若是設定為在 `MultiModel` 模式下執行的容器，則相較於預設的 `SingleModel` 模式，為其執行個體佈建的儲存磁碟區會較大。相較於 `SingleModel` 模式，這可在執行個體儲存磁碟區快取更多模型。

當選擇 SageMaker AI 機器學習 (ML) 執行個體類型時，請考慮下列事項：
+ 目前所有 CPU 執行個體類型與單一 GPU 執行個體類型均支援多模型端點。
+ 對於您要託管於多模型端點後方模型的流量分佈 (存取模式)，以及模型大小 (可在執行個體的記憶體載入幾個模型)，請留意下列資訊：
  + 將執行個體的記憶體容量視為模型要載入的快取空間，並將 vCPU 數量視為對於已載入模型執行推論的並行限制 (假設調用模型已繫結 CPU)。
  + 對於 CPU 支援的執行個體，vCPU 數量會影響每個執行個體的最大並行調用 (假設調用模型已繫結 CPU)。更高數量的 vCPU 可讓您同時調用更多唯一模型。
  + 對於 GPU 支援的執行個體，較高執行個體與 GPU 記憶體容量可讓您載入更多模型並準備就緒可提供推斷請求服務。
  + 對於 CPU 與 GPU 支援的執行個體，擁有部分可用 “閒置” 記憶體，以便卸載未使用模型，這尤其適用具多個執行個體的多模型端點。如果執行個體或可用區域故障，這些執行個體上的模型會重新路由到端點後方的其他執行個體。
+ 決定載入/下載時間公差：
  + d 執行個體類型系列 (例如 m5d、c5d 或 r5d) 以及 g5 隨附 NVMe (非揮發性記憶體儲存裝置) SSD，可提供高 I/O 效能，而且可能會縮短將模型下載到儲存磁碟區所需的時間，以及容器從儲存磁碟區載入模型所需的時間。
  + 由於 d 與 g5 執行個體類型隨附 NVMe SSD 儲存，SageMaker AI 不會將 Amazon EBS 儲存磁碟區連接到這些託管多模型端點的機器學習 (ML) 運算執行個體。當模型的大小類似且同質 (亦即它們具有類似的推論延遲和資源需求)，自動擴展的效果最理想。

您也可利用下列指引來協助您最佳化多模型端點的模型載入：

**選擇無法將所有目標模型保存於記憶體的執行個體類型**

在某些情況下，您可選擇無法將所有目標模型同時保存於記憶體的執行個體類型，藉此選擇降低成本。SageMaker AI 會在耗盡記憶體時動態卸載模型，以便保留空間供新目標模型使用。對於不常請求的模型，您會犧牲動態負載延遲。在延遲需求較嚴密的情況下，您可選擇較大的執行個體類型或更多執行個體。預先投入時間進行效能測試及分析，可協助成功進行生產部署。

**評估模型快取命中**

Amazon CloudWatch 指標可協助您評估模型。如需詳細資訊了解可搭配多模型端點使用的指標，請參閱[多模型端點部署的 CloudWatch 指標](multi-model-endpoint-cloudwatch-metrics.md)。

 您可以使用 `ModelCacheHit` 指標的 `Average` 統計資料，監控已載入模型中的請求比率。您可以使用 `ModelUnloadingTime` 指標的 `SampleCount` 統計資料，監控在某個期間內傳送到容器的取消載入請求數量。如模型太常卸載 (代表出現*輾轉現象* (Thrashing)；由於模型工作集的快取空間不足，因此再次取消載入及載入模型)，請考慮使用具有更多記憶體的較大執行個體類型，或增加多模型端點後方的執行個體數量。對於具有多個執行個體的多模型端點，請注意模型可能會在 1 個以上的執行個體上載入。

# 建立多模型端點


您可以使用 SageMaker AI 主控台或 適用於 Python (Boto) 的 AWS SDK 來建立多模型端點。若要透過主控台建立 CPU 或 GPU 支援的端點，請參閱以下各節的主控台程序。如果您想要使用 建立多模型端點 適用於 Python (Boto) 的 AWS SDK，請使用下列各節中的 CPU 或 GPU 程序。CPU 與 GPU 工作流程類似，但有幾項差異，例如容器需求。

**Topics**
+ [

## 建立多模型端點 (主控台)
](#create-multi-model-endpoint-console)
+ [

## 使用 CPUs搭配 建立多模型端點 適用於 Python (Boto3) 的 AWS SDK
](#create-multi-model-endpoint-sdk-cpu)
+ [

## 使用 GPUs 搭配 建立多模型端點 適用於 Python (Boto3) 的 AWS SDK
](#create-multi-model-endpoint-sdk-gpu)

## 建立多模型端點 (主控台)
建立多模型端點 (主控台)

您可利用主控台建立 CPU 與 GPU 支援的多模型端點。利用下列程序，透過 SageMaker AI 主控台建立多模型端點。

**建立多模型端點 (主控台)**

1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 選擇 **Model** (模型)，然後從 **Inference** (推斷) 群組中選擇 **Create model** (建立模型)。

1. 在 **Model name** (模型名稱) 中，輸入名稱。

1. 針對 **IAM role**，選擇或建立已連接 `AmazonSageMakerFullAccess` IAM 政策的 IAM 角色。

1.  針對 **Container definition** (容器定義) 區段的 **Provide model artifacts and inference image options** (提供模型成品與推論映像選項)，選擇 **Use multiple models** (使用多個模型)。  
![\[[建立模型] 頁面區段，在此您可選擇使用多個模型。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/mme-create-model-ux-2.PNG)

1. 針對 **Inference container image** (推論容器映像)，輸入所需容器映像的 Amazon ECR 路徑。

   針對 GPU 模型，您必須使用 NVIDIA Triton 推論伺服器支援的容器。如需可搭配 GPU 支援端點使用的容器映像清單，請參閱 [NVIDIA Triton 推論容器 (僅限 SM 支援)](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#nvidia-triton-inference-containers-sm-support-only)。如需 NVIDIA Triton 推論伺服器的詳細資訊，請參閱[搭配 SageMaker AI 使用 Triton 推論伺服器](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)。

1. 選擇**建立模型**。

1. 部署多模型端點，做法就像部署單一模型端點一樣。如需說明，請參閱[將模型部署至 SageMaker AI 託管服務](ex1-model-deployment.md#ex1-deploy-model)。

## 使用 CPUs搭配 建立多模型端點 適用於 Python (Boto3) 的 AWS SDK
建立 CPU 支援的多模型端點 (開發套件)

請參閱下一節來建立由 CPU 執行個體支援的多模型端點。您可利用 Amazon SageMaker AI [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model)、[https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) 與 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint) API 來建立多模型端點，就像建立單一模型端點一樣，但有兩個變更。當定模型義容器時，您必須傳遞新的 `Mode` 參數值 `MultiModel`。您也需要傳遞指定模型成品所在之 Amazon S3 的字首 `ModelDataUrl` 欄位，而不是單一模型成品的路徑，就像部署單一模型時的做法一樣。

如需使用 SageMaker AI 部署多個 XGBoost 模型至單一端點的範例筆記本，請參閱[多模型端點 XGBoost 範例筆記本](https://sagemaker-examples.readthedocs.io/en/latest/advanced_functionality/multi_model_xgboost_home_value/xgboost_multi_model_endpoint_home_value.html)。

下列程序概述該範例採用的重要步驟，以便建立 CPU 支援的多模型端點。

**部署模型 (AWS SDK for Python (Boto 3))**

1. 取得容器，其需包含支援部署多模型端點的映像。如需支援多模型端點的內建演算法與架構容器清單，請參閱[支援的多模型端點適用演算法、架構與執行個體](multi-model-support.md)。我們在此範例採用 [K 近鄰 (k-NN) 演算法](k-nearest-neighbors.md) 內建演算法。我們呼叫 [SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable/v2.html) 公用程式函式 `image_uris.retrieve()` 來取得 k 近鄰內建演算法映像位址。

   ```
   import sagemaker
   region = sagemaker_session.boto_region_name
   image = sagemaker.image_uris.retrieve("knn",region=region)
   container = { 
                 'Image':        image,
                 'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                 'Mode':         'MultiModel'
               }
   ```

1. 取得 an 適用於 Python (Boto3) 的 AWS SDK SageMaker AI 用戶端並建立使用此容器的模型。

   ```
   import boto3
   sagemaker_client = boto3.client('sagemaker')
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [container])
   ```

1. (選用) 如果您使用的是序列推論管道，請在管道納入額外容器，並將其包含在 `CreateModel` 的 `Containers` 引數中：

   ```
   preprocessor_container = { 
                  'Image': '<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/<PREPROCESSOR_IMAGE>:<TAG>'
               }
   
   multi_model_container = { 
                 'Image': '<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/<IMAGE>:<TAG>',
                 'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                 'Mode':         'MultiModel'
               }
   
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [preprocessor_container, multi_model_container]
               )
   ```
**注意**  
您只能在序列推論管道中使用一個啟用多模型的端點。

1. (選用) 如您的使用案例無法從模型快取受益，請將 `MultiModelConfig` 參數 `ModelCacheSetting` 欄位的值設為 `Disabled`，並將其包含在呼叫 `create_model` 的 `Container` 引數。`ModelCacheSetting` 欄位的預設值為 `Enabled`。

   ```
   container = { 
                   'Image': image, 
                   'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                   'Mode': 'MultiModel' 
                   'MultiModelConfig': {
                           // Default value is 'Enabled'
                           'ModelCacheSetting': 'Disabled'
                   }
              }
   
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [container]
               )
   ```

1. 為該模型設定多模型端點。建議您至少使用兩個執行個體來設定端點。這可讓 SageMaker AI 在模型的多個可用區域中提供一組高可用性的預測結果。

   ```
   response = sagemaker_client.create_endpoint_config(
                   EndpointConfigName = '<ENDPOINT_CONFIG_NAME>',
                   ProductionVariants=[
                        {
                           'InstanceType':        'ml.m4.xlarge',
                           'InitialInstanceCount': 2,
                           'InitialVariantWeight': 1,
                           'ModelName':            '<MODEL_NAME>',
                           'VariantName':          'AllTraffic'
                         }
                   ]
              )
   ```
**注意**  
您只能在序列推論管道中使用一個啟用多模型的端點。

1. 使用 `EndpointName` 和 `EndpointConfigName` 參數建立多模型端點。

   ```
   response = sagemaker_client.create_endpoint(
                 EndpointName       = '<ENDPOINT_NAME>',
                 EndpointConfigName = '<ENDPOINT_CONFIG_NAME>')
   ```

## 使用 GPUs 搭配 建立多模型端點 適用於 Python (Boto3) 的 AWS SDK
建立 GPU 支援的多模型端點 (開發套件)

請參閱下列區段建立 GPU 支援的多模型端點。您可利用 Amazon SageMaker AI [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model)、[https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) 與 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint) API 來建立多模型端點 ，這類似建立單一模型端點，但有幾項變更。當定模型義容器時，您必須傳遞新的 `Mode` 參數值 `MultiModel`。您也需要傳遞指定模型成品所在之 Amazon S3 的字首 `ModelDataUrl` 欄位，而不是單一模型成品的路徑，就像部署單一模型時的做法一樣。對於 GPU 支援的多模型端點，您也必須使用搭配 NVIDIA Triton 推論伺服器的容器，該伺服器已針對 GPU 執行個體進行最佳化。如需可搭配 GPU 支援端點使用的容器映像清單，請參閱 [NVIDIA Triton 推論容器 (僅限 SM 支援)](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#nvidia-triton-inference-containers-sm-support-only)。

如需範例筆記本示範如何建立由 GPU 支援的多模型端點，請參閱[運用 Amazon SageMaker AI 多模型端點 (MME) 在 GPU 執行多個深度學習模型](https://github.com/aws/amazon-sagemaker-examples/blob/main/multi-model-endpoints/mme-on-gpu/cv/resnet50_mme_with_gpu.ipynb)。

下列程序針對建立由 GPU 支援的多模型端點概述重要步驟。

**部署模型 (AWS SDK for Python (Boto 3))**

1. 定義容器映像。若要建立具有 GPU 支援 ResNet 模型的多模型端點，請定義要使用 [NVIDIA Triton 伺服器映像](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)的容器。此容器支援多模型端點，並已最佳化以便用於 GPU 執行個體。我們呼叫 [SageMaker AI Python SDK](https://sagemaker.readthedocs.io/en/stable/v2.html) 公用程式函式 `image_uris.retrieve()` 來取得映像位址。例如：

   ```
   import sagemaker
   region = sagemaker_session.boto_region_name
   
   // Find the sagemaker-tritonserver image at 
   // https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-triton/resnet50/triton_resnet50.ipynb
   // Find available tags at https://github.com/aws/deep-learning-containers/blob/master/available_images.md#nvidia-triton-inference-containers-sm-support-only
   
   image = "<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/sagemaker-tritonserver:<TAG>".format(
       account_id=account_id_map[region], region=region
   )
   
   container = { 
                 'Image':        image,
                 'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                 'Mode':         'MultiModel',
                 "Environment": {"SAGEMAKER_TRITON_DEFAULT_MODEL_NAME": "resnet"},
               }
   ```

1. 取得 an 適用於 Python (Boto3) 的 AWS SDK SageMaker AI 用戶端並建立使用此容器的模型。

   ```
   import boto3
   sagemaker_client = boto3.client('sagemaker')
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [container])
   ```

1. (選用) 如果您使用的是序列推論管道，請在管道納入額外容器，並將其包含在 `CreateModel` 的 `Containers` 引數中：

   ```
   preprocessor_container = { 
                  'Image': '<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/<PREPROCESSOR_IMAGE>:<TAG>'
               }
   
   multi_model_container = { 
                 'Image': '<ACCOUNT_ID>.dkr.ecr.<REGION_NAME>.amazonaws.com/<IMAGE>:<TAG>',
                 'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                 'Mode':         'MultiModel'
               }
   
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [preprocessor_container, multi_model_container]
               )
   ```
**注意**  
您只能在序列推論管道中使用一個啟用多模型的端點。

1. (選用) 如您的使用案例無法從模型快取受益，請將 `MultiModelConfig` 參數 `ModelCacheSetting` 欄位的值設為 `Disabled`，並將其包含在呼叫 `create_model` 的 `Container` 引數。`ModelCacheSetting` 欄位的預設值為 `Enabled`。

   ```
   container = { 
                   'Image': image, 
                   'ModelDataUrl': 's3://<BUCKET_NAME>/<PATH_TO_ARTIFACTS>',
                   'Mode': 'MultiModel' 
                   'MultiModelConfig': {
                           // Default value is 'Enabled'
                           'ModelCacheSetting': 'Disabled'
                   }
              }
   
   response = sagemaker_client.create_model(
                 ModelName        = '<MODEL_NAME>',
                 ExecutionRoleArn = role,
                 Containers       = [container]
               )
   ```

1. 為模型設定具 GPU 支援執行個體的多模型端點。建議您將端點設為多個執行個體，以便提供高可用性與更高快取命中。

   ```
   response = sagemaker_client.create_endpoint_config(
                   EndpointConfigName = '<ENDPOINT_CONFIG_NAME>',
                   ProductionVariants=[
                        {
                           'InstanceType':        'ml.g4dn.4xlarge',
                           'InitialInstanceCount': 2,
                           'InitialVariantWeight': 1,
                           'ModelName':            '<MODEL_NAME>',
                           'VariantName':          'AllTraffic'
                         }
                   ]
              )
   ```

1. 使用 `EndpointName` 和 `EndpointConfigName` 參數建立多模型端點。

   ```
   response = sagemaker_client.create_endpoint(
                 EndpointName       = '<ENDPOINT_NAME>',
                 EndpointConfigName = '<ENDPOINT_CONFIG_NAME>')
   ```

# 調用多模型端點
調用多模型端點

若要調用多模型端點，請使用 SageMaker AI 執行時期的 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime.html#SageMakerRuntime.Client.invoke_endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime.html#SageMakerRuntime.Client.invoke_endpoint)，這類似調用單一模型端點，只有一項變更。傳遞新的 `TargetModel` 參數，指定要將目標鎖定於端點的哪些模型。SageMaker AI 執行時期 `InvokeEndpoint` 請求支援利用 `X-Amzn-SageMaker-Target-Model` 做為新標題，這會採用針對調用指定模型的相對路徑。SageMaker AI 系統會將 `CreateModel` API 呼叫提供的字首與模型的相對路徑加以結合，藉此建構模型的絕對路徑。

對於 CPU 與 GPU 支援的多模型端點，下列程序相同。

------
#### [ AWS SDK for Python (Boto 3) ]

下列範例預測請求會在範例筆記本使用 [適用於 Python 的AWS SDK (Boto 3)](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime.html)。

```
response = runtime_sagemaker_client.invoke_endpoint(
                        EndpointName = "<ENDPOINT_NAME>",
                        ContentType  = "text/csv",
                        TargetModel  = "<MODEL_FILENAME>.tar.gz",
                        Body         = body)
```

------
#### [ AWS CLI ]

 下列範例顯示如何利用 AWS Command Line Interface 提出兩行 CSV 請求 (AWS CLI)：

```
aws sagemaker-runtime invoke-endpoint \
  --endpoint-name "<ENDPOINT_NAME>" \
  --body "1.0,2.0,5.0"$'\n'"2.0,3.0,4.0" \
  --content-type "text/csv" \
  --target-model "<MODEL_NAME>.tar.gz"
  output_file.txt
```

如推論成功，就會針對您的推論請求提出具相關資訊的 `output_file.txt`。如需如何使用 進行預測的更多範例 AWS CLI，請參閱 SageMaker Python SDK 文件中的[使用 進行預測 AWS CLI](https://sagemaker.readthedocs.io/en/stable/frameworks/tensorflow/deploying_tensorflow_serving.html#making-predictions-with-the-aws-cli)。

------

多模型端點會視需要動態載入目標模型。您可以在執行 [MME 範例筆記本](https://sagemaker-examples.readthedocs.io/en/latest/advanced_functionality/multi_model_xgboost_home_value/xgboost_multi_model_endpoint_home_value.html)時觀察這一點，因為它會透過對託管於單一端點後方的多個目標模型的隨機調用反覆進行。對指定模型的第一個請求需要比較久的時間，因為必須從 Amazon Simple Storage Service (Amazon S3) 下載模型，然後再載入記憶體。這稱為*冷啟動*，預期在多模型端點進行最佳化，以便為客戶提供更優異的價格效能。後續呼叫完成的速度會比較快，因為載入模型後不會有其他負荷。

**注意**  
對於 GPU 支援的執行個體，若 GPU 容器含有 507 的 HTTP 回應碼，表示記憶體或其他資源不足。這會導致未使用的模型從容器卸載，以便載入更常用的模型。

## 針對 ModelNotReadyException 錯誤重試請求


當您第一次呼叫 `invoke_endpoint` 模型時，系統會從 Amazon Simple Storage Service 下載該模型，並載入推論容器。這會導致第一次呼叫需要更長時間才能返回。由於模型已載入，因此後續對相同模型的呼叫會較快完成。

SageMaker AI 會在呼叫 `invoke_endpoint` 之後，於 60 秒內傳回回應。部分模型太大，無法在 60 秒內下載。如模型未在 60 秒逾時限制之前完成載入，則對 `invoke_endpoint` 提出的請求會傳回錯誤碼 `ModelNotReadyException`，且模型會繼續下載並載入推論容器，最長可達 360 秒。如您收到 `invoke_endpoint` 請求的 `ModelNotReadyException` 錯誤碼，請重試請求。根據預設，Python (Boto 3) AWS SDKs （使用[舊版重試模式](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#legacy-retry-mode)) 和導致`ModelNotReadyException`錯誤的 Java 重試`invoke_endpoint`請求。您可設定重試策略，以便繼續重試請求長達 360 秒。如您預估模型下載並載入容器需要超過 60 秒，請設定 SDK 插槽逾時為 70 秒。如需進一步資訊了解如何針對 適用於 Python (Boto3) 的 AWS SDK設定重試策略，請參閱[設定重試模式](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#configuring-a-retry-mode)。下列程式碼顯示的範例設定重試策略為重試呼叫 `invoke_endpoint`，最長可達 180 秒。

```
import boto3
from botocore.config import Config

# This example retry strategy sets the retry attempts to 2. 
# With this setting, the request can attempt to download and/or load the model 
# for upto 180 seconds: 1 orginal request (60 seconds) + 2 retries (120 seconds)
config = Config(
    read_timeout=70,
    retries={
        'max_attempts': 2  # This value can be adjusted to 5 to go up to the 360s max timeout
    }
)
runtime_sagemaker_client = boto3.client('sagemaker-runtime', config=config)
```

# 新增或移除模型
新增或移除模型

您可以將額外的模型部署到多模型端點，並立即透過該端點進行調用。新增模型時，您不需要更新或關閉端點，因此可避免逐一為各個新模型建立和執行個別端點的費用。對於 CPU 與 GPU 支援的多模型端點，新增及移除模型的程序相同。

 當執行個體達到記憶體容量，且需要下載更多模型至容器時，SageMaker AI 會從容器卸載未使用模型。當磁碟區達到容量且需要下載新模型時，SageMaker AI 也會從執行個體儲存磁碟區刪除未使用模型成品。對新增模型的第一個調用會需要比較久的時間，因為端點需要時間來將模型從 S3 下載到託管端點之執行個體中的容器記憶體

執行端點後，請將一組新的模型成品複製到您要儲存模型的 Amazon S3 位置。

```
# Add an AdditionalModel to the endpoint and exercise it
aws s3 cp AdditionalModel.tar.gz s3://amzn-s3-demo-bucket/path/to/artifacts/
```

**重要**  
若要更新模型，請像新增模型的做法一樣，繼續進行相關步驟。使用新的唯一名稱。請勿覆寫 Amazon S3 的模型成品，因為舊版模型可能仍載入於容器或端點的執行個體儲存磁碟區。接著，對新模型的調用就能調用舊版模型。

一旦儲存在 S3 中，用戶端應用程式即可從其他目標模型中請求取得預測。

```
response = runtime_sagemaker_client.invoke_endpoint(
                        EndpointName='<ENDPOINT_NAME>',
                        ContentType='text/csv',
                        TargetModel='AdditionalModel.tar.gz',
                        Body=body)
```

若要從多模型端點中刪除模型，請停止從用戶端中調用模型，並將其從儲存模型成品的 S3 位置中移除。

# 為 SageMaker AI 多模型端點建置自有容器
使用自有容器

請參閱以下各節了解如何針對多模型端點使用自有容器及相依性。

**Topics**
+ [

## 在 CPU 支援的執行個體為多模型端點提供自有相依性
](#build-multi-model-container-cpu)
+ [

## 在 GPU 支援的執行個體為多模型端點提供自有相依性
](#build-multi-model-container-gpu)
+ [

## 運用 SageMaker AI 推論工具組
](#multi-model-inference-toolkit)
+ [

# 多模型端點的自訂容器合約
](mms-container-apis.md)

## 在 CPU 支援的執行個體為多模型端點提供自有相依性


如預先建置的容器映像都無法滿足您的需求，您可建置自有容器來搭配 CPU 支援的多模型端點使用。

Amazon SageMaker AI 部署的自訂 Amazon Elastic Container Registry (Amazon ECR) 映像應遵守[具託管服務的自訂推論程式碼](your-algorithms-inference-code.md)所述的基本合約，該合約會規範 SageMaker AI 如何與執行您自有推斷程式碼的 Docker 容器進行互動。若是能夠並行載入並為多個模型提供服務的容器，則會有必須遵從的額外 API 和行為。這份額外的合約包含了載入、列出、取得和取消載入模型的 API，以及另一個調用模型的 API。也有 API 必須遵守的不同錯誤情境行為。若要表示容器符合額外的要求，您可以將下列命令新增到 Docker 檔案：

```
LABEL com.amazonaws.sagemaker.capabilities.multi-models=true
```

SageMaker AI 也會將環境變數插入到容器中

```
SAGEMAKER_MULTI_MODEL=true
```

如果您要為序列推論管道建立多模型端點，則 Docker 檔案必須具有多模型和序列推論管道所需的標籤。如需序列資訊管道的詳細資訊，請參閱[使用推論管道執行即時預測](inference-pipeline-real-time.md)。

為協助您實作自訂容器的這些要求，提供下列兩個程式庫：
+ [多模型伺服器](https://github.com/awslabs/multi-model-server)是一種可為機器學習模型提供服務的開放原始碼架構，可安裝於容器中以提供符合新多模型端點容器 API 要求的前端。它可提供多模型端點所需的 HTTP 前端和模型管理功能，以將多個模型託管於單一容器內、動態地將模型載入到容器中及從中取消載入模型，以及在指定的載入模型上執行推斷。它還提供了隨插即用的後端，支援隨插即用的自訂後端處理常式，可讓您實作自己的演算法。
+ [SageMaker AI 推論工具組](https://github.com/aws/sagemaker-inference-toolkit)是使用組態和設定來引導多模型伺服器的程式庫，以使其與 SageMaker AI 多模型端點相容。也可讓您根據不同的情境需求調校重要效能參數，例如每個模型的工作者數量。

## 在 GPU 支援的執行個體為多模型端點提供自有相依性


針對採用由 GPU 支援執行個體的多模型端點，多模型伺服器與 SageMaker AI 推論工具組程式庫目前不支援其運用自有容器 (BYOC) 功能。

若要使用由 GPU 支援的執行個體建立多模型端點，您可利用 SageMaker AI 支援的 [NVIDIA Triton 推論伺服器](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)，並搭配 [NVIDIA Triton 推論容器](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#nvidia-triton-inference-containers-sm-support-only)。若要採用自有相依性，您可採用 SageMaker AI 支援的 [NVIDIA Triton 推論伺服器](https://docs.aws.amazon.com/sagemaker/latest/dg/triton.html)來建置自有容器，做為 Docker 檔案的基礎映像：

```
FROM 301217895009.dkr.ecr.us-west-2.amazonaws.com/sagemaker-tritonserver:22.07-py3
```

**重要**  
若要用於 GPU 支援的多模型端點，具 Triton 推論伺服器的容器是唯一支援的容器。

## 運用 SageMaker AI 推論工具組


**注意**  
SageMaker AI 推論工具組僅支援 CPU 支援的多模型端點。SageMaker AI 推論工具組目前不支援 GPU 支援的多模型端點。

[支援的多模型端點適用演算法、架構與執行個體](multi-model-support.md) 列出支援多模型端點的預先建置容器。如果你想要使用其他任何架構或演算法，則需要建置容器。最簡單的做法是運用 [SageMaker AI 推論工具組](https://github.com/aws/sagemaker-inference-toolkit)來擴展現有預先建置的容器。SageMaker AI 推論工具組是多模型伺服器 (MMS) 的實作，可讓您建立可在 SageMaker AI 部署的端點。如需示範如何設定及部署可在 SageMaker AI 支援多模型端點之自訂容器的範例筆記本，請參閱[多模型端點 BYOC 範例筆記本](https://github.com/awslabs/amazon-sagemaker-examples/tree/master/advanced_functionality/multi_model_bring_your_own)。

**注意**  
SageMaker AI 推論工具組僅支援 Python 模型處理常式。如果您想要以其他任何語言來實作處理常式，則必須建置您自己的容器，以實作其他多模型端點 API。如需相關資訊，請參閱[多模型端點的自訂容器合約](mms-container-apis.md)。

**使用 SageMaker AI 推論工具組來擴展容器**

1. 建立模型處理常式。MMS 需要模型處理常式，這是一個 Python 檔案，其中實作函式來預處理、從模型取得預測，以及在模型處理常式中處理輸出。如需模型處理常式的範例，請參閱範例筆記本中的 [model\$1handler.py](https://github.com/awslabs/amazon-sagemaker-examples/blob/master/advanced_functionality/multi_model_bring_your_own/container/model_handler.py)。

1. 匯入推論工具組，並使用其 `model_server.start_model_server` 函式來啟動 MMS。下列範例來自範例筆記本中的 `dockerd-entrypoint.py` 檔案。請注意，呼叫 `model_server.start_model_server` 會傳遞上一個步驟中描述的模型處理常式：

   ```
   import subprocess
   import sys
   import shlex
   import os
   from retrying import retry
   from subprocess import CalledProcessError
   from sagemaker_inference import model_server
   
   def _retry_if_error(exception):
       return isinstance(exception, CalledProcessError or OSError)
   
   @retry(stop_max_delay=1000 * 50,
          retry_on_exception=_retry_if_error)
   def _start_mms():
       # by default the number of workers per model is 1, but we can configure it through the
       # environment variable below if desired.
       # os.environ['SAGEMAKER_MODEL_SERVER_WORKERS'] = '2'
       model_server.start_model_server(handler_service='/home/model-server/model_handler.py:handle')
   
   def main():
       if sys.argv[1] == 'serve':
           _start_mms()
       else:
           subprocess.check_call(shlex.split(' '.join(sys.argv[1:])))
   
       # prevent docker exit
       subprocess.call(['tail', '-f', '/dev/null'])
       
   main()
   ```

1. 在 `Dockerfile` 中，複製第一個步驟中的模型處理常式，並將上一個步驟中的 Python 檔案指定為 `Dockerfile` 中的進入點。下列幾行來自範例筆記本中使用的 [Dockerfile](https://github.com/awslabs/amazon-sagemaker-examples/blob/master/advanced_functionality/multi_model_bring_your_own/container/Dockerfile)：

   ```
   # Copy the default custom service file to handle incoming data and inference requests
   COPY model_handler.py /home/model-server/model_handler.py
   
   # Define an entrypoint script for the docker image
   ENTRYPOINT ["python", "/usr/local/bin/dockerd-entrypoint.py"]
   ```

1. 建置並註冊容器。範例筆記本中有下列殼層指令碼，可建置容器，並上傳到您 AWS 帳戶的 Amazon Elastic Container Registry 儲存庫：

   ```
   %%sh
   
   # The name of our algorithm
   algorithm_name=demo-sagemaker-multimodel
   
   cd container
   
   account=$(aws sts get-caller-identity --query Account --output text)
   
   # Get the region defined in the current configuration (default to us-west-2 if none defined)
   region=$(aws configure get region)
   region=${region:-us-west-2}
   
   fullname="${account}.dkr.ecr.${region}.amazonaws.com/${algorithm_name}:latest"
   
   # If the repository doesn't exist in ECR, create it.
   aws ecr describe-repositories --repository-names "${algorithm_name}" > /dev/null 2>&1
   
   if [ $? -ne 0 ]
   then
       aws ecr create-repository --repository-name "${algorithm_name}" > /dev/null
   fi
   
   # Get the login command from ECR and execute it directly
   $(aws ecr get-login --region ${region} --no-include-email)
   
   # Build the docker image locally with the image name and then push it to ECR
   # with the full name.
   
   docker build -q -t ${algorithm_name} .
   docker tag ${algorithm_name} ${fullname}
   
   docker push ${fullname}
   ```

現在，您可以使用此容器在 SageMaker AI 部署多模型端點。

**Topics**
+ [

## 在 CPU 支援的執行個體為多模型端點提供自有相依性
](#build-multi-model-container-cpu)
+ [

## 在 GPU 支援的執行個體為多模型端點提供自有相依性
](#build-multi-model-container-gpu)
+ [

## 運用 SageMaker AI 推論工具組
](#multi-model-inference-toolkit)
+ [

# 多模型端點的自訂容器合約
](mms-container-apis.md)

# 多模型端點的自訂容器合約
API 容器合約

若要處理多個模型，容器必須支援一組可讓 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
載入模型

指示容器將主體 `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
列出模型

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

```
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
取得模型

這是 `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
卸載模型 API

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

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

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

## 調用模型 API
調用模型

從提供的特定 `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，然後啟動卸載未使用模型以便進行回收。

# 多模型端點安全
安全

多模型端點中的模型和資料共同位於執行個體儲存磁碟區和容器記憶體中。Amazon SageMaker AI 端點的所有執行個體都會在您擁有的單一租用戶容器上執行。只有您的模型才能在您的多模型端點上執行。您有責任管理請求與模型的對應，並向使用者提供正確目標模型的存取權。SageMaker AI 使用 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 來提供 IAM 身分型政策，您可用以指定允許或拒絕的動作與資源，以及在何種條件下允許或拒絕動作。

根據預設，具多模型端點 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 許可的 IAM 主體可在 S3 字首位址 (定義於 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) 操作) 調用任何模型，前提是操作所定義的 IAM 執行角色具下載模型的權限。如果您需要限制 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 存取 S3 的一組有限模型，您可以執行下列其中一項操作：
+ 使用 `sagemaker:TargetModel` IAM 條件金鑰，限制 `InvokeEndpont` 呼叫為託管於端點的特定模型。例如，下列政策只有在 `TargetModel` 欄位的值符合其中一個指定常規表達式時，才能允許 `InvokeEndpont` 請求：

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Action": [
                  "sagemaker:InvokeEndpoint"
              ],
              "Effect": "Allow",
              "Resource":
              "arn:aws:sagemaker:us-east-1:111122223333:endpoint/endpoint_name",
              "Condition": {
                  "StringLike": {
                      "sagemaker:TargetModel": ["company_a/*", "common/*"]
                  }
              }
          }
      ]
  }
  ```

------

  如需 SageMaker AI 條件金鑰的相關資訊，請參閱《AWS Identity and Access Management 使用者指南》**的[適用 Amazon SageMaker AI 的條件金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsagemaker.html#amazonsagemaker-policy-keys)。
+ 建立具有更多限制性 S3 字首的多模型端點。

如需詳細資訊了解 SageMaker AI 如何使用角色來管理對端點的存取權以及如何代表您執行作業，請參閱[如何使用 SageMaker AI 執行角色](sagemaker-roles.md)。客戶可能也有各自的合規要求所指定的某些資料隔離需求，這些需求可透過 IAM 身分達成。

# 多模型端點部署的 CloudWatch 指標


Amazon SageMaker AI 為端點提供指標，讓您能夠監控快取命中率、載入模型數量，以及在多模型端點的載入、下載和上傳的模型等候時間。CPU 與 GPU 支援的多模型端點有部分指標不同，因此以下各節說明可用於每種類型多模型端點的 Amazon CloudWatch 指標。

如需有關指標的詳細資訊，請參閱[Amazon CloudWatch 中的 Amazon SageMaker AI 指標](monitoring-cloudwatch.md)的**多模型端點模型載入指標**與**多模型端點模型執行個體指標**。不支援依據模型的指標功能。

## 適用 CPU 支援多模型端點的 CloudWatch 指標


您可在 CPU 支援的多模型端點監視下列指標。

`AWS/SageMaker` 命名空間包含下列從呼叫到 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 的模型載入指標。

指標是以 1 分鐘的頻率提供。

如需資訊了解 CloudWatch 指標的保留期間，請參閱 *Amazon CloudWatch API 參考*的 [GetMetricStatistics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)。

**多模型端點的模型載入指標**


| 指標 | Description | 
| --- | --- | 
| ModelLoadingWaitTime  |  調用請求為了執行推斷而等候目標模型下載或載入 (或這兩項作業) 的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelUnloadingTime  |  透過容器 `UnloadModel` API 呼叫取消載入模型所花費的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelDownloadingTime |  從 Amazon Simple Storage Service (Amazon S3) 下載模型所花費的時間間隔。 單位：微秒 有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelLoadingTime  |  透過容器 `LoadModel` API 呼叫載入模型所花費的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelCacheHit  |  傳送到已載入模型之多模型端點的 `InvokeEndpoint` 請求數目。 平均統計資料會顯示已載入模型的請求比率。 單位：無 有效的統計資料：平均、總和、範例計數  | 

**多模型端點的模型載入指標維度**


| 維度 | Description | 
| --- | --- | 
| EndpointName, VariantName |  針對指定端點與變體的 `ProductionVariant` 篩選端點調用指標。  | 

`/aws/sagemaker/Endpoints` 命名空間包含下列從呼叫到 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 的執行個體指標。

指標是以 1 分鐘的頻率提供。

如需資訊了解 CloudWatch 指標的保留期間，請參閱 *Amazon CloudWatch API 參考*的 [GetMetricStatistics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)。

**多模型端點的模型執行個體指標**


| 指標 | Description | 
| --- | --- | 
| LoadedModelCount  |  多模型端點的容器中所載入的模型數目。此指標會按每個執行個體發出。 週期為 1 分鐘的平均統計資料會說明每個執行個體載入的模型平均數目。 總和統計資料會說明端點的所有執行個體中所載入的模型總數目。 此指標追蹤的模型不一定是唯一的，因為模型可能會在端點的多個容器中載入。 單位：無 有效的統計資訊：平均、總和、下限、上限與範例計數  | 
| CPUUtilization  |  每個個別 CPU 核心使用率的總和。每個核心範圍的 CPU 利用率為 0 到 100。例如，如果有四個 CPU，則 `CPUUtilization` 的範圍為 0% 到 400%。 對於端點變體，值為執行個體上主要容器與輔助容器的 CPU 利用率總和。 單位：百分比  | 
| MemoryUtilization |  執行個體上的容器使用的記憶體的百分比。此值範圍為 0%–100%。 對於端點變體，值為執行個體上主要容器與輔助容器的記憶體利用率總和。 單位：百分比  | 
| DiskUtilization |  執行個體容器運用的磁碟空間百分比。此值範圍為 0%–100%。 針對端點變體，值為執行個體上主要容器與輔助容器的磁碟空間利用率總和。 單位：百分比  | 

## GPU 多模型端點部署的 CloudWatch 指標


您可在 GPU 支援的多模型端點監視下列指標。

`AWS/SageMaker` 命名空間包含下列從呼叫到 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 的模型載入指標。

指標是以 1 分鐘的頻率提供。

如需資訊了解 CloudWatch 指標的保留期間，請參閱 *Amazon CloudWatch API 參考*的 [GetMetricStatistics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)。

**多模型端點的模型載入指標**


| 指標 | Description | 
| --- | --- | 
| ModelLoadingWaitTime  |  調用請求為了執行推斷而等候目標模型下載或載入 (或這兩項作業) 的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelUnloadingTime  |  透過容器 `UnloadModel` API 呼叫取消載入模型所花費的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelDownloadingTime |  從 Amazon Simple Storage Service (Amazon S3) 下載模型所花費的時間間隔。 單位：微秒 有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelLoadingTime  |  透過容器 `LoadModel` API 呼叫載入模型所花費的時間間隔。 單位：微秒  有效的統計資訊：平均、總和、下限、上限與範例計數   | 
| ModelCacheHit  |  傳送到已載入模型之多模型端點的 `InvokeEndpoint` 請求數目。 平均統計資料會顯示已載入模型的請求比率。 單位：無 有效的統計資料：平均、總和、範例計數  | 

**多模型端點的模型載入指標維度**


| 維度 | Description | 
| --- | --- | 
| EndpointName, VariantName |  針對指定端點與變體的 `ProductionVariant` 篩選端點調用指標。  | 

`/aws/sagemaker/Endpoints` 命名空間包含下列從呼叫到 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 的執行個體指標。

指標是以 1 分鐘的頻率提供。

如需資訊了解 CloudWatch 指標的保留期間，請參閱 *Amazon CloudWatch API 參考*的 [GetMetricStatistics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)。

**多模型端點的模型執行個體指標**


| 指標 | Description | 
| --- | --- | 
| LoadedModelCount  |  多模型端點的容器中所載入的模型數目。此指標會按每個執行個體發出。 週期為 1 分鐘的平均統計資料會說明每個執行個體載入的模型平均數目。 總和統計資料會說明端點的所有執行個體中所載入的模型總數目。 此指標追蹤的模型不一定是唯一的，因為模型可能會在端點的多個容器中載入。 單位：無 有效的統計資訊：平均、總和、下限、上限與範例計數  | 
| CPUUtilization  |  每個個別 CPU 核心使用率的總和。每個核心的 CPU 使用率範圍為 0‐100。例如，如有四個 CPU，`CPUUtilization` 的範圍為 0%–400%。 對於端點變體，值為執行個體上主要容器與輔助容器的 CPU 利用率總和。 單位：百分比  | 
| MemoryUtilization |  執行個體上的容器使用的記憶體的百分比。此值範圍為 0%-100%。 對於端點變體，值為執行個體上主要容器與輔助容器的記憶體利用率總和。 單位：百分比  | 
| GPUUtilization |  執行個體上的容器使用的 GPU 單位的百分比。此值範圍可介於 0‐100，乘以 GPU 數量。例如，如有四個 GPU，`GPUUtilization` 的範圍為 0%–400%。 對於端點變體，值為執行個體上主要容器與輔助容器的 GPU 利用率總和。 單位：百分比  | 
| GPUMemoryUtilization |  執行個體上的容器使用的 GPU 記憶體的百分比。此值範圍為 0‐100，乘以 GPU 數量。例如，如有四個 GPU，`GPUMemoryUtilization` 的範圍為 0%–400%。 對於端點變體，值為執行個體上主要容器與輔助容器的 GPU 記憶體利用率總和。 單位：百分比  | 
| DiskUtilization |  執行個體容器運用的磁碟空間百分比。此值範圍為 0%–100%。 針對端點變體，值為執行個體上主要容器與輔助容器的磁碟空間利用率總和。 單位：百分比  | 

# 設定 SageMaker AI 多模型端點模型快取行為


根據預設，多模型端點會在記憶體 (CPU 或 GPU，視您擁有 CPU 或 GPU 支援的執行個體而定) 與磁碟快取常用模型，以便提供低延遲推論。僅當容器用完記憶體或磁碟空間無法容納新目標模型時，才會從磁碟卸載和/或刪除已快取模型。

您可變更多模型端點的快取行為，並在呼叫 [create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) 時，設定 `ModelCacheSetting` 參數來明確啟用或停用模型快取。

對於不受益於模型快取的使用案例，建議設定 `ModelCacheSetting` 參數的值為 `Disabled`。例如，當需要從端點為大量模型提供服務，但每個模型僅調用一次 (或很少使用) 時。對於這類使用案例，若設定 `ModelCacheSetting` 參數的值為 `Disabled`，則相較於預設快取模式，可提高 `invoke_endpoint` 請求的每秒交易數 (TPS)。在這些使用案例，TPS 較高是因為 SageMaker AI 會在 `invoke_endpoint` 請求之後執行下列動作：
+ 以非同步方式從記憶體卸載模型，並在調用模型之後立即從磁碟刪除該模型。
+ 在推論容器為下載及載入模型提供更高並行性。對於 CPU 與 GPU 支援的端點而言，並行是容器執行個體 vCPU 數目的因素之一。

如需指導方針了解如何針對多模型端點選擇 SageMaker AI 機器學習 (ML) 執行個體類型，請參閱[多模型端點部署的執行個體建議](multi-model-endpoint-instance.md)。

# 為多模型端點部署設定自動擴展政策


SageMaker AI 多模型端點完全支援自動擴展 ，其可管理模型複本，確保模型根據流量模式進行擴展。建議您根據 [多模型端點部署的執行個體建議](multi-model-endpoint-instance.md) 來設定多模型端點與執行個體大小，也請為端點設定基於執行個體的自動擴展功能。用來觸發自動擴展事件的調用率，是根據由端點提供服務之整組模型之間的彙總預測集合。如需有關設定端點自動擴展的其他詳細資訊，請參閱[自動化擴展 Amazon SageMaker AI 模型](https://docs.aws.amazon.com/sagemaker/latest/dg/endpoint-auto-scaling.html)。

您可在 CPU 與 GPU 支援的多模型端點利用預先定義及自訂指標來設定自動擴展政策。

**注意**  
SageMaker AI 多模型端點指標可用於 1 分鐘的精細程度。

## 定義擴展政策


若要指定擴展政策的指標和目標值，您可設定目標追蹤擴展政策。您可以使用預先定義的指標或自訂指標。

擴展政策的組態設定是以 JSON 區塊表示。您會將擴展政策的組態設定，儲存為文字檔案中的 JSON 區塊。叫用 AWS CLI 或 Application Auto Scaling API 時，您可以使用該文字檔案。如需政策組態語法的詳細資訊，請參閱 *Application Auto Scaling API 參考*中的 `[TargetTrackingScalingPolicyConfiguration](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_TargetTrackingScalingPolicyConfiguration.html)`。

您可使用下列的選項，來定義目標追蹤擴展政策的組態設定。

### 使用預先定義的指標


若要快速定義變體的目標追蹤擴展政策，請使用 `SageMakerVariantInvocationsPerInstance` 預先定義的指標。`SageMakerVariantInvocationsPerInstance` 是每個變體執行個體每分鐘調用的平均次數。我們強烈建議您使用此指標。

若要在擴展政策中使用預先定義的指標，請為您的政策建立目標追蹤組態設定。在目標追蹤的組態設定中，請針對預先定義的指標加入 `PredefinedMetricSpecification`，以及針對該指標的目標值加入 `TargetValue`。

下列的範例是變體目標追蹤擴展的典型政策組態設定。在此一組態設定中，我們使用了 `SageMakerVariantInvocationsPerInstance` 這個預先定義的指標，來調整變體執行個體的數量，如此每個執行個體的 `InvocationsPerInstance` 指標值都是 `70`。

```
{"TargetValue": 70.0,
    "PredefinedMetricSpecification":
    {
        "PredefinedMetricType": "InvocationsPerInstance"
    }
}
```

**注意**  
建議您在運用多模型端點時採用 `InvocationsPerInstance`。此指標的 `TargetValue` 取決於應用程式的延遲需求。同時建議您對端點進行負載測試，以便設定合適的擴展參數值。若要進一步了解如何為端點進行負載測試及設定自動擴展，請參閱以下部落格：[在 Amazon SageMaker AI 設定自動擴展推論端點](https://aws.amazon.com/blogs/machine-learning/configuring-autoscaling-inference-endpoints-in-amazon-sagemaker/)。

### 使用自訂的指標


如果您需要制定目標追蹤擴展政策，來滿足您的自訂需求，請定義自訂的指標。您可以根據與擴展成比例變動的任何生產變體指標，來定義自訂的指標。

並非所有的 SageMaker AI 指標都適用於目標追蹤。指標必須是有效的使用率指標，而且必須能夠表示執行個體的忙碌程度。指標的值必須與變體執行個體的數量，反向地按比例增加或減少。也就是說，當執行個體的數量增加時，指標的值就應該減少。

**重要**  
在生產運作中部署自動擴展功能之前，您必須使用自訂的指標來測試此項功能。

#### CPU 支援多模型端點的自訂指標範例


下列的範例是擴展政策的目標追蹤組態設定。在此組態，針對名為 `my-model` 的模型，自訂指標 `CPUUtilization` 會根據所有執行個體 50% 的平均 CPU 使用率來調整端點的執行個體計數。

```
{"TargetValue": 50,
    "CustomizedMetricSpecification":
    {"MetricName": "CPUUtilization",
        "Namespace": "/aws/sagemaker/Endpoints",
        "Dimensions": [
            {"Name": "EndpointName", "Value": "my-endpoint" },
            {"Name": "ModelName","Value": "my-model"}
        ],
        "Statistic": "Average",
        "Unit": "Percent"
    }
}
```

#### GPU 支援多模型端點的自訂指標範例


下列的範例是擴展政策的目標追蹤組態設定。在此組態，針對名為 `my-model` 的模型，自訂指標 `GPUUtilization` 會根據所有執行個體50% 的平均 GPU 使用率來調整端點的執行個體計數。

```
{"TargetValue": 50,
    "CustomizedMetricSpecification":
    {"MetricName": "GPUUtilization",
        "Namespace": "/aws/sagemaker/Endpoints",
        "Dimensions": [
            {"Name": "EndpointName", "Value": "my-endpoint" },
            {"Name": "ModelName","Value": "my-model"}
        ],
        "Statistic": "Average",
        "Unit": "Percent"
    }
}
```

## 新增冷卻時間


若要針對端點的橫向擴展來新增冷卻時間，請指定 `ScaleOutCooldown` 的值 (秒)。同樣地，若要針對模型的規模縮減來新增冷卻時間，請新增 `ScaleInCooldown` 的值 (秒)。如需 `ScaleInCooldown` 和 `ScaleOutCooldown` 的詳細資訊，請參閱 *Application Auto Scaling API 參考*中的 `[TargetTrackingScalingPolicyConfiguration](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_TargetTrackingScalingPolicyConfiguration.html)`。

下列的範例是擴展政策的目標追蹤組態設定。此組態採用預先定義指標 `SageMakerVariantInvocationsPerInstance`，以便根據該變體所有執行個體的 `70` 平均值來調整擴展。這個組態設定分別提供了 10 分鐘的規模縮減冷卻時間，和 5 分鐘的橫向擴展冷卻時間。

```
{"TargetValue": 70.0,
    "PredefinedMetricSpecification":
    {"PredefinedMetricType": "SageMakerVariantInvocationsPerInstance"
    },
    "ScaleInCooldown": 600,
    "ScaleOutCooldown": 300
}
```

# 多容器端點


SageMaker AI 多容器端點方便客戶在單一 SageMaker AI 端點上部署使用不同模型或架構的多個容器。容器可按順序作為推論管道執行，或者透過直接調用個別存取每個容器，以提高端點使用率並最佳化成本。

如需有關如何依序調用多容器端點中容器的資訊，請參閱[Amazon SageMaker AI 中的推論管道](inference-pipelines.md)。

如需有關調用多容器端點中特定容器的資訊，請參閱[透過直接調用調用多容器端點](multi-container-direct.md)

**Topics**
+ [

# 建立多容器端點 (Boto 3)
](multi-container-create.md)
+ [

# 更新多容器端點
](multi-container-update.md)
+ [

# 透過直接調用調用多容器端點
](multi-container-direct.md)
+ [

# 具有直接調用的多容器端點的安全性
](multi-container-security.md)
+ [

# 具有直接調用的多容器端點指標
](multi-container-metrics.md)
+ [

# 自動擴展多容器端點
](multi-container-auto-scaling.md)
+ [

# 排解多容器端點問題
](multi-container-troubleshooting.md)

# 建立多容器端點 (Boto 3)


透過呼叫 [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)、[CreateEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html) 和 [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) API，來建立多容器端點，方法就如同建立任何其他端點一樣。您可以循序執行這些容器作為推論管道，或使用直接調用來執行每個個別的容器。多容器端點在您呼叫 `create_model` 時具有下列要求：
+ 請改用 `Containers`參數而非 `PrimaryContainer`，並在 `Containers`參數中納入超過一個容器。
+ 具有直接調用的多容器端點中的每個容器都需要 `ContainerHostname`參數。
+ 將 `InferenceExecutionConfig`欄位的 `Mode`參數設為 `Direct`，以直接調用每個容器，或透過 `Serial`來使用容器作為推論管道。預設模式為 `Serial`。

**注意**  
目前，設有多容器端點最多支援 15 個容器的限制。

下列範例中會建立多容器模型以供直接調用。

1. 透過直接調用建立容器元素和 `InferenceExecutionConfig`。

   ```
   container1 = {
                    'Image': '123456789012.dkr.ecr.us-east-1.amazonaws.com/myimage1:mytag',
                    'ContainerHostname': 'firstContainer'
                }
   
   container2 = {
                    'Image': '123456789012.dkr.ecr.us-east-1.amazonaws.com/myimage2:mytag',
                    'ContainerHostname': 'secondContainer'
                }
   inferenceExecutionConfig = {'Mode': 'Direct'}
   ```

1. 使用容器元素建立模型並設定 `InferenceExecutionConfig`欄位。

   ```
   import boto3
   sm_client = boto3.Session().client('sagemaker')
   
   response = sm_client.create_model(
                  ModelName = 'my-direct-mode-model-name',
                  InferenceExecutionConfig = inferenceExecutionConfig,
                  ExecutionRoleArn = role,
                  Containers = [container1, container2]
              )
   ```

若要建立端點，您必須像建立任何其他端點一樣，呼叫 [create\$1endpoint\$1config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) 和 [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint)。

# 更新多容器端點


若要更新 Amazon SageMaker AI 多容器端點，請完成下列步驟。

1.  呼叫 [create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) 來建立新模型，其中 `InferenceExecutionConfig` 欄位的 `Mode` 參數有新的值。

1.  呼叫 [create\$1endpoint\$1config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config)，透過使用您在上一個步驟中建立的新模型，以不同名稱建立新的端點組態。

1.  呼叫 [update\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.update_endpoint)，使用您在上一個步驟中建立的新端點組態來更新端點。

# 透過直接調用調用多容器端點


SageMaker AI 多容器端點方便客戶部署多個容器，以在 SageMaker AI 端點上部署不同的模型。您最多可以在單一端點上託管 15 個不同的推論容器。透過使用直接調用，您可以將請求傳送至託管在多容器端點上的特定推論容器。

 要使用直接調用來調用多容器端點，請如同調用任何其他端點一樣呼叫 [invoke\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-runtime.html#SageMakerRuntime.Client.invoke_endpoint)，並使用 `TargetContainerHostname`參數指定您要調用的容器。

 

 下列範例會直接調用多容器端點的 `secondContainer`，以取得預測。

```
import boto3
runtime_sm_client = boto3.Session().client('sagemaker-runtime')

response = runtime_sm_client.invoke_endpoint(
   EndpointName ='my-endpoint',
   ContentType = 'text/csv',
   TargetContainerHostname='secondContainer', 
   Body = body)
```

 對於向多容器端點的每個直接調用請求，只有具有 `TargetContainerHostname`的容器才能處理調用請求。如果您執行下列任何操作，將會收到驗證錯誤：
+ 指定未存在端點的 `TargetContainerHostname`
+ 未在設為直接調用的端點請求中指定 `TargetContainerHostname`的值
+ 在端點請求中指定未設為直接調用的 `TargetContainerHostname`值。

# 具有直接調用的多容器端點的安全性


 對於具有直接調用的多容器端點，透過共用記憶體和儲存磁碟區，在單一執行個體中託管多個容器。您有責任使用安全容器、維護請求與目標容器的正確映射，以及為使用者提供目標容器正確的存取權。SageMaker AI 使用 IAM 角色提供 IAM 身分型政策，方便您透過這些政策指定是否允許或拒絕對該角色存取資源，以及在何種條件下可進行存取。如需 IAM 角色的資訊，請參閱*AWS Identity and Access Management 使用者指南*中的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。如需有關身分型政策的資訊，請參閱[身分型政策和資源型政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html)。

預設情況下，具有直接調用之多容器端點 `InvokeEndpoint` 許可的 IAM 主體，可以調用您在呼叫 `invoke_endpoint` 時指定的端點名稱中端點內的任何容器。如需限制 `invoke_endpoint`對多容器端點內的一組有限容器的存取，請使用 `sagemaker:TargetContainerHostname`IAM 條件索引鍵。下列政策顯示如何限制端點內特定容器的呼叫。

下列政策只有在 `TargetContainerHostname`欄位的值符合其中一個指定規則表達式時，才能允許 `invoke_endpoint`請求。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "sagemaker:InvokeEndpoint"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:sagemaker:us-east-1:111122223333:endpoint/endpoint_name",
            "Condition": {
                "StringLike": {
                    "sagemaker:TargetModel": [
                        "customIps*",
                        "common*"
                    ]
                }
            }
        }
    ]
}
```

------

當 `TargetContainerHostname`欄位的值符合 `Deny`陳述式中指定的規則表達式之一時，下列政策會拒絕 `invoke_endpoint`請求。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "sagemaker:InvokeEndpoint"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:sagemaker:us-east-1:111122223333:endpoint/endpoint_name",
            "Condition": {
                "StringLike": {
                    "sagemaker:TargetModel": [
                        "model_name*"
                    ]
                }
            }
        },
        {
            "Action": [
                "sagemaker:InvokeEndpoint"
            ],
            "Effect": "Deny",
            "Resource": "arn:aws:sagemaker:us-east-1:111122223333:endpoint/endpoint_name",
            "Condition": {
                "StringLike": {
                    "sagemaker:TargetModel": [
                        "special-model_name*"
                    ]
                }
            }
        }
    ]
}
```

------

 如需有關 SageMaker AI 條件索引鍵的資訊，請參閱 *AWS Identity and Access Management 使用者指南*中的 [SageMaker AI 條件索引鍵](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsagemaker.html#amazonsagemaker-policy-keys)。

# 具有直接調用的多容器端點指標


除了 [Amazon CloudWatch 中的 Amazon SageMaker AI 指標](monitoring-cloudwatch.md) 中列出的端點指標之外，SageMaker AI 另根據每個容器提供指標。

具有直接調用的多容器端點的每個容器指標位於 CloudWatch 中，並分為兩個命名空間：`AWS/SageMaker` 和 `aws/sagemaker/Endpoints`。`AWS/SageMaker` 命名空間包含調用相關的指標，`aws/sagemaker/Endpoints` 命名空間則包含記憶體和 CPU 使用率指標。

下表列出具有直接調用之多容器端點的每個容器指標。所有指標都使用 [`EndpointName, VariantName, ContainerName`] 維度，該維度會針對特定變體篩選特定端點的指標，並對應於特定容器。這些指標與推論管道共用相同的指標名稱，但僅限每個容器層級 [`EndpointName, VariantName, ContainerName`]。

 


|  |  |  |  | 
| --- |--- |--- |--- |
|  指標名稱  |  Description  |  維度  |  NameSpace  | 
|  Invocations  |  傳送至端點內容器的 InvokeEndpoint請求數量。若要取得傳送至容器的請求總數，請使用 Sum統計資料。單位：無有效統計資料：Sum、Sample Count |  EndpointName, VariantName, ContainerName  | AWS/SageMaker | 
|  Invocation4XX Errors  |  模型傳回某特定容器 4xxHTTP 回應代碼以回應的 InvokeEndpoint請求數量。對於每個 4xx 回應，SageMaker AI 會傳送 1。單位：無有效統計資料：Average、Sum |  EndpointName, VariantName, ContainerName  | AWS/SageMaker | 
|  Invocation5XX Errors  |  模型傳回某特定容器 5xxHTTP 回應代碼以回應的 InvokeEndpoint請求數量。對於每個 5xx 回應，SageMaker AI 會傳送 1。單位：無有效統計資料：Average、Sum |  EndpointName, VariantName, ContainerName  | AWS/SageMaker | 
|  ContainerLatency  |  從 SageMaker AI 的觀點來看，目標容器做出回應所花的時間。ContainerLatency 包含傳送請求、從模型的容器擷取回應，以及在容器中完成推論所花的時間。單位：微秒有效統計資料：Average、Sum、Min、Max、Sample Count |  EndpointName, VariantName, ContainerName  | AWS/SageMaker | 
|  OverheadLatency  |  在回應用戶端請求而花費的時間中，SageMaker AI 為了處理額外負荷而另外花費的時間。OverheadLatency 的計算是從 SageMaker AI 收到請求，直到回應傳回給用戶端的時間再減去 ModelLatency。額外負荷延遲可能隨著請求和回應承載大小、請求頻率，以及請求的身分驗證或授權等因素而不同。單位：微秒有效統計資料：Average、Sum、Min、Max、'樣本計數' |  EndpointName, VariantName, ContainerName  | AWS/SageMaker | 
|  CPUUtilization  | 執行個體上執行的各個容器所使用的 CPU 單位百分比。值的範圍從 0% 到 100%，並乘以 CPU 的數量。例如，如果有四個 CPU，CPUUtilization 的範圍可能從 0% 到 400%。對於具有直接調用的端點，CPUUtilization 指標的數量等於該端點中的容器數量。單位：百分比  |  EndpointName, VariantName, ContainerName  | aws/sagemaker/Endpoints | 
|  MemoryUtilizaton  |  執行個體上執行的各個容器所使用的記憶體百分比。這個值的範圍從 0% 到 100%。與 CPUUtilization 類似，在具有直接調用的端點中，MemoryUtilization 指標的數量等於該端點中的容器數量。單位：百分比  |  EndpointName, VariantName, ContainerName  | aws/sagemaker/Endpoints | 

上表中的所有指標都特定於具有直接調用的多容器端點。除了這些特殊的每個容器指標之外，在變體層級也有指標 `[EndpointName, VariantName]`，其中包含表格中所有預期 `ContainerLatency`指標的維度。

# 自動擴展多容器端點


如果您想要使用 `InvocationsPerInstance`指標為多容器端點設定自動擴展，建議您每個容器中的模型在每個推論請求上顯示類似的 CPU 利用率和延遲。會建議這麼做，是因為如果到多容器端點的流量從低 CPU 利用率模型轉換為高 CPU 利用率模型，但整體呼叫量維持不變，則端點將不會向外擴展，並且可能沒有足夠的執行個體來處理對高 CPU 利用率模型的所有請求。如需設定自動擴展端點的資訊，請參閱[Amazon SageMaker AI 模型的自動擴展](endpoint-auto-scaling.md)。

# 排解多容器端點問題


下列各節可協助您排解多容器端點的錯誤。

## Ping 運作狀態檢查錯誤


 使用多容器時，端點記憶體和 CPU 會在端點建立期間承受較高的壓力。具體而言，`MemoryUtilization` 和 `CPUUtilization`指標高於單一容器端點，因為使用率壓力與容器數量成正比。因此，建議您選擇具有足夠記憶體和 CPU 的執行個體類型，以確保執行個體上有足夠的記憶體，來載入所有模型 (部署推論管道時也適用相同的原則)。否則，您的端點建立步驟可能會失敗並顯示錯誤訊息，例如：`XXX did not pass the ping health check`。

## 缺少 accept-bind-to-port=true Docker 標籤


多容器端點中的容器會接聽 `SAGEMAKER_BIND_TO_PORT`環境變數指定的連接埠 (而非 8080)。當容器在多容器端點中執行時，SageMaker AI 會自動將此環境變數提供給容器。如果此環境變數不存在，容器預設使用連接埠 8080。若要表示您的容器符合此需求，請使用下列命令，將標籤新增到您的 Dockerfile：

```
LABEL com.amazonaws.sagemaker.capabilities.accept-bind-to-port=true
```

 否則，您將看到一則錯誤訊息，例如：`Your Ecr Image XXX does not contain required com.amazonaws.sagemaker.capabilities.accept-bind-to-port=true Docker label(s).`

 如果您的容器需要接聽第二個連接埠，請選擇 `SAGEMAKER_SAFE_PORT_RANGE` 環境變數指定的範圍內的連接埠。將此值以 *XXXX*-*YYYY* 格式的包含範圍來指定，其中 XXXX 和 YYYY 是兩個多位數整數。當您在多容器端點中執行容器時，SageMaker AI 會自動提供此值。

# Amazon SageMaker AI 中的推論管道
推論管道

*推論管道*是一種由兩個到十五個直線順序容器構成的 Amazon SageMaker AI 模型，可處理資料推論的請求。您可以使用推論管道定義和部署任意的演算法組合，包括預先訓練的 SageMaker AI 內建演算法。以及您自己封裝在 Docker 容器中的自訂演算法。您可以使用推論管道來合併預先處理、預測及後續處理資料科學任務。推論管道是全受管。

您可以新增 SageMaker AI Spark ML Serving 和 scikit-learn 容器，重複使用針對訓練模型開發的資料轉換器。整個組合的推論管道可視為 SageMaker AI 模型，可用來進行即時預測或直接處理批次轉換，完全不需要任何外部預先處理。

在推論管道模型內，SageMaker AI 會將調用當成一系列 HTTP 請求來處理。管道中的第一個容器處理最初的請求，然後將中間的回應當作請求傳送給第二個容器，以此類推，遍及管道中的每個容器。SageMaker AI 會將最終回應傳回用戶端。

您部署管道模型時，SageMaker AI 會在端點或轉換任務中，於每個 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體安裝和執行所有容器。特徵處理和推論以低延遲執行，因為容器共置於同一個 EC2 執行個體。您可以使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) 操作或從主控台，定義適用於管道模型的容器。您可以使用 `Containers` 參數來設定構成管道的容器，而不是設定一個 `PrimaryContainer`。您也可以指定容器執行的順序。

管道模型是不可變的，但您可以使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html) 操作來開發新的模型，以更新推論管道。本模組化在試驗期間支援更大的靈活性。

如需有關如何使用 SageMaker 模型註冊庫建立推論管道的資訊，請參閱[使用模型註冊庫進行模型註冊部署](model-registry.md)。

使用這項功能無須額外成本。您只需為端點上執行的執行個體付費。

**Topics**
+ [

## 推論管道的範例筆記本
](#inference-pipeline-sample-notebooks)
+ [

# 使用 SparkML 和 Scikit-learn 進行特徵處理
](inference-pipeline-mleap-scikit-learn-containers.md)
+ [

# 建立管道模型
](inference-pipeline-create-console.md)
+ [

# 使用推論管道執行即時預測
](inference-pipeline-real-time.md)
+ [

# 使用推論管道執行批次轉換
](inference-pipeline-batch.md)
+ [

# 推論管道日誌和指標
](inference-pipeline-logs-metrics.md)
+ [

# 推論管道的故障診斷
](inference-pipeline-troubleshoot.md)

## 推論管道的範例筆記本
範例筆記本

如需示範如何建立和部署推論管道的範例，請參閱[具有 Scikit-learn 和線性學習程式的推論管道](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-python-sdk/scikit_learn_inference_pipeline)範例筆記本。如需建立和存取您可以用來在 SageMaker AI 執行範例的 Jupyter 筆記本執行個體說明，請參閱[Amazon SageMaker 筆記本執行個體](nbi.md)。

若要查看所有 SageMaker AI 範例的清單，請在建立並開啟筆記本執行個體後，選擇 **SageMaker AI 範例**標籤。有三個推論管道筆記本。剛說明的前兩個推論管道筆記本位於 `advanced_functionality` 資料夾，第三個筆記本則位於 `sagemaker-python-sdk` 資料夾。若要開啟筆記本，請選擇其**使用**標籤，然後選擇**建立複本**。

# 使用 SparkML 和 Scikit-learn 進行特徵處理
使用 Spark ML 和 Scikit-learn 來處理特徵

使用 Amazon SageMaker AI 內建演算法或自訂演算法訓練模型之前，您可以使用 Spark 和 scikit-learn 前置處理器轉換資料及設計特徵。

## 使用 Spark ML 進行特徵處理


您可以透過 [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html) 這個無伺服器 ETL (擷取、轉換、載入) 服務，從您的 SageMaker AI 筆記本執行 Spark ML 任務。您也可以連接到現有的 EMR 叢集，以透過 [Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-what-is-emr.html) 執行 Spark ML 任務。若要這樣做，您需要一個 AWS Identity and Access Management (IAM) 角色，授予從 SageMaker AI 筆記本進行呼叫的許可 AWS Glue。

**注意**  
若要查看 AWS Glue 支援哪些 Python 和 Spark 版本，請參閱 [AWS Glue 版本備註](/glue/latest/dg/release-notes.html)。

完成特徵工程後，您需要利用 MLeap 將 Spark ML 任務封裝並串列化到 MLeap 容器，以新增至推論管道。您不需要使用外部管理的 Spark 叢集。透過此方法，您可以順暢地從幾列的樣本擴大到數百 TB 的資料。同樣的轉換器適用於訓練和推論，因此，您不再需要重複進行預先處理和特徵工程邏輯，或開發一性解決方案以保留模型。透過推論管道，您不需要維護外部基礎設施，您可以直接從資料輸入進行預測。

當您在 上執行 Spark ML 任務時 AWS Glue，Spark ML 管道會序列化為 [MLeap](https://github.com/combust/mleap) 格式。接著，您可以將工作與 SageMaker AI 推論管道中的 [SparkML 模型服務容器](https://github.com/aws/sagemaker-sparkml-serving-container)搭配使用。*MLeap* 是一種用於機器學習管道的序列化格式和執行引擎。它支援 Spark、Scikit-learn 和 TensorFlow 以訓練管道，並將管道匯出至稱為 MLeap 套件的序列化管道。您可以將這些套件還原序列化到 Spark，以進行批次模式評分，或還原序列化到 MLeap 執行期，以強化即時 API 服務。

如需示範如何使用 Spark ML 進行特徵處理的範例，請參閱[使用 Amazon EMR 中的 Apache Spark 訓練機器學習模型，並在 SageMaker AI ](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-python-sdk/sparkml_serving_emr_mleap_abalone)範例筆記本中部署。

## 使用 Scikit-Learn 進行特徵處理


您可以直接在 Amazon SageMaker AI 執行 scikit-learn 工作並封裝成容器。如需建置 scikit-learn 特徵提取模型的 Python 程式碼範例 (此模型接受 [Fisher's Iris flower data set](http://archive.ics.uci.edu/ml/datasets/Iris) 訓練並根據型態測量來預測鳶尾花品種)，請參閱 [IRIS Training and Prediction with Sagemaker Scikit-learn](https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-python-sdk/scikit_learn_iris)。

# 建立管道模型
建立管道模型

若要建立可部署到端點或用於批次轉換工作的管道模型，請使用 Amazon SageMaker AI 主控台或 `CreateModel` 操作。

**建立推論管道 (主控台)**

1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 選擇**模型**，然後從**推論** 群組中選擇 **建立模型**。

1. 在**建立模型**頁面，提供模型名稱、選擇 IAM 角色，然後如果您想使用私有 VPC，請指定 VPC 值。  
![\[為推論管道建立模型的頁面。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/create-pipeline-model.png)

1. 若要新增關於推論管道中的容器的資訊，請選擇 **Add container (新增容器)**，然後選擇 **Next (下一步)**。

1. 針對每個容器，以您想要的執行容器的順序填寫欄位，最多十五個。填寫 **Container input options (容器輸入選項)**、**Location of inference code image (推論程式碼影像的位置)**，以及 (選擇性) **Location of model artifacts (模型成品的位置)**、**Container host name (容器主機名稱)** 和 **Environmental variables (環境變數)** 欄位。  
![\[建立具有容器的管道模型。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/create-pipeline-model-containers.png)

   **MyInferencePipelineModel** 頁面摘要說明可為模型提供輸入的容器的設定。如果您在對應的容器定義中提供環境變數，SageMaker AI 會在 **Environment variables (環境變數)** 欄位中顯示這些環境變數。  
![\[管道模型的容器設定摘要。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-MyInferencePipelinesModel-recap.png)

# 使用推論管道執行即時預測
即時推論

您可以使用推論管道中已訓練的模型，直接進行即時預測，而不需要執行外部預先處理。您設定管道時，您可以選擇使用 Amazon SageMaker AI 中已有的內建特徵轉換器。或者，您可以只使用幾行 scikit-learn 或 Spark 程式碼，以實作您自己的轉換邏輯。

[MLeap](https://combust.github.io/mleap-docs/) (機器學習管道的序列化格式和執行引擎) 支援 Spark、scikit-learn 和 TensorFlow，以訓練管道並匯出至稱為 MLeap 套件的序列化管道。您可以將這些套件還原序列化到 Spark，以進行批次模式評分，或還原序列化到 MLeap 執行期，以強化即時 API 服務。

管道中的容器會監聽 `SAGEMAKER_BIND_TO_PORT` 環境變數指定的連接埠 (而不是 8080)。在推論管道中執行時，SageMaker AI 會自動提供此環境變數給容器。如果此環境變數不存在，容器預設使用連接埠 8080。若要表示您的容器符合此需求，請使用下列命令，將標籤新增到您的 Dockerfile：

```
LABEL com.amazonaws.sagemaker.capabilities.accept-bind-to-port=true
```

如果您的容器需要監聽第二個連接埠，請選擇 `SAGEMAKER_SAFE_PORT_RANGE` 環境變數指定的範圍內的連接埠。以 **"XXXX-YYYY"** 格式的包含範圍指定值，其中 `XXXX` 和 `YYYY` 是多位數整數。您在多容器管道中執行容器時，SageMaker AI 會自動提供此值。

**注意**  
若要在包含 [SageMaker AI 內建演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-algo-docker-registry-paths.html)的管道中使用自訂 Docker 映像檔時，您需要 [Amazon Elastic Container Registry (Amazon ECR) 政策](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)。您的 Amazon ECR 儲存庫必須授與 SageMaker AI 提取映像的許可。如需詳細資訊，請參閱[推論管道 Amazon ECR 許可的疑難排解](inference-pipeline-troubleshoot.md#inference-pipeline-troubleshoot-permissions)。

## 建立和部署推論管道端點
即時推論管道端點

以下程式碼使用 SageMaker AI SDK，依序使用 SparkML 和 XGBoost 模型建立及部署即時推論管道模型。

```
from sagemaker.model import Model
from sagemaker.pipeline_model import PipelineModel
from sagemaker.sparkml.model import SparkMLModel

sparkml_data = 's3://{}/{}/{}'.format(s3_model_bucket, s3_model_key_prefix, 'model.tar.gz')
sparkml_model = SparkMLModel(model_data=sparkml_data)
xgb_model = Model(model_data=xgb_model.model_data, image=training_image)

model_name = 'serial-inference-' + timestamp_prefix
endpoint_name = 'serial-inference-ep-' + timestamp_prefix
sm_model = PipelineModel(name=model_name, role=role, models=[sparkml_model, xgb_model])
sm_model.deploy(initial_instance_count=1, instance_type='ml.c4.xlarge', endpoint_name=endpoint_name)
```

## 從推論管道端點要求即時推論
呼叫推論端點

下列範例說明如何呼叫推論端點，並以 JSON 格式傳送請求承載，以進行即時預測：

```
import sagemaker
from sagemaker.predictor import json_serializer, json_deserializer, Predictor

payload = {
        "input": [
            {
                "name": "Pclass",
                "type": "float",
                "val": "1.0"
            },
            {
                "name": "Embarked",
                "type": "string",
                "val": "Q"
            },
            {
                "name": "Age",
                "type": "double",
                "val": "48.0"
            },
            {
                "name": "Fare",
                "type": "double",
                "val": "100.67"
            },
            {
                "name": "SibSp",
                "type": "double",
                "val": "1.0"
            },
            {
                "name": "Sex",
                "type": "string",
                "val": "male"
            }
        ],
        "output": {
            "name": "features",
            "type": "double",
            "struct": "vector"
        }
    }

predictor = Predictor(endpoint=endpoint_name, sagemaker_session=sagemaker.Session(), serializer=json_serializer,
                                content_type='text/csv', accept='application/json')

print(predictor.predict(payload))
```

您從 `predictor.predict(payload)` 得到的回應是模型的推論結果。

## 即時推論管道範例


您可以[使用 SKLearn 預測器來執行此範例筆記本](https://github.com/awslabs/amazon-sagemaker-examples/blob/master/sagemaker-python-sdk/scikit_learn_randomforest/Sklearn_on_SageMaker_end2end.ipynb)，其中會顯示如何部署端點、執行推論請求，然後還原序列化回應。在 [Amazon SageMaker 範例 GitHub 儲存庫中](https://github.com/awslabs/amazon-sagemaker-examples)，找到此筆記本和更多範例。

# 使用推論管道執行批次轉換
批次轉換

若要取得整個資料集的推論，您可以在已訓練的模型上執行批次轉換。若要對整個資料集執行推論，您可以將為了即時處理而建立並部署到端點的相同推論管道模型，用於批次轉換任務。若要在管道中執行批次轉換工作，您可以從 Amazon S3 下載輸入資料，然後透過一或多個 HTTP 請求將資料傳送到推論管道模型。如需示範如何準備批次轉換資料的範例，請參閱[使用線性學習程式範例筆記本的 Amazon SageMaker 多模型端點](https://github.com/awslabs/amazon-sagemaker-examples/tree/master/advanced_functionality/multi_model_linear_learner_home_value)的 “第 2 節 - 使用 Scikit Learn 預先處理原始存放資料”。如需 Amazon SageMaker AI 批次轉換的相關資訊，請參閱[使用 Amazon SageMaker AI 進行批次轉換以進行推論](batch-transform.md)。

**注意**  
若要在包含 [Amazon SageMaker AI 內建演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-algo-docker-registry-paths.html)的管道中使用自訂 Docker 映像檔，您需要 [Amazon Elastic Container Registry (ECR) 政策](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)。您的 Amazon ECR 儲存庫必須授與 SageMaker AI 提取映像的許可。如需詳細資訊，請參閱[推論管道 Amazon ECR 許可的疑難排解](inference-pipeline-troubleshoot.md#inference-pipeline-troubleshoot-permissions)。

以下範例示範如何使用 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 執行轉換工作。在此範例中，`model_name` 是結合 SparkML 與 XGBoost 模型 (在先前範例中建立) 的推論管道。`input_data_path` 指定的 Amazon S3 位置包含要下載和傳送至 Spark ML 模型的輸入資料 (CSV 格式)。轉換工作完成之後，`output_data_path` 指定的 Amazon S3 位置會包含 XGBoost 模型傳回的輸出資料 (CSV 格式)。

```
import sagemaker
input_data_path = 's3://{}/{}/{}'.format(default_bucket, 'key', 'file_name')
output_data_path = 's3://{}/{}'.format(default_bucket, 'key')
transform_job = sagemaker.transformer.Transformer(
    model_name = model_name,
    instance_count = 1,
    instance_type = 'ml.m4.xlarge',
    strategy = 'SingleRecord',
    assemble_with = 'Line',
    output_path = output_data_path,
    base_transform_job_name='inference-pipelines-batch',
    sagemaker_session=sagemaker.Session(),
    accept = CONTENT_TYPE_CSV)
transform_job.transform(data = input_data_path, 
                        content_type = CONTENT_TYPE_CSV, 
                        split_type = 'Line')
```

# 推論管道日誌和指標
日誌和指標

為了維護 Amazon SageMaker AI 資源的可靠性、可用性和效能，監控很重要。若要監控推論管道效能並排除故障，請使用 Amazon CloudWatch 日誌和錯誤訊息。如需 SageMaker AI 提供之監控工具的相關資訊，請參閱[監控 Amazon SageMaker AI 中的 AWS 資源](monitoring-overview.md)。

## 使用指標來監控多容器模型
指標

若要監控推論管道中的多容器模型，請使用 Amazon CloudWatch。CloudWatch 可收集原始資料，將這些資料轉換為可讀取且幾近即時的指標。SageMaker AI 訓練任務和端點會在 `AWS/SageMaker` 命名空間中寫入 CloudWatch 指標和日誌。

下表列出以下各項的指標和維度：
+ 端點調用
+ 訓練任務、批次轉換任務和端點執行個體

*維度*是可唯一識別指標的名稱/值組。您可以對指標指派最多 10 個維度。如需有關使用 CloudWatch 進行監控的詳細資訊，請參閱[Amazon CloudWatch 中的 Amazon SageMaker AI 指標](monitoring-cloudwatch.md)。

**端點調用指標**

`AWS/SageMaker` 命名空間包含從呼叫到 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) 的下列要求指標。

指標每隔 1 分鐘回報一次。


| 指標 | Description | 
| --- | --- | 
| Invocation4XXErrors |  模型傳回 `4xx` HTTP 回應代碼以回應的 `InvokeEndpoint` 請求數量。對於每個 `4xx` 回應，SageMaker AI 會傳送 `1`。 單位：無 有效的統計資訊：`Average`、`Sum`  | 
| Invocation5XXErrors |  模型傳回 `5xx` HTTP 回應代碼以回應的 `InvokeEndpoint` 請求數量。對於每個 `5xx` 回應，SageMaker AI 會傳送 `1`。 單位：無 有效的統計資訊：`Average`、`Sum`  | 
| Invocations |  傳送到模型端點的 `number of InvokeEndpoint` 請求。 若要取得傳送至模型端點的請求總數，請使用 `Sum` 統計。 單位：無 有效的統計資訊：`Sum`、`Sample Count`  | 
| InvocationsPerInstance |  傳送到模型的端點調用數量，由 `InstanceCount` 在每個 `ProductionVariant` 中進行標準化。SageMaker AI 將 1/`numberOfInstances` 做為各個請求的值傳送，而 `numberOfInstances` 為請求時間端點後的 ProductionVariant 使用中執行個體數量。 單位：無 有效的統計資訊：`Sum`  | 
| ModelLatency | 一或多個模型做出回應所花的時間。這包括傳送請求、從模型容器擷取回應及在容器中完成推論所花的時間。ModelLatency 是推論管道中所有容器花費的總時間。單位：微秒有效的統計資訊：`Average`、`Sum`、`Min`、`Max`、樣本計數 | 
| OverheadLatency |  在回應用戶端請求而花費的時間中，SageMaker AI 為了處理額外負荷而另外花費的時間。`OverheadLatency` 的計算是從 SageMaker AI 收到請求，直到回應傳回給用戶端的時間再減去 `ModelLatency`。額外負荷延遲可能隨著請求和回應承載大小、請求頻率，以及請求的身分驗證或授權等因素而不同。 單位：微秒 有效的統計資訊：`Average`、`Sum`、`Min`、`Max`、`Sample Count`  | 
| ContainerLatency | 從 SageMaker AI 的觀點來看，推論管道容器做出回應所花的時間。ContainerLatency 包含傳送請求、從模型的容器擷取回應，以及在容器中完成推論所花的時間。單位：微秒有效的統計資訊：`Average`、`Sum`、`Min`、`Max`、`Sample Count` | 

**端點調用指標的維度**


| 維度 | Description | 
| --- | --- | 
| EndpointName, VariantName, ContainerName |  針對指定端點上的 `ProductionVariant`，以及指定的變體，篩選端點調用指標。  | 

對於推論管道端點，CloudWatch 會將您帳戶中每個容器延遲指標列為 **SageMaker AI** 命名空間中的**端點容器指標**和**端點變體指標**，如下所示。只有推論管道才會顯示 `ContainerLatency` 指標。

![\[適用於推論管道的 CloudWatch 儀表板。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-endpoint-metrics.png)


對於每個端點和每個容器，延遲指標會顯示容器、端點，變體及指標的名稱。

![\[端點的延遲指標。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-endpoint-metrics-details.png)


**訓練任務、批次轉換任務及端點執行個體指標**

命名空間 `/aws/sagemaker/TrainingJobs`、`/aws/sagemaker/TransformJobs` 和 `/aws/sagemaker/Endpoints` 包含以下關於訓練任務和端點執行個體的指標。

指標每隔 1 分鐘回報一次。


| 指標 | Description | 
| --- | --- | 
| CPUUtilization |  執行個體上執行的容器所使用的 CPU 單位百分比。值的範圍從 0% 到 100%，並乘以 CPU 的數量。例如，如果有四個 CPU，`CPUUtilization` 的範圍可能從 0% 到 400%。 若為訓練任務，`CPUUtilization` 是執行個體上執行的演算法容器的 CPU 使用率。 若為批次轉換任務，`CPUUtilization` 是執行個體上執行的轉換容器的 CPU 使用率。 若為多容器模型，`CPUUtilization` 是執行個體上執行的所有容器的 CPU 使用率總和。 若為端點變體，`CPUUtilization` 是執行個體上執行的所有容器的 CPU 使用率總和。 單位：百分比  | 
| MemoryUtilization | 執行個體上執行的容器所使用的記憶體百分比。這個值的範圍從 0% 到 100%。若為訓練任務，`MemoryUtilization` 是執行個體上執行的演算法容器所使用的記憶體。若為批次轉換任務，`MemoryUtilization` 是執行個體上執行的轉換容器所使用的記憶體。若為多容器模型，MemoryUtilization 是執行個體上執行的所有容器所使用的記憶體總和。若為端點變體，`MemoryUtilization` 是執行個體上執行的所有容器所使用的記憶體總和。單位：百分比 | 
| GPUUtilization |  執行個體上執行的容器所使用的 GPU 單位百分比。`GPUUtilization` 的範圍從 0% 到 100%，並乘以 GPU 的數量。例如，如果有四個 GPU，`GPUUtilization` 的範圍可能從 0% 到 400%。 若為訓練任務，`GPUUtilization` 是執行個體上執行的演算法容器所使用的 GPU。 若為批次轉換任務，`GPUUtilization` 是執行個體上執行的轉換容器所使用的 GPU。 若為多容器模型，`GPUUtilization` 是執行個體上執行的所有容器所使用的 GPU 總和。 若為端點變體，`GPUUtilization` 是執行個體上執行的所有容器所使用的 GPU 總和。 單位：百分比  | 
| GPUMemoryUtilization |  執行個體上執行的容器所使用的 GPU 記憶體百分比。GPUMemoryUtilization 範圍從 0% 到 100%，並乘以 GPU 的數量。例如，如果有四個 GPU，`GPUMemoryUtilization` 的範圍可能從 0% 到 400%。 若為訓練任務，`GPUMemoryUtilization` 是執行個體上執行的演算法容器所使用的 GPU 記憶體。 若為批次轉換任務，`GPUMemoryUtilization` 是執行個體上執行的轉換容器所使用的 GPU 記憶體。 若為多容器模型，`GPUMemoryUtilization` 是執行個體上執行的所有容器所使用的 GPU 總和。 若為端點變體，`GPUMemoryUtilization` 是執行個體上執行的所有容器所使用的 GPU 記憶體總和。 單位：百分比  | 
| DiskUtilization |  執行個體上執行的容器所使用的磁碟空間百分比。DiskUtilization 的範圍從 0% 到 100%。批次轉換任務不支援這個指標。 若為訓練任務，`DiskUtilization` 是執行個體上執行的演算法容器所使用的磁碟空間。 若為端點變體，`DiskUtilization` 是執行個體上執行的所有已提供容器所使用的磁碟空間總和。 單位：百分比  | 

**Dimensions for Training Job, Batch Transform Job, and Endpoint Instance Metrics (訓練任務、批次轉換任務與端點執行個體指標的維度)**


| 維度 | Description | 
| --- | --- | 
| Host |  若為訓練任務，`Host` 的格式為 `[training-job-name]/algo-[instance-number-in-cluster]`。使用此維度來篩選所指定訓練任務和執行個體的執行個體指標。此維度格式只會在 `/aws/sagemaker/TrainingJobs` 命名空間中顯示。 若為批次轉換任務，`Host` 的格式為 `[transform-job-name]/[instance-id]`。使用此維度來篩選指定批次轉換任務和執行個體的執行個體指標。此維度格式只會在 `/aws/sagemaker/TransformJobs` 命名空間中顯示。 若為端點，`Host` 的格式為 `[endpoint-name]/[ production-variant-name ]/[instance-id]`。使用此維度來篩選指定端點、變體和執行個體的執行個體指標。此維度格式只會在 `/aws/sagemaker/Endpoints` 命名空間中顯示。  | 

為了協助您對訓練任務、端點與筆記本執行個體生命週期組態除錯，只要是演算法容器、模型容器或筆記本執行個體生命週期組態傳送給 `stdout` 或 `stderr` 的任何內容，SageMaker AI 也會傳送給 Amazon CloudWatch Logs。您可以使用此資訊來除錯和分析進度。

## 使用日誌來監控推論管道
日誌

下表列出 SageMaker AI 傳送到 Amazon CloudWatch 的日誌群組和日誌串流 

*日誌串流*是一系列共用相同來源的日誌事件。每個單獨日誌串流是由 CloudWatch 中的單獨日誌來源所組成。*日誌群組*是共用相同保留、監控和存取控制設定的日誌串流群組。

**日誌**

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/inference-pipeline-logs-metrics.html)

**注意**  
您建立具有生命週期組態的筆記本執行個體時，SageMaker AI 會建立 `/aws/sagemaker/NotebookInstances` 日誌群組。如需詳細資訊，請參閱[使用 LCC 指令碼自訂 SageMaker 筆記本執行個體](notebook-lifecycle-config.md)。

如需關於 SageMaker AI 記錄格式的詳細資訊，請參閱[Amazon SageMaker AI 的 CloudWatch Logs](logging-cloudwatch.md)。

# 推論管道的故障診斷
疑難排解

若要進行推論管道問題的故障診斷，請使用 CloudWatch 日誌和錯誤訊息。如果您在包含 Amazon SageMaker AI 內建演算法的管道中使用自訂 Docker 映像檔，可能也會遇到許可問題。若要授予必要許可，請建立 Amazon Elastic Container Registry (Amazon ECR) 政策。

**Topics**
+ [

## 推論管道 Amazon ECR 許可的疑難排解
](#inference-pipeline-troubleshoot-permissions)
+ [

## 使用 CloudWatch 日誌進行 SageMaker AI 推論管道的疑難排解
](#inference-pipeline-troubleshoot-logs)
+ [

## 使用錯誤訊息進行推論管道的故障診斷
](#inference-pipeline-troubleshoot-errors)

## 推論管道 Amazon ECR 許可的疑難排解
ECR 許可

您在包含 [SageMaker AI 內建演算法](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-algo-docker-registry-paths.html)的管道中使用自訂 Docker 映像檔時，您需要 [Amazon ECR 政策](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)。此政策可讓您的 Amazon ECR 儲存庫授與 SageMaker AI 提取映像的許可。此政策必須新增下列許可：

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "allowSageMakerToPull",
            "Effect": "Allow",
            "Principal": {
                "Service": "sagemaker.amazonaws.com"
            },
            "Action": [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:BatchCheckLayerAvailability"
            ],
            "Resource": "*"
        }
    ]
}
```

------

## 使用 CloudWatch 日誌進行 SageMaker AI 推論管道的疑難排解
日誌

對於將推論管道部署到 Amazon CloudWatch 的端點，SageMaker AI 會在每個容器的以下路徑發佈端點的容器日誌。

```
/aws/sagemaker/Endpoints/{EndpointName}/{Variant}/{InstanceId}/{ContainerHostname}
```

例如，此端點的日誌會發佈到以下日誌群組和串流：

```
EndpointName: MyInferencePipelinesEndpoint
Variant: MyInferencePipelinesVariant
InstanceId: i-0179208609ff7e488
ContainerHostname: MyContainerName1 and MyContainerName2
```

```
logGroup: /aws/sagemaker/Endpoints/MyInferencePipelinesEndpoint
logStream: MyInferencePipelinesVariant/i-0179208609ff7e488/MyContainerName1
logStream: MyInferencePipelinesVariant/i-0179208609ff7e488/MyContainerName2
```

*日誌串流*是一系列共用相同來源的日誌事件。每個單獨日誌串流是由 CloudWatch 中的單獨日誌來源所組成。*日誌群組*是共用相同保留、監控和存取控制設定的日誌串流群組。

**查看日誌群組和串流**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽頁面中，選擇 **Logs (日誌)**。

1. 在 **Log Groups (日誌群組)** 中，依 **MyInferencePipelinesEndpoint** 篩選：  
![\[針對推論管道端點篩選的 CloudWatch 日誌群組。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-log-group-filter.png)

1. 若要查看日誌串流，請在 CloudWatch **日誌群組** 頁面選擇 **MyInferencePipelinesEndpoint**，然後選擇**搜尋日誌群組**。  
![\[推論管道的 CloudWatch 日誌串流。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/pipeline-log-streams-2.png)

如需 SageMaker AI 發佈的日誌清單，請參閱[推論管道日誌和指標](inference-pipeline-logs-metrics.md)。

## 使用錯誤訊息進行推論管道的故障診斷
錯誤訊息

推論管道錯誤訊息指出哪些容器故障。

如果 SageMaker AI 調用端點時發生錯誤，服務會傳回 `ModelError` (錯誤碼 424)，指出哪個容器故障。如果請求承載 (來自前一個容器的回應) 超過 5 MB 的限制，SageMaker AI 會提供詳細的錯誤訊息，例如：

收到來自 MyContainerName1 的回應，狀態碼為 200。不過，從 MyContainerName1 到 MyContainerName2 的請求承載為 6000000 位元組，已超過最大限制 5 MB。

``

SageMaker AI 建立端點時，如果容器的 ping 運作狀態檢查失敗，則會傳回 `ClientError`，並指出上一次運作狀態檢查時未通過 ping 檢查的所有容器。

# 刪除端點和資源


刪除端點，停止產生費用。

## 刪除端點


使用 適用於 Python (Boto3) 的 AWS SDK、 搭配 以程式設計方式刪除端點 AWS CLI，或使用 SageMaker AI 主控台以互動方式刪除端點。

SageMaker AI 會釋放建立端點時部署的所有資源。刪除端點並不會刪除端點組態或 SageMaker AI 模型。如需有關如何刪除端點組態和 SageMaker AI 模型的資訊，請參閱[刪除端點組態](#realtime-endpoints-delete-endpoint-config)和[刪除模型](#realtime-endpoints-delete-model)。

------
#### [ 適用於 Python (Boto3) 的 AWS SDK ]

使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteEndpoint.html) API 刪除端點。為 `EndpointName` 欄位指定端點名稱。

```
import boto3

# Specify your AWS Region
aws_region='<aws_region>'

# Specify the name of your endpoint
endpoint_name='<endpoint_name>'

# Create a low-level SageMaker service client.
sagemaker_client = boto3.client('sagemaker', region_name=aws_region)

# Delete endpoint
sagemaker_client.delete_endpoint(EndpointName=endpoint_name)
```

------
#### [ AWS CLI ]

若要刪除端點，請使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-endpoint.html) 命令。為 `endpoint-name` 旗標指定端點名稱。

```
aws sagemaker delete-endpoint --endpoint-name <endpoint-name>
```

------
#### [ SageMaker AI Console ]

使用 SageMaker AI 主控台以互動方式刪除端點。

1. 在位於 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 瀏覽功能表的 SageMaker AI 主控台，選擇**推論**。

1. 從下拉式功能表選擇**端點**。在您的 AWS 帳戶中建立的端點清單會依名稱、Amazon Resource Name (ARN)、建立時間、狀態和上次更新端點時的時間戳記顯示。

1. 選取您要刪除的端點。

1. 選取右上角的**動作**下拉式按鈕。

1. 選擇**刪除**。

------

## 刪除端點組態


使用 適用於 Python (Boto3) 的 AWS SDK、 搭配 以程式設計方式刪除端點組態 AWS CLI，或使用 SageMaker AI 主控台以互動方式刪除端點組態。刪除端點組態並不會刪除使用這個組態建立的端點。如需如何刪除端點的資訊，請參閱[刪除端點](#realtime-endpoints-delete-endpoint)。

請勿刪除作用中端點正在使用的端點組態，也不要在端點更新或建立時刪除端點組態。如果刪除作用中或正在建立或更新之端點的端點組態，可能會失去對端點使用中執行個體類型的可見度。

------
#### [ 適用於 Python (Boto3) 的 AWS SDK ]

使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteEndpointConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteEndpointConfig.html) API 刪除端點。為 `EndpointConfigName` 欄位指定端點組態名稱。

```
import boto3

# Specify your AWS Region
aws_region='<aws_region>'

# Specify the name of your endpoint configuration
endpoint_config_name='<endpoint_name>'

# Create a low-level SageMaker service client.
sagemaker_client = boto3.client('sagemaker', region_name=aws_region)

# Delete endpoint configuration
sagemaker_client.delete_endpoint_config(EndpointConfigName=endpoint_config_name)
```

您可以選擇使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html) API 傳回已部署模型 (生產變體) 名稱的相關資訊，例如模型名稱，以及與該部署模型相關的端點組態名稱。為 `EndpointConfigName` 欄位提供端點名稱。

```
# Specify the name of your endpoint
endpoint_name='<endpoint_name>'

# Create a low-level SageMaker service client.
sagemaker_client = boto3.client('sagemaker', region_name=aws_region)

# Store DescribeEndpointConfig response into a variable that we can index in the next step.
response = sagemaker_client.describe_endpoint_config(EndpointConfigName=endpoint_name)

# Delete endpoint
endpoint_config_name = response['ProductionVariants'][0]['EndpointConfigName']
                        
# Delete endpoint configuration
sagemaker_client.delete_endpoint_config(EndpointConfigName=endpoint_config_name)
```

如需 `DescribeEndpointConfig` 傳回之其他回應元素的詳細資訊，請參閱 [SageMaker API 參考指南](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Operations_Amazon_SageMaker_Service.html)的 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html)。

------
#### [ AWS CLI ]

若要刪除端點組態，請使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-endpoint-config.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-endpoint-config.html) 命令。為 `endpoint-config-name` 旗幟指定端點組態名稱。

```
aws sagemaker delete-endpoint-config \
                        --endpoint-config-name <endpoint-config-name>
```

您可以選擇使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-endpoint-config.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-endpoint-config.html) API 命令傳回已部署模型 (生產變體) 名稱的相關資訊，例如模型名稱，以及與該部署模型相關的端點組態名稱。為 `endpoint-config-name` 旗標提供端點名稱。

```
aws sagemaker describe-endpoint-config --endpoint-config-name <endpoint-config-name>
```

隨即會傳回 JSON 回應。您可以複製貼上、使用 JSON 剖析器，或使用專為 JSON 剖析而建置的工具，取得與該端點相關的端點組態名稱。

------
#### [ SageMaker AI Console ]

使用 SageMaker AI 主控台以互動方式刪除端點組態。

1. 在位於 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 瀏覽功能表的 SageMaker AI 主控台，選擇**推論**。

1. 從下拉式功能表選擇**端點組態**。 AWS 帳戶建立的端點組態清單會依名稱、Amazon Resource Name (ARN) 和建立時間顯示。

1. 選取您要刪除的端點組態。

1. 選取右上角的**動作**下拉式按鈕。

1. 選擇**刪除**。

------

## 刪除模型


使用 適用於 Python (Boto3) 的 AWS SDK、 搭配 以程式設計方式刪除 SageMaker AI 模型 AWS CLI，或使用 SageMaker AI 主控台以互動方式刪除 SageMaker AI 模型。刪除 SageMaker AI 模型只會刪除在 SageMaker AI 建立的模型項目。刪除模型不會刪除模型成品、推論程式碼，或您在建立模型時指定的 IAM 角色。

------
#### [ 適用於 Python (Boto3) 的 AWS SDK ]

使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteModel.html) API 刪除 SageMaker AI 模型。為 `ModelName` 欄位指定模型名稱。

```
import boto3

# Specify your AWS Region
aws_region='<aws_region>'

# Specify the name of your endpoint configuration
model_name='<model_name>'

# Create a low-level SageMaker service client.
sagemaker_client = boto3.client('sagemaker', region_name=aws_region)

# Delete model
sagemaker_client.delete_model(ModelName=model_name)
```

您可以選擇使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html) API 傳回已部署模型 (生產變體) 名稱的相關資訊，例如模型名稱，以及與該部署模型相關的端點組態名稱。為 `EndpointConfigName` 欄位提供端點名稱。

```
# Specify the name of your endpoint
endpoint_name='<endpoint_name>'

# Create a low-level SageMaker service client.
sagemaker_client = boto3.client('sagemaker', region_name=aws_region)

# Store DescribeEndpointConfig response into a variable that we can index in the next step.
response = sagemaker_client.describe_endpoint_config(EndpointConfigName=endpoint_name)

# Delete endpoint
model_name = response['ProductionVariants'][0]['ModelName']
sagemaker_client.delete_model(ModelName=model_name)
```

如需 `DescribeEndpointConfig` 傳回之其他回應元素的詳細資訊，請參閱 [SageMaker API 參考指南](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Operations_Amazon_SageMaker_Service.html)的 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html)。

------
#### [ AWS CLI ]

使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-model.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/delete-model.html) 命令刪除 SageMaker AI 模型。為 `model-name` 旗標指定模型名稱。

```
aws sagemaker delete-model \
                        --model-name <model-name>
```

您可以選擇使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-endpoint-config.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/describe-endpoint-config.html) API 命令傳回已部署模型 (生產變體) 名稱的相關資訊，例如模型名稱，以及與該部署模型相關的端點組態名稱。為 `endpoint-config-name` 旗標提供端點名稱。

```
aws sagemaker describe-endpoint-config --endpoint-config-name <endpoint-config-name>
```

隨即會傳回 JSON 回應。您可以複製貼上、使用 JSON 剖析器，或使用專為 JSON 剖析而建置的工具，取得與該端點相關的模型名稱。

------
#### [ SageMaker AI Console ]

使用 SageMaker AI 主控台以互動方式刪除 SageMaker AI 模型。

1. 在位於 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 瀏覽功能表的 SageMaker AI 主控台，選擇**推論**。

1. 從下拉式功能表選擇**模型**。在您 AWS 帳戶中建立的模型清單會依名稱、Amazon Resource Name (ARN) 和建立時間顯示。

1. 選取您要刪除的模型。

1. 選取右上角的**動作**下拉式按鈕。

1. 選擇**刪除**。

------

# Amazon SageMaker AI 模型的自動擴展
自動擴展規模

Amazon SageMaker AI 支援託管模型的自動擴展 (自動擴展)。*自動擴展*會動態調整針對模型佈建的執行個體數量，因應工作負載的變更。當工作負載增加時，自動擴展會讓更多的執行個體上線。當工作負載減少時，自動擴展會移除不必要的執行個體，讓您不需為了用不到的已佈建執行個體再支付費用。

**Topics**
+ [

# 自動擴展政策概觀
](endpoint-auto-scaling-policy.md)
+ [

# 自動擴展先決條件
](endpoint-auto-scaling-prerequisites.md)
+ [

# 使用主控台設定模型自動擴展
](endpoint-auto-scaling-add-console.md)
+ [

# 註冊模型
](endpoint-auto-scaling-add-policy.md)
+ [

# 定義擴展政策
](endpoint-auto-scaling-add-code-define.md)
+ [

# 套用擴展政策
](endpoint-auto-scaling-add-code-apply.md)
+ [

# 編輯擴展政策的說明
](endpoint-auto-scaling-edit.md)
+ [

# 暫時關閉擴展政策
](endpoint-auto-scaling-suspend-scaling-activities.md)
+ [

# 刪除擴展政策
](endpoint-auto-scaling-delete.md)
+ [

# 描述擴展活動以檢查擴展活動的狀態
](endpoint-scaling-query-history.md)
+ [

# 將端點擴展到零個執行個體
](endpoint-auto-scaling-zero-instances.md)
+ [

# 負載測試您的自動擴展組態
](endpoint-scaling-loadtest.md)
+ [

# 使用 CloudFormation 建立擴展政策
](endpoint-scaling-cloudformation.md)
+ [

# 更新使用自動擴展的端點
](endpoint-scaling-update.md)
+ [

# 刪除針對自動擴展功能設定的端點
](endpoint-delete-with-scaling.md)

# 自動擴展政策概觀


若要使用自動擴展，請定義新增和移除生產變體執行個體數量的擴展政策，以回應實際的工作負載。

若要在工作負載變化時自動擴展，您有兩個選項：目標追蹤和步進擴展政策。

在多數情況下，建議您使用目標追蹤擴展政策。透過目標追蹤，您可以選擇 Amazon CloudWatch 指標和目標值。自動擴展會建立和管理擴展政策的 CloudWatch 警示，並根據指標和目標值來計算擴展調整內容。該政策會根據需要來新增或移除執行個體數量，以讓指標保持在等於或接近指定目標值的值。例如，擴展政策如果使用預先定義的 `InvocationsPerInstance` 指標和 70 的目標值，可將 `InvocationsPerInstance` 保持在等於或接近 70。如需詳細資訊，請參閱《Application Auto Scaling 使用者指南》中的[目標追蹤擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html)。

您可以在需要進階組態時使用步驟擴展，例如指定在何種情況下要部署的執行個體數目。例如，如果您想讓端點從零個作用中執行個體橫向擴充，您就必須使用步進擴展。如需進一步瞭解步進擴展政策，請參閱*《Application Auto Scaling 使用者指南》*中的[步進擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-step-scaling-policies.html)。

如要建立目標追蹤擴展政策，您必須指定以下項目：
+ **指標** — 要追蹤的 CloudWatch 指標，例如每個執行個體的平均調用次數。
+ **目標值** — 指標的目標值，例如每分鐘每個執行個體 70 次調用。

您可以使用預先定義的指標或自訂指標建立目標追蹤擴展政策。預先定義的指標會以列舉類型定義，如此您可以在程式碼中透過名稱來指定指標，或是在 SageMaker AI 主控台中使用指標。或者，您可以使用 AWS CLI 或 Application Auto Scaling API，根據預先定義或自訂的指標套用目標追蹤擴展政策。

請注意，擴展活動之間會有冷卻時間，以防止容量快速波動。您可自行選擇是否設定擴展政策的冷卻時間。

如需進一步瞭解自動擴展的重要概念，請參閱以下章節。

## 排程擴展


您也可以建立排程動作，在特定時間執行擴展活動。您可以建立僅擴展一次或依週期性排程擴展的排程動作。執行排程動作之後，擴展政策可以繼續決定是否隨著工作負載變化動態擴展容量。排程擴展只能從 AWS CLI 或 Application Auto Scaling API 管理。如需詳細資訊，請參閱《Application Auto Scaling 使用者指南》中的[排程擴展](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-step-scaling-policies.html)。

## 擴展限制上限和下限


設定自動擴展時，您必須先指定擴展限制，才能建立擴展政策。您可以分別為最小和最大值設定限制。

下限必須至少為 1，且必須小於或等於指定上限值。

上限必須大於或等於指定下限值。SageMaker AI 自動擴展功能不會強制為此值設定限制。

若要決定一般流量所需的擴展上限和下限，請使用預期的傳輸流量來傳送到您的模型，以測試您的自動擴展組態設定。

如果變體的流量變成 0，SageMaker AI 會自動將規模調整至指定的執行個體數量下限。在此情況下，SageMaker AI 會發出值 0 的指標。

有三種方式可以指定容量下限和上限：

1. 透過主控台更新**執行個體數量下限**和**執行個體數量上限**設定。

1. 執行 [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) 命令時，請使用 AWS CLI 並包含 `--min-capacity`和 `--max-capacity`選項。

1. 呼叫 [RegisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html) API 並指定 `MinCapacity` 和 `MaxCapacity` 參數。

**提示**  
您可以提高最小值來手動橫向擴充，或降低最大值來手動縮減。

## 冷卻時間


模型縮減 (減少容量) 或橫向擴充 (增加容量) 時，會使用*冷卻時間*來防止過度擴展。這會減慢後續擴展活動，直到時間到期為止。更準確來說，這會封鎖縮減請求刪除執行個體的動作，並限制建立橫向擴充請求用的執行個體。如需詳細資訊，請參閱《Application Auto Scaling 使用者指南》**中的[定義冷卻時間](https://docs.aws.amazon.com/autoscaling/application/userguide/target-tracking-scaling-policy-overview.html#target-tracking-cooldown)。

您可以在擴展政策中設定冷卻時間。

如果您不指定縮減或橫向擴充的冷卻時間，則擴展政策會使用預設值 (各為 300 秒)。

在您測試擴展組態設定時，如果執行個體新增或移除的速度過快，請考慮增加此值。如果傳輸到您模型的資料流具有許多突增的峰值，或是您針對變體定義了多個擴展政策，就可能會出現前述的現象。

如果執行個體新增的速度不夠快，沒辦法因應增加的傳輸流量，請考慮減少此值。

## 相關資源


如需進一步瞭解自動擴展組態設定，請參閱以下資源：
+ *AWS CLI 命令參考*中的[應用程式自動擴展](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling)一節
+ [Application Auto Scaling API 參考](https://docs.aws.amazon.com/autoscaling/application/APIReference/)
+ [Application Auto Scaling 使用者指南](https://docs.aws.amazon.com/autoscaling/application/userguide/)

**注意**  
SageMaker AI 最近推出了以即時推論端點為基礎的新推論功能。您可以使用定義端點的執行個體類型和初始執行個體數量的端點組態來建立 SageMaker AI 端點。接著，建立一個推論元件，也就是可以用來將模型部署到端點的 SageMaker AI 託管物件。如需有關擴展推論元件的資訊，請參閱 AWS 部落格上的 [SageMaker AI 新增了新的推論功能，以協助降低基礎模型部署成本和延遲](https://aws.amazon.com/blogs/aws/amazon-sagemaker-adds-new-inference-capabilities-to-help-reduce-foundation-model-deployment-costs-and-latency/)，以及[使用 SageMaker AI 的最新功能平均降低 50% 的模型部署成本](https://aws.amazon.com/blogs/machine-learning/reduce-model-deployment-costs-by-50-on-average-using-sagemakers-latest-features/)。

# 自動擴展先決條件
先決條件

您必須先建立 Amazon SageMaker AI 模型部署，才能使用自動擴展。您可以針對相同的端點擁有多個模型版本。每個模型稱為[生產 (模型) 變體](model-ab-testing.md)。如需關於部署模型端點的詳細資訊，請參閱[將模型部署至 SageMaker AI 託管服務](ex1-model-deployment.md#ex1-deploy-model)。

若要啟用模型的自動擴展，您可以透過 Application Auto Scaling API 使用 SageMaker AI 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS SDK。
+ 如果這是您第一次為模型設定擴展，建議您 [使用主控台設定模型自動擴展](endpoint-auto-scaling-add-console.md)。
+ 使用 AWS CLI 或 Application Auto Scaling API 時，流程是將模型註冊為可擴展的目標、定義擴展政策，然後套用。在 SageMaker AI 主控台導覽窗格的**推論**下，選擇**端點**。尋找模型的端點名稱，然後選擇以它來尋找變體名稱。您必須同時指定端點名稱和變體名稱，才能啟用模型的自動擴展。

結合 Amazon SageMaker AI、Amazon CloudWatch 和 Application Auto Scaling API 即可達成自動擴展。如需進一步瞭解所需最低許可，請參閱*《Application Auto Scaling 使用者指南》*中的 [Application Auto Scaling 身分型政策範例](https://docs.aws.amazon.com/autoscaling/application/userguide/security_iam_id-based-policy-examples.html)。

`SagemakerFullAccessPolicy` IAM 政策具備執行自動擴展所需要的全部許可。如需 SageMaker AI IAM 許可的詳細資訊，請參閱 [如何使用 SageMaker AI 執行角色](sagemaker-roles.md)。

如果您管理自有許可政策，您必須加入下列許可：

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sagemaker:DescribeEndpoint",
        "sagemaker:DescribeEndpointConfig",
        "sagemaker:UpdateEndpointWeightsAndCapacities"
      ],
      "Resource": "*"
    },
    {    
        "Effect": "Allow",
        "Action": [
            "application-autoscaling:*"
        ],
        "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/sagemaker.application-autoscaling.amazonaws.com/AWSServiceRoleForApplicationAutoScaling_SageMakerEndpoint",
      "Condition": {
        "StringLike": { "iam:AWSServiceName": "sagemaker.application-autoscaling.amazonaws.com"	}
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:PutMetricAlarm",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:DeleteAlarms"
      ],
      "Resource": "*"
    }
  ]
}
```

------

## 服務連結角色


Auto Scaling 使用 `AWSServiceRoleForApplicationAutoScaling_SageMakerEndpoint` 服務連結角色。此服務連結角色會授予 Application Auto Scaling 許可以描述政策的警示、監控目前的容量多寡，以及擴展目標資源。系統會自動建立此角色。為了成功自動建立該角色，您必須有 `iam:CreateServiceLinkedRole` 動作的許可。如需詳細資訊，請參閱《應用程式自動擴展使用者指南》**中的[服務連結角色](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-service-linked-roles.html)。

# 使用主控台設定模型自動擴展


**設定模型的自動擴展 (主控台)**

1. 開啟位在 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 的 Amazon SageMaker AI 主控台。

1. 在導覽窗格中，選擇**推論**，然後選擇**端點**。

1. 選擇您的端點，然後針對**端點執行時期設定**選擇變體。

1. 選擇**設定自動擴展**。

1. 在**設定變體自動擴展**頁面上，針對**變體自動擴展**，執行下列動作：

   1. 針對**執行個體數量下限**，輸入您希望擴展政策維持的執行個體數量下限。必須設定至少 1 個執行個體。

   1. 針對**執行個體數量上限**，輸入您希望擴展政策維持的執行個體數量上限。

1. 請針對**內建擴展政策**，執行下列動作：

   1. 針對**目標指標**，系統會自動選取 `SageMakerVariantInvocationsPerInstance` 且無法變更。

   1. 針對**目標值**，輸入模型的每個執行個體每分鐘的平均調用數量。若要決定此值，請遵循 [負載測試](endpoint-scaling-loadtest.md) 中的準則。

   1. (選用) 針對**縮減的冷卻期間 (秒)** 和**橫向擴充的冷卻時間 (秒)**，分別輸入每個冷卻時間的秒數。

   1. (選用) 若不想在流量減少時讓自動擴展終止執行個體，請選取**停用縮減**。

1. 選擇**儲存**。

此程序會向 Application Auto Scaling 登錄模型，將變體作為可擴展的目標。當您登錄模型時，Application Auto Scaling 會進行驗證檢查，以確定符合下列條件：
+ 模型已存在
+ 權限足夠
+ 變體的執行個體如果是具有爆量效能執行個體 (例如 T2)，則您不能登錄此等變體
**注意**  
對於像是 T2 等可爆量的執行個體，SageMaker AI 不支援其自動擴展功能，因為這類執行個體已可隨工作負載的增加來增加容量。如需爆量效能執行個體的資訊，請參閱 [Amazon EC2 執行個體類型](https://aws.amazon.com/ec2/instance-types/)。

# 註冊模型


將擴展政策新增至模型之前，您必須先註冊模型以進行自動擴展，並定義模型的擴展限制。

下列程序說明如何使用 () 或 Application Auto Scaling API 註冊模型 AWS Command Line Interface （生產變體AWS CLI) 以進行自動擴展。

**Topics**
+ [

## 註冊模型 (AWS CLI)
](#endpoint-auto-scaling-add-cli)
+ [

## 註冊模型 (應用程式自動擴展 API)
](#endpoint-auto-scaling-add-api)

## 註冊模型 (AWS CLI)


若要註冊生產變體，請使用 [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) 命令搭配下列參數：
+ `--service-namespace`—將此值設定為 `sagemaker`。
+ `--resource-id`—模型的資源識別符 (特別是，生產變體)。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是生產變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `--scalable-dimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。
+ `--min-capacity`—執行個體數量下限。此值必須設定為至少大於 1，而且必須小於或等於 `max-capacity` 所指定的值。
+ `--max-capacity`—執行個體數量上限。此值必須設定為至少大於 1，而且必須大於或等於 `min-capacity` 所指定的值。

**Example**  
下列範例說明如何註冊在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體，此變體可動態擴展，以包含 1 到 8 個執行個體。  

```
aws application-autoscaling register-scalable-target \
  --service-namespace sagemaker \
  --resource-id endpoint/my-endpoint/variant/my-variant \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount \
  --min-capacity 1 \
  --max-capacity 8
```

## 註冊模型 (應用程式自動擴展 API)


若要以 Application Auto Scaling 註冊您的模型，請使用 [RegisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html) Application Auto Scaling API 動作搭配下列參數：
+ `ServiceNamespace`—將此值設定為 `sagemaker`。
+ `ResourceID`—生產變體的資源識別符。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `ScalableDimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。
+ `MinCapacity`—執行個體數量下限。此值必須設定為至少大於 1，而且必須小於或等於 `MaxCapacity` 所指定的值。
+ `MaxCapacity`—執行個體數量上限。此值必須設定為至少大於 1，而且必須大於或等於 `MinCapacity` 所指定的值。

**Example**  
下列範例說明如何註冊在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體，此變體可動態擴展，以使用 1 到 8 個執行個體。  

```
POST / HTTP/1.1
Host: application-autoscaling.us-east-2.amazonaws.com
Accept-Encoding: identity
X-Amz-Target: AnyScaleFrontendService.RegisterScalableTarget
X-Amz-Date: 20230506T182145Z
User-Agent: aws-cli/2.0.0 Python/3.7.5 Windows/10 botocore/2.0.0dev4
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
    "ServiceNamespace": "sagemaker",
    "ResourceId": "endpoint/my-endpoint/variant/my-variant",
    "ScalableDimension": "sagemaker:variant:DesiredInstanceCount",
    "MinCapacity": 1,
    "MaxCapacity": 8
}
```

# 定義擴展政策


將擴展政策新增至模型之前，請先以文字檔案中的 JSON 區塊儲存政策組態。叫用 AWS Command Line Interface (AWS CLI) 或 Application Auto Scaling API 時，您可以使用該文字檔案。您可以選擇適合的 CloudWatch 指標來最佳化擴展。不過，在生產環境中使用自訂指標之前，您必須以自訂指標測試自動擴展。

**Topics**
+ [

## 指定預先定義的指標 (CloudWatch 指標：InvocationsPerInstance)
](#endpoint-auto-scaling-add-code-predefined)
+ [

## 指定高解析度預先定義的指標 (CloudWatch 指標：ConcurrentRequestsPerModel 和 ConcurrentRequestsPerCopy)
](#endpoint-auto-scaling-add-code-high-res)
+ [

## 定義自訂指標 (CloudWatch 指標：CPUUtilization)
](#endpoint-auto-scaling-add-code-custom)
+ [

## 定義自訂指標 (CloudWatch 指標：ExplanationsPerInstance)
](#endpoint-auto-scaling-online-explainability)
+ [

## 指定冷卻時間
](#endpoint-auto-scaling-add-code-cooldown)

本節說明目標追蹤擴展政策的政策組態範例。

## 指定預先定義的指標 (CloudWatch 指標：InvocationsPerInstance)


**Example**  
以下是變體的目標追蹤政策組態範例，該組態會將每個執行個體的平均調用保持在 70。將此組態儲存至名為 `config.json` 的檔案。  

```
{
    "TargetValue": 70.0,
    "PredefinedMetricSpecification":
    {
        "PredefinedMetricType": "SageMakerVariantInvocationsPerInstance"
    }
}
```
如需詳細資訊，請參閱 *Application Auto Scaling API 參考*中的 [TargetTrackingScalingPolicyConfiguration](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_TargetTrackingScalingPolicyConfiguration.html)。

## 指定高解析度預先定義的指標 (CloudWatch 指標：ConcurrentRequestsPerModel 和 ConcurrentRequestsPerCopy)


透過下列高解析度 CloudWatch 指標，您可以為模型所接收的並行請求量設定擴展政策：

**ConcurrentRequestsPerModel**  
模型容器所接收的並行請求數量。

**ConcurrentRequestsPerCopy**  
推論元件所接收的並行請求數量。

這些指標會追蹤模型容器所處理的並行請求數量，包括排入容器佇列的請求。針對以記號串流形式傳送推論回應的模型，這些指標會追蹤每個請求，直到模型傳送請求的最後一個字符為止。

高解析度指標比標準 CloudWatch 指標更頻繁發出資料。例如 `InvocationsPerInstance` 指標等標準指標每分鐘發出一次資料。而高解析度指標每 10 秒即發出一次資料。因此，隨著模型的並行流量增加，您的政策會比標準指標更快橫向擴充以進行回應。不過，隨著模型流量減少，您的政策會以與標準指標相同的速度縮減。

以下是目標追蹤政策組態範例，如果每個模型的並行請求數量超過 5，則會新增執行個體。將此組態儲存至名為 `config.json` 的檔案。

```
{
    "TargetValue": 5.0,
    "PredefinedMetricSpecification":
    {
        "PredefinedMetricType": "SageMakerVariantConcurrentRequestsPerModelHighResolution"
    }
}
```

如果您使用推論元件將多個模型部署到相同端點，您可以建立一個類似的政策。在此情況下，請將 `PredefinedMetricType` 設為 `SageMakerInferenceComponentConcurrentRequestsPerCopyHighResolution`。

如需詳細資訊，請參閱 *Application Auto Scaling API 參考*中的 [TargetTrackingScalingPolicyConfiguration](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_TargetTrackingScalingPolicyConfiguration.html)。

## 定義自訂指標 (CloudWatch 指標：CPUUtilization)


若要使用自訂指標建立目標追蹤擴展政策，請指定指標名稱、命名空間、單位、統計資料，以及零或多個維度。維度由維度名稱和維度值組成。您可以使用隨容量比例變更的任何生產變體指標。

**Example**  
下列的組態範例是有自訂指標的目標追蹤擴展政策。此政策會根據所有執行個體的平均 CPU 使用率 50% 來擴展變體。將此組態儲存至名為 `config.json` 的檔案。  

```
{
    "TargetValue": 50.0,
    "CustomizedMetricSpecification":
    {
        "MetricName": "CPUUtilization",
        "Namespace": "/aws/sagemaker/Endpoints",
        "Dimensions": [
            {"Name": "EndpointName", "Value": "my-endpoint" },
            {"Name": "VariantName","Value": "my-variant"}
        ],
        "Statistic": "Average",
        "Unit": "Percent"
    }
}
```
如需詳細資訊，請參閱《*Application Auto Scaling API 參考*》中的 [CustomizedMetricSpecification](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_CustomizedMetricSpecification.html)。

## 定義自訂指標 (CloudWatch 指標：ExplanationsPerInstance)


當端點啟用線上可解釋性時，會發出一個 `ExplanationsPerInstance` 指標，輸出每個執行個體的一個變體每分鐘可解釋性的平均記錄數。可解釋記錄的資源使用率，可以和預測的記錄大為不同。我們強烈建議啟用線上可解釋性，將此指標用於端點的目標追蹤擴展。

您可以為可擴展目標建立多個目標追蹤政策。請考慮從 [指定預先定義的指標 (CloudWatch 指標：InvocationsPerInstance)](#endpoint-auto-scaling-add-code-predefined) 區段 (除了 `ExplanationsPerInstance` 政策) 加入 `InvocationsPerInstance` 政策。如果大多數調用因為 `EnableExplanations` 參數中設定的閾值而未傳回解釋，則端點可以選擇 `InvocationsPerInstance` 政策。如果有大量的解釋，端點可以使用該 `ExplanationsPerInstance` 策略。

**Example**  
下列的組態範例是有自訂指標的目標追蹤擴展政策。該政策擴展會調整變體執行個體的數量，讓每個執行個體的 `ExplanationsPerInstance` 指標為 20。將此組態儲存至名為 `config.json` 的檔案。  

```
{
    "TargetValue": 20.0,
    "CustomizedMetricSpecification":
    {
        "MetricName": "ExplanationsPerInstance",
        "Namespace": "AWS/SageMaker",
        "Dimensions": [
            {"Name": "EndpointName", "Value": "my-endpoint" },
            {"Name": "VariantName","Value": "my-variant"}
        ],
        "Statistic": "Sum"
    }
}
```

如需詳細資訊，請參閱《*Application Auto Scaling API 參考*》中的 [CustomizedMetricSpecification](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_CustomizedMetricSpecification.html)。

## 指定冷卻時間


您可以選擇指定 `ScaleOutCooldown` 和 `ScaleInCooldown` 參數，在目標追蹤擴展政策中定義冷卻時間。

**Example**  
以下是變體的目標追蹤政策組態範例，該組態會將每個執行個體的平均調用保持在 70。這個政策組態分別提供了 10 分鐘 (600 秒) 的縮減冷卻時間和 5 分鐘 (300 秒) 的橫向擴充冷卻時間。將此組態儲存至名為 `config.json` 的檔案。  

```
{
    "TargetValue": 70.0,
    "PredefinedMetricSpecification":
    {
        "PredefinedMetricType": "SageMakerVariantInvocationsPerInstance"
    },
    "ScaleInCooldown": 600,
    "ScaleOutCooldown": 300
}
```
如需詳細資訊，請參閱 *Application Auto Scaling API 參考*中的 [TargetTrackingScalingPolicyConfiguration](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_TargetTrackingScalingPolicyConfiguration.html)。

# 套用擴展政策


在註冊您的模型和定義擴展政策之後，請將此擴展政策套用到已註冊的模型。本節說明如何使用 AWS Command Line Interface (AWS CLI) 或 Application Auto Scaling API 套用擴展政策。

**Topics**
+ [

## 套用目標追蹤擴展政策 (AWS CLI)
](#endpoint-auto-scaling-add-code-apply-cli)
+ [

## 套用擴展政策 (Application Auto Scaling API)
](#endpoint-auto-scaling-add-code-apply-api)

## 套用目標追蹤擴展政策 (AWS CLI)


若要將擴展政策套用至模型，請使用 [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) AWS CLI 命令搭配下列參數：
+ `--policy-name`—擴展政策的名稱。
+ `--policy-type`—將此值設定為 `TargetTrackingScaling`。
+ `--resource-id`—此變體的資源識別符。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `--service-namespace`—將此值設定為 `sagemaker`。
+ `--scalable-dimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。
+ `--target-tracking-scaling-policy-configuration`—要用於模型的目標追蹤擴展政策組態。

**Example**  
下列的範例將名為 `my-scaling-policy` 的目標追蹤擴展政策套用到在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體。請針對 `--target-tracking-scaling-policy-configuration` 選項，指定您先前建立的 `config.json` 檔案。  

```
aws application-autoscaling put-scaling-policy \
  --policy-name my-scaling-policy \
  --policy-type TargetTrackingScaling \
  --resource-id endpoint/my-endpoint/variant/my-variant \
  --service-namespace sagemaker \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount \
  --target-tracking-scaling-policy-configuration file://config.json
```

## 套用擴展政策 (Application Auto Scaling API)


若要使用 Application Auto Scaling API 將擴展政策套用到變體，請使用 [PutScalingPolicy](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_PutScalingPolicy.html) Application Auto Scaling API 動作搭配下列參數：
+ `PolicyName`—擴展政策的名稱。
+ `ServiceNamespace`—將此值設定為 `sagemaker`。
+ `ResourceID`—此變體的資源識別符。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `ScalableDimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。
+ `PolicyType`—將此值設定為 `TargetTrackingScaling`。
+ `TargetTrackingScalingPolicyConfiguration`—要用於變體的目標追蹤擴展政策組態。

**Example**  
下列的範例將名為 `my-scaling-policy` 的目標追蹤擴展政策套用到在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體。政策組態會將每個執行個體的平均調用保持在 70。  

```
POST / HTTP/1.1
Host: application-autoscaling.us-east-2.amazonaws.com
Accept-Encoding: identity
X-Amz-Target: AnyScaleFrontendService.
X-Amz-Date: 20230506T182145Z
User-Agent: aws-cli/2.0.0 Python/3.7.5 Windows/10 botocore/2.0.0dev4
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
    "PolicyName": "my-scaling-policy",
    "ServiceNamespace": "sagemaker",
    "ResourceId": "endpoint/my-endpoint/variant/my-variant",
    "ScalableDimension": "sagemaker:variant:DesiredInstanceCount",
    "PolicyType": "TargetTrackingScaling",
    "TargetTrackingScalingPolicyConfiguration": {
        "TargetValue": 70.0,
        "PredefinedMetricSpecification":
        {
            "PredefinedMetricType": "SageMakerVariantInvocationsPerInstance"
        }
    }
}
```

# 編輯擴展政策的說明


建立擴展政策後，您可以編輯其名稱以外的任何設定。

 若要使用 編輯目標追蹤擴展政策 AWS 管理主控台，請使用您用於 的相同程序[使用主控台設定模型自動擴展](endpoint-auto-scaling-add-console.md)。

您可以使用 AWS CLI 或 Application Auto Scaling API，以與建立新擴展政策相同的方式編輯擴展政策。如需詳細資訊，請參閱[套用擴展政策](endpoint-auto-scaling-add-code-apply.md)。

# 暫時關閉擴展政策


設定自動擴展之後，如果您需要在不受擴展政策 (動態擴展) 干擾的情況下處理問題，您可以採取下列方式：
+ 呼叫 [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) CLI 命令或 [RegisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html) API 動作，指定 `DynamicScalingInSuspended` 和 `DynamicScalingOutSuspended` 的布林值，以暫停和繼續擴展活動。  
**Example**  

  下列範例說明如何暫停名為 `my-variant` 且在 `my-endpoint` 端點上執行的變體擴展政策。

  ```
  aws application-autoscaling register-scalable-target \
    --service-namespace sagemaker \
    --resource-id endpoint/my-endpoint/variant/my-variant \
    --scalable-dimension sagemaker:variant:DesiredInstanceCount \
    --suspended-state '{"DynamicScalingInSuspended":true,"DynamicScalingOutSuspended":true}'
  ```
+ 停用政策的縮減部分，防止特定目標追蹤擴展政策在變體中縮減。這個方式可防止擴展政策刪除執行個體，同時讓此政策仍然能夠根據需要來建立執行個體。

  使用 [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) CLI 命令或 [PutScalingPolicy](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_PutScalingPolicy.html) API 動作編輯政策，指定 `DisableScaleIn` 的布林值，以暫時停用和啟用縮減活動。  
**Example**  

  以下範例是擴展政策 (會橫向擴充，但不會縮減) 的目標追蹤組態。

  ```
  {
      "TargetValue": 70.0,
      "PredefinedMetricSpecification":
      {
          "PredefinedMetricType": "SageMakerVariantInvocationsPerInstance"
      },
      "DisableScaleIn": true
  }
  ```

# 刪除擴展政策


如果您不再需要擴展政策，可以隨時將其刪除。

**Topics**
+ [

## 刪除所有擴展政策並取消註冊模型 (主控台)
](#endpoint-auto-scaling-delete-console)
+ [

## 刪除擴展政策 (AWS CLI 或 Application Auto Scaling API)
](#endpoint-auto-scaling-delete-code)

## 刪除所有擴展政策並取消註冊模型 (主控台)


**刪除所有擴展政策，並取消註冊變體為可擴展目標**

1. 開啟位在 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 的 Amazon SageMaker AI 主控台。

1. 在導覽窗格中選擇**端點**。

1. 選擇您的端點，然後針對**端點執行時期設定**選擇變體。

1. 選擇**設定自動擴展**。

1. 選擇**取消登錄自動擴展**。

## 刪除擴展政策 (AWS CLI 或 Application Auto Scaling API)


您可以使用 AWS CLI 或 Application Auto Scaling API 從變體中刪除擴展政策。

### 刪除擴展政策 (AWS CLI)


若要刪除變體的擴展政策，請使用 [delete-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/delete-scaling-policy.html) 命令搭配下列參數：
+ `--policy-name`—擴展政策的名稱。
+ `--resource-id`—此變體的資源識別符。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `--service-namespace`—將此值設定為 `sagemaker`。
+ `--scalable-dimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。

**Example**  
下列的範例從在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體刪除名為 `my-scaling-policy` 的目標追蹤擴展政策。  

```
aws application-autoscaling delete-scaling-policy \
  --policy-name my-scaling-policy \
  --resource-id endpoint/my-endpoint/variant/my-variant \
  --service-namespace sagemaker \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount
```

### 刪除擴展政策 (Application Auto Scaling API)


若要從變體刪除擴展政策，請使用 [DeleteScalingPolicy](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_DeleteScalingPolicy.html) Application Auto Scaling API 動作搭配下列參數：
+ `PolicyName`—擴展政策的名稱。
+ `ServiceNamespace`—將此值設定為 `sagemaker`。
+ `ResourceID`—此變體的資源識別符。針對這項參數，資源的類型為 `endpoint`，而唯一識別符是變體的名稱。例如 `endpoint/my-endpoint/variant/my-variant`。
+ `ScalableDimension`—將此值設定為 `sagemaker:variant:DesiredInstanceCount`。

**Example**  
下列的範例從在 `my-endpoint` 端點上執行且名為 `my-variant` 的變體刪除名為 `my-scaling-policy` 的目標追蹤擴展政策。  

```
POST / HTTP/1.1
Host: application-autoscaling.us-east-2.amazonaws.com
Accept-Encoding: identity
X-Amz-Target: AnyScaleFrontendService.DeleteScalingPolicy
X-Amz-Date: 20230506T182145Z
User-Agent: aws-cli/2.0.0 Python/3.7.5 Windows/10 botocore/2.0.0dev4
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
    "PolicyName": "my-scaling-policy",
    "ServiceNamespace": "sagemaker",
    "ResourceId": "endpoint/my-endpoint/variant/my-variant",
    "ScalableDimension": "sagemaker:variant:DesiredInstanceCount"
}
```

# 描述擴展活動以檢查擴展活動的狀態
檢查擴展活動的狀態

您可以透過描述擴展活動來檢查自動擴展端點的擴展活動狀態。Application Auto Scaling 提供過去六週內，具有指定之命名空間的擴展活動的描述性資訊。如需詳細資訊，請參閱《Application Auto Scaling 使用者指南》**中的[適用於 Application Auto Scaling 的擴展活動](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-scaling-activities.html)。

若要檢查擴展活動的狀態，請使用 [describe-scaling-activities](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scaling-activities.html) 命令。您無法透過主控台檢查擴展活動的狀態。

**Topics**
+ [

## 描述擴展活動 (AWS CLI)
](#endpoint-how-to)
+ [

## 從執行個體配額中找出封鎖的擴展活動 (AWS CLI)
](#endpoint-identify-blocked-autoscaling)

## 描述擴展活動 (AWS CLI)


若要描述向 Application Auto Scaling 註冊的所有 SageMaker AI 資源的擴展活動，請使用 [describe-scaling-activities](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scaling-activities.html) 命令，為 `--service-namespace` 選項指定 `sagemaker`。

```
aws application-autoscaling describe-scaling-activities \
  --service-namespace sagemaker
```

若要描述特定資源的擴展活動，請納入 `--resource-id` 選項。

```
aws application-autoscaling describe-scaling-activities \
  --service-namespace sagemaker \
  --resource-id endpoint/my-endpoint/variant/my-variant
```

下列範例顯示執行此命令時的輸出。

```
{
    "ActivityId": "activity-id",
    "ServiceNamespace": "sagemaker",
    "ResourceId": "endpoint/my-endpoint/variant/my-variant",
    "ScalableDimension": "sagemaker:variant:DesiredInstanceCount",
    "Description": "string",
    "Cause": "string",
    "StartTime": timestamp,
    "EndTime": timestamp,
    "StatusCode": "string",
    "StatusMessage": "string"
}
```

## 從執行個體配額中找出封鎖的擴展活動 (AWS CLI)


橫向擴充 (新增更多執行個體) 時，您可能會達到您的帳戶層級執行個體配額。您可以使用 [describe-scaling-activities](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scaling-activities.html) 命令來檢查是否已達到執行個體配額。當您超出配額時，系統會封鎖自動擴展。

若要檢查是否已達到執行個體配額，請使用 [describe-scaling-activities](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scaling-activities.html) 命令，並指定 `--resource-id` 選項的資源 ID。

```
aws application-autoscaling describe-scaling-activities \
    --service-namespace sagemaker \
    --resource-id endpoint/my-endpoint/variant/my-variant
```

在傳回語法中，檢查 [StatusCode](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_ScalingActivity.html#autoscaling-Type-ScalingActivity-StatusCode) 和 [StatusMessage](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_ScalingActivity.html#autoscaling-Type-ScalingActivity-StatusMessage) 鍵及其相關值。`StatusCode` 傳回 `Failed`。在 `StatusMessage` 內有一則訊息，指出已達到帳戶層級的服務配額。以下是訊息的範例：

```
{
    "ActivityId": "activity-id",
    "ServiceNamespace": "sagemaker",
    "ResourceId": "endpoint/my-endpoint/variant/my-variant",
    "ScalableDimension": "sagemaker:variant:DesiredInstanceCount",
    "Description": "string",
    "Cause": "minimum capacity was set to 110",
    "StartTime": timestamp,
    "EndTime": timestamp,
    "StatusCode": "Failed",
    "StatusMessage": "Failed to set desired instance count to 110. Reason: The 
    account-level service limit 'ml.xx.xxxxxx for endpoint usage' is 1000 
    Instances, with current utilization of 997 Instances and a request delta 
    of 20 Instances. Please contact AWS support to request an increase for this 
    limit. (Service: AmazonSageMaker; Status Code: 400; 
    Error Code: ResourceLimitExceeded; Request ID: request-id)."
}
```

# 將端點擴展到零個執行個體


設定端點的自動擴展時，您可以允許縮減程序，將服務中執行個體的數量減少到零。這樣一來，您可以在端點未提供推論請求，因此不需要任何作用中執行個體的期間節省成本。

不過，在縮減至零個執行個體之後，端點在佈建至少一個執行個體之前，無法回應任何傳入的推論請求。若要自動化佈建程序，請使用 Application Auto Scaling 建立步進擴展政策。然後將政策指派給 Amazon CloudWatch 警示。

設定步進擴展政策和警示後，端點會在收到無法回應的推論請求後，自動佈建執行個體。請注意，佈建程序需要花費幾分鐘。在此期間，任何調用端點的嘗試都會產生錯誤。

下列程序說明如何設定端點的自動擴展，使其縮減至和擴展自零個執行個體。這些程序搭配使用命令和 AWS CLI。

**開始之前**

在端點可以縮減至和擴展自零個執行個體之前，端點必須符合下列要求：
+ 位於服務中。
+ 託管一個或多個推論元件。端點只有在託管推論元件時，才能在零執行個體之間擴展。

  如需進一步瞭解如何在 SageMaker AI 端點上託管推論元件，請參閱 [部署用於即時推論的模型](realtime-endpoints-deploy-models.md)。
+ 在端點組態中，您已經針對生產變體 `ManagedInstanceScaling` 物件，將 `MinInstanceCount` 參數設為 `0`。

  如需此參數的參考資訊，請參閱 [ProductionVariantManagedInstanceScaling](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProductionVariantManagedInstanceScaling.html)。

**讓端點縮減至零個執行個體 (AWS CLI)**

請針對端點所託管的每個推論元件，執行下列動作：

1. 將推論元件註冊為可擴展目標。註冊時，請將容量下限設為 `0`，如下列命令所示：

   ```
   aws application-autoscaling register-scalable-target \
     --service-namespace sagemaker \
     --resource-id inference-component/inference-component-name \
     --scalable-dimension sagemaker:inference-component:DesiredCopyCount \
     --min-capacity 0 \
     --max-capacity n
   ```

   在此範例中，將 *inference-component-name* 取代為推論元件的名稱。將 *n* 取代為橫向擴充時要佈建的推論元件複本數量上限。

   如需此命令及其每個參數的詳細資訊，請參閱《AWS CLI 命令參考》**中的 [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html)。

1. 將目標追蹤政策套用至推論元件，如下列命令所示：

   ```
   aws application-autoscaling put-scaling-policy \
     --policy-name my-scaling-policy \
     --policy-type TargetTrackingScaling \
     --resource-id inference-component/inference-component-name \
     --service-namespace sagemaker \
     --scalable-dimension sagemaker:inference-component:DesiredCopyCount \
     --target-tracking-scaling-policy-configuration file://config.json
   ```

   在此範例中，將 *inference-component-name* 取代為推論元件的名稱。

   在此範例中，`config.json` 檔案包含目標追蹤政策組態，如下所示：

   ```
   {
     "PredefinedMetricSpecification": {
         "PredefinedMetricType": "SageMakerInferenceComponentInvocationsPerCopy"
     },
     "TargetValue": 1,
     "ScaleInCooldown": 300,
     "ScaleOutCooldown": 300
   }
   ```

   如需更多追蹤政策組態範例，請參閱 [定義擴展政策](endpoint-auto-scaling-add-code-define.md)。

   如需此命令及其每個參數的詳細資訊，請參閱《AWS CLI 命令參考》**中的 [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html)。

**讓端點自零個執行個體橫向擴充 (AWS CLI)**

請針對端點所託管的每個推論元件，執行下列動作：

1. 將步進擴展政策套用至推論元件，如下列命令所示：

   ```
   aws application-autoscaling put-scaling-policy \
     --policy-name my-scaling-policy \
     --policy-type StepScaling \
     --resource-id inference-component/inference-component-name \
     --service-namespace sagemaker \
     --scalable-dimension sagemaker:inference-component:DesiredCopyCount \
     --step-scaling-policy-configuration file://config.json
   ```

   在此範例中，將 *my-scaling-policy* 取代為政策的唯一名稱。將 *inference-component-name* 取代為推論元件的名稱。

   在此範例中，`config.json` 檔案包含步進擴展政策組態，如下所示：

   ```
   {
       "AdjustmentType": "ChangeInCapacity",
       "MetricAggregationType": "Maximum",
       "Cooldown": 60,
       "StepAdjustments":
         [
            {
              "MetricIntervalLowerBound": 0,
              "ScalingAdjustment": 1
            }
         ]
   }
   ```

   觸發此步進擴展政策時，SageMaker AI 會佈建必要的執行個體，以支援推論元件複本。

   建立步進擴展政策後，請記下其 Amazon Resource Name (ARN)。在下一個步驟中，您會需要 CloudWatch 警示的 ARN。

   如需有關步進擴展政策的詳細資訊，請參閱《Application Auto Scaling 使用者指南》**中的[步進擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-step-scaling-policies.html)。

1. 建立 CloudWatch 警示並將步進擴展政策指派給它，如下範例所示：

   ```
   aws cloudwatch put-metric-alarm \
   --alarm-actions step-scaling-policy-arn \
   --alarm-description "Alarm when SM IC endpoint invoked that has 0 instances." \
   --alarm-name ic-step-scaling-alarm \
   --comparison-operator GreaterThanThreshold  \
   --datapoints-to-alarm 1 \
   --dimensions "Name=InferenceComponentName,Value=inference-component-name" \
   --evaluation-periods 1 \
   --metric-name NoCapacityInvocationFailures \
   --namespace AWS/SageMaker \
   --period 60 \
   --statistic Sum \
   --threshold 1
   ```

   在此範例中，將 *step-scaling-policy-arn* 取代為步進擴展政策的 ARN。將 *ic-step-scaling-alarm* 取代為您選擇的名稱。將 *inference-component-name* 取代為推論元件的名稱。

   此範例將 `--metric-name` 參數設為 `NoCapacityInvocationFailures`。端點收到推論請求，但沒有可以提供請求的作用中執行個體時，SageMaker AI 會發出此指標。在此情況下，警示會啟動上一個步驟的步進擴展政策。

   如需此命令及其每個參數的詳細資訊，請參閱《AWS CLI 命令參考》**中的 [put-metric-alarm](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-alarm.html)。

# 負載測試您的自動擴展組態
負載測試

進行負載測試，以選擇運作結果符合您預期的擴展組態。

下列的負載測試準則，假設您所使用的擴展政策，使用了預先定義的目標指標 `SageMakerVariantInvocationsPerInstance`。

**Topics**
+ [

## 決定效能特性
](#endpoint-scaling-loadtest-variant)
+ [

## 計算目標負載
](#endpoint-scaling-loadtest-calc)

## 決定效能特性


進行負載測試，以找出您的模型生產變體執行個體可處理的峰值 `InvocationsPerInstance`，和並行作業增加時的請求延遲。

這個值取決於所選擇的執行個體類型、模型的用戶端通常會傳送的酬載，以及模型所具備任何外部相依項目的效能。

**若要找出您的模型生產變體每秒可處理的峰值請求數 (RPS)，以及請求的延遲**

1. 使用單一執行個體，來設定您模型的端點。關於設定端點的方法，詳細資訊請參閱[將模型部署至 SageMaker AI 託管服務](ex1-model-deployment.md#ex1-deploy-model)。

1. 使用負載測試工具來產生數量不斷增加的平行請求，並監控負載測試工具的 RPS 和輸出中的模型延遲。
**注意**  
您還可以監控每分鐘可處理的請求數而非 RPS。在這個情境中，不需要在方程式中乘上 60 以求出 `SageMakerVariantInvocationsPerInstance`，如下所示。

   當模型的延遲增加，或交易成功的比例減少時，這就是模型可處理的峰值 RPS。

## 計算目標負載


在找出變體的效能特性之後，您可以決定應允許傳送到執行個體的最大 RPS。用於擴展的閾值，必須小於這個最大值。請利用下列的方程式，並結合負載測試，來為您擴展組態中的 `SageMakerVariantInvocationsPerInstance` 目標指標，找出正確的值。

```
SageMakerVariantInvocationsPerInstance = (MAX_RPS * SAFETY_FACTOR) * 60
```

其中，`MAX_RPS` 是您先前所找出的最大 RPS，`SAFETY_FACTOR` 則是您所選擇的安全係數，用來確保您的用戶端不會超過最大 RPS。乘上 60，從 RPS 轉換為每分鐘的調用數，以符合每分鐘的 CloudWatch 指標，SageMaker AI 用它來部署自動擴展 (如果您測量的是每分鐘處理的請求數，而非每秒鐘處理的請求數，就不需執行此作業)。

**注意**  
SageMaker AI 建議您用 0.5 的 `SAFETY_FACTOR` 開始測試。測試您的擴展組態，確保您的模型在端點增加和減少客戶傳輸流量時，能如預期運作。

# 使用 CloudFormation 建立擴展政策


下列範例說明如何使用 CloudFormation在端點上設定模型自動擴展。

```
  Endpoint:
    Type: "AWS::SageMaker::Endpoint"
    Properties:
      EndpointName: yourEndpointName
      EndpointConfigName: yourEndpointConfigName

  ScalingTarget:
    Type: "AWS::ApplicationAutoScaling::ScalableTarget"
    Properties:
      MaxCapacity: 10
      MinCapacity: 2
      ResourceId: endpoint/my-endpoint/variant/my-variant
      RoleARN: arn
      ScalableDimension: sagemaker:variant:DesiredInstanceCount
      ServiceNamespace: sagemaker

  ScalingPolicy:
    Type: "AWS::ApplicationAutoScaling::ScalingPolicy"
    Properties:
      PolicyName: my-scaling-policy
      PolicyType: TargetTrackingScaling
      ScalingTargetId:
        Ref: ScalingTarget
      TargetTrackingScalingPolicyConfiguration:
        TargetValue: 70.0
        ScaleInCooldown: 600
        ScaleOutCooldown: 30
        PredefinedMetricSpecification:
          PredefinedMetricType: SageMakerVariantInvocationsPerInstance
```

如需詳細資訊，請參閱*《Application Auto Scaling 使用者指南》*中的[以 AWS CloudFormation建立 Application Auto Scaling](https://docs.aws.amazon.com/autoscaling/application/userguide/creating-resources-with-cloudformation.html)。

# 更新使用自動擴展的端點


當您更新端點時，Application Auto Scaling 會檢查在該端點上，是否有任何模型成為自動擴展的目標。如果更新作業將會針對做為自動擴展目標的任何模型，並更其執行個體類型，則更新會失敗。

在 中 AWS 管理主控台，您會看到警告，指出您必須先從自動擴展取消註冊模型，才能更新模型。如果您試著透過呼叫 [UpdateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html) API 來更新端點，則呼叫會失敗。在您更新端點之前，請先呼叫 [DeregisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_DeregisterScalableTarget.html) Application Auto Scaling API 動作，刪除針對該端點設定的所有擴展政策，然後再取消註冊變體為可擴展目標。在更新端點之後，您可以將更新的變體註冊為可擴展目標，然後連接擴展政策。

有一種例外狀況。如果您針對已設定自動擴展的變體，來變更其模型，則 Amazon SageMaker AI 自動擴展功能會允許更新。這是因為變更模型對效能的影響，通常不足以大到會改變擴展的動作。如果您真的針對已設定自動擴展的變體，來變更其模型，請確定對模型所進行的變更，不會造成對效能和擴展動作的重大影響。

當您更新套用自動擴展的 SageMaker AI 端點，請完成以下步驟：

**更新套用自動擴展的端點**

1. 呼叫 [DeregisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_DeregisterScalableTarget.html)，將端點從可擴展的目標解除登錄。

1. 由於在進行更新操作時會封鎖自動擴展 (或是若您在上一個步驟中關閉了自動縮減)，因此您可能需要採取額外的預防措施，以便在更新期間增加端點的執行個體數目。若要這樣做，請呼叫 [UpdateEndpointWeightsAndCapacities](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html) 以更新端點所託管生產變體的執行個體數量。

1. 重複呼叫 [ DescribeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpoint.html)，直到回應的 `EndpointStatus` 欄位的值是 `InService`。

1. 呼叫 [DescribeEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html) 以取得目前端點組態的值。

1. 呼叫 [ CreateEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html)，建立新的端點組態。對於您想要保留現有執行個體數量或加權的生產變體，請使用上一個步驟中對 [DescribeEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html) 呼叫所得回應的相同變體名稱。對於所有其他值，請使用在上一步中呼叫 [DescribeEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeEndpointConfig.html) 時所取得回應的值。

1. 透過呼叫 [UpdateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html) 來更新端點。將您在上一步中建立的端點組態指定為 `EndpointConfig` 欄位。如果要保留執行個體計數或加權等變體屬性，請將 `RetainAllVariantProperties` 參數值設定為 `True`。這會指定具有相同名稱的生產變體將使用最新版本 `DesiredInstanceCount` 進行更新，這是來自對 `DescribeEndpoint` 的呼叫所得的回應，而不管新 `EndpointConfig` 中 `InitialInstanceCount` 欄位值為何。

1. (選用) 透過呼叫 [RegisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html) 和 [PutScalingPolicy](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_PutScalingPolicy.html) 重新啟用自動擴展。

**注意**  
只有在因下列變更而更新端點時，才需要進行步驟 1 和 7：  
變更已設定自動擴展的生產變體的執行個體類型
移除已設定自動擴展的生產變體。

# 刪除針對自動擴展功能設定的端點


如果您刪除端點，Application Auto Scaling 會檢查在該端點上，是否有任何模型成為了自動擴展的目標。如果有的話，而且您有解除登錄模型的權限，Application Auto Scaling 會逕自解除這些作為可擴展目標的登錄，不會再另行通知您。如果您使用的自訂許可政策不提供 [DeregisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_DeregisterScalableTarget.html) 動作的許可，您必須在刪除端點之前請求存取此動作。

**注意**  
如果其他使用者在端點上已設定變體的自動擴展，則身為 IAM 使用者的您，許可或許不足以刪除該端點。

# 執行個體存放區磁碟區


當您建立端點時，Amazon SageMaker AI 會將 Amazon Elastic Block Store (Amazon EBS) 儲存磁碟區連接至託管端點的 Amazon EC2 執行個體。儲存磁碟區的大小可擴展，儲存選項分為兩類：SSD 支援的儲存裝置和 HDD 支援的儲存裝置。

有關 Amazon EBS 儲存和功能的更多相關資訊，請參閱以下頁面。
+ [Amazon EBS 功能](https://aws.amazon.com/ebs/features/)
+ [Amazon EBS 使用者指南](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html)

如需託管執行個體儲存磁碟區的完整清單，請參閱[託管執行個體儲存磁碟區表格](https://aws.amazon.com/releasenotes/host-instance-storage-volumes-table/) 

**注意**  
只有當您建立[非同步推論](async-inference.md)或[即時推論](realtime-endpoints.md)端點類型時，Amazon SageMaker AI 才會將 Amazon Elastic Block Store (Amazon EBS) 儲存磁碟區連接至 Amazon EC2 執行個體。如需自訂 Amazon EBS 儲存磁碟區的更多資訊，請參閱[大型模型推論的 SageMaker AI 端點參數](large-model-inference-hosting.md)。

# 驗證生產環境中的模型


 使用 SageMaker AI，您就可以使用變體，在相同端點背後測試多個模型或模型版本。變體由機器學習 (ML) 執行個體和 SageMaker AI 模型中指定的服務元件組成。您可以有端點背後的多個變體。每個變體都可以具有不同的執行個體類型，或可自動擴展且獨立於其他變體的 SageMaker AI 模型。可以使用不同的資料集、不同的演算法、不同的機器學習 (ML) 架構或所有這些的任何組合訓練變體內的模型。端點背後的所有變體共用相同的推論程式碼。SageMaker AI 支援兩種類型的變體 (生產變體和陰影變體)。

 如果端點背後具有多個生產變體，則可以將一部分推論請求配置給每個變體。每個請求只會轉接至其中一個生產變體。轉接請求到所在的生產變體會將回應提供給呼叫者。您可以比較各個生產變體如何彼此相對執行。

 您也可以具有與端點背後之生產變體相對應的陰影變體。導向生產變體的一部份推論請求會複寫到陰影變體。陰影變體的回應會記錄進行比較，並不會傳回給呼叫者。這可讓您不會在陰影變體所產生的回應中公開呼叫者的情況下，測試陰影變體的效能。

**Topics**
+ [

# 使用生產變體測試模型
](model-ab-testing.md)
+ [

# 使用陰影變體測試模型
](model-shadow-deployment.md)

# 使用生產變體測試模型


 在生產機器學習 (ML) 工作流程中，資料科學家和工程師經常嘗試以各種方式改善效能，例如執行 [使用 SageMaker AI 執行自動模型調校](automatic-model-tuning.md)、訓練其他或更新的資料、改善功能選擇、使用更好的更新執行個體和服務容器。您可以使用生產變體來比較模型、執行個體和容器，並選擇最佳執行候選項來回應推論請求。

 透過 SageMaker AI 多變體端點，您可以將端點調用請求發佈到多個生產變體，方法是為每個變體提供流量分佈，或直接為每個請求調用特定變體。在本主題中，這兩種方法都會用來測試機器學習 (ML) 模型。

**Topics**
+ [

## 指定流量分配來測試模型
](#model-testing-traffic-distribution)
+ [

## 調用特定變體來測試模型
](#model-testing-target-variant)
+ [

## 模型 A/B 測試範例
](#model-ab-test-example)

## 指定流量分配來測試模型


 若要在多個模型之間分配流量以測試模型，請在端點組態中指定每個生產變體的權重，以指定要路由至每個模型的流量百分比。如需相關資訊，請參閱 [CreateEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html)。下圖顯示更詳細的運作情形。

![\[此範例顯示如何在 SageMaker AI 中使用 InvokeEndpoint 工作在模型之間分配流量。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-traffic-distribution.png)


## 調用特定變體來測試模型


 若要透過調用每個請求的特定模型來測試多個模型，請在呼叫 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) 時提供 `TargetVariant` 參數值，以指定要調用的特定模型版本。SageMaker AI 可確保請求由您指定的生產變體處理。如果您已提供流量分配並指定 `TargetVariant` 參數的值，則目標路由會覆寫隨機流量分配。下圖顯示更詳細的運作情形。

![\[此範例顯示如何在 SageMaker AI 中使用 InvokeEndpoint 工作為每個請求調用特定模型。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-target-variant.png)


## 模型 A/B 測試範例


 在新模型的驗證過程中，使用生產流量在新模型和舊模型之間執行 A/B 測試，是很有效的最後步驟。在 A/B 測試中，您可以測試模型的不同變體，並比較每個變體的表現。如果較新版的模型比現有版本的效能更好，請在生產環境中以新版本取代舊版模型。

 下列範例示範如何執行 A/B 模型測試。如需實作此範例的範例筆記本，請參閱[在生產環境中進行機器學習 (ML) 模型 A/B 測試](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker_endpoints/a_b_testing/a_b_testing.html)。

### 步驟 1：建立和部署模型


 首先，我們在 Amazon S3 中定義模型所在的位置。我們在後續步驟部署模型時會使用這些位置：

```
model_url = f"s3://{path_to_model_1}"
model_url2 = f"s3://{path_to_model_2}"
```

 接下來，我們以影像和模型資料建立模型物件。這些模型物件用於將生產變體部署到端點。我們以不同的資料集、不同的演算法或機器學習 (ML) 架構及不同的超參數來訓練機器學習 (ML) 模型，以開發模型：

```
from sagemaker.amazon.amazon_estimator import get_image_uri

model_name = f"DEMO-xgb-churn-pred-{datetime.now():%Y-%m-%d-%H-%M-%S}"
model_name2 = f"DEMO-xgb-churn-pred2-{datetime.now():%Y-%m-%d-%H-%M-%S}"
image_uri = get_image_uri(boto3.Session().region_name, 'xgboost', '0.90-1')
image_uri2 = get_image_uri(boto3.Session().region_name, 'xgboost', '0.90-2')

sm_session.create_model(
    name=model_name,
    role=role,
    container_defs={
        'Image': image_uri,
        'ModelDataUrl': model_url
    }
)

sm_session.create_model(
    name=model_name2,
    role=role,
    container_defs={
        'Image': image_uri2,
        'ModelDataUrl': model_url2
    }
)
```

 現在，我們建立兩個生產變體，各自有不同的模型和資源需求 (執行個體類型和計數)。這可讓您在不同的執行個體類型上測試模型。

 我們將兩個變體的 initial\$1weight 都設為 1。這表示 50% 的請求傳送至 `Variant1`，其餘 50% 的請求傳送至 `Variant2`。這兩個變體的權重總和是 2，每個變體的權重分配為 1。這表示每個變體會收到總流量的 1/2 (或 50%)。

```
from sagemaker.session import production_variant

variant1 = production_variant(
               model_name=model_name,
               instance_type="ml.m5.xlarge",
               initial_instance_count=1,
               variant_name='Variant1',
               initial_weight=1,
           )

variant2 = production_variant(
               model_name=model_name2,
               instance_type="ml.m5.xlarge",
               initial_instance_count=1,
               variant_name='Variant2',
               initial_weight=1,
           )
```

 最後，我們已準備好將這些生產變體部署到 SageMaker AI 端點。

```
endpoint_name = f"DEMO-xgb-churn-pred-{datetime.now():%Y-%m-%d-%H-%M-%S}"
print(f"EndpointName={endpoint_name}")

sm_session.endpoint_from_production_variants(
    name=endpoint_name,
    production_variants=[variant1, variant2]
)
```

### 步驟 2：調用已部署的模型


 現在，我們將請求傳送至這個個端點以即時獲得推論。我們使用流量分配和直接設定目標。

 首先，我們使用上一個步驟中設定的流量分配。每個推論回應都包含負責處理請求的生產變體名稱，因此，我們可以看到兩個生產變體的流量大致相等。

```
# get a subset of test data for a quick test
!tail -120 test_data/test-dataset-input-cols.csv > test_data/test_sample_tail_input_cols.csv
print(f"Sending test traffic to the endpoint {endpoint_name}. \nPlease wait...")

with open('test_data/test_sample_tail_input_cols.csv', 'r') as f:
    for row in f:
        print(".", end="", flush=True)
        payload = row.rstrip('\n')
        sm_runtime.invoke_endpoint(
            EndpointName=endpoint_name,
            ContentType="text/csv",
            Body=payload
        )
        time.sleep(0.5)

print("Done!")
```

 SageMaker AI 會針對 Amazon CloudWatch 中的每個變體發出指標，例如 `Latency` 和 `Invocations`。關於 SageMaker AI 發出的指標，如需完整指標清單，請參閱[Amazon CloudWatch 中的 Amazon SageMaker AI 指標](monitoring-cloudwatch.md)。我們來查詢 CloudWatch 以取得每個變體的調用次數，以了解調用如何依預設值分配給變體：

![\[每個變體的 CloudWatch 調用次數範例。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-variant-invocations.png)


 現在，讓我們在呼叫 `invoke_endpoint` 時將 `Variant1` 指定為 `TargetVariant`，以調用特定版本的模型。

```
print(f"Sending test traffic to the endpoint {endpoint_name}. \nPlease wait...")
with open('test_data/test_sample_tail_input_cols.csv', 'r') as f:
    for row in f:
        print(".", end="", flush=True)
        payload = row.rstrip('\n')
        sm_runtime.invoke_endpoint(
            EndpointName=endpoint_name,
            ContentType="text/csv",
            Body=payload,
            TargetVariant="Variant1"
        ) 
        time.sleep(0.5)
```

 若要確認所有新的調用都由 `Variant1` 處理，我們可以查詢 CloudWatch 以取得每個變體的調用次數。我們看到，在最近的調用中 (最新的時間戳記)，所有請求都由 `Variant1` 處理，符合我們的指定。沒有調用 `Variant2`。

![\[每個變體的 CloudWatch 調用次數範例。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-invocations-target1.png)


### 步驟 3：評估模型效能


 為了判斷哪個模型版本表現更好，讓我們評估每個變體的準確性、精確度、召回、F1 分數及接受者操作特性/曲線下面積。首先，讓我們看看 `Variant1` 的這些指標：

![\[操作 Variant1 特性曲線的範例接收器。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-curve.png)


現在，讓我們看看 `Variant2` 的這些指標：

![\[操作 Variant2 特性曲線的範例接收器。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model2-curve.png)


 在我們已定義的大多數指標上，`Variant2` 表現較好，所以這就是生產環境中應該使用的變體。

### 步驟 4：增加最佳模型的流量


 既然已確定 `Variant2` 表現優於 `Variant1`，我們就將更多流量轉給此變體。我們可以繼續使用 `TargetVariant` 來調用特定的模型變體，但更簡單的方法是呼叫 [UpdateEndpointWeightsAndCapacities](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html)，以更新分配給每個變體的權重。這樣可變更生產變體的流量分配，而不需要更新端點。回想一下設定這一節，我們設定變體權重將流量分割成 50/50。從以下每個變體調用總數的 CloudWatch 指標，可看出每個變體的調用模式：

![\[每個變體的 CloudWatch 總調用數指標範例。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-invocations-even-dist.png)


 現在，我們透過使用 `UpdateEndpointWeightsAndCapacities` 為每個變體指派新權重來將 75％ 的流量轉移到 `Variant2`。SageMaker AI 現在會將 75% 的推論請求傳送給 `Variant2` 並將剩餘的 25% 請求傳送至 `Variant1`。

```
sm.update_endpoint_weights_and_capacities(
    EndpointName=endpoint_name,
    DesiredWeightsAndCapacities=[
        {
            "DesiredWeight": 25,
            "VariantName": variant1["VariantName"]
        },
        {
            "DesiredWeight": 75,
            "VariantName": variant2["VariantName"]
        }
    ]
)
```

 從每個變體調用總數的 CloudWatch 指標，可看出 `Variant2` 的調用次數多於 `Variant1`：

![\[每個變體的 CloudWatch 總調用數指標範例。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-invocations-75-25.png)


 我們可以繼續監控指標，而在滿意變體的效能時，就可以將 100% 的流量路由到該變體。我們使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html) 來更新變體的流量分配。`Variant1` 的權重設定為 0，而 `Variant2` 的權重設定為 1。SageMaker AI 現在會將 100% 的所有推論請求傳送至 `Variant2`。

```
sm.update_endpoint_weights_and_capacities(
    EndpointName=endpoint_name,
    DesiredWeightsAndCapacities=[
        {
            "DesiredWeight": 0,
            "VariantName": variant1["VariantName"]
        },
        {
            "DesiredWeight": 1,
            "VariantName": variant2["VariantName"]
        }
    ]
)
```

 從每個變體調用總數的 CloudWatch 指標，可看出所有推論請求都由 `Variant2` 處理，而 `Variant1` 不處理任何推論請求。

![\[每個變體的 CloudWatch 總調用數指標範例。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/model-invocations-best-model.png)


 現在，您可以放心地更新端點並從端點刪除 `Variant1`。在生產環境中，您也可以將新變體新增至端點，並遵循步驟 2-4，以繼續測試新模型。

# 使用陰影變體測試模型


 您可以使用 SageMaker AI Model Shadow Deployments 建立長時間執行的陰影變體，以驗證模型服務堆疊的任何新候選元件，然後再將其提升至生產環境。下圖顯示更詳細的陰影收體運作情形。

![\[陰影變體的詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/juxtaposer/shadow-variant.png)


## 部署陰影變體


 下列程式碼範例示範如何以程式設計方式部署陰影變體。請將範例中的*使用者預留位置文字*取代為您自己的資訊。

1.  建立兩個 SageMaker AI 模型：一個用於生產變體，另一個用於陰影變體。

   ```
   import boto3
   from sagemaker import get_execution_role, Session
                   
   aws_region = "aws-region"
   
   boto_session = boto3.Session(region_name=aws_region)
   sagemaker_client = boto_session.client("sagemaker")
   
   role = get_execution_role()
   
   bucket = Session(boto_session).default_bucket()
   
   model_name1 = "name-of-your-first-model"
   model_name2 = "name-of-your-second-model"
   
   sagemaker_client.create_model(
       ModelName = model_name1,
       ExecutionRoleArn = role,
       Containers=[
           {
               "Image": "ecr-image-uri-for-first-model",
               "ModelDataUrl": "s3-location-of-trained-first-model" 
           }
       ]
   )
   
   sagemaker_client.create_model(
       ModelName = model_name2,
       ExecutionRoleArn = role,
       Containers=[
           {
               "Image": "ecr-image-uri-for-second-model",
               "ModelDataUrl": "s3-location-of-trained-second-model" 
           }
       ]
   )
   ```

1.  建立端點組態。在組態中指定生產和陰影變體。

   ```
   endpoint_config_name = name-of-your-endpoint-config
   
   create_endpoint_config_response = sagemaker_client.create_endpoint_config(
       EndpointConfigName=endpoint_config_name,
       ProductionVariants=[
           {
               "VariantName": name-of-your-production-variant,
               "ModelName": model_name1,
               "InstanceType": "ml.m5.xlarge",
               "InitialInstanceCount": 1,
               "InitialVariantWeight": 1,
           }
       ],
       ShadowProductionVariants=[
           {
               "VariantName": name-of-your-shadow-variant,
               "ModelName": model_name2,
               "InstanceType": "ml.m5.xlarge",
               "InitialInstanceCount": 1,
               "InitialVariantWeight": 1,
           }
      ]
   )
   ```

1. 建立端點。

   ```
   create_endpoint_response = sm.create_endpoint(
       EndpointName=name-of-your-endpoint,
       EndpointConfigName=endpoint_config_name,
   )
   ```

# SageMaker Clarify 線上可解釋性
線上解釋性

本指南說明如何使用 SageMaker Clarify 設定線上可解釋性。透過 SageMaker AI [即時推斷](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html)端點，您可以持續、即時分析可解釋性。線上可解釋性功能適用於 [Amazon SageMaker AI Machine Learning 工作流程](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-mlconcepts.html)的**部署到生產**部分。

## Clarify 線上可解釋性如何運作
運作方式

下圖描述了用於託管服務可解釋性請求的端點的 SageMaker AI 架構。它描述了端點、模型容器及 SageMaker Clarify 解釋器之間的互動。

![\[SageMaker AI 架構，展示了用於託管服務隨需可解釋性請求的端點。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/clarify/DeveloperGuideArchitecture.png)


以下是 Clarify 線上可解釋性的工作原理。應用程式會將 REST 樣式的 `InvokeEndpoint` 請求傳送至 SageMaker AI 執行期服務。服務會將此請求路由至 SageMaker AI 端點，以取得預測與解釋。接著，服務接收來自端點的回應。最後，服務將回應傳回應用程式。

為了提高端點可用性，SageMaker AI 會根據端點組態的執行個體計數，自動嘗試在多個可用區域分發端點執行個體。在端點執行個體，根據新的可解釋性請求，SageMaker Clarify 解釋器會呼叫模型容器以進行預測。然後它會計算並傳回特徵屬性。

以下是建立使用 SageMaker Clarify 線上可解釋性端點的四個步驟：

1. 請依照[預先檢查](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html)步驟檢查您的預先訓練 SageMaker AI 模型是否與線上可解釋性相容。

1. 使用 `CreateEndpointConfig` API 透過 SageMaker Clarify 解釋器組態[建立端點組態](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html)。

1. [建立端點](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)並使用 `CreateEndpoint` API 將端點組態提供給 SageMaker AI。此服務會啟動組態所指定的機器學習運算執行個體，接著進行模型部署。

1. [調用端點](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)：端點投入使用後，呼叫 SageMaker AI 執行時間 API `InvokeEndpoint` 將請求傳送至端點。然後，端點回傳解釋及預測。

# 預先檢查模型容器


本節說明如何在設定端點之前預先檢查模型容器輸入及輸出的相容性。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)測試端點。

# 設定及建立端點
設定及建立端點

建立適合您模型的新端點組態，並使用此組態建立端點。您可以使用在[預先檢查步驟](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html)驗證的模型容器來建立端點，並啟用 SageMaker Clarify 線上可解釋性特徵。

使用 `sagemaker_client` 物件透過 [CreateEndpointConfig](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateEndpointConfig.html) API 建立端點。在 `ExplainerConfig` 參數設定成員 `ClarifyExplainerConfig`，如下所示：

```
sagemaker_client.create_endpoint_config(
    EndpointConfigName='name-of-your-endpoint-config',
    ExplainerConfig={
        'ClarifyExplainerConfig': {
            'EnableExplanations': '`true`',
            'InferenceConfig': {
                ...
            },
            'ShapConfig': {
                ...
            }
        },
    },
    ProductionVariants=[{
        'VariantName': 'AllTraffic',
        'ModelName': 'name-of-your-model',
        'InitialInstanceCount': 1,
        'InstanceType': 'ml.m5.xlarge',
    }]
     ...
)
sagemaker_client.create_endpoint(
    EndpointName='name-of-your-endpoint',
    EndpointConfigName='name-of-your-endpoint-config'
)
```

對 `sagemaker_client` 物件的第一次呼叫會建立一個新的端點組態，並啟用可解釋性特徵。第二個呼叫會使用端點組態來啟動端點。

**注意**  
您也可以在 [SageMaker AI 即時推斷多模型端點後面的一個容器託管多個模型](https://docs.aws.amazon.com/sagemaker/latest/dg/multi-model-endpoints.html)，並使用 SageMaker Clarify 設定線上可解釋性。

# `EnableExplanations` 運算式


`EnableExplanations` 參數為[https://jmespath.org/](https://jmespath.org/)布林值運算式字串。它針對可解釋性請求的**每筆記錄**進行評估。如果此參數被評估為 **true**，則記錄將被解釋。如果此參數被評估為 **false**，則不會產生解釋。

SageMaker Clarify 會將每筆記錄的模型容器輸出還原序列化為 JSON 相容資料結構，然後使用 `EnableExplanations` 參數來評估資料。

**備註**  
根據模型容器輸出的格式，記錄有兩個選項。  
如果模型容器輸出為 CSV 格式，則會將記錄載入為 JSON 陣列。
如果模型容器輸出為 JSON Lines 格式，則會將記錄載入為 JSON 物件。

`EnableExplanations` 參數是可以在 `InvokeEndpoint` 或 `CreateEndpointConfig` 作業期間傳遞的 JMESPath 運算式。如果您提供的 JMESPath 運算式無效，則端點建立將會失敗。如果運算式有效，但運算式評估結果未預期，則會成功建立端點，但在調用端點時會產生錯誤。使用 `InvokeEndpoint` API 測試 `EnableExplanations` 運算式，然後將其套用至端點組態。

以下是有效 `EnableExplanations` 運算式的一些範例。在這些範例中，JMESPath 運算式會使用反引號字元將常值括起來。例如，``true`` 表示 true。


| 運算式 (字串表示) | 模型容器輸出 (字串表示) | 評估結果 (布林值) | 意義 | 
| --- | --- | --- | --- | 
|  '`true`'  |  (N/A)  |  True  |  無條件啟動線上可解釋性。  | 
|  '`false`'  |  (N/A)  |  False  |  無條件停用線上可解釋性。  | 
|  '[1]>`0.5`'  |  '1,0.6'  |  True  |  對於每筆記錄，模型容器輸出其預測的標籤和機率。如果記錄的機率 (索引 1) 大於 0.5，則解釋該記錄。  | 
|  '機率 >`0.5`'  |  '\$1"predicted\$1label":1,"probability":0.6\$1'  |  True  |  對於每筆記錄，模型容器都會輸出 JSON 資料。如果一筆記錄的機率大於 0.5，則對其進行解釋。  | 
|  '\$1contains(probabilities[:-1], max(probabilities))'  |  '\$1"probabilities": [0.4, 0.1, 0.4], "labels":["cat","dog","fish"]\$1'  |  False  |  對於多類別模型：如果記錄的預測標籤 (具有最大機率值的類別) 是最後一個類別，則解釋該記錄。從字面上看，該運算式意味著最大機率值不在機率清單中 (除了最後一個)。  | 

# 綜合資料集


SageMaker Clarify 使用核心 SHAP 演算法。指定一筆記錄 (也稱為範例或執行個體) 及 SHAP 組態，解釋器首先產生一個合成資料集。然後，SageMaker Clarify 查詢模型容器以取得資料集的預測，然後計算並傳回特徵屬性。綜合資料集的大小會影響 Clarify 解釋器的執行期。較大的綜合資料集比較小的資料集需要更多時間來取得模型預測。

 合成資料集大小是由下列公式所決定：

```
Synthetic dataset size = SHAP baseline size * n_samples
```

SHAP 基準大小是 SHAP 基準資料中的記錄數。此資訊取自 `ShapBaselineConfig`。

`n_samples` 的大小是由解釋器組態的參數 `NumberOfSamples` 及特徵的數量所設定。如果特徵的數量為 `n_features`，則 `n_samples` 如下所示：

```
n_samples = MIN(NumberOfSamples, 2^n_features - 2)
```

如果未提供 `NumberOfSamples`，則以下顯示 `n_samples`。

```
n_samples = MIN(2*n_features + 2^11, 2^n_features - 2)
```

例如，具有 10 個特徵的表格記錄的 SHAP 基準大小為 1。如果未提供 `NumberOfSamples`，則綜合資料集包含 1022 筆記錄。如果記錄具有 20 個特徵，則合成資料集包含 2088 筆記錄。

對於 NLP 問題，`n_features` 等於非文字特徵的數量加上文字單位的數量。

**注意**  
`InvokeEndpoint` API 有請求逾時限制。如果綜合資料集太大，解釋器可能無法在此限制內完成計算。如有必要，請使用先前的資訊來瞭解並減少 SHAP 基準大小及 `NumberOfSamples`。如果您的模型容器設定為處理批次請求，您也可以調整 `MaxRecordCount` 的值。

# 調用端點


端點執行後，請使用 SageMaker AI 執行期服務的 SageMaker AI 執行期 [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) API 向端點傳送請求或調用端點。作為回應，SageMaker Clarify 解釋器會將這些要請求為無法解釋的請求進行處理。

**注意**  
若要調用端點，請選擇下列其中一種選項：  
如需使用 Boto3 或 AWS CLI 叫用端點的指示，請參閱 [調用模型以進行即時推論](realtime-endpoints-test-endpoints.md)。
若要使用適用於 Python 的 SageMaker SDK 調用端點，請參閱 [Predictor](https://sagemaker.readthedocs.io/en/stable/api/inference/predictors.html) API。

## 請求


`InvokeEndpoint` API 有一個可選參數 `EnableExplanations`，該參數會對應到 HTTP 標題 `X-Amzn-SageMaker-Enable-Explanations`。如果提供此參數，它會覆寫 `ClarifyExplainerConfig` 的 `EnableExplanations` 參數。

**注意**  
`InvokeEndpoint` API 的 `ContentType` 及 `Accept` 參數為必要項目。支援的格式包括 MIME 類型 `text/csv` 及 `application/jsonlines`。

使用 `sagemaker_runtime_client` 將請求傳送至端點，如下所示：

```
response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName='name-of-your-endpoint',
    EnableExplanations='`true`',
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',  # single record (of four numerical features)
)
```

對於多模型端點，請在上一個範例請求傳遞其他 `TargetModel` 參數，以指定端點的目標模型。多模型端點會視需要動態載入目標模型。如需多模型端點的詳細資訊，請參閱[多模型端點](multi-model-endpoints.md)。如需如何從單一端點設定及調用多個目標模型的範例，請參閱 [SageMaker Clarify 多模型端點範例筆記本的線上可解釋性](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular_multi_model_endpoint/multi_model_xgboost_with_online_explainability.ipynb)。

## 回應


如果使用 `ExplainerConfig` 建立端點，則會使用新的回應結構描述，此新架構與缺少提供的 `ExplainerConfig` 參數的端點不同且不相容。

回應的 MIME 類型為 `application/json`，回應承載可以從 UTF-8 位元組解碼為 JSON 物件。下面顯示了這個 JSON 物件的成員如下：
+ `version`：以字串格式顯示的回應結構描述版本。例如 `1.0`。
+ `predictions`：請求做出的預測如下：
  + `content_type`：預測的 MIME 類型，指的是模型容器回應的 `ContentType`。
  + `data`：作為請求的模型容器回應承載傳遞的預測資料字串。
+ `label_headers`：來自 `LabelHeaders` 參數的標籤標題。這在解釋器組態或模型容器輸出所提供。
+ `explanations`：請求承載提供的解釋。如果沒有解釋任何記錄，則該成員傳回空物件 `{}`。
+ 
  + `kernel_shap`：指請求中每筆記錄的核心 SHAP 解釋陣列的索引鍵。如果沒有解釋記錄，則相應的解釋為 `null`。

`kernel_shap` 元素具有下列成員：
+ `feature_header`：解釋器組態 `ExplainerConfig` 中 `FeatureHeaders` 參數提供的特徵的標題名稱。
+ `feature_type`：由解釋器推斷或在 `ExplainerConfig` 中的 `FeatureTypes` 參數提供的特徵類型。此元素僅適用於 NLP 可解釋性問題。
+ `attributions`：屬性物件的陣列。文字特徵可以有多個屬性物件，每個屬性物件對應一個單位。屬性物件具有下列成員：
  + `attribution`：為每個類別提供的機率值清單。
  + `description`：文字單位的描述，僅適用於 NLP 可解釋性問題。
    + `partial_text`：解釋者解釋的文字部分。
    + `start_idx`：從零開始的索引，用於標識部分文字片段開頭的陣列位置。

# 程式碼範例：Python 的 SDK


本節提供範例程式碼，以建立及調用使用 SageMaker Clarify 線上可解釋性的端點。這些程式碼範例使用[適用於 Python 的AWS SDK。](https://aws.amazon.com/sdk-for-python/)

## 表格式資料


下列範例使用表格式資料及稱為 `model_name` 的 SageMaker AI 模型。在此範例中，模型容器接受 CSV 格式的資料，每筆記錄都有四個數字特徵。在此最小組態中，**僅用於示範目的**，SHAP 基準資料設定為零。請參閱[用於可解釋性的 SHAP 基準](clarify-feature-attribute-shap-baselines.md)以了解如何為`ShapBaseline`選擇更適當的值。

設定端點，如下所示：

```
endpoint_config_name = 'tabular_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
    EndpointConfigName=endpoint_config_name,
    ProductionVariants=[{
        'VariantName': 'AllTraffic',
        'ModelName': model_name,
        'InitialInstanceCount': 1,
        'InstanceType': 'ml.m5.xlarge',
    }],
    ExplainerConfig={
        'ClarifyExplainerConfig': {
            'ShapConfig': {
                'ShapBaselineConfig': {
                    'ShapBaseline': '0,0,0,0',
                },
            },
        },
    },
)
```

使用端點組態建立端點，如下所示：

```
endpoint_name = 'tabular_explainer_endpoint'
response = sagemaker_client.create_endpoint(
    EndpointName=endpoint_name,
    EndpointConfigName=endpoint_config_name,
)
```

使用 `DescribeEndpoint` API 來檢查建立端點的進度，如下所示：

```
response = sagemaker_client.describe_endpoint(
    EndpointName=endpoint_name,
)
response['EndpointStatus']
```

端點狀態為 “”InService” 之後，請使用測試記錄調用端點，如下所示：

```
response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',
)
```

**注意**  
在先前的程式碼範例中，對於多模型端點，請在請求中傳遞其他 `TargetModel` 參數，以指定端點的目標模型。

假設回應的狀態碼為 200 (無錯誤)，並載入回應主體，如下所示：

```
import codecs
import json
json.load(codecs.getreader('utf-8')(response['Body']))
```

端點的預設動作是解釋記錄。以下顯示傳回的 JSON 物件中的範例輸出。

```
{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv; charset=utf-8",
        "data": "0.0006380207487381"
    },
    "explanations": {
        "kernel_shap": [
            [
                {
                    "attributions": [
                        {
                            "attribution": [-0.00433456]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [-0.005369821]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [0.007917749]
                        }
                    ]
                },
                {
                    "attributions": [
                        {
                            "attribution": [-0.00261214]
                        }
                    ]
                }
            ]
        ]
    }
}
```

使用 `EnableExplanations` 參數來啟用隨選解釋，如下所示：

```
response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='1,2,3,4',
    EnableExplanations='[0]>`0.8`',
)
```

**注意**  
在先前的程式碼範例中，對於多模型端點，請在請求中傳遞其他 `TargetModel` 參數，以指定端點的目標模型。

在此範例中，預測值小於 `0.8` 的臨界值，因此不解釋該記錄：

```
{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv; charset=utf-8",
        "data": "0.6380207487381995"
    },
    "explanations": {}
}
```

使用視覺化工具來協助解譯傳回的解釋。下列影像顯示如何使用 SHAP 圖來瞭解每個特徵對預測做出的貢獻。圖表上的基礎值，也稱為預期值，是訓練資料集的平均預測。使期望值升高的特徵為紅色，使期望值降低的特徵為藍色。如需其他資訊，請參閱 [SHAP 附加力配置](https://shap.readthedocs.io/en/latest/generated/shap.plots.force.html)。

![\[範例 SHAP 圖，可用來了解每個功能對預測的貢獻。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/clarify/force-plot.png)


如需表格式資料，請參閱[完整範例筆記本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular/tabular_online_explainability_with_sagemaker_clarify.ipynb)。

## 文字資料


本節提供一個程式碼範例，用於建立及調用文字資料的線上可解釋性端點。此程式碼範例使用適用於 Python 的 SDK。

下列範例使用文字資料及名為 `model_name` 的 SageMaker AI 模型。在此範例中，模型容器會接受 CSV 格式的資料，而且每筆記錄都是單一字串。

```
endpoint_config_name = 'text_explainer_endpoint_config'
response = sagemaker_client.create_endpoint_config(
    EndpointConfigName=endpoint_config_name,
    ProductionVariants=[{
        'VariantName': 'AllTraffic',
        'ModelName': model_name,
        'InitialInstanceCount': 1,
        'InstanceType': 'ml.m5.xlarge',
    }],
    ExplainerConfig={
        'ClarifyExplainerConfig': {
            'InferenceConfig': {
                'FeatureTypes': ['text'],
                'MaxRecordCount': 100,
            },
            'ShapConfig': {
                'ShapBaselineConfig': {
                    'ShapBaseline': '"<MASK>"',
                },
                'TextConfig': {
                    'Granularity': 'token',
                    'Language': 'en',
                },
                'NumberOfSamples': 100,
            },
        },
    },
)
```
+ `ShapBaseline`：保留用於自然語言處理 (NLP) 處理的特殊記號。
+ `FeatureTypes`：將特徵識別為文字。如果未提供此參數，解釋器將嘗試推斷特徵類型。
+ `TextConfig`：指定文字特徵分析的細微性及語言單位。在此範例中，語言為英文，而細微性 `token` 表示英文文字中的單字。
+ `NumberOfSamples`：設置綜合資料集大小上限的限制。
+ `MaxRecordCount`：模型容器可以處理的請求中記錄的最大數目。設定此參數是為了穩定效能。

使用端點組態建立端點，如下所示：

```
endpoint_name = 'text_explainer_endpoint'
response = sagemaker_client.create_endpoint(
    EndpointName=endpoint_name,
    EndpointConfigName=endpoint_config_name,
)
```

端點狀態變為 `InService` 後，調用端點。下列程式碼範例使用測試記錄，如下所示：

```
response = sagemaker_runtime_client.invoke_endpoint(
    EndpointName=endpoint_name,
    ContentType='text/csv',
    Accept='text/csv',
    Body='"This is a good product"',
)
```

如果請求成功完成，則回應主體將返回類似以下內容的有效 JSON 物件：

```
{
    "version": "1.0",
    "predictions": {
        "content_type": "text/csv",
        "data": "0.9766594\n"
    },
    "explanations": {
        "kernel_shap": [
            [
                {
                    "attributions": [
                        {
                            "attribution": [
                                -0.007270948666666712
                            ],
                            "description": {
                                "partial_text": "This",
                                "start_idx": 0
                            }
                        },
                        {
                            "attribution": [
                                -0.018199033666666628
                            ],
                            "description": {
                                "partial_text": "is",
                                "start_idx": 5
                            }
                        },
                        {
                            "attribution": [
                                0.01970993241666666
                            ],
                            "description": {
                                "partial_text": "a",
                                "start_idx": 8
                            }
                        },
                        {
                            "attribution": [
                                0.1253469515833334
                            ],
                            "description": {
                                "partial_text": "good",
                                "start_idx": 10
                            }
                        },
                        {
                            "attribution": [
                                0.03291143366666657
                            ],
                            "description": {
                                "partial_text": "product",
                                "start_idx": 15
                            }
                        }
                    ],
                    "feature_type": "text"
                }
            ]
        ]
    }
}
```

使用視覺化工具幫助解釋傳回的文字屬性。下列影像顯示如何使用 captum 視覺化公用程式來瞭解每個單字對預測的貢獻。色彩飽和度越高，此單字的重要性越高。在此範例中，高度飽和的亮紅色表示強烈的負面貢獻。高度飽和的綠色表示強烈的正面貢獻。白色表示該單字具有中性的貢獻。如需有關解析及轉譯屬性的其他資訊，請參閱 [captum](https://github.com/pytorch/captum) 程式庫。

![\[Captum 視覺化公用程式用於瞭解每個單字如何對預測做出貢獻。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/clarify/word-importance.png)


如需文字資料，請參閱[完整範例筆記本](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/natural_language_processing/nlp_online_explainability_with_sagemaker_clarify.ipynb)。

# 故障診斷指南


如果您在使用 SageMaker Clarify 線上可解釋性功能時遇到錯誤，請參閱本節的主題。

**`InvokeEndpoint` API 失敗，並顯示錯誤 “ReadTimeoutError:Read timeout on endpoint (端點讀取逾時)…”** 

此錯誤表示無法在[請求逾時](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)設定的 60 秒時間限制內完成請求。

若要減少請求延遲，請嘗試以下操作：
+ 在推斷期間調整模型的效能。例如，SageMaker AI [Neo](https://aws.amazon.com/sagemaker/neo/) 可以針對推斷進行最佳化模型。
+ 允許模型容器處理批次請求。
+ 使用較大的 `MaxRecordCount` 來減少從解釋器到模型容器的呼叫次數。這將減少網路延遲和開銷。
+ 使用已配置更多資源的執行個體類型。或者，將更多執行個體指派給端點，以協助平衡負載。
+ 減少單一 `InvokeEndpoint` 請求內的記錄數量。
+ 減少基準資料中的記錄數量。
+ 使用較小的 `NumberOfSamples` 值來減少合成資料集的大小。如需樣本數量如何影響您的合成資料集的詳細資訊，請參閱[綜合資料集](clarify-online-explainability-create-endpoint-synthetic.md)。

# 使用轉接器推論元件微調模型
使用轉接器微調

使用 Amazon SageMaker AI，您可以託管預先訓練的基礎模型，而無需從頭開始建立自己的模型。不過，若要針對業務的獨特需求量身打造一般用途的基礎模型，您必須建立經過微調的版本。低秩適應 (LoRA) 是具成本效益的微調技術之一。LoRA 的原理是，只需更新大型基礎模型的一小部分，就能使模型適應新的任務或領域。LoRA 轉接器只需幾個額外的轉接器層，即可增強基本基礎模型的推論。

如果您使用 SageMaker AI 推論元件託管基本基礎模型，您可以透過建立*轉接器推論元件*來使用 LoRA 轉接器微調該基本模型。當您建立轉接器推論元件時，可以指定下列項目：
+ 要包含轉接器推論元件的*基本推論元件*。基本推論元件包含您想要調整的基礎模型。轉接器推論元件會使用您指派給基本推論元件的運算資源。
+ 您已在 Amazon S3 中存放 LoRA 轉接器的位置。

建立轉接器推論元件之後，您可以直接調用它。當您這麼做時，SageMaker AI 會將轉接器與基本模型結合，以增強產生的回應。

**開始之前**

您必須先符合下列需求，才能建立轉接器推論元件：
+ 您有一個基本推論元件，其中包含要調整的基礎模型。您已將此推論元件部署至 SageMaker AI 端點。

  如需將推論元件部署至端點的詳細資訊，請參閱[部署用於即時推論的模型](realtime-endpoints-deploy-models.md)。
+ 您有 LoRA 轉接器模型，而且已將模型成品儲存為 Amazon S3 中的 `tar.gz` 檔案。您可以在建立轉接器推論元件時指定成品的 S3 URI。

下列範例使用 SDK for Python (Boto3) 來建立和調用轉接器推論元件。

**Example `create_inference_component` 呼叫以建立轉接器推論元件**  
下列範例會建立轉接器推論元件，並指派給基本推論元件：  

```
sm_client.create_inference_component(
    InferenceComponentName = adapter_ic_name,
    EndpointName = endpoint_name,
    Specification={
        "BaseInferenceComponentName": base_inference_component_name,
        "Container": {
            "ArtifactUrl": adapter_s3_uri
        },
    },
)
```
當您在自己的程式碼中使用此範例時，請取代預留位置值，如下所示：  
+ *adapter\$1ic\$1name* – 轉接器推論元件的唯一名稱。
+ *endpoint\$1name* – 託管基本推論元件的端點名稱。
+ *base\$1inference\$1component\$1name* – 基本推論元件的名稱，其中包含要調整的基礎模型。
+ *adapter\$1s3\$1uri* – 會使用 LoRA 轉接器成品尋找 `tar.gz` 檔案的 S3 URI。
您可以使用與正常推論元件的程式碼類似的程式碼，來建立轉接器推論元件。差別在於，對於 `Specification` 參數，您會省略 `ComputeResourceRequirements` 金鑰。當您調用轉接器推論元件時，會由基本推論元件載入該元件。轉接器推論元件使用基本推論元件的運算資源。  
如需使用 SDK for Python (Boto3) 建立和部署推論元件的詳細資訊，請參閱[使用 Python SDK 部署模型](realtime-endpoints-deploy-models.md#deploy-models-python)。

建立轉接器推論元件之後，您可以在 `invoke_endpoint` 請求中指定其名稱來調用它。

**Example `invoke_endpoint` 呼叫以調用轉接器推論元件**  
下列範例會調用轉接器推論元件：  

```
response = sm_rt_client.invoke_endpoint(
    EndpointName = endpoint_name,
    InferenceComponentName = adapter_ic_name,
    Body = json.dumps(
        {
            "inputs": prompt,
            "parameters": {"max_new_tokens": 100, "temperature":0.9}
        }
    ),
    ContentType = "application/json",
)

adapter_reponse = response["Body"].read().decode("utf8")["generated_text"]
```
當您在自己的程式碼中使用此範例時，請取代預留位置值，如下所示：  
+ *endpoint\$1name* – 託管基本和轉接器推論元件的端點名稱。
+ *adapter\$1ic\$1name* – 轉接器推論元件的名稱。
+ *prompt* – 推論請求的提示。
如需使用 SDK for Python (Boto3) 調用推論元件的詳細資訊，請參閱[調用模型以進行即時推論](realtime-endpoints-test-endpoints.md)。