vLLM 从入门到生产部署学习教程

用户问："中国的首都是什么？"

模型内心活动：
第1步：看到问题 → 生成 "北"
第2步：看到问题 + "北" → 生成 "京"
第3步：看到问题 + "北京" → 生成 "是"
第4步：看到问题 + "北京是" → 生成 "中"
...

传统分配方式：

读者A（短请求，只看1本书）→ 分到一张 4人桌  → ❌ 浪费3个座位
读者B（长请求，要看10本书）→ 分到一张 4人桌  → ❌ 座位不够，坐不下
读者C（中等请求）→ 分到一张 4人桌          → 📍 刚好够用

读者A走了 → 他的4人桌空出来了 → 但因为大小固定
            新来的读者D（需要3个座位）坐不进去 → ❌ 碎片浪费

📦 KV 缓存被切成统一大小的"块"（Block），每块默认存 16 个 token

传统方式（连续分配）：
读者A: [████████████]   ← 一整张连续的大桌子
读者B: [████████]       ← 另一张连续的大桌子
空闲:   [░░░░░░░░░░]    ← 碎片，谁也塞不进去

✨ PagedAttention（分页管理）：
读者A: [块3][块7][块1][块9]  ← 物理上不连续，但逻辑上是连续的
读者B: [块5][块2]            ← 灵活分配，按需取用

物理显存分布：
[块3][块5][块7][块1][块2][块9]  ← 所有块整整齐齐，没有碎片！

传统方式         PagedAttention
──────────       ──────────────
内存利用率 30%   内存利用率 95%+  ← 几乎用满！
碎片化严重       几乎零碎片        ← 所有块一样大
固定分配         按需分配          ← 用多少分多少
不可共享         支持共享          ← 相同前缀可共用

# 打开终端，输入：
nvidia-smi

# 查看输出顶部的 "CUDA Version" 字段
# 如果是 12.1 或更高，就满足要求！
# 如果是 11.x，需要先升级 CUDA

# 【第一步】创建虚拟环境（强烈建议！避免和系统 Python 打架）
# 用 Python 自带的 venv 模块创建一个干净的"小房间"
python -m venv vllm-env

# 进入这个"小房间"（Windows 用 vllm-env\Scripts\activate）
source vllm-env/bin/activate

# 【第二步】安装 vLLM
# 注意：pip 会自动检测你的 CUDA 版本并下载匹配的预编译包
pip install vllm

# 【第三步】验证安装成功
python -c "import vllm; print(f'vLLM 版本: {vllm.__version__}')"
# 如果打印出版本号（如 0.7.0），就成功了！🎉

# 【第一步】安装 uv（如果还没装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 【第二步】创建虚拟环境并安装
uv venv myenv --python 3.12 --seed  # --seed 表示同时安装 pip
source myenv/bin/activate

# 【第三步】安装 vLLM（感受下速度差异！）
uv pip install vllm

# 【第一步】拉取官方镜像（类似下载一个"vLLM 系统镜像"）
docker pull vllm/vllm-openai:latest

# 【第二步】运行容器
# --gpus all      : 给容器分配所有 GPU
# -p 8000:8000    : 把容器内的 8000 端口映射到本机
# --model ...     : 指定要加载的模型
docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-1.5B-Instruct

# 现在打开浏览器访问 http://localhost:8000/docs 就能看到 API 文档了！

# 克隆完整的 vLLM 源码仓库到本地
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 以"可编辑模式"安装（-e），这样修改源码后无需重新安装
pip install -e .

from vllm import LLM, SamplingParams

# ===========================================
# 第一步：加载模型
# ===========================================
# LLM 是 vLLM 的核心类，负责管理模型和推理
# 这里我们用 Qwen2.5-1.5B（15 亿参数的小模型），
# 8GB 显存的显卡就能运行！
print("🔄 正在加载模型...（第一次会下载，请耐心等待）")
llm = LLM(model="Qwen/Qwen2.5-1.5B-Instruct")

# ===========================================
# 第二步：配置生成参数
# ===========================================
# SamplingParams 控制模型如何"选择下一个词"
sampling_params = SamplingParams(
    temperature=0.8,      # 🌡️ 温度：控制随机性（0=稳定保守，1=天马行空）
    top_p=0.95,           # 🎯 核采样：只从概率最高的前 95% 的词中选择
    max_tokens=100,       # 📏 最多生成 100 个 token（约 70 个汉字）
)

