zero-to-sglang README

The project's README from github.com/datawhalechina/zero-to-sglang. As one markdown file: README.md.

zero-to-sglang banner

zero-to-sglang

简体中文 English

📚 《从零手搓SGLang》

A hands-on tutorial on LLM inference: build a mini-sglang from scratch, then read the real SGLang source.

GitHub stars GitHub forks Language GitHub Project Online Reading

从推理的本质出发,手搓一个 mini-sglang,再吃透真实 SGLang 的源码

Datawhale × RadixArk


🎯 项目介绍

  大模型已经从「训练」卷到「推理」了。应用爆发之后,推理成本和延迟成了真正的瓶颈:同样一块卡,好的推理引擎能多扛好几倍的请求。但市面上讲推理引擎的教程不多,要么只讲概念不动手,要么直接让你啃 SGLang 源码,从哪儿下手都不知道。

  这门课想补上这个缺口。前半部分,我们从推理最核心的问题讲起:KV Cache 为什么要有、prefill 和 decode 差在哪、compute-bound 和 memory-bound 到底是什么意思。中间部分,带着你从零手搓一个 mini-sglang:前向、生成、KV Cache、HTTP 服务、Continuous Batching、Paged KV Cache、RadixAttention,一样一样加上去。后半部分,回到真实的 SGLang,讲清楚它那些前沿优化具体是怎么做的,最后教你怎么给 SGLang 提第一个像样的 PR。

  本项目由 Datawhale 和 RadixArk(SGLang 团队创立的公司)共同发起,值得信赖!SGLang 在推理框架领域技术扎实、迭代活跃,认可这个项目的话,欢迎去 sglang官方仓库 点个 ⭐。

✨ 你能学到什么

📋 前置要求

🔗 相关链接

📖 课程目录

状态图例:✅ 已完成 🔄 更新中 📝 待完善 🚧 筹备中 ⏸️ 暂缓

标注 粗体 的章节由 SGLang 官方成员编写。

章节 关键内容 状态
Part 0 — 开课之前
0.1 Coding Ethics and Open-Source Spirit(编码伦理与开源精神) 对自己代码负责、沟通时说人话、Profile 永远是第一步、开源精神 ✅
0.2 Deploy Your First SGLang Server(部署你的第一个 SGLang 服务) 环境设置,在你自己的 GPU 上用 SGLang 跑起 Qwen3-0.6B ✅
Part I — 基础概念(concepts only,无代码、无 GPU)
1. Introduction to LLM LLM 的定义与发展脉络、Transformer 架构、自回归生成、关键基础概念 ✅
2. Introduction to inference 训练 vs 推理、prefill/decode、compute-bound vs memory-bound、Roofline model ✅
3. Introduction to GPU GPU 架构基础、LLM 推理在 GPU 上的执行流程、从硬件理解推理瓶颈 🔄
4. KV Cache: The Core Data Structure of Inference 从 Attention 推导 KV Cache、cache 生命周期、显存占用定量分析 ✅
5. Introduction to Benchmark TTFT / TPOT / ITL / Goodput 等核心指标、百分位与尾延迟、怎么设计/跑/读 benchmark 🔄
Part II — 从零手搓 Mini SGL
1. mini-sglang:推理引擎长什么样 推理引擎的总体架构、模块划分、本部分的 roadmap 📝
2. Inside SGLang: The Path of a Request 一个请求从进入到返回的完整生命周期 🚧
3. Your First 200 Lines: Forward Pass and Generation 手写前向传播与自回归生成循环 🚧
4. KV Cache: From O(n²) to O(n) 缓存实现与注意力计算优化 🚧
5. Serving It: HTTP and Concurrent Requests HTTP 服务化、并发请求处理 🚧
6. Continuous Batching and the Scheduler 连续批处理与调度器设计 🚧
7. Paged KV Cache and Memory Management 分页 KV Cache 与显存管理 🚧
8. RadixAttention and Prefix Caching RadixAttention 与前缀缓存 🚧
9. Multi-process & Tensor Parallelism 多进程与张量并行 🚧
10. Speculative Decoding 投机解码 🚧
Part III — 高级推理技术(深入真实 SGLang)
1. Attention Backends(FlashInfer / Triton / FA3 / FlashMLA)and CUDA Graph 主流 Attention 后端对比与 CUDA Graph 🚧
2. Quantization and Low-Precision Inference 量化与低精度推理 🚧
3. Hierarchical Caching 分层缓存 🚧
4. Scaling Out: DP Attention, EP, PP 横向扩展:DP Attention / EP / PP 🚧
5. Prefill-Decode Disaggregation Prefill-Decode 分离 🚧
Part IV — 如何为 SGLang 做贡献(可选)
1. Deploying SGLang with the Cookbook 使用 Cookbook 部署 SGLang 🚧
2. Measuring It All: Profiling and Trace Analysis Profiling 与 Trace 分析 🚧
3. SGLang PR Workflow SGLang PR 全流程 🚧

🗓️ 编写进度

起始日期:2026 年 8 月 24 日(周一)。每章约一周,加粗章节由 SGLang 官方成员编写。

部分 时间安排 状态
Part 0 — 开课之前 已完成 ✅
Part I — 基础概念 8.24 ~ 9.06 编写,9.07 ~ 9.13 review 🔄
Part II — 从零手搓 Mini SGL 9.14 ~ 10.04 编写,10.05 ~ 10.10 review 🚧
Part III — 高级推理技术 10.10 ~ 11.15 🚧
Part IV — 如何为 SGLang 做贡献 11.16 ~ 12.6 🚧

