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

# HyperPod 上推論的資料擷取
<a name="sagemaker-hyperpod-model-deployment-data-capture"></a>

Amazon SageMaker HyperPod 推論資料擷取可讓您記錄推論請求和回應資料，以進行模型監控、偵錯和模型改進。推論請求會從 SageMaker AI 端點流向 Application Load Balancer，然後流向模型 Pod。您可以在每個層級獨立啟用擷取，從最外層 （第 1 層，SageMaker AI 端點） 到最深層 （第 3 層，模型 Pod)：


**資料擷取層**  

| Tier | 擷取點 | 擷取的內容 | Amazon S3 路徑 | 
| --- | --- | --- | --- | 
| 第 1 層 | SageMaker AI 端點 | 輸入和輸出承載、取樣、 AWS KMS 加密 | {s3Uri}/{hash}/sme/ | 
| 第 2 層 | Application Load Balancer | 存取日誌 （請求路徑、用戶端 IPs、延遲） | {s3Uri}/{hash}/alb/ | 
| 第 3 層 | 模型 Pod | 具有可設定取樣、緩衝和承載大小限制的推論輸入和輸出承載。當您提供金鑰時支援 AWS KMS 加密。擷取最接近模型的資料，以獲得最深層的可見性。 | {s3Uri}/{hash}/pod/ | 

第 1 層會在 SageMaker AI 執行期 API 界限擷取完整承載，且需要端點註冊。當您需要與 SageMaker AI Model Monitor 的相容性時，請使用第 1 層。第 3 層使用可設定的緩衝、取樣和承載限制擷取推論容器的完整承載，無需 SageMaker AI 端點註冊即可運作。當您需要最接近模型的深入可見性時，請使用第 3 層。啟用任意組合 — 每個層都會在請求流程中的不同點擷取。

所有層都會寫入您的 Amazon S3 儲存貯體。如果您未指定 `s3Uri`，資料預設會存放在 TLS 憑證儲存貯體的`/data-capture/`字首下。在儲存貯體中，每個部署都會根據衍生自叢集 ARN、命名空間、CRD 類型和部署名稱的雜湊取得唯一的路徑。相同的部署一律會產生相同的字首，因此資料擷取來自多個 CRD 提交的成品，以相同的部署流程為目標到相同的 Amazon S3 子資料夾。

若要停用層的資料擷取，請將其`enabled`欄位設定為 ，`false`或從 CRD 中移除層區段。若要停用所有資料擷取，請完全移除 `dataCapture`區段。

## 設定資料擷取
<a name="sagemaker-hyperpod-model-deployment-data-capture-config"></a>

透過將`dataCapture`區段新增至您的 `InferenceEndpointConfig`或 `JumpStartModel` CRD 來啟用資料擷取。`dataCapture` 區塊包含單一 `s3Uri`（選用） 和一或多個層組態。下列範例顯示啟用所有三個層的整體結構：

```
  dataCapture:
    s3Uri: s3://my-capture-bucket/captures/   # Optional. Defaults to TLS bucket.
    sagemakerEndpoint:
      enabled: true
      # Tier 1 fields...
    loadBalancer:
      enabled: true
    modelPod:
      enabled: true
      # Tier 3 fields...
```

`dataCapture.s3Uri` （選用，字串）  
存放擷取資料的 Amazon S3 URI。如果未指定，TLS 憑證儲存貯體會與`/data-capture/`字首搭配使用。長度上限：512 個字元。儲存貯體必須與叢集位於相同的帳戶中。

### 第 1 層：SageMaker AI 端點擷取
<a name="sagemaker-hyperpod-model-deployment-data-capture-tier1"></a>

第 1 層使用 SageMaker AI 的原生 `DataCaptureConfig`來擷取端點層級的推論輸入和輸出承載。這是最外部的擷取點，並與 SageMaker AI Model Monitor 相容，以進行自動化資料品質監控。如需 SageMaker AI 資料擷取的詳細資訊，請參閱[從即時端點擷取資料](https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor-data-capture.html)。

```
    sagemakerEndpoint:
      enabled: true
      initialSamplingPercentage: 100
      kmsKeyId: arn:aws:kms:us-east-2:123456789012:key/my-key-id
      captureOptions:
        - captureMode: Input
        - captureMode: Output
      captureContentTypeHeader:
        jsonContentTypes:
          - application/json
```

`sagemakerEndpoint.enabled` （必要，布林值）  
設定為 `true`以啟用第 1 層擷取。

`sagemakerEndpoint.initialSamplingPercentage` （選用，整數，0–100)  
要擷取的推論請求百分比。預設： `100` （擷取所有請求）。

