SGLang 学习手册

一份面向大模型推理岗的 SGLang 工程笔记，44 章，从 RadixAttention 一直写到 K8s 部署。 每章里凡是讲到具体实现，都标着 file_path:line_number，方便你随时跳到 SGLang 源码对照。

姊妹项目 vllm-learning 是同一套章节布局，写完一篇就可以跳过去看 vLLM 同位置怎么做。

这份手册解决什么问题

我写这份笔记，是因为自己读 SGLang 源码的时候踩了一圈坑，回头发现没有一份资料把"为什么这么设计 → 在哪一行代码里 → 出事了怎么排查"这三件事串起来讲。如果你是：

• 准备面试，不想再背"RadixAttention 解决了什么"这种二手答案；
• 业务正在 SGLang / vLLM / TensorRT-LLM 之间挑引擎；
• TTFT / TPOT 不达标，要从调度层一路追到 attention kernel；
• 想给 SGLang 提 PR，但 scheduler、radix cache、model runner 之间的咬合没看明白，

那这本是给你写的。

不适合两种人：完全没接触过 LLM 推理（先看 01-overview/00-prerequisites.md 把前置铺平），以及纯 prompt engineer 不碰服务侧——这本太工程。

与 vllm-learning 的关系

读完本书任何一章，跳到 vllm-learning 同名位置对照着看，两套引擎的设计权衡会清楚很多。专门有一章 01-overview/03-sglang-vs-vllm.md 做这件事。

怎么用这份资料

有两种打开方式。Markdown 直接读——本 README 当目录，按文件名点进去，适合在 IDE 里一边读一边对着源码翻。HTML 在线版——跑一次 python3 build_html.py，打开 _site/index.html，多了侧栏、全文搜索、Mermaid 渲染、阅读时间估算。Markdown 链接、Mermaid 图、代码块在两种模式下都能用。

每章统一的结构：

谁该读这一篇？ ... 前置阅读： ... 耗时： N 分钟 学完能： ...

正文（含 mermaid / 表格 / 代码引用）

## 小结
## 自检（3-5 题，自答）
## 下一步（跳转推荐）

从头到尾过一遍大约 25-30 小时，动手实验另算。

学习路径

flowchart LR
    A[Week 1<br/>建立直觉<br/>~6h] --> B[Week 2<br/>吃透核心算法<br/>~8h]
    B --> C[Week 3<br/>啃源码<br/>~10h]
    C --> D[Week 4<br/>前端 DSL / 分布式 / 生产<br/>~10h]

    A -.-> A1[01-overview]
    B -.-> B1[02-core-concepts]
    C -.-> C1[03-code-walkthrough]
    D -.-> D1[04-optimizations]
    D -.-> D2[05-distributed]
    D -.-> D3[06-frontend-language]
    D -.-> D4[08-production-deployment]

按章节顺序读最系统。时间紧的话，挑下面这几条路径：

章节索引

每章后面跟一句话，告诉你这章解决什么问题。

1. 总览 · 01-overview/ — 6 章

• 00-prerequisites.md — 🆕 token / KV cache / TTFT·TPOT / 前缀缓存基础一次铺平，零基础起点。
• 01-what-is-sglang.md — SGLang 是什么、双层架构、它真正不同于 vLLM 的四个地方（RadixAttention / 压缩 FSM / cache-aware / DSL）。
• 02-architecture.md — 三进程（Tokenizer / Scheduler / Detokenizer）+ ZMQ 数据流。
• 03-sglang-vs-vllm.md — 与 vLLM 全方位对比，选型决策表。
• 04-project-structure.md — sglang/ 1000+ 文件的模块地图。
• 05-quickstart.md — 5 分钟跑通：装环境、起服务、发请求。

2. 核心概念 · 02-core-concepts/ — 5 章

