vLLM 块大小参数配置与调优

调 vLLM 块大小时，在 vllm serve 参数参考定义的 --block-size 中指定每个连续 KV cache block 包含的 token 数；它不等于上下文长度，也不等于单轮批处理上限。固定模型、请求负载及其余参数后逐次改变块大小，再对照启动日志和同口径基准报告中的 GPU KV cache、最大并发、吞吐与时延，才能判断哪组配置适合当前环境。

块大小参数与其他上限的区别

调 --block-size 时，应同时区分几个容易混淆的参数。vllm serve 参数参考说明，--max-model-len 覆盖 prompt 与 output，未设置时从 model config 推导；--max-num-seqs 限制单次迭代处理的 sequence 数，--max-num-batched-tokens 则限制单次迭代处理的 token 数。

这些参数承担不同职责，因此比较块大小时应保持它们不变。若同时修改上下文长度、并发序列数或单轮 token 上限，就无法判断显存和吞吐变化究竟来自哪个设置，也不要把某个固定块大小当作适用于所有模型和硬件的答案。

在 vllm serve 中配置块大小参数

根据 Engine Arguments 说明，在线服务所需的 engine arguments 作为 vllm serve 的参数传入。在现有启动命令中加入以下参数，并把 YOUR_VALUE 换成当前要验证的 token 数：

--block-size YOUR_VALUE

也可以使用 YAML 加载配置。Server Arguments 文档给出的加载形式是：

vllm serve --config config.yaml

配置值的优先级依次为 command line、config file、defaults。YAML 中的字段拼写应按当前版本的 Server Arguments 核对，不要猜测字段名。

块大小调优：先建立可比基线

每轮只改变 --block-size，其余条件保持一致：

• 使用相同模型、GPU 数量、运行环境和依赖版本。
• 固定 --max-model-len、--max-num-seqs、--max-num-batched-tokens 及显存相关设置。
• 固定数据集、请求端点、请求生成方式和并发限制。
• 保存启动日志及完整基准报告，不只记录最终吞吐。

Benchmark CLI 文档说明，--request-rate 默认为 inf，会立即发送全部请求；未设置 --max-concurrency 时，并发请求数不受限制。做参数对照时，可为两组配置填写相同的有限值：

--request-rate YOUR_VALUE
--max-concurrency YOUR_VALUE

同一文档还提醒，对同一服务重复运行 vllm bench serve 可能复用 prefix cache，并抬高吞吐。因此，各轮应在相同初始状态下运行，并在报告中记录是否复用了已有服务状态。

怎样确认块大小调整生效

启动后先查看日志，而不是只确认进程能够运行。Parallelism and Scaling 文档指出，GPU KV cache size 会报告 GPU KV cache 可同时容纳的总 token 数，并给出由此得到的最大并发。比较基线与候选配置时，先核对这两个输出，再进行请求测试。

随后使用同口径基准。文档给出的在线基准形式如下：

vllm bench serve \
  --backend vllm \
  --model NousResearch/Hermes-3-Llama-3.1-8B \
  --endpoint /v1/completions \
  --dataset-name sharegpt

按 Benchmark CLI 文档的定义，报告包含 request throughput、output-token throughput 和 total-token throughput；TTFT 从客户端发送请求计到收到首个 streamed output，TPOT 每个请求计算一次且排除首 token。对比时还应查看 ITL，即连续 streamed output 之间的时间间隔，避免只看单一吞吐数字。

显存紧张或频繁抢占时怎么调整

KV cache 空间耗尽时，vLLM 可能抢占请求，并在空间恢复后重新计算；vLLM V1 的默认 preemption mode 是 RECOMPUTE，不是 SWAP。Optimization and Tuning 文档建议，面对频繁 preemption，可提高 gpu_memory_utilization，或降低 max_num_seqs、max_num_batched_tokens，以减少并发请求需要的 KV cache。

块大小候选配置若仍出现 KV cache 不足，应先检查这些显存与并发边界，再判断块大小是否适合当前负载。官方参数说明没有给出块大小增减必然改善吞吐的统一方向，因此应以相同负载下的日志和基准报告为准。

常见出错点

• 一次修改多个参数：会导致无法归因，应每轮只改变 --block-size。
• 忽略有效配置值：检查 command line、YAML 与默认值之间的覆盖关系。
• 直接比较重复请求结果：先排除 prefix cache 对吞吐的影响。
• 只验证能否启动：还要核对 GPU KV cache、最大并发及 TTFT、TPOT 等指标。

以上步骤按正文所链接的官方文档整理，未运行或测量；使用前请结合当前版本复核参数与命令。

资料来源

• Engine Arguments (vLLM docs)
• vllm serve - CLI Reference (vLLM docs)
• Server Arguments (vLLM docs source)
• Parallelism and Scaling (vLLM docs source)
• Optimization and Tuning (vLLM docs source)
• Benchmark CLI - vLLM docs