避坑指南:HunyuanImage_2.1_ComfyUI常见12个疑难问题(模型加载失败、显存不足、画质差等)一次讲清
避坑指南:HunyuanImage_2.1_ComfyUI常见12个疑难问题(模型加载失败、显存不足、画质差等)一次讲清
HunyuanImage_2.1_ComfyUI 是腾讯 HunyuanImage 2.1 文生图大模型面向 ComfyUI 的官方重打包模型文件仓库,内含扩散模型、文本编码器与 VAE 三类共 11 个模型文件。本文整理了新手在 ComfyUI 中部署它时最常踩的 12 个坑——模型加载失败、显存不足、画质差、中文字乱码等,并逐一给出解决方案,帮你一次配通。
一、先认清仓库:11 个模型文件都放在哪
本仓库只做一件事:把 HunyuanImage 2.1 的模型按 ComfyUI 的目录规范拆分打包。下载后把 split_files 下的三个目录整体拷入 ComfyUI/models/ 即可,官方放置规范见 README.md:
📂 ComfyUI/models/
├── 📂 diffusion_models/ 扩散模型(6 个)
├── 📂 text_encoders/ 文本编码器(3 个)
└── 📂 vae/ VAE(2 个)
三类文件速览:
| 类别 | 目录 | 作用 |
|---|---|---|
| 扩散模型 | split_files/diffusion_models/ | 核心生图模型,有 bf16 / fp8 / distilled(蒸馏加速)/ refiner(精修)四个版本 |
| 文本编码器 | split_files/text_encoders/ | 理解提示词,主力是 Qwen 2.5 VL 7B,另有负责画面内文字的 ByteT5(GlyphXL) |
| VAE | split_files/vae/ | 把潜空间解码回图像,主模型与 refiner 各配一个 |
💡 提示:仓库文件通过 Git LFS 存储,下载方式直接影响文件是否完整,这也是下面第 2 个坑的根源。
二、模型放置与加载问题(坑 1~4)
1. 模型加载失败:加载器下拉框里找不到模型
绝大多数"加载失败"其实只是放错了目录。请核对:
- 扩散模型必须在
ComfyUI/models/diffusion_models/ - 文本编码器必须在
ComfyUI/models/text_encoders/ - VAE 必须在
ComfyUI/models/vae/
三类文件互相不能混放。放好后重启 ComfyUI(或在界面点击刷新),下拉框才会出现新模型。
2. 下载方式不对:文件只有几 KB?
本仓库的 .safetensors 全部走 Git LFS。如果直接用普通 git clone 却没装 LFS,拉下来的会只有 4KB 左右的指针文本文件,ComfyUI 自然报模型无效/损坏。
正确做法:先安装 LFS 再克隆:
git lfs install
git clone https://gitcode.com/hf_mirrors/Comfy-Org/HunyuanImage_2.1_ComfyUI
克隆后检查文件大小:真正的模型文件都是 GB 级,几 KB 的请重新 git lfs pull 补拉。
3. 文件名不能自己改
加载器是按固定文件名识别的,例如 hunyuanimage2.1_bf16.safetensors、qwen_2.5_vl_7b.safetensors、hunyuan_image_2.1_vae_fp16.safetensors。重命名、加中文、改大小写都会导致找不到模型。
4. 文件放对了,ComfyUI 仍报"模型不存在"或节点报错
通常是 ComfyUI 本体或工作流节点版本太旧,不认识 HunyuanImage 2.1 的新模型格式:
- 把 ComfyUI 更新到最新版本后再试;
- 检查节点管理器(Node Manager)里的相关自定义节点是否有更新;
- 确认 ComfyUI 使用的 Python 环境依赖完整。
三、显存与性能问题(坑 5~8)
5. 生成时报 OOM / 显存不足(CUDA out of memory)
HunyuanImage 2.1 是大参数模型,bf16 全精度组合对显存要求不低。按显存档位选配置:
| 显卡显存 | 推荐搭配 | 说明 |
|---|---|---|
| 24GB 及以上 | bf16 扩散模型 + bf16 Qwen 文本编码器 | 画质与稳定性最佳 |
| 12~16GB | fp8 扩散模型 + fp8 文本编码器 | 显存占用大幅降低,画质损失很小 |
| 12GB 以下 | 全 fp8 + 降低分辨率 | 比较紧张,建议 1024 左右起步 |
仍报 OOM 时依次尝试:降低输出分辨率 → 换 fp8 版本 → 关闭不必要的预览节点。
6. bf16 / fp8 / distilled 版本怎么选?
- bf16:全精度,画质上限最高,显存吃得最多;
- fp8_e4m3fn:8bit 量化版,显存占用约为 bf16 的一半左右,适合 12GB 级显卡,是"性价比之选";
- distilled(蒸馏版):为少步数采样优化,hunyuanimage2.1_distilled_fp8_e4m3fn.safetensors 等蒸馏模型只需很少的采样步数即可出图,速度优势非常明显。
一句话建议:显存够选 bf16 保画质;显存紧选 fp8;追求速度选 distilled。
7. 出图太慢怎么办?
三条加速路径,按效果排序:
- 换 distilled 模型:采样步数可以降到原版的零头,速度提升最明显;
- 适当降低分辨率与采样步数;
- 不需要精修效果时,跳过 refiner 阶段(见下一个问题)。
8. refiner 模型是必须的吗?
不是。hunyuanimage2.1_refiner_bf16.safetensors(或其 fp8 版)属于可选的二次精修模型,用于在初稿基础上再提升细节质感。工作流中不接 refiner 分支,只用主模型 + hunyuan_image_2.1_vae_fp16.safetensors 就能正常出图,只是少一道精修工序。
四、画质与效果问题(坑 9~11)
9. 画质差、画面模糊或有噪点
逐项排查,命中率从高到低:
- 采样步数不足:非蒸馏模型请给足步数,别用蒸馏版的少步数跑 bf16 原模型;
- 分辨率过低:建议 1024×1024 及以上起步;
- 想再进一步:显存充足时接 refiner 分支 + 配套 hunyuan_image_refiner_vae_fp16.safetensors,细节会有明显提升;
- 显卡够强却用了 fp8:可换回 bf16 版本对比。
10. 画面里的中文/文字是乱码、缺笔划?
这是 HunyuanImage 2.1 最容易困惑的点:模型里有一个专门负责画面内文字渲染的编码器 byt5_small_glyphxl_fp16.safetensors(ByteT5 + GlyphXL)。如果工作流没有加载它,或提示词里文字书写不规范,图内文字就容易变乱码。请确认工作流中该编码器节点已正确接入,并尽量把要写进画面的文字用引号明确标出。
11. 不同版本可以混搭吗(比如 fp8 主模型 + bf16 文本编码器)?
技术上大部分组合能跑,但注意两点:
- 混搭的显存占用按"最吃显存的那个"算,fp8 的意义就打了折扣;
- refiner 模型必须搭配它对应的 refiner VAE,主模型 VAE 与 refiner VAE 不要张冠李戴,否则解码结果会异常。
推荐成套使用:高显存全 bf16、中显存全 fp8,简单不出错。
五、其他常见问题(坑 12)
12. 要全部下载吗?磁盘占多大?
不推荐一次全下。三个目录共 11 个文件,全量是几十 GB 级别。按硬件只取所需:
- 24GB 显存:bf16 主模型 + bf16 Qwen 编码器 + 主 VAE(追求精修再补 refiner 两件套);
- 12~16GB:fp8 主模型 + fp8 Qwen 编码器 + ByteT5 编码器 + 主 VAE;
- 想要出图快:把主模型换成对应的 distilled 版本。
ByteT5 文本渲染编码器体积很小且对中文海报类需求很实用,建议无论如何保留一个。
写在最后
🧭 记住这张排查顺序图:文件完整吗(LFS)→ 目录对吗 → ComfyUI 版本新吗 → 显存够吗 → 参数对吗。按这个顺序过一遍,上面 12 个问题基本都能定位到根因。模型文件清单与目录规范可随时对照 README.md,祝一次配通、出图顺利!