• 01-radix-attention.md — Radix tree 组织前缀缓存的核心算法。
• 02-frontend-dsl.md — gen / select / fork 六大原语。
• 03-cache-aware-scheduling.md — 调度时考虑 cache 命中而非纯 FCFS。
• 04-compressed-fsm.md — 受约束解码：压缩自动机 + jump-ahead。
• 05-token-attention.md — Token 级别 KV 管理 vs Page 级别。

3. 源码走读 · 03-code-walkthrough/ — 8 章

• 01-server-entry.md — launch_server.py 的完整调用链。
• 02-tokenizer-manager.md — 请求入口进程、in-flight 维护、流式回写。
• 03-scheduler.md — Scheduler.event_loop_normal 3900+ 行精读。
• 04-model-runner.md — ForwardBatch / CUDA Graph / Sampler。
• 05-radix-tree.md — RadixCache.match_prefix / insert / evict 代码细节。
• 06-attention-backends.md — FlashInfer / Triton / Torch 怎么切。
• 07-detokenizer.md — 增量 BPE detokenize + SSE 流式。
• 08-io-struct.md — 消息体 schema 一览。

4. 优化 · 04-optimizations/ — 4 章

• 01-flashinfer.md — Cascade Inference / Page Table API 对接。
• 02-speculative-decoding.md — EAGLE / N-gram / Medusa。
• 03-quantization.md — FP8 / AWQ / GPTQ / Marlin 矩阵。
• 04-cuda-graph.md — 何时开 / 何时关 / 捕获边界。

5. 分布式 · 05-distributed/ — 4 章

• 01-tensor-parallelism.md — TP 切法 + AllReduce + KV 分布。
• 02-data-parallelism.md — DP 模式 + router 协同。
• 03-expert-parallelism.md — DeepSeek / Mixtral 的 MoE EP 切分。
• 04-disaggregated.md — Prefill/Decode 分离架构。

6. 前端 DSL · 06-frontend-language/ — 4 章

• 01-dsl-walkthrough.md — 用 DSL 写一个 ReAct agent。
• 02-multimodal.md — 图像/视频输入的 DSL 与 Runtime 支持。
• 03-json-schema.md — JSON Schema → 压缩 FSM 编译路径。
• 04-tool-use.md — Function calling 状态机与流式触发。

7. 实操 · 07-hands-on/ — 4 章

• 01-setup.md — uv 装环境 / GPU 检查 / 起 7B 服务。
• 02-benchmark-throughput.md — bench_serving.py 跑可重复数字。
• 03-debug-scheduler.md — 给 Scheduler 加 print 看 batch 演化。
• 04-custom-frontend.md — 用 DSL 写检索+多分支+投票工作流。

8. 生产部署 · 08-production-deployment/ — 9 章

• 01-docker.md — 官方镜像 + 自建镜像对比。
• 02-kubernetes.md — Deployment + Service + GPU 资源模板。
• 03-monitoring.md — Prometheus 指标 + Grafana 面板。
• 04-slo.md — TTFT/TPOT/p99 SLO + 容量公式。
• 05-incident-playbook.md — 8 类典型故障 runbook。
• 06-cost-tuning.md — GPU 利用率 / batch size / 模型选型。
• 07-router.md — sgl-router 架构与路由策略。
• 08-multi-tenant.md — 隔离 / 配额 / 计费。
• 09-versioning.md — 版本兼容、模型版本、API 版本。

9. 应用特性 · 09-advanced-features/ — 5 章

• 01-sampling.md — top-k/p / temperature / logprobs / penalties。
• 02-structured-output.md — 压缩 FSM 进阶 + JSON Schema 边角。
• 03-multimodal-vlm.md — Vision encoder cache / Qwen2-VL / LLaVA。
• 04-lora.md — LoRA 多适配器动态加载。
• 05-embedding.md — 用 SGLang 引擎跑 embedding / rerank。

SGLang 仓库地标速查

完整地图见 01-overview/04-project-structure.md。

怎么读这本书

