解决HuggingFace PEFT库中LoraConfig的exclude_modules参数错误问题

在使用HuggingFace的PEFT(Parameter-Efficient Fine-Tuning)库进行模型微调时，开发者可能会遇到一个常见的错误："TypeError: LoraConfig.init() got an unexpected keyword argument 'exclude_modules'"。这个问题通常发生在尝试加载使用较新版本PEFT库训练的LoRA适配器时。

问题背景

PEFT库提供了参数高效的微调方法，其中LoRA(Low-Rank Adaptation)是一种流行的技术。当开发者尝试加载一个使用较新版本PEFT训练的LoRA适配器时，可能会遇到上述错误。这是因为较新版本的PEFT引入了exclude_modules参数，而旧版本不支持这个参数。

问题原因

这个错误的核心原因是版本不匹配。具体来说：

1. 适配器是使用PEFT的主分支(开发版本)训练的，其中包含了exclude_modules参数
2. 而当前环境中安装的是PEFT的稳定版本(如0.13.2)，该版本尚未包含这个新参数

解决方案

针对这个问题，有以下几种解决方法：

方法一：升级PEFT到开发版本

最直接的解决方案是将PEFT升级到最新的开发版本：

pip uninstall peft
pip install git+https://github.com/huggingface/peft

这将安装包含exclude_modules参数的最新开发版本(如peft-0.13.3.dev0)。

方法二：手动修改适配器配置

如果不想升级PEFT版本，可以手动编辑适配器的配置文件adapter_config.json，删除其中的exclude_modules相关行。

方法三：等待官方发布新版本

PEFT团队正在努力使配置向前兼容，未来版本将能自动处理这类问题。开发者可以关注官方更新。

相关注意事项

在使用LoRA进行微调时，还需要注意以下几点：

1. 模块名称匹配：确保modules_to_save中指定的模块名称与模型实际结构完全一致。例如，对于Qwen2.5模型，正确的嵌入层名称是embed_tokens而非embed_token。

2. 词汇表大小：如果微调过程中修改了词汇表(如添加特殊token)，需要确保modules_to_save包含lm_head和embed_tokens，并且正确调整了嵌入层大小。

3. 版本一致性：训练和推理时应使用相同版本的PEFT库，以避免因版本差异导致的问题。

总结

PEFT库的LoRA技术为大型语言模型的高效微调提供了强大支持。遇到exclude_modules参数错误时，开发者可以通过升级PEFT版本或手动修改配置来解决。随着PEFT库的持续发展，这类兼容性问题将逐步减少，为开发者提供更流畅的体验。