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

# 在 HyperPod 叢集上實作推論可觀測性
<a name="sagemaker-hyperpod-model-deployment-observability"></a>

Amazon SageMaker HyperPod 提供全面的推論可觀測性功能，可讓資料科學家和機器學習工程師監控和最佳化其部署的模型。此解決方案透過 SageMaker HyperPod 可觀測性啟用，並自動收集推論工作負載的效能指標，從而透過整合的 [Prometheus](https://prometheus.io/) 和 [Grafana](https://grafana.com/oss/) 儀表板提供生產備妥監控。

透過預設啟用的指標，平台會擷取必要的模型效能資料，包括調用延遲、並行請求、錯誤率和字符層級指標，同時為偏好實作自訂可觀測性解決方案的客戶提供標準 Prometheus 端點。

**注意**  
本主題會深入探討如何在 HyperPod 叢集上實作推論可觀測性。如需更一般的參考，請參閱[叢集和任務可觀測性](sagemaker-hyperpod-eks-cluster-observability-cluster.md)。

本指南提供在您的 HyperPod 叢集上實作和使用推論可觀測性的逐步指示。您將了解如何在部署 YAML 檔案中設定指標、根據您的角色 (管理員、資料科學家或機器學習工程師) 存取監控儀表板、使用 Prometheus 端點與自訂可觀測性解決方案整合，以及針對常見的監控問題進行疑難排解。

## 支援的推論指標
<a name="sagemaker-hyperpod-model-deployment-observability-metrics"></a>

**呼叫指標**

這些指標會擷取模型推論請求和回應資料，無論您的模型類型或服務架構為何，都會提供通用的可見性。推論指標啟用時，這些指標會在調用時計算，並匯出到您的監控基礎設施。
+ `model_invocations_total` - 對模型的調用請求總數 
+ `model_errors_total` - 模型調用期間的錯誤總數
+ `model_concurrent_requests` - 作用中並行模型請求
+ `model_latency_milliseconds` - 模型調用延遲，以毫秒為單位
+ `model_ttfb_milliseconds` - 第一個位元組延遲的模型時間，以毫秒為單位

**模型容器指標**

這些指標可讓您深入了解模型容器的內部操作，包括字符處理、佇列管理和架構特定的效能指標。可用的指標取決於您的模型服務架構：
+ [TGI 容器指標](https://huggingface.co/docs/text-generation-inference/en/reference/metrics) 
+ [LMI 容器指標](https://github.com/deepjavalibrary/djl-serving/blob/master/prometheus/README.md) 

**指標維度**

所有推論指標都包含全方位標籤，可在您的整個部署中啟用詳細篩選和分析：
+ **叢集身分：**
  + `cluster_id` - HyperPod 叢集的唯一 ID
  + `cluster_name` - HyperPod 叢集的名稱
+ **資源身分：**
  + `resource_name` - 部署名稱 (例如，"jumpstart-model-deployment")
  + `resource_type` - 部署類型 (jumpstart、inference-endpoint)
  + `namespace` - 適用於多租用戶的 Kubernetes 命名空間
+ **模型特性：**
  + `model_name` - 特定模型識別碼 (例如，"llama-2-7b-chat")
  + `model_version` - 用於 A/B 測試和復原的模型版本
  + `model_container_type` - 服務架構 (TGI、LMI、-)
+ **基礎設施內容：**
  + `pod_name` - 用於偵錯的個別 Pod 識別碼
  + `node_name` - 用於資源相互關聯的 Kubernetes 節點
  + `instance_type` - 用於成本分析的 EC2 執行個體類型
+ **操作內容：**
  + `metric_source` - 收集點 (reverse-proxy、model-container)
  + `task_type` - 工作負載分類 (推論)

## 在部署 YAML 中設定指標
<a name="sagemaker-hyperpod-model-deployment-observability-yaml"></a>

Amazon SageMaker HyperPod 預設會為所有模型部署啟用推論指標，提供立即可觀測性，無需額外設定。您可以修改部署 YAML 組態來自訂指標行為，以根據您的特定要求啟用或停用指標收集。

**從 JumpStart 部署模型**

使用下列 YAML 組態來部署已啟用指標的 JuJumpStartmpStart 模型：

```
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: JumpStartModel
metadata:
  name:mistral-model
  namespace: ns-team-a
spec:
  model:
    modelId: "huggingface-llm-mistral-7b-instruct"
    modelVersion: "3.19.0"
  metrics:
    enabled:true # Default: true (can be set to false to disable)
  replicas: 2
  sageMakerEndpoint:
    name: "mistral-model-sm-endpoint"
  server:
    instanceType: "ml.g5.12xlarge"
    executionRole: "arn:aws:iam::123456789:role/SagemakerRole"
  tlsConfig:
    tlsCertificateOutputS3Uri: s3://hyperpod/mistral-model/certs/
```

**從 Amazon S3 或 Amazon FSx 部署自訂和微調模型**

使用下列 YAML 搭配詳細指標設定來設定自訂推論端點：

```
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: JumpStartModel
metadata:
  name:mistral-model
  namespace: ns-team-a
spec:
  model:
    modelId: "huggingface-llm-mistral-7b-instruct"
    modelVersion: "3.19.0"
  metrics:
    enabled:true # Default: true (can be set to false to disable)
  replicas: 2
  sageMakerEndpoint:
    name: "mistral-model-sm-endpoint"
  server:
    instanceType: "ml.g5.12xlarge"
    executionRole: "arn:aws:iam::123456789:role/SagemakerRole"
  tlsConfig:
    tlsCertificateOutputS3Uri: s3://hyperpod/mistral-model/certs/

Deploy a custom inference endpoint

Configure custom inference endpoints with detailed metrics settings using the following YAML:

apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: inferenceendpoint-deepseeks
  namespace: ns-team-a
spec:
  modelName: deepseeks
  modelVersion: 1.0.1
  metrics:
    enabled: true # Default: true (can be set to false to disable)
    metricsScrapeIntervalSeconds: 30 # Optional: if overriding the default 15s
    modelMetricsConfig:
        port: 8000 # Optional: if overriding, it defaults to the WorkerConfig.ModelInvocationPort.ContainerPort within the InferenceEndpointConfig spec 8080
        path: "/custom-metrics" # Optional: if overriding the default "/metrics"
  endpointName: deepseek-sm-endpoint
  instanceType: ml.g5.12xlarge
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: model-weights
      region: us-west-2
    modelLocation: deepseek
    prefetchEnabled: true
  invocationEndpoint: invocations
  worker:
    resources:
      limits:
        nvidia.com/gpu: 1
      requests:
        nvidia.com/gpu: 1
        cpu: 25600m
        memory: 102Gi
    image: 763104351884.dkr.ecr.us-west-2.amazonaws.com/djl-inference:0.32.0-lmi14.0.0-cu124
    modelInvocationPort:
      containerPort: 8080
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    environmentVariables: ...
  tlsConfig:
    tlsCertificateOutputS3Uri: s3://hyperpod/inferenceendpoint-deepseeks4/certs/
```

**注意**  
若要停用特定部署的指標，請在您的 YAML 組態中設定 `metrics.enabled: false`。

## 依角色監控推論工作負載並針對其進行疑難排解
<a name="sagemaker-hyperpod-model-deployment-observability-role"></a>

Amazon SageMaker HyperPod 提供全面的可觀測性功能，其可支援從初始叢集設定到進階效能疑難排解的不同使用者工作流程。根據您的角色和監控要求，使用以下指引。

**HyperPod 管理員**

**您的責任：**啟用可觀測性基礎設施，並確保整個叢集的系統運作狀態。

**您需要知道的事項：**
+ 整個叢集的可觀測性會為所有工作負載提供基礎設施指標
+ 一鍵式設定會使用預先設定的儀表板部署監控堆疊
+ 基礎設施指標與模型特定的推論指標不同

**您需要執行的事項：**

1. 導覽至 HyperPod 主控台。

1. 選取您的叢集。

1. 前往您剛建立的 HyperPod 叢集詳細資訊頁面。您將看到安裝 HyperPod 可觀測性附加元件的新選項。

1. 按一下**快速安裝**選項。1-2 分鐘後，所有步驟都將完成，而且您將看到 Grafana 儀表板和 Prometheus 工作區詳細資訊。

此單一動作會自動部署 EKS 附加元件、設定可觀測性運算子，以及在 Grafana 中佈建預先建置的儀表板。

**資料科學家**

**您的責任：**有效率地部署模型並監控其基本效能。

**您需要知道的事項：**
+ 部署模型時會自動啟用指標
+ Grafana 儀表板提供模型效能的立即可見性
+ 您可以篩選儀表板以專注於您的特定部署

**您需要執行的事項：**

1. 使用您偏好的方法部署模型：

   1. Amazon SageMaker Studio UI

   1. HyperPod CLI 命令

   1. 筆記本中的 Python SDK

   1. kubectl 搭配 YAML 組態

1. 存取您的模型指標：

   1. 開啟 Amazon SageMaker Studio

   1. 導覽至 HyperPod 叢集並開啟 Grafana 儀表板

   1. 選取推論儀表板

   1. 套用篩選條件以檢視您的特定模型部署

1. 監控關鍵績效指標

   1. 追蹤模型延遲和輸送量

   1. 監控錯誤率和可用性

   1. 檢閱資源使用率趨勢

完成後，您將立即了解模型的效能，而無需進行額外的設定，從而能夠快速識別部署問題或效能變更。

**機器學習引擎 (MLE)**

**您的責任：**維持生產模型效能並解決複雜的效能問題。

**您需要知道的事項：**
+ 進階指標包括模型容器詳細資訊，例如佇列深度和字符指標
+ 跨多個指標類型的相互關聯分析會顯示根本原因
+ 自動擴展組態會直接影響流量突增期間的效能

**假設案例：**客戶的聊天模型會遇到間歇性慢速回應。使用者抱怨大約 5-10 秒的延遲。MLE 可以利用推論可觀測性進行系統效能調查。

**您需要執行的事項：**

1. 檢查 Grafana 儀表板以了解效能問題的範圍和嚴重性：

   1. 高延遲警示自 09:30 起生效

   1. P99 延遲：8.2 秒 (正常：2.1 秒)

   1. 受影響的時段：09:30-10:15 (45 分鐘)

1. 關聯多個指標，以了解事件期間的系統行為：

   1. 並行請求：突增至 45 (正常：15-20)

   1. Pod 擴展：KEDA 在事件期間擴展了 2→5 個 Pod

   1. GPU 使用率：保持正常 (85-90%)

   1. 記憶體用量：正常 (24GB/32GB)

1. 檢查分散式系統行為，因為基礎設施指標看起來正常：

   1. 節點層級檢視：所有 Pod 都集中在相同的節點上 (分佈情況不佳)

   1. 模型容器指標：TGI 佇列深度顯示 127 個請求 (正常：5-10 個)

   ```
   Available in Grafana dashboard under "Model Container Metrics" panel
           Metric: tgi_queue_size{resource_name="customer-chat-llama"}
           Current value: 127 requests queued (indicates backlog)
   ```

1. 識別互連組態問題：

   1. KEDA 擴展政策：太慢 (30 秒輪詢間隔)

   1. 擴展時間軸：擴展回應落後流量高峰 45 秒以上

1. 根據分析實作針對性修正：

   1. 更新的 KEDA 輪詢間隔：30 秒 → 15 秒

   1. 增加了擴展組態中的 maxReplicas

   1. 已調整擴展閾值來提早擴展 (15 個並行請求與 20 個並行請求)

您可以使用全方位指標有系統地診斷複雜的效能問題、實作針對性修正，並建立預防措施來維持一致的生產模型效能。

## 實作您自己的可觀測性整合
<a name="sagemaker-hyperpod-model-deployment-observability-diy"></a>

Amazon SageMaker HyperPod 透過業界標準的 Prometheus 端點公開推論指標，讓您可與現有的可觀測性基礎設施整合。當您偏好實作自訂監控解決方案，或與第三方可觀測性平台整合，而不是使用內建的 Grafana 和 Prometheus 堆疊時，請使用此方法。

**存取推論指標端點**

**您需要知道的事項：**
+ 推論指標會自動在標準化 Prometheus 端點上公開
+ 無論您的模型類型或服務架構為何，都可以使用指標
+ 標準 Prometheus 湊集實務適用於資料收集

**推論指標端點組態：**
+ **連接埠：**9113
+ **路徑：**/metrics
+ **完整端點：**http://pod-ip:9113/metrics

**可用的執行個體指標**
+ `model_invocations_total` - 對模型的調用請求總數
+ `model_errors_total` - 模型調用期間的錯誤總數
+ `model_concurrent_requests` - 每個模型的作用中並行請求
+ `model_latency_milliseconds` - 模型調用延遲，以毫秒為單位
+ `model_ttfb_milliseconds` - 第一個位元組延遲的模型時間，以毫秒為單位

**存取模型容器指標**

**您需要知道的事項：**
+ 模型容器公開其服務架構特有的其他指標
+ 這些指標提供內部容器洞見，例如字符處理和佇列深度
+ 端點組態因模型容器類型而異

**對於使用文字生成推論 (TGI) 容器的 JumpStart 模型部署：**
+ **連接埠：**8080 (模型容器連接埠)
+ **路徑：**/metrics
+ **文件：**[https://huggingface.co/docs/text-generation-inference/en/reference/metrics](https://huggingface.co/docs/text-generation-inference/en/reference/metrics)

**對於使用大型模型推論 (LMI) 容器的 JumpStart 模型部署：**
+ **連接埠：**8080 (模型容器連接埠)
+ **路徑：**/server/metrics
+ **文件：**[https://github.com/deepjavalibrary/djl-serving/blob/master/prometheus/README.md](https://github.com/deepjavalibrary/djl-serving/blob/master/prometheus/README.md)

**對於自訂推論端點 (BYOD)：**
+ **連接埠：**客戶設定的 (預設 8080。在 InferenceEndpointConfig 規格內預設為 WorkerConfig.ModelInvocationPort.ContainerPort)
+ **路徑：**客戶設定的 (預設 /metrics)

**實作自訂可觀測性整合**

透過自訂可觀測性整合，您負責：

1. **指標湊集：**從上述端點實作與 Prometheus 相容的湊集

1. **資料匯出：**設定匯出至您選擇的可觀測性平台

1. **警示：**根據您的操作要求設定警示規則

1. **儀表板：**為您的監控需求建立視覺化儀表板

## 針對推論可觀測性問題進行疑難排解
<a name="sagemaker-hyperpod-model-deployment-observability-troubleshoot"></a>

**儀表板未顯示任何資料**

如果 Grafana 儀表板是空的，且所有面板都顯示「無資料」，請執行下列步驟來調查：

1. 驗證管理員是否已安裝推論可觀測性：

   1. 導覽至 [HyperPod 主控台] > [選取叢集] > [檢查「可觀測性」狀態是否顯示「已啟用」]

   1. 驗證是否可從叢集概觀存取 Grafana 工作區連結

   1. 確認已設定 Amazon Managed Prometheus 工作區並正在接收資料

1. 驗證 HyperPod 可觀測性是否已啟用：

   ```
   hyp observability view      
   ```

1. 驗證模型指標是否已啟用：

   ```
   kubectl get jumpstartmodel -n <namespace> customer-chat-llama -o jsonpath='{.status.metricsStatus}' # Expected: enabled: true, state:Enabled       
   ```

   ```
   kubectl get jumpstartmodel -n <namespace> customer-chat-llama -o jsonpath='{.status.metricsStatus}' # Expected: enabled: true, state:Enabled        
   ```

1. 檢查指標端點：

   ```
   kubectl port-forward pod/customer-chat-llama-xxx 9113:9113
   curl localhost:9113/metrics | grep model_invocations_total# Expected: model_invocations_total{...} metrics
   ```

1. 檢查日誌：

   ```
   # Model Container
   kubectl logs customer-chat-llama-xxx -c customer-chat-llama# Look for: OOM errors, CUDA errors, model loading failures
   
   # Proxy/SideCar
   kubectl logs customer-chat-llama-xxx -c sidecar-reverse-proxy# Look for: DNS resolution issues, upstream connection failures
   
   # Metrics Exporter Sidecar
   kubectl logs customer-chat-llama-xxx -c otel-collector# Look for: Metrics collection issues, export failures
   ```

**其他常見問題**


| 問題 | 解決方案 | Action | 
| --- | --- | --- | 
|  未安裝推論可觀測性  |  透過主控台安裝推論可觀測性  |  在 HyperPod 主控台中「啟用可觀測性」  | 
|  已在模型中停用指標  |  更新模型組態  |  將 `metrics: {enabled: true}` 新增至模型規格  | 
|  未設定 AMP 工作區  |  修正資料來源連線  |  驗證 Grafana 資料來源中的 AMP 工作區 ID  | 
|  網路連線  |  檢查安全群組/NACL  |  確保 Pod 可以到達 AMP 端點  |