Monitoring and Observability for vLLM Deployments: Prometheus Metrics, Grafana Dashboards, and Alerting Rules

部署大模型推理服务时，成本失控和性能瓶颈是两大核心痛点。根据 Cloudflare 2024 年发布的《AI Inference Latency Report》，vLLM 在生产环境中平均 P99 首 token 延迟为 1.8 秒，但若缺乏监控，超过 30% 的请求会在 GPU 显存溢出后直接超时。同时，中国信息通信研究院（CAICT）2024 年《人工智能云服务发展白皮书》指出，国内 MLOps 团队因观测不足导致的 GPU 闲置浪费占总算力支出的 18%-25%。这意味着，没有一套完善的监控与可观测性体系，vLLM 部署的吞吐和成本优势将大打折扣。本文从 Prometheus 指标采集、Grafana 看板构建到告警规则设计，提供一份可直接落地的技术白皮书。

vLLM 内置 Prometheus 指标架构

vLLM 从 0.4.0 版本起原生暴露 /metrics 端点，输出格式兼容 Prometheus。这些指标覆盖引擎运行时状态、请求生命周期和硬件利用率三大维度，无需额外埋点即可接入。

核心指标分类与采集端点

vLLM 默认在 8000 端口提供 /metrics，可通过环境变量 VLLM_HOST 和 VLLM_PORT 自定义。指标分为三类：引擎指标包括 vllm:num_requests_running（当前正在解码的请求数）、vllm:num_requests_waiting（调度队列长度）；性能指标如 vllm:time_to_first_token_seconds（首 token 延迟直方图）和 vllm:request_prompt_tokens（输入长度分布）；硬件指标通过 nvml 暴露 GPU 显存占用和温度。建议采集间隔设为 15 秒，避免对推理吞吐产生超过 1% 的性能影响。

关键指标解读：调度器状态

vllm:num_requests_waiting 是判断系统是否过载的关键。当该值持续超过 max_num_seqs（默认 256）的 80% 时，说明调度器已饱和。结合 vllm:gpu_cache_usage_perc（KV cache 利用率）可区分是显存瓶颈还是计算瓶颈——若缓存使用率低于 70% 但等待队列增长，则瓶颈在 GPU 计算能力。

Grafana 看板构建：从数据到决策

一个生产级 Grafana 看板至少需要四个面板：请求吞吐、延迟分布、KV cache 利用率和 GPU 资源状态。以下提供基于 vLLM 0.6.0 的 JSON 模型关键配置。

请求吞吐与错误率面板

使用 PromQL 查询 rate(vllm:num_requests_succeeded[5m]) 得到每秒成功请求数（RPS）。对于错误率，vLLM 暴露 vllm:request_errors_total 计数器，按错误类型（error_type 标签包括 timeout、oom、bad_request）区分。用 rate(vllm:request_errors_total[5m]) / rate(vllm:num_requests_succeeded[5m]) 计算错误率，阈值应低于 1%。超过 5% 时，通常对应显存溢出（OOM）或模型加载异常。

KV cache 效率热力图

vLLM 的 vllm:gpu_cache_usage_perc 指标按 GPU 索引暴露。使用 Grafana 的 State Timeline 面板，将每张 GPU 的缓存利用率按时间轴着色，可直观发现缓存碎片化问题。当利用率在 5 分钟内波动超过 20% 且伴随延迟抖动，说明 max_num_batched_tokens 参数需调优。实际案例中，某团队将 max_num_batched_tokens 从 4096 降至 2048 后，P99 延迟下降 42%（来源：vLLM GitHub Issue #4567，2024）。

告警规则设计：避免误报与漏报

告警应基于多指标复合条件，而非单一阈值。以下规则适用于 Prometheus Alertmanager，建议告警间隔 5 分钟，避免重复通知。

核心告警规则示例

• 高延迟告警：histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m])) > 5，持续 3 分钟触发。这意味着 P99 首 token 延迟超过 5 秒，通常由调度队列堆积或 GPU 降频引起。
• 显存溢出预警：vllm:gpu_cache_usage_perc > 0.85 且 vllm:num_requests_waiting > 100，持续 2 分钟。此时应触发自动扩容或降低 batch size。若同时 node_memory_MemAvailable_bytes < 5GB（节点内存不足），则需重启 vLLM 进程释放碎片。
• 请求成功率告警：rate(vllm:request_errors_total[5m]) / rate(vllm:num_requests_succeeded[5m]) > 0.05，持续 1 分钟。此规则可捕获模型加载后首次推理的冷启动错误。

告警分级与通知渠道

将告警分为 P0（服务不可用）、P1（性能退化）、P2（资源预警）三级。P0 通过电话或 PagerDuty 触发，P1 推送至企业微信或钉钉群，P2 记录到日志系统。注意，vLLM 的 vllm:num_requests_running 指标若归零且等待队列不为空，应作为 P0 处理——这表示引擎死锁。

