Gahow Wang
fc445df0ad
Captures the full review of bugs, fake/half-implemented features, dead branches, and quality gaps found in cache_aware_proxy.py, replayer, and the shell scripts. Each item has file:line, problem, fix, and verification steps so any contributor can pick it up directly.
769 lines
28 KiB
Markdown
769 lines
28 KiB
Markdown
# Repo 修复指南 (FIXES.md)
|
||
|
||
> 本文档对应 2026-05-23 的 repo review。每条 issue 自包含：定位、动机、复现/验证、改法。按严重度从高到低排列，建议**自上而下**逐项修复，每条修完独立提交一个 commit。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [B1. 删除死状态 `_inst_cumulative_tokens`](#b1)
|
||
- [B2. 修复 replayer CLI 与 shell 脚本不一致（阻断实验）](#b2)
|
||
- [B3. 处理 PD-sep `--fire-and-forget` 损坏路径](#b3)
|
||
- [B4. 实现或移除 H4 cache-ratio gate](#b4)
|
||
- [B5. 修复 `_percentile` off-by-one](#b5)
|
||
- [B6. 统一 `bench.sh` 的模型路径](#b6)
|
||
- [M1. `cached_blocks` 替换策略改为真正的 LRU](#m1)
|
||
- [M2. P 候选选择避开 `active_p_offloads`](#m2)
|
||
- [M3. 把 `MAX_OFFLOAD_INFLIGHT` 暴露为 CLI 参数](#m3)
|
||
- [M4. `session_affinity` 在 combined / pd-sep 之间命名空间隔离](#m4)
|
||
- [M5. fallback 路径 client 断流时的资源泄漏](#m5)
|
||
- [M6. `_send_prefill_async` 与同步路径的核算不一致](#m6)
|
||
- [D1. 移除 `_send_prefill_async` 与 `--fire-and-forget`](#d1)
|
||
- [D2. 删除/归档 `run_benchmark.sh` 与 `run_experiments.sh`](#d2)
|
||
- [D3. 归档历史一次性 `analyze_*.py` / `compare_*.py`](#d3)
|
||
- [D4. 修正 `compute_roofline.py` 的硬编码 trace 路径](#d4)
|
||
- [D5. `HEAVY_THRESHOLD` / `OVERLOAD_FACTOR` 改读 args](#d5)
|
||
- [S1. 给 `replayer/metrics.py` 与 cost-model 加单元测试](#s1)
|
||
- [S2. 给 vLLM patch 加 import-time 校验](#s2)
|
||
- [S3. REPORT.md 加 errata block](#s3)
|
||
- [验收清单](#验收清单)
|
||
|
||
---
|
||
|
||
<a id="b1"></a>
|
||
## B1. 删除死状态 `_inst_cumulative_tokens`
|
||
|
||
**严重度**: High（误导性死代码）。
|
||
|
||
**定位**: `scripts/cache_aware_proxy.py:76, 102–104, 125`。
|
||
|
||
**问题**:
|
||
- `_inst_cumulative_tokens` 是 module-level list，每次 turn 1 路由后 `+= input_length`。
|
||
- 全 repo grep 这个名字只有写入点，没有任何读取。
|
||
|
||
**验证**:
|
||
```bash
|
||
grep -rn "_inst_cumulative_tokens" /home/gahow/phd/agentic-kv
|
||
# 只应该看到 cache_aware_proxy.py 自己的 5 行；如有其它读取者，先确认意图再删
|
||
```
|
||
|
||
**改法**:
|
||
1. 删除 `cache_aware_proxy.py:76` 行 `_inst_cumulative_tokens: list[int] = []`。
|
||
2. 删除 `pick_instance` 内的 `global _inst_cumulative_tokens` 与 `:103-104` 的初始化。
|
||
3. 删除 `:125` 的累加。
|
||
4. 不需要替代实现——load 计算用 `inst.ongoing_tokens`，session 粘性用 `affinity` dict。
|
||
|
||
---
|
||
|
||
<a id="b2"></a>
|
||
## B2. 修复 replayer CLI 与 shell 脚本不一致（最高优先级）
|
||
|
||
**严重度**: Critical（阻断 REPORT 自己规定的 next-step 实验）。
|
||
|
||
**定位**:
|
||
- `replayer/__main__.py:14-26`: argparse 当前**只**接受 `--trace --output --endpoint --model --concurrency-limit --request-timeout --request-limit -v`。
|
||
- `scripts/run_benchmark.sh:32, 70-71`: 仍传 `--time-scale` 和 `--max-inflight-sessions`。
|
||
- `scripts/run_experiments.sh:58-59`: 同样问题。
|
||
- `REPORT.md:521, 541`: 把 `--max-inflight-sessions 64+` 列为 next step。
|
||
|
||
**问题**:
|
||
- 跑这两个 shell 脚本会立刻 `SystemExit(2)`：unrecognized arguments。
|
||
- 报告里的"下一步实验"无法执行。
|
||
|
||
**决策**: 两条路线，**二选一**，本 repo 推荐路线 A。
|
||
|
||
### 路线 A（推荐）：恢复 `--max-inflight-sessions`，保持 `--time-scale` 移除
|
||
|
||
理由：REPORT §3.6 已经论证 trace-driven replay（无时间压缩）是正确的；但高并发实验需要一个并发上限旋钮。把 `--max-inflight-sessions` 重新加回来，语义为"全局活跃 session 数上限的 semaphore"。
|
||
|
||
**改法**:
|
||
|
||
1. 修改 `replayer/__main__.py`：
|
||
```python
|
||
p.add_argument("--max-inflight-sessions", type=int, default=None,
|
||
help="Cap concurrent active sessions (None = unlimited; "
|
||
"use to simulate higher-than-trace concurrency)")
|
||
```
|
||
并把它塞进 `ReplayConfig`：
|
||
```python
|
||
config = ReplayConfig(
|
||
...
|
||
max_inflight_sessions=args.max_inflight_sessions,
|
||
)
|
||
```
|
||
|
||
2. 修改 `replayer/replay.py` 的 `ReplayConfig` 与 dispatch 逻辑：
|
||
- 在 `ReplayConfig` 里加 `max_inflight_sessions: int | None = None`。
|
||
- 在 `replay_trace` 里：若 `max_inflight_sessions` 不为 None，创建 `asyncio.Semaphore(max_inflight_sessions)`，每个 session 任务 `async with sem:` 包住整段 session 重放（不是单个 request）。
|
||
- 若为 None，保持现有行为（无上限，仅 `concurrency_limit` 是 HTTP 层 safety semaphore）。
|
||
|
||
3. 删除 shell 脚本里的 `--time-scale`：
|
||
- `scripts/run_benchmark.sh:32, 70`: 删除 `--time-scale` 选项与传参。
|
||
- `scripts/run_experiments.sh:58`: 同上。
|
||
|
||
4. 验证：
|
||
```bash
|
||
python -m replayer --trace traces/w600_r0.0015_st30.jsonl \
|
||
--output /tmp/x.jsonl --endpoint http://localhost:9090 \
|
||
--max-inflight-sessions 64
|
||
# 不应再报 unrecognized arguments
|
||
```
|
||
|
||
5. 同步更新 `REPORT.md:430` 的 CLI 表格（删 `--time-scale`，保留 `--max-inflight-sessions`）。
|
||
|
||
### 路线 B：彻底删掉这两个参数 + 删 shell 脚本
|
||
|
||
如果不打算再跑高并发实验，则：
|
||
1. 删 `scripts/run_benchmark.sh` 和 `scripts/run_experiments.sh`（与 D2 合并）。
|
||
2. 修订 `REPORT.md:521, 541, 530` 中提到 `--max-inflight-sessions` 的全部段落，明确说"该参数已删除，对应实验留给后续工作"。
|
||
|
||
**任选一条，但不能保留现状。**
|
||
|
||
---
|
||
|
||
<a id="b3"></a>
|
||
## B3. PD-sep `--fire-and-forget` 路径损坏
|
||
|
||
**严重度**: High（reachable-but-broken）。
|
||
|
||
**定位**: `scripts/cache_aware_proxy.py:552-554, 570-573, 507-521`。
|
||
|
||
**问题**:
|
||
- `_handle_pd_sep` 在 `--fire-and-forget` 时 `asyncio.create_task(_send_prefill_async(...))` **不等 P 完成**。
|
||
- 紧接 `:570-583` 立刻发起 D 端 decode，decode 携带 `remote_bootstrap_addr` + `remote_engine_id` + `transfer_id`。
|
||
- 但 P 端此时可能尚未注册 `transfer_id`，Mooncake 拉取失败 → D 端 502。
|
||
- 此外 `_send_prefill_async:507-521` 在异常分支只 `breakdown["prefill_error"] = True`，错误不会传递给 client。
|
||
|
||
**改法**:
|
||
|
||
如果按 [D1](#d1) 直接删，那这一条自动消失。
|
||
否则按以下方式修：
|
||
|
||
1. 在 `_send_prefill_async` 里加一个 `asyncio.Event`：
|
||
```python
|
||
async def _send_prefill_async(p_inst, api, prefill_data, p_headers,
|
||
token_ids, input_length, breakdown,
|
||
ready: asyncio.Event):
|
||
try:
|
||
resp = await p_inst.client.post(api, json=prefill_data, headers=p_headers)
|
||
resp.raise_for_status()
|
||
await resp.aclose()
|
||
breakdown["t_prefill_done"] = _time.monotonic()
|
||
p_inst.record_prefix(token_ids)
|
||
except Exception as e:
|
||
breakdown["t_prefill_done"] = _time.monotonic()
|
||
breakdown["prefill_error"] = str(e)
|
||
finally:
|
||
p_inst.ongoing_tokens -= input_length
|
||
ready.set()
|
||
```
|
||
|
||
2. 在 `_handle_pd_sep` 里，发 decode 之前 `await ready.wait()`（带超时），保证 transfer_id 已注册：
|
||
```python
|
||
ready = asyncio.Event()
|
||
asyncio.create_task(_send_prefill_async(..., ready=ready))
|
||
try:
|
||
await asyncio.wait_for(ready.wait(), timeout=PREFILL_TIMEOUT_S)
|
||
except asyncio.TimeoutError:
|
||
raise HTTPException(502, "Prefill not registered in time")
|
||
if "prefill_error" in breakdown:
|
||
raise HTTPException(502, breakdown["prefill_error"])
|
||
```
|
||
|
||
3. 这样语义其实就跟同步等待几乎一样了——更佳决策是按 [D1](#d1) 直接删。
|
||
|
||
---
|
||
|
||
<a id="b4"></a>
|
||
## B4. 实现或移除 H4 cache-ratio gate
|
||
|
||
**严重度**: High（design doc 与代码不一致 / fake feature）。
|
||
|
||
**定位**: `scripts/cache_aware_proxy.py:288, 308`；`analysis/elastic_hypotheses.md`；`scripts/run_h4_cache_gate.sh`。
|
||
|
||
**问题**:
|
||
- `cache_ratio = cache_hit / max(input_length, 1)` 计算后**仅写入 breakdown**，没有任何分支根据它决策。
|
||
- `analysis/elastic_hypotheses.md` 与 `run_h4_cache_gate.sh` 都假定"当 cache_ratio < 阈值时不 offload"；目前完全无效。
|
||
|
||
**改法（推荐：实现）**:
|
||
|
||
1. 在 `cache_aware_proxy.py` 顶部加常量与 CLI：
|
||
```python
|
||
CACHE_GATE_RATIO = 0.3 # default; overridden by --cache-gate-ratio
|
||
```
|
||
```python
|
||
p.add_argument("--cache-gate-ratio", type=float, default=0.3,
|
||
help="Min cache_hit/input ratio to allow offload "
|
||
"(0.0 disables gate, 1.0 disables offload)")
|
||
```
|
||
并在 `__main__` 里 `CACHE_GATE_RATIO = global_args.cache_gate_ratio`（参考 [D5](#d5)，最好不要用 module-level 赋值，直接读 args）。
|
||
|
||
2. 在 `:312` 之前加 gate：
|
||
```python
|
||
if cache_ratio < CACHE_GATE_RATIO:
|
||
offload_reason = "cache_gate_%.2f" % cache_ratio
|
||
elif current_offloads >= MAX_OFFLOAD_INFLIGHT:
|
||
offload_reason = "cap_reached_%d" % current_offloads
|
||
elif offload_cost < colocated_cost:
|
||
use_offload = True
|
||
offload_reason = "cost_model_%.1fvs%.1f" % (offload_cost, colocated_cost)
|
||
else:
|
||
offload_reason = "colocated_cheaper_%.1fvs%.1f" % (colocated_cost, offload_cost)
|
||
```
|
||
|
||
3. 把 `--cache-gate-ratio` 加到 `scripts/bench.sh` 与 `scripts/launch_phase1_ps.sh` 的 proxy 启动行（默认值 0.3，elastic 模式生效）。
|
||
|
||
**或者（不实现）**: 把 `:288` 的 `cache_ratio` 计算与写入删除，并在 `analysis/elastic_hypotheses.md` 顶部加一句"H4 gate 设计未落地，结论待验证"。
|
||
|
||
---
|
||
|
||
<a id="b5"></a>
|
||
## B5. `_percentile` off-by-one
|
||
|
||
**严重度**: Medium（影响所有 summary 数据）。
|
||
|
||
**定位**: `replayer/metrics.py:103-107`。
|
||
|
||
**问题**:
|
||
```python
|
||
idx = round((len(sorted_vals) - 1) * pct)
|
||
```
|
||
对 len=100, pct=0.5 → `round(49.5) = 50`（Python banker's rounding 偶向偶）。
|
||
对 len=2, pct=0.5 → `round(0.5) = 0`，但 `round(1.5) = 2` 等场景不稳定；银行家舍入让结果在偶数 idx 上偏倚。
|
||
所有 p50 在偶数 sample 上偏向上中位。
|
||
|
||
**改法**:
|
||
|
||
替换为线性插值（与 numpy.percentile 默认一致）：
|
||
|
||
```python
|
||
def _percentile(sorted_vals: list[float], pct: float) -> float:
|
||
n = len(sorted_vals)
|
||
if n == 1:
|
||
return sorted_vals[0]
|
||
rank = pct * (n - 1)
|
||
lo = int(rank)
|
||
hi = min(lo + 1, n - 1)
|
||
frac = rank - lo
|
||
return sorted_vals[lo] * (1 - frac) + sorted_vals[hi] * frac
|
||
```
|
||
|
||
**验证**:
|
||
```python
|
||
# 单测：见 S1
|
||
assert _percentile([1, 2, 3, 4], 0.5) == 2.5
|
||
assert _percentile([1, 2], 0.5) == 1.5
|
||
assert _percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 0.9) == 9.1
|
||
```
|
||
|
||
---
|
||
|
||
<a id="b6"></a>
|
||
## B6. 统一 `bench.sh` 的模型路径
|
||
|
||
**严重度**: Medium（新机器跑直接挂）。
|
||
|
||
**定位**: `scripts/bench.sh:23`。
|
||
|
||
**问题**:
|
||
- `bench.sh:23`: `MODEL="${MODEL_PATH:-/home/admin/cpfs/wjh/models/Qwen/Qwen3-Coder-30B-A3B-Instruct}"`
|
||
- 其它脚本 (`launch_vllm.sh`、`launch_elastic_p2p.sh`) 与 `TODO.md`：`$HOME/models/Qwen/Qwen3-Coder-30B-A3B-Instruct`。
|
||
|
||
**改法**:
|
||
|
||
把 `bench.sh:23` 的默认值改为：
|
||
```bash
|
||
MODEL="${MODEL_PATH:-$HOME/models/Qwen/Qwen3-Coder-30B-A3B-Instruct}"
|
||
```
|
||
|
||
并 `grep -rn "/home/admin/cpfs"` 检查整 repo 没有其它残留：
|
||
```bash
|
||
grep -rn "/home/admin/cpfs" /home/gahow/phd/agentic-kv
|
||
```
|
||
若有则一并替换为 `$HOME/models/...`。
|
||
|
||
---
|
||
|
||
<a id="m1"></a>
|
||
## M1. `cached_blocks` 替换策略改为真正的 LRU
|
||
|
||
**严重度**: Medium（router 估算 cache_hit 与真实 vLLM APC 长期偏差）。
|
||
|
||
**定位**: `scripts/cache_aware_proxy.py:71-72`（`record_prefix`）。
|
||
|
||
**问题**:
|
||
```python
|
||
if len(self.cached_blocks) > 200000:
|
||
self.cached_blocks = set(list(self.cached_blocks)[-100000:])
|
||
```
|
||
- `set` 迭代顺序在 CPython 不保证插入序，"取后 100k"等价于随机丢一半。
|
||
- 这与 vLLM 内部 LRU 完全不一致，是 §3.6 提到的 24pp APC gap 的部分来源。
|
||
|
||
**改法**:
|
||
|
||
把 `cached_blocks: set[int]` 改成 `OrderedDict[int, None]` 充当 LRU：
|
||
|
||
```python
|
||
from collections import OrderedDict
|
||
|
||
class InstanceState:
|
||
def __init__(self, ...):
|
||
...
|
||
self.cached_blocks: OrderedDict[int, None] = OrderedDict()
|
||
self.cache_capacity = 200000 # blocks; tune with --cache-capacity-blocks
|
||
|
||
def estimate_cache_hit(self, token_ids):
|
||
if not token_ids or len(token_ids) < BLOCK_SIZE:
|
||
return 0
|
||
hit = 0
|
||
for i in range(0, len(token_ids) - BLOCK_SIZE + 1, BLOCK_SIZE):
|
||
bh = hash(tuple(token_ids[i:i + BLOCK_SIZE]))
|
||
if bh in self.cached_blocks:
|
||
self.cached_blocks.move_to_end(bh) # LRU touch
|
||
hit += BLOCK_SIZE
|
||
else:
|
||
break
|
||
return hit
|
||
|
||
def record_prefix(self, token_ids):
|
||
if not token_ids:
|
||
return
|
||
for i in range(0, len(token_ids) - BLOCK_SIZE + 1, BLOCK_SIZE):
|
||
bh = hash(tuple(token_ids[i:i + BLOCK_SIZE]))
|
||
if bh in self.cached_blocks:
|
||
self.cached_blocks.move_to_end(bh)
|
||
else:
|
||
self.cached_blocks[bh] = None
|
||
if len(self.cached_blocks) > self.cache_capacity:
|
||
self.cached_blocks.popitem(last=False) # evict LRU
|
||
```
|
||
|
||
**进阶**: 容量应根据真实 KV cache 大小标定（vLLM 启动后 `total_blocks * block_size`），不要写死 200000。可以：
|
||
- 加 `--cache-capacity-blocks` CLI（默认 200000）；
|
||
- 或者从 vLLM `/metrics` 抓 `vllm:gpu_cache_usage_perc` 反推容量。
|
||
|
||
---
|
||
|
||
<a id="m2"></a>
|
||
## M2. P 候选选择避开 `active_p_offloads`
|
||
|
||
**严重度**: Medium。
|
||
|
||
**定位**: `scripts/cache_aware_proxy.py:291-295`。
|
||
|
||
**问题**:
|
||
- 选 P 候选只按 `c.ongoing_tokens`，没有考虑某 instance 已经在为别人做 offload。
|
||
- 配合 `MAX_OFFLOAD_INFLIGHT=4` 是 global cap，单 instance 可能扛多个 offload。
|
||
|
||
**改法**:
|
||
|
||
把 `:291-292` 的 key 加上 P-offload 罚项：
|
||
|
||
```python
|
||
def _p_pick_score(inst):
|
||
return (inst.ongoing_tokens
|
||
+ inst.active_p_offloads * HEAVY_THRESHOLD)
|
||
|
||
p_candidate = min((c for c in combined_instances if c is not best_inst),
|
||
key=_p_pick_score)
|
||
```
|
||
|
||
并把 `MAX_OFFLOAD_INFLIGHT` 拆成 per-instance：
|
||
|
||
```python
|
||
if any(c.active_p_offloads >= MAX_OFFLOAD_PER_INSTANCE
|
||
for c in combined_instances):
|
||
# 全员上限，不 offload
|
||
...
|
||
elif p_candidate.active_p_offloads >= MAX_OFFLOAD_PER_INSTANCE:
|
||
offload_reason = "p_inst_cap_reached"
|
||
```
|
||
|
||
---
|
||
|
||
<a id="m3"></a>
|
||
## M3. 把 `MAX_OFFLOAD_INFLIGHT` 暴露为 CLI
|
||
|
||
**严重度**: Low–Medium。
|
||
|
||
**定位**: `cache_aware_proxy.py:32, 312`。
|
||
|
||
**问题**: 模块常量 `MAX_OFFLOAD_INFLIGHT = 4`，未暴露 CLI；高并发实验时会成为隐性 bottleneck。
|
||
|
||
**改法**:
|
||
|
||
1. `parse_args` 里加：
|
||
```python
|
||
p.add_argument("--max-offload-inflight", type=int, default=4,
|
||
help="Global cap on concurrent P-role offloads")
|
||
```
|
||
|
||
2. 在 `_handle_combined` 里读 `global_args.max_offload_inflight` 而不是常量（与 [D5](#d5) 一致）。
|
||
|
||
3. 同步 `bench.sh` / `launch_phase1_ps.sh`，elastic 模式可设大一点。
|
||
|
||
---
|
||
|
||
<a id="m4"></a>
|
||
## M4. `session_affinity` 在 combined / pd-sep 之间命名空间隔离
|
||
|
||
**严重度**: Low（当前不会同时跑两种模式，但属隐患）。
|
||
|
||
**定位**: `cache_aware_proxy.py:158, 532`。
|
||
|
||
**问题**: 全局 `session_affinity: dict[str, int]`；combined 模式 idx 指向 `combined_instances`，pd-sep 模式同 dict 又被 `pick_instance(prefill_instances, ...)` 写入并指向 `prefill_instances`。同一个 session_id 在两种模式下索引含义不同。
|
||
|
||
**改法**:
|
||
|
||
把 `session_affinity` 改成两个：
|
||
|
||
```python
|
||
session_affinity_combined: dict[str, int] = {}
|
||
session_affinity_prefill: dict[str, int] = {}
|
||
```
|
||
|
||
`_handle_combined` 用前者，`_handle_pd_sep` 用后者。`pick_instance` 签名不变，只在调用方传不同 dict。
|
||
|
||
---
|
||
|
||
<a id="m5"></a>
|
||
## M5. fallback 路径 client 断流时的资源泄漏
|
||
|
||
**严重度**: Low–Medium（高并发下可能累积）。
|
||
|
||
**定位**: `cache_aware_proxy.py:438-467`（`_handle_heavy_offload` fallback）；`:364-387`（`_handle_combined` 主路径）；`:585-598`（`_handle_pd_sep`）。
|
||
|
||
**问题**:
|
||
- StreamingResponse 返回后，若 client 在 generator 未被消费时断开，generator 不会进入 `try`，`finally` 不会触发。
|
||
- 结果：`d_inst.ongoing_tokens` / `num_requests` / `pending_prefill_tokens` 永不释放，shadow state 与真实 load 越走越偏。
|
||
- 长时间运行后 router 认为某些 instance 一直满载，路由失衡。
|
||
|
||
**改法**:
|
||
|
||
把"扣减"从 `finally` 换成 `BackgroundTasks`/`FastAPI` 的 lifecycle 不可靠，最稳妥是**在路由阶段就只做"加"，扣减在异步监听 client disconnect 的协程里做**。简化版改法：
|
||
|
||
1. 包一层 `try/finally` 在调用 `StreamingResponse(generate(), ...)` 之前，并把状态扣减用 `request.is_disconnected()` 轮询或注册到 `BackgroundTask`。
|
||
2. 或者更简单：在 `inst.ongoing_tokens += input_length` 的同时把"应在结束时扣减的值"塞进一个 dict（key=request_id），并在 `app` 层每 30s 扫一次 stale 请求（超过 `request_timeout * 2` 的）做兜底回收。
|
||
|
||
**最小可行修复**：周期性 reconcile，在 `cache_aware_proxy.py` 里加一个后台 task：
|
||
|
||
```python
|
||
async def _reconcile_loop():
|
||
while True:
|
||
await asyncio.sleep(60)
|
||
for inst in combined_instances + prefill_instances + decode_instances:
|
||
# 简单 sanity: ongoing_tokens 永远 >= 0
|
||
if inst.ongoing_tokens < 0:
|
||
inst.ongoing_tokens = 0
|
||
if inst.num_requests < 0:
|
||
inst.num_requests = 0
|
||
# 进阶：与 vLLM /metrics 对账，详见 TODO.md item 6
|
||
```
|
||
|
||
并在 `lifespan` 启动该 task。这只是兜底，不解决根因；根因解决要走 TODO.md 第 6 条的 vLLM → Redis exact-state 路线。
|
||
|
||
---
|
||
|
||
<a id="m6"></a>
|
||
## M6. `_send_prefill_async` 与同步路径的核算不一致
|
||
|
||
**严重度**: Low（与 D1 一并解决）。
|
||
|
||
**定位**: `cache_aware_proxy.py:507-521` vs `:556-568`。
|
||
|
||
**问题**:
|
||
- 同步路径在 finally 扣 `p_inst.ongoing_tokens`；
|
||
- async 路径同样扣 `ongoing_tokens`，但 `pending_prefill_tokens` 在 PD-sep 路径中**两边都没维护**——表面一致，但与 combined 路径的语义不一致。
|
||
|
||
**改法**: 看 [D1](#d1)。如果保留 fire-and-forget，加上 `breakdown` 的 ready event（[B3](#b3)）后，同时确保两路径核算字段对称。
|
||
|
||
---
|
||
|
||
<a id="d1"></a>
|
||
## D1. 移除 `_send_prefill_async` 与 `--fire-and-forget`
|
||
|
||
**严重度**: Cleanup。
|
||
|
||
**定位**: `cache_aware_proxy.py:507-521`（function）、`:552-554`（caller）、`:634-635`（CLI flag）。
|
||
|
||
**问题**:
|
||
- grep 全 repo 所有 launch / bench / experiment 脚本，`--fire-and-forget` 0 处使用。
|
||
- 配合 [B3](#b3)，这条 reachable 但 broken 的路径是 dead-on-arrival。
|
||
|
||
**改法**:
|
||
|
||
1. 删除 `_send_prefill_async` 整个函数。
|
||
2. 删除 `_handle_pd_sep` 里 `if global_args.fire_and_forget: ... else:` 的分支，只保留同步 path。
|
||
3. 删除 CLI 里的 `p.add_argument("--fire-and-forget", ...)`。
|
||
4. `grep -rn "fire-and-forget\|fire_and_forget"` 确认无残留。
|
||
|
||
---
|
||
|
||
<a id="d2"></a>
|
||
## D2. 删除/归档 `run_benchmark.sh` 与 `run_experiments.sh`
|
||
|
||
**严重度**: Cleanup。
|
||
|
||
**定位**: `scripts/run_benchmark.sh`、`scripts/run_experiments.sh`。
|
||
|
||
**问题**: 与 [B2](#b2) 同源，两脚本仍传已删 CLI 参数；事实上不再可运行。
|
||
|
||
**改法**:
|
||
|
||
1. `mkdir -p scripts/legacy`
|
||
2. `git mv scripts/run_benchmark.sh scripts/run_experiments.sh scripts/legacy/`
|
||
3. 在 `scripts/legacy/README.md` 写一行："这些脚本对应早期 `--time-scale` / `--max-inflight-sessions` API，已归档，新实验请用 `scripts/bench.sh`。"
|
||
4. 若选择 [B2](#b2) 路线 A 重新加回 `--max-inflight-sessions`，可顺便把 `run_benchmark.sh` 从 legacy 拉回并修参数。
|
||
|
||
---
|
||
|
||
<a id="d3"></a>
|
||
## D3. 归档历史一次性 `analyze_*.py` / `compare_*.py`
|
||
|
||
**严重度**: Cleanup（影响新人理解）。
|
||
|
||
**定位**: `scripts/` 下约 20 个 `analyze_*.py` / `compare_*.py`。
|
||
|
||
**问题**:
|
||
- 大量脚本指向 `outputs/<exp>/...` 的旧实验路径（被 `.gitignore` 忽略，实际不存在）。
|
||
- `compute_roofline.py:165` 硬编码 `traces/sampled_1000req_seed42.jsonl`（已不存在，详见 [D4](#d4)）。
|
||
- 多个 `compare_*.py` 引用已删除实验目录。
|
||
|
||
**改法**:
|
||
|
||
1. 列一张表（在本文件下方"附录 A"或新建 `scripts/INVENTORY.md`），把每个 analyze/compare 脚本归类：
|
||
- **保留**: 有结构化用法、对当前 trace/output 仍可跑（如 `analyze_trace.py`、`analyze_breakdown.py`、`analyze_cache_hit.py`、`analyze_eviction.py`、`compare_results.py`）。
|
||
- **归档**: 一次性、特定实验 ID（如 `compare_ab_final.py`、`compare_balanced.py`、`compare_elastic_v4.py`、`compare_p2p.py`、`final_*.py`、`compare_aggregation.py`、`analyze_3way.py`、`analyze_h4_results.py`、`analyze_h5_rdma.py`、`profile_*.py`、`plot_gpu_timeline.py` 等）。
|
||
|
||
2. `git mv` 归档类到 `scripts/legacy/`。
|
||
|
||
3. 保留类的脚本：
|
||
- 顶部加 docstring，写明输入路径变量与示例命令。
|
||
- 凡是硬编码 `outputs/...` 路径的，全改成 `argparse` 参数。
|
||
|
||
**最小行动**: 至少把以下"明显死"的归档：
|
||
```
|
||
scripts/legacy/
|
||
├── compare_ab_final.py
|
||
├── compare_adaptive.py
|
||
├── compare_aggregation.py
|
||
├── compare_balanced.py
|
||
├── compare_elastic_v4.py
|
||
├── compare_p2p.py
|
||
├── final_all_comparison.py
|
||
├── final_comparison.py
|
||
├── final_gpu_comparison.py
|
||
├── analyze_3way.py
|
||
├── analyze_aggregation.py
|
||
├── analyze_h4_results.py
|
||
├── analyze_h5_rdma.py
|
||
├── analyze_p2p_cache.py
|
||
├── analyze_gpu_ab.py
|
||
├── analyze_ablations.py
|
||
├── plot_gpu_timeline.py
|
||
├── profile_fnf.py
|
||
├── profile_why_pdsep_loses.py
|
||
├── ab_gpu_test.sh
|
||
├── run_elastic_stability_test.sh
|
||
├── run_h4_cache_gate.sh
|
||
├── run_lmetric_ab.sh
|
||
├── run_ps_ablation.sh
|
||
├── run_ps_flexd.sh
|
||
├── run_ps_remaining.sh
|
||
└── run_v2_offload.sh
|
||
```
|
||
|
||
---
|
||
|
||
<a id="d4"></a>
|
||
## D4. 修正 `compute_roofline.py` 的硬编码 trace 路径
|
||
|
||
**严重度**: Low。
|
||
|
||
**定位**: `scripts/compute_roofline.py:165`。
|
||
|
||
**问题**: 写死 `trace_path = "traces/sampled_1000req_seed42.jsonl"`，文件已不存在。
|
||
|
||
**改法**:
|
||
|
||
```python
|
||
import argparse
|
||
|
||
def main():
|
||
p = argparse.ArgumentParser()
|
||
p.add_argument("--trace", type=str,
|
||
default="traces/w600_r0.0015_st30.jsonl",
|
||
help="Trace JSONL path")
|
||
args = p.parse_args()
|
||
trace_path = args.trace
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
<a id="d5"></a>
|
||
## D5. `HEAVY_THRESHOLD` / `OVERLOAD_FACTOR` 改读 args
|
||
|
||
**严重度**: Low。
|
||
|
||
**定位**: `cache_aware_proxy.py:30-34, 663-664, 88, 112`。
|
||
|
||
**问题**:
|
||
- 顶部 `HEAVY_THRESHOLD = 20000`，`__main__` 里 `HEAVY_THRESHOLD = global_args.heavy_threshold` 是给 module-level 名字赋值；
|
||
- 函数体里 `_p_offload_penalty(inst)` 与 `pick_instance` 直接读 `HEAVY_THRESHOLD` 名字（globals），运行时正常生效；
|
||
- 但若以后把 module 当库 import（例如加单测），`__main__` 块不执行，CLI 覆盖丢失。
|
||
|
||
**改法**:
|
||
|
||
把所有"运行时可调"常量挪到一个 `Settings` dataclass 里：
|
||
|
||
```python
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class Settings:
|
||
heavy_threshold: int = 20000
|
||
overload_factor: float = 2.0
|
||
max_offload_inflight: int = 4
|
||
cache_gate_ratio: float = 0.3
|
||
prefill_throughput: float = 7000.0
|
||
rdma_overhead_s: float = 2.0
|
||
cache_capacity_blocks: int = 200000
|
||
|
||
SETTINGS = Settings()
|
||
```
|
||
|
||
`parse_args` 后直接 `SETTINGS = Settings(**vars(args).filter(...))` 或逐字段赋值。函数体里改用 `SETTINGS.heavy_threshold` 等。
|
||
|
||
---
|
||
|
||
<a id="s1"></a>
|
||
## S1. 给 `replayer/metrics.py` 与 cost-model 加单元测试
|
||
|
||
**严重度**: Quality。
|
||
|
||
**问题**: 整 repo 0 个测试。`_percentile`、`InstanceState.estimate_cache_hit`、`pick_instance`、cost-model 都该有最小覆盖。
|
||
|
||
**改法**:
|
||
|
||
1. 新建 `tests/` 目录，加 `tests/__init__.py`。
|
||
2. `tests/test_metrics.py`：
|
||
```python
|
||
from replayer.metrics import _percentile
|
||
|
||
def test_percentile_even():
|
||
assert _percentile([1, 2, 3, 4], 0.5) == 2.5
|
||
|
||
def test_percentile_odd():
|
||
assert _percentile([1, 2, 3, 4, 5], 0.5) == 3
|
||
|
||
def test_percentile_p99():
|
||
assert _percentile(list(range(1, 101)), 0.99) == 99.01
|
||
```
|
||
|
||
3. `tests/test_proxy_pick.py`：
|
||
```python
|
||
import sys, pathlib
|
||
sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "scripts"))
|
||
from cache_aware_proxy import InstanceState, pick_instance, BLOCK_SIZE
|
||
|
||
def _new_inst(url="http://x"):
|
||
inst = InstanceState.__new__(InstanceState)
|
||
inst.url = url
|
||
inst.ongoing_tokens = 0
|
||
inst.pending_prefill_tokens = 0
|
||
inst.num_requests = 0
|
||
inst.active_p_offloads = 0
|
||
inst.cached_blocks = type(inst).__dict__.get(
|
||
"cached_blocks", set)()
|
||
return inst
|
||
# ...session affinity & overload tests
|
||
```
|
||
|
||
4. `pyproject.toml` 加 `[tool.pytest]` 段，跑 `pytest -q`。
|
||
|
||
---
|
||
|
||
<a id="s2"></a>
|
||
## S2. 给 vLLM patch 加 import-time 校验
|
||
|
||
**严重度**: Quality。
|
||
|
||
**定位**: `patches/0001-fix-kv-transfer-abort-race.patch`。
|
||
|
||
**问题**: 单 assert→warn 替换。未来升级 vLLM 时极易漏打 patch；当前没有运行时自检。
|
||
|
||
**改法**:
|
||
|
||
在 `scripts/cache_aware_proxy.py` 启动时（`lifespan` 开头）加：
|
||
|
||
```python
|
||
def _verify_vllm_patch():
|
||
"""启动时自检：被 patch 的 scheduler 是否仍包含期望的 warn 路径。"""
|
||
import inspect
|
||
try:
|
||
from vllm.v1.core.sched.scheduler import Scheduler
|
||
src = inspect.getsource(Scheduler)
|
||
if "assert req_id in self.requests" in src:
|
||
print("WARNING: vLLM scheduler still has the unpatched assert; "
|
||
"expect engine death on KV transfer abort race. "
|
||
"Apply patches/0001-fix-kv-transfer-abort-race.patch.")
|
||
except Exception as e:
|
||
print(f"vLLM patch self-check skipped: {e}")
|
||
```
|
||
|
||
并在 `lifespan` 最开始调用。
|
||
|
||
---
|
||
|
||
<a id="s3"></a>
|
||
## S3. REPORT.md 加 errata block
|
||
|
||
**严重度**: Quality（避免读者引用过期结论）。
|
||
|
||
**定位**: `REPORT.md` 顶部。
|
||
|
||
**改法**:
|
||
|
||
在 §1 后插入：
|
||
|
||
```markdown
|
||
## 0. Errata / 已废弃章节
|
||
|
||
> 本报告为多次方法论修订后的累积版本，下列章节结论已被后续小节修订或推翻：
|
||
>
|
||
> - §3.1（PD-sep vs PD-combined 初版对比）：使用旧采样 + `--time-scale`，被 §3.6 推翻，**勿引用**。
|
||
> - §3.5（elastic v3）：warm-vs-fresh 对比无效（baseline 实例未冷启动），**勿引用**。
|
||
> - §X 中提到的 `--max-inflight-sessions 64+` 实验：CLI 已删除，对应实验需先按 FIXES.md B2 路线 A 恢复参数后再做。
|
||
>
|
||
> 当前**唯一权威的**结果章节为 §3.6 与 §3.7。
|
||
```
|
||
|
||
---
|
||
|
||
## 验收清单
|
||
|
||
修复完成后，按此清单逐项验证。
|
||
|
||
- [ ] `grep -rn "_inst_cumulative_tokens" .` → 0 hits（B1）
|
||
- [ ] `python -m replayer --help` 列表里**有**或**没有** `--max-inflight-sessions`（视 B2 路线选择，二者必须自洽）
|
||
- [ ] `bash scripts/bench.sh ...` 在干净 repo 上能跑通至少 baseline 模式
|
||
- [ ] `grep -rn "fire-and-forget\|fire_and_forget" scripts/` → 0 hits（D1 完成）
|
||
- [ ] `grep -rn "/home/admin/cpfs" .` → 0 hits（B6）
|
||
- [ ] `cache_aware_proxy.py` 中 `cache_ratio` 出现且**被某个分支引用**（B4 完成）
|
||
- [ ] `pytest -q` 跑通新加的最小测试（S1）
|
||
- [ ] `REPORT.md` 有 §0 Errata 段（S3）
|
||
- [ ] 单跑 elastic 模式启动时打印 vLLM patch self-check 结果（S2）
|
||
- [ ] `scripts/legacy/` 下能找到归档的脚本（D2、D3）
|
||
- [ ] `_percentile([1,2,3,4], 0.5) == 2.5`（B5）
|
||
|
||
## 修复顺序建议（按 PR 切分）
|
||
|
||
1. **PR 1（不破坏行为，纯清理）**: B1、D1、D2、D3、D4、B6、S3
|
||
2. **PR 2（修 bug）**: B5、M1、M5（轻量 reconcile）
|
||
3. **PR 3（恢复实验能力）**: B2 路线 A（恢复 `--max-inflight-sessions`），同步 S1 加单测
|
||
4. **PR 4（落地设计）**: B4（cache-ratio gate）、M2、M3、D5
|
||
5. **PR 5（健壮性）**: M4、S2、剩余 M5 进阶版
|
||
|
||
修完 PR 1–3 即可重新运行 REPORT 自己规定的 next-step 实验；PR 4–5 是 elastic 真正落地的前置。
|