docs: 层 2 关账——§6.1 远程实证勘误"预期见毛刺" + roadmap 存档点 + 接口回看

- docs/03 §6.1：两次远程跑（sanity/noclip）均平稳，勘误当初"预期毛刺"的错误
  预测；三条实证结论（爆炸真机制但本区间高度阻尼、grad_norm 是裁剪前值、层 5
  真正杀手锏是 logit-free）
- roadmap 存档点：层 2 ✅ 关账，判据全过、关键发现、接口回看（全判"深"，
  三条不返工小注）；章节索引 03 标已关账；下一步层 3

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/00-roadmap.md

@@ -8,14 +8,16 @@
 > 每次断点（层完成/工作暂停）更新此节。恢复上下文时：读 CLAUDE.md → 本节 → 对应章节文档。
 
 - **日期**: 2026-07-19
-- **当前层**: 层 2（white-box OPD），**代码已完成（U1-U5 全绿，66 单测通过）**，待远程冒烟
+- **当前层**: 层 2（white-box OPD）**✅ 已关账**；下一步进层 3（相似度 + MC 估计器）
-- **层 2 远程冒烟待办（下一步，用户在远程机执行）**: `bash scripts/train_whitebox.sh sanity`（50 步）。三盯：① `nvidia-smi` 确认 B=4/T=2048 不 OOM（白盒 = student+teacher 两份全词表 logits，§5 估算但未实测，OOM 阶梯：降 B→2、再开 gradient_checkpointing）；② KL loss 曲线应见**毛刺**（§4.1 梯度爆炸实况，截图留档给层 5 当有界乘子对照）；③ `distill/num_gen_tokens_per_step` 不塌成 0（生成没空转）。首跑会下载 teacher Qwen3-4B（GB 级）到 /data/zym/hf_cache
+- **层 2 代码构成**: U1 DistillConfig（configs.py，两温度分名/三处刻意缺席/max_grad_norm 显式化）；U2 token_divergence + 梯度爆炸单测（trainer.py，全词表 KL/JSD）；U3 SFTCollator prompt_only 模式（data.py）；U4 DistillTrainer + build_generated_batch（trainer.py，生成→双前向→divergence）；U5 train_whitebox.py/.sh（full/sanity/noclip 三模式）。附带：load_sft_dataset 毛刺已磨平（改吃散装参数）；hf-mirror 不代理 Xet CAS → HF_HUB_DISABLE_XET=1
-- **层 2 代码构成**: U1 DistillConfig（configs.py，两温度分名/三处刻意缺席）；U2 token_divergence + 梯度爆炸单测（trainer.py，全词表 KL/JSD）；U3 SFTCollator prompt_only 模式（data.py）；U4 DistillTrainer + build_generated_batch（trainer.py，生成→双前向→divergence）；U5 train_whitebox.py/.sh。附带：load_sft_dataset 毛刺已磨平（改吃散装参数，接口回看记录清账）
+- **层 2 关账判据全过**（详见 docs/03 §6.1 实证）: 66 单测全绿；B=4/T=2048 **实测不 OOM**（§5 估算成立）；两次远程跑（sanity 裁到 1.0 / noclip ≈关裁剪+lr5×）均平稳、不 NaN、生成不塌（num_gen ~1900-4096）、loss 0.35→0.21 下降；checkpoint 存下
+- **层 2 关键发现（勘误"预期见毛刺"）**: §4.1 梯度爆炸是真机制（U2 单测坐实单 token π_T→0 暴涨），但真实训练**高度阻尼**——同门 teacher + per-token mean 摊平，batch 级 grad_norm 峰值仅 ~14 且只降不升，关裁剪也不炸。启示：`grad_norm` 日志是**裁剪前**值（14→2 那串即爆炸证据，被 HF 默认 max_grad_norm=1.0 静默压平，现已显式化）；层 5 有界乘子 π̂ 真正杀手锏是 **logit-free**（白盒的同 tokenizer 约束把你锁在温和区间）
+- **层 2 接口回看**（§6.5 每层必做，全部判"深"，无需返工的毛刺）: DistillConfig/token_divergence/build_generated_batch/load_sft_dataset(已修) 接口均远简于实现。三条**记录不返工**的小注：① DistillTrainer 从 self.data_collator.tokenizer 取 student tokenizer（隐式耦合，但省一个冗余参数，可接受）；② SFTCollator 名字略超范（现含 prompt_only 非 SFT 模式），rename 的 churn 不值；③ token_divergence 的 labels 仅作掩码非目标（已在 docstring 标注）
 - **层 0**: ✅ 已关账（2026-07-18）
 - **层 1**: ✅ 已关账（2026-07-18）。判据全过：正本缓存 sha `33deb18c…`（1000 条，键唯一，think 残留 0，仅 2 条硬题截断）；正式 1 epoch loss 0.94→0.60（56s/16 步）；checkpoint 生成通顺（`/data/zym/outputs/sft_qwen3-0.6b_dapo1k`）；接口回看完成（全部模块判"深"；毛刺记录：load_sft_dataset 吃整个 SFTConfig 迫使诊断脚本填假 output_dir，层 2 第二消费方出现时定夺）
 - **层 1 疤痕档案**（详见 docs/02 §2.6/§5 勘误）: ① 显存大头是 (B,T,V) logits 链与激活（正比 B×T，与参数量无关），B=8 曾爆 80G；② HF 梯度累积契约两幕剧（×8 → ÷4），终解 = model_accepts_loss_kwargs=False 退出新式契约；③ 缓存正本纪律：本地生成一次、单向 scp 分发、sha256 对账，两侧独立生成曾花双份钱且内容漂移
 - **诊断工具箱**: scripts/diag_collator.py（对齐链逐环）、diag_loss_probe.py（预训练 CE 基准 0.85）、diag_generate.py（生成质量）——层 2+ 数值异常照此三板斧
