zero2vllm

📚《从零手搓 vLLM》

从理解大模型如何生成，理解其推理过程中的缓存与调度，到手写算子以及对应的优化手段，让我们更能彻底地理解vLLM。

第一次来 · 快速开始 · 课程大纲 · 特性与优化地图 · 学习路线 · 框架阅读地图 · 当前进度 · 参与贡献

文档导航 · 开发路线 · 更新记录 · 使用许可

课程建设中。 Part 1 的 1.1—1.6 已提供完整正文、CPU 代码、操作命令、练习答案和统一检查入口；另有 INT4 Linear 实验、7 篇专题导读和双后端配置模板。2.1—2.7 的模型构建、真实权重加载、请求生命周期、迭代调度、CPU 张量分页、前缀共享与 HTTP 流式服务已完成 CPU 验证，3.1—3.5 已提供固定版本源码阅读、调度/KV 与执行张量实验、Runner 演进、配置解析及 CPU 静态核验。9.1 已提供含 zero-point 的量化/反量化/重量化、模型 Passport、6 张中文图与 17 个 CPU 案例。9.2 进一步提供非方阵分组 Q/DQ、FP8/FP4 表示、尾组补零与有效位宽计算，含 20 个 CPU 案例和 7 张中文图。9.3 已补充校准协议、Observer、有效 token 预算及权重/层/任务误差对照。9.4 已补充量化误差控制推导、GPTQ 核心参考、缩放/旋转与 STE 实验。第13篇面向工程师，12节规划覆盖P/D性能建模、SLO配比、Mooncake/KV系统、Dynamo与llm-d控制面，以及生产运维验收。全部 135 节已有独立目录；后续引擎功能逐节推进，A100/C500 的 GPU 实验尚待实机验证。

根据已有基础选一个入口，完成后再沿学习路线深入。课程的完整范围保留在后面的 19 篇、135 章大纲中。

首次学习可按现有材料的短路线推进。算法统一在 9.4 量化算法与误差控制，量化主线重点是策略、数据布局、算子实现、内核调优与 vLLM 接入。

完整学习第一篇：Part 1 学习与命令总表，从生成原理走到缓存、性能指标、模型结构和采样正确性。

继续第二篇：2.1 构建最小 PyTorch 模型，在 CPU 上运行两层 Decoder，逐层对齐 RMSNorm、RoPE、Attention 与 SwiGLU。

接着学习 2.2 加载真实模型权重：加载固定版本的 SmolLM2-135M，理解权重布局、GQA、RoPE 和共享参数，在 CPU 上与 Transformers 逐层对齐。

再通过 2.3 请求与缓存生命周期处理完成、取消与异常，观察独立缓存和运行额度如何回收。 随后在 2.4 静态与连续批处理中让调度器选择每轮工作，比较补位、等待与输出间隔。 在 2.5 分页缓存中把物理块池接到 K/V 张量，验证地址映射、因果读取和释放复用。 继续在 2.6 前缀缓存中让请求复用真实 K/V，用冷暖对照、分叉请求与内存压力解释命中、共享和逐出。 在 2.7 HTTP 与流式输出中，从 HTTP 和异步编程基础开始，把引擎接到真实本机服务，检查客户端慢读、断连、超时与错误收尾。

继续阅读 3.1 vLLM 请求旅程与 3.2 调度与 KV 管理：沿固定源码追踪请求，再手算和回放逐轮调度、块分配、共享引用与抢占。随后在 3.3 模型执行与注意力后端把计划变成张量，核对数值和输出归属。继续在 3.4 Runner 演进理解状态组织与图模式，再用 3.5 配置解析追踪最终参数。这些基础部分不依赖 GPU。

其余学习入口见七篇专题导读。导读表示已有材料，目录中的 🧩 不等于完整章节或 GPU 验收完成。

调用模型生成一句话，是理解推理系统的起点。继续往下看，还会遇到许多具体问题：

• 为什么读入一段长文本，与逐个生成 token，表现出不同的性能瓶颈？
• 历史 token 的 K/V 应该怎样保存？并发请求增加时，显存又该如何分配？
• 一个请求提前结束后，新的请求怎样进入正在运行的批次？
• 同一份模型切换到另一种 GPU，哪些逻辑可以共用，哪些算子和依赖需要适配？
• 怎样用正确性检查和性能数据判断一次修改是否有效？

