PP × HiCache L3
社区问题与修复全景

读完能带走 ③

一份可操作结论：PP+L2 / PP+L3 各自是否可用于生产、崩溃后如何从报错反推根因（第 11 页诊断路径）。

现状（2026-08）

L2+PP 系列修复已合入（#27285 / #28916 / #29258 / #31869…）。 L3+PP 主修复 #27010 仍是 open 状态。 maintainer 于 2026-08-05 在 #30158 明确表态：“PP + L3 is not supported yet.”

L1 → L2 备份（write-through）

触发：前缀在 L1 的命中数攒够阈值（_inc_hit_count）——是热点才值得花 D2H 带宽备份，将来被 GPU 逐出后还能从 L2 快速捞回。

链路：write_backup → controller.write 入 write_queue → start_writing 在独立 write_stream 上整批 D2H DMA（专用流，不占计算流、不影响正在跑的 forward）→ HiCacheAck 入 ack_write_queue → 每步 writing_check 用 finish_event.query() 非阻塞问「拷完没」，完成才收尾（发 KV event、标记 backuped、触发 L2→L3、解锁 device 副本）。

# Backed-up nodes must form a
# contiguous prefix from root
# (no gaps).
if not write_back and (
    node.parent != self.root_node
    and not node.parent.backuped
):
    return 0   # 父未备份 → 本节点跳过

hiradix_cache.py:858——为什么必须从根连续、不能有洞：树节点的完整前缀 = 根到它的整条路径。父节点没备份而子节点备份了，恢复时拿到的是「断头的中间段」——缺前缀的 KV 无法使用（attention 需要完整前缀）。所以父亲没备份，儿子先跳过，下次再说。

L2 → L1 回载（load_back）

触发：组 batch 时 match_prefix 发现前缀在树上有记录、但 device 副本已被逐出——数据只剩 L2 那份，要用必须先搬回 GPU。

边载边算：KV 按层组织、前向也逐层算，所以不必等全部拷完——init_load_back（hiradix_cache.py:1358）收集 evicted 祖先 → controller.load → load_stream 逐层 load_to_device_per_layer，每完成第 i 层就推进 LayerDoneCounter，计算流算第 i 层 attention 前 wait 到 i 即可。H2D 与前几层计算流水线重叠，回载延迟几乎被藏掉。

• 全有或全无：不足 load_back_threshold（10 token）不搬——搬运固定开销比重算还贵；超 mem_quota 放弃——不为回载把别人的热数据逐出去；
• 失败先 evict() 腾 device 空间再重试一次，仍不行就重算。

L2 → L3 备份（backup）

触发：卡片 ① 那条链的自然延续——L1→L2 的 write ack 收尾时顺手触发 write_backup_storage。注意介质换了：D2H 是 GPU DMA 走 stream，写 L3 是网络/磁盘 IO，改由后台 Python 线程承担。

链路：StorageOperation 入 backup_queue → backup_thread 按 STORAGE_BATCH_SIZE 分批 page_set → ack_backup_queue。期间 node.protect_host() 把 host 页钉住——写到一半源页被逐出，落到存储的就是垃圾。MLA 模型只有 tp_rank 0 写 L3：latent KV 在各 rank 完全相同，不去重会写 N 份一样的数据。

L3 → L2 预取（prefetch，唯一可撤销）

触发时机最特别：请求刚入 waiting queue 就发起（scheduler.py:2427 _prefetch_kvcache），不等被调度——用排队的「死时间」掩盖 L3 的网络延迟，轮到组 batch 时数据最好已在 L2。

链路：prefetch_from_storage 分配 host 内存、登记 ongoing_prefetch[rid] → 后台线程先 batch_exists 问存储「这个前缀你存了多长」，命中不足阈值直接 revoke（连下载都不开始）；足够才分批 page_get，每批产一个 PrefetchAck(completed_tokens)。线程流水线见下页。

