> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ComfyUI MiniMax H3 视频生成指南
> 如何在 ComfyUI 中使用开放权重的 MiniMax H3：文生视频、图生视频、参考生视频工作流，支持原生立体声音频，附提示词编写技巧与 Sage Attention 加速方法。
[MiniMax H3](https://www.minimax.io/blog/minimax-h3) 是 MiniMax 推出的通用全模态生成模型，现已以开放权重形式提供。它能在单一上下文中联合理解文本、图像、视频和音频，并生成带**原生立体声音频**的视频：语音、音效和音乐在单次前向传播中一并建模，而非事后叠加。开放权重在短边 768 像素（约 100 万像素）下以 24fps 生成约 15 秒的视频。2K 输出来自 MiniMax 的托管服务，在 ComfyUI 中需要单独跑一次放大。
ComfyUI 原生支持 MiniMax H3。文档分为六个页面：
* **概述**（本页）：模型能力、工作流索引、输出分辨率、步数、采样器与调度器，以及加速技巧
* **[原生工作流](/zh/tutorials/video/minimax/minimax-h3-native)**：文生视频、图生视频、参考生视频，以及高级原生节点技巧
* **[多帧参考](/zh/tutorials/video/minimax/minimax-h3-multiframe)**：将参考帧锚定在输出时间线上的特定位置
* **[Fun ControlNet Union](/zh/tutorials/video/minimax/minimax-h3-fun-controlnet)**：使用控制视频驱动 H3，或使用遮罩进行视频修补
* **[提示词指南](/zh/tutorials/video/minimax/minimax-h3-prompt-guide)**：MiniMax 官方提示词编写指南、通用技巧与提示词嵌入
* **[FastH3](/zh/tutorials/video/minimax/minimax-h3-fastvideo)**：FastVideo 的 FastH3 检查点及其稀疏注意力工作流
请确保你的 ComfyUI 已经更新。
* [ComfyUI 下载](https://www.comfy.org/download)
* [ComfyUI 更新教程](/zh/installation/update_comfyui)
本指南里的工作流可以在[工作流模板](/zh/interface/features/template)中找到。如果找不到，可能是 ComfyUI 没有更新。
如果加载工作流时有节点缺失，可能原因有：
1. 你用的不是最新版（每夜版）。
2. 启动时有些节点导入失败。
* [Cloud](https://cloud.comfy.org) 会在 ComfyUI 稳定版本发布后更新。
所以，如果你发现本文档中有任何核心节点缺失，可能是因为新核心节点尚未在最新稳定版中发布。请等待下一个稳定版发布。
H3 的开放权重让你可以在本地运行该模型。对本地生成的输出进行商业使用需要 [MiniMax 商业许可证](https://comfy.org/minimax/license)，该许可证可通过 Comfy（唯一官方经销商）获取。在 Comfy Cloud 上生成的输出已包含商业使用权。
## 主要功能
* **原生立体声音频**：对话、音效和音乐可与视频一同生成，并在同一个 MP4 文件中同步
* **多模态上下文**：文本、图像、视频和音频参考可在单次生成中组合使用
* **参考驱动生成**：从参考素材中锁定角色身份、风格、动作、相机运镜或声音
* **指令遵循**：使用自然语言描述参考素材与目标镜头之间的关系
* **准确的文本渲染**：拼写文本和品牌元素渲染清晰
* **开放权重**：在 ComfyUI 中本地运行，可完全控制每个参数
## 入门
ComfyUI 支持开放权重的 MiniMax H3。开始使用：
1. 更新 ComfyUI。基础的文生视频、图生视频和参考生视频模板需要 0.30.0 或更高版本。多帧参考需要 0.34.0。Fun ControlNet Union、稀疏注意力节点和 Model Attention Backend 节点需要 0.35.0，FastH3 需要 0.36.0
2. 前往**模板库** > **视频**，选择任意一个 MiniMax H3 工作流
3. 按照弹出窗口的提示下载模型并运行工作流。下载量视模板而定，可能达到几十 GB，请预留磁盘空间和时间。
模型文件托管在 Hugging Face 的 [Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3) 仓库中。
LoRA 要与它蒸馏时所用的 checkpoint 构建对应，仓库同时提供两种构建时请选 `pruned` 版本。pruned checkpoint 用一张较短的共享曲线基表（`adaln_t_table`，1025 个曲线采样 × 8 个基列）取代时间嵌入器和全宽 adaln 权重，ComfyUI 会从 checkpoint 本身读取该基表，模板加载的正是 pruned 构建（`minimax_h3_fl2va_pruned_int8_convrot.safetensors` 与 `minimax_h3_ref2va_pruned_int8_convrot.safetensors`，另有 bf16 与 fp8 版本）。在完整构建（`minimax_h3_fl2va_int8_convrot.safetensors` 或 `minimax_h3_ref2va_int8_convrot.safetensors`）上蒸馏的 LoRA 带有 adaln 权重，而 pruned 构建中没有与之对应的张量：ComfyUI 会报出形状不匹配并且不合并这些权重，这部分 LoRA 因此被跳过。工作流下载的 turbo LoRA 不含任何 adaln 张量，在两种构建上都能加载。
## 工作流索引
模板库目前附带六个示例工作流。它们只是示例模板，并非完整列表：通过原生 MiniMax H3 节点，该模型支持更多生成模式，您可以使用这些节点构建更多工作流。模板库中还包含图生视频模板的一个续接变体（`video_minimax_h3_i2v_continuation`）。
根据文本提示词生成视频，并带有原生立体声音频
根据输入图像生成视频，并支持可选的首帧/尾帧控制
通过参考图像、视频和音频，锁定角色、风格、动作、相机运动或声音
使用链式连接的 Add Guide 节点，将参考帧锚定在输出时间线上的指定位置
使用 Canny、Depth、HED、MLSD 或 Pose 控制视频驱动 H3，或使用遮罩执行视频 inpainting
底层节点模式：**MiniMax H3 Image to Video** 节点覆盖文生视频和首帧/尾帧图生视频（t2va 与 fl2va），**MiniMax H3 Reference to Video** 节点覆盖以图像、视频和音频为参考的参考驱动生成（ref2va）。
提示词编写资源（官方指南、通用技巧与提示词嵌入）请参见[提示词指南](/zh/tutorials/video/minimax/minimax-h3-prompt-guide)。
## 设置输出分辨率
每个工作流都使用一个 **Resolution Selector（分辨率选择器）** 节点来控制总体输出尺寸。该节点根据三个设置计算 `width` 和 `height`，其输出直接连接到 MiniMax H3 节点的 `width` 和 `height` 输入：
* **宽高比**：选择一个预设，例如 `16:9 (Widescreen)`、`9:16 (Portrait Widescreen)` 或 `1:1 (Square)`
* **百万像素**：输出的目标总像素数。数值越大画面越大，数值越小生成越快
* **取整倍数**：计算结果会取整到该数值的最近倍数。保持为 `32`，与 H3 的分辨率网格一致
模板默认使用一个较快的预览尺寸。要获得全质量输出，请在 16:9 下将分辨率选择器的百万像素设为 `0.98`，即 H3 的原生画布（短边 768px，16:9 下为 1344x768）；或在 MiniMax H3 节点的 `width` 和 `height` 中直接输入 `1344 x 768`（默认值）。请跳过 `1.0` 百万像素档：它得到 1376x768，超出模型 768x1344 像素的面积上限。
远超原生画布的帧无法保持细节：H3 的训练分辨率约为 100 万像素，生成阶段丢掉的细节，后续再放大也补不回来。需要 2K 输出时，先在原生画布下生成，再单独跑一次放大。
## 步数
这些数值适用于基础权重，且模板中的 **Enable Lightning LoRA** 开关处于关闭状态，这是默认设置，采样 20 步。开启该开关会加载 turbo LoRA，步数在文生视频与图生视频模板（含续写变体）中降至 8 步，在自带参考 turbo LoRA 的模板（参考生视频、多帧参考、Fun ControlNet Union）中降至 4 步。在文生视频与图生视频模板中，该开关是子图节点上的 `turbo_mode` 控件。
调度越短，参考驱动的镜头受影响最大。参考 token 会参与每一个采样步，因此开启该开关后，留给这部分条件引导的步数要少得多：在 4 步时，参考可能几乎没有被应用，主体的姿态或面部角度也可能随着片段推进逐渐偏离参考。当镜头需要严格跟随参考时，保持 **Enable Lightning LoRA** 开关关闭，改用基础的 20 步调度；如果参考仍然漂移，再把步数提高到 25。
一个镜头需要多少步，取决于画面内容：
* 内容简单的镜头在 12 到 16 步就能成立
* 包含高频细节的镜头（锁子甲、花丝或花卉纹样、成堆的小物件）会一直改善到约 50 步。低于这个范围时，这些区域会出现不稳定的三角形网格伪影，并在运动中游移，而蒸馏出的降步 LoRA 和 turbo 检查点会最先放大这一类问题
* 步数更高也会同时改善提示词遵循度和运动，大部分收益在 16 步左右就能拿到。超过约 50 步后，差异很难察觉
* 步数无法补上原生画布本身解析不出的锐度，因此画面发软首先要看分辨率
音频比画面收敛得更晚。视频与音频在同一次采样中一起去噪，由同一份调度驱动，因此在画面已经停止变化的步数之后，音轨仍在继续改善。语音和音色最后才收敛：在 8 步时它们是输出中最弱的部分，12 步及以上才能让音轨保持可用。
## 采样器与调度器
所有本地 MiniMax H3 工作流都使用 `res_multistep` 采样器和 `simple` 调度器。文生视频、图生视频和 FastH3 模板把这两个节点放在工作流的子图内部，需要进入子图才能修改。在参考生视频、多帧参考和 Fun ControlNet Union 模板中，`KSamplerSelect` 和 `BasicScheduler` 位于顶层画布上。
`res_multistep` 是二阶多步采样器：每一步都会复用上一步的去噪估计。第一步没有可复用的估计，因此按普通的一阶（Euler）步骤执行，二阶步骤从第二步开始。`er_sde` 以同样的方式逐级升阶：在默认的 `max_stage` 为 3 时，第一步只跑一个阶段，第二步跑两个阶段，从第三步起才跑满三个阶段。
多步采样的历史记录存在于单次采样过程内部，而不是 Latent 中，因此把调度拆分给两个采样器的工作流不会把它延续下去。在双采样器配置中，例如先跑基础阶段、做一次 Latent 放大后再交给第二个采样器时，第二个采样器从空历史开始：它的第一步以一阶运行，二阶更新要到第二步才恢复。这一步的影响在短尾段上最明显，因为尾段本就没有几步，其中一步只以低阶执行。要么把整条调度放在一次采样过程中，要么给第二个采样器足够多的步数去重建历史。
flow shift 这一对参数来自模型定义，而不是工作流：ComfyUI 的 H3 定义带有 `shift` `12` 和 `audio_shift` `3`，除 FastH3 之外的所有工作流都读取这两个值，因此这些工作流里不会出现 shift 节点。FastH3 模板则内置了 **ModelSamplingMiniMaxH3** 节点（在工作流 JSON 里为 `MiniMaxH3SigmaShift`，分类 `model/patch/minimax`），取值为 `shift_video` `10`、`shift_audio` `3`，这正是其蒸馏调度所依据的一对参数。视频 shift 决定采样器的 sigma 调度，模型再把视频调度反推到共享的基础网格上，并由此推导出音频调度。当检查点需要另一组取值时再添加该节点，并贴近该检查点所依据的值：在蒸馏的 8 步版本上，把 `shift_video` 用 `3` 而不是 `10` 来采样，画面会出现网格状伪影。
## 使用 Sage Attention 加速生成
示例工作流默认使用标准注意力实现。使用 [Sage Attention](https://github.com/woct0rdho/SageAttention) 可以将生成速度大约提升一倍，质量损失极小。Sage Attention 是可选依赖，需要你自行安装：
1. 安装 `sageattention` Python 包。从 [SageAttention releases](https://github.com/woct0rdho/SageAttention/releases) 页面下载与你 PyTorch 和 CUDA 版本匹配的 wheel 文件，然后用 `pip install ` 安装。
2. 安装 [KJNodes 自定义节点](https://github.com/kijai/ComfyUI-KJNodes)，它提供了 `Patch Sage Attention KJ` 节点。可以使用 ComfyUI Manager 安装，或将仓库克隆到 `ComfyUI/custom_nodes/` 后重启 ComfyUI。
3. 在工作流中添加 `Patch Sage Attention KJ` 节点，并将其连接在 `UNETLoader` 和 `BasicGuider` 节点之间：它的 `model` 输入接收来自 `UNETLoader` 的模型，`model` 输出连接到 `BasicGuider` 的 `model` 输入。将 `sage_attention` 设置为 `auto`。
4. 照常运行工作流。只需要给 guider 打补丁；scheduler 只负责生成 sigmas，可以保持不变。
注意：
* Sage Attention 要求 float16 或 bfloat16 张量。MiniMax H3 的部分层使用其他数据类型，因此你可能会在控制台看到 "Input tensors must be in dtype of torch.float16 or torch.bfloat16, using pytorch attention instead" 消息。这是正常现象；受影响的层会回退到标准注意力，生成仍然可以正常工作。
* 另一种方式是使用 `--use-sage-attention` 启动参数启动 ComfyUI 来全局启用 Sage Attention，无需添加节点。
### INT8 注意力导致的质量劣化
使用 Sage Attention 时，如果视频片段末尾附近出现画面形变或屏幕文字乱码，最可能的原因是 INT8 注意力量化。H3 的最后几个 Transformer 块将大部分注意力键信号集中到少数通道中，而使用单一共享缩放对整行进行取整的 INT8 内核会丢失部分信号。
具体适用哪种修复方式，取决于工作流加载的检查点：
* **模板附带的是 int8-convrot 检查点**：文生视频、图生视频和图生视频续接变体使用 `minimax_h3_fl2va_pruned_int8_convrot.safetensors`，参考生视频、多帧参考和 Fun ControlNet Union 使用 `minimax_h3_ref2va_pruned_int8_convrot.safetensors`。**Comfy Kitchen attention 不支持这些检查点**，采样会因对齐错误而崩溃（[ComfyUI issue #15529](https://github.com/Comfy-Org/ComfyUI/issues/15529)）。使用这些检查点时请保持默认注意力，或在 `UNETLoader` 中加载对应的 bf16 版本（`minimax_h3_fl2va_pruned_bf16.safetensors` 或 `minimax_h3_ref2va_pruned_bf16.safetensors`，需要更多显存），然后再按下文切换后端。
* **使用 bf16 检查点时，把稠密注意力后端切换为 Comfy Kitchen attention 即可消除伪影。** 它的 INT8 内核在量化前先进行通道旋转，从而在与 Sage Attention 相近的速度下保留该信号。
要切换后端，请添加内置的 **Model Attention Backend** 节点（分类 `model/patch`），并将其后端设置为 `comfy kitchen attention`。把它连接在模型通往 `BasicGuider` 的位置，也就是 `LoraLoaderModelOnly` 节点及其 Enable Lightning LoRA 开关之后。另一种方式是使用 `--use-ck-attention` 启动参数启动 ComfyUI（ComfyUI 0.32.0 及以上版本可用）。该后端由随 ComfyUI 自带的 `comfy-kitchen` 包提供，只有当你的硬件支持 INT8 内核时，它才会出现在该节点的后端列表中。
## 使用稀疏注意力加速生成
注意力开销会随视频时长快速上升。ComfyUI 内置的 **Model Sparse Attention** 节点（分类 `model/patch`，实验性功能，ComfyUI 0.35.0 及以上版本）会在符合条件的层上执行块稀疏注意力来降低这部分开销，序列越长收益越明显。把它的 `method` 设为 `sol-attn`，也就是基础 H3 权重使用的模式（`sla` 和 `vsa` 需要针对相应模式训练的权重）。稀疏路径需要 CUDA 以及来自 `comfy-kitchen` 的 `sol_attn` 内核；否则每一层都会静默回退到稠密注意力，你不会看到任何加速。
* **不要在采样的最开始和最后几步启用稀疏注意力。** 默认值为 `start_percent` `0.2`、`end_percent` `1.0`，也就是从调度的 20% 一直稀疏到最后一步。把开始时间推迟到 `0.4` 左右、结束时间提前到 `0.9` 左右，可以让开头画面的运动和结尾几帧保持稠密，代价是速度略有下降。
* **H3 上保持 `sink_conditioning` 的默认值**（`exact_kv_and_rows`）。它会让打包的文本、音频和参考行保持精确计算，并让生成音频的查询行保持稠密，因此稀疏路径不会降低音轨质量。
* **`tau` 决定 `sol-attn` 的稀疏程度**：`1.0` 大约保留 16% 的关键块做精确计算，`1.5` 约 7%，`2.0` 约 2.7%。默认值为 `1.3`，数值越高越快，风险也越大。
* **短视频片段收益有限。** 长度低于 `min_tokens`（默认 `12288`）的序列，以及 `dense_blocks` 中列出的块都会保持稠密。
FastH3 检查点使用同一个节点的 `vsa` 模式，该模式按 `keep_percent` `10` 的稀疏模式训练。详见 [FastH3 工作流页面](/zh/tutorials/video/minimax/minimax-h3-fastvideo)。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.