3步解决ComfyUI ControlNet Aux插件模型下载失败问题

3步解决ComfyUI ControlNet Aux插件模型下载失败问题

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

ControlNet Aux作为ComfyUI的核心预处理插件，为AI图像生成提供了20+种控制信号生成能力。然而，模型下载失败是用户最常遇到的障碍。本文提供一套快速诊断与解决方案，帮助你在5分钟内完成模型配置。

问题诊断：为什么模型下载总是失败？

深度估计预处理器的完整工作流展示，模型下载是第一步

ControlNet Aux插件依赖Hugging Face Hub下载预训练模型，失败原因通常集中在三个层面：

1. 网络环境问题：国内访问Hugging Face不稳定，连接超时
2. 配置路径错误：模型存储路径权限不足或路径过长
3. 依赖缺失：缺少必要的Python包或版本不兼容

快速检查清单

• 网络能否访问huggingface.co
• ckpts文件夹是否有写入权限
• 环境变量AUX_ANNOTATOR_CKPTS_PATH是否正确设置
• 配置文件config.yaml是否存在且格式正确

方案对比：三种解决路径任选其一

实操步骤：按需选择适合你的方案

方案一：基础配置修复（推荐新手）

步骤1：验证依赖安装

# 进入插件目录 cd /path/to/ComfyUI/custom_nodes/comfyui_controlnet_aux # 检查关键依赖 pip list | grep -E "torch|huggingface_hub|opencv-python" # 如有缺失，重新安装 pip install -r requirements.txt

步骤2：配置文件设置

# 创建或编辑 config.yaml annotator_ckpts_path: "./ckpts" custom_temp_path: "/tmp/controlnet_aux" USE_SYMLINKS: False

步骤3：路径权限修复

# 确保ckpts目录存在且有写入权限 mkdir -p ckpts chmod 755 ckpts # 检查路径长度（Windows需<255字符） echo "当前路径: $(pwd)"

方案二：代理环境配置（网络受限环境）

步骤1：设置环境变量

# Linux/macOS export HTTP_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://127.0.0.1:7890" # Windows PowerShell $env:HTTP_PROXY="http://127.0.0.1:7890" $env:HTTPS_PROXY="http://127.0.0.1:7890"

步骤2：配置Hugging Face镜像

# 设置镜像源 export HF_ENDPOINT="https://hf-mirror.com" # 或修改huggingface配置 huggingface-cli config set cache_dir /path/to/cache huggingface-cli config set endpoint https://hf-mirror.com

步骤3：验证连接

# 测试Hugging Face连接 python -c "from huggingface_hub import HfApi; api = HfApi(); print(api.list_models(search='ControlNet'))"

方案三：手动下载部署（离线环境）

步骤1：定位模型文件查看源码中的模型定义，如src/custom_controlnet_aux/util.py：

HF_MODEL_NAME = "lllyasviel/Annotators" DWPOSE_MODEL_NAME = "yzd-v/DWPose" DENSEPOSE_MODEL_NAME = "LayerNorm/DensePose-TorchScript-with-hint-image"

步骤2：手动下载模型

# 使用wget或浏览器下载 # 主模型仓库：https://huggingface.co/lllyasviel/Annotators # 具体文件如：ControlNetHED.pth、body_pose_model.pth等 # 创建对应目录结构 mkdir -p ckpts/lllyasviel/Annotators mkdir -p ckpts/yzd-v/DWPose

步骤3：文件放置规则

ckpts/ ├── lllyasviel/ │ └── Annotators/ │ ├── ControlNetHED.pth │ ├── body_pose_model.pth │ └── hand_pose_model.pth └── yzd-v/ └── DWPose/ ├── yolox_l.onnx └── dw-ll_ucoco_384.onnx

效果验证：确认模型加载成功

多种预处理器的输出效果对比，验证模型加载成功

验证步骤1：运行测试脚本

# 创建测试脚本 test_load.py import sys sys.path.append('/path/to/comfyui_controlnet_aux') from custom_controlnet_aux.hed import HEDdetector try: detector = HEDdetector.from_pretrained() print("✅ HED模型加载成功！") except Exception as e: print(f"❌ 模型加载失败: {e}")

验证步骤2：检查模型文件

# 查看已下载的模型 find ckpts -name "*.pth" -o -name "*.onnx" -o -name "*.pt" | head -20 # 检查文件大小（正常应>10MB） ls -lh ckpts/lllyasviel/Annotators/*.pth

验证步骤3：ComfyUI界面验证

1. 启动ComfyUI
2. 添加"AIO Aux Preprocessor"节点
3. 选择任意预处理器（如"Canny Edge"）
4. 连接图像输入，观察是否正常输出处理结果

常见错误排查表

高级配置：优化下载体验

启用符号链接节省空间

# config.yaml 中设置 USE_SYMLINKS: True annotator_ckpts_path: "/absolute/path/to/ckpts"

自定义缓存目录

# 设置环境变量 export AUX_TEMP_DIR="/path/to/large/disk/temp" export HF_HOME="/path/to/huggingface/cache"

批量预下载常用模型

# pre_download_models.py from custom_controlnet_aux.util import custom_hf_download models = [ ("lllyasviel/Annotators", "ControlNetHED.pth"), ("lllyasviel/Annotators", "body_pose_model.pth"), ("yzd-v/DWPose", "yolox_l.onnx"), ] for repo_id, filename in models: try: path = custom_hf_download(repo_id, filename) print(f"✅ 下载成功: {filename}") except Exception as e: print(f"❌ 下载失败 {filename}: {e}")

通过以上三步操作，你可以快速诊断并解决ComfyUI ControlNet Aux插件的模型下载问题。记住核心要点：检查网络→验证配置→手动备用，这三个环节覆盖了99%的下载失败场景。如果问题依旧，建议查看ComfyUI日志文件或项目GitHub Issues获取社区支持。

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