vLLM 怎样配置连续批处理最大 token

vLLM 中，连续批处理每次迭代最多处理多少 token，主要由 max_num_batched_tokens 控制。它不是“最多同时处理多少个请求”，而是一次调度迭代里可安排的 token 总预算。通常可以先用 8192 或 16384 作为起点，再根据首 token 延迟（TTFT）、交互延迟（ITL）、吞吐量和显存余量调整。

官方地址：https://docs.vllm.ai/en/latest/configuration/optimization/

需要降低交互延迟时先减小 max_num_batched_tokens；需要提高长提示词的 TTFT 和吞吐潜力时再逐步增大。参数改变后，要把它和 max_model_len、chunked prefill 以及 KV Cache 一起看。

这个参数到底限制什么

max_num_batched_tokens 表示单次迭代允许处理的最大 token 数。连续批处理会把已经进入解码阶段的请求和正在做预填充的请求放进调度循环，但每轮不能超过这份预算。它与下面几个参数的职责不同：

Python 启动时怎样配置

如果使用 vllm.LLM 创建引擎，可以直接传入同名的 Python 参数。下面的例子把每次迭代预算设为 16384，适合用来说明参数位置；实际数值仍要按模型、GPU 和请求长度调整。

from vllm import LLM

# 通过 token 预算控制每轮连续批处理的规模。
# 较大的值允许一次安排更多预填充 token，但可能增加解码请求的等待。
llm = LLM(
    model="your-model-id",
    max_num_batched_tokens=16384,
    max_model_len=8192,
)

# 这里的 prompts 只是示例输入，真正服务场景应使用自己的请求队列。
outputs = llm.generate(["请用三句话解释连续批处理"])
for output in outputs:
    # 读取生成文本，便于把结果交给上层业务。
    print(output.outputs[0].text)

这段配置的关键是参数名称中的 batched：它控制的是批次 token 预算，不会把单个请求的上下文上限自动改成 16384。若 max_model_len 仍是 8192，单请求依旧受到 8192 的长度限制。

在线服务怎样用 vllm serve 设置

在线服务对应的 CLI 参数是 --max-num-batched-tokens。vLLM 文档支持带单位的可读整数，因此可以写成 16k；为了减少不同脚本或环境对单位解析的误解，也可以直接写成 16384。

# 启动兼容 OpenAI API 的 vLLM 服务，并设置每轮 token 预算。
# 16k 表示 16,000；生产脚本也可以改写为 16384。
vllm serve your-model-id \
  --max-model-len 8192 \
  --max-num-batched-tokens 16k \
  --port 8000

# 查看命令帮助，确认当前安装版本暴露的调度参数。
vllm serve --help | grep max-num-batched-tokens

如果服务脚本还设置了 --max-num-scheduled-tokens，它通常会跟随 max_num_batched_tokens，但在某些会向批次追加 token 的场景下可能更小。不要只修改其中一个参数就假设实际调度预算一定相同。

怎样根据延迟目标选择数值

vLLM 的 chunked prefill 会把长预填充拆成更小的块，并与解码请求放到同一调度循环。官方优化说明给出的方向很明确：

• 更小的预算，例如 2048，更有利于 ITL，因为一轮预填充占用的 token 更少，解码请求不容易被拖慢。
• 更大的预算更有利于 TTFT，因为一次可以处理更多提示词 token；在较小模型和大 GPU 上，官方建议为了吞吐量考虑高于 8192 的值。
• 预算不是越大越好。预填充一次占用过多会让已经在生成的请求等待，显存不足时还可能触发抢占和重算。

可以按下面的顺序调参：先固定模型和 max_model_len，从 8192 或 16384 运行一组稳定负载；如果 ITL 超过目标，降低预算；如果 TTFT 和吞吐量仍有余量，再逐步提高。每次只改一个关键变量，便于把变化归因到 token 预算。

关闭 chunked prefill 时的边界

在 vLLM V1 中，chunked prefill 在可用时默认开启。若显式关闭它，官方文档要求 max_num_batched_tokens 大于 max_model_len；如果反过来设置，服务可能在启动阶段失败。因此，下面这种组合不适合关闭 chunked prefill 的场景：

# 关闭分块预填充时，批次 token 预算必须高于单请求上下文上限。
# 这里 16384 大于 8192，满足该边界；实际仍要结合显存决定。
vllm serve your-model-id \
  --disable-chunked-prefill \
  --max-model-len 8192 \
  --max-num-batched-tokens 16384

如果只是为了控制长提示词对解码的影响，优先考虑保留 chunked prefill 并调小预算，而不是直接关闭分块机制。关闭后，预填充和解码之间的调度关系会改变，旧的经验值不能直接照搬。

和显存、抢占问题怎样一起判断

当日志频繁出现 preemption 或显存不足时，单纯增大 token 预算可能让问题更严重。此时要把几个旋钮放在一起看：

• 适当提高 gpu_memory_utilization，为 KV Cache 留出更多空间，但要给系统和其他进程保留余量。
• 降低 max_num_batched_tokens 或 max_num_seqs，减少单轮调度的工作量。
• 如果模型和硬件允许，再考虑增加 tensor parallel 或 pipeline parallel；这会引入同步和通信成本。
• 持续观察 preemption 计数与 TTFT、ITL，不要只看 GPU 利用率。

一个实用的起始表如下：

一份简短的配置决策

如果你只需要一个可执行的选择过程，可以按这四步做：

1. 在线对话优先关注 ITL，从 2048、4096 或 8192 这类较小预算开始。
2. 批量生成或长提示词优先关注 TTFT 和吞吐量，从 8192 或 16384 开始。
3. 发现 preemption、OOM 或解码请求排队变长时，先回退预算，再检查并发序列数和 KV Cache。
4. 关闭 chunked prefill 前，确认 max_num_batched_tokens > max_model_len，并重新评估显存。

最后要记住：max_num_batched_tokens 是调度预算，不是性能保证值。真正合适的数字取决于模型大小、提示词分布、输出长度、GPU 显存和业务延迟目标。

常见问题

max_num_batched_tokens 越大吞吐量一定越高吗？

不一定。它提高了单轮可以安排的 token 数，但过大的预填充工作会让解码请求等待，也可能增加显存压力。应结合 TTFT、ITL 和吞吐量一起观察。

它和 max_num_seqs 可以互相替代吗？

不能。前者限制 token 总预算，后者限制序列数量。短请求很多时可能先碰到序列数上限，长提示词场景则可能先碰到 token 预算上限。

为什么命令行参数是横线，Python 参数是下划线？

这是 CLI 和 Python 参数的命名约定不同：命令行使用 --max-num-batched-tokens，Python 使用 max_num_batched_tokens，表达的是同一项配置。