vllm recipe muse glimmer

你打算用 vLLM 起 Muse Glimmer，多半会卡在几个地方：拉下来的权重格式跟 vLLM 版本对不对得上、量化档位选哪个、max_model_len 和 gpu_memory_utilization 该填多少、并发一上来就 OOM 或者输出变慢。这篇不讲框架原理，只给一套可执行的配方梳理顺序：先确认权重与版本，再按卡算显存和并发，然后落参数、最后按现象排查。具体数字请到站内对应页面按当时口径核对。

用 vLLM 起 Muse Glimmer，卡人的地方通常不是框架本身，而是前置对齐没做好：权重格式跟你装的 vLLM 版本对不对得上、量化档位选哪一档、max_model_len 和 gpu_memory_utilization 该填多少、并发一上来就 OOM 或者输出变慢。这篇不聊原理，只给一套可执行的配方梳理顺序：先确认权重与版本，再按卡算显存和并发，然后落参数，最后按现象排查。

顺序很重要，因为后一步的结论依赖前一步的前提。权重格式没确认就去调并发，等于在错的地基上盖楼；量化档位没定就想算显存，也算不准。文中涉及的所有具体数字，都请到站内对应页面按当时的口径核对，别拿别处的旧数直接套。

第一步：先把权重、格式和 vLLM 版本对齐

这一步没做完，后面全是白费。你手里拿到的可能是原始权重，也可能是别人已经量化好的权重，这两者对 vLLM 的加载路径和显存占用完全不同。拿量化配置去套原始权重，或者反过来，通常不是慢一点，而是直接起不来。

• 确认权重是原始格式还是已量化格式，加载路径和显存占用按哪种走要心里有数
• 比对模型卡里的架构名与当前 vLLM 版本的支持范围，不匹配先升或降版本，别急着调参
• 检查权重目录能否被容器或本地进程读到，走 Docker 注意挂载路径与文件权限
• 模型文件缺片会报加载失败，别误判成显存不足；核对模型自身的上下文上限与许可证条款

加载期报错

服务还没跑起来就失败，多半是格式、版本、路径三类问题

架构名

模型卡里标明的结构标识，vLLM 靠它匹配内置实现

第二步：按卡算显存，再推并发上限

显存别只算权重那一块。实际要吃三部分：权重占用、KV Cache、框架本身与碎片开销。只按权重选卡是最常见的翻车点，模型能装进去，但并发一开就崩。

并发不是拍脑袋定的。用总显存减去权重与开销，再除以单条请求的 KV 占用，倒推出一个上限，然后再留点安全余量。单条 KV 占用跟上下文长度直接相关，具体数值可以在 /models/deploy 的部署测算里按当时口径估。

1. 先量基线用 /tools/speed-test 在你这套环境上跑一轮，拿到延迟底数，别拿别人的数字当自己的基准
2. 小并发压测从低并发起步，记录吞吐与延迟，确认稳定后再往上加，一次只加一档
3. 看拐点并发继续加，如果延迟开始明显抬头或出现 OOM，就退回到上一个稳定档位

第三步：起服务时的参数配方顺序

参数有先后，按这个顺序落，改起来才不会互相干扰。先定 max_model_len，它直接决定 KV Cache 上限，设得比业务实际需要大很多，等于白白吃掉并发空间；再定 gpu_memory_utilization，给 KV Cache 留出余量，压到极限的长请求或并发峰值容易崩。

• 并行方式按卡数配，单卡放不下再上多卡，多卡通信本身有开销，卡数不是越多越快
• 接口层参数与部署参数要分开管，API 侧的超时和并发限制得跟引擎侧匹配
• 前端重试策略要和后端承载能力对齐，否则一次抖动会被重试放大
• 每改一个参数都记录前后数值，方便后面归因，别一次堆三个变量

第四步：出错按这个顺序查，别乱试

排查的关键是先分清故障发生在哪个阶段。加载期报错和运行期报错，根因基本不重叠，混在一起查只会浪费轮次。

• 遇到显存类报错，先降 max_model_len 和并发，再考虑换量化档位，最后才动卡
• 输出乱先怀疑模板与对话格式没对齐，而不是先怀疑模型本身
• 同一现象反复出现就固定变量，一次只改一个参数
• 记录改前改后，把判断依据落到笔记里，避免下次重复踩