vLLM推理服务监控与指标解读
从 OpenAI 兼容服务的 `/metrics` 端点入手，读取请求队列、KV cache、TTFT、端到端延迟和 token 计数，逐项判断推理服务是否受排队、执行或生成阶段影响。
要监控 vllm serve，先确认 /metrics 能被抓取，再把 running、waiting、KV cache、TTFT、端到端延迟和 token 计数放在同一张观察表里；只看总延迟，无法判断请求究竟在排队还是已经进入执行。vLLM 的在线服务通过 vllm serve 接收 engine arguments，而 vLLM 的 Production Metrics 说明指标暴露在 OpenAI 兼容服务的 /metrics 端点。下面按准备、验证、解读和排查推进。
从 vllm serve 的 /metrics 开始检查
先准备正在运行的 API server、Prometheus，以及能够访问该服务的网络路径。抓取配置应最终指向 /metrics，不要误填成 /v1 推理路径。
Prometheus 的入门配置把抓取任务放在 scrape_configs 下，通过 job_name 标识任务，并在 static_configs.targets 中列出目标地址。可按这个结构填写：
scrape_configs:
- job_name: YOUR_VALUE
static_configs:
- targets: ['YOUR_VALUE']
把两个 YOUR_VALUE 替换为自己的任务名和可访问地址，并将文件保存为 prometheus.yml，再按文档提供的方式启动：
./prometheus --config.file=prometheus.yml
确认数据链路已经打通
访问服务器的 /metrics，确认输出中存在 vllm:num_requests_running。随后用现有 API 客户端发送一次正常请求，观察请求状态、token counter 和 latency histogram 是否出现或变化。
如果直接访问端点有数据，而 Prometheus 中没有，先核对 targets、端口和最终抓取路径；如果端点本身也没有数据，再检查服务进程和网络可达性。能看到一个指标只能证明端点可访问，不能证明队列和延迟处于健康状态。
先读请求状态和资源信号
以下定义来自 vLLM 的 Production Metrics 指标页。先分清 Gauge、Counter 和 Histogram，再决定是看当前值、增量还是分布。
| 指标 | 类型 | 重点含义 |
|---|---|---|
vllm:num_requests_running |
Gauge | 模型执行批次中的请求数 |
vllm:num_requests_waiting |
Gauge | 等待处理的请求数 |
vllm:kv_cache_usage_perc |
Gauge | KV cache 使用比例，数值 1 表示 100% |
vllm:time_to_first_token_seconds |
Histogram | 首个 token 到达时间，单位为秒 |
vllm:e2e_request_latency_seconds |
Histogram | 请求端到端延迟，单位为秒 |
vllm:request_queue_time_seconds |
Histogram | 请求处于 WAITING 阶段的时间 |
vllm:prompt_tokens、vllm:generation_tokens |
Counter | 已处理的输入和生成 token 数 |
vllm:num_preemptions |
Counter | 引擎累计抢占次数 |
vllm:prefix_cache_hits |
Counter | prefix caching 命中的 token 数 |
vllm:request_success |
Counter | 成功处理的请求数 |
请求状态和延迟要一起读：num_requests_waiting 上升，同时 request_queue_time_seconds 变长，说明请求在进入处理前已经形成积压。KV cache 接近 1，且 num_preemptions 的累计值持续增加，则应重点检查缓存内存压力。Counter 表示累计量，计算速率时应看时间窗内的增量，而不是直接把当前累计值当成瞬时负载。
把延迟拆成排队、首 token 和生成阶段
先比较 TTFT 与端到端延迟。TTFT 上升，表示首 token 前的等待增加；TTFT 相对稳定而端到端延迟上升时，再检查后续 token 生成阶段。不要把整段请求延迟全部归因于排队。
vLLM 的指标设计文档给出了单请求 TPOT 的计算方式：
(end-to-end latency - TTFT) / (number of output tokens - 1)
该公式用于输出 token 数大于 1 的请求，结果表示首 token 之后每个输出 token 的平均时间间隔。对于 Histogram，不要自行挑选某个 bucket 代表整体延迟。Prometheus 的查询函数文档说明，histogram_quantile(φ, b) 可以从 classic 或 native histogram 计算分位数；聚合 classic histogram 时，by 子句必须保留 le 标签。
从 token 计数和成功率看吞吐与错误
在同一统计范围和连续时间窗内，用 vllm:generation_tokens 的增量除以经过时间，可以得到生成 token 速率。这个值反映 token 吞吐，不等同于每秒请求数。
vllm:request_success 只统计成功处理的请求，不是失败请求数。没有可核对的总请求数时，不要据此推算失败率或错误类型；应把成功计数与网关、应用日志中的请求总量及错误记录对应起来。
常见误区与排查顺序
- 抓取层：
/metrics没有数据，先查服务状态、目标地址、端口和路径，不要直接归因于 GPU 或模型性能。 - 队列层： waiting 和 queue time 同时升高，先确认请求是否在进入执行前积压。
- 缓存层： KV cache 接近
1且 preemptions 增量变大，重点检查缓存内存压力。 - 延迟层： 联合查看 queue time、TTFT、端到端延迟和 TPOT，不要只看一个总延迟数字。
- 数据层： 区分 Gauge 与 Counter，也不要把
request_success当成错误计数；指标名称或参数发生变化时，先核对当前版本文档。
这些步骤依据正文所链接的官方文档整理，未运行这些步骤或生成性能结果；使用前应按当前版本复核。