第一章系统概览 on Machine Learning 学习笔记

1.1 SGLang 到底是什么

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

SGLang 到底是什么#

这一节先解决整本书最基础的问题：SGLang 到底应该被看成什么系统。只有这个问题先回答清楚，后面的请求路径、调度器和执行壳才不会被误读成彼此独立的局部实现。

它首先不是一个单一人格的项目#

很多系统对外只有一种主要形态，例如：

一个单纯的 HTTP server
一个单纯的 SDK
一个单纯的离线 engine

SGLang 不是这样。只要顺着最外层入口看一遍，你很快就会发现它同时暴露了三种不同的人格：

language API
python/sglang/lang/api.py 里的 gen(...)、user(...)、assistant(...)、system(...)
runtime / engine API
Engine、RuntimeEndpoint、ServerArgs
serving surface
sglang serve、python -m sglang.launch_server、OpenAI-compatible HTTP 接口

也就是说，SGLang 不是”先有一个 server，后来顺手加了点 API”；它从一开始就是一套同时面向 prompt program、runtime 承载和服务暴露的系统。

三种入口的实际代码对比#

先看三段可以真正运行的代码，再回来看它们共享什么。

入口一：Language API（描述式编程）

用 @sgl.function 把生成逻辑写成程序：

import sglang as sgl

@sgl.function
def classify_sentiment(s, text):
 s += sgl.system(“You are a classifier. Reply with one word: positive/negative/neutral.”)
 s += sgl.user(text)
 s += sgl.assistant(sgl.gen(“label”, max_new_tokens=5, regex=r”positive|negative|neutral”))

