企业官网建设流程全解析

上个月我把 Qwen2.5-7B-Instruct 用 vLLM 部署成内部平台的 OpenAI 兼容 API，目标很直接：让十几个业务方同时调用，单接口 P95 延迟控制在 2 秒以内。结果从压测到上线，前后踩了四个大坑——不是模型能力问题，全是部署参数和调度策略的细节。今天这篇就把每个坑的现象、原因、排查思路和最终配置一次讲清楚，给正准备用 vLLM 做开源大模型高并发 API 的人当个参考。

先交代一下环境，后面所有参数都基于这套：Ubuntu 22.04，A100 80G 单卡，vLLM 0.6.3，模型 Qwen2.5-7B-Instruct，bf16 精度，通过vllm serve启动 OpenAI 兼容服务。这套组合现在非常常见，你换成 13B 或者 70B 模型，坑的类型是一样的，只是数字要重算。

1. 坑一：max-model-len 拍脑袋乱设，KV Cache 直接被吃穿

1.1 线上 400 报错，问题出在启动参数

服务上线第一天就出事了。短文本测试全部通过，结果有业务方直接传了一份几页纸的合同文本进来，API 立刻返回 400：

This model's maximum context length is 4096 tokens. However, you requested 5120 tokens. Please reduce the length of the messages or completion.

这个报错在 GitHub issues 里被问了无数次，原因非常朴素：启动 vLLM 时--max-model-len默认取了模型 config 里的 4096，或者你自己设了一个偏小的值，导致请求超过这个长度直接被拒绝。更隐蔽的是，很多团队根本不看启动日志里打印的 KV cache 信息，等线上爆了才发现并发能力远远低于预期。

还有个特别容易忽略的细节：如果你用了--served-model-name给模型起了别名，而调用方传的 model 字段和别名对不上，也会报类似的 400 错误。热词里那个 "The supported API model names are deepseek-v4-pro..." 就是同一个坑。确保调用方的 model 名称和服务端--served-model-name完全一致，这是 OpenAI 兼容接口的基本礼仪。

1.2 为什么 max-model-len 和显存是强耦合的

很多人以为max-model-len只是一个"允许的最大长度"开关，调大点没坏处。实际上它直接决定单条序列占用的 KV cache 大小。

KV cache 是推理过程中缓存的 Key 和 Value 矩阵，用来避免每生成一个 token 都重新计算前面的注意力。它的大小可以近似用这个公式算：

单序列 KV cache = 2 × num_hidden_layers × num_key_value_heads × head_dim × dtype_size × max_model_len

以 Qwen2.5-7B 为例，config.json 里num_hidden_layers=28，num_key_value_heads=4，head_dim=128，bf16 每个数占 2 字节，那么每个 token 的 KV cache 占用：

2 × 28 × 4 × 128 × 2 = 57344 字节 ≈ 56 KB

一个 max_model_len=32768 的请求，单序列 KV cache 就有 1.75 GB。如果你在 A100 上，gpu_memory_utilization 预留了 50GB 给 KV cache，那理论上最多同时跑 28 个这种长度的请求，再往上就是 OOM。

所以max-model-len不是"越大越好"，它是一个显存预算的分配开关。设小了，长文本请求被拒；设大了，单序列吃掉太多 KV cache，系统整体并发能力暴跌。

1.3 先统计业务 token 分布，再确定 max-model-len

这个坑的解法不是靠猜，而是靠业务数据。上线前我用 tokenizer 把历史请求做了一次长度分布统计：

from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct") lengths = [len(tokenizer.encode(text)) for text in historical_prompts] # 输出 P50/P90/P95/P99 分位数 for p in [50, 90, 95, 99]: val = sorted(lengths)[int(len(lengths) * p / 100)] print(f"P{p}: {val}")

统计结果显示，我们内部业务 95% 的请求在 8K token 以内，但偶尔会有 20K 左右的长文档。最终我把max-model-len定在 32768，既覆盖了长文档场景，也没有把并发压到不可接受的程度。启动命令是：

vllm serve Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --max-model-len 32768 \ --gpu-memory-utilization 0.90

