第 5 章 vLLM：工业级推理引擎深度剖析

# 最朴素的推理方式
from transformers import AutoModelForCausalLM, AutoTokenizer
 
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-7B-Instruct")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-7B-Instruct")
 
inputs = tokenizer("Hello", return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=100)

KV Cache = 2 (K + V) × num_layers × num_heads × head_dim × seq_len × bytes_per_element

2 × 28 × 28 × 128 × 4096 × 2 bytes ≈ 1.6 GB

Static Batching:
请求 A: ████████████░░░░░░░░  (12 token, 等到 20 token 的位置才释放)
请求 B: ████████████████████  (20 token)
请求 C: ██████░░░░░░░░░░░░░░  (6 token, 浪费 14 个位置的计算)
         ────────────────────
         所有请求必须等 B 结束

GPU 显存:
┌────────────────────────────────────────────────────────┐
│ 请求 A 的 KV Cache [████████░░░░░░░░░░░░]  50% 浪费   │
│ 请求 B 的 KV Cache [██░░░░░░░░░░░░░░░░░░]  90% 浪费   │
│ 请求 C 的 KV Cache [████████████████░░░░]  20% 浪费   │
│ ░░░░░░░░░░░░░░░░░░░  无法分配新请求（碎片化）         │
└────────────────────────────────────────────────────────┘

逻辑视图（每个请求看到的连续 KV Cache）:
请求 A: [Block 0][Block 1][Block 2][Block 3]

物理视图（GPU 显存中的实际存储，不连续）:
┌──────────────────────────────────────────────┐
│ [A-B2] [B-B0] [A-B0] [C-B1] [A-B3] [B-B1]  │
│ [C-B0] [A-B1] [Free] [Free] [C-B2] [Free]   │
└──────────────────────────────────────────────┘

Block Table（block table，逻辑块 → 物理块的映射表，等价于操作系统的页表 page table）:
请求 A: {0→2, 1→7, 2→0, 3→4}
请求 B: {0→1, 1→5}
请求 C: {0→6, 1→3, 2→10}

时间 →
Static Batch 1:
  请求 A: ████████ (done)
  请求 B: ████████████████████ (done)
  请求 C: ████ (done, 但要等 B)
  ────────────────────── batch 结束，才能处理新请求

Static Batch 2:
  请求 D: ██████████████ (done)
  请求 E: ██ (done, 等 D)

时间 →
Step  1: [A][B][C]     ← 三个请求同时处理
Step  2: [A][B][C]
Step  3: [A][B][C]
Step  4: [A][B][D]     ← C 完成，D 立刻加入
Step  5: [A][B][D]
Step  6: [E][B][D]     ← A 完成，E 立刻加入
Step  7: [E][B][D]
Step  8: [E][F][D]     ← B 完成，F 立刻加入
...

# 推荐用 pip，需要 CUDA 12.1+
pip install vllm
 
# 验证安装
python -c "import vllm; print(vllm.__version__)"

export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2-7B --local-dir ./models/Qwen2-7B

pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen2-7B', cache_dir='./models')"

python -m vllm.entrypoints.openai.api_server --model ./models/Qwen2-7B

# 启动 OpenAI 兼容的 API 服务（OpenAI Compatible API：复刻 OpenAI /v1 端点的协议，让任何 OpenAI SDK 都能直接对接 vLLM）
vllm serve Qwen/Qwen2-7B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.9

# 测试
curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2-7B-Instruct",
        "messages": [{"role": "user", "content": "Hello!"}],
        "max_tokens": 100
    }'

# 2 卡部署 —— 每张卡装一半模型
vllm serve Qwen/Qwen2-72B-Instruct \
    --tensor-parallel-size 2 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.9
 
# 4 卡部署
vllm serve Qwen/Qwen2-72B-Instruct \
    --tensor-parallel-size 4 \
    --max-model-len 8192
 