state = classify_sentiment.run(text=”The food was amazing!”, backend=sgl.RuntimeEndpoint(“http://localhost:30000”))
print(state[“label”]) # → “positive”

关键特征：@sgl.function 把生成意图（包括结构化约束 regex）直接写成 Python 函数，执行时异步分派给 runtime。

1.2 为什么不能只把它看成一个 server

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

为什么不能只把它看成一个 server#

很多人第一次接触 SGLang，会先把它放进“高性能推理服务”的类别里。这个切入点不完全错，但如果只停在这里，后面就会很难理解语言层 API、结构化生成和 engine 嵌入式用法为什么会和 serving 共享同一套内部对象。

“像 server” 的部分当然存在#

从外部表面看，把 SGLang 当作 server 并不奇怪：

你可以直接 sglang serve
可以用 OpenAI-compatible HTTP 接口请求它
它有路由、middleware、metrics、API key 和健康检查

所以“它像一个 server”这件事本身没有问题。问题在于，如果把这个结论升级成“它本质上只是一个 server”，你后面就会不断遇到解释不通的地方。

哪些现象说明它不只是 server#

最直接的几个现象是：

language API 是一等入口
gen(...)、system(...)、user(...) 并不是文档装饰，它们是系统正式暴露的编程接口。
engine / runtime 也是一等入口
Engine(...)、RuntimeEndpoint(...) 说明系统并不要求所有用法都绕 HTTP。
结构化约束直接进入生成主链
regex、json_schema、tool calling 并不是 server 外层附加功能，而会一路落到采样与执行路径。

这些现象都指向同一件事：server 只是 SGLang 的一个对外表面，而不是它唯一的系统定义。

这种误读会具体带来什么后果#

如果把它只看成 server，后面最常见的后果有三个：

把本应在 language API 理解的问题，硬塞回 HTTP request 视角；
把 GenerateReqInput、Req、ForwardBatch 这类运行时对象，误看成“HTTP 请求在内部的变种”；
把结构化生成、tool parser 和 Responses API 都看成“接口特性”，而忽略它们实际上深入到了 generation path。

一旦发生这三种误读，后面的章节虽然还能各自读懂，但整本书的主线会断。

1.3 全书主线、边界与核心不变量

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

全书主线、边界与核心不变量#

这一节负责把全书真正反复回扣的主线钉住。它不会提前展开全部实现，但会说明哪些对象、边界和运行时语义构成了后面章节共享的底板。

这本书写什么，不写什么#

这本书写的是：

请求怎样进入、排队、执行、回包；
这些路径在源码里分别落在哪些对象和文件上；
当系统出问题时，应该先回到哪条主线和哪组证据。

这本书不写的是：

所有模型、所有 backend、所有实验分支的百科式覆盖；
未经验证的性能结论；
把目录结构直接当作架构真相的强断言。

换句话说，这本书追求的是“稳定主线 + 稳定锚点”，不是“覆盖一切可能的局部知识”。

全书反复回扣的主线#

如果把全书压缩成一条最短主线，它其实就是：

请求怎样进入系统；
请求怎样被压成运行时对象；
请求怎样进入 queue、cache、execution；
结果怎样回到协议表面；
出了问题以后，证据链怎样重新回到这些对象和边界上。

这条主线之所以重要，是因为它决定了后面的章节顺序：

第二部分先走通请求路径；
第三部分再进入执行核心；
第四部分最后才回到代码导读、观测和维护。

如果没有这条主线，后面的章节就会更像平铺专题，而不像一本系统书。

哪些不变量必须在后文持续成立#

后面无论写哪一章，至少有四条东西应该持续成立。

不变量一：请求对象会变形，但不会失去边界#

请求会一路变化：

ChatCompletionRequest
GenerateReqInput
ReqState
TokenizedGenerateReqInput
Req
ScheduleBatch
ForwardBatch

但每一层都必须仍然有明确职责。后文如果把这些对象混着讲，这条不变量就被破坏了。

不变量二：控制面和数据面必须分得开#

session、abort、priority、weight update、logging configuration 这些更像控制面；batch、KV cache、forward、sampling、text delta 则更像数据面。两者会互相影响，但不应该被写成同一个层次的问题。

不变量三：运行时边界比目录边界更重要#

后面不断会出现：

TokenizerManager
Scheduler
DetokenizerManager
ModelRunner

这些边界不是因为目录刚好这么分，而是因为运行时真的靠这些边界在推进状态。全书后面必须一直把它们当成正式边界，而不是方便记忆的模块名。

不变量四：观测和证据必须能回到主线#

RequestStage、ReqTimeStats、request logger、trace、dump、profile、tests 这些内容，后面都不应该变成“独立工具箱”。它们存在的意义，是把排障和维护重新接回请求主线和运行时边界。

读每章时都该反复问的三个问题#

为了把这组不变量真正变成阅读工具，而不是抽象口号，可以把它压成三个固定问题：

这一章主要保护哪条不变量？
如果这条不变量被打破，系统会先表现成什么症状？
哪个源码锚点最能证明这条不变量存在？

只要对每章都能回答这三个问题，整本书就不容易被读散。

为什么这一节必须放在最前面#

如果这些范围和不变量不先说清楚，后面读到某一章时你很容易犯两种错误：

看到局部细节就把它当成全书中心；
看到后面的证据链又把它当成新的旁支专题。

把不变量先立起来的好处，是后面每一章都知道自己在护哪一层，不需要临时再给自己找存在理由。

第一章 系统概览 on Machine Learning 学习笔记

1.1 SGLang 到底是什么

SGLang 到底是什么#

它首先不是一个单一人格的项目#

三种入口的实际代码对比#

1.2 为什么不能只把它看成一个 server

为什么不能只把它看成一个 server#

“像 server” 的部分当然存在#

哪些现象说明它不只是 server#

这种误读会具体带来什么后果#

1.3 全书主线、边界与核心不变量

全书主线、边界与核心不变量#

这本书写什么，不写什么#

全书反复回扣的主线#

哪些不变量必须在后文持续成立#

不变量一：请求对象会变形，但不会失去边界#

不变量二：控制面和数据面必须分得开#

不变量三：运行时边界比目录边界更重要#

不变量四：观测和证据必须能回到主线#

读每章时都该反复问的三个问题#

为什么这一节必须放在最前面#

第一章系统概览 on Machine Learning 学习笔记