vLLM 0.29在线服务部署实践:从环境配置到DeepSeek/Qwen实战 vLLM 0.29的Online Serving我实际跑了快一个月今天趁着休息把这篇导读笔记整理出来。vLLM这个词在LLM部署圈已经不需要多解释它基本是当前大模型在线推理服务的事实标准。0.29这个版本我升级之后最直观的感受是在线路径的调度比之前顺了很多跑DeepSeek、Qwen这类开源模型时从启动到提供OpenAI兼容接口整个流程已经可以无脑串起来。这篇笔记适合两类人一是刚接触vLLM、想把自己的模型挂成服务的人二是已经在用但想了解v0.29版本到底有哪些改进、线上配置怎么调最优的人。我会把安装避坑、启动参数、DeepSeek部署、Qwen部署、常见故障排查全部捋一遍尽量少讲虚的多给能直接抄作业的东西。1. v0.29的Online Serving到底改了什么1.1 在线推理和离线推理完全两码事很多人第一次用vLLM跑模型会误以为它和普通推理脚本一样给定一批prompt跑完拿结果。但Online Serving要解决的完全是另一个问题——请求是随时到达的用户可能同时发来一堆长短不一的文本有的要几百token结果有的要几千token结果服务端必须在毫秒级做出调度决策。传统做法是动态batching把同一时刻到达的请求凑成一个batch送进GPU。听起来合理但问题在于batch里只要有一个慢请求其他人就得等它跑完。vLLM的核心创新就是连续批处理continuous batching一个请求生成的token一旦结束立刻从batch中挪走腾出的显存和计算资源马上给新请求插队。这个机制在长文档摘要、多轮对话这类使用场景下收益特别明显。另一个绕不开的技术是PagedAttention。大模型推理过程中需要缓存KV cache它的大小和序列长度成正比如果像传统框架那样预先分配连续显存很容易出现碎片和浪费长上下文直接爆显存。PagedAttention把KV cache切成固定大小的“页”像操作系统管理内存一样动态分配显存利用率提升非常可观。这也是vLLM在同等显存条件下能比不少框架跑更长的上下文、更高并发的根本原因。1.2 升级0.29后我实打实感知到的变化我不能代表官方给你列changelog只说我升级前后的体感。首先调度器明显更稳了。以前混着跑几个很长的system prompt加一堆短请求偶尔会出现短请求被长prefill堵死的情况要等很久才开始吐字。0.29把chunked prefill做得更成熟之后大段的prompt会被切成小块穿插在其他请求之间执行短请求的首字延迟好了很多。其次前缀缓存prefix caching命中率体感更好。多轮对话里每轮都带一大段历史消息如果缓存的key设计得不够好实际用处有限。0.29这版对长公共前缀的识别更准同一个用户连续对话、同一个system prompt反复调用时吞吐能提一截。第三对DeepSeek和Qwen这类模型的兼容性补强了。早期版本跑一些做过多轮对话微调的模型容易出现停不下来或格式错乱现在只要权重和tokenizer配置没问题基本拉起就能用对量化模型的支持也顺手很多。另外命令行入口也统一了vllm serve这条命令在0.29版本里可以直接用不需要去记那一长串python -m vllm.entrypoints.openai.api_server。2. 安装与运行前的环境准备2.1 CUDA、Python、PyTorch版本对齐vLLM不是那种pip装完就高枕无忧的纯Python库它带了大量CUDA扩展编译和运行都依赖环境里CUDA、PyTorch、Python三者的匹配关系。我的建议很简单先统一基线。Python选3.10或3.11比较稳3.12能用但有些扩展包可能要等编译CUDA Toolkit和驱动的对应关系要确认好至少保证驱动支持你需要的CUDA版本。conda create -n vllm python3.11 -y conda activate vllm pip install --upgrade pip pip install vllm0.29.0装完先跑一句检查命令确认PyTorch里的CUDA版本是通的python -c import torch; print(torch.__version__, torch.version.cuda) nvidia-smi nvcc --version这里有个很常见的误区nvidia-smi显示的是驱动支持的最高CUDA版本不代表你的运行环境真的启用了这个版本nvcc --version显示的是CUDA Toolkit编译器的版本两者不一致非常正常。你真正要关心的是PyTorch编译时用的CUDA版本以及它能识别的显卡驱动是否满足要求。如果torch打印的CUDA版本是12.4驱动需要支持CUDA 12.4及以上否则会报CUDA driver version is insufficient。2.2 装vllm会改变torch版本怎么破“安装vllm会改变已经安装好的torch”这个坑我几乎每次在技术群里都能看到有人踩。原因很简单vLLM的依赖声明里对torch版本有硬性要求pip在解析依赖时发现当前环境的torch不满足就会先卸载旧的、再装上匹配的版本。如果你之前是用pip install torch装的深度学习环境里面可能还跑着unsloth、flash-attn、transformers的某个特定版本这一换torch连锁反应就来了。我自己遇到过最离谱的一次原本torch 2.1.0cu118装了vllm之后被换成了2.3.0cu124结果以前训练代码里用到的某个自定义CUDA算子直接报二进制不兼容查了半天才发现是torch的wheel变了连CUDA runtime版本都换了。所以我的建议非常明确务必用独立的conda环境或venv跑vLLM不要直接往已有的训练环境里装。如果确实需要共用一个环境先装vllm再装其他依赖。因为vllm安装过程中会强制调整torch后装它的代价最小。如果你坚持保留某个torch版本不要用--no-deps硬装那会导致运行时缺一堆依赖。更靠谱的做法是查vLLM的requirements文件把它的依赖列表手动装齐再固定你想要的torch版本。如果已经装乱了恢复其实也不难pip uninstall -y vllm torch pip install torch你原来的版本但卸载操作会连带清理掉依赖它的其他库这就是为什么我一再强调用独立环境。2.3 模型文件准备本地目录最省心vLLM启动时可以填HuggingFace的模型ID比如deepseek-ai/DeepSeek-R1-Distill-Qwen-32B它会自动去拉权重。但线上部署我不推荐这样做网络一抖动、HF又限速服务起半天起不来而且每次重复初始化都可能在权重下载上浪费时间。最好先把模型下载到本地磁盘然后用本地路径启动。huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-32B --local-dir /data/models/DeepSeek-R1-Distill-Qwen-32B没有huggingface-cli的话可以直接用Python脚本调用huggingface_hub的snapshot_download函数效果一样。下载完确认目录里有config.json、tokenizer.json、模型权重文件等。我习惯把所有模型按型号-精度-日期的格式组织目录避免后期忘记这个目录对应哪个权重版本。3. 用vllm serve把模型跑起来核心参数与工具链3.1 vllm serve入口与关键参数0.29版本里vllm serve是官方推荐的启动方式它等价于老的python -m vllm.entrypoints.openai.api_server但参数组织更清晰。默认情况下服务监听0.0.0.0:8000暴露的是OpenAI兼容API包括/v1/models、/v1/completions、/v1/chat/completions这几个端点。最基本的启动命令vllm serve Qwen/Qwen3.8-Flash-Next \ --served-model-name qwen-flash \ --max-model-len 32768 \ --gpu-memory-utilization 0.85 \ --max-num-seqs 64这里--served-model-name一定要重视。你本地模型目录的名字可以随便起但API调用的时候用的是这个served name。如果不指定客户端就必须用完整的HF路径来请求经常对不上指定成简短别名之后OpenAI客户端那边就轻松很多。核心参数我列了一张速查表参数作用我的建议值--tensor-parallel-size使用的GPU数量把模型切分到多卡单卡填1多卡填实际卡数--max-model-len最大序列长度包括输入和输出按显存和业务需要调别一味求大--gpu-memory-utilizationvLLM最多占用的显存比例0.8~0.9过大会导致后续实验没显存--max-num-seqs同一时刻最多处理的请求数32~128看模型大小和显存--dtype权重精度常用auto/float16/bfloat16绝大多数模型直接auto即可--quantization量化方式如awq/gptq/fp8只有量化模型才需要指定--swap-spaceCPU内存swap的大小单位GB默认4显存紧张时可以加大--enable-prefix-caching开启前缀缓存0.29里对多轮对话很划算很多人不理解为什么vLLM一启动就把显存占掉接近90%以为出bug了。这是它的设计逻辑根据gpu-memory-utilization预先分配好KV cache池避免运行过程中频繁申请显存。这个比例设得太低实际能并发处理的请求数量就会缩水设得太高又没有余量给模型权重、CUDA context和其他杂项运气不好直接OOM。我通常是先85%小模型可以到90%遇到OOM再往下降。3.2 合理调整max-model-len和并发窗口max-model-len是最容易拍脑袋调的参数。7B模型在fp16下权重占14GB左右但KV cache才是吃显存的大头。每多保留一个token的KV cache就要按层数、注意力头数、每头维度去算字节数。以常见的7B Qwen结构为例一个token的KV cache大概是几百KB到1MB级别看起来不多但你乘上32768的序列长度再乘上并发请求数数字立刻就膨胀了。这就是为什么很多人设了--max-model-len 65536以后启动直接报CUDA out of memory模型权重还没算进去光是KV cache预算已经爆了。我的做法是先用小一点的长度比如16384启动完打开vLLM日志看它打印的Maximum concurrency for 16384 tokens这类提示再根据业务需要往上微调。--max-num-seqs则是控制并发窗口的。调高它确实能提高吞吐但每个并发请求都会占用KV cache资源在总显存固定的情况下并发数和序列长度是跷跷板。如果业务里长文本请求很多宁愿把并发调低一点把长度留给真正的长对话。3.3 监控服务状态日志和指标接口服务启动起来之后不能只看进程在不在。vLLM的日志会实时打印两行关键信息Running: 8 reqs, Waiting: 2 reqs Throughput: 356.8 tokens/sRunning是正在生成token的请求数Waiting是在队列里等待调度的请求数。如果Waiting长期很大说明并发窗口或者调度策略跟不上。Throughput是实际每秒生成token的数量这是衡量服务处理能力最直接的数字。vLLM还暴露了/metrics端点输出Prometheus格式的指标数据比如vllm:num_requests_running、vllm:time_to_first_token_seconds等。生产环境我建议直接接PrometheusGrafana把TTFT和TPOT这两个指标画出来。TTFT是首字延迟用户体感主要受它影响TPOT是每个token的生成时间反映模型推理速度。4. 实战部署DeepSeek与Qwen4.1 跑DeepSeek-R1-Distill和DeepSeek-V3最近“vllm部署deepseek”这个搜索词热度一直很高但很多人一上来就想部署DeepSeek-V3这个671B的大家伙结果一看显存傻眼了就算FP8量化权重也要670GB左右单机四卡H100都不一定吃得下更别提高并发下的KV cache开销。所以实际部署我强烈建议先从蒸馏版本入手。我自己线上跑的是deepseek-ai/DeepSeek-R1-Distill-Qwen-32B四张A100 80G配置如下vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-32B \ --tensor-parallel-size 4 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9 \ --served-model-name deepseek-r1 \ --dtype bfloat16 \ --max-num-seqs 64这里--tensor-parallel-size 4会把模型切分到四张卡上模型权重平均分摊推理时通过NCCL做all-reduce同步。多卡模式下--dtype bfloat16是比较稳的选择fp16在部分显卡上容易遇到精度和数值溢出的边界问题。如果你真的需要上DeepSeek-V3或V3.1这种超大MoE要确认vLLM 0.29对MoE模型的支持是否完整启动参数里大概率还需要调整专家并行Expert Parallel相关的选项。模型加载时间会非常长经常要等几分钟到十几分钟。建议把--max-num-seqs调高到128甚至256因为MoE模型参数量虽大单次推理只激活部分专家连续批处理能榨出更多吞吐。另外V3推荐直接在FP8下跑能省将近一半显存。4.2 单卡跑Qwen3.8-Flash-Next的配置“qwen3.8-flash-next”这类轻量模型是我个人最喜欢的Online Serving入门选择。单卡就能跑显存压力小启动快非常适合先把服务链路调通再切换到更大模型。vllm serve Qwen/Qwen3.8-Flash-Next \ --served-model-name qwen-flash \ --max-model-len 32768 \ --gpu-memory-utilization 0.85 \ --max-num-seqs 128 \ --enable-prefix-caching单卡部署的要点在于不要盲目堆max-num-seqs虽然128看起来能同时处理更多请求但每个请求都会占用KV cache。我自己实测在A100 80G上max-model-len设为32768、并发128时吞吐已经相当可观再往上调并发TTFT反而会因为排队和显存换页变长。适度的并发能压满GPU过度的并发只会制造排队。如果第一遍启动发现OOM我的调试顺序是先把max-model-len降到16384再把gpu-memory-utilization降到0.8最后才考虑压缩并发。这三个参数按这个顺序调90%的启动OOM都能解决。4.3 用OpenAI客户端调通接口vLLM的OpenAI兼容API意味着你不需要引入任何vLLM专属SDK直接用openai这个Python包就行。from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) resp client.chat.completions.create( modelqwen-flash, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 用一句话解释vLLM的工作原理}, ], max_tokens512, ) print(resp.choices[0].message.content)注意api_key随便填什么vLLM默认不做鉴权。model字段要填--served-model-name指定的名字否则会报model not found。不用Python的话curl一样能调curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen-flash, messages: [{role: user, content: 你好}], max_tokens: 256 }返回的JSON结构和OpenAI官方完全一致choices[0].message.content就是模型生成的文本usage里会带上prompt和completion的token数量。线上如果要做流式输出加上stream: true然后按data:前缀逐行解析SSE事件即可。5. 常见问题排查与避坑清单5.1 CUDA out of memory这是Online Serving里出现频率最高的报错但原因往往不是单一的。启动阶段就OOM十有八九是max-model-len或者gpu-memory-utilization配置和模型权重不匹配。先用一个保守参数启动--max-model-len 8192 --gpu-memory-utilization 0.7 --max-num-seqs 16如果这样能起来再逐步放大每放大一个参数就观察日志里的显存占用。运行过程中OOM通常和并发有关。某个长请求临时把KV cache池占满了新请求找不到可用空间。可以适当降低max-num-seqs或者开启--enable-chunked-prefill让单个长prompt不要一次性占满所有缓存。还有一个细节如果模型本身是用FP16权重跑显存里还要放CUDA graph的捕获区域这部分显存不会被计入KV cache预算。所以别把gpu-memory-utilization调到0.99给自己留点余地。5.2 NCCL、多卡并行与等待多卡启动时进程卡在“正在初始化模型”或直接报NCCL error最常见的两个原因一是网络通信端口被防火墙拦截二是GPU之间通信拓扑有问题。排查第一步先把NCCL日志打开NCCL_DEBUGINFO vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-32B --tensor-parallel-size 4日志会打印出每个rank的建立过程如果卡在connect或报timeout基本就是网络问题。另外检查一下CUDA_VISIBLE_DEVICES的设置多卡机器上顺序很重要写错了会让vLLM以为只用了一张卡。用nvidia-smi topo -m可以查看GPU之间的拓扑关系有NVLink连接的卡之间做tensor parallel性能最好。5.3 量化、长文本、模板兼容性问题量化模型跑起来出现奇怪的输出或者prompt被截断先检查--quantization参数是否有指定。AWQ和GPTQ模型需要对应量化格式有些模型目录里同时有fp16和awq两套权重文件vLLM会优先按模型卡片的quant_method来判断判断不准时就手动指定。长文本场景下输出突然变成乱码或重复token多半是上下文长度接近模型训练上限模型开始“放飞自我”。这不是vLLM的bug而是模型本身的能力边界。解决办法是业务层面截断历史消息不要把所有内容都塞给模型。还有一类问题是chat template错乱。Qwen这类模型在tokenizer的chat_template字段里已经内置了正确的对话格式vLLM会自动识别。但如果你用的是自己拼接的prompt格式再配上错误的模板模型就会胡说八道。遇到异常输出先检查请求里的messages格式是否正确不要先怀疑vLLM。5.4 高并发下的超时与排队本地测试一切正常线上一上量就出现ReadTimeout、connection reset by peer问题往往不在vLLM本身而在TCP连接和请求排队。vLLM会为每个请求分配一个KV cache槽位当所有槽位都占用时新请求进入Waiting队列。如果Waiting队列太长客户端设置的超时时间又很短自然就断连了。我的经验是客户端超时设置至少60秒长文本场景300秒服务端这边提高max-num-seqs可以加快排队消化速度但如果显存已经打满提这个参数只会让OOM来得更快。更优雅的做法是做两层负载均衡前面加一层API网关做流量控制vLLM服务本身放在内网不直接暴露公网。这样即使有突发流量也能在网关层先限流避免服务端被瞬时并发打崩。这篇笔记写到这最想说的其实是开头那句话环境干净比什么都重要。vLLM 0.29的Online Serving本身已经足够好用但我见过太多人栽在装环境、调版本、改参数这些前置环节上反而没机会体验它真正的调度能力。如果你是第一次接触vLLM建议先拿Qwen这类小模型单卡跑通一遍再上多卡跑DeepSeek链路通了后面就顺了。等你们部署过程中踩到什么新坑欢迎再交流。