ValueError: Unable to load scheduler using load method: MiniMaxAI/MiniMax-H3 does not appear to have a file named scheduler_config.json.

问题场景

用户在 Diffusers 0.40.0 中通过 ModularPipeline.from_pretrained(local_dir) 或 blocks.init_pipeline(local_dir) 从本地目录加载 MiniMaxAI/MiniMax-H3 转换检查点，随后调用 load_components() 时触发问题。该模型的 modular_model_index.json 中包含九个 "pretrained_model_name_or_path": "MiniMaxAI/MiniMax-H3" 条目，导致加载器忽略本地 snapshot 目录，转而尝试从 Hub 下载完整仓库（约 134 GB）。在离线模式下，组件加载失败并被置为 None。

报错原文

ValueError: Unable to load scheduler using load method: MiniMaxAI/MiniMax-H3 does not appear to have a file named scheduler_config.json.

原因分析

问题根源在 modular_pipeline.py（v0.40.0）中的路径解析不对称逻辑。可能原因包括：

• 当目录中存在 modular_model_index.json 时（约第 1749 行），每个组件的 spec 会原样从该文件重建（约第 1755 行），其中记录的 Hub 仓库 ID 优先级高于本地目录路径。
• 当不存在 modular_model_index.json 而回退到 model_index.json 时（约第 1768 行），spec 会被构建为 "repo": pretrained_model_name_or_path，即采用本地目录路径——这才是用户期望的行为。
• 官方确认这是“按设计”的行为：加载器根据 modular_model_index.json 中的说明加载每个组件，不猜测意图也不改写路径。

环境排查

• 确认 Diffusers 版本是否为 0.40.0 或更早版本；main 分支在修复前同样受影响。
• 检查 modular_model_index.json 与 model_index.json 中所有 pretrained_model_name_or_path 字段是否指向 Hub 仓库 ID（如 MiniMaxAI/MiniMax-H3）而非本地路径。
• 确认本地 snapshot 是否通过 hf download MiniMaxAI/MiniMax-H3 --local-dir <path> 获取（此类快照不自包含）。
• 检查是否处于离线模式（HF_HUB_OFFLINE=1），该模式下会直接报错而非触发下载。
• 核对 huggingface_hub、PyTorch、Transformers、Accelerate 版本与安装环境。

解决步骤

1. 方案一（官方推荐，可优先尝试）：生成自包含目录。在联网环境下先完整加载模型：
   pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components()
   然后使用 overwrite_modular_index=True 保存为自包含目录：
   pipe.save_pretrained(local_dir, overwrite_modular_index=True)
2. 注意：后续版本行为已变更。根据 #14659 的改动，新版中 overwrite 已默认开启，因此在新版本中 save_pretrained() 会默认生成自包含目录，无需额外传参。
3. 方案二（手动修改索引文件，作为临时 workaround）：将本地 snapshot 中 modular_model_index.json 和 model_index.json 内的九个 pretrained_model_name_or_path 条目全部改为本地路径，然后再执行加载。
4. 方案三（适用于已持有本地快照的用户）：如果在修复发布前已通过 hf download --local-dir 获得快照，并且想要避免二次下载，只能手写修改索引文件，或先临时允许下载完成一次后保存为自包含格式。官方暂无针对已下载快照的“零下载”迁移路径。
5. 升级 Diffusers 版本：检查并升级到包含 #14659 修复的版本，以获得默认 overwrite 行为和更完善的文档说明。

验证方法

执行下列任一方式确认问题已解决：

• 在离线模式（HF_HUB_OFFLINE=1）下运行原始复现脚本，检查 pipe.scheduler 是否成功加载 MiniMaxH3Scheduler 而非 None。
• 使用 save_pretrained(..., overwrite_modular_index=True) 生成自包含目录后，检查新生成的 modular_model_index.json，确认其中的 pretrained_model_name_or_path 已指向本地相对路径而非 Hub ID。
• 在本地目录存在对应 scheduler_config.json 且无网络连接的情况下运行加载，不再出现 ValueError: Unable to load scheduler... 报错。

参考来源

huggingface/diffusers #14640
huggingface/diffusers #14659（overwrite 默认开启的修复）

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。