首页/资讯中心/详情

ComfyUI ControlNet Aux插件模型下载失败？3步彻底解决

ComfyUI ControlNet Aux插件模型下载失败？3步彻底解决
📅 发布时间：2026/6/29 14:48:54

ComfyUI ControlNet Aux插件模型下载失败？3步彻底解决

【免费下载链接】comfyui_controlnet_auxComfyUI's ControlNet Auxiliary Preprocessors项目地址: https://gitcode.com/gh_mirrors/co/comfyui_controlnet_aux

ComfyUI ControlNet Aux插件作为AI绘画创作的核心辅助工具，提供了超过30种图像预处理功能，从边缘检测到深度估计，从姿态识别到语义分割，是提升AI绘画控制精度的利器。然而，许多用户在实际使用中都会遇到模型文件下载失败的困扰，这不仅影响创作效率，更让新手用户望而却步。本文将为您提供从快速诊断到永久解决的完整方案，确保您的ControlNet Aux插件能够顺畅运行。

问题全景：为什么ControlNet Aux模型下载总是失败？

ControlNet Aux插件采用了模块化设计，每个预处理功能都对应独立的预训练模型文件。当您首次使用某个功能时，插件会从Hugging Face等平台自动下载对应的模型文件。下载失败通常表现为以下几种情况：

🔴 常见错误症状

  • 插件节点显示红色错误状态，控制台输出"Connection timeout"或"Network error"
  • 预处理功能完全无法使用，ComfyUI界面提示模型加载失败
  • 下载进度卡在0%或反复尝试后最终失败
  • 特定模型（如DSINE、Depth Anything）下载特别困难

📊 模型文件分布情况根据项目文档，ControlNet Aux依赖的模型文件主要分布在：

  • Hugging Face的lllyasviel/Annotators仓库（约15个核心模型）
  • 其他第三方仓库如LiheYoung/Depth-Anything、hr16/DWPose等
  • 总计超过50个模型文件，大小从几MB到几百MB不等

快速诊断：5分钟定位下载问题根源

在开始修复前，我们需要先确认问题的具体原因。打开ComfyUI的控制台或日志文件，观察错误信息的具体内容：

网络连通性测试

# 测试与Hugging Face的连接 ping huggingface.co # 测试特定模型仓库 curl -I https://huggingface.co/lllyasviel/Annotators

检查配置文件

查看项目根目录下的config.yaml文件（如不存在，复制config.example.yaml）：

annotator_ckpts_path: "./ckpts" # 模型存储路径 custom_temp_path: "" # 临时下载目录 USE_SYMLINKS: False # 是否使用符号链接

🔍 关键检查点

  1. 存储路径权限：确保ComfyUI对ckpts目录有写入权限
  2. 磁盘空间：至少预留5GB空间用于模型缓存
  3. 网络代理：国内用户需要配置代理或使用镜像源

核心解法：3种模型获取策略

方案一：手动下载（最可靠）

对于网络环境不佳的用户，手动下载是最稳定的解决方案：

步骤1：查找模型文件参考项目README.md中的"Assets files of preprocessors"章节，找到对应模型的下载链接。例如：

  • HED边缘检测：https://huggingface.co/lllyasviel/Annotators/blob/main/ControlNetHED.pth
  • Depth Anything深度估计：https://huggingface.co/spaces/LiheYoung/Depth-Anything/blob/main/checkpoints/depth_anything_vitl14.pth

步骤2：创建目录结构在ComfyUI安装目录下创建正确的文件夹结构：

ComfyUI/ ├── custom_nodes/ │ └── comfyui_controlnet_aux/ │ └── ckpts/ # 主模型目录 │ ├── lllyasviel/ │ │ └── Annotators/ # 核心模型仓库 │ ├── LiheYoung/ │ │ └── Depth-Anything/ # 深度估计模型 │ └── hr16/ # DWPose等模型

步骤3：放置模型文件将下载的.pth、.onnx或.torchscript.pt文件放入对应目录，保持文件名与代码中一致。

方案二：配置代理加速

如果希望保持自动下载功能，可以配置网络代理：

Windows用户

# 设置系统代理 set HTTP_PROXY=http://127.0.0.1:7890 set HTTPS_PROXY=http://127.0.0.1:7890 # 或者在ComfyUI启动脚本中添加 python main.py --proxy http://127.0.0.1:7890

Linux/macOS用户

export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890

方案三：使用国内镜像源

对于无法访问国际网络的用户，可以尝试以下方法：

  1. 修改下载源：编辑src/custom_controlnet_aux/util.py文件，将Hugging Face链接替换为国内镜像
  2. 使用离线包：从国内网盘下载完整的模型包，解压到ckpts目录
  3. 配置环境变量：设置HF_ENDPOINT=https://hf-mirror.com

深度优化：配置文件详解与调优

配置文件关键参数

创建或编辑config.yaml文件，优化下载体验：

# 模型存储路径（使用绝对路径更稳定） annotator_ckpts_path: "D:/AI/ComfyUI/custom_nodes/comfyui_controlnet_aux/ckpts" # 临时下载目录（SSD硬盘加速下载） custom_temp_path: "D:/temp" # 禁用符号链接，避免权限问题 USE_SYMLINKS: False # 超时设置（网络不佳时增加） # 在util.py中custom_hf_download函数修改etag_timeout参数

