QwenLM/Qwen项目中微调Qwen-1.8B模型后Tokenizer加载问题的分析与解决

在使用QwenLM/Qwen项目进行Qwen-1.8B模型微调后，部分开发者遇到了一个典型的模块导入错误：ModuleNotFoundError: No module named 'transformers_modules.qwen_1'。这个问题虽然看似简单，但背后涉及Hugging Face Transformers库的动态模块加载机制和模型命名的规范性问题。

问题现象

当开发者完成Qwen-1.8B模型的微调后，尝试使用AutoTokenizer.from_pretrained()加载tokenizer时，系统抛出模块未找到的错误。错误信息明确指出Python解释器无法在transformers_modules命名空间下找到名为qwen_1的模块。

根本原因分析

经过深入排查，发现问题的根源在于模型checkpoint文件夹的命名方式。Hugging Face Transformers库在处理模型名称时，会将点号(".")转换为下划线("_")，这是Python模块导入系统的限制所致。当checkpoint文件夹名称包含点号（如"Qwen-1.8B"）时，Transformers库会尝试将"1.8B"转换为"1_8B"，但在某些情况下这种转换可能不完全或不一致，导致动态模块加载失败。

解决方案

解决此问题的方法非常简单但有效：

1. 将包含点号的checkpoint文件夹名称改为使用下划线
2. 例如将"Qwen-1.8B"重命名为"Qwen-1_8B"

这种命名方式既符合Python模块命名规范，又能确保Transformers库正确识别和加载模型相关的tokenizer和配置。

技术背景

Hugging Face Transformers库实现了一种动态模块加载机制，它会根据模型名称自动查找并加载对应的模型类、tokenizer类和配置类。这一机制依赖于Python的标准模块导入系统，而Python模块名称不允许包含点号（除了作为包分隔符），因此库内部会进行名称转换。

当模型名称包含特殊字符时，这种转换可能出现问题。特别是在以下场景：

• 模型名称包含多个点号
• 模型名称以数字开头
• 模型名称包含连字符等其他特殊字符

最佳实践建议

为了避免类似问题，建议在模型开发和微调过程中遵循以下命名规范：

1. 使用下划线代替点号和其他特殊字符
2. 避免使用纯数字开头的名称
3. 保持名称简洁且具有描述性
4. 在整个项目中使用一致的命名约定

对于Qwen系列模型，可以考虑采用如"Qwen_1_8B"或"Qwen1_8B"这样的命名方式，既清晰又符合Python模块命名规范。

总结

这个问题虽然解决起来简单，但它提醒我们在深度学习项目中对文件和目录命名的重要性。遵循Python模块命名规范不仅能避免技术问题，还能提高代码的可维护性和可移植性。对于使用Hugging Face生态系统的开发者来说，理解Transformers库的动态加载机制有助于更快地诊断和解决类似问题。