项目结构导览：sglang/ 1000+ 文件地图

谁该读这一篇？ 第一次打开 SGLang 仓库，被 1000+ 个文件淹没的工程师。 前置阅读： 02-architecture.md 至少把三进程拓扑记住。 耗时： 25 分钟（之后当字典查而不是顺序读） 学完能： 1. 第一眼就能定位到任意功能对应的目录； 2. 知道哪些目录是"主路径"（开发 80% 时间在那里），哪些是"特定场景目录"； 3. 给团队介绍 SGLang 内部时，能在白板画出顶层结构； 4. 后续每一章源码精读你能预先知道"这章的代码在哪个目录"。

1. 顶层目录

打开 sglang/，你会看到：

sglang/
├── python/               ← Python 代码主体（90% 在这）
│   └── sglang/
│       ├── srt/          ← SGLang Runtime，后端
│       ├── lang/         ← 前端 DSL
│       ├── launch_server.py
│       ├── bench_*.py    ← 基准测试入口
│       └── ...
├── sgl-kernel/           ← C++/CUDA 高性能算子
├── rust/                 ← Rust 实现（router、tokenizer 加速等）
├── sgl-model-gateway/    ← 模型网关（多副本前置）
├── benchmark/            ← 基准脚本（不是 bench_*.py，是更宏观的 case）
├── examples/             ← 例子代码（学习时直接抄）
├── docker/               ← Dockerfile + 镜像构建脚本
├── docs/, docs_new/      ← 文档（docs_new 是当前在写）
├── test/                 ← 单元 / 集成测试
├── proto/                ← gRPC protobuf 定义
├── scripts/              ← 杂项脚本（CI、release、helpers）
├── 3rdparty/             ← 第三方依赖快照（一般不动）
├── assets/               ← README 用的图
└── experimental/         ← 试验性代码（不保证稳定）

最重要的是 python/sglang/srt/ — Scheduler、RadixCache、Worker 全在那。

2. `python/sglang/` 一级目录

python/sglang/
├── srt/                    ← 后端：本书 80% 内容
├── lang/                   ← 前端 DSL：第 6 章主战场
├── launch_server.py        ← 命令行入口（python -m sglang.launch_server）
├── bench_serving.py        ← 在线吞吐基准
├── bench_offline_throughput.py
├── bench_one_batch.py      ← 单 batch 性能微基准
├── bench_one_batch_server.py
├── auto_benchmark.py       ← 自动化基准（穷搜参数）
├── check_env.py            ← 环境检查（装完跑一下，看 CUDA 等是否就绪）
├── compile_deep_gemm.py    ← DeepGEMM 预编译（DeepSeek 优化路径）
├── eval/                   ← 评测脚本
├── benchmark/              ← 更复杂的基准 case
├── cli/                    ← `sglang serve` 等命令行子命令
├── multimodal_gen/         ← 多模态生成相关
├── jit_kernel/             ← JIT 编译的小算子
├── test/                   ← 测试
├── profiler.py             ← 性能 profiler 工具
├── global_config.py        ← 全局配置（一般不动）
├── utils.py                ← 杂用工具
├── version.py              ← 版本号
└── __init__.py

3. `srt/`：SGLang Runtime 的全景

这是核心，按模块分门别类（30+ 子目录）：

