1.2 vLLM 快速入门

1.1 vLLM 的核心优势#

1.2 vLLM 在推理生态中的定位#

2.1 传统 KV Cache 的问题#

LLM 推理的 Decode 阶段需要缓存之前所有 token 的 Key 和 Value 向量（即 KV Cache），以避免重复计算。传统做法是为每个请求预分配一块连续的显存空间，大小按模型支持的最大序列长度计算。

这就带来了三个问题：

• 内部碎片：大多数请求用不到最大长度，预留空间大量浪费
• 外部碎片：请求结束后释放的空间大小不一，难以被新请求复用
• 无法共享：Beam Search 等场景中，多个候选序列共享前缀部分的 KV Cache，但连续内存布局无法实现共享

💡 提示：对于一个 13B 参数的模型，单个请求的 KV Cache 在最大序列长度下可能占用数 GB 显存。如果同时处理几十个请求，显存瓶颈会比模型权重本身更严重。

2.2 PagedAttention 的解决方案#

PagedAttention 的核心思想非常直观——把操作系统管理内存的方式搬到 KV Cache 管理上来：

具体工作方式：

1. 分块存储：KV Cache 不再要求连续内存，而是被切分成固定大小的 Block（如 16 个 token 为一个 Block）
2. 按需分配：每生成一个 token，只在当前 Block 未满时追加，填满后才分配新的 Block
3. 映射表管理：每个请求维护一个 Block Table，记录自己的逻辑 Block 到物理 Block 的映射关系
4. 内存共享：多个请求如果有相同的前缀（如 System Prompt），可以共享同一组物理 Block，大幅节省显存

⚠️ 注意：PagedAttention 的分块存储意味着 KV Cache 在物理上是不连续的，vLLM 需要专门的 CUDA Kernel 来高效地从分散的 Block 中读取数据进行 Attention 计算。

3.1 系统要求#

3.2 使用 uv 安装（推荐）#

uv 是 Rust 编写的高速 Python 包管理器，vLLM 官方推荐使用它来安装，能自动检测 CUDA 版本并选择匹配的 PyTorch：

1
# 创建虚拟环境
2
uv venv --python 3.12 --seed
3
source .venv/bin/activate
4

5
# 安装 vLLM（自动检测 CUDA 版本）
6
uv pip install vllm --torch-backend=auto

--torch-backend=auto 会根据系统 CUDA 驱动自动选择合适的 PyTorch 版本。也可以显式指定后端，如 --torch-backend=cu126。

3.3 使用 conda + pip 安装#

1
conda create -n vllm-env python=3.12 -y
2
conda activate vllm-env
3
pip install --upgrade uv
4
uv pip install vllm --torch-backend=auto

3.4 AMD ROCm 环境#

1
uv venv --python 3.12 --seed
2
source .venv/bin/activate
3
uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/

目前 ROCm 支持 Python 3.12、ROCm 7.0，要求 glibc >= 2.35。

3.5 验证安装#

1
python -c "import vllm; print(vllm.__version__)"

4.1 基础用法#

1
from vllm import LLM, SamplingParams
2

3
# 定义采样参数
4
sampling_params = SamplingParams(
5
    temperature=0.8,
6
    top_p=0.95,
7
    max_tokens=256,
8
)
9

10
# 加载模型（自动下载 HuggingFace 模型）
11
llm = LLM(model="Qwen/Qwen2.5-7B-Instruct")
12

13
# 批量生成
14
prompts = [
15
    "请用一句话解释什么是 Transformer：",
16
    "Python 和 C++ 的主要区别是什么？",
17
    "推荐三本深度学习入门书籍：",
18
]
19

20
outputs = llm.generate(prompts, sampling_params)
21

22
for output in outputs:
23
    prompt = output.prompt
24
    generated = output.outputs[0].text
25
    print(f"Prompt: {prompt}")
26
    print(f"Generated: {generated}\n")

📌 关键点：LLM 构造时会一次性将模型加载到 GPU 显存中。默认情况下 vLLM 会使用 90% 的可用 GPU 显存（模型权重 + KV Cache），可通过 gpu_memory_utilization 参数调整。

4.2 Chat 模式推理#

对于 Instruct/Chat 模型，需要正确应用 Chat Template。vLLM 提供了两种方式：

方式一：使用 llm.chat（推荐）

1
from vllm import LLM, SamplingParams
2

