一、整体架构与源码结构

进程级架构

SGLang 的 SRT Server 采用多进程架构主要由三个组件构成：

┌─────────────────────────────────────────────────────────────────┐
│ SRT Server 进程架构 │
│ │
│ ┌──────────────────┐ │
│ │ HTTP Server │ FastAPI。接收 OpenAI 兼容 API 请求 │
│ │ │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ TokenizerManager│ 进程1: tokenize → 发送 token_id 到 Scheduler│
│ │ (python/sglang/ │ ZMQ 通信 │
│ │ runtime/) │ │
│ └────────┬─────────┘ │
│ │ ZMQ │
│ ┌────────▼──────────────────────────────────────┐ │
│ │ Scheduler │ │
│ │ ├── waiting_queue │ │
│ │ ├── grammar_queue │ │
│ │ ├── running_batch │ │
│ │ ├── RadixTree │ │
│ │ └── TokenToKVPool • │
│ └────────┬──────────────────────────────────────┘ |
│ | |
│ ... |
└─────────────────────────────────────────────────────────────────┘

源码目录结构

痛点：新手经常迷失在庞大的代码树中，不知道哪些文件才是关键入口。

sglang/
├── python/sglang/
│ ├── runtime/ # 主要运行时
│ | ├── scheduler.py # ★ 调度器主要
│ | ├── radix_attention.py # ★ 基数树 KV Cache 管理
| | ├── model_runner.py # 模型执行器
| | └── server_args.py # 启动参数
| ├── srt/ # SRT 引擎
| | ├── layers/attention/
| | | ├── flashinfer_backend.py # FlashInfer 实现
| | | ├── flashattention_backend.py #
| | | └── triton_backend.py #
| | ├── layers/radix_attention.py # ★ RadixAttention 层
| | ├── managers/
| | ├── schedule_batch.py # ★ Batch 数据结构
| | �├─ tokenizer_manager.py
| | �├─ detokenizer_manager.py
| | �├─ constrained/
| �├─ fsm.py # 有限状态机
| �└─ grammar.py
| �└─ server.py #入口
| �├─ backend/ # 前端语言运行时
| �└─ entrypoints/ # HTTP入口
└── test/

二、RadixAttention：基数树 KV Cache 管理

数据结构设计

源码位置的观点是。python/sglang/srt/layers/radix_attention.py + python/sglang/runtime/radix_attention.py

痛点：传统 KV Cache 实现只能按请求维度管理，导致跨请求复用几乎不可能；阅读代码时不清楚“节点”和“物理块”之间的映射关系。

class RadixTreeNode:
"""基数树节点"""
def __init__:
self.children: Dict = {} # key = token_id。value = 子节点
self.parent: RadixTreeNode = None
self.lock_ref: int = 0 # 引用计数
self.last_access_time: float = time.time # LRU 时间戳
self.value: int = -1 # 对应的 KV Cache物理块索引
self.key: Tuple = # 节点对应的 token 序列
class RadixTree:
"""基数树主体"""
def __init__:
self.root = RadixTreeNode
self.token_to_kv_pool = TokenToKVPool # KV Cache物理内存池
self.evictable_size_ = 0 # 可淘汰的 KV Cache 大小

关键设计细节

• 节点粒度：不是每个 token 一个节点，而是每个唯一 token 子序列一个节点，实现前缀压缩。
• 引用计数：lock_ref记录活跃请求数量。引用计数>0 的节点不可淘汰.
• 物理内存池：TokenToKVPool统一管理 GPU 显存，避免碎片化。按理说，

前缀匹配与插入流程

痛点：A/B 测试时发现大量计算在重复前缀上。却找不到自动复用的实现，

请求到达，token 序列:
Step : 前缀匹配
┌─────────────────────────────────────┐
│ 输入: |
│ 基数树中已有: |
│ root → → → |
│ 匹配过程: |
│ ✓ 完全匹配 → 子节点 |
│ ✓ 完全匹配 → 子节点 |
│ ✓ 匹配，但还有 |
│ ✗ 无匹配 → 停止 |
│结果这方面，prefix_len =6，不需要计算前6个token|
从┃新增部分来看，需要计算 KV |
└─────────────────────────────────────┘

源码主要原因

def match_prefix -> Tuple,List,List]:
"""返回已匹配的 token、对应节点链和未匹配剩余部分"""
node = self.root
matched_tokens =
matched_nodes =
remaining = list
while remaining:
matched = False
for child_key。child_node in node.children.items:
if self._prefix_match:
matched_tokens.extend
matched_nodes.append
node = child_node
remaining = remaining
child_node.lock_ref += 1
child_node.last_access_time = time.time
matched = True
break
elif self._partial_prefix_match:
# 部分匹配，需要分裂处理
pass
if not matched:
break
return matched_tokens,matched_nodes,remaining

节点分裂机制

痛点：A/B 场景下出现“方法冲突”，但不知道如何在代码层面安全分裂。

分裂前的观点是，root → →
↑新请求的观点是。分裂后:
root → → →
↘→

• 分裂时同步拆分对应的 KV Cache 块。
• 的 KV 块保持不变，仅更新索引关系。
• 操作复杂度为 O，因为仅修改指针和计数。话说回来，

L​RU 淘汰策略

痛点：K‑V 缓存满了却不知道何时还有如何安全回收无用缓存。

def evict -> int:
"""淘汰最少使用的 KV Cache，释放至少 need_size 空间"""
evicted=0
candidates=self._collect_evictable_nodes # 按 LRU 排序
for node in candidates:
if evicted>=need_size:
break
if node.lock_ref>0:
continue # 被活跃请求引用，不可淘汰
parent=node.parent
del parent.children # 从树中断开
self.token_to_kv_pool.free # 回收物理内存
evicted+=len
self._try_merge # 父仅剩单子时合并
return evicted

L​RU 后自动合并示例：

淘汰前这方面，→ →
合并后这方面。→

L​RU 与 vLLM PagedAttention 本质区别对比表格

维度	vLLM PagedAttention	SGLang RadixAttention
数据结构	块表	基数树
管理粒度	单请求内分页	跨请求前缀复用
复用方式	Copy‑on‑Write	最长前缀匹配
淘汰策略	请求结束释放	LRU 按需淘汰
缓存生命周期	仅限当前请求	跨请求持久化
树结构变更	无分裂/合并/压缩 有分裂、合并、压缩机制 三、调度器：零开销 CPU 调度 + Overlap机制 调度器主要循环 & 痛点定位 SGLang 的 Scheduler 是整个推理引擎最复杂的类。老实说，很多使用者抱怨“CPU 成为瓶颈”。因为传统框架在每次 batch 前都要阻塞等待 GPU 完成。下面展示了零开销设计思路。 class Scheduler: def eventloopnormal: """Normal 模式的事件循环""" while True: recvrequests # ZMQ 接收新 request batch=self.preparebatch # 根据 LSPF 排序组 batch result=self.runbatch # 同步 GPU 推理 self.processbatch_result Overlap Scheduler：CPU‑GPU 流水线重叠 & 痛点说明