# Failure-mode Taxonomy

**日期**：2026-05-13
**性质**：集中清单 + 诊断手册
**对象**：跑实验时遇到失败要立刻 lookup 的合作者；写 paper §Limitations 时需引用的人；reviewer 想问"你为什么觉得这次会更稳"时的答案

本文把当前系统已识别的失败模式按"症状 → 根因 → 触发条件 → 当前缓解 → 真正的修复"梳成一张表。所有条目都有 forensic 链接到原始实验 doc。

---

## 0. TL;DR

5 类已识别失败模式，按"是否阻碍 paper claim"分组：

| 类别 | 名称 | 阻碍 paper | 真正修复 |
|---|---|:---:|---|
| **A. 控制层级联** | Mooncake "instance not alive" cascade | ✅ | admission backoff + per-D pending-seed budget |
| **B. 路由偏置** | Cold-D / overlap-pinning | ✅ | first-principles overlap term redefinition |
| **C. KV 抖动** | Evict storm（session-level evict） | ✅ | [BLOCK_LEVEL_EVICTION_DESIGN_ZH.md](BLOCK_LEVEL_EVICTION_DESIGN_ZH.md) |
| **C'. KV 抖动** | Reseed storm（turn 1 大 seed 并发） | ✅ | per-D pending-seed budget + (C 缓解后频率自降) |
| **D. Vendor 不变量** | streaming-session correction invariant crash (E3) | ❌（hotfix 已 land） | 删除 correction 路径（block-level evict 完成后） |

A / B / C 三类是 Milestone 1 必须解决的；C' 是 A 的次因；D 已临时止血但根本修复绑在 C 上。

---

## 1. A — Mooncake "instance not alive" cascade

### 1.1 症状

- 客户端看：`RuntimeError: generate stream ended before producing any token`
- D scheduler 日志：`[mooncake] Decode instance could be dead, dropping ...`
- 整批请求被 abort，单一 sweep 在数分钟内从健康降到 80% failure（[E1_E2_RESULTS_ZH.md](E1_E2_RESULTS_ZH.md) E2：1054 / 1285 失败）

### 1.2 根因（forensic 链路）

```
admission no-space (D KV pool 满)
    → router 立刻 fallback 走 seed/reseed 路径
    → 多个并发 seed 同时打 mooncake P→D
    → P→D 出口排队，handshake 阶段超时
    → mooncake 把对端标记 dead
    → SGLang 把 dead 链路上的 in-flight req 全部 abort
    → 客户端看到批量 generate-stream 中断
```

### 1.3 触发条件

- D KV pool 接近满（≥ ρ·K_d，默认 0.95）
- router fallback chain 把多个 reseed 在毫秒级窗口内发起
- mooncake heartbeat 超时（默认窗口短）

### 1.4 当前缓解

- `--kvcache-seed-min-turn-id=2` 跳过 turn 1 大 seed，减少首爆（main 分支 stable 配置）
- `--mc-transfer-timeout=1800s` 默认值（commit 905d671）减少假性 dead
- `--request-timeout-s=180/300` 让客户端不至于看见整 hour 卡死，但不阻止 cascade 自身

→ 这些都是治标，不是治本。E2 在 4×H200 NDR 真硬件下仍 80% 失败 ([E1_E2_RESULTS_ZH.md](E1_E2_RESULTS_ZH.md))。

### 1.5 真正的修复（路线图 §S3）

1. **admission RPC backoff + jitter**：拒绝时不立刻 fallback，给 D scheduler 喘息机会。
2. **per-D pending-seed budget**：同时刻最多 K 个 seed 在 transfer 队列里，超出排队而不爆裂。
3. **mooncake heartbeat 与 admission 解耦**：admission 路径不再 imply "对端 alive"。
4. **Backpressure pause hint 闭环**（[SGLANG_PATCH_INVENTORY_ZH.md](SGLANG_PATCH_INVENTORY_ZH.md) §2.3 当前 EXPERIMENTAL）。

---

## 2. B — Cold-D / overlap-pinning

### 2.1 症状

- N=k decode workers，但只有 ~k-1 真正承载流量；某些 D 0 binding
- Per-D load 直方图严重偏斜（E2：D0:600 / D1:685 / **D2:0**）
- 整体 throughput 受最忙 D 限制；裸 latency 不一定差，但容量利用率差 33%+

