3. 批处理参数概览：常用批处理参数及其作用

vLLM 的批处理能力并非“自动发生”的魔法，而是由一组高度耦合的参数共同驱动。理解这些参数，是进行后续调优的前提。本章不讨论具体调优技巧，而是先建立一张完整的“参数地图”，明确每个参数控制哪个环节、影响哪些资源、以及它们之间的主次关系。

3.1 核心参数分层：从“能不能跑”到“跑得快不快”

面对 vLLM 引擎中数十个可调参数，初学者最容易犯的错误是“眉毛胡子一把抓”。实际上，批处理相关参数存在清晰的逻辑分层。我们可以将其划分为三个层级：容量层、调度层和执行层。容量层决定系统能“装下”多少请求，调度层决定请求如何被“组织”进批次，执行层则决定每个批次内部的计算如何被“加速”。

上图展示了三个层级之间的依赖关系。容量层的 --max-num-seqs 是调度层的硬约束，调度层不可能组织出超过容量上限的批次；而调度层的 --max-num-batched-tokens 又直接影响执行层中 CUDA Graph 的捕获尺寸。理解这种“上层约束下层”的关系，是避免参数冲突的关键。

3.2 关键参数逐一拆解

下面按照“参数名 → 默认值 → 作用机制 → 典型影响”的顺序，对最核心的 6 个参数进行拆解。这些参数在后续章节中会反复出现，请务必掌握其本质。

3.2.1 --max-num-seqs（容量层核心）

该参数定义了引擎在任意时刻最多允许多少个序列同时处于“活跃”状态。它直接决定了 GPU 上 KV Cache 的内存分配上限。默认值通常为 256，但在实际部署中，该值需要根据 --gpu-memory-utilization 和 --max-model-len 共同推算。如果设置过大，会导致 KV Cache 内存溢出；设置过小，则 GPU 利用率不足。

3.2.2 --max-num-batched-tokens（调度层核心）

这是控制“单次前向传播最多处理多少 token”的参数。它比 --max-num-seqs 更精细，因为一个批次中不同序列的长度差异可能很大。例如，10 个序列每个 100 token 与 100 个序列每个 10 token，虽然总 token 数相同，但计算模式完全不同。该参数默认值为 2048，调优时需结合 GPU 算力与显存带宽。

3.2.3 --gpu-memory-utilization（容量层基础）

该参数控制 vLLM 最多占用 GPU 显存的比例（默认 0.9）。剩余显存留给模型权重、激活值和 CUDA 上下文。它不直接决定批大小，但通过限制 KV Cache 的总量，间接约束了 --max-num-seqs 的有效上限。调优时建议先固定此值，再调整序列数。

3.2.4 --max-paddings（调度层辅助）

vLLM 采用连续批处理（Continuous Batching），但某些场景下仍需 padding。此参数限制因对齐而浪费的 token 数量。默认值为 0（即不允许额外 padding），但在使用某些不支持动态形状的算子时，可能需要放宽此限制。

3.2.5 --chunked-prefill-size（执行层关键）

当请求的 prefill 阶段（即处理输入提示词阶段）token 数过大时，会阻塞 decode 阶段的批处理。此参数将 prefill 拆分为多个 chunk，使得长提示词请求可以与短请求交错执行。默认值为 -1（不启用），推荐在混合负载场景下设置为 512 或 1024。

3.2.6 --enable-prefix-caching（调度层优化）

启用后，vLLM 会缓存已计算过的 token 前缀的 KV 状态。当新请求的提示词与缓存前缀匹配时，可直接复用，无需重新计算。该参数对“多轮对话”和“相似提示词”场景的吞吐提升非常显著，但会额外占用显存用于存储前缀索引。

3.3 参数间的典型冲突与优先级

实际配置时，参数之间经常发生“互相拉扯”。以下是一个典型的冲突场景：

因此，调参的优先级顺序应为：先确定模型与显存 → 再设定 --gpu-memory-utilization → 推算 KV Cache 上限 → 反推 --max-num-seqs 与 --max-model-len 的可行组合 → 最后微调调度与执行层参数。

3.4 参数速查清单

下表汇总了上述参数的核心属性，便于日常查阅。建议将此表打印或保存为本地速查卡。

参数名	所属层级	默认值	核心作用	调优方向
--max-num-seqs	容量层	256	限制并发序列总数	增大可提吞吐，但受显存约束
--max-num-batched-tokens	调度层	2048	限制单批次总 token 数	增大可减少调度开销，但需匹配算力
--gpu-memory-utilization	容量层	0.9	控制 KV Cache 可用显存比例	过高易 OOM，过低则批容量不足
--max-paddings	调度层	0	允许的 padding token 上限	仅在算子不支持动态形状时调整
--chunked-prefill-size	执行层	-1（关闭）	拆分 prefill 为多个 chunk	混合负载下设为 512~1024 改善延迟
--enable-prefix-caching	调度层	False	复用已计算的前缀 KV	多轮对话场景建议开启

3.5 常见误区与复盘

在指导团队配置 vLLM 时，我发现以下三个误区最具代表性，值得单独指出：

• 误区一：盲目调大 --max-num-seqs 以为能提升吞吐。实际上，当批大小超过 GPU 算力承受范围时，单 token 生成延迟会显著上升，整体吞吐反而下降。正确做法是观察 GPU 利用率 与 平均 ITL（Inter-Token Latency），找到拐点。
• 误区二：忽略 --max-model-len 对 KV Cache 的放大效应。该参数每增加一倍，KV Cache 占用也近似翻倍。很多 OOM 问题并非显存不足，而是 --max-model-len 设置过长导致预留空间过大。
• 误区三：将 --max-num-batched-tokens 与 --max-num-seqs 混为一谈。前者是 token 维度，后者是序列维度。一个 2048 token 的批次，可以是 2 个 1024-token 的序列，也可以是 64 个 32-token 的序列。两者对计算核心的利用模式完全不同。