第 1 章：什么是 vLLM

1.1 定义

vLLM是一个开源的大语言模型（LLM）推理和部署引擎，旨在提供高性能、低成本的 LLM 服务解决方案。

1.2 核心价值

传统方案 vLLM 方案
─────────────────────────────
GPU 利用率低 → GPU 利用率高 (<4% 浪费)
响应速度慢 → 吞吐量提升 24 倍
内存浪费严重 → 节省约 50% 显存
成本高昂 → 更低的硬件成本

1.3 应用场景

• 离线批量推理：一次性处理大量文本生成任务

• 在线 API 服务：为多个用户提供实时对话服务

• 边缘设备部署：在有限硬件上运行大模型

• 研究实验：快速验证不同模型的效果

第 2 章：环境准备与安装

2.1 系统要求

2.2 安装方式一：pip（最简单）

# 基础安装 pip install vllm # 指定版本（稳定版推荐） pip install vllm==0.11.2

2.3 安装方式二：uv（更快）

# 先安装 uv（现代 Python 包管理器） pip install uv # 使用 uv 安装 vLLM（速度是 pip 的 10-100 倍） uv pip install vllm

2.4 安装方式三：conda + pip

# 创建 conda 环境 conda create -n vllm_env python=3.10 -y conda activate vllm_env # 安装 vLLM pip install vllm

2.5 Docker 安装（隔离环境推荐）

# 拉取镜像 docker pull vllm/vllm-openai:latest # 运行容器（支持 GPU） docker run --gpus all \ -p 8000:8000 \ -v /path/to/models:/models \ vllm/vllm-openai:latest \ serve vllm/example_model

2.6 验证安装

python -c "import vllm; print(vllm.__version__)" # 应该输出类似：0.11.2

2.7 测试运行

创建一个测试文件test_vllm.py：

from vllm import LLM, SamplingParams print("✅ vLLM 安装成功！")

第 3 章：核心概念解析

3.1 LLM（大语言模型）

LLM = Large Language Model

• 本质：一个能"理解"和"生成"人类语言的神经网络

• 输入：一段文字（Prompt）

• 输出：预测的最可能的后续文字

• 常见模型：Llama 3, Qwen, ChatGLM, Baichuan

3.2 KV Cache 是什么？

问题背景

在 LLM 生成过程中，每个新 token 都需要用到之前所有 token 的计算结果。直接重复计算会导致：

• 极慢的速度

• 巨大的内存浪费

解决方案：缓存

将每一步计算的 Key 和 Value 保存下来，后续直接使用，称为KV Cache。

时间步 t=1: 输入"今天天气真" → 计算 KV → 输出"好" 时间步 t=2: 输入"今天天气真好" → 复用之前的 KV + 新增 KV → 输出"的"

3.3 PagedAttention 技术原理

这是 vLLM 的核心创新技术，灵感来自操作系统管理内存的分页机制。

传统 Attention vs PagedAttention

【传统方法】连续内存分配 ┌──────────────────────────────────────┐ │ [Block 1][未用空间][未用空间... ] ← 浪费 └──────────────────────────────────────┘ 【PagedAttention】分页内存分配 ┌──────────────────────────────────────┐ │ [Page1]──┐ │ │ [Page2]──┼→ PageTable → 逻辑块 A │ │ [Page3]──┘ │ │ │ │ [Page4]──┐ │ │ [Page5]──┼→ PageTable → 逻辑块 B │ └──────────────────────────────────────┘ 非连续物理存储，通过页表映射

关键优势

3.4 Continuous Batching（连续批处理）

问题

传统批处理方式：等待一批中所有请求都完成才能开始下一批

Continuous Batching 解决方式

每个请求独立进行，随时可以加入或离开批次，最大化 GPU 利用率。

时间 → 传统批处理：[█ 批次 1 █] [空闲] [█ 批次 2 █] [空闲] ... Continuous: [█ 批次 1 ███ 批次 2 █] [███████...] （无空闲）

第 4 章：第一个 vLLM 程序

4.1 Hello World 示例

from vllm import LLM, SamplingParams # Step 1: 初始化 LLM 引擎 llm = LLM(model="Qwen/Qwen2.5-0.5B-Instruct") # 小白建议用这个小模型 # Step 2: 设置采样参数 sampling_params = SamplingParams( temperature=0.8, # 创造性：0.0=机械，1.0=随机 top_p=0.95, # 从最可能的前 95% 中选择 max_tokens=100, # 最大生成 token 数 ) # Step 3: 准备输入提示 prompts = [ "你好，请介绍一下你自己", "中国的首都是哪里？", "用一句话形容人工智能的未来" ] # Step 4: 执行推理 outputs = llm.generate(prompts, sampling_params) # Step 5: 打印结果 for output in outputs: prompt = output.prompt generated_text = output.outputs[0].text print(f"用户：{prompt}") print(f"AI:{generated_text}\n") print("=" * 60)

