全书术语表与易混概念对照#

这章解决什么问题#

书一旦变厚，最先失去稳定性的通常不是局部事实，而是对象边界。尤其在 SGLang 这种系统里，很多词会在不同章节反复出现，但它们并不站在同一抽象层。只要口径稍微漂移，读者就会在章节之间反复重建自己的对象模型，最终把“回扣”读成“混乱”。

这一章的作用，就是把全书里最关键、最容易混淆的一批术语统一收口。它不提供新的机制细节，而是提供一套总坐标：当你在后文再次看到 Req、ForwardBatch、response_format 或 TTFT 时，应该立即知道它们属于哪一层、不要和什么混读、需要回到哪几章继续追。

把这一章当成全书总词表，而不是一次性读完就结束的前言。更实用的用法通常是：

优秀技术书里的术语表，真正提供的不是名词解释，而是认知止损能力。这一章承担的正是这个职责。

术语	主层次	更像什么	不要和什么混读
`ReqState`	入口 / 回包层	API server 与 `TokenizerManager` 侧的请求状态容器	不要把它当成 scheduler 主语
`Req`	调度 / 执行层	单请求运行时本体，持有 `fill_ids`、`output_ids`、前缀和 KV 相关状态	不要把它当成 HTTP 回包状态
`rid`	跨层标识	单请求身份锚点	不等于 batch 内部位置

更稳的记法是：ReqState 偏“调用方还在等什么”，Req 偏“系统还在推进什么”。

术语	主层次	更像什么	不要和什么混读
`ScheduleBatch`	scheduler 侧	哪些请求一起推进、当前 batch 怎样成形	不等于 tensor 级执行对象
`ModelWorkerBatch`	worker 交界层	从调度视图裁出来、只保留 worker 真正需要的子集	不要把它单独当作调度主语
`ForwardBatch`	`ModelRunner` 侧	执行视图，含 `ForwardMode`、positions、spec 信息和采样元数据	不要把它当成 waiting queue 的延续

更稳的记法是：ScheduleBatch 偏调度，ForwardBatch 偏执行，中间还有一层 worker façade。

术语	主层次	更像什么	不要和什么混读
`TokenizerManager`	请求入口与回包收敛	请求入口、`rid_to_state`、streaming 等待和部分证据链收口点	不只是 tokenizer
`DetokenizerManager`	输出尾部	token 到文本的收口层，管理 `decode_status`、stop trim 和 grouped decode	不只是字符串后处理
`TpModelWorker`	scheduler 与执行壳之间	worker façade，承接 batch 和各类控制动作	不等于模型本体
`ModelRunner`	执行中枢	模型、KV cache、attention backend、`forward()` / `sample()` 汇合点	不只是 `model.forward()` 的薄封装

更稳的记法是：manager 讲编排与回包，worker 讲执行外壳，runner 讲执行内核汇合点。

术语	主层次	更像什么	不要和什么混读
`prefix_indices`	请求视图	当前请求“已经能复用的前缀视图”	不一定等于树缓存正式保护的长度
`cache_protected_len`	所有权边界	已被 prefix cache 正式接管的那一段	不等于 `len(prefix_indices)`
`host_hit_length`	分层命中说明	有多少前缀来自 host / storage 命中并回灌	不等于纯 device hit
`ReqToTokenPool`	请求到账本	逻辑请求位置到 token 槽位的映射层	不等于真正的物理 KV 存储
`TokenToKVPoolAllocator`	槽位管理	物理 KV index 分配器	不要和 prefix tree 混成一层

更稳的记法是：前缀命中首先是请求视图，其次才是所有权与物理占用。

术语	主层次	覆盖什么	不要和什么混读
`queue_time`	调度等待	从进入 scheduler 等待到真正进 forward 前的切片	不等于总延迟
TTFT	用户首感知	`first_token_time - created_time`	不等于纯 prefill latency
`response_sent_to_client_time`	对外发送边界	系统最后一次把结果送出给调用方的时刻	不等于内部 finished 边界
`finished_time` / `request_finished_ts`	内部完成边界	系统认为请求真正结束的时刻	不等于客户端已看到最后一个 chunk
`e2e_latency`	总体耗时	端到端时长	不等于模型执行时间

更稳的记法是：TTFT 讲“第一次看到”，response_sent_to_client_time 讲“最后一次送出”，finished_time 讲“系统内部正式收尾”。

术语	主层次	更像什么	不要和什么混读
`response_format`	协议约束层	最终输出形状约束	不等于 tool 选择策略
`tool_choice`	工具调用策略层	是否必须走工具回路、工具集如何被裁剪	不等于 grammar backend
grammar backend	约束执行层	约束对象怎样存活、推进、回滚	不等于 parser
`tool parser`	解释层	把模型输出解释成可消费的 tool call 结构	不等于约束对象
`SamplingParams`	收口层	协议字段、约束和采样语义最终汇合的参数对象	不要只把它看成 sampling 配置

更稳的记法是：一个决定约束空间，一个决定工具策略，一个负责解释输出，一个负责把它们统一落成执行参数。

术语	主层次	更像什么	不要和什么混读
`RequestStage` / `ReqTimeStats`	时间语义层	请求阶段切片与统一时间线	不只是 trace 标签集合
`RequestLogger`	请求完成日志层	把 finished request 结构化落盘	不等于 crash replay
request dump / crash dump	复现场景层	线上样本或崩溃前窗口材料	不等于 metrics
schedule simulator	离线实验层	用已记录请求做调度策略实验	不等于完整 runtime replay

更稳的记法是：观测工具先分“时间线、完成日志、复现场景、离线实验”，再决定先抓哪一类。

下面这些词最容易成对混读，读到后面时尤其值得反查：

如果你发现自己在某一章里又开始把这几对词混起来，通常不是那一章本身有问题，而是需要先回到这里重新校准对象边界。

这一章最常回扣的，不是概览，而是后面的三类正文：

也就是说，这一章真正的角色不是“概览的最后一页”，而是全书后半程反复要回来的总词表。

如果把整本书看成一条不断回扣的系统主线，这一章的职责就是防止回扣变成漂移。它不负责提供新机制，而负责让同一个对象在不同章节出现时，仍然站在同一条稳定坐标轴上。

优秀技术书很少靠“每章发明新术语”来显得高级。更成熟的写法，恰恰是把少量核心对象反复讲透，并始终保持同一套命名和边界。这一章服务的就是这个目标。