5. 核心模块

本章拆解 SGLang 中每个核心模块的职责、输入、输出、生命周期、异常处理与扩展方式。

1. Python API / OpenAI API Server

职责

提供用户入口，把程序或 HTTP 请求交给 Language Frontend。

输入

• Python sgl.* 程序
• HTTP 请求（OpenAI 兼容格式）

输出

• 生成的文本 / token 流
• 结构化输出（JSON、函数调用结果）

扩展方式

Python API 可以自定义 function、工具调用、prompt template；API Server 基于 FastAPI，可扩展中间件与认证。v0.5.21 起还新增了面向判别类任务的 Decisions API（/v1/decisions，把 LLM / VLM 变成低延迟分类与打分器）和 Score API（/v1/score，一次请求对全部候选打分），拓展了 SGLang 在 rerank、分类、评测场景的使用边界。

---

2. Language Frontend

职责

把用户程序编译成 IR，并捕获变量、约束、依赖。

输入

• sgl.gen、sgl.select、sgl.fork 等调用
• 采样参数、约束条件

输出

• Intermediate Representation（IR）
• 执行图中的变量绑定

生命周期

随程序构建而创建，IR 生成后交给 Compiler。

---

3. Compiler

职责

对 IR 做全局优化，生成执行计划。

优化手段

• 合并多个 gen 调用到同一次 forward。
• 识别可共享前缀，提前调度复用。
• 为结构化约束生成 FSM / grammar。

输出

• Schedule Plan
• 约束编译结果

---

4. Runtime

职责

SGLang 的控制中心，连接编译器、调度器、缓存和执行后端。

输入

• Schedule Plan
• 新请求 / 程序

输出

• 执行命令给 Worker
• 输出 token 给 Detokenizer

生命周期

服务启动时初始化，直到进程退出。

---

5. Scheduler

职责

决定每轮 iteration 计算哪些 token。

输入

• 待执行调用列表
• 各调用已计算/待计算 token 数
• token budget / 显存预算

输出

• 本轮需要 forward 的 token 集合
• 每个调用对应的新 token 数

关键行为

• 统一处理 prefill / decode。
• 与 RadixCache 交互，只计算未缓存 suffix。
• 支持 continuous batching 和 chunked prefill。

---

6. RadixCache / KV Cache Manager

职责

用 Radix Tree 管理 KV Cache，实现自动前缀复用。

输入

• token 序列
• KV block 元数据

输出

• 最长匹配前缀长度
• 可复用的 KV block 列表

生命周期

伴随 Runtime 整个生命周期。

异常处理

• 显存不足：触发 LRU 回收。
• 树过大：按引用计数和最近使用策略淘汰。

扩展方式

• HiCache / UnifiedRadixTree（v0.5.12 起）：支持 SSD offload、SWA 模型，L2 主机内存缓存可动态挂载/卸载，L3 兼容 Mooncake Store、3FS、NIXL、AIBrix 等多种后端。
• 统一 Radix Tree（v0.5.19 起）成为所有配置的默认缓存（含 Full-attention-only 模型），替代原先按模型类型区分的多套实现。
• Rust 核心（v0.5.21 起）成为前缀缓存默认实现，提升大规模并发下的树操作性能。

---

7. TokenizerManager / Detokenizer

职责

文本与 token ID 互转；处理 unicode 多字节字符；在结构化生成中维护 token-to-char 映射。

---

8. Worker / Model Runner

职责

执行模型 forward，管理 GPU。

输入

• token ids
• RadixCache 提供的 KV 布局
• attention metadata

输出

• logits
• sampled tokens

扩展方式

支持本地 Worker、多节点 Worker、TP / PP / DP。

---

9. Constrained Sampler / XGrammar

职责

把结构化约束编译成可执行形式，并在每轮采样时生成合法 token mask。

输入

• regex / JSON Schema / EBNF
• 当前 FSM / grammar 状态
• logits

输出

• masked logits
• 下一个合法 token

关键后端

• XGrammar-2：SGLang v0.5.11 起的默认后端，支持 JSON、EBNF、regex；mask 生成与 GPU 推理重叠，并支持 jump-forward decoding。
• Outlines：社区常用，提供 FSM-based 约束。
• Llguidance：可选后端，可通过 --grammar-backend 切换。

---

10. Attention Backend

实现选项

• FlashAttention / FlashInfer
• MLA / FlashMLA（DeepSeek 系列）
• DSA 稀疏后端：flashmla_sparse / flashmla_sparse_q8 / fa3 / tilelang / trtllm（DeepSeek-V3.2）
• 自定义 kernel（如 CuteDSL prefill kernel for Blackwell）

选择逻辑

根据 GPU 架构、模型类型、是否使用 prefix caching / structured generation 自动选择。

模块协作图

本章小结

SGLang 的模块划分清晰，Compiler 和 RadixCache 是其与 vLLM 最大的差异点。理解 Runtime 如何协调这两个模块，是掌握 SGLang 的关键。