vLLM — 高性能 LLM 推理引擎¶

# === pip 安装（最简单） ===
pip install vllm  # 安装 vLLM

# === 指定 CUDA 版本安装 ===
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu124  # CUDA 12.4

# === 从源码安装（获取最新功能） ===
git clone https://github.com/vllm-project/vllm.git  # 克隆仓库
cd vllm  # 进入目录
pip install -e .  # 可编辑模式安装

# 验证安装
python -c "import vllm; print(vllm.__version__)"  # 打印版本号

# 启动 OpenAI 兼容的 API 服务器
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000  # 在 8000 端口启动服务

# 指定 GPU 数量（多卡并行）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --tensor-parallel-size 2 \
  --port 8000  # 用 2 张 GPU 并行推理

# 启动后就有了 OpenAI 兼容的 API
# 可以直接用 OpenAI SDK 调用

from openai import OpenAI  # 导入 OpenAI SDK

# 创建客户端，指向本地 vLLM 服务
client = OpenAI(
    base_url="http://localhost:8000/v1",  # vLLM 的 OpenAI 兼容端点
    api_key="vllm"  # vLLM 不需要真实 Key
)

# 对话请求
response = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",  # 模型名称
    messages=[
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "解释一下什么是 16S rRNA 测序？"}
    ],
    temperature=0.7,  # 创造性参数
    max_tokens=1000  # 最大输出长度
)

print(response.choices[0].message.content)  # 打印回答

from vllm import LLM, SamplingParams  # 导入 vLLM 核心类

# 加载模型
llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",  # HuggingFace 模型名
    tensor_parallel_size=1,  # GPU 数量
    gpu_memory_utilization=0.9  # GPU 显存使用率（90%）
)

# 设置采样参数
sampling_params = SamplingParams(
    temperature=0.7,  # 温度（越高越有创造力）
    top_p=0.9,  # 核采样
    max_tokens=512  # 最大生成长度
)

# 批量推理（vLLM 的强项——高吞吐批处理）
prompts = [
    "什么是宏基因组学？",
    "解释 Shannon 多样性指数。",
    "QIIME2 和 Mothur 有什么区别？"
]

outputs = llm.generate(prompts, sampling_params)  # 批量生成

for output in outputs:
    print(f"问题: {output.prompt}")  # 打印问题
    print(f"回答: {output.outputs[0].text}")  # 打印回答
    print("---")

传统推理的问题：
- GPU 显存像一整块地 → 每个请求要预留一大片
- 实际用不到那么多 → 60-80% 的显存被浪费了
- 就像每个人要占一整排座位，就算只有一个人

PagedAttention 的方案：
- 把显存切成小页（像操作系统的虚拟内存）
- 每个请求按需分配页
- 用多少分多少，不浪费
- 就像电影院自由选座，一个人只占一个座

效果：
- 同样的 GPU，能同时服务更多请求
- 吞吐量提升 2-24 倍

# FP8 量化（显存减半，精度几乎不降）
vllm serve Qwen/Qwen2.5-72B-Instruct \
  --quantization fp8 \
  --port 8000  # FP8 量化运行 72B 模型

# AWQ 4-bit 量化
vllm serve TheBloke/Qwen2.5-7B-AWQ \
  --quantization awq \
  --port 8000  # 4-bit 量化，显存占用更小

# GPTQ 量化
vllm serve TheBloke/Qwen2.5-7B-GPTQ \
  --quantization gptq \
  --port 8000  # GPTQ 量化

# GGUF 格式（llama.cpp 的格式）
vllm serve ./model.gguf \
  --port 8000  # 直接加载 GGUF 文件

# 张量并行（一个模型分到多张 GPU）
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --port 8000  # 用 4 张 GPU 运行 70B 模型

# 流水线并行（模型按层分配到不同 GPU）
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --pipeline-parallel-size 2 \
  --tensor-parallel-size 2 \
  --port 8000  # 2路流水线 x 2路张量并行 = 4 GPU

# 用小模型预测 + 大模型验证，加速推理
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --speculative-model meta-llama/Llama-3.2-1B-Instruct \
  --num-speculative-tokens 5 \
  --port 8000

# 原理：
# 1. 1B 小模型快速预测接下来5个 token
# 2. 70B 大模型一次性验证这5个 token
# 3. 正确的直接用，错误的重新生成
# 效果：推理速度提升 1.5-3 倍

# 对于有共同前缀的请求（如相同的 system prompt），
# vLLM 会缓存已计算的 KV Cache，避免重复计算

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enable-prefix-caching \
  --port 8000  # 开启前缀缓存

# V1 引擎中前缀缓存几乎零开销（<1%）
# 对于 RAG 场景效果明显——相同的知识库上下文只计算一次

# 使用官方 Docker 镜像
docker run --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-7B-Instruct  # Docker 一键启动

# 生产环境推荐加上共享内存参数
# --shm-size 1g  避免 CUDA IPC 错误