它与前三条的本质区别：预取是投机——请求可能被 abort、命中可能不足、排队时间可能不够，所以全程支持中途放弃。而这些每批一个的 ack，正是第 16 页 MIN 投票的「选票」、第 20 页 abort 后「空转也要发够」的那个东西。

预取全流程（L3 → L2，逐步走一遍）

• 步 1 · 提交（调度线程）：请求入 waiting queue 时 prefetch_from_storage——分配 host 内存、登记 ongoing_prefetch[rid]、任务丢进 prefetch_queue，立即返回。
• 步 2 · 探询（① prefetch_thread）：batch_exists 问 L3「这个前缀你存了多长」，命中长度跨 rank MIN 汇聚；不足阈值 → 丢 prefetch_revoke_queue，整个预取撤销，到此为止。
• 步 3 · 下载（② prefetch_io_aux）：任务经 prefetch_buffer 移交，分批 page_get 把 KV 页下载进 host；每下完一批往 prefetch_sync_queue 丢一个 PrefetchAck(completed_tokens=本地累计)。
• 步 4 · 投票（③ prefetch_sync_thread）：把第 k 批 ack 与其他 rank 的第 k 批做 all_reduce(MIN)（gloo），共识进度写入 ack_prefetch_queue。
• 步 5 · ack 回收 / 结算（调度线程）：每步 check_hicache_events 消费共识进度与 revoke；请求出队组批时终止预取，用最后一个共识值当 host 命中长度。

步 3–5 的逐帧图解就是第 16 页；abort 打进来时步 3 不得提前退出（第 20 页）。

备份全流程（L2 → L3，只有三步）

• 步 1 · 提交（调度线程）：L1→L2 的 write ack 收尾时触发 write_backup_storage——StorageOperation 入 backup_queue，host 页 protect_host() 钉住防逐出。
• 步 2 · 写出（④ backup_thread）：按 STORAGE_BATCH_SIZE 分批 page_set 写进 L3 后端，完成凭证入 ack_backup_queue。
• 步 3 · ack 回收（调度线程）：解除 protect、节点标记已入 L3。

备份链比预取链简单得多的原因：写 L3 是纯本地副作用，结果不影响任何调度决策，所以不需要跨 rank 投票——ack_backup_queue「只能本地排水」说的就是这个。预取则相反：它的结果（命中多长）直接进组批决策，必须走共识。

①收请求：只碰 L2 的「池账」，树上无痕

process_input_requests 构造 Req 入 waiting_queue，本身不碰任何缓存；真正动手的是入队瞬间的 _prefetch_kvcache（scheduler.py:2427）：从 HostKVCache 池 alloc 一段 host 页、登记 ongoing_prefetch[rid]，随即返回。

排队期间，后台线程（第 5 页 ①②）分批 page_get 把 L3 字节持续写进这段页——但页尚未挂上 host 树，别的请求看不见；revoke / abort 可整段退回（第 20 页）。L1 在本步一个字节、一个节点都不动。

③组批：全部元数据修改的收口，固定顺序三小步

• ack 回收与状态提交（check_hicache_events，hiradix_cache.py:1459）：write ack → 节点标 backuped（host_value 生效，顺手触发 L2→L3）；load ack → 清 loading 标记；L3 预取按 MIN 共识值结算——已到前缀挂上 host 树、尾段 host 页退回。
• 匹配 + 回载：match_prefix 部分命中会分裂 TreeNode——查询也改树形；命中段若 device 副本已被逐出，init_load_back（hiradix_cache.py:1358）alloc device slot 并提交逐层 H2D。
• 分配 + 上锁（alloc_for_extend）：req_to_token_pool 占 slot、alloc_token_slots 给新 token 留位——不够先 evict()（L1 唯一的删除入口，LRU 剪除 lock_ref==0 子树，common.py:278）；inc_lock_ref 把前缀整条路径锁成 protected。decode 侧 prepare_for_decode 每请求 +1 slot、kv_committed_len += 1。
• chunk 尺寸（PP + --enable-dynamic-chunking 时）：续 chunk 的 token 数也在本步定——用全员同构的延迟模型解出，决策输入是启动时广播的画像数据、不是各 rank 自测的耗时（第 18 页）。