srt/
├── managers/               ★ 进程主体：Scheduler / TokenizerManager / Detokenizer
├── model_executor/         ★ GPU 前向：ModelRunner / CUDA Graph
├── mem_cache/              ★ KV cache：RadixCache / memory pool / allocator
├── layers/                 ★ 模型层（attention / moe / linear / quantization）
├── models/                 ★ 模型实现（llama / qwen / deepseek / mixtral ...）
├── sampling/               ★ 采样器
├── distributed/            ★ TP / PP / NCCL 集合通信
├── disaggregation/         ★ Prefill/Decode 分离
├── lora/                   ★ LoRA 多适配器
├── constrained/            ★ 受约束解码（压缩 FSM）
├── speculative/            ★ 投机解码（EAGLE / Medusa）
├── function_call/          ★ Function calling 解析
├── multimodal/             ★ 多模态编码器、processor
├── entrypoints/            ★ HTTP / gRPC / Engine 接口
├── tokenizer/              ★ tokenizer 工具
├── compilation/            ★ torch.compile / inductor 相关
├── checkpoint_engine/      ★ 模型权重加载与同步（推理时也用得到）
├── connector/              ★ 与外部 KV store / RDMA 对接
├── eplb/                   ★ Expert 负载均衡（MoE）
├── configs/                ★ 各种 dataclass 配置
├── server_args.py          ★ 启动参数大全（顶级 dataclass）
├── environ.py              ★ 环境变量定义（SGLANG_*）
├── parser/                 ← 输出 parser
├── multiplex/              ← 多请求复用
├── batch_overlap/          ← Overlap 调度配套
├── batch_invariant_ops/    ← 数值确定性优化
├── observability/          ← metrics / logging / tracing
├── session/                ← 会话 API
├── arg_groups/             ← argparse 工具
├── compilation/            ← torch.compile 后端
├── elastic_ep/             ← 弹性专家并行
├── grpc/                   ← gRPC 服务
├── ray/                    ← Ray 集成
├── plugins/                ← 插件注册
├── platforms/              ← 平台抽象（NVIDIA / AMD / Intel）
├── hardware_backend/       ← 硬件后端
├── weight_sync/            ← RL 训练时权重同步
├── debug_utils/            ← 调试辅助
├── state_capturer/         ← 状态捕获
├── utils/                  ← 工具
├── model_loader/           ← 模型加载逻辑
├── dllm/                   ← Diffusion LLM 支持
├── batch_invariant_ops/    ← 数值不变性算子
└── constants.py            ← 常量

带 ★ 的是"主路径"，开发 80% 时间集中在这。

4. `managers/`：进程主体（精读重点）

managers/
├── scheduler.py                 ★★★ 3900+ 行，调度主循环
├── tokenizer_manager.py         ★★★ TM 进程主体（2800+ 行）
├── detokenizer_manager.py       ★★★ Detokenizer 进程主体
├── schedule_batch.py            ★★ ScheduleBatch（一步的 batch 描述）
├── schedule_policy.py           ★★ cache-aware policy 实现
├── io_struct.py                 ★★★ 全部消息体 dataclass
├── tp_worker.py                 ★ Tensor parallel worker（rank > 0）
├── data_parallel_controller.py  ★ DP 控制器
├── multimodal_processor.py      ← 多模态请求处理
├── disagg_service.py            ← P/D 分离辅助
├── mm_utils.py                  ← 多模态工具
├── embed_types.py               ← embedding 任务专用
├── cache_controller.py          ← KV cache 异步管理（HiCache 等）
├── scheduler_components/        ← scheduler 拆分出来的组件
├── scheduler_input_blocker.py   ← 暂停入口（背压用）
├── tokenizer_manager_score_mixin.py  ← TM 的 score 任务 mixin
├── tokenizer_control_mixin.py   ← TM 的控制 API mixin
├── multi_tokenizer_mixin.py     ← 多 TM 副本场景
├── prefill_delayer.py           ← prefill 节流
├── overlap_utils.py             ← overlap 调度辅助
├── hisparse_coordinator.py      ← HiSparse 协调器
├── async_dynamic_batch_tokenizer.py  ← 异步动态 batch tokenize
├── template_manager.py / template_detection.py  ← chat template
├── communicator.py              ← 进程间通信封装
├── scheduler_pp_mixin.py        ← PP 支持
├── scheduler_recv_skipper.py    ← 收消息时的跳过策略
├── utils.py
└── configure_logging.py

最常去的 4 个文件：scheduler.py / tokenizer_manager.py / detokenizer_manager.py / io_struct.py。

5. `mem_cache/`：内存与前缀缓存

mem_cache/
├── radix_cache.py               ★★★ 主流前缀缓存实现
├── hiradix_cache.py             ★★ HiCache（CPU 镜像 + 异步 prefetch）
├── memory_pool.py               ★★★ KV cache 物理存储
├── allocator.py                 ★★ slot 分配
├── base_prefix_cache.py         ← 抽象基类
├── chunk_cache.py               ← chunked prefill cache 模式
├── evict_policy.py              ← 淘汰策略接口
├── cache_init_params.py         ← 初始化参数
├── common.py
├── events.py                    ← cache 事件
├── cpp_radix_tree/              ← C++ 加速版本
├── deepseek_v4_*.py             ← DeepSeek 专用压缩内存池
├── hicache_storage.py           ← HiCache 持久化
├── mamba_radix_cache.py         ← Mamba 专用
├── hi_mamba_radix_cache.py      ← Mamba + HiCache
├── hisparse_memory_pool.py      ← HiSparse 长上下文专用
├── hybrid_cache/                ← 混合缓存
├── flush_cache.py               ← cache flush 工具
├── kv_cache_builder.py          ← 初始化时构建
└── base_swa_memory_pool.py      ← SWA（sliding window）专用

