vLLM

vLLM 快速入门

让 GPU 不再”摸鱼”——用 PagedAttention 把 LLM 推理吞吐量提升 10 倍以上。

这是什么？适合谁？

vLLM 是 UC Berkeley 开发的 LLM 推理和服务引擎，核心创新是 PagedAttention 算法——像操作系统的虚拟内存管理一样管理 LLM 的 KV Cache，大幅减少显存浪费，让 GPU 利用率从 30% 提升到 90%+。GitHub 86K+ stars，3.1K+ contributors，是 OpenAI、Anthropic、Databricks 等公司生产环境的基础设施。v0.25.1 为当前稳定版，支持 Python 3.10+（推荐 3.12+）。

适合谁？一是需要部署 LLM 服务的企业，追求高吞吐和低延迟；二是 AI Infra 工程师，需要精细控制推理参数和调度策略；三是需要分布式推理的团队（多卡/多节点）。不适合：个人用户想在笔记本上跑模型（用 Ollama），以及只需要单次推理的研究场景（用 transformers 直接推理）。

准备工作

• 环境：Python 3.10+，CUDA 12.1+（GPU 推理）
• 安装：pip install vllm 或 uv pip install vllm --torch-backend auto
• 硬件：建议 NVIDIA GPU（A100/H100 最佳），CPU 推理也支持但速度慢
• 模型：HuggingFace 模型或本地路径

3 步快速上手

第 1 步：安装

pip install vllm

第 2 步：启动 API 服务

vllm serve deepseek-ai/DeepSeek-V4-Flash --port 8000

第 3 步：调用 API

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

常见踩坑

踩坑 1：OOM（显存不足）

• 症状：启动时报 CUDA out of memory
• 原因：模型太大，显存放不下
• 解决：使用 --tensor-parallel-size 2 跨多卡推理，或 --gpu-memory-utilization 0.85 限制显存使用

踩坑 2：与 transformers 版本冲突

• 症状：ImportError 或模型加载失败
• 原因：vLLM 依赖特定版本的 transformers
• 解决：pip install vllm --upgrade 自动安装兼容版本，或使用 uv 安装 uv pip install vllm --torch-backend auto 自动处理依赖

踩坑 3：首次模型加载极慢（5-10 分钟）

• 症状：第一次启动模型加载耗时极长
• 原因：vLLM 需要将模型权重重排为 PagedAttention 所需的格式，并编译 CUDA kernel
• 解决：这是正常现象，后续启动会使用缓存；使用 --enforce-eager 跳过 CUDA graph 优化加快首次启动（以牺牲部分推理速度为代价）

踩坑 4：多卡推理时显存分配不均

• 症状：一张卡显存 80%，另一张 20%
• 原因：tensor parallel 策略导致各卡负载不平衡
• 解决：检查 --tensor-parallel-size 参数是否正确，确认模型架构是否支持均匀拆分；部分 MoE（Mixtral 等）天然存在不平衡

踩坑 5：API 返回 502 但进程存活

• 症状：上游调用报 502 Bad Gateway
• 原因：vLLM 在处理完请求后清理 KV Cache 时耗时过长，导致健康检查超时
• 解决：设置 --max-model-len 4096 限制最大序列长度，或增加 --keep-alive-timeout 300 健康检查超时时间

踩坑 6：流式输出（Streaming）中途中断

• 症状：stream=True 时部分响应被截断
• 原因：客户端或网络超时，或模型本身在生成过程中触发 stop token 未正确处理
• 解决：设置 stop=["<|im_end|>", "<|endoftext|>"] 明确结束标记，客户端增大 timeout 到 60s+

踩坑 7：Windows 上安装失败

• 症状：pip install vllm 报编译错误
• 原因：vLLM 的 CUDA kernel 需要 MSVC 编译器和 CUDA Toolkit
• 解决：使用 Docker 运行（推荐），或切换到 WSL2。Windows 原生支持有限。来源

FAQ 常见问题

Q1：vLLM 是免费的吗？

A：vLLM 完全开源免费，采用 Apache 2.0 许可证。项目由 UC Berkeley 发起，获得 a16z、Sequoia Capital、NVIDIA、AWS、Google Cloud 等赞助。没有任何付费版本或 SaaS 限制。你只需要支付 GPU 云服务器费用（如 AWS p4d 约 $32/小时）。来源

Q2：vLLM 和 Ollama、TGI、TensorRT-LLM 有什么区别？

