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）

当前评分（无容量项）：

score = (
    overlap + sticky * self.sticky_bonus,
    sticky,
    inflight_penalty,
    assignment_penalty,
)

提议改为：

# 新增：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。