7.1 从仓库入口回到请求主线

从仓库入口回到请求主线#

这章解决什么问题#

如果你第一次进入 SGLang 仓库，最容易犯的错误是直接钻进 python/sglang/srt。这样当然能看到大量核心实现，但你会很快失去“哪些入口是给用户的，哪些入口是给 runtime 的”这层方位感。更稳的读法，是先看四个文件：README.md、python/sglang/__init__.py、python/sglang/lang/api.py 和 python/sglang/launch_server.py。

README.md 的价值不是介绍所有内部细节，而是告诉你项目怎样向外描述自己。当前 README 直接把 “Backend Tutorial” 和 “Frontend Tutorial” 分开列出，这能帮助你先建立“双表面”认知。python/sglang/__init__.py 则把 public surface 展开成 import 入口：一边是 function、gen、system、user、assistant 等语言层 API，另一边是 RuntimeEndpoint、ServerArgs 与 Engine 这类运行时入口。

接着读 python/sglang/lang/api.py，你会看到 Runtime(...) 与 Engine(...) 都只是懒导入包装，而 gen(...) 则把 regex、json_schema、sampling 参数等语言层能力显式暴露出来。最后再看 python/sglang/launch_server.py，你就能把“language API”“offline engine”“server entrypoint”三类入口区分开，而不是把它们混成一个抽象的“调用 SGLang”。

为什么按这条顺序读仓库#

这样安排顺序，不是为了显得系统化，而是为了减少误读。仓库顶层目录天然混合了“对外表面”“核心 runtime”“示例与测试”“性能与扩展”四类材料。如果你没有先用几个稳定入口把外层地图建立起来，后面看到 entrypoints、managers、mem_cache、benchmark、sgl-kernel 时，就很难判断它们在整体叙事里分别扮演什么角色。

因此，这一章的真正设计理由，是先建立阅读顺序，再建立目录认识。你不是在背一个文件系统，而是在学习一套“从公开入口走回主链路，再从主链路走向扩展材料”的路径。只有这样，代码导读章节才和前面的 request lifecycle、runtime architecture、scheduling/memory 构成同一本书，而不是一组平行笔记。

回到 python/sglang/srt 时，先找五个目录#

带着入口感再回到 python/sglang/srt，阅读顺序会清楚很多。第一站看 entrypoints/，因为这里定义了 HTTP、gRPC、engine 等真正进入 runtime 的门。第二站看 managers/，因为请求状态、队列、批次、流式输出和大量运行时编排都在这里。第三站看 model_executor/，这里更接近模型前向与设备执行。第四站看 mem_cache/，这里解释请求状态如何映射到可复用的 KV 存储。第五站看 observability/，这里提供 metrics、trace 与 request stage 观测能力。

这样的顺序并不是唯一正确答案，但它和请求主线是对齐的：先找门，再找编排，再找执行，再找缓存，最后找观测。只要顺序不乱，仓库即使继续增长，你也不容易在一堆特性目录里迷失。

这里补图比纯文字更有效，因为仓库阅读顺序本质上就是一张“入口到子系统”的导航图。下面这张图承担的职责，是把“哪些目录先看、哪些后看、哪些是主链路、哪些是支撑材料”直接可视化。

flowchart LR
    A["README.md"] --> B["python/sglang/__init__.py"]
    B --> C["python/sglang/lang/api.py"]
    C --> D["python/sglang/launch_server.py"]
    D --> E["python/sglang/srt/entrypoints/"]
    E --> F["python/sglang/srt/managers/"]
    F --> G["python/sglang/srt/model_executor/"]
    F --> H["python/sglang/srt/mem_cache/"]
    F --> I["python/sglang/srt/observability/"]
    G --> J["examples/"]
    H --> K["test/"]
    I --> L["docs/"]
    J --> M["benchmark/ / sgl-kernel / sgl-model-gateway"]