生产环境部署：Prometheus + Node Exporter 集成

vLLM 的指标需与节点级指标配合才能定位根因。推荐在每台推理节点部署 Node Exporter，暴露 CPU 内存和网络指标。

采集配置与数据保留

Prometheus 的 scrape_configs 中，vLLM 目标应添加标签 job="vllm"，并使用 relabel_configs 提取 GPU 索引。数据保留策略：原始指标保留 7 天，聚合指标保留 30 天。对于高频指标如 vllm:time_to_first_token_seconds，建议在 Prometheus 侧启用 recording rule 预聚合为 5 分钟均值，减少存储开销。根据 Grafana Labs 2024 年《Observability Survey》，超过 60% 的团队因保留策略不当导致历史对比困难。

跨云环境注意事项

若使用国内云厂商（阿里云、腾讯云）的托管 Prometheus 服务，需注意 vLLM 指标中的 vllm:gpu_cache_usage_perc 可能被自带的 GPU 监控覆盖。建议在 vLLM 启动参数中添加 --disable-log-requests 减少日志量，避免磁盘 I/O 干扰指标采集。对于海外部署（如 AWS EKS），可使用 Prometheus Operator 的 ServiceMonitor 自动发现 vLLM Pod。

成本关联分析：监控驱动优化

监控不应止于告警，更应反哺成本。通过将 Prometheus 指标与云厂商计费数据关联，可量化每千 token 的推理成本。

单位推理成本计算

使用 rate(vllm:num_generation_tokens_total[1h]) 获取每小时生成 token 数，结合云 GPU 实例价格（如 A100 80GB 按需 $3.93/小时，来源：AWS 2024 年定价页），得到 $0.00000109/ token。若该值高于模型训练时的预估成本 20%，说明推理效率不足。此时应检查 vllm:gpu_cache_usage_perc 是否低于 60%，并考虑启用 vLLM 的 --enable-prefix-caching 功能，该功能在重复性请求场景下可降低 30%-50% 的 KV cache 消耗。

自动扩缩容触发条件

根据 vllm:num_requests_waiting 和 vllm:gpu_cache_usage_perc 的复合指标，可设置 HPA（Horizontal Pod Autoscaler）。例如，当 vllm:gpu_cache_usage_perc > 0.8 且等待队列超过 50 时，触发扩容。注意，vLLM 的扩缩容需考虑模型加载时间（通常 1-3 分钟），因此最小扩容间隔应设为 5 分钟，避免震荡。

常见陷阱与调优建议

即使指标采集完整，实践中仍有三个高频问题。

指标延迟与丢点

Prometheus 拉取间隔过大（超过 30 秒）会导致 vllm:time_to_first_token_seconds 直方图桶计数失真。解决方案：将 scrape_interval 设为 10 秒，并在 vLLM 启动参数中添加 --max-log-len 0 减少日志缓冲对指标暴露的影响。

多 GPU 场景的标签缺失

vLLM 0.5.0 之前版本不暴露 GPU 索引标签，导致无法区分单机多卡场景。升级至 0.6.0 或手动添加 gpu_id 标签。若无法升级，可通过 Node Exporter 的 nvidia_smi_gpu_index 指标关联。

告警风暴抑制

当 vLLM Pod 重启时，所有指标归零，可能触发大量告警。使用 Alertmanager 的 group_wait 和 group_interval 参数，将同一 Pod 的告警合并为一条。具体配置：group_wait: 30s，group_interval: 5m。

FAQ

Q1：vLLM 的 Prometheus 指标是否需要额外安装 exporter？

不需要。vLLM 从 0.4.0 版本起内置 /metrics 端点，只需在 Prometheus 配置中添加对应的 scrape target。若需 GPU 硬件指标，建议额外部署 Node Exporter 和 DCGM Exporter，后者可提供显存温度、功率等 20 余项指标。

Q2：如何设置 vLLM 的告警阈值，避免频繁误报？

建议使用复合条件而非单一阈值。例如，P99 延迟告警条件为 histogram_quantile(0.99, rate(...)) > 5 持续 3 分钟，且同时 vllm:num_requests_waiting > 50。误报率可降低 60% 以上，参考 Grafana Labs 2024 年《Alerting Best Practices》指南。

Q3：vLLM 在 Kubernetes 中如何自动发现监控目标？

使用 Prometheus Operator 的 PodMonitor 或 ServiceMonitor 资源。配置 spec.selector.matchLabels 匹配 vLLM Pod 的标签（如 app: vllm），并设置 spec.endpoints.port: metrics。注意，vLLM 默认端口为 8000，需在 Service 中暴露该端口。

参考资料

• Cloudflare 2024 年《AI Inference Latency Report》
• 中国信息通信研究院 2024 年《人工智能云服务发展白皮书》
• Grafana Labs 2024 年《Observability Survey》
• AWS 2024 年《Amazon EC2 P4d Instance Pricing》
• vLLM 官方文档 2024 年《Monitoring and Metrics》