今天在 GitHub Trending 上看到一个有意思的项目：MiniMax-AI/MiniMax-H3，一个通用全模态（omni-modal）生成系统，能在端到端流程中直接产出带原生立体声音频的高分辨率视频。它不只是又一个文生视频模型，而是把"理解"与"生成"放在同一套多模态序列里统一处理。

一、项目概述

MiniMax H3 是一个通用、全模态的生成系统。它的核心能力可以概括为两点：

  1. 统一的多模态理解：能够理解由文本、图像、视频、音频组成的任意混合上下文（context），并在预训练阶段就具备广泛的跨模态指令跟随能力。
  2. 原生音视频联合生成：直接生成视频与立体声音频，分辨率最高可达 2K，时长 4–15 秒，输出 24 FPS、32 kHz 立体声。

它支持丰富的输入/输出规格：

维度规格
输出时长4–15 秒
输出宽高比21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
输出分辨率短边默认 768px；2K 经由 H3-Regenerate-2K
输出帧率24 FPS
输出音频32 kHz 立体声
对话语言中英日韩等 11 种稳定支持

H3 开源发布了两个任务专用检查点：

  • H3-Base-FL2VA：首帧/尾帧模式。支持 0/1/2 张输入图——无图即文生视频（t2va），单图即首帧或尾帧生视频（fl2va），双图即首末帧生视频。
  • H3-Base-Ref2VA：全参考（omni-reference）模式。支持 ≤ 9 张图、≤ 3 段视频、≤ 3 段音频的混合参考输入，总文件数上限 12。

此外，仓库还附带 9 个 skill：其中 h3-prompt-writing 是纯 Markdown + 参考文件的通用提示词 skill（兼容 Claude Code、Cursor、OpenAI Agent 等任意能读取 SKILL.md 的 harness），其余 8 个是面向 MiniMax Hub 画布工作流的风格化视频生成 skill。

二、技术原理

完整的 H3 系统由三个模块构成，理解→生成→升分辨率形成端到端流水线。

2.1 H3-Context-IR：多模态上下文预处理（托管 API）

H3-Context-IR 是面向自由形式多模态输入的预处理与编排系统。它解析文本、图像、音频、参考视频之间的关系，以及这些素材与"期望生成结果"之间的关系，内部包含指令解析、跨模态关联、时序理解与复杂逻辑推理四个阶段，最终把理解结果序列化为 H3-Base 可接受的上下文中间表示（Context-IR）。

官方强调：Context-IR 的质量直接决定最终输出质量，强烈建议把它接入生成流水线，或参照 Prompting Guidance 自建上下文处理系统。由于依赖多阶段工作流和多个托管模型，该模块未随开源发布，仅提供可复现官方行为的 API。

2.2 H3-Base：33B 单流 Omni-Transformer

H3-Base 的架构非常"克制"，从源码披露看，它把不同模态编码进统一的 packed 多模态序列，再用一个单流 Transformer 联合预测视频与音频 latent：

  • H3-Encoder：直接复用 Qwen3-VL-32B 的全量预训练权重，取第 50 层 hidden states 喂给 Omni-Transformer；并新增了 <d> 等特殊 token，因此使用时必须配套仓库内的 tokenizer 配置。
  • H3-VisualVAE：时序因果视频自编码器，空间压缩 16×、时序压缩 4×、24 个 latent 通道（记为 f16t4d24）。在进入 Transformer 前还会做 1×2×2 的 patchify，使得视觉 token 的有效空间下采样达 32×、时序 4×。训练后额外训练了一个 ViT 解码器，兼顾重建质量与解码成本。
  • H3-AudioVAE：左右声道共用同一套编解码器、各自独立处理，再重组成立体声；每声道把 32 kHz 音频压缩成 40 Hz 的 latent 序列。
  • H3-Omni-Transformer：33B 参数稠密单流 Transformer，其中约 13B 位于 AdaLN 相关分支（推理部署时可预计算并缓存，无需加载）。注意力与 FFN 层均不含模态特定结构，模态差异仅体现在输入/输出层和 AdaLN 分支；位置信息采用三维 MM-RoPE (t, h, w)。训练末期引入了原生稀疏注意力以降低长序列开销（初版开源自带 full attention 推理，稀疏注意力后续开源）。

2.3 H3-Regenerate-2K：用基座模型"重画"高清

传统做法是接一个专用超分模块，而 H3 选择让基座模型以 in-context 方式重新生成自己的低清结果：把 768p 结果与原始上下文一并喂回 H3，再生成 2K 输出。这样做有两个优势——（1）最大程度复用基座的生成能力；（2）in-context 形式能复用原始多模态上下文，从而恢复超分方法只能"猜"的细节（如小文字、精细纹理）。该模块目前尚未开源，通过官方 API 验证结果。

三、安装与快速开始

3.1 环境要求

模型以 Hugging Face diffusers 流水线形式发布，核心依赖如下（来自仓库 requirements.txt）：

