
Lazy loading is not working properly
快速结论:该问题主要发生在用户执行 import transformers 时,因 Transformers 在导入阶段对多个深度学习后端(TensorFlow、JAX/Flax)进行探测和目录扫描,导致导入时间显著延长(约3.5秒)。优先排查是否安装了多余的后端,并设置环境变量禁用它们。
问题场景
用户在 Python 环境中执行 import transformers 命令,或脚本中导入该库时触发,常见于同时安装了 PyTorch、TensorFlow、JAX/Flax 等多种框架的开发环境。问题在 GitHub Issue #44273 中被报告,后续在 PR #45013 中有修复尝试,但部分用户仍报告存在延迟。
报错原文
time python -c "import transformers"
real 0m3.669s
user 0m4.789s
sys 0m0.311s
预期行为:应小于0.5秒。
原因分析
主要原因为 Transformers 库在导入时执行了昂贵的目录扫描(_create_import_structure_from_path),跨300多个模型目录检查文件结构。当同时安装多个后端(如 TensorFlow、JAX)时,导入过程会尝试探测这些后端的可用性,这是导致延迟的最大单一因素——通常将导入时间从约1秒增加到3.5秒。部分用户的硬件性能差异也可能导致持续延迟,如在 Issue 后续评论中,即便修复后仍有用户遇到约2.7秒的导入时间。
环境排查
- 确认是否安装了多个深度学习后端:PyTorch、TensorFlow、JAX/Flax。
- 确认 Transformers 库版本:尝试升级到最新
main分支或通过 PR #45013 引入的修复版本。 - 运行
python utils/check_import_complexity.py查看导入模块总数(正常应小于1000,如585或595)。 - 检查硬件性能:同一代码在不同机器上可能表现不同。
解决步骤
- 优先尝试:设置环境变量禁用不需要的后端,在导入 Transformers 之前运行:
export TRANSFORMERS_NO_TF=1 export TRANSFORMERS_NO_FLAX=1或在 Python 代码中:
import os os.environ["TRANSFORMERS_NO_TF"] = "1" os.environ["TRANSFORMERS_NO_FLAX"] = "1" import transformers - 如果完全不需要 TensorFlow 或 JAX,可以卸载对应库以加速导入:
pip uninstall tensorflow jax flax - 使用选择性导入替代全量导入,如:
from transformers import AutoModel而非
import transformers。 - 升级到较新版本或基于 PR #45013 修复的版本(如从 GitHub
main分支安装),该修复通过更积极的延迟加载将导入模块数控制在1000以内。 - 运行性能检测脚本以确认优化效果:
python utils/check_import_complexity.py --display查看完整的模块加载树。
验证方法
执行 time python -c "import transformers",观察导入时间是否显著下降。理想情况下应小于0.5秒,如果能稳定在1秒以内或更佳(如0.3-0.4秒),则问题已改善。同时运行 python utils/check_import_complexity.py 确认导入模块数未超过1000的阈值。