4.2 参数说明

SamplingParams 常用参数

第 5 章：API 详解与实践

5.1 LLM 类（高级 API，推荐使用）

适合：快速开发、简单场景

from vllm import LLM, SamplingParams # 初始化 llm = LLM( model="meta-llama/Llama-2-7b-hf", # 模型名称或路径 tensor_parallel_size=1, # 多 GPU 时设置 >1 gpu_memory_utilization=0.9, # GPU 显存使用比例 max_model_len=4096 # 上下文长度 ) # 生成 outputs = llm.generate( prompts=["Hello"], sampling_params=SamplingParams(temperature=0.8) ) # 关闭 llm.shutdown()

5.2 AsyncLLMEngine（异步 API，生产推荐）

适合：高并发、需要流式输出的场景

import asyncio from vllm import SamplingParams from vllm.engine.async_llm_engine import AsyncLLMEngine async def main(): # 初始化异步引擎 engine = AsyncLLMEngine.from_model_config( model_config="meta-llama/Llama-2-7b-hf" ) sampling_params = SamplingParams(temperature=0.8) async for output in engine.generate( {"prompt": "Hello"}, sampling_params=sampling_params, request_id="request-1" ): print(output.outputs[0].text) await engine.end_request(request_id="request-1") await engine.shutdown() # 运行 asyncio.run(main())

5.3 流式输出

from vllm import LLM, SamplingParams llm = LLM(model="Qwen/Qwen2.5-0.5B-Instruct") params = SamplingParams( temperature=0.8, max_tokens=50, stream=True, # 启用流式输出 stream_options={"include_start_code": False} ) outputs = llm.generate("请讲一段话", params) # 查看生成的片段 for token in outputs[0].outputs[0].tokens: print(token.text, end="", flush=True)

第 6 章：OpenAI API 兼容服务

6.1 启动服务器

# 本地运行（默认端口 8000） python -m vllm.entrypoints.api_server \ --model Qwen/Qwen2.5-0.5B-Instruct \ --port 8000 # 后台运行 nohup python -m vllm.entrypoints.api_server \ --model Qwen/Qwen2.5-0.5B-Instruct \ --host 0.0.0.0 \ --port 8000 > server.log 2>&1 &

6.2 使用 OpenAI SDK 调用

from openai import OpenAI # 配置客户端 client = OpenAI( base_url="http://localhost:8000/v1", api_key="not-needed" # vLLM 不需要真正的密钥 ) # 调用 response = client.chat.completions.create( model="Qwen/Qwen2.5-0.5B-Instruct", messages=[ {"role": "user", "content": "请用英文介绍 Python"} ], temperature=0.7, max_tokens=200 ) print(response.choices[0].message.content)

6.3 Stream 模式

with client.chat.completions.create( model="Qwen/Qwen2.5-0.5B-Instruct", messages=[{"role": "user", "content": "写一首诗"}], stream=True, ) as stream: for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)

第 7 章：性能优化

7.1 GPU 资源调优

llm = LLM( model="your-model", gpu_memory_utilization=0.95, # 提高显存使用率 max_num_batched_tokens=8192, # 每批最大 token max_num_seqs=256, # 每批最大序列数 swap_space=16, # CPU 交换空间（GB） )

7.2 批处理大小选择

7.3 监控工具

# 添加日志 llm = LLM( model="...", enforce_eager=False, # 使用编译加速 disable_log_stats=False, # 开启性能统计 ) # 观察控制台输出的性能指标 # tokens/s, throughput, GPU memory usage 等

附录 A：常见问题排查

Q1: 安装失败

# 检查 CUDA 版本 nvcc --version # 确保 Python >= 3.8 python --version # 清理缓存重装 pip cache purge pip install vllm --no-cache-dir

Q2: 显存不足

llm = LLM( gpu_memory_utilization=0.7, # 降低使用比例 max_model_len=2048, # 减少上下文长度 )

Q3: 找不到模型

# 自动下载 python script.py # 第一次运行会自动下载 # 或手动下载后指定路径 llm = LLM(model="./local/path/to/model")

附录 B：参考资源

官方文档

中文资源

• vLLM 中文站：https://vllm.hyper.ai/

• 知乎教程：https://zhuanlan.zhihu.com/p/691038809

视频资源

• YouTube: A Beginner's Guide to Understanding and Using vLLM

• Bilibili: vLLM 实战教程

🎓 下一步学习建议

1. ✅ 完成本文档的所有代码示例

2. 📚 阅读 vLLM 官方设计文档（PagedAttention）

3. 💻 实践一个完整项目（如聊天机器人、文章生成器）

4. 🔧 尝试修改配置参数观察性能变化

5. 🤝 参与社区讨论和问题解答