antirez/h3.c · 上手攻略

• 仓库：antirez/h3.c
• 链接：https://github.com/antirez/h3.c
• 分类：AI 推理引擎 · 视频生成 · Apple Silicon
• 作者：Tom
• 更新：2026-08-23

这是什么

h3.c 是 MiniMax H3 视频/音频生成模型的原生 Metal 推理引擎，专为 Apple Silicon 设计。由 antirez（Redis 作者）手写 C + Metal 实现，不依赖 Python 或 PyTorch，直接跑在 Mac 的 GPU 上。

H3 是 MiniMax 开源的多模态生成模型，支持文生视频、文生音频、首帧/尾帧条件化、Ref2VA 有序参考（图片/视频/音频输入）。h3.c 把这个模型本地化到 Mac，无需云端算力，在 M3/M5 Max 上即可跑出可用的视频生成结果。

⚠️ 项目处于活跃开发阶段（"vertical slices"方式迭代），README 中的性能数字和参数可能随版本变化。

解决什么问题

现有 H3 Mac 推理方案的痛点：

• ComfyUI / MLX 端口慢：非原生实现，512×512 视频动辄 15 分钟以上
• 需要 Python 环境：依赖链重，不适合轻量部署
• 显存/内存压力大：H3 checkpoint 约 33 GB，峰值物理内存约 40 GB

h3.c 用纯 C + Metal 直接对接 Apple GPU，去掉所有中间层，实现了：

• M5 Max 512×512 约 16.69 秒（45 层 + reuse 2，默认质量）
• 4 步去噪激进模式约 3.5 秒（画质打折但可用）
• SSD 流式模式：DiT 存储从 ~36.5 GiB 降至 ~2.0 GiB（牺牲约 26-84% 速度换取内存）

快速安装

前置要求

• macOS（Apple Silicon，M3 Max 或 M5 Max 测试通过）
• Hugging Face 上的 MiniMax-H3 checkpoint 放在本地 ./MiniMax-H3 目录
• ffmpeg 和 ffprobe 在 PATH 中
• 编译工具（make、clang）

编译

git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j8

下载模型

# 约 33 GB，需要登录 HuggingFace
# 使用 huggingface-cli 或手动下载 MiniMax-H3 权重
# 放到 ./MiniMax-H3 目录
mkdir -p outputs

验证模型布局

./h3 --info -d ./MiniMax-H3

--info 只检查模型布局并打印选中的 Metal 设备，不会加载全部权重或生成媒体。

核心用法

交互式 REPL（推荐入门）

不加 -p 启动交互式会话，保持 BF16 prompt conditioning、DiT、视频解码器在内存中，重复 prompt 不用重新加载：

./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6

常用命令：

推荐首发配置（验证过的均衡预设）

./h3 --profile \
  -d ./MiniMax-H3 \
  -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." \
  --width 512 --height 512 \
  --frames 22 --steps 20 \
  --layers 45 --reuse 2 \
  --show \
  -o outputs/fox-fast.mp4

• --steps 20：20 步去噪（默认档）
• --reuse 2：跳过一半去噪转换，用速度换质量
• --layers 45：用 45/50 个 transformer 块（省显存）
• --show：在支持的终端（Kitty/Ghostty/iTerm2/WezTerm/Konsole）显示逐帧预览

质量档位控制（可组合）

最小可跑命令（4 步激进）：

./h3 --profile \
  -d ./MiniMax-H3 \
  -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur." \
  --width 512 --height 512 --frames 22 \
  --steps 4 --layers 50 --reuse 1 \
  --show \
  -o outputs/fox-4step.mp4

4 步约 3.5 秒出结果，与 29 步参考（约 26.4 秒）SSIM 约 0.55，内容和运动保持一致。

低内存模式（SSD 流式）

./h3 --profile \
  -d ./MiniMax-H3 \
  -p "A red fox walks through fresh snow in a pine forest." \
  --width 512 --height 512 --frames 22 --steps 20 \
  --layers 50 --reuse 1 --ssd-streaming \
  -o outputs/fox-ssd.mp4

DiT 存储从 ~36.5 GiB 降至 ~2.0 GiB（512px），速度慢约 84%（1.35s → 2.49s）。注意 --show 保持预览 VAE 常驻额外 ~10 GiB。

分辨率与时长

• 输出宽高必须是 32 的倍数，最小 32×32
• H3 输出 24 fps，时长向上取整到合法帧数：22帧≈0.92s、243帧≈10.1s
• --seconds N 自动换算帧数（比直接指定 --frames 更直观）
• 支持最大 1344×768

终端预览（可选）

# 使用 --show 显示逐帧预览（iTerm2 / WezTerm / Konsole / Kitty / Ghostty）
./h3 --profile ... --show ...

# 或输出 PPM 帧文件
./h3 ... --frames-dir ./frames ...

# 禁用 MP4 编码（ffmpeg 不可用时）
./h3 ... -o ''

典型适用场景

1. 本地视频生成原型：不依赖云端，在 M3/M5 Max 上快速验证 prompt 效果
2. prompt 迭代：交互式 REPL 保持状态，重复 seed 调试细节
3. 首帧/尾帧条件化：控制视频起止画面，实现情节连贯的短视频序列
4. Ref2VA 多模态参考：输入图片或视频片段作为生成引导
5. 内存受限环境：SSD 流式模式在 2 GiB DiT 占用下运行（适合非工作站 Mac）

坑与注意

1. M5 Max 实测数据，MacBook 会降频：桌面 M5 Max 跑满载长时间生成不会降频，笔记本用户注意散热和热节流
2. 首次运行付模型加载成本：比较性能应从第二次运行开始
3. --reuse 和 --core-reuse 互斥：不能同时开启
4. --ssd-streaming 不能与 --use-int8-row-fc2 并用
5. --token-reduction + --layers 40 + --reuse 3 三合一会出色彩振铃：验证过的组合，不要再叠加
6. 512×512 是最稳妥开发尺寸：README 明确推荐，其他尺寸模型质量未充分验证
7. 256×256 自动半频 RoPE：避免了伪影但细节和构图空间有限
8. 数值像素级与 MLX 不一致：随机数和执行引擎不同，内容和运动应一致，但不保证逐像素相同
9. 视频音频生成：README 提到支持但未展开详细用法，文档尚不完整

与同类对比

h3.c 的核心优势是无 Python 原生 Metal 实现：绕过 Python 开销，直接调用 Apple GPU，在 Mac 上实现本地视频生成的工程可行性。

一句话推荐结论

在 Apple Silicon Mac 上跑 MiniMax H3 视频生成的首选开源引擎——纯 C + Metal、无 Python 依赖、M5 Max 16 秒出 512px 视频，适合本地 prompt 迭代和轻量视频原型。（⚠️ 需 33 GB 模型文件 + ~40 GB 峰值内存，请确认硬件条件再动手）

来源：GitHub README (https://github.com/antirez/h3.c) · Web 搜索补充 (daily.dev / aiweekly.co / qwe.edu.pl / X @MiniMax_AI 2026-08-10 推文)

待验证：int8 QKV 路径具体参数、音频生成详细用法、--core-reuse 与 --reuse 性能对比数字。