三小步的走查示意见本页下方图 4c。

⑤前向：唯一大规模写 KV 字节的地方，三条流并发

• 计算流：每层 attention 算出新 K/V，当场 set_kv_buffer 写进 ③ 分好的 out_cache_loc——extend 一次写 N 行、decode 写 1 行（memory_pool.py:1052）。
• load 流：load_to_device_per_layer 逐层 H2D 落回载字节，拷完第 i 层推进 LayerDoneCounter，计算流等到 i 才算第 i 层——「边载边算」（第 4 页卡片 ②）。
• write 流：此前提交的 L1→L2 备份在 write_stream 上做 D2H——只读 device、写 host，不占计算流。

三条流并发碰同一个 pool 而不打架，靠的是 slot 所有权在 ③ 已划清：计算流只写本批的 out_cache_loc，load 流只写重新占位的 slot，write 流只读被锁住的前缀。

L2 · writing_check 的前后（#27285 系）

# 修复前（upstream pre-#27285 的形态）
while ack_write_queue:
    ack = ack_write_queue[0]
    if not ack.finish_event.query():  # ① 问本地进度：DMA 拷到哪了
        break
    ack_write_queue.pop(0)         # ② 答案直接决定 drain 数
    _finish_write_through_ack(ack) # ③ 消费 ack 改树 → 分歧

# 修复后（hiradix_cache.py:1006）
finish_count = 0                      # 先只数 ack，不消费
for _, ev, _ in ack_write_queue:
    if not ev.query(): break          # 本地照样问
    finish_count += 1
finish_count = self._sync_hicache_ack_finish_count(
    finish_count)
                                      # ← 新增：TP-MIN + PP 节拍
while finish_count > 0:               # 按协议数精确消费
    ack_write_queue.pop(0); ...

query() 那行还在——物理进度无法对齐也不必对齐；插入的是高亮那一道协议变换。两个细节：PP 方向只传节拍、不沿用 PP0 计数（各 stage DMA 队列深度不同，沿用 → 形态 B pop from empty list）；同步必须无条件执行（条件跳过 → NCCL 序错位死锁，#26923）。

L3 · 预取结算的前后（#27010 系）

# 修复前（pre-#27010）：结算直接读本地进度
completed = operation.completed_tokens   # 纯本地读数
matched = min(host_hit_len, completed)   # 一跳进命中长度
                                         # → 896 vs 0（图 5）

# 修复后（hiradix_cache.py:1543）——两道协议
# 道1·进度值：每批 ack 先过 prefetch_sync_thread 的
#   all_reduce(MIN) 才推进 completed_tokens（第 16 页）
should_terminate = False
if self.pp_rank == 0:                 # 道2·只有 PP0 有权判断
    should_terminate = op.is_terminated() or \
        self.can_terminate_prefetch(op)
self._all_reduce(t, ReduceOp.MAX)     # 裁决广播
if t.item() != 1: return False
terminate_prefetch(op)                # 全员同刻终止
handle_prefetch_result(op)            # 用共识进度结算

completed_tokens 连名字都没变，但它的取值来源（本地累计 → MIN 共识）和读取时机（各自随时读 → PP0 裁决、全员同刻）都被协议接管——L3 的 per-rank 读数本来一跳直达命中长度，所以要包两道。

背景 · 立项

2026-05-13 周会决议：先保证 L2+PP 绝对正确，再攻 L3（L3 宕机时 PP 无 fallback）。于是从 L3 大 patch #27010 中把 L2 部分拆出为本 PR。作者 stepinto，2026-06-06 合入；改动横跨 hiradix_cache / unified_radix_cache / cache_controller / hybrid_cache，并新增 e2e KL 测试。

背景 · 立项

