调试与踩坑合集

PEFT 大多数错误集中在三个环节：选 target_modules、save/load、量化集成。 本章把这些高频问题列成清单，按"现象 → 原因 → 定位 → 处理"四列写。

11.1定位类问题

11.2训练类问题

11.3save/load 类问题

11.4合并 / 卸载类问题

11.5与 transformers Trainer 配合的问题

11.6调试小工具

看 LoRA 真的接上了吗

from peft.tuners.lora import LoraLayer
for name, m in model.named_modules():
    if isinstance(m, LoraLayer):
        print(name, "→ active:", m.active_adapters,
              "merged:", m.merged_adapters,
              "r:", m.r if hasattr(m, "r") else "n/a")

看 LoRA 矩阵的范数（训练健康度）

for name, m in model.named_modules():
    if isinstance(m, LoraLayer):
        for adapter in m.active_adapters:
            A = m.lora_A[adapter].weight
            B = m.lora_B[adapter].weight
            print(f"{name}/{adapter}  ||A||={A.norm():.4f}  ||B||={B.norm():.4f}")

训练初期 B 应该接近 0（零初始化），训练后 B 应该有非平凡 magnitude（如 > 0.01）。如果训完 B 还接近 0，说明梯度没流过来。

用 hook 看 LoRA 输出的贡献

activations = []
def hook(module, x, y):
    base_out = module.base_layer(x[0])
    delta = y - base_out
    activations.append((module, delta.abs().mean().item()))

for name, m in model.named_modules():
    if isinstance(m, LoraLayer):
        m.register_forward_hook(hook)

# 跑一次推理，看每层 LoRA 贡献多少
model(input_ids=...)
for m, d in activations[:5]:
    print(m, d)

11.7常用环境变量

11.8定位思路（通用）

1. 先在 0.5B 小模型上跑通（Qwen2.5-0.5B 等），再换大模型；
2. 先纯 LoRA 跑通，再加 QLoRA / DoRA / 多 adapter；
3. 每加一个开关跑一次，避免一次开 5 个开关定位不到；
4. 用 print_trainable_parameters() 当 sanity check，没匹配就别往下走；
5. 断网时设 TRANSFORMERS_OFFLINE=1 避免无谓重试。

11.9DoRA + ZeRO-3 / FSDP 的已知坑

DoRA 在分布式训练时有几个隐形陷阱。tuners/lora/dora.py:94 的 get_lora_weight 注释里写得明白："use eye matrix to avoid FSDP issues"，这是因为：

11.10PEFT + FSDP 的 use_orig_params

FSDP 1 默认 use_orig_params=False——FSDP 把多个参数展平打包成一个大张量，分块切到各 rank。这跟 PEFT 的"trainable / frozen 混合"完全不兼容（FSDP 看到一堆 frozen 参数夹着少量 trainable）。两种修复：

accelerate config 里写 fsdp_use_orig_params: true（FSDP v1）或 fsdp_version: 2 即可。Trainable Tokens 这种特殊 tuner（tuners/trainable_tokens/）也明确要求 use_orig_params。

11.11量化 + bias 的互斥

有几条 PEFT 不会显式报错但行为反常的"已知不兼容"：

11.12这章你需要带走的

• 50% PEFT 问题来自 target_modules 没匹配上，每次都先 print 一下；
• 另 25% 来自 save/load 顺序，load 时记得 PeftModel.from_pretrained；
• QLoRA 训练前必调 prepare_model_for_kbit_training；
• 调试 LoRA 健康度：看 ||B|| 的 norm 训完是否远离 0；
• 遇到诡异问题先在 0.5B 模型上复现，节约时间。