`sagemakerEndpoint.captureOptions` （選用，列出）  
指定要擷取推論請求承載 (`Input`)、推論回應承載 (`Output`) 或兩者。每個項目都有一個`captureMode`欄位設定為 `Input`或 `Output`。預設：`[Input, Output]`（同時擷取請求和回應）。上限：32 個項目。

`sagemakerEndpoint.kmsKeyId` （選用，字串）  
用於加密靜態擷取資料的 AWS KMS 金鑰 ARN、金鑰 ID、別名名稱或別名 ARN。指定時，系統會使用此金鑰加密擷取的資料。省略時，會使用預設的 Amazon S3 儲存貯體加密設定來加密資料。長度上限：2048 個字元。

`sagemakerEndpoint.captureContentTypeHeader` (選用)  
指定如何解譯所擷取承載的內容類型。支援 `jsonContentTypes`和 `csvContentTypes`陣列。上限：每個 10 個項目。

### 第 2 層：負載平衡器擷取
<a name="sagemaker-hyperpod-model-deployment-data-capture-tier2"></a>

第 2 層啟用 ALB 存取日誌，擷取請求中繼資料，例如用戶端 IPs、請求路徑和延遲。

```
    loadBalancer:
      enabled: true
```

`loadBalancer.enabled` （必要，布林值）  
設定為 `true`以啟用第 2 層擷取。

**注意**  
ALB 存取日誌會擷取請求中繼資料，包括 URLs和查詢參數。使用 POST 請求內文，而不是查詢敏感輸入的參數。ALB 日誌不支援 AWS KMS 加密，且僅使用 Amazon S3 預設加密。

### 第 3 層：模型 Pod 擷取
<a name="sagemaker-hyperpod-model-deployment-data-capture-tier3"></a>

第 3 層擷取模型 Pod 層級的推論輸入和輸出承載，提供最深入的推論流量可見性。當您需要精細控制緩衝、承載大小限制，以及擷取最接近模型時，請使用此層。

```
    modelPod:
      enabled: true
      initialSamplingPercentage: 100
      kmsKeyId: arn:aws:kms:us-east-2:123456789012:key/my-key-id
      captureOptions:
        - captureMode: Input
        - captureMode: Output
      bufferConfig:
        batchSize: 100
        flushIntervalSeconds: 60
      payloadConfig:
        maxPayloadSizeKB: 1024
```

`modelPod.enabled` （必要，布林值）  
設定為 `true`以啟用第 3 層擷取。

`modelPod.initialSamplingPercentage` （選用，整數，0–100)  
要擷取的推論請求百分比。預設： `100` （擷取所有請求）。

`modelPod.captureOptions` （選用，列出）  
指定要擷取推論請求承載 (`Input`)、推論回應承載 (`Output`) 或兩者。每個項目都有一個`captureMode`欄位設定為 `Input`或 `Output`。預設：`[Input, Output]`（同時擷取請求和回應）。上限：32 個項目。

`modelPod.kmsKeyId` （選用，字串）  
用於加密靜態擷取資料的 AWS KMS 金鑰 ARN、金鑰 ID、別名名稱或別名 ARN。指定時，系統會使用此金鑰加密擷取的資料。省略時，系統會使用預設的 Amazon S3 儲存貯體加密設定來加密資料。長度上限：2048 個字元。

`modelPod.bufferConfig.batchSize` （選用，整數，1–1000)  
排清前要批次處理的推論請求數量。預設：`10`。

`modelPod.bufferConfig.flushIntervalSeconds` （選用，整數，10–300)  
批次在排清之前保留的秒數上限，無論是否已達到批次大小。預設：`60`。

`modelPod.payloadConfig.maxPayloadSizeKB` (選用，整數)  
每個請求的承載大小上限，以 KB 為單位。超過此限制的承載會被截斷。如果未設定，則會擷取整個承載。

## 更新附加元件
<a name="sagemaker-hyperpod-model-deployment-update-addon"></a>

**先決條件：驗證並連線至您的 EKS 叢集**

向 AWS 您的帳戶進行身分驗證。在連線之前，請收集 EKS 叢集名稱、區域和 HyperPod 叢集 ARN：

```
CLUSTER={{EKS_CLUSTER_NAME}}
REGION={{REGION}}
HP_ARN={{HYPERPOD_CLUSTER_ARN}}
```

連線至您的 EKS 叢集：

```
aws eks update-kubeconfig --region {{REGION}} --name {{EKS_CLUSTER_NAME}}
```

更新附加元件組態：