恒定速率的算术解释：每轮固定的 clone + Work 句柄开销 × PP0 与 PP1 的循环速率差 = 常数斜率，与流量无关。作者 whybeyoung，2026-06-23 合入；同样的修复镜像到 UnifiedRadixCache。流水线定位：与 #27285 同址——③ 组批第一行的 check_hicache_events。

背景 · 立项

umbrella #22607 的终点站：周会决议先拆出 L2（#27285），剩余 L3 部分即本 PR（作者 stepinto，仍 open）。改动横跨 cache_controller / hiradix_cache / unified_radix_cache / mooncake_store 等六个模块、新建两个通信组。验证结果见本页下方「三问」。

通道 1PG1 · 命中长度投 MIN

探询线程各自问 L3「这个前缀你存了多长」。各 rank 拉的是自己的 KV 分片——走不同网卡、落不同存储节点，答案天然不同，查询失败还可能是 0。修复后：本地答案先在专用 gloo 组上 all_reduce(MIN)，全员再拿共识值决定「下不下、下多长」。

为什么取 MIN：共识长度以内的数据每个 rank 都真实拿得到——MIN 是唯一全员兑现得起的值。

通道 2PG2 · 下载进度逐批投 MIN

下载线程每完成一批，产一个 PrefetchAck(completed_tokens=本地累计)。本 PR 新增一条投票线程 prefetch_sync_thread，只做一件事：拿本 rank 的第 k 个 ack 与其他 rank 的第 k 个做 all_reduce(MIN)，把「全员都至少下到了多少」写进调度线程读的队列。

③ 组批读到的永远是共识进度——PP0 本地 896、PP1 本地 300，两边读到的都是 300；本地进度从不直接进决策（逐帧动画：第 16 页）。

通道 3pp_sync · 控制决策 leader 裁决

「何时终止预取」「本步 drain 几条消息」是控制类决策，不适合对称投票：终止用 all_reduce(MAX)——有一个 rank 说该停就全员停；drain 数量先 TP/CP 内 MIN、再取 PP0 的值沿 PP 链下发，其余 rank 服从。

数值类 MIN、控制类 leader——第 2 页的两种对齐原语在此并用。

per-rank 量只进入系统一次：画像 → 广播 → 纯函数

• PP0 单点画像（scheduler_pp_mixin.py:1776）：启动时构造 128 个 token 数递减的 dummy 请求逐个前向实测延迟；DPA 下还须填 global_num_tokens（本 dp 组 = 长度、其余 0）发起 idle batch 参与 MLP sync（:1831，#17339）——呼应组合场景 deck DPA 页的「必须发起 idle batch」。
• 广播原始样本：先 attn_tp 组内 broadcast，再 pp_group.broadcast_object_list(src=0)（:1930）——发的是 (seq_lens, latencies) 原始数据，不是各 rank 自己测。
• 全员同拟合：每个 rank 用同一份数据跑同一个确定性 lstsq（:2654；丢弃首样本防无 warmup 偏差 #17198，样本 < 8 或 a ≤ 0 拒绝拟合）。此后 predict(history_len) 是纯函数，history_len 本受请求流契约保护——全网格解出同一个 chunk size，运行时零通信。
• 失败安全：画像抛异常 → 告警并退回固定 chunk（scheduler.py:1058）；预测无解返 None → 用 base。

与 #27285 / #27010 同款范式（第 13 / 16 页）：不对齐 IO、只对齐决策输入——延迟这个 per-rank 量在启动时被采样一次，随即转为协议数据。

落点与修复沉淀

• 只作用于续 chunk：组批时仅当 chunked_req 非空才预测（scheduler.py:3130）——首 chunk 用 base，后续按 history 递减；prefill buffer 按 1.25×base 预留探测余量（server_args.py:5368）。
• 修复沉淀：#15372 采样 32→128 点、对齐下限 page→max(page, 64)；#16140 chunk 下限 base/4——防长 history 下解出微小 chunk、固定开销反超收益；#17198 拟合丢首样本；#17339 DPA 画像参与 collective。平滑系数 SGLANG_DYNAMIC_CHUNKING_SMOOTH_FACTOR=0.75 防尺寸骤降。
• centralized 方案再进一步：本地 plan-driven 分支里，chunk 尺寸随 extend_lens、chunked_rid 编入 PPPrefillPlan 由 PP0 统一下发，其余 rank build_batch_from_plan 镜像 chunked_req 指针（scheduler_pp_mixin.py:143/794）——从「全员同构地各自算」升级为「单点算、协议发」。

