vLLM 推理服务引擎：安装、主要功能与同类对比

自建大模型服务的团队常卡在同一个地方：显卡买回来了，权重也下载好了，可单卡能同时接几个请求、显存怎么在多个请求间分配、长上下文一来吞吐为什么断崖式下跌，这些都得自己写代码解决。手写一套基于 PyTorch 的推理脚本，几十行能让单个请求跑起来，要支撑线上并发，后面全是内存管理和调度的工作量。

vLLM 是用 Python 编写的 LLM 推理与服务引擎，读取 Hugging Face 上的模型权重，对外提供 OpenAI 兼容的 HTTP 接口，让团队把大模型部署成可并发调用的服务。

项目 2023 年 2 月创建，最初在加州大学伯克利分校 Sky Computing Lab 开发，现在由 2000 多名贡献者共同维护。仓库采用 Apache License 2.0 许可证，主要语言是 Python，占 84.9%，其余为 Rust 6.1%、Cuda 4.2%、C++ 3.3%。抓取时 Star 数 92765，Fork 22707，开放 Issue 8332 个。仓库地址是 https://github.com/vllm-project/vllm，项目主页是 vllm.ai。

它的典型场景是模型自托管。手里有 A100、H100 或者国产加速卡，要把 Llama、Qwen、DeepSeek 这类开源权重变成内部可调用的 API，同时希望单卡吞吐高于原生 PyTorch、显存占用更低，这就是它在做的事。模型来源是 Hugging Face 上 200 多个已支持的架构，包括纯解码器模型、MoE 模型、混合注意力与状态空间模型、多模态模型、embedding 检索模型、reward 与分类模型。

五分钟先跑通

README 推荐的安装方式是用 uv：

uv pip install vllm

不用 uv 的话直接 pip 也可以：

pip install vllm

这个包会编译 CUDA 内核，在 Mac 上安装会直接失败，报错信息见后面的“实际使用中的坑”。要从源码构建 wheel，文档给的入口是 docs.vllm.ai 里的 build wheel from source 章节，仓库首页只写了这一条指路。

启动服务这一段，README 没有在仓库首页给出完整命令，只把读者引向官方文档的 Quickstart。社区 Issue 里出现过的启动形式是这样：

vllm serve Qwen/... --enable-reasoning --reasoning-parser deepseek_r1

模型 ID 换成自己实际要部署的那个，参数按需要增删。Docker 路线在 Issue 里出现过镜像名 vllm/vllm-openai:gptoss，仓库里有 docker/ 目录，但没有在首页给出通用的 docker run 示例。

跑通之后你会得到什么

服务起来后，本机会跑起一个 OpenAI 兼容的 API server。README 还提到同时支持 Anthropic Messages API 和 gRPC，客户端用现有的 OpenAI SDK 把 base URL 指过来就能发请求，流式输出是支持的。

README 没有写默认端口号，也没有写健康检查路径，这两项要去 docs.vllm.ai 查。响应侧支持结构化输出（用 xgrammar 或 guidance）、tool calling，以及 reasoning parser 对推理内容的解析。

下一步能做的事取决于你部署在哪。单机单卡跑通之后，通常要接着调并行度、量化格式和显存占用比例；多机部署则要配 tensor 或 pipeline 并行。这两件事的配置项都不在仓库首页。

主要功能

PagedAttention 是这套引擎的起点，用分页方式管理注意力层的 key/value 显存。README 把它列为高效管理 KV 内存的核心机制，项目最初的论文（arXiv 2309.06180）写的就是这件事。

连续批处理、chunked prefill、前缀缓存三项一起决定了吞吐表现。新请求进来不用等上一批算完才排队，长 prompt 会被切块处理，相同前缀的请求可以复用已经算过的 KV。

CUDA/HIP 图分 piecewise 和 full 两种模式，作用是减少 kernel 启动开销。这类优化在低延迟场景里比吞吐场景更关键。

量化支持的面很宽，README 列出的格式有 FP8、MXFP8/MXFP4、NVFP4、INT8、INT4、GPTQ/AWQ、GGUF、compressed-tensors、ModelOpt、TorchAO。选哪种格式取决于显卡代际和能容忍的精度损失，文档里有单独一章。

内核层面，注意力用了 FlashAttention、FlashInfer、TRTLLM-GEN、FlashMLA、Triton；GEMM 与 MoE 用了 CUTLASS、TRTLLM-GEN、CuTeDSL。另外还有 torch.compile 做自动内核生成与图级变换。