# 跨机器部署（8 卡 × 2 机器）
# TP=8（每机器内），PP=2（跨机器）
vllm serve deepseek-ai/DeepSeek-V3 \
    --tensor-parallel-size 8 \
    --pipeline-parallel-size 2

vllm serve <model> \
    # 基础配置
    --host 0.0.0.0 \
    --port 8000 \
    --served-model-name my-model \        # API 中的模型名称
    --api-key sk-xxx \                    # 设置 API key
 
    # 性能参数
    --max-model-len 8192 \                # 最大上下文长度
    --gpu-memory-utilization 0.90 \       # GPU 显存利用率上限
    --max-num-seqs 256 \                  # 最大并发请求数
    --max-num-batched-tokens 8192 \       # 一次 prefill 的最大 token 数
 
    # 量化
    --quantization awq \                  # 使用 AWQ（Activation-aware Weight Quantization，激活感知权重量化，主流 4bit 量化算法之一，第 7 章细讲）量化模型
    --dtype auto \                        # 数据类型，auto 会自动选择
 
    # 并行
    --tensor-parallel-size 2 \            # Tensor 并行度
    --pipeline-parallel-size 1 \          # Pipeline 并行度
 
    # 高级优化
    --enable-prefix-caching \             # 开启 Prefix Caching
    --enable-chunked-prefill              # 开启 Chunked Prefill（把长 prefill 切片，和 decode 交织执行）

GPU 显存分配:
┌──────────────────────────────────────┐
│  模型权重 (固定)              ~40%   │
├──────────────────────────────────────┤
│  KV Cache (动态)              ~50%   │  ← gpu-memory-utilization 控制的部分
├──────────────────────────────────────┤
│  预留 (CUDA context + 碎片)   ~10%   │  ← CUDA context: 每个进程绑定到 GPU 上的运行时上下文，存放 stream、module 等
└──────────────────────────────────────┘

# 模型原始支持 32768，但实际业务用不到那么长
# 降低 max-model-len 可以减少 KV Cache 预分配，腾出显存给更多并发
vllm serve Qwen/Qwen2-7B-Instruct --max-model-len 4096

vllm serve Qwen/Qwen2-7B-Instruct --enable-prefix-caching

vllm serve Qwen/Qwen2-7B-Instruct --enable-chunked-prefill

POST /v1/chat/completions    ← 对话补全
POST /v1/completions         ← 文本补全
POST /v1/embeddings          ← 文本嵌入
GET  /v1/models              ← 模型列表

from openai import OpenAI  # OpenAI 官方 Python SDK，等价于 npm 包 openai 的 Python 版
 
# 原来调 OpenAI
# client = OpenAI(api_key="sk-xxx")
 
# 改成调 vLLM，只需要改 base_url
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",  # vLLM 默认不需要 key
)
 
response = client.chat.completions.create(
    model="Qwen/Qwen2-7B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain PagedAttention in 3 sentences."},
    ],
    temperature=0.7,  # temperature: 采样温度，越高输出越发散，0 等同贪心解码
    max_tokens=200,
    stream=True,
)
 
for chunk in response:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

// TypeScript / Node.js
import OpenAI from 'openai';
 
const client = new OpenAI({
  baseURL: 'http://your-vllm-server:8000/v1',
  apiKey: 'not-needed',
});
 
// 后面的代码完全不用改
const response = await client.chat.completions.create({
  model: 'Qwen/Qwen2-7B-Instruct',
  messages: [{ role: 'user', content: 'Hello' }],
});

from openai import OpenAI
 
client = OpenAI(base_url="http://localhost:8000/v1", api_key="na")
 
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                },
                "required": ["city"],
            },
        },
    }
]
 
response = client.chat.completions.create(
    model="Qwen/Qwen2-7B-Instruct",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto",
)
 
# 模型会返回 tool_calls
message = response.choices[0].message
if message.tool_calls:
    call = message.tool_calls[0]
    print(f"调用工具: {call.function.name}")
    print(f"参数: {call.function.arguments}")

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2-7B-Instruct \
    --enable-auto-tool-choice \
    --tool-call-parser hermes