# ===========================================
# 第三步：让它说句话
# ===========================================
outputs = llm.generate("你好，请介绍一下自己。", sampling_params)

# ===========================================
# 第四步：看结果
# ===========================================
for output in outputs:
    prompt = output.prompt          # 输入的内容
    generated = output.outputs[0].text  # 模型生成的内容
    print(f"\n📝 输入: {prompt}")
    print(f"✨ 输出: {generated}")
    print(f"🔢 生成了 {len(output.outputs[0].token_ids)} 个 token")

# 确保在虚拟环境中
python test_vllm.py

🔄 正在加载模型...（第一次会下载，请耐心等待）
（这里会显示模型下载进度条，取决于你的网速）

📝 输入: 你好，请介绍一下自己。
✨ 输出: 你好！我是 Qwen，一个由阿里云开发的大语言模型...
🔢 生成了 85 个 token

from vllm import LLM, SamplingParams

# ===========================================
# 1. 加载模型
# ===========================================
# 这里用 7B 模型（70 亿参数），需要约 16GB 显存
# 如果显存不够，可以换成 "Qwen/Qwen2.5-1.5B-Instruct"
llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    # trust_remote_code=True 的作用：
    # 有些模型的代码不在 HuggingFace 标准库中，需要加载模型自带的代码
    # 安全提示：只在信任的模型来源使用
    trust_remote_code=True,
    # tensor_parallel_size=1 表示只用 1 张 GPU
    # 如果有多张 GPU 可以设为 2、4...（详见第 5.4 节）
    tensor_parallel_size=1,
)

# ===========================================
# 2. 配置采样参数（控制模型怎么"说话"）
# ===========================================
# 每个参数的作用，下面都给你讲透了
sampling_params = SamplingParams(
    # 🌡️ temperature（温度）：0~2 之间的数
    #   0    = 每次选概率最高的词 → 稳定但机械
    #   0.7  = 偶尔选概率低的词 → 有创意但不离谱
    #   1.0+ = 经常选冷门词 → 天马行空，可能胡说八道
    temperature=0.7,
    
    # 🎯 top_p（核采样阈值）：0~1 之间的数
    #   只保留概率加起来达到 top_p 的候选词
    #   0.9 表示：从概率最高的词里选，直到累计概率到 90%
    #   作用是砍掉概率极低的"离谱选项"
    top_p=0.9,
    
    # 📏 max_tokens：最多生成多少个 token
    #   注意：一个中文汉字 ≈ 1~2 个 token
    #   设太小 → 话没说完就断了；设太大 → 可能啰嗦
    max_tokens=512,
    
    # 🔄 frequency_penalty（频率惩罚）：-2~2
    #   正数 → 避免重复用同一个词（说过的词扣分）
    #   0    → 不干预
    #   负数 → 鼓励重复（写诗时可能有用）
    frequency_penalty=0.0,
    
    # 🔄 presence_penalty（存在惩罚）：-2~2
    #   和 frequency_penalty 类似，但更狠——只要出现过的词都扣分
    #   鼓励模型聊新话题，而不是反复说同一个词
    presence_penalty=0.0,
    
    # ⏹️ stop：遇到这些词就停止生成
    #   像句号一样，告诉模型"话说到这里就够了"
    stop=["<|endoftext|>"],
)

# ===========================================
# 3. 批量输入 — 一次喂多个问题
# ===========================================
# vLLM 会自动把这些问题"打包"处理，比一个一个跑快很多
prompts = [
    "请解释什么是机器学习？用简单的话说。",
    "写一首关于春天的诗，四行就行。",
    "用 Python 实现一个快速排序算法，加上注释。",
]

print(f"🚀 开始处理 {len(prompts)} 个请求...")
outputs = llm.generate(prompts, sampling_params)
print("✅ 全部处理完成！\n")

# ===========================================
# 4. 处理输出结果
# ===========================================
for i, output in enumerate(outputs):
    prompt = output.prompt
    generated_text = output.outputs[0].text
    
    print(f"━━━ 请求 {i+1} ━━━")
    print(f"📝 输入: {prompt[:50]}...")  # 只显示前 50 个字符
    print(f"✨ 输出: {generated_text[:200]}...")  # 只显示前 200 个字符
    print(f"📊 Token 数: {len(output.outputs[0].token_ids)}")
    print()