```
VERSION=$(aws eks describe-addon --cluster-name $CLUSTER --addon-name amazon-sagemaker-hyperpod-inference --region $REGION --query 'addon.addonVersion' --output text)
CURRENT_CONFIG=$(aws eks describe-addon --cluster-name $CLUSTER --addon-name amazon-sagemaker-hyperpod-inference --region $REGION --query 'addon.configurationValues' --output text)
NEW_CONFIG=$(echo "$CURRENT_CONFIG" | jq --arg arn "$HP_ARN" '. + {hyperpodClusterArn: $arn}')

aws eks update-addon \
--cluster-name $CLUSTER \
--addon-name amazon-sagemaker-hyperpod-inference \
--addon-version "$VERSION" \
--configuration-values "$NEW_CONFIG" \
--resolve-conflicts OVERWRITE \
--region $REGION
```

**等待附加元件處於作用中狀態，然後部署模型**

## 更新現有叢集的許可
<a name="sagemaker-hyperpod-model-deployment-data-capture-iam"></a>

若要在 HyperPod 推論部署上啟用資料擷取，請設定下列 IAM 許可。

1. **推論運算子執行角色**

   新增下列 S3 許可：

   ```
   {
       "Sid": "DataCaptureS3Access",
       "Effect": "Allow",
       "Action": "s3:PutObject",
       "Resource": "arn:aws:s3:::hyperpod-tls*/data-capture/*",
       "Condition": {
           "StringEquals": {
               "aws:ResourceAccount": "${aws:PrincipalAccount}"
           }
       }
   }
   ```

   如果您想要使用自訂 S3 儲存貯體，請新增儲存貯體名稱。

   如果您使用客戶管理的 KMS 金鑰，也請新增：

   ```
   {
       "Sid": "DataCaptureKmsAccess",
       "Effect": "Allow",
       "Action": [
           "kms:Decrypt",
           "kms:GenerateDataKey"
       ],
       "Resource": "arn:aws:kms:*:*:key/*",
       "Condition": {
           "StringLike": {
               "kms:ViaService": "s3.*.amazonaws.com",
               "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::hyperpod-tls*"
           },
           "StringEquals": {
               "aws:ResourceAccount": "${aws:PrincipalAccount}"
           }
       }
   }
   ```

1. **S3 CSI 驅動程式角色**

   新增下列 S3 許可：

   ```
   {
       "Sid": "DataCaptureWriteAccess",
       "Effect": "Allow",
       "Action": [
           "s3:PutObject",
           "s3:AbortMultipartUpload"
       ],
       "Resource": "arn:aws:s3:::hyperpod-tls*/data-capture/*",
       "Condition": {
           "StringEquals": {
               "aws:ResourceAccount": "${aws:PrincipalAccount}"
           }
       }
   }
   ```

   如果您使用客戶管理的 KMS 金鑰，也請新增：

   ```
   {
       "Sid": "DataCaptureKmsAccess",
       "Effect": "Allow",
       "Action": [
           "kms:Decrypt",
           "kms:GenerateDataKey",
           "kms:DescribeKey"
       ],
       "Resource": "arn:aws:kms:*:*:key/*",
       "Condition": {
           "StringLike": {
               "kms:ViaService": "s3.*.amazonaws.com"
           },
           "StringEquals": {
               "aws:ResourceAccount": "${aws:PrincipalAccount}"
           }
       }
   }
   ```

1. **S3 儲存貯體政策**

   只有在您啟用負載平衡器資料擷取 （第 2 層） 以允許 ALB 寫入存取日誌時，才新增此儲存貯體政策。將 取代`$ACCOUNT_ID`為 AWS 您的帳戶 ID。

   ```
   {
       "Sid": "AllowALBAccessLogDelivery",
       "Effect": "Allow",
       "Principal": {
           "Service": "logdelivery.elasticloadbalancing.amazonaws.com"
       },
       "Action": "s3:PutObject",
       "Resource": "arn:aws:s3:::hyperpod-tls*/data-capture/*",
       "Condition": {
           "StringEquals": {
               "aws:SourceAccount": "$ACCOUNT_ID"
           }
       }
   }
   ```

## 最佳實務
<a name="sagemaker-hyperpod-model-deployment-data-capture-perf"></a>
+ 使用 `initialSamplingPercentage` 控制擷取的資料量。從生產中較低的百分比開始，並視需要增加。
+ 使用 `payloadConfig.maxPayloadSizeKB`（第 3 層） 來限制擷取承載的大小，並控制儲存成本。
+ 如果您的工作負載需要使用您自己的 AWS KMS 金鑰進行靜態加密，`kmsKeyId`請為第 1 層和第 3 層指定 。