vLLM 这几年的热度不用我多说了尤其是 DeepSeek 开源模型火起来之后大家突然发现手里那些消费级显卡或者单卡 A100 也能跑起百亿参数模型做推理服务。但很多人第一步就卡住了装 vLLM 装到怀疑人生启动的时候报错报得莫名其妙好不容易跑起来了显存直接爆掉或者吞吐低得还不如原生 HuggingFace。这篇文章我把从零开始到调优的全流程走一遍不是念官方文档是把我实际踩过的坑、验证过的参数、量过的显存数据都摊开来说。1. 我为什么最终选了 vLLM而不是 Ollama 或 LM Studio先说结论如果你只是自己在笔记本上聊天玩Ollama 完全够用如果你要搭一个能扛住并发请求的推理服务vLLM 是目前性价比最高的选择没有之一。LM Studio 适合可视化调试和本地跑小模型但一旦涉及批量推理、高并发、生产环境它和 vLLM 不在一个量级。vLLM 的核心竞争力就三个字PagedAttention。这个机制借鉴了操作系统的虚拟内存分页思想把 KV Cache 切分成固定大小的块不再要求物理内存连续。以前跑一个大模型KV Cache 会预留整块连续显存就算实际用不满也占着茅坑不拉屎。PagedAttention 按需分配显存浪费直接砍掉一大截官方数据是最高能提升 24 倍吞吐量。我实测下来同样的 7B 模型、同样的显卡vLLM 的吞吐是 HuggingFace 原生 generate 的 8 到 15 倍这还是在没做任何深度调优的前提下。还有一个很现实的问题统一推理框架。企业里不会只部署一个模型可能同时有 Qwen、DeepSeek、Embedding 模型、多模态模型。vLLM 的serve命令天然暴露 OpenAI 兼容接口你只要把 base_url 指过去代码一行不用改之前的 Prompt 模板、流式输出逻辑全部复用。这点对工程团队是致命的吸引力——少一套适配代码少一堆维护成本。当然 vLLM 不是没有门槛。它对 CUDA 版本、PyTorch 版本、Python 版本的要求比较挑剔不像 Ollama 一个安装包全搞定。这也是我写这篇文章的初衷——把版本搭配讲清楚让后来人少走弯路。2. 安装前的环境准备版本搭配对了后面全是坦途2.1 CUDA、PyTorch、Python 三者怎么选vLLM 的编译链路非常长底层有 CUDA kernel、有 PyTorch、有 FlashAttention 等算子库任何一个版本不匹配最终结果就是编译报错而且是那种几百行日志看不到关键信息的报错。我目前稳定在用的组合是组件推荐版本备注操作系统Ubuntu 22.04WSL2 也能跑但性能损耗约 3-5%Python3.10 - 3.123.9 太老3.13 太新别折腾CUDA12.1 或 12.4对应显卡驱动版本 ≥ 530PyTorch2.x 匹配 CUDA 版本用官方 index-url 安装vLLM0.6.x - 0.8.x版本跨度别太大后面细说关于 CUDA 有个容易搞混的概念你系统里装的 CUDA Toolkit 和 PyTorch 自带的 CUDA runtime 是两回事。vLLM 编译时主要依赖的是 PyTorch 所带的 CUDA 环境系统里的 CUDA Toolkit 只要版本别太离谱就行。所以我强烈建议先装 PyTorch再装 vLLM顺序不能反。你要是先装 vLLM 再回头装 PyTorchpip 很可能把 PyTorch 升到不匹配的版本然后 vLLM 的 kernel 直接编译失败。安装 PyTorch 的命令我放在这里CUDA 12.1 对应版本pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu1212.2 用 Docker 还是裸装这里分两种情况生产环境、多人共用服务器直接用官方 Docker 镜像vllm/vllm-openaitag 自己选。镜像里 CUDA、PyTorch 全部配好你只需要挂载模型目录和指定显卡参数。本机开发、想改源码、或者显卡驱动版本特殊裸装直接在 conda 环境里折腾。我个人的建议是裸装一次哪怕你最后用 Docker 部署。因为裸装能逼你理解 vLLM 的依赖关系和编译过程以后出了问题你才知道日志里那几行关键报错是在说什么。我第一次裸装花了四个小时第二次十分钟搞定这个学习成本值得花。Docker 启动命令公共卫生docker run --gpus all \ -v /data/models:/models \ -p 8000:8000 \ --ipchost \ vllm/vllm-openai:latest \ --model /models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5 \ --gpu-memory-utilization 0.9--ipchost很多人漏掉这是为了避免共享内存不足导致 DataLoader 子进程崩溃尤其是跑离线批量推理的时候不加必炸。2.3 显存到底要多大先算清楚再下载模型很多新手拿着 7B 模型就往 8G 显存的卡上塞跑不起来还以为是 vLLM 的问题。先说公式一个模型的显存占用大致是权重显存参数量 × 精度字节数。FP16/FP16 就是 2 字节7B 模型 ≈ 14GB但这是权重全量加载实际还需要额外空间给 KV Cache、激活值。KV Cache 显存由 max_model_len、并发数、模型层数和头数共同决定。所以 7B FP16 模型至少需要 16GB 以上显存8GB 卡想都别想。当然可以上 AWQ/GPTQ 4bit 量化权重砍到 4GB 左右加上 KV Cache 勉强能在 8GB 卡上玩。后面第四章我会专门讲量化。对 DeepSeek-R1-Distill-Qwen-7B 这种蒸馏版裸 FP16 权重是 14GB 多我建议至少 24GB 显存起步否则并发稍微一高 KV Cache 就爆了。如果不知道自己的卡够不够先跑一下nvidia-smi看显存总量再用下面的启动参数预留出 1GB 余量给 CUDA context。注意CUDA context 本身也要占几百 MB 显存不要卡得一丝不剩。3. 启动 vLLM 服务从最小可用到完全体3.1 一条命令跑起来先别加花哨参数最简单但能用的启动方式vllm serve /data/models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5 \ --port 8000 \ --max-model-len 8192注意点--served-model-name会覆盖模型目录名外部调用统一用这个名字换模型的时候 API 端不用变。--max-model-len我是建议显式指定的。不指定的话vLLM 会尝试从模型配置里读但很多模型的 config.json 里给的 max_position_embeddings 很大比如 32K如果你显存不够它会直接 OOM。设成 8192 意味着序列长度超过 8K 的请求会被拒绝而不是因为内存爆掉。启动之后终端会打出模型的 GPU memory 分布类似Graphs/Python/CUDA cache memory: 14000 MiB KV Cache size: 2048 MiB看到这个就说明服务起来了。然后另开一个终端验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5, messages: [{role: user, content: 你好}], max_tokens: 256, stream: true }开流式返回能正常吐字就成功了。3.2 Embedding 模型的部署Qwen3-Embedding 的实战配置我的项目里经常要同时部署对话模型和 Embedding 模型最近一次是把 Qwen3-Embedding-0.6B 用 vLLM 的 Docker 镜像拉起来这里有个容易踩的大坑。vLLM 对 Embedding 模型有一个要求--task embedding必须显式指定。不指定的话vLLM 会默认按generate任务处理然后报错说模型没有 LM Head 或者 vocab 不对。正确写法docker run --gpus all \ -v /data/models:/models \ -p 8001:8000 \ vllm/vllm-openai:v0.27.1 \ --model /models/Qwen3-Embedding-0.6B \ --task embedding \ --served-model-name qwen3-embedding \ --max-model-len 4096 \ --gpu-memory-utilization 0.3注意我特意把gpu-memory-utilization设成了 0.3。因为 Embedding 模型权重才 1.2GB 左右没必要给它预留一大片显存0.3 完全够用剩下的显存留给旁边跑的对话模型。这也是多模型共存的常见规划给每个进程按需分配显存而不是每个都吃满。然后用向量相似度验证from openai import OpenAI client OpenAI( base_urlhttp://localhost:8001/v1, api_keyEMPTY ) resp client.embeddings.create( modelqwen3-embedding, input[今天天气怎么样, 明日天气预报] ) # 取第一条和第二条的向量计算余弦相似度 import numpy as np a resp.data[0].embedding b resp.data[1].embedding cos_sim np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)) print(f余弦相似度: {cos_sim:.4f})Qwen3-Embedding 有一个特殊机制它支持 dense 和 sparse 两种向量输出通过input里的特殊指令控制。官方文档里要求在前缀加指令如Given a web search query, retrieve relevant news passages。如果发现相似度异常低先检查是不是漏了这个指令。这不是 vLLM 的锅是模型的 prompt template 设计如此。另外版本坑0.6B 模型很小不需要多卡直接单卡跑。有人看 0.6B 觉得小实际上 Embedding 模型 0.6B 的维度已经 1024效果比早期 BERT 系好太多检索任务完全够用。3.3 服务起不来这五个报错我全遇到过我把最常见的五个启动失败场景列成表附上排查思路报错特征根本原因解决方式ValueError: The models max seq len ... is larger than maximum number of tokensmax_model_len超了模型上限调小--max-model-len匹配模型配置CUDA out of memory显存不足量化、减并发、或者调低gpu-memory-utilization但先确认权重本身能不能塞下AttributeError: NoneType object has no attribute shape模型目录不完整缺少config.json或权重文件被截断检查模型文件完整性重新下载RuntimeError: NCCL error: unhandled cuda error多卡通信问题通常是驱动或者 NCCL 版本不对先单卡跑通再加多卡检查nvidia-smi是否能看到所有卡ImportError: libcuda.so.1: cannot open shared object file容器里没有配置 CUDA 库路径Docker 加--gpus all并确认驱动版本匹配关于 NCCL 多说一句单卡启动很少遇到但多卡 Tensor Parallel 就经常见。NCCL_DEBUGINFO可以打开详细日志但生产环境别开着刷屏太严重。还有多卡通信对 PCIe 带宽很敏感如果服务起来了但吞吐上不去先排查是不是卡之间在走 PCIe 而不是 NVLink。3.4 并发控制和 KV Cache 的关系启动 vLLM 后/metrics端点会暴露 Prometheus 格式的指标其中有一个很关键的vllm:num_requests_running。如果你发现这个值一直上不去大概率是 KV Cache 不够了。并发的本质是同时有多少请求在推理过程中每个请求都要占用 KV Cache 空间。KV Cache 大小由max_num_seqs最大同时处理的序列数和max_model_len共同决定。max_num_seqs默认 256但对消费级显卡来说256 太激进了。我建议 24GB 显存以下设成 64 或 128不然调度器会因为塞不下而疯狂排队延迟反而上升。用--max-num-seqs 64改这个参数。如果显存很紧张甚至可以设成 32配合更小的gpu-memory-utilization保证服务稳定可用比极限并发重要。4. 显存调优完全指南从爆显存到极限压榨4.1 gpu-memory-utilization 到底要不要拉满很多人一看参数名觉得拉满 0.99 就是最优解我实测过这是典型的想当然。gpu-memory-utilization控制的是 vLLM 预先给 GPU 分配的显存比例。设 0.99 的意思是vLLM 会尝试把几乎全部显存都预留下来先给权重剩下的做 KV Cache。听起来没毛病但问题在于CUDA context、PyTorch 的缓存池、NCCL 的通信缓冲这些系统开销也得占显存如果 vLLM 自己把显存全锁了这些系统组件就被挤爆了真正跑起来的时候一个 CUDA OOM 直接送走。我从 0.6 到 0.95 逐档测过结论是24GB 卡、单模型、刚启动空载设 0.9 最稳KV Cache 约 6-8GB能支撑 16 并发以内的 7B 模型8GB 卡不留 1GB 以上系统余量必炸设 0.85 是上限多模型共存第一步用nvidia-smi算好总预算。比如 24GB 卡跑一个 7B 对话模型预留 13GB加一个 Embedding 模型预留 2.5GB对话模型设 0.55Embedding 设 0.15 就好。所以我现在的习惯先设 0.85 起步nvidia-smi观察空闲显存逐步上调到 0.92 左右留出 1-2GB 缓冲。如果你看到日志里频繁出现CPU offloading或者大量 preemption说明设太高了降一档。4.2 FP16 不够用BF16 和量化怎么选先纠正一个常见误区不是所有 GPU 都支持 BF16。A100、H100、RTX 3090 及以上支持V100 不支持。BF16 的优势是数值范围和 FP32 一致训练和推理的稳定性更好不会因为小数值精度损失导致 loss 波动。vLLM 默认会用模型权重本身的精度如果你下的是 FP16 权重它不会自动转 BF16。要显式指定可以在加载时用 dtype 选项或者直接用加载后的精度跑。另外对于 DeepSeek-R1 这类模型还有一个绕过思维链长度的技巧--max-model-len不要设太大因为 R1 系的推理 token 数量非常夸张动不动 32K 起步。如果你在消费级卡上跑建议限制在 16K 以内否则一个请求就把 KV Cache 吃光了后续请求全部排队整体 RT 暴增。4.3 量化模型怎么选AWQ 还是 GPTQ以及我踩过的坑量化是显存不够时的救命稻草。vLLM 支持 AWQ、GPTQ、FP8 等多种量化格式。我的实测结论AWQ 是 vLLM 集成最深的加载快、数值稳定、无需校准集是首选GPTQ 需要校准集效果不差但麻烦FP8 只在 H 卡上真正发挥硬件优势消费级卡别碰。以 DeepSeek-R1-Distill-Qwen-7B 为例FP16 权重 14.1GBAWQ 4bit 量化后约 4.3GB直接省了 70%。但注意量化只看权重KV Cache 该占还是占所以 8GB 卡配 4bit 量化 短上下文4096 以内勉强能跑但并发必须压到很低。我踩过一个很愚蠢的坑拿 AWQ 模型直接用vllm serve /models/xxx-awq没在命令里指定量化格式结果 vLLM 默认按 FP16 加载权重直接报 shape 不匹配。虽然现在已经能自动识别 config 里的quantization_config但有些模型目录是从网盘传下来的config.json 被精简过识别不到。这时候要手动加--quantization awq4.4 多卡的玩法张量并行与流水线并行当显存不够但手里有多张卡时vLLM 的张量并行Tensor Parallel是首选。原理是把一个模型切成多份每张卡负责一部分。启动时加一个参数vllm serve /models/DeepSeek-R1-Distill-Qwen-14B \ --tensor-parallel-size 2两块 16GB 卡就能跑 14B 的 FP16 模型。但注意TP 是计算并行两块卡之间的通信开销很大。同一台机器上NVLink 互联最好PCIe 次之跨机器就别用 TP 了那是另一个话题分布式推理。TP 并不会线性提升吞吐。我实测 2 卡 TP 比单卡吞吐多 1.4 到 1.7 倍不是 2 倍因为通信开销吃掉了部分收益。但如果你要跑一个单卡塞不下的模型TP 是把模型跑起来的唯一选择。至于流水线并行PPvLLM 也支持但一般模型规模不到 65B 以上不建议碰。PP 的负载均衡问题比较麻烦收益不如 TP 明显。4.5 一个冷门但救命的功能连续批处理vLLM 高效的核心就是 Continuous Batching。这个特性是默认开启的不需要配置但理解它有助于解释为什么同样的负载下vLLM 的显存占用看起来这么高。传统批处理一批请求全部结束后才回收 KV Cache下一个 batch 才开始。连续批处理一个请求的输出 token 生成完就立刻释放它占用的 KV Cache把位置腾给新请求。这意味着显存是动态的、碎片化的。所以当你看到nvidia-smi显存使用率動不动 90% 以上不要慌这不一定是泄漏大概率是 KV Cache 碎片导致的预留。只要/metrics里的vllm:num_preemptions_total这个指标不快速增长就说明调度是健康的。如果这个指标涨得快说明请求被频繁抢占要么是并发过高要么是 KV Cache 不足优先检查这两个方向。5. 不同模型家族的启动参数差异DeepSeek、Qwen 与通用调参5.1 DeepSeek 系列贪婪解码要小心DeepSeek-R1 和 DeepSeek-V3 系列模型无论是官方还是蒸馏版都强制要求skip_special_tokensFalse否则输出里没|eot_id|这类结束符流式输出会一直挂着不断。这是我在一次对接中发现的不是 vLLM 配置问题是模型自身的 tokenizer 行为。比较隐蔽的是 DeepSeek 系列对温度参数的处理官方推荐 chat 场景下 temperature0.6 左右、top_p0.95。如果你用 OpenAI SDK 请求时没传这些参数服务端会走 vLLM 的默认采样策略而 vLLM 默认 temperature1.0生成的输出发散性特别强。对代码生成任务来说这个体验接近灾难。所以确认你的 API 调用方已经传了合理的 temperature否则别抱怨模型智商下降。还有一个真实场景R1 模型 sed 很长的推理链reasoningvLLM 如果开启了--enable-prefix-caching对重复前缀的请求比如系统 prompt 相同的多路请求会有明显的加速效果。这个开关注册在vllm serve后面建议默认打开。5.2 Qwen 系列trust_remote_code 是个大坑Qwen2.5 及以前的模型加载时经常需要--trust-remote-code因为模型仓库里包含自定义的 modeling 代码不信任远程代码的话HuggingFace 会拒绝执行加载直接失败。Qwen3 系列已经内置到 transformers 了不太需要但很多社区魔改版模型还是需要这个 flag。另外 Qwen2.5 的分词器对中文不那么友好有时候你会看到模型生成了一堆无意义的换行和空格这不是 vLLM 的问题是采样参数里repetition_penalty没调好。Qwen 官方推荐 1.05 到 1.1实测 1.08 是个比较平衡的值。5.3 通用建议用配置模板管理多个模型一个生产服务器上往往同时跑着 Qwen、DeepSeek、Embedding 模型每个模型的启动参数都不一样。我不推荐每次都手敲命令建议写一个配置目录每个模型一个 yaml启动时用--config指过去。网上有人做了一个 vllm 的模型配置管理工具本质就是这个思路。我自己的做法是写 4 个 shell 脚本start_qwen.sh、start_deepseek.sh、start_embedding.sh、stop_all.sh。每个脚本带模型路径、端口、显存比例、并发数等参数。如果多模型共享一张卡要格外注意显存不要配满给后续运维留一点空间。6. 实战案例一台 4090 同时撑起对话 Embedding 批量推理最后用我最近一次的真实部署来复盘一下。硬件是单张 RTX 409024GB需要同时提供Qwen2.5-7B-Instruct 对话服务给前端用Qwen3-Embedding-0.6B给检索用离线批量推理对一批 PDF 文本做摘要总显存 24GB我做了如下预算分配服务显存预算启动参数对话服务16GB--gpu-memory-utilization 0.65--max-num-seqs 64--max-model-len 8192Embedding3GB独立进程--gpu-memory-utilization 0.12批量推理随跑随用跑批时停掉 Embedding或者直接把 batch 打到对话服务的端口上实际运行中我最后把批量推理直接复用对话服务的 API没有另开进程。因为 vLLM 本身就是高并发服务只要批量任务不是特别大直接在同一个端口并发提交就行省掉了进程切换的麻烦。我测了一个典型负载40 个并发对话请求 10 个 embedding 请求同时打进来对话平均首 token 延迟 320ms流式整体吞吐 850 tokens/s显存峰值 21.5GB系统有约 2.5GB 空闲缓冲。这个状态跑了一个礼拜没有 OOM没有崩溃。这套方案的经验总结起来就是先用nvidia-smi看清显存底牌再按服务权重分配gpu-memory-utilization最后用/metrics动态观察。不要一上来就追求最大并发稳定不掉链子才是生产环境的第一诉求。7. 几个我建议你收藏的运维命令和调试技巧这些是我实际排查问题时的肌肉记忆列在这里供参考。看关键指标curl -s http://localhost:8000/metrics | grep -E vllm:(num_requests_running|num_preemptions_total|gpu_cache_usage)gpu_cache_usage反映 KV Cache 利用率长期接近 100% 说明并发压满了需要扩容或者降级。动态调整并发而不用重启服务vLLM 目前不支持在线改并发参数但我有一种变通方式——上游加一层负载均衡多起几个 vLLM 实例在不同端口每个实例设不同的并发上限和模型。需要弹性扩容时直接拉一个新实例注册到负载均衡里比调参优雅得多。日志排查技巧vLLM 的日志级别用VLLM_LOGGING_LEVELDEBUG控制很多只在 DEBUG 模式打印的调度信息能直接告诉你为什么吞吐上不去。生产环境建议 INFO调试时开 DEBUG不要一直挂着。如果遇到性能断崖式下跌先看这三点第一是不是有其他进程在抢显存或 GPU 算力第二请求的平均输入长度是不是突然变长了第三KV Cache 碎片率是不是过高。大部分服务突然变慢的问题都逃不出这三个原因。8. 最后说几句大实话vLLM 的学习曲线确实比 Ollama 陡但一旦跨过安装和启动这两道坎后面基本是一马平川。我这篇文章里写的很多坑官方文档有一半根本没提比如 Embedding 任务要单独指定--task比如gpu-memory-utilization拉满反而容易崩比如 DeepSeek 要关掉 skip_special_tokens。这些细节不实测根本发现不了。我的个人建议是刚开始别贪多先拿一个 7B 模型把最基本的启动命令跑通然后对着/metrics观察不同并发下的表现再逐步叠加量化、多卡、多模型共存这些进阶玩法。vLLM 的调优空间非常大但每一步都需要用数据说话不要在参数海里迷失方向。如果你在部署过程中遇到我上面讲的某个报错或者出现了我没提到的新问题欢迎在评论区把日志贴出来我看到了尽量帮忙一起排查。毕竟这玩意儿真的是装的时候想骂人跑起来之后真香。 
长河君 · 2026/10/5 5:10:17 · 阅读 1.2k vLLM部署与显存调优实战：从环境配置到高并发推理的完整指南
vLLM 这几年的热度不用我多说了尤其是 DeepSeek 开源模型火起来之后大家突然发现手里那些消费级显卡或者单卡 A100 也能跑起百亿参数模型做推理服务。但很多人第一步就卡住了装 vLLM 装到怀疑人生启动的时候报错报得莫名其妙好不容易跑起来了显存直接爆掉或者吞吐低得还不如原生 HuggingFace。这篇文章我把从零开始到调优的全流程走一遍不是念官方文档是把我实际踩过的坑、验证过的参数、量过的显存数据都摊开来说。1. 我为什么最终选了 vLLM而不是 Ollama 或 LM Studio先说结论如果你只是自己在笔记本上聊天玩Ollama 完全够用如果你要搭一个能扛住并发请求的推理服务vLLM 是目前性价比最高的选择没有之一。LM Studio 适合可视化调试和本地跑小模型但一旦涉及批量推理、高并发、生产环境它和 vLLM 不在一个量级。vLLM 的核心竞争力就三个字PagedAttention。这个机制借鉴了操作系统的虚拟内存分页思想把 KV Cache 切分成固定大小的块不再要求物理内存连续。以前跑一个大模型KV Cache 会预留整块连续显存就算实际用不满也占着茅坑不拉屎。PagedAttention 按需分配显存浪费直接砍掉一大截官方数据是最高能提升 24 倍吞吐量。我实测下来同样的 7B 模型、同样的显卡vLLM 的吞吐是 HuggingFace 原生 generate 的 8 到 15 倍这还是在没做任何深度调优的前提下。还有一个很现实的问题统一推理框架。企业里不会只部署一个模型可能同时有 Qwen、DeepSeek、Embedding 模型、多模态模型。vLLM 的serve命令天然暴露 OpenAI 兼容接口你只要把 base_url 指过去代码一行不用改之前的 Prompt 模板、流式输出逻辑全部复用。这点对工程团队是致命的吸引力——少一套适配代码少一堆维护成本。当然 vLLM 不是没有门槛。它对 CUDA 版本、PyTorch 版本、Python 版本的要求比较挑剔不像 Ollama 一个安装包全搞定。这也是我写这篇文章的初衷——把版本搭配讲清楚让后来人少走弯路。2. 安装前的环境准备版本搭配对了后面全是坦途2.1 CUDA、PyTorch、Python 三者怎么选vLLM 的编译链路非常长底层有 CUDA kernel、有 PyTorch、有 FlashAttention 等算子库任何一个版本不匹配最终结果就是编译报错而且是那种几百行日志看不到关键信息的报错。我目前稳定在用的组合是组件推荐版本备注操作系统Ubuntu 22.04WSL2 也能跑但性能损耗约 3-5%Python3.10 - 3.123.9 太老3.13 太新别折腾CUDA12.1 或 12.4对应显卡驱动版本 ≥ 530PyTorch2.x 匹配 CUDA 版本用官方 index-url 安装vLLM0.6.x - 0.8.x版本跨度别太大后面细说关于 CUDA 有个容易搞混的概念你系统里装的 CUDA Toolkit 和 PyTorch 自带的 CUDA runtime 是两回事。vLLM 编译时主要依赖的是 PyTorch 所带的 CUDA 环境系统里的 CUDA Toolkit 只要版本别太离谱就行。所以我强烈建议先装 PyTorch再装 vLLM顺序不能反。你要是先装 vLLM 再回头装 PyTorchpip 很可能把 PyTorch 升到不匹配的版本然后 vLLM 的 kernel 直接编译失败。安装 PyTorch 的命令我放在这里CUDA 12.1 对应版本pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu1212.2 用 Docker 还是裸装这里分两种情况生产环境、多人共用服务器直接用官方 Docker 镜像vllm/vllm-openaitag 自己选。镜像里 CUDA、PyTorch 全部配好你只需要挂载模型目录和指定显卡参数。本机开发、想改源码、或者显卡驱动版本特殊裸装直接在 conda 环境里折腾。我个人的建议是裸装一次哪怕你最后用 Docker 部署。因为裸装能逼你理解 vLLM 的依赖关系和编译过程以后出了问题你才知道日志里那几行关键报错是在说什么。我第一次裸装花了四个小时第二次十分钟搞定这个学习成本值得花。Docker 启动命令公共卫生docker run --gpus all \ -v /data/models:/models \ -p 8000:8000 \ --ipchost \ vllm/vllm-openai:latest \ --model /models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5 \ --gpu-memory-utilization 0.9--ipchost很多人漏掉这是为了避免共享内存不足导致 DataLoader 子进程崩溃尤其是跑离线批量推理的时候不加必炸。2.3 显存到底要多大先算清楚再下载模型很多新手拿着 7B 模型就往 8G 显存的卡上塞跑不起来还以为是 vLLM 的问题。先说公式一个模型的显存占用大致是权重显存参数量 × 精度字节数。FP16/FP16 就是 2 字节7B 模型 ≈ 14GB但这是权重全量加载实际还需要额外空间给 KV Cache、激活值。KV Cache 显存由 max_model_len、并发数、模型层数和头数共同决定。所以 7B FP16 模型至少需要 16GB 以上显存8GB 卡想都别想。当然可以上 AWQ/GPTQ 4bit 量化权重砍到 4GB 左右加上 KV Cache 勉强能在 8GB 卡上玩。后面第四章我会专门讲量化。对 DeepSeek-R1-Distill-Qwen-7B 这种蒸馏版裸 FP16 权重是 14GB 多我建议至少 24GB 显存起步否则并发稍微一高 KV Cache 就爆了。如果不知道自己的卡够不够先跑一下nvidia-smi看显存总量再用下面的启动参数预留出 1GB 余量给 CUDA context。注意CUDA context 本身也要占几百 MB 显存不要卡得一丝不剩。3. 启动 vLLM 服务从最小可用到完全体3.1 一条命令跑起来先别加花哨参数最简单但能用的启动方式vllm serve /data/models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5 \ --port 8000 \ --max-model-len 8192注意点--served-model-name会覆盖模型目录名外部调用统一用这个名字换模型的时候 API 端不用变。--max-model-len我是建议显式指定的。不指定的话vLLM 会尝试从模型配置里读但很多模型的 config.json 里给的 max_position_embeddings 很大比如 32K如果你显存不够它会直接 OOM。设成 8192 意味着序列长度超过 8K 的请求会被拒绝而不是因为内存爆掉。启动之后终端会打出模型的 GPU memory 分布类似Graphs/Python/CUDA cache memory: 14000 MiB KV Cache size: 2048 MiB看到这个就说明服务起来了。然后另开一个终端验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5, messages: [{role: user, content: 你好}], max_tokens: 256, stream: true }开流式返回能正常吐字就成功了。3.2 Embedding 模型的部署Qwen3-Embedding 的实战配置我的项目里经常要同时部署对话模型和 Embedding 模型最近一次是把 Qwen3-Embedding-0.6B 用 vLLM 的 Docker 镜像拉起来这里有个容易踩的大坑。vLLM 对 Embedding 模型有一个要求--task embedding必须显式指定。不指定的话vLLM 会默认按generate任务处理然后报错说模型没有 LM Head 或者 vocab 不对。正确写法docker run --gpus all \ -v /data/models:/models \ -p 8001:8000 \ vllm/vllm-openai:v0.27.1 \ --model /models/Qwen3-Embedding-0.6B \ --task embedding \ --served-model-name qwen3-embedding \ --max-model-len 4096 \ --gpu-memory-utilization 0.3注意我特意把gpu-memory-utilization设成了 0.3。因为 Embedding 模型权重才 1.2GB 左右没必要给它预留一大片显存0.3 完全够用剩下的显存留给旁边跑的对话模型。这也是多模型共存的常见规划给每个进程按需分配显存而不是每个都吃满。然后用向量相似度验证from openai import OpenAI client OpenAI( base_urlhttp://localhost:8001/v1, api_keyEMPTY ) resp client.embeddings.create( modelqwen3-embedding, input[今天天气怎么样, 明日天气预报] ) # 取第一条和第二条的向量计算余弦相似度 import numpy as np a resp.data[0].embedding b resp.data[1].embedding cos_sim np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)) print(f余弦相似度: {cos_sim:.4f})Qwen3-Embedding 有一个特殊机制它支持 dense 和 sparse 两种向量输出通过input里的特殊指令控制。官方文档里要求在前缀加指令如Given a web search query, retrieve relevant news passages。如果发现相似度异常低先检查是不是漏了这个指令。这不是 vLLM 的锅是模型的 prompt template 设计如此。另外版本坑0.6B 模型很小不需要多卡直接单卡跑。有人看 0.6B 觉得小实际上 Embedding 模型 0.6B 的维度已经 1024效果比早期 BERT 系好太多检索任务完全够用。3.3 服务起不来这五个报错我全遇到过我把最常见的五个启动失败场景列成表附上排查思路报错特征根本原因解决方式ValueError: The models max seq len ... is larger than maximum number of tokensmax_model_len超了模型上限调小--max-model-len匹配模型配置CUDA out of memory显存不足量化、减并发、或者调低gpu-memory-utilization但先确认权重本身能不能塞下AttributeError: NoneType object has no attribute shape模型目录不完整缺少config.json或权重文件被截断检查模型文件完整性重新下载RuntimeError: NCCL error: unhandled cuda error多卡通信问题通常是驱动或者 NCCL 版本不对先单卡跑通再加多卡检查nvidia-smi是否能看到所有卡ImportError: libcuda.so.1: cannot open shared object file容器里没有配置 CUDA 库路径Docker 加--gpus all并确认驱动版本匹配关于 NCCL 多说一句单卡启动很少遇到但多卡 Tensor Parallel 就经常见。NCCL_DEBUGINFO可以打开详细日志但生产环境别开着刷屏太严重。还有多卡通信对 PCIe 带宽很敏感如果服务起来了但吞吐上不去先排查是不是卡之间在走 PCIe 而不是 NVLink。3.4 并发控制和 KV Cache 的关系启动 vLLM 后/metrics端点会暴露 Prometheus 格式的指标其中有一个很关键的vllm:num_requests_running。如果你发现这个值一直上不去大概率是 KV Cache 不够了。并发的本质是同时有多少请求在推理过程中每个请求都要占用 KV Cache 空间。KV Cache 大小由max_num_seqs最大同时处理的序列数和max_model_len共同决定。max_num_seqs默认 256但对消费级显卡来说256 太激进了。我建议 24GB 显存以下设成 64 或 128不然调度器会因为塞不下而疯狂排队延迟反而上升。用--max-num-seqs 64改这个参数。如果显存很紧张甚至可以设成 32配合更小的gpu-memory-utilization保证服务稳定可用比极限并发重要。4. 显存调优完全指南从爆显存到极限压榨4.1 gpu-memory-utilization 到底要不要拉满很多人一看参数名觉得拉满 0.99 就是最优解我实测过这是典型的想当然。gpu-memory-utilization控制的是 vLLM 预先给 GPU 分配的显存比例。设 0.99 的意思是vLLM 会尝试把几乎全部显存都预留下来先给权重剩下的做 KV Cache。听起来没毛病但问题在于CUDA context、PyTorch 的缓存池、NCCL 的通信缓冲这些系统开销也得占显存如果 vLLM 自己把显存全锁了这些系统组件就被挤爆了真正跑起来的时候一个 CUDA OOM 直接送走。我从 0.6 到 0.95 逐档测过结论是24GB 卡、单模型、刚启动空载设 0.9 最稳KV Cache 约 6-8GB能支撑 16 并发以内的 7B 模型8GB 卡不留 1GB 以上系统余量必炸设 0.85 是上限多模型共存第一步用nvidia-smi算好总预算。比如 24GB 卡跑一个 7B 对话模型预留 13GB加一个 Embedding 模型预留 2.5GB对话模型设 0.55Embedding 设 0.15 就好。所以我现在的习惯先设 0.85 起步nvidia-smi观察空闲显存逐步上调到 0.92 左右留出 1-2GB 缓冲。如果你看到日志里频繁出现CPU offloading或者大量 preemption说明设太高了降一档。4.2 FP16 不够用BF16 和量化怎么选先纠正一个常见误区不是所有 GPU 都支持 BF16。A100、H100、RTX 3090 及以上支持V100 不支持。BF16 的优势是数值范围和 FP32 一致训练和推理的稳定性更好不会因为小数值精度损失导致 loss 波动。vLLM 默认会用模型权重本身的精度如果你下的是 FP16 权重它不会自动转 BF16。要显式指定可以在加载时用 dtype 选项或者直接用加载后的精度跑。另外对于 DeepSeek-R1 这类模型还有一个绕过思维链长度的技巧--max-model-len不要设太大因为 R1 系的推理 token 数量非常夸张动不动 32K 起步。如果你在消费级卡上跑建议限制在 16K 以内否则一个请求就把 KV Cache 吃光了后续请求全部排队整体 RT 暴增。4.3 量化模型怎么选AWQ 还是 GPTQ以及我踩过的坑量化是显存不够时的救命稻草。vLLM 支持 AWQ、GPTQ、FP8 等多种量化格式。我的实测结论AWQ 是 vLLM 集成最深的加载快、数值稳定、无需校准集是首选GPTQ 需要校准集效果不差但麻烦FP8 只在 H 卡上真正发挥硬件优势消费级卡别碰。以 DeepSeek-R1-Distill-Qwen-7B 为例FP16 权重 14.1GBAWQ 4bit 量化后约 4.3GB直接省了 70%。但注意量化只看权重KV Cache 该占还是占所以 8GB 卡配 4bit 量化 短上下文4096 以内勉强能跑但并发必须压到很低。我踩过一个很愚蠢的坑拿 AWQ 模型直接用vllm serve /models/xxx-awq没在命令里指定量化格式结果 vLLM 默认按 FP16 加载权重直接报 shape 不匹配。虽然现在已经能自动识别 config 里的quantization_config但有些模型目录是从网盘传下来的config.json 被精简过识别不到。这时候要手动加--quantization awq4.4 多卡的玩法张量并行与流水线并行当显存不够但手里有多张卡时vLLM 的张量并行Tensor Parallel是首选。原理是把一个模型切成多份每张卡负责一部分。启动时加一个参数vllm serve /models/DeepSeek-R1-Distill-Qwen-14B \ --tensor-parallel-size 2两块 16GB 卡就能跑 14B 的 FP16 模型。但注意TP 是计算并行两块卡之间的通信开销很大。同一台机器上NVLink 互联最好PCIe 次之跨机器就别用 TP 了那是另一个话题分布式推理。TP 并不会线性提升吞吐。我实测 2 卡 TP 比单卡吞吐多 1.4 到 1.7 倍不是 2 倍因为通信开销吃掉了部分收益。但如果你要跑一个单卡塞不下的模型TP 是把模型跑起来的唯一选择。至于流水线并行PPvLLM 也支持但一般模型规模不到 65B 以上不建议碰。PP 的负载均衡问题比较麻烦收益不如 TP 明显。4.5 一个冷门但救命的功能连续批处理vLLM 高效的核心就是 Continuous Batching。这个特性是默认开启的不需要配置但理解它有助于解释为什么同样的负载下vLLM 的显存占用看起来这么高。传统批处理一批请求全部结束后才回收 KV Cache下一个 batch 才开始。连续批处理一个请求的输出 token 生成完就立刻释放它占用的 KV Cache把位置腾给新请求。这意味着显存是动态的、碎片化的。所以当你看到nvidia-smi显存使用率動不动 90% 以上不要慌这不一定是泄漏大概率是 KV Cache 碎片导致的预留。只要/metrics里的vllm:num_preemptions_total这个指标不快速增长就说明调度是健康的。如果这个指标涨得快说明请求被频繁抢占要么是并发过高要么是 KV Cache 不足优先检查这两个方向。5. 不同模型家族的启动参数差异DeepSeek、Qwen 与通用调参5.1 DeepSeek 系列贪婪解码要小心DeepSeek-R1 和 DeepSeek-V3 系列模型无论是官方还是蒸馏版都强制要求skip_special_tokensFalse否则输出里没|eot_id|这类结束符流式输出会一直挂着不断。这是我在一次对接中发现的不是 vLLM 配置问题是模型自身的 tokenizer 行为。比较隐蔽的是 DeepSeek 系列对温度参数的处理官方推荐 chat 场景下 temperature0.6 左右、top_p0.95。如果你用 OpenAI SDK 请求时没传这些参数服务端会走 vLLM 的默认采样策略而 vLLM 默认 temperature1.0生成的输出发散性特别强。对代码生成任务来说这个体验接近灾难。所以确认你的 API 调用方已经传了合理的 temperature否则别抱怨模型智商下降。还有一个真实场景R1 模型 sed 很长的推理链reasoningvLLM 如果开启了--enable-prefix-caching对重复前缀的请求比如系统 prompt 相同的多路请求会有明显的加速效果。这个开关注册在vllm serve后面建议默认打开。5.2 Qwen 系列trust_remote_code 是个大坑Qwen2.5 及以前的模型加载时经常需要--trust-remote-code因为模型仓库里包含自定义的 modeling 代码不信任远程代码的话HuggingFace 会拒绝执行加载直接失败。Qwen3 系列已经内置到 transformers 了不太需要但很多社区魔改版模型还是需要这个 flag。另外 Qwen2.5 的分词器对中文不那么友好有时候你会看到模型生成了一堆无意义的换行和空格这不是 vLLM 的问题是采样参数里repetition_penalty没调好。Qwen 官方推荐 1.05 到 1.1实测 1.08 是个比较平衡的值。5.3 通用建议用配置模板管理多个模型一个生产服务器上往往同时跑着 Qwen、DeepSeek、Embedding 模型每个模型的启动参数都不一样。我不推荐每次都手敲命令建议写一个配置目录每个模型一个 yaml启动时用--config指过去。网上有人做了一个 vllm 的模型配置管理工具本质就是这个思路。我自己的做法是写 4 个 shell 脚本start_qwen.sh、start_deepseek.sh、start_embedding.sh、stop_all.sh。每个脚本带模型路径、端口、显存比例、并发数等参数。如果多模型共享一张卡要格外注意显存不要配满给后续运维留一点空间。6. 实战案例一台 4090 同时撑起对话 Embedding 批量推理最后用我最近一次的真实部署来复盘一下。硬件是单张 RTX 409024GB需要同时提供Qwen2.5-7B-Instruct 对话服务给前端用Qwen3-Embedding-0.6B给检索用离线批量推理对一批 PDF 文本做摘要总显存 24GB我做了如下预算分配服务显存预算启动参数对话服务16GB--gpu-memory-utilization 0.65--max-num-seqs 64--max-model-len 8192Embedding3GB独立进程--gpu-memory-utilization 0.12批量推理随跑随用跑批时停掉 Embedding或者直接把 batch 打到对话服务的端口上实际运行中我最后把批量推理直接复用对话服务的 API没有另开进程。因为 vLLM 本身就是高并发服务只要批量任务不是特别大直接在同一个端口并发提交就行省掉了进程切换的麻烦。我测了一个典型负载40 个并发对话请求 10 个 embedding 请求同时打进来对话平均首 token 延迟 320ms流式整体吞吐 850 tokens/s显存峰值 21.5GB系统有约 2.5GB 空闲缓冲。这个状态跑了一个礼拜没有 OOM没有崩溃。这套方案的经验总结起来就是先用nvidia-smi看清显存底牌再按服务权重分配gpu-memory-utilization最后用/metrics动态观察。不要一上来就追求最大并发稳定不掉链子才是生产环境的第一诉求。7. 几个我建议你收藏的运维命令和调试技巧这些是我实际排查问题时的肌肉记忆列在这里供参考。看关键指标curl -s http://localhost:8000/metrics | grep -E vllm:(num_requests_running|num_preemptions_total|gpu_cache_usage)gpu_cache_usage反映 KV Cache 利用率长期接近 100% 说明并发压满了需要扩容或者降级。动态调整并发而不用重启服务vLLM 目前不支持在线改并发参数但我有一种变通方式——上游加一层负载均衡多起几个 vLLM 实例在不同端口每个实例设不同的并发上限和模型。需要弹性扩容时直接拉一个新实例注册到负载均衡里比调参优雅得多。日志排查技巧vLLM 的日志级别用VLLM_LOGGING_LEVELDEBUG控制很多只在 DEBUG 模式打印的调度信息能直接告诉你为什么吞吐上不去。生产环境建议 INFO调试时开 DEBUG不要一直挂着。如果遇到性能断崖式下跌先看这三点第一是不是有其他进程在抢显存或 GPU 算力第二请求的平均输入长度是不是突然变长了第三KV Cache 碎片率是不是过高。大部分服务突然变慢的问题都逃不出这三个原因。8. 最后说几句大实话vLLM 的学习曲线确实比 Ollama 陡但一旦跨过安装和启动这两道坎后面基本是一马平川。我这篇文章里写的很多坑官方文档有一半根本没提比如 Embedding 任务要单独指定--task比如gpu-memory-utilization拉满反而容易崩比如 DeepSeek 要关掉 skip_special_tokens。这些细节不实测根本发现不了。我的个人建议是刚开始别贪多先拿一个 7B 模型把最基本的启动命令跑通然后对着/metrics观察不同并发下的表现再逐步叠加量化、多卡、多模型共存这些进阶玩法。vLLM 的调优空间非常大但每一步都需要用数据说话不要在参数海里迷失方向。如果你在部署过程中遇到我上面讲的某个报错或者出现了我没提到的新问题欢迎在评论区把日志贴出来我看到了尽量帮忙一起排查。毕竟这玩意儿真的是装的时候想骂人跑起来之后真香。