【Bug已解决】Detail: removal of.peft_configwhen performing.unload()? 解决方案一、现象长什么样PEFT 的PeftModel.unload()用来“卸载所有 adapter把模型还原回纯基座”。但在实际使用中有个让人困惑的细节model get_peft_model(base, cfg) model.unload() # 期望还原成 base之后会出现这些情况unload()之后对象上仍然挂着.peft_config属性一个存了LoraConfig的字典但模型结构已经不是 PeftModel 了——这个残留的peft_config让后续判断“这到底是不是已卸载”变得含糊卸载后你想再次add_adapter/get_peft_model重新挂 adapter因为.peft_config没被清干净状态机处于“既不是纯 base、又不是正常 PeftModel”的中间态导致KeyError或“重复注入”检查isinstance(model, PeftModel)为 False结构还原了但hasattr(model, peft_config)仍为 True属性残留两份真相互相矛盾merge_and_unload()之后再unload()残留状态更乱有时peft_config里还留着已被合并掉的 adapter 名序列化/复制这个“半卸载”的对象时残留的peft_config被一起 pickle加载回来结构又错。一句话unload()在“还原模型结构”和“清理内部状态尤其是.peft_config”这两件事上没有完全对齐留下了一个语义模糊的中间态。二、背景要理解这个细节得看 PEFT 的PeftModel内部状态self.peft_config一个dict键是adapter_name如default值是对应PeftConfig。它记录了“当前挂了哪些 adapter、各自什么配置”。self.base_model被包装的基座里面各lora.Linear替换了原nn.Linear。unload()做的事遍历所有被替换的模块把lora.Linear还原回原始nn.Linear取出base_layer然后通常把self就地改回 base_model 的结构。问题在于unload()还原结构时不一定同步清掉self.peft_config。于是出现“结构已还原、但peft_config字典还在”的残留。这个残留本身是 PEFT 内部状态对外表现为“我到底是卸载了还是没卸载”。更微妙的是有些版本unload()返回的是 base model 本身不再有 PeftModel 方法和属性有些版本是就地修改self使其表现得像 base。行为不一致让.peft_config的存废也不一致。下面用可运行代码演示这个“结构还原但peft_config残留”的细节并给出干净的清理方式。三、根因根因一句话unload()还原了模型结构lora.Linear → 原 Linear但没有同步、显式地清理/归一化内部状态peft_config留下“结构已还原但状态未还原”的语义模糊中间态。展开结构还原 ≠ 状态还原unload()重挂base_layer但peft_config字典可能仍持有着已不存在的 adapter 配置。行为不一致不同 PEFT 版本unload()是“返回新 base”还是“就地改 self”不同导致peft_config残留与否也不确定。后续操作踩坑基于残留peft_config的判断是否已挂 adapter、能否再 add会得出错误结论。修复方向在unload()之后显式把peft_config归一化清空或保留为只含 base 的空状态并统一“卸载后对象身份”的约定避免中间态。四、最小可运行复现下面用一个自包含的迷你 PeftModel 仿制把“结构还原但peft_config残留”的细节演示清楚不依赖 PEFT 内部版本差异聚焦状态机逻辑。import torch import torch.nn as nn class MiniPeftModel(nn.Module): 简化版结构还原后 peft_config 是否残留复现该细节。 def __init__(self, base, cfg): super().__init__() self.base_model base self.peft_config {default: cfg} # 记录已挂 adapter def unload(self, clear_configTrue): # 这里 base 已是原结构真实 PEFT 会先把 lora.Linear 还原 if clear_config: self.peft_config {} # 显式清空 - 干净 # 真实 PEFT 在此把 self 还原为 base_model我们用返回值模拟 return self.base_model def is_loaded(self): return len(self.peft_config) 0 torch.manual_seed(0) base nn.Linear(16, 16) cfg {r: 4, peft_type: LORA} # 情况 Aunload 不清 peft_config - 残留对应部分版本行为 m MiniPeftModel(base, cfg) restored m.unload(clear_configFalse) print(卸载后 peft_config 残留:, m.peft_config) # {default: {...}} 仍在 print(is_loaded 误判为已加载:, m.is_loaded()) # True错误 # 情况 Bunload 显式清 peft_config - 干净 m2 MiniPeftModel(base, cfg) m2.unload(clear_configTrue) print(卸载后 peft_config 清空:, m2.peft_config) # {} print(is_loaded 正确为 False:, m2.is_loaded()) # False运行后情况 A 显示peft_config残留并导致“误判为已加载”情况 B 显示清空后状态一致。这正是该 issue 想澄清的细节——unload应当把peft_config一并清理。五、解决方案第一层最小直接修复修复 1unload 后显式清空 peft_config如clear_configTrue分支self.peft_config {}让“结构还原”与“状态还原”同步。修复 2用is_loaded()这类统一判断不依赖 hasattr不要写if hasattr(model, peft_config)而是提供明确的状态查询def is_adapter_active(model): pc getattr(model, peft_config, None) return bool(pc) # 空字典 未挂修复 3unload 后若要复用先确认干净model.unload() assert not is_adapter_active(model), unload 后仍有残留 adapter 状态 # 现在可以安全地重新 add_adapter六、解决方案第二层结构性改进改进 1封装一个“确定性 unload”def safe_unload(peft_model): 统一行为卸载并清空所有 adapter 状态。 restored peft_model.unload() # 兜底确保 peft_config 被清 if hasattr(restored, peft_config): restored.peft_config {} return restored改进 2重载后再 add_adapter 前重置状态机def reset_for_reload(model): if hasattr(model, peft_config): model.peft_config.clear() if hasattr(model, active_adapter): model.active_adapter None return model # 用法 model safe_unload(model) reset_for_reload(model) model.add_adapter(fresh, new_cfg) # 干净起步改进 3统一“卸载后对象身份”约定项目里约定unload()之后一律通过返回值拿 base不再用原引用并对返回值做“无 peft_config”断言base model.unload() assert not hasattr(base, peft_config), base 不应残留 peft_config七、解决方案第三层断言 / CI 守护import torch import torch.nn as nn import pytest class MiniPeftModel(nn.Module): def __init__(self, base, cfg): super().__init__() self.base_model base self.peft_config {default: cfg} def unload(self, clear_configTrue): if clear_config: self.peft_config {} return self.base_model def is_loaded(self): return len(self.peft_config) 0 def test_unload_clears_config(): base nn.Linear(16, 16) m MiniPeftModel(base, {r: 4}) m.unload(clear_configTrue) assert m.peft_config {} assert m.is_loaded() is False def test_unload_without_clear_leaves_residue(): base nn.Linear(16, 16) m MiniPeftModel(base, {r: 4}) m.unload(clear_configFalse) assert m.is_loaded() is True # 确认残留确实存在复现 bug 行为 def test_reload_after_clean_unload(): base nn.Linear(16, 16) m MiniPeftModel(base, {r: 4}) m.unload(clear_configTrue) # 模拟重新 add m.peft_config[fresh] {r: 8} assert m.is_loaded() is True def test_returned_base_has_no_peft_config(): base nn.Linear(16, 16) m MiniPeftModel(base, {r: 4}) restored m.unload(clear_configTrue) # 真实场景里 restored 是 base这里 base 本就没有 peft_config assert not hasattr(base, peft_config)这四个测试守护“unload 清空 config、不留清则残留、清后可重载、返回的 base 无残留”。八、排查清单遇到unload()后状态混乱时按序查检查peft_config是否残留hasattr(model, peft_config)且len 0即说明没清干净。统一用is_loaded()判断别用hasattr猜用“peft_config 是否为空”作唯一真相。unload 后显式清空model.peft_config {}兜底。用返回值拿 basebase model.unload()原引用不再信任。重载前 reset 状态机peft_config.clear()active_adapterNone。reload 后确认干净assert not is_adapter_active(model)。版本差异不同 PEFT 版本unload()行为不同封装safe_unload屏蔽差异。序列化前清理pickle 前确保无残留peft_config避免加载回来结构错。九、小结removal of .peft_config when performing .unload()的细节是unload()还原了模型结构lora.Linear → 原 Linear却没有同步、显式地清理内部状态peft_config留下“结构已还原但状态未还原”的语义模糊中间态导致“究竟卸载没卸载”的判断自相矛盾、重载时踩坑。**最小修复是**unload()后显式清空peft_config并用统一的is_loaded()看 peft_config 是否为空代替hasattr判断**结构性改进是封装safe_unload、重载前reset_for_reload清状态机、统一“卸载后通过返回值拿 base”的约定最后用测试守护“unload 清空 config、不留清则残留、清后可重载、返回 base 无残留”。把结构与状态同步清理unload 的语义就干净了。