SGLang 源码学习路线图（AI Infra 视角）

整体架构概览

SGLang Runtime（SRT）是一个多进程 serving 架构，核心数据流如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
用户请求 (HTTP/gRPC/Python API)
    │
    ▼
┌──────────────────────────────────────────────────┐
│              HTTP Server (FastAPI)                │  entrypoints/http_server.py
└────────────────────┬─────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────┐
│                  Engine                           │  entrypoints/engine.py
│  启动所有子进程，提供 Python API                    │
└────────────────────┬─────────────────────────────┘
                     │ ZMQ IPC
                     ▼
┌──────────────────────────────────────────────────┐
│            TokenizerManager（主进程）              │  managers/tokenizer_manager.py
│  分词、多模态预处理、请求路由                        │
└────────────────────┬─────────────────────────────┘
                     │ ZMQ IPC
                     ▼
┌──────────────────────────────────────────────────┐
│             Scheduler（子进程，每 GPU 一个）        │  managers/scheduler.py
│  continuous batching 调度、内存管理                 │
│  ┌────────────────────────────────────────────┐  │
│  │  ScheduleBatch / SchedulePolicy            │  │
│  └────────────────────────────────────────────┘  │
└────────────────────┬─────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────┐
│             ModelRunner（在 Scheduler 进程内）     │  model_executor/model_runner.py
│  模型加载、GPU forward、CUDA Graph                │
│  ┌────────────────────────────────────────────┐  │
│  │  models/ (214 个模型)  +  layers/ (算子层)  │  │
│  └────────────────────────────────────────────┘  │
└────────────────────┬─────────────────────────────┘
                     │ ZMQ IPC
                     ▼
┌──────────────────────────────────────────────────┐
│          DetokenizerManager（子进程）              │  managers/detokenizer_manager.py
│  增量 detokenize，流式返回结果                      │
└──────────────────────────────────────────────────┘

关键设计：所有进程间通信走 ZMQ IPC，CPU 调度和 GPU 计算可以 overlap（双 CUDA stream）。

阶段一：入口与启动流程（1-2 天）

目标：搞清楚服务怎么拉起来、请求怎么进来

顺序 文件 行数 读什么
1 server_args.py ~9384 所有 CLI 参数定义，了解 SGLang 能配什么
2 entrypoints/http_server.py - FastAPI 路由定义，/v1/chat/completions 等 OpenAI 兼容接口
3 entrypoints/engine.py:192 ~1733 class Engine — 看 __init__ 和 _launch_subprocesses()，理解进程编排
4 managers/io_struct.py ~2384 GenerateReqInput 等请求/响应数据结构，所有进程间传递的消息类型

阅读建议：从 Engine.__init__ 出发，跟踪一个 /v1/completions 请求的完整路径，画出调用链。

阶段二：分词与请求预处理（1 天）

目标：理解请求在进入调度器之前经历了什么

文件 重点
managers/tokenizer_manager.py:372 TokenizerManager — 核心方法 generate_request()：验证 → 分词 → ZMQ 发送 → 等待响应
managers/detokenizer_manager.py 增量 detokenize，支持流式输出
managers/multimodal_processor.py 图片/视频等多模态输入处理

阶段三：调度器 — 最核心模块（3-5 天）

目标：深入理解 continuous batching 调度循环

Scheduler 是整个系统的大脑（约 4900 行），重点读：

顺序 文件 读什么
1 managers/schedule_batch.py Req（单个请求）和 ScheduleBatch（一个 batch）的数据结构
2 managers/schedule_policy.py 调度策略：FCFS、LPM（Longest Prefix Match）等
3 managers/scheduler.py:359 核心：找到 event_loop_normal() 方法，理解每步做什么
4 managers/scheduler_components/ 调度器的模块化子组件

调度循环伪代码（event_loop_normal）：

1
2
3
4
5
6
7
8
9
while True:
    recv_reqs = recv_requests()           # 从 TokenizerManager 收请求
    process_input_requests(recv_reqs)      # 放入等待队列
    batch = get_next_batch_to_run()        # 调度决策：prefill 还是 decode
    if batch:
        result = run_batch(batch)          # 调用 ModelRunner.forward()
        process_batch_result(batch, result) # 处理结果，发给 Detokenizer
    else:
        on_idle()                          # 空闲处理

重点理解：

  • Prefill 和 Decode 是两个不同阶段，调度策略不同
  • Chunked prefill：长 prompt 分块处理，避免长时间阻塞 decode
  • Overlap 模式（event_loop_overlap）：用两个 CUDA stream 实现 CPU 调度与 GPU 计算并行

阶段四：内存管理与 KV Cache（3-5 天）

目标：理解 GPU 显存怎么分配、怎么复用

这是 SGLang 的核心竞争力之一（RadixAttention）：

顺序 文件 读什么
1 mem_cache/memory_pool.py KV Cache 的 GPU 内存池，token 到 KV 的映射
2 mem_cache/radix_cache.py RadixAttention — 用 Radix Tree 实现 prefix caching
3 mem_cache/base_prefix_cache.py prefix cache 的抽象接口
4 mem_cache/allocation.py 内存分配策略
5 mem_cache/evict_policy.py 缓存淘汰策略（LRU 等）
6 mem_cache/chunk_cache.py 分块缓存实现