这张图比前面的段落多解释了一点：docs/、examples/、test/ 并不是主链路之外的“杂项”，而是理解、使用和维护主链路时要不断回访的支撑材料。

docs、examples 与 test 各自回答什么问题#

很多人读源码时会低估仓库里非源码目录的价值。SGLang 不是只有 python/sglang。docs/ 负责回答“项目怎样面向外部解释自己”，examples/ 负责回答“这些能力最小怎样用起来”，test/ 负责回答“维护者认为什么行为必须被回归验证”。

从当前仓库看，docs/basic_usage/ 里有 OpenAI-compatible API、offline engine API、具体模型文档等；这些文件帮你理解产品表面和参数约定。examples/runtime/README.md 和 examples/runtime/engine/readme.md 则把常见工作流分成 server、engine、multimodal、token-in-token-out、custom server 等几类，是把内部能力映射成最小可运行场景的地方。examples/monitoring/README.md 还说明了 metrics 暴露后怎样接 Prometheus / Grafana。

test/README.md 的价值则更偏工程视角。它明确说明了 registered/、manual/、run_suite.py、srt/ 等测试区域的职责，以及 CI 是怎样发现和组织测试文件的。对理解维护成本来说，这些信息很重要：它告诉你仓库作者认为哪些路径需要长期回归保护，哪些目录属于历史包袱，哪些能力需要特殊硬件或 nightly 流程才能覆盖。

哪些目录属于性能扩展或旁路能力#

如果你只关心请求主链路，看到 benchmark/、sgl-kernel/、sgl-model-gateway/ 这些目录时很容易分不清优先级。一个实用判断是：这些目录大多不是“先理解请求是怎么跑起来”所必需的，而是“当你已经理解主链路之后，再去看性能、扩展和旁路能力”。

benchmark/ 里聚合了大量基准与实验脚本，适合在你已经知道 runtime 主要部件之后，再去看系统怎样被评估。sgl-kernel/ 更偏底层 kernel 与独立测试，不适合拿来建立第一层架构图。sgl-model-gateway/ 则属于另一条更偏服务网关与协议编排的能力线，读它之前最好已经知道核心 runtime 的边界在哪里。

一个更稳的仓库阅读顺序#

如果你准备持续读这个仓库，可以按下面的顺序推进：

  1. 先读 README.md、python/sglang/__init__.py、python/sglang/lang/api.py 和 python/sglang/launch_server.py，建立外部入口地图。
  2. 再读 python/sglang/srt/entrypoints/ 与 python/sglang/srt/managers/，把请求主链路和运行时编排走通。
  3. 然后读 python/sglang/srt/model_executor/ 与 python/sglang/srt/mem_cache/，把执行层和缓存层边界补齐。
  4. 最后再根据目的回到 docs/、examples/、test/、benchmark/、sgl-kernel/ 或 sgl-model-gateway/。

这样读的好处是，你不会把顶层目录当成平铺的文件系统，而会把它们理解成“公开表面、主链路、执行层、验证与扩展”四类不同材料。对一本设计与实现导读来说，这正是代码导读章节应该提供的那张地图。

本章对应哪些代码路径#

本章的核心锚点首先不是 srt 内部文件，而是 README.md、python/sglang/__init__.py、python/sglang/lang/api.py 和 python/sglang/launch_server.py 这四个入口。它们共同定义了“项目怎样面向外部出现”。在这之后，再顺着 python/sglang/srt/entrypoints/、python/sglang/srt/managers/、python/sglang/srt/model_executor/、python/sglang/srt/mem_cache/ 和 python/sglang/srt/observability/ 进入内部主链路。

要把这张地图和验证材料接起来，再补上 docs/basic_usage/、examples/runtime/README.md、examples/runtime/engine/readme.md、examples/monitoring/README.md 与 test/README.md 就足够了。这样一来，这一章就不只是“仓库里有什么”，而是明确回答了：为什么按这条顺序读，以及这些路径分别支持哪一类理解任务。