最常去的 3 个文件：radix_cache.py / memory_pool.py / allocator.py。

6. `layers/`：模型层

layers/
├── attention/                  ★ 各 attention 后端（FlashInfer / Triton / Torch）
│   ├── flashinfer_backend.py
│   ├── triton_backend.py
│   ├── torch_backend.py
│   └── ...
├── moe/                        ★ MoE 实现（含 EP）
├── quantization/               ★ 量化算法
├── linear.py                   ← TP 切分的 Linear
├── embeddings.py
├── rotary_embedding.py
├── layernorm.py
├── activation.py
├── logits_processor.py
├── sampler.py
└── ...

7. `models/`：模型实现

models/
├── llama.py             ← Llama 系列
├── qwen2.py / qwen3.py  ← Qwen 系列
├── deepseek_v2.py / deepseek_v3.py
├── mixtral.py
├── gemma2.py / gemma3.py
├── phi3.py
├── llava.py / llava_onevision.py / qwen_vl.py / minicpm_v.py  ← VLM
└── ...（数十个模型）

每个文件一个模型架构。要加新模型就在这里写。

8. 一张"想找 X 就去 Y"的查询表

想找	去哪里
服务怎么启动的	`launch_server.py`、`srt/entrypoints/http_server.py`
一次请求怎么进 GPU 的	`srt/managers/tokenizer_manager.py` → `scheduler.py` → `model_executor/model_runner.py`
调度主循环	`srt/managers/scheduler.py:event_loop_normal`（1372）
Cache-aware 排序	`srt/managers/schedule_policy.py`
前缀缓存数据结构	`srt/mem_cache/radix_cache.py`
KV 物理存储	`srt/mem_cache/memory_pool.py` + `allocator.py`
Attention kernel 选择	`srt/layers/attention/` 下 `*_backend.py`
加新模型	`srt/models/<name>.py` + `srt/configs/<name>.py`
加新量化方法	`srt/layers/quantization/`
投机解码	`srt/speculative/`
受约束解码	`srt/constrained/`
Function calling 解析	`srt/function_call/`
多模态预处理	`srt/multimodal/` + `srt/managers/multimodal_processor.py`
LoRA	`srt/lora/`
启动参数有哪些	`srt/server_args.py`
环境变量有哪些	`srt/environ.py`
Tensor parallel 集合通信	`srt/distributed/`
P/D 分离	`srt/disaggregation/`
Router	`sglang/rust/` 或 `sgl-router/`
监控指标	`srt/observability/`
CUDA Graph	`srt/model_executor/cuda_graph_runner.py`
前端 DSL 解释器	`python/sglang/lang/interpreter.py`
DSL API	`python/sglang/lang/api.py`
单元测试	`python/sglang/test/`、`test/`
Docker 镜像	`docker/Dockerfile.*`
基准测试	`python/sglang/bench_serving.py`、`benchmark/`

9. `sgl-kernel/`：C++ / CUDA 算子库

sgl-kernel/
├── csrc/                ← C++ / CUDA 源码
├── python/sgl_kernel/   ← Python 绑定
├── CMakeLists.txt
├── Makefile
├── build.sh             ← 构建脚本（独立编译）
└── benchmark/           ← 算子级基准

什么时候动它：

你要加新 CUDA kernel（fused 算子、新 attention 变体）。
性能 profiling 显示 Python 层的算子瓶颈。

普通使用不需要碰这里——pip install sglang 已经预编译好。

10. `rust/`：Rust 实现

rust/
├── sgl_router/          ← 路由器主体
├── sgl_tokenizer/       ← Tokenizer 加速（绑定 huggingface tokenizers）
└── ...

Rust 不是给应用层用的，是为了把"高频路径的 CPU 工作"从 Python 里剥出来。

11. `examples/`：直接抄的好地方

examples/
├── runtime/             ← 后端 API 示例
├── frontend_language/   ← DSL 示例（最值得学）
├── multi_modal/
├── lora/
├── ...

新手第一周直接 cd examples/frontend_language/ && python ... 跑一遍。

12. 一张"代码量"地图（粗略）

