vLLM 部署实战：高吞吐 LLM 推理服务

传统 KV Cache:
┌──────────────────────────────────┐
│ Request A: [████████░░░░░░░░░░░] │  预分配，大量浪费
│ Request B: [██████████████░░░░░] │
│ Request C: [██░░░░░░░░░░░░░░░░░] │
└──────────────────────────────────┘
显存利用率：~40%

PagedAttention:
┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
│A1│A2│B1│B2│B3│C1│A3│B4│A4│B5│  按需分配，零浪费
└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
显存利用率：~95%

docker run --gpus all \
  -v /models:/models \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model /models/Qwen3-7B-Instruct \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.9

from vllm import LLM, SamplingParams

llm = LLM(
    model="/models/Qwen3-7B-Instruct",
    tensor_parallel_size=1,       # GPU 数量
    gpu_memory_utilization=0.9,    # 显存利用率
    max_model_len=8192,            # 最大上下文长度
    enable_prefix_caching=True,    # 前缀缓存
    enforce_eager=False,           # CUDA Graph 优化
)

sampling = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1024,
)

# 批量推理
outputs = llm.generate(
    ["你好", "解释RAG", "写一段Python代码"],
    sampling,
)

# 启动 API 服务
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen3-7B-Instruct \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --served-model-name qwen3-7b

# 客户端调用（与 OpenAI SDK 完全兼容）
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="vllm")

response = client.chat.completions.create(
    model="qwen3-7b",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)

llm = LLM(
    model="/models/Qwen3-7B-Instruct",
    
    # 批处理
    max_num_seqs=256,           # 最大并发序列数
    max_num_batched_tokens=8192, # 每批最大 token 数
    
    # KV Cache
    gpu_memory_utilization=0.9,  # 显存利用率（0.8-0.95）
    swap_space=4,                # CPU 交换空间 (GB)
    
    # 量化
    quantization="awq",          # AWQ 量化（省 50% 显存）
)

# 启用前缀缓存：相同 system prompt 的请求共享 KV Cache
llm = LLM(
    model="/models/Qwen3-7B-Instruct",
    enable_prefix_caching=True,
)

# 效果：
# 第一个请求：1.2s（生成 KV Cache）
# 后续相同 system prompt 的请求：0.3s（复用 KV Cache）

# 用小模型猜，大模型验
llm = LLM(
    model="/models/Qwen3-7B-Instruct",
    speculative_model="/models/Qwen3-0.5B",  # 草稿模型
    num_speculative_tokens=5,                 # 每轮猜 5 个 token
)

# 效果：吞吐量提升 1.5-2x
# 原理：小模型快速生成 5 个候选 token，大模型一次性验证

# AWQ 量化（推荐）
# 模型大小：14GB → 5GB
# 性能损失：<2%
llm = LLM(
    model="/models/Qwen3-7B-Instruct-AWQ",
    quantization="awq",
    max_model_len=8192,
)

# GPTQ 量化
llm = LLM(
    model="/models/Qwen3-7B-Instruct-GPTQ",
    quantization="gptq",
)

# FP8（H100 以上 GPU）
llm = LLM(
    model="/models/Qwen3-7B-Instruct",
    quantization="fp8",
)

# 4 GPU 张量并行
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen3-72B-Instruct \
  --tensor-parallel-size 4 \
  --port 8000

# 原理：将模型权重切分到 4 张 GPU
# GPU 0: attention layers (1/4)
# GPU 1: attention layers (2/4)  
# GPU 2: attention layers (3/4)
# GPU 3: attention layers (4/4)
# 每次前向传播需要 4 GPU 通信

# 2 GPU 流水线并行
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen3-72B-Instruct \
  --pipeline-parallel-size 2 \
  --port 8000

# vLLM 内置 Prometheus 指标
# 访问 http://localhost:8000/metrics

# 关键指标：
# vllm:num_requests_running    - 运行中的请求数
# vllm:num_requests_waiting    - 排队中的请求数
# vllm:gpu_cache_usage_perc    - GPU 缓存使用率
# vllm:time_to_first_token     - 首 Token 延迟
# vllm:time_per_output_token   - 每 Token 生成时间
# vllm:e2e_request_latency     - 端到端延迟

# Prometheus 配置
scrape_configs:
  - job_name: 'vllm'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: '/metrics'

# docker-compose.yml
version: '3.8'
services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=hf_xxx
    volumes:
      - /models:/models
    ports:
      - "8000:8000"
    command:
      - --model=/models/Qwen3-7B-Instruct
      - --tensor-parallel-size=1
      - --max-model-len=8192
      - --gpu-memory-utilization=0.9
      - --enable-prefix-caching
      - --served-model-name=qwen3-7b
      - --uvicorn-log-level=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: ["gpu"]

# 降低显存占用
llm = LLM(
    model="...",
    gpu_memory_utilization=0.85,   # 降低
    max_model_len=4096,            # 缩短上下文
    max_num_seqs=64,               # 减少并发
    quantization="awq",            # 量化
)

# 原因：KV Cache 未命中
# 解决：启用前缀缓存
llm = LLM(
    model="...",
    enable_prefix_caching=True,
)

# 原因：批太小
# 解决：增加并发
llm = LLM(
    model="...",
    max_num_seqs=256,
    max_num_batched_tokens=16384,
)