3
llm = LLM(model="Qwen/Qwen2.5-7B-Instruct")
4
sampling_params = SamplingParams(temperature=0.7, max_tokens=512)
5

6
messages_list = [
7
    [
8
        {"role": "system", "content": "你是一个 AI Infra 专家。"},
9
        {"role": "user", "content": "解释什么是张量并行？"},
10
    ],
11
    [
12
        {"role": "user", "content": "vLLM 和 TensorRT-LLM 有什么区别？"},
13
    ],
14
]
15

16
outputs = llm.chat(messages_list, sampling_params)
17

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

方式二：手动应用模板

1
from transformers import AutoTokenizer
2
from vllm import LLM, SamplingParams
3

4
model_name = "Qwen/Qwen2.5-7B-Instruct"
5
tokenizer = AutoTokenizer.from_pretrained(model_name)
6
llm = LLM(model=model_name)
7

8
messages_list = [
9
    [{"role": "user", "content": "什么是 KV Cache？"}],
10
]
11

12
# 手动应用 chat template
13
texts = tokenizer.apply_chat_template(
14
    messages_list,
15
    tokenize=False,
16
    add_generation_prompt=True,
17
)
18

19
outputs = llm.generate(texts, SamplingParams(temperature=0.7))

⚠️ 注意：llm.generate 不会自动应用 Chat Template。如果直接传入裸文本给 Chat 模型，输出质量可能很差甚至乱码。务必使用 llm.chat 或手动调用 apply_chat_template。

4.3 HuggingFace generation_config 的影响#

vLLM 默认会读取模型仓库中的 generation_config.json（如果存在），并用其中的参数覆盖 vLLM 的默认值。如果你想使用 vLLM 自身的默认采样配置，需要显式设置：

1
llm = LLM(model="Qwen/Qwen2.5-7B-Instruct", generation_config="vllm")

5.1 启动服务器#

1
vllm serve Qwen/Qwen2.5-7B-Instruct

默认监听 http://localhost:8000，可通过 --host 和 --port 自定义：

1
vllm serve Qwen/Qwen2.5-7B-Instruct \
2
    --host 0.0.0.0 \
3
    --port 8080 \
4
    --tensor-parallel-size 2

💡 提示：同样可以通过 --generation-config vllm 来禁用 HuggingFace 默认的 generation_config。

5.2 Chat Completions API#

这是最常用的接口，对标 OpenAI 的 v1/chat/completions：

使用 curl：

1
curl http://localhost:8000/v1/chat/completions \
2
    -H "Content-Type: application/json" \
3
    -d '{
4
        "model": "Qwen/Qwen2.5-7B-Instruct",
5
        "messages": [
6
            {"role": "system", "content": "你是一个有帮助的助手。"},
7
            {"role": "user", "content": "什么是 PagedAttention？"}
8
        ],
9
        "temperature": 0.7,
10
        "max_tokens": 512
11
    }'

使用 Python openai 客户端：

1
from openai import OpenAI
2

3
# 只需修改 base_url，其他代码完全不变
4
client = OpenAI(
5
    api_key="EMPTY",  # vLLM 默认不需要认证
6
    base_url="http://localhost:8000/v1",
7
)
8

9
response = client.chat.completions.create(
10
    model="Qwen/Qwen2.5-7B-Instruct",
11
    messages=[
12
        {"role": "system", "content": "你是一个 AI 基础设施专家。"},
13
        {"role": "user", "content": "解释 Continuous Batching 的工作原理。"},
14
    ],
15
    temperature=0.7,
16
    max_tokens=512,
17
)
18

19
print(response.choices[0].message.content)

5.3 Completions API#

对标 OpenAI 的 v1/completions，适用于文本补全场景：

1
from openai import OpenAI
2

3
client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")
4

5
completion = client.completions.create(
6
    model="Qwen/Qwen2.5-7B-Instruct",
7
    prompt="LLM 推理优化的三个核心方向是",
8
    max_tokens=256,
9
    temperature=0.8,
10
)
11

12
print(completion.choices[0].text)

5.4 API 认证#

生产环境中建议开启 API Key 认证：

1
vllm serve Qwen/Qwen2.5-7B-Instruct --api-key my-secret-key

也可以通过环境变量设置：

1
export VLLM_API_KEY=my-secret-key
2
vllm serve Qwen/Qwen2.5-7B-Instruct

客户端调用时传入对应的 api_key：

1
client = OpenAI(api_key="my-secret-key", base_url="http://localhost:8000/v1")

