1.1 第一版范围与阅读地图

Mon, 01 Jan 0001 00:00:00 +0000

第一版范围与阅读地图#

这本书第一版解决什么问题#

第一版首先解决的是“如何建立一套不走偏的阅读顺序”。面对 SGLang 这样同时包含 language API、server entrypoint、runtime orchestration、memory cache、sampling、structured output 和 observability 的项目，直接从目录深处切入，很容易只看到局部机制，看不到系统为什么被组织成现在这样。

因此，第一版先追求一条稳定的主线，而不是面面俱到。它优先覆盖产品定位、frontend 心智模型、请求主链路、Serving 与 SRT 的边界，以及调度与 KV Cache 的基本配合关系。这样做的结果，是读者能先获得一张可靠的地图，再决定往哪个局部深挖。

为什么这样设计第一版范围#

从仓库约束看，这本书必须遵守“从外到内”的写法：先概览，再请求生命周期，再运行时架构，再调度与内存，再执行模型和结构化生成，最后才进入代码导读、扩展与调试。这不是形式要求，而是为了把“产品表面”和“内部实现”分层讲清楚。

同样重要的是，第一版必须控制非目标。它不会试图覆盖完整 API 手册、全部实验特性、所有硬件与后端适配细节，也不会把整个上游仓库写成逐文件百科。这里的基本判断是：一本能够发布的第一版，应该先把主干讲稳，而不是把枝叶都列出来。

阅读地图#

推荐阅读顺序是：先读 1.2 为什么是 SGLang：Frontend Language 与 Runtime 心智模型，确认系统的外部形态；再读 2.1 一次请求如何穿过 SGLang，把请求主链路走一遍；然后进入 3.1 Serving 层与 SRT 分层，理解控制面、入口层和核心执行层的边界。

如果你更关注实现性能与资源管理，可以在上述三章之后继续看 4. 调度与内存和 5. 执行模型。再往后是 6. 结构化生成与 API，它把约束生成和对外接口表面接回主链路；最后进入 7. 代码导读与 8. 扩展与调试，把阅读路径落回仓库和维护操作层。

本章对应哪些代码路径#

这一章本身不是源码细节章，所以代码路径映射只要求到目录级和模块级。第一版的主要锚点包括上游仓库顶层目录、README 中对“Backend Tutorial / Frontend Tutorial”的公开入口，以及 python/sglang/__init__.py 暴露的 public surface。

换句话说，这一章的功能不是带你读实现细节，而是告诉你后面读代码时该把哪些入口当成“地图坐标”。后续进入请求生命周期和运行时架构之后，代码路径才会进一步落到 launch_server、entrypoints、managers、mem_cache 等更具体的位置。

1.2 为什么是 SGLang：Frontend Language 与 Runtime 心智模型

Mon, 01 Jan 0001 00:00:00 +0000

为什么是 SGLang：Frontend Language 与 Runtime 心智模型#

它解决什么问题#

很多人第一次接触 SGLang，会先把它归类成一个“高性能推理服务框架”。这个理解并不算错，但不完整。因为从上游 README 和 public API 看，SGLang 同时把自己呈现成两类东西：一类是对外服务的运行时入口，另一类是直接被程序调用的 language-level API。

这个双重形态，正是本章要先讲清楚的问题。如果不先把它讲清楚，读者后面看到 sglang serve、python -m sglang.launch_server、Engine(...)、Runtime(...)、gen(...)、user(...)、assistant(...) 这些入口时，很容易把它们当成风格不同但本质相同的调用方式，而忽略它们其实落在不同抽象层。

为什么说它不只是一个 serving engine#

事实层面，上游 README 当前把 “Backend Tutorial” 与 “Frontend Tutorial” 分开列出；而 python/sglang/__init__.py 则同时导出 function、gen、system、user、assistant 这类语言层 API，以及 RuntimeEndpoint、ServerArgs、Engine 这类运行时入口。这说明 public surface 本身就已经分成了“描述生成流程的语言层”与“承载执行的运行时层”。

推断层面，这意味着 SGLang 的核心价值不只在“跑得快”，还在“把 prompt program、structured generation 与 runtime execution 接到一套统一表面上”。第一版在这里不会展开所有机制细节，但会先把这套双层心智模型钉住：语言层负责描述，运行时层负责承载，服务层负责暴露。

这套心智模型如何帮助后续阅读#

有了这个框架，后面的章节角色会清楚很多。2.1 一次请求如何穿过 SGLang 讲的是请求如何进入系统并跨过这些层之间的 handoff；3.1 Serving 层与 SRT 分层讲的是这些层各自负责什么，不负责什么。

同时，这套心智模型也约束了我们后面对源码的阅读方式。比如 python/sglang/lang/api.py 更适合被当作语言层入口来读，而 python/sglang/launch_server.py 与 python/sglang/srt/entrypoints/* 更适合被当作服务化入口与运行时入口来读。把这些入口混在一起，会让读者失去方向感。

1. 概览 on Machine Learning 学习笔记