重点理解：

  • Radix Tree 如何让多个请求自动共享相同 prefix 的 KV cache（比如系统 prompt）
  • 与 vLLM 的 PagedAttention（block-level）相比，SGLang 的 token-level 管理有什么优势
  • 缓存淘汰：当显存不够时怎么决定驱逐哪些 cache

进阶：hiradix_cache.py（GPU+CPU 分层缓存）、deepseek_v4_memory_pool.py（DeepSeek V4 专用内存池）

阶段五：模型执行层（3-5 天）

目标：理解 GPU 上实际怎么跑 forward

顺序 文件 读什么
1 model_executor/model_runner.py:257 ModelRunner — load_model() 加载权重、forward() 执行推理
2 model_executor/forward_batch_info.py ForwardBatch — 传给模型的所有元信息
3 model_executor/forward_context.py forward 上下文（线程局部状态）
4 model_executor/cuda_graph_config.py CUDA Graph 配置
5 models/llama.py 选一个典型模型看实现，Llama 是最好的起点

重点理解：

  • CUDA Graph：capture 阶段录制 GPU 操作，replay 阶段零开销重放，减少 kernel launch 延迟
  • Prefill 和 Decode 的 forward 为什么不一样（计算模式差异）
  • 模型权重从 HuggingFace 加载到 GPU 的完整流程

阶段六：算子层 / Layers（3-5 天）

目标：理解底层高性能算子实现

模块 文件数 重点
layers/attention/ 40+ backend FlashInfer（主力）、FlashAttention、FlashMLA（DeepSeek MLA）、Triton 等
layers/moe/ ~19 MoE 路由与执行：Triton fused MoE、Expert Parallelism
layers/linear.py 1 线性层，含各种量化适配
layers/quantization/ 多 INT8、FP8、FP4、GPTQ、AWQ 等量化方案
layers/rotary_embedding/ 多 RoPE 等位置编码实现
layers/sampler.py 1 top-p、top-k、temperature 等采样策略
layers/logits_processor.py 1 logits 后处理
layers/radix_attention.py 1 RadixAttention 的 layer 封装

建议：先读 layers/attention/base_attn_backend.py 理解 attention backend 的抽象接口，再看 flashinfer_backend.py 理解主力实现。

阶段七：分布式与并行（2-3 天）

目标：理解多 GPU / 多节点推理

文件 读什么
distributed/parallel_state.py TP/PP/DP/EP 并行状态管理
distributed/communication_op.py AllReduce、AllGather 等集合通信封装
managers/data_parallel_controller.py Data Parallelism 控制器，请求如何分发到多个 Scheduler
managers/tp_worker.py Tensor Parallelism worker
disaggregation/ Prefill-Decode 分离（PD disaggregation），prefill 和 decode 跑在不同 GPU 上

阶段八：高级特性（按兴趣选读）

特性 目录 说明
投机解码 speculative/ Eagle、N-gram、MTP、DFlash、DSpark 等多种策略
结构化输出 constrained/ 基于 xgrammar/outlines 的 JSON schema、正则约束
LoRA 热加载 lora/ 运行时动态加载/卸载 LoRA adapter，多 LoRA 批量推理
工具调用 function_call/ Function calling 支持
计算通信重叠 batch_overlap/ overlap scheduling 细节
弹性专家并行 elastic_ep/ 动态调整 Expert Parallelism
权重同步 weight_sync/ 在线训练/RLHF 场景下的权重热更新

推荐阅读顺序总结

1
2
3
4
5
6
7
8
9
10
11
12
13
🟢 第一周：跑通全链路（理解"请求从进来到出去经过了什么"）
   server_args.py → engine.py → io_struct.py
   → tokenizer_manager.py → scheduler.py (event_loop_normal)
   → model_runner.py → llama.py（选一个模型看）

🟡 第二周：深入核心机制（理解"为什么快"）
   schedule_batch.py → schedule_policy.py
   → radix_cache.py → memory_pool.py
   → forward_batch_info.py → flashinfer_backend.py → sampler.py

🔴 第三周+：进阶专题（理解"怎么扩展"）
   CUDA Graph → MoE → distributed/
   → speculative/ → disaggregation/ → quantization/

实践建议

  1. 先跑起来：python -m sglang.launch_server --model meta-llama/Llama-3.1-8B-Instruct 启动实例，发请求感受流程
  2. 加日志调试：在 scheduler.py 的 event_loop_normal 里加 print，观察每轮调度决策
  3. 跑单测：test/ 目录有大量测试用例，从简单的跑起来理解各模块行为
  4. 对比 vLLM：SGLang 的三个核心差异点值得对比学习：
    • RadixAttention（prefix caching） vs vLLM 的 PagedAttention
    • Chunked prefill + overlap scheduling 的调度设计
    • ZMQ 多进程架构 vs vLLM 的 Ray/单进程架构
  5. 读 benchmark：benchmark/ 目录下有各种性能测试脚本，帮助理解优化目标

所有文件路径相对于 python/sglang/srt/，除非另有说明。