本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在集群上实现推理可观测性 HyperPod
<a name="sagemaker-hyperpod-model-deployment-observability"></a>

Amazon SageMaker HyperPod 提供全面的推理可观测性功能，使数据科学家和机器学习工程师能够监控和优化其部署的模型。[https://prometheus.io/](https://prometheus.io/)

利用默认启用的指标，该平台可以捕获关键模型性能数据，包括调用延迟、并发请求数、错误率和令牌级指标，同时为倾向于实施自定义可观测性解决方案的客户提供标准 Prometheus 端点。

**注意**  
本主题深入探讨如何在集群上实现推理可观测性。 HyperPod 有关更多一般参考信息，请参阅[集群和任务可观测性](sagemaker-hyperpod-eks-cluster-observability-cluster.md)。

本指南提供了在集群上实现和使用推理可观测性的 step-by-step说明。 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 或亚马逊部署经过微调的自定义模型 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. 亚马逊 SageMaker 工作室用户界面

   1. HyperPod CLI 命令

   1. 笔记本中的 Python SDK

   1. 带 YAML 配置的 kubectl

1. 访问模型指标：

   1. 打开亚马逊 SageMaker 工作室

   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 通过行业标准的 Prometheus 终端节点 SageMaker HyperPod 公开推理指标，从而实现与您现有的可观测性基础设施的集成。如果您倾向于实现自定义监控解决方案或与第三方可观测性平台集成，而不是使用内置的 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)

**对于使用大型 JumpStart 模型推理 (LMI) 容器的模型部署：**
+ **端口：**8080（模型容器端口）
+ **路径：**/server/metrics
+ **文档：https://github.com/deepjavalibrary/**[djl-.md serving/blob/master/prometheus/README](https://github.com/deepjavalibrary/djl-serving/blob/master/prometheus/README.md)

**对于自定义推理端点（BYOD）：**
+ **端口：**客户配置（默认为 8080）默认为。 WorkerConfig ModelInvocationPort。 ContainerPort 在 InferenceEndpointConfig 规格范围内。）
+ **路径：**由客户配置（默认值为 /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
   ```

**其他常见问题**


| 问题 | 解决方案 | 处理建议 | 
| --- | --- | --- | 
|  未安装推理可观测性功能  |  通过控制台安装推理可观测性功能  |  控制台中的 “启用可观察性” HyperPod   | 
|  模型中已禁用指标  |  更新模型配置  |  将 `metrics: {enabled: true}` 添加到模型规格  | 
|  未配置 AMP 工作区  |  修复数据来源连接  |  确认 Grafana 数据来源中的 AMP 工作区 ID  | 
|  网络连接  |  检查安全组/ NACLs  |  确保容器组（pod）可到达 AMP 端点  |