在 ComfyUI 里跑 MiniMax H3：版本门槛、模型放置与 R2V 模板节点链拆解

2026-08-09

MiniMax H3 在 ComfyUI 里已经有官方教程和三个官方工作流模板了，但真正会绊住人的不是节点连线，而是几个很容易被跳过的前提：你的 ComfyUI 版本够不够、模型是从哪个仓库下的、下了几个文件、模板里那串看不懂的数学表达式在干什么。这篇按官方教程页（docs.comfy.org/tutorials/video/minimax/minimax-h3）和 Comfy-Org/workflow_templates 仓库里的模板 JSON 把这条路径捋一遍，核对日 2026-08-09。

先说清楚立场：本文没有任何本机运行结果。下面所有内容都是官方教程、模板文件和 release notes 的口径，不含效果评价。

一、版本门槛：0.30.0 是底线，但建议直接上 0.31.0

官方教程页写明需要 ComfyUI version 0.30.0 or later，v0.30.0 发布于 2026-08-03。模板的说明里给出了关联 PR ComfyUI#15224，也就是 H3 支持落地的那次改动。

真正值得留意的是紧接着的下一个版本。ComfyUI v0.31.0（2026-08-08）的 release notes 里有这么一条：

fix(minimax): cast raw parameters to input device in H3 VAEs by @rivadart in PR #15268

翻译过来是：H3 的 VAE 里有一处原始参数没有转换到输入所在的设备上，v0.31.0 修掉了它。也就是说，H3 支持在 v0.30.0 刚落地，一周之内就有一个设备转换相关的修复跟进。所以我的建议是别停在 0.30.0，直接更到 v0.31.0 或更新。 到了 v0.31.0，README 的 Features 已经把 MiniMax H3 正式列在「Audio and video generation」类目下，和 LTX-AV 并列。

模板说明里还有一条官方提示，用桌面端或云端的人尤其要看：ComfyUI Desktop 和 Cloud 跟随 stable 发布，因此某些「nightly 才支持」的模型可能暂时还用不了。 这句话的实际含义是，你在 GitHub 上看到某个模型的支持 PR 已经合并，不代表你的 Desktop 客户端此刻就能用——两条发布轨道的节奏不一样。遇到「教程里有这个节点、我这儿搜不到」，先确认自己在哪条轨道上，再去怀疑安装。

二、★ 权重不是从 MiniMax 官方仓库下的

这是交叉使用时最容易搞错的一点：ComfyUI 用的是 huggingface.co/Comfy-Org/MiniMax-H3，不是 MiniMaxAI/MiniMax-H3。而且是量化/裁剪过的版本。

类别	文件名	放置目录
diffusion_models（t2v/i2v）	`minimax_h3_fl2va_pruned_int8_convrot.safetensors`	`ComfyUI/models/diffusion_models/`
diffusion_models（r2v）	`minimax_h3_ref2va_pruned_int8_convrot.safetensors`	`ComfyUI/models/diffusion_models/`
text_encoders	`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`	`ComfyUI/models/text_encoders/`
vae（视频）	`minimax_h3_video_vae_fp16.safetensors`	`ComfyUI/models/vae/`
vae（音频）	`minimax_h3_audio_vae_fp32.safetensors`	`ComfyUI/models/vae/`

看文件名就能读出精度信息：扩散模型带 pruned_int8_convrot，文本编码器带 nvfp4_awq。而 MiniMax 官方 README 里写的两个 checkpoint（H3-Base FL2VA 与 H3-Base Ref2VA）精度是 BF16。ComfyUI 这边的 int8 convrot 支持是逐步加进来的：v0.27.0（2026-06-30）的主要变化就是新增 int8 convrot 模型支持，v0.30.0 又补了 int8 convrot 的 embedding lookup（PR #15035）。

