docs: archive deprecated docs to docs/archive/, drop E1 from onboarding
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
263
docs/archive/KVCACHE_CENTRIC_PROGRESS_ZH.md
Normal file
263
docs/archive/KVCACHE_CENTRIC_PROGRESS_ZH.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# KV-cache centric P/D routing 当前进展
|
||||
|
||||
本文记录当前原型在 SGLang xPyD 上围绕 session-aware / KV-cache-aware P/D routing 的实现、实验结果和阶段性结论。实验日期为 2026-04-24 至 2026-04-25。
|
||||
|
||||
## 目标和核心假设
|
||||
|
||||
目标是在单机 8 GPU xPyD 环境中验证：针对 agentic coding workload，session-aware / KV-cache-aware P/D routing 是否能提升端到端延迟。
|
||||
|
||||
当前重点假设：
|
||||
|
||||
1. 在 PD-disaggregation 下，P 节点和 D 节点可能同时保留同一个 session 的 prefix KV，形成 P/D duplicate。
|
||||
2. 如果预测某个 session 后续会 direct-to-D，那么 P 侧在 radix/prefix cache eviction 时可以优先淘汰这部分 prefix cache。
|
||||
3. 这样可以给 P 节点释放 cache 空间，提高 P 侧 prefix cache reuse。
|
||||
4. 如果 P 侧 reuse 提升后 D 侧开始成为瓶颈，可以通过增加 xPyD 中 D 的配比，也就是增加 y，缓解 decode 侧压力。
|
||||
|
||||
实验结果表明：第 2、3 点在 P cache 高压 workload 下成立；第 4 点只部分成立，因为瓶颈会从 decode prealloc 转移到 P->D transfer/bootstrap pipeline。
|
||||
|
||||
## 已实现机制
|
||||
|
||||
### 1. Trace profile 和 paired comparison
|
||||
|
||||
新增 `agentic_pd_hybrid profile` 子命令和 `src/agentic_pd_hybrid/profile.py`。
|
||||
|
||||
能力：
|
||||
|
||||
- 统计 trace 的 session 数、turn2+ 数、append tokens、overlap ratio、direct-to-D eligible turn。
|
||||
- 对比 baseline/candidate metrics，输出 paired E2E latency delta。
|
||||
- 用于解释 micro-benchmark 与 Ali filtered workload 的差异。
|
||||
|
||||
### 2. P 侧 priority eviction 支持
|
||||
|
||||
修改 SGLang server args，允许：
|
||||
|
||||
```bash
|
||||
--radix-eviction-policy priority
|
||||
```
|
||||
|
||||
router/replay 支持内部字段：
|
||||
|
||||
- `smg_prefill_priority`
|
||||
- `smg_decode_priority`
|
||||
|
||||
router 会将内部字段剥离，只把标准 `priority` 分别传给 P/D backend。这样可以让 direct-to-D predicted session 在 P 侧使用更低优先级，例如 `-100`，普通请求使用 `100`。
|
||||
|
||||
### 3. Kvcache seed/direct admission 控制
|
||||
|
||||
新增多种 seed/reseed 过滤：
|
||||
|
||||
- `kvcache_seed_max_resident_tokens`
|
||||
- `kvcache_seed_max_output_tokens`
|
||||
- `kvcache_seed_min_turn_id`
|
||||
- `kvcache_seed_only_multiturn_sessions`
|
||||
- `kvcache_seed_max_inflight_decode`
|
||||
|
||||
新增 P streaming session backup 策略：
|
||||
|
||||
- `release-after-transfer`：P->D transfer 后释放 P 侧 session backup。
|
||||
- `capacity-backup`：容量允许时保留 P 侧 backup。
|
||||
|
||||
当前主实验使用 `release-after-transfer`。
|
||||
|
||||
### 4. 稳定性修复
|
||||
|
||||
之前 worker-admission 实验会在 replay 尾部卡住，不写出 metrics。原因是 benchmark 的长 `timeout_s=3600` 同时用于：
|
||||
|
||||
- SGLang stack 启动等待
|
||||
- replay client 单请求
|
||||
- router 到 P/D backend 的单请求
|
||||
|
||||
修复后新增：
|
||||
|
||||
- `BenchmarkConfig.request_timeout_s`
|
||||
- CLI `benchmark-live --request-timeout-s`
|
||||
- launch plan `router_request_timeout_s`
|
||||
|
||||
当前做法：
|
||||
|
||||
- `timeout_s=3600` 继续用于 SGLang 启动和整体 stack 等待。
|
||||
- `request_timeout_s=180` 用于 replay client 和 router 到 P/D backend 的单请求。
|
||||
- control-plane probe/open/close session 使用 2s timeout，fail closed。
|
||||
|
||||
修复效果：worker-admission 从“尾部卡死不落盘”变为“卡住请求记录为 ReadTimeout，整轮实验完成并写 metrics”。
|
||||
|
||||
## 关键实验结果
|
||||
|
||||
### P cache pressure 下 priority eviction 是否提升 P 侧 reuse
|
||||
|
||||
配置：2P2D，P `--max-total-tokens 90000`，micro workload 316 requests / 58 sessions。
|
||||
|
||||
| 配置 | ok/total | mean E2E | p99 | request cached tokens | P log cached tokens | P new-token total |
|
||||
|---|---:|---:|---:|---:|---:|---:|
|
||||
| LRU | 314/316 | 28.171s | 43.409s | 8.204M | 7.783M | 2.236M |
|
||||
| Priority | 314/316 | 28.165s | 41.935s | 8.401M | 7.981M | 2.039M |
|
||||
|
||||
结论：
|
||||
|
||||
- 在 P cache eviction 高频触发时，priority eviction 确实提高 P 侧 prefix reuse。
|
||||
- cached tokens 增加约 197k，new prefill tokens 减少约 197k。
|
||||
- 但 mean E2E 基本不变，说明性能瓶颈转移到 D decode/transfer。
|
||||
|
||||
### 增加 D 配比前的 D 侧瓶颈证据
|
||||
|
||||
2P2D priority pressure 下：
|
||||
|
||||
- decode `#queue-req`：max/mean/p90 = 0/0/0
|
||||
- decode token usage：max 0.98，mean 0.842，p90 0.96
|
||||
- decode `#transfer-req`：max 7，mean 4.61，p90 7
|
||||
- decode `#prealloc-req`：max 21，mean 11.6，p90 21
|
||||
|
||||
解释：
|
||||
|
||||
- D 侧不是普通 waiting queue 堆积。
|
||||
- 真正压力在 token usage、transfer queue 和 prealloc queue。
|
||||
|
||||
### D scaling：router admission 旧结果
|
||||
|
||||
| 配置 | ok/total | mean | p50 | p90 | p99 | error |
|
||||
|---|---:|---:|---:|---:|---:|---:|
|
||||
| 2P2D | 314/316 | 28.165s | 30.576s | 38.267s | 41.935s | 2 |
|
||||
| 2P3D | 290/316 | 29.915s | 31.428s | 40.856s | 45.964s | 26 |
|
||||
| 2P4D | 285/316 | 30.566s | 32.823s | 40.566s | 44.838s | 31 |
|
||||
|
||||
结论：
|
||||
|
||||
- 直接增加 D 不稳定。
|
||||
- 2P3D/2P4D 的错误主要来自 `kvcache-centric` seed/direct 路径。
|
||||
- 日志显示 decode 侧出现 `WaitingForInput` timeout 和 `KVTransferError`。
|
||||
|
||||
### D scaling：worker admission + request timeout 修复后
|
||||
|
||||
配置：P `--max-total-tokens 90000`，priority eviction，worker admission，`request_timeout_s=180`。
|
||||
|
||||
| 配置 | ok/total | mean | p50 | p90 | p99 | error |
|
||||
|---|---:|---:|---:|---:|---:|---:|
|
||||
| 2P2D | 313/316 | 29.838s | 30.742s | 39.641s | 52.506s | 3 |
|
||||
| 2P3D | 299/316 | 29.349s | 30.569s | 42.161s | 46.113s | 17 |
|
||||
| 2P4D | 312/316 | 26.442s | 27.759s | 38.197s | 47.970s | 4 |
|
||||
|
||||
对应 decode log 摘要：
|
||||
|
||||
| 配置 | decode usage mean | decode transfer mean | decode prealloc mean |
|
||||
|---|---:|---:|---:|
|
||||
| 2P2D | 0.859 | 4.86 | 11.3 |
|
||||
| 2P3D | 0.877 | 5.70 | 6.92 |
|
||||
| 2P4D | 0.809 | 5.31 | 3.46 |
|
||||
|
||||
结论：
|
||||
|
||||
- 2P4D + worker admission + request timeout 是当前最好的 D scaling 配置。
|
||||
- 相比旧 2P4D，成功率从 285/316 提升到 312/316，mean 从 30.566s 降到 26.442s。
|
||||
- 但 p99 仍未稳定改善，tail 仍由 P->D transfer/bootstrap timeout 主导。
|
||||
- 2P3D 不稳定，错误 17 个，不适合作为当前推荐配置。
|
||||
|
||||
### 与默认 PD-disaggregation 的同配置对比
|
||||
|
||||
为了避免和旧 2P2D/no-pressure 基线混比，补跑了同一 workload、同一 2P4D、同一 P `--max-total-tokens 90000`、同一 `time_scale=50`、同一 `request_timeout_s=180` 的默认 PD-disaggregation 基线。
|
||||
|
||||
| 策略 | ok/total | mean | p50 | p90 | p99 | cached total | direct-to-D |
|
||||
|---|---:|---:|---:|---:|---:|---:|---:|
|
||||
| 默认 PD-disaggregation 2P4D | 316/316 | 29.210s | 28.940s | 47.434s | 52.605s | 8.165M | 0 |
|
||||
| KVC 2P4D latency-best | 312/316 | 26.442s | 27.759s | 38.197s | 47.970s | 7.882M | 11 |
|
||||
| KVC 2P4D seed-min2 | 316/316 | 26.729s | 25.840s | 43.589s | 50.426s | 8.337M | 3 |
|
||||
|
||||
结论：
|
||||
|
||||
- 如果只看成功请求延迟，KVC 2P4D latency-best 相比默认 PD：
|
||||
- mean 改善约 9.5%；
|
||||
- p50 改善约 4.1%；
|
||||
- p90 改善约 19.5%；
|
||||
- p99 改善约 8.8%。
|
||||
- 但 latency-best 有 4 个 `ReadTimeout`，全部来自 turn1 大 seed 的 P->D transfer/bootstrap timeout。
|
||||
- `kvcache_seed_min_turn_id=2` 可以消除这些错误，达到 316/316 成功，同时 mean/p50/p90/p99 仍然优于默认 PD。
|
||||
- 因此当前推荐分成两档：
|
||||
- 追求最低 mean/p90：使用 KVC 2P4D latency-best。
|
||||
- 追求稳定性：使用 KVC 2P4D seed-min2。
|
||||
|
||||
### 进一步优化尝试
|
||||
|
||||
在当前最佳配置基础上尝试了三个优化方向：
|
||||
|
||||
| 策略 | ok/total | mean | p50 | p90 | p99 | 结论 |
|
||||
|---|---:|---:|---:|---:|---:|---|
|
||||
| KVC 2P4D latency-best | 312/316 | 26.442s | 27.759s | 38.197s | 47.970s | 延迟最优，但有 4 个 turn1 seed timeout |
|
||||
| transfer-cap4 | 304/316 | 27.961s | 29.785s | 38.730s | 45.192s | 不可取，实时 transfer queue snapshot 滞后，错误更多 |
|
||||
| disable-failed-session | 285/316 | 29.179s | 30.878s | 42.794s | 46.411s | 不可取，失败 session 降级会放大后端异常状态 |
|
||||
| seed-min2 | 316/316 | 26.729s | 25.840s | 43.589s | 50.426s | 稳定性最优 |
|
||||
| inflight0 | 316/316 | 29.497s | 31.186s | 43.498s | 48.022s | 太保守，几乎关闭 KVC 收益 |
|
||||
|
||||
从错误明细看，latency-best 的 4 个错误全部是 turn1 seed timeout，每个都是约 1250 KV blocks 的大 seed。`seed-min2` 跳过 turn1 seed 后，错误全部消失，说明当前主要稳定性问题是启动阶段 seed 风暴，而不是后续 direct append 本身。
|
||||
|
||||
transfer-cap4 没有效果，说明仅依赖 D worker 的实时 `decode_transfer_queue_reqs` 不够；并发请求可能同时读取到尚可的 snapshot，然后一起进入 P->D transfer，导致 backlog 在 admission 后形成。
|
||||
|
||||
## Ali filtered 当前状态
|
||||
|
||||
Ali filtered small-append trace：
|
||||
|
||||
- 81 requests
|
||||
- 28 sessions
|
||||
- 53 turn2+
|
||||
- max input 18901
|
||||
- max output 1925
|
||||
- span 5414s
|
||||
|
||||
PD baseline：
|
||||
|
||||
- ok 81/81
|
||||
- mean 9.072s
|
||||
- p50 7.086s
|
||||
- p90 21.761s
|
||||
- p99 26.813s
|
||||
|
||||
Kvcache-centric 在 Ali filtered 上曾出现 58-67 个 router 200 后挂住、无 metrics 的问题。当前 request timeout 和 control-plane timeout 修复后，应重新跑 Ali filtered；在未重跑前，不把 Ali filtered 纳入最终性能结论。
|
||||
|
||||
## 当前结论
|
||||
|
||||
1. kvcache centric 可以提高 KV reuse，但需要满足 workload 条件：
|
||||
- session 有多 turn；
|
||||
- turn2+ append 较小；
|
||||
- prefix overlap 高；
|
||||
- P 侧 cache 有 eviction pressure；
|
||||
- D 侧 seed/direct admission 不把 transfer pipeline 打爆。
|
||||
|
||||
2. 不适合的 workload：
|
||||
- 单 turn 或 session 间隔过长；
|
||||
- turn2+ append 很大，direct-to-D 不能省掉多少 prefill；
|
||||
- prefix overlap 低；
|
||||
- P cache 没有 eviction pressure；
|
||||
- D transfer/prealloc 已经高压。
|
||||
|
||||
3. 用户关于 P/D duplicate 的假设部分成立：
|
||||
- 如果 D session 已经 resident，P 侧对应 streaming session backup 可以视为 duplicate。
|
||||
- `release-after-transfer` 可以避免长期保留 P/D 两份 session KV。
|
||||
- priority eviction 进一步让 P 在必须 eviction 时优先淘汰 direct-to-D predicted session prefix。
|
||||
|
||||
4. 但当前机制还没有完全解决性能问题：
|
||||
- P 侧 reuse 提升后，E2E 不一定改善。
|
||||
- 主要原因是 D 侧 transfer/bootstrap pipeline 成为瓶颈。
|
||||
- 增加 D 可以降低 prealloc，但不能自动降低 transfer backlog。
|
||||
- 当前同配置下 KVC 已经可以优于默认 PD，但必须在 latency-best 和 stable 两种策略之间取舍。
|
||||
|
||||
## 下一步优化方向
|
||||
|
||||
1. transfer-aware admission：
|
||||
- seed/direct 不只看 D token capacity，也要看 `decode_transfer_queue_reqs`、`decode_prealloc_queue_reqs`、`decode_retracted_queue_reqs`。
|
||||
- 当 transfer queue 高时，应该主动走 PD fallback。
|
||||
- 当前实验显示，单纯使用实时 transfer queue threshold 不够，需要配合本地 reservation。
|
||||
|
||||
2. per-D transfer budget：
|
||||
- 对每个 D 设置 seed/reseed 并发上限。
|
||||
- 不能只按 session residency 或 token headroom 判断。
|
||||
- 特别要限制 turn1 大 seed 的并发，避免启动阶段 seed 风暴。
|
||||
|
||||
3. P/D ratio 联合调度：
|
||||
- 2P4D 当前最好，但 P queue 也随 D 增加而上升。
|
||||
- 后续需要测试 3P3D、3P4D、4P4D 等组合，确认 P transfer source 是否成为瓶颈。
|
||||
|
||||
4. Ali filtered 重跑：
|
||||
- 使用 request timeout 修复后的版本重新跑 Ali filtered。
|
||||
- 如果仍然没有收益，需要按 session gap、append size、overlap ratio 分桶分析。
|
||||
|
||||
5. 更严格的成功率指标：
|
||||
- 当前不能只看成功请求的 mean/p90。
|
||||
- 必须同时报告 ok/total、timeout/error 类型和 tail latency。
|
||||
Reference in New Issue
Block a user