Hugging Face's logo

alibaba-pai
/
MiniMax-H3-Fun-Controlnet-Union-2.0

Text-to-Video
VideoX Fun
controlnet
controlnet-union
video-to-video
image-text-to-video
video-inpainting
Model card Files
xet
 Community
1
MiniMax-H3-Fun-Controlnet-Union-2.0 / README_zh.md
bubbliiiing
Update readme
7d2c95d
preview code
|
Raw
History Blame Contribute Delete
11.8 kB
metadata 
license: other
license_link: LICENSE.md
license_name: minimax-h3-community-license-agreement
library_name: videox_fun
tags:
  - controlnet
  - controlnet-union
  - video-to-video
  - image-text-to-video
  - text-to-video
  - video-inpainting
tasks:
  - text-to-video-synthesis

MiniMax-H3-Fun-Controlnet-Union-2.0

Github

2.0 新变化

MiniMax-H3-Fun-Controlnet-Union（v1） MiniMax-H3-Fun-Controlnet-Union-2.0（本模型）
控制条件 5 种 — Canny、深度、HED、MLSD、姿态 8 种 — 新增涂鸦、布局、灰度
控制分支深度 5 个控制块（第 0, 10, 20, 30, 40 层） 10 个控制块（第 0, 5, 10, …, 45 层）— 在 50 个 transformer 块中每 5 层设置一个注入点
修复掩码像素方案 pre_norm（空洞区域约为 VAE 输入空间的 −2，接近纯黑） **post_norm**（空洞区域置 0，即中灰色，与 Wan 2.1 一致）— 修复区域衔接更干净
Checkpoint 内容 control_proj_in + 5 个 control_blocks（约 6.8 GB） control_proj_in + 10 个 control_blocks（约 13.5 GB）
所需配置 minimax_h3_control.yaml minimax_h3_control_inpaint_post_norm.yaml

其他方面与 v1 保持一致：control_in_dim = 49（潜变量 + 掩码后潜变量 + 掩码图，控制与修复共用同一分支）、control_apply_audio = false、引导蒸馏（guidance_scale = 1.0），以及同样的零初始化门控加性注入主分支。

⚠️ 用 v1 配置加载本 checkpoint 会"静默失败"。 使用 minimax_h3_control.yaml（仅 5 个块）时，模型只会搭建一半的控制分支：load_state_dict(strict=False) 会把 control_blocks.5~9 当作多余键直接丢弃，其余权重还会错位加载，最终产出完全错误的结果。请务必使用 minimax_h3_control_inpaint_post_norm.yaml。

模型文件说明

文件名 说明
MiniMax-H3-Fun-Controlnet-Union-2.0.safetensors MiniMax-H3 的 ControlNet-Union-2.0 分支权重，仅包含控制分支（control_proj_in 与 10 个 control_blocks，约 13.5 GB），需叠加加载到 MiniMax-H3 基础 transformer 之上。单个 checkpoint 覆盖 8 种控制条件（Canny、深度、HED、MLSD、姿态、涂鸦、布局、灰度）及视频修复。

模型特性

  • 一个 checkpoint 统管 8 种控制条件：Canny、深度、HED、MLSD、姿态、涂鸦、布局、灰度控制视频的视频到视频生成，无需为每种条件单独切换 checkpoint。
  • 更密集的控制注入：控制分支接入 50 个 transformer 块中的 10 个（第 0, 5, 10, 15, 20, 25, 30, 35, 40, 45 层），每条控制跳接都经零初始化门控投影后叠加到主分支。注入点数量约为 v1 的 2 倍，对控制视频的结构还原更严格。
  • 引导蒸馏：以 guidance_scale = 1.0 推理，每步仅需一次前向计算，无需 classifier-free guidance。
  • 支持视频修复，采用 post_norm 方案：控制输入拓宽至 control_in_dim = 49（潜变量 + 掩码后潜变量 + 掩码图通道）。与 v1 不同，掩码区域的像素是在 ImageNet 归一化之后置零（空洞为 0，对应中灰），而非归一化之前（v1 中空洞落在 −2 附近，接近纯黑），修复区域与保留区域的融合更加自然。对应脚本：examples/minimax_h3_fun/predict_v2v_control_inpaint.py。
  • control_context_scale 控制整体注入强度：它在控制跳接叠加回主分支前对其进行缩放——1.0 为最强控制（下方所有结果均用此值），调低可减弱控制视频的约束，0.0 则完全关闭控制分支。
  • 生成结果严格跟随控制视频：帧数自动向下取整到视频 VAE 可解码的最大 17 * n + 5（时长上限 15 秒）；画布在 height * width 像素预算内沿用控制视频自身的宽高比（二者均为 32 的倍数）；固定 24 fps 输出。
  • 提示词越详细，生成越稳定。建议在 prompt 中同时描述场景、主体与镜头运动。

