ComfyUI 离线部署 ControlNet 预处理器：模型文件下载与路径配置全攻略
1. 为什么需要离线部署ControlNet预处理器？
最近在给客户部署ComfyUI时遇到一个典型场景：他们的生产环境完全隔离外网，但需要用到ControlNet的各类预处理器功能。这让我意识到，很多AI绘画开发者都会面临类似需求——可能是出于数据安全考虑，或是网络条件受限，甚至单纯想避免在线下载的不稳定性。
离线部署的核心痛点其实就两个：模型文件获取和路径配置。先说模型文件，ControlNet的预处理器种类繁多，从人体姿态识别（open_pose）到深度图生成（depth_anything），每种都需要特定的模型文件支持。而ComfyUI默认会尝试从HuggingFace等平台在线下载，这在无网络环境下显然行不通。
更麻烦的是路径配置。我见过不少开发者手动下载了模型文件，却因为放错位置导致ComfyUI无法识别。比如depth_anything的模型必须放在custom_nodes/comfyui_controlnet_aux/ckpts下的特定子目录，这和原始下载链接的层级结构直接相关。下面我会用实测过的方案，带你一步步避开这些坑。
2. 预处理器模型文件下载指南
2.1 主流预处理器模型清单
先列个实战中最高频使用的预处理器清单。每个都需要下载对应的模型文件，注意文件大小从几十MB到几个GB不等：
anime_face_segment（动漫人脸分割）
核心文件：UNet.pth
典型用途：二次元角色面部特征提取
下载技巧：这个模型较小（约200MB），适合先用来测试下载流程densepose（人体3D姿态）
核心文件：densepose_r50_fpn_dl.torchscript
注意点：需要TorchScript格式的版本，普通PyTorch模型不兼容hed（边缘检测）
核心文件：ControlNetHED.pth
实测效果：对服装褶皱等细节捕捉极佳leres（深度估计）
特殊要求：需要同时下载res101.pth和latest_net_G.pth
避坑提示：两个文件缺一不可，且必须保持版本一致
2.2 手动下载的三种方法
方法一：直接浏览器下载
最简单的方式是拼接下载链接。比如要获取hed模型：
https://huggingface.co/lllyasviel/Annotators/resolve/main/ControlNetHED.pth关键技巧是把下载链接中的blob换成resolve，main分支名可能需替换为实际分支。
方法二：用wget命令行
在内网服务器上推荐这种方式：
wget https://huggingface.co/lllyasviel/Annotators/resolve/main/ControlNetHED.pth遇到大文件时可以加-c参数支持断点续传。
方法三：Git LFS克隆
适合需要批量下载的情况：
git lfs install git clone https://huggingface.co/lllyasviel/Annotators注意这会把整个仓库下载下来，建议先确认所需文件位置。
3. 模型文件路径配置详解
3.1 目录结构黄金法则
ComfyUI对ControlNet预处理器的路径要求非常严格，必须遵循这个公式：
ComfyUI/custom_nodes/comfyui_controlnet_aux/ckpts/{原始下载路径的后半部分}举个例子，depth_anything的官方下载链接是：
LiheYoung/Depth-Anything/checkpoints/depth_anything_vitl14.pth那么本地路径就应该是：
ComfyUI/custom_nodes/comfyui_controlnet_aux/ckpts/LiheYoung/Depth-Anything/checkpoints/depth_anything_vitl14.pth我整理了个常见预处理器的路径对照表：
| 预处理器类型 | 原始下载路径片段 | 本地存放路径片段 |
|---|---|---|
| open_pose | lllyasviel/Annotators | lllyasviel/Annotators |
| midas | lllyasviel/Annotators | lllyasviel/Annotators |
| depth_anything | LiheYoung/Depth-Anything/checkpoints | LiheYoung/Depth-Anything/checkpoints |
3.2 验证配置是否成功
启动ComfyUI后，在控制台看到类似这样的日志说明配置正确：
[ControlNet Aux] Loaded anime_face_segment model from: /path/to/UNet.pth如果报Model file not found，检查：
- 路径层级是否完全匹配
- 文件名是否包含多余字符（如下载时自动添加的(1)）
- 文件权限是否正确（Linux/Mac需chmod 644）
4. 常见问题解决方案
4.1 模型加载失败排查
现象一：报错提示SHA256校验失败
这是因为ComfyUI内置了模型文件的预期哈希值。解决方案：
- 确认下载的是官方原版文件
- 或修改源码中的校验逻辑（不推荐）
现象二：CUDA out of memory
部分大模型如depth_anything_vitl14需要至少8GB显存。变通方案：
- 改用小尺寸模型（如vits14）
- 添加
--lowvram参数启动ComfyUI
4.2 加速加载的技巧
符号链接妙用
如果模型存放在NAS等网络存储，可以：ln -s /mnt/nas/models/ControlNetHED.pth ./custom_nodes/comfyui_controlnet_aux/ckpts/lllyasviel/Annotators/预加载到内存
在启动脚本中加入：import torch torch.load('path/to/model.pth')
5. 进阶：自定义预处理器的集成
有时需要用到官方未收录的预处理器。以最近热门的SAM图像分割为例：
- 下载SAM的vit_h模型（sam_vit_h_4b8939.pth）
- 创建新目录：
mkdir -p custom_nodes/comfyui_controlnet_aux/ckpts/facebook/SAM/ - 修改
__init__.py注册新预处理器：register_node( "SAMPreprocessor", "path/to/sam_vit_h_4b8939.pth" )
这种方案我在医疗影像分析项目中成功应用，关键是要确保模型输入输出格式与ControlNet兼容。