技术手册 /
ComfyUI 本地部署 /
模型依赖与目录规范（权重放哪）
模型依赖与目录规范（权重放哪）
12-ComfyUI 本地部署 · 2026-10-12 · 4.2 KB
本地 ComfyUI 跑不通，九成是权重没放对。本篇讲清"放哪、怎么核对、放错会怎样"。
本专题手工维护；⚠ 唯一由脚本生成的是 02-模型依赖总表.md（逐模板清单 ✓）。
一、三条铁律（先记住）
- 放对分类目录：权重必须放进
ComfyUI\models\下对应的分类子目录（放错＝等于没放 ✗） - 文件名不要改：依赖表里写的是确切文件名 ⇒ 改名后引擎找不到 ✓（重命名要连依赖声明一起改，做不到就别改）
.part是没下完：看到.part后缀 ⇒ 重新下载/续传，⛔ 别硬跑 ✗
包内 ComfyUI\models\ 下已经建好几十个分类目录（checkpoints / loras / vae / diffusion_models / text_encoders / clip / controlnet / upscale_models / ipadapter / insightface / facerestore_models / TTS / LLM …）
⇒ 你只需把文件放进对应目录；某个分类确实没有 ⇒ 新建同名目录即可 ✓
二、常见权重 → 放哪个目录（用户视角对照表）
| 你下载到的东西（通常长这样） | 放进 |
|---|---|
主模型 / 大模型（_bf16.safetensors、_fp8.safetensors、-int4*.safetensors） | models\diffusion_models\（老式全家桶模型才是 models\checkpoints\ ⇒ 以依赖表为准） |
LoRA（_v1.safetensors、-LoRA-*.safetensors） | models\loras\ |
VAE（ae.safetensors、_vae.safetensors） | models\vae\ |
文本编码器（qwen_.safetensors、gemma_.safetensors、t5xxl*.safetensors） | models\text_encoders\（少数版本在 models\clip\ ⇒ 见 §三） |
CLIP Vision（clip_vision*.safetensors） | models\clip_vision\ |
ControlNet（controlnet.safetensors） | models\controlnet\ |
放大 / 超分模型（RealESRGAN_.pth、upscaler*.safetensors） | models\upscale_models\ |
潜空间放大器（spatial-upscaler、latent-upscale） | models\latent_upscale_models\ |
IPAdapter（ip-adapter*.safetensors） | models\ipadapter\ |
换脸（inswapper_128.onnx） | models\insightface\ |
换脸（reswapper_256.onnx） | models\reswapper\ |
人脸修复（GFPGANv.pth、codeformer.pth） | models\facerestore_models\ |
| GGUF 量化权重 | 与同族普通权重同一个目录（如 diffusion_models\） |
语音 / TTS 相关（SenseVoiceSmall、voxcpm、Qwen3-TTS-*） | models\SenseVoice\ · models\voxcpm\ · models\Qwen3-TTS-Models\（按依赖表） |
| 视频超分（SEEDVR2 系） | models\SEEDVR2\ |
语言模型（llm、LLM） | models\LLM\ |
去背景 / 抠图（rembg、lama、vitmatte、sam3 系） | models\rembg\ · models\lama\ · models\vitmatte\ · models\sam3\ |
⚠ 拿不准就查 02-模型依赖总表.md：它按模板列出每个必需权重的确切文件名与目标目录（唯一权威 ✓）
三、ComfyUI 报错里出现 xxx_name 时，该放哪个目录
运行失败时常看到"找不到 xxx_name"这类提示 —— 它说的是要找的字段，对应目录如下：
| 报错里的字段 | 大概率要放这里 | 备注 |
|---|---|---|
ckpt_name | models\checkpoints\ | 全家桶式大模型 |
unet_name / svd_name | models\diffusion_models\ | 分离式（只含扩散部分） |
lora_name | models\loras\ | |
vae_name | models\vae\ | |
clip_name（含 clip_name1..4） | models\text_encoders\（部分版本是 models\clip\） | ⚠ 两套口径都真实存在 ⇒ 按报错目录提示放；不确定时两个目录各放一份 ✓ |
clip_vision_name | models\clip_vision\ | |
control_net_name | models\controlnet\ | |
model_name | models\upscale_models\（少数是 models\checkpoints\） | 同上：按提示放，必要时两边都放 ✓ |
ipadapter_file | models\ipadapter\ | |
swap_model | models\insightface\ | inswapper_128.onnx |
face_restore_model | models\facerestore_models\ | GFPGAN / CodeFormer |
⚠ 目录型权重：依赖表里有不带扩展名的条目（例如 LTX23_video_vae_bf16）—— 那是一个目录，不是单文件 ⇒ 把整个目录放进去 ✓
四、最容易放错的 5 处（按踩坑频率）
diffusion_models↔checkpoints：新式模板（如 Z-Image、LTX、Qwen-Image）用分离式权重 ⇒ 放diffusion_models；老全家桶才放checkpointstext_encoders↔clip：两者都出现过（同一类文件）⇒ 报错时按提示；不确定就两个目录都放一份（占空间但一定对）upscale_models↔latent_upscale_models：普通放大 vs 潜空间放大，不是同一种，别混 ✓- 换脸三兄弟：
insightface（inswapper_128.onnx）·reswapper（reswapper_256.onnx）·facerestore_models（GFPGAN/CodeFormer）—— 三个都要各自放对 ✓ - 音频/TTS 各子目录：
TTS/Qwen3-TTS-Models/SenseVoice/voxcpm是不同节点族 ⇒ 按依赖表放 ✓
📄 包内还有一份"需自行下载"的说明（在 models\facerestore_models\ 目录里）：换脸相关的几个权重不随包提供，要自己下载并按它写的目录放 ✓
它同时写明本产品的原则：节点（程序）与模型（权重）分离，出厂只带节点代码 ⇒ 权重由你按需补齐 ✓
五、想和已有 ComfyUI 共用权重（不用复制两份）
包内提供了 ComfyUI\extra_model_paths.yaml.example（官方模板）：
- 把它改名为
extra_model_paths.yaml（去掉.example） - 按里面注释填你已有的 models 根路径
- 重启 ComfyUI 生效
⇒ 适合"我已经有别的 ComfyUI + 一堆权重"的老用户 ✓；⚠ 路径要写对、且那个目录结构要与本包一致 ✓
六、核对清单（放完权重跑一遍）
- [ ] 文件放进依赖表写的那个目录（不是"看起来像"的目录）
- [ ] 文件名没改、没有
.part - [ ] 目录型权重放的是整个目录
- [ ] 跑启动器 → 看缺失检测是否还有红项
- [ ] 应用 → 设置 → 本地 ComfyUI → 「引擎自检」看节点/服务是否正常
- [ ] 仍然失败 ⇒ 去任务详情/日志里看它到底在哪个目录找哪个文件（照报错放，最快 ✓）
来源：E:/workbuddyProj/unlimitCanvas/ai_manual/comfyui_local/01-模型依赖与目录规范.md