第三章请求路径 on Machine Learning 学习笔记

3.1 从 /v1/chat/completions 到 Scheduler

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

从 `/v1/chat/completions` 到 `Scheduler`#

这章解决什么问题#

如果你只从 API 表面看 SGLang，很容易把 /v1/chat/completions 理解成一个普通的 FastAPI 路由：接收一个 JSON，请求进入模型，最后吐出字符串。这个理解能帮助你调用接口，但几乎不能帮助你读源码。因为从源码角度看，这条链路真正重要的不是 HTTP，而是请求对象怎样一步步从“协议形态”收缩成“运行时形态”。

更准确地说，这一章主要回答四个问题：

OpenAI-compatible 请求是在什么地方结束协议层处理的。
统一的 runtime 请求对象是怎样建立起来的。
TokenizerManager 在这条链里到底承担了什么职责。
请求到了 scheduler 以后，是在哪一步真正变成运行时工作单元 Req。

沿着这条链读，更稳的做法不是把它看成五个彼此独立的函数，而是看成一组按顺序演化的请求对象：

ChatCompletionRequest -> GenerateReqInput -> ReqState established -> TokenizedGenerateReqInput -> Req

一张图先看完整主线#

如果先不陷进局部代码细节，这条链更适合先压成“分层边界”来看：

flowchart TB
 subgraph Protocol["协议层"]
 A["/v1/chat/completions<br/>ChatCompletionRequest"]
 end

 subgraph APIServer["API server / serving 层"]
 B["OpenAIServingBase.handle_request"]
 C["OpenAIServingChat._convert_to_internal_request"]
 D["GenerateReqInput"]
 end

 subgraph Bridge["TokenizerManager 边界层"]
 E["ReqState"]
 F["TokenizerManager._tokenize_one_request"]
 G["TokenizedGenerateReqInput"]
 end

 subgraph Runtime["Scheduler / runtime 层"]
 H["Scheduler.handle_generate_request"]
 I["Req"]
 J["grammar / queue / batch"]
 end

 A --> B --> C --> D
 D --> E
 D --> F --> G
 G --> H --> I --> J

这张图最值得记住的一点是：TokenizerManager 不是简单的“协议后、scheduler 前”中转站，而是一条正式边界。ReqState 和 TokenizedGenerateReqInput 都从这里分化出来。

3.2 Streaming 与回包组装

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

Streaming 与回包组装#

3.1 讲到请求被 scheduler 接管为止。这一节补的是后半段：scheduler 已经产出了 token 级结果以后，结果怎样回到 API server，怎样被逐步解码成文本，又怎样被组装成 streaming chunk 或完整响应。

这一节只关注四个问题：

scheduler 输出的到底是什么。
DetokenizerManager 怎样把 token ids 变成字符串增量。
TokenizerManager 怎样把返回结果折叠回 ReqState。
serving 层怎样基于同一份后端状态分出 streaming 和 non-streaming 两种响应路径。

一张图先看返回主线#

先把这一节要讲的链路压成一张图：

flowchart TB
 A["Scheduler<br/>BatchTokenIDOutput"] --> B["DetokenizerManager<br/>增量 detokenize"]
 B --> C["BatchStrOutput"]
 C --> D["TokenizerManager._handle_batch_output<br/>回填 ReqState"]
 D --> E["TokenizerManager._wait_one_response"]
 E --> F["streaming SSE chunks"]
 E --> G["full ChatCompletionResponse"]

这张图里最重要的一点是：scheduler 并不直接回文本。它先回 token ids 和一组伴随的 meta 信息，然后由 detokenizer 和 API server 侧状态层一起完成后面的收口。

如果把这条返回链再压成“对象怎样变化”，可以得到更清楚的第二张图：

flowchart LR
 A["BatchTokenIDOutput<br/>token ids + finish/meta"] --> B["BatchStrOutput<br/>text delta + output_ids + meta"]
 B --> C["ReqState<br/>text / output_ids / time_stats"]
 C --> D["streaming chunk"]
 C --> E["full response"]

第一张图强调进程边界，第二张图强调返回对象的变化顺序。两张图合起来，基本就把这一节的主线钉住了。

3.3 Session、timeout 与 abort 分叉

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

Session、timeout 与 abort 分叉#

3.1 和 3.2 讲的是最小主链：请求怎样进入 runtime，结果又怎样回到协议表面。但真实系统里并不只有这条标准路径。session、timeout 和 abort 都会改变请求对象的命运，而且它们改变的不是“输出样式”，而是请求到底还能不能沿主链继续走下去。