import asyncio
from vllm import AsyncLLMEngine, SamplingParams
from vllm.engine.arg_utils import AsyncEngineArgs

async def main():
    # 配置引擎参数（和离线模式类似，但用 AsyncEngineArgs）
    engine_args = AsyncEngineArgs(
        model="Qwen/Qwen2.5-7B-Instruct",
        tensor_parallel_size=1,
    )
    
    # 创建异步引擎
    # 异步 = 不阻塞主线程，可以同时处理其他事情
    engine = AsyncLLMEngine.from_engine_args(engine_args)
    
    # 采样参数（和之前一样）
    sampling_params = SamplingParams(max_tokens=256, temperature=0.8)
    
    # 发送请求（需要给每个请求一个唯一 ID）
    request_id = "request-001"
    results_generator = engine.generate(
        "请介绍一下深度学习的发展历史，用 3 个阶段来说。",
        sampling_params,
        request_id
    )
    
    # 🔄 流式获取结果
    # async for 表示"来一个处理一个"，不等全部生成完
    print("🤖 模型正在思考...")
    async for request_output in results_generator:
        if len(request_output.outputs) > 0:
            # 每次拿到最新的已生成文本
            text = request_output.outputs[0].text
            # \r 让光标回到行首，实现"原地刷新"的打字效果
            print(f"\r生成中: {text}", end="", flush=True)
    
    print("\n✅ 生成完成！")

# Python 3.7+ 的异步入口
asyncio.run(main())

# 一行命令启动一个完整的 OpenAI 兼容 API 服务
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \              # 监听所有网络接口（0.0.0.0 = 允许外部访问）
  --port 8000 \                  # 服务端口（类似 Web 服务器的 80 端口）
  --api-key your-api-key \       # API 密钥（防止未授权访问）
  --served-model-name qwen-7b \  # 对外显示的模型名（可以随便起名）
  --max-model-len 4096 \         # 最大上下文长度（越长越耗显存）
  --gpu-memory-utilization 0.9   # GPU 显存利用率（0.9 = 90%）

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

# server.py
from vllm.entrypoints.openai.api_server import run
import uvicorn

if __name__ == "__main__":
    uvicorn.run(
        "vllm.entrypoints.openai.api_server:app",  # Flask/FastAPI 风格的路由
        host="0.0.0.0",
        port=8000,
        log_level="info",
    )

# 运行方式
python server.py

# 可以加命令行参数覆盖默认配置
vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000

# 【测试 1】列出可用模型（相当于"菜单"）
curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer your-api-key"

# 预期返回：
# {
#   "data": [
#     {"id": "qwen-7b", "object": "model", ...}
#   ]
# }

