第十章扩展点与维护策略 on Machine Learning 学习笔记

10.1 安全扩展边界

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

安全扩展边界#

这一节会回答"哪些层适合扩展，哪些层一动就容易破坏不变量"，把扩展动作从"能改"提升到"知道该改哪里"。

为什么要先讲边界再讲扩展#

对大型 runtime 来说，最大的风险通常不是"不会改"，而是"改错层"。如果边界判断错了，你很可能写出一个能工作、但很快就会污染主链的 patch。

下面用具体文件路径把安全层和危险层说清楚。

安全扩展层：协议表面#

代表路径：python/sglang/srt/entrypoints/openai/

这里是 OpenAI-compatible API 的协议转换层：protocol.py 定义请求/响应结构，serving_chat.py、serving_completions.py 等文件把 HTTP 请求转换成内部对象。

为什么安全：这层的改动不会影响 Req 的生命周期、不会改变调度判断，只影响"协议层怎样呈现能力"。

典型安全扩展：在 ChatCompletionRequest 里加一个新的可选字段（比如 cache_hint），然后在 to_sampling_params() 里把它映射到内部参数。整个改动局限在 protocol.py 一个文件，不需要改 scheduler.py 或 model_runner.py。

# protocol.py 里的安全扩展示例
class ChatCompletionRequest(BaseModel):
 # ... 已有字段 ...
 cache_hint: Optional[str] = None # 新增可选字段

 def to_sampling_params(self) -> SamplingParams:
 # ... 已有逻辑 ...
 if self.cache_hint:
 sampling_params["cache_key"] = self.cache_hint
 return SamplingParams(**sampling_params)

这类改动的回归路径也很短：只需要测试 ChatCompletionRequest 的序列化/反序列化和 to_sampling_params() 的输出，不需要跑完整的调度回归。

安全扩展层：模型适配面#

代表路径：python/sglang/srt/model_executor/model_runner.py 和 models/ 目录

添加一个新模型架构，只需要在 models/ 里实现标准接口（forward、load_weights 等），然后在模型注册表里登记。这不会改变 ModelRunner 怎样调度 batch，也不会改变 KV cache 的分配逻辑。

10.2 回归验证与测试路径

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

回归验证与测试路径#

这一节把"改了什么就跑哪些测试"这件事具体化，避免每次改 scheduler、cache 或 parser 都靠临时经验拼验证。

测试目录结构#

SGLang 的测试集中在两个位置：

test/
└── srt/ # runtime 相关测试
 ├── test_serving_chat.py # OpenAI-compatible chat 接口回归
 ├── test_serving_completions.py # 文本补全接口回归
 ├── test_radix_cache.py # RadixCache 单元测试
 ├── test_grammar_backend.py # grammar constraint 测试
 ├── test_chunked_prefill.py # chunked prefill 正确性
 ├── test_speculative_decoding.py # speculative decoding 回归
 ├── test_torch_compile.py # torch.compile 集成
 └── test_bench_latency.py # 延迟 benchmark

test/srt/ 里的测试分三类：

接口回归（test_serving_*.py）：发真实 HTTP 请求，验证响应格式和内容正确性；
单元测试（test_radix_cache.py 等）：直接调用内部类，验证局部逻辑；
Benchmark（test_bench_latency.py 等）：度量性能指标，不做 assert。

按改动类型选测试#

改动：协议层（`entrypoints/openai/protocol.py` 或 `serving_*.py`）#

最小验证：

10.3 版本升级与长期维护

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

版本升级与长期维护#

这一节从长期维护角度回看这本书本身和上游仓库：版本升级时哪些结论最容易漂移，哪些锚点需要优先复核，以及怎样用最小代价判断一章的内容是否仍然成立。

升级时最容易漂移的东西#

这本书当前绑定的版本是 SGLang v0.5.10（commit 1519acf37c23f2189adb93f57ca9cd2db1bebf18）。不同类型的内容在版本升级时的漂移速度很不一样：

漂移最快（小版本就可能变）：

SamplingParams 的具体字段。字段增减、默认值调整、互斥约束变化是最高频的 API 变动。本书引用了 json_schema、regex、ebnf、structural_tag 等字段，这些都需要在新版本里确认仍然存在且语义没有变化。
ChatCompletionRequest.to_sampling_params() 的映射逻辑。这个函数把协议层字段翻译成内部参数，任何新增的 response_format 类型都会改变这里的逻辑。
Prometheus metrics 名称（sglang:num_running_reqs 等）。这些名称在 minor 版本里偶尔会被重命名或拆分。

漂移中等（大版本可能变）：

三管理器的进程拓扑（TokenizerManager / Scheduler / DetokenizerManager）。这个架构在 v0.5.x 里相对稳定，但如果引入 disaggregated prefill 等特性，拓扑会发生变化。
ForwardBatch 的字段集合。执行层的核心对象，字段语义比名称更稳定，但新并行策略可能引入新字段。
RadixCache 的对外接口（match_prefix / insert / evict 的参数类型）。

漂移慢（跨大版本仍成立）：

核心设计原则：Radix tree 的 prefix reuse 机制、KV cache 两级池设计、NCCL AllReduce 的 TP 模式。这些是深层架构决策，不会轻易改变。
Megatron-LM 风格的 column/row parallel 切分方式。
Grammar constraint 的 token mask 机制（DFA/PDA 编译 + per-step bitmask）。

快速检查：一章的内容是否仍然成立#

对每一章，有一个最快的验证方法：找到书里提到的最关键的函数或字段，在新版本的源码里 grep。

第十章 扩展点与维护策略 on Machine Learning 学习笔记

10.1 安全扩展边界

安全扩展边界#

为什么要先讲边界再讲扩展#

安全扩展层：协议表面#

安全扩展层：模型适配面#

10.2 回归验证与测试路径

回归验证与测试路径#

测试目录结构#

按改动类型选测试#

改动：协议层（entrypoints/openai/protocol.py 或 serving_*.py）#

10.3 版本升级与长期维护

版本升级与长期维护#

升级时最容易漂移的东西#

快速检查：一章的内容是否仍然成立#

第十章扩展点与维护策略 on Machine Learning 学习笔记

改动：协议层（`entrypoints/openai/protocol.py` 或 `serving_*.py`）#