Nunchaku ComfyUI加载模型失败如何解决？

Question

问题：在使用 Nunchaku ComfyUI 时，加载自定义模型经常出现“Model not found”或“Failed to load checkpoint”错误，导致工作流中断。该问题多发生在配置路径不正确、模型文件权限受限或版本不兼容的情况下。即使模型文件已放置于 `models/checkpoints` 目录，界面仍无法识别。此外，部分用户反馈启用插件或自定义节点后，模型加载过程会无响应或卡死。如何排查并解决此类模型加载失败问题？

Answer 1

1. 常见错误现象与初步排查

在使用 Nunchaku ComfyUI 加载自定义模型时，用户频繁遇到“Model not found”或“Failed to load checkpoint”等报错。这些提示通常出现在工作流执行初期，尤其是在加载 Checkpoint 节点时触发。

• 模型文件虽已放置于 models/checkpoints/ 目录，但前端界面未刷新显示。
• 手动输入模型路径后仍提示无法找到模型文件。
• 部分情况下，界面卡死在“Loading...”状态，无进一步日志输出。

初步判断应从文件路径、权限设置和基础配置入手。

2. 文件系统层级排查：路径与权限校验

确保模型文件的物理路径正确且可访问是首要步骤。Nunchaku ComfyUI 默认扫描 models/checkpoints 目录下的 .ckpt 或 .safetensors 文件。

检查项	建议操作	验证命令（Linux/macOS）
文件是否存在	确认模型文件实际存在于目标目录	ls models/checkpoints/ | grep your_model
读取权限	确保运行 ComfyUI 的用户有读权限	chmod 644 models/checkpoints/*.safetensors
符号链接问题	避免使用软链指向外部存储设备	readlink -f models/checkpoints/model.ckpt

3. 配置文件与环境变量深度分析

Nunchaku ComfyUI 支持通过配置文件自定义模型搜索路径。若修改过 config.json 或启动脚本中的路径映射，可能导致索引失效。

{
  "checkpoint_paths": [
    "./models/checkpoints",
    "/external/models/diffusion"
  ],
  "disable_mmap_load": false
}

注意：disable_mmap_load 若设为 true，在某些低内存环境下会导致加载失败或卡顿。

4. 模型格式与版本兼容性检测

并非所有 PyTorch 保存的模型都能被 ComfyUI 正常加载。需验证模型是否为标准格式：

1. 使用 Python 脚本验证模型可读性：

import torch
try:
    ckpt = torch.load("models/checkpoints/model.safetensors", map_location='cpu')
    print("Model loaded successfully")
except Exception as e:
    print(f"Load failed: {e}")

常见不兼容原因包括：混合精度训练权重、非标准 state_dict 结构、由非主流框架导出（如 TensorFlow 转换而来）。

5. 插件与自定义节点干扰分析

启用第三方插件（如 ComfyUI-Custom-Nodes）可能劫持模型加载流程。部分节点会在初始化时预加载全部模型，造成资源争用。

可通过以下方式隔离问题：

• 临时重命名 custom_nodes 文件夹以禁用所有插件。
• 逐一启用插件，定位冲突源。
• 查看日志中是否有类似 [CustomNode] Overriding load_checkpoint 的钩子信息。

6. 日志追踪与调试流程图

完整的模型加载失败排查路径可通过如下 Mermaid 流程图表示：

graph TD
      A[出现 Model not found 错误] --> B{模型文件存在?}
      B -- 否 --> C[检查路径拼写与挂载情况]
      B -- 是 --> D{有读权限?}
      D -- 否 --> E[调整 chmod / chown]
      D -- 是 --> F{能否用 torch.load 打开?}
      F -- 否 --> G[模型损坏或格式异常]
      F -- 是 --> H{启用自定义节点?}
      H -- 是 --> I[逐个禁用排查]
      H -- 否 --> J[检查 config.json 路径配置]
      J --> K[重启服务并刷新浏览器缓存]

7. 内存与硬件资源瓶颈处理

大模型（如 >7B 参数）在加载时可能因显存不足导致进程冻结而非抛出明确异常。此时可通过以下手段诊断：

• 监控 GPU 使用率：nvidia-smi
• 限制并发加载数量，在 execution.py 中调整队列大小。
• 启用 CPU 卸载（offload）策略，减少 VRAM 压力。

此外，SSD 读取速度慢也可能导致长时间“卡死”，建议将模型置于 NVMe 固态硬盘上。

8. 缓存机制与前端同步问题

ComfyUI 前端依赖后端返回模型列表，若缓存未更新，即使文件已放入目录也不会显示。

解决方法：

1. 重启 ComfyUI 服务。
2. 清除浏览器缓存或使用无痕模式访问。
3. 调用 API 强制刷新：GET /folder_paths?folder_name=checkpoints
4. 检查后端日志是否输出：Found X checkpoints under ./models/checkpoints

若该行未出现，则说明扫描机制未生效，需检查 Python 文件遍历逻辑。

9. 高级调试技巧：Hook 与动态注入

对于复杂场景，可在 folder_paths.py 中插入调试语句：

# 在 get_filename_list 函数内添加
print(f"[DEBUG] Scanning path: {full_folder}", os.listdir(full_folder))

也可使用 strace -e openat python main.py 追踪文件系统调用，确认程序是否尝试打开目标模型。

结合 lsof | grep .safetensors 可查看当前被锁定的模型文件。

10. 自动化检测脚本建议

为提升运维效率，推荐构建自动化健康检查脚本：

#!/bin/bash
MODEL_DIR="models/checkpoints"
if [ ! -d "$MODEL_DIR" ]; then
  echo "ERROR: Model directory missing"
  exit 1
fi

for model in $MODEL_DIR/*.safetensors; do
  if ! python -c "import torch; torch.load('$model', map_location='cpu')" 2>/dev/null; then
    echo "CORRUPTED: $model"
  fi
done

此脚本可用于 CI/CD 环境或部署前验证。