投机解码支持 n-gram、suffix、EAGLE、DFlash 四种方案。并行方面有 tensor、pipeline、data、expert、context 五种，README 另提到 disaggregated prefill、decode、encode，把预填充和解码拆到不同实例上跑。

多 LoRA 是另一个实用功能，dense 层和 MoE 层都能挂多个适配器，适合一个底座模型服务多个微调任务的团队。

硬件覆盖面是它被广泛采用的原因之一。NVIDIA、AMD、Intel 的 GPU 和 x86/ARM/PowerPC 的 CPU 都能跑，另有一批硬件插件：Google TPU、Intel Gaudi、IBM Spyre、Huawei Ascend、Rebellions NPU、Apple Silicon、MetaX GPU。

常用参数与配置

仓库首页没有参数清单，能逐字写下来的很少。社区 Issue 的 Qwen3 用法里出现两个：--enable-reasoning 打开推理模式，--reasoning-parser 指定解析器，示例值是 deepseek_r1。同一条 Issue 说明 vLLM v0.8.4 及以上原生支持全部 Qwen3 与 Qwen3MoE 模型。

Docker 部署走镜像 tag，Issue 里出现过 vllm/vllm-openai:gptoss 这个写法。量化、并行度、显存比例这些参数都在文档里，README 没有列。部署前建议先翻 docs.vllm.ai 的对应章节，不要照抄别处搜到的命令行，不同版本的参数名有变化。

结果在哪里看

调用结果直接返回在 HTTP 响应里，这是最直接的输出。仓库 README 没有说明日志文件落在哪个目录，也没有说明有没有指标接口。容器部署就看容器日志，进程部署就看标准输出。

运行状态相关的文档在 docs.vllm.ai。README 提到的用户论坛是 discuss.vllm.ai，开发者 Slack 是 slack.vllm.ai，这两个是遇到部署问题时比较快的求助渠道。

实际使用中的坑

Mac 装不上。在 Mac 上执行 pip install vllm 会报 RuntimeError: Cannot find CUDA_HOME. CUDA must be available to build the package.。这条 Issue 有 115 条评论、86 个 reaction，标记为已解决，但 Mac/Metal/MPS 本身不在 README 的支持列表里。

Blackwell 卡上的 FlashAttention 3。RTX 5090 上跑 gpt-oss 时报 Sinks are only supported in FlashAttention 3，另有用户在 4090 48GB 上碰到同样的报错。两条都标记为已解决，处理方式是跟着 Issue 里的环境配置走。

新卡的部署步骤。社区单独写了一份针对 RTX 5080/5090 的步骤型 Issue，139 条评论、44 个 reaction，已解决。手里是新卡的话，按这份步骤走比按通用文档走省事。

多模态支持还没收敛。[RFC]: Multi-modality Support on vLLM 有 98 条评论，状态是待解决，说明这块能力在路线图上仍在讨论。依赖多模态的团队要做版本调研。

另外两条待解决的：DeepSeek-V4-Flash 在 A100/A800（SM8x）上的支持（108 条评论），以及 Kimi-K2.6 的推理字段间歇性只输出感叹号、content 为 null（93 条评论）。这两条都还没有结论。

同类项目对比

取舍说明：如果部署目标是 Mac 或者一台没有独立显卡的机器，vLLM 直接装不上，这时候该考虑的是云端 API 或者别的 CPU 优先方案。如果团队真正的痛点是给多个人分显卡、按租户管模型实例，vLLM 本身不做这层调度，拿 gpustack 这类集群管理器来管更合适，vLLM 在其中只承担推理后端这一个角色。反过来，只有一台机器、只要跑通一个模型接口，上集群管理反而多一层维护成本。

什么情况下别用它

机器是 Mac，或者只有 CPU 又不能接受很低的吞吐，别用，安装这一步就过不去。只是偶尔调一次模型、不需要并发，直接买云端 API 更省钱，为这个维护一套 GPU 环境和驱动不划算。

没有 GPU 运维能力的团队也要谨慎。编译对应显卡架构的内核、调并行度、排查显存溢出，都是需要有人长期盯着的活，Issue 列表里那些报错多数与显卡代际和环境版本相关。

业务强依赖多模态并且要求能力稳定，现阶段要再等等，相关 RFC 仍是待解决状态。需要跨团队分配显卡资源的场景也不适合单靠它解决，那是集群管理层的事。