# 【测试 2】聊天补全（核心功能）
# 注意：stream=true 表示启用流式输出
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "qwen-7b",
    "messages": [
      {"role": "system", "content": "你是一个 helpful 的助手。"},
      {"role": "user", "content": "什么是大语言模型？"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": true
  }'

# 流式输出时会看到 data: {"choices":[{"delta":{"content":"大"}}]}
# data: {"choices":[{"delta":{"content":"语言"}}]}
# ... 一个字一个字地返回

from openai import OpenAI

# ===========================================
# 初始化客户端
# ===========================================
# 唯一的区别：把 api_base 换成你的 vLLM 服务地址
# 其他代码完全不用改！
client = OpenAI(
    base_url="http://localhost:8000/v1",  # 👈 vLLM 的服务地址
    api_key="your-api-key"                # 👈 你设置的 API 密钥
)

# ===========================================
# 聊天补全（非流式）
# ===========================================
response = client.chat.completions.create(
    model="qwen-7b",
    messages=[
        {"role": "system", "content": "你是一个专业的技术顾问。"},
        {"role": "user", "content": "解释一下 PagedAttention 的工作原理，用大白话说。"}
    ],
    temperature=0.7,
    max_tokens=1024,
    # stream=False 表示等全部生成完再返回
)

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

# ===========================================
# 流式版本（适合聊天 UI）
# ===========================================
response = client.chat.completions.create(
    model="qwen-7b",
    messages=[
        {"role": "system", "content": "你是一个专业的 AI 助手。"},
        {"role": "user", "content": "用 Python 实现一个二分查找。"}
    ],
    temperature=0.7,
    max_tokens=1024,
    stream=True,  # 👈 启用流式输出
)

# 逐块接收生成的内容，实现"打字机效果"
print("🤖: ", end="", flush=True)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()  # 最后换行

# AWQ 量化（最常用，精度损失小）
# 注意：需要下载专门的 AWQ 版本模型（以 -AWQ 结尾）
vllm serve TheBloke/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --max-model-len 8192

# GPTQ 量化
vllm serve TheBloke/Qwen2.5-7B-Instruct-GPTQ \
  --quantization gptq \
  --max-model-len 8192

# FP8 量化（需要 H100/H200 等支持 FP8 的 GPU）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --quantization fp8 \
  --max-model-len 8192

# 启动时启用 LoRA 支持
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enable-lora \           # 开启 LoRA 功能
  --max-loras 5 \           # 最多同时加载 5 个 LoRA 适配器
  --max-lora-rank 64 \      # LoRA 的秩（越大适配能力越强，也越耗显存）
  --lora-extra-vocab-size 256  # 如果 LoRA 引入了新词，需要预留空间

from vllm import LLM, SamplingParams
from vllm.lora.request import LoRARequest

# 加载基座模型，同时启用 LoRA
llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    enable_lora=True,
    max_loras=4,         # 最多 4 个适配器同时驻留内存
)

sampling_params = SamplingParams(max_tokens=256, temperature=0.7)

# 切换不同的 LoRA 适配器，得到不同的"人设"回复
# 每个 LoRA 适配器是一个很小的文件（通常 10~100 MB）
outputs = llm.generate(
    ["请写一个产品营销文案。（用营销专家的语气）"],
    sampling_params,
    lora_request=LoRARequest(
        lora_name="marketing-lora",    # 适配器名称
        lora_int_id=1,                 # 适配器 ID
        lora_path="./lora-marketing"   # 适配器文件路径
    )
)

vllm serve Qwen/Qwen2-VL-7B-Instruct \
  --trust-remote-code \
  --max-model-len 8192 \
  --limit-mm-per-prompt image=4 \  # 每个请求最多 4 张图片
  --gpu-memory-utilization 0.9

from openai import OpenAI
import base64

client = OpenAI(base_url="http://localhost:8000/v1", api_key="token-abc123")

# 辅助函数：把图片文件转成 base64 编码（图片的"文本表示"）
def encode_image(image_path):
    """读取图片文件，返回 base64 编码的字符串"""
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

# 读取你的图片
base64_image = encode_image("example.jpg")

response = client.chat.completions.create(
    model="Qwen/Qwen2-VL-7B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请描述这张图片的内容。"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
                    # data:image/jpeg;base64, 表示这是一张内嵌的 JPEG 图片
                }
            ]
        }
    ],
    max_tokens=512
)

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

# 用 2 张 GPU 跑一个 72B 模型
vllm serve Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 2 \  # 2 张 GPU 并行
  --max-model-len 4096

# 用 4 张 GPU（指定使用哪几张）
CUDA_VISIBLE_DEVICES=0,1,2,3 vllm serve Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 4    # 4 张 GPU 并行

llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    enable_prefix_caching=True,  # 启用前缀缓存
    max_num_seqs=256,            # 最多同时处理 256 个请求
)

# 提高显存利用率（默认 0.9 = 90%，可适当调高到 0.95）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.95

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 128 \             # 最大并发序列数（同时处理多少个请求）
  --max-num-batched-tokens 8192 \  # 最大批处理 token 数（批次大小上限）
  --block-size 16                  # KV 块大小（默认 16 个 token 一块）

# 显存不够时的"救命三连"：
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --quantization awq \          # 1. 量化
  --gpu-memory-utilization 0.8 \ # 2. 降低显存占用率
  --max-model-len 2048          # 3. 缩短上下文长度

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 256 \              # 增加并发数（让流水线更满）
  --max-num-batched-tokens 16384 \  # 增大批处理大小（一次处理更多 token）
  --scheduling-policy fcfs \        # 调度策略（fcfs=先来先服务，priority=优先级）
  --enable-chunked-prefill \        # 启用分块预填充（把大请求切成小块，减少等待）
  --prefill-chunk-size 2048         # 预填充块大小

