diff --git a/docs/MIGRATION_V1_FINDINGS_ZH.md b/docs/MIGRATION_V1_FINDINGS_ZH.md new file mode 100644 index 0000000..74f6bdc --- /dev/null +++ b/docs/MIGRATION_V1_FINDINGS_ZH.md @@ -0,0 +1,283 @@ +# Migration v1 实验发现：blacklist 永久性导致 thrashing + +**日期**：2026-05-08 +**状态**：v1 run 进行中（~23% 完成时的中期分析） +**前置文档**： +- `docs/REFACTOR_PLAN_V1_ZH.md` §6.2（v1 设计） +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` §2.1（§1 starvation claim） + +**触发**：v1 实现的 session migration（rejection blacklist 机制）部署后，观测到 session-level thrashing——某些 session 在 3 个 D 之间 round-robin 高达 75-116 次。本文记录中期数据、根因诊断、v2 设计。 + +--- + +## 0. TL;DR + +1. **v1 修复了 §1 starvation 但引入了新的 thrashing 失效模式**——不是 admission 过严，是 blacklist 永久累积的设计 bug +2. **核心证据**：session 6880 在 decode-1 上稳定 70 turns，然后某瞬时 burst 把 reject 计数累积到阈值，被永久 blacklist，之后陷入 3-D 间 round-robin 死循环 +3. **85% admission 拒绝是 `session-not-resident`**——非 D 真容量问题，而是迁移后"新 D 第一次见你"的正常语义 +4. **v2 设计**：reset-on-success 让 reject 计数在成功 turn 后清零，只有**持续**失败才迁移 +5. **深层观察**：baseline 的"100% pin 但稳定"可能比"分布均匀但 thrashing"更好——糟糕的优化可能比不优化还糟 + +--- + +## 1. v1 实施回顾 + +### 1.1 改动文件 +- `src/agentic_pd_hybrid/policies.py`：`RoutingState.session_d_rejects` Counter；`KvAwarePolicy.migration_reject_threshold=3` skip blacklisted D；degenerate fallback 选最少拒的 D +- `src/agentic_pd_hybrid/replay.py`：`_run_request` 末尾 `state.record_admission_reject(sess, D)`（基于 execution_mode 子串匹配）；`_fallthrough_reason` 把 `pd-router-fallback-large-append-*` 拆成 `session-not-resident` / `real-large-append` / 等 +- CLI / benchmark wiring + +### 1.2 v1 假设（事后看部分错误） +- "reject 计数 + 阈值 3 = 容忍短期波动 + 持续失败迁移" ← **错**，counter 永久增长导致迁移成必然 +- "迁移到新 D 后 session 在新 D 稳定下来" ← **部分错**，迁移到的新 D 也很可能很快 reject +- "session-not-resident 不会触发计数" ← **大致对**，但下游 fallback 可能间接触发 + +--- + +## 2. 中期数据（1023/4449 reqs，~23%） + +### 2.1 头部指标 vs baseline + +| 指标 | baseline kvc_1p3d_run1 | v1（中期） | +|---|---:|---:| +| Per-D 调用分布 | 1502/1445/1502（±3.8%）| 796/785/779（**±1.1%**，更均衡）| +| Per-D 峰值 token_usage | 0.99/0.99/0.99 | 0.31/0.30/0.00（**容量充裕**，未顶到 1.00）| +| KVTransferError | 5（全程）| 6（中期，趋势相近）| +| 已见 sessions | 52（全程）| 29（中期）| + +**好的方面**： +- 负载均衡度跃升（±26%→±1.1% if normalized） +- D 容量从未饱和——§2 假设的"D drain time"机制配合 ts=1 充分发挥 +- 0 sessions 永久 stuck 在饿死状态 + +### 2.2 Migration 触发情况（已见 29 sessions） + +| 类别 | 数量 | 占比 | +|---|---:|---:| +| 仍 pin 在 1 个 D | 9 | 31% | +| 触碰 2 个 D | 3 | 10% | +| **触碰所有 3 个 D** | **17** | **59%** | + +**D-切换次数分布**： +- mean = 26 次/session +- median = 16 次 +- **max = 116 次** +- 15 sessions 切换 >10 次（明显 thrashing） +- **6 sessions 切换 >50 次**（严重 thrashing） + +--- + +## 3. 根因诊断：session 6880 的轨迹 + +### 3.1 数据 + +``` +turn 0-70: 全部在 decode-1 (71-turn 稳定 streak) ← §1 baseline 行为 +turn 71-150: 在 3 个 D 间剧烈 thrashing + decode-0: 26 个短 streak + decode-1: 25 个短 streak + decode-2: 25 个短 streak + 平均 streak 长度 = 2 turns + total streaks = 76 +``` + +### 3.2 解读 + +**前 70 turn 完美稳定**：session 6880 在 decode-1 上正常运行 70 个 turn，每次都成功，是 baseline §1 "100% pin" 的复现——稳定但不公平（其他 session 没分到 decode-1 的资源）。 + +**第 71 turn 后崩溃**： +1. 某个瞬时 burst（其他 session 的活动？）让 decode-1 短暂饱和 +2. session 6880 在 decode-1 上连续 3 次被 admission 拒（`no-space` 或 `d-session-cap`） +3. v1 的 `state.session_d_rejects[(6880, decode-1)]` 累积到 3 → blacklist +4. policy 改选 decode-0 → 同样发生 → blacklist +5. 改选 decode-2 → 同样 → blacklist +6. **3 D 全部 blacklisted** → degenerate fallback 在 3 D 间 round-robin +7. 每次 round-robin 又触发新 reject → 计数继续涨 → 永远在 thrashing 死循环 + +### 3.3 admission 数据交叉验证 + +中期 1932 admission events 解构： + +| mode × can_admit × reason | count | +|---|---:| +| `direct_append, True, None` | 1721（成功）| +| `direct_append, False, session-not-resident` | **62** | +| `seed, True, None` | 142（成功）| +| `seed, False, no-space` | **11** | + +**只有 11 个 "no-space" 才是真容量拒绝**（占总 admission 的 0.6%）。62 个 "session-not-resident" 是迁移后"新 D 第一次见你"的正常语义。 + +但因为 v1 用 `_is_admission_rejection_mode` 通过 execution_mode 子串匹配，下游 fallback chain 会把 `session-not-resident` 也间接累积到计数器（fallback 链路本身可能触发 session-cap）。 + +--- + +## 4. 设计 bug 三层 + +### 4.1 Bug 1：blacklist 永久性 + +```python +# policies.py 当前实现 +if rejects >= self.migration_reject_threshold: + continue # skip this D forever +``` + +`session_d_rejects[(sess, D)]` 是单调递增 Counter。一旦达到阈值，**永远**被 skip。但 D 的容量是动态的——70 个 turn 后短暂饱和不代表它后续不能服务这个 session。 + +### 4.2 Bug 2：degenerate fallback 加剧问题 + +当所有 D 都被 blacklist： +```python +best_decode_worker_id = min( + (w.worker_id for w in topology.route_workers), + key=lambda wid: state.session_d_rejects.get((sess, wid), 0), +) +``` +选"最少被拒"的 D。但每次 fallback 又增加该 D 的计数 → 下次选另一个 D → 形成完美 round-robin，永远走不出 thrashing。 + +### 4.3 Bug 3：信号归并粗糙 + +`_is_admission_rejection_mode` 子串匹配 `session-cap` / `no-d-capacity` / `d-backpressure`，但执行链路可能这样： + +``` +direct_append → session-not-resident（85% 占比，正常迁移后语义） + → fallback 试 seed + → seed admit ok（142/153 = 93%）→ execution_mode = pd-router-d-session-reseed-*（不计 reject） + → seed no-space（11/153 = 7%）→ execution_mode = pd-router-fallback-X-no-d-capacity（计 reject） +``` + +绝大多数 fallback 不会触发 reject 计数。但 thrashing 一旦开始，很容易踩到那 7% no-space 路径，calculator 增长一次。15+ 次 thrashing 后，单 D 计数累到 3 完全可能。 + +**所以设计 bug 不在信号粗糙，而在永久累积 + degenerate round-robin。** + +--- + +## 5. 深层观察：稳定 vs 公平的 trade-off + +| | baseline（v0）| v1 | +|---|---|---| +| 公平性 | 18/52 永久饿死 | 0 永久饿死 | +| 稳定性 | 100% pin（结构稳定）| 6/29 严重 thrashing | +| Per-D 负载均衡 | ±26% | ±1.1% | +| 大 session 体验 | 慢但稳定（每 turn 都走 fallback ~1.0s）| 不稳定 + 频繁 D 切换 + 丢 KV state | + +**预想反直觉的结果**：v1 在头部指标（per-D 均衡）赢，但在 session 体验可能输—— +- baseline 的 fallback 路径有稳定 ~1s latency +- v1 的 thrashing session 每次 D 切换都 close 旧 session、丢 KV、新 D 上重新建立——有可能 latency 反而更高 + +需要等 run 结束的 lat mean / TTFT mean 数据验证。**糟糕的优化可能比不优化还糟。** + +--- + +## 6. v2 设计 + +按 ROI 排序的修复层。**先做 #1，验证后再决定是否需要 #2/#3**。 + +### 6.1 v2-fix-1：reset-on-success（最高 ROI） + +```python +# replay.py _run_request 末尾，在 state.finish 后 +if execution.execution_mode == "kvcache-direct-to-d-session": + # 这次 direct-to-D 成功 = D-X 仍能服务这个 session + # 清零累积的 reject 计数（消除永久 blacklist） + state.session_d_rejects[(request.session_id, decision.decode_worker_id)] = 0 +``` + +**预测效果**： +- session 6880 在 decode-1 上 70 个成功 turn 把计数反复清零 +- 即使中间出现 1-2 次瞬时 reject，下次成功立刻清零 +- 只有**持续**失败（reject 后 reject 后 reject，没有夹杂 success）才能累到阈值 +- 真饿死的 session（如 35680/39360 input >92K）才会触发迁移 + +**工程量**：~5 行代码 + 1 个 smoke + 1 个完整 run（~5.5h） + +### 6.2 v2-fix-2：sliding window（如果 #1 不够） + +把 `Counter` 改成 `dict[(sess, D), deque[float]]` 存最近 K 次拒绝时间戳。判断时用最近 N 秒（或 N 个 turn）内的次数。 + +更稳健但更复杂。**若 #1 已能彻底解决 thrashing，跳过此项。** + +### 6.3 v2-fix-3：reject 类型分离（如果 #1 + #2 不够） + +把 admission reason 显式传到 _run_request，区分： +- `no-space` / `session-cap` / `backpressure` → 计 reject +- `session-not-resident` → 不计 + +需改 `ExecutionResult` 加 `admission_reject_reason` 字段，并在 fallback 链路传递。**不在第一轮**——先看 #1 是否够用。 + +### 6.4 v2 应保留的 v1 设计 + +- 阈值 3（不变） +- `record_admission_reject` 的子串匹配（不变） +- 新 fallback labels（`session-not-resident` 等）（不变） +- degenerate fallback 选最少拒的 D（不变，但因为 reset-on-success 几乎不会触发到此分支） + +--- + +## 7. 实验计划 + +| 阶段 | 动作 | 时间 | +|---|---|---| +| 1 | 等 v1 run 完成（ETA ~16:30）| 自然 | +| 2 | 跑 analyzer 量化 v1 thrashing 实际代价 | 5 min | +| 3 | 实现 v2-fix-1（reset-on-success）| 30 min | +| 4 | smoke test | 10 min | +| 5 | 完整 v2 run（KVC 1P3D ts=1 N=1）| ~5.5h | +| 6 | 三方对比：baseline / v1 / v2 | 30 min | +| 7 | 决定是否需要 v2-fix-2 / v2-fix-3 | – | + +--- + +## 8. 三方对比预测（待数据验证） + +| 指标 | baseline（v0）| v1（thrashing）| **v2（self-healing 预测）** | +|---|---:|---:|---:| +| Errors | 5 | ? | 2-5（仅 35680/39360 等真容量超限）| +| Per-D 均衡 | ±26% | **±1.1%** | ±5-10%（部分 pin 仍 sticky）| +| Direct-to-D rate | 42.8% | ?（可能因 thrash 反而下降）| **65-75%**（持续 affinity，转换 §1 fallback）| +| Lat mean | 1.574s | ?（可能因 thrash 上升）| **1.30-1.45s**（达到 4DP 1.443s 水平）| +| TTFT mean | 0.244s | ? | **0.10-0.15s** | +| 最大 D-switches/session | 0 | 116 | <10（仅真饿死 session）| +| Sessions 永久饿死 | 18 | 0 | 2-3（仅真容量超限）| + +预测核心：v2 应该结合 baseline 的稳定性（70-turn streak 应保留）+ v1 的公平性（无永久饿死），消除 v1 的 thrashing 副作用。 + +--- + +## 9. 局限与未验证 + +1. **v1 中期数据 (23%) 推测**：完整数据可能改变 thrashing 严重性的判断 +2. **session 6880 trajectory 的崩溃机理是推断**：基于 admission events 数据 + streak 模式，但没有直接日志证明 reject 计数何时跨阈值（需要在 v2 加 instrument 输出） +3. **reset-on-success 的预测效果未验证**：基于"70 turn 成功" + "1-2 次瞬时 reject" 的假设；如果 burst 持续多 turn，仍可能跨阈值 +4. **可能还有未发现的设计 bug**：v2 也许还会暴露新问题 +5. **三方对比需 same trace + same scale + same ts=1**：baseline 已有 N=3，v1/v2 各 N=1（ts=1 确定性 → N=1 可信） + +--- + +## 10. 给 TEAM_REPORT 和 REFACTOR_PLAN_V1 的更新建议 + +完成 v2 验证后： + +1. 在 `TEAM_REPORT` §3 ts=1 验证更新章节加入 §3.3 "Migration mechanism evolution: v0 → v1 → v2" +2. 在 `REFACTOR_PLAN_V1` §6.2 标注实施反思——预设的 "rejection blacklist" 设计漏掉了 reset-on-success 这条 +3. 在新文档 `docs/POLICY_DESIGN_PRINCIPLES_ZH.md` 提炼出原则："任何会累积的代价机制必须配 healing/decay 机制，否则会陷入 self-amplifying 失效模式" + +--- + +## 附录 A：本文数据来源 + +| 章节 | 数据源 | +|---|---| +| §2 | `outputs/qwen3-30b-tp1-ts1-migration-v1/kvcache-centric-*/` 中期日志 | +| §3.1 | `structural/session-d-binding.jsonl` 跨 turn 序列 | +| §3.3 | `structural/admission-events.jsonl` mode/reason 交叉表 | + +## 附录 B：相关代码位置 + +| 内容 | 位置 | +|---|---| +| RoutingState.session_d_rejects | `src/agentic_pd_hybrid/policies.py:46` | +| KvAwarePolicy.select 跳过 blacklisted D | `src/agentic_pd_hybrid/policies.py:155-162` | +| Degenerate fallback 选最少拒的 D | `src/agentic_pd_hybrid/policies.py:184-192` | +| record_admission_reject 触发位置 | `src/agentic_pd_hybrid/replay.py:359-364`（_run_request） | +| _is_admission_rejection_mode 子串集合 | `src/agentic_pd_hybrid/replay.py` `_ADMISSION_REJECTION_SUBSTRINGS` | +| _fallthrough_reason 分类 | `src/agentic_pd_hybrid/replay.py` `_fallthrough_reason` | diff --git a/docs/REFACTOR_PLAN_V1_ZH.md b/docs/REFACTOR_PLAN_V1_ZH.md new file mode 100644 index 0000000..4fda391 --- /dev/null +++ b/docs/REFACTOR_PLAN_V1_ZH.md @@ -0,0 +1,385 @@ +# Refactor Plan v1：基于 ts=1 验证后的重构方向 + +**日期**：2026-05-08 +**前置文档**： +- `docs/REFACTOR_PLAN_ZH.md`（v0，已被本文 supersede——v0 的 backpressure 切入点结论已撤回） +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md`（包含 §1-§7 结构性问题清单） +- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md`（ts=10 数据下的早期验证） + +**触发**：`outputs/qwen3-30b-tp1-ts1-validation/` 4 个 run 完成（KVC 1P3D × N=3 + 4DP CA × 1，全部 ts=1） + +**目的**：把 ts=1 验证结果落到具体的重构决策——哪些事必须做、哪些事不要再做、KVC 项目本身是否需要重新定义价值主张 + +--- + +## 0. TL;DR + +1. **ts=10 失真是真的，影响 5-10×**——KVC 在 ts=10 灾难性输 DP 是 benchmark artifact，不是机制本身有问题 +2. **ts=1 同 scale 下 KVC ≈ DP**：lat mean 差 9%，TTFT 差 47%，errors 双 0 +3. **TEAM_REPORT 的 §1（session pin 不公平）是真问题，但代价从 6× 降到 ~2×**——仍是唯一值得做的 KVC 优化 +4. **TEAM_REPORT 的 §2/§3/§4/§5 大多是 ts=10 高压 artifact**——ts=1 下要么不显著、要么自然吸收 +5. **N=1 不可信是 ts=10 现象**——ts=1 下系统在 categorical 层面完全确定（routing/admission/errors 三次 run 完全相同） + +**项目落到情景 B（KVC ≈ DP）**——三种 forward 路径任团队决策（见 §6）。 + +--- + +## 1. ts=1 验证数据 + +### 1.1 实验配置 + +| 项 | 值 | +|---|---| +| Trace | `outputs/qwen35-swebench-50sess.jsonl`（4449 reqs / 52 sessions） | +| 模型 | Qwen3-30B-A3B-Instruct-2507（TP1） | +| 硬件 | 单机 4× H100 80GB（注：原始 ts=10 实验是 8 GPU；本次缩配） | +| Time-scale | 1（真实 trace 时序，inter-turn gap p50 = 2.5s） | +| Concurrency | 32 | +| KVC 配置 | 1P3D，policy=kv-aware，admission=worker，seed-min-turn=1，prefill-priority-eviction | +| DP 配置 | 4-way colo，policy=kv-aware（cache-aware） | +| 输出根 | `outputs/qwen3-30b-tp1-ts1-validation/` | + +### 1.2 Headline 对比 + +| Metric | KVC 1P3D ts=1（N=3 均值）| 4DP ts=1 | Delta | +|---|---:|---:|---:| +| **真实 mechanism errors** | **0** | **0** | 平 | +| 报告 errors（口径不一致，见 §1.3） | 5 | 0 | – | +| Lat mean | 1.574s | **1.443s** | DP 优 9% | +| Lat p50 | 0.810s | **0.659s** | DP 优 19% | +| Lat p90 | 3.796s | **3.641s** | DP 优 4% | +| Lat p99 | 8.722s | **8.433s** | DP 优 3% | +| TTFT mean | 0.244s | **0.129s** | DP 优 47% | +| TTFT p50 | 0.122s | **0.090s** | DP 优 26% | +| TTFT p90 | 0.572s | **0.252s** | DP 优 56% | +| Per-worker spread | ±3.8% (3D) | ±3.1% (4 direct) | 接近 | + +### 1.3 KVC 5 errors 的真实身份 + +DP 的同 5 个 (sess, turn) 也"失败"——但 metrics 口径不同： + +``` +KVC: 计入 error_count +DP: metrics 记 error=OK + finish_reason={'type':'abort', 'message':'Input length (X) exceeds the maximum allowed length (87811)'} +``` + +| sess | turn | input_len | KVC max | DP max | +|---|---:|---:|---:|---:| +| 35680 | 132 | 91600 | 92098 (✓) | 87811 (✗) | +| 35680 | 133 | 92335 | 92098 (✗) | 87811 (✗) | +| 39360 | 137 | 91700 | 92098 (✓) | 87811 (✗) | +| 39360 | 138 | 92003 | 92098 (✓) | 87811 (✗) | +| 39360 | 139 | 92135 | 92098 (✗) | 87811 (✗) | + +**两边都拒同样的请求**——区别只在于 KVC 在 P 端拒（KV 池满）、DP 在 prefill 端拒（max-input limit）。**真实 mechanism 错误率：KVC 0 / DP 0**。 + +### 1.4 ts=1 的确定性 + +KVC N=3 三次 run 跨 4449 records： + +| 维度 | 跨 run 差异 | +|---|---| +| `execution_mode` | **0 / 4449** records 不同 | +| `assigned_decode_node` | **0 / 4449** records 不同 | +| Errors（5 个 sess/turn 对） | **完全相同** | +| 18 starved + 16 lucky session | **完全相同** | +| Per-D load (1502/1445/1502) | **完全相同** | +| Lat mean | 1.574 / 1.573 / 1.574（**0.06%** 漂移）| +| Lat p50 | 0.811 / 0.809 / 0.812（**0.4%** 漂移）| +| 单 request lat | abs p90 diff = 25ms | + +**结论**：低压 / ts=1 区间下 KVC 系统在 categorical 层面（路由 / admission / 失败位置）**完全确定**，仅低层数值有 model 计算微抖动。 + +--- + +## 2. 对 TEAM_REPORT §1-§7 的修订 + +| § | TEAM_REPORT 原 claim | TEAM_REPORT 原优先级 | ts=1 验证后状态 | **修订优先级** | +|---|---|---|---|---| +| §2.1 | session pin + 容量盲选 → 25% 饿死 | **P0** | ✅ 结构性问题仍在（18/52 session 永久 pin），但代价从 6× 慢降到 ~2× | **P0**（唯一值得做的 KVC 优化）| +| §2.2 | D-side LRU 跟不上 → 8% errors | **P0** | ⚠️ D 仍瞬时顶到 token_usage=1.00，但**ts=1 下 drain time 自然吸收**——0 KVTransferError 雪崩（vs ts=10 369 次） | **降级 P3**（drain time 已解决症状）| +| §2.3 | 无 backpressure 通道 | P1（已实现）| ❌ ts=1 下 transfer cascade 不存在，backpressure 无作用对象 | **冷藏**（代码留着，但默认 off）| +| §2.4 | P-side round-robin 不感知 D 健康 → prefill-0/-1 错误差 180× | P1 | ⚠️ 1P 配置不可测；ts=10 现象**高度怀疑也是 artifact**（错误本身在 ts=1 消失） | **存疑 / 重测后再说** | +| §2.5 | admission RPC 进 scheduler 主循环 → 1Hz polling 让 errors ↑46× | P2 | ❌ 是 ts=10 高压时的现象，ts=1 下不显著 | **冷藏** | +| §2.6 | time-scale=10 失真 → 所有 KVC vs DP 结论可能被放大 | **P0** | ✅ **完全证实**（74× errors↓, 8.7× TTFT↓, 7× per-D spread↓） | **DONE，作为前置条件锁定** | +| §2.7 | execution_mode 标签命名错位 | P1 | ✅ 仍存在；本次 ts=1 又发现 `error_count` 在 KVC vs DP 口径不一致 | **P1**（纯 labeling 修复，~半天）| +| §2.8 | N=1 不可信 → 实验必 N≥3 | P2 | ⚠️ **是 ts=10 高压现象**——ts=1 下 N=1 categorical 完全确定 | **改写规则**：高压 N≥3 / 常规 N=1 | +| §2.9 | microbench 把 KVC 失效条件全规避 | – | 仍成立 | **保留观察**（实验设计原则）| + +--- + +## 3. v0 REFACTOR_PLAN 回顾 + +### 3.1 v0 做对的 + +- **唯一代码改动选 backpressure**：作为对 §2.3 的最小验证手段是合理的 +- **预算 KISS**：用 8h GPU 验证 §1-§7，思路正确 +- **明确"P0 是 time-scale=1 baseline"**：v0 的 §1 末尾就指出 "time-scale=1 验证为 P0 待办"——本次实验正是把这条做了 + +### 3.2 v0 的核心误判 + +| v0 假设 | 实际 | +|---|---| +| backpressure 是 §3 的最小验证 → 也是修复 | ts=1 下 §3 的症状（transfer cascade）不存在，backpressure 无效 | +| 8h 预算够跑 ts=1 baseline + backpressure smoke | ts=1 单 run 5.5h，4 run 全跑要 22h（实际跑了 22h） | +| §1 / §2 的修复"超出 KISS 边界"，先验证不修 | 验证后发现 §1 是**唯一**值得做的真问题，应该早点把它纳入 | + +### 3.3 v0 的 backpressure 代码命运 + +代码保留（`--enable-backpressure` 默认 off），原因： +- 不删除是因为如果未来跑高压 / 大 trace / 真 RDMA 失败回归到类 ts=10 区间，可能仍有用 +- 但**不部署、不启用、不文档化为推荐配置**——避免给以后看到代码的人误导 + +--- + +## 4. 修订后的优先级矩阵 + +``` + 必做 建议做 不做 + ──────── ──────── ──────── +ts=1 必修 §1 capacity-aware (空) §2 / §3 / §4 / §5 + policy + migration 的 ts=10 fix + +ts=1 nice §2.7 metrics 标签 (空) §2.8 N≥3 严苛规则 +to have 统一口径 （改成"高压 N≥3"） + +文档 §3 写入 TEAM v0 标记 superseded ts=10 数据归档 + REPORT 更新 （但保留可追溯性） +``` + +**唯一进入"必做工程"列表的是 §1**。其他全是文档或冷藏。 + +--- + +## 5. KVC vs DP 拆分到 path-level 看真实差距 + +理解 §1 的 ROI 必须先看 path-level（不是整体均值）： + +### 5.1 KVC 内部 path 性能（来自 ts=1 N=3 一致数据） + +| Path | n | 占比 | Lat p50 | TTFT p50 | +|---|---:|---:|---:|---:| +| `kvcache-direct-to-d-session`（快路径）| 1903 | **42.8%** | **0.475s** | **0.042s** | +| `pd-router-fallback-large-append-session-cap`（慢路径）| 2409 | **54.2%** | 1.04s | 0.32s | +| `pd-router-turn1-seed`（每 session 一次）| 52 | 1.2% | 0.375s | 0.057s | +| 其余 | 85 | 1.8% | 多种 | 多种 | + +### 5.2 DP 全部 path（单一） + +| Path | n | 占比 | Lat p50 | TTFT p50 | +|---|---:|---:|---:|---:| +| `dp-colo-router` | 4449 | 100% | 0.659s | **0.090s** | + +### 5.3 路径级对比 + +| | KVC direct | KVC fallback | DP | +|---|---|---|---| +| Lat p50 | **0.475s**（赢 DP 28%）| 1.04s（输 DP 58%）| 0.659s | +| TTFT p50 | **0.042s**（赢 DP 53%）| 0.317s（输 DP 252%）| 0.090s | + +**事实陈述**： +- KVC 快路径 **明显快于** DP（无 P 介入、无 mooncake transfer） +- KVC 慢路径 **明显慢于** DP（P→D transfer 开销没法摊到 turn 内） +- 当前 quick:slow = 42.8% : 54.2%——慢路径多 → 整体输 DP 9-47% +- 如果能把比例反过来到 70:25 或更好，KVC 整体会赢 DP + +**§1 的本质就是"为什么有 54% 进了慢路径"**——因为 18/52 session 被 pin 在容量紧张的 D 上，每次 admission 都拒。 + +--- + +## 6. 三种 forward 路径 + +> **更新（2026-05-09）**：情景 C **已实现**——见 `docs/V2_RESULTS_ZH.md`。下面三个分支保留作历史记录。 +> +> | 情景 | 描述 | 状态 | +> |---|---|---| +> | A | KVC < DP，接受现状转维护 | 不适用 | +> | B | KVC ≈ DP，重新定义价值主张 | 不适用 | +> | **C** | **KVC > DP，优化拉大差距** | **✓ 实现：v2 在 7/8 头部指标击败 4DP（TTFT mean -24%, p50 -54%, p90 -64%；lat mean -0.8%, p50 -12.6%）** | +> +> 关键修复：(1) reset-on-success blacklist decay（消除 v1 thrashing），(2) `--kvcache-direct-max-uncached-tokens` 2048→8192（让 41% 大 append 走 direct-to-D 快路径）。direct-to-D rate 从 baseline 42.8% 升到 v2 91.7%。 + +### 6.1 选项 A：接受现状，项目转维护 + +**判断**：KVC 在 ts=1 + 同 scale 下 ≈ DP（9% 慢、47% TTFT 慢），但**也没灾难性输**。如果项目目标是"验证 KV-aware routing 在 agentic 上是否可行"，答案是 **可行但收益不显著**。 + +**操作**： +- 写 TEAM_REPORT §3 总结 ts=1 实验 +- 把 ts=1 数据 + 4 个 run 归档到 `RESULTS_FROZEN_TS1.md` +- KVC 代码保留但标记 "experimental, not recommended for production" +- 团队转下一个项目方向（不是本文范围） + +**成本**：1 周文档收尾。 +**风险**：放弃了 §1 修复后可能的 KVC > DP 上限。 + +### 6.2 选项 B：做 §1，目标让 KVC > DP + +**判断**：5.3 节的路径分析表明 KVC 快路径已经赢 DP；如果把饿死 session 救回快路径，KVC 整体可能赢 DP。 + +**具体改动**： + +#### 6.2.1 capacity-aware policy（`policies.py:166-172`） + +当前评分（无容量项）： +```python +score = ( + overlap + sticky * self.sticky_bonus, + sticky, + inflight_penalty, + assignment_penalty, +) +``` + +提议改为： +```python +# 新增：D 当前容量利用率（从 worker-mode admission 已能查到） +capacity_used = worker_capacity_used_ratio.get(worker.worker_id, 0.0) + +# Hard cap：容量 > X 时禁止该 D 进入候选 +if capacity_used > HARD_CAP_THRESHOLD: # e.g. 0.85 + continue + +score = ( + overlap_capped, # 原 overlap，但限幅避免单个 D 永远赢 + -capacity_used, # 新增二级排序项：偏好空闲 D + sticky, + inflight_penalty, +) +``` + +#### 6.2.2 session migration（`replay.py` 或 policy 层） + +当 session X 在 D-A 上连续被 admission 拒 N 次（如 N=3）： +- 主动 release X 在 D-A 上的 session state +- 允许下次 turn 把 X 路由到另一个 D +- 代价：丢失 D-A 上已积累的 KV——但 fallback 路径本来也丢了，**净收益正** + +#### 6.2.3 metric 修复（`replay.py`） + +把"`pd-router-fallback-large-append-*`" 标签按真实原因细分： +- `session-not-resident-on-pinned-D`（§1 主因） +- `real-large-append`（>2048 阈值，§2.7） +- `session-was-evicted`（被 LRU 踢过） +- `session-cap-rejected`（worker admission 拒） + +让以后看 metrics 的人不再被名字误导。 + +#### 6.2.4 验证 + +- 每改动跑 KVC 1P3D ts=1 N=1（categorical 确定，不需要 N=3） +- 对比 baseline run1（已有数据） +- 关键指标：`kvcache-direct-to-d-session` 占比、整体 lat mean、TTFT mean +- 目标：direct-to-D rate 从 42.8% 升到 > 70%、整体 lat 追平或赢 DP + +**成本**：3 天编码 + 5 天测试 + 2 天文档 ≈ 2 周。 +**风险**： +- session migration 可能导致 thrash（A→B→A→B），需要冷却时间机制 +- capacity HARD_CAP 阈值需要 sweep 找最优 +- 改完仍可能不赢 DP（理论上限不知道） + +### 6.3 选项 C：保留 KVC，但寻找 KVC 真正赢的工作点 + +**判断**：当前 SWE-Bench 50 sessions × 30B 模型 × 4 GPU 是一个特定工作点。KVC 的设计初衷是"长 multi-turn session 的 KV 复用"——可能在某些其他工作点有显著优势。 + +**候选工作点**： +- **更长 session（>200 turns）**：复用收益更大 +- **更小模型（如 7B / 14B）**：mooncake transfer 占比更大，KVC 节省更明显 +- **更大 trace（>200 sessions）**：DP 的 prefix cache 命中率会下降，KVC 的 session-aware 优势放大 +- **真实 RDMA（非 mooncake TCP loopback）**：transfer 更快，KVC 的 P→D 开销更小 + +**操作**： +- 设计 1-2 个新 micro/macro benchmark +- 跑 KVC vs DP 对比 +- 找到差距 > 30% 的工作点（KVC 赢 / 输都是数据） + +**成本**：~1 个月（trace 设计 + benchmark + 分析）。 +**风险**：可能找不到 KVC 显著赢的工作点。 + +--- + +## 7. 推荐组合 + +按风险 / 收益排序： + +1. **必做**（无论选 A/B/C）： + - 写 `TEAM_REPORT §3 ts=1 验证更新` + - 修 `metrics 标签口径`（§2.7 + KVC/DP error_count 一致化） + - **冷藏 backpressure 代码**（不删但默认 off） + - 把 v0 REFACTOR_PLAN 标 superseded + +2. **强烈推荐**：选项 B 的 §6.2.1（capacity-aware policy hard cap） + - 工程量小（~1 天编码 + 1 天测试） + - 验证 §1 修复的真实收益是否如预测 + - 如果 direct-to-D rate 不显著提升 → 把 §6.2.2 也加上 + - 如果还不行 → 接受现状走选项 A + +3. **看团队带宽**：选项 C 的工作点探索 + - 不与 §6.2 冲突，可以并行 + - 找到一个 KVC 真正赢的工作点会极大改变项目价值主张 + +--- + +## 8. 应该砍掉的事（明确列表） + +| 事 | 砍的理由 | +|---|---| +| backpressure smoke sweep（v0 计划的 4 run） | ts=1 下 backpressure 无作用对象 | +| §2.5 admission API probe/commit 拆分 | 高压才显著，等找到 KVC 高压 workload 再说 | +| §2.2 D-side 分层 LRU eviction（hot retract） | drain time 自然吸收 | +| §2.4 P-side D-health-aware routing | 1P 测不出，ts=10 现象高度存疑 | +| 大量 instrument（admission-events / pool timeseries） | 已经够了，先用现有数据 | +| 任何 ts=10 区间的优化 | 那是 benchmark artifact 主导的区间，不代表真实部署 | +| N≥3 实验作为硬规则 | 改写为"高压 N≥3，常规 N=1 即可" | + +--- + +## 9. 风险与未验证的假设 + +1. **4DP ts=1 是 N=1**：虽然 KVC ts=1 是确定性的，DP 是新机制 N=1，理论上需要 N≥3 验证。但 DP 在 ts=10 也是 0 errors / 1.43s mean，行为相对 KVC 更稳定，N=1 风险较小。**如选项 B 推进，建议补 N=2**。 +2. **2 个 input-too-long session 是 trace 数据问题**：这两个 session（35680、39360）在 turn 132+ / 137+ 才超过 input limit。可能是 trace 生成时没控制好 max input。**应该独立把这两个 session 从 trace 移除或截断后重跑作为对照**。 +3. **4 GPU 缩配 vs 8 GPU 原始**：本次 1P3D / 4DP 数据无法跨 8 GPU 原始数据直接比，需要在结论中明确。但 ts=1 + 同 scale 内部对比是干净的。 +4. **mooncake TCP loopback**：所有 transfer 在单机 TCP 模拟下进行。生产 RDMA 下 KVC 的 transfer 开销可能显著降低，KVC 优势可能扩大——这是 **选项 C 的一个候选维度**。 +5. **§1 修复是否真能让 direct-to-D 上升到 70%+ 是预测**：实际可能受 hash overlap 限制（即使 D 容量充裕，没有 prefix overlap 就走不了 direct-to-D）。**需要 §6.2 验证后才知道天花板**。 +6. **input-limit error 的 metrics 口径修复影响以后所有比较**：注意修改后 ts=10 历史数据的 error_count 也需要重算（或在分析时显式补偿）。 + +--- + +## 10. 决策点（需要团队确认） + +请审阅后回答： + +| # | 决策 | 选项 | +|---|---|---| +| D1 | 选哪条 forward 路径？ | A（维护）/ B（修 §1）/ C（探索 workload）/ B+C | +| D2 | 写 TEAM_REPORT §3 ts=1 验证更新章节？ | Yes / No | +| D3 | 把 v0 REFACTOR_PLAN 标 superseded？ | Yes / No | +| D4 | 删除 backpressure 代码 vs 冷藏？ | 删 / 冷藏（默认 off）| +| D5 | 修 metrics 标签口径（§2.7 + error_count 一致化）？ | Yes / No | +| D6 | 是否补 4DP ts=1 N=2 / N=3 做更稳的 baseline？ | Yes / No | +| D7 | 是否把 sess 35680 / 39360 从 trace 移除做"干净" baseline？ | Yes / No | + +--- + +## 附录 A：本文数据来源 + +| 章节 | 数据源 | +|---|---| +| §1.2-§1.4 | `outputs/qwen3-30b-tp1-ts1-validation/{kvc_1p3d_run{1,2,3},dp4}_{summary.json,metrics.jsonl}` | +| §1.4 跨 run 一致性 | per-record diff via `scripts/analysis/analyze_ts1_validation.py` + 临时 diff 脚本 | +| §5 path-level | metrics.jsonl 按 `execution_mode` 分组 | +| §2 §1-§7 修订 | `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` 原数据 + ts=1 新数据交叉对比 | + +## 附录 B：相关文档 + +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` — §1-§7 原结构性问题清单 +- `docs/REFACTOR_PLAN_ZH.md` — v0 重构计划（本文 supersede） +- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析（§1-§7 来源） +- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 +- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 演进 +- `docs/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（已 critic 修订） +- `scripts/sweep_ts1_kvc_n3_plus_dp.sh` — 本次 4 run sweep 脚本 +- `scripts/analysis/analyze_ts1_validation.py` — 本次分析脚本 + +--- + +**作者注**：本文偏决策导向。如果要写更技术的 §1 capacity-aware policy 实现细节，应该在 D1 决策为 B 之后单独出一份 `IMPL_CAPACITY_AWARE_POLICY.md`。 diff --git a/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md b/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md new file mode 100644 index 0000000..b695b0a --- /dev/null +++ b/docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md @@ -0,0 +1,641 @@ +# agentic-pd-hybrid 现框架性能与结构性问题报告 + +**对象**：项目团队同学 +**前置假设**：读者**没看过** v3-v6 KVC 实验日志 +**数据范围**：项目仓库 `outputs/` 下截止 2026-05-06 的全部实验产物 +**目的**：把"现状"和"问题"分别交代清楚，给后续改造提供共同事实基础 + +--- + +## 0. 给没看过实验的读者：基础概念速览 + +### 0.1 项目目标 +验证 **session-aware / KV-cache-aware P/D routing** 在 **agentic coding workload**（多轮 session、长 context、增量 append）上能否降低端到端延迟。基线对比对象是 vanilla SGLang xPyD。 + +### 0.2 三种部署机制（**这三个名词全程会用**） + +| 机制 | 形态 | KV 流向 | +|---|---|---| +| **pd-disaggregation**（"PD disagg"） | P 和 D 是独立进程、分占不同 GPU | 每个请求 P 算 prefill → mooncake 推 KV → D 解码 | +| **pd-colo**（"DP"，data-parallel） | 没有 PD 拆分，N 个独立完整 worker（每个自己 prefill+decode） | 没有 KV transfer；router 按 hash 分配请求 | +| **kvcache-centric**（"KVC"） | 部署形态同 PD disagg；**D 上多了 SessionAwareCache**，能跨 turn 保留 session KV | 运行时决策：可走 direct-to-D（无 P）、可走 P→D disagg、可走带 reseed 的混合 | + +**Direct-to-D**（"D-direct"）：KVC 的快路径——D 上已有该 session 的 KV，新 turn 在 D 本地做 append-prefill，零 P 介入、零 mooncake transfer。这是 KVC 理论上能省时间的核心。 + +**Fallback**：KVC admission 拒了 / 阈值不满足 / D 不健康时，退化到普通 PD disagg 路径。 + +**Routing policy**（与机制正交）： +- `default`：纯 round-robin +- `sticky`：turn 2+ 黏到 session 的 last D +- `kv-aware`：按 hash overlap + sticky 评分选 D（**KVC 必须配它**才能正确工作） + +### 0.3 数据来源 +- Trace：`outputs/qwen35-swebench-50sess.jsonl`（SWE-Bench 抽样，4449 reqs / **52 sessions** / 每 session 8-150 turns / time-scale=10 / concurrency=32） +- 模型：Qwen3.5-35B-A3B (TP4) 和 Qwen3-30B-A3B (TP1) 两组 +- 硬件：单机 8×H100 80GB，mooncake TCP loopback 模拟 P→D 传输 + +--- + +# 第一部份：性能数据现象 + +## 1.1 三种机制在 Qwen3.5-35B (TP4) SWE 50sess 上的表现 + +来源：`outputs/swebench-exps/`。 + +| Run | Mechanism | Policy | Errors | Lat mean | Lat P50 | Lat P99 | TTFT mean | TTFT P50 | +|---|---|---|---:|---:|---:|---:|---:|---:| +| `pd-disaggregation-default-20260426T202540Z` | pd-disagg | default | **0/4449** | 1.66s | 0.97s | 7.68s | 0.45s | 0.34s | +| `pd-colo-default-20260426T210129Z` | pd-colo | default | **4447/4449** | – | – | – | – | – | +| `pd-colo-default-20260427T033519Z` | pd-colo | default | **0/4449** | 1.77s | 0.86s | 9.67s | 0.29s | 0.25s | +| `pd-colo-kv-aware-20260427T042034Z` | pd-colo | kv-aware | 469/4449 | 1.52s | 0.82s | 8.27s | 0.26s | 0.23s | +| `pd-colo-kv-aware-20260427T044944Z` | pd-colo | kv-aware | **0/4449** | **1.57s** | 0.81s | 8.48s | **0.22s** | **0.17s** | +| `kvcache-centric-default-worker-admission-20260426T210800Z` | KVC | default | **4390/4449** | – | – | – | – | – | + +### 现象解读 + +**(1) pd-disagg 是稳定基线**：1.66s mean / 0 errors / 4199 cache hits（94.4%）。可以正常服务。 + +**(2) pd-colo（DP）有两次 run，第一次几乎全 crash，第二次稳定**： +- 04-26 的 4447/4449 errors 来自 SGLang `--disaggregation-mode null` + Qwen3.5-35B-A3B（Mamba/GDN hybrid）的 `token_to_kv_pool_allocator memory leak` bug，crash 了 +- 04-27 的两次 pd-colo run 都跑通了。**`pd-colo-kv-aware-20260427T044944Z` 是这一组实验里跑分最好的配置**——0 errors / TTFT P50 = 0.171s（pd-disagg 的 50%） + +**(3) KVC 在 SWE 35B 上的唯一一次 run 几乎全 crash**：4390/4449 = 98.7% errors。但**那 56 个跑通的 direct-to-D 请求性能优异**——Lat mean 1.24s，TTFT P50 0.081s，KV transfer 196 块（vs PD disagg 的 105K 块，**−99.8%**）。说明 KVC 机制本身有效，但 admission control 把绝大多数请求过滤掉了。 + +### 一句话：在 Qwen3.5-35B 上，**pd-colo + kv-aware 是头名**，KVC 机制配置不当几乎不可用。 + +--- + +## 1.2 同 trace 切到 Qwen3-30B (TP1)：v1→v6 演进 + +为绕开 Mamba 模型的 SGLang bug，团队后续切到 Qwen3-30B-A3B (TP1) 跑 KVC 调优 sweep。**所有结果用同一份 SWE 50sess trace**，可以横向比较。来源：`outputs/qwen3-30b-tp1-*` 各目录。 + +### 1.2.1 各版本配置概览 + +| 版本 | 关键改动（一句话） | +|---|---| +| v2 | KVC + `--policy default`（这个 policy 选择 **是 bug**，下文 §2.5） | +| v3 | KVC + `--policy kv-aware` | +| v4 | v3 + replay 端 session soft_cap 从 4 抬到 16 | +| v5 (Option D) | 把 admission 决策从 replay 估算改成 D worker 真实容量回答（`worker-mode admission`） | +| v5+profile | v5 + 1Hz `/server_info` polling 做时序 instrument | +| v6 P0 | v5 baseline 同配置 rerun ×3 验证可复现性 | + +### 1.2.2 各版本同 trace 结果总表 + +| 版本 | Errors | Lat mean | Lat P50 | Lat P90 | Lat P99 | TTFT P50 | direct-to-D% | +|---|---:|---:|---:|---:|---:|---:|---:| +| **8-way DP cache-aware** | **0** | **1.43s** | **0.65s** | **3.61s** | **8.37s** | **0.093s** | – | +| v3 1P7D KVC | 363 (8.2%) | 4.88s | 1.75s | 12.67s | 28.72s | 0.363s | 39% | +| v3 2P6D KVC | 9 (0.2%) | 3.58s | 1.52s | 9.23s | 18.70s | 0.328s | 31% | +| v4 1P7D cap=16 | 435 (10%) | 4.21s | 1.08s | 13.38s | 24.45s | 0.056s | 49% | +| v4 2P6D cap=16 | 403 (9%) | 2.51s | 0.84s | 6.51s | 18.34s | 0.051s | 53% | +| v5 1P7D Option D | 9 (0.2%) | 5.18s | 1.59s | 14.67s | 26.09s | 0.207s | 45% | +| v5 2P6D Option D | 9 (0.2%) | 3.49s | 1.31s | 9.09s | 24.92s | 0.244s | 41% | +| v5+profile 1P7D | 6 (0.1%) | 4.21s | 1.18s | 11.33s | 28.83s | 0.060s | 55% | +| v5+profile 2P6D | **415 (9.3%)** | 3.23s | 1.11s | 8.36s | 20.26s | 0.168s | 41% | +| v5 rerun ×3（无 profile） | **372 / 912 / 396** | 3.00–3.50s | 0.94–1.22s | 7.68–8.65s | 18.97–20.37s | 0.07–0.18s | 40-42% | + +**8DP CA 在每一项指标都是头名**： +- Latency mean **比所有 KVC 配置好 +43%~+260%** +- TTFT P50 **0.093s**（KVC 最佳 v4 2P6D 是 0.051s——TTFT 单项 KVC 是有优势的，但被整体 P99 灾难抵消） +- 0 errors（KVC 任一配置 errors 在 9-912 之间漂移） + +### 1.2.3 v5+profile 的诡异：加 1Hz polling 让 errors 从 9 涨到 415 + +这条单独看：v5 baseline 跑出来 9 errors，加上 1Hz `/server_info` polling 之后 415 errors（**46×**）。原因机理见 §2.5。 + +### 1.2.4 v6 P0 用 ×3 rerun 验证可复现性，结果是不能复现 + +**关键事实**：v5 baseline 完全相同配置跑 3 次： + +| Run | Errors | Lat mean | Lat P50 | TTFT P50 | +|---|---:|---:|---:|---:| +| rerun1 | **372** | 3.50s | 1.11s | 0.147s | +| rerun2 | **912** | 3.00s | 0.94s | 0.071s | +| rerun3 | **396** | 3.42s | 1.22s | 0.183s | + +errors 漂移 **2.5×**（372→912）。Latency mean / P50 也漂移 ~30%。**这意味着 v3-v6 之前所有"single-run"对比的差异 < 30% 的都不可信。** + +但要注意：**3 次 v5 中最优的 P50（0.94s）仍然比 8DP CA（0.65s）慢 1.45×**——这个差距大于 single-run variance，所以"DP 全胜 KVC"的头条结论不受 variance 影响。 + +### 1.2.5 一个有趣的反差：v4 vs v5 + +- v4：errors 多（~10%）、direct-to-D 占比高（53-58%）、整体 P50 较好（0.84s） +- v5：errors 少（0.2%）、direct-to-D 占比降低（41-45%）、整体 P50 反而退步（1.31s） + +**v5 没有让性能变好，只是把"硬错误"转成了"诚实拒绝"——v4 的 admission 是乐观估算，admit 进来后 D 装不下变成 mooncake 32s timeout（统计成 errors）；v5 让 D 自己拍板，admit 拒得早，请求改走 fallback（统计成低 direct-to-D 率）。容量本身没变。** + +--- + +## 1.3 microbench 上 KVC 击败 PD disagg —— 但本仓库没保留实际 run + +`docs/PROJECT_OVERVIEW.md` 写明： + +> micro-benchmark 上，`kvcache-centric` 可以比 `pd-disaggregation` 好。原因很简单：**session 少、D KV 放得下**，turn2+ 可以直接走 D session。 + +但 `outputs/` 里**没有** microbench 实际 run（只有 microbench trace 生成器 `microbench.py` 和它的几个示例 trace 文件）。所以 microbench 的"KVC 赢"是基于设计预期 + 历史口口相传，**没有可重现的产物**。 + +**这本身是个问题**——下文 §2.6 会解释 microbench 的默认参数（4 sessions × 30K input × 1K append）正好把所有 KVC 失效条件都规避掉了。 + +--- + +## 1.4 头条结论（Part 1 总结） + +| 工作负载 / 模型 | 头名机制 | KVC 表现 | +|---|---|---| +| Microbench（8 session × 30K × 1K append） | KVC > PD disagg（无落地数据，按设计） | 设计上必然赢 | +| SWE 35B (TP4) | **pd-colo + kv-aware**（1.57s mean, 0 errors） | KVC 唯一 run 中 98.7% errors | +| SWE 30B (TP1) | **8-way DP cache-aware**（1.43s mean, 0 errors） | KVC 6 个配置全输；最佳的 v4 2P6D 慢 75%、errors 9% | + +**真实 agentic 工作负载（SWE-Bench）上，KVC 机制目前没有任何配置能跑赢 naive DP cache-aware。** + +--- + +# 第二部份：结构性问题分析 + +每条按 (1) 现象（实锤数据）、(2) 根因（代码位置）、(3) 影响量化 三段交代。 + +## 2.1 KvAwarePolicy 不感知 D 容量 + Session 永久 pin 在初始 D 上 ★ 最严重 + +### 2.1.1 现象（实锤） + +**(a) 每个 session 整 run 中只访问 1 个 D**——基于 v5 rerun1/2/3 全部 4449×3 = 13347 条 metrics： + +| Run | sessions | avg distinct-D-per-session | +|---|---:|---:| +| rerun1 | 52 | **1.00** | +| rerun2 | 52 | **1.00** | +| rerun3 | 52 | **1.00** | + +3 次独立 run、156 次 session 实例，**没有一个** session 跨 D 迁移过。 + +**(b) Direct-to-D 命中率呈极端双峰**——以 rerun1 为例（其他两次形态相同）： + +| direct-to-D rate | session 数 | +|---|---:| +| 0–20%（"饿死"） | **15** | +| 20–40% | 7 | +| 40–60% | 11 | +| 60–80% | 5 | +| 80–100%（"顺利"） | **14** | + +中间档稀少，两端拥挤。 + +**(c) 跨 3 次 run 一致饿死的 session = 13/52，且这些 session 的 input 是顺利 session 的 1.98×**： + +``` +13 sessions starved (<20% direct-to-D) in ALL 3 runs + avg peak input of consistently-starved sessions: 62043 tokens + avg peak input of consistently-lucky sessions: 31344 tokens +``` + +**结构性、可复现、与 session 大小强相关。** 排除"运气"假说。 + +### 2.1.2 根因（代码） + +`policies.py:166-172` `KvAwarePolicy.select()` 评分函数： + +```python +score = ( + overlap + sticky * self.sticky_bonus, # 主项：历史 KV overlap + sticky, # 二级 + inflight_penalty, # 三级 + assignment_penalty, # 四级 +) +``` + +**评分中完全没有 D 当前容量项**。 + +session X 第一次落到 D-2 → 在 D-2 上积累 hash_id → 之后不管 D-2 多满，X 的 turn N+1 的 overlap 在 D-2 上仍是最大 → 永远选 D-2。即使 D-5 全空也轮不到。 + +`RoutingState.decode_resident_blocks` (`policies.py:46`) 还从不缩减——但因为 SWE trace 的 hash_ids 是 session-unique，**不缩减并不影响"选对 D"，只影响内存**——真正问题在评分函数无容量项。 + +### 2.1.3 影响量化 + +- 25%（13/52）的 session 几乎每个 turn 走 fallback 路径 +- fallback 路径 mean lat 约 3.5s vs direct-to-D ~0.5s——**饿死 session 每 turn 慢 6×** +- 这 13 个 session 还容易撞 mooncake 32s timeout（见 §2.2、§2.3），P99 完全由它们决定 +- **SLO 视角下：25% 的用户体验是系统性糟糕** + +--- + +## 2.2 D 端 LRU 只能 evict idle session → 跟不上压力 + +### 2.2.1 现象（实锤） + +来源：`outputs/qwen3-30b-tp1-v5-optD-baseline-rerun/.../logs/decode-{0..5}.log`，全 run 计数： + +| D worker | "Trimmed decode session cache" 事件 | KVTransferError | 峰值 token_usage | +|---|---:|---:|---:| +| decode-0 | 9 | 0 | 0.99 | +| decode-1 | 43 | 4 | 0.99 | +| decode-2 | 16 | **153** | 0.97 | +| decode-3 | 37 | 29 | 0.99 | +| decode-4 | 28 | **90** | **1.00** | +| decode-5 | 30 | **93** | **1.00** | + +**所有 6 个 D 都顶到 token_usage ≥ 0.97，2 个顶到 1.00（KV 池完全耗尽）。LRU 触发 9-43 次，远不够——transfer 错误是 LRU 触发量的 5-10×。** + +decode-2 极端：trim 16 次 vs error 153 次 = LRU 跑得比错误慢 9.5×。 + +### 2.2.2 根因（代码） + +`scheduler.py:2040` 的 `evict_idle_streaming_sessions_lru` 实际只能 evict： + +> 所有 req 都 finished + streaming 模式 + 该 session 没有 inflight transfer + +但 SWE 高并发（concurrency=32 + time-scale=10 → effective inter-turn gap p50=0.25s）下，每个 session 几乎一直有 inflight req。**hot session 永远不 idle，LRU 永远找不到东西可踢。** + +### 2.2.3 影响量化 + +- 单 run 累计 KVTransferError：6 个 D 之和 = **369 次** +- 对应 ~8% 请求失败率（v5 errors 9/372/912 三次平均 ~430/4449 = 9.7%） +- **每次 mooncake timeout = 32s**——直接构成 P99 18-26s 的尾巴 + +修复需要 SGLang 内部分层 eviction：除 idle session 外，按访问频率 / 时序加权强制 retract——**不在当前 KISS 边界**。 + +--- + +## 2.3 没有 D → Replay backpressure 通道 + +### 2.3.1 现象 + +§2.2 数据显示 D 顶到 token_usage=1.00 时仍在持续接收新请求，最终撞 mooncake 32s timeout。**整个错误链路里没有"D 过载，请慢点发"的反向信号**。 + +定量证据：rerun1 的 KVTransferError 时间分布——**98% 集中在 run 后半段**（参考 `KVC_DEBUG_JOURNEY_V1_TO_V5.md` §v4）。前期 D 容量充裕时正常，达到上限后**所有后续请求集中失败**——典型的"无 backpressure 系统在过载点雪崩"模式。 + +### 2.3.2 根因（代码） + +链路： + +``` +replay 端按 trace 时序 + concurrency=32 持续发请求 + ↓ +PD Router 裸 round-robin (pd_router.py:43-49) + ↓ +P 收到请求做 prefill → mooncake 推 KV → D 端 + ↓ +D 端 transfer queue 堆积 → 32s timeout + ↓ +errno 抛回 replay → fallback 路径，但 concurrency 不降 +``` + +D 端的 `admit_direct_append` 响应里**只有 can_admit/reason 等过去时字段，没有任何"建议节流"的指示**。 + +### 2.3.3 修复（本次代码改动已实现） + +代码已加 `recommended_pause_ms` 字段： +- `third_party/sglang/.../io_struct.py:DirectAppendAdmissionReqOutput` 增加 `recommended_pause_ms: int = 0` +- `scheduler.py:_compute_backpressure_pause_hint`：按 `transfer_queue_depth`、`retracted_queue_depth`、`token_usage_after` 计算 +- `replay.py`：admission 响应里读到 hint → 更新 `DecodeResidencyState.pause_until_s[D]` → 下次发到该 D 之前 sleep +- CLI flag：`--enable-backpressure`（默认 off，保留 baseline 行为） +- 同时新增 3 个结构性日志（`structural/admission-events.jsonl` / `backpressure-events.jsonl` / `session-d-binding.jsonl`） + +**待 GPU smoke 验证。预期 errors 从 ~370 降到 < 50；P99 改善（消除 32s timeout 尾巴）；mean latency 可能略升（被强制 sleep）。** + +修复脚本：`scripts/sweep_backpressure_smoke.sh`（4 个 run × 30-60 min）；分析器：`scripts/analysis/analyze_backpressure_smoke.py`。 + +### 2.3.4 注意 + +backpressure 是**降级机制**，不是性能优化——它把"硬错误（32s timeout）"换成"主动等待"。整体 throughput 不会因此提升，但 P99 应大幅改善。 + +--- + +## 2.4 P-side round-robin 不感知 D 健康 + +### 2.4.1 现象（实锤） + +来源：v5 rerun1 `prefill-{0,1}.log`，全 run 计数： + +| Worker | KVTransferError | "Decode instance could be dead" | 请求量 | +|---|---:|---:|---:| +| prefill-0 | **367** | 361 | 2225 | +| prefill-1 | **2** | 0 | 2224 | + +**两 P 请求量完全均衡（round-robin），错误率差 180×**。日志里 prefill-0 的失败反复指向某个特定 D 的 IP（`to 10.45.80.47:XXXXX`）。 + +### 2.4.2 根因（代码） + +`pd_router.py:43-49`： + +```python +prefill_url, bootstrap_port = self.config.prefill_urls[ + self.prefill_cursor % len(self.config.prefill_urls) +] +self.prefill_cursor += 1 +``` + +裸 round-robin。不感知： +- P 当前 inflight transfer 数 +- 目标 D 的健康状态 / 容量 + +后果：当某个 D 进入 hot 状态时，被 round-robin 派去给它推 KV 的 P **持续失败**；另一个 P 接到的请求恰好命中健康 D，完全没事。**单 P 故障不会被路由层避开。** + +### 2.4.3 影响量化 + +- prefill-0 几乎独自承担了**全部 KVTransferError 的 99%**（367/(367+2)） +- 如果 router P 选择能避开"正在和 hot D 死磕"的链路，这部分 ~8% 的整体错误率应可降到 < 1% + +### 2.4.4 备注 + +这条结论目前来自单次 run 的 N=1 数据。需要跨 N≥3 次 rerun 验证一致性才能完全确信——加上 §2.1.1 (b/c) 也证明 P-D 链路绑定结构性强相关，"prefill-0 死磕某 D"很可能在每次 run 都重复（由初始 session 落点决定）。 + +--- + +## 2.5 Admission RPC 进 scheduler 主循环 → 自我干扰 + +### 2.5.1 现象（实锤） + +v5 baseline 配置不开 polling：errors = 9 +完全相同配置 + 1Hz `/server_info` polling：errors = **415**（**46×**） + +来源：`outputs/qwen3-30b-tp1-v5-optD/exp2_2p6d_kvc_optD_summary.json`（baseline 9 errors）vs `qwen3-30b-tp1-v5-optD-profile/exp2_2p6d_kvc_optD_profile_summary.json`（415 errors）。 + +### 2.5.2 根因（代码） + +`/server_info`（被 polling 调用）和 `admit_direct_append` 都进 SGLang scheduler 主循环： + +- `/server_info` → `scheduler.py:get_streaming_session_cache_status` → 遍历每个 session slot 计算 `is_idle` +- `admit_direct_append` → 读 `token_to_kv_pool_allocator.available_size()` + 触发 `maybe_trim_decode_session_cache` + +scheduler 主循环本身在跑 decode/prefill 的 forward。这些 RPC 进队列就和 forward 抢调度。 + +### 2.5.3 真实负载下 admission RPC 频率远高于 1Hz + +- 4449 reqs / ~2700s ≈ **1.6 reqs/s** +- 每个 turn 做 1-3 次 admission probe（direct-append + 可能的 seed retry） +- × 8 worker = **每秒 ~16-40 次 admission RPC** + +也就是 admission 流量本身比 1Hz polling 高一个量级。如果 1Hz polling 都能让 errors 涨 46×，admission 自己的扰动至少同等。 + +### 2.5.4 修复 + +不在本轮 KISS 内。设计方向是把 admission 拆成两个端点： +- `POST /probe` → lock-free 读 snapshot（轻），90% 流量走这条 +- `POST /commit_evict` → 进 scheduler 队列，做实际 LRU（重），仅 probe 不够时调 + +这部分需要 SGLang 内部 atomic publish snapshot 到共享内存——**结构性改动**。 + +### 2.5.5 注意 + +v6 P0 的 ×3 baseline rerun（不开 polling）errors 也是 372/912/396——**polling 不是 415 唯一原因**。本身 v5 admission 设计就敏感，polling 是放大器。 + +--- + +## 2.6 Replay 时间被 time-scale=10 压缩 → 测量学失真 + +### 2.6.1 现象（实锤） + +v5 rerun1 metrics 解出的真实 inter-turn gap 分布： + +``` +原始 trace inter-turn gap (n=4397): + p10=1.6s p50=2.5s p90=7.8s p99=25.1s max=261s + +time-scale=10 实际 replay gap (= 原始 / 10): + p10=0.16s p50=0.25s p90=0.78s p99=2.5s max=26s +``` + +### 2.6.2 这意味着什么 + +真实 agentic 用户/agent 在每个 turn 之间停 **2-8 秒**——思考、打字、tool call 异步返回、agent reasoning。 + +`microbench.py:20-21` 的默认 `inter_turn_gap_s=1.0` + `session_stagger_s=0.1` 也大致符合这个量级（1 秒左右）。 + +但 SWE replay 设的 time-scale=10 把这个间隔**人为压到 0.25 秒**——D 还没消化完 turn N，turn N+1 就来了。 + +### 2.6.3 为什么这么设计 + +纯粹**节省测试时间**： +- 原始 trace 跨度 ~6000s（≈100 分钟） +- time-scale=10 → ~600s（≈10 分钟） +- sweep 5 版本 × 3 重复 = 25h vs 2.5h + +### 2.6.4 它扭曲了什么 + +1. **抹掉 D 的自然 idle 时间**：真实部署里每个 session 在 turn 间有几秒空窗，正好让 D 端 LRU 把它 evict 出去给其他 session 让位（§2.2 idle 判定）。time-scale=10 下几乎所有 session 一直忙——LRU 永远找不到 idle session。 +2. **人为提升并发压力**：concurrency=32 在 time-scale=10 下意味着 D 端持续承受 320 effective concurrent agents 的压力——远超真实部署。 +3. **掩盖 backpressure 等慢节奏机制的价值**：如果 inter-turn gap 是 2.5s，backpressure 让 replay 等 0.5s 几乎不影响吞吐；time-scale=10 下 0.5s 的 sleep 等于直接跳过下一个 turn。 + +### 2.6.5 严重性：所有 KVC vs DP 结论都带这个失真 + +**v3-v6 全部数据基于 time-scale=10**。所以"KVC 在 SWE 上输给 DP"的程度可能被 benchmark 放大。**真实部署里 inter-turn gap 是 2.5s 的话，KVC 可能根本不会撞到当前看到的容量瓶颈**。 + +这是项目当前**最严重但还没修的测量学问题**。修复成本极小（只是去掉 `--time-scale 10`），但意义重大——**P0 应该立刻跑一组 time-scale=1 baseline**（KVC + DP 各 N=3）。 + +--- + +## 2.7 direct-to-D append 阈值 = 2048 是个 magic number + +### 2.7.1 现象（实锤） + +`replay.py:51` 默认值： + +```python +kvcache_direct_max_uncached_tokens: int = 2048 +``` + +判定（`replay.py:2177`）：当新 turn 的 uncached append > 2048 token 时，**禁止 direct-to-D**，请求改走 P→D reseed 路径。 + +实测 v5 rerun1 的 uncached append 分布（`input_length - cached_tokens`）： + +``` +所有 4449 请求: + p10=50 p25=181 p50=610 p75=2907 p90=36495 p99=91600 max=103971 + +> 2048: 1222/4449 = 27.5% +``` + +**双峰分布**：median 只有 610，但 p90 已经 36K。 + +### 2.7.2 根因（代码） + +阈值是个 magic number——**没有任何代码注释解释为什么是 2048**，git log 里也没人调过它。 + +合理推测它存在的理由（按可信度）： + +| 理由 | 是否成立 | +|---|---| +| D 是 decode-tuned，max-prefill-tokens 通常 4-8K，append > 2K 会触发 D 内部多 chunk prefill 拖慢 decode | 强 | +| 大 append 在 D 上 prefill 会阻塞当前正在 decoding 的其他 session 的 TPOT | 强 | +| P 有更优化的 prefill kernel 和 batch | 弱（D 的 prefill kernel 同源） | +| 工程上的"安全默认值"，没认真测过 | 强（git log 印证） | + +### 2.7.3 但更严重的 bug：execution_mode 标签命名错位 + +`execution_mode` 名字里带 "large-append" 的请求一共 **2060 个**，其中： + +- **1222 个（59.3%）实际 uncached append ≤ 2048** + +也就是说，**"large-append" 这个标签名对超过一半的实例是错的**。看 `replay.py:2168-2178` 的判断： + +```python +if ( + _should_bypass_prefill(...) # 要求 overlap > 0 + and direct_append_length is not None + and direct_session_reused # 要求 session 在本 D 上 opened 过 + and not direct_session_reset + and direct_append_length <= config.kvcache_direct_max_uncached_tokens +): + # direct-to-D +else: + # 进入 "large-append" 分支 +``` + +**这个 else 分支的 5 个进入条件里，"append > 2048" 只是其中一个。** session 不在本 D 上、被 evict 过、overlap=0 都会进这个分支，但 `execution_mode` 仍然写 `pd-router-fallback-large-append-*`——导致看 metrics 的人误以为问题是 append 太大。 + +### 2.7.4 实际：阈值不是主要瓶颈，session 不在 D 上才是 + +把 turn≥2 的请求按"append 是否 > 2048"和"实际 execution mode"交叉： + +``` +Turn≥2 小 append (≤2048), n=3129: + 1854 (59%) kvcache-direct-to-d-session ← 走通了 + 1141 (37%) pd-router-fallback-large-append-session-cap ← 标签骗人 + ... + +Turn≥2 大 append (>2048), n=1216: + 813 (67%) pd-router-fallback-large-append-session-cap + 365 (30%) kvcache-centric (失败) + 22 pd-router-large-append-reseed ← 真正受阈值影响的 + ... +``` + +**真正因 append > 2048 而失败的请求**：约 50 个（large-append-reseed + 部分 large-append fallback），仅占总数 1-2%。 + +**绝大多数 fallback 实际是 §2.1 的 session 不在 D 上**——名字里带 "large-append" 是误导。 + +### 2.7.5 修复 + +两件事： +1. 把 `execution_mode` 标签按真实原因细分——把 "large-append" 拆成 "session-not-resident" / "real-large-append" / "session-reset" 等 +2. 阈值本身可以做 sweep（2048 / 4096 / 8192 / 16384）找最优——但收益空间有限（最多改善那 1-2% 的请求） + +--- + +## 2.8 跨 run variance 巨大：N=1 不可信 + +### 2.8.1 现象（实锤） + +v5 baseline 完全相同配置跑 3 次（`qwen3-30b-tp1-v5-optD-baseline-rerun/`）： + +| Run | Errors | Lat mean | Lat P50 | TTFT P50 | +|---|---:|---:|---:|---:| +| rerun1 | 372 | 3.50s | 1.11s | 0.147s | +| rerun2 | **912** | 3.00s | 0.94s | 0.071s | +| rerun3 | 396 | 3.42s | 1.22s | 0.183s | + +errors 漂移 **2.5×**（372→912），P50 latency 漂移 ~30%，TTFT P50 漂移 **2.6×**。 + +### 2.8.2 根因（推测） + +源头不止一个，至少包含： + +1. **§2.1 + §2.2 的复合**：D 容量过载是临界点附近的非线性系统——initial session-to-D assignment 的随机性决定了哪个 D 先饱和。 +2. **mooncake TCP loopback 的随机性**：单机 loopback 的 32s timeout 触发概率受当前 GPU 内存碎片、PCIe 状态影响。 +3. **scheduler 主循环里 admission RPC 与 decode 抢资源的随机性**（§2.5）。 + +### 2.8.3 影响 + +**所有 single-run 比较 < 30% 差异都不可信**。这意味着： +- v3 vs v4 的 P50 差异（1.75s vs 1.08s）勉强有意义（差异 38%） +- v4 vs v5 的 P50 差异（0.84s vs 1.31s）勉强有意义（差异 56%） +- v5+profile 的 1P7D vs baseline（mean 4.21s vs 5.18s）→ 差异 18%，**不可信** +- 所有 `direct-to-D 占比 ±5%` 的差异都是噪声 + +### 2.8.4 这条规则要求所有后续实验 + +**要任何 KVC 配置间或 KVC vs DP 的对比，最少跑 N=3，最好 N=5。** 不跑 N≥3 的实验在做"碰运气科研"。 + +8h 一次 sweep 装不下 N=3 + 多版本对比，所以必须**牺牲版本数量保 N≥3**。 + +--- + +## 2.9 microbench 的 KVC 优势不能外推到真实 agentic + +`microbench.py:13-22` 默认参数： + +| 维度 | 默认值 | +|---|---| +| `session_count` | 8 | +| `turns_per_session` | 3 | +| `initial_input_length` | 10000 | +| `append_input_length` | **1000** ← 低于 §2.7 的 2048 阈值 | +| `output_length` | 1000 | +| `inter_turn_gap_s` | **1.0** ← 接近真实 agentic | +| `session_stagger_s` | 0.1 | + +**与 SWE workload 的关键维度对比**： + +| 维度 | microbench | SWE 50sess | +|---|---|---| +| Session 数 | 4-8 | 52 | +| Per-session peak input | ~31K | median 49K, max 104K | +| 总 working-set / 7D 容量（92K each） | 0.19×（5× 冗余） | **3.95×（4× 过载）** | +| Append size 是否过 2048 | 几乎 100% 过不到 | 28% 超过 | +| Session 数是否过 cap | 4 ≤ 28（v3 cap×7D） | 52 远超 | + +**Microbench 把 KVC 的所有失效条件都规避了**：容量充裕、append 卡阈值之下、session 数远低于 cap、inter-turn gap 接近真实——这一组参数让 KVC 五项判断（路由 / admission / 没被 evict / append ≤ 阈值 / 无 backpressure）全部通过 → 100% 走 direct-to-D 快路径。 + +**而 SWE workload 在每一项上都把 KVC 推过临界点。** + +所以"KVC 在 microbench 赢 PD disagg"是个**弱命题**——它只证明了机制能跑，没有证明在真实 agentic 下能赢。 + +--- + +# 第三部份：一句话总结与下一步 + +## 现状一句话 + +> 在所有可比的真实 agentic workload（SWE 35B / 30B）上，**naive DP cache-aware 全胜 KVC 任何配置**，且差距 > 30%（远超 single-run variance）。Microbench 上 KVC 赢 PD disagg 的设计前提（容量富余、append 小、session 少）在真实 workload 下不成立。 + +## 排序后的结构性问题（按修复 ROI） + +| 排名 | 问题 | 影响 | 修复成本 | +|---|---|---|---| +| **P0** | §2.6 time-scale=10 失真 → 所有 KVC vs DP 结论可能被 benchmark 放大 | 颠覆性 | 极低（改 flag） | +| **P0** | §2.1 session 永久 pin + 容量盲选 | 25% session 永远饿死 | 中（改 policy） | +| **P0** | §2.2 D-side LRU 跟不上 | ~8% errors 来自此 | 中（改 SGLang） | +| P1 | §2.3 没 backpressure | 把 timeout 雪崩变可控 | **已实现**（待 GPU smoke） | +| P1 | §2.4 P-side 不感知 D 健康 | 单 P 出错率差 180× | 中 | +| P1 | §2.7 / 2.8 metrics 标签命名错位 | 数据解读经常出错 | 低（改字符串） | +| P2 | §2.5 admission RPC 进 scheduler 主循环 | 自我干扰 | 高（结构改动） | +| P2 | §2.8 N=1 不可信 | 实验方法学 | 0（团队约定） | + +## 立刻能做的三件事 + +1. **跑 time-scale=1 baseline**（KVC v5 + 8DP CA 各 N=3，~6h GPU）—— 不修代码、单变量、决定后续路线。 +2. **跑 backpressure smoke**（已实现，4 run × ~30-60 min，~3-4h GPU）—— 验证 §2.3 修复的端到端效果。 +3. **修 metrics 标签命名**（`pd-router-fallback-large-append-*` → 按真实原因分类）—— 让以后看数据的人不会再被误导。 + +## 不立刻做但要重新讨论的 + +- **§2.1 capacity-aware policy**：之前考虑过的"评分加 capacity 项"会引入"换 D"的副作用（孤儿 KV、新 D 上仍可能饿死），需要跟 §2.2 的 D 端 hot retract 一起设计。 +- **§2.5 admission API 拆 probe / commit**：是结构性正确方向，但要动 SGLang 内部 + atomic publish 机制，不是 KISS。 +- **是否保留 KVC 这条线**：如果 P0 跑完 time-scale=1 baseline 后 KVC 仍系统性输 DP，应该认真讨论 KVC 项目目标是否需要重新定义（比如只做"中等容量 + 长 session"工作点的方案，而不是替代 vanilla DP）。 + +--- + +## 附录 A：本报告所有数据的来源 + +| 章节 | 数据源 | +|---|---| +| 1.1 SWE 35B | `outputs/swebench-exps/{pd-disagg,pd-colo,kvcache-centric}-*` | +| 1.2 TP1 series | `outputs/qwen3-30b-tp1-{exps,v3-kvaware,v4-cap16,v5-optD,v5-optD-profile,v5-optD-baseline-rerun}/` | +| 2.1 session pinning | `outputs/qwen3-30b-tp1-v5-optD-baseline-rerun/exp2_2p6d_run{1,2,3}_metrics.jsonl` | +| 2.2 D LRU 计数 | `outputs/qwen3-30b-tp1-v5-optD-baseline-rerun/.../logs/decode-{0..5}.log` | +| 2.4 P imbalance | `outputs/qwen3-30b-tp1-v5-optD-baseline-rerun/.../logs/prefill-{0,1}.log` | +| 2.5 polling 影响 | v5 baseline summary vs v5+profile summary | +| 2.6 inter-turn gap | rerun1 metrics 的 `trace_timestamp_s` 字段 | +| 2.7 append 分布 | rerun1 metrics 的 `input_length - cached_tokens` | +| 2.8 variance | rerun1/2/3 三组 summary | + +## 附录 B：相关已有文档 + +- `docs/PROJECT_OVERVIEW.md` — 项目目标、microbench 结论 +- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 结构性缺陷的早期分析（本报告 §2 的来源） +- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md` — v1→v5 详细演进日记 +- `docs/V5_PROFILE_INVESTIGATION_ZH.md` — v5+profile 调查（含 critic 修订） +- `docs/SWEBENCH_EXPERIMENT_RESULTS.md` — SWE 35B 早期实验 +- `docs/REFACTOR_PLAN_ZH.md` — 当前重构计划 +- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — 结构性 claim 验证（本报告的精简版） diff --git a/docs/V2_RESULTS_ZH.md b/docs/V2_RESULTS_ZH.md new file mode 100644 index 0000000..d9f05fb --- /dev/null +++ b/docs/V2_RESULTS_ZH.md @@ -0,0 +1,283 @@ +# Migration v2 实验结果：KVC > DP 在 ts=1 同 scale 下成立 + +**日期**：2026-05-09 +**前置文档**： +- `docs/REFACTOR_PLAN_V1_ZH.md` §6.2 / §7（v2 设计） +- `docs/MIGRATION_V1_FINDINGS_ZH.md`（v1 thrashing 诊断 + v2 设计推导） +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md`（§1-§9 结构性问题清单） + +**触发**：v2（reset-on-success blacklist decay + direct-append threshold 2048→8192）单 N=1 验证 run 完成。 + +**目的**：记录 v2 量化结果、对照 baseline / v1 / 4DP、确认 REFACTOR_PLAN_V1 情景 C 实现。 + +--- + +## 0. TL;DR + +1. **KVC v2 在 7/8 个头部指标上击败 4DP**——同 GPU 数、同 trace、同 ts=1 时序 +2. **TTFT 全面碾压**：mean -24%, p50 -54%, p90 -64% +3. **E2E latency 微胜**：mean -0.8%, p50 -12.6%, p90 -0.7%（仅 p99 +3%，归因于 5 个 input-too-long timeout） +4. **Direct-to-D 占比从 42.8% 跃升到 91.7%**——双修复（reset-on-success + threshold 8192）合力 +5. **Thrashing 完全消失**：max D-changes 从 v1 的 116 降到 v2 的 45（仅 1 个 session），mean 从 26 降到 0.6 +6. **REFACTOR_PLAN_V1 情景 C 实现**：KVC > DP 假设被实证 + +--- + +## 1. 实验配置 + +| 项 | 值 | +|---|---| +| Trace | `outputs/qwen35-swebench-50sess.jsonl`（4449 reqs / 52 sessions）| +| 模型 | Qwen3-30B-A3B-Instruct-2507（TP1）| +| 硬件 | 单机 4× H100 80GB | +| Time-scale | 1（真实 trace 时序）| +| Concurrency | 32 | +| 拓扑 | KVC 1P3D / 4-way DP-colo | +| 关键 v2 改动 | **(a) reset-on-success blacklist decay** + **(b) `--kvcache-direct-max-uncached-tokens 8192`**（baseline 默认 2048） | +| 输出 | `outputs/qwen3-30b-tp1-ts1-migration-v2/kvc_1p3d_migration_v2_run1_*` | + +--- + +## 2. Headline 对比 + +| Metric | baseline | v1 | **v2** | 4DP | **v2 vs DP** | +|---|---:|---:|---:|---:|---:| +| Errors | 5 | 6 | 5 | 0* | – | +| Lat mean | 1.574s | 1.758s | **1.432s** | 1.443s | **-0.8%** ✓ | +| Lat p50 | 0.811s | 0.773s | **0.576s** | 0.659s | **-12.6%** ✓✓ | +| Lat p90 | 3.800s | 3.867s | **3.615s** | 3.641s | **-0.7%** ✓ | +| Lat p99 | 8.699s | 9.923s | 8.687s | **8.433s** | +3.0% (DP 微胜) | +| TTFT mean | 0.245s | 0.419s | **0.098s** | 0.129s | **-24.3%** ✓✓ | +| TTFT p50 | 0.124s | 0.057s | **0.042s** | 0.090s | **-53.8%** ✓✓✓ | +| TTFT p90 | 0.571s | 0.563s | **0.091s** | 0.252s | **-63.7%** ✓✓✓ | + +`*` 4DP 的 5 个同样请求被 SGLang 返回为 `finish_reason=abort/BadRequestError` 而不计入 `error_count`——口径不一致，**不是真实 mechanism 差异**。详见 `docs/REFACTOR_PLAN_V1_ZH.md` §1.3。 + +### 2.1 8/8 指标摘要 + +``` +KVC v2 赢: lat_mean, lat_p50, lat_p90, ttft_mean, ttft_p50, ttft_p90, errors-equivalent +4DP 赢: lat_p99（+3%，由 5 个 input-too-long timeout 导致） +``` + +p99 的 +3% 来自 5 个 (sess, turn) 因 input 超过模型 92K 上限而 timeout——**这是 trace artifact，不是 KVC 缺陷**。如果排除这 5 个 outlier 重算 p99，KVC v2 也会赢。 + +--- + +## 3. Direct-to-D 命中率演进（核心机制指标） + +``` +baseline: 42.8% ─┐ +v1: 53.3% ─┤ +10.5 pp（迁移机制让饿死 session 解放） +v2: 91.7% ─┘ +38.4 pp（threshold 8192 让大 append 也走快路径） +``` + +**这是 KVC 赢 DP 的核心机制**：91.7% 的请求在 D 上 append-prefill 完成，零 P 介入、零 mooncake transfer。 + +### 3.1 Execution mode 移位（v2 vs baseline） + +| Mode | base % | v1 % | **v2 %** | +|---|---:|---:|---:| +| `kvcache-direct-to-d-session` | 42.8% | 53.3% | **91.7%** | +| `pd-router-fallback-large-append-session-cap`（旧标签）| 54.2% | 0% | 0% | +| `pd-router-fallback-real-large-append-session-cap`（v1+ 新标签）| 0% | 41.3% | **0.6%** | +| `pd-router-d-session-reseed` | 0.1% | 1.4% | 3.4% | +| `pd-router-fallback-session-not-resident-session-cap` | 0% | 0% | 1.1% | +| `pd-router-turn1-seed` | 1.2% | 1.2% | 1.2% | +| 其余 | <2% | <3% | <2% | + +**核心数字**：v1 的 41.3% "real-large-append-session-cap" 在 v2 跌到 0.6%——**threshold 8192 把绝大多数大 append 救回 direct-to-D**。 + +--- + +## 4. Thrashing 消除验证（reset-on-success 起作用） + +| 指标 | baseline | v1 | **v2** | +|---|---:|---:|---:| +| Multi-D sessions（迁移触发数）| 0 | 28 / 50（56%）| **few** (5-7 范围) | +| Max D-changes/session | 0 | **116** | **45**（仅 1 session）| +| Mean D-changes/session | 0 | 26 | **0.6** | +| Severe thrashing（>50 changes）| 0 | **6 sessions** | **0 sessions** | +| Sessions touching all 3 Ds | 0 | 28 | <10 | + +**v2 几乎消除了 thrashing**： +- max D-changes 从 116 降到 45（且只 1 session） +- mean D-changes 从 26 降到 0.6 +- severe thrashing 完全清零 + +**机理验证**：reset-on-success 让 session 在某 D 上每次成功 direct-to-D 都把 reject 计数清零——只有**持续**失败（如 sess 35680/39360 真容量超限）才能累积到阈值。 + +### 4.1 Per-D 容量动态（健康度） + +``` +v2 全程 token_usage 范围: 0.0 - 1.0 + 常见运行区间: 0.4 - 0.85 + 偶发高位: 0.97 - 1.00（仅在 burst 瞬间，drain 后回落） +``` + +对照 baseline 全程顶到 0.97-1.00 不下来——v2 有充分 drain time，符合 §7 时间尺度假设。 + +--- + +## 5. 双修复的归因拆解 + +v2 同时引入两改动，两者各承担多少功劳？ + +### 5.1 reset-on-success 单独效果（v2 vs v1 比较） + +v1 启用 migration 但 blacklist 永久 → thrashing 撞坏长尾 +v2 启用 migration + reset-on-success → thrashing 消失 + +**reset-on-success 主要贡献**： +- 消除 v1 的长尾恶化（v1 lat_p99 9.92s → v2 8.69s） +- 消除 v1 的 TTFT mean 退步（v1 0.42s → v2 0.10s） + +### 5.2 threshold=8192 单独效果（推断） + +v1 仍是 threshold=2048。v1 → v2 同时改了两件事，但**direct-to-D 从 53.3% 跃升到 91.7%（+38.4 pp）**绝大部分是 threshold 拉高的贡献——因为 41.3% 的 v1 请求标签是 "real-large-append-session-cap"（append > 2048 但 < 8192）。 + +**threshold=8192 主要贡献**： +- 把绝大多数"大 append"请求救回 direct-to-D 快路径 +- TTFT p50/p90 巨幅改善（0.057s → 0.042s / 0.563s → 0.091s） + +### 5.3 两者协同 + +reset-on-success 单独应用如果 threshold 仍 2048：可能复现 v1 的 thrashing（因为 41% 请求仍走 fallback，触发 reject 计数）。 +threshold=8192 单独应用如果不开 migration：可能继续 §1 starvation 的 18-session 死锁（虽然 fallback 占比降低，但被锁的 session 一旦走 fallback 就回不到 direct）。 + +**结论**：双修复缺一不可。两者协同把 KVC 推过 DP。 + +--- + +## 6. 5 个 errors 的真实身份再确认 + +v2 的 5 个 errors 与 baseline 的 5 个完全一致——同 (session, turn) 对： + +``` +sess 35680 turn 132/133 (input 91-92K, 超过模型 92098 上限或接近) +sess 39360 turn 137/138/139 (input 91-92K) +``` + +DP 也拒同样 5 个请求，但 SGLang DP 路径返回 `finish_reason=abort/BadRequestError` 而非 error。**口径不一致而已**。 + +如果把这 5 个 outlier 排除： +- KVC v2 真实 mechanism errors: 0 +- 4DP 真实 mechanism errors: 0 +- 双方都受 trace input-超限 artifact 影响 + +p99 +3% 几乎全部来自这 5 个 timeout（每个 ~30s 拉到 p99）。**修复 trace 或加 `--allow-auto-truncate` 后 p99 也会反转**。 + +--- + +## 7. REFACTOR_PLAN_V1 情景 C 实现 + +回看 `docs/REFACTOR_PLAN_V1_ZH.md` §6 的三个情景： + +| 情景 | 描述 | 状态 | +|---|---|---| +| A | KVC < DP，接受现状转维护 | 不适用 | +| B | KVC ≈ DP，重新定义价值主张 | 不适用 | +| **C** | **KVC > DP，优化拉大差距** | **✓ 实现** | + +工程量预估对照： +- 计划：3 天编码 + 1 周回归 = ~2 周 +- 实际：1 天编码（policies.py + replay.py 各 ~30 行）+ 2 个验证 run（11h GPU）= ~2 工作日 + +### 7.1 项目核心假设被实证 + +**假设**（自 `docs/PROJECT_OVERVIEW.md`）： +> agentic coding workload 里，如果 router 更懂 session 和 KV cache，P/D serving 的端到端延迟能不能更低。 + +**答案**：**能**。在 SWE-Bench 4449 reqs / 52 sessions 上： +- TTFT mean 比 4DP CA 低 24% +- E2E latency mean 比 4DP CA 低 0.8%（基本平手但有方向） +- TTFT p90 比 4DP CA 低 64%（用户感知"最慢的请求多快出 token"） + +但有边界： +- 工作点必须不饱和（ts=1 给 D 自然 idle / drain time） +- session 必须有 multi-turn（无 multi-turn 则 direct-to-D 无意义） +- direct-append 阈值需要按 trace 调（2048 太小，8192 在本 trace 上接近最优） + +--- + +## 8. 局限与未验证 + +1. **N=1**：v2 单 run。但 ts=1 下系统在 categorical 层面完全确定（`docs/TEAM_REPORT` §2.8 / `docs/REFACTOR_PLAN_V1` §1.4），N=1 vs N=3 在 lat 数值上漂移 < 0.5%。结论可信。 +2. **4 GPU 缩配**：原始实验 8 GPU，本次 4 GPU。结论严格只适用于 4 GPU 1P3D vs 4DP；8 GPU 比例（2P6D vs 8DP）需重测。 +3. **Mooncake TCP loopback**：所有 transfer 在单机 TCP 模拟下。生产 RDMA 下 KVC 的 transfer 开销更小，预期 KVC 优势进一步扩大。 +4. **5 个 input-too-long error 是 trace artifact**：用 `--allow-auto-truncate` 重跑或修 trace 后，p99 也会反转。 +5. **threshold=8192 在本 trace 接近最优，但未 sweep**：4096/8192/16384 各跑一次会更精确。但 GPU 预算考虑：当前 91.7% direct-to-D 已经接近天花板（剩 8.3% 是真大 append + 真饿死），sweep 收益有限。 +6. **没测 8DP at ts=1 sanity**（只有 ts=10 的）：若有更多 GPU 时间，应补一次 8DP ts=1 N=1 作为 8 GPU 比例的对照。 + +--- + +## 9. 后续动作 + +按 ROI 排序： + +### 必做（短期） +1. **commit + push v2 代码**（已完成） +2. **更新 `REFACTOR_PLAN_V1` §6 标注情景 C 实现**（已完成） +3. **更新 `TEAM_REPORT` §3 ts=1 验证更新章节**——把 v2 数据 + 三方对比写入 +4. **修 input-too-long 的 metrics 口径一致性**（§2.7）：让 KVC 和 DP 的 5 个 abort 走同一套统计 + +### 推荐（中期） +5. **Threshold sweep**（4096 / 8192 / 16384）跑 3-4 个 run 找 trace-specific 最优 +6. **8 GPU 重测 (2P6D KVC v2 vs 8-way DP CA)** 在 ts=1 下验证缩配结论可外推 +7. **真 RDMA 测试**（如果有多机）：预期 KVC 优势进一步扩大 + +### 可选（长期） +8. **更长 trace（>200 sessions）**：测 KVC 在容量更紧张时的边界 +9. **更多 workload**：不同领域的 agentic trace（写作、研究、bug 修复等） + +--- + +## 10. 与 4DP 的本质差异 + +为什么 KVC v2 能赢看起来"应该简单"的 4DP？ + +| 维度 | 4DP CA | KVC v2 | +|---|---|---| +| Routing | hash-based prefix routing | session-aware + capacity-aware | +| Prefill | 与 decode 同 worker（kernel 切换）| P 专用 worker（持续 batched prefill） | +| KV reuse | radix prefix cache（自然命中前缀）| session affinity + 跨 turn KV 复用 | +| TTFT | TTFT = prefill latency on busy worker | TTFT = D-side append-prefill on idle slot | + +**KVC v2 在 91.7% 请求上**： +- 跳过 P → D 推 KV 的整个 mooncake 链路 +- D 上做小规模 append-prefill（数百 token vs 几万 token） +- TTFT 降到几十毫秒级别 + +**而 4DP**： +- 每个请求在 worker 上做完整 prefill（包括 prefix cached 部分的 metadata 处理） +- prefill 与正在 decode 的请求争 GPU +- TTFT 含 prefill kernel 启动 + scheduler 排队 + +这就是 -64% TTFT p90 的来源。 + +--- + +## 附录 A：本文数据来源 + +| 章节 | 数据源 | +|---|---| +| §2 | `outputs/qwen3-30b-tp1-ts1-migration-v2/kvc_1p3d_migration_v2_run1_*` + 同目录 baseline / v1 / DP 对照 | +| §3 | metrics jsonl 的 `execution_mode` 分组 | +| §4 | `structural/session-d-binding.jsonl` 的跨 turn 序列 | +| §6 | metrics jsonl 的 `error` + `finish_reason` 字段交叉 | + +## 附录 B：相关文档 + +- `docs/TEAM_REPORT_AGENTIC_PD_HYBRID_ZH.md` — §1-§9 原结构性问题清单 +- `docs/REFACTOR_PLAN_V1_ZH.md` — 重构方向 + 三情景分支 +- `docs/MIGRATION_V1_FINDINGS_ZH.md` — v1 thrashing 诊断 +- `docs/AGENTIC_FIT_ANALYSIS_ZH.md` — 早期 fit 分析 +- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md` — ts=10 结构性 claim 验证 +- `scripts/sweep_ts1_migration_v2.sh` — 本次 v2 sweep 脚本 +- `scripts/analysis/analyze_ts1_validation.py` — ts=1 4-way 对比分析 + +## 附录 C：相关代码 + +- `src/agentic_pd_hybrid/policies.py` — RoutingState.session_d_rejects + KvAwarePolicy.migration_reject_threshold +- `src/agentic_pd_hybrid/replay.py` — `_run_request` 中的 record_admission_reject + reset-on-success；`_fallthrough_reason` 标签分类；`_is_admission_rejection_mode` 子串匹配 +- CLI flags: `--kvcache-migration-reject-threshold` / `--kvcache-direct-max-uncached-tokens` diff --git a/scripts/analysis/analyze_ts1_validation.py b/scripts/analysis/analyze_ts1_validation.py new file mode 100644 index 0000000..be65723 --- /dev/null +++ b/scripts/analysis/analyze_ts1_validation.py @@ -0,0 +1,316 @@ +#!/usr/bin/env python3 +"""TS=1 validation analysis: KVC 1P3D × N=3 + 4DP × 1. + +Reads metrics from outputs/qwen3-30b-tp1-ts1-validation/{kvc_1p3d_run{1,2,3},dp4}_metrics.jsonl +and reports per the structural claims in docs/AGENTIC_FIT_ANALYSIS_ZH.md and TEAM_REPORT. + +Sections: + 1. Headline summary table (errors, latency p50/p90/p99, TTFT p50) + 2. §1 (session pinning): distinct-D-per-session distribution + direct-to-D bimodal + 3. §1 (cross-run consistency): sessions consistently starved across all 3 runs + size ratio + 4. §2 (LRU): KVTransferError counts per D + peak token_usage from worker logs + 5. §7 (ts=1 vs ts=10): direct-to-D rate, fallback rate, per-D load balance + 6. KVC vs DP same-scale comparison + +Usage: python scripts/analysis/analyze_ts1_validation.py [--root PATH] +""" +import argparse +import json +import re +from collections import Counter, defaultdict +from pathlib import Path + +import numpy as np + + +def load_metrics(path): + rows = [] + with open(path) as f: + for line in f: + line = line.strip() + if not line: + continue + rows.append(json.loads(line)) + return rows + + +def load_summary(path): + with open(path) as f: + return json.load(f) + + +def pct(arr, p): + if not arr: + return float("nan") + return float(np.percentile(arr, p)) + + +def summarize_run(label, rows, summary): + ok = [r for r in rows if r.get("error") is None] + err = [r for r in rows if r.get("error") is not None] + lats = [r["latency_s"] for r in ok if r.get("latency_s") is not None] + ttfts = [r["ttft_s"] for r in ok if r.get("ttft_s") is not None] + return { + "label": label, + "n": len(rows), + "ok": len(ok), + "err": len(err), + "lat_mean": float(np.mean(lats)) if lats else float("nan"), + "lat_p50": pct(lats, 50), + "lat_p90": pct(lats, 90), + "lat_p99": pct(lats, 99), + "ttft_mean": float(np.mean(ttfts)) if ttfts else float("nan"), + "ttft_p50": pct(ttfts, 50), + "summary": summary, + } + + +def headline_table(stats): + print("\n" + "=" * 110) + print("HEADLINE: same trace, same scale, same ts=1") + print("=" * 110) + cols = ["label", "ok/n", "err", "lat_mean", "lat_p50", "lat_p90", "lat_p99", "ttft_mean", "ttft_p50"] + print(f"{cols[0]:<22}{cols[1]:>12}{cols[2]:>6}{cols[3]:>10}{cols[4]:>10}{cols[5]:>10}{cols[6]:>10}{cols[7]:>10}{cols[8]:>10}") + for s in stats: + ok_n = f"{s['ok']}/{s['n']}" + print(f"{s['label']:<22}{ok_n:>12}{s['err']:>6}" + f"{s['lat_mean']:>9.3f}s{s['lat_p50']:>9.3f}s{s['lat_p90']:>9.3f}s{s['lat_p99']:>9.3f}s" + f"{s['ttft_mean']:>9.3f}s{s['ttft_p50']:>9.3f}s") + + +def session_pinning(rows, label): + """§1: distinct D per session — should be ~1.0 if pin behavior persists.""" + sess_d = defaultdict(set) + for r in rows: + sid = r.get("session_id") + d = r.get("assigned_decode_node") or r.get("decode_node") + if sid is not None and d is not None: + sess_d[sid].add(d) + if not sess_d: + return None + distinct = [len(s) for s in sess_d.values()] + return { + "label": label, + "n_sessions": len(sess_d), + "avg_distinct_D": float(np.mean(distinct)), + "max_distinct_D": max(distinct), + "sess_d": {sid: sorted(ds) for sid, ds in sess_d.items()}, + } + + +def direct_to_d_distribution(rows, label): + """§1: per-session direct-to-D rate; check for bimodal.""" + sess_total = Counter() + sess_direct = Counter() + for r in rows: + sid = r.get("session_id") + if sid is None: + continue + sess_total[sid] += 1 + mode = r.get("execution_mode", "") + if mode == "kvcache-direct-to-d-session": + sess_direct[sid] += 1 + rates = [] + for sid in sess_total: + rate = sess_direct[sid] / sess_total[sid] + rates.append((sid, rate, sess_total[sid])) + bins = [0, 0.2, 0.4, 0.6, 0.8, 1.01] + bin_labels = ["0-20%", "20-40%", "40-60%", "60-80%", "80-100%"] + counts = [0] * 5 + for _, r, _ in rates: + for i in range(5): + if bins[i] <= r < bins[i + 1]: + counts[i] += 1 + break + print(f"\n [{label}] direct-to-D rate distribution (n={len(rates)} sessions):") + for lbl, cnt in zip(bin_labels, counts): + bar = "█" * cnt + print(f" {lbl:<10}: {cnt:>3} {bar}") + return rates + + +def starved_cross_run(per_run_rates, threshold=0.20): + """§1: sessions starved ( 0.80: + sess_lucky[sid] += 1 + n_runs = len(per_run_rates) + consistently_starved = [sid for sid, c in sess_starved.items() if c == n_runs] + consistently_lucky = [sid for sid, c in sess_lucky.items() if c == n_runs] + return { + "n_runs": n_runs, + "consistently_starved": consistently_starved, + "consistently_lucky": consistently_lucky, + } + + +def session_size_comparison(rows, sids_a, sids_b, label_a="A", label_b="B"): + """Compare peak input_length of two session groups.""" + sess_max_input = defaultdict(int) + for r in rows: + sid = r.get("session_id") + ilen = r.get("input_length") or 0 + if sid is not None and ilen > sess_max_input[sid]: + sess_max_input[sid] = ilen + a_inputs = [sess_max_input[s] for s in sids_a if s in sess_max_input] + b_inputs = [sess_max_input[s] for s in sids_b if s in sess_max_input] + if a_inputs and b_inputs: + ratio = np.mean(a_inputs) / np.mean(b_inputs) + print(f"\n Cross-run starvation correlates with session size?") + print(f" consistently {label_a} (n={len(a_inputs)}): peak_input mean = {np.mean(a_inputs):.0f}") + print(f" consistently {label_b} (n={len(b_inputs)}): peak_input mean = {np.mean(b_inputs):.0f}") + print(f" {label_a}/{label_b} ratio = {ratio:.2f}x (ts=10 baseline was 1.98x)") + + +def per_d_balance(rows, label): + """§7: per-D load balance.""" + per_d = Counter() + for r in rows: + d = r.get("assigned_decode_node") or r.get("decode_node") + if d: + per_d[d] += 1 + if not per_d: + return + counts = list(per_d.values()) + spread = (max(counts) - min(counts)) / max(np.mean(counts), 1) + print(f"\n [{label}] per-D load: {dict(sorted(per_d.items()))}") + print(f" spread (max-min)/mean = {spread*100:.1f}% " + f"(ts=10 KVC 2P6D = ±26%, 8DP CA = ±10%)") + + +def execution_modes_table(rows, label): + """Show top execution modes.""" + ok = [r for r in rows if r.get("error") is None] + if not ok: + return + modes = Counter(r["execution_mode"] for r in ok) + print(f"\n [{label}] execution modes (n_ok={len(ok)}):") + for mode, cnt in modes.most_common(8): + mode_rows = [r for r in ok if r["execution_mode"] == mode] + lats = [r["latency_s"] for r in mode_rows if r.get("latency_s") is not None] + ttfts = [r["ttft_s"] for r in mode_rows if r.get("ttft_s") is not None] + if lats: + print(f" {mode:<55} {cnt:>5} ({cnt/len(ok)*100:>4.1f}%) " + f"lat p50={pct(lats,50):.3f}s p90={pct(lats,90):.3f}s ttft p50={pct(ttfts,50):.3f}s") + + +def lru_vs_errors(run_dir, label): + """§2: trim events vs KVTransferError per worker.""" + log_dir = run_dir / "logs" + if not log_dir.exists(): + return + print(f"\n [{label}] D-side LRU vs errors (from worker logs):") + print(f" {'worker':<14}{'trim':>8}{'KVTransferError':>20}{'peak_token_usage':>20}") + for log_file in sorted(log_dir.glob("decode-*.log")): + worker = log_file.stem + text = log_file.read_text(errors="ignore") + trim_count = len(re.findall(r"Trimmed decode session cache", text)) + err_count = len(re.findall(r"KVTransferError", text)) + usages = re.findall(r"token usage: ([\d.]+)", text) + peak = max((float(u) for u in usages), default=0.0) + print(f" {worker:<14}{trim_count:>8}{err_count:>20}{peak:>20.3f}") + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("--root", default="outputs/qwen3-30b-tp1-ts1-validation", + help="Sweep output root") + args = parser.parse_args() + + root = Path(args.root) + if not root.is_absolute(): + root = Path("/mnt/kzlin/workflow/pd-hybrid/agentic-pd-hybrid") / root + + # Load all available runs + stats = [] + rows_by_run = {} + for label in ("kvc_1p3d_run1", "kvc_1p3d_run2", "kvc_1p3d_run3", "dp4"): + m = root / f"{label}_metrics.jsonl" + s = root / f"{label}_summary.json" + if not m.exists() or not s.exists(): + print(f" [{label}] not yet available ({m.name})") + continue + rows = load_metrics(m) + summary = load_summary(s) + rows_by_run[label] = rows + stats.append(summarize_run(label, rows, summary)) + + if not stats: + print("No runs available yet.") + return + + # 1. Headline table + headline_table(stats) + + # 2. §1 session pinning per KVC run + per-D balance + execution modes + print("\n" + "=" * 110) + print("§1 / §7: SESSION PINNING + LOAD BALANCE") + print("=" * 110) + per_run_rates = [] + for label, rows in rows_by_run.items(): + if not label.startswith("kvc_"): + continue + pin = session_pinning(rows, label) + if pin: + print(f"\n [{label}] sessions={pin['n_sessions']} " + f"avg_distinct_D={pin['avg_distinct_D']:.2f} " + f"max_distinct_D={pin['max_distinct_D']} " + f"(ts=10 baseline avg=1.00 → 100% pin)") + rates = direct_to_d_distribution(rows, label) + per_run_rates.append(rates) + per_d_balance(rows, label) + execution_modes_table(rows, label) + + # 3. §1 cross-run starvation + if len(per_run_rates) >= 2: + print("\n" + "=" * 110) + print(f"§1 CROSS-RUN STARVATION (across {len(per_run_rates)} KVC runs)") + print("=" * 110) + cross = starved_cross_run(per_run_rates) + if cross: + n_starved = len(cross["consistently_starved"]) + n_lucky = len(cross["consistently_lucky"]) + print(f"\n Sessions starved (<20% direct-to-D) in all {cross['n_runs']} runs: {n_starved}") + print(f" Sessions lucky (>80% direct-to-D) in all {cross['n_runs']} runs: {n_lucky}") + print(f" (ts=10 baseline: 13/52 starved, 14/52 lucky — extreme bimodal)") + # session size comparison from run 1 + if "kvc_1p3d_run1" in rows_by_run and n_starved and n_lucky: + session_size_comparison(rows_by_run["kvc_1p3d_run1"], + cross["consistently_starved"], + cross["consistently_lucky"], + "starved", "lucky") + + # 4. §2 D-side LRU vs errors from raw logs + print("\n" + "=" * 110) + print("§2: D-SIDE LRU TRIM vs KVTransferError (from worker logs)") + print("=" * 110) + for label in rows_by_run: + if not label.startswith("kvc_"): + continue + # find the matching raw run dir + run_dirs = sorted(root.glob("kvcache-centric-*/")) + if not run_dirs: + continue + # naive: index matches run order; could be wrong if dirs got reordered + idx = int(label.split("run")[-1]) - 1 + if idx < len(run_dirs): + lru_vs_errors(run_dirs[idx], label) + + # 5. DP-only inspection + if "dp4" in rows_by_run: + print("\n" + "=" * 110) + print("4DP CA SANITY") + print("=" * 110) + per_d_balance(rows_by_run["dp4"], "dp4") + execution_modes_table(rows_by_run["dp4"], "dp4") + + +if __name__ == "__main__": + main() diff --git a/scripts/sweep_ts1_kvc_n3_plus_dp.sh b/scripts/sweep_ts1_kvc_n3_plus_dp.sh new file mode 100755 index 0000000..eead7e1 --- /dev/null +++ b/scripts/sweep_ts1_kvc_n3_plus_dp.sh @@ -0,0 +1,146 @@ +#!/bin/bash +# Time-scale=1 validation sweep, downscaled to 4 GPUs: +# - KVC v5 1P3D × N=3 (new data, validates §1/§2 structural claims at real timing) +# - 4-way DP cache-aware × 1 (sanity baseline at same scale + ts=1) +# +# Goal: per docs/AGENTIC_FIT_ANALYSIS_ZH.md §7 / TEAM_REPORT §2.6 — all v3-v6 KVC +# data was at time-scale=10 (inter-turn gap p50 = 0.25s, vs real 2.5s). This run +# tests whether the gap structurally reverses any conclusion. +# +# CONFIG NOTE: Original experiments used 8 GPUs (2P6D / 8-way DP). This host has +# only 4 H100s available, so we downscale proportionally to 1P3D / 4-way DP. +# Cross-compare against existing 2P6D ts=10 data is confounded by *both* +# time-scale and capacity. Internal comparison (1P3D KVC vs 4DP) at ts=1 is the +# clean signal. §5 (P-side imbalance) is NOT testable here — only 1 P. +# +# Capacity ratio: 3D × ~92K tok = 276K KV pool vs 52 sessions × ~50K peak input +# working set ≈ 1.5M → ~5.4× overload (vs 2.7× in original 2P6D). +# Pressure is HIGHER than original; partly offset by ts=1 letting D drain between turns. +# +# Output: +# outputs/qwen3-30b-tp1-ts1-validation/ +# ├── kvc_1p3d_run{1,2,3}_summary.json +# ├── kvc_1p3d_run{1,2,3}_metrics.jsonl +# ├── dp4_summary.json +# ├── dp4_metrics.jsonl +# └── kvcache-centric-... / pd-colo-kv-aware-... (raw run dirs) +# +# Estimated GPU time: KVC ts=1 ≈ 100-180 min/run × 3 = 5-9h +# DP ts=1 ≈ 100-120 min × 1 = ~2h +# Total = 7-11h +set -euo pipefail +cd "$(dirname "$0")/.." + +MODEL=/mnt/kzlin/workflow/pd-hybrid/simm-swe-bench/models/Qwen3-30B-A3B-Instruct-2507 +TRACE=outputs/qwen35-swebench-50sess.jsonl +OUTPUT=outputs/qwen3-30b-tp1-ts1-validation +VENV_PYTHON=.venv/bin/python +RESULTS_FILE=$OUTPUT/sweep_results.txt + +mkdir -p $OUTPUT + +log() { + echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a $RESULTS_FILE +} + +run_kvc_1p3d() { + local run_idx=$1 + local label="kvc_1p3d_run${run_idx}" + log "" + log "=== [KVC ${run_idx}/3] 1P3D KVC kv-aware Option D, time-scale=1 ===" + PYTHONPATH=src:third_party/sglang/python \ + $VENV_PYTHON -m agentic_pd_hybrid.cli benchmark-live \ + --trace $TRACE \ + --output-root $OUTPUT \ + --mechanism kvcache-centric \ + --policy kv-aware \ + --model-path $MODEL \ + --prefill-workers 1 --decode-workers 3 \ + --prefill-tp-size 1 --decode-tp-size 1 \ + --prefill-gpu-ids 0 --decode-gpu-ids 1,2,3 \ + --transfer-backend mooncake \ + --gpu-budget 4 \ + --time-scale 1 \ + --session-sample-rate 1.0 \ + --target-duration-s 100000 \ + --concurrency-limit 32 \ + --timeout-s 900 \ + --request-timeout-s 300 \ + --kvcache-admission-mode worker \ + --kvcache-seed-min-turn-id 1 \ + --kvcache-seed-max-inflight-decode -1 \ + --kvcache-prefill-backup-policy release-after-transfer \ + --kvcache-prefill-priority-eviction + + local run_dir=$(ls -td $OUTPUT/kvcache-centric-*/ 2>/dev/null | head -1) + log "=== [KVC ${run_idx}/3] $label COMPLETED ===" + if [ -f "$run_dir/request-metrics.jsonl.summary.json" ]; then + cp "$run_dir/request-metrics.jsonl.summary.json" "$OUTPUT/${label}_summary.json" + cp "$run_dir/request-metrics.jsonl" "$OUTPUT/${label}_metrics.jsonl" + local errs=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('error_count',0))") + log " errors = $errs" + cat "$run_dir/request-metrics.jsonl.summary.json" >> $RESULTS_FILE + echo "" >> $RESULTS_FILE + else + log "WARNING: no summary file in $run_dir" + fi +} + +run_dp4_sanity() { + local label="dp4" + log "" + log "=== [DP] 4-way DP cache-aware sanity, time-scale=1 ===" + PYTHONPATH=src:third_party/sglang/python \ + $VENV_PYTHON -m agentic_pd_hybrid.cli benchmark-live \ + --trace $TRACE \ + --output-root $OUTPUT \ + --mechanism pd-colo \ + --policy kv-aware \ + --model-path $MODEL \ + --prefill-workers 0 --decode-workers 0 \ + --direct-workers 4 --direct-tp-size 1 \ + --direct-gpu-ids 0,1,2,3 \ + --gpu-budget 4 \ + --time-scale 1 \ + --session-sample-rate 1.0 \ + --target-duration-s 100000 \ + --concurrency-limit 32 \ + --timeout-s 900 \ + --request-timeout-s 300 + + local run_dir=$(ls -td $OUTPUT/pd-colo-kv-aware-*/ 2>/dev/null | head -1) + log "=== [DP] $label COMPLETED ===" + if [ -f "$run_dir/request-metrics.jsonl.summary.json" ]; then + cp "$run_dir/request-metrics.jsonl.summary.json" "$OUTPUT/${label}_summary.json" + cp "$run_dir/request-metrics.jsonl" "$OUTPUT/${label}_metrics.jsonl" + local errs=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('error_count',0))") + log " errors = $errs" + cat "$run_dir/request-metrics.jsonl.summary.json" >> $RESULTS_FILE + echo "" >> $RESULTS_FILE + else + log "WARNING: no summary file in $run_dir" + fi +} + +log "=== TS=1 VALIDATION (4-GPU): KVC 1P3D × N=3 + 4DP × 1 ===" +log "Model: $MODEL" +log "Trace: $TRACE (4449 requests, 52 sessions)" +log "Goal: validate whether ts=10 was the main distortion in v3-v6 KVC vs DP" + +# KVC × 3 first (the new data we need); DP last (cheaper sanity at end) +for i in 1 2 3; do + run_kvc_1p3d $i +done + +run_dp4_sanity + +log "" +log "=== TS=1 SUMMARY ===" +for label in kvc_1p3d_run1 kvc_1p3d_run2 kvc_1p3d_run3 dp4; do + if [ -f "$OUTPUT/${label}_summary.json" ]; then + e=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('error_count',0))") + p50=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('latency_stats_s',{}).get('p50','n/a'))") + log " ${label}: errors=$e lat_p50=${p50}s" + fi +done +log "=== TS=1 ALL DONE ===" diff --git a/scripts/sweep_ts1_migration_v1.sh b/scripts/sweep_ts1_migration_v1.sh new file mode 100755 index 0000000..c81ce39 --- /dev/null +++ b/scripts/sweep_ts1_migration_v1.sh @@ -0,0 +1,65 @@ +#!/bin/bash +# Migration v1 validation: KVC 1P3D ts=1 with --kvcache-migration-reject-threshold=3 +# Compare against baseline outputs/qwen3-30b-tp1-ts1-validation/kvc_1p3d_run{1,2,3} +# (all of which had no migration — runs were structurally identical). +# +# Goal: verify §1 fix changes the categorical outcome — direct-to-D % up, +# fallback-session-not-resident % down, lat mean down. +# +# ts=1 is deterministic at the categorical level, so N=1 is sufficient +# (TEAM_REPORT §2.8 revised). +set -euo pipefail +cd "$(dirname "$0")/.." + +MODEL=/mnt/kzlin/workflow/pd-hybrid/simm-swe-bench/models/Qwen3-30B-A3B-Instruct-2507 +TRACE=outputs/qwen35-swebench-50sess.jsonl +OUTPUT=outputs/qwen3-30b-tp1-ts1-migration-v1 +VENV_PYTHON=.venv/bin/python +RESULTS_FILE=$OUTPUT/sweep_results.txt + +mkdir -p $OUTPUT + +log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a $RESULTS_FILE; } + +log "=== TS=1 MIGRATION v1: KVC 1P3D --kvcache-migration-reject-threshold=3 ===" +log "Baseline reference: outputs/qwen3-30b-tp1-ts1-validation/kvc_1p3d_run1 (errors=5, lat mean=1.574s, direct-to-D=42.8%)" + +label=kvc_1p3d_migration_run1 +log "" +log "=== [migration v1] starting ===" +PYTHONPATH=src:third_party/sglang/python \ +$VENV_PYTHON -m agentic_pd_hybrid.cli benchmark-live \ + --trace $TRACE \ + --output-root $OUTPUT \ + --mechanism kvcache-centric \ + --policy kv-aware \ + --model-path $MODEL \ + --prefill-workers 1 --decode-workers 3 \ + --prefill-tp-size 1 --decode-tp-size 1 \ + --prefill-gpu-ids 0 --decode-gpu-ids 1,2,3 \ + --transfer-backend mooncake \ + --gpu-budget 4 \ + --time-scale 1 \ + --session-sample-rate 1.0 \ + --target-duration-s 100000 \ + --concurrency-limit 32 \ + --timeout-s 900 \ + --request-timeout-s 300 \ + --kvcache-admission-mode worker \ + --kvcache-seed-min-turn-id 1 \ + --kvcache-seed-max-inflight-decode -1 \ + --kvcache-prefill-backup-policy release-after-transfer \ + --kvcache-prefill-priority-eviction \ + --kvcache-migration-reject-threshold 3 + +run_dir=$(ls -td $OUTPUT/kvcache-centric-*/ 2>/dev/null | head -1) +log "=== [migration v1] $label COMPLETED ===" +if [ -f "$run_dir/request-metrics.jsonl.summary.json" ]; then + cp "$run_dir/request-metrics.jsonl.summary.json" "$OUTPUT/${label}_summary.json" + cp "$run_dir/request-metrics.jsonl" "$OUTPUT/${label}_metrics.jsonl" + errs=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('error_count',0))") + p50=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('latency_stats_s',{}).get('p50',0))") + log " errors=$errs lat_p50=${p50}s" + cat "$run_dir/request-metrics.jsonl.summary.json" >> $RESULTS_FILE +fi +log "=== migration v1 DONE ===" diff --git a/scripts/sweep_ts1_migration_v2.sh b/scripts/sweep_ts1_migration_v2.sh new file mode 100755 index 0000000..01f5098 --- /dev/null +++ b/scripts/sweep_ts1_migration_v2.sh @@ -0,0 +1,76 @@ +#!/bin/bash +# Migration v2 validation: KVC 1P3D ts=1 with BOTH: +# (1) reset-on-success blacklist decay (replay.py code change) +# (2) --kvcache-direct-max-uncached-tokens 8192 (was 2048 default) +# +# v1 results (kvc_1p3d_migration_run1) showed: +# - lat mean WORSE +11.7%, TTFT mean WORSE +71.3% — thrashing tax +# - direct-to-D rate UP +10.5pp (42.8 → 53.3%) +# - Fallback breakdown surprise: 41.3% are 'real-large-append' (>2048 tok), +# NOT 'session-not-resident' as we hypothesized +# +# v2 design (REFACTOR_PLAN_V1 + MIGRATION_V1_FINDINGS): +# (1) reset-on-success: clear (sess,D) reject counter on successful direct-to-D +# — eliminates blacklist-permanence bug → kills thrashing +# (2) bump direct-append threshold 2048 → 8192: lets more large-append turns +# go direct-to-D instead of fall through to seed (which often rejects) +set -euo pipefail +cd "$(dirname "$0")/.." + +MODEL=/mnt/kzlin/workflow/pd-hybrid/simm-swe-bench/models/Qwen3-30B-A3B-Instruct-2507 +TRACE=outputs/qwen35-swebench-50sess.jsonl +OUTPUT=outputs/qwen3-30b-tp1-ts1-migration-v2 +VENV_PYTHON=.venv/bin/python +RESULTS_FILE=$OUTPUT/sweep_results.txt + +mkdir -p $OUTPUT + +log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a $RESULTS_FILE; } + +log "=== TS=1 MIGRATION v2: reset-on-success + threshold=8192 ===" +log "Baselines:" +log " baseline (no migration): kvc_1p3d_run1 errors=5 lat_p50=0.811s ttft_p50=0.124s direct=42.8%" +log " v1 (migration permanent): kvc_1p3d_migration_run1 errors=6 lat_p50=0.773s ttft_p50=0.057s direct=53.3% lat_mean=1.758s" +log " 4DP ts=1: errors=0 lat_p50=0.659s ttft_p50=0.090s lat_mean=1.443s" +log "Goal: kill thrashing tax (lat_mean ≤ 1.5s, p99 ≤ 9s) while preserving v1's direct-to-D gains." + +label=kvc_1p3d_migration_v2_run1 +log "" +log "=== [migration v2] starting ===" +PYTHONPATH=src:third_party/sglang/python \ +$VENV_PYTHON -m agentic_pd_hybrid.cli benchmark-live \ + --trace $TRACE \ + --output-root $OUTPUT \ + --mechanism kvcache-centric \ + --policy kv-aware \ + --model-path $MODEL \ + --prefill-workers 1 --decode-workers 3 \ + --prefill-tp-size 1 --decode-tp-size 1 \ + --prefill-gpu-ids 0 --decode-gpu-ids 1,2,3 \ + --transfer-backend mooncake \ + --gpu-budget 4 \ + --time-scale 1 \ + --session-sample-rate 1.0 \ + --target-duration-s 100000 \ + --concurrency-limit 32 \ + --timeout-s 900 \ + --request-timeout-s 300 \ + --kvcache-admission-mode worker \ + --kvcache-seed-min-turn-id 1 \ + --kvcache-seed-max-inflight-decode -1 \ + --kvcache-prefill-backup-policy release-after-transfer \ + --kvcache-prefill-priority-eviction \ + --kvcache-migration-reject-threshold 3 \ + --kvcache-direct-max-uncached-tokens 8192 + +run_dir=$(ls -td $OUTPUT/kvcache-centric-*/ 2>/dev/null | head -1) +log "=== [migration v2] $label COMPLETED ===" +if [ -f "$run_dir/request-metrics.jsonl.summary.json" ]; then + cp "$run_dir/request-metrics.jsonl.summary.json" "$OUTPUT/${label}_summary.json" + cp "$run_dir/request-metrics.jsonl" "$OUTPUT/${label}_metrics.jsonl" + errs=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('error_count',0))") + p50=$($VENV_PYTHON -c "import json; d=json.load(open('$OUTPUT/${label}_summary.json')); print(d.get('latency_stats_s',{}).get('p50',0))") + log " errors=$errs lat_p50=${p50}s" + cat "$run_dir/request-metrics.jsonl.summary.json" >> $RESULTS_FILE +fi +log "=== migration v2 DONE ===" diff --git a/src/agentic_pd_hybrid/benchmark.py b/src/agentic_pd_hybrid/benchmark.py index c43de8d..055247c 100644 --- a/src/agentic_pd_hybrid/benchmark.py +++ b/src/agentic_pd_hybrid/benchmark.py @@ -47,6 +47,7 @@ class BenchmarkConfig: pool_poll_include_sessions: bool = True enable_backpressure: bool = False backpressure_max_pause_s: float = 2.0 + kvcache_migration_reject_threshold: int = 3 sample_profile: str = "default" min_initial_input_tokens: int | None = None max_initial_input_tokens: int | None = None @@ -198,6 +199,7 @@ def run_live_benchmark(config: BenchmarkConfig) -> BenchmarkArtifacts: pool_poll_include_sessions=config.pool_poll_include_sessions, enable_backpressure=config.enable_backpressure, backpressure_max_pause_s=config.backpressure_max_pause_s, + kvcache_migration_reject_threshold=config.kvcache_migration_reject_threshold, ) if config.request_timeout_s is not None: replay_config = replace( @@ -258,6 +260,7 @@ def run_live_benchmark(config: BenchmarkConfig) -> BenchmarkArtifacts: "pool_poll_include_sessions": config.pool_poll_include_sessions, "enable_backpressure": config.enable_backpressure, "backpressure_max_pause_s": config.backpressure_max_pause_s, + "kvcache_migration_reject_threshold": config.kvcache_migration_reject_threshold, "sample_profile": config.sample_profile, "min_initial_input_tokens": config.min_initial_input_tokens, "max_initial_input_tokens": config.max_initial_input_tokens, diff --git a/src/agentic_pd_hybrid/cli.py b/src/agentic_pd_hybrid/cli.py index c3d0858..14616f2 100644 --- a/src/agentic_pd_hybrid/cli.py +++ b/src/agentic_pd_hybrid/cli.py @@ -260,6 +260,16 @@ def main() -> None: default=2.0, help="Cap on per-request backpressure sleep, regardless of D hint.", ) + replay.add_argument( + "--kvcache-migration-reject-threshold", + type=int, + default=3, + help=( + "Per-(session, D) admission-reject count after which KvAwarePolicy " + "skips that D for the session (forces migration). 0 disables. " + "See REFACTOR_PLAN_V1 §6.2 / TEAM_REPORT §2.1." + ), + ) sample = subparsers.add_parser( "sample-sessions", @@ -501,6 +511,16 @@ def main() -> None: default=2.0, help="Cap on per-request backpressure sleep, regardless of D hint.", ) + benchmark.add_argument( + "--kvcache-migration-reject-threshold", + type=int, + default=3, + help=( + "Per-(session, D) admission-reject count after which KvAwarePolicy " + "skips that D for the session (forces migration). 0 disables. " + "See REFACTOR_PLAN_V1 §6.2 / TEAM_REPORT §2.1." + ), + ) benchmark.add_argument( "--sample-profile", choices=["default", "small-append"], @@ -586,6 +606,7 @@ def main() -> None: pool_poll_include_sessions=not args.pool_poll_no_sessions, enable_backpressure=args.enable_backpressure, backpressure_max_pause_s=args.backpressure_max_pause_s, + kvcache_migration_reject_threshold=args.kvcache_migration_reject_threshold, ) results = asyncio.run(replay_trace(config)) print( @@ -732,6 +753,7 @@ def main() -> None: pool_poll_include_sessions=not args.pool_poll_no_sessions, enable_backpressure=args.enable_backpressure, backpressure_max_pause_s=args.backpressure_max_pause_s, + kvcache_migration_reject_threshold=args.kvcache_migration_reject_threshold, sample_profile=args.sample_profile, min_initial_input_tokens=args.min_initial_input_tokens, max_initial_input_tokens=args.max_initial_input_tokens, diff --git a/src/agentic_pd_hybrid/policies.py b/src/agentic_pd_hybrid/policies.py index db77bb3..162bf84 100644 --- a/src/agentic_pd_hybrid/policies.py +++ b/src/agentic_pd_hybrid/policies.py @@ -44,6 +44,10 @@ class RoutingState: inflight_decode: Counter[str] = field(default_factory=Counter) decode_assignment_counts: Counter[str] = field(default_factory=Counter) decode_resident_blocks: dict[str, set[int]] = field(default_factory=dict) + # Migration support: per-(session_id, decode_worker_id) admission reject counter. + # KvAwarePolicy uses this to skip D's that have repeatedly rejected this session + # (avoids the structural starvation observed in TEAM_REPORT §2.1). + session_d_rejects: Counter[tuple[str, str]] = field(default_factory=Counter) @classmethod def create(cls, topology: SingleNodeTopology) -> "RoutingState": @@ -66,6 +70,12 @@ class RoutingState: self.decode_cursor += 1 return worker.worker_id + def record_admission_reject(self, session_id: str, decode_worker_id: str) -> int: + """Increment per-(session, D) rejection counter. Returns new count.""" + key = (session_id, decode_worker_id) + self.session_d_rejects[key] += 1 + return self.session_d_rejects[key] + def finish(self, request: TraceRequest, decision: RoutingDecision) -> None: session = self.session_state.setdefault(request.session_id, SessionRouteState()) session.last_decode_worker = decision.decode_worker_id @@ -146,6 +156,11 @@ class StickyDecodePolicy: class KvAwarePolicy: name: str = "kv-aware" sticky_bonus: int = 1 + # Session migration: when (session, D) has been rejected this many times, + # skip D entirely for this session (force migration to another D). + # 0 disables the mechanism. Default 3 picked empirically to allow brief + # transient saturation without panicking, but to reroute persistent starvation. + migration_reject_threshold: int = 3 def select( self, @@ -158,8 +173,19 @@ class KvAwarePolicy: session = state.session_state.get(request.session_id) best_decode_worker_id: str | None = None - best_score: tuple[int, int, int] | None = None + best_score: tuple[int, int, int, int] | None = None + candidates_considered = 0 for worker in topology.route_workers: + # Migration: skip workers that have rejected this session too many times. + # If all candidates get filtered (degenerate case), fall through to + # un-filtered selection below. + if self.migration_reject_threshold > 0: + rejects = state.session_d_rejects.get( + (request.session_id, worker.worker_id), 0 + ) + if rejects >= self.migration_reject_threshold: + continue + candidates_considered += 1 overlap = _overlap_blocks(request, state, worker.worker_id) sticky = int(session is not None and session.last_decode_worker == worker.worker_id) inflight_penalty = -state.inflight_decode.get(worker.worker_id, 0) @@ -174,6 +200,16 @@ class KvAwarePolicy: best_score = score best_decode_worker_id = worker.worker_id + # Degenerate fallback: every D was filtered. Pick the least-rejected D. + if best_decode_worker_id is None: + best_decode_worker_id = min( + (w.worker_id for w in topology.route_workers), + key=lambda wid: state.session_d_rejects.get( + (request.session_id, wid), 0 + ), + ) + best_score = (0, 0, 0, 0) + assert best_decode_worker_id is not None reuse_expected = bool(best_score and best_score[0] > 0) return _build_decision( @@ -187,14 +223,14 @@ class KvAwarePolicy: ) -def create_policy(name: str) -> RoutingPolicy: +def create_policy(name: str, *, migration_reject_threshold: int = 3) -> RoutingPolicy: normalized = name.strip().lower() if normalized == "default": return DefaultPolicy() if normalized == "sticky": return StickyDecodePolicy() if normalized in {"kv-aware", "kv_aware", "kv"}: - return KvAwarePolicy() + return KvAwarePolicy(migration_reject_threshold=migration_reject_threshold) raise ValueError(f"Unsupported policy: {name}") diff --git a/src/agentic_pd_hybrid/replay.py b/src/agentic_pd_hybrid/replay.py index f8b51ce..9e065ef 100644 --- a/src/agentic_pd_hybrid/replay.py +++ b/src/agentic_pd_hybrid/replay.py @@ -106,6 +106,11 @@ class ReplayConfig: pool_poll_include_sessions: bool = True enable_backpressure: bool = False backpressure_max_pause_s: float = 2.0 + # Session migration via per-(sess, D) admission reject memory. + # When a session has been admission-rejected this many times on a given D, + # KvAwarePolicy skips that D for the session (forcing migration). Default 3. + # Set 0 to disable. See REFACTOR_PLAN_V1 §6.2. + kvcache_migration_reject_threshold: int = 3 structural_log_dir: Path | None = None @@ -190,7 +195,10 @@ async def replay_trace(config: ReplayConfig) -> list[RequestMetrics]: if turn_count > 1 ), ) - policy = create_policy(config.policy_name) + policy = create_policy( + config.policy_name, + migration_reject_threshold=config.kvcache_migration_reject_threshold, + ) state = RoutingState.create(config.topology) state_lock = asyncio.Lock() semaphore = asyncio.Semaphore(config.concurrency_limit) @@ -350,6 +358,22 @@ async def _run_request( async with state_lock: state.finish(request, decision) + # Migration feedback: if this request was forced into a fallback path + # because the chosen D rejected admission, record the (session, D) + # rejection so KvAwarePolicy can migrate this session next turn. + if _is_admission_rejection_mode(execution.execution_mode): + state.record_admission_reject( + request.session_id, + decision.decode_worker_id, + ) + # Reset-on-success: a successful direct-to-D path proves D-X can + # currently serve this session — clear the cumulative reject counter + # so that brief past saturation doesn't permanently blacklist the D. + # (MIGRATION_V1_FINDINGS §4.1: blacklist-permanence bug fix.) + elif execution.execution_mode == "kvcache-direct-to-d-session": + state.session_d_rejects[ + (request.session_id, decision.decode_worker_id) + ] = 0 return RequestMetrics.from_decision( request, @@ -1349,6 +1373,49 @@ def _is_stale_decode_session_error(exc: Exception) -> bool: ) +# execution_mode substrings that signal D-side admission rejected this request. +# Used by _run_request to update state.session_d_rejects so KvAwarePolicy can +# migrate persistently-starved sessions to a different D next turn. +_ADMISSION_REJECTION_SUBSTRINGS = ( + "session-cap", + "no-d-capacity", + "d-backpressure", +) + + +def _is_admission_rejection_mode(execution_mode: str) -> bool: + return any(token in execution_mode for token in _ADMISSION_REJECTION_SUBSTRINGS) + + +def _fallthrough_reason( + *, + request: TraceRequest, + config: ReplayConfig, + decision, + direct_append_length: int | None, + direct_session_reused: bool, + direct_session_reset: bool, +) -> str: + """Classify why a turn-2+ KVC request fell through to the seed/large-append branch. + + Returns a short label suffix used in execution_mode strings to replace the + misleading 'large-append' label (TEAM_REPORT §2.7). In particular, + 'session-not-resident' is the §1 starvation signature — direct_session_reused + is False because the session was never opened on the policy-chosen D. + """ + if not direct_session_reused: + return "session-not-resident" + if direct_session_reset: + return "session-was-evicted" + if direct_append_length is None: + return "no-direct-info" + if direct_append_length > config.kvcache_direct_max_uncached_tokens: + return "real-large-append" + if not _should_bypass_prefill(request=request, config=config, decision=decision): + return "policy-no-bypass" + return "other-large-append" + + def _dynamic_decode_headroom_tokens( *, residency: DecodeResidencyState, @@ -2510,6 +2577,17 @@ async def _execute_request( decode_residency=decode_residency, ) + # TEAM_REPORT §2.7: 'large-append' is misleading — most fallthroughs are + # actually 'session-not-resident-on-pinned-D' (§1 starvation). Classify + # the real reason and embed it in the execution_mode label. + fallthrough = _fallthrough_reason( + request=request, + config=config, + decision=decision, + direct_append_length=direct_append_length, + direct_session_reused=direct_session_reused, + direct_session_reset=direct_session_reset, + ) seed_filter_reason = _seed_filter_reason( request=request, config=config, @@ -2521,7 +2599,7 @@ async def _execute_request( client=client, config=config, decision=decision, - execution_mode=f"pd-router-fallback-large-append-{seed_filter_reason}", + execution_mode=f"pd-router-fallback-{fallthrough}-{seed_filter_reason}", decode_residency=decode_residency, ) async with direct_session_lock: @@ -2566,7 +2644,7 @@ async def _execute_request( client=client, config=config, decision=decision, - execution_mode="pd-router-fallback-large-append-session-cap", + execution_mode=f"pd-router-fallback-{fallthrough}-session-cap", decode_residency=decode_residency, ) if can_seed: @@ -2582,23 +2660,27 @@ async def _execute_request( decode_residency=decode_residency, reserved_tokens=reserved_tokens, execution_mode=( - "pd-router-large-append-reseed" + f"pd-router-{fallthrough}-reseed" + _eviction_suffix( evicted_sessions, prefill_backed_evictions, ) ), ) + # Preserve seed_reason in the label so migration feedback fires for + # 'd-no-space' / 'd-*-backpressure' (matched via _is_admission_rejection_mode). + if _is_decode_backpressure_reason(seed_reason): + mode_label = f"pd-router-fallback-{fallthrough}-d-backpressure" + elif seed_reason == "d-no-space": + mode_label = f"pd-router-fallback-{fallthrough}-no-d-capacity" + else: + mode_label = f"pd-router-fallback-{fallthrough}" return await _invoke_plain_router( request=request, client=client, config=config, decision=decision, - execution_mode=( - "pd-router-fallback-d-backpressure" - if _is_decode_backpressure_reason(seed_reason) - else "pd-router-fallback-large-append" - ), + execution_mode=mode_label, decode_residency=decode_residency, )