alibaba-pai/MiniMax-H3-Fun-Controlnet-Union · Hugging Face

来源：https://huggingface.co/alibaba-pai/MiniMax-H3-Fun-Controlnet-Union GitHub仓库：https://github.com/aigc-apps/VideoX-Fun

MiniMax-H3-Fun-Controlnet-Union 是一个针对 MiniMax-H3（https://huggingface.co/MiniMaxAI/MiniMax-H3）训练的 ControlNet-Union 模型，采用 VideoX-Fun 管线进行训练。单一的检查点文件可根据 Canny、Depth、HED、MLSD 或 Pose 控制视频来调节 MiniMax-H3 视频生成器，同时也支持视频修复功能。

模型卡

模型特性

• 联合控制：单一检查点可处理 Canny、Depth、HED、MLSD 和 Pose 控制视频，用于视频到视频生成，无需为每种条件切换检查点。
• 控制分支连接至 50 个 transformer 块中的 5 个（层 0、10、20、30、40）；每个控制跳转通过一个零门控投影添加到主分支。
• 经过引导蒸馏：运行时设置 guidance\_scale = 1\.0，每一步只需前向传播一次，无需分类器自由引导。
• 支持修复：控制输入维度扩展为 control\_in\_dim = 49（潜变量 + 带掩码的潜变量 + 掩码通道）；使用 examples/minimax\_h3\_fun/predict\_v2v\_control\_inpaint\.py。
• control\_context\_scale 在每个控制跳转添加到主分支之前对其进行缩放：1\.0 提供最强控制（以下所有结果均采用此设置），低于 1\.0 的值会减弱控制视频的引导，0\.0 则完全关闭控制分支。
• 生成遵循控制视频：帧数会自动调整至视频 VAE 可解码的最大 17 \* n \+ 5（时长上限为 15 秒），画布保持控制视频自身的宽高比，在 height \* width 像素预算内（均为 32 的倍数），并以固定的 24 fps 运行。
• 详细的提示能提供更好的稳定性；我们建议在提示中描述场景、主体和摄像头。

生成结果

以下所有示例均使用 num\_inference\_steps = 40、guidance\_scale = 1\.0、control\_context\_scale = 1\.00、种子值 43 生成。

Canny

Depth

HED

MLSD

Pose

推理

更多详细信息请访问 VideoX-Fun 仓库。

请克隆 VideoX-Fun 仓库并创建所需目录：

# 克隆代码
git clone https://github.com/aigc-apps/VideoX-Fun.git

# 进入 VideoX-Fun 目录
cd VideoX-Fun

# 创建模型目录
mkdir -p models/Diffusion_Transformer

然后将基础 MiniMax-H3 模型和此检查点下载到 models/Diffusion\_Transformer 目录。

📦 models/
├── 📂 Diffusion_Transformer/
│   ├── 📂 MiniMax-H3/
│   └── 📂 MiniMax-H3-Fun-Controlnet-Union/
│       └── 📦 MiniMax-H3-Fun-Controlnet-Union.safetensors

接着，编辑 examples/minimax\_h3\_fun/predict\_v2v\_control\.py 文件顶部的设置并运行。

model_name          = "models/Diffusion_Transformer/MiniMax-H3"
config_path         = "config/minimax_h3/minimax_h3_control.yaml"
transformer_path    = "models/Diffusion_Transformer/MiniMax-H3-Fun-Controlnet-Union/MiniMax-H3-Fun-Controlnet-Union.safetensors"
control_video       = "your_control_video.mp4"
prompt              = "your prompt"

python examples/minimax_h3_fun/predict_v2v_control.py

注意事项：

• config\_path 必须精确构建与训练时一致的控制分支（control\_blocks\_places: \[0, 10, 20, 30, 40\]、control\_in\_dim: 49、control\_apply\_audio: false）；布局不匹配将导致检查点无法加载。
• 此检查点是经过引导蒸馏的：请保持 guidance\_scale = 1\.0；高于 1 的值会应用两次引导并降低输出质量。
• 控制检查点仅包含控制分支；基础的 MiniMax-H3 权重必须存在于 model\_name 指定的路径中。
• 内存：transformer（约 62 GB）加上 Qwen3-VL 文本编码器（约 62 GB）无法完全装入一个 80 GB 显存的 GPU；请在单个 80 GB GPU 上使用 model\_group\_offload（最快）或 model\_cpu\_offload\_and\_qfloat8。

许可证

此模型是 MiniMax-H3 的衍生作品，根据 MiniMax H3 社区许可证协议 发布。请在使用前仔细阅读许可证，特别是其中的地域限制和可接受使用政策。