启动后务必用/v1/models接口确认参数生效：

curl http://localhost:8000/v1/models

返回的 JSON 里max_model_len字段会显示当前实际值。我用一个表格列出 Qwen2.5-7B 在 A100 80G、KV cache 预算约 50G 的前提下，不同 max-model-len 对应的单序列占用和理论最大并发：

注意这里的并发上限是"所有请求都跑满 max-model-len"的极端值，实际业务请求长短不一，可用并发会更高。但方向很清楚：max-model-len 每翻一倍，长请求的并发能力就减半。所以很多人图省事直接设 128K，上线后 QPS 上不去，根本不是 vLLM 不行，而是 KV cache 预算早就被超长序列吃干了。

2. 坑二：默认并发参数直接用于生产，QPS 上不去还偶发 OOM

2.1 现象：压测一到 10 并发就开始排队

第二个坑是上线前压测踩的。vLLM 的默认启动参数看起来很省心，不传--max-num-seqs、--max-num-batched-tokens也能跑。我用 locust 模拟 10 个并发用户跑了一个简单的问答场景，结果傻眼了：单请求延迟 300ms，但 10 并发时 P95 直接跳到 5 秒，GPU 利用率一直在 20%~40% 之间波动，任务堆积严重。

更诡异的是，偶尔还会冒出来 CUDA out of memory。单请求明明怎么跑都不会 OOM，为什么并发一高就爆显存？

2.2 原理：max-num-seqs 和 max-num-batched-tokens 是配合关系

vLLM 之所以快，核心是 continuous batching：一个 iteration 里同时处理多个序列，动态地在 prefill 和 decode 之间切换。控制这个行为的有两个关键参数：

• --max-num-seqs：一个 iteration 里最多同时处理的序列数，默认通常是 256。
• --max-num-batched-tokens：一个 iteration 里最多处理的 token 总数，不同版本默认值有差别，有的版本默认 2048，有的默认 8192，务必用vllm serve --help确认。

这两个参数是配合关系，不是独立关系。max-num-batched-tokens决定了每轮迭代的"总预算"，max-num-seqs决定了这个预算最多分给几个序列。

如果max-num-batched-tokens太小，而每个请求在 prefill 阶段有几千 token，那么一个迭代里只能塞进一两个序列，剩余序列全部排队，吞吐自然上不去。反过来，如果你把max-num-batched-tokens拉到很大，每轮迭代要处理大量 token，GPU 显存瞬时峰值会飙升，碰到几个长序列同时 prefill，OOM 就来了。

我们当时的情况就是这个典型：默认 max-num-batched-tokens 对长 prompt 业务太小，调度器每轮只能喂进去少量请求，QPS 上不去；而当请求数量堆积、某些请求的 batch 被强行合并时，显存峰值又爆了。

2.3 解法：按场景给参数，用 bench 验证

这个问题没有万能参数，但有一个合理的经验路径。首先想清楚你的业务形态：

• 短文本场景（输入输出都在 1K token 以内），可以把max-num-batched-tokens设大，让更多请求同时挤进一个 iteration。
• 长文本场景（输入几 K，输出几百 token），max-num-seqs不能太大，否则 prefill 阶段会短时间吃掉大量显存。

我调了一版参数，用下来比较稳定：

注意表格只是起点值，不是终点。关键是验证手段。vLLM 0.6 以上版本自带了压测命令vllm bench serve，可以直接跑一组基准：

vllm bench serve --model Qwen/Qwen2.5-7B-Instruct \ --tokenizer Qwen/Qwen2.5-7B-Instruct \ --input-len 512 --output-len 256 \ --max-num-seqs 32 \ --max-num-batched-tokens 4096

它会输出吞吐量和延迟分布，我用它快速对比不同参数组合，比自己在 locust 里造数据高效得多。另外，压测时一定要盯着/metrics接口，关注vllm:num_requests_running和vllm:num_requests_waiting两个指标。如果 running 长期低于 max-num-seqs 而 waiting 一直在涨，说明参数没配好，GPU 在空转而不是没有资源。

