11 · 训练调试手册

   第 0 步：在【10 个样本】上训练，能不能把 loss 降到接近 0？
            │
            ├─ ❌ 不能  → 有 BUG，别调参了，去第二节查
            │
            └─ ✅ 能    → 模型和数据管线是通的
                          │
   第 1 步：全量数据训练，训练 loss 降吗？
            │
            ├─ ❌ 不降  → 欠拟合：加容量 / 加 lr / 减正则
            │
            └─ ✅ 降    → 看验证 loss
                          │
   第 2 步：验证 loss 跟着降吗？
            │
            ├─ ❌ 不降或上升 → 过拟合：加数据 / 加正则 / 早停
            │
            └─ ✅ 降       → 恭喜，现在才轮到调参提分

# 第 0 步的标准写法
tiny_x, tiny_y = X[:10], y[:10]
for step in range(500):
    optimizer.zero_grad()
    loss = criterion(model(tiny_x), tiny_y)
    loss.backward(); optimizer.step()
    if step % 100 == 0: print(step, loss.item())
# 期望：loss 降到 < 0.01。降不下去 = 有 bug

   分类任务（C 类，初始时模型在均匀乱猜）：
       第一个 loss ≈ ln(C)

       2 类  → 0.693
       10 类 → 2.303
       100 类→ 4.605

   ⭐ 明显偏离说明：
      · 大得多  → 初始化太大 / 标签错位 / 输出层有问题
      · 小得多  → 【标签泄漏】或者类别极度不平衡

① 标签对齐了吗？
   打印几个 (输入, 标签) 对，肉眼确认没错位
   ⚠️ shuffle 时 X 和 y 分别 shuffle 是经典事故

② 梯度真的在流吗？
   for n,p in model.named_parameters():
       print(n, p.grad.abs().mean() if p.grad is not None else "None")
   → 出现 None 或 0：梯度断了

③ loss 函数用对了吗？
   · 多分类用 CrossEntropyLoss（输入是 logits，不要自己加 softmax！）
   · 二分类用 BCEWithLogitsLoss（不要自己加 sigmoid！）
   ⚠️ 重复加激活是最高频的错误之一

④ 输入的形状/数值对吗？
   print(X.shape, X.dtype, X.min(), X.max(), X.mean())
   → 全 0？没归一化？dtype 是 int 不是 float？

⑤ lr 是不是离谱？
   试 1e-2 / 1e-3 / 1e-4 三档，如果全都不动，那是 bug 不是 lr

def sanity_check(model, loader, criterion, device):
    xb, yb = next(iter(loader))
    xb, yb = xb.to(device), yb.to(device)

    # ① 输入长什么样
    print(f"X {tuple(xb.shape)} {xb.dtype} "
          f"min={xb.min():.3f} max={xb.max():.3f} mean={xb.mean():.3f}")
    print(f"y {tuple(yb.shape)} {yb.dtype} unique={yb.unique()[:10].tolist()}")

    # ② 第一个 loss 对不对
    out = model(xb)
    loss = criterion(out, yb)
    print(f"输出 {tuple(out.shape)} mean={out.mean():.3f} std={out.std():.3f}")
    print(f"首个 loss = {loss.item():.4f}  (分类应≈ln(类别数))")   # ⭐

    # ③ 梯度流通吗
    loss.backward()
    dead = [n for n, p in model.named_parameters()
            if p.grad is None or p.grad.abs().max() == 0]
    print(f"无梯度的参数: {dead if dead else '无 ✅'}")            # ⭐
    model.zero_grad()

# ❌ 后来加的层没进优化器 → 它的梯度算了但永远不更新
import torch
import torch.nn as nn
optimizer = torch.optim.AdamW(model.encoder.parameters(), lr=1e-3)
model.head = nn.Linear(512, 10)      # 这层永远不会被训练 💀

# ✅ 自检：优化器管的参数数量对不对
n_opt = sum(p.numel() for g in optimizer.param_groups for p in g["params"])
n_all = sum(p.numel() for p in model.parameters() if p.requires_grad)
assert n_opt == n_all, f"优化器只管了 {n_opt}/{n_all} 个参数！"   # ⭐

# 每个 epoch 打印
print(f"epoch {e} | train {train_loss:.4f} | val {val_loss:.4f} "
      f"| lr {optimizer.param_groups[0]['lr']:.2e} "
      f"| grad {grad_norm:.3f} | 输出均值 {out.mean():.3f} | 用时 {t:.1f}s")

import torch
grad_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), 1e9).item()  # 只测量不裁剪

# 梯度累积：用小显存模拟大 batch
for i, (xb, yb) in enumerate(loader):
    loss = criterion(model(xb), yb) / accum_steps
    loss.backward()
    if (i + 1) % accum_steps == 0:
        optimizer.step(); optimizer.zero_grad()

☐ 固定所有随机种子（python / numpy / torch / cuda）
☐ DataLoader 的 shuffle 也受种子控制
☐ 记录：代码版本、超参、数据版本、库版本
☐ 同样配置跑 3 次，看方差有多大  ⭐
     └ 这个方差决定了「涨 0.3% 算不算真的涨」（第 5 章）

def set_seed(s=42):
    import random, numpy as np, torch
    random.seed(s); np.random.seed(s)
    torch.manual_seed(s); torch.cuda.manual_seed_all(s)
    torch.backends.cudnn.deterministic = True