关于 vLLM 的疑问我最近一次看到这么密集是在一堆部署咨询里。有人拿昇腾 910B-A2 问为什么通过 vLLM 启动 embedding 和 reranker 模型不行有人拿 Windows 10 问能不能直接跑还有人盯着启动命令里的--enforce-eager、max-num-seqs反复确认到底哪些参数该开哪些不该开这些问题的表面症状完全不同但追问到底层其实都在问同一件事vLLM 到底应该在什么条件下、以什么方式使用才能有一个可预期、可重复、可维护的结果我把这类问题的答案整理成一套“vLLM Recipes”。Recipes 不是菜谱也不是命令手册而是把一次成功的临时操作固化成匹配场景、模型、硬件和运行参数的启动与运维方案。真正值钱的不是 vLLM 这个引擎本身而是你围绕它沉淀下来的配方。单次跑通不算会用稳定、可控、可解释才算。这篇文章不打算讲 vLLM 的全部 API那没有意义。我想沿着最常被问到的几个真实场景把环境、参数、模型格式、排障路径和工程化方法拆开讲清楚最后给你一个可以直接复用的配方卡模板。1. 先搞清楚 vLLM 处在哪一层很多问题就不会乱1.1 vLLM 是一个推理服务引擎不是一个万能模型加载器很多人第一次接触 vLLM是看到“它能加速推理”。这句话没有错但容易造成一个误解好像只要是模型丢给 vLLM它都能启动、都能提速。真实情况要窄得多。vLLM 的优化重点是生成式大模型的在线和批量推理。它通过 PagedAttention 管理 KV Cache通过 continuous batching 提升吞吐把 GPU 上千变万化的请求调度成密集计算。这些优化只对“自回归生成”这一类任务有直接意义。遇到 embedding、reranker、分类这类非生成式任务vLLM 不是不能碰而是它的设计重心不在那里支持度和稳定性都会差很多。所以你问“能不能在昇腾 910B-A2 上通过 vLLM 启动 embedding 和 reranker”我不能拍胸脯说“可以”或“不行”。从社区反馈和工程经验看这类需求不顺利是常见现象。原因往往不是单一可能是硬件适配层没有覆盖这些模型结构可能是某个算子在 NPU 上缺失也可能是官方支持矩阵里根本没有把这类任务列为目标。你要做的不是去硬改 vLLM而是先去确认你的硬件、vLLM 版本、模型结构三者是否在一个被验证过的组合里。1.2 和 PyTorch、LangChain 不在同一个层热词里有人问“LangChain、vLLM 跟 PyTorch 框架是一个类型吗”这是个好问题。它们都在 AI 技术栈里但属于不同层也解决不同问题。PyTorch 是最底层的深度学习框架之一。它负责张量运算、自动求导、模型训练和模型执行的基础能力。vLLM 的底层也依赖 PyTorch但不是取代关系。vLLM 是面向推理部署的服务引擎。它拿到一个已经训练好的模型做服务化封装、推理加速、请求调度、并发管理。你可以不写任何训练代码只需要指定模型路径和启动参数就能得到一个 HTTP 服务。LangChain 则更高一层属于应用编排框架。它负责把模型、工具、检索、记忆拼成一条应用链路。它调用的是模型的能力至于是通过 vLLM 接口调用还是通过 OpenAI 风格接口调用LangChain 不关心。三者不是二选一的关系。常见组合是PyTorch 负责训练vLLM 负责模型推理服务LangChain 负责上层应用编排。同样和 vLLM 经常放在一起比较的 SGLang也和 vLLM 属于同一层都是大模型推理服务引擎。区别更多体现在性能优化的侧重、支持的模型范围、调度策略和生态成熟度上。选型时不要只盯着 benchmark还要看团队的维护能力。1.3 为什么“能不能跑”很难一句话回答准确评估一个模型在 vLLM 上能不能跑至少要确认四件事模型结构和 tokenizer 是否被 vLLM 支持。模型格式比如 safetensors、GGUF、AWQ、GPTQ是否被当前版本支持。硬件平台比如 NVIDIA、AMD、昇腾是否有对应适配。你的输入输出方式是否符合该模型的推理任务类型。这四个条件只要有一个不满足就可能出现“模型能加载但输出乱码”“启动报算子错误”“请求排队但没结果”等故障。所以遇到“能不能跑”的问题先查支持矩阵不要直接拿生产流量去试。2. 先搭一个“正经”的部署环境再谈参数2.1 为什么 Windows 不是首选热词里有人问 vLLM 能不能在 Windows 10 中使用。从工程经验看官方主线更多面向 Linux 环境Windows 不是首选部署平台。如果你只是做代码阅读或小规模调试可以尝试 WSL2 或 Docker Desktop 的方案但要接受几个现实GPU 透传依赖 WSL2 加 NVIDIA Windows 驱动配置不复杂但性能和稳定性可能不如原生 Linux。vLLM 依赖的编译链路和算子库在 Windows 原生环境里更容易遇到兼容问题。社区大多在 Linux 下排查问题你遇到一个 Windows 专属报错能参考的资料会少很多。所以我的建议是如果你只是先验证效果用 WSL2 或远程 Linux 服务器都行如果要长期部署不要纠结直接用 Ubuntu 加 Docker 这类方案。2.2 Ubuntu 24.04 下的依赖顺序Ubuntu 24.04 部署 vLLM最容易出问题的不是 vLLM 本身而是环境依赖顺序。通常按这个顺序检查系统里是否安装了 NVIDIA 显卡驱动nvidia-smi是否能正常输出。驱动对应的 CUDA 能力是否满足 vLLM 要求的版本。这里不建议手动装系统级 CUDA 后去覆盖很多问题都是版本冲突引起的。如果使用 Docker要确认 NVIDIA Container Toolkit 已经安装并且 Docker 能识别gpus参数。Python 版本是否符合 vLLM 当前版本要求。不同版本对 Python 的支持范围不同不要默认 3.12 一定没问题。显存容量和共享内存设置。如果你在装完驱动后运行nvidia-smi可以看到 GPU但 Docker 里执行nvidia-smi报错“could not select device”大概率是 NVIDIA Container Toolkit 没装好或者 Docker engine 需要重启。另外很多人拿着 RTX 2080 Ti 这类 11GB 显存卡去跑 27B 甚至更大的模型结果自然是 OOM。这不是 vLLM 的问题而是模型规模和硬件匹配的问题。要么换小模型要么做量化要么换卡。在做任何调参之前先估算一下模型权重在当前精度下到底要占多少显存比盲目找参数更有效。2.3 Docker 启动示例在 NVIDIA GPU 环境下一个常见的 vLLM Docker 启动命令长这样。注意这只是结构示例实际版本号、镜像名和参数要以你确定的版本为准。docker run --gpus all \ -v /data/models:/models \ -v /data/cache:/root/.cache \ -p 8000:8000 \ --ipchost \ --shm-size2g \ vllm/vllm-openai:latest \ vllm serve /models/Qwen3-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85这里有几个容易忽略的细节--ipchost和--shm-size是共享内存设置。有些数据集加载或数据处理依赖共享内存太小会导致进程崩溃。--shm-size2g只是示例数据量大时可以调大但不要盲目拉满。模型目录用只读挂载更稳妥可以在-v后追加:ro防止运行时误写模型文件。端口映射要注意容器内端口和 host 端口别搞反。2.4 昇腾等 NPU 环境要单独确认适配层关于昇腾 910B-A2 这类 NPU 环境vLLM 不只是一个 pip 包那么简单。跨硬件推理需要相应的运行时和算子适配层。这意味着你使用的 vLLM 版本必须是带对应后端适配的分支或插件版本。模型结构需要在该后端上做过算子验证。很多社区案例是在一个非常具体的版本组合上跑通的换一个版本就可能失败。所以遇到昇腾上跑不动的问题不要急着怪 vLLM。先检查当前 vLLM 是否包含目标硬件的后端再看模型里的自定义算子是否受支持。如果有官方支持矩阵表以表为准如果没有找一个验证过的镜像或版本组合比自己去编译源码省力得多。2.5 环境检查清单一个可控的环境应该具备这些特征驱动、容器运行时、Python、vLLM 版本都在一个已知兼容区间内。模型文件有固定目录路径中不要有中文、空格和特殊符号。启动脚本有版本号能回溯到某个跑通的时间点。日志输出到固定目录方便排障。另外不同 vLLM 版本的行为差异可能很大。保留旧版本跑通的参数组合不要拿旧教程里的命令生搬硬套到新版本上这是很多人的坑。环境不是一次配置完就结束了它会随驱动、依赖和模型升级发生变化。每次升级前先记录升级前后的版本再跑小样本验证再全量发布。3. 一条启动命令的“配方学”高频参数不是玄学3.1 先跑一条最小命令不管业务多复杂我建议先跑最小命令确认模型能加载、请求能返回。最小命令不需要堆参数。vllm serve /models/Qwen3-7B-Instruct \ --max-model-len 4096 \ --gpu-memory-utilization 0.80 \ --max-num-seqs 8 \ --dtype auto这里我刻意降低了--max-num-seqs因为第一次验证时重点不是吞吐而是链路通不通。等确认返回正常再逐步提并发。3.2 --enforce-eager什么时候开什么时候关--enforce-eager是高频率问题之一。它本质上是让 vLLM 关闭 CUDA Graph 的预建改用更传统的 eager 执行方式。默认情况下vLLM 会尝试把某些算子做静态化加速以降低调度开销但这也可能带来更长的启动时间、更高的显存占用以及在某些自定义模型或非 NVIDIA 硬件上的兼容问题。什么时候开--enforce-eager遇到启动阶段算子报错怀疑和 CUDA Graph 有关。使用自定义模型、动态 shape 很复杂的模型。在非 NVIDIA 硬件或兼容性弱的软件栈上调试。什么时候不要开追求稳定低延迟和高吞吐的生产环境。关闭 CUDA Graph 通常会导致性能下降。模型已经能正常启动但你想压测吞吐时建议先不开看默认行为是否满足。一个常见误区是看到--enforce-eager能绕过一个报错就长期保留。实际上它只是绕过了优化路径没有修复根因。正确做法是把错误日志保留下来定位是算子问题还是模型结构问题而不是用参数绕完就不管了。3.3 max-num-seqs 和显存利用率热词里出现 max-num-seq对应 vLLM 参数一般是--max-num-seqs口语里经常省掉最后的 s。它控制的是服务端最多同时处理的序列数量。这个值不是越大越好。每个序列都会占用一部分 KV cache。当max-num-seqs设得过大请求稍微一多KV cache 就会把显存打满接着触发 OOM 或服务不稳定。设置过小GPU 利用不充分吞吐上不去。所以它必须和--gpu-memory-utilization一起看。--gpu-memory-utilization控制的是 vLLM 最多占用多少显存比例。默认值通常是 0.9意思是把最多 90% 的显存留给模型和 KV cache。如果你还要在同卡跑其他进程就要调低。我的经验顺序是先确定模型权重占用再根据剩余显存设计 KV cache再倒推 max-num-seqs。不要一上来就把 64、128 写进启动脚本。3.4 max-model-len、dtype 和 reasoning-parser--max-model-len限制模型能处理的最大上下文长度。它同时影响输入、输出和 KV cache 大小。设得过大会明显增加显存开销设得过小长文本请求会直接报错。你需要根据真实业务分布来设而不是只拿模型的宣称上下文长度来设。--dtype auto应该是最常见的默认选择。如果模型权重是 fp16 或 bf16vLLM 会自动按权重精度加载。如果显存紧张可以尝试量化版本或调低精度但有些自定义模型对精度很敏感需要先验证。--reasoning-parser这个参数近期在部署带推理链的模型时被频繁提到。它解决的是让服务端把模型的推理链和最终答案按结构化方式解析出来。这类模型通常会输出“推理过程加答案”的混合文本如果不做解析下游拿到的是混杂内容。使用 reasoning-parser 时有几个注意点不是所有模型都自带可解析的推理格式参数要在模型输出格式匹配时才有意义。不同版本对 reasoning parser 的支持范围不一先在小样本上验证解析结果。如果你只是普通对话模型不需要加这个参数加了反而可能输出不符合预期。3.5 参数管理的核心先小批量、再压测、再固化调参最大的坑是同时改多个参数出了问题不知道是谁引起的。正确做法是每次只改一个变量记录前后差异。比如先固定--gpu-memory-utilization0.85只调--max-num-seqs观察显存和延迟再把 max-model-len 调大观察 KV cache 变化。跑通后把参数组合和当时的环境版本一起保存下来。这是“配方”最原始的形式。没有版本记录的参数三个月后就是废纸。4. 不同业务场景的 vLLM 配方模型格式决定路线4.1 纯聊天/生成场景标准 safetensors 最省心如果你只是给对话模型提供 OpenAI 兼容接口直接用 safetensors 格式的模型文件通常是最稳的路线。主流 Hugging Face 模型大多发布 safetensors 权重能直接被 vLLM 加载。类似于社区里常出现的 qwen3.x 系列模型从 9B 到 27B 不同大小部署参数和显存需求完全不同。不要看别人用了某个参数就抄先确认你的模型尺寸、精度和 GPU 型号。启动后可以用 curl 做一次冒烟测试curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: /models/Qwen3-7B-Instruct, messages: [{role: user, content: 你好}], max_tokens: 64 }注意返回里的model字段要和启动时传入的模型名或路径一致。如果不一致部分客户端会报 model not found。如果你需要可视化验证vLLM 提供的 playground 页面适合做冒烟测试但不要依赖它做自动化回归它更适合人工快速点击查看输出。4.2 量化模型AWQ/GPTQ 通常比 GGUF 省心热词里有人问“vLLM 起 gguf”。这是一个需要小心处理的话题。GGUF 是 llama.cpp 生态里常用的量化格式vLLM 对它的支持并不像对 safetensors 那样完整往往需要一个额外的转换或集成路径。如果你的模型只有 GGUF 格式而你要用 vLLM 部署我的建议是先去确认当前 vLLM 版本是否支持直接加载该 GGUF 文件。如果不支持看能否从原始模型导出 safetensors再用 AWQ 或 GPTQ 做量化。如果团队里没有做过量化的人优先使用模型发布方提供的量化版本而不是自己转。AWQ 和 GPTQ 是 vLLM 生态里更常见的量化方式。它们能显著降低显存占用但要注意量化后的模型在精度、输出稳定性和推理速度上不一定优于原版需要用小批量评测集验证。4.3 embedding 和 reranker先确认支持矩阵别拿 vLLM 硬扛回到开头的问题vLLM 能不能启动 embedding 和 reranker我的判断是在社区主流案例中vLLM 主要面向生成式模型embedding 和 reranker 类任务不是它的主战场。即便某些版本或分支支持了这类模型可用范围和稳定性也需要单独确认。具体到昇腾 910B-A2 这样的硬件上问题会更难。因为除了模型结构支持之外还要看 NPU 后端是否实现了对应的算子。两步都通了这个组合才算真正能用。如果你需要的是 embedding 和 reranker我建议先看这几条路如果项目里只有少量 API 调用优先用专门的 embedding 服务或模型的官方服务接口。如果必须本地部署去找支持这类模型的专用推理框架而不是硬套 vLLM。如果确定要用 vLLM先跑通一个最小样例确认返回向量形式和 rerank 分数正确再接入业务。下面是一个简单的场景选型参考场景推荐方案说明对话生成、代码生成vLLM / SGLang生成式模型vLLM 优势明显问答系统长文本vLLM 加长上下文模型调大 max-model-len注意显存文档向量化专门的 embedding 服务vLLM 对 embedding 支持有限检索重排专门的 reranker 服务别拿生成模型框架硬扛低显存单机AWQ/GPTQ 量化加 vLLM量化格式要验证精度离线批量推理vLLM 的离线接口可复用脚本避免重复启动4.4 模型文件的版本和敏感性不管什么场景都要先确认模型文件、tokenizer、config.json 和 vLLM 版本的兼容性。有些模型变更了词汇表或 attention 实现旧版 vLLM 可能加载失败。加载成功后还要跑几个真实请求检查输出和参考链路是否一致不能只看“能返回结果”就算通过。5. 部署后最常遇到的几个问题按这个顺序排查5.1 现象分类vLLM 部署后的问题可以粗分为四类OOM 或启动失败。能启动但请求很慢或卡住。输出乱码、截断、内容异常。并发一上来就报错或服务重启。不同现象对应的排障路径完全不同。不要一上来就改参数。5.2 排查链路输入、环境、参数、工具边界我建议每次排障都按下面这个顺序走先看现象记录报错信息、复现步骤和后端日志。再看输入请求格式是否正确模型名是否匹配输入长度是否超过 max-model-len是否包含异常字符。再看环境驱动版本、CUDA 版本、容器共享内存、磁盘空间、依赖版本。再看参数gpu-memory-utilization、max-num-seqs、max-model-len、并发数、量化方式。最后再怀疑 vLLM 本身的限制当前版本是否支持该模型结构是否为已知 bug。这个顺序的用意是先从最容易验证的层面排除再进入复杂的工具边界。很多人一遇到 OOM 就调显存参数结果根因是磁盘空间满了导致模型加载失败白白浪费时间。5.3 爆显存排查先从上下文和并发入手热词里有人问“vLLM 加载 9B 模型爆显存”。9B 模型是不是一定会爆不一定。显存占用不是只看模型参数量。实际显存消耗包括模型权重本身。优化器状态和中间激活推理时通常比训练少但仍存在。KV cache这是大头取决于 max-model-len、max-num-seqs 和模型层数。CUDA context 和加速库的运行时开销。所以排查爆显存时先看这几个数字模型权重在目标精度下大概占多少 GB。一个粗略估法是参数量乘每参数字节数再乘以一个系数。你的 max-model-len 和 max-num-seqs 组合需要多少 KV cache。当前 GPU 总显存有多少剩余有多少。一个保守的调整顺序是先降低--gpu-memory-utilization到 0.6 左右再把--max-num-seqs降到 4同时减小--max-model-len看是否还能启动。如果还不能再考虑量化或换卡。5.4 请求卡住或异常别急着重启请求卡住通常不是参数一个原因。先确认服务日志里是否出现 “Waiting for available sequences”。是否多个请求互相挤占了 max-num-se