《从 0 实现 SGLang》第 1 篇 · LLM 推理引擎到底在做什么

千行代码，一步步搭出一个现代 LLM 推理引擎，吃透大模型推理的每一项关键技术。

本阶段目标 — 最简推理实现

用最朴素的方式把端到端推理跑通：先搭起整体框架，再逐个模块替换为完整实现。整个阶段共 5 篇短文：

本篇你将学到

• 一句话能说清"LLM 推理引擎在做什么"；
• 理解 prefill 与 decode 为何要分两步，KV cache 为何是核心；
• 看到推理引擎 4 类进程的全景图，作为后续阶段展开的起点；
• 获得一张系列阅读路线表，可按自己关心的方向选择性阅读。

本篇不涉及实现，只界定问题与目标。

1. LLM 推理引擎到底在做什么

一句话定义：给定一段 prompt，逐 token 生成续写，直到遇到停止条件。把这一过程包装成能以"请求"形式被外部高效调用的服务系统，便是 LLM 推理引擎。

与训练框架的区别

很多人第一次接触 LLM 推理时，会以为"加载模型然后调用model.generate()即可"。这在演示场景下尚可成立，但在生产场景下远远不够。

它要解决的真问题

吞吐量（每秒处理多少请求）、延迟（首 token 多快出、token 间隔多稳）、显存利用率（KV cache 不爆）、公平性（长请求不能饿死短请求）。

怎么解决

把"一次 forward 跑模型"拆成 prefill 与 decode 两个阶段、引入 KV cache、把请求打包成 batch、用 scheduler 决定每一步谁能上、用分页显存避免碎片、用 CUDA Graph 消除 launch 开销——这正是本系列后续 8 个阶段要逐一构建的东西。

本篇不展开任何一个机制，只把问题边界画清楚。

2. Prefill 与 Decode：为什么必须分两步

一个朴素假设

初次接触推理时常会产生这样的疑问：既然 transformer 是一次 forward，为何不能在 prompt 后拼接 N 个待生成的 PAD 一并送入，一次性输出 N 个 token？

答案藏在 causal mask 里。Transformer 的自注意力中，第 k 个位置只能看到前 k-1 个位置，这是因果性的硬约束——你必须先生成第 k 个 token，才能为第 k+1 个 token 提供 K/V。换句话说，生成阶段的 token 之间存在数据依赖，串行无法绕开。

因此自然分为两个阶段

Prefill：把整个 prompt 一次性送入模型。所有 prompt token 之间没有"未来依赖"问题（它们是已知输入），可以并行算 attention。并行度 = prompt 长度，通常几十到几千，算力密集。

Decode：每一步只生成 1 个新 token。新 token 需要对全部历史 KV 算 attention，但自己只有一个 query。并行度 = batch 内同时在 decode 的请求数，通常 16~256，显存带宽密集。

工程上的连锁后果

两个阶段在硬件瓶颈、kernel 实现、调度策略上几乎完全不同，这是这套引擎后续所有复杂度的根源：

• kernel 选择不同：prefill 用flash_attn_varlen_func（变长拼一起算），decode 用flash_attn_with_kvcache（带 cache 的特殊路径）。后文会展开。
• 调度策略不同：prefill 的约束在于避免显存溢出（token budget），decode 的约束在于避免 batch 过小（带宽利用率）。后文会展开。
• 优化重点不同：prefill 阶段 7PU 一般已经满载，性能上限是算力；decode 阶段 7PU 经常空转，性能上限是 CPU launch 开销。这也是后续引入 CUDA Graph 和 overlap scheduling 的原因。

拓展：PD 分离

既然 prefill 和 decode 在硬件瓶颈、kernel 选型、调度策略上都不同，能不能把它们放到不同机器上？这就是PD 分离（Prefill-Decode Disaggregation，Splitwise / DistServe / MoonCake 等近期工作的核心思想）：

