ComfyUI运行Minimax-H3-Singularity-V2-Pruned的10个常见问题与解决方案:排错速查清单
ComfyUI运行Minimax-H3-Singularity-V2-Pruned的10个常见问题与解决方案:排错速查清单
Minimax-H3-Singularity-V2-Pruned 是专为 ComfyUI 打造的 MiniMax H3 视频生成模型剪枝量化版,提供 INT8 无损版(21.0 GB)与 W4A8 低显存版(12.5 GB)两种 .safetensors 格式,支持文生视频与图生视频。本文汇总新手在部署该模型时最常遇到的 10 个 ComfyUI 加载、显存不足、LFS 下载等常见问题,并给出可直接照做的解决方案,帮你快速完成排错。
📁 先认识仓库里的文件
在开始排错前,先确认你手里有哪些文件(本仓库共 3 个模型文件 + 1 份说明文档):
| 文件 | 大小 | 量化格式 | 推荐场景 |
|---|---|---|---|
| Minimax-h3_Singularity_ref2va_v2_Pruned_int8.safetensors | 21.0 GB | INT8 主干 + 无损剪枝 AdaLN | 追求 100% 无损画质的显存充足设备 |
| Minimax-h3_Singularity_ref2va_v2_Pruned_w4a8.safetensors | 12.5 GB | Asym W4A8 INT8 | 低显存设备 |
| adaln_affine.safetensors | 约 95 KB | AdaLN 曲线基(rank-8 Ref2VA 子空间) | 搭配剪枝 H3 LoRA / PowerLoRA 生态使用 |
| README.md | - | 项目说明 | 文件清单、剪枝细节与使用步骤见 README.md |
💡 文件清单与推荐硬件的完整对照表,可直接查看 README.md。
1. 下载到手的 .safetensors 只有 136 字节,打开是文本?
症状:文件只有几十字节,用文本编辑器打开会看到 version https://git-lfs... 和 size 20977345816 之类的指针内容。
原因:仓库的模型文件由 Git LFS 管理,未配置 LFS 时 clone 下来的只是指针文件,不是真正的模型。
解决:先安装 Git LFS,再拉取真实文件:
git lfs install
git clone https://gitcode.com/hf_mirrors/Abiray/Minimax-h3-Singularity-V2-Pruned
cd Minimax-h3-Singularity-V2-Pruned
git lfs pull
完成后 int8 文件应为 21.0 GB 左右,而不是 136 字节。
2. 模型放好了,ComfyUI 加载器里却看不到?
原因:文件放错目录。该模型必须放在 ComfyUI 的扩散模型目录:
ComfyUI/models/diffusion_models/
解决:
- 将 int8 或 w4a8 文件移入上述目录(文件名保持不变)。
- 重启 ComfyUI,或在模型加载节点上刷新模型列表。
放置步骤详见 README.md 的 "How to Use in ComfyUI" 一节。
3. int8 和 w4a8 两个版本,我该选哪个?
快速判断:看你的显存和画质需求。
| 对比项 | int8 版 | w4a8 版 |
|---|---|---|
| 文件大小 | 21.0 GB | 12.5 GB |
| 精度策略 | 100% 无损画质(剪枝仅针对 AdaLN,不影响运动动态) | Asym W4A8,16 级 Lloyd-Max 码本 |
| 适用硬件 | 显存充足、追求画质的设备 | 低显存设备 |
- 显存 ≥ 24 GB 且对画质敏感 → 选 int8;
- 显存紧张(如 12~16 GB)→ 选 w4a8。
4. 生成视频时报显存不足(Out of memory)
解决(按优先级尝试):
- 切换到 12.5 GB 的 w4a8 版本,显存占用直接降低约 40%;
- 降低输出分辨率、帧数或视频时长;
- 在 ComfyUI 中启用模型卸载/显存优化(model offload)相关选项。
该模型已做过剪枝(移除 130.3 亿 AdaLN 参数、节省约 13 GB 空间),但主干仍是 INT8 量级,低显存设备仍建议以 w4a8 为主,剪枝细节见 README.md。
5. 加载 w4a8 版本报错,提示格式不识别?
原因:w4a8 文件采用 ComfyUI 的 asym_w4a8_int8 量化格式,需要对应版本的 ComfyUI 原生 INT8 加载器,或支持混合量化的自定义节点(如 comfyui-mixed-quantizer)。
解决:
- 将 ComfyUI 更新到支持
asym_w4a8_int8的版本; - 或安装 README.md 中提到的混合量化自定义节点后重试加载。
6. adaln_affine.safetensors 是什么?需要一起加载吗?
它不是主模型,而是剪枝后的 AdaLN 曲线基(rank-8 Ref2VA 子空间的 adaln_basis + adaln_mean),仅约 95 KB。
- 只跑普通文生视频/图生视频:主模型文件放对目录即可,不需要手动加载它;
- 使用剪枝版 H3 LoRA / PowerLoRA 生态时:它保证与标准曲线基 100% 兼容,建议与 LoRA 一起放置在模型目录备用。
7. 提示缺少 text encoder 或 VAE,工作流跑不起来?
原因:MiniMax H3 工作流需要三部分配合,光有主模型不够。
解决:按 README.md 的说明,为工作流补齐:
- Qwen3-VL 文本编码器(text encoder);
- MiniMax-H3 视频 VAE + 音频 VAE;
- 本仓库的 int8/w4a8 主模型。
三者齐备后,节点连线与普通的视频生成工作流一致。
8. 生成画面有色偏或网格状伪影?
解决:本剪枝版在重新量化前,已使用 float64 精度精确执行了 Hadamard 逆旋转( 蝶形变换),专门消除了色偏与网格伪影。如果出现这些问题,通常是:
- 使用了更旧的未修正版本文件 → 核对文件名是否为
ref2va_v2_Pruned系列; - 文件不完整 → 按下一节的校验方法重下;
- 加载节点或版本不匹配 → 统一使用支持该格式的加载器。
9. 如何校验下载的文件没有损坏?
解决:用 sha256sum 校验(Linux/macOS),或在 Windows 上用 certutil:
sha256sum Minimax-h3_Singularity_ref2va_v2_Pruned_int8.safetensors
各文件的正确校验值(来自仓库 LFS 元数据,.gitattributes 中声明了 *.safetensors filter=lfs):
| 文件 | SHA256 | 正确大小 |
|---|---|---|
| int8 主模型 | bc7c5efb713a8a5042d2bc177bda343af7f4e6340edb23d3fb2644b336147a50 |
20977345816 字节(≈21.0 GB) |
| w4a8 主模型 | 036b91ef9d4d101e5436f7ce2a6c4d95add733b2540f37c15de0ffca55ac1f73 |
12547844936 字节(≈12.5 GB) |
| adaln_affine.safetensors | 98fbeba868fd1d08b8232dce62abb3f5427dd49fb08462869633a3d53533b50f |
96960 字节 |
校验值不一致时,直接重新执行 git lfs pull 补拉文件。
10. 能商用吗?需要注意哪些许可限制?
注意:本模型基于 WarmBloodAban/Minimax-H3 Singularity,底层架构为 MiniMax H3,受 MiniMax H3 Community License Agreement 约束(许可证为 minimax-h3-community,见 README.md 的许可说明)。
建议:商用前仔细阅读社区许可条款;模型剪枝、转换与优化工作由 Abiray 完成,使用时请一并尊重上游模型方的授权要求。
✅ 排错速查清单
| # | 问题 | 一句话解决方案 |
|---|---|---|
| 1 | 模型文件只有 136 字节 | 执行 git lfs install && git lfs pull |
| 2 | 加载器看不到模型 | 移入 ComfyUI/models/diffusion_models/ 并重启 |
| 3 | 不知道选哪个版本 | 显存充足选 int8,低显存选 w4a8 |
| 4 | 生成时 OOM | 换 w4a8、降分辨率/帧数、开启 offload |
| 5 | w4a8 格式不识别 | 更新 ComfyUI 或安装 comfyui-mixed-quantizer |
| 6 | 不知 adaln_affine 用途 | 主流程无需手动加载,LoRA 场景备用 |
| 7 | 缺 text encoder/VAE | 补齐 Qwen3-VL 编码器与 H3 视频/音频 VAE |
| 8 | 画面色偏、网格伪影 | 确认使用 ref2va_v2 剪枝版并校验文件 |
| 9 | 怀疑文件损坏 | 用 SHA256 校验,不一致则重新 git lfs pull |
| 10 | 商用疑虑 | 遵守 MiniMax H3 社区许可证条款 |
按以上清单逐项排查,绝大多数 ComfyUI 部署 MiniMax-H3-Singularity-V2-Pruned 的问题都能在几分钟内定位解决。祝生成愉快 🎬