结论只有一句，多的一句都不能说：在 ComfyUI 里跑的 H3，和照 MiniMax README 用官方推理栈跑的 H3，权重形态不是一回事。评估效果时不要把两边的结果混着看。 至于量化后画质如何、损失多少，官方没给数据，我们也没有任何对比结果，这里不提供任何结论。

另一个坑：t2v/i2v 和 r2v 用的是两个独立的扩散模型文件。模板说明原文强调 ref2va 用的「is a different set of weights from the fl2va model used by the t2v/i2v templates」。想三个模板都跑，两个文件都得下，别以为下一个就够了。

三、命令与目录：怎么把文件放对位置

官方模板给出的目录树是这样的（原样）：

📂 ComfyUI/
├── 📂 models/
│   ├── 📂 vae/
│   │   ├── minimax_h3_video_vae_fp16.safetensors
│   │   └── minimax_h3_audio_vae_fp32.safetensors
│   ├── 📂 diffusion_models/
│   │   └── minimax_h3_fl2va_pruned_int8_convrot.safetensors
│   └── 📂 text_encoders/
│       └── qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors

（跑 R2V 时，diffusion_models 下换成 minimax_h3_ref2va_pruned_int8_convrot.safetensors；两个都要就都放进去。）

下载地址的形态是 https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/<子目录>/<文件名>。子目录层级以你打开 Hugging Face 仓库页看到的为准，我不替你猜。Linux/macOS 下可以这样组织：

cd <你的 ComfyUI 目录>

# 视频 VAE 与音频 VAE
wget -P models/vae \
  https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/<子目录>/minimax_h3_video_vae_fp16.safetensors
wget -P models/vae \
  https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/<子目录>/minimax_h3_audio_vae_fp32.safetensors

# 文本编码器
wget -P models/text_encoders \
  https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/<子目录>/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors

# 扩散模型：跑 t2v/i2v 用 fl2va，跑 r2v 用 ref2va
wget -P models/diffusion_models \
  https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/<子目录>/minimax_h3_ref2va_pruned_int8_convrot.safetensors

Windows 上没有 wget 的话，用浏览器下完手动放进对应目录是一样的，关键只在于目录名一个字都不能错——官方模板给的目录树就是唯一口径，vae 归 vae、扩散模型归 diffusion_models、文本编码器归 text_encoders，放错位置的直接后果就是加载器节点里选不到这个文件名。

至于启动参数，教程页提到一个可选优化：Patch Sage Attention KJ 节点，官方教程称可加速约两倍，需要单独安装依赖，ComfyUI 侧对应的启动参数是 --use-sage-attention。教程页同时注明，你可能会看到 “using pytorch attention instead” 之类的消息，这属于正常现象。这条是可选项，第一次跑通之前不建议叠加。以上命令与参数按官方文档语义组合，未逐项实测，以官方文档与 python main.py --help 的实际输出为准。

四、三个模板与 R2V 的节点链全貌

教程页列出三个模板：Text-to-Video（T2V）、Image-to-Video（I2V）、Reference-to-Video（R2V），模板 JSON 在 Comfy-Org/workflow_templates 仓库，文件名分别是 templates/video_minimax_h3_t2v.json 和 templates/video_minimax_h3_r2v.json。R2V 是链路最长、也最能看出 H3 架构长什么样的一个，下面这张表是直接从模板 JSON 读出来的取值：

节点类型	模板里的取值
`UNETLoader`	`minimax_h3_ref2va_pruned_int8_convrot.safetensors`，weight_dtype `default`
`CLIPLoader`	`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`，type `minimax`，device `default`
`VAELoader` ×2	`minimax_h3_video_vae_fp16.safetensors` / `minimax_h3_audio_vae_fp32.safetensors`
`MiniMaxH3ReferenceToVideo`	prompt、width `1344`、height `768`、length `124`、ref_image_size `match`
`LoadImage` ×2	模板自带的两张示例图
`PrimitiveStringMultiline`	提示词输入
`RandomNoise`	种子 + `randomize`
`KSamplerSelect`	`res_multistep`
`BasicScheduler`	scheduler `simple`、steps `20`、denoise `1`
`BasicGuider` / `SamplerCustomAdvanced`	引导与采样
`PrimitiveFloat`（Duration）	`5`（秒）
`ComfyMathExpression`	`max(5, round(a * 24)) + (5 - (max(5, round(a * 24)) % 17)) % 17`
`VAEDecode` / `VAEDecodeAudio`	分别解码视频与音频
`CreateVideo`	fps `24`、第二参数 `8`
`SaveVideo`	输出前缀 `video/MiniMax_H3`，格式与编码均 `auto`
`ResolutionSelector`	`16:9 (Widescreen)`、megapixels `0.4`、multiple `32`

