# v13_E 设计文档 — 调整后的定位

> 日期：2026-05-02 （调整版）
> 状态：**暂不运行。v13_D 已在跑且表现超预期（ep10 F=0.402），先等 v13_D 跑完 25 epoch**
> 定位：v13_D 之后的**扩展实验**（可能的 v13_F），而非替代

---

## 重要前提（来自 postmortem）

之前此文档写的是 "v13_D 崩溃，v13_E 抢救"。**这个前提错了。** v13_D 在 ep8 spatial loss ramp 放开后 F 从 0.19 跳到 0.40，ep10 已经超过 v12 best (0.378) 并仍在上涨。v13_D 是目前最强的实验。

v13_E 的实际价值是 **在 v13_D 之后再加一层**：启用 num_active head 的训练 + 让 SELD official evaluator 用 top-K̂ gate。这是 v13_D **没有**做的改动，理论上正交。

---

## v13_E 设计（保持不变，但动机重写）

### 改动

- **[E-1]** cls warmup 8 epochs + 20 total epochs
- **[E-2]** 启用 num_active head 训练（`lambda_frame_num_active = 0.5`）+ 推理 top-K̂ gate

### 和 v13_D 的关系

| 改动 | v13_D | v13_E |
|---|---|---|
| cls warmup 长度 | 8 | 8 |
| cosine LR | ✓ | ✗ |
| Top-K rank loss | ✓ | ✗ |
| EMA | ✓ | ✗ |
| resume optimizer | ✓ | ✗ |
| num_active head 训练 | ✗ | **✓** |
| SELD top-K̂ gate | ✗ | **✓** |

v13_E 是一个**剥离了 v13_D 的 loss/schedule 改动、只加 num_active 的对照组**。不能直接比 "哪个 F 高"，而是回答：

> **在同样 8 ep warmup 下，num_active head + top-K̂ gate 单独带来多少 F？**

如果 v13_E 最终 F > v13_D，说明 num_active 是正贡献，应该在 v13_F 里合并；反之说明它和 v13_D 的 Top-K rank 路径冲突。

---

## 何时运行 v13_E

**先看 v13_D 最终结果**：
1. 如果 v13_D 稳定在 0.43 以上 → 写 v13_F = v13_D + num_active 做融合
2. 如果 v13_D 最终不到 0.40 → 跑 v13_E 看 num_active 单独能达到多少
3. 如果算力充足 → 现在就可以跑 v13_E 做独立 ablation（对照组）

---

## 预期（基于 v13_D 实测）

| 指标 | v12 best | v13_D ep10 | v13_E 预期 |
|---|---|---|---|
| F20 | 0.378 | 0.402 | 0.39~0.42 |
| aR | 0.126 | 0.069 | 0.13~0.18 |

v13_E 的 **aR 预期比 v13_D 高**（num_active 补漏报），但 **F 可能持平或略低**（没有 Top-K rank + cosine + EMA 的增益）。

---

## 代码状态

- ✅ `spatial_loss.py` — `_build_frame_track_official_segment_dicts` 加 `use_num_active_gate` 参数
- ✅ `train_spatial_beats.py` — `make_ov1_unified_v13e_config` 已注册，CLI dispatch OK
- ✅ `run_ov1_unified_v13e.sh` — 可运行
- ✅ smoke test 通过

## 不影响其它实验

所有改动通过 config flag，默认 False。v12/v13_B/v13_C/v13_D 不受影响，照旧可跑。

## 参考

- 主要错误诊断记录：`docs/v13_honest_postmortem.md`
- v13_D 设计：`docs/v13d_spatial_beats_design.md`