-- **已完成学习**: 第一/二章全部精讲；第三章已写待读（含 standard 路径解剖三大反直觉点精讲）
+- **已完成学习**: 第一/二/三章全部精讲（第三章含 standard 路径三大反直觉点、两温度、抉择原则、§4.1 梯度爆炸机制+实证）
 - **未精讲的文档账**: docs/01 的 §3.7（KL 锚三处实现差异）、§3.8（论文外稳定器）、§4（训练步流程走读）
 - **远程磁盘备忘**: 根分区 100% 的结构性原因是 `/root/zym`（507G 历史工作区）压在根分区，建议择期整体搬迁 `/data`；临时缓解 = 清 `/tmp/pip-unpack-*`、旧 tar.gz、journal。所有新增写盘已改道 `/data/zym`
 
@@ -38,7 +40,7 @@
 | `00-roadmap.md` | 本文 | ✅ |
 | `01-paper-code-map.md` | 论文 §3-§4 精读 + 参考实现全景解剖 + 概念↔代码对照表 | ✅ |
 | `02-sft-baseline.md` | 层 1：SFT 与数据管线 | ✅ 待读 |
-| `03-whitebox-opd.md` | 层 2：token 级 KL 蒸馏及其脆弱性 | ✅ 待读 |
+| `03-whitebox-opd.md` | 层 2：token 级 KL 蒸馏及其脆弱性（含 §6.1 远程实证） | ✅ 已关账 |
 | `04-mc-estimator.md` | 层 3：MC 估计 + 贝叶斯平滑 | ⬜ |
 | `05-entropy-chunking.md` | 层 4：熵调度 | ⬜ |
 | `06-omniopd-full.md` | 层 5：完整损失与 teacher 客户端 | ⬜ |

docs/03-whitebox-opd.md

@@ -121,5 +121,20 @@ server 路径更粗：teacher 只回传 top-k logprobs 三张表（DT:2676-2679
 
 1. **本地 CPU 单测**：divergence 手算对拍（V=5 玩具分布，β∈{0,1,0.5} 三点各一）；β=1 与 β=0 的方向性断言（teacher 置信/弥散两种分布下 loss 排序）；**梯度爆炸测试**：固定 student，teacher 对采样 token 的概率从 1e-1 衰减到 1e-6，断言梯度范数单调暴涨且超阈值——为层 5 的"有界乘子"对照埋桩。
 2. **collator 回归**：放开 prompt-only 后，全部既有 SFT 测试必须原样通过。
-3. **远程冒烟**：50 步，盯 KL loss 曲线与生成样本质量；预期能看到 loss 毛刺（梯度爆炸的实况）——这本身就是教学目标，截图留档给层 5 当对比。
+3. **远程冒烟**：盯 KL loss 曲线、`grad_norm`、`distill/num_gen_tokens_per_step`。
-4. 关账判据：白盒蒸馏 1k 子集跑通不 NaN（允许毛刺），生成质量肉眼不劣于 SFT 基线；接口回看完成。
+4. 关账判据：白盒蒸馏跑通不 NaN，生成不塌空，接口回看完成。
+
+### 6.1 远程实证（2026-07-19，两次跑，勘误当初的"预期见毛刺"）
+
+**当初预测错了**：docs 原写"预期能看到 loss 毛刺（梯度爆炸实况）"。实跑**没有毛刺**，两次都平稳。诚实记录 + 解释：
+
+| 跑 | 配置 | loss | grad_norm |
+|----|------|------|-----------|
+| sanity | 裁到 1.0、lr 1e-6、50 步 | 平滑 0.35→0.22 | 14.42 → ~2（单调降） |
+| noclip | ≈关裁剪、lr 5e-6、15 步 | 平滑 0.35→0.21 | 14.42 → ~2（无尖峰，且更快收敛） |
+
+三条实证结论：
+
+- **爆炸是真机制、但本区间高度阻尼**。§4.1 在单测里坐实（单个 π_T→1e-6 的 token 梯度暴涨），但真实训练里：① **同门 teacher**（Qwen3 0.6B↔4B）使 student 很少采到 teacher 真恨的 token；② **per-token mean 把每步 ~4000 token 的梯度尖峰摊平**（单测看单 token 机制，真实看上千 token 平均后果）。故 batch 级 grad_norm 峰值只 ~14（比健康 ~2 高 5-7 倍，但远非几十上百），且只降不升。
+- **关键坑：`grad_norm` 日志是裁剪前值**。sanity 的 14→2 那串本身就是爆炸证据，只是 HF 默认 `max_grad_norm=1.0` 把**步长**裁掉了、loss 才平滑——这个静默稳定器现已提进 `DistillConfig`（见其注释）。noclip 关掉它，grad_norm 曲线几乎不变（第 1 步两跑完全相同=14.42，验证确定性），但大步长反而**加速收敛**、仍不炸。
+- **重构层 5 动机的认知**：白盒的"同 tokenizer"硬约束把你锁在相对温和的区间（换跨家族 teacher 会先被词表校验拦下），所以层 5 有界乘子 π̂ 的真正杀手锏不在"防这个温和爆炸"，而在 **logit-free**（teacher 只给文本、拿不到 logits，白盒根本跑不了）。爆炸的干净见证留在 U2 单测。