Unable to resume model training with a locally downloaded model and trust remote code

快速结论：该报错通常出现在使用 trust_remote_code=True 加载带有自定义代码的本地模型后，进行训练 checkpoint 保存/恢复（resume）时。优先检查 checkpoint 目录中是否保留了模型原始目录的自定义 .py 代码文件。

适用环境：Issue 中确认的环境为 Python >=3.12、accelerate>=1.13.0、datasets>=4.8.5、sentence-transformers>=5.4.1、torch>=2.11.0、transformers>=5.8.0；涉及 SentenceTransformer、Transformers Trainer 与 Slurm 多卡训练。操作系统、CUDA、显卡型号在 Issue 中未明确给出。

最快修复方案：该 Issue 最终由 huggingface/transformers PR #46876 修复。可优先尝试升级到包含该修复的 Transformers 版本（例如较新的 main 或对应发布版本），然后重新保存 checkpoint 并恢复训练。

注意事项：Issue 评论中提到的“保存 checkpoint 时复制自定义 .py 文件”只是社区成员提出的修复思路，并非已在 Issue 中验证的手动操作步骤；在无法升级 Transformers 时，可临时手动将模型原始目录中的自定义代码文件复制到 checkpoint 目录再尝试 resume，但这属于推测性规避方案，未在 Issue 中得到确认。

问题场景

用户使用 huggingface_hub.snapshot_download 将模型 voyageai/voyage-4-nano 下载到本地目录，然后用 SentenceTransformer(base_model_path, trust_remote_code=trust_remote_code) 加载，并通过 Transformers Trainer 进行训练。当调用 trainer.train(resume_from_checkpoint=resume) 恢复训练时，由于 checkpoint 目录中缺少自定义远程代码文件，加载 checkpoint 阶段失败。

报错原文

Unable to resume model training with a locally downloaded model and trust remote code

[rank1]: Traceback (most recent call last):
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/train.py", line 236, in <module>
[rank1]:     main()
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/train.py", line 217, in main
[rank1]:     trainer_stats = trainer.train(resume_from_checkpoint=resume)
[rank1]:                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/transformers/trainer.py", line 1415, in train
[rank1]:     self._load_from_checkpoint(resume_from_checkpoint)
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/trainer.py", line 966, in _load_from_checkpoint
[rank1]:     loaded_model = model_class(checkpoint_path, trust_remote_code=self.model.trust_remote_code)
[rank1]:                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/util/decorators.py", line 41, in wrapper
[rank1]:     return func(*args, **kwargs)
[rank1]:            ^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/sentence_transformer/model.py", line 183, in __init__
[rank1]:     super().__init__(
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/model.py", line 198, in __init__
[rank1]:     modules, self.module_kwargs = self._load_modules(
[rank1]:                                   ^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/model.py", line 974, in _load_modules
[rank1]:     return self._load_config_modules(model_name_or_path, **load_kwargs)
[rank1]:            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/model.py", line 1165, in _load_config_modules
[rank1]:     module = module_class.load(
[rank1]:              ^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/modules/transformer.py", line 1708, in load
[rank1]:     return cls(model_name_or_path=model_name_or_path, **init_kwargs)
[rank1]:            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/util/decorators.py", line 87, in wrapper
[rank1]:     return func(*args, **kwargs)
[rank1]:            ^^^^^^^^^^^^^^^^^^^^^
[rank1]:   File "/e/project1/reformo/enrico/slurm-st/.venv/lib/python3.12/site-packages/sentence_transformers/base/modules/transformer.py", line 642, in __init__
[rank1]:     self.model = self._load_model(
[rank1]:                  ^^^^^^^^^^^^^^^^^
...

原因分析

最可能的原因是：当模型通过 trust_remote_code=True 加载、且依赖模型仓库中的自定义代码（例如自定义 modeling_*.py）时，Trainer 在 _save_checkpoint 阶段没有把这些自定义远程代码文件一并复制到 checkpoint 目录中。恢复训练时，_load_from_checkpoint 会以 checkpoint 路径作为 model_name_or_path 重新构造模型，动态模块加载器在 checkpoint 目录里找不到这些自定义文件，导致加载失败。Issue 评论中 Tom 指出这可能与 PR #15379 相关的回归有关，但这一判断未在 Issue 中最终确认。

环境排查

确认 Transformers 版本，是否包含 PR #46876 的修复（Issue 中反馈该问题已由 #46876 修复）。
确认 SentenceTransformers 版本（Issue 中为 >=5.4.1）以及 trust_remote_code 是否在模型构造和 checkpoint 恢复两处都保持一致。
检查本地模型目录（snapshot_download 的目标目录）中是否存在自定义 .py 文件，例如 modeling_*.py、configuration_*.py 等。
检查 checkpoint 目录（resume_from_checkpoint 指向的路径）中是否同样包含上述自定义代码文件。
确认 PyTorch（Issue 中 >=2.11.0）和 accelerate（>=1.13.0）版本；CUDA 与显卡型号在 Issue 中未给出，可自行确认是否与所装 PyTorch 匹配。

解决步骤

优先升级 Transformers 到包含 PR #46876 修复的版本（较新的 main 或对应发布版本），这是 Issue 中维护者确认的修复方向。
升级后，删除旧的（缺少自定义代码文件的）checkpoint，或在新的训练中重新触发一次 checkpoint 保存，使新 checkpoint 包含自定义远程代码文件。
重新运行 trainer.train(resume_from_checkpoint=resume)，确认恢复训练阶段不再在 _load_config_modules / Transfomer.load 处失败。
如暂时无法升级 Transformers，可优先尝试的规避方式是：手动将本地模型原始目录中的自定义 .py 文件复制到对应 checkpoint 目录中，再执行 resume。该方式属于推测性规避，未在 Issue 中验证。

验证方法

再次运行训练脚本，观察 trainer.train(resume_from_checkpoint=resume) 是否能正常完成 checkpoint 加载并继续训练；若原先抛出异常的 _load_from_checkpoint → _load_modules → _load_config_modules → module_class.load 调用链不再报错，且训练进度从 checkpoint 处恢复，即可认为问题已解决。