Zero to SGLang

这是什么？适合谁？

Zero to SGLang（datawhalechina/zero-to-sglang）是 Datawhale 与 RadixArk（SGLang 团队创立的公司）联合发起的 LLM 推理系统化开源教程，中英双语，副标题《从零手搓 SGLang》。它解决一个真实痛点：推理引擎教程要么只讲概念不动手，要么直接让你啃 SGLang 源码无从下手。这门课三段式推进——先从推理本质讲起（KV Cache 为什么要有、prefill 和 decode 差在哪、compute-bound 与 memory-bound 是什么），再从零手搓一个 mini-sglang（前向、生成、KV Cache、HTTP 服务、Continuous Batching、Paged KV Cache、RadixAttention 逐个加上去），最后回到真实 SGLang 讲前沿优化并走通第一个 PR 流程。

适合谁：想系统理解 LLM 推理内核的算法/infra 工程师；准备给 SGLang 或同类推理框架（vLLM、TensorRT-LLM）贡献代码的开发者；课程作业或面试需要”手搓推理引擎”经历的学生。

不适合：只想调用 OpenAI 兼容 API、不关心引擎内部实现的纯应用层开发者；没有 Python + PyTorch 基础的零基础读者。

使用前提：Python 与 PyTorch 基础；需要 GPU（Part II 手搓实验建议 CUDA 环境）；SGLang 前置知识不要求。

准备工作

1. 环境：Python 3.x + PyTorch，GPU 环境（手搓实验部分）
2. 账号：GitHub 账号（Part III 提 PR 用）
3. 成本：教程本身免费开源；主要成本在 GPU 算力（云 GPU 数十元/小时级，视实验规模而定）
4. 时间：完整学完约数周，Part II 每章可独立完成
5. 资料：在线阅读版 datawhalechina.github.io/zero-to-sglang（中文 /ch/，英文 /eng/ 翻译中）

快速上手（3 步）

第一步：克隆仓库并浏览课程结构

git clone https://github.com/datawhalechina/zero-to-sglang.git
cd zero-to-sglang

仓库含 course-material/ch/（中文）与 course-material/eng/（英文）两套课程材料，配合在线阅读版使用。

预期产出：了解课程 roadmap——Part I 概念 → Part II 手搓 Mini SGL → Part III 真实 SGLang 源码与 PR。

第二步：从 Part I 读起，跑通概念

先读 KV Cache、prefill/decode、compute-bound vs memory-bound 三章。这三章是后面所有手搓实验的理论地基——不搞清”为什么 KV Cache 把注意力从 O(n²) 降到 O(n)“，第 4 章的缓存实现会看不懂数据结构为什么那样设计。

预期产出：能用自己的话解释 KV Cache 的作用、prefill 与 decode 两阶段的差异、算力瓶颈与显存瓶颈的判别。

第三步：进入 Part II 手搓 mini-sglang

按章推进：mini-sglang 总体架构 → 手写前向与自回归生成循环 → KV Cache → HTTP 服务化 → Continuous Batching 与调度器 → Paged KV Cache 与显存管理 → RadixAttention 与前缀缓存。每章代码量控制在可完成的规模（“Your First 200 Lines”级别）。

成功判定：完成 Chapter 3 后你有一个能跑通的前向+生成循环；完成 Chapter 7 后你的引擎支持分页 KV Cache；Part III 结束时能在 SGLang 官方仓库提交第一个像样的 PR。

初级用法

• 概念速查：把 Part I 当 KV Cache / Continuous Batching / Paged KV Cache 的中文速查手册，比零散博客系统
• 手搓实验：Chapter 3-8 每章对应一个可运行的 mini-sglang 增量版本，跟着写一遍胜过读十篇源码解析
• 源码导读：Part II 结束后直接对照真实 SGLang 源码读 “Inside SGLang: The Path of a Request”，请求生命周期逐行可追溯
• 双语学习：英文版 /eng/ 翻译中，中文版为权威版本

高级玩法

