当你的业务需要接入大模型推理能力时vLLM 是目前性价比最高的方案之一。无论是本地私有化部署 Qwen、Llama 这类开源模型还是想基于 OpenAI 兼容协议快速改造现有系统vLLM 都能显著提升吞吐、降低显存占用。本文将完整拆解从环境搭建、核心原理到生产部署的全流程附带常见报错解决方案新手入门、后端项目落地都适用。先说一个典型场景同样一块 GPU直接用 HuggingFace Transformers 加载 Qwen3-8B 做并发推理显存很快打满多个请求排队等待首字延迟高换成 vLLM 之后同样的硬件却能支撑几十路并发吞吐提升非常明显。这个差距从哪来答案就在 vLLM 的两个核心设计里PagedAttention和连续批处理。下面我们围绕这两点展开再结合完整可运行的部署示例带你快速上手 vLLM。1. 为什么本地部署大模型总是“慢半拍”很多同学第一次在本地跑大模型用的都是 Transformers 库的generate方法。这种方式在单条请求、小并发场景下没有问题但一旦进入真实业务问题就会集中爆发。第一个瓶颈是显存浪费。Decoder 模型在生成每一个 token 时都需要把之前所有 token 的 Key 和 Value 缓存下来这些缓存称为 KV Cache。不同序列长度不同、请求数量不同KV Cache 的大小也在动态变化。传统框架通常按最大长度预先分配一块连续显存实际用不满的部分就白白浪费了。直观地说你在 24GB 显存上可能只能同时跑 2 到 3 个并发请求大部分显存都花在了预留空间上。第二个瓶颈是批处理方式落后。HuggingFace 的generate方法默认采用静态批处理一批请求同时开始必须等最慢的那个生成完整批才能释放。如果这批请求里有长文本其他短请求只能空等GPU 利用率被拉低。第三个瓶颈是调度开销。传统推理框架没有显式的调度器每个请求都占一份 GPU 资源请求多了就轮流排队整体延迟不可控。vLLM 正是为了解决这三个问题而设计的。它把 KV Cache 的管理方式从“连续显存”改成了“分页显存”同时引入连续批处理机制让 GPU 始终处理“此刻真正在计算”的请求而不是等待整批结束。2. 环境准备与版本说明vLLM 对运行环境有一定要求建议在 Linux 环境下使用常见的 Ubuntu 20.04 / 22.04 都是官方支持范围。Windows 虽然可以通过 WSL 运行但生产环境更推荐直接使用 Linux 服务器。需要准备的基础环境如下操作系统Ubuntu 20.04 或 22.04本文示例以 Ubuntu 22.04 为准Python3.9 到 3.12 之间推荐 3.10 或 3.11GPUNVIDIA 显卡支持 CUDA建议显存 16GB 以上CUDA 驱动建议 11.8 或 12.1 及以上PyTorch2.0 或以上安装 vLLM 时会自动匹配模型本文以 Qwen3-8B 为例你也可以换成 Qwen2.5、Llama 3 等开源模型这里要特别提醒一点版本需要根据你的项目实际情况调整。vLLM 版本更新非常快不同版本对 CUDA、Python、PyTorch 的兼容性略有差异。建议你通过官方 PyPI 页面或 GitHub Releases 查看当前最新版本的依赖要求再决定具体安装方式。3. vLLM 核心原理拆解在正式部署之前我们先拆解 vLLM 的两个核心设计。理解了它们后面排查问题时思路会清晰很多。3.1 PagedAttention像操作系统管理内存一样管理显存PagedAttention 的思路借鉴了操作系统的虚拟内存分页机制。传统推理框架为 KV Cache 分配连续显存而 vLLM 会把 KV Cache 切成固定大小的块每个块可以存储在显存的任意位置块与块之间用索引表关联。举个例子假设一个请求需要 64 个 token 长度的 KV Cache传统方式会一次性预留一整块足够装 64 个 token 的连续显存。但实际生成过程中这 64 个 token 不是一开始就全部存在而是逐个生成的。如果请求只生成到 20 个 token 就结束剩下 44 个 token 的预留空间就浪费了。vLLM 的处理方式是按需分配小块每个块默认可以存储 16 个 token 的 KV Cache。生成时先用 2 个块承载 32 token不够了再追加第 3 个块。这样显存利用率变得非常接近 100%不会因为预留空间造成浪费。同时因为块可以不连续存放vLLM 可以在一个物理显存区域里混合存储多个请求的 KV Cache只要每个请求维护自己的块索引表即可。这在连续批处理中非常关键多个并发请求共享同一块显存空间谁需要增长谁就申请新块。PagedAttention 带来的直接收益有两个显存利用率大幅提升同一块 GPU 可以容纳更多并发请求吞吐量提高因为可并发执行的请求数量变多了。3.2 连续批处理不让 GPU 等任何一个请求连续批处理是 vLLM 另一个核心机制。它解决的是传统静态批处理的等待问题。在静态批处理中GPU 一次处理一批请求这批请求必须同时完成才能进入下一批。如果某个请求生成了很长的回复其他短请求只能等着。在连续批处理中调度器会以 token 级别进行调度。每个推理步骤step结束后系统检查当前批次的请求状态已经生成结束的请求立即释放显存还在生成中的请求继续参与下一轮计算新到达的请求可以在任意时刻插入当前批次。整个过程像流水线一样GPU 每个 step 都在做有效计算不会出现“一长拖慢全批”的情况。你不需要手动开启这个功能vLLM 默认就启用连续批处理。但它不是无限地堆并发你可以通过配置参数控制最大批大小避免显存溢出。相关参数是--max-num-seqs、--max-num-batched-tokens后面会用到。4. 快速部署用 vLLM 启动 Qwen3 模型这一节我们从零开始完成 vLLM 的安装、模型下载和服务启动最终达到“通过 API 调用本地模型”的效果。4.1 安装 vLLM建议创建独立的 Python 虚拟环境避免污染系统环境。python3 -m venv vllm-env source vllm-env/bin/activate pip install --upgrade pip pip install vllm如果网络环境允许建议使用 FastAPIs 和 uvicornvLLM 的 OpenAI 兼容服务依赖这两个组件安装 vLLM 时通常会自动带上。安装完成后验证一下python -c import vllm; print(vllm.__version__)能正常输出版本号说明安装成功。如果你的 CUDA 版本比较特殊建议根据官方文档选择对应的预编译 wheel 包安装避免编译过程中出现兼容性问题。4.2 下载模型vLLM 本身不提供模型下载功能它需要你通过 HuggingFace 下载模型到本地目录。如果你在境内网络环境建议配置镜像加速。export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B --local-dir ./models/Qwen3-8B如果不想安装 HuggingFace CLI也可以直接使用git lfs clonegit lfs install git clone https://hf-mirror.com/Qwen/Qwen3-8B ./models/Qwen3-8B模型文件较大约 16GB 左右下载时间取决于网络状况。下载完成后确认目录下包含config.json、model.safetensors或分片文件以及tokenizer.json。4.3 启动 OpenAI 兼容服务vLLM 提供了一条命令启动 OpenAI 兼容 API 服务python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen3-8B \ --served-model-name qwen3-8b \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 32参数说明--model模型路径可以是 HuggingFace 模型 ID也可以是本地目录--served-model-name对外暴露的模型名称客户端调用时使用的名字--host监听地址0.0.0.0表示允许外部访问--portAPI 服务端口--max-model-len模型支持的最大上下文长度这个值需要根据你的 GPU 显存调整--gpu-memory-utilization允许 vLLM 使用的显存比例默认 0.9--max-num-seqs最大并发序列数值越大吞吐越高但显存压力也越大。如果你在部署 Qwen3-8B 时显存不足可以把--max-model-len降到 4096或者把--max-num-seqs降到 16优先保证服务能启动。启动成功后终端会输出类似下面的信息INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000这时再开一个终端请求一下模型列表接口curl http://localhost:8000/v1/models正常响应里会包含模型名称和元信息说明服务已经启动。4.4 验证一次完整推理用 curl 发送一次对话请求curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-8b, messages: [ {role: user, content: 用一句话解释什么是大语言模型} ], max_tokens: 128, temperature: 0.7 }返回结果的choices[0].message.content字段就是模型生成的回答。到这里一个完整的 vLLM 推理服务已经跑起来了。5. Python 实战调用 OpenAI 兼容 API服务启动后你可以像调用 OpenAI 官方 API 一样调用本地模型。只需要把base_url指向本地服务地址即可。5.1 基础调用示例首先安装 OpenAI Python SDKpip install openai然后编写一个最简单的调用脚本# 文件chat_demo.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelqwen3-8b, messages[ {role: system, content: 你是一个乐于助人的AI助手。}, {role: user, content: 请给我三个Python学习建议。}, ], temperature0.7, max_tokens512, ) print(response.choices[0].message.content)这里有一个关键点api_key填什么都可以因为 vLLM 默认不校验 API Key但 OpenAI SDK 要求这个字段不能为空。如果你的服务部署在公网建议增加网关鉴权不要直接裸奔。运行python chat_demo.py如果一切正常终端会输出模型生成的回答。5.2 流式输出示例流式输出更适合聊天机器人场景可以逐字显示生成内容显著降低用户的等待感。# 文件chat_stream.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) stream client.chat.completions.create( modelqwen3-8b, messages[ {role: user, content: 介绍一下vLLM的主要特点}, ], max_tokens1024, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)5.3 并发吞吐压测思路为了验证 vLLM 的吞吐优势可以写一个简单的并发脚本同时发送多个请求观察完成时间和显存变化。# 文件concurrency_test.py import concurrent.futures from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) def single_request(i): response client.chat.completions.create( modelqwen3-8b, messages[{role: user, content: 请从1数到50中间用逗号分隔。}], max_tokens512, temperature0.3, ) return len(response.choices[0].message.content) with concurrent.futures.ThreadPoolExecutor(max_workers16) as executor: futures [executor.submit(single_request, i) for i in range(16)] for future in concurrent.futures.as_completed(futures): print(完成一次请求返回长度:, future.result())压测时可以用nvidia-smi观察显存和 GPU 利用率。你会发现 vLLM 能把 GPU 利用率拉得很高而不是像传统方式那样大部分时间在处理排队等待。6. 常见问题与排查思路下面整理几个高频问题大家部署时遇到概率较高。问题现象常见原因解决思路启动时提示 CUDA out of memorymax-model-len设置过大或 GPU 显存不足降低--max-model-len或减小--gpu-memory-utilization也可以换成量化模型服务启动成功但请求超时显存接近上限导致调度等待降低--max-num-seqs减小最大并发数客户端报 model not foundserved-model-name与请求中的 model 不一致检查请求中的模型名并与启动参数对齐首字延迟很高生成长度远超预期或并发过多适当降低max_tokens检查是否存在慢请求占用 Batch调用时出现 expecting value 错误服务返回非 JSON 内容常见于代理或负载均衡拦截直接访问 vLLM 地址测试排查中间层问题多卡环境无法双卡运行模型未正确设置张量并行参数启动时添加--tensor-parallel-size 2再说几个值得注意的点关于--max-model-len的坑。这个参数很多人随意设置结果显存直接打满。它决定了模型可以处理的最大上下文长度包括输入和输出。Qwen3-8B 官方支持 32768 甚至更长的上下文但你的显存不一定装得下。如果显存不够优先缩短上下文长度这样单请求显存占用会明显下降。关于量化模型。显存不够用的时候量化是最直接的方案。vLLM 支持 AWQ、GPTQ、FP8 等量化模型的加载。例如启动 AWQ 量化模型只需在参数中指定--quantization awq模型路径换成量化后的权重目录即可。量化模型在精度上会有少量损失但换来的显存节省非常可观。关于 vLLM 部署的本地模型能否联网。vLLM 本身只是推理服务不负责网络访问。模型是否联网取决于你调用的工具或插件比如接入搜索 API 或 RAG 检索服务。如果只是纯聊天模型没有联网能力。7. 最佳实践与生产建议从“能跑”到“跑得稳、跑得快、可运维”中间还有不少工程细节。这里总结几条实际项目里最值得注意的建议。第一合理设置服务参数不要盲目拉满。很多人调参只看吞吐把--max-num-seqs设得很高。实际上并发数过高时每个请求的排队时长也会变长整体响应时间反而上升。建议根据业务场景做一次压测找到一个吞吐和延迟的平衡点。线上业务如果对首字延迟敏感比如聊天机器人建议降低并发上限如果是离线批量任务可以把并发调高追求吞吐。第二使用模型量化策略应对显存瓶颈。现在开源社区基本都会发布量化版本比如 Qwen3 系列的 FP8、AWQ、GPTQ 版本。量化后模型体积可能缩小到原来的一半甚至更少。对生产环境来说量化不是“可选方案”而是“标配方案”之一。量化版本部署时建议和原版做一轮效果对比确认精度在可接受范围内。第三日志和监控要提前接入。vLLM 本身带有 Prometheus 指标输出能力通过--enable-metrics开启后可以采集 token 吞吐、请求延迟、GPU 显存使用等指标。配合 Grafana 做可视化大盘能及时发现问题。具体指标地址可以通过/metrics路径获取。第四Docker Compose 部署更利于运维。生产环境不建议直接裸跑进程。把 vLLM 服务容器化配合 Compose 管理可以做到一键启动、资源限制、日志收集。类似的配置文件可以这样写# 文件docker-compose.yml services: vllm: image: vllm/vllm-openai:latest command: - --model - /models/Qwen3-8B - --served-model-name - qwen3-8b - --host - 0.0.0.0 - --port - 8000 - --max-model-len - 8192 volumes: - ./models:/models ports: - 8000:8000 environment: - HF_HOME/models - CUDA_VISIBLE_DEVICES0,1 deploy: resources: reservations: devices: - driver: nvidia count: 2 capabilities: [gpu] restart: unless-stopped注意这里使用的是vllm/vllm-openai镜像实际使用时请根据你当前的 vLLM 版本选择合适的镜像 tag。配置文件里指定了CUDA_VISIBLE_DEVICES0,1表示使用两张 GPU如果你只有一张卡需要删掉对应环境变量。第五对外暴露服务必须加鉴权。vLLM 的 OpenAI 兼容服务本身不校验 token直接暴露到公网很危险。推荐在 Nginx 或 API 网关上做一层代理统一校验 API Key、限流、审计。这一层必须做不能省。第六模型更新和回滚要有计划。生产环境不要直接覆盖旧模型目录。建议保留上一版本模型目录切换时先部署新服务验证没有问题后再切流量。这样即使新模型效果不佳也能快速回滚。8. 总结与学习路线本文围绕 vLLM 做了完整拆解先解释了 GPU 推理慢的三个瓶颈再深入讲解 PagedAttention 和连续批处理两大核心机制然后从安装环境、下载模型、启动服务到 Python 调用走通了完整流程。最后整理了常见问题和生产部署建议。现在你已经能把一个开源模型部署成标准 OpenAI 兼容服务并通过 Python 调用。下一步进阶方向有三个一是继续学习 LLM 推理优化的其他技术比 FlashAttention、投机解码、前缀缓存等二是深入理解量化原理掌握 AWQ、GPTQ、FP8 的原理差异和适用场景三是把模型接入到 RAG、Agent、Function Calling 等真实业务链路解决更多实际问题。vLLM 项目迭代非常快很多时候问题并不是“a 行不行”而是“在当前版本、当前硬件、当前模型下怎么组合最优”。建议你在动手部署时先跑通最小可用版本再逐步调整参数配合压测数据去做决策。如果本文对你有帮助可以收藏备用后续部署大模型时随手查一查。