gahow/agentic-pd-hybrid
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: archive deprecated docs to docs/archive/, drop E1 from onboarding

Browse Source 
Two cleanups:

1. Drop "E1: naive 1P3D default" experiment from the onboarding manual.
   GPU hours are precious; naive 1P3D + policy=default has near-certain
   loss on multi-turn cache hit (it's round-robin without prefix awareness),
   so the comparison doesn't add information vs E1=naive 1P3D kv-aware.
   The new manifest has only 2 runs: E1 (naive 1P3D kv-aware) + E2 (KVC
   v2 + RDMA). Run-time budget drops from 16.5h serial to 11h serial /
   5.5h parallel. Updated:
   - §0 TL;DR ("3 组" -> "2 组")
   - §2 H1 hypothesis (drop "default and kv-aware each one" -> just kv-aware)
   - §3.1 experiment matrix (3 rows -> 2 rows + rationale for the drop)
   - §3.2 startup config (drop E1 default section, renumber E2/E3 -> E1/E2)
   - §6 decision table + expected-range table
   - §7 FAQ ("3 个 E1-E3" -> "2 个 E1-E2")
   - §9 deliverables

2. Move 8 deprecated docs to docs/archive/:
     AGENTIC_FIT_ANALYSIS_ZH.md         (ts=10 era analysis; superseded)
     STRUCTURAL_VALIDATION_REPORT_ZH.md (ts=10 era validation; superseded)
     KVC_DEBUG_JOURNEY_V1_TO_V5.md      (v1-v5 sweep process notes)
     V5_PROFILE_INVESTIGATION_ZH.md     (v5 1Hz polling investigation)
     REFACTOR_PLAN_ZH.md                (v0 plan; superseded by V1)
     KVCACHE_CENTRIC_PROGRESS_ZH.md     (earliest 2026-04-27 progress)
     SWEBENCH_EXPERIMENT_PROGRESS.md    (early SWE trace setup)
     SWEBENCH_EXPERIMENT_RESULTS.md     (early SWE result snapshot)

   All cross-references in active docs (V2_DEEP_ANALYSIS / V2_RESULTS /
   REFACTOR_PLAN_V1 / TEAM_REPORT / ONBOARDING) rewritten from
   `docs/FOO.md` to `docs/archive/FOO.md` via sed pass.

   Added `docs/archive/README.md` explaining what each archived doc is
   and when (if ever) to reopen it. Designed so a new reader hitting
   the archive dir immediately knows it's not required reading.

After this commit the active docs in docs/ are 9 files (down from 17),
which should make the onboarding doc's "Level 1 / Level 2 / Level 3"
classification self-evident.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
kzlin
2026-05-11 22:40:35 +08:00
parent 5a2fb8799c
commit 7590e55189
14 changed files with 83 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/ONBOARDING_NEXT_AGENT_ZH.md
View File

@@ -11,7 +11,7 @@
1. 你接手的是 **agentic-pd-hybrid**——SGLang xPyD 基础上加 session-aware KVCache 层的 LLM serving 框架，目标是在多轮长 context coding agent workload 上比 vanilla DP 快
2. v2（迁移机制 + threshold tuning）已经在 SWE-Bench 50sess trace ts=1 上**击败 4DP CA** 6/8 个 latency/TTFT 指标，但 **TTFT p99 输 3×**（1.28s vs 0.43s）
3. 上一个 agent 已诊断出 TTFT p99 长尾的根因——8.3% 请求走 reseed 慢路径，每次需要 P 重算 prefill + mooncake transfer = 3-7s
4. **你的任务**：在有 GPU + IB RDMA 的环境上跑 3 组对照实验，验证 (a) naive 1P3D 拓扑相对 KVC 的边际贡献、(b) 启用真 RDMA 后 KVC v2 的 TTFT p99 是否能压到 ~0.7s 量级
4. **你的任务**：在有 GPU + IB RDMA 的环境上跑 2 组对照实验，验证 (a) naive 1P3D + kv-aware 相对 KVC 的边际贡献、(b) 启用真 RDMA 后 KVC v2 的 TTFT p99 是否能压到 ~0.7s 量级
5. 跑完结果 push 到 `outputs/`，主 agent 会拉下来更新 paper draft 和 future-work 文档
---
@@ -41,12 +41,12 @@
### Level 3：归档（**别读**，是历史包袱）
- `docs/AGENTIC_FIT_ANALYSIS_ZH.md`：ts=10 时代的早期分析，结论已被 ts=1 数据 supersede
- `docs/STRUCTURAL_VALIDATION_REPORT_ZH.md`：ts=10 数据下的结构性验证，同上
- `docs/KVC_DEBUG_JOURNEY_V1_TO_V5.md`：v1-v5 调优 sweep 的过程笔记，知道有这个文件就行
- `docs/V5_PROFILE_INVESTIGATION_ZH.md`：profile 调查，已 supersede
- `docs/REFACTOR_PLAN_ZH.md`：v0 重构计划，已被 V1 supersede
- `docs/SWEBENCH_EXPERIMENT_*.md`：早期实验日志
- `docs/archive/AGENTIC_FIT_ANALYSIS_ZH.md`：ts=10 时代的早期分析，结论已被 ts=1 数据 supersede
- `docs/archive/STRUCTURAL_VALIDATION_REPORT_ZH.md`：ts=10 数据下的结构性验证，同上
- `docs/archive/KVC_DEBUG_JOURNEY_V1_TO_V5.md`：v1-v5 调优 sweep 的过程笔记，知道有这个文件就行
- `docs/archive/V5_PROFILE_INVESTIGATION_ZH.md`：profile 调查，已 supersede
- `docs/archive/REFACTOR_PLAN_ZH.md`：v0 重构计划，已被 V1 supersede
- `docs/archive/SWEBENCH_EXPERIMENT_*.md`：早期实验日志
### Level 0：本手册的"姐妹"文档（**读这个之前你应该已经在看本文了**）
@@ -77,7 +77,7 @@ Branch: kvc-debug-journey-v1-to-v4 = 主分支（v2 已合入）
| # | 假设 | 验证方法 | 预期结果 |
|---|---|---|---|
| H1 | KVC v2 相对 4DP 的胜利不只是来自 1P3D 拓扑——KVC 层（admission / migration / direct-to-D）也有显著贡献 | 跑 naive 1P3D ts=1 N=1（vanilla SGLang pd-disagg，policy=default 和 kv-aware 各一次）作为中间对照 | naive 1P3D 应该处于 KVC v2 和 4DP 之间。如果它 ≈ KVC v2 → 胜利来自拓扑而非 KVC 层；如果 ≈ 4DP → 胜利来自 KVC 层 |
| H1 | KVC v2 相对 4DP 的胜利不只是来自 1P3D 拓扑——KVC 层（admission / migration / direct-to-D）也有显著贡献 | 跑 naive 1P3D + policy=kv-aware ts=1 N=1（vanilla SGLang pd-disagg，无 KVC 层）作为中间对照 | naive 1P3D 应该处于 KVC v2 和 4DP 之间。如果它 ≈ KVC v2 → 胜利来自拓扑而非 KVC 层；如果 ≈ 4DP → 胜利来自 KVC 层 |
| H2 | 启用真 RDMA 把 mooncake P→D transfer 从 1.5-4s 压到 200-400ms，TTFT p99 从 1.28s 降到 ~0.7s | 在 v2 sweep 加 `--force-rdma --ib-device mlx5_0`，跑同 trace 同 ts=1 | TTFT p99 应该 ~0.5-0.8s 区间。如果没改变 → mooncake 实际没用 RDMA / 配置错误；如果降到 ~0.3s → 我们对 transfer 段贡献的估计偏低 |
| H3 | 即使启用 RDMA，TTFT p99 仍然输 DP（因为 re-prefill 段不动） | 同 H2 实验结果 | 应该看到 TTFT p99 ~0.7s > DP 0.43s。如果 ≤ DP → 我们对 re-prefill 段成本的估计错了，可能整个 slow path 理论需要重审 |
@@ -87,40 +87,37 @@ Branch: kvc-debug-journey-v1-to-v4 = 主分支（v2 已合入）
### 3.1 实验矩阵（按 ROI 排序）
GPU hour 珍贵，砍掉了原计划的 naive 1P3D + policy=default baseline（low-ROI——naive 1P3D 用 default policy 在多轮 cache 命中上几乎必败，没必要拿这个对比当 H1 的对照点）。最终保留 2 个 run：
| # | 配置 | GPU | mechanism | policy | RDMA | 预期时长 | 目的 |
|---|---|---:|---|---|---|---:|---|
| **E1** | naive 1P3D default | 4 | pd-disaggregation | default | 不影响 | ~5.5h | H1 baseline 1 |
| **E2** | naive 1P3D kv-aware | 4 | pd-disaggregation | kv-aware | 不影响 | ~5.5h | H1 baseline 2 |
| **E3** | KVC v2 + RDMA | 4 | kvcache-centric | kv-aware | **on** | ~5.5h | H2/H3 |
| **E1** | naive 1P3D kv-aware | 4 | pd-disaggregation | kv-aware | **on** | ~5.5h | H1：分离"1P3D + kv-aware policy"贡献 vs "KVC 层（admission/migration/direct-to-D）"贡献 |
| **E2** | KVC v2 + RDMA | 4 | kvcache-centric | kv-aware | **on** | ~5.5h | H2/H3：验证 RDMA 能把 TTFT p99 从 1.28s 压到 ~0.7s |
三个 run 串行约 16.5h，并行用两组 GPU 可压到 11h。
两个 run 串行约 11h，并行用两组 GPU 可压到 ~5.5h。
### 3.2 启动配置：详细 flag 清单
参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版。三个新 sweep 脚本的关键 flag：
参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版。两个新 sweep 脚本的关键 flag：
#### E1: naive 1P3D default
#### E1: naive 1P3D kv-aware
```bash
python -m agentic_pd_hybrid \
--mechanism pd-disaggregation \
--policy default \
--policy kv-aware \
--topology-pd 1P3D \
--transfer-backend mooncake \
--force-rdma --ib-device mlx5_0 \ # ← 别忘了 RDMA（即使是 naive 也用 RDMA，单独测拓扑而非 transport）
--force-rdma --ib-device mlx5_0 \ # ← 单独测拓扑+policy 而非 transport，必须开 RDMA 才能跟 E2 公平
--trace outputs/qwen35-swebench-50sess.jsonl \
--time-scale 1.0 \
--concurrency 32 \
--request-timeout-s 300 \
--max-input-len 87811 \ # ← 拉齐到 DP 限，消除 abort 数量不对等
--output-root outputs/qwen3-30b-tp1-ts1-naive-1p3d-default
--output-root outputs/qwen3-30b-tp1-ts1-naive-1p3d-kvaware
```
#### E2: naive 1P3D kv-aware
同上，只改：`--policy kv-aware` 和 `--output-root` 路径
#### E3: KVC v2 + RDMA
#### E2: KVC v2 + RDMA
参考 `scripts/sweep_ts1_migration_v2.sh`，**只加两个 flag**：
@@ -242,22 +239,22 @@ git -c user.email=YOUR_EMAIL -c user.name=YOUR_NAME commit -m "..."
☐ cache_hit_request_count + total_cached_tokens (推 cache hit rate)
```
### 三组对照实验跑完后看以下"决定性数字"
### 两组对照实验跑完后看以下"决定性数字"
| 比较 | 关键看点 | 决策 |
|---|---|---|
| naive 1P3D default vs naive 1P3D kv-aware | TTFT p50 差距 | 量化"policy=kv-aware 单独带来的收益" |
| naive 1P3D kv-aware vs KVC v2 | TTFT p50/p99、direct-to-D 占比 | 量化"KVC 层（admission/migration/direct-to-D）在 kv-aware 之上的额外收益" |
| KVC v2 (TCP) vs KVC v2 + RDMA | TTFT p99、reseed mode 的耗时（execution_mode == reseed 的 ttft_s p50） | 验证 H2/H3：RDMA 救多少 transfer 段 |
| E1 (naive 1P3D kv-aware) vs E2 (KVC v2 + RDMA) | TTFT p50/p99、direct-to-D 占比 | 量化"KVC 层（admission/migration/direct-to-D）在 kv-aware 之上的额外收益"（H1） |
| KVC v2 (TCP, 历史 v2 run) vs E2 (KVC v2 + RDMA) | TTFT p99、reseed mode 的耗时（execution_mode == reseed 的 ttft_s p50） | 验证 H2/H3：RDMA 救多少 transfer 段 |
| E1 (naive 1P3D kv-aware) vs DP 4w（历史 ts=1 baseline）| 全部 latency / TTFT 指标 | 间接锚定"拓扑差异 + kv-aware policy"的天花板 |
### 期待的数字范围（如果实验顺利）
| 配置 | lat p50 | lat p99 | TTFT p50 | TTFT p99 | direct-to-D % |
|---|---:|---:|---:|---:|---:|
| naive 1P3D default | ~0.85s | ~9-12s | ~0.30s | ~1.5-2s | N/A |
| naive 1P3D kv-aware | ~0.75s | ~8-10s | ~0.20s | ~0.8-1.2s | N/A |
| KVC v2 + RDMA | ~0.58s | ~7-8s | ~0.04s | **~0.5-0.8s** | ~91% |
| (参考) DP 4w | 0.67s | 8.4s | 0.09s | 0.43s | N/A |
| **E1** naive 1P3D kv-aware | ~0.75s | ~8-10s | ~0.20s | ~0.8-1.2s | N/A |
| **E2** KVC v2 + RDMA | ~0.58s | ~7-8s | ~0.04s | **~0.5-0.8s** | ~91% |
| (参考) KVC v2 + TCP（历史） | 0.58s | 8.7s | 0.04s | 1.29s | 91.6% |
| (参考) DP 4w（历史 ts=1） | 0.67s | 8.4s | 0.09s | 0.43s | N/A |
**如果你看到的数字偏离这个范围 ≥ 2×**，先停下来检查配置（环境验证 §3.3 那些项目），不是写报告。
@@ -290,7 +287,7 @@ A: 仓库里 `outputs/qwen3-30b-exps/pd-disaggregation-default-20260427T062616Z/
**Q: 我想跑别的对照（更大 trace / 更多 GPU / 真实 RDMA 跨节点）。**
A: 先把上面 3 个 E1-E3 跑完。这 3 个是论文核心 contribution 的 ablation，不能跳。其它对照（更长 trace、8 GPU 2P6D、真跨节点 RDMA）见 `V2_DEEP_ANALYSIS_ZH §7.3`，作为 follow-up。
A: 先把上面 2 个 E1-E2 跑完。这 2 个是论文核心 contribution 的 ablation，不能跳。其它对照（更长 trace、8 GPU 2P6D、真跨节点 RDMA、补 naive 1P3D + policy=default）见 `V2_DEEP_ANALYSIS_ZH §7.3`，作为 follow-up。
**Q: 跑完后想自动出对比图。**
@@ -318,14 +315,13 @@ A: 看 `src/agentic_pd_hybrid/metrics.py` 里 `RequestMetrics` dataclass。所
## 9. 主 agent 留给你的两个具体期待
1. **三组对照实验跑完后**，在新 commit message 里给我以下数字（用 `recompute_summary.py` 输出格式）：
1. **两组对照实验跑完后**，在新 commit message 里给我以下数字（用 `recompute_summary.py` 输出格式）：
```
E1 naive 1P3D default: lat={mean,p50,p90,p99} ttft={mean,p50,p90,p99} fail_count
E2 naive 1P3D kv-aware: 同上
E3 KVC v2 + RDMA: 同上 + reseed-mode 的 ttft p50/p99 分开
E1 naive 1P3D kv-aware: lat={mean,p50,p90,p99} ttft={mean,p50,p90,p99} fail_count
E2 KVC v2 + RDMA: 同上 + reseed-mode 的 ttft p50/p99 分开
```
2. **跑 E3 时收集 reseed 路径的实测耗时分布**：
2. **跑 E2 时收集 reseed 路径的实测耗时分布**：
```
pd-router-d-session-reseed 这个 execution_mode 的 ttft_s 分布
并把 P→D mooncake transfer 时长 vs P 端 re-prefill 时长 单独拉出