ComfyUI下载checkpoints时模型加载失败如何解决？

Question

在使用ComfyUI下载并加载Checkpoints模型时，常出现“模型加载失败”的错误，提示如“Failed to load model: invalid file”或“Unknown format”。该问题多因模型文件未完整下载、保存路径错误或格式不兼容所致。常见情况是用户将模型存放于非`models/checkpoints`目录，或文件损坏、扩展名不符（如.part残留）。此外，部分自定义节点或ComfyUI Manager插件更新滞后，也可能导致解析失败。需检查文件完整性、校验SHA256值，并确保使用与ComfyUI兼容的稳定扩散模型格式（如.ckpt或.safetensors）。

Answer 1

ComfyUI中Checkpoints模型加载失败的深度解析与系统性解决方案

1. 问题现象与初步诊断

在使用ComfyUI加载Stable Diffusion Checkpoint模型时，用户常遇到如下错误提示：

• Failed to load model: invalid file
• Unknown format
• Model not found in expected directory

这些提示通常指向文件读取或解析阶段的中断。最直观的原因包括模型未完整下载、存放路径错误或文件扩展名异常（如残留的.part后缀）。

2. 文件存储路径规范与目录结构校验

ComfyUI遵循严格的模型目录管理机制。所有Checkpoints模型必须置于指定路径下才能被正确识别：

    <comfyui_root>/
    └── models/
        └── checkpoints/
            ├── model_v1.safetensors
            ├── model_legacy.ckpt
            └── custom_model_v2.safetensors
    

若模型文件被放置于custom_models、backup或其他非标准路径，则加载器将无法扫描到该文件，导致“模型未找到”错误。

3. 模型文件完整性验证流程

网络传输中断可能导致模型仅部分下载。此时文件系统中会残留临时片段，例如：

文件名	状态	说明
realisticVision.safetensors.part	未完成	下载中断残留
dreamshaper_8.safetensors	已完成	正常可加载
protogenX5.ckpt.tmp	临时文件	应手动清理

4. 格式兼容性分析：.ckpt vs .safetensors

尽管两者均为PyTorch序列化格式，但存在本质差异：

• .ckpt：基于pickle的旧格式，存在反序列化安全风险，已被主流平台逐步弃用。
• .safetensors：由Hugging Face开发，采用内存映射和静态解析，加载更快且无执行代码风险。

ComfyUI优先支持.safetensors，某些自定义节点可能完全不支持.ckpt格式。

5. SHA256校验：确保文件一致性

为验证模型完整性，建议在终端执行SHA256哈希比对：

# Linux/macOS
shasum -a 256 models/checkpoints/dreamshaper_8.safetensors

# Windows (PowerShell)
Get-FileHash -Algorithm SHA256 models\checkpoints\dreamshaper_8.safetensors

将输出结果与模型发布页提供的校验值对比，不一致则说明文件损坏或被篡改。

6. 自定义节点与插件版本冲突排查

部分第三方节点（如ComfyUI-Custom-Nodes-Pack）依赖特定版本的模型解析库。当ComfyUI核心更新而插件未同步时，可能出现解析异常。

推荐检查流程：

1. 确认ComfyUI主分支为最新稳定版（GitHub main）
2. 运行git submodule update --init --recursive
3. 通过ComfyUI Manager更新所有自定义节点
4. 清除浏览器缓存并重启服务

7. 加载失败的调试日志分析

启动ComfyUI时添加--verbose参数可输出详细加载信息：

[INFO] Loading checkpoint: realisticVision.safetensors
[WARNING] Failed to mmap model file - falling back to copy
[ERROR] Invalid magic number in safetensors header
[FAIL] Model loading aborted: unknown format
    

其中“Invalid magic number”明确指示文件头部非safetensors标准结构，极可能是损坏或伪装文件。

8. 系统级环境因素考量

除应用层配置外，还需关注底层环境：

• 磁盘空间不足导致写入截断
• NTFS/FAT32文件系统对大文件（>4GB）支持差异
• Docker容器内挂载卷权限限制
• 杀毒软件锁定正在写入的模型文件

9. Mermaid流程图：模型加载诊断决策树

graph TD
    A[模型加载失败] --> B{文件在models/checkpoints?}
    B -- 否 --> C[移动至正确路径]
    B -- 是 --> D{扩展名为.ckpt或.safetensors?}
    D -- 否 --> E[重命名或转换格式]
    D -- 是 --> F[执行SHA256校验]
    F --> G{哈希匹配?}
    G -- 否 --> H[重新下载]
    G -- 是 --> I[检查自定义节点版本]
    I --> J{是否最新?}
    J -- 否 --> K[更新插件]
    J -- 是 --> L[启用--verbose调试模式]
    L --> M[分析日志输出]

10. 高级建议：构建自动化校验流水线

对于企业级部署或频繁模型迭代场景，建议集成CI/CD风格的模型验证机制：

# 示例：Python脚本批量校验 import hashlib def sha256sum(filename): h = hashlib.sha256() with open(filename, "rb") as f: while chunk := f.read(8192): h.update(chunk) return h.hexdigest() for model in os.listdir("models/checkpoints"): print(f"{model}: {sha256sum(model)}")

结合预设白名单哈希值，实现自动化的模型可信度评估。