支持的控制条件

条件 控制信号 2.0 新增？
Canny Canny 边缘图
Depth 单目深度图
HED HED 边缘检测图
MLSD 直线段检测图
Pose DWPose 人体骨架
Scribble 手绘 / 草图线条 ✅
Layout 边界框布局图 ✅
Gray 灰度（亮度）视频 ✅

Layout（布局）控制视频沿用 Wan2.1-VACE 的布局生成方案：将每个主体的边界框（通过检测/跟踪获得，或直接指定）以不同颜色绘制在白色背景上，渲染成一段普通的 RGB 视频作为控制输入。可直接复用 VACE-Annotators 的预处理工具（如 vace_preproccess.py --task layout_track ...），从参考视频或一组 bbox 生成布局控制视频。

生成效果

以下所有样例均在 num_inference_steps = 40、guidance_scale = 1.0、control_context_scale = 1.00、随机种子 43，画布模式 control、像素预算 704×1280、24 fps 的条件下生成。每组对比中，上排为控制视频，下排为生成结果。

CannyDepthHEDMLSD
PoseScribble ✨Layout ✨Gray ✨

视频修复（post_norm）

源视频中被打上掩码的区域会根据 prompt 重新绘制，画面其余部分原样保留。掩码视频中，需要重新生成的区域为白色，需要保留的区域为黑色。

源视频掩码修复输出

推理

更多细节请参见 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 基础模型与本 checkpoint 下载至 models/Diffusion_Transformer 下：

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

接着修改 examples/minimax_h3_fun/predict_v2v_control.py（视频修复用 predict_v2v_control_inpaint.py）顶部的配置项，然后运行：

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

python examples/minimax_h3_fun/predict_v2v_control.py

注意事项：

  • config_path 必须是 config/minimax_h3/minimax_h3_control_inpaint_post_norm.yaml：只有它能按 checkpoint 期望的结构完整搭建控制分支（control_blocks_places: [0, 5, 10, 15, 20, 25, 30, 35, 40, 45]、control_in_dim: 49、control_apply_audio: false、inpaint_masked_pixel_mode: post_norm）；若用 v1 的 minimax_h3_control.yaml（仅 5 个块），一半控制权重会被静默丢弃。
  • 纯控制（不做修复输入）时，pipeline 会自动把掩码通道补零，因此这个修复版 checkpoint 一样能正确跑普通的 Canny/深度/… 控制任务。
  • 本 checkpoint 经过引导蒸馏：请保持 guidance_scale = 1.0；大于 1 会叠加两次引导，反而损害画质。
  • 控制 checkpoint 只含控制分支，model_name 目录中必须有 MiniMax-H3 基础权重。
  • Layout 条件的控制视频请使用 Wan2.1-VACE 的布局生成管线制作（见支持的控制条件）；其余控制视频的格式与 v1 保持一致。
  • 显存：transformer（约 62 GB）加 Qwen3-VL 文本编码器（约 62 GB）无法在单张 80 GB 显卡上全量驻留；单卡 80 GB 请使用 model_group_offload（速度最快）或 model_cpu_offload_and_qfloat8。

许可证

本模型为 MiniMax-H3 的衍生模型，依据 MiniMax H3 社区许可证协议 发布。使用前请仔细阅读许可条款，尤其是地域限制与可接受使用政策（AUP）。