第八章代码库导读 on Machine Learning 学习笔记

8.1 如何从入口开始读仓库

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

如何从入口开始读仓库#

这一节会把"第一次打开仓库应该先看哪里"这件事流程化，同时告诉你在每个文件里应该具体找什么。

为什么仓库入口顺序很重要#

如果你第一次进入 SGLang 仓库，最容易犯的错误是直接钻进 python/sglang/srt。这样当然能看到大量核心实现，但你会很快失去"哪些入口是给用户的，哪些入口是给 runtime 的"这层方位感。

第一站：`README.md`#

看什么：快速安装块（pip install sglang）和两个最小示例——一个展示 language API，一个展示 OpenAI-compatible serving。

你应该能答出来：

SGLang 的语言 API（sgl.function、sgl.gen()）和 serving API（launch_server + HTTP 请求）是两条平行入口，还是一条路径的两种写法？（答案：平行，两条独立入口）
一个最简服务是一个进程还是多个进程？

读完 README，你对整个项目的外形应该有了基本感知。

第二站：`python/sglang/init.py`#

命令：

# 先看 __init__.py 暴露了什么
cat python/sglang/__init__.py | grep -v "^#" | grep -v "^$"

看什么：__init__.py 里 from ... import 的符号就是项目对外承诺的 public API。

重点找这两类：

语言层符号：function、gen、user、assistant、system、image 等——这些是 language API 的构造块；
runtime 层符号：Engine、launch_server、RuntimeEndpoint 等——这些是 serving API 的入口。

看完之后你应该能画一条分界线：lang/ 下的是给 Python 程序调用的语言 API，srt/ 下的是 runtime 本体。

8.2 按问题定位源码

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

按问题定位源码#

这一节从症状出发，告诉你如果问题发生在请求主线、batch 调度、cache 或输出侧，第一步该打开哪个文件、grep 什么符号。

为什么"按问题定位"比"按目录阅读"更值钱#

知道仓库结构，和真正会用仓库排障，是两件不同的事。很多人在知道"目录有哪些"之后，面对真实问题时还是不知道第一步该打开哪个文件。

这一节不再讲"目录长什么样"，而是讲"遇到具体症状，先从哪里下手"。

症状 1：请求进来了，但没有响应#

首先确认请求有没有到达 TokenizerManager：

# 在 server 日志里找 request id
grep "rid=" server.log | tail -20
# 如果看不到 rid=xxx，说明请求没有通过 HTTP 层进入主链

如果没有 rid，问题在 entrypoints/：

# 找 /v1/chat/completions 路由注册
grep -n "chat/completions\|completions" python/sglang/srt/entrypoints/openai/serving_chat.py | head -10
# 找 /generate 路由
grep -n "@router\|add_route\|route" python/sglang/srt/entrypoints/http_server.py | head -20

如果有 rid 但没有后续日志，问题在 TokenizerManager 和 Scheduler 之间的 IPC：

# 找 TokenizerManager 把请求发给 Scheduler 的位置
grep -n "send_to_scheduler\|send.*generate" python/sglang/srt/managers/tokenizer_manager.py | head -20
# 找 Scheduler 接收请求的位置
grep -n "recv_from_tokenizer\|handle_generate" python/sglang/srt/managers/scheduler.py | head -20

症状 2：请求在 waiting queue 里停太久#

首先通过 metrics 确认是哪种等待：

8.3 关键目录、关键对象与关键证据

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

关键目录、关键对象与关键证据#

这一节把全书反复出现的源码位置、关键对象和调试证据面压缩成一张实际可用的索引，方便在排障时快速回到正确入口。

五类目录及其职责#

python/sglang/srt/
├── entrypoints/ # 门：HTTP 服务、OpenAI-compatible API、Engine 入口
│ ├── http_server.py 路由注册和请求分发
│ └── openai/
│ ├── protocol.py ChatCompletionRequest → SamplingParams 转换
│ ├── serving_chat.py /v1/chat/completions 处理
│ └── serving_completions.py /v1/completions 处理
│
├── managers/ # 编排：三管理器和进程边界
│ ├── tokenizer_manager.py API server 侧、状态持有、tokenize
│ ├── scheduler.py batch 组织、admission、KV 分配
│ └── detokenizer_manager.py token → text，流式回传
│
├── model_executor/ # 执行：forward pass 和模型
│ ├── model_runner.py 接收 ForwardBatch，执行前向，返回 logits
│ └── forward_batch_info.py ForwardBatch 定义（调度层→执行层的契约）
│
├── mem_cache/ # 缓存：KV 池和 RadixCache
│ ├── radix_cache.py 前缀复用的核心数据结构
│ ├── base_prefix_cache.py RadixCache 的接口定义
│ └── memory_pool.py ReqToTokenPool + TokenToKVPool 的物理分配
│
└── observability/ # 证据：metrics 上报和请求日志
 ├── prometheus_client.py Prometheus metrics 注册和上报
 └── request_logger.py 请求级别的时间戳和日志

这五类目录对应的是整本书的五层架构：入口 → 编排 → 执行 → 缓存 → 证据。每当你不确定问题出在哪一层时，从这个结构出发能最快缩小范围。

第八章 代码库导读 on Machine Learning 学习笔记

8.1 如何从入口开始读仓库

如何从入口开始读仓库#

为什么仓库入口顺序很重要#

第一站：README.md#

第二站：python/sglang/__init__.py#

8.2 按问题定位源码

按问题定位源码#

为什么"按问题定位"比"按目录阅读"更值钱#

症状 1：请求进来了，但没有响应#

症状 2：请求在 waiting queue 里停太久#

8.3 关键目录、关键对象与关键证据

关键目录、关键对象与关键证据#

五类目录及其职责#

第八章代码库导读 on Machine Learning 学习笔记

第一站：`README.md`#

第二站：`python/sglang/init.py`#