• prefill 池：算力密集，用 H100/H200 这类高 FLOPs 卡；算完 prompt 把 KV cache 通过 RDMA / NVLink 传给 decode 池
• decode 池：带宽密集，用显存大、带宽高但 FLOPs 不必那么强的卡；只做 token 逐个生成

好处主要有四个：

1. 干扰彻底消除：prefill 的"算力大锤"不再卡住 decode 的"毫秒级 token 流"，TTFT（首 token 延迟）和 ITL（token 间间隔）可以分别优化
2. 硬件可以错配：prefill 节点配高算力卡、decode 节点配大显存卡，每一类各用所长，整体 $ / token 更优
3. 独立扩缩容：长输出场景下 decode 工作量远大于 prefill，可以单独扩 decode pool 而不动 prefill
4. SLO 解耦：两个池的指标互不干扰，prefill 池专注吞吐、decode 池专注尾延迟

代价：节点间要高速传 KV cache（依赖 RDMA / NVLink switch），调度系统要跨机 routing + 容灾，复杂度明显上升；小规模部署反而不划算。本系列只构建单机引擎，PD 分离不展开——但理解"为什么会出现这种架构"对后面读真实产线系统很有帮助。

下面这张图把两阶段的负载差异画出来，可作为后续讨论的原点。

3. KV Cache：核心的核心

它存在的根本原因

回看 decode 的每一步：算 attention(Q_new, K_all, V_all)。其中 Q_new 是当前这个新 token 的 query，K_all、V_all 是从 prompt 第 1 个 token 到上一个生成 token 的全部 key 和 value。

关键观察：K_all 和 V_all 的前 n-1 项在上一步已经算过了，没有任何理由再算一次。把它们存下来、增量追加新一项即可——这就是 KV cache。

再深入一层：为什么位置 i 的 K_i、V_i 不会随时间变化？因为它们都是 hidden state 的线性投影——K_i = W_k · h_i、V_i = W_v · h_i。而每一层 transformer 的 h_i 又来自 attention(Q_i, K_{0…i}, V_{0…i})——causal mask 让它只依赖位置 ≤ i，跟"未来生成的 token"完全无关。换句话说，一旦位置 i 的 K_i、V_i 写入 cache，后续无论生成多少新 token 都不会改它。这就是 KV cache 安全可重用的根本依据。

复杂度差异有多大

设隐藏维度为 d，生成第 k 个 token 时需要的计算量：

上面这张表里每一项的复杂度都能从矩阵形状直接读出来——(m×p) × (p×n)的乘法成本是m · n · p：

从 N³ 降至 N²。当 N=1000 时，差距达到 1000 倍。这并非一项普通优化，而是让 LLM 推理在工程上可行的前提。下文的示例代码将直观呈现这一差距。

它带来的新问题（伏笔）

KV cache 解决了一个根本瓶颈，但同时引入了两个新的工程问题，这两个问题贯穿后面几个阶段：

1. 显存占用爆炸：Llama-3 8B 在 4096 上下文下，单条请求的 KV cache ≈ 2 GB。100 个并发请求就吃掉 200 GB——而一块 H100 只有 80 GB 显存。这是后续引入 Paged KV Cache的动机。

2. 跨请求的浪费：很多生产场景里，所有请求共享同一份 system prompt。这部分 KV 完全可以复用，而不是每条请求都从头算一遍。这是后续引入 Radix Cache的动机。

本篇不展开这两个机制，只埋下伏笔——为后续的分页与 prefix tree 留好动机。

