agentic-pd-hybrid/docs/REFACTOR_PLAN_V1_ZH.md

# 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`。