# vLLM 默认启用 CUDA 图，能显著提升性能
# 只有在调试时才需要禁用它：
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enforce-eager  # 禁用 CUDA 图（调试用，生产环境不建议）

# 延迟优化配置（牺牲部分吞吐量，换取更快的首字响应）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 32 \             # 减少并发数（更少请求排队）
  --max-num-batched-tokens 4096 \ # 减小批处理大小（每批少处理一些）
  --enable-prefix-caching         # 启用前缀缓存（相同开头不重算）

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enable-chunked-prefill \
  --prefill-chunk-size 1024  # 块越小，延迟越低，但吞吐也越低

# 查看可用的模型列表
curl http://localhost:8000/v1/models

# 查看 Prometheus 指标（vLLM 内置了详细的性能指标）
curl http://localhost:8000/metrics

# 常用指标的说明（输出很多，关注这几个）：
# - vllm:num_requests_running  → 正在处理的请求数
# - vllm:num_requests_waiting  → 等待中的请求数（这个持续>0说明超载了）
# - vllm:gpu_cache_usage_perc  → GPU 缓存使用率

import time
from vllm import LLM, SamplingParams

def benchmark(model_name, num_prompts=10):
    """
    简单的性能测试函数，帮你量化 vLLM 的性能
    
    参数：
        model_name: 模型名称
        num_prompts: 测试用的请求数量
    """
    llm = LLM(model=model_name)
    sampling_params = SamplingParams(max_tokens=256, temperature=1.0)
    
    # 生成测试用的 prompts（相同的 prompt，方便对比）
    prompts = ["写一篇关于人工智能的文章。" for _ in range(num_prompts)]
    
    # 预热（第一次加载可能包含冷启动开销，不算在正式成绩里）
    print("🔥 预热中...")
    llm.generate(["预热"], sampling_params)
    print("✅ 预热完成，开始正式测试\n")
    
    # 正式测试
    start_time = time.time()
    outputs = llm.generate(prompts, sampling_params)
    end_time = time.time()
    
    # 统计结果
    total_tokens = sum(len(output.outputs[0].token_ids) for output in outputs)
    elapsed = end_time - start_time
    throughput = total_tokens / elapsed
    
    print(f"📊 测试结果")
    print(f"━━━━━━━━━━━━━━━━━━━━")
    print(f"  模型: {model_name}")
    print(f"  请求数: {num_prompts}")
    print(f"  总生成 token 数: {total_tokens}")
    print(f"  总耗时: {elapsed:.2f}s")
    print(f"  吞吐量: {throughput:.2f} tokens/s")
    print(f"  平均每请求耗时: {elapsed/num_prompts:.2f}s")
    print(f"━━━━━━━━━━━━━━━━━━━━")

# 运行测试
benchmark("Qwen/Qwen2.5-7B-Instruct")

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.92 \
  --max-model-len 4096 \
  --max-num-seqs 64 \
  --max-num-batched-tokens 8192 \
  --api-key your-production-key \
  --served-model-name qwen-7b \
  --host 0.0.0.0 \
  --port 8000 \
  --enable-prefix-caching \
  --trust-remote-code

vllm serve Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 4 \      # 4 张 GPU 并行
  --max-model-len 8192 \          # 支持长上下文
  --gpu-memory-utilization 0.93 \ # 稍高一点的显存利用率
  --max-num-seqs 128 \            # 同时处理 128 个请求
  --max-num-batched-tokens 16384 \ # 大批次吞吐更高
  --api-key your-production-key \
  --served-model-name qwen-72b \
  --host 0.0.0.0 \
  --port 8000 \
  --trust-remote-code \
  --enable-prefix-caching         # 如果 System Prompt 都一样，省很多算力

# docker-compose.yml
version: '3.8'

services:
  vllm:
    # 使用官方镜像，省去环境配置的麻烦
    image: vllm/vllm-openai:latest
    runtime: nvidia                     # 启用 NVIDIA GPU 支持
    ports:
      - "8000:8000"                     # 映射端口
    environment:
      - NVIDIA_VISIBLE_DEVICES=all      # 让容器看到所有 GPU
    volumes:
      # 挂载模型缓存目录，避免每次重启都要重新下载模型
      - ./models:/root/.cache/huggingface/hub
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --host 0.0.0.0
      --port 8000
      --api-key your-api-key
      --served-model-name qwen-7b
      --max-model-len 8192
      --gpu-memory-utilization 0.9
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all                # 分配所有 GPU
              capabilities: [gpu]
    # 自动重启策略：除非手动停止，否则挂了自动重启
    restart: unless-stopped
    # 日志大小限制，防止日志撑爆磁盘
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

