如果你现在还在用 HF Transformers 的原始脚本给大模型做并发服务那 2025 年你大概率会被 vLLM 拉开 5 到 10 倍的吞吐量差距。这个项目不是简单的“换一个启动脚本”而是一套完整的 LLM 推理系统核心解决两件事显存不够用和并发一高就卡。vLLM 最值得关注的是 PagedAttention 显存管理、Continuous Batching 连续批处理、自动前缀缓存以及 OpenAI 兼容 API。也就是说你既可以用它跑在线服务也可以直接做离线批量推理还能无缝接到 LangChain、FastGPT、Open WebUI 这些框架里。硬件门槛上NVIDIA GPU 是首选7B 级别模型建议 16G 以上显存小模型 6G 到 8G 也能起步Windows 支持比较弱生产推荐 Linux 或 WSL2。这篇文章会带你走一遍 vLLM 从安装部署、启动服务、功能测试、接口调用、批量任务到性能排查的完整流程。同时会把最近大家搜索比较多的问题一起处理掉比如--enforce-eager到底有什么影响、--max-num-seqs怎么调、能不能用来做 embedding/reranker、Windows 上到底能不能跑。1. vLLM 核心能力速览先看清楚 vLLM 的定位和边界再决定怎么用。能力项说明项目全称vLLM高吞吐量 LLM 推理与部署系统开源团队源自 UC Berkeley 等高校和研究机构目前是社区活跃的大模型推理项目之一核心机制PagedAttention、Continuous Batching、Automatic Prefix Caching主要功能在线 OpenAI 兼容 API 服务、离线批量推理、多模态模型推理、量化模型加载接口能力提供/v1/completions、/v1/chat/completions等兼容接口推荐硬件NVIDIA GPU 为主Ampere 架构30 系/40 系/50 系等以上体验较好显存需求由模型大小决定7B 模型通常建议 16G 左右小模型可尝试 6G-8G需按实际测试支持平台Linux 最优Windows 建议 WSL2macOS 支持有限启动方式命令行启动、Python 脚本启动、Docker 启动是否支持批量任务支持离线批量推理也支持在线接口并发调用是否支持多显卡支持张量并行Tensor Parallelism通过--tensor-parallel-size设置适用场景生产级 LLM 服务、高并发问答、长上下文推理、批量评测、多模态理解这里的重点是vLLM 不是一个“全功能 AI 平台”它做的是推理引擎负责把你训练好的或开源的大模型跑起来并且跑得快、占用更合理。2. 适用场景与使用边界2.1 适合什么场景vLLM 最擅长的场景有三类。第一类是高并发在线服务。典型例子是大模型聊天机器人、RAG 问答系统、企业内部 Copilot。这类场景下请求数量大、并发波动明显vLLM 的 Continuous Batching 能在一个迭代窗口内动态塞入新请求不会像传统批处理那样必须等整批结束才能接收下一批。第二类是长上下文推理。PagedAttention 把 KV Cache 按块管理和操作系统内存分页类似能有效减少 KV Cache 碎片化。处理长文档、长对话、论文分析这种“上下文越长越吃显存”的任务时优势很明显。第三类是离线批量推理。比如你要对 1 万条测试数据跑评测或者批量生成一批内容。vLLM 的离线接口可以直接传入一个 prompt 列表一次性调度执行。2.2 不适合什么场景先说不适合的单条短请求、对延迟极其敏感、且不关心吞吐量的场景。vLLM 的最大优势是吞吐单请求延迟不一定比专门的轻量推理引擎低。需要频繁切换多个不同模型但显存又很紧张的环境。vLLM 加载模型后会保留大量 KV Cache 空间模型热切换成本高。Windows 裸环境下的生产部署。vLLM 对 Windows 原生支持弱官方更推荐 Linux 容器。部署 embedding 向量模型和 reranker 重排模型。虽然较新版本的 vLLM 可以启动部分 embedding 模型但它核心不是向量检索服务功能成熟度和稳定性不如专门的 Text Embeddings InferenceTEI工具。如果你要在昇腾 910B-A2 这类非 NVIDIA 硬件上跑 embedding/reranker更不建议直接用 vLLM 硬上优先看厂商适配的推理框架。生成式 LLM 服务才是 vLLM 的主场。2.3 合规与安全边界部署模型时要注意模型 License 是否符合你的使用场景尤其是商用场景。如果 vLLM 服务暴露在公网必须加鉴权和访问控制避免被任意调用。多模态模型处理图片、文档时确认素材来源合法、不涉及未授权个人隐私。不要让模型基于未授权的真实人物或版权内容生成商业输出。3. 本地部署环境准备vLLM 对运行环境有一定要求安装前建议逐项检查。3.1 操作系统生产环境优先 Linux例如 Ubuntu 20.04 或 22.04。如果你只有 Windows建议安装 WSL2在 WSL2 内跑 Linux 环境。直接装 Windows 原生的 vLLM依赖冲突和 CUDA 版本兼容问题会非常多。3.2 GPU 与驱动vLLM 的加速依赖 CUDA你需要NVIDIA 显卡驱动版本满足你所装 CUDA 版本的要求。可以用nvidia-smi查看驱动版本和 GPU 显存。显存建议7B 模型 16G 左右更舒服小模型 6G 到 8G 可以起步实际占用取决于max_model_len、并发数和量化方式。3.3 Python 与 CUDAPython 版本建议 3.9 到 3.12具体看 vLLM 官方要求。CUDA 版本建议 11.8 或 12.1 等较新版本但不要直接手动安装一套和其他依赖冲突的 CUDA建议让 vLLM 的安装过程处理 PyTorch 和 CUDA 运行时匹配。必须确认 GPU 驱动能支撑对应的 CUDA runtime。更稳妥的判断是先跑通一个小模型再看日志里的设备信息和显存分配。3.4 磁盘与内存7B 模型权重文件大约 15G 左右FP16量化模型会更小Qwen 30B 级别模型需要 60G 左右磁盘空间。内存至少 16G 起步推荐 32G 以上。批量推理时 CPU 内存占用也会明显上升。3.5 安装前检查清单# 查看驱动版本和 GPU 信息 nvidia-smi # 查看 Python 版本 python --version # 查看 pip 版本 pip --version确认 NVIDIA GPU 能被系统识别后再进入安装步骤。4. 安装部署与启动方式4.1 pip 安装 vLLM最省事的方式是 pip 安装。需要注意vLLM 会自动匹配 PyTorch 和 CUDA 版本不要先手动装一个“自以为对”的 PyTorch然后再装 vLLM这样最容易出现版本冲突。pip install vllm国内网络环境如果下载慢可以使用镜像加速但要注意镜像仓库同步的版本可能稍有延迟。pip install vllm -i https://mirrors.aliyun.com/pypi/simple/如果你想用最新源码也可以从 GitHub 克隆后执行pip install -e .但对大多数使用者来说pip 稳定版就够了。4.2 命令行启动 OpenAI 兼容 API 服务启动一个标准 OpenAI 兼容服务模型以 Qwen 系列 7B 为例vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --served-model-name qwen2.5-7b \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.8 \ --max-model-len 8192 \ --max-num-seqs 32如果你用的是较旧版本的 vLLM也可以用传统入口启动python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --port 8000 \ --served-model-name qwen2.5-7b启动成功后终端会显示服务地址http://0.0.0.0:8000同时会打印 GPU 显存分配信息、KV Cache 预留空间、模型加载耗时等。4.3 Python 离线批量推理启动如果没有在线服务需求可以直接在 Python 里加载模型并批量推理。这种方式适合离线评测、批量打标签、批量内容生成。from vllm import LLM, SamplingParams llm LLM( modelQwen/Qwen2.5-7B-Instruct, tensor_parallel_size1, gpu_memory_utilization0.8, max_model_len8192, max_num_seqs32, ) sampling_params SamplingParams( temperature0.7, top_p0.9, max_tokens512, ) prompts [ 用一句话解释 vLLM 的核心优势。, 写一段 Python 代码读取 CSV 文件并统计每列缺失值。, 总结大模型部署时的显存优化方法。, ] outputs llm.generate(prompts, sampling_params) for output in outputs: print(Prompt:, output.prompt) print(Generated:, output.outputs[0].text) print( * 40)这里的gpu_memory_utilization0.8表示最多使用 80% 的可用显存剩下部分留给 CUDA context 和其他开销。max_num_seqs控制一次调度处理的最大序列数。4.4 Docker 启动如果你生产环境已经容器化优先使用 Docker 镜像。vLLM 官方提供 Dockerfile构建或拉取镜像后直接启动docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ --ipchost \ vllm/vllm-openai \ --model Qwen/Qwen2.5-7B-Instruct使用 Docker 时要注意nvidia-container-toolkit 必须安装好否则容器内识别不到 GPU。5. 功能测试与效果验证5.1 基础文本生成测试服务启动后先用 curl 验证服务是否正常响应curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-7b, messages: [ {role: user, content: 介绍一下 vLLM 的 PagedAttention} ], max_tokens: 256 }如果返回 JSON 中包含choices[0].message.content说明基础文本生成成功。判断标准返回状态码 200。返回内容不是空字符串。服务日志中能看到请求耗时和 token 吞吐数据。常见失败原因模型名称不匹配served-model-name设置的是什么请求里的model字段就必须填什么。端口被占用换成其他端口比如--port 8001。5.2 多模态模型测试较新版本的 vLLM 支持多模态模型比如 LLaVA 系列、Qwen-VL 系列。启动方式是在命令中指定多模态模型然后通过 chat completion 接口传图片 URL 或 base64 数据。curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-vl-7b, messages: [ { role: user, content: [ {type: image_url, image_url: {url: https://example.com/test.png}}, {type: text, text: 这张图片里有什么} ] } ], max_tokens: 256 }判断标准模型能基于图片内容给出合理描述。如果报错先确认模型是多模态版本再确认图片 URL 是否能被服务端访问。5.3 长上下文测试vLLM 处理长上下文的能力是它的卖点之一。你可以构造一段较长的文档要求模型从文档中间或末尾提取信息。测试时重点观察显存占用是否飙升。响应是否在合理时间内返回。模型是否丢失文档前文的信息。如果长上下文提示词超过max_model_lenvLLM 会直接报错。这时需要调大--max-model-len但显存占用也会同步增加。vllm serve Qwen/Qwen2.5-7B-Instruct \ --max-model-len 32768 \ --gpu-memory-utilization 0.95.4 并发请求测试vLLM 的优势就是高并发。我们写一个简单的 Python 脚本发送并发请求观察吞吐量和稳定性。import json import threading import time import urllib.request url http://localhost:8000/v1/chat/completions payload { model: qwen2.5-7b, messages: [{role: user, content: 用一句话解释连续批处理技术}], max_tokens: 64, } results [] def send_request(idx): data json.dumps(payload).encode(utf-8) req urllib.request.Request( url, datadata, headers{Content-Type: application/json}, ) start time.time() try: with urllib.request.urlopen(req, timeout120) as resp: body json.loads(resp.read().decode(utf-8)) content body[choices][0][message][content] cost time.time() - start results.append((idx, cost, content)) except Exception as e: results.append((idx, -1, str(e))) threads [] for i in range(50): t threading.Thread(targetsend_request, args(i,)) threads.append(t) t.start() for t in threads: t.join() success [r for r in results if r[1] 0] print(总请求数:, len(results)) print(成功数:, len(success)) print(平均耗时:, sum(r[1] for r in success) / len(success) if success else N/A)这个脚本不是压测工具只是一个快速功能验证。真正的性能数据需要用 wrk、Locust 或 Grafana k6 单独跑。6. 接口 API 与批量任务6.1 OpenAI 兼容接口说明vLLM 的在线服务最实用的地方就是接口长得很像 OpenAI。你只要把base_url换成 vLLM 地址就能用openaiPython SDK 直接调用。from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelqwen2.5-7b, messages[ {role: system, content: 你是一个技术助手。}, {role: user, content: vLLM 比传统推理快在哪里}, ], max_tokens256, temperature0.7, streamTrue, ) for chunk in response: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)如果需要流式输出设置streamTrue即可。FastGPT、Dify、Open WebUI 这类工具很多都支持自定义 OpenAI 兼容服务地址直接把地址填成 vLLM 服务即可接入。6.2 批量离线推理vLLM 的离线推理接口天然支持批量任务。你可以从文件读取所有 prompt批量传给LLM.generate。import json from vllm import LLM, SamplingParams llm LLM( modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.8, ) sampling_params SamplingParams( temperature0.7, top_p0.9, max_tokens512, ) # 从文件读取待处理列表 prompts [] with open(input_prompts.jsonl, r, encodingutf-8) as f: for line in f: data json.loads(line) prompts.append(data[prompt]) outputs llm.generate(prompts, sampling_params) with open(output_results.jsonl, w, encodingutf-8) as f: for output in outputs: record { prompt: output.prompt, result: output.outputs[0].text, } f.write(json.dumps(record, ensure_asciiFalse) \n)输入文件示例input_prompts.jsonl{prompt: 写一个关于 Spring Boot 的入门教程大纲。} {prompt: 解释 Kafka 和 RabbitMQ 的区别。} {prompt: 给出一个 Python 二分查找实现。}6.3 批量任务怎么提高成功率批量任务最怕一个请求超时或格式错误搞挂整个任务。建议每条 prompt 单独记录日志。用try-except捕获异常保存失败索引。失败任务单独重试不整体重跑。批量任务分批执行例如每次 100 条避免单次请求列表过长导致内存压力。6.4 API 调用失败排查调用接口常见的错误有三类第一类是模型名写错返回model_not_found。处理方法是把请求里的model字段设置成--served-model-name指定的名称。第二类是请求参数超过模型限制报context_length_exceeded。减少max_tokens或调大--max-model-len。第三类是服务端 OOM返回 500。需要降低--max-num-seqs、降低--gpu-memory-utilization或者换成更小的模型/量化模型。7. 资源占用与性能观察7.1 显存占用如何观察vLLM 启动日志里会直接显示 KV Cache 预留了多少显存。同时可以用 nvidia-smi 实时观察nvidia-smi -l 1-l 1表示每秒刷新一次。重点看显存占用和 GPU 利用率。vLLM 的显存分配逻辑和普通推理不同。它会把--gpu-memory-utilization指定比例内的显存全部管理起来一部分用于模型权重一部分用于 KV Cache。在服务不忙时KV Cache 不会被全部用完但日志里显示的已分配显存看起来会比较高这是正常现象。7.2--enforce-eager到底有什么影响最近很多人问--enforce-eager的作用。简单说vLLM 默认会使用 CUDA Graph 优化把某些计算图提前编译好推理时减少 CPU 和 GPU 之间的调度开销。但这会占用额外显存而且和新模型、新算子的兼容性偶尔会出问题。加上--enforce-eager之后vLLM 不再使用 CUDA Graph而是走 eager mode 即时执行。好处是启动时显存占用低一些。遇到 CUDA Graph 相关报错时可以绕过问题。适合显存紧张或模型兼容性有问题的环境。代价是吞吐量会下降单请求延迟可能变高。如果 GPU 算力足够正常生产尽量不要加这个参数。如果你的 7B 模型在 8G 显存上启动一直 OOM可以试试vllm serve Qwen/Qwen2.5-7B-Instruct \ --enforce-eager \ --gpu-memory-utilization 0.85 \ --max-model-len 40967.3--max-num-seqs怎么调--max-num-seqs控制每个调度窗口最多处理的序列数量。调大这个值并发吞吐会提升但显存占用和调度压力也会增大。调小这个值每个序列吃的资源更少适合显存受限场景。经验是16G 显存跑 7B 模型可以先设 32 到 64。显存只有 8G先把max-num-seqs降到 16 以下。具体数值以观察显存占用和吞吐变化为准不同模型差异很大。7.4 精度与量化对性能的影响vLLM 支持 FP16、BF16、INT8、INT4AWQ、GPTQ等量化模型。FP16 是默认选择精度更稳定BF16 在部分新卡上有更好的数值范围适合训练和推理INT8 和 INT4 能显著降低显存占用但输出精度会有轻微损失。如果你的显存正好卡在“差一点就能装下”的状态优先选量化版本vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \ --quantization awq \ --gpu-memory-utilization 0.85使用量化模型时要确认模型文件本身是量化过的而不是普通 FP16 权重。7.5 CPU 推理和 GPU 推理差异vLLM 主要面向 GPU 推理。CPU 模式可以跑但性能和吞吐优势会大幅缩水。如果你只在 macOS 或纯 CPU 环境更合适的选择是 llama.cpp 或其他 CPU 推理引擎而不是强行装 vLLM。8. 常见问题与排查方法问题现象可能原因排查方式解决方案安装 vLLM 时报依赖冲突PyTorch/CUDA 版本和 vLLM 不匹配查看 pip 冲突日志卸载 torch重新执行 pip install vllm让其自动匹配Windows 上启动报错vLLM 对 Windows 原生支持弱查看报错堆栈中的算子编译信息使用 WSL2 或 Linux Docker 环境模型加载后显存直接溢出max-model-len太大或gpu-memory-utilization太高观察启动日志中 KV Cache 分配数值调小--max-model-len降低--gpu-memory-utilization或使用量化模型启动时提示 CUDA 不可用驱动不满足 CUDA 版本需求运行python -c import torch; print(torch.cuda.is_available())升级 NVIDIA 驱动安装匹配的 CUDA 版本端口 8000 被占用已有服务占用该端口lsof -i :8000查看进程换端口或关闭占用进程API 返回 404路径写错或服务未完整启动检查是否访问/v1/chat/completions确认使用 OpenAI 兼容路径前缀带/v1batch 任务中间卡住单条请求超时或长上下文计算过慢查看 vLLM 日志确认是否在处理某条长 prompt降低单批数量给单个请求设置超时把失败任务单独重试用 vLLM 启动 embedding/reranker 模型失败vLLM 核心服务对象是生成式模型查询官方文档确认是否支持该模型类型部署向量模型建议使用 TEI 或 Sentence Transformers 独立服务昇腾等非 NVIDIA GPU 上跑不起来vLLM 默认适配 NVIDIA CUDA查看是否有厂商适配版本使用华为昇腾等硬件厂商发布的推理框架或分支版本不要直接硬套 vLLM 默认安装包请求返回内容被截断max_tokens设置过小看返回 JSON 中finish_reason是否为length调大max_tokens输出质量不稳定推理温度、采样参数设置不合理对比不同 temperature 的结果调低 temperature固定随机种子9. 最佳实践与使用建议9.1 第一跑从小参数开始第一次启动 vLLM 时不要追求高并发和大上下文。先跑通一个最小实例确认服务正常再逐步调整参数。推荐的最小启动配置vllm serve Qwen/Qwen2.5-7B-Instruct \ --max-model-len 2048 \ --gpu-memory-utilization 0.7 \ --max-num-seqs 8这个配置能在大多数 8G 到 16G 显存环境下稳定启动。跑通后再根据业务需求逐步提高max-model-len和max-num-seqs。9.2 模型和输入输出目录分开管理建议目录结构/models 模型权重文件 /inputs 批量推理输入文件 /outputs 批量推理输出文件 /logs vLLM 服务日志模型文件、输入素材、输出结果分开批量任务重跑时不会误删中间产物。9.3 批量任务必须加日志和失败重试批量任务不要只把结果打印到终端。每次执行建议写一个任务日志记录每一条 prompt 的开始时间、结束时间、成功状态和输出长度。失败的重试次数建议 3 次以内避免对同一坏样本无限重试。9.4 多机调用时vLLM 不一定和业务代码同机很多人把 vLLM 和 ComfyUI、LangChain 等工具混在一起担心必须部署在同一台机器上。实际上 vLLM 是一个独立服务业务代码只要能通过 HTTP 访问到 vLLM 的端口即可。比如 A 机器跑 vLLM 服务B 机器跑 LangChain Agent 或 ComfyUI 工作流B 机器只需要把 LLM 的base_url指向 A 机器的 IP 和端口。9.5 接口服务要限制访问范围vLLM 的 OpenAI 兼容接口默认不带鉴权。生产环境建议加一层网关或反向代理限制来源 IP或者在网关层加上 API Key 校验。9.6 注意模型授权和数据隐私部署开源模型时先确认模型 License 是否允许商用。如果服务会接收用户真实对话数据要做好数据脱敏和隐私合规。涉及图片理解、语音处理时务必确认素材来源已获授权。9.7 关于推理框架的定位LangChain、Spring AI 这类工具是应用编排层负责管理 Agent、Prompt 和工具调用。vLLM 是底层推理服务负责把模型跑起来。两者不是同类框架而是上下游关系。vLLM 的竞争对手是 SGLang、TensorRT-LLM、llama.cpp 这些推理引擎不是 LangChain。10. 总结与下一步vLLM 最值得尝试的点是 PagedAttention 带来的显存利用率和 Continuous Batching 带来的高吞吐。这两个机制让普通单卡环境能跑更大的模型、扛更多的并发。如果你准备开始建议第一步先跑一个 7B 级别的模型用默认参数启动一个最小服务然后用 curl 验证接口通不通再跑一个几十条的并发脚本观察吞吐和显存变化。你最先要验证的功能是基本文本生成和并发稳定性。最容易踩的坑有三个一是 Windows 原生环境装 vLLM 导致各种编译报错二是max-model-len和gpu-memory-utilization设置过大直接 OOM三是把 vLLM 当成通用推理平台试图让它跑 embedding 和 reranker 任务结果发现支持不完善。后续可以继续扩展的方向包括接入量化模型降低显存门槛、用张量并行跑 30B 以上大模型、把 vLLM 接到 LangChain Agent 或 FastGPT 上做应用层开发、对比 SGLang 在不同模型上的性能差异。建议先熟悉离线批量推理和 OpenAI 兼容 API 这两个能力再往生产环境演进。