chunk 与缓存的交界不变：每片结束仍走 cache_unfinished_req 入树 + 锁移交（第 8 / 22 页），动态的只是「下一片切多长」。

DPController 细拆：不只是个转发器

• 身份：独立进程 sglang::data_parallel_controller，同时是整个 dp × pp × tp Scheduler 网格的父进程——所有 Scheduler 都由它按 pp_rank × tp_rank 双重循环 fork 出来（data_parallel_controller.py:481）。多节点时只有 node_rank 0 的 controller 跑分发 event_loop，其余节点的只做拉起与守护。
• 消息三分法（:259）：生成 / 嵌入请求 → 按策略挑一个 dp 组；Profile / Block 类 → 发全体 worker；其余控制消息（AbortReq 等）→ 只发每个 tp 组的 rank0，组内复制交给既有广播通道（组合场景 deck）。发错的后果各不相同：请求发两组 = 重复计算重复回包；全局事漏一个 = 状态不齐；控制事发全员 = 与组内广播重复送达、消息序列分叉。
• 负载从共享内存来：「多忙」只有 Scheduler 自己知道，跨进程怎么拿？问一圈（请求-响应）= 每次分发一个往返、阻塞分发热路径；让 Scheduler 推送 = 新增一条消息流、有堆积；写 shm 快照 = 写方无锁零开销、读方随取——负载天然容忍几毫秒陈旧，不值得付一次通信（DPBudget，:91，按时间戳去重）。滞后的代价用两招补：每分发一个请求即本地投机 +1 + 真实快照最多 20ms 刷一次（:220）——否则突发下每次分发都采信滞后快照，整批集中落到同一个 dp 组。
• 外部路由优先：req.routed_dp_rank 已被 router 指定则直通（:599），本地策略仅作为回退——PD 部署下选组权在 router，不在 controller。

支柱 1等耗时：动态分块

把「等 token 数」换成「等耗时」：PP0 启动时实测 128 个递减 chunk 拟合 f(l)=al²+bl+c，运行时对续 chunk 解 f(L+x)−f(L)=T 反推 token 数——每片耗时恒定，流水线无凸块（--enable-dynamic-chunking，仅 pp>1，scheduler.py:1058）。

数值防线：下限 base/4 · 对齐 max(page, 64) · 平滑 0.75 · 上限 context−L−100。

支柱 2一致性：per-rank 量只进入系统一次 + 单点决策

延迟画像只在 PP0 采样，broadcast_object_list 广播原始样本，全员跑同一个确定性 lstsq → predict(history_len) 是纯函数、运行时零通信。本地 centralized 方案更进一步：PP0 组批，chunk 尺寸随 extend_lens / chunked_rid 编入 PPPrefillPlan 下发，下游 build_batch_from_plan 镜像 chunked_req（scheduler_pp_mixin.py:143/794）——从「全员同构地各自算」升级为「单点算、协议发」。

支柱 3状态提交与异常不变式

chunk 间隙照走 cache_unfinished_req：已算 KV 入树、锁移交更深节点（第 22 页 ⓑ）；chunked 半途 abort 不当场拆——记 _pending_chunked_abort，下个调度步开头这个全员必经的位置统一清（scheduler.py:2689）；PP 下 abort 先记 intent、按固定节奏经 plan 生效，不允许任何 rank 单方面跳过 collective。

一定要上 PP + L3

• 跟进 #27010 分支自行验证；
• SGLANG_ENABLE_UNIFIED_RADIX_TREE=1 缓解 LRU 时钟发散；
• 调小 --hicache-size；监控三种崩溃签名并配 crash 转储。