# 启动（-d 表示后台运行）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

                    ┌──────────────┐
                    │    Nginx     │  ← 负载均衡器（流量入口）
                    │  (反向代理)   │
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
    ┌───────▼───────┐ ┌───▼────────┐ ┌───▼────────┐
    │  vLLM 节点 1   │ │ vLLM 节点 2 │ │ vLLM 节点 3 │
    │  (A100 x 4)   │ │ (A100 x 4) │ │ (A100 x 4) │
    └───────────────┘ └────────────┘ └────────────┘

# nginx.conf
http {
    # 定义一组后端 vLLM 服务节点
    upstream vllm_backends {
        # 支持加权轮询：server vllm-1:8000 weight=3;
        server vllm-1:8000;
        server vllm-2:8000;
        server vllm-3:8000;
    }

    server {
        listen 80;
        
        location /v1/ {
            proxy_pass http://vllm_backends;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            
            # 流式响应需要：禁用缓冲，否则 SSE 会卡住
            proxy_buffering off;
            proxy_cache off;
            
            # 超时设置（大模型推理可能超过 60 秒）
            proxy_read_timeout 300s;  # 5 分钟超时
            proxy_connect_timeout 30s;
        }
        
        # 健康检查端点
        location /health {
            proxy_pass http://vllm_backends/health;
            access_log off;
        }
    }
}

# 启动 vLLM 服务并暴露指标端口（默认 8000 上就有 /metrics）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000

# 指标端点：http://localhost:8000/metrics

# prometheus.yml
scrape_configs:
  - job_name: 'vllm'
    scrape_interval: 15s              # 每 15 秒采集一次
    static_configs:
      - targets: ['localhost:8000']   # vLLM 服务地址

# 设置 API Key，所有请求必须携带此 Key
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --api-key your-secure-api-key-here

# 调用时需要带 Authorization 头
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer your-secure-api-key-here" \
  -d '{"model":"qwen-7b", "messages":[{"role":"user","content":"Hello"}]}'

# 场景一：仅允许内网访问（最安全）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 127.0.0.1 \    # 只监听本地回环地址
  --port 8000
# 然后通过 Nginx 反代对外暴露，由 Nginx 负责 HTTPS 和认证

# 场景二：配合反向代理实现 HTTPS
# 在 Nginx 层配置 SSL 证书，vLLM 本身不需要处理加密

# 定义限流区域：每个 IP 限速 10 请求/秒
limit_req_zone $binary_remote_addr zone=vllm:10m rate=10r/s;

server {
    location /v1/ {
        # burst=20：允许瞬间突增 20 个请求
        # nodelay：不延迟，超过限制直接返回 503
        limit_req zone=vllm burst=20 nodelay;
        proxy_pass http://vllm_backends;
    }
}

Unsupported platform, please use CUDA, ROCm, or CPU.

# ① 先检查当前 CUDA 版本
nvidia-smi        # 查看 CUDA Version（驱动支持的最高版本）
nvcc --version    # 查看当前使用的 CUDA 版本

# ② 如果 CUDA < 12.1，有两种选择：
# 方案 A：升级 CUDA（推荐）
#    去 NVIDIA 官网下载 CUDA 12.1+
# 方案 B：用 Docker（更省事，不用折腾环境）
docker pull vllm/vllm-openai:latest

fatal error: cblas.h: No such file or directory

# Ubuntu/Debian 系统
sudo apt update
sudo apt install libopenblas-dev

# CentOS/RHEL 系统
sudo dnf install openblas-devel

CUDA out of memory. Tried to allocate 512.00 MiB

# 默认 max-model-len 通常为 8192 或 32768
# 降低到 2048 可以省 50~70% 的 KV 缓存显存
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-model-len 2048

# 换成 AWQ 量化版本，显存直接减半
vllm serve TheBloke/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq

