GPU 大模型系统论文解读站

加餐 B03 · Mini-SGLang 代码导读

原作：sgl-project（SGLang 官方）· MIT 许可 · 约 5000 行 Python 读懂现代 LLM 推理系统 · 无需 GPU 即可读码

代码名片

Mini-SGLang——SGLang 官方组织（sgl-project）出品的精简版推理框架：约 5000 行带类型标注的 Python 代码实现了 SGLang 的核心，目标写在 README 里："揭开现代 LLM 推理系统的复杂面纱"。它既是能真实跑生产的推理引擎（Qwen3 全系实测、性能对标 SGLang 本尊），又是一份透明的参考实现。

仓库：sgl-project/mini-sglang（MIT 许可，⭐ 5.2k）；官方架构文档：docs/structures.md；姊妹课程：zero-to-sglang（SGLang × Datawhale 中文推理课）。

本页性质：代码导读页——基于官方仓库与官方架构文档整理的读码路线图，带你按顺序读懂这本"带注解的推理系统书"。读它不需要 GPU，只需要读完 B02 的注意力代码基础。

为什么值得读

一句话：nanoGPT 之于 GPT 训练，mini-sglang 之于推理服务。训练侧"从零写 GPT"的教程很多，推理侧（KV Cache 怎么管、请求怎么调度、多卡怎么协同）却少有这样小而完整的开源范本。它把 vLLM/SGLang 论文里的那些名词——Radix Cache、Chunked Prefill、Overlap Scheduling、张量并行——全部落到能逐行读懂的代码上。

对读者要说清楚的一点：这不是玩具。Qwen3-0.6B 到 32B 的离线与在线基准测试都真实对标过 SGLang 本尊，Overlap Scheduling 还专门留了消融开关（MINISGL_DISABLE_OVERLAP_SCHEDULING=1）供你做对照实验。

系统架构：四个进程一台戏

Mini-SGLang 是一个分布式系统，由几个独立进程协作：

进程间用 ZeroMQ (ZMQ) 传控制消息，GPU 之间的张量数据走 NCCL（torch.distributed）。一次请求的完整生命周期：用户请求 → API Server → Tokenizer → Scheduler (Rank 0) 广播给所有 Rank → 各 Rank 调度并触发本地 Engine 算出下一个 token → Rank 0 收集结果 → Detokenizer → 流式回传用户。

五大核心机制（论文概念的代码落点）

Radix Cache：用基数树管理 KV Cache，让共享前缀的请求（同一个 system prompt 的所有请求）直接复用已算好的部分。对应模块 minisgl.kvcache，里面同时实现了 NaiveCacheManager 和 RadixCacheManager——对照读，立刻明白 Radix 到底优化了什么。

Chunked Prefill：长 prompt 的预填充切块执行，削峰显存占用，调度器里能看到它和 decode 的混合批处理。

Overlap Scheduling：CPU 上的调度与 GPU 上的计算重叠执行，把调度开销藏进 GPU 时间；基准页还提供消融开关供你自己验证收益。

张量并行（TP）：多卡切分模型，通信原语是 all-reduce / all-gather，对应模块 minisgl.distributed。

优化内核：注意力后端可切换 FlashAttention 与 FlashInfer（minisgl.attention），自定义 CUDA 内核放在 minisgl.kernel，用 tvm-ffi 做 JIT 绑定。

代码地图与阅读路线

源码在 python/minisgl 下，模块分工清晰。推荐的读码顺序，跟着一条请求的生命周期走：

  1. minisgl.server——看 launch_server 怎么把四个进程拉起来；
  2. minisgl.tokenizer + minisgl.message——文本如何变成 token 消息；
  3. minisgl.core——Req、Batch、Context 三个核心数据结构（一切状态都在这里）；
  4. minisgl.scheduler——核心中的核心：批处理、Chunked Prefill、Overlap 都在这里；
  5. minisgl.engine——单卡 TP worker：模型、KVCache、注意力后端、CUDA Graph 回放的管理者；
  6. minisgl.kvcache——Naive 与 Radix 两种管理器对照精读；
  7. minisgl.attention + minisgl.models（Llama / Qwen3）+ minisgl.layers——模型与算子层；
  8. minisgl.kernel、minisgl.distributed——想深入再读的内核与通信。

配套：官方 features.md 列全了功能与命令行参数；跑不起 GPU 就读 zero-to-sglang 课程的图文版。