vLLM chunked prefill 配置速查:max_num_batched_tokens 对 TTFT/ITL 的影响与调参
更新时间:2026-10-06。前面 chunked prefill 与 PD 分离 讲过切分 prefill 的原理和它如何演化出 prefill/decode 分离架构,continuous batching 调度器 讲过 vLLM 的迭代级调度。本篇落到具体操作:vLLM 里 chunked prefill 相关的几个参数到底调什么、调多大、按什么顺序验证效果。
本文要回答的问题
- chunked prefill 在 vLLM 里由哪几个参数控制,默认行为是什么?
max_num_batched_tokens调大调小分别伤害谁?- 按「TTFT 优先 / ITL 优先 / 吞吐优先」三种目标怎么给参数?
一、参数地图:三个旋钮管三件事
vLLM V1 里 chunked prefill 默认开启,核心旋钮三个。
max_num_batched_tokens:一次调度步里所有请求合计最多处理多少 token(prefill 切片和 decode token 共享这个预算)。它是 chunked prefill 的实际切片大小——一个 8000 token 的 prompt 在预算 2048 下要分 4 步算完,每步和队列里的 decode 请求混排。调小,decode 几乎不被 prefill 挤占,ITL(token 间延迟)平稳,但长 prompt 的 TTFT 被拉长成多步;调大则相反。
max_num_seqs:一次调度步最多容纳的请求条数。它限制的是 decode 侧的批次宽度,对显存里 KV block 的占用也有直接影响。注意它和预算的耦合:max_num_seqs 设得比 max_num_batched_tokens 还大没有意义(每条请求 decode 一步至少要 1 个 token),通常让 seqs 保持在预算的 1/8~1/4 区间,给 prefill 切片留出空间。
long_prefill_token_threshold(V1 新增):超过这个长度的 prompt 才会被强制切片,短 prompt 一步算完。它把「保护 decode 不被长 prompt 冲击」和「短请求别多走弯路」两个诉求分开了。没有这个参数的旧版本里,一个 512 token 的短 prompt 也可能因为预算紧张被切成两步,平白多付一步的调度与 kernel 启动开销——短请求的 TTFT 里这种固定开销占比很高,阈值参数就是为此而生。
为什么 chunked prefill 能平滑 ITL,值得用一句话点透:没有它时,一个 16K token 的 prompt 到来会独占整个调度步几百毫秒,期间所有 decode 请求陪停,用户看到输出流「卡住」一下;有了它,长 prompt 被切成十几段穿插进 decode 之间,每个调度步的时长被钉在预算对应的常数附近,decode 的吐字节奏自然平稳。本质上这是把「大任务阻塞小队列」的经典调度问题用时间片轮转解掉,和操作系统的抢占式调度是同一个思想。
图里是一个调度步的预算分配:decode 请求每步必占 token,prefill 切片吃剩余预算。这就是为什么 max_num_batched_tokens 的效果强烈依赖当前 decode 并发——同样 2048 的预算,10 路 decode 时切片有 2038,500 路 decode 时只剩 1548,高峰期 prefill 自然变慢。由此还能推出一个反直觉结论:decode 并发极高时,调大预算主要利好的是 prefill 切片而不是 decode——decode 的占用是随并发等比增长的固定项,预算增量几乎全部流向切片空间。所以当监控显示高峰期 TTFT 恶化而 ITL 依然平稳时,正确的动作是抬预算而不是加副本。
二、调参速查:按优化目标给值
先给硬件无关的直觉基准:H100/A100 级 GPU 上 max_num_batched_tokens 的典型工作区间是 2048~8192,低于 1024 时 prefill 吞吐被切碎明显,高于 16384 时长 prompt 对 ITL 的冲击基本等于没开 chunked prefill。消费级或小显存卡(如 24G 的 4090 跑 7B)可以把区间整体下移一档,1024~4096 往往就是全部可调空间——卡越小,调度步的常数开销占比越高,切太碎的惩罚来得越早。
| 优化目标 | max_num_batched_tokens | 配套动作 | 代价 |
|---|---|---|---|
| ITL 平稳优先(流式聊天) | 2048~4096 | 适度调大 max_num_seqs | 长 prompt TTFT 变长 |
| TTFT 优先(RAG 长文档) | 4096~8192 | 开 prefix cache 摊销共享前缀 | 高峰期 ITL 抖动 |
| 吞吐优先(离线批处理) | 8192~16384 | 配合大 batch 离线入口 | 交互延迟牺牲 |
表里的「代价」列就是这条权衡曲线的另一种说法:三个目标不可能同时拿满,调参前先和产品侧确认 SLO 保的是哪一个分位数。
调参的标准流程是三步。第一步,固定 max_num_seqs 为线上 P95 并发,用真实长度分布的回放流量扫 max_num_batched_tokens 的 4 个档位(2048/4096/8192/16384),画 TTFT P50/P99 和 ITL P99 三条曲线。第二步,找交点:ITL P99 开始恶化的前一个档位就是工作点——对大多数交互式服务这个点落在 4096 附近。第三步,用 long_prefill_token_threshold 做精修:把它设为线上 prompt 长度的 P80 左右,让占多数的短 prompt 享受单步完成,只切真正长的那 20%。
给一组一手的数感参考(H100 单卡、13B 模型、FP16):预算 2048 时一个调度步的时长约 30~50 毫秒(视 decode 占比),这就是 ITL 抖动的下限;16K prompt 在预算 2048 下 TTFT 约 400~600 毫秒,预算 8192 下压到 200 毫秒以内,但此时 decode 流的 P99 ITL 会从 60 毫秒涨到 150 毫秒以上。数字随模型与硬件变,但「TTFT 和 ITL 沿预算轴此消彼长」的权衡形状不变——调参不是找最优值,是在这条权衡曲线上选 SLO 允许的位置。如果 SLO 两头都卡不住,说明单实例容量到顶,该做的是加副本或上 PD 分离,而不是继续拧这个旋钮。
两个常见误判要避开。其一,不要拿合成等长 prompt 压测调参——真实流量的长度是重尾分布,等长 8K prompt 压出来的最优预算在混合流量下几乎总是偏大,上线后 ITL 崩。其二,chunked prefill 不省总算力:它重排的是时间,不是总量,TTFT 的均值在打开后通常还会略升(多步的调度开销),收益体现在 P99 的平滑和 ITL 的稳定上,拿均值指标验收会得出错误结论。
补一个版本差异提醒:vLLM V0 时代 chunked prefill 需要用 enable_chunked_prefill=True 显式打开,且和 prefix cache、投机解码等特性有组合限制;V1 架构(0.8 之后默认)里它是内置行为,组合限制基本解除,但老文档和旧部署脚本里的开关写法如果带到新版本,可能被静默忽略或报弃用警告。升级版本后第一件事是查启动日志确认调度器实际工作在哪种模式,别拿 V0 的参数语义套 V1 的行为。多卡 TP 部署时还要注意预算是每个 worker 各自记账的,TP=4 时四个卡各自按同样的预算切片,不存在「预算除以 TP 数」的说法——但调度由 0 号 worker 统一发起,行为仍等价于单卡语义,不需要为 TP 额外折算。
和 PagedAttention 显存 的联动也提一句:max_num_batched_tokens 不直接占显存,但 max_num_seqs × 平均上下文长度决定 KV block 水位,调大并发前先用 vLLM 启动日志里的「maximum concurrency」估算值核对,别让调度器频繁进入抢占(preemption)状态——抢占重算的代价远超 chunked prefill 省下的那点平滑。
三、观测与验收
上线后盯三个指标:time_to_first_token 的分位数曲线(看 TTFT)、time_per_output_token 的 P99(看 ITL 抖动)、num_preemptions 计数(看是否显存水位过高导致抢占)。前两个按 TTFT/TPOT SLO 的方法设告警。验收口径一句话:同等吞吐下 ITL P99 应显著下降,TTFT P99 不劣化或改善,抢占计数为零。三项有任一不满足,回到上一步的扫描流程换档。
排障时还有两个旁证指标好用。gpu_cache_usage_perc(KV block 水位)长期高于 0.9 说明并发开太猛,抢占随时可能发生;调度器日志里 prefill 切片步数的中位数如果远大于 prompt 长度分布的预期,说明预算相对 decode 并发偏小,高峰期 prefill 被饿死——表现为 TTFT 随负载线性恶化但 ITL 漂亮,这正是「预算调小了」的指纹,反向调大一档再观察即可。
这一篇在知识体系里的位置
本篇是 vLLM 部署调参线的速查篇:上游 chunked prefill 与 PD 分离(机制原理)、vLLM V1 调度器设计(调度器内部);同层 continuous batching 调度器、batch 延迟吞吐曲线。
总结
vLLM chunked prefill 的调参核心就一句话:max_num_batched_tokens 是每个调度步的 token 总预算,decode 先扣、prefill 切片吃余量——调小保 ITL、调大保 TTFT,交互式服务的工作点通常在 4096 附近,配合 long_prefill_token_threshold 设在 prompt 长度 P80 让短请求免切片;调参必须用真实重尾分布流量扫档,以 ITL P99 恶化点为界,并记住它平滑的是分位数不是均值,验收盯 TTFT/ITL 分位数和抢占计数三件事。