vllm-project/vllm · 上手攻略

• 仓库：vllm-project/vllm
• 链接：https://github.com/vllm-project/vllm
• 分类：llm-infra
• 作者：Tom
• 更新：2026-07-07

这是什么

vLLM 是一个高吞吐量、内存高效的 LLM 推理与服务引擎，最初由 UC Berkeley Sky Computing Lab 开发，现已成长为全球最活跃的开源 AI 基础设施项目之一，拥有来自 2000+ 贡献者的社区支持。

核心突破是 PagedAttention 技术——受操作系统虚拟内存分页启发，将 KV Cache 切分成小块动态管理，显著减少显存碎片，提升 GPU 利用率。在 2023 年 SOSP 会议上发表论文《Efficient Memory Management for Large Language Model Serving with PagedAttention》。

支持场景：对话服务、批量推理、分布式部署、RLHF 训练、speculative decoding、多模态模型。

解决什么问题

传统 LLM 推理引擎（如 naive HF text-generation）在高并发、长上下文、多用户场景下存在三大痛点：

1. 显存碎片化：KV Cache 连续分配，长序列显存浪费严重
2. 吞吐量低：缺乏 continuous batching，请求级批处理效率差
3. 部署复杂：缺少 OpenAI 兼容 API，生产环境集成成本高

vLLM 通过 PagedAttention + Continuous Batching + Prefix Caching 组合拳，在不牺牲精度的情况下实现 3-5 倍吞吐量提升（官方 benchmark vs HuggingFace TGI）。

快速安装

推荐方式（uv）

uv pip install vllm

GPU 环境要求

• NVIDIA GPU（CUDA 11.8 或 12.1+）
• 需要足够 VRAM：7B 模型约需 14GB，70B 模型约需 140GB（fp16）
• ROCm（AMD GPU）支持：需要安装 hipBLASLt，见 官方文档

从源码编译（需要 CUDA toolkit）

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -r requirements-build.txt
python setup.py install  # 或 python setup.py bdist_wheel

⚠️ 注意：从源码编译需要 ~30 分钟和充足磁盘空间，建议仅开发场景使用。正式部署推荐 pip/uv 安装预编译轮。

验证安装

import vllm
print(vllm.__version__)

核心用法

1. Python API 离线推理（最常用）

from vllm import LLM, SamplingParams

# 初始化模型（自动下载 HuggingFace 权重）
llm = LLM(model="meta-llama/Llama-2-7b-chat-hf")

# 采样参数
sampling_params = SamplingParams(
    temperature=0.8,
    top_p=0.95,
    max_tokens=256,
)

# 批量推理
outputs = llm.generate(["Hello, my name is", "The capital of France is"], sampling_params)

for output in outputs:
    print(output.outputs[0].text)

2. OpenAI 兼容 API 服务器（生产部署）

启动服务：

vllm serve meta-llama/Llama-2-7b-chat-hf \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2

调用方式与 OpenAI API 完全兼容：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-2-7b-chat-hf",
    "messages": [{"role": "user", "content": "Explain quantum computing"}]
  }'

⚠️ 注意：2026 年 7 月最新版本已默认使用 --enforce-eager=False（torch compile 模式），启动时间更长但推理更快。如需快速冷启动，加 --enforce-eager。

3. 多 GPU 分布式（Tensor Parallel）

# 4 GPU 并行
vllm serve meta-llama/Llama-2-70b-hf \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.9

Python API 方式：

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    tensor_parallel_size=4,
    gpu_memory_utilization=0.9,
)

4. 支持的量化格式

# FP8（推荐，精度损失小）
llm = LLM(model="meta-llama/Llama-2-70b-hf", quantization="fp8")

# INT8 / INT4（GPTQ）
llm = LLM(model=".../Llama-2-70b-gptq", quantization="gptq")

# AWQ
llm = LLM(model=".../Llama-2-70b-awq", quantization="awq")

# GGUF（ llama.cpp 格式，需要指定目录）
llm = LLM(model="./models/llama-2-70b.Q4_K_M.gguf")

5. Streaming 输出

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Llama-2-7b-chat-hf")
sampling_params = SamplingParams(max_tokens=512, temperature=0.7)

# streaming 模式
for output in llm.generate(["Write a haiku about AI"], sampling_params, streaming=True):
    print(output.outputs[0].text, end="", flush=True)

6. 多 LoRA 适配（生产高频场景）

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    enable_lora=True,
    max_lora_rank=16,
)

from vllm import LoraConfig
# 加载多个 LoRA 权重，动态切换

7. vLLM 与 LangChain 集成

from langchain_community.llms import VLLM

llm = VLLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    trust_remote_code=True,
    max_model_len=4096,
    tensor_parallel_size=2,
)

典型适用场景

坑与注意

1. 冷启动慢：默认 torch.compile 编译首个请求，首次调用等待 ~30-60 秒。使用 --enforce-eager 可跳过，但吞吐量下降。
2. 显存估算不准：模型权重 + KV Cache 叠加，70B fp16 需 ~140GB VRAM，建议 gpu_memory_utilization 从 0.85 开始调。
3. 权重下载依赖 HuggingFace：需提前 huggingface-cli login 或设置 HF_TOKEN 环境变量；私有模型同理。
4. AMD GPU 支持有限：ROCm 5.7+ 支持但非所有内核都优化，复杂模型可能有未预期错误，建议生产用 NVIDIA。
5. 多模态 encoder 不在 TP 范围：VLM 的 vision encoder 共享，Tensor Parallel 只切分 LLM 部分。
6. speculative decoding 限制：需要额外的小模型（draft model），总显存增加，不是所有架构都支持。
7. 版本兼容性：vLLM 更新频繁，不同版本对同一模型的权重格式可能有要求，升级前建议查 changelog。

与同类对比

一句话：如果你需要高并发、高显存效率的生产级推理，vLLM 是当前最优选择；如果只是本地随便跑个模型玩，Ollama 更省事。

一句话结论

vLLM 是当前开源 LLM 推理引擎的顶流选择——PagedAttention + Continuous Batching 带来的显存效率和吞吐量优势无可替代，是搭建生产级 AI 服务的首选基建。