vLLM OpenAI 兼容服务怎样限制并发请求

vLLM OpenAI 兼容服务要限制并发，不能只找一个“最大并发数”参数。更稳妥的做法是把入口请求数、正在运行的序列数和每轮 token 预算分开设置：前者控制排队长度，中间一层控制调度器同时运行多少请求，最后一层限制单轮计算量。

官方文档：https://docs.vllm.ai/en/latest/cli/serve/

先分清 vLLM 并发控制的三个层次

问题现场通常是“同时发 20 个请求后延迟陡增”，但根因可能不同。请求还在 API server 等待，应该看队列阀门；已经进入调度器但 GPU decode 批次过大，应该收窄运行态序列；长 prompt 让首 token 延迟变高，则要看 prefill token 预算。三者不能用一个数字替代。

用 max-num-queued-reqs 设置入口阀门

如果目标是让单实例最多承受固定数量的在途请求，先设置 --max-num-queued-reqs。它统计等待或运行中的请求，并在达到限制时让新请求收到 503；这适合把过载变成可重试信号，而不是让队列无限增长。

# 示例：把单实例在途请求上限设为 32，数值需按压测调整
vllm serve your-model \
  --max-num-queued-reqs 32 \
  --max-num-seqs 16 \
  --max-num-active-seqs 8

这里的 32 不是吞吐承诺，也不是 GPU 能同时生成 32 条序列。若启用了数据并行，队列阀门在 API server 侧统计它路由到的 DP 实例，而 max-num-seqs 的语义与每个 DP rank 的 runner 更相关。

用 max-num-active-seqs 收窄运行态并发

--max-num-seqs 影响模型 runner 的容量，--max-num-active-seqs 则用来限制调度器实际允许进入 RUNNING 的请求数。把后者设成 8、前者设成 16，表示保留 runner 的容量空间，但让 decode 批次更小；不能把 active 值设得大于 seq 值。

如果 503 很少但单请求延迟随着并发上升，优先复查 active 序列数与 KV cache 余量；如果大量请求在入口直接 503，则先调队列上限或扩展实例，不要只提高 active 值。

用 token 上限校准延迟与显存边界

--max-num-batched-tokens 表示单轮最多处理的 token 数，决定 prompt 与 decode token 如何争用一次调度预算；它不是“最多 N 个请求”。如果关注首 token 延迟，还可以用 --max-num-queued-tokens 限制处于 prefill 阶段的 prompt token 总量，超过后同样返回 503。

# 示例：限制每轮 token 预算，并给 prefill backlog 设置阀门
vllm serve your-model \
  --max-num-batched-tokens 4096 \
  --max-num-queued-tokens 12000
# 这两个值要结合 prompt 长度、目标 TTFT 和 KV cache 余量压测

排查时记录三类现象：请求是否收到 503、等待时间是否先增长、输出阶段是否变慢。短 prompt 但 decode 慢，倾向查看 active 序列；长 prompt 导致 TTFT 变差，倾向查看 queued tokens；队列持续堆积，则需要降低入口压力或增加实例。

把配置结果接到客户端重试策略

客户端不要对 503 立即无间隔重试，否则会把被拒绝的流量再次推回队列。建议使用带抖动的指数退避，并设置总重试时限；多实例部署时可把 503 当作转发到其他实例的信号。单实例场景则应记录请求长度、等待时间和最终状态，用压测结果反推三个阀值。

相关问题

max-num-seqs 能不能直接当最大并发数？

不能。它面向调度器的序列处理和 runner 容量；API 入口是否继续接收请求，还要看 queued requests、queued tokens 以及多实例路由。

把 max-num-queued-reqs 调大是不是吞吐就会更高？

不一定。它主要改变等待上限，过大的队列可能换来更长延迟。应先找到 503、TTFT、decode 延迟和显存余量之间的平衡点。

总结来说，vLLM 并发限制的可操作组合是：用 max-num-queued-reqs 防止入口无限堆积，用 max-num-active-seqs 控制运行态批次，再用 token 参数约束 prefill 与单轮计算量。每次只调整一层，并用 503 与延迟数据复查结果。