几个习惯，是我自己读这种工程项目踩了几年坑后留下的，分享给你：

别信博客，直接看代码。 SGLang 的源码注释很克制，但 commit log 和 PR 描述讲得比任何二手解读都清楚。

先看数据结构，再看逻辑。 读 Scheduler 之前先翻一遍 io_struct.py 里的字段；读 RadixCache 之前先看 TreeNode 长什么样（radix_cache.py:208）。字段读完，整个模块的代码就只是在维护这些字段。

打 print 比读注释快。 启动 server 时加 --log-level debug，在 Scheduler.event_loop_normal 和 RadixCache.match_prefix 各塞一句 print，跑一次实际请求，比啃半天文档管用。

自己画三张图： 请求从 HTTP 进入到 HTTP 出去的全链路；RadixTree 的演化过程；Scheduler 一步迭代里的决策流。这三张图自己画过一遍，整本书就活起来了。

讲 SGLang，必须能讲 vLLM。 离开对比谈优势就是空的。专门一章 01-overview/03-sglang-vs-vllm.md 做这件事，你也应该自己也总结一份。

面试自检清单

读完整本之后，下面这些问题你应该能在一两分钟里讲清楚，并且能指出对应的源码位置。每题附一段简答 + 章节链接。

每题都有专门展开，分布在 02-core-concepts / 03-code-walkthrough / 04-optimizations / 05-distributed / 08-production-deployment 几个目录里。

必读资料

按我建议的阅读顺序排：

1. SGLang 论文（Zheng et al., NeurIPS 2024，SGLang: Efficient Execution of Structured Language Model Programs）。先读这篇，再读代码，会少走很多弯路。其中 §4 是 RadixAttention，反复看那两页。
2. FlashInfer 论文（Ye et al.）。SGLang 默认就跑在这套 attention kernel 上，不读这篇，后面看 attention backend 那章会很吃力。
3. PagedAttention 论文（Kwon et al., SOSP 2023）。理解 SGLang 为什么这么设计，前提是知道 vLLM 当年怎么做的。
4. xgrammar 论文（Dong et al.）。SGLang 压缩 FSM 的对照组。
5. EAGLE / EAGLE-2。SGLang 投机解码的当家方案。
6. SGLang 官方文档 —— https://docs.sglang.ai/

构建与部署

想把这本书转成 HTML 网站、PDF、EPUB，或者推到 GitHub Pages，详见 DEPLOY.md。常用命令：

python3 build_html.py      # → _site/  (含搜索 + Mermaid + KaTeX + 阅读时间)
python3 build_pdf_epub.py  # → _site/sglang-learning.pdf + .epub
./deploy_gh_pages.sh <repo-url>

如果你想把材料放别处，设环境变量 SGLANG_LEARNING_SRC / SGLANG_LEARNING_DST 即可。

关于 SGLang submodule

本仓库把 SGLang 上游作为 git submodule 挂载在 sglang/，当前固定到：

commit ed85bcf8c3639c20b7fd2970b607353db5c3abfa
        (gateway-v0.3.1-4559-ged85bcf8c, 2026-05)

第一次克隆：

git clone <this-repo-url>
git submodule update --init --recursive

更新到上游最新（注意：行号会漂，章节里的 file_path:line_number 索引会失效）：

cd sglang
git fetch origin
git checkout main && git pull
cd .. && git add sglang && git commit -m "Bump SGLang submodule"

贡献与扩展

发现 file_path:line_number 失效了？SGLang 主分支变化快，欢迎 PR 修正。

想新加一章？沿用每章统一的"章首导读 + 正文 + 小结/自检/下一步"模板，已写好的样板章节可作范例：

• 总览：01-overview/01-what-is-sglang.md
• 核心概念：02-core-concepts/01-radix-attention.md
• 源码走读：03-code-walkthrough/03-scheduler.md

开始读 01-overview/01-what-is-sglang.md。 或者从 00-prerequisites.md 铺前置。