ComfyUI‑H3‑FunControl：首个可用的 MiniMax‑H3 ControlNet 节点，逐帧锁定视频运动轨迹

ComfyUI-H3-FunControl 是一个填补了 MiniMax H3 生态空白的关键插件，它实现了基于 Fun-ControlNet 的逐帧视频驱动功能。这是目前已知第一个能在 ComfyUI 中实际加载并运行 Kijai 重新推导的曲线形式（Curved Form）ControlNet 权重的节点，允许用户通过深度图、Canny 边缘、姿态（Pose）、HED 或 MLSD 等控制信号，精确引导 H3 生成符合指定结构的视频。

• GitHub：https://github.com/wyzborrero/ComfyUI-H3-FunControl

核心亮点

• 逐帧结构控制：
  • 支持输入深度、Canny、姿态、HED 或 MLSD 视频/图像序列。
  • 生成的视频将严格遵循控制信号的几何结构与动作轨迹，而非仅依赖提示词或首帧。
• 兼容修剪版 H3 模型：
  • 专门适配广泛使用的曲线形式 AdaLN 修剪版 H3 检查点（如 minimax_h3_fl2va_pruned_int8_convrot.safetensors）。
  • 自动检测并拒绝不兼容的全宽 AdaLN 原始权重，避免静默失败。
• 零依赖轻量实现：
  • 完全基于 ComfyUI 原生 H3 模块构建，无需额外安装复杂的第三方库（除可选的 Sol-Attn 加速外）。
  • 代码极简，通过 transformer_options 钩子注入控制块，不修改核心代码。
• 完善的错误防护与文档：
  • 详细记录了 8 大“陷阱”（如静默失败、执行缓存、链式强度求和等），并提供了解决方案。
  • 内置形状校验与音频段保护机制，确保控制信号仅作用于视频部分，不破坏音频同步。

安装与权重准备

1. 安装插件

cd ComfyUI/custom_nodes
git clone https://github.com/wyzborrero/ComfyUI-H3-FunControl.git
# 重启 ComyUI

2. 下载兼容权重

你需要使用 Kijai 重新推导的曲线形式权重，而非阿里巴巴 PAI 发布的原始全宽权重。

• 推荐文件：minimax_h3_fun_controlnet_union_pruned_bf16.safetensors
• 存放路径：ComfyUI/models/controlnet/

关键使用技巧与避坑指南

1. 链式控制强度预算 (Trap 3)

当同时使用多个 ControlNet（如深度+姿态）时，它们的跳跃连接会求和。

• 错误做法：深度 Strength 1.0 + 姿态 Strength 1.0 = 总强度 2.0（导致过曝、细节丢失）。
• 正确做法：将总强度视为预算。例如：深度 0.3 + 姿态 0.7 = 总强度 1.0。

2. 掩码值设置 (Trap 4)

在无修复（Inpainting）模式下，掩码潜空间为零。

• Mask Value 1：指示模型重现黑色（因为掩码潜空间为 0），导致画面坍缩为剪影。
• Mask Value 0：推荐设置。指示模型忽略掩码潜空间，正常生成风格与内容。

3. 稀疏注意力加速陷阱 (Trap 8)

若使用 Sol-Attn 进行加速：

• 必须关闭 Morton 重排序 (morton: false)。
• 原因：ControlNet 的跳跃连接基于栅格顺序的行偏移添加，Morton 重排序会打乱令牌顺序，导致控制信号应用到错误的令牌上，使控制完全失效且无报错。
• 性能：关闭 Morton 后仍可获得约 1.51 倍 加速。

4. 提前释放控制 (End Percent)

• 默认 end_percent=1.0 会让控制贯穿所有采样步，可能抑制后期步骤生成的纹理细节。
• 建议：对于空旷背景或需要丰富纹理的场景，将 end_percent 设为 0.6-0.8，让模型在后期自由发挥细节。

5. 角色参考配合

• ControlNet 仅驱动运动与结构，不负责角色外观。
• 最佳实践：结合 MiniMaxH3ReferenceToVideo 节点，将角色参考图放入 ref_image_0，同时使用 ControlNet 驱动动作。这能解决仅用首帧导致的角色“裸模化”或风格丢失问题。

性能基准 (RTX 5090, 90帧 1280×704)