5.5 支持的 API 端点#

6.1 采样参数（SamplingParams）#

💡 提示：对于大多数生产场景，推荐 temperature=0.7, top_p=0.9 作为起点。追求确定性输出时设 temperature=0。

6.2 引擎关键参数#

6.3 显存估算与 gpu-memory-utilization#

vLLM 启动时会按照以下方式分配显存：

1
总 GPU 显存 × gpu_memory_utilization = 模型权重 + KV Cache + 临时缓冲区

KV Cache 可用空间 = 总配额 - 模型权重 - 固定开销。KV Cache 越大，能同时处理的请求越多，吞吐就越高。

1
# 如果显存紧张，适当降低利用率
2
vllm serve Qwen/Qwen2.5-7B-Instruct --gpu-memory-utilization 0.85
3

4
# 如果需要限制最大序列长度来节省 KV Cache 空间
5
vllm serve Qwen/Qwen2.5-7B-Instruct --max-model-len 4096

⚠️ 注意：如果模型加载后启动报错 OOM，通常需要降低 --gpu-memory-utilization 或 --max-model-len，或者增加 --tensor-parallel-size 分摊到多卡。

6.4 Attention Backend 选择#

vLLM 会自动选择当前平台上性能最优的 Attention 后端，也可以手动指定：

1
# 使用 FlashAttention
2
vllm serve Qwen/Qwen2.5-7B-Instruct --attention-backend FLASH_ATTN
3

4
# 使用 FlashInfer
5
vllm serve Qwen/Qwen2.5-7B-Instruct --attention-backend FLASHINFER

7.1 基础用法#

1
# 2 卡张量并行
2
vllm serve Qwen/Qwen2.5-72B-Instruct --tensor-parallel-size 2
3

4
# 4 卡张量并行（适合 70B+ 模型）
5
vllm serve Qwen/Qwen2.5-72B-Instruct --tensor-parallel-size 4

在离线推理中同样支持：

1
from vllm import LLM, SamplingParams
2

3
llm = LLM(
4
    model="Qwen/Qwen2.5-72B-Instruct",
5
    tensor_parallel_size=4,
6
)
7

8
outputs = llm.generate(["解释 vLLM 的架构"], SamplingParams(max_tokens=256))

7.2 模型大小与 GPU 数量参考#

以下是常见模型大小在 FP16 精度下的显存需求估算：

💡 提示：实际所需显存 = 模型权重 + KV Cache + 运行时开销。使用量化（如 AWQ INT4）可以将权重大小缩减约 4 倍，从而用更少的 GPU 服务更大的模型。

7.3 vLLM 支持的并行方式#

vLLM 支持五种并行策略：

• 张量并行（Tensor Parallelism）：将模型的各层权重矩阵按列/行切分到多张 GPU
• 流水线并行（Pipeline Parallelism）：将模型的不同层分配到不同 GPU
• 数据并行（Data Parallelism）：多个副本独立处理不同请求
• 专家并行（Expert Parallelism）：MoE 模型中将不同专家分配到不同 GPU
• 上下文并行（Context Parallelism）：将长序列的上下文分散到多张 GPU

对于大部分场景，张量并行是首选，配置最简单且效果最好。

8.1 启动时 OOM#

1
torch.cuda.OutOfMemoryError: CUDA out of memory.

✅ 解决方案：

1
# 方法一：降低显存利用率
2
vllm serve model_name --gpu-memory-utilization 0.8
3

4
# 方法二：缩短最大序列长度
5
vllm serve model_name --max-model-len 2048
6

7
# 方法三：增加张量并行
8
vllm serve model_name --tensor-parallel-size 2
9

10
# 方法四：使用量化模型
11
vllm serve model_name --quantization awq

8.2 Chat 模型输出乱码#

如果使用 llm.generate 直接传入文本给 Chat 模型，输出可能不符合预期。

✅ 解决方案：改用 llm.chat 方法或手动调用 tokenizer.apply_chat_template，确保输入格式符合模型的 Chat Template。

8.3 ModelScope 下载模型#

国内环境下载 HuggingFace 模型较慢，可以切换到 ModelScope：

1
export VLLM_USE_MODELSCOPE=True
2
vllm serve Qwen/Qwen2.5-7B-Instruct

8.4 指定信任远程代码#

部分模型需要执行自定义代码：

1
vllm serve model_name --trust-remote-code