目录	Python 行数（约）
`srt/managers/`	10k+
`srt/models/`	20k+（数十个模型）
`srt/layers/`	15k+
`srt/mem_cache/`	3k+
`srt/distributed/`	2k+
`srt/disaggregation/`	3k+
`srt/constrained/`	1.5k+
`lang/`	3k+
`sgl-kernel/csrc/`	10k+（C++/CUDA）

合计 60k+ 行 Python + 10k+ 行 C++/CUDA + Rust 若干。你不需要全部读 —— 按业务/兴趣抽 1-2 个子系统精读即可。

13. 小结

顶层划分：python/sglang/srt/（后端）+ lang/（前端）+ sgl-kernel/（CUDA）+ rust/（高性能 CPU 路径）。
srt/managers/、srt/mem_cache/、srt/model_executor/、srt/layers/、srt/models/ 是日常 80% 时间所在。
找代码先查 §8 的"想找 X 就去 Y"表，比 grep 更快。
第一周不要试图全读源码，先抓主流程。

14. 自检

我想看 cache-aware 调度的具体算法，去哪个文件？

答案

[`sglang/python/sglang/srt/managers/schedule_policy.py`](../sglang/python/sglang/srt/managers/schedule_policy.py)。关键类：`SchedulePolicy`（141）、`PrefillAdder`（405）；关键方法：`calc_priority`（162，按命中长度算权重）、`add_one_req`（813，把请求塞进当前 batch）。策略枚举：`CacheAwarePolicy`（125）有 LPM/DFS_WEIGHT/PRIORITY 三种。

我想给 SGLang 加一个 Phi-4 的模型实现，新文件放哪？需要改哪些注册地方？

答案

新建 [`srt/models/phi4.py`](../sglang/python/sglang/srt/models/)（仿照 `llama.py` / `qwen2.py`，实现 `class Phi4ForCausalLM(nn.Module)` 含 `forward` 和 `compute_logits`）。注册位置：[`srt/model_loader/`](../sglang/python/sglang/srt/model_loader/) 下的 architecture registry（`ModelRegistry`），把 `"Phi4ForCausalLM"` 映射到新类。如果 attention 形状特殊（如 MoE / MLA）还要在 [`srt/layers/attention/attention_registry.py`](../sglang/python/sglang/srt/layers/attention/attention_registry.py) 加分支。最后在 [`srt/configs/`](../sglang/python/sglang/srt/configs/) 加 ModelConfig 子类（如果 HF config 字段需要映射）。

我想知道 SGLang 都支持哪些环境变量，去哪个文件？

答案

[`sglang/python/sglang/srt/environ.py`](../sglang/python/sglang/srt/environ.py)。所有 `SGLANG_*` 环境变量定义在这里（每个一个 typed accessor），grep 这个文件能看全。 `--help` 看到的是命令行参数（在 [`server_args.py`](../sglang/python/sglang/srt/server_args.py)），而环境变量是更细粒度的调试 / 实验开关。

我想看 sglang serve 的命令行子命令，去哪个目录？

答案

[`sglang/python/sglang/cli/`](../sglang/python/sglang/cli/)。 `sglang serve` 是 `sglang` console_script 入口的子命令，内部最终也会调到 `launch_server.py` 的 `run_server`。 `cli/` 下面还有其它子命令（如 `sglang router`、`sglang bench`），结构按 Python click / argparse 子命令组织。

我想看 router 的源码，应该是 Python 还是 Rust？路径？

答案

**Rust**。路径：[`sglang/rust/sgl_router/`](../sglang/rust/) 或仓库根的 `sgl-router/`（取决于版本布局）。选 Rust 的原因：router 要扛 50k+ QPS、做 Bloom filter 近似匹配 + 路由决策，Python 会成瓶颈。 Python 部分只有客户端 wrapper（`sglang serve router` 子命令调 Rust 二进制）。同样 `rust/sgl_tokenizer/` 是 Rust 加速的 tokenizer 绑定。

15. 下一步

05-quickstart.md — 跑起来。
03-code-walkthrough/ — 每个核心模块逐个精读，本章是它们的"目录索引"。
07-hands-on/01-setup.md — 装环境 + 跑 example。

上游源码起点：sglang/。

项目结构导览：sglang/ 1000+ 文件地图

1. 顶层目录

2. python/sglang/ 一级目录

3. srt/：SGLang Runtime 的全景

4. managers/：进程主体（精读重点）

5. mem_cache/：内存与前缀缓存

6. layers/：模型层

7. models/：模型实现