★ FEATURED ARTICLE 如果你最近在捣鼓大模型应用十有八九会撞见vLLM这个名字。它不是一个模型而是一套把大模型跑成服务的推理框架核心就干两件事把推理速度提上去把显存利用榨干。网上教程很多但真正从零开始装、启动、调显存一路走下来的完整记录反而很少尤其是那些“官方文档没写、但实际必踩”的坑。这篇文章就把我踩过的路完整走一遍从环境准备、安装启动到显存参数逐条调优最后附上压测数据和问题排查经验。适合要在自己机器上部署 Qwen、DeepSeek 蒸馏版等模型或者正在为团队做推理服务的同学参考。1. 动手之前先搞懂vLLM 到底是干什么的值不值得装1.1 三个核心机制PagedAttention、Continuous Batching、算子融合先花五分钟理解 vLLM 为什么快否则后面调参全是瞎猜。它最核心的是PagedAttention分页注意力。传统推理框架在生成每个 token 时会把历史 token 的 KV 缓存Key-Value Cache连续分配一整块显存但序列长短不一有人生 100 个 token有人生 1000 个按最大长度预留必然浪费。vLLM 学的是操作系统的分页内存管理把 KV 缓存切成固定大小的块按需分配、不连续也没关系。你不需要知道它的底层指针怎么跳只需要理解一个结论同样的显存vLLM 能同时跑的并发请求数比传统方案多出一个量级。第二个机制是Continuous Batching连续批处理。传统做法是一批请求一起进、一起出有人已经生成完了也得等着整批结束GPU 在等待期间基本在空转。vLLM 的做法是“动态拼桌”任何一个请求生成完毕立刻释放它的显存并把新的请求塞进同一个 batch。就像快餐店翻台不是等一桌全吃完才让下一桌进而是哪个位子空了立刻补人。这对在线服务太关键了尤其是多用户并发。第三个是算子融合把多个小 GPU 算子合成一个大算子减少 kernel 启动开销。这一层普通用户感知不大但累计起来对吞吐提升很可观。vLLM 本身还会自动选最优后端比如 FlashAttention所以你想手动干预的地方其实不多。搞清这三点你就明白vLLM 解决的是“怎么把模型跑快、跑满”的问题模型本身的智商则由你选的权重决定。它不是一个模型更像一个“装载引擎”。所以你别指望部署了一个 7B 模型就比原版聪明但你可以指望它比原版跑得稳、扛得住并发。1.2 部署前必须确认的硬件与软件前置条件vLLM 对 GPU 有强依赖本质上指望 NVIDIA 的 CUDAAMD 那边有 ROCm 的试验性支持但别拿生产环境去赌。NVIDIA 显卡起步建议20 系以上实际上 30 系、40 系最稳良心推荐单卡 24GB 的 3090 或 4090 作为个人部署起点。原因很简单一个 7B 模型 BF16 权重约 14GB剩下 10GB 正好留给 KV Cache 和推理中间数据起步刚好不憋屈。显存这块先记一个粗略公式总显存需求 ≈ 模型权重 KV Cache 激活值 CUDA Context。权重最好算参数量乘以每个参数字节数BF16/FP16 约 2 字节INT8 约 1 字节INT4 约 0.5 字节。7B 模型 BF16 就是 7B × 2 ≈ 14GB。KV Cache 是变量取决于并发数、序列长度和模型层数后面第 4 章我会给完整计算。激活值和 CUDA Context 通常吃 1~2GB 左右不能忽视。系统层面vLLM 官方保证 Linux 环境这正是很多人卡住的点。Windows 上能用但要走 WSL2 或社区版后面单独说。CUDA 版本建议用 12.x 系列我个人建议直接看官方文档当前推荐的组合别自己乱配。Python 要 3.10 以上3.10/3.11 比较稳太新的 3.13 偶尔有第三方库还没跟上。2. 安装pip 一行的背后藏着一堆版本匹配问题2.1 CUDA、PyTorch、vLLM 三者版本要“锁死”很多新手以为pip install vllm就完事了装完一跑各种报错根本原因在于vLLM 不是纯 Python 库它带一堆 CUDA 编译的二进制扩展对 PyTorch 和 CUDA 版本非常敏感。说直白点vLLM 是在某个特定 PyTorch 版本上编译出来的你用不同版本运行时很可能因为 ABI 不兼容直接崩。而且 vLLM 的依赖解析是强制的它发现你环境里的 torch 版本不对会直接把 torch 卸载重装成它自己要的版本。这就是热门搜索里“安装 vllm 会改变已经安装好的 torch”这个坑的来历。我真实遇到过环境里原本有 PyTorch 2.3项目里其他代码都好好的装完 vLLM 之后 torch 变成了 2.5结果另一个依赖旧版 torch 的库直接 ImportError。所以第一原则就是永远给 vLLM 建一个独立 conda 虚拟环境别往 base 环境里塞。我用的是这套组合conda create -n vllm python3.10 -y conda activate vllm pip install vllm如果你要完全复刻一个已验证环境建议顺序是先按 PyTorch 官网装好指定版本再装 vLLM装完立刻python -c import vllm; print(vllm.__version__)和python -c import torch; print(torch.__version__)验证一下确保没被悄悄替换。2.2 pip 安装与源码编译两条路怎么选绝大多数场景pip install vllm就够了。它会自动下载与当前 CUDA 版本匹配的预编译 wheel装完直接能用。如果你想体验最新特性或者用的显卡比较新也可以指定 wheel 通道。源码编译适合两类人一是要改 vLLM 内部逻辑做魔改的二是官方 wheel 没覆盖你 GPU 架构的。编译流程网上资料很多我这里只提醒一点源码编译前必须把 CUDA toolkit、GCC、ninja 装齐否则中途报错够你折腾一下午。编译一次大约 20~40 分钟取决于机器性能。我自己的经验先用 pip 版本验证整套流程确认模型和数据没问题之后再考虑要不要源码编译冲新特性不要一上来就编译。2.3 Windows 装 vLLM 的额外说明官方二进制只为 Linux 做了保证Windows 上装 vLLM 有两种主流路径。第一种是 WSL2Windows Subsystem for Linux这也是我比较推荐的方式在 Windows 上装好 WSL2 发行版比如 Ubuntu安装 CUDA 驱动时用的是 Windows 侧的驱动WSL2 内部直接用/usr/local/cuda工具链GPU 通过 WSL 透传性能和原生 Linux 非常接近。第二种是社区版也就是最近热词里提到的 vLLM Windows 社区版。这套方案能在纯 Windows 环境跑但涉及额外 Python 包安装稳定性看版本遇到问题反馈渠道也不如 Linux 丰富。如果你是 Windows 用户我的建议是生产项目老老实实 WSL2纯学习尝鲜可以试试社区版。WSL2 有两个小坑你一定会遇到一是模型权重放在/mnt/c/...这种 Windows 挂载路径下时文件读取比 Linux 原生磁盘慢很多建议把权重复制到 WSL 的 ext4 文件系统里二是跨文件系统路径容易触发权限问题启动时如果报Permission denied优先排查权重文件在不在 ext4 目录下。3. 启动从“命令行能跑”到“接口稳定响应”3.1 一条命令把模型拉起启动参数逐个拆解装好之后最直接的验证方式是用 vLLM 自带的 OpenAI 兼容 API 服务启动。下面这条命令是启动 Qwen2.5-7B-Instruct 的完整示例python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen-7b \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.85 \ --max-model-len 8192每个参数都有它的定位。--model填 HuggingFace 上的模型 ID 或本地权重目录--served-model-name是暴露给客户端看的模型别名你可以随意取方便以后换模型外层不用改--host 0.0.0.0表示允许局域网内其他机器访问如果只是本机调试改成127.0.0.1更安全--port 8000是 API 服务端口。后面两个参数是显存调优的关键第 4 章重点讲。启动日志里你会看到 vLLM 输出模型的参数量、层数、KV Cache 大小等关键信息。等看到Uvicorn running on http://0.0.0.0:8000类似字样说明服务已经起来了。然后可以通过 curl 快速验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen-7b, messages: [{role: user, content: 你好介绍下你自己}], max_tokens: 128 }这条命令如果返回一段正常的 JSON 回复说明整套链路全通了。用 Python 请求库调用也差不多核心就是 POST 到/v1/chat/completions传model、messages、max_tokens这几个字段。顺便说一句vLLM 同时支持/v1/completions想做纯文本补全或测试生成质量时很好用。3.2 用脚本封装成“随时可重启的服务”裸命令行启动有几个问题你关了终端服务就断了崩溃后没有自动拉起启动参数一变就混乱。我习惯写一个start.sh脚本把环境激活、GPU 检查、端口检查、日志记录都串起来。#!/bin/bash # vLLM 服务启动脚本 conda activate vllm # 检查 GPU 状态 nvidia-smi --query-gpumemory.total,memory.used --formatcsv # 检查端口是否被占用 if ss -tln | grep -q :8000; then echo 端口 8000 已被占用请先释放 exit 1 fi # 后台启动并将日志写入文件 nohup python -m vllm.entrypoints.openai.api_server \ --model ./models/qwen2.5-7b-instruct \ --served-model-name qwen-7b \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.85 vllm.log 21 echo 服务启动中日志见 vllm.log日志文件很重要。vLLM 在运行期遇到的问题基本都会写进日志排查时第一件事就是看最后的输出而不是到处搜报错。如果你在一个长期运行的服务器上部署还可以用 systemd 或 supervisord 来做进程守护这部分属于部署工程化的范畴了先不展开。3.3 启动失败的高频原因与排查手法启动失败的情况非常多我总结三个最高频的。第一种是CUDA 版本不匹配典型报错是类似CUDA error: no kernel image is available on the device或者ImportError: libcudart.so.xx。这说明你跑 vLLM 的那个 Python 进程找不到合适的 CUDA 运行时。排查方法是确认nvidia-smi显示的驱动版本然后python -c import torch; print(torch.version.cuda)如果前后不一致基本就是环境混了。解决思路是重建干净 conda 环境重新装一遍 vLLM别再往老环境里补。第二种是端口被占服务一启动就退看日志会发现Address already in use。用ss -lntp | grep 8000找到占用进程kill 掉或者换个端口。第三种是模型路径加载失败日志里出现FileNotFoundError或The models config.json is missing。这个问题往往是路径写错了或者 HuggingFace 需要联网验证。优先使用本地目录先把模型权重完整下载到本地启动命令里填本地绝对路径不要每次启动都去 HF 仓库拉取。4. 显存调优从“一跑就 OOM”到“把每一 MB 显存榨干”4.1 先学会算显存账权重、KV Cache、激活值各占多少显存调优不是玄学核心就是把账算明白。前面说过权重是固定开销KV Cache 是浮动大头它由并发请求数、序列长度、模型结构共同决定。单层 KV Cache 占用的显存公式是2K 和 V 两份 × num_kv_heads × head_dim × block_size × 每个元素字节数这里num_kv_heads是模型里 KV 头的数量head_dim是每个头的维度这些值在模型的config.json里都能查到。整卡要预分的 KV Cache 总量是“每层占用 × 层数 × 序列总长度”其中序列总长度近似等于并发数 × 平均序列长度。说得更实操一点vLLM 启动时并不是等请求来了才分配 KV Cache而是提前从显存里划出一大块预留区域大小由gpu_memory_utilization决定用不完的部分也不会给其他进程。所以你会看到一种现象明明 GPU 利用率才 10%显存已经被 vLLM 占了大半。这不是泄露是预分配机制。我实际跑过一个 7B 模型的估算BF16 权重 14GB如果显存总共 24GBgpu_memory_utilization0.9那么 KV Cache 大约能拿到24×0.9 - 14 - 2激活与CUDA Context≈ 5.6GB。这 5.6GB 能支持多长的并发序列取决于模型层数、KV 头数。所以一个常见误区是我把max_model_len设成 32K模型就能处理 32K 上下文但实际上 KV Cache 装不下那么大的序列服务照样 OOM。4.2 第一刀gpu_memory_utilization 到底给多少合适--gpu-memory-utilization默认 0.9意思是 vLLM 最多用 90% 的显存。很多人为了多塞点并发一上来就调到 0.95结果启动直接报 CUDA out of memory这是典型的“贪心反噬”。原因在于 GPU 上除了 vLLM 还有 CUDA Context、驱动预留、其他进程占用的显存你还要给 PyTorch 的动态分配留一点余量。我的经验是从 0.85 起步跑一个 2~4 并发的压测观察显存占用和报错没有 OOM 逐步加 0.02~0.03直到接近临界点再回退 0.02 作为安全余量。单卡 24GB 跑 7B 模型时0.85~0.9 是比较舒服的区间。多卡环境还要注意每张卡的显存可能不完全一样比如非对称卡组vLLM 遵循木桶效应以最小那张卡的可用显存为准。配套gpu-memory-utilization的还有两个“限流阀”--max-num-seqs控制最多同时处理多少序列--max-num-batched-tokens控制每批次最多处理多少 token。它们的作用是防止某个突发大请求瞬间冲爆显存预留区。预算不够充足时把--max-num-seqs设成 16 或 32能让服务的行为更可预测。4.3 第二刀max_model_len、block_size 与 KV Cache 的联动--max-model-len是影响显存分配的隐形大手。它告诉 vLLM 每条请求最长可以多少 tokenvLLM 按这个上限预分配 KV Cache 块。如果你设置 32K但业务平均只有 2K 上下文那大部分预留显存都在“干瞪眼”白白浪费。反过来如果你不小心设太小长文档请求直接报错。这是一个典型的参数匹配问题。我的建议是先统计你业务里的最大上下文需求然后按业务需求上限 × 1.2 倍来设max-model-len。比如你确定不会超过 8K就设 8192如果你偶尔有 16K 的文档再考虑 16384。不要盲目追求大大意味着 KV Cache 预分配更多能容纳的并发更少。--block-size默认是 16表示 KV Cache 按 16 个 token 一块来分配。如果你的业务大多是很短的文本比如单轮问答把 block size 调小到 8可以让小块内碎片更少如果业务是超长文档维持 16 反而更省显存块管理开销。这个参数我一般不轻易动但在极短文本场景确实实测过有 5% 左右的吞吐提升。4.4 第三刀量化、多卡切分与 CPU Offload 实战显存实在不够用就得动量化。vLLM 支持 AWQ 和 GPTQ 两种主流量化格式。AWQ 需要额外传一个量化参数文件GPTQ 则直接从模型目录里读取相关配置。拿 7B 模型举例BF16 权重 14GB换成 INT4 量化后大约 4GB省下 10GB 全部可以挪给 KV Cache这对单卡部署非常香。多卡方案叫Tensor Parallel张量并行用--tensor-parallel-size 2指定把模型切到两张卡上跑。注意它要求卡片之间带宽足够猛NVLink 优先PCIe 也能跑但跨卡传输会成为瓶颈。这里有一个很多新手犯的错误以为两张 24GB 卡就能跑 48GB 的模型。不对张量并行是“单层模型的矩阵被切成两半分别放在两卡上”它能提升吞吐和显存容量上限但跨卡通信本身会额外占显存实际可用比例通常低于你的算术预期。CPU Offload 我一般放到最后考虑。它能把部分权重或 KV Cache 换到内存但代价是推理速度大幅下降。除非你显存只够加载权重而完全跑不动 KV Cache且对延迟不敏感否则不推荐生产环境用。4.5 实测一组显存调优数据下面这组数据是我在一张 RTX 4090 上跑 Qwen2.5-7B-Instruct单请求生成长度 256 token 时做的对比测试。测试工具是自己写的 Python 并发脚本固定总请求数 200变化的是显存参数数据大体能反映趋势配置gpu_memory_utilizationmax_model_len并发数平均吞吐(tokens/s)是否OOM配置A0.9819264约 850否配置B0.95819264启动时即OOM是配置C0.854096128约 1020否配置D0.851638432约 720否从这组数据能看出两件事第一gpu_memory_utilization调太满不会提升性能只会让你连服务都起不来第二max_model_len对并发上限有决定作用把序列长度从 8192 降到 4096KV Cache 省出的空间能多塞一倍并发吞吐反而更高。调优的核心就是不要为用不到的长上下文买单。5. 实战把 DeepSeek / Qwen 通过 vLLM 压测一遍5.1 模型选型与权重下载现在很多人想跑 DeepSeek。需要先明确一点DeepSeek-R1 满血版是 671B 的 MoE 模型个人机器基本无缘那是多卡集群专属普通人现实的选择是DeepSeek-R1-Distill-Qwen-7B或14B这类蒸馏版。它们继承了部分推理风格体量却只有 7B/14B24GB 显存就可以吃得下。下载权重有几个方式我相对推荐用 HuggingFace 官方库配合断点续传工具一次性拉全。如果直接下文件一定记得把config.json、tokenizer.json这几个配套文件都下全少一个都可能启动失败。模型文件都放到本地路径后启动命令改成--model /path/to/model_dir这样最省心。5.2 压测脚本怎么写我习惯用一个简单 Python 脚本做压测方便调整并发和收集指标。核心代码如下import time import requests from concurrent.futures import ThreadPoolExecutor URL http://localhost:8000/v1/chat/completions def send_one(idx): payload { model: qwen-7b, messages: [{role: user, content: 用一句话解释什么是大模型}], max_tokens: 128, temperature: 0.7, } start time.time() resp requests.post(URL, jsonpayload, timeout300) cost time.time() - start return cost, resp.status_code total 200 with ThreadPoolExecutor(max_workers32) as pool: results list(pool.map(send_one, range(total))) ok_count sum(1 for _, code in results if code 200) avg_cost sum(c for c, _ in results) / total print(f成功率: {ok_count}/{total}, 平均响应时间: {avg_cost:.2f}s)正式压测前我通常先发 1 个请求确认延迟基线再提到 8 并发、32 并发逐渐增加。这样做的好处是能区分“模型本身慢”和“并发上去后资源竞争导致的慢”方便定位瓶颈。注意观察两个指标吞吐每秒完成多少 token和首 token 延迟TTFT。前者反映系统的整体处理能力后者反映用户体验。vLLM 日志里自带了这两个指标也可以直接在响应结果里看时间戳计算。5.3 压测结论与调整迭代记录我实测的印象是DeepSeek-R1-Distill-Qwen-7B 用 vLLM 默认参数跑32 并发下基本稳定但显存占用达到 90% 以上。把max_model_len从默认值降低到 6000 后并发能推到 64吞吐提升约 30%。这说明对特定模型做一次参数微调收益是立竿见影的。DeepSeek 系列有一点特别提醒它们默认生成时会输出很长的思考过程max_tokens要留足否则容易截断。同时这类推理模型偏好一次输出长文本对 KV Cache 的压力更大如果不追求它的思考链建议在 prompt 层面对思考长度做限制或者在服务层把max_tokens设为一个可控值。6. 常见问题与排查技巧实录6.1 高频问题速查表症状大概率原因排查命令/方法解决办法启动报 CUDA error: out of memorygpu_memory_utilization 太高或显存被占nvidia-smi查看显存占用调低到 0.85检查是否有残留进程启动报 no kernel image availablevLLM 与 CUDA/PyTorch 版本不匹配torch.version.cuda对照重建 conda 环境按官方组合重装请求返回 404/模型名错误served-model-name 填错看启动日志中的模型名请求体里 model 字段用启动日志里的名字首次请求很慢后续变快模型权重从磁盘加载未预热无用一次空请求预热或提前加载权重WSL2 下 GPU 不可见驱动/WSL 未正确透传nvidia-smi在 WSL 里是否可用Windows 安装支持 WSL 的 NVIDIA 驱动服务运行中显存不断上涨日志级别过高或监控工具抢显存watch 显存变化检查是否有别进程占显存确认服务自身占用保持稳定6.2 我踩过的三个坑第一个坑是前文提过的“torch 被 vLLM 偷偷替换”。当时我在一个已有环境里pip install vllm后整个环境的 torch 从 2.1 跳到 2.5导致另一个项目的模型加载直接崩。从那以后我所有 vLLM 相关部署全部改用独立 conda 环境不再混用。第二个坑是gpu_memory_utilization0.95导致启动崩溃。当时 24GB 的卡上只跑一个 7B 模型算下来应该绰绰有余结果每次启动都报 CUDA error 811。后来看了 vLLM 的源码逻辑才明白它预留 KV Cache 时是按显存总量比例计算的0.95 看起来是 95% 显存但对 PyTorch 底层的 CUDA Context 分配来说余量已经被挤压到临界点。这个坑最典型的教训是显存“看起来够”和“真正够用”是两回事凡事留 10% 余量。第三个坑是max_model_len设置的“自我感动”。我一开始设成 32K想着长文档能力必须拉满结果并发稍高直接 OOM。后面统计了业务的上下文长度90% 的请求都在 2K 以内把max_model_len调到 4096 后同样显存下并发翻倍吞吐提升非常明显。在 vLLM 里大上下文不是免费的午餐它每时每刻都在用显存为你买单。我个人在使用中的体会是vLLM 的参数调优没有银弹它的本质是在“显存总量、并发数量、序列长度”三者之间做权衡。每次只动一个变量把日志和压测数据记录下来再决定下一步比凭感觉东调一下西调一下可靠多了。如果没有明确方向就按“gpu_memory_utilization → max_model_len → max_num_seqs → 量化/多卡”的顺序逐层调。最后再分享一个小技巧启动日志里 vLLM 会打印它估算的并发能力那一行字基本是你调参的北极星没事多盯着看看。
阅读完成 · 觉得有帮助？
