登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  科技周边 >  人工智能

PEFT LoraConfig 怎样只训练指定模块

来源:17golang原创

时间:2026-11-19 13:33:25 289浏览 收藏

如果你只想微调 Transformer 的注意力投影层,关键不是把 target_modules 写得越多越好,而是让它准确匹配模型里的真实模块名。PEFT 的 LoRA 会把适配器放到匹配到的模块上,其他基础权重继续保持冻结;因此“只训练指定模块”的核心就是选择规则,而不是额外手动冻结一遍模型。

官方文档:https://huggingface.co/docs/peft/package_reference/lora

这篇只讨论 LoraConfig 的目标模块匹配、排除模块和额外保存模块,不展开数据集、训练器或量化参数。

先把接口目标说清楚:训练的是适配器

调用方通常有两个要求:一是只在指定层注入 LoRA,二是保存结果时不要把整个基础模型都变成可训练参数。最小配置可以这样写:

from peft import LoraConfig, get_peft_model

# 只把注意力中的 query、value 投影作为 LoRA 目标
config = LoraConfig(
    r=8,                         # rank 越大,适配器参数越多
    lora_alpha=16,               # 控制 LoRA 缩放系数
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,           # 训练时对适配分支做轻微 dropout
    bias="none",                # 不额外训练基础层 bias
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(base_model, config)
peft_model.print_trainable_parameters()  # 用摘要确认可训练参数规模
LoraConfig、目标模块名与适配器层之间的静态关系说明图
图1:目标模块匹配说明图,查看配置入口、模块名匹配规则和 LoRA 适配器边界;这是原创结构图,不是运行截图。

这里的 q_proj 和 v_proj 不是要求完整路径,而是列表项的模块名后缀。只要模型中的模块名称以这些字符串结尾,就可能被选中。不同架构可能叫 query、value 或其他名字,所以不能直接照抄另一种模型的配置。

参数设计:列表后缀和字符串正则是两套语义

target_modules 传列表时,PEFT 会按完整名称或名称后缀匹配;传单个字符串时,则按正则表达式匹配。窄范围选择建议使用列表,规则化选择才使用正则:

# 列表:只匹配名称等于 q_proj 或以 q_proj 结尾的模块
config_by_suffix = LoraConfig(
    target_modules=["q_proj"],  # 中文含义:只选 query 投影这一类模块
)

# 字符串:用正则表达式表达更细的命名规则
config_by_regex = LoraConfig(
    target_modules=r".*\.self_attn\.(q_proj|v_proj)$",  # 中文含义:只选注意力里的 q/v 投影
)

# 只有确实想覆盖模型全部线性层时,才使用这个保留字
config_all_linear = LoraConfig(
    target_modules="all-linear",  # 中文含义:按模型线性层规则选择,而不是手写名称
)

“只训练指定模块”通常不应从 all-linear 开始,因为它会扩大范围。需要覆盖 QLoRA 常见的全部线性层时才使用它;如果模型架构无法自动识别目标模块,才回到手动列表。

排除误匹配,区分模块训练和模块保存

当后缀匹配覆盖面过大,可以用 exclude_modules 再收窄。它与 target_modules 使用相同的列表后缀或字符串正则思路。另一个容易混淆的参数是 modules_to_save:它表示适配器之外还要设置为可训练并保存的模块,不是 LoRA 的目标模块替代品。

config = LoraConfig(
    target_modules=["q_proj", "v_proj"],
    exclude_modules=["cross_attn.q_proj"],  # 中文含义:排除一个不想注入 LoRA 的分支
    modules_to_save=["classifier"],          # 中文含义:分类头全量训练并写入检查点
    bias="none",                             # 中文含义:保持基础层 bias 不参与训练
)

# 先打印名称,再根据真实命名决定是否需要排除或保存额外模块
for name, module in base_model.named_modules():
    if name.endswith(("q_proj", "v_proj", "classifier")):
        print(name, type(module).__name__)  # 中文含义:只观察候选模块,不执行训练

可以把三者记成一句话:target_modules 决定“哪里加 LoRA”,exclude_modules 决定“哪些匹配结果不要加”,modules_to_save 决定“哪些额外模块按自身参数训练并保存”。

目标模块、排除模块、层过滤与额外保存模块的静态边界说明图
图2:训练范围边界说明图,查看目标筛选、层范围和额外保存模块的关系;这是原创结构图,不是运行截图。

错误处理与兼容:先看名字,再决定匹配范围

最常见的“没有按预期训练”不是 LoRA 失效,而是模块命名不一致。先从 named_modules() 中找出真实路径,再选择后缀或正则;不要因为没有报错就认为目标命中了。对层数很多的模型,还可以配合 layers_to_transform 和 layers_pattern 限制某个模块列表中的层号。

如果同一后缀同时出现在 self-attention、cross-attention 或其他分支,优先改用带父路径的正则;如果只想训练少数层,则同时写明层模式和层索引。这样做比在训练完成后猜测“到底哪些参数更新了”更容易维护。

最后检查三件事:目标模块名称是否真实存在;排除规则是否误伤目标;modules_to_save 是否确实是需要全量训练的模块。确认这三点后,再扩大 target_modules 范围或切换到 all-linear,否则适配器大小和显存都会无谓增加。

常见问题

target_modules 写列表时必须写完整路径吗?

不必须。列表项可以是完整模块名,也可以是模块名后缀;但如果同一后缀在多个分支出现,就应改用更精确的正则或配合排除规则。

想训练分类头,应该把它放进 target_modules 吗?

如果分类头需要按自身参数全量训练,通常放进 modules_to_save 更直观;target_modules 仍只表达 LoRA 注入位置。

小结:先用真实模块名确定范围,再用列表后缀完成窄匹配,用正则表达分支边界,用 exclude_modules 排除误命中,用 modules_to_save 管理额外全量训练模块。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>