你已经在用 vLLM 起服务，但每次换个模型或换张卡，还是得回头翻仓库里那一堆示例，看哪个跟自己的情况最接近。配方（recipes）不是教程，是「官方验证过的配置组合」，照着抄能少踩不少坑，抄错了也容易卡在权重不匹配或参数对不上。这篇给的是一个查阅顺序：先按任务分类，再按硬件和量化方式缩小范围，最后落到具体参数怎么核对。
vLLM 的官方配方仓库（recipes）跟 examples、docs 不是一回事。examples 教你怎么调某个接口，docs 讲参数含义，而 recipes 是「模型 + 硬件 + 参数」组合起来跑通过的现成方案，相当于别人替你试错过的配置清单。你换了模型或换了卡，直接翻配方往往比对着文档一条条拼参数快得多。
这篇不重复讲 vLLM 怎么装，只给一个查阅顺序：先按任务分类找对应目录，再用硬件和量化方式缩小范围，最后落到参数逐项核对。需要具体数字的时候，一律去站内页面看当时的情况，别拿别人机器上的显存值当通用标准。
配方仓库到底解决什么问题
配方存在的意义是缩短你从「模型支持」到「服务能稳定跑」之间的路。它把权重来源、并行策略、量化格式、上下文长度这些容易互相打架的东西提前绑成一套，你抄的是组合，不是单个命令。所以判断要不要看配方，看的是你的组合有没有偏离常见路径。
- 新模型刚发布、你还没见过它的权重目录结构，配方里通常已写清该从哪加载、需不需要转换
- 换卡换架构，尤其是国产卡或多机多卡，配方里的适配分支和已知限制能省掉一轮试错
- 要上并发、关心吞吐和显存占用，配方给的并行与显存基线可以直接当压测起点
- 反过来，模型在支持列表里、你只想先把本地权重跑起来，用官方最小启动命令更快，不必先扒配方
按场景定位：三类需求对三类配方
翻仓库前先给自己的需求归个类，能少翻一大半目录。下面这张表是三类典型需求与你要重点看的内容对照，找目录时按第一列去筛，第二列决定你读配方时先看哪几段。
| 你的需求 | 先看配方的哪部分 | 判断是否适用的信号 |
|---|---|---|
| 单一模型快速起服务 | 权重来源、量化格式、上下文长度设置 | 配方里的模型名和量化格式跟你的权重一致 |
| 硬件适配（国产卡、多机多卡） | 专门的适配分支、已知限制说明 | 明确列出支持或不支持的功能项，而不是只给命令 |
| 性能与并发调优 | 并行策略、显存参数、批处理相关设置 | 给出的是基线配置加调优方向，而非唯一固定值 |
- 先按任务筛目录把需求归到上表三类之一，只进对应类目录，别从仓库根目录一路点下去。
- 再用硬件和量化缩小同名模型可能有多份配方，按你的卡代次和量化格式挑最接近的一份，跨代直接抄是主要翻车来源。
- 最后核对版本对齐确认配方假定的 vLLM 主版本、权重版本、驱动与 CUDA 代次跟你环境同代，具体数字到站内资料库页面核对当时的值。
抄配方前的四项核对清单
找到最接近的配方之后，别急着整段复制。先做四项核对，能挡掉大部分「照抄却起不来」的情况。核对的重点不是记住数字，而是搞清每个关键参数为什么存在。
| 核对项 | 怎么核 | 不通过时的后果 |
|---|---|---|
| 版本对齐 | vLLM 主版本、权重版本、驱动与 CUDA 代次是否同代 | 参数名对不上、算子编译失败或权重加载报错 |
| 参数可解释 | 逐项问「不写会怎样」，再决定抄不抄 | 把别人的显存数字当通用值，换机器就 OOM |
| 依赖与镜像 | 配方给的镜像标签和额外依赖一起看 | 只抄命令行漏掉预编译算子，启动即失败 |
| 失败归因 | 先分清是权重加载问题还是显存与并行配置问题 | 按错误方向排查，浪费大量时间 |
排查顺序建议固定下来：先看权重能不能被正确识别，再看显存够不够、并行度是否合理，最后才动性能参数。顺序反了，很容易在前面几步没排干净时就调吞吐，越调越乱。
# 起服务时把日志留住，失败先看权重加载段落，再看显存与并行相关报错
vllm serve <你的模型路径> --tensor-parallel-size <按你的卡数> 2>&1 | tee serve.log什么时候别照着配方抄
配方再全也有它覆盖不到的地方。下面几种情况，把它当参考而不是模板，反而更省事。
- 你的卡和配方里的卡不同代：并行度与显存切分参数基本都要重算，直接抄大概率 OOM 或跑不满
- 量化格式与官方权重不一致：配方里的加载参数不适用，要回去看该量化方案自己的说明
- 追求极限吞吐：配方给的是能跑通的基线，调优得自己压测并逐步改参数，别指望抄一份就到位
- 模型权重经过你二次合并或裁剪：配方假定的结构已经变了，参数需重新验证
配方帮你跳过的是「前人踩过的坑」，不是「你这台机器的账」。
最后提醒一句：配方仓库更新频率不低，你半年前抄过的配置，换了个主版本可能就不适用了。每次重新上手前，花几分钟看一眼目标配方最近改了什么、适配的卡和量化方式有没有变，比事后查报错便宜得多。
下一步配方选好后，先把当前各家中转站与官方 API 的实际价格、可用模型情况核对一遍，再决定哪些模型走官方、哪些走中转；站内价格追踪页按当时的数字更新，别用旧截图做决策。→常见问题
vLLM 的 recipes 和 examples 有什么区别，我该看哪个？
examples 是单个功能的最小演示，比如怎么调某个参数、怎么写请求；recipes 是成套方案，针对某个模型加某类硬件给出一组能跑通的组合。想快速验证接口用法看 examples，想少试错地把模型在特定卡上跑起来看 recipes。两者经常互相引用，顺着一路点过去就行。
照着配方抄还是报错，一般先查哪里？
按这个顺序：先确认权重的版本和格式跟配方是否一致，再看 vLLM 主版本是否对得上，第三步看显存和并行参数是不是按你自己卡的数量重算过。前两步对不上属于「抄错对象」，第三步对不上属于「抄了别人的机器」，性质不同，修法也不同。
配方里没有我用的模型或卡怎么办？
没有对应配方不等于跑不了，只是没人替你验证过组合。可以退回到 vLLM 的模型支持列表确认模型结构是否被支持，再自己按最小命令起一遍，从一个并行度和保守的上下文长度开始，逐步加压测。跑通之后把参数记下来，下次换卡再按同样思路重算一遍。
