打开技术社区看到一条很简短的标题Inferact vLLM creators are hiring。关键词只要一个就足够让跑过推理服务的人停下vLLM。不管 Inferact 是组织名、项目代号还是招聘主体它传达的信号都差不多——vLLM 团队还在扩张这个框架还处于快速迭代期。对大部分工程师来说与其只看招聘页面不如趁这段时间把 vLLM 的部署、启动、调用、批量任务和排错整套流程完整跑一遍。vLLM 是目前使用最广泛的开源大模型推理与服务框架之一。它的核心机制是 PagedAttention 和 continuous batching解决的最大问题非常具体把本地大模型变成高吞吐、稳定的 HTTP 推理服务。它默认提供 OpenAI 兼容 API背后支持量化、多 GPU 张量并行、前缀缓存、多模态输入等能力。也就是说一条命令就能把 HuggingFace 上的开源模型变成可以对外调用的服务。这篇文章围绕 vLLM 实际落地展开环境准备、pip/Docker/源码三种安装方式、OpenAI 兼容 API 调用、离线批量任务、关键参数调优、显存与性能观察、常见问题排查以及和 SGLang 的选型对比。如果你正准备私有化部署大模型或者要评估 vLLM 能不能接进现有业务这篇文章可以直接收藏。1. vLLM 核心能力速览先给结论再讲细节。vLLM 的能力边界和硬件要求用一个表概括能力项说明项目类型开源大模型推理与服务框架核心机制PagedAttention、continuous batching、前缀缓存等主要功能模型部署、OpenAI 兼容 API、离线批量推理、量化、多 GPU 并行、多模态输入硬件要求推荐 NVIDIA GPUAMD、昇腾等平台需要额外适配工具链显存占用取决于模型大小、量化方式、max-model-len、并发序列数需实际测试启动方式命令行 / Docker / 源码统一提供 HTTP 服务API 支持支持 OpenAI 兼容接口并暴露 /metrics 监控端点批量任务支持 Python 同步批量生成也支持异步推理引擎适合人群关注私有化部署、接口服务、高性能推理的工程师这里补充一点很多人问“我的显卡能不能跑 vLLM”。显卡兼容性主要取决于 vLLM 版本和 CUDA 工具链。新架构显卡建议优先用较新的 vLLM 版本因为新显卡的 attention 内核通常需要新版本支持。显存占用不能一概而论但可以做一个粗略估算一个 7B 模型在 FP16 下光权重就需要约 14GB 显存7B 参数 × 2 字节KV cache、激活值和 CUDA context 还会继续占用进去。所以生产环境一定要用gpu-memory-utilization限制别让进程默认吃满显存。2. 适用场景与使用边界vLLM 能解决的问题非常明确但也不是万能方案。先聊适合的场景。第一类场景是私有化大模型服务。如果业务要求数据不出内网或者不想按 token 付费vLLM 可以把开源模型部署成统一入口团队内部通过 OpenAI 兼容接口调用迁移成本很低。第二类场景是高并发在线服务。RAG 问答、代码助手、客服机器人这类连续请求场景vLLM 的 continuous batching 优势明显。它能把多个请求的推理过程混在一起调度而不是一个请求一个请求排队所以吞吐量比朴素实现高很多。第三类场景是离线批量任务。批量总结、分类、信息抽取、翻译等任务不需要实时响应vLLM 提供 Python 批量生成 API直接吃掉一个文本列表处理完再输出结果。再看边界。vLLM 的主链路默认面向生成式 LLM。embedding 向量模型和 reranker 模型不是 vLLM 主要解决的问题跨平台、跨任务场景下支持程度差别很大。比如在昇腾 910B 环境里经常出现“vLLM 启动不了 embedding 和 reranker 模型”的问题这一点后面排查章节会单独展开。另外 vLLM 追求的是高吞吐和批量效率不是绝对的“单请求最低延迟”。如果你的场景是单用户、超低延迟交互可能还要在流式输出、模型大小和调度策略上单独优化。显存很小的机器vLLM 也能跑但需要配合量化模型和小序列数把预期放低一点。合规边界也要提前说清楚。vLLM 本身是开源工具但部署的模型各有各的许可证商用前必须确认模型协议。处理个人数据、内部文档时要做好脱敏。对外提供生成服务时必须保证生成内容合法合规不能用于生成违法或有害内容。3. vLLM 本地部署环境准备开始部署前先把环境检查一遍避免装到一半才发现缺依赖。操作系统层面生产环境推荐 Linux。Windows 上 vLLM 的原生支持有限更稳妥的路线是 Docker 或 WSL 2。开发机快速验证可以用 macOS 跑小模型但 GPU 加速效果不稳定不建议作为主力环境。GPU 和驱动检查是第一步。vLLM 的主要目标平台是 NVIDIA GPU先确认显卡和驱动可用nvidia-smi能正常打印显卡型号、驱动版本、显存总量后续步骤才继续。Python 环境建议用虚拟环境隔离。先创建并激活python -m venv .venv source .venv/bin/activate python --version pip install --upgrade pipPython 版本、CUDA 版本、PyTorch 版本和 vLLM 版本之间有对应关系。不同 vLLM 版本对依赖的要求不一样安装前先查目标版本的官方文档或 requirements 文件不要盲目装最新版。更稳的做法是直接看 PyPI 页面说明。磁盘空间要留够。一个大模型权重从几 GB 到几十 GB 不等还要考虑镜像、依赖和运行日志。建议至少预留模型大小两倍以上的空间。端口占用也要提前检查。vLLM 默认启动在 8000 端口如果这个端口被其他服务占用启动就会失败。检查方式ss -ltnp | grep 8000有输出就说明端口被占用后续启动时换一个端口。最后是模型下载。vLLM 默认从 HuggingFace 拉取模型第一次运行会下载权重。如果下载速度不理想可以使用国内加速镜像在.bashrc或当前终端设置export HF_ENDPOINThttps://hf-mirror.com下载一次之后会缓存在本机后续使用本地路径加载会快很多。4. vLLM 安装部署与启动方式vLLM 的安装有三种主流方式pip、Docker、源码编译。三种方式适用场景不同按需选择。4.1 pip 安装最简单的验证方式适合已有 Python 环境的开发机pip install vllm已经装过的话需要升级pip install --upgrade vllmpip 安装会同时拉取 PyTorch 等依赖。日常测试和学习场景这种方式最快。4.2 Docker 部署Docker 是目前生产环境推荐的方式环境隔离彻底依赖不会污染宿主机。宿主机需要先装好 NVIDIA 驱动和 nvidia-container-toolkit然后用官方镜像启动docker pull vllm/vllm-openai:latest docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --ipchost \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model Qwen/Qwen2.5-7B-Instruct这里说明几个参数。--gpus all把宿主机所有 GPU 映射进容器-v把 HuggingFace 缓存目录挂载进去避免模型重复下载--ipchost是官方建议用于共享内存通信-p 8000:8000把容器 8000 端口暴露到宿主机。最后面的--model Qwen/Qwen2.5-7B-Instruct是模型名称可以替换成 HuggingFace 仓库 ID 或本地模型路径。4.3 源码安装源码安装适合要改内核、调试 attention 实现或者研究性能细节的人。从 GitHub 拉代码后执行git clone https://github.com/vllm-project/vllm.git cd vllm pip install -e .源码安装会编译内核比较耗时而且对编译工具链有要求。普通用户不建议走这条路。5. 启动服务与 OpenAI 兼容 API 接入vLLM 的核心用法是启动一个 OpenAI 兼容的 HTTP 推理服务。5.1 启动命令以Qwen/Qwen2.5-7B-Instruct为例在 base 环境安装好 vllm 后执行vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.85 \ --max-model-len 8192 \ --max-num-seqs 16--host 0.0.0.0表示监听所有网卡允许局域网内其他机器访问。如果只在本地测试改成127.0.0.1更安全。--gpu-memory-utilization 0.85限制显存使用上限 85%给系统留出余量。--max-model-len 8192限制最大上下文长度。--max-num-seqs 16控制调度器每次最多处理的序列数。第一次运行会下载权重文件启动需要一些时间。看到终端的Starting vLLM日志和端口监听输出说明服务已经起来了。5.2 健康检查服务起来后先查模型列表确认 API 可用curl http://localhost:8000/v1/models正常会返回一个 JSON 对象里面包含模型 ID 和元数据。如果这个请求失败先看终端日志再查端口。端口被占用、模型加载失败、显存不足都会导致 API 打不开。5.3 Chat 补全调用模型就绪后用 curl 测试一次最基本的对话补全curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [ {role: user, content: 用一句话介绍 vLLM} ], max_tokens: 256, temperature: 0.7 }参数结构就是 OpenAI 的 chat completions 格式。model字段必须和服务启动时设置的模型名一致否则会返回 404。在 Python 里调用更常见。只需要指定base_url和假的api_key因为 vLLM 的本地服务默认不校验 keyfrom openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelQwen/Qwen2.5-7B-Instruct, messages[ {role: user, content: 什么是连续批处理} ], max_tokens256, temperature0.7, ) print(response.choices[0].message.content)依赖的 Python 包是openai这个接口调用方式意味着原本用 OpenAI SDK 写的代码只需要改base_url就能接 vLLM 本地服务。6. 批量任务与离线推理接口服务适合在线场景离线批量任务用 vLLM 的 Python API 更直接。6.1 同步批量生成先初始化模型再把一组 prompt 一次性传给generate方法from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct) prompts [ 把这句话翻译成英文本地部署大模型越来越重要。, 请用 50 字总结连续批处理的好处。, ] sampling_params SamplingParams( temperature0.7, top_p0.9, max_tokens512, ) outputs llm.generate(prompts, sampling_params) for output in outputs: print(output.outputs[0].text)这段代码会先加载模型再把两个 prompt 组成一个 batch 执行。批量推理的优势是吞吐高但显存消耗也会随批量增大而上升。如果显存吃紧把一次性传入的 prompt 列表拆小分多次跑。6.2 异步推理与任务队列生产环境的批量任务经常是大量文本不断进入逐个处理。这种场景更适合用 vLLM 的AsyncLLMEngine或者把任务投递到消息队列由多个 worker 去消费。消息队列的好处很明显任务不会因为进程崩溃而丢失可以重复消费也方便做失败重试。批量任务的设计上每条任务尽量带上唯一 ID输出结果写文件时记录对应 ID这样即使中间挂了也能从断点继续。6.3 批量任务控制批量任务最怕一次塞太多导致显存溢出。通用做法是控制 batch 大小、开启日志、加超时和重试。每个 prompt 单独捕获异常不要让一个失败任务拖垮整个 batch。批量任务跑完还要检查输出质量不要直接拿结果上线。7. 关键参数解读与推理调优vLLM 的启动参数很多真正影响部署效果的是这几个关键项。7.1 max-model-lenmax-model-len控制最大上下文长度直接影响 KV cache 分配。长度设得越大KV cache 占用越高能并发的序列数就越少。默认值由模型配置推断如果实际输入都是短文本可以调小这个值省下的显存留给并发。7.2 gpu-memory-utilizationgpu-memory-utilization控制 vLLM 最多使用多少比例的 GPU 显存。默认是 0.9但生产环境建议保守一点比如 0.85避免和其他进程抢显存导致 OOM。显存不足时优先调低这个值。7.3 max-num-seqsmax-num-seqs是调度器在一次迭代中最多处理的序列数。这个值调大可以提高并发吞吐但显存压力也跟着上升。显存有限时把 16 改成 8 甚至 4稳定性会好很多。7.4 tensor-parallel-sizetensor-parallel-size用于多 GPU 并行。一个 70B 模型单卡装不下可以用这个参数把模型切到多张卡上vllm serve /path/to/model \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.85这里会同时用到多张 GPU启动前确认nvidia-smi能看到所有卡。7.5 quantization量化是降低显存和提升吞吐的常用手段。vLLM 支持 AWQ、GPTQ、FP8 等量化格式启动时指定量化方式vllm serve /path/to/model \ --quantization awq \ --dtype float16注意量化模型和普通模型文件格式不一样需要先做量化或用现成的量化权重。量化会带来一定的精度损失是否接受要以业务效果为准。7.6 chunked prefill较新版本的 vLLM 已经默认支持 chunked prefill它会把 prefill 阶段的 long context 拆成多个 chunk和 decode 阶段混合调度降低显存瞬时峰值提升 GPU 利用率。调优的顺序建议是先用一个小模型把流程跑通再逐项调大上下文和并发每次只改一个参数观察显存和吞吐变化不要一次改太多导致不知道哪个参数引起问题。8. 资源占用与性能观察部署完 vLLM 之后怎么判断服务状态是否健康这里给一套完整的观察方法。启动时vLLM 终端日志会输出 GPU 内存分配情况包括GPU KV cache size之类的字段。这个数字表示 vLLM 实际分配了多少显存给 KV cache是判断并发容量上限的第一参考。运行中用nvidia-smi实时查看显存和利用率nvidia-smi -l 1-l 1表示每秒刷新一次。如果看到显存占用很高先别急着下结论vLLM 会预分配 KV cache所以显存高是正常现象重点看 GPU 利用率和吞吐是否正常。更精细的观察方式是直接用 vLLM 暴露的指标接口curl http://localhost:8000/metrics返回的是 Prometheus 格式指标。不同版本指标名会有差异但通常包括请求数、生成 token 数、延迟等数据。生产环境建议把这些指标接到 Prometheus Grafana服务状态一目了然。关注的性能指标主要这几个方向TTFTtime to first token首个 token 的延迟影响交互感。生成吞吐每秒生成多少个 token影响批量任务效率。并发序列数当前实际处理的序列数对比max-num-seqs。KV cache 使用率是否接近上限接近说明并发容量不够。一个容易踩的误区是只看nvidia-smi的显存。vLLM 的高显存占用可能是预分配结果并不等同于异常。更合理的判断方式是看日志中 KV cache 的使用率和请求成功率。另外如果你的启动日志里出现类似dflash2之类的 attention backend 标识这通常代表当前环境启用了对应的 FlashAttention 内核。不同 vLLM 版本、显卡架构对应的后端名不一样遇到不理解的关键词不要直接搜到就改参数先看这个版本 release notes 里对 attention backend 的说明。9. 常见问题与排查方法vLLM 部署过程中的问题多数集中在依赖、显存、端口和模型路径这几个方面。下面按问题现象整理成排查表。问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动检查终端日志、ss -ltnp | grep 8000换端口或重启服务CUDA out of memory显存不足查看 nvidia-smi 显存状态调低 gpu-memory-utilization调小 max-model-len 和 max-num-seqs或使用量化模型依赖安装失败Python、CUDA、PyTorch 版本不匹配查看 pip 日志和版本号先查目标 vLLM 版本的 requirements必要时用 Docker 隔离模型下载失败HuggingFace 仓库不可达或磁盘空间不足查看下载日志和磁盘余量使用国内镜像源或先手动下载模型再挂载到本地路径API 返回 404 model not found请求中的 model 字段和启动时的模型名不一致调用/v1/models查看模型 ID修正请求中的 model 字段批量任务卡住并发过高、显存不足或请求超时查看终端日志和 GPU 利用率减小 batch 大小、调大超时时间、添加失败重试日志出现 dflash2 等后端标识启用了特定 attention 内核对照版本 release notes按官方说明确认后端行为不必强行修改9.1 昇腾 910B 无法启动 embedding 和 reranker 模型社区里关于昇腾 910B 环境的问题非常集中典型描述是在昇腾服务器上装了 vLLM但没法通过它启动 embedding 向量模型和 reranker 模型。这里有两层原因。第一层vLLM 的主链路默认面向生成式 LLMembedding 和 reranker 任务的支持程度取决于具体版本和任务类型。第二层昇腾平台要跑 vLLM 在线推理服务必须正确安装 CANN、torch_npu 等工具链并且服务端版本和 vLLM 版本要匹配。更稳妥的架构思路是让不同组件做自己擅长的事情。向量化链路建议使用专门的 embedding 服务化方案比如 TEI、FlagEmbedding 部署方案或者向量数据库自带的 embedding 服务reranker 也可以用专门的排序服务方案。vLLM 集中精力跑生成式模型。这种设计不仅避开平台兼容问题也让每个服务的问题定位更清晰。10. vLLM 与 SGLang 快速对比在选择推理框架时SGLang 是 vLLM 最常被拿来对比的框架。两个都是开源项目都支持 OpenAI 兼容 API、连续批处理和并发推理。核心区别在底层优化思路。对比维度vLLMSGLang核心优化PagedAttention、continuous batchingRadixAttention、前缀自动复用APIOpenAI 兼容 API 成熟稳定同样提供 OpenAI 兼容 API前端能力结构化输出、多模态支持逐年完善在结构化生成、控制流方面设计更激进生态成熟度高被大量生产系统采用增长快社区热度高选型建议生产推理服务优先考虑复杂结构化生成、前沿特性试验可对比更具体的说vLLM 的优势是生态成熟、文档丰富、和 HuggingFace 生态的兼容性好适合作为团队默认推理引擎。SGLang 用了 RadixAttention在前缀复用场景比如多轮对话