ComfyUI如何加载外部模型库？

Question

在使用ComfyUI时，如何正确加载自定义或第三方模型（如外部Stable Diffusion Checkpoint、LoRA、ControlNet等）是一个常见问题。用户常遇到模型文件已放入指定目录但仍无法在节点中识别的情况。问题通常出在模型路径配置不当、文件命名不规范或未重启ComfyUI导致缓存未更新。此外，某些插件模型需额外依赖库支持，若缺少相应依赖也会导致加载失败。如何确保ComfyUI正确扫描并加载位于自定义目录中的外部模型？特别是在使用Git克隆的社区模型库时，应如何组织文件结构并配置加载路径？

Answer 1

ComfyUI中自定义与第三方模型加载的深度解析

1. 基础概念：ComfyUI模型加载机制概述

ComfyUI作为基于节点的Stable Diffusion图形化界面工具，其模型加载依赖于预设的目录结构和运行时扫描机制。系统在启动时会递归扫描指定路径下的模型文件，并将其注册到可用节点中。

默认情况下，ComfyUI识别以下关键模型类型：

• Checkpoints：主模型权重文件（.ckpt 或 .safetensors）
• LoRA：低秩适配模型（.safetensors）
• ControlNet：条件控制网络（.pth 或 .safetensors）
• Vision Transformers：如IP-Adapter等视觉编码器
• Text Encoders：如CLIP-L/14等文本编码模型

这些模型需放置在models/子目录下对应类别文件夹中，例如models/checkpoints、models/loras等。

2. 文件路径配置与目录结构规范

为确保模型被正确识别，必须遵循标准目录布局。当使用Git克隆社区模型库（如ControlNet官方库）时，推荐采用符号链接或软链接方式集成至ComfyUI环境。

典型项目结构示例如下：

comfyui/
├── models/
│   ├── checkpoints/
│   ├── loras/
│   ├── controlnet/
│   └── ipadapter/
├── custom_nodes/
└── main.py
    

若将外部模型仓库克隆至/external_models/controlnet_v11，可通过创建符号链接实现无缝接入：

ln -s /external_models/controlnet_v11/comfyui_controlnet nodes/custom_nodes/comfyui_controlnet

3. 模型命名规范与元数据兼容性

文件命名不当是导致模型无法识别的主要原因之一。应避免使用空格、特殊字符（#、%、&等），建议采用小写字母加连字符格式。

模型类型	推荐命名格式	错误示例	正确示例
Checkpoint	model_name.safetensors	My Model V2.ckpt	dreamshaper_8.safetensors
LoRA	lora_name.safetensors	[Trained] LoRA #3.pth	character_style_lora.safetensors
ControlNet	control_*.pth/.safetensors	controlnet openpose v2	control_openpose-fp16.safetensors
VAE	*.pt 或 *.ckpt	VAE (fixed).ckpt	kl-f8.pt

4. 缓存机制与热重载策略

ComfyUI在启动时构建模型缓存索引，若新增模型后未重启服务，则可能无法显示。可通过以下两种方式刷新：

1. 重启ComfyUI进程（最可靠）
2. 调用API端点：POST /reload_all 触发重新扫描

部分高级部署环境中可启用自动监控模块，监听models/目录变更事件并动态更新模型列表。

5. 插件依赖管理与Python环境隔离

某些第三方节点（如ComfyUI-Custom-Nodes-Aux）需要额外依赖库支持，常见缺失依赖包括：

• torchvision
• opencv-python-headless
• transformers
• diffusers

建议使用虚拟环境进行依赖管理：

python -m venv comfy_env
source comfy_env/bin/activate
pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu118
pip install opencv-python transformers diffusers
    

6. Git集成与版本化模型管理流程图

对于团队协作或多设备同步场景，推荐通过Git管理模型配置与节点插件。以下是完整的模型集成流程：

graph TD A[克隆社区模型库] --> B{检查requirements.txt} B -->|存在| C[安装依赖] B -->|不存在| D[手动确认依赖项] C --> E[创建符号链接至custom_nodes] D --> E E --> F[验证模型目录结构] F --> G[重启ComfyUI服务] G --> H[在Loader节点中测试加载] H --> I{是否成功?} I -->|是| J[完成集成] I -->|否| K[检查日志输出] K --> L[排查路径/权限/依赖问题] L --> G

7. 日志诊断与调试技巧

当模型未出现在选择列表中时，应优先查看启动日志中的扫描信息。典型成功日志片段如下：

[INFO] Found 3 checkpoints in ./models/checkpoints
[INFO] Loading LoRA: ./models/loras/style_transfer.safetensors
[INFO] Registering ControlNet model: control_depth-fp16.safetensors
    

若出现File not found或Unsupported format提示，则需检查文件完整性及扩展名匹配情况。

进阶调试手段包括：

• 启用详细日志模式：--verbose 参数启动
• 使用os.listdir()脚本验证目录可读性
• 检查文件权限（Linux/macOS）：chmod 644 *.safetensors