本地大模型推理延迟排查实操

讲解大模型推理延迟的定位顺序：先用 TTFT 与 TPOT 区分首 token 与输出阶段，再检查 vLLM 的 KV cache、调度、并行配置，以及 nginx 的代理缓冲与超时。

排查本地部署大模型的推理延迟，先把 TTFT 与 TPOT 分开记录，再依次检查 vLLM 的调度与 KV cache、并行和启动配置，以及 nginx 的代理缓冲与超时。每轮只改一个变量，用相同模型、输入、输出长度、并发和访问路径复测，才能分清首 token、持续生成和网络传输各自造成的延迟。

本地部署大模型的基线怎么记

先把模型标识、请求正文、期望输出 token 数、并发度和访问路径写进基线。冷启动与稳态分开记录，每次只改一个参数，并保留上一轮结果。若直连 vLLM 与经过 nginx 的结果不同，后续就有独立的网络检查对象，不能把所有差异都归到模型或 GPU。

先确认请求走对入口

vLLM 的 OpenAI-Compatible Server 文档说明，Completions API 位于 /v1/completions，仅适用于文本生成模型且不支持 suffix；Chat API 位于 /v1/chat/completions，需要 chat template，并忽略 user。先确认业务使用哪一种入口：

/v1/completions
/v1/chat/completions

官方启动形式如下，将 YOUR_VALUE 替换为实际 API key：

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

请求能通过所选入口返回，只说明链路可用；首 token 与后续 token 的时间仍要分别记录。

从资源、KV cache 与调度查起

资源层面，vLLM 的调优说明给出的最低值是：部署使用 N 张 GPU 时，至少需要 2 + N 个物理 CPU 核。KV cache 空间耗尽时，vLLM 会抢占请求；V1 默认采用 RECOMPUTE 而不是 SWAP，空间恢复后再重新计算。频繁抢占时，文档先建议提高 gpu_memory_utilization，或降低 max_num_seqs、max_num_batched_tokens。

延迟取舍并非单向：较小的 max_num_batched_tokens 有利于 inter-token latency，文档举例为 2048；较大的值有利于 TTFT。V1 在可行时默认启用 chunked prefill，并优先调度 decode 请求；关闭 chunked prefill 时，max_num_batched_tokens 必须大于 max_model_len。

区分多卡并行与启动耗时

vLLM 的并行与扩展文档指出，tensor_parallel_size 把各层参数分到多张 GPU，是单节点常用策略；pipeline_parallel_size 则把不同层放到不同 GPU 并顺序处理。启动日志中的 GPU KV cache size 表示 GPU KV cache 同时可存储的 token 总数。多节点部署时，文档规则是 tensor_parallel_size 等于每节点 GPU 数，pipeline_parallel_size 等于节点数；若节点内 GPU 没有 NVLINK，例如 L40S，文档建议使用 pipeline parallelism，以获得更高吞吐和更低通信开销。

vLLM 的显存控制说明指出，降低 max_model_len 和 max_num_seqs 可以减少内存；CUDA graphs 默认启用，也会额外占用 GPU 内存。启用 tensor parallelism 时，每个进程都会读取完整 checkpoint，磁盘读取时间会随并行规模增加。设备选择应使用 CUDA_VISIBLE_DEVICES，而不是在 vLLM 启动前调用 torch device functions。

用 nginx 排除代理层延迟

同一请求直连正常，经过 nginx 后却成批出现，应先检查代理缓冲。NGINX 的 ngx_http_proxy_module 文档规定，proxy_buffering 默认开启；关闭后，响应会在收到时同步传给客户端，上游应用也可通过响应头逐次切换缓冲状态。该文档还记录，proxy_read_timeout 默认是 60s，计算的是两次连续读取之间的间隔，不是整个响应的传输时间；proxy_connect_timeout 默认也是 60s，通常不能超过 75s。

检查以下设置或响应头：

proxy_buffering off;

X-Accel-Buffering: no

这适用于需要收到即转发的 token streaming 或 SSE。若连接建立较慢，或上游长时间没有继续读取，再检查对应超时设置。

用一致负载验证调整

若需要标准化负载生成与延迟统计，MLPerf Inference Rules要求所有提交使用 LoadGen，并把延迟定义为从 LoadGen 调度向 SUT 传递查询，到收到回复的时间；LLM benchmark 会收集 TTFT 和 TPOT。Server 场景按 Poisson distribution 发送查询，指标是系统支持的 Maximum Poisson throughput；Offline 场景在开始时一次发送全部样本，不设延迟约束，指标是 measured throughput；Single stream 在上一请求完成后才发送下一请求，指标是 90% 分位的 early-stopping latency estimate。

本地排查应保持输入、输出长度、并发度和访问路径一致。不要用 Offline throughput 证明在线低延迟，也不要把不同场景的结果横向比较。

收口时排除混写

重点检查是否把冷启动与稳态混在一起，是否同时修改了多个参数，以及是否只记录总耗时而遗漏 TTFT、TPOT。保留基线、一次只改一个变量，才能判断改动究竟改善了哪一段链路。

这些步骤依据正文所链接的官方文档整理，使用前应按当前版本重新核对。