torch>=2.4.0
diffusers>=0.32.2          # 官方文档指向 minimax-h3 分支，必要时 pip install 源码版
transformers>=4.45.0       # 提供 Qwen3-VL 文本编码器
safetensors>=0.4.3
accelerate>=0.34.0         # 33B 模型多卡加载
huggingface_hub>=0.25.0    # hf CLI 下载
numpy>=1.24.0
Pillow>=10.0.0
soundfile>=0.12.0          # 音频写出
imageio>=2.34.0 / imageio-ffmpeg>=0.5.0 / av>=11.0.0  # 视频 I/O

提示：当前 main 分支的 diffusers 可能尚未合入 H3 类，建议安装源码版 pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"（见仓库 issue #3）。

3.2 下载模型

H3 的检查点以自包含 HF 风格仓库分发，下面按任务族下载：

# 原始检查点（SGLang / vLLM 用）
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" "Ref2VA/*" --local-dir MiniMax-H3

# 仅 FL2VA 任务族
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3

diffusers 用户无需手动下载，ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 会自动拉取所需组件。

3.3 最简部署（SGLang）

官方推荐 SGLang / vLLM / diffusers / ComfyUI 四种推理框架。以 SGLang 为例：

# FL2VA 服务
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 --port 30010 \
  --model-variant fl2va

# Ref2VA 服务
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 --port 30011 \
  --model-variant ref2va

四、使用方法与实战

4.1 本地 768p 复现

仓库提供了三个可复现用例脚本：T2VA（文生视频）、FL2VA（首末帧生视频）、Ref2VA（多模态参考生视频），分别对应 reproducible-768p-*-request.sh，可直接跑通 768p 音视频生成。

4.2 完整 2K 工作流（本地 H3-Base + 官方 API）

要复现 API 直出的 2K 质量，需要把本地 SGLang 服务与官方 H3-Context-IR、H3-Regenerate-2K 两个 API 串联：

# 本地 SGLang 端点
SGLANG_DEPLOYMENT_URL="<sglang-deployment-url>"

# MiniMax API（CN / Global 二选一）
MINIMAX_API_BASE="https://api.minimaxi.com"
# MINIMAX_API_BASE="https://api.minimax.io"

# 平台申请的 Token
TOKEN="<token>"

整个流程分三步：先用 H3-Context-IR API 把自由输入转成结构化 Context-IR（官方示例里它被正确化成了带镜头、声景、非叙事音乐的精细 prompt），再交给本地 H3-Base 出 768p 音视频，最后用 H3-Regenerate-2K API 升到 2K。仓库对 T2VA、首帧图生视频（I2VA）、多模态参考生视频（Ref2VA）三种 case 都给出了端到端脚本与参考输出。

4.3 提示词 Skill（通用 harness 可用）

如果你想把 H3 的提示词经验直接装进自己的 Agent：

npx skills add https://github.com/MiniMax-AI/MiniMax-H3 --skill h3-prompt-writing

它提供 base-en.txt（文本/关键帧模式）与 ref-en.txt（全参考 Ref2VA 模式）两份提示词指南，纯本地文件、无外部 API 调用，通用性很强。

五、常见问题与解决方案

Q1：pip 装好 diffusers 后仍报找不到 H3 模型类？ A：当前 PyPI 的 diffusers 可能尚未合入 H3 相关类。按 requirements.txt 注释，安装源码分支：pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"（对应 issue #3）。

Q2：推理报错 tokenizer / 特殊 token 缺失？ A：H3 向 tokenizer 注入了新的特殊 token（如 <d>）。务必使用仓库随附的 tokenizer 与配置文件，不能用默认的 Qwen3-VL tokenizer 直接替换。

Q3：显存不够、多卡加载失败？ A：33B 稠密模型需要 accelerate 做 device_map/多卡切分；SGLang 部署示例使用 4 卡 + --ulysses-degree 4。单卡部署需确认 BF16 权重与足够显存。

Q4：Context-IR / Regenerate-2K 为何不在开源权重里？ A：这两个模块依赖多阶段托管服务，初版未开源。官方通过 API 提供行为复现与结果验证；社区可参照 Prompting Guidance 自建 Context-IR 预处理系统。

Q5：内容被拦截 / 生成失败？ A：用户提交的文本、图像、视频及增强后的 prompt 都会经过自动化审核，敏感或侵权内容可能被拦截（存在误杀可能）。请遵守 MiniMax H3 社区许可协议中的合法使用与限制条款。

六、总结

MiniMax H3 的亮点在于用一套统一的多模态序列 + 单流 33B Transformer，把"理解复杂跨模态指令"和"联合生成视频与立体声音频"做到了端到端。Context-IR 预处理、VisualVAE/AudioVAE 独立的 latent 设计、以及"用基座 in-context 重画 2K"的思路，都体现了对音视频一致性与细节保真的工程取舍。虽然 Context-IR 与 Regenerate-2K 仍以 API 形式提供，但开源的 H3-Base（FL2VA / Ref2VA 双检查点）配合 SGLang/vLLM/ComfyUI，已经足以让社区本地复现 768p 音视频，并对照官方 2K 结果做验证。对多模态生成、视频 Agent 方向感兴趣的开发者，值得把它纳入自己的工具链试一试。