# 默认 0.9（用 90% 显存），降到 0.7 留更多余量
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.7

# 默认 max-num-seqs=256，降到 32 减少 KV 缓存占用
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 32

nvidia-smi
# 关键看：GPU-Util（利用率）和 Memory（显存使用）
# 如果 GPU-Util < 80%，说明 GPU 没吃饱

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 256 \              # 增加并发数
  --max-num-batched-tokens 16384    # 增大批次大小

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

# 减少并发 + 启用分块预填充
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-num-seqs 16 \            # 减少排队人数
  --enable-chunked-prefill \     # 允许小请求插队
  --prefill-chunk-size 1024      # 切得更碎，插队更灵活

Address already in use

# ① 找到谁占用了端口
lsof -i :8000
# 或
netstat -tulpn | grep :8000

# ② 选择：杀掉进程 或 换端口
kill -9 <PID>                                          # 杀掉占用进程
vllm serve Qwen/Qwen2.5-7B-Instruct --port 8001        # 或换个端口

export VLLM_LOGGING_LEVEL=DEBUG
vllm serve Qwen/Qwen2.5-7B-Instruct
# 日志会详细到每个步骤的加载过程

# 有时候下载中断导致模型文件损坏
# 删除缓存，重新下载
rm -rf ~/.cache/huggingface/hub/models--Qwen--Qwen2.5-7B-Instruct

# 重新启动（会自动下载）
vllm serve Qwen/Qwen2.5-7B-Instruct

# ① 最常用：查看 vLLM 的详细运行日志
export VLLM_LOGGING_LEVEL=DEBUG

# ② CUDA 内核调试（如果怀疑 GPU 计算有问题）
# 让 CUDA 操作变成同步的（方便定位出错点，但速度慢很多）
export CUDA_LAUNCH_BLOCKING=1

# ③ 函数调用追踪（会大幅降低性能，仅调试用）
export VLLM_TRACE_FUNCTION=1

export NCCL_DEBUG=TRACE          # 打印 NCCL 通信日志
export NCCL_DEBUG_SUBSYS=ALL     # 打印所有子系统的调试信息
# 然后重新运行 vllm serve，观察 NCCL 相关的输出

llm = LLM(
    model="your-custom-model",     # HuggingFace 上的模型名
    trust_remote_code=True,        # 信任并使用模型自带的加载代码
)

from vllm import ModelRegistry
from vllm.model_executor.models import YourCustomModel

# 把你的模型注册到 vLLM 的模型注册表中
ModelRegistry.register_model("YourCustomModel", YourCustomModel)

# 然后就可以像使用内建模型一样使用了
llm = LLM(model="your-model-path")

# 安装示例
pip install vllm-flash-attn

vLLM     → 吞吐量之王，生产首选（⭐ 本教程的主角）
SGLang   → vLLM 的最强对手，结构化生成更强
Ollama   → 个人使用最方便，下载即用
TGI      → HuggingFace 亲儿子，生态集成好

# 基础命令
vllm serve <model-name>                                    # 启动服务
vllm serve <model-name> --host 0.0.0.0 --port 8000         # 指定端口

# 性能相关
vllm serve <model-name> --tensor-parallel-size 2           # 多卡推理
vllm serve <model-name> --quantization awq                 # 量化
vllm serve <model-name> --enable-prefix-caching            # 前缀缓存
vllm serve <model-name> --enable-chunked-prefill           # 分块预填充

# 高级功能
vllm serve <model-name> --enable-lora                      # 启用 LoRA
vllm serve <model-name> --trust-remote-code                # 自定义模型

# 生产配置
vllm serve <model-name> --api-key your-key                 # 设置 API Key
vllm serve <model-name> --gpu-memory-utilization 0.9      # 显存控制
vllm serve <model-name> --max-model-len 4096               # 上下文长度

本教程 ✅ → 你已经能：
  1. 理解 PagedAttention 原理
  2. 安装和使用 vLLM
  3. 做离线推理和 API 服务
  4. 优化性能、部署生产环境
  5. 遇到问题能自己排查

下一步 🎯 → 可以尝试：
  1. 阅读 vLLM 官方文档深入某个特性
  2. 尝试用 vLLM 部署不同的模型
  3. 搭建完整的推理服务平台（含监控）
  4. 参与 vLLM 开源社区贡献