源码精读系列第四篇， 形式略不同：被读的项目本身就是教学产物， 所以这篇博客把”如何从最小实现学习”的反思和技术内容交织在一起写。 完整 HTML 深度阅读（带 Tufte 风格的边栏反思）在 /sources/mini-sglang.html。
来龙
2025 年 12 月 SGLang 团队做了开源世界里不常见的事：给自己的系统写了第二个、 更小的实现—— 大约 5,000 行 Python， 比生产引擎小 140 倍。 保留了四进程架构、 RadixAttention、 chunked prefill、 overlap scheduling、 tensor parallelism。 其他一切（27 个 attention backend、 分级 cache、 P/D 分离 serving、 投机解码、 多模态等）全部删掉。 一个下午就能读完。 让 72.9 万行的母项目突然变得可读。
这一篇围绕一个问题展开：这个双生子的存在， 除了代码本身， 还教会了我们什么？
关键位置的缩水
两个引擎都有的模块， 逐文件对比：
| 模块 | full SGLang | mini-SGLang | 倍数 |
|---|---|---|---|
| Scheduler | 4006 行单类 + Mixins | 280 行 + 6 个 helper 文件 | 14× |
| ModelRunner / Engine | 3607 行 | 253 行 + 独立 graph.py | 14× |
| RadixCache | 828 行 | 253 行 | 3.3× |
| Attention backends | 27 个 | 2 个（FlashAttention、 FlashInfer） | 13× |
| 模型 | ~50 个架构 | 2 个（Llama、 Qwen3） | 25× |
| 整包 | 728,969 行 | ~5,000 行 | 140× |
非均匀的倍数本身就是数据。 高倍数的模块（scheduler、 runner、 attention）承载了很多 features、 版本、 边缘情况； 低倍数的模块（RadixCache 只缩 3.3 倍）由算法本质支配 —— 正确的 radix 树有”最低行数下限”。
五条浮现出来的反思
代码本身没说但读完会带走的几个：
1. 小是一个透镜， 不是约束
容易把 mini-SGLang 当成”通向真东西的踏脚石”。 这种 framing 低估了它。 5,000 行版本不是次等 —— 它是服务于不同目的的不同产物。 生产版本优化吞吐量和功能覆盖； 教学版本优化的是每个概念的阅读时间。 两个都对， 两个都必要。
文化创新不在代码， 而在决定写一份主要使用者是”读者”而非”运维”的代码。 这种决定在开源里很罕见。 历史上它来自个人项目（Karpathy 的 nanoGPT、 何恺明的 MAE）。 LMSYS 在机构规模上做这件事， 还和生产版同步维护， 是一个安静的先例。
2. 拆分本身就是教学
mini-SGLang 教学价值最高的一步是 scheduler 的拆分。 生产版有一个 4006 行的类带 4 个 Mixins（SchedulerMlxOverlapMixin、 scheduler_dp_attn_mixin、 …）。 mini 把同样的职责拆成 7 个聚焦小文件 —— scheduler.py（280 行， 主循环）+ cache.py + decode.py + prefill.py + io.py + table.py + config.py。
Mixin 模式很聪明因为避免了文件爆炸， 但它把行为分散到继承链上， grep 不易显形。 读一个 4006 行带 4 个 Mixin 的类需要读者在脑里维护部分 method resolution order —— 这种心智税随着代码库年龄复利累积。
对你自己代码的启发：当一个类突破大约 800 行时， 问自己到底在做一件事还是在掩盖一次被错过的拆分。 教学版终究会拆开它 —— 那生产版不如早一点考虑拆。
3. 教学版有时候更好
直觉上， 最小版应该是其父项目的严格子集。 但 mini-SGLang 偶尔会改进掉 full SGLang 的某些设计。 最清楚的一例： KV cache 引用计数。 full SGLang 用手动 inc_lock_ref() / dec_lock_ref() 配对 —— 这是个知名的踩雷点， 容易泄漏（这正是 SGLang 那篇精读 里的 Trap N° 3）。 mini 引入 lock_handle()， 返回一个 RadixCacheHandle frozen dataclass —— RAII 模式， 泄漏在结构上几乎不可能。
教学版能 ship 这个更干净的设计， 是因为它没有被任何调用方锁死。 所以 mini-SGLang 也作为一个影子设计存在 —— 一份关于”如果在空白页重新设计， full SGLang 会长什么样”的可工作草图。 读它不只是学当下， 也是窥探下一版。
4. 缺失什么教会你什么是”可选的”
mini-SGLang 的取舍线刚好划在架构和架构之上的 features 之间。 砍掉的内容： 27 个 attention backend 中的 25 个、 大约 50 种模型架构、 AITER/ROCm/MUSA/NPU 路径、 投机解码、 P/D 分离、 结构化生成、 多模态、 分级 cache、 observability 栈、 独立的 sgl-kernel wheel。
这些都不是不重要 —— 它们正是 production SGLang 存在的原因。 它们只是不基础到”LLM 推理引擎如何工作”这一层。
对你自己的系统：先在脑里写”mini 版”。 找出”不删掉就无法成立”的那些组件。 先把它们做好。 其他全部作为可选 features 叠上去。 按这个方式成长起来的生产系统（即便从未把 mini 公开）， 比通过堆积长出来的系统， 维护性明显更好。
5. “教学即代码”是一条真实的第三路径
文档朽得比代码快。 一个第二份、 更小的、 与主版本同步维护的实现， 是文档之外的第三条路 —— 不是 just-code， 也不是 just-docs， 而是为了被阅读而存在的代码。
如果这种做法在开源 MLSys 圈传开， 每个主要系统都会有一个教学双生子。 PyTorch 已有 nanoGPT 级别的教学 fork； vLLM 还没有； TensorRT-LLM 完全没有。 mini-SGLang 作为机构级先例的意义， 比它作为某一具体仓库的意义更大。
一套实用 workflow
如果你确实要碰 SGLang 内部：
- 第一遍 —— 顺序读完 mini-SGLang， 按
__main__→server/→tokenizer/→core.py→kvcache/→scheduler/→engine/→attention/+models/的次序。 大约 5 小时。 目标：建立词汇表。 - 建索引 —— 每个 mini 文件， 标注它对应 full SGLang 的哪个文件/目录。 保留成你的私人对照表。
- 针对性阅读 —— 要碰 full SGLang 前， 先复习对应的 mini 部分（~15 分钟）， 然后带着结构进 full。
- 差读 —— 当 full 有 mini 没有的（disaggregation、 EAGLE）， 把它读成”在已熟基础上加的外挂”， 而不是”重新学一次”。
- 贡献方向 —— mini 有 full 没有的模式， 都是潜在的重构 PR 候选。 那个 RAII handle 就是一个。
★ 更大的画面
冷启动读 72.9 万行代码的恐惧， 跟代码本身好不好没什么关系 —— 是和”无法在工作记忆里持有”有关。 同一个系统先以 5,000 行读完， 再读 72.9 万行版， 是不同的认知任务 —— 第二次读不是”读”， 是”认”。 同样的神经元， 完全不同的体验。 mini-SGLang 在这个意义上是个礼物 —— 它把”恐惧式阅读”换成了”自信式识别”。
如果你 2026 年在写系统软件， 而你的 codebase “大到没法教”， 考虑一下你是否欠社区一个教学双生子。 工作量真实但有界。 杠杆巨大。
→ 完整 HTML 深度阅读： /sources/mini-sglang.html —— Tufte 注释式 essay 版式， 反思以斜体小字在右边栏与正文并行； 奶油纸面、 暗红/靛蓝/苔绿点缀、 Marcellus + Crimson Pro 字体。
系列到目前为止：
- 源码精读 001 — SkyPilot（编排， 21 万行）
- 源码精读 002 — full SGLang（推理， 极繁版， 72.9 万）
- 源码精读 003 — vLLM（推理， 另一条路径， 63.3 万）
- 源码精读 004 — mini-SGLang（推理， 教学版， 5 千） ← 你在这里