zero2vllm 围绕这些问题组织课程，以 vLLM 为主要源码学习对象。 我们从可手算的小例子开始，逐步实现模型前向、生成循环、KV Cache、调度和服务，再把教学实现与真实推理框架对应起来。

课程采用“问题 → 原理 → 最小实现 → 实验 → 源码对应”的学习方式。各章围绕可以运行、观察或检查的结果组织，进阶部分再讨论性能与平台差异；已交付的内容以各章状态为准。

以下是完整课程的建设目标，已完成内容见当前进度。

• 理解推理过程：串起 Tokenizer、Attention、Prefill、Decode 与逐 token 生成。
• 构建教学引擎：从简单循环走到缓存管理、连续批处理、分页缓存和流式服务。
• 阅读 vLLM 源码：追踪请求入口、调度器、KV 管理、模型执行与注意力后端。
• 系统学习优化策略：APC、FlashAttention、编译与图执行、权重/激活/KV 量化、推测解码和 DBO。
• 掌握分布式设计：TP、PP、DP、EP、CP、PCP、DCP、SP，以及 MoE、KV 传输与分离式部署。
• 认识完整服务能力：多模态、Pooling、LoRA、结构化输出、工具调用、推理输出、权重更新与运维。
• 设计可信的实验：比较输出正确性，测量首响应、生成速度、吞吐与尾延迟。
• 理解跨平台适配：在 CUDA 与 MACA 两条路径中辨认公共逻辑、运行环境和算子差异。
• 学习工程协作：固定实验版本，整理最小复现，阅读补丁并验证改动。

学生与初学者：会写基础 Python，希望理解推理系统如何工作。可以从 CPU 实验开始，沿基础路线学习；矩阵乘法、PyTorch 与 Transformer 的必要知识会在课程中补充。

有基础的工程师：已了解 PyTorch 或模型部署，希望进一步掌握调度、缓存、源码、性能分析和国产 GPU 适配。可以按问题进入相应章节的工程进阶部分。

前置知识：

• 必需：Python 的函数、类、列表和基本调试。
• 建议：了解矩阵运算、神经网络前向计算；进入真实模型章节前熟悉基础 PyTorch。
• 按需学习：CUDA/GPU 编程、C++ 和底层算子，在后端与优化专题中逐步引入。

具体章节顺序、阶段交付物、GPU 条件与交叉章节分工见学习路线。每章共用基础正文，附工程进阶与平台说明；完整技术范围见课程目录。

**现在就能做：**完成 Part 1 六节与 2.1—2.7 CPU 实验，继续运行 INT4 Linear 实验，阅读专题导读、检查逻辑块分配和配置模板。2.2 的真实权重实验不需要 GPU；0.2 的 vLLM 生成体验可后置。

A100 和 C500 是我们首批计划验证的设备。 学生可以只选择一种 GPU 路径；最低显存要求会随具体模型和实验的实测结果公布。

需要 Python 3.11+。在仓库根目录执行，不需要第三方包、模型下载或 GPU：

python -m zero2vllm next-token-demo --output .local/runs/part-01-inference/01-next-token/default.json

从五个教学词项和二维向量开始，逐项观察 Embedding、Q/K/V、因果 Attention、logits 和生成循环。默认输入“我 喜欢”，第一步选中 ID 2；verification.passed 应为 true。权重是为手算设置的，没有训练语言能力。

阅读第一课正文与五道练习，对照实际运行结果。预计 60—90 分钟完成手算、实验和自查。

整篇六节的命令、参数说明和练习见 Part 1 总表。一次运行 28 个案例、全套测试与文档检查：

python -m scripts.experiments.part01

结果保存在 .local/runs/part-01-inference/summary.json 及各案例文件中。性能指标使用标明来源的模拟时间线，容量/Roofline 为假设估算，均不代表 GPU 实测。

下载并解压仓库，或克隆到本地后，在包含 pyproject.toml 的根目录执行。需要 Python 3.11+，无需下载模型或安装第三方包。

python -m zero2vllm demo

这个实验使用固定随机权重的单头 Attention 模型，分别运行“完整重算”和“使用 KV Cache”的生成过程，比较每一步整个词表上的输出分数（logits）。

默认输入 4 个 token，生成 8 个新 token。检查结果：

这是用于学习计算过程的小模型，token ID 没有自然语言含义；投影位置计数也不能直接换算为 GPU 加速倍数。