A：vLLM（86K stars）以 PagedAttention 著称，吞吐量领先同行 2-10x。Ollama（120K stars）是个人用户首选，操作最简单，一个命令 ollama run 即可，但不适合生产。HuggingFace TGI 是 HF 官方的推理方案，集成最好但性能中等。NVIDIA TensorRT-LLM 性能极致（FP8 推理），但配置复杂度高，需要 NVIDIA GPU。综合推荐：个人用 Ollama，企业生产用 vLLM，极致性能用 TensorRT-LLM。来源

Q3：vLLM 支持哪些模型架构？

A：vLLM 支持的模型非常广泛：DeepSeek V4/V3.2/R1 系列、Meta Llama 4/3 系列、Google Gemma 4/3、Mistral AI 全系列、Qwen 3.6/3.5/3、Kimi K2 系列、MiniMax M3、Z-AI GLM 5 系列、NVIDIA Nemotron 系列。也支持多模态模型（vLLM Omni）。几乎所有 HuggingFace 上的主流开源模型都兼容。来源

Q4：vLLM 支持多少种硬件？

A：vLLM 支持 NVIDIA GPU（CUDA）、AMD GPU（ROCm）、Intel GPU（XPU）、Google TPU、AWS Neuron（Trainium/Inferentia）、Huawei Ascend NPU、IBM Spyre、Apple Silicon 和 CPU 推理。是覆盖面最广的推理引擎之一。来源

Q5：vLLM 的生产部署怎么配置？

A：推荐 Docker 部署：docker run --gpus all -p 8000:8000 vllm/vllm-openai:latest --model meta-llama/Llama-4-17B。配合 Kuberay/Ray 做弹性扩缩。生产环境建议设置 --max-num-seqs 256 限制并发数，--gpu-memory-utilization 0.85 预留显存，--port 8000 --host 0.0.0.0 监听全部网络接口。也可使用 AIBrix（K8s AI 基础设施）做托管部署。来源

初级用法

1. 离线推理：from vllm import LLM; llm = LLM(model="deepseek-ai/DeepSeek-V4-Flash"); output = llm.generate(["你好"])
2. 查看支持模型列表：vllm list-models 显示本地可用的模型列表
3. 交互式测试：vllm serve model-name --chat-template chat-template.jinja 自定义聊天模板
4. 获取服务器指标：curl http://localhost:8000/metrics 查看 vLLM 的 Prometheus 指标
5. 批量推理：llm.generate(["prompt1", "prompt2", "prompt3"], use_tqdm=True) 一次性批量处理多个 prompt

高级玩法

1. Prefix Caching：--enable-prefix-caching 缓存生成 prompt 前缀的 KV Cache，系统消息相同场景加速 2-5x
2. Speculative Decoding：用小模型（如 model=small-draft-model）做草稿生成，大模型验证，加速推理 1.5-2x
3. LoRA 热加载：--enable-lora 支持运行时动态加载/卸载 LoRA adapter，无需重启服务
4. Automatic Prefix Caching：APC 自动检测共享前缀，特别适合聊天应用（所有请求共享 System Prompt）
5. Guided Decoding：结合 Outlines 库实现结构化输出（JSON Schema、Regex、JSON Mode），让 LLM 的输出严格符合格式要求

小技巧

1. 使用 --trust-remote-code 加载 HuggingFace 上需要自定义代码的模型（大多数模型需要此参数）
2. 查看实时 GPU 使用：nvidia-smi 配合 --gpu-memory-utilization 动态调整，避免 OOM
3. 多 LoRA 模型同时加载：--lora-modules lora1=/path/to/lora1 lora2=/path/to/lora2 运行时通过 API 切换
4. --enable-auto-tool-choice：vLLM 支持 Function Calling 和 Tool Use，配合 OpenAI 兼容 API 使用
5. 请求日志：启动时添加 --log-requests 记录每次请求的延迟和 Token 数，方便性能调优

进阶学习建议

• 阅读 vLLM 官方文档：https://docs.vllm.ai 了解全部参数和部署方案
• 学习 PagedAttention 论文：arxiv.org/abs/2309.06180，理解 vLLM 的核心原理
• 使用 vLLM Playground：Web UI 交互式测试不同推理参数
• 性能调优：关注 perf.vllm.ai 的基准测试，对比不同 GPU 和配置的吞吐数据
• 参加 vLLM Conference：vLLM 每年举办技术会议（2026 年 8 月在 Ray Summit），了解最新发展动态和最佳实践

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

• vLLM 官网
• vLLM GitHub
• vLLM 文档
• PagedAttention 论文