agentic-pd-hybrid/docs/D_TO_P_SYNC_DESIGN_ZH.md

D→P KV 反向推送设计

日期：2026-05-12 分支：h200-cu130（在此分支上做，后续 cherry-pick 到 feat/d-to-p-sync 备用） 目标：让 reseed 路径绕过 P 端 re-prefill，把 reseed 总耗时从 3-7s 压到接近一次 RDMA P→D' 传输（~200-400ms） 前置：docs/RESEED_SLOW_PATH_AND_D_TO_P_GAP_ZH.md（reseed 现状），docs/KVC_EVICTION_GRANULARITY_DESIGN_ZH.md（架构层背景）

---

0. TL;DR

1. 现状：v2 reseed 路径 = P open session + P 完整 re-prefill（~1.5-3s）+ P→D' mooncake transfer（~200-400ms RDMA）。re-prefill 段是 KVC TTFT p99 的主体。
2. 目标：D 在 direct-to-D append 完成后异步把新 KV 增量推回 P。reseed 触发时 P 已经有 fresh snapshot → 跳过 model.forward()、直接复用 KV 做 P→D' 传输。
3. 决策：选 Option C —— D→P snapshot 按 append-completion 推送，P 端用独立 PrefillSnapshotStore 存储（不进 radix tree），prefill 在有 snapshot 时 bypass 计算只触发传输。
4. 拒绝的 alternatives：A（让 P radix tree 接受多生产者写入，§4.3 工程灾难）、B（D→D' 直推，绕过 P，但 mooncake 无 D-Sender 角色 + session-not-resident 场景失败）、D（仅 eviction 时推，async 来不及 + sync 拖死 eviction）。
5. 工程量：~600 LOC，拆 6-8 commit。最难的是 mooncake 双角色化的 thread-safety 和 P 端 prefill bypass 的调度器 hook。
6. 必须 RDMA：所有传输走 mooncake batch_transfer，不允许 TCP fallback。

---

1. 决策依据

Option A — P radix tree 多生产者写入（拒绝）

让 P 端 RadixCache 接受 D 喂来的 KV 块，融入 prefix tree。

为何拒绝：

• SGLang radix tree 假设单生产者（本 worker 的 model 输出）。改动涉及节点写入路径、引用计数、跨 worker 数据格式、eviction policy 协调。
• 工程量 ~1-2 周，且是侵入式改动，长期维护成本高。
• 与 vendor 上游 diff 太大，未来 rebase 风险高。

Option B — D→D' 直推（拒绝）

migration 时 D_old 把 KV 直接发到 D_new，绕过 P。

为何拒绝：

• 触发条件 session-not-resident 时 KV 已 free，D_old 拿不到任何数据可推。
• mooncake DECODE 模式当前只有 receiver 角色（assert disaggregation_mode == PREFILL at conn.py:1563）；新增 D-Sender 角色与 P-Receiver 角色对偶，工程量与 Option C 相当但只 cover 部分场景。
• D→D' 控制平面需要额外协调（"哪个 D 当前持有 session"），增加路由复杂度。

Option C — D→P snapshot + P SessionSlot + prefill bypass（选定）

D 在 append-completion 时异步把整个 session 当前 KV 镜像推到 P；P 用一个独立的 PrefillSnapshotStore 存（不进 radix tree）；reseed 时 P 跳过 model.forward()，直接用 snapshot 触发 P→D' 传输。

为何选它：

1. P 端不动 radix tree——SnapshotStore 是侧表，无 multi-producer 问题
2. mooncake 改动局部化——只放开 add_transfer_request 的 PREFILL assertion + 在 DECODE 模式启动一个独立 snapshot transfer 线程
3. 可以分阶段验证——D→P 推 → P 收到 → P 存 → P 用，每一步可独立 smoke test
4. failure semantics 干净——snapshot 缺失就 fallback 到现有 re-prefill 路径，零回退风险
5. 跨 P 的扩展简单——P-Receiver 状态在 P 上，多 P 时各管各的 session

Option D — 仅 eviction 时推（拒绝）

D 在驱逐 session 之前推一次 KV 到 P，平时不推。

为何拒绝：

• async 推送：reseed 触发时（下一 turn 到达）可能 push 还没到 P 完。需要 reseed path 等 push 完成 → 把延迟成本只是搬家。
• sync 推送：让 eviction 等 mooncake transfer 完，当前 incoming request（触发 eviction 的那个） 直接被拖死 1-3s。比当前 reseed 还差。
• 不能 cover 非 eviction 触发的 reseed（如 migration、admission-no-d-capacity）。