继续阅读引导实验：KV Cache 前后是否计算一致，或查看已运行的结果。

python -m zero2vllm demo --output .local/runs/part-01-inference/03-kv-cache/cpu-kv-cache.json
python -m unittest discover -s tests -v

试着改变 prompt 或输出长度，先预测重复计算量，再检查结果。

python -m zero2vllm quant-demo --output .local/runs/part-09-quantization/08-bit-packing-serialization-and-repack/cpu-int4-linear.json

实验实现沿 K 分组的 Q/DQ、有符号 INT4 打包及两条量化 Linear 参考路径。默认包含尾组和奇数打包，分别报告实现误差与量化误差，并把 scale 计入存储。详见实验教程；它是 CPU 数学参考，GPU 融合内核与 vLLM 集成待完成。

python -m zero2vllm doctor --output .local/environment/host.json
python -m zero2vllm profile configs/platforms/cuda/a100.toml
python -m zero2vllm profile configs/platforms/maca/c500.toml

这一步用于整理环境信息和检查配置。模板会列出尚未填写的实际版本；配置完整后可预览容器内的启动参数。正式部署步骤随 A100、C500 实机验证补齐，见双后端环境与配置。

本版共 19 篇、135 个正式章节规划，每篇、每节都有独立目录；未完成小节先提供教学骨架，两个 CPU 实验已归入对应篇。目录齐全不表示正文全部完成；前置知识、练习产出、设备条件见详细课程目录。

状态：✅ 已完成并有本地验证；🧩 有部分材料或代码；📋 已规划、正文待编写。 功能已被上游收录也不等于本项目已经实测。

✅ CPU 引导实验：KV Cache 前后是否计算一致

✅ CPU 量化实验：INT4 打包、分组缩放与 Linear

课程按 2026-09-15 查阅的 vLLM 官方功能文档、设计说明与源码注册表扩展。详细的术语、设备条件、组合实验和注册项见完整特性地图；14 组、233 个注册/配置命名条目用于后续检查遗漏，其中包含别名、模型映射与占位项。

Chunked Prefill 也曾被缩写为 CP，但它属于调度策略，单卡即可学习。 PCP/DCP 的合法度数、Q/KV 分布与模型限制见并行策略详解和上游并行配置。

TBO 已纳入对照专题，vLLM 侧使用官方名称 DBO（Dual Batch Overlap）。 课程分别讲 DBO、异步调度、Async TP，以及 SGLang 的 TBO/SBO，避免混用参数。vLLM DBO 设计

• 单卡 A100/C500：先做模型基线，再逐项验证缓存、调度、Attention、编译、量化、推测和服务能力。
• 多卡/多机：TP/PP/DP/EP/PCP/DCP/SP/DBO 与分离式部署都有正式章节、推导和实验设计；真实通信性能需要额外设备。
• 硬件/模型专用功能：FP8/FP4、特定 FlashAttention 代际、稀疏模型与专用 kernel 全部收录，并注明支持条件。
• 功能组合：单独设计 APC×Chunked Prefill、Quant×KV dtype、Graph×Spec、EP×DBO、PD×并行映射等消融实验。

当前新增章节为教学规划，A100/C500 的 GPU 实测状态仍为待验证。完整支持矩阵随固定版本和实机记录逐项建立。

学习 vLLM 时，也可以借助其他项目理解不同层次的设计。下表给出课程计划采用的阅读视角；具体代码以各项目的固定版本为准。

学生先按课程完成自己的小实现，再按章节阅读对应项目；工程师可以围绕同一个问题比较实现。框架介绍和阅读材料的覆盖范围，与本工程已经实测的平台范围分别记录。

公共课程和实验口径共用，运行环境按后端分别管理：

模型、输入、dtype、采样参数和负载方法尽量统一；驱动、镜像、注意力后端与实际版本分别记录。先在每个平台建立正确性和性能基线，再分析两套系统的差异。环境说明 · 实验记录规范

教学引擎先完成可检查的参考实现，再逐步接入优化算子。当前的 CPU 数学实验与逻辑块模拟，是后续 PyTorch 和 GPU 实现的起点。

第一篇已补充讲解、图解和短示例，重点加强 1.4—1.6；见学习入口。

当前代码版本：v0.1.0.dev0。

**接下来：**Review 并试学 3.4—3.5，再进入第四篇，分别建立 A100/CUDA 与 C500/MACA 的环境和小模型基线。量化 GPU 算子与 vLLM 接入按开发路线推进；每阶段以代码、正文和验证记录共同验收。

