# 重训问题跟踪

> 基于 `需要重训的问题.md` 整理，标注了当前重构状态（2026-08-04）。
> 代码基准：当前 HEAD（已删除距离场通路、掩码位 CE、修正子集 3）。

---

## 已完成（本次重构已解决）

| 问题 | 内容 | 措施 |
|------|------|------|
| **A 方案 1** | 距离场整条通路空转 1069 万参数 | 已删除 `DistFieldEncoder` + `dist_quantizer` + `z_dist` 全部通路 |
| **D** | CE 在全部 169 格上算，一半是"抄写" | 已在 `cross_entropy_loss` 加入 mask 参数，仅对被掩码位置计算 |
| **H-1** | 子集 3 空操作，20% 数据重复 | 已删除无效的 `out[0][out[0] == ENTRANCE] = MASK_ID` 行 |

---

## 待解决（按优先级排序）

### 1. 码本防塌缩（问题 B）

**现象**：`quantizer1` 利用率 37.2%（16/32 存活），死去码字范数为 0。`quantizer3` 利用率 37.3%。`quantizer2` 反而 96.1% 健康。

**根因**：`VectorQuantizer` 只有 EMA 更新，无任何防塌缩机制。`VQ_GAMMA = 0.0`（entropy loss 未启用），`VQDecodeHead` 从未被训练脚本 import。

**与症状的对应**：

| 阶段 | 条件通道状态 | 表现 |
|------|-------------|------|
| stage1 墙 | z1 用 37% + 距离场已删 | 差 |
| stage2 门/怪/入口 | z2 96.1% 健康 | 好 |
| stage3 资源 | z3 37.3% | 尚可 |

**建议措施**：

- ① 死码重启（dead-code restart）：在 `VectorQuantizer.ema_update` 中检测 `ema_cluster_size` 长期低于阈值的码字，用随机真实 z_e 重新初始化
- ② 启用 `VQ_GAMMA = 0.1`，打开 entropy loss
- ③ 或恢复两段式课程：先用 `VQDecodeHead` 做重建预训练，再冻结 VQ 训 MaskGIT

**需重训**：是。已死的码字（范数为 0，离任何 z_e 都是 ~7.7）在当前 checkpoint 上不可恢复。

**把握度**：中 — 码本利用率必涨，但对生成质量的改善幅度未知。

---

### 2. 码本监控（问题 C）

**现象**：`dist_quantizer` 塌缩了 320 epoch，训练日志从未提及。当前日志合并打印三个码本的 PPL（`PPL: 31.1 / 64`），掩盖了 `quantizer1` 只有 37% 的真相。

**措施**：

- ① 分开打印每个码本的 PPL/利用率/存活码字数
- ② 加离线诊断脚本，直接从 `.pth` 读 `ema_cluster_size` 和 `codebook.weight`，不用跑前向

**需重训**：否。**现在就能做。**

**把握度**：确定 — 纯粹是监控完善，无副作用。

---

### 3. 用上数据集中的额外字段（问题 G）

**现象**：`ginka-dataset.json` 每条记录有 `roomCount`、`highDegBranchCount`、`val`（16 维浮点，6098 种取值），但 `dataset.py` 只读了 `map` 和 `outerWall`。这些是数据侧已算好的拓扑信息，恰好是"墙该怎么排"的直接监督信号。

| 字段 | 内容 | 取值种类 |
|------|------|----------|
| `val` | 16 维浮点向量 | 6098 种（6731 张中） |
| `roomCount` | 房间数 | 17 种 |
| `highDegBranchCount` | 高度分支数 | 35 种 |

**措施**：将 `roomCount` / `highDegBranchCount` / `val` 加进 `struct_inject`（当前只有对称性 3 bit + outerWall 1 bit），或作为额外条件 token。

**需重训**：是。改条件输入。

**把握度**：中 — 比已删除的距离场有信息量得多（6098 种取值 vs 距离场实测只用到 3 种），是所有方案里信息量最明确的一条。

---

### 4. 条件注入方式改为 cross-attention（问题 F）

**现象**：所有 z 条件 token 被 flatten 成一个 d_model 维全局向量，通过 AdaLN 做全局 scale/shift 注入。z 中的 86 bit 只能以"全局风格"形式影响输出，没有任何机制传达空间位置信息。

**当前代码**（`maskGIT/model.py`）：
```
cond_seq = torch.cat([z_proj, e_struct, e_remain], dim=1)
c = self.cond_proj(cond_seq.reshape(B, -1))  # [B, d_model]
```

**措施**：改为 cross-attention — z 作为 memory，地图 token 作为 query。

**需重训**：是。改模型结构，权重完全不兼容。

**把握度**：低 — 此为推测，无实验证据证明它是主要瓶颈。工程量最大，建议放到最后。

---

### 5. 数据集去重（问题 H-2）

**现象**：6731 张训练数据中唯一的有 6379 张，重复 352 张（5.23%）。

**措施**：去重。不算严重，但免费。

**需重训**：否。改数据，可从头训。

---

### 6. 连通性损失（问题 E）

**原始建议**：不做。推理侧拒绝采样 + repair_connectivity 已做到可用率 100%。可微的连通性损失很难做，投入产出比不高。

**状态**：搁置。

---

## 建议实施顺序

| 顺序 | 事项 | 需重训 | 把握度 | 说明 |
|------|------|--------|--------|------|
| **1** | 码本监控（问题 C） | 否 | 确定 | 现在就能加，一行代码 |
| **2** | 码本防塌缩（问题 B ①+②） | 是 | 中 | 利用率必涨 |
| **3** | 用上额外字段（问题 G） | 是 | 中 | 信息量最明确 |
| **4** | 数据集去重（问题 H-2） | 否 | 确定 | 顺便做 |
| **5** | cross-attention（问题 F） | 是 | 未验证 | 工程量最大，最后做 |
| — | 连通性损失（问题 E） | — | — | 搁置 |

**建议 2+3 一起改、跑一次训练；1+4 不用重训，随时能做。**