教程页还提到 MiniMaxH3ImageToVideo 节点和可选的 Patch Sage Attention KJ。

这张表里有三处值得单独说。

第一，CLIPLoader 的 type 是 minimax。 加载器选错类型，加载出来的文本编码结果就不是模型期望的那套，这是从下拉框里手搓工作流时最容易踩的一格。

第二，那串 ComfyMathExpression。 官方教程说 H3「snaps to the model’s 17-frame-per-block (17k+5) grid」，模板里这行表达式就是它的实现：先把你填的秒数 a 乘 24 取整（下限 5），再补齐到 17k+5。也就是说你填的秒数不会被原样使用，会被吸附到一个合法帧数上。默认 Duration 是 5 秒，节点里 length 写的是 124。看到最终帧数和你按 24fps 心算的结果对不上，不是 bug。

第三，两条解码路径。 采样器输出的是音视频联合的 LATENT，同时喂给 VAEDecode（走视频 VAE，fp16）和 VAEDecodeAudio（走音频 VAE，fp32），每个解码节点会自动从打包的 latent 里取出属于自己的那一半，最后由 CreateVideo 把两路 mux 成一个带同步声音的 MP4。这正是 H3 联合预测视频与音频 latent 这件事在节点图上的样子——你会同时需要两个 VAE 文件，原因就在这里。

五、R2V 的参考输入与提示词标签

R2V 的输入槽位是 ref_images / ref_videos / ref_video_audios / ref_audios。上限与 MiniMax 官方 README 一致：最多 9 张参考图、3 段参考视频（每段可带自己的配套音轨）、3 段独立参考音频。

关键规则是提示词里要按连接顺序用标签引用输入，官方原文强调「in the exact order they were connected」。写出来是这个样子：

<Picture 1> 里的人物站在 <Picture 2> 的场景中，镜头缓慢右移；
参考 <Video 1> 的运镜节奏；对白语气参考 <Audio 1>。

<Picture N>、<Video N>、<Audio N> 这些标签原样写，不要换成中文。顺序错了，模型对应到的就不是你以为的那张图。官方在模板说明结尾专门提醒：ref2va 的输出对提示词措辞非常敏感，标签要精确匹配，并且明确说明哪个参考负责画面的哪一部分。

ref_image_size 有两档，模板默认 match：

match：把参考缩放到生成分辨率，更快；
max：保留最高 2048px 短边，identity 保真更强，代价是速度。官方给的原因是「reference tokens ride along every sampling step」——参考 token 会跟着每一个采样步走。

六、几个反直觉的默认值

模板的默认值不等于官方推荐值，这一点在 H3 模板上格外明显。

ResolutionSelector 默认 megapixels 是 0.4，而教程页给的推荐值是 1.0。按模板内嵌的尺寸参考表（16:9、multiple=32），0.4 对应 864×480，0.98 对应 1344×768——后者正是 MiniMaxH3ReferenceToVideo 节点里写死的宽高。所以你在 Resolution Selector 上调 megapixels 时，实际是在这张映射表上挪档位，而不是随手填一个数。

另一处：BasicScheduler 模板默认 simple，但官方说明自己就写了，对这类参考密集的提示词，beta 或 normal 调度器往往比 simple 表现更好。模板默认值和官方建议不一致，这属于官方明写的调参线索，遇到 R2V 结果不理想时，这是第一个可以改的旋钮。