这一节只处理三类正式分叉：

session 会改写 Req 的构造方式；
timeout 会改写请求结束的阶段；
abort 会从 API server、client 或 scheduler 不同方向切断主链。

一张图先看分叉#

先把这几条分叉压成一张图：

flowchart TB
 A["标准生成请求"] --> B["进入 tokenizer / scheduler 主链"]
 A --> C["带 session_params"]
 C --> D["Session.create_req<br/>复用前缀 / append / replace"]
 A --> E["client disconnect / explicit abort"]
 E --> F["TokenizerManager.abort_request"]
 A --> G["waiting timeout / running timeout"]
 G --> H["Scheduler abort paths"]

这张图里最重要的一点是：session、timeout 和 abort 都不是主链末尾的补丁，而是会直接改写请求路径和对象状态的正式分叉。

3.4 Batch、多 worker 与多模态路径

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

Batch、多 worker 与多模态路径#

3.1 和 3.2 都是按“单请求、单 worker、纯文本”这个最小闭环来讲的。这一节补的是把这条闭环放大之后会发生什么：当请求变成 batch、当 tokenizer worker 不止一个、当输入不再只有文本，这条路径会在哪些 handoff 点上变形。

这一节只关心三个变化：

batch 如何改变发送和回包方式；
多 tokenizer worker 如何改变 request routing 和 response routing；
多模态输入如何改变 tokenization 之前的准备阶段。

一张图先看放大后的主线#

flowchart TB
 A["GenerateReqInput<br/>batch / multimodal"] --> B["TokenizerManager"]
 B --> C["single request path"]
 B --> D["batch request path"]
 B --> E["multi-worker routing"]
 B --> F["mm_processor / encoder path"]
 D --> G["BatchTokenizedGenerateReqInput"]
 E --> H["http_worker_ipc / SenderWrapper"]
 F --> I["mm_inputs / input_ids rewrite"]

这张图里最重要的一点是：放大后的路径不是“原主链复制很多份”。一旦进入 batch、多 worker 或 multimodal 模式，输入对象、发送方式和回包对位方式都会发生变化。

3.5 Embedding 与 Reranking 路径

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

Embedding 与 Reranking 路径#

3.1 到 3.4 讲的都是生成式请求：模型一步步生成 token，直到 stop 或 length 触发。但 SGLang 还支持另外两类完全不同的执行路径：Embedding（把文本压缩成向量）和 Reranking（对查询-文档对打分）。这两类路径没有生成循环，不需要 KV cache，执行逻辑和返回对象都和生成路径有本质差异。

这一节回答三件事：

Embedding 和 Reranking 请求走的是什么路径，和生成请求有哪些分叉；
ModelRunner 在这两类请求里实际执行的是什么；
输出对象是什么形态，怎样回到 API 表面。

生成 vs Embedding：两种完全不同的任务模式#

先把两种模式的差异压成一张对比表：

	生成（Generation）	Embedding
任务目标	输出 token 序列	输出向量表示
执行方式	prefill + decode 循环	一次 forward pass
KV cache	需要（decode 复用前缀）	不需要
输出	token ids / 文本	浮点向量 `[hidden_size]`
API 入口	`/v1/chat/completions`	`/v1/embeddings`
模型类型	decoder-only LLM	encoder-only 或 decoder-only

最重要的一点是：Embedding 请求只有 prefill，没有 decode 循环。模型跑完一次前向，从 last_hidden_state 或 pooler_output 里取出向量，直接回包。因为没有 decode，KV cache 在这条路径上几乎没有价值。

第三章 请求路径 on Machine Learning 学习笔记

3.1 从 /v1/chat/completions 到 Scheduler

从 /v1/chat/completions 到 Scheduler#

这章解决什么问题#

一张图先看完整主线#

3.2 Streaming 与回包组装

Streaming 与回包组装#

一张图先看返回主线#

3.3 Session、timeout 与 abort 分叉

Session、timeout 与 abort 分叉#

一张图先看分叉#

3.4 Batch、多 worker 与多模态路径

Batch、多 worker 与多模态路径#

一张图先看放大后的主线#

3.5 Embedding 与 Reranking 路径

Embedding 与 Reranking 路径#

生成 vs Embedding：两种完全不同的任务模式#

第三章请求路径 on Machine Learning 学习笔记

从 `/v1/chat/completions` 到 `Scheduler`#