Hugging Face PEFT

Hugging Face PEFT 是实现和管理 LoRA、Prefix/Prompt Tuning 等参数高效微调方法的工具库。

典型职责

  • 为基础模型注入 adapter
  • 选择 target modules 与配置 rank/scaling
  • 保存、加载和切换 adapter
  • 将 adapter 合并进基础权重（视方法与部署需求）

API、模型模块名与 merge 流程随版本和架构变化；代码笔记应锁依赖版本并记录验证日期。

它在训练链中的位置

1
2
3
4
5
6
model + task
→ LoraConfig / PrefixConfig
→ get_peft_model 注入 adapter
→ 只让 adapter 产生梯度
→ save_pretrained 保存增量权重
→ adapter 独立加载或 merge 后部署

PEFT 库负责参数注入和状态管理，不负责替你决定数据格式、loss mask、量化策略或评测集。出现效果问题时，应先区分“adapter 没训练到”和“训练到了但任务定义错误”。

实操验收

  • 打印 model.print_trainable_parameters()，确认比例和预期一致。
  • 保存并重新加载 adapter，检查 base model、tokenizer、配置和 dtype 是否匹配。
  • 对比未 merge、merge、重新启动进程后三种路径的 logits/关键样例。
  • 记录 transformers、peft、bitsandbytes 版本；模块命名和量化集成经常随版本变化。

相关节点：PEFT、LoRA、QLoRA。参考：PEFT 文档。

一个最小的配置决策

1
2
3
4
5
6
7
8
config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    task_type="CAUSAL_LM",
)
model = get_peft_model(base_model, config)

这段代码真正隐含了三个假设：模型确实有这些模块名；任务的 loss 只监督预期 token；部署时会同时找到相同的 base revision 和 adapter。若 target_modules 没命中、task_type 错或 tokenizer/template 漂移，训练可能正常结束，却没有得到可用的增量能力。

因此 PEFT 的验收不应只看 adapter 文件大小，而要保存 resolved config、命中模块列表、可训练参数量、base model revision 和一组 merge 前后固定样例。adapter 是对基座的引用式增量，不是可以脱离基座独立运行的完整模型。