vLLM 怎样设置连续批处理的并发上限

vLLM 连续批处理通常先用 --max-num-seqs 约束单个引擎每轮可处理的序列数量，再用 --max-num-batched-tokens 约束每轮 token 工作量。它们不是 HTTP 连接数限制，也不保证服务只接收同样数量的请求。若安装版本支持 --max-num-active-seqs，还可以在保留模型 runner 容量的同时，单独压低 RUNNING 状态的活跃请求数。

官方参数入口：https://docs.vllm.ai/en/latest/cli/serve/。本文讨论单个文本生成引擎、每请求一个输出的配置思路；多副本、数据并行、多个候选输出和推测解码需要另外核对计数范围。以下数值仅为配置例子，不代表任何显卡的安全容量或吞吐承诺。

把连续批处理的上限分成三个容量边界

连续批处理不是让所有请求凑齐后一起生成完整答案。请求的生成长度不同，服务会持续调度可运行的工作。因此，限制“一个批次多大”和限制“入口收了多少请求”是两件事。

可以把这组配置理解为“执行容量与入口容量分离”的模式：执行侧控制共享计算资源，入口侧控制积压的规模。执行侧仍可能因为 token 预算、KV cache 空间等条件而没有用满名义上的序列容量。

给单个引擎配置序列数和 token 预算

先为普通文本生成准备一组易解释的显式值。假设模型已经完整保存到本地 /srv/models/text-model，GPU 和 vLLM 版本与该模型兼容，可以使用下面的启动写法。路径须替换为实际模型目录；这些命令未在本文环境执行。

# 仅监听本机；模型目录替换为已经准备好的本地模型
# 32 是每轮序列容量示例，2048 是每轮 token 预算示例
vllm serve /srv/models/text-model \
  --host 127.0.0.1 \
  --max-num-seqs 32 \
  --max-num-batched-tokens 2048 \
  --enable-chunked-prefill

显式启用 chunked prefill，是为了允许提示词预填充按剩余 token 预算分块。不要把 2048 理解成请求只能输入 2048 token；输入长度还受模型上下文配置等限制。反过来，不启用分块时也不能照搬这组预算关系，应查安装版本对完整 prefill 的要求。

配置后的判断重点不是“立刻看到 32 个请求同时输出”，而是启动参数及最终引擎配置是否对应预期，并且真实负载下的延迟、排队和内存压力是否可接受。序列容量是上限，不是调度器必须填满的目标。

保留 runner 容量时单独降低活跃请求数

当问题是“runner 已按较大容量准备好，但希望解码阶段少一些活跃请求”时，直接把 max_num_seqs 改小可能同时改变 runner 的逐请求缓冲区与 CUDA graph 容量。最新官方 CLI 列出的 max_num_active_seqs 用于把这两个选择分开：它约束调度器能放进 RUNNING 的请求数，数值不得大于 max_num_seqs；未设置时沿用默认的接纳行为。

# 仅用于安装版本明确支持 max-num-active-seqs 的情况
# 保留 64 的 runner 容量，活跃请求数示例设为 16
vllm serve /srv/models/text-model \
  --host 127.0.0.1 \
  --max-num-seqs 64 \
  --max-num-active-seqs 16 \
  --max-num-batched-tokens 2048 \
  --enable-chunked-prefill

这不是说模型已经能安全同时承载 64 条长上下文，也不是显存隔离开关。保留更大的 runner 容量本身仍有资源代价。若当前安装版本没有这个参数，应采用基础的 max_num_seqs 限制或先做版本迁移评估，不要靠写入同名环境变量假定它生效。

特别要避免一边把活跃数降到 16，一边把 token 预算、模型长度和并行方式也全部改掉。那样即使体验变化，也无法解释是哪一个配置造成的。合理的配置记录应保留模型、版本、硬件、上下文分布和修改项。

入口积压不能靠缩小批次解决

假设入口已经接收了很多请求，把每轮序列容量设成 16，并不自动把第 17 个 HTTP 请求拒绝掉。执行容量变小而进入速度不变时，更多工作可能停留在等待区域。排队时间还占用客户端的超时预算。

最新官方 CLI 还提供 --max-num-queued-reqs。名称中虽有 queued，它计算的却是 waiting 或 running 的在途请求总量，不是“仅等待队列长度”。到达限制时，新请求返回 HTTP 503。该限制位于 API server 进程侧，覆盖它路由的多个 data-parallel rank；不能误当成全公司所有副本共享的一个计数器。

# 仅用于安装版本同时支持 active 与 queued 两个参数的情况
# 单 API server 示例：活跃上限 16，在途总量上限 48
vllm serve /srv/models/text-model \
  --host 127.0.0.1 \
  --max-num-seqs 64 \
  --max-num-active-seqs 16 \
  --max-num-batched-tokens 2048 \
  --max-num-queued-reqs 48 \
  --enable-chunked-prefill

这里的 48 不是额外允许等待 48 个，也不能简单断言永远恰好等待 32 个：RUNNING 数可能低于 16，状态也会变化。它只是这个入口的在途总量阀门。若版本不支持，应在网关或业务层设计独立的有限队列、超时与过载响应，不要让排队无限增长。

客户端收到过载响应后，也不能立即无限重试。需要有重试上限、退避和总超时预算；否则重试流量本身会继续挤压入口。本文不展开网关实现，也不把该阀门当作用户配额系统。

按负载判断这组上限是否适合

交互式服务更关心首 token 等待和生成间隔；离线任务通常更重视完成总工作量。相同的序列容量不一定适合这两种目标。增大容量可能提高资源利用，也可能加重竞争；减小容量可能改善部分请求的体验，同时降低整体吞吐或拉长等待。没有脱离模型、硬件与请求长度的通用最佳值。

给部署人员的判断顺序是：明确当前限制的是执行侧还是入口侧；确认参数在所装版本存在；保留一组可回退配置；在代表性负载下分别观察等待数量、首 token 延迟、生成间隔、完成吞吐和 KV cache 压力。本文只提供配置和取舍解释，没有提供实测数据，也没有宣称这些数值已经过容量测试。

max-num-seqs 等于在线用户数吗？

不等于。用户可能没有正在推理，也可能发出多个请求；连接、请求与序列不是统一计数。多输出等模式更不能直接按用户数换算。

只降低 max-num-batched-tokens 能把并发固定为 16 吗？

不能。它限制每轮 token 工作量，不是固定请求数开关。要按对象选择序列容量或活跃请求限制。

用了 tensor parallel，序列容量是否按 GPU 张数相乘？

不要这样计算。tensor parallel 的多张 GPU 协作承载引擎，不是自动生成多个独立接纳池。data parallel、多副本及 API server 路由范围也必须分别理解。

新参数报 unrecognized arguments 应怎么处理？

按安装版本的 CLI 和对应版本文档调整配置；删去不支持的参数时，还要重新评估它原本承担的容量边界，不能只为了启动成功而保留“已限制入口”的错误预期。

官方参考：vLLM serve 参数；vLLM 优化与调优。阅读时选择与安装版本匹配的文档；latest 页面中的新增参数不能自动套用到旧版本。