vLLM Recipes 不是一个独立模型也不是某个固定版本的功能开关而是一组围绕 vLLM 的部署与优化配方。我第一次看到这个词的时候也在想它到底是一份官方文档还是社区里流传的实战合集跑过几轮之后我的理解是Recipes 更像把环境准备、启动参数、模型格式、并发设置、故障排查这些步骤整理成可复用的模板让你在换模型、换机器、换任务时不用每次从头踩一遍。这篇文章就按实际部署顺序拆一遍先说清 vLLM 能解决什么问题、适合什么人再给环境准备和启动命令接着讲 max-num-seqs、--enforce-eager、--reasoning-parser 这些高频参数的作用最后补充 GGUF、显存爆掉、Embedding/Reranker、Windows 和昇腾环境里的常见问题。如果你正准备用 vLLM 部署大模型或者已经在部署但被参数和报错卡住这篇可以直接照着试。1. 先搞清楚 vLLM Recipes 是什么再开始搭环境1.1 vLLM Recipes 解决的核心问题vLLM 本身是一个面向大语言模型推理的服务框架核心能力是通过 PagedAttention 这类机制降低 KV cache 对显存的浪费提升吞吐。Recipes 是“配方”它不是模型也不是某一个具体工具软件而是一套可复制的操作模板。实战中最大的痛点往往是模型能加载但并发一高就失败换一个模型后参数不知道在哪里改容器里共享内存不够显存爆掉不知道先动哪个参数。vLLM Recipes 想解决的就是把这些零散问题变成一步步能执行的检查清单。简单说它不负责教你训练模型而是负责让你把已经训练好的模型稳定地跑成服务。我一般会先看一份 Recipe 里有没有回答三个问题在什么环境下跑、用哪些启动参数、拿到结果后怎么判断正常。如果这三个点不清晰那这份配方大概率只是写了几个命令后面遇到问题还是要猜。1.2 这套配方适合谁不适合谁适合用 vLLM Recipes 的人有这么几类需要快速起一个 OpenAI 风格接口的人。在本地或云 GPU 上部署开源模型的人。在低显存机器上试小模型的人。要做批量推理或者要把模型接入上层业务的人。想知道 Docker、WSL2、Ubuntu、昇腾这些环境差异的人。不适合的场景也比较明确。如果你主要做模型训练那 vLLM 不是你的核心工具如果完全不能用 GPU那 vLLM 的收益会大打折扣如果只是调用别人已经封装好的 API也不需要自己部署。还有一类是边缘设备或极小显存设备vLLM 不是最优选择这种场景更适合轻量推理框架。1.3 开始之前要确认的硬件和软件底线部署前先把环境检查清楚。很多报错不是代码问题是前置条件没满足。检查项最低建议为什么重要GPUNVIDIA 显卡显存 8GB 起步模型权重和 KV cache 都占显存显存决定模型规模系统Linux 优先其次 WSL2vLLM 的预编译包和 CUDA 依赖在 Linux 上最完整内存16GB 以上更稳加载模型和 tokenizer 时内存不足会先于显存报错磁盘7B 模型约需 15GB13B 约 26GB下载和解压模型都要空间建议预留两倍驱动与 CUDA驱动版本要支持对应 CUDA 环境版本不匹配会在 import 或启动阶段直接报错如果你要跑 27B 这种更大的模型常见情况需要更高显存比如两张 24GB 卡或一张 48GB 卡。只有单卡 24GB 时基本要考虑量化模型或更短的上下文长度。先想清楚这些再进入下面的部署流程会少踩很多坑。2. 环境准备Linux、Docker、Windows 和昇腾的取舍2.1 为什么生产环境优先选 LinuxvLLM 对 Linux 的适配最完整很多预编译包只发布 Linux 版本。Windows 原生安装不是绝对不行但往往要自己编译容易在 CUDA 工具链、MSVC 版本和 Python 环境上绕圈。如果只是学习用 WSL2 或 Docker Desktop 也能跑但如果是长期提供服务建议直接用 Ubuntu 服务器。判断标准很简单启动一个服务能不能用少于十行命令完成重启后会不会依赖图形界面。Linux 服务器配合 systemd 或容器编排管理起来会清晰很多。vLLM 的日志输出、进程停止、资源监控也都更适合命令行环境。2.2 Ubuntu Docker 部署 vLLM 的推荐步骤使用 Docker 部署时模型目录和输出目录最好都挂在宿主机上。这样模型文件不用每次都复制进容器日志和输出结果也方便持久化。一个典型的启动命令如下docker pull vllm/vllm-openai:latest docker run --gpus all \ --ipchost \ --shm-size8g \ -v /models:/models \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model /models/your-model-dir \ --task generate \ --max-model-len 8192 \ --gpu-memory-utilization 0.85这里的镜像名和 tag 是示例实际版本要以你拉到的镜像和模型要求为准。--shm-size一定要给足。vLLM 在并发场景里会用到共享内存容器默认的 /dev/shm 常常只有 64MB几路并发请求一上来就容易报 “No space left on device”。--ipchost可以让容器和宿主机共享 IPC 空间对多进程通信有帮助。注意容器里出现 “No space left on device” 时先看 /dev/shm 是不是太小不要急着扩磁盘。启动后建议先看日志确认模型加载完成、服务监听在 8000 端口。再用一条 curl 请求验证而不是直接开并发。2.3 Windows 10 能不能原生跑 vLLM能但不推荐。Windows 原生跑 vLLM 不是完全不可能前提是 CUDA、PyTorch、Visual Studio 编译环境、Python 版本全部对齐这通常要花不少时间。更顺手的方式是在 Windows 10 上用 Docker Desktop WSL2。这样底层的 Linux 内核、CUDA 驱动都走 WSL2vLLM 的安装路径和 Linux 服务器基本一致踩坑成本低很多。另一种更省事的思路是在 Linux 服务器上部署 vLLMWindows 只做客户端通过 API 调用。对大多数业务形态来说这个方案最稳定也不会被 Windows 原生编译问题拖住。2.4 昇腾 910B-A2 上跑 Embedding/Reranker 的排查思路“昇腾 910B-A2 服务器上不能通过 vLLM 启动 embedding 向量和 reranker 模型”这个问题很多人问过。先说结论vLLM 原生最擅长的是文本生成对 embedding 和 rerank 的支持取决于你使用的分支、扩展版本和任务参数。遇到启动失败不要先怀疑硬件故障按下面顺序排查确认当前 vLLM 是否支持--task embedding或--task rerank这类任务参数。检查容器里是否安装了对应昇腾后端的适配包以及它是否匹配当前 vLLM 版本。看具体报错是模型加载阶段失败还是任务类型初始化失败。这两个问题排查方向完全不同。如果当前版本确实不支持就把服务拆开embedding 和 reranker 用专门框架部署生成模型继续用 vLLM。embedding 和 rerank 是向量检索链路中的一环它们对批处理方式、推理缓存和生成模型都不一样硬合在一起反而容易互相干扰。实际项目里我更倾向于把这类任务拆成独立服务哪怕只是为了让后续扩容和压测更清晰。3. 启动模型前必须搞懂的参数max-num-seqs、enforce-eager、reasoning-parser3.1 --max-num-seqs 控制什么很多人把--max-num-seqs理解成“最大请求数”其实它控制的是同一时刻最多排进调度器的序列数量。可以简单理解为“模型内部最多同时处理多少条 prompt 轨迹”。它和--max-model-len不是一回事--max-model-len限制单条序列的最大长度--max-num-seqs限制并行的序列数量。调大这个值吞吐通常会上去但显存和调度压力也会同步增加。如果你在做批量推理时发现显存不够先把--max-num-seqs降到 4 或 1 再观察而不是一上来就换小模型。如果模型本身很吃显存保持 1 到 2 更稳。注意不要一上来就把 max-num-seqs 拉满先用 4 验证稳定性和显存占用再逐步往上加。3.2 --enforce-eager 的影响vLLM 默认会通过 CUDA Graph 捕获计算图来降低调度开销。--enforce-eager是把这个优化关掉强制所有算子走 eager 模式。影响有三点首次请求的编译时间变短因为不用等待 CUDA Graph 捕获。显存占用会有所下降适合显存比较紧的环境。代价是解码路径缺少图优化可能带来更高的单 token 延迟和吞吐下降。所以不要看到“能降显存”就默认要开。生产环境如果显存刚好够用先不开--enforce-eager等确认了吞吐指标再决定。有些容器或远端环境 CUDA Graph 捕获会失败此时加上这个参数可以减少启动阶段的问题。它更像一个兼容开关不是通用加速器。3.3 --reasoning-parser 解决什么问题--reasoning-parser是给带推理能力的模型准备的。比如模型输出里有一段思维推导再给出最终答案这个参数能帮助把推理段落从最终回答中解析出来。注意它解决的是输出解析问题不是提升模型推理能力。如果模型本身不输出结构化推理文本或者你的应用不关心推理过程不需要开这个参数。开启后如果输出格式变了先确认你的 prompt 和 chat template 是否匹配不要怪模型变笨了。3.4 显存不够时的第一排查顺序加载 9B 级别模型爆显存或者换更大上下文后 OOM优先按这个顺序排查看nvidia-smi确认显存是被权重占掉还是被 KV cache 占掉。降低--max-model-len例如从 8192 降到 4096。显存不够时这是最直接的一步。降低--max-num-seqs限制并发。调整--gpu-memory-utilization比如 0.9 改成 0.8给 KV cache 留出余量。再考虑开--enforce-eager。最后才换量化模型。这个顺序的原因很简单前四步是在同样的模型权重下减少动态内存分配不会改变输出质量。换量化模型会改变精度应该放在最后。4. 模型格式和量化GGUF、safetensors、9B 模型爆显存4.1 vLLM 加载 GGUF 的真实情况vLLM 对 GGUF 的支持是有的但没有 safetensors 那么完整。很多模型发布时会同时给 safetensors 和 GGUF 两种格式。如果你的 vLLM 版本确认支持用--load-format gguf加载可以试vllm serve /models/model.gguf --load-format gguf --max-model-len 4096但要注意GGUF 主要围绕 llama.cpp 系列推理工具设计vLLM 的加载路径在算子支持、量化参数解析和历史版本上可能有差异。如果你遇到“能加载但输出不正确”或者“加载到一半报格式错误”先确认模型卡上推荐的加载方式和当前 vLLM 版本。正式项目里我更建议优先用 safetensors 格式省去格式兼容带来的额外变量。真需要 GGUF 时也可以考虑直接用 llama.cpp 的服务端不要在一棵树上吊死。4.2 加载 9B 级别模型爆显存时先做什么一个 9B 模型如果用 BF16 加载权重大约需要 18GB 显存。这还没算 KV cache、激活值和调度器开销。所以你在 24GB 显卡上跑感觉“刚好能跑”其实已经很紧。此时如果--max-model-len设置成 8192它会给每条序列预留较大上下文空间几批请求后就会爆。第一步先把上下文长度降下来比如从 8192 降到 4096 或 2048再跑一轮测试。第二步把--max-num-seqs改成 1 或 2观察显存占用。如果这样能跑说明你只需要在质量、速度和显存之间重新取平衡不一定要换模型。如果降到 2048 仍然爆再考虑量化。4.3 量化方案怎么选常见量化方案有 AWQ、GPTQ、FP8也有少量 GGUF 量化。它们的取舍可以这样看格式适用场景注意事项BF16显存充裕追求精度占用最大FP8较新硬件速度与精度平衡需要硬件支持AWQ低显存部署通用性好需要准备量化权重目录GPTQ低显存部署社区模型多不同 step 和 group size 效果有差异选量化模型时记得同时下载对应的 tokenizer 和配置文件。很多启动失败不是推理引擎问题而是模型目录不完整或格式不统一。如果原始材料里没有明确说某个量化版本适合你的任务先用小输入验证输出质量再决定是否迁移。5. 框架定位vLLM 和 SGLang、LangChain、PyTorch 不是同一层5.1 vLLM 和 SGLang 的对比点SGLang 和 vLLM 都是大模型推理服务框架定位接近但偏好不同。vLLM 生态更成熟资料多社区默认支持广。SGLang 在某些场景下对长文本、结构化输出和并行采样做了专门优化所以在一些新模型发布时会看到“推荐用 SGLang”的说法。实际选型时不要只信宣传。用同一个模型、同一批请求、同样显存限制分别在两个框架上跑对比启动时间、吞吐、延迟和能不能稳定跑完任务。如果只是单机部署一个 7B 或 9B 模型两个框架都能应付差异主要在你的任务负载和模型兼容性上。我的建议是先把你常用的输入样例跑通再决定要不要迁移。不要因为某个新功能就立刻切换框架稳定性更重要。5.2 LangChain、vLLM、PyTorch 分别解决什么问题经常有人问“LangChain、vLLM 跟 PyTorch 是一个类型吗”它们不是同层的东西。PyTorch 是深度学习计算框架负责算子、自动求导和模型训练。vLLM 是基于 PyTorch 的推理服务框架负责把训练好的模型高效地部署成 API。LangChain 是应用层编排工具负责把模型调用、提示词、工具调用和外部数据串成流程。可以简单类比PyTorch 是发动机vLLM 是整车LangChain 是导航和出行计划。用 LangChain 接 vLLM通常应该调用 vLLM 暴露的 OpenAI 兼容 API而不是在 LangChain 内部直接操作 vLLM 的底层引擎。6. 从单条请求到生产服务Playground、API 和验证6.1 用 Playground 或者 /docs 验证很多仓库会放一个叫 Playground 的前端页面但 vLLM 本身最稳的验证通道不是某个固定 UI。启动服务后打开http://127.0.0.1:8000/docs会看到 Swagger 文档可以直接在页面里发请求。更简单的做法是用 curl 检查curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: /models/your-model-dir, messages: [{role: user, content: 你好}], max_tokens: 128 }返回的 JSON 里如果有choices字段基本说明服务通了。如果请求卡住或者返回空先看服务日志再看输入格式不要急着改模型参数。很多“服务不通”的问题其实是模型目录不对、端口没监听、或者请求里 model 名称和启动参数不一致。先把这些基础