zero2vllm/
├── docs/
│   ├── chapters/                 19 篇、135 节
│   │   └── part-02-engine/
│   │       └── 01-pytorch-model/
│   │           ├── README.md     正文
│   │           ├── lab.md        实验命令
│   │           ├── exercises.md  练习答案
│   │           ├── examples/     本节示例
│   │           └── results/      已验证结果
│   ├── platforms/                平台说明
│   ├── engineering/              架构与实验规范
│   ├── references/               参考资料入口
│   ├── maintenance/              维护说明和写作模板
│   └── assets/                   共享图片
├── metadata/
│   ├── course/parts/             按篇拆分的中文课程数据
│   ├── translations/en/parts/    对应英文大纲
│   └── upstream/                 功能清单
├── zero2vllm/                    共享 Python 实现
├── tests/{reference,modeling,integration,maintenance}/
├── scripts/{docs,experiments,environment}/
├── configs/{platforms,templates}/
├── reports/{quality,platforms,history}/
└── .local/{runs,checks,archive}/  本地区，不上传

完整目录约定和后续填充方法见目录管理。

代码沿单一源码树演进，后续通过阶段标签对应课程进度。具体模块职责见工程设计。

没有 GPU，能学到哪一步？

现在即可完成 Part 1、2.1 PyTorch、2.2 真实权重加载、2.3 请求生命周期、2.4 调度回放、2.5 张量分页、2.6 前缀共享、2.7 HTTP 流式服务、CPU KV Cache、INT4 打包和 Linear 实验，阅读 7 篇导读，修改逻辑块模拟，并完成调度、切分、通信预算的手算。GPU 内核与实际服务性能需要对应设备验证。

需要先掌握 CUDA，或同时拥有 A100 和 C500 吗？

可以先从 Python 和基础实验开始。GPU 实践选择一条路径即可，底层编程知识在后端和优化章节中按需补充。

“手写 mini-vLLM”与当前代码是什么关系？

它是课程的阶段目标。目前已完成数学参考和部分缓存逻辑，2.1 已交付最小 PyTorch Decoder，2.2 已完成真实权重加载与参考对齐，2.3 已实现同步请求管理和取消回收，2.4 已加入静态/连续准入与三种预算检查，2.5 已连接 CPU 物理块池、KV 张量与 Attention，2.6 已加入跨请求完整前缀共享、引用计数与逐出，2.7 已接入本机 HTTP、SSE、背压和断连取消；真实模型增量 KV、张量批执行与 GPU 服务继续逐节推进。

多卡专题需要我现在就有多张卡吗？

可以先完成张量切分、进程组和通信成本的 CPU 推导/模拟，再阅读源码。真正的通信、DBO、EP 与多机性能需要相应设备；单卡结果不能代替这部分验证。

这里的“完整”如何维护？

以查阅日期对应的官方公开功能和配置为覆盖目标，保留注册表清单和章节映射。模型、后端、插件和组合持续变化，更新时同时记录新增、废弃及平台条件，不把一个大纲描述成永久完整的支持矩阵。

课程会跟随所有框架的最新版本吗？

当前导读注明查阅来源与适用范围。进入完整源码实验和 GPU 验收时再锁定 tag/commit、插件和环境版本；新版本通过独立验证后更新。其他框架也保留各自的版本和实验条件。

可以从一个小问题开始：

• 改进概念解释、公式推导或练习。
• 补充正确性测试，复现并修复缓存和调度问题。
• 提交 A100/C500 的实际环境与实验记录。
• 整理框架源码阅读笔记、性能分析或环境排查过程。

章节采用统一的“基础内容 + 动手实验 + 工程进阶”结构。提交内容应注明运行条件和真实状态；代码改动附相关检查，性能结论附原始数据。

贡献说明 · 章节模板 · 实验记录规范 · 维护者上传说明

课程组织方式受到 Datawhale zero-to-sglang 的启发：让基础理解、逐步实现和真实源码阅读形成连续的学习过程。感谢 vLLM、SGLang、nano-vllm、mini-sglang、Transformers、llama.cpp、TensorRT-LLM 与 MetaX 社区提供的公开源码和技术资料。

本项目的设计与当前代码独立编写。各参考项目的角色与来源见上方阅读地图及参考资料。

If this project helps you, please give it a Star ⭐!

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.