扩展点与维护路径#

这章解决什么问题#

这一章解决的是“如果你不只是阅读 SGLang，而是准备修改它，应该从哪里下手”。这包括两类常见需求：一类是功能扩展，例如支持新模型、调整 parser、增加协议适配；另一类是维护性工作，例如加测试、跑回归、按贡献流程提交变更。

如果没有这一章，前面的章节会把系统讲清楚，但读者仍然会缺少一个问题的答案：知道系统怎么工作之后，下一步怎样安全地改它。这也是为什么本章要放在最后，它更像“把理解转成可操作路径”的收束章。

为什么扩展点不能只靠目录猜#

目录当然能给提示，但真正的扩展点最好看官方维护文档。docs/supported_models/extending/support_new_models.md 明确说明：支持新的语言模型，通常只需要在 python/sglang/srt/models 下增加一个文件；如果是多模态模型，还要额外考虑 model_config.py、conversation.py、multimodal processor、image feature extraction 和 multimodal token 处理等组件。

这比简单说“去 models 目录改”更有价值，因为它告诉你：扩展点不仅是文件位置，还包括一组必须一起成立的适配面。也正因为这样，本章不会把“支持新模型”简化成单点改动，而会把它当作一条跨模块路径来讲。

扩展路径本身也适合用图来收束，因为它横跨文档、源码和测试。下面这张图回答的是：一个“想改 SGLang”的工程任务，通常会穿过哪些入口，而不是停留在哪个单独目录。

flowchart LR
    A["扩展目标\n新模型 / 新协议 / 新 parser / 新 hook"] --> B["阅读入口\nsupport_new_models.md\ncontribution_guide.md\ntest/README.md"]
    B --> C["源码扩展面\nmodels / entrypoints / parser / multimodal"]
    C --> D["验证路径\nunit tests / server tests / bench_one_batch / benchmark"]
    D --> E["贡献路径\npre-commit / CI / PR / review"]

这张图比纯文字多解释了一点：扩展并不是“改完源码再说”，而是一条从设计入口到验证入口再到贡献入口的闭环。也正因为这样，本章会把测试和贡献流程看成扩展点的一部分，而不是附录。

模型扩展与协议扩展分别落在哪里#

模型扩展更偏 python/sglang/srt/models/、相关 config、processor 和测试路径。support_new_models.md 还给出了调试建议：用 Hugging Face 参考输出与 python3 -m sglang.bench_one_batch --correct --model ... 进行对比，并把模型加入测试套件与 benchmark。这说明扩展不是只让代码“能跑”，而是要让它进入长期维护路径。

协议或服务表面的扩展，则更可能落在 python/sglang/srt/entrypoints/、parser、conversation / chat template 等区域。例如文档里多次提到 OpenAI-compatible API、custom chat template、tool parser 和 gateway path，这些都属于“不是改模型本体，但会改变系统对外行为”的扩展面。

为什么测试和贡献路径也属于扩展点的一部分#

从 test/README.md 和 docs/developer_guide/contribution_guide.md 看，SGLang 对“怎么改”是有明确工程约束的：新增功能应当补测试，CI 有阶段与 suite，unit tests 与 server-required tests 分开，贡献前要跑 pre-commit、必要时跑 accuracy test 和 benchmark。对 runtime 项目来说，这些不是外围流程，而是扩展点的一部分。

原因很简单：很多改动即使接口正确，也可能在调度、缓存或性能上引入回归。如果你把“扩展能力”只理解成改源码，而忽略了测试与贡献流程，那你实际扩展的是一个不稳定分支，而不是项目本身。

一个更稳的进入顺序#

如果你准备对 SGLang 做真实改动，可以按下面的顺序进入：

先用前面章节建立主链路和模块边界认识。
再根据目标选择扩展面：模型、协议、parser、observability 或测试。
进入对应文档与源码锚点，例如 support_new_models.md、test/README.md、contribution_guide.md、python/sglang/srt/models/、python/sglang/srt/entrypoints/。
最后再回到回归与 benchmark，确认改动不仅“能工作”，而且“能被维护”。

这个顺序的核心，不是让你慢一点，而是减少方向错误。对于这样的 inference runtime，改错入口比写慢几小时代价更大。

如果你真的准备改这里，要先小心什么#

对模型扩展来说，最危险的不是“类没写出来”，而是“看起来能跑，但没有进入正确的测试与 benchmark 路径”。对协议扩展来说，最危险的不是接口没通，而是把协议层逻辑悄悄渗进 runtime 主链路，导致后续维护越来越难。

因此，这一章最想提醒读者的一点是：扩展不是只改代码，还要同时想清楚验证路径。你准备改哪一层，就应该同步知道改完后拿什么证明它仍然成立。这也是为什么本章把 support_new_models.md、test/README.md 和 contribution_guide.md 放在同一条扩展闭环里。

一个更接近现实工程的收束#

真正让一章像技术书而不是专栏的，往往是最后这一类提醒：当你带着“我要改这里”的心态离开这一章时，脑子里应该同时带走两条路径，一条是“源码入口在哪里”，另一条是“验证入口在哪里”。如果只带走前者，你得到的是 hack path；两条都带走，你得到的才是 maintainer path。

一个最小扩展清单#

把这一章落成可操作清单之后，最少可以记住下面四件事：

1. 先确认改动属于模型扩展、协议扩展还是调试/观测扩展
2. 先找官方维护文档里的入口，不要只靠目录猜
3. 改源码之前同步确认测试和 benchmark 的验证路径
4. 把“能跑”升级成“能维护、能回归、能提交”

这类清单看起来简单，但它正是很多优秀技术书和普通专栏的差别所在：它不只给读者理解，还给读者一个能带走的动作框架。

从“能改”到“改得稳”的距离#

对很多系统来说，写出第一版 patch 并不难，真正难的是把 patch 放进长期维护轨道。SGLang 这种 runtime 更是如此，因为很多变化会穿过模型支持、请求主链路、缓存状态、协议表面和测试路径。一个改动只要落在这些路径的交界处，就很容易出现“看起来能工作，但以后不好维护”的问题。

因此，本章真正想把读者从“会动手”推进到“会维护”。这也是为什么它会一直反复强调：改动入口和验证入口必须一起出现。对一本好技术书来说，最后一章能否让读者形成这种维护者视角，往往比再增加几个 API 参数解释更重要。

本章对应哪些代码路径#

这一章最重要的锚点包括 docs/supported_models/extending/support_new_models.md、docs/developer_guide/contribution_guide.md、test/README.md、python/sglang/srt/models/、python/sglang/srt/entrypoints/、python/sglang/srt/parser/ 与 python/sglang/srt/multimodal/。

如果你进一步追模型扩展，可以从 support_new_models.md 指向的 python/sglang/srt/models/*.py、model_config.py、conversation.py 和相关测试文件出发；如果追服务表面或协议适配，则更适合先看 entrypoints、parser、template 和 API 文档的对应锚点。

小结#

扩展点这一章真正想传达的是：SGLang 的“可扩展”不是一句抽象特性，而是一组已经被文档、源码目录和测试流程共同定义出来的入口。理解这些入口之后，你就不只是能读这套系统，也能更稳地改这套系统。