《Sglang 设计与实现》#

这本书的目标不是把 SGLang 写成一份 API 手册，也不是把整个仓库逐目录翻译成中文。第一版更像一条可复用的理解路径：先建立产品与系统心智模型，再进入请求主链路、运行时分层、调度与内存、执行模型、结构化生成与接口表面，最后再回到代码导读、扩展点和调试抓手。

这也意味着本书会主动控制范围。凡是没有经过源码、官方文档或上游公开入口核实的性能数字、架构结论、实现细节，本书都不会写成确定事实。需要推断时，会明确标出“推断”，避免把工作性理解伪装成源码结论。

这本书回答什么#

第一版重点回答三个问题。第一，SGLang 到底是一个什么样的系统，为什么它既像 frontend language，又像 serving/runtime surface。第二，一次请求是如何进入、分发、执行并返回结果的。第三，阅读上游仓库时，应该优先盯哪些模块、哪些入口、哪些 handoff 点。

与此对应，本书每一章都尝试回答同样的三个子问题：它解决什么问题，为什么这样设计，以及这件事落在哪些代码路径上。这样做的目的，是让“理解设计”与“回到代码”之间保持双向映射，而不是只停留在概念描述。

章节地图#

这本书当前按八个 section 组织。你可以把它们当成一组带顺序的 landing page：先用前四章建立主线，再按兴趣进入后四章。

1. 概览：锁定第一版范围、阅读顺序和 frontend language / runtime 的双层心智模型。
2. 请求生命周期：把请求从入口到 handoff 的主链路先走通。
3. 运行时架构：解释 serving surface、SRT 与内部模块边界的工作性划分。
4. 调度与内存：收束 scheduler、batch 与 KV Cache 的关系。
5. 执行模型：单独处理 token generation loop、decode 与 sampling 的角色。
6. 结构化生成与 API：把 constrained decoding、schema/tool parser 与外部接口表面分开看。
7. 代码导读：把前面的心智模型映射回仓库目录、关键模块和测试样例。
8. 扩展与调试：收束观测、排障、扩展点与回归验证抓手。

下面这张图不是装饰，它解决的是“整本书到底按什么层次展开”的理解障碍。相比纯文字列表，它把“哪几章先建立心智模型，哪几章再落向实现和维护”直接画成了一条可视路径。

flowchart LR
    A["1. 概览<br/>范围、读法、Frontend 心智模型"] --> B["2. 请求生命周期<br/>请求如何进入与回包"]
    B --> C["3. 运行时架构<br/>Serving / SRT / managers / executor"]
    C --> D["4. 调度与内存<br/>Scheduler / ScheduleBatch / KV cache"]
    D --> E["5. 执行模型<br/>ForwardBatch / ModelRunner / sampling"]
    E --> F["6. 结构化生成与 API<br/>约束解码 / OpenAI-compatible / native"]
    F --> G["7. 代码导读<br/>从入口回到仓库主线"]
    G --> H["8. 扩展与调试<br/>metrics / trace / replay / extension"]

读这张图时，最重要的不是记住标题，而是看清“从外到内”的推进顺序。前四章负责把系统工作方式立起来，后四章负责把这套理解映射回执行模型、接口表面、仓库结构和维护路径。后文每一章出现的图，都会尽量沿着这条顺序继续细化。

阅读方式#

如果你第一次接触 SGLang，建议从 1. 概览开始，先读“第一版范围与阅读地图”和“为什么是 SGLang：Frontend Language 与 Runtime 心智模型”。读完这两章之后，再进入 2. 请求生命周期和 3. 运行时架构，把整体数据流与模块边界先框起来。

如果你已经在读上游仓库，想更快地建立源码抓手，可以把本书当成一份导航层。先看概览，再顺着请求路径去找 launch_server、entrypoints、managers、model_executor、mem_cache 这些关键区域。等主线稳住之后，再回到 4. 调度与内存、5. 执行模型和 7. 代码导读，把“为什么这样组织”与“代码具体在哪”接起来。