1. 坑一max-model-len 拍脑袋设 32K显存先爆了1.1 服务起不来的现场先说第一次翻车。当时是帮业务方部署一个 72B 的对话模型机器是 8 卡 A100 80G。业务提的需求很直接“用户可能会贴长文档进来上下文至少给到 32K。”我想都没想启动命令里直接写了--max-model-len 32768 --gpu-memory-utilization 0.9。结果模型权重倒是加载进去了但 worker 进程在初始化 KV cache 的时候直接CUDA out of memory一个卡都没活下来。折腾了一晚上后来把gpu-memory-utilization降到 0.7还是不行因为问题根本不在这个参数。这个坑的本质是很多人把max-model-len当成一个“软性配置”以为它只是限制输入长度上限。实际上它是 vLLM 启动时预分配显存的核心依据之一。1.2 KV cache 增长的数学账要理解这个问题得算一笔账。Transformer 推理时每个请求的每个 token 都要为每一层、每一个 KV head 保存一份 Key 和 Value 向量这就是 KV cache。单 token 的 KV cache 占用可以用这个公式估算KV cache 字节数 / token 2 × num_hidden_layers × num_kv_heads × head_dim × dtype_bytes以 Qwen2.5-72B-Instruct 为例num_hidden_layers 80num_key_value_heads 8head_dim 128用 BF162 字节推理2 × 80 × 8 × 128 × 2 327,680 字节 ≈ 320KB / token也就是说一个请求的上下文只要有 32K token就要占掉约 10GB 显存。72B 模型本身的权重用 BF16 大概是 144GB8 卡均匀分布后每卡 18GB 权重。每张 80G 卡刨掉权重还剩 60G 左右看起来 10GB 似乎也放得下别忘了vLLM 是给所有并发请求共享 KV cache 池的。假设来了 100 个并发请求每个请求的 PV 都接近 32K那就需要 1000GB 的 KV cache 空间——8 张卡全加起来都不够。启动时 vLLM 会按max-model-len × max-num-seqs的极限值去预留显存所以即使是空跑只要这两个参数乘出来的数字超过显存余量服务就起不来。1.3 怎么设才合理我后来给自己的部署定了一个公式化的流程先回答三个问题再填参数业务真实的输入 token 分布是什么看 P99不看最大值。期望的并发上限是多少不是“用户量”是同一时刻在推理的序列数。显存里除了权重和 KV cache要不要留空间给--cpu-offload-gb或 LoRA 权重确认完这些再倒推max-model-len。我当时把 32K 砍到了 16Kmax-num-seqs设为 128再算 KV cache 预算320KB × 16384 × 128 ≈ 655GB8 张 A100 80G 每卡 80G权重占 18G剩余 62GKV cache 摊到每卡大约 82G——还是超。最后是把gpu-memory-utilization调到 0.85max-num-seqs降到 96才稳定跑起来。说句实话如果业务真的要求百万 token 上下文类似最近看到那种 1048576 context 的报错单靠调max-model-len是撑不住的。那种规模得上 P-D 分离 多机 KV cache offload 或者稀疏注意力已经不是一个启动参数能解决的问题了。自部署场景下先摸清自己的显存预算再定上下文长度这是最基础的认知。2. 坑二并发从 50 提到 200TTFT 全线飘红2.1 压测数据里的分裂现象服务跑起来之后进入了压测阶段。我们用 locust 打流量先看 QPS发现并发从 50 提到 200QPS 从 110 涨到了 230看起来好像“扩容有效”。但客户端另一边反馈首 token 延迟已经无法接受了并发数TTFT首 token 延迟TPOT每 token 耗时QPS500.4s35ms1101002.8s52ms19020012.6s88ms230TPOT 涨得不算夸张但 TTFT 直接翻了 30 倍。用户体感就是打几个字就开始转圈半天不出第一个字。页面上的超时重试机制一触发请求又叠进来雪球越滚越大。这个现象很多人遇到过但没有意识到问题出在 vLLM 的调度机制上。2.2 vLLM 调度机制里藏着的原因vLLM 使用的是 continuous batching它把 prefill首轮计算读全部 prompt 生成第一个 token和 decode后续逐 token 生成放在同一个调度周期里处理。问题在于prefill 是计算密集型的一个长 prompt 的 prefill 可能吃掉几百毫秒甚至几秒的 GPU 算力而 decode 是访存密集型的每个 token 只做一次前向的一小步。两者混在一起跑时新请求的 prefill 会和老请求的 decode 抢同一个 Scheduler 的 step。默认情况下Scheduler 倾向于先把攒够max-num-batched-tokens的 token 一次性塞进一次 step这时候老请求的 decode 节奏被强行拉长等 prefill 做完老请求才能继续。并发越高、排队越久每次 step 里 prefill 占用的比例越大decode 的持续生成被频繁打断TTFT 自然就起飞了。还有一个隐藏因素vLLM 的默认抢占策略是回退swap或重算recompute。当max-num-seqs满了新请求进来会抢占旧请求的 KV cache 块被抢占的序列要么被 offload 到 CPU要么标记为 recompute。如果是长对话、多轮请求抢占一次的成本非常高TTFT 会瞬间翻几倍。2.3 解法的优先级排序这个问题不是加机器就能立刻好的我按生效成本从低到高排一下限流在 gateway 层限制并发请求数不要让超过 vLLMmax-num-seqs的请求同时涌入。超出的请求返回 503 或者排队等待。很多人担心 503 会影响体验实际上合理的 503 retry-after 比无限堆积让所有人卡死要健康得多。开启 chunked prefill--enable-chunked-prefill会把大 prompt 的 prefill 切成小块插在 decode 之间执行。这样每次 step 的时间不会被单个大 prefill 拉爆TTFT 的抖动会小很多。代价是长 prompt 的总体 prefill 时间可能变长但对在线服务来说稳定性更重要。限制单步 token 量--max-num-batched-tokens不要设太大一般 40968192 比较合理。它直接约束了单次 forward 的总 token 数防止 prefill 一进来就把整帧 GPU 时间吃完。彻底方案是 P-D 分离prefill 和 decode 分实例跑。这是目前大规模推理服务的主流做法。prefill 实例用更少的卡专注处理 promptdecode 实例用更多卡专注续写。两者之间通过队列通信。vLLM 虽然也有相关支持但运维复杂度明显高一个级别小规模部署不建议一上来就搞。我在实测里先做了 1 和 2把max-num-seqs压到 128并发 200 时 TTFT 从 12.6s 降到了 2.1s已经能接受了。如果还卡再考虑物理拆分。2.4 别只看 GPU 利用率最后提醒一句vLLM 的 /metrics 里有vllm:time_to_first_token_seconds和vllm:num_requests_running这类指标压测时一定要盯着看。GPU 利用率接近 100% 不代表“高效”也可能是 prefill 风暴把算力全占了。判断系统健康度必须以 TTFT 和 TPOT 为准而不是只看利用率。3. 坑三开了一周的 prefix cache命中率不到 2%3.1 缓存没生效的表现这个坑是我在一次 RAG 知识库项目里踩的。当时所有用户请求都带一段很长的固定系统提示词后面接检索到的文档片段。我心想这种场景简直是 prefix cache 的完美对象于是开了--enable-prefix-caching还把 system prompt 尽量写得长一点、固定一点。结果一周之后看监控prefix cache 的命中率长期在 1%2% 之间徘徊。等于白开。一开始我怀疑是版本不支持后来挨个排查才发现问题比想象中要多。vLLM 的 prefix caching 是精确匹配它把 KV cache 按物理块block组织每个 block 默认 16 个 token。只有当请求的 token 序列前缀与缓存中已存储的 block 完全一致时才能命中并跳过这部分 prefill 计算。也就是说只要动态参数放在 prompt 的最前面哪怕只有一个时间戳或 trace_id 不同第一个 block 就对不上后续所有相同的系统提示词全部 miss。3.2 真实场景里常见的三种“断前缀”写法排查下来业务代码里有三类常见写法会导致前缀半天对不齐动态字段放在系统提示词之前。例如有些 SDK 会在 messages 头部自动插入 request_id 或 timestamp这些字段每一次请求都不同直接把前缀打断了。多轮对话里把历史记录拼在系统提示词后面、用户最新问题之前。历史记录本身就因对话而异整个前缀自然全变。同一段 RAG 文档每次被检索出来后 token 化结果不同。比如中间插入了换行符、空格或者文档顺序由检索得分动态排序前缀对不上。3.3 优化命中率的实操方法既然根因是前缀不一致解法就围绕“让公共前缀尽量长、尽量稳定”来做把动态内容后置。所有带时间戳、随机 ID、用户标识的字段放到 prompt 末尾前面只保留完全确定的系统提示词和固定知识片段。对 RAG 场景优先把检索文档放在用户问题之前并且固定文档间的分隔符格式。同一个知识库如果被不同人频繁问类似问题文档部分命中后收益会非常可观。检查 chat template。OpenAI 兼容接口下messages 转 prompt 是通过--chat-template指定的 jinja2 模板完成的。如果你用默认模板但业务侧在消息里塞了name字段不同请求可能 token 化出不同的角色前缀。最好固定模板并在本地把同一个 prompt 跑两次 tokenizer 对比输出。如果命中率还是上不去可以调整 block 大小。vLLM 默认--block-size 16改成 32 或 64 能让一次命中的粒度变大。但代价是内存浪费率上升一个 block 如果只用了 10 个 token剩下的 22 个 token 空间就当垃圾空着。是否划算要用真实流量测。另外说一个认知上的盲区prefix cache 节省的是 prefill 算力不是显存。即使全部命中KV cache 该占的内存还是占着。所以千万别把这个功能当成“解决显存不足”的方案。对于短 prompt 为主的业务命中收益很小开了也就图个心理安慰。4. 坑四升级 0.23.0 后 batch 推理“张冠李戴”4.1 错乱的响应内容这是我个人觉得最该写的一个坑因为它是服务“看起来没挂但返回的内容是错的”。当时我把推理服务从 vLLM 0.22.5 升级到 0.23.0回归测试只跑了单请求的冒烟用例一切正常。等并发跑到 120 左右时业务方反馈出现了“串答案”——问 A 的问题返回的是 B 的开头继续追问输出又变成重复片段、断在句子中间。最要命的是日志里完全没有任何报错HTTP 状态码也是 200。你用 curl 单独测任何一个请求都是正常的只有并发上去才复现。4.2 排查过程一步步定位到 chunk_size这个问题的定位过程我一直记着因为是典型的“低并发永远测不出来、高并发偶发触发”的 bug。排错顺序大概是这样的第一步先确认不是业务侧的问题。把出错的请求和响应都打了日志发现内容里混入了另一个请求的输出片段。为了确认我在返回的文本里搜索了另一个请求 prompt 中出现的高频词确实命中了。第二步验证低并发下是否稳定。把并发降到 1连续跑同一个 prompt 100 次输出完全一致。说明不是模型权重或采样参数的问题。第三步怀疑采样阶段。错乱的样本有一个特征输出总是从某个中间 token 开始像是采样时拿错了序列的 logits。vLLM 在 continuous batching 里会批量采样每个序列都有自己的 logits 块如果 logits 的索引偏移就会把 A 序列的 logits 送到 B 序列的采样器里。第四步翻版本变更和 issue 讨论。热词里一直有人提 “vLLM 0.23.0 chunk_size bug”顺着这条线索查发现 0.23.0 里 chunked prefill 路径确实存在一个和chunk_size相关的回归会在大并发、开启 chunked prefill 时偶发导致 logits block 错位。关闭--enable-chunked-prefill后同样的并发量不再复现。4.3 生产和版本策略教训这类 bug 暴露出来的不是某个参数的问题而是部署策略上的问题。我现在给团队定了几条纪律第一生产环境锁定 minor 版本小版本升级最多在同 minor 内打补丁。新版本先在一个单独的 shadow 环境跑几天用真实流量镜像验证再考虑切换。第二升级后必须跑“混合 prompt 并发回归”。具体做法是准备 10 个不同主题的 prompt并发 200 循环请求然后检查每个 response 里是否包含其他 prompt 的特征词。这个脚本很简单但能抓到大部分“串答案”类问题。第三对关键业务增加一层语义哨兵。比如在网关层对输出做一次轻量校验发现响应文本里包含不应出现的其他会话特征词时直接让请求失败重试而不是把错误结果返回给用户。从那次之后我再碰见“偶发错乱”类的问题第一反应就不再是查模型权重、调采样温度而是先怀疑框架层和调度层。这个思维转换可能比任何参数调优都值钱。5. 上线前值得抄走的调优清单四个坑都说完最后放一套我目前部署新模型时直接用的步骤和模板。有需要可以照着抄根据自己的显存和业务改一下参数就行。5.1 一个基础启动配置模板以 8 卡 A100 80G / 7B 模型为例我常用这套参数vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --served-model-name qwen25-7b \ --max-model-len 16384 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 128 \ --max-num-batched-tokens 8192 \ --enable-chunked-prefill \ --enable-prefix-caching \ --block-size 16几个参数按场景微调的方向短对话为主max-model-len降到 8192KV cache 占用更少能支撑更高并发。长文档 RAG 多max-model-len保持 16384 或以上同时打开--enable-prefix-caching并且保证动态字段放在 prompt 尾部。并发尖峰明显适当调低max-num-seqs宁可排队也不要让请求全部堆进显存导致 OOM。如果模型支持 GQA 并且 KV head 比较小KV cache 的占用会低很多max-num-seqs可以相应调大。5.2 上线前的三道检查我的标准流程是部署完之后不急着接真实流量先跑三件事多梯度压测并发 10 / 50 / 200 各跑 10 分钟记录 TTFT、TPOT、QPS。观察 TTFT 是否随并发线性恶化如果有明显拐点回头调max-num-seqs和max-num-batched-tokens。缓存命中验证用固定的 system prompt 动态 query 请求 100 次查看监控中 prefix cache 命中率是否明显上升。如果没变化说明前缀没有对齐需要改 prompt 结构。版本回归锁定当前 vLLM 版本号跑一遍混合 prompt 并发测试确认没有语义串扰。之后每次升级都要重新跑。5.3 日常运维需要盯的指标上线后建议把 vLLM /metrics 里的这几个指标接到告警平台vllm:num_requests_running和vllm:num_requests_swappedswapped 数值突然变高说明 preemption 频繁需要降并发或加显存。vllm:kv_cache_usage_percent超过 90% 就要警惕 OOM 风险。vllm:time_to_first_token_secondsP99 超过业务容忍线时优先检查调度配置而不是盲目扩容。最后分享一个不算技巧但很重要的体会部署开源大模型成 API真正的难点不是“让它跑起来”而是“让它在流量压力下还保持正确和稳定”。这四个坑里前两个是规模之坑多算显存、多看指标就能躲开后两个是心智之坑得靠流程和预案才能兜住。希望这篇能帮你少熬几个夜。