--- 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](https://img.shields.io/badge/🎬%20Code-VideoX_Fun-blue)](https://github.com/aigc-apps/VideoX-Fun) ## 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](https://github.com/ali-vilab/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 仓库并创建模型目录： ```sh # 克隆代码 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`）顶部的配置项，然后运行： ```python 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" ``` ```sh 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](https://github.com/ali-vilab/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 社区许可证协议](LICENSE) 发布。使用前请仔细阅读许可条款，尤其是地域限制与可接受使用政策（AUP）。