""" 示例：不加 cache 与加 cache 的复杂度对比 用一个 2 层、hidden=4096、vocab=100 的简化 GPT 跑两种生成方式： A) naive — 每生成 1 个 token 都重新跑整段序列 B) cached — prefill 一次后，decode 每步只算 1 个新 token 观察 wall-time 差距随生成长度增长是否符合理论： naive ∈ O(N³)，cached ∈ O(N²) """importtimeimporttorchimporttorch.nnasnnimporttorch.nn.functionalasF torch.manual_seed(42)# 有 GPU 就跑 GPU，没有就退回 CPU（示例模型的参数很小，非推理开销占比大，实测倍数可能远小于理论值）device=torch.device("cuda"iftorch.cuda.is_available()else"cpu")HIDDEN_DIM,NUM_HEADS,VOCAB_SIZE=4096,32,100# hidden=4096 接近真实 LLM 尺度HEAD_DIM=HIDDEN_DIM//NUM_HEADS# = 128classDemoAttn(nn.Module):def__init__(self):super().__init__()self.qkv=nn.Linear(HIDDEN_DIM,3*HIDDEN_DIM,bias=False)self.out_proj=nn.Linear(HIDDEN_DIM,HIDDEN_DIM,bias=False)defforward(self,x,kv_cache=None):# x 形状: [batch, seq, hidden]；kv_cache=None 表 prefill，否则 decode (seq=1)batch,seq,_=x.shape q,k,v=self.qkv(x).chunk(3,dim=-1)# 拆头：[batch, seq, hidden] → [batch, heads, seq, head_dim]q=q.view(batch,seq,NUM_HEADS,HEAD_DIM).transpose(1,2)k=k.view(batch,seq,NUM_HEADS,HEAD_DIM).transpose(1,2)v=v.view(batch,seq,NUM_HEADS,HEAD_DIM).transpose(1,2)# 关键：decode 时把新 K/V 追加到历史 cache 上——这就是 cache 复用的本质ifkv_cacheisnotNone:cached_k,cached_v=kv_cache k=torch.cat([cached_k,k],dim=2)v=torch.cat([cached_v,v],dim=2)new_kv_cache=(k,v)attn_out=F.scaled_dot_product_attention(q,k,v,is_causal=(kv_cacheisNone))attn_out=attn_out.transpose(1,2).reshape(batch,seq,HIDDEN_DIM)returnself.out_proj(attn_out),new_kv_cacheclassDemoGPT(nn.Module):def__init__(self):super().__init__()self.embedding=nn.Embedding(VOCAB_SIZE,HIDDEN_DIM)self.layers=nn.ModuleList([DemoAttn()for_inrange(2)])self.lm_head=nn.Linear(HIDDEN_DIM,VOCAB_SIZE,bias=False)defforward(self,token_ids,kv_caches=None):x=self.embedding(token_ids)new_kv_caches=[]fori,layerinenumerate(self.layers):x,layer_cache=layer(x,Noneifkv_cachesisNoneelsekv_caches[i])new_kv_caches.append(layer_cache)returnself.lm_head(x),new_kv_cachesdefgenerate_naive(model,prompt,max_new_tokens):# 每一步把整段 token_ids 重新过一遍模型——完全不复用历史 K/Vseq=promptfor_inrange(max_new_tokens):logits,_=model(seq)seq=torch.cat([seq,logits[:,-1:].argmax(-1)],dim=1)returnseqdefgenerate_cached(model,prompt,max_new_tokens):# prefill 一次性写入 cache；之后 decode 每步只把新 token 喂进去logits,kv_caches=model(prompt)last_token=logits[:,-1:].argmax(-1)output_pieces=[prompt,last_token]for_inrange(max_new_tokens-1):logits,kv_caches=model(last_token,kv_caches=kv_caches)last_token=logits[:,-1:].argmax(-1)output_pieces.append(last_token)returntorch.cat(output_pieces,dim=1)defsync():# CUDA op 是异步的，timing 前要同步；CPU 上是空操作ifdevice.type=="cuda":torch.cuda.synchronize()model=DemoGPT().to(device).eval()prompt=torch.randint(0,VOCAB_SIZE,(1,32),device=device)MAX_NEW_TOKENS=64withtorch.no_grad():# warmup：避开第一次 forward 的 kernel 编译 / cache 分配开销generate_naive(model,prompt,4)generate_cached(model,prompt,4)sync()t0=time.perf_counter();generate_naive(model,prompt,MAX_NEW_TOKENS);sync();t1=time.perf_counter()t2=time.perf_counter();generate_cached(model,prompt,MAX_NEW_TOKENS);sync();t3=time.perf_counter()print(f"device :{device}")print(f"prompt_len=32, max_new_tokens={MAX_NEW_TOKENS}")print(f"naive :{t1-t0:.3f}s")print(f"cached :{t3-t2:.3f}s ({(t1-t0)/(t3-t2):.1f}x faster)")

