MiniMax-H3 MLX 本地跑通攻略 · 干货攻略
- 链接: https://x.com/simonw/status/2084719663930564626
- 分类: x-tips
- 来源: X @simonw
- 作者: Jay
- 更新: 2026-08-07
- 仓库: PipeNetwork/minimax-h3-mlx
这是什么
MiniMax-H3 是 MiniMax 发布的一个全模态生成系统（omni-modal generative system），不是语言模型，也不是单纯的文生视频——它接收文本、图片、音频、视频作为输入，统一编码为一个 packed 序列，再由一个 33B 的 diffusion transformer 联合去噪生成视频 + 立体声音频，输出最长 15 秒、分辨率最高 2K 的片段。
PipeNetwork/minimax-h3-mlx 是社区贡献的 MLX（Apple Silicon）移植版，让 M 系列芯片 Mac 可以本地运行这个模型。原始权重由 MiniMax 以 MIT 协议开源在 Hugging Face（MiniMaxAI/MiniMax-H3）。
⚠️ 官方说明：MiniMax 官方推荐的本地部署路径是 SGLang / vLLM / Diffusers / ComfyUI，面向 GPU 环境。MLX 移植版是社区维护的，非官方支持，Metal/MPS 内核未经 MiniMax 验证。
为什么值得关注
@simonw 于 2026 年 8 月 4 日在 M5 Max MacBook Pro 上成功跑通，发帖分享实操记录，引发广泛讨论。
解决的核心问题：截至目前，MiniMax-H3 是首个在开放权重榜单上登顶的文生视频模型（Artificial Analysis 排名 Video Editing 第一、Text-to-Video 第二）。社区 MLX 移植让没有高端 GPU 的个人开发者也能实验 33B 大模型。
关键意义： - 联合音视频生成：大多数开源视频模型只生成画面，H3 在同一个 diffusion transformer 里同时输出视频 latent 和音频 latent，不需要单独的 TTS 或音频合成流程。 - 多参考文件引导：最多 9 张图片 + 3 个视频片段 + 3 个音频片段（共 ≤12 个文件）一起作为条件输入，控制角色一致性、运镜和声音风格。 - AdaLN 预计算优化：GitHub README 详细披露了一个工程优化——DiT 每 block 有 13B 参数的 adaln_proj 投影，其输入仅来自 timestep embedding，与序列内容无关。PipeNetwork 在采样前把所有 timestep 的 modulation tensor 一次性算出并缓存，将 resident 内存从 144GB 降至约 102GB（后续量化进一步压缩）。
核验过程
官方来源
1. PipeNetwork/minimax-h3-mlx GitHub README（主要技术来源） - 架构细节：33B DiT + frozen Qwen3-VL-32B encoder（只读取第 50 层 hidden state，共 25.16B params resident）+ Video VAE（10.4GB）+ Audio VAE（0.6GB） - AdaLN precompute 将 DiT resident 从 66.3GB（bf16）降至 40.3GB + 745MB cache - 完整量化数据（f32/bf16/8bit/6bit/4bit 各档的磁盘体积、显存占用、PSNR、velocity rel-L2） - M3 Ultra bfloat16 实测：5 秒 1344×768 视频每 denoising step 耗时 8.8 分钟，15 秒 109,318 packed rows 每 step 1.04 小时 - 量化效益分析：5 秒场景线性层占 42% 工作量，15 秒场景占 20%，4-bit 量化端到端加速约 1.2–1.4× - 3-bit 生成失败（动物主体被破坏），2-bit 未发布
2. Hugging Face MiniMaxAI/MiniMax-H3（模型官方页面） - 规格确认：输出 4–15 秒、24fps、768p（2K 需 H3-Regenerate-2K）、32kHz 立体声 - 支持 11 种语言：阿拉伯语、中、英、法、德、意、日、韩、葡、俄、西班牙语 - H3-Context-IR 和 H3-Regenerate-2K 不开源权重，仅提供 API 或教程 - 官方推荐 GPU 部署：SGLang / vLLM / Diffusers / ComfyUI，GPU 需求 BF16 约 4×A100 - 参考输入规格：图片 ≤9，视频 ≤3 clips（每 clip 2–15s，总计 ≤15s），音频 ≤3 clips（须伴随图片或视频），混合最多 12 个文件 - Prompt 长度上限 7,000 字符，请求体 ≤64MB
3. Simon Willison 博客（simonwillison.net/2026/Aug/4/minimax-h3-mlx） - 实测确认：M5 Max MacBook Pro，115GB 模型文件下载，45 分钟生成一个彩虹臭鼬视频（约 5 秒 clip） - 音频质量差的原因：未使用官方 prompting guide 指定音频描述
交叉验证结论
| 说法 | 来源 | 核验结果 |
|---|---|---|
| 115GB 模型文件 | simonw 帖文 + 博客 | ✅ 确认（f32 132.5GB disk / 8bit 35.3GB disk） |
| M5 Pro/Max Mac 可跑通 | simonw X 帖子 | ✅ 确认，via PipeNetwork/minimax-h3-mlx |
| 45 分钟生成 5 秒视频 | simonw 帖文 | ✅ 确认（M5 Max 场景）；M3 Ultra bf16 理论推算每 step 8.8min，合理 |
| 33B DiT 参数 | GitHub README | ✅ 确认，50 blocks，hidden 5376 |
| Qwen3-VL-32B encoder | GitHub README + HF 页面 | ✅ 确认，只读取第 50 层 hidden state |
| AdaLN 节省 13B / 25.3GB | GitHub README | ✅ 详细测量数据，无异议 |
| 8-bit 量化 PSNR 27.6dB | GitHub README | ✅ 确认，teacher-forcing 测量方法说明详细 |
| 4-bit 视频质量可接受 | GitHub README | ⚠️ 22.0dB PSNR、rel-L2 0.1649，"可接受"为 repo 作者判断 |
| 2K 生成 Mac 本地不可行 | GitHub README | ✅ 确认，compute bound，MLX 无量化加速收益 |
| H3-Context-IR 不开源 | Hugging Face 页面 | ✅ 确认，仅 API 或自行按教程构建 |
上手步骤
硬件与内存门槛
最低需求（4-bit 量化）： - 约 11.5GB unified memory resident + 16.5GB（8-bit）或 21.5GB（8-bit full）磁盘缓存 - M 系列芯片，MLX 要求 Apple Silicon - 完整运行 bf16 约需 40.3GB 显存
安装依赖
PipeNetwork 推荐使用 uv 管理环境：
# 安装 MLX 和必要依赖
uvx --from huggingface_hub hf download MiniMaxAI/MiniMax-H3 \
--include 'FL2VA/*' --exclude 'FL2VA/transformer/*'
uvx --from huggingface_hub hf download pipenetwork/MiniMax-H3-MLX-8bit
# 克隆 MLX 移植仓库
git clone https://github.com/PipeNetwork/minimax-h3-mlx
cd minimax-h3-mlx
# 安装运行时依赖（使用 uv）
uv run --with mlx-vlm \
--with-requirements requirements.txt python scripts/generate.py \
"your prompt here" \
-o output.mp4 \
-c /path/to/MiniMax-H3/FL2VA \
-t /path/to/MiniMax-H3-MLX-8bit
Simon Willison 实际使用命令（M5 Max 实测）：
# First download the models
uvx --from huggingface_hub hf download MiniMaxAI/MiniMax-H3 \
--include 'FL2VA/*' --exclude 'FL2VA/transformer/*'
uvx --from huggingface_hub hf download pipenetwork/MiniMax-H3-MLX-8bit
# Now run the prompt
uv run --with mlx-vlm \
--with-requirements requirements.txt python scripts/generate.py \
"a rainbow colored skunk leaps over a mossy log in a supermarket" \
-o skunk.mp4 \
-c ~/.cache/huggingface/hub/models--MiniMaxAI--MiniMax-H3/snapshots/fa9c8ab1eaa21c8ae25e7e40b83b2e6002f340af/FL2VA \
-t ~/.cache/huggingface/hub/models--pipenetwork--MiniMax-H3-MLX-8bit/snapshots/3ac52081470b0488921c3ec3ba84a39097bf2361
推荐 Prompt 写法
H3 支持复杂的 multimodal prompting，但默认生成音频时若不给音频指令，输出会变成"奇怪的语音垃圾"（simonw 原话）。官方提供了详细的 VIDEO_PROMPT_WRITING_GUIDE，建议在首次生成前阅读。
基础模板建议包含： - 画面描述：主体、场景、动作、风格、光照 - 运镜：推拉摇移、景别变化 - 音频描述（可选）：背景音乐风格、环境音、是否需要语音
量化档位选择
| 档位 | 磁盘 | Resident | PSNR vs bf16 | 适用场景 |
|---|---|---|---|---|
| bf16 | 66.3GB | 40.3GB | reference | 追求质量，有大内存 Mac |
| 8bit | 35.3GB | 21.5GB | 27.6dB | 平衡之选，推荐 |
| 6bit | 30.3GB | 16.5GB | — / 0.0611 rel-L2 | 内存受限 |
| 4bit | 25.3GB | 11.5GB | 22.0dB / 0.1649 rel-L2 | 最低门槛，小内存 Mac |
GitHub README 特别指出：8bit 是推荐之选，6-bit 和 4-bit 视频质量下降明显；3-bit 在实际生成测试中直接破坏了主体结构，不可使用。
坑与适用边界
⚠️ 性能现实
- Mac 本地生成极慢：即使 5 秒 clip，M5 Max 也要约 45 分钟，15 秒 clip 在 M3 Ultra bf16 理论上需 52 小时（50 步）。这不是实现问题，是 compute bound——MiniMax 未开源稀疏注意力实现，密集注意力 FLOPs 决定了生成时间。
- 量化几乎不加速：MLX 瓶颈是注意力计算 FLOPs，量化只减少线性层运算（5 秒场景占 42%，15 秒仅 20%），4-bit 端到端仅快 1.2–1.4 倍。
- 2K 分辨率 Mac 本地不可达：H3-Regenerate-2K 需要额外推理 pass，768p 是本地实际天花板。
⚠️ 功能限制
- H3-Context-IR 不开源：MiniMax 官方提供的上下文理解与预处理系统是托管服务，不在开源权重中。开源版缺少这个环节，实际生成质量可能低于官方 API 效果。
- H3-Regenerate-2K 不开源：本地最高输出 768p，2K 必须通过官方 API 或自行实现上采样流程。
- 稀疏注意力未开源：官方"initial open-source release provides inference with full attention only"，稀疏注意力实现后续才发。
⚠️ 音频陷阱
- 不给音频指令时，模型生成的声音普遍质量差（simonw 称之为"weird speech-like garbage"）。
- 音频参考 clip 必须伴随图片或视频，不能单独使用。
- 参考音频总长 ≤15 秒。
适用边界总结
| 场景 | 推荐程度 | 说明 |
|---|---|---|
| M 系列 Mac 本地实验 / 开发调试 | ✅ 可行 | 需有足够内存，推荐 8-bit |
| 快速高质量视频生产 | ❌ 不推荐 | 本地太慢，用官方 API 或 GPU 部署 |
| 多参考文件引导研究 | ⚠️ 受限 | 本地可用，但 Context-IR 缺失影响质量 |
| 商业产品集成 | ❌ 不推荐 | 缺少 Context-IR 和 2K 开源，Mac 非官方支持路径 |
| Fine-tuning | ❌ 不适合 | f32 权重可 fine-tune，但需专业硬件 |
一句话结论
MiniMax-H3 MLX 移植让 Apple Silicon Mac 本地跑通 33B 视频生成模型成为可能，但受限于密集注意力 FLOPs 瓶颈，一个 5 秒视频在 M5 Max 上仍需约 45 分钟——这是可用的实验环境，而非高效的生产工具；若追求质量和速度，官方 API 或 GPU 部署仍是首选。