vLLM 实战：高吞吐大模型推理服务部署

当你把 Qwen、Llama 这类大模型接到线上业务，最先撞上的往往不是准确率，而是吞吐量。原生 HuggingFace transformers 逐请求推理，GPU 显存里大量的 KV Cache 因为碎片化和预留而浪费，并发一高就 OOM 或排队。vLLM 正是为解决大模型推理的高吞吐与高显存利用率而生：它用 PagedAttention 把 KV Cache 像操作系统虚拟内存一样分页管理，让显存利用率逼近理论上限，单卡吞吐常常能翻 2–5 倍。

一、为什么需要 vLLM：大模型推理的吞吐瓶颈

自回归生成是“一个 token 接一个 token”的串行过程。每生成一个新 token，都要把前面所有 token 的 Key/Value 缓存（KV Cache）读一遍。传统推理框架为每个请求预先分配一段连续显存，长度按 max_length 估算，结果大量显存被“预留但没用到”；同时请求之间无法共享相同前缀的缓存。并发一上来，显存迅速见底，要么 OOM，要么请求堆积、延迟飙升。这正是线上大模型服务最常见的性能天花板。

vLLM 由 UC Berkeley 团队开源，核心创新是 PagedAttention。它借鉴操作系统的虚拟内存分页思想，把 KV Cache 切成固定大小的 block 按需分配，使显存利用率从传统方案的 20%–40% 提升到 90% 以上，从而在同硬件下支撑数倍并发。下面从原理到落地完整走一遍。

二、核心原理：PagedAttention 做了什么

PagedAttention 把 KV Cache 拆成若干固定大小的“页（block）”，每个 block 可存放在显存任意位置，通过一张映射表记录逻辑块到物理块的对应关系。好处有两点：

• 消除碎片：不再需要连续大块显存，按需分配、用完即回收，显存利用率接近 100%。
• 共享前缀：在并行采样（如 beam search、对同一 prompt 的多路补全）时，相同前缀的 block 可被多个序列安全共享，进一步省显存。

这与操作系统的分页内存、写时复制（Copy-on-Write）思路一脉相承，因此 vLLM 在批量并发、长上下文场景下收益最明显。

三、快速安装与单机启动

vLLM 需要较新的 CUDA 驱动与 NVIDIA 显卡。推荐用官方 PyPI 包安装，再用内置的 OpenAI 兼容服务入口启动：

pip install vllm

# 启动 OpenAI 兼容 API 服务（模型可换成本地路径或 HuggingFace 仓库名）
vllm serve Qwen/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 8000

服务起来后，默认在 http://localhost:8000/v1 提供与 OpenAI 完全一致的接口，老代码几乎零改动即可接入。注意不同 vLLM 版本的启动命令略有差异，旧版用 python -m vllm.entrypoints.openai.api_server，新版统一为 vllm serve。

四、用 OpenAI 兼容 API 调用

因为接口兼容 OpenAI，直接用官方 SDK 把 base_url 指向本地即可：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",   # vLLM 默认不校验 key
)

resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "用一句话解释 PagedAttention"}],
    temperature=0.7,
)
print(resp.choices[0].message.content)

不写代码时，用 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 的吞吐很大程度取决于启动参数。下面几个最常用：

一个典型的多卡高并发启动命令：

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.9 \
  --max-num-seqs 128 \
  --enable-prefix-caching

六、量化部署：在更小显存上跑更大模型

7B 模型用 FP16 约需 14GB 显存，量化能显著压缩。vLLM 原生支持多种量化后端：

# 需先准备好量化权重（如社区已发布的 -AWQ 版本或 AutoAWQ 自行量化）
vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --quantization awq

量化是“用少量精度换显存”，对话、摘要类任务通常几乎无感；但数学、代码等强推理场景建议先小流量对比效果再全量。

七、用 Docker 容器化部署

生产环境推荐用官方镜像，避免本机 CUDA 版本错配：

docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 --port 8000

多实例前面再挂一层 Nginx 反向代理 做统一入口、TLS 与限流，可参考本站的 Docker 部署 实践。容器编排也可交给 GitHub Actions 做构建与冒烟。

八、吞吐压测与监控

上线前务必用接近真实的 prompt 分布压测，重点关注四个指标：

import concurrent.futures
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

def ask(i):
    r = client.chat.completions.create(
        model="Qwen/Qwen2.5-7B-Instruct",
        messages=[{"role":"user","content":f"第{i}个问题：用三句话介绍 Kubernetes。"}],
    )
    return len(r.choices[0].message.content)

with concurrent.futures.ThreadPoolExecutor(max_workers=32) as ex:
    print("完成请求数:", len(list(ex.map(ask, range(200)))))

name: llm-smoke
on: [push]
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - name: Start vLLM
        run: |
          docker run -d --gpus all -p 8000:8000 vllm/vllm-openai:latest \
            --model Qwen/Qwen2.5-0.5B-Instruct --host 0.0.0.0 --port 8000
          sleep 60
      - name: Smoke test
        run: |
          curl -f http://localhost:8000/v1/models
          curl -f http://localhost:8000/v1/chat/completions \
            -H "Content-Type: application/json" \
            -d '{"model":"Qwen/Qwen2.5-0.5B-Instruct","messages":[{"role":"user","content":"ping"}]}'