### 2.2 根因

Inferact / Ali coding agent trace 在每个 session 开头有 ~12K 的"system prompt + tool schema"，这些 24-token 块在所有 session 之间共享 hash。kv-aware policy 的 `overlap` term 把它们当成"该 D 已经常驻这些 hash" → 任何新 session 都被 score 推向 D0/D1（最先 warm 的两个）→ D2 永远 0 overlap → 永远不被选 → 永远 cold。

### 2.3 触发条件

- 多 session workload + 共享 boilerplate prefix
- `migration_reject_threshold > 0` 且 reject 从未触发（因为 D0/D1 还没满）

### 2.4 当前缓解

`KvAwarePolicy.load_floor_bonus`（commit 93fce42）：

```
floor_bonus = K * max(0, mean - assigned) / max(1, mean)
```

E3 实测 D2 binding 从 0 升到 22.5%（[E3_FINDINGS_ZH.md](E3_FINDINGS_ZH.md) §1）。

→ 这是 patch，不是修复。`K` 是 magic number；boilerplate 的 hash 数量大于 `K / sticky_bonus` 时仍 cold。

### 2.5 真正的修复（路线图 §S5）

把 `overlap` 重新定义为 **"该 session 在该 D 上独占 prefix 的 hash 数"**：

```
exclusive_overlap(s, d) := |prefix_hashes(s) ∩ resident[d] ∩ session_owned[s]|
```

其中 `session_owned[s]` 排除其它 session 也持有的 hash。Boilerplate 共享 hash 不进 `exclusive_overlap`，score 自然分散。需要 D 端在 `admit_direct_append` 响应里返回 per-session resident hash 集合的 sketch（Bloom filter / minhash）。

---

## 3. C — Evict storm（session-level eviction）

### 3.1 症状

- 在 D 内存有压力的 workload 下，每 1–2 分钟出现 30–90K tokens 的 KV pool 释放峰
- 紧随其后的同 session 请求触发 `Reseed`：P 重 prefill 50K + mooncake transfer 50K（3–7s）
- TTFT 长尾完全由这类 reseed 主导（[V2_DEEP_ANALYSIS_ZH.md](V2_DEEP_ANALYSIS_ZH.md) §3.2）

### 3.2 根因

`SessionAwareCache.release_session` 一次性 `free([cache_protected_len, kv_allocated_len))`——即整段 session-exclusive 尾部。E3 实测：90 次 evict、平均一次 free 67,726 tokens、25/50 session 受影响（[KVC_EVICTION_GRANULARITY_DESIGN_ZH.md](KVC_EVICTION_GRANULARITY_DESIGN_ZH.md) §0）。

→ 与 SGLang 标准 radix 的 leaf-by-leaf 渐进 evict 形成鲜明对比。这部分 KV 从未进 radix，所以享受不到 LRU 的细粒度蚕食。

### 3.3 触发条件

- D KV pool 接近满
- `maybe_trim_decode_session_cache` 被 scheduler 触发（在 `DecodePreallocQueue` 检测到 `available_size() <= 0` 时）

### 3.4 当前缓解

- `--kvcache-session-soft-cap=N`（main 分支）：限制 D 上常驻 session 数 → 提前 trim，避免顶到爆
- `--kvcache-direct-max-uncached-tokens=8192`（v2）：降低 direct path 吃 KV 的速度

→ 都是放慢节奏，没有解决"单次 free 太大"的根本问题。

### 3.5 真正的修复（路线图 §S1）

[BLOCK_LEVEL_EVICTION_DESIGN_ZH.md](BLOCK_LEVEL_EVICTION_DESIGN_ZH.md)：让 streaming-session decode 输出每 turn finish 时 `inner.cache_finished_req` 进 radix → `release_session` 退化为 `dec_lock_ref` + 删 slot → radix LRU 按 24-token leaf 蚕食。

预期：单次 evict 从 67K 降到 ≤ 500 tokens；reseed 频次降一个数量级。

---

## 4. C' — Reseed storm（turn 1 大 seed 并发）

### 4.1 症状

