先找当前症状，
一次只排查一个原因。

# 第 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

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} 个参数！"   # ⭐

# 🧩 骨架：`e` 来自你自己的代码，这一段只看写法
# 每个 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")

# 🧩 骨架：`model` 来自你自己的代码，这一段只看写法
import torch
grad_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), 1e9).item()  # 只测量不裁剪

# 🧩 骨架：`loader` 来自你自己的代码，这一段只看写法
# 梯度累积：用小显存模拟大 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()

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