作者：Hawk Wu · 联系邮箱：hawk.wu525@gmail.com
面向初中级程序员和软件工程类学生，具备 Python 基础即可，不要求具备大模型系统背景，系统讲解 vLLM V1 的 核心架构、源码调用链和性能优化机制。
本书不采用逐文件翻译的方式。每章都从一个可观察的问题出发，依次经过直觉模型、 最小实现、系统位置、真实源码、运行实验和设计取舍，最终让读者能够独立定位和 分析 vLLM 的新功能。
- 上游仓库：
vllm-project/vllm - 分支：
main - Commit：
5893426b88f7b3cd21101d194eb1c6f0a6f0e27b - 基线日期：2026-09-07
- 文档状态：第 01 至 10 章已有正文、图解、11 个教学程序和实验模板，均保持
draft - 最近文档复核：2026-10-08；修正抢占、采样、显存估算、UVA、并行回复与 Pareto 解释， 同步检查实验记录、网页说明与 EPUB。见本轮问题与验证记录。
- 首次逐章检查记录与再次复核记录：问题、证据、验证结果及未运行范围。
正式章节必须绑定自己的源码 commit。上游更新后，不得假设旧结论仍然有效。
| 章 | 标题 | 目标篇幅 | 状态 |
|---|---|---|---|
| 01 | 从 Transformer 到大模型推理 | 50 页 | draft |
| 02 | vLLM 全景与一次请求的生命周期 | 45 页 | draft |
| 03 | Engine 与 EngineCore | 45 页 | draft |
| 04 | Scheduler 与 Continuous Batching | 65 页 | draft |
| 05 | KV Cache 内存管理 | 75 页 | draft |
| 06 | PagedAttention 与 Attention Backend | 65 页 | draft |
| 07 | Executor、Worker 与 Model Runner | 60 页 | draft |
| 08 | 异步执行、torch.compile 与 CUDA Graph | 45 页 | draft |
| 09 | 分布式与多 GPU 推理 | 60 页 | draft |
| 10 | 实验、性能分析与优化 | 50 页 | draft |
draft 表示章节正文、图解和无 GPU 实验已经形成，但真实 NVIDIA GPU 动态验证或独立
人工复核仍待完成；outline 表示源码入口已建立，正文尚在扩写。
项目首页已提供一套可直接发布的静态展示页：https://cluster1900.github.io/vllm_reader/。
页面源码位于 docs/，不依赖构建工具；在 GitHub 仓库的 Settings → Pages 中将
Source 设为 Deploy from a branch，选择 main 和 /docs 目录即可发布。首页包含封面、
主调用链、十章目录、阅读路线、源码证据说明和作者信息；章节正文仍以仓库 Markdown 为唯一维护源。
项目将 Mermaid 图和 LaTeX 公式渲染为自包含 SVG，再由 Pandoc 生成 EPUB3：
pnpm install --frozen-lockfile
python3 scripts/build_epub.py构建还需要 Python 3、Pandoc、Node.js，以及 epub/puppeteer-config.json 中指定的浏览器。
默认浏览器路径适用于 macOS 上的 Google Chrome；在其他机器上需改为本机可执行文件路径。
封面使用 epub/cover-imagegen.png，由 imagegen 生成并作为 EPUB3 封面图片嵌入。
默认产物为 dist/vllm-source-guide.epub。构建结束时会自动运行
scripts/check_epub.py，检查 EPUB 容器、封面、目录和链接，并与 Markdown 逐项比对正文、表格、代码、图示与公式。
全书还使用 scripts/enrich_pedagogy.py 维护教学提示。每章都包含针对目标读者的阅读
方法，每张 Mermaid 图后都有读图说明；scripts/check_book.py 会检查这些内容没有遗漏。
目标总篇幅约 560 页。页数是控制内容比例的估算，不是完成标准。
EPUB 的正文来源为 阅读指南、10 个章节和术语表。 阅读指南不再硬编码在构建脚本中；仓库链接保留原文字，指向固定提交的 GitHub 页面， 书内链接则指向对应章节。校验器检查顺序与内容，不能只靠段落数或字数判断一致。
行内公式使用 $...$，块公式使用独立行 $$，需要支持数学扩展的 Markdown 预览器。
EPUB 已嵌入排版完成的 SVG 公式，不依赖 MathML 或在线脚本。
详细规则见 公式写作与构建约定。
- 快速建立主干： 01 -> 02 -> 03 -> 04 -> 05 -> 06（先读寻址与元数据）-> 07 -> 10（先读指标与实验方法）。
- 深入 GPU 执行： 主干完成后阅读 06 -> 08。
- 进入生产部署： 主干完成后阅读 09 -> 10。
- 源码贡献准备： 全部章节，并完成每章的源码追踪题和实验。
详细的章节依赖、写作契约和验收标准见 全书写作蓝图。
- AGENTS.md：人类与 AI agent 的源码研究和写作规范。
- 全书写作蓝图：章节关系、统一结构和阅读路线。
- 写作路线图：各章进度和里程碑。
- 源码版本记录：所有研究基线。
- 章节源码映射：十章与当前实现的关键符号对应关系。
- 术语表：跨章节统一使用的术语定义。
python3 scripts/check_book.py该命令检查十章文件、frontmatter、内部链接、Markdown 代码围栏，以及
meta/chapter-source-map.json 中的源码路径、关键符号和上游 commit；函数与类引用通过 AST 核对完整定义。它不替代对
控制流、边界条件和实验结果的人工复核。