🚀 快速开始

# 克隆仓库
git clone https://github.com/datawhalechina/zero-to-sglang.git
cd zero-to-sglang
# 安装基础依赖(根据具体章节需求安装)

学习路径

1️⃣ 读 Part I,先把推理的整体认知建立起来(不需要 GPU)
2️⃣ 跟着 Part II,从 0 到 1 手搓一个 mini-sglang
3️⃣ 进 Part III,对照真实 SGLang 源码理解前沿优化
4️⃣ 完成 Part IV,走通 profiling、trace 分析和 PR 全流程

项目结构

zero-to-sglang/
├── course-material/         # 课程正文
│   ├── ch/                  # 中文(在线阅读 /ch/)
│   │   ├── part0/           # Part 0:开课之前
│   │   ├── part1/           # Part I:基础概念(更新中)
│   │   ├── part2/           # Part II:从零手搓 Mini SGL(规划中)
│   │   ├── part3/           # Part III:高级推理技术(规划中)
│   │   ├── part4/           # Part IV:如何为 SGLang 做贡献(规划中)
│   │   └── WRITING_TEMPLATE.md
│   └── eng/                 # English(在线阅读 /eng/,翻译中)
│       ├── part0/
│       └── WRITING_TEMPLATE.md
├── community/               # 社区贡献专区:手搓记录、踩坑、学习笔记
│   ├── ch/
│   └── eng/
├── docs/.vitepress/         # VitePress 站点配置
├── README.md                # 项目说明(中文)
├── README_en.md             # 项目说明(English)
└── .gitignore               # Git 忽略配置

🤝 如何贡献

我们是一个开放的开源社区,欢迎任何形式的贡献。动手之前,请先读一遍 Part 0,了解我们期望的编码伦理与开源精神。

1. 改进课程正文

2. 分享你的实践

内容放在 community/ch/(英文放 community/eng/)对应的目录下。

提 PR 的流程

  1. Fork 本仓库,从 main 切一个分支
  2. PR 具体要求见 community/ch/PR_requirement.md,提交之前请逐条核实

❓ 常见问题

Q: 没有 GPU 可以学吗?

可以。Part I 完全不涉及 GPU;Part II 的大部分代码能在 CPU 上调试,但完整的性能验证和 Part III 的深入内容建议用 GPU(云服务也行)。

Q: 需要先精通 CUDA 吗?

不需要。这门课从推理的概念出发,Part III 才会深入 Attention Backends 等底层内容,到时候再按需补就行。

💬 读者交流群

欢迎加入 zero-to-sglang 读者交流群,与大家一起交流学习、答疑解惑:

读者交流群
读者交流群

👥 贡献者

注:我们感谢每一位为项目做出贡献的开发者!

特别感谢

🎓 引用

如果 zero-to-sglang 对您的研究或工作有所帮助,欢迎引用:

@misc{zero_to_sglang2026,
  title  = {zero-to-sglang: Building an LLM Inference Engine from Scratch},
  author = {TODO},
  year   = {2026},
  url    = {https://github.com/datawhalechina/zero-to-sglang},
  note   = {GitHub repository}
}

⭐ Star History

如果这个项目对你有帮助,欢迎给个 Star ⭐️!

📄 许可证

知识共享许可协议

本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。


让更多人能系统性地学会 LLM 推理引擎的构建

Made with ❤️ by Datawhale & RadixArk

zero-to-sglang (datawhalechina/zero-to-sglang)

speculative-decoding
Searching Database…

What is this?The official SGLang x Datawhale course on LLM inference: it teaches how inference engines work, has you build a mini-sglang from scratch, and then digs into the real SGLang source code.
Is this a course I read, or a codebase I clone and run?Mostly a course: written chapters served as a docs site (built with VitePress), plus a reference mini-sglang implementation that you code along with in Part II.
What does the learning path look like if I start today?Four steps: read Part I for inference fundamentals (no GPU needed), build a mini-sglang from zero in Part II, study real SGLang optimizations in Part III, then finish Part IV's profiling, trace analysis and PR workflow.
What do I need to know before starting?Proficient Python with basic software-engineering habits, PyTorch and neural-network basics, plus linear algebra and probability. CUDA knowledge is optional — the course fills in what you need as it goes.
Is the course finished, or can I read it all now?It's still being written. Work started Aug 24, 2026 at about one chapter per week: Part 0 is done and Part I is nearly there, but most Part II chapters are still in preparation, with Parts III-IV due by Dec 2026.
Can I reuse the materials for my own workshop or company training?Careful: it's licensed CC BY-NC-SA 4.0, so you must give attribution, share adaptations under the same license, and non-commercial use only — company training would need separate permission.
What will I actually have built by the end of Part II?A working mini-sglang engine: forward pass and autoregressive generation, KV Cache, an HTTP server handling concurrent requests, continuous batching with a scheduler, Paged KV Cache, RadixAttention with prefix caching, multi-process tensor parallelism and speculative decoding — added one step at a time.
Is the course available in English?Yes — the project ships in both English and Chinese. Translated chapters go under course-material/eng/, and helping with translation is one of the listed ways to contribute.
What does Part 0 cover before the main course starts?Two starter chapters: coding ethics and the open-source spirit, and deploying your first SGLang server — you set up the environment and run Qwen3-0.6B on your own GPU with real SGLang before touching any theory.
Size
77.8 MB
Stars
1.5K
Updated
CommitOct 15
Age
1mo
Commits · 90 Days