---

2. 架构

+---------------- D worker (decode_thread + new snapshot_sender_thread) -----+
|                                                                            |
|  direct-to-D append done                                                   |
|        |                                                                   |
|        v                                                                   |
|  on_session_step_committed(session_id, kv_committed_len, kv_indices)        |
|        |                                                                   |
|        v                                                                   |
|  SnapshotSendQueue [throttle by token-delta >= K_DELTA]                    |
|        |                                                                   |
|        v                                                                   |
|  KVSnapshotSender                                                          |
|        |                                                                   |
|        | mooncake batch_transfer (RDMA)                                    |
|        v                                                                   |
+-----------------------------|----------------------------------------------+
                              |
                              v
+---------------- P worker (prefill_thread + new snapshot_receiver_thread) ---+
|                                                                            |
|  KVSnapshotReceiver listening (ZMQ control + mooncake data)                |
|        |                                                                   |
|        v                                                                   |
|  PrefillSnapshotStore[session_id] -> SnapshotEntry {                       |
|      req_pool_idx, kv_indices, kv_committed_len, last_recv_time            |
|  }                                                                         |
|                                                                            |
|  When prefill request arrives with session_id + snapshot_token:             |
|        |                                                                   |
|        v                                                                   |
|  prefill_bypass_check(session_id, requested_seq_len)                       |
|     | hit: skip model.forward, reuse stored kv, fire P→D' transfer        |
|     | miss: fall through to normal prefill                                 |
+----------------------------------------------------------------------------+

+--------------- agentic-pd-hybrid (replay.py) -------------------------------+
|                                                                            |
|  _invoke_kvcache_seeded_router (reseed entry):                              |
|    1. GET /v1/sessions/{sid}/snapshot_status on P → seqlen                  |
|    2. if seqlen >= requested input_len:                                     |
|         set request header x-prefill-use-snapshot=1                         |
|         route to P → P uses bypass path                                     |
|       else:                                                                 |
|         normal seeded_router (re-prefill)                                   |
+----------------------------------------------------------------------------+

---

3. 数据流时间线

3.1 Direct-to-D append + 异步 D→P push

t=0     turn N 到 D，走 direct-to-D append-prefill
t=T1    direct append 完成，scheduler 调 cache_finished_req
        SessionAwareCache.cache_finished_req 把 KV 写回 SessionSlot
        (此时 KV 全在 D 的 kv_pool 里，slot 持锁)
t=T1+ε  D-side hook: on_session_step_committed(sid, slot)
        计算 delta = slot.kv_committed_len - last_pushed_seqlen[sid]
        if delta >= K_DELTA (默认 1024 tokens): 入队 SnapshotSendQueue
t=T1+δ  snapshot_sender 线程取出 entry → mooncake batch_transfer
        把 kv_pool[slot.req_pool_idx, 0:kv_committed_len] 推到 P
t=T1+δ' P-side mooncake receive callback 触发
        P 在 kv_pool 预分配 slots → 写入 → 更新 SnapshotStore[sid]
t=T2    P 标记 snapshot 可用，更新 last_recv_time

关键约束：D→P push 与 D 自己的 decode/append 在不同 thread/stream，必须保证 KV 在传输期间不被 evict。

• 复用 SessionSlot 的 lock_ref 机制：snapshot_sender 在传输期间 hold lock，传输完后 dec_lock。
• 如果 session 在传输期间被 release_session 调用，snapshot 应该 abort（数据不一致）。

3.2 Reseed 触发 + P 走 bypass 路径

t=0      turn N+M 到达，KvAwarePolicy 选 D'，但 admit 拒绝（capacity / not-resident）
t=10ms   replay.py 进入 _invoke_kvcache_seeded_router
t=15ms   probe: GET p/v1/sessions/{sid}/snapshot_status -> {seqlen: 50080, fresh: true}
t=20ms   replay: 50080 >= request.input_length (49800)，触发 bypass 路径
t=25ms   open D' streaming session (HTTP)
t=30ms   open P streaming session, set x-prefill-use-snapshot header
t=40ms   forward request to SGLang pd-router → P
t=45ms   P scheduler 看到 use-snapshot 标记
         → SnapshotStore.lookup(sid) -> SnapshotEntry
         → 跳过 model.forward()
         → 直接复用 SnapshotEntry.kv_indices 给 mooncake KVSender