- workload 起步阶段（前 30–60s）所有 session 同时打 turn 1
- 多个并发 `Seed`（每个 ~50–90K tokens）打 mooncake → 与 §1 cascade 重合

### 4.2 根因

`KvAwarePolicy` 启动阶段 `resident[d]` 全空，所有 D score 相同，但 ε 重试 + per-trial admit 不阻止并发。

### 4.3 触发条件

- trace `time_scale=1` 重放下，session 在原始到达密度内同时启动
- 没有 per-D pending-seed 限流

### 4.4 当前缓解

- `--kvcache-seed-min-turn-id=2`：跳过 turn 1 seed 完全（main 分支 stable 配置）
- 副作用：失去 turn-1 的 KV 注入，turn 2 必走 reseed（但反而稳定，因为 reseed 是分散在时间上的）

### 4.5 真正的修复

- per-D pending-seed budget（同 §1.5 第 2 项）
- §3.5 完成后 evict 频次自降，间接降低 reseed 频次

---

## 5. D — Streaming-session correction invariant crash (E3 landmine)

### 5.1 症状

- D scheduler 抛 `AssertionError` at `schedule_batch.py:1646`：`seq_len - pre_len == req.extend_input_len`
- 整个 D worker 进程退出 → router 看见对端死 → §1 cascade

### 5.2 根因

[E3_FINDINGS_ZH.md](E3_FINDINGS_ZH.md) §2：streaming-session correction（commit b8e6f13）把 `extend_input_len` 改写为 `max(0, fill_len - prefix_len)`，但下游 invariant 还从原始 fill_ids/prefix_indices 计算。当 `fill_len < prefix_len`（多 turn 累积 prefix > 当前 turn 增量）时数学上不可能满足。

### 5.3 触发条件

- streaming session 跨 turn 已 commit prefix 长于本 turn 的新增 fill_ids
- E2 因 pipeline 阻塞从未跑到这个状态；E3 修了 cold-D bottleneck → pipeline 更快 → landmine 暴露

### 5.4 当前缓解

commit 986f351 的 pre-filter pass：在 `prepare_for_extend` 入口 drop 这类 req（让 client 看错误响应而不是 worker 崩）。是止血。

### 5.5 真正的修复

`schedule_batch.py:1572–1646` 这整段 correction 路径在 block-level eviction refactor 完成后**结构上不再需要**——[BLOCK_LEVEL_EVICTION_DESIGN_ZH.md](BLOCK_LEVEL_EVICTION_DESIGN_ZH.md) §3.7 已说明 refactor 后 fill_ids / prefix_indices 一致性由 radix `match_prefix` 自动保证。

→ 不要再加更多 correction 子句；要删整段。

---

## 6. 失败诊断 cheat sheet

跑 sweep 时按下表 lookup：

| 你看到 | 大概率是 | 先查 |
|---|---|---|
| 客户端 `RuntimeError: generate stream ended before...` | §1 cascade | D scheduler log 搜 `instance could be dead` |
| 某个 D `binding=0` 而其它 D 繁忙 | §2 cold-D | `per_decode_load` 直方图 |
| TTFT p99 突然抬到 5–8s 量级 | §3 evict storm | `release_session` 调用频次 + 平均 free tokens |
| Sweep 起步阶段失败率高、稳态低 | §4 reseed storm | mooncake transfer queue 在前 30s 的峰值 |
| D worker 进程异常退出 | §5 invariant crash | scheduler log 搜 `AssertionError`、`extend_input_len` |

---

## 7. 与路线图的衔接

- [AUDIT_AND_ROADMAP_ZH.md](AUDIT_AND_ROADMAP_ZH.md) Milestone 1 的第 1/3/4 项分别对应本表 C / A / B 的真正修复。完成 Milestone 1 后本表 §1–§4 应该都从"未修"降级为"已缓解"，§5 直接消失。
- 论文 §Limitations 必须老实写出现状："we identify five failure modes; A/C are addressed by this work, B/C' are partially addressed, D is a transient artifact of the in-progress refactor."

---

**核心句**：把失败模式当 first-class artifact 来管理——每个失败都有"症状 → 根因 → 触发 → 缓解 → 真正修复"五字段，是把 prototype 推到 production-grade 的关键工具。reviewer 看见你能枚举失败远比看见你赢得 baseline 更让人信服。