最后提一句尺寸上限：教程页的约束是短边 768px、上限 768×1344、取整到 32 的倍数。参考表里有 2.0 那一档，但别把它理解成「H3 在 ComfyUI 里能出 2K」——H3 的 2K 是靠 H3-Regenerate-2K 模块实现的，而该模块尚未开源、只有 API，ComfyUI 侧的模板里没有它。

七、怎么验收

跑之前和跑之后，人要盯的是这几处：

版本：先确认 ComfyUI 至少到 v0.31.0，再往下走。0.30.0 能用，但那个 VAE 设备转换的修复不在里面。
五个下拉框：UNETLoader、CLIPLoader、两个 VAELoader 都能在下拉框里选到对应文件名，且 CLIPLoader 的 type 是 minimax。选不到就是目录放错了，不是版本问题。
两路 VAE 都连上：只连视频 VAE 的工作流是跑不出带声音的结果的，音频 VAE 缺一路，VAEDecodeAudio 那条支路就断了。
帧数：确认最终 length 落在 17k+5 上，别和自己心算的秒数×24 较劲。
输出：模板里 SaveVideo 的输出前缀是 video/MiniMax_H3，格式与编码都是 auto，成品会以这个前缀落到 ComfyUI 的输出目录下。具体文件名由 ComfyUI 自己生成，这里不替你猜。

这五处对应的其实就是官方教程与模板说明里反复强调的四个前提：版本、下载来源、文件数量、加载器类型。它们各自失败时的表现完全不同——目录放错是「选不到文件」，只下了一个扩散模型文件是「换个模板就加载不到权重」，CLIPLoader 类型选错是文本编码这一环走了别的分支，而版本早于 0.30.0 则根本不在官方声明的支持范围内。先按这四个前提逐条排掉，再去怀疑工作流连线。

八、什么情况别走这条路

你要复现 MiniMax 官方效果：那就别只看 ComfyUI。官方系统里 H3-Context-IR 负责把复杂的多模态输入精炼成中间表示，README 明确说它对最终质量至关重要，但它没有包含在这次开源发布里，只有 API；H3-Regenerate-2K 同样未开源。ComfyUI 模板里跑的是中间那一层。拿到开源权重不等于拿到官方链路。
你要做效果横评：ComfyUI 侧是量化权重，MiniMax 官方是 BF16，两边不是同一套权重，横着比没有意义。
你在 Desktop/Cloud 上、又急着用最新支持的模型：这两条轨道跟随 stable，nightly 才支持的东西可能暂时不可用，别把时间花在反复重装上。
涉及商用：H3 的许可是 MiniMax H3 Community License Agreement，条款以官方 LICENSE 原文为准，本文不做任何解读。ComfyUI 自身是 GPL-3.0。

九、出了问题往哪提

模板内嵌的说明给了一条官方分流规则，照着走能省不少来回：

跑不起来、运行时报错 → github.com/comfyanonymous/ComfyUI/issues
UI / 前端问题 → github.com/Comfy-Org/ComfyUI_frontend/issues
工作流本身的问题（模板节点连线、默认值） → github.com/Comfy-Org/workflow_templates/issues

提之前先把版本号、模板名和五个模型文件名列出来，能少一轮问答。

延伸阅读

本文依据 MiniMax H3 官方仓库（github.com/MiniMax-AI/MiniMax-H3）的 README 与模型配置文件，以及 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py 与 release notes 整理，核对日 2026-08-09，对应 ComfyUI 版本 v0.31.0。ComfyUI 侧的模型文件与工作流信息来自 docs.comfy.org 的官方教程与 Comfy-Org/workflow_templates 仓库的模板文件。本文内容为官方文档与仓库口径，未在本机部署或调用过 H3，也未运行过文中的工作流。参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准；模型、部署方式与许可条款以官方最新说明为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。