PEFT 怎样卸载 adapter 并保留基础模型

PEFT 里“把 adapter 卸载掉”不等于“把 LoRA 权重合并进基础模型”。如果只是想恢复一个不带 adapter 模块的基础模型，应使用 unload()，并把它的返回值重新赋给变量；如果只是临时做一次基础模型推理，则使用 disable_adapter() 上下文管理器更合适。

官方地址：https://huggingface.co/docs/peft/en/package_reference/peft_model

记住三个边界：临时对比用 disable_adapter()，移除 LoRA 模块用 unload()，需要把增量写入基础权重才考虑 merge_and_unload()。unload() 不是原地操作，必须接住返回的基础模型对象。

先分清禁用、卸载和删除

这三个动作都可能被口头称为“去掉 adapter”，但对对象生命周期的影响不同。disable_adapter() 只在上下文范围内停用 adapter，离开代码块后模型仍然保留它；unload() 移除 PEFT 模块并返回基础模型，不把 adapter 增量合并进去；delete_adapter(name) 针对命名 adapter 做删除，适合仍在管理多个 adapter 的 PeftModel。

可以按下面的判断来选 API：

用 unload 返回基础模型

最小写法是先加载基础模型和 adapter，再把 unload() 的结果赋给新变量。官方文档把它定义为移除所有 LoRA 模块并返回基础模型；它不是对原对象做完清理后继续原地使用的快捷方法。

from transformers import AutoModelForCausalLM
from peft import PeftModel

# 先创建没有 adapter 的基础模型对象
base_model = AutoModelForCausalLM.from_pretrained("your-base-model")

# 加载训练好的 adapter；adapter_dir 可以是本地保存目录或 Hub 标识
peft_model = PeftModel.from_pretrained(base_model, "your-adapter-dir")

# unload 不合并 LoRA 增量，必须接住返回的基础模型引用
plain_model = peft_model.unload()

# 后续把 plain_model 当作基础模型使用，不要继续把旧 peft_model 当作清理结果
print(type(plain_model).__name__)

这里最容易写错的是最后一行赋值。只调用 peft_model.unload() 却继续使用 peft_model，会把“调用过卸载”和“当前引用已经是基础模型”混为一谈。实际代码中还应根据自己的模型类型保留 tokenizer、设备和 dtype 配置；这些对象不由 unload() 自动替换。

不要把 unload 和 merge_and_unload 混为一谈

unload() 的目的，是把 adapter 模块从模型结构中移除，同时保留基础权重本身；merge_and_unload() 则是把 LoRA 增量合并到基础权重，再返回一个可作为单体模型使用的对象。前者适合恢复、换 adapter 或重新组织实验，后者适合明确需要单文件或减少推理时额外 adapter 路径的场景。

# 这个上下文只临时停用 adapter，离开代码块后仍可继续使用 PEFT 模型
with peft_model.disable_adapter():
    # 这里用于做基础模型与 adapter 输出的对照，不会移除模块
    baseline_output = peft_model.generate(**inputs)

# 需要恢复不带 adapter 的模型时，接住 unload 的返回值
plain_model = peft_model.unload()

# 需要合并权重时才使用另一条 API；它不是 unload 的同义替换
merged_model = another_peft_model.merge_and_unload()

如果需求是“稍后还要切回 adapter”，不要用 unload() 代替临时禁用；如果需求是“保留当前 PEFT 对象但去掉其中一个命名 adapter”，才考虑 delete_adapter()。把这些操作混在一个长生命周期对象里，最容易造成实验状态不透明。

多 adapter 和 Notebook 重跑时怎么排查

PEFT 官方文档说明，加载多个 adapter 时要给新 adapter 唯一名称，而且新加载的 adapter 不会自动成为 active adapter。若只是需要切换当前任务，应使用 set_adapter()；若要移除整个 adapter 模块并回到基础模型，应使用 unload()；若只想删除一个命名项，应在仍然持有 PeftModel 时调用 delete_adapter()。

# 多 adapter 时为每个任务使用稳定且唯一的名称
peft_model.load_adapter("review-adapter-dir", adapter_name="review")

# set_adapter 只改变当前激活的 adapter，不会删除其他已加载项
peft_model.set_adapter("review")

# 只删除命名 adapter 时保留 PeftModel 结构，名称必须与加载时一致
peft_model.delete_adapter("review")

# 如果整个对象要回到基础模型，使用返回值替换引用
plain_model = peft_model.unload()

在 Notebook 中反复执行同一个单元格时，旧对象可能仍被变量引用。看到“模型已经被 PEFT 修改过”之类提示时，先确认是否把同一个基础模型再次传给了 get_peft_model()，再决定是重新从基础模型加载，还是在明确的生命周期末尾接住 unload() 的返回值。不要仅凭某个属性是否存在就断言 adapter 仍在参与前向计算，应该优先查看当前对象类型、已加载 adapter 名称和实际引用关系。

发布前可以按这张清单判断

• 只想做基础模型对照：用 with model.disable_adapter():。
• 想移除所有 LoRA 模块且不合并：用 plain_model = model.unload()。
• 想删掉一个命名 adapter：保留 PeftModel，调用 delete_adapter("name")。
• 想得到合并后的单体模型：明确选择 merge_and_unload()，不要把它当作普通清理。
• Notebook 重跑：避免旧基础模型引用被再次包装；清理后继续使用返回对象或重新加载干净基础模型。

常见问题

unload 会把 LoRA 权重合并进基础模型吗？

不会。按官方 API 语义，unload() 是移除 adapter 模块并返回基础模型；需要合并权重时应单独选择 merge_and_unload()。

为什么调用 unload 后还要重新赋值？

因为它不是原地操作。继续使用旧的 PeftModel 引用，代码表达的就不是“当前变量已经恢复为基础模型”。

disable_adapter 和 unload 应该怎么选？

只做一次临时对照选 disable_adapter()；要结束 PEFT 生命周期并拿回基础模型选 unload()。前者保留结构，后者返回不含 adapter 模块的模型对象。

删除一个 adapter 后还能继续切换其他 adapter 吗？

可以，只要仍然使用 PeftModel 并且其他 adapter 尚未被删除；删除时传入加载时使用的名称，不要把基础模型名称当作 adapter 名称。

因此，PEFT 的“卸载”首先是对象生命周期问题：临时禁用、移除模块、删除命名项和合并权重分别对应不同 API。把返回值、adapter 名称和 Notebook 变量引用管理清楚，通常就能避免重复注入与误把基础模型当成合并模型的问题。