AI Deploy大模型本地部署帮你部署

vLLM推理服务日志分析指南

本文说明如何从 `/metrics` 指标入口、周期性 INFO 日志和请求路径入手，区分排队、首 token 延迟、端到端延迟、KV cache 压力与请求结果，并给出启动、核对、关联分析和排错步骤。

分析 vLLM 推理服务日志，应先从 OpenAI 兼容 API 服务器的 /metrics 指标入口核对运行中请求、等待请求、KV cache 与延迟直方图，再用 LoggingStatLogger 每 5 秒输出的 INFO 关键指标日志交叉检查。若响应变慢，先区分请求是在 WAITING 阶段积压，还是首个 token 之后耗时变长；不要把单条慢请求直接等同于服务整体变慢。

先准备 vLLM 推理服务的观测入口

先准备以下材料：

  • 保存实际使用的启动配置，并集中留存服务侧应用日志。
  • 准备能够访问 /metrics 的监控通道，保留抓取结果或原始输出。
  • 记录业务侧可用于关联的请求标识、到达与完成时间、模型名和处理结果。

让监控与业务日志使用同一时间基准，并标出实例、版本、部署或参数变更时间。分析时先限定一个请求时间窗，再关联启动、请求和指标记录；只摘录一条 ERROR，通常无法判断问题发生在等待、首 token 还是后续生成阶段。

用结构化日志保留请求上下文

先按 OpenAI 兼容服务器文档中的 vllm serve 形式启动服务。下面仅用 YOUR_VALUE 代替密钥：

vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
  --dtype auto \
  --api-key YOUR_VALUE

该服务的日志通过 Python 的 logging.config.dictConfig 配置；按 日志配置说明加入以下参数，可输出结构化 JSON：

--logging-config.formatter json

需要把请求与指标关联起来时，vllm serve CLI 参数说明记录了以下开关：

--enable-log-requests

启用后，INFO 级别会记录 Request ID、请求参数和 LoRA 请求信息；DEBUG 级别还会记录文本或 token ID 形式的 prompt 输入。Prompt 可能包含业务数据，应只在受控排障窗口启用，并限制日志的保存时间和访问范围。

按队列、延迟和资源顺序分析

依据 生产指标列表，可以按请求状态、延迟和资源压力依次检查。

  • 先看等待。 vllm:num_requests_running 表示模型执行批次中的请求数，vllm:num_requests_waiting 表示等待处理的请求数，vllm:request_queue_time_seconds 记录请求处于 WAITING 阶段的时间。等待请求和队列时间同时上升时，先确认积压发生在执行前，再对照 单次迭代处理上限：
--max-num-seqs
--max-num-batched-tokens

调整前一次只改变一个相关参数，并继续使用相同指标和时间窗比较；官方参数说明没有给出适用于所有模型的固定值。

  • 再看首 token 与完整请求。 vllm:time_to_first_token_seconds 是 TTFT 直方图，vllm:e2e_request_latency_seconds 是端到端延迟直方图。官方给出的 每请求 TPOT 计算方法是：
TPOT = (end-to-end latency - TTFT) / (number of output tokens - 1)

仅在输出 token 数大于 1 时按该式解释。TTFT 上升时，排查重点应放在首个 token 产生之前；端到端延迟上升而 TTFT 相对稳定时，则应检查首个 token 之后的处理过程。这只是分流方法，不是根因结论。

  • 最后看缓存与累计变化。 vllm:kv_cache_usage_perc 是 KV cache 使用率 gauge，数值 1 表示 100%；vllm:num_preemptions 是累计抢占计数。vllm:prefix_cache_hits、prompt 与 generation token 计数以及 vllm:request_success 也属于累计指标，观察时应比较时间窗内是否增长，而不是只看总值。

核对 API 路径和参数差异

请求路径正确，并不代表参数行为完全一致。接口路径与参数说明列出了常见入口：

/v1/completions
/v1/chat/completions
/v1/embeddings

/v1/completions 只适用于文本生成模型，并且不支持 suffix；/v1/chat/completions 需要 chat template，并忽略 user 参数；/v1/embeddings 只适用于 embedding 模型。使用 OpenAI client 时，top_k 这类扩展参数应放入 extra_body；直接发送 HTTP 请求时，应合并进 JSON 请求体。Chat API 的 image_url.detail 不受支持，因此客户端接受某项参数，不代表服务端会采用它。

检查分析链路是否生效

完成下面几步，才算建立了可重复的日志分析链路：

  • 确认监控端能够访问前文的 /metrics，并按已经列出的 gauge、histogram 和 counter 名称逐项搜索。
  • 将 INFO 指标记录、请求日志和业务结果按统一时间窗对齐，避免把重启前后的数据混在一起。
  • 写下结论所依据的指标、配置版本和时间范围，明确问题位于等待阶段、首 token 之前，还是首个 token 之后。无法完成这种关联时，先不要给出单一根因。

常见出错点

  • 升级后指标消失。 根据 指标弃用策略，指标被弃用后会在下一个次版本隐藏，再下一个版本移除，因此仪表盘不应永久依赖已经进入弃用流程的名称。
  • 旧脚本继续使用旧参数。 日志参数迁移说明要求新命令改用：
--logging-config.pylogging_config_file

而不是已弃用的：

--log-config-file
  • 把 DEBUG 输出直接长期保存。 这可能连同 prompt 内容一起扩大数据暴露范围；排障结束后，应停止临时日志配置并按内部数据处理要求清理结果。

本文步骤依据正文所链接的官方文档整理，使用前请对照当前版本复核。

资料来源