仓库地址：https://github.com/hhk-png/cycle-agent
00 前言与导读
本章目标：说明这本教程要解决什么问题、适合谁读、按什么顺序读，以及如何亲手运行配套的 mini-vLLM 代码把原理变成可执行的代码。
1. 为什么写这本教程
vLLM 是目前最流行的开源 LLM 推理与 serving 引擎，但它也是一个相当复杂的系统：分页 KV cache、连续批处理、投机解码、量化、多卡并行、OpenAI 兼容服务......如果只把它当成一个"黑盒"来调用，遇到问题会无从下手。
这本教程的目标有两个，且缺一不可：
- 读懂原理：把 vLLM 的核心机制讲透------它为什么快、内存如何管理、调度器在做什么、服务架构长什么样。
- 亲手实现 ：配套一个自包含、可运行、纯 NumPy 实现的 mini-vLLM，把论文和源码里最难懂的部分（PagedAttention、调度器、前缀缓存、抢占、投机解码）用几百行可读代码复刻出来。
一句话概括："原理 + 代码"双线并行。 看懂 vLLM 不是靠背 API，而是能自己把核心机制重新造一遍。
2. 你将学到什么
读完这本教程，你应该能回答以下问题：
- PagedAttention：KV cache 为什么会产生内存碎片？分块 + 块表（block table）如何消灭碎片？和操作系统的分页有什么区别？
- Continuous batching：为什么静态批处理浪费 GPU？iteration-level 调度如何让 GPU 时刻满载？
- KV cache 管理：前缀缓存、copy-on-write、recompute 抢占、chunked prefill 各解决什么问题？
- 采样与解码参数：temperature / top-k / top-p / 惩罚项 / beam search / 引导解码各改了什么？如何调出想要的行为？（第 05 章）
- 服务架构 ：
LLMEngine/AsyncLLMEngine/ 调度器 / Worker 之间如何协作？OpenAI 兼容 server 如何把 HTTP 请求变成引擎 step？ - 量化：weight-only 量化的原理，vLLM 的 GPTQ / AWQ / FP8 支持。
- 投机解码：draft + verify 为何能"无损"加速？EAGLE、Medusa 等方案怎么提升接受率？
- 部署：多卡并行（张量并行 / 流水并行）、显存调优、指标监控、生产上线。
- 未来方向：PD 分离、MLA、MoE、长上下文等正在发生的变化（详见《12-未来方向.md》）。
3. 阅读前置要求
| 知识 | 要求 | 说明 |
|---|---|---|
| Transformer / LLM 基础 | 必须 | 知道 attention、自回归解码、KV cache 是什么 |
| Python | 必须 | 能读懂类、装饰器、生成器、asyncio 基本用法 |
| NumPy | 建议 | 本教程代码用纯 NumPy，熟悉 np.einsum、广播即可 |
| PyTorch | 建议 | 知道 nn.Module、.state_dict()，便于对照 vLLM 源码 |
| CUDA | 可选 | 不写 CUDA 内核也能读懂；了解即可提升源码阅读体验 |
如果你完全不懂 Transformer，建议先花半天过一遍 Transformer 的基本结构（embedding、多头注意力、前馈网络、LayerNorm）再回来。
4. 章节地图
| 章 | 标题 | 一句话摘要 |
|---|---|---|
| 00 | 前言与导读 | 教程目标、阅读方法、配套代码怎么跑（本章） |
| 01 | 认识 vLLM | vLLM 是什么、解决什么问题、与其它框架对比 |
| 02 | 核心原理 | prefill/decode、KV cache、PagedAttention、连续批处理、前缀缓存、抢占、投机解码、量化 |
| 03 | 架构设计 | LLMEngine、Scheduler、BlockManager、ModelRunner、并行执行、数据流 |
| 04 | 快速上手 | 安装、LLM 离线推理、vllm serve 在线服务、OpenAI API |
| 05 | 采样与解码参数 | 温度/top-k/top-p、惩罚项、beam search、logprobs、引导解码/结构化输出 |
| 06 | 从零实现 mini-vLLM | 用纯 NumPy 复刻核心机制，逐模块精读配套代码 |
| 07 | 调度与连续批处理 | 迭代级调度、token 预算、分块 prefill、抢占与状态机 |
| 08 | 性能优化 | PagedAttention kernel、CUDA graphs、显存调参、并行策略、benchmark |
| 09 | 量化 | weight-only vs W8A8、GPTQ / AWQ / FP8 / GGUF、KV cache 量化 |
| 10 | 生产部署 | OpenAI 兼容服务、Docker、Kubernetes、可观测性、结构化输出、多 GPU |
| 11 | 生态与集成 | HF 生态、OpenAI SDK、LangChain/LlamaIndex、Ray、自定义模型接入 |
| 12 | 未来方向 | PD 分离、MoE 优化、注意力架构演进、长上下文 |
| 13 | 常见问题与 FAQ | 安装、加载、显存、性能、服务的速查手册 |
| 14 | 分布式推理与多卡部署 | TP/PP/EP/DP 原理与通信代价、Ray 集群、多机部署、并行策略选型 |
| 15 | 多模态与 LoRA 推理 | 视觉语言模型的多模态输入、LoRA 适配器推理 |
| 16 | 附录 A：环境变量与参数参考 | 环境变量、CLI 参数按主题分组速查，EngineArgs ↔ 配置对象映射 |
| 17 | 附录 B：内存估算与容量规划 | 显存三大部分、KV 预算公式、从目标并发反推参数的完整实例 |
| 18 | 附录 C：mini-vLLM 完整工程参考 | 完整 API 参考、关键数据约定、验证矩阵、9 个练习（含 1 个热身）、调试指南 |
| 19 | 模型架构基础 | MHA/MQA/GQA/MLA、RoPE/ALiBi、RMSNorm/SwiGLU、MoE，vLLM 支持的架构速查 |
| 20 | 端到端部署案例 | 从零把一个模型跑成生产服务：选型→容量规划→部署→接入→压测→监控 |
| 21 | 附录 D：性能基准测试与调优指南 | 压测方法论：指标定义、工具链、负载设计、结果解读与调优循环 |
| 22 | 附录 E：术语表 | 全教程关键词速查：十个主题分组 + 拼音/字母索引，随手定位术语与章节 |
第 06 章是全书"动手"的高潮：它会带着你逐行阅读
mini-vllm/下的源码，并把每个模块映射回 vLLM 的真实文件。第 14、15 章是两个"进阶专题"（分布式并行、多模态与 LoRA），按需选读；第 16、17、18、21、22 章是五份"参考手册" （参数 / 显存 / 工程 / 压测 / 术语），适合在实操时按需翻阅，不需要顺序精读。其中第 18 章（附录 C）是 mini-vLLM 的"工程手册"------想让实现"会改、能扩展"，读它；第 21 章（附录 D）是"压测手册"------想给服务建立一套可复现的基准测试与调优流程，读它；第 22 章（附录 E）是"术语手册"------被陌生词绕晕时随手查它。
第 19 章（模型架构基础）与第 20 章（端到端部署案例）是本教程的"纵深补充"：前者把 MHA/GQA/MLA、RoPE、MoE 等决定 KV cache 与内核的架构知识讲透，后者给出一条可以照做的完整部署路线。读完主干之后，这两章分别回答"模型为什么是这样"与"怎么把它跑成产品"。
4.1 教程内容全景图
把整本教程放在一张图上，主线是 原理 → 实现 → 工程 → 生态 → 未来 → 参考：
① 原理地基 00 导读 → 01 认识 vLLM → 02 核心原理 → 03 架构设计
│
② 亲手实现 04 快速上手 → 05 采样与解码参数 → 06 从零实现 mini-vLLM → 07 调度与连续批处理
（mini-vLLM） │ │
▼ ▼
③ 工程纵深 08 性能优化 → 09 量化 → 10 生产部署 ──────────► 20 端到端部署案例
│
④ 生态与前沿 11 生态与集成 → 12 未来方向 → 13 常见问题 FAQ
│
⑤ 进阶专题 14 分布式多卡 / 15 多模态与 LoRA / 19 模型架构基础
│
⑥ 参考手册 16 附录A 参数 / 17 附录B 显存 / 18 附录C 工程 / 21 附录D 压测 / 22 附录E 术语读图要点：
- ①② 是主干：必须读。02 讲机制、06 把机制变成可跑代码。
- ③ 是工程纵深：想让部署有谱，至少过一遍 08 与 20。
- ④⑤ 按需：生态集成（11）、未来方向（12）、进阶专题（14/15/19）互不依赖。
- ⑥ 是字典：遇到具体问题再翻，不必顺序读。21 章（附录 D）放在这里，因为压测是为"性能调优"服务的，需要在 08 章之后读效果最好。
4.2 本教程如何覆盖"现状与未来"
vLLM 是快速演进的项目，教程刻意把"现在能跑的东西"和"正在发生的变化"分开讲，避免把临时的实现细节当成长久标准：
| 层次 | 教程内容 | 对应章节 |
|---|---|---|
| 当下的真实实现（mini-vLLM） | 纯 NumPy 复刻的骨干机制：分页 KV、连续批处理、前缀缓存、抢占、投机解码、int8 量化 | 第 06 章逐行精读 + 第 18 章附录 C 工程手册 |
| 当前 vLLM 的真实功能 | V0/V1 引擎、调度器、OpenAI 兼容服务、量化、TP/PP/EP、多模态、LoRA、引导解码 | 第 01--11 章（以 2024--2025 年稳定特性为主线） |
| 未来方向（演进中） | PD 分离、MLA、MoE 优化、长上下文、更强的投机方案 | 第 12 章 + 第 19 章架构基础 |
一句话：mini-vLLM 是"原理的骨架"，真实 vLLM 是"完整的血肉"，第 12 章是"看它往哪长"。 三者对照阅读，既不会被细节淹没，也不会把过时行为当成现状。
5. 如何使用本教程
5.0 按目标选路线：四条学习路径
这本教程信息量很大，按你的目标选一条主线最有效率：
| 路线 | 目标 | 必读章节 | 怎么走 |
|---|---|---|---|
| 🧭 原理路线 | 真正理解 vLLM 为什么快 | 00 → 01 → 02 → 03 → 07 → 12 | 第 2 章是地基；第 7 章讲吞吐的灵魂；第 12 章看趋势 |
| 🛠️ 工程路线 | 看懂 / 改写 serving 引擎代码 | 00 → 02 → 03 → 06 → 18 | 第 6 章逐行读 mini-vLLM，然后立刻做第 18 章附录 C 的扩展练习 0--3 |
| 🚀 实战路线 | 快速部署到生产 | 00 → 04 → 05 → 08 → 10 → 13 → 16 → 17 → 20 | 先第 4 章跑起来；遇到问题翻第 13 章 FAQ 和 16/17 章两个附录；最后用第 20 章跑一遍完整部署 |
| 🎯 进阶路线 | 跑多卡 / 多模态 / 量化 | 09 → 14 → 15（配合 05、19） | 按需选读，不必按顺序；第 14、15 章是独立专题，架构基础见第 19 章 |
新手如果拿不准，走原理路线 ，它能给你最稳的地基；想动手改代码，随时跳到工程路线。
5.1 顺序阅读（推荐）
如果你是从零开始的读者，按 00 → 01 → 02 → ... → 13 的顺序读：前四章建立理论，05 章掌握采样与解码参数，06 章动手实现，07--10 章看工程细节，11--13 章看生态、前沿与实战；14、15 两章是进阶专题（分布式并行、多模态与 LoRA），16、17、18、21、22 五章是参考手册（参数、容量、mini-vLLM 工程手册、压测、术语）在实操时按需查阅，19 章（模型架构基础）在遇到架构术语时查阅，20 章（端到端部署案例）在准备上线时作为完整范本照做。
5.2 跳读
如果你已经有 vLLM 使用经验，可以：
- 直接读 06 章，对照代码看实现；
- 想调好生成质量，读 05 章采样与解码参数；
- 遇到具体报错，直接翻 13 章 FAQ；
- 查环境变量 / CLI 参数，翻 16 章附录 A；
- 算显存 / 规划并发，翻 17 章附录 B；
- 想弄懂模型架构（GQA/MLA/RoPE/MoE），读 19 章模型架构基础；
- 想完整部署一个真实服务，照 20 章端到端部署案例做一遍；
- 想了解趋势，读 12 章未来方向；
- 想上多卡 / 多机，读 14 章分布式推理与多卡部署；
- 想跑多模态 / LoRA，读 15 章多模态与 LoRA 推理；
- 想给 mini-vLLM 加特性 / 查它完整 API / 做扩展练习，翻 18 章附录 C；
- 想系统化地压测 / 调优一个服务的性能，读 21 章附录 D 性能基准测试与调优指南（先读完 08 章效果更佳）；
- 被术语绕晕 / 想快速复习，翻 22 章附录 E 术语表------每个词条都标注了对应章节，是阅读时的"随身词典"。
5.3 一边读一边跑代码
原理文字难免抽象，强烈建议边读边跑。所有代码位于：
vllm-toturial/
00-前言与导读.md 01-认识vLLM.md ... 13-常见问题与FAQ.md
mini-vllm/ # 可运行的迷你实现
minivllm/ # Python 包（engine / scheduler / kv_cache / api_server...）
scripts/train.py # 训练 tiny GPT 并保存 checkpoint
tests/ # 单元测试（engine / paged-attention / server）
artifacts/tinygpt/ # 训练产物（config.json / model.npz / tokenizer.json）先安装依赖并进入目录：
bash
git clone git@github.com:hhk-png/cycle-agent.git # 或直接进入已有的 vllm-toturial/
cd vllm-toturial/mini-vllm
pip install numpy fastapi uvicorn httpx pytest # 或 pip install -e .[test]（见 pyproject.toml）依赖极简：运行时只需
numpy、fastapi、uvicorn，测试还需httpx、pytest；无需 CUDA、无需 PyTorch，普通 CPU 笔记本即可跑通（Python ≥3.10 即可，教程撰写环境为 Python 3.14 + NumPy 2.x）。
依次运行：
bash
# 1) 训练一个小型 GPT 模型（纯 NumPy，约 6 分钟），输出到 artifacts/tinygpt/
python scripts/train.py --steps 400 --embd 96 --layers 3 --out artifacts/tinygpt
# （省略参数会产出更小的模型，几十秒即可完成）
# 2) 运行端到端测试，验证引擎正确性（确定性、批处理等价、chunked prefill、前缀缓存、抢占）
python tests/test_engine.py
# 3) 启动 OpenAI 兼容服务
python -m minivllm serve --model artifacts/tinygpt --port 8000
# 另开一个终端测试：
curl http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{"prompt":"vLLM is","max_tokens":32}'其它可玩命令：
bash
python -m minivllm chat --model artifacts/tinygpt # 交互聊天
python -m minivllm demo --model artifacts/tinygpt # 连续批处理演示（打印每一步）
python -m minivllm spec --model artifacts/tinygpt # 投机解码演示（打印接受率）
python -m minivllm quant --model artifacts/tinygpt # int8 权重量化前后对比6. 配套代码：mini-vLLM 是什么
mini-vllm/ 是一份自包含、可运行、纯 NumPy 写的 vLLM 迷你复刻（约 3000 行，含测试）。它不是玩具：它真正实现了 vLLM 的骨干机制，只是把 GPU 内核换成了可读的 NumPy 数组运算：
| mini-vllm 文件 | 对应 vLLM 真实模块 | 内容 |
|---|---|---|
minivllm/kv_cache.py |
vllm/core/block_manager_v1.py + vllm/worker/model_runner.py |
分页 KV store、块分配器、前缀缓存、块表、copy-on-write |
minivllm/scheduler.py |
vllm/core/scheduler.py |
连续批处理、chunked prefill、recompute 抢占 |
minivllm/attention.py |
vllm/attention/ops/paged_attn.py |
纯 NumPy 版 PagedAttention |
minivllm/engine.py |
vllm/engine/llm_engine.py |
引擎主循环：add_request / step / generate |
minivllm/api_server.py |
vllm/entrypoints/openai/api_server.py |
FastAPI + /v1/completions、/v1/chat/completions |
minivllm/speculative.py |
vllm/spec_decode/ |
投机解码（bigram draft + target verify） |
minivllm/quantize.py |
vllm/model_executor/layers/quantization/ |
int8 weight-only 量化 |
这份代码本身就是教材的一部分：第 06 章会带着你逐行读它 ，每份文件都有详尽的中文注释和与真实 vLLM 的对照说明。读完第 06 章后，第 18 章（附录 C）提供完整 API 参考、关键数据约定、验证矩阵与 9 个由浅入深的练习（含 1 个热身）------它是把"读懂"升级为"会改"的工程手册。
7. 学习建议与约定
- 先跑起来，再深挖 ：能跑通
python scripts/train.py和python tests/test_engine.py后，你对该系统就有"手感"了。 - 善用测试 ：
tests/test_*.py既是回归测试也是文档------test_chunked_prefill_matches_full验证"分块 prefill 不改变输出"，test_paged_attention把分页注意力与稠密注意力对拍。 - 对照真实源码：每个 mini-vllm 模块顶部都标注了对应的 vLLM 真实路径，读 mini 版时遇到疑问就翻真实源码。
- 示例命令 统一在
mini-vllm/目录下执行；教程中的路径均为相对vllm-toturial/或mini-vllm/的相对路径；版本以 vLLM 2024--2025 年稳定特性为主线。
8. 小结
- 本教程 = 原理 + 动手，配套一份可运行的纯 NumPy mini-vLLM。
- 核心议题：PagedAttention、连续批处理、KV cache 管理、OpenAI 兼容服务、量化、投机解码、部署、未来方向。
- 前置要求：Transformer 基础 + Python + 一点 NumPy/PyTorch；CUDA 可选。
- 打开第一章的姿势：先
python scripts/train.py和python tests/test_engine.py把代码跑起来，再按章节顺序读。
准备好了就开始：下一章《01-认识vLLM.md》带你认识这个引擎本身。