我这边的最终调整是--max-num-seqs 96 --max-num-batched-tokens 8192，10 并发压测 P95 从 5 秒降到 1.2 秒，OOM 再没出现过。

3. 坑三：重复前缀不缓存，几十路并发全在重复 prefill

3.1 现象：TTFT 高，GPU 算力拉满但吞吐还是上不去

第三个坑是在优化请求延迟时发现的。我们服务的 prompt 结构很固定：一大段几百字的 system prompt，加上几条 few-shot 示例，最后才是用户的真实问题。理论上前面的公共前缀每次都一样，每次请求都应该直接复用，但实测 TTFT（首 token 延迟）一直很高，GPU 计算量看起来也很满，吞吐却没有对应提升。

后来看 vLLM 的日志，prefix cache hit rate 一直徘徊在个位数。也就是说，绝大多数请求都在重复计算同一段 system prompt 和 few-shot，这是巨大的浪费。

3.2 原理：Automatic Prefix Caching 的命中条件，比你想的更苛刻

vLLM 提供 Automatic Prefix Caching（APC），原理是把 prompt 切分成固定大小的 block（默认 16 个 token），为每个 block 计算 token id 的 hash，缓存 KV block。新请求进来时，如果前缀 block 的 hash 和缓存里的一致，就直接复用 KV，跳过 prefill 计算。

听起来很美，但命中条件非常苛刻：必须是 token 级别的前缀完全一致，而且对齐到 block 边界。这意味着三件事：

第一，前缀必须放在 prompt 的最前面，中间不能插入任何变化的内容。如果 system prompt 是固定的，但你在最前面拼了一个"当前时间"或者"request_id"，那第一个 block 的 hash 就对不上，后续所有缓存全部失效。

第二，消息结构必须稳定。在 OpenAI 兼容模式下，vLLM 会把 messages 数组用 chat template 拼成一个字符串，再切 block。如果你这次是 system 在前，下次是 user 在前，或者 system 内容顺序微调，缓存立刻作废。

第三，很多团队忽略的：加载模型时用的 chat template 版本变了，也会导致前缀完全对不上。这个我们踩过，升级 vLLM 后 tokenizer_config.json 的 chat template 被更新了，老缓存全部失效。

3.3 解法：显式开启缓存，把 prompt 结构设计成"前固定后变化"

先说参数。老版本 vLLM 需要显式传--enable-prefix-caching，新版本虽然默认开，我还是建议你在启动脚本里显式写出来，防止版本升级后行为变化：

vllm serve Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --max-model-len 32768 \ --gpu-memory-utilization 0.90 \ --max-num-seqs 96 \ --max-num-batched-tokens 8192 \ --enable-prefix-caching

然后是最关键的结构设计。prompt 应该遵守"前固定后变化"原则：

• system prompt 开头完全固定，不要插时间戳、request_id、随机数。
• few-shot 示例放在 system 后面，位置和顺序保持稳定。
• 变化的业务参数放到 user 消息的末尾，或者在 messages 里作为最后一条消息传入。

举个例子，如果你要传"姓名、诉求"这两个变化字段，不要把单一字符串拼在 system 前面，而是放在 user 的最后：

system: 你是客服助手，规则如下…… user: 我叫张三，我的诉求是查询订单状态。

而不是：

system: 当前用户叫张三，诉求是查询订单状态，下面是客服规则……

前者 system 固定，前缀缓存能命中；后者每个用户都不同，缓存完全失效。

效果方面，我们固定大约 1.5K token 的 system prompt 之后，缓存命中率从个位数提升到 80% 以上。RAG 场景收益更大——把长文档放 system 开头、query 放最后，多个用户问同一篇文档时，文档部分的 prefill 几乎可以完全跳过。这里要提醒一句：多副本部署时 KV cache 是各实例独立的，负载均衡如果随机路由，缓存命中率会被稀释。如果业务对缓存依赖很高，可以考虑在网关层按 system prompt 的 hash 做一致性路由，让相同前缀的请求尽量打到同一个实例。

