最近一个月，知乎上有个现象挺有意思：vLLM 的源码解析，突然变成了一场连载潮。
就在昨天（8月13日），一天之内又冒出两篇新的——一篇把 V1 调度器的调度流程从头梳理了一遍，一篇讲 KV Cache 从 Tensor 到 Block 的完整入门。往前倒一个月，《从源码读懂 vLLM》《vLLM 解析》《vLLM 源码详解》《vllm v1 源码精读》好几个系列在同时更新，B站连"15分钟理解 vLLM"这种入门视频都冲上了几百收藏。
对想读源码的人来说，表面看是好事：资料从来没这么全过。但我把这一波连载逐个翻了一遍之后，发现一个不太显眼的坑——
这些系列讲的，可能根本不是同一个版本的代码。
今天这篇，就把这波连载潮整理成一张地图：谁在写、写的是哪个版本、适合谁、从哪条路线读起。准备入坑读 vLLM 源码的，建议先收藏再看。
先看这波潮有多密
把最近一个月（7月中旬到8月13日）知乎上能搜到的 vLLM 源码向内容捋一遍，大致是这个密度：
连载系列至少5个：
《从源码读懂 vLLM》系列：顺着"一个请求的端到端旅程"走读源码，已经更到第三篇（手写可验证的 FlashAttention），第一篇7月13日发布，目前32赞74收藏
《vLLM 解析》系列：从 LLM 推理基础讲到 MoE、MLA、混合架构，再到 KV Cache 分页与块池，8月份连更三篇
《vLLM 源码详解》系列：三篇连发，覆盖 KV Cache 内存管理、调度器与 Worker、PagedAttention CUDA 内核
《vllm v1 源码精读》系列：KV Cache 管理、Chunked Prefill、异步架构、投机解码，所有代码标注文件路径和行号
《vLLM 学习》笔记类：Disaggregated Prefill、Rerank 客户端这种功能点拆解
单篇深度文还有一批： V1 Scheduler 调度流程梳理、分布式并行与通信全景（19赞）、从 Custom AllReduce 理解多卡通信与拓扑优化（110赞）。
入门总览也有： 8月13日刚发的《算法同学学 LLM Infra 系列(1) 一口气看懂 vLLM》，一天拿了33赞79收藏。知乎 更早的《LLM Infra 学习资料整理-推理》238赞，一直在更新。
连知乎上都出现了"从推理引擎源码学习的角度，建议从 vllm 还是 sglang 入手？"这种问题——说明想读源码的人已经多到开始纠结路线了。
这波潮不是偶然。vLLM 的 V1 架构重写基本稳定下来，官方去年也发了 Anatomy of vLLM 解剖文。vLLM官方博客 加上这一年算法岗往 Infra 转型的人变多，"读懂推理引擎"从少数人的需求变成了刚需。
真正的坑：版本基线五花八门
资料多是好事，但读源码的资料有个特殊属性：它和代码版本强绑定。vLLM 恰好是迭代最快的开源项目之一，几个月一个样。我把各系列的版本基线挨个核了一遍，情况是这样的：
系列/文章 | 版本基线 | 备注 |
|---|---|---|
《从源码读懂 vLLM》 | v0.22.0（V1架构） | 文内明确声明，代码标注位置 |
《vLLM 源码详解》 | v0.2.0 | 对照的是 2023 年论文时代的代码 |
《vllm v1 源码精读》 | 固定 commit ba22152 | 行号完全可复现 |
《V1 Scheduler 调度流程梳理》 | v0.24.0 | 昨天刚发 |
《vLLM 分布式并行与通信全景》 | v0.26.0 | 作者自己吐槽"vLLM 变化实在太快" |
《一口气看懂 vLLM》 | 不绑定版本 | 基于官方博客 anatomy 文，讲架构骨架 |
看到问题了吗？从 v0.2.0 到 v0.26.0，横跨了两个大时代。知乎专栏
这不是小事。v0.2.0 是 2023 年 PagedAttention 论文刚发表时的代码，那个年代的 vLLM（现在大家叫它 V0 架构）里，核心概念是 SequenceGroup、BlockSpaceManager、Copy-on-Write 这一套；而现在的 V1 架构里，KV Cache 的入口已经变成了 vllm/v1/core/ 下的 block_pool 这套东西，调度器也整个重写过。
也就是说：如果你跟着《vLLM 源码详解》系列学完，满脑子 BlockSpaceManager，然后打开现在 pip 装下来的 vLLM 想对照——会对不上。不是你没读懂，是那套代码结构已经退役了。
我特意核了一下：8月13日新发的 KV Cache 机制详解，源码入口写的就是 vllm/v1/core/block_pool.py；而《vLLM 源码详解》讲的还是 BlockSpaceManager 的物理映射和 CoW fork 共享。同一个主题"KV Cache 管理"，两篇文章讲的是两代实现。知乎
《vLLM 源码详解》的作者其实很坦诚，开篇就标了"本文源码基于 v0.2.0"，而且这个系列的价值在于贴着原论文讲设计思想，质量不差。问题不在作者，在于读者如果没注意到版本基线这行小字，很容易把"论文时代的实现"当成"现在的实现"。
顺带说一句：这也解释了为什么《vllm v1 源码精读》的作者要把代码固定到某个 commit——源码解析文里写的行号，上游一次合并就全漂移了，固定 commit 是唯一能保证"读者能复现"的办法。知乎专栏 这个方法论，值得每个准备自己写笔记的人抄。
三条路线，看你读源码是想干嘛
版本坑说清楚了，下面是路线。我的建议是按"你读源码的目的"来选，而不是按"哪个系列火"来选。
路线一：算法同学想建立整体认知，不打算改代码
适合：平时主要调模型、被 CUDA OOM 折磨过、想搞懂推理引擎黑盒里发生了什么的人。
顺序：先看 vLLM 官方博客的 Anatomy of vLLM 解剖文（中文社区大部分总览文都引用它），或者知乎那篇《一口气看懂 vLLM》，半小时建立"AsyncLLM → EngineCore → Scheduler/ModelRunner/Worker"的骨架认知；然后用《从源码读懂 vLLM》系列一当主线，它基于 v0.22.0 但走的是 V1 架构，"一个请求的端到端旅程"这个视角对建立直觉最友好。
这条路线不追求行号精确，追求"知道每个组件干嘛、边界在哪"。
路线二：推理工程师，准备改代码、调优、排查生产问题
适合：工作里真的要维护 vLLM 服务的人。
第一步不是读文章，是先把你生产环境跑的版本固定下来：`git checkout vX.Y.Z`，或者直接用线上镜像对应的 tag。然后在这个版本上读，文章只当导读。主线推荐按请求生命周期走：入口（entrypoints）→ 调度（v1/core/sched）→ KV Cache 管理（v1/core/block_pool）→ 执行（worker/model_runner）。模块细节用《vLLM 解析》系列当字典查，它覆盖了 MoE、MLA 这些新架构；多机多卡的部分看《分布式并行与通信全景》（注意它基线是 v0.26.0，你版本不同的话重点看设计而不是行号）。
这条路线的核心原则：代码是原文，文章是注释。版本不一致时以你 checkout 的代码为准。
路线三：学生或研究者，想理解设计思想
适合：要写论文、做系统方向研究、或者就是想搞懂"为什么这么设计"的人。
直接从《vLLM 源码详解》系列 + PagedAttention 原论文入手——v0.2.0 反而是优势，因为它离论文最近，SequenceGroup、BlockSpaceManager、CoW、重计算 vs 换出的权衡，这些设计决策在原初版本里看得最清楚。读完再回头看 V1 为什么重构（调度器从 Python 循环演化、架构简化），你对"系统怎么演化"的理解会比只看现代版本深一层。
几个实操提醒
读之前先 checkout。pip 装的 site-packages/vllm 也能读，但行号会跟着版本漂，跟着文章对行号时容易错位。《从源码读懂 vLLM》的作者也建议对照 site-packages 看，前提是你版本和文章对得上。
认准 vllm/v1/ 路径。现在读 V1 架构，入口都在 v1 目录下；看到不带 v1 的路径（比如 vllm/core/block_manager），多半是 V0 遗产，心里先打个问号。
概念词也要分代。BlockSpaceManager、SequenceGroup、Copy-on-Write 是 V0 词汇；block_pool、KV Cache manager、scheduler（v1/core/sched）是 V1 词汇。搜资料时带上版本号，能省掉一半的混乱。
别指望一篇文章管很久。《分布式并行与通信全景》的作者自己都说"vLLM 变化实在太快"。知乎 这类内容的正确用法是当阶段性地图，不是圣经。
想验证理解，去 issues 和 benchmark 里对答案。读源码读出来的理解，最好用一次实际的压测或者一个 issue 复现来检验，不然很容易"看起来懂了"。
最后说句实在的：这波连载潮本身是个好信号——说明中文社区对推理引擎的关注，已经从"会部署"进化到"要读懂"了。但 vLLM 的迭代速度决定了，任何源码解析都有保质期。
选路线之前，先看版本基线；读文章之前，先 checkout 代码。这两件事做了，这波资料才是地图；不做，它们就是一堆互相矛盾的罗生门。
你最近在读 vLLM 的哪个模块？卡在哪个版本上？评论区聊聊，看看能不能凑一张社区的踩坑清单。