t=50ms   mooncake P→D' RDMA transfer 启动
t=300ms  P→D' 完成，D' 上 session 重建
t=305ms  D' 开始 decode
t=350ms  first token 出来 → TTFT

收益对照：

段	当前 reseed	bypass 后
P open session	~50ms	~50ms
P re-prefill	~1500-3000ms	0
P→D' transfer (RDMA)	~200-400ms	~200-400ms
D' decode start	~50ms	~50ms
TTFT 总	~1.8-3.5s	~0.3-0.5s

---

4. 接口和数据结构

4.1 Mooncake 双角色

Change: MooncakeKVManager.__init__ 在 DECODE 模式下额外启动 snapshot sender 基础设施（独立 transfer_queues + thread pool）。

# In MooncakeKVManager.__init__, after start_decode_thread() in DECODE mode:
if envs.SGLANG_DTOP_SNAPSHOT_ENABLED.get():
    self._init_snapshot_sender()  # new

def _init_snapshot_sender(self):
    self.snapshot_send_queue: FastQueue = FastQueue()
    self.snapshot_executor = ThreadPoolExecutor(max_workers=2)
    threading.Thread(
        target=self._snapshot_send_worker,
        daemon=True,
    ).start()

Change: 删除 add_transfer_request 的 assert PREFILL，改为按 caller 路径分发：

• add_transfer_request —— prefill 用，保持现状
• add_snapshot_transfer_request —— 新增，decode 用

4.2 新 class：DecodeKVSnapshotSender

class DecodeKVSnapshotSender:
    """Sender on D for pushing session KV snapshot back to P."""
    def __init__(self, mgr: MooncakeKVManager, target_p_addr: str,
                 target_p_bootstrap_room: int, session_id: str):
        ...

    def send(self, kv_indices: npt.NDArray[np.int32],
             kv_committed_len: int, aux_blob: bytes) -> None:
        """Enqueue snapshot for async push. Non-blocking."""

    def poll(self) -> KVPoll: ...

4.3 P 端 PrefillSnapshotStore + Receiver

@dataclass
class SnapshotEntry:
    session_id: str
    req_pool_idx: int
    kv_indices: torch.Tensor   # device indices into kv_pool
    kv_committed_len: int
    aux_blob: bytes
    last_recv_time: float


class PrefillSnapshotStore:
    """Side-table on P: session_id -> SnapshotEntry. NOT in radix tree."""
    def __init__(self, kv_pool_allocator, req_to_token_pool, max_sessions: int = 8):
        self.entries: dict[str, SnapshotEntry] = {}
        self.max_sessions = max_sessions
        ...

    def ingest(self, session_id: str, kv_data: torch.Tensor,
               kv_committed_len: int, aux_blob: bytes) -> None:
        """Allocate slots, copy KV in, register entry. LRU-evicts when full."""

    def lookup(self, session_id: str) -> Optional[SnapshotEntry]: ...

    def release(self, session_id: str) -> None:
        """Free the slots + remove entry."""

4.4 P-side prefill bypass 调度器 hook

Change: scheduler.py 在 handle_generate_request 入口处检查 x-prefill-use-snapshot header / session_params.use_snapshot=True：

if snapshot_requested and self._snapshot_store.has(session_id):
    entry = self._snapshot_store.lookup(session_id)
    if entry.kv_committed_len >= len(input_ids) - K_TAIL_TOLERANCE:
        return self._bypass_prefill_with_snapshot(req, entry)
# else: normal prefill

_bypass_prefill_with_snapshot 把 entry 的 kv_indices 作为 prefix_indices 喂给 mooncake sender 启动 P→D' 传输，完全跳过 model.forward()。

4.5 D 端 commit hook

Change: scheduler.py 在 handle_finish_request / cache_finished_req 完成后调用：

if (self._enable_d_to_p_sync and req.session and req.session.streaming
        and self._has_p_snapshot_target(req.session.session_id)):
    self._maybe_enqueue_snapshot_push(req.session.session_id)

_maybe_enqueue_snapshot_push 检查 delta，符合阈值就 enqueue 到 snapshot_send_queue。

4.6 HTTP endpoints (P)

GET  /v1/sessions/{sid}/snapshot_status
     -> {"exists": bool, "seqlen": int, "freshness_s": float}

