PEFT PeftModel 怎样只保存适配器权重
来源:17golang原创
时间:2026-11-20 09:29:52 468浏览 收藏
训练完 LoRA 或其他 PEFT 方法后,交付目录通常不应该再复制一份基础模型。更稳妥的做法是让 PeftModel.save_pretrained() 只写适配器配置和适配器权重,部署时再把它挂回同一个基础模型。
官方地址:https://huggingface.co/docs/peft/main/en/package_reference/peft_model
一句话结论:保留PeftModel,调用save_pretrained,通过selected_adapters选定要交付的适配器,并保持safe_serialization=True;不要先把适配器合并回基础模型再期待得到“纯适配器”目录。
先区分基础模型、适配器和合并模型的保存边界
PeftModel 同时持有基础 Transformer 模型和 PEFT 配置。适配器保存的目标,是把增量参数及其配置独立出来,而不是把基础模型的全部参数复制一遍。这样发布包更小,也方便同一份基础模型挂载多个业务适配器。

如果已经执行了合并操作,模型参数的边界就改变了。此时得到的是带有适配器效果的完整模型,适合单体部署,却不再是本文讨论的“只保存适配器权重”。
用 save_pretrained 选择适配器并启用安全序列化
下面的示例假定训练过程已经得到一个包含名为 default 的适配器的 model。示例只展示保存决策,不需要下载模型或运行训练。
from pathlib import Path
from peft import PeftModel
# 交付目录只放适配器,不把基础模型目录复制进来。
adapter_dir = Path("./release/customer-support-adapter")
# 只保存指定适配器;safe_serialization 默认就是 True,这里显式写出边界。
model.save_pretrained(
adapter_dir,
safe_serialization=True,
selected_adapters=["default"],
save_embedding_layers="auto",
is_main_process=True,
)
# 目录交付给加载方时,仍需提供同版本或兼容的基础模型。
print(adapter_dir / "adapter_config.json")
selected_adapters=None 时通常会保存全部适配器;生产发布最好显式列出名称,避免把实验适配器一起打进包里。safe_serialization=True 使用 safetensors 形式保存适配器文件,是更清楚的交付默认值。
save_embedding_layers="auto" 会根据配置判断是否需要保存常见嵌入层。如果业务词表或目标模块确实改动过嵌入层,应把这项纳入发布评审,不要把“适配器目录很小”当成唯一目标。
把生产目录、权限和分布式主进程边界写清楚
企业环境里,保存目录最好按模型、适配器名称和发布版本隔离,并由发布账户创建、由推理账户只读。不要把 Hub Token、数据集路径或训练日志写进适配器配置旁边的自定义文件。
如果使用 DDP、FSDP2 或 HSDP,is_main_process 不是“只有一个进程调用保存”的开关。官方说明要求涉及分布式张量时所有参与 rank 都调用保存,让集体收集能够完成;只有负责写文件的主进程设置为 True。把这条约束写入训练作业说明,能避免进程组等待。
# 分布式作业中,所有 rank 都进入保存调用;只有主进程写交付文件。
is_main_process = (rank == 0)
model.save_pretrained(
adapter_dir,
safe_serialization=True,
selected_adapters=["default"],
is_main_process=is_main_process,
)
审计上至少保留适配器名称、基础模型标识、代码提交号和保存目录的版本记录。不要把完整训练数据或私密配置塞进文章所示的交付目录。
用 from_pretrained 设计回载入口并检查发布清单
适配器目录能否独立交付,关键不在于它是否包含基础模型,而在于它能否被明确地回载到约定的基础模型上。回载示例保留同一个适配器名,便于多适配器服务按名称管理。

from transformers import AutoModelForCausalLM
from peft import PeftModel
# 基础模型由部署配置提供,适配器目录只承担增量参数。
base_model = AutoModelForCausalLM.from_pretrained(base_model_id)
model = PeftModel.from_pretrained(
base_model,
"./release/customer-support-adapter",
adapter_name="default",
is_trainable=False,
)
# 明确切换到推理态,避免回载后误把适配器当作训练对象。
model.set_adapter("default", inference_mode=True)
发布清单可以压缩成四项:适配器配置文件、适配器权重文件、基础模型标识、适配器名称。若使用了多个适配器,再加上允许发布的适配器列表;若发生过合并,则另按完整模型交付流程处理。
常见问题
为什么目录里没有基础模型文件?
这是预期结果。适配器保存只负责增量参数,部署端必须能取得匹配的基础模型,并用 PeftModel.from_pretrained 重新挂载。
怎么只保存其中一个适配器?
为 selected_adapters 传入明确的适配器名称,例如 ["default"],不要依赖当前激活状态来猜测交付范围。
什么时候不适合只交付适配器?
如果运行环境不能稳定取得基础模型、需要单文件离线交付,或团队已经把适配器合并成完整模型,就应采用完整模型发布方案,并单独记录这一边界。
总结:先保留基础模型与适配器的边界,再用 save_pretrained 明确选项保存,最后用同一基础模型回载。对生产发布而言,目录最小化只是结果,适配器名称、嵌入层范围和分布式主进程规则才是可维护性的关键。
-
130 收藏
-
284 收藏
-
387 收藏
-
328 收藏
-
426 收藏
-
339 收藏
-
233 收藏
-
191 收藏
-
368 收藏
-
267 收藏
-
358 收藏
-
321 收藏
-
443 收藏
-
429 收藏
-
165 收藏
-
240 收藏
-
289 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习