PEFT LoRA 只训练目标模块的参数选择方法

我第一次把 LoRA 接到一个结构不熟的 Transformer 上时，最容易犯的错不是 rank 写错，而是“看起来像目标”的模块名没有真正被 PEFT 选中，或者一口气把不该训练的层也放进了范围。比较稳的做法是：先从模型真实的模块树拿到候选名，再用 target_modules 选择 LoRA 插入点，最后用参数统计和名称清单复核。PEFT 官方地址：https://huggingface.co/docs/peft/en/package_reference/lora

一、先把目标范围缩成模块名集合

不要从模型名称或网上的通用配置直接猜层名。先把实际模块树打印出来，观察注意力投影、MLP 投影和输出头在当前架构中的命名。不同模型可能把 query/value 写成 q_proj、v_proj，也可能采用另一套名称。

# 只列出线性层，先确认当前模型真正使用的模块名
for name, module in model.named_modules():
    if isinstance(module, torch.nn.Linear):
        print(name)

# 生产配置前先把输出保存成审查清单，避免只凭记忆填写目标名
target_names = [name for name, module in model.named_modules()
                if isinstance(module, torch.nn.Linear)]
print("linear module count:", len(target_names))

这一步的结果不是最终配置，而是边界清单。若目标只在注意力层，后续就不要把同名的 MLP 层一起选进来；如果只想限制某几层，还要把层号或名称前缀一并纳入检查。

二、用 target_modules 接入 LoRA

常规选择写在 LoraConfig.target_modules。例如只训练注意力的 query/value 投影，可以使用后缀列表；如果任务明确需要覆盖 Transformer 中全部线性层，再使用 all-linear。后者更接近 QLoRA 风格，显存和训练参数都会上升，不应当作为“先试试”的默认值。

from peft import LoraConfig, TaskType

# 先限制在注意力投影，降低训练范围并保留清晰的回滚边界
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj"],
    bias="none",
)

# 只有在验证集证明需要更宽覆盖时，才改成 target_modules="all-linear"
peft_model = get_peft_model(model, lora_config)

列表项不一定要求写完整路径，PEFT 会按模块名规则匹配；但“配置成功”不代表选到了你想要的层。目标名不存在时，可能出现静默漏选，所以模型结构检查和训练参数统计不能省略。

三、区分额外训练模块与参数级目标

分类时记住三个不同概念：target_modules 是给模块加 LoRA；modules_to_save 是把指定完整模块保持可训练并保存，例如任务头或自定义分类头；target_parameters 面向的是模块树里直接存放的参数，典型场景是部分 MoE 专家权重不是 nn.Linear，因此没有可改写的 forward。

# 分类头需要完整更新时，单独放进 modules_to_save
lora_config = LoraConfig(
    task_type=TaskType.SEQ_CLS,
    r=8,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],
    modules_to_save=["score"],  # 任务头完整训练并随适配器保存
)

# 只有目标确实是 nn.Parameter 时才这样写；不要拿它替代普通模块选择
moe_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=8,
    target_modules=[],
    target_parameters=["mlp.experts.gate_up_proj"],
)

如果使用 MoE 参数级目标，还要考虑推理开销：专家参数上的 LoRA 可能让推理阶段计算更多未激活专家，部署前应单独评估合并适配器或更窄目标范围的代价。

四、用参数统计和命名清单做发布前检查

接入适配器后，先看 PEFT 给出的总量和可训练量，再把可训练参数名打印出来。你需要确认三件事：基础模型权重没有被意外解冻；目标模块数量和预期相符；modules_to_save 中的完整模块确实出现。

# 统计 LoRA 和额外保存模块的训练范围
peft_model.print_trainable_parameters()

# 用名称清单排除误选；正式训练前可把清单写入实验记录
trainable = [(name, tuple(param.shape))
             for name, param in peft_model.named_parameters()
             if param.requires_grad]
for name, shape in trainable[:30]:
    print(name, shape)

# 清单为空或数量异常时先停止训练，不要靠 loss 曲线事后猜原因
if not trainable:
    raise RuntimeError("没有找到可训练参数，请检查 target_modules")

如果统计结果远大于预期，先检查是否把 all-linear、任务头和多组 adapter 叠加；如果接近零，优先回到 named_modules() 对照命名，而不是只改 rank。

五、根据显存与效果调整范围

生产上我更愿意采用“窄范围起步、验证集驱动扩展”的顺序：先用 q_proj、v_proj 建立基线，再决定是否加入 k_proj、MLP 投影、完整任务头或 all-linear。每次只改一类目标，并记录可训练参数量、显存峰值和验证集指标，这样才能知道收益来自范围变化还是超参数变化。

相关问题

target_modules 写错会立刻报错吗？

不一定。官方排障说明提醒，无法对应模型模块的目标名可能被静默跳过，因此必须结合模块名和可训练参数统计复核。

modules_to_save 能替代 target_modules 吗？

不能。前者保存并训练完整模块，后者决定 LoRA 小矩阵插入哪些模块，二者可以同时使用。

什么时候需要 target_parameters？

当目标是直接存放的 nn.Parameter，尤其是部分 MoE 专家权重，而不是普通带 forward 的模块时再考虑。