POST /v1/sessions/{sid}/snapshot_target
     -> {"bootstrap_addr": str, "bootstrap_room": int}
     (D queries this once per session to learn where to push)

4.7 agentic-pd-hybrid hook

File: src/agentic_pd_hybrid/replay.py

In _invoke_kvcache_seeded_router, before opening P session:

if config.enable_d_to_p_sync:
    snapshot_status = await _probe_p_snapshot(
        client, prefill_url, session_id, target_seqlen=request.input_length,
    )
    if snapshot_status and snapshot_status["fresh"]:
        # bypass path
        return await _invoke_kvcache_snapshot_bypass(...)
# else: existing seeded router

4.8 CLI flag

--enable-d-to-p-sync   (default off)
--d-to-p-sync-delta-tokens   (default 1024)
--d-to-p-sync-max-sessions   (default 8 on P)

---

5. 实现路线图（每步独立 commit）

#	Commit subject	Files	Why a separate commit
1	feat(sglang): mooncake bidirectional infra for D→P snapshot	third_party/sglang/.../mooncake/conn.py	隔离 mooncake 层改动；不破坏 PD-disagg 现有路径
2	feat(sglang): PrefillSnapshotStore + DecodeKVSnapshotSender	third_party/sglang/.../mem_cache/, third_party/sglang/.../disaggregation/mooncake/	新数据结构
3	feat(sglang): P-side prefill bypass with snapshot	third_party/sglang/.../managers/scheduler.py, tokenizer_manager.py	调度器 hook，最危险，单独提交便于回滚
4	feat(sglang): D-side session commit hook → snapshot push	third_party/sglang/.../managers/scheduler.py, session_aware_cache.py	D 端 trigger
5	feat(sglang): HTTP endpoints for snapshot status/target	third_party/sglang/.../entrypoints/http_server.py	API 表面
6	feat(agentic): D→P sync hook in seeded_router	src/agentic_pd_hybrid/replay.py	客户端逻辑
7	feat(agentic): --enable-d-to-p-sync CLI + config	src/agentic_pd_hybrid/cli.py, benchmark.py	CLI 接入
8	feat(experiments): smoke test + E4 sweep scripts	scripts/, docs/D_TO_P_SMOKE_RESULTS_ZH.md	验收 + 落盘

---

6. Metrics + 观察性

Structural log channels（写到 structural/d-to-p-sync.jsonl）

{"ts": ..., "event": "snapshot_push_enqueued",  "sid": "...", "delta": 2048}
{"ts": ..., "event": "snapshot_push_sent",      "sid": "...", "bytes": 4_200_000_000, "dur_ms": 320}
{"ts": ..., "event": "snapshot_push_failed",    "sid": "...", "reason": "..."}
{"ts": ..., "event": "snapshot_recv_ingested",  "sid": "...", "seqlen": 50000}
{"ts": ..., "event": "snapshot_evicted",        "sid": "...", "reason": "lru|session_close|stale"}
{"ts": ..., "event": "snapshot_bypass_hit",     "sid": "...", "seqlen": 50000, "saved_prefill_ms_est": 1800}
{"ts": ..., "event": "snapshot_bypass_miss",    "sid": "...", "reason": "no_entry|stale|seqlen_short"}

Per-request metrics (additional fields in metrics.jsonl)

d_to_p_snapshot_used: bool
d_to_p_snapshot_age_s: float | None
d_to_p_push_count_during_session: int

Sweep summary 应回答的问题

1. snapshot push 触发频率（每秒多少次）
2. snapshot LRU eviction 是不是瓶颈（freshness 分布）
3. reseed 触发时 bypass hit rate
4. bypass vs fallback 的 TTFT 分布对比

---

7. 失败模式 + 回退

失败模式	现象	处理
D→P transfer 中途失败	mooncake KVPoll.Failed	snapshot_send_queue 重试 1 次，再失败放弃；保留旧 entry
P snapshot store 满	LRU 淘汰最旧 entry	log eviction event
reseed 时 snapshot stale	entry.kv_committed_len < requested input_len - K_TAIL_TOLERANCE	回退到 normal re-prefill
D 重启 / session 丢失	D 上 session_aware_cache 没了	snapshot_target 注册过期；下次 push 收到 404 → 清理 D 端记录
P 重启	snapshot store 清空	下次 reseed probe 拿到 not-exists → fallback
双重 push（多个 D 喂同一 session）	不该发生（session 同时只在一个 D），但保险起见用 last-write-wins + log warning