模型下载逻辑解析

ControlNet Aux的下载机制位于src/custom_controlnet_aux/util.py的custom_hf_download函数：

def custom_hf_download(pretrained_model_or_path, filename, cache_dir=temp_dir, ckpts_dir=annotator_ckpts_path, subfolder='', use_symlinks=USE_SYMLINKS): # 1. 检查本地是否已有模型 # 2. 如不存在则从Hugging Face下载 # 3. 支持断点续传和缓存 # 4. 可配置符号链接节省空间

💡 实用技巧

  • 首次使用前，先运行install.bat或pip install -r requirements.txt安装所有依赖
  • 对于大模型文件，可以分批次下载，避免同时下载多个文件
  • 下载失败时，检查ckpts目录下的.incomplete文件并手动清理

长效维护：建立稳定的模型管理方案

模型版本管理

ControlNet Aux的不同版本可能依赖不同模型，建议：

  1. 备份重要模型：将常用模型文件备份到本地或云存储
  2. 版本对应表：记录插件版本与模型文件的对应关系
  3. 增量更新：只下载新增功能的模型，复用已有文件

性能优化建议

🚀 GPU加速配置对于DWPose等计算密集型预处理，启用GPU加速：

# 在config.yaml中配置ONNX执行提供者 EP_list: ["CUDAExecutionProvider", "CPUExecutionProvider"]

📁 目录结构优化

ckpts/ ├── lllyasviel/ │ └── Annotators/ │ ├── ControlNetHED.pth # 2.6MB │ ├── dpt_hybrid-midas-501f0c75.pt # 345MB │ └── ZoeD_M12_N.pt # 71MB ├── LiheYoung/ │ └── Depth-Anything/ │ └── checkpoints/ │ └── depth_anything_vitl14.pth # 335MB └── hr16/ └── DWPose/ └── dw-ll_ucoco_384.onnx # 178MB

故障排除清单

当遇到下载问题时，按此清单逐步排查：

  1. 网络层面

    • 测试ping huggingface.co是否通
    • 检查防火墙和杀毒软件设置
    • 尝试更换网络环境（手机热点测试）

  2. 配置层面

    • 确认config.yaml文件存在且格式正确
    • 检查ckpts目录权限（Windows用户注意管理员权限）
    • 验证磁盘空间充足（>5GB）

  3. 环境层面

    • 运行python -c "import huggingface_hub; print(huggingface_hub.__version__)"
    • 检查Python版本（推荐3.8-3.10）
    • 确认torch和torchvision版本兼容

常见问题快速解答

❓ Q1：为什么部分模型能下载，部分失败？A：不同模型存储在不同服务器，网络对各服务器的访问情况存在差异。深度估计模型通常较大，下载更容易失败。

❓ Q2：手动下载后插件还是不识别怎么办？A：检查以下几点：

  • 文件路径是否正确（对照README.md中的路径）
  • 文件名是否完全一致（包括扩展名）
  • 文件完整性（重新下载验证MD5）
  • 重启ComfyUI使插件重新扫描

❓ Q3：如何验证模型文件是否正确？A：使用以下方法：

  • 文件大小校验（与官方文档对比）
  • 在Python中尝试加载：torch.load('模型路径', map_location='cpu')
  • 运行简单的测试脚本验证功能

❓ Q4：下载太慢，有没有加速方法？A：可以尝试：

  • 使用下载工具（如IDM、Aria2）单独下载大文件
  • 配置系统级代理或VPN
  • 在非高峰时段下载
  • 使用国内镜像源（如hf-mirror.com）

❓ Q5：出现"CUDA out of memory"错误怎么办？A：这通常不是下载问题，而是运行时内存不足：

  • 减小批处理大小（batch size）
  • 使用CPU模式运行部分预处理
  • 升级显卡驱动和CUDA版本
  • 关闭其他占用GPU的程序

终极解决方案：一键安装包

对于希望完全避免下载问题的用户，社区提供了完整的模型包：

  1. 完整模型包：包含所有预训练模型的离线安装包
  2. 增量更新包：仅包含新增或更新的模型文件
  3. 国内网盘镜像：百度网盘、阿里云盘等国内高速下载

获取方式：

  • 访问项目GitCode页面查看"Releases"部分
  • 加入ComfyUI中文社区获取分享链接
  • 关注开发者社交媒体获取更新通知

通过以上系统性的解决方案，您应该能够彻底解决ComfyUI ControlNet Aux插件的模型下载问题。记住，手动下载虽然步骤稍多，但却是最稳定可靠的方法。建立好本地的模型仓库后，您将获得：

  • ✅ 永久可用的预处理功能
  • ✅ 更快的加载速度（无需网络请求）
  • ✅ 离线环境下的完整功能
  • ✅ 稳定的创作体验

现在就开始优化您的ControlNet Aux配置，享受流畅无阻的AI绘画创作体验吧！

【免费下载链接】comfyui_controlnet_auxComfyUI's ControlNet Auxiliary Preprocessors项目地址: https://gitcode.com/gh_mirrors/co/comfyui_controlnet_aux

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考