/opt/miniconda3/lib/python3.12/site-packages/torch/cuda/__init__.py:61: FutureWarning: The pynvml package is deprecated. Please install nvidia-ml-py instead. If you did not install pynvml directly, please report this to the maintainers of the package that installed pynvml for you. import pynvml # type: ignore[import] device : cpu prompt_len=32, max_new_tokens=64 naive : 4.900 s cached : 3.152 s (1.6x faster)

4. 推理引擎的核心模块

到此为止，单条请求内部发生的事情已经讲完。但工程上面对的从来都不是单条请求，而是并发的请求流。

单进程为何不够

理论上可以，但实际上不可行，原因有三：

1. Python GIL（Global Interpreter Lock）：CPython 同一时刻只允许一个线程执行 Python 字节码。tokenizer / Detokenizer / HTTP 处理都是 CPU 密集的纯 Python 代码，一旦它们抢到 GIL，Scheduler 主循环就只能等——GPU 因此空转。
2. GPU 调度需要独占主循环：Scheduler 必须在每个 step 之后立刻决定下一个 batch 怎么组——任何阻塞都会让 GPU 空转。
3. 故障隔离：tokenizer 抛异常不应该让整个引擎挂掉。

因此自然分成 4 类进程

我们要构建的推理引擎把整个系统拆成 4 个相互独立的 Python 进程，靠 ZMQ 消息总线相互连接：

• API Server：接 HTTP 请求、对接 OpenAI 兼容接口、维护 SSE 流式连接（SSE = Server-Sent Events，单向的 HTTP 推送，让客户端能边收 token 边显示）；
• Tokenizer Worker：把文本切成 token id（CPU 密集，独立进程不阻塞 GPU 调度）；
• Scheduler：拥有 GPU。维护请求队列、KV cache 池、Engine 实例；每一步决定哪些请求进入 batch；
• Detokenizer Worker：把生成的 token id 增量解码回文本（要处理多字节 UTF-8 的边界问题，独立成进程便于隔离）。

后续阶段都在拆这张图

本系列的大部分阶段，本质上都是在"展开其中某一个框"：

• 后续大部分阶段都发生在Scheduler 框内（KV cache、batch、调度、CUDA Graph、Radix、TP）；
• 直到系列末段才把API Server / Tokenizer / Detokenizer三个框展开，讲它们怎么和 Scheduler 通信、SSE 怎么实现、/v1/chat/completions怎么对齐 OpenAI 协议。

下方这张图给出整体地图，先把握其结构，内部细节后续逐一展开。

5. 系列阶段一览

整个系列分 9 个阶段（1~9），每个阶段以一个"可运行的里程碑"为终点：

每个阶段末尾建议停下来，通读自己写完的代码，再进入下一阶段。

小结

用一句话回到开篇所立的定义：LLM 推理引擎就是把"prompt → 续写"这件事，包装成一个能并发服务、显存利用率高、延迟可控的系统。它的核心结构有三层：

• 算法层：prefill / decode 两阶段 + KV cache，把生成 N 个 token 的复杂度从 O(N³) 压到 O(N²)；
• 调度层：batch、scheduler、paged cache、prefix tree，让多请求高效共享 GPU；
• 架构层：4 类进程 + ZMQ 消息总线，让 CPU、网络、调度互不阻塞。

接下来的每个阶段，都是在把这三层中的某一块"换成完整实现"。

下一篇预告

2 核心数据结构：Req与SamplingParams——下一篇将引入用于表示一条请求的Req结构，看它如何用cached_len/device_len等几个长度字段同时支撑 prefill 和 decode 两阶段，并理解 greedy 快路径的判定条件。