核心不变量：D→P sync 失败永远只导致 fallback 到现有 re-prefill 路径，不影响正确性。

---

8. 测试

Smoke test 阶段（commit #8）

scripts/smoke_d_to_p_sync.sh：

1. 启 1P1D，开启 --enable-d-to-p-sync
2. 跑 5 sessions × 3 turns 的迷你 trace
3. 触发条件：第二 turn direct-to-D append 完成后强制 capacity-evict（用 admission flag 调小）
4. 第三 turn 必然走 reseed 路径
5. 验证：
   • structural log 有 snapshot_push_sent + snapshot_recv_ingested
   • 第三 turn metrics 显示 d_to_p_snapshot_used=true
   • TTFT 与 cold prefill 的差异 ≥ 1s

E4 端到端 sweep（feature 验收完成后）

详见 §9。

---

9. 实验：E4 KVC w/ D→P vs naive PD-disagg

目标：证明 KVC + D→P 在保持 session affinity 设计独特性的前提下 latency 优于 naive PD-disagg（E1 baseline）。

实验矩阵

#	配置	期望验证
E1（已有）	naive 1P3D + kv-aware + RDMA	baseline，无 KVC 层
E3（已有）	KVC v2 + RDMA + load-floor	KVC 但无 D→P，reseed 重 prefill
E4	KVC v2 + RDMA + load-floor + D→P	KVC + D→P bypass
E4-ablate	KVC v2 + RDMA + load-floor + D→P，但人为 disable bypass	排除 push 流量本身的副作用

假设

• H4-1：E4 的 TTFT p99 ≤ E1。证明：KVC + D→P 在 p99 长尾上不再输 naive PD-disagg。
• H4-2：E4 的 reseed 占比（execution_mode=reseed）不变，但 reseed 路径自身 TTFT 中位 ≤ E1 normal 路径 TTFT 中位。
• H4-3：E4 的总 throughput 略低于 E3（因为 D→P 推送占带宽），但 TTFT/latency 优势足以补偿。

数据集

• outputs/inferact_50sess.jsonl（同 E1/E2/E3）
• md5 7bb263a32600ef5a6ef5099ba340a487

报告（事前 commit docs/E4_PROTOCOL_ZH.md，跑完后 docs/E4_RESULTS_ZH.md）

每个 hypothesis 标注：

• 证实 / 证伪 / 部分证实
• 数字证据
• 失败原因（若证伪）
• 后续工作建议

---

10. 边界 + 非目标

本设计不解决：

• D→D' 直推：未来若证实场景 X 必须用，可走 Option B 作为补充
• 跨 P 协调：现假设单 P。多 P 时每个 P 各自维护自己的 snapshot store，session 路由到哪个 P 是 router 决定
• 跨节点 mooncake：当前 H200 是单机 4 GPU，IB device 选 mlx5_60。跨节点 RDMA 留作 future work
• snapshot 持久化：P 重启 snapshot 全丢，下次 reseed 走 fallback。不写盘
• prefill bypass 与 chunked prefill 的交互：bypass 走的是 "全 session KV 直接传输"，不和 chunked prefill 并存。若 P 当前正在 chunked-prefill 这个 session，bypass 等到现有 chunk 结束再起

---

11. 决策点（等评审）

#	问题	默认
D1	snapshot push 的 throttle delta K_DELTA = 1024 tokens 合理？太小会泛滥推送，太大会让 snapshot 滞后	起步用 1024，跑 smoke 看流量再调
D2	snapshot LRU 上限 max_sessions = 8 合理？P 池 ~92K tokens，session 平均 50K → 1-2 个？	8 太乐观，改 4
D3	bypass 时 P 是否走 mooncake 的 staging buffer？还是直接 zerocopy	直接 zerocopy，避免一次 device→device 拷贝
D4	D-side push 失败后是否上报 router 影响策略？	不上报，fail-open（fallback re-prefill 也能跑）
D5	snapshot 是否包含 aux/state？（mamba state, swa 状态等）	E4 实验 trace 只用 Qwen3，无 mamba。aux 跟着 KV 一起带

---

核心句：D→P 同步是 KVC 设计真正击败 naive PD-disagg 的关键缺口。本设计用 P 端独立 snapshot store + prefill bypass 的最小改动方案，避开 radix tree 多生产者扩展的工程陷阱，~600 LOC 拆 8 commit 可在单次 session 完成。验收后即可启动 E4 实验对比 KVC vs naive。