• PR 实战流水线：按 Part III 的 profiling 与 trace 分析章节，定位 SGLang 的真实性能问题并提交修复 PR——课程作者就是 SGLang 团队（RadixArk），PR 会被官方 review
• 前沿优化地图：量化、分层缓存、DP Attention / EP / PP、Prefill-Decode 分离这些生产级优化在 Part III 有专题，可作为选型与调优 checklist
• 面试级项目：手搓的 mini-sglang（含 Continuous Batching + Paged KV Cache + RadixAttention）本身就是高含金量的 infra 面试作品

常见踩坑

1. 症状：Part II 实验跑不动/OOM。 原因：mini-sglang 实验需要 GPU，无卡环境会失败。解决：用云 GPU（按小时计费），或先用小模型/小 batch 验证逻辑再放大。
2. 症状：英文版内容缺失。 原因：/eng/ 仍在翻译中，进度落后于中文版。解决：以中文版（/ch/）为准，英文版作对照。
3. 症状：Chapter 4 的 KV Cache 数据结构看不懂。 原因：跳过了 Part I 概念章直接进手搓。解决：回读 KV Cache: From O(n²) to O(n) 前置理论，手推一遍复杂度。
4. 症状：想直接给 SGLang 提 PR 但不知道从哪下手。 原因：真实 SGLang 代码量大，盲目读源码效率低。解决：严格按课程的请求生命周期路线（Chapter 2 Inside SGLang）走，先小 PR（文档/测试）再性能 PR。
5. 症状：本地 SGLang 服务起不来。 原因：本课程不等于 SGLang 部署教程，引擎本身有独立依赖要求。解决：纯部署需求请看 SGLang 官方仓库文档（本站也有 SGLang 条目），本课程聚焦原理与源码。

小技巧

• 手搓时每完成一章就 git commit 一次，形成自己的增量历史，复习时 diff 相邻章节看每次优化改了什么
• 对照学习：mini-sglang 的每个模块去真实 SGLang 源码里找对应实现，双向验证理解
• 学 Continuous Batching 前先把”静态批处理为什么浪费”写成一句话结论，学完再回来修正
• 在线阅读版支持直接跳章，通勤时可用手机读 Part I 概念章

常见问题 FAQ

Q1: 这门课和 SGLang 官方文档有什么区别？

A: SGLang 官方文档教你怎么部署使用引擎；本课程教你引擎内部怎么实现——从 KV Cache 到 RadixAttention 手搓一遍，最后带你看真实源码。前者是用户视角，后者是引擎开发者视角。

Q2: 需要多强的 GPU？

A: Part II 手搓实验是教学级实现，消费级单卡（如 24GB 显存级）足够跑通核心章节；大规模实验才需要多卡。无卡环境建议租云 GPU。

Q3: 免费吗？什么协议？

A: 课程材料免费开源；star 增长快（627★/46 fork，采集日期 2026-09-10）。注意仓库暂未在 GitHub 标注开源 license（Datawhale 教程惯例常为 CC 协议，以仓库最新声明为准），商用需自行确认。

Q4: 学完能干什么？

A: 三个层次：看懂主流推理引擎的设计权衡；具备给 SGLang/vLLM 类项目贡献代码的能力；面试 infra 岗位时有可展示的手搓项目。

Q5: 中文还是英文？

A: 中英双语，中文版完整且为权威版本，在线阅读 /ch/ 路径；英文版 /eng/ 翻译中。

Q6: 需要先学过 CUDA 吗？

A: 不必须。课程用 Python/PyTorch 层面讲清计算与显存的关系，CUDA 知识在深入 SGLang 真实源码（如 kernel 级优化）时再补。

参考链接

• 官方仓库 datawhalechina/zero-to-sglang
• 在线阅读版（中文）
• SGLang 官方仓库 sgl-project/sglang
• Datawhale 组织主页

本文基于公开资料（GitHub 官方 README 与在线阅读版）整理，AI 辅助生成，未做本地安装实测；采集日期 2026-09-10。课程结构与代码以官方仓库最新版本为准。