4. 坑四：长请求堵住短请求，P95 延迟直接失控

4.1 现象：P95 飙升、监控探活误报、503/529 频发

第四个坑是真正上线后才暴露的。短请求压测一切正常，但混合场景一上来——既有几十 token 的短问答，又有几千 token 的长文档生成——P95 延迟直接失控。短请求明明 200ms 就能做完，硬生生等了十几秒。更难受的是，监控系统频繁探活/health，有时候探活都超时，误报服务不可用，触发了一堆无意义的告警和重启。

这种场景在热词里太常见了：503 server overloaded、529 overloaded，全是典型的容量不足或调度被长任务堵死的报警。

4.2 原理：先到先服务的批调度，长任务会挤压短任务

vLLM 的 continuous batching 虽然能动态混合 prefill 和 decode，但整体调度还是偏"先到先服务"。一个长输出序列在 decode 阶段会一直占住max-num-seqs里的一个位置，并且每轮 iteration 至少消耗一个 token 的max-num-batched-tokens预算。

如果长请求大量挤进来，它们会持续占住并发名额，短请求即使先到也可能排不进去；而 vLLM 的 API server 默认会把暂时处理不了的请求放进 waiting 队列而不是直接拒绝，于是等待时间一路累积，P95 就崩了。

另外，探活也会成为帮凶。/health接口本身只检查进程是否活着，但它同样会进入 API server 的处理流程。如果你在高负载时高频调用它，它可能因为排队超时导致误报，而误报触发的服务重启又会把正在处理的请求全部打断，雪上加霜。

4.3 解法：限流入口、拆分长短任务、多副本 + 一致性哈希

针对这个问题，我做了三件事。

第一，在 API 网关层加限流，超过阈值直接返回 429，而不是让请求无限排队。vLLM 本身不擅长做业务级限流，它更倾向于接收所有请求然后尽力调度。对高并发 API 来说，快速失败比无限等待更健康，客户端可以拿到明确信号去重试或降级。用 nginx 做个最简单的并发限制：

limit_req_zone $binary_remote_addr zone=llm_api:10m rate=20r/s; server { location /v1/completions { limit_req zone=llm_api burst=40 nodelay; proxy_pass http://vllm_upstream; } }

第二，把长请求和短请求拆到不同的 vLLM 实例上。长文档分析走一个--max-num-seqs 16 --max-model-len 32768的实例，短问答走另一个--max-num-seqs 128 --max-model-len 8192的实例，互不抢占。这个策略对混合负载非常有效，代价是多部署一套环境，但收益是延迟曲线变得非常平稳。

第三，改造探活和监控方式。不要只靠/health，它只能告诉你进程在不在，不能告诉你处理能力强不强。更可靠的容量信号是/metrics里的 waiting 队列长度。只要vllm:num_requests_waiting持续大于 0，说明实例已经饱和，应该扩容而不是重启。我把告警规则改成了"waiting 持续 10 秒以上"才触发扩容，探活频率从每 1 秒一次降到每 15 秒一次，误报率立刻降了下来。

多副本扩容时还有个小技巧：如果副本数不止一个，网关尽量按用户或者按 system prompt 做哈希路由，这样能最大程度保住跨请求的 prefix cache。最简单的方式是在网关层对messages[0].content取 hash 再对副本数取模，实测能把多副本场景下的缓存命中率保持在单实例的 80% 以上。

这轮部署下来，我的体感是 vLLM 的默认参数能跑通 demo，但离稳定的高并发 API 还差得很远。你真正要做的不是照抄某一组参数，而是先摸清四个数字：业务侧的真实 token 分布、KV cache 预算、单实例并发上限、副本数。这四个数字一旦清晰，大部分故障都能在启动命令阶段提前避开。

最后再分享一个实用建议：所有参数改动都要落到启动脚本的版本管理里，压测结果和参数一一对应。我们后来排查 P95 飙升时，就是靠 git 历史对比才发现某个同学把--max-num-batched-tokens从 8192 调到了 16384，导致长请求大批挤占 batch。没有历史记录，这种问题查起来会非常痛苦。