h3.c：antirez 用纯 C 给 Apple Silicon 写的 MiniMax-H3 推理引擎

原文来源：GitHub - antirez/h3.c — Redis 作者 antirez 用 C 语言和 Metal 为 Apple Silicon 打造的 MiniMax-H3 原生推理引擎，主打单文件架构、端到端文生视频、SSD 流式低内存运行。

antirez（Salvatore Sanfilippo）在离开 Redis 维护工作后，一直在做一些"写着玩但极其认真"的项目。这次他把目光转向了 MiniMax 的开源视频生成模型 H3：h3.c 是一个纯 C + Metal 的推理引擎，目标是在 Mac 上原生跑 MiniMax-H3，从模型解析、prompt 编码、视频/音频生成到首尾帧条件控制全部打通。项目发布没几天就冲上了 Hacker News 榜首，目前在 GitHub 已有 1100+ star。

这个项目解决什么问题

MiniMax-H3 是 MiniMax 开源的大型多模态模型，能根据文本生成视频和音频，还支持参考图/参考视频的条件生成。官方权重在 Hugging Face 上以 safetensors 格式发布，但官方推理链路依赖 MLX 等框架，在 Apple Silicon 上的性能和内存表现并不理想——33B 的 transformer 加上 Qwen 编码器和多路 VAE 解码器，全部驻留统一内存的话，普通配置的 Mac 根本跑不动。

h3.c 的思路是把整条推理管线用 C 和 Metal 重写：不依赖 Python、不依赖 MLX，直接读 safetensors 权重，自己实现 tokenizer、transformer、VAE、采样调度和视频编码。项目描述里写得很直白：按"垂直切片"的方式推进——先搞定确定性的模型元数据解析，再做 Metal 算子与 MLX 的数值对齐，然后是 prompt 编码、文生视频/音频，最后是首尾帧条件和多参考图（Ref2VA）。目前文生视频/音频、首尾帧条件、有序参考图已经端到端跑通，正在做 M3 Max 和 M5 Max 上的逐层性能优化。

上手体验：一条命令生成视频

项目的教程写得相当友好。假设 Hugging Face 的模型快照在 ./MiniMax-H3，并且系统里有 FFmpeg：

make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3

--info 只检查模型布局和 Metal 设备，不加载全部权重，适合快速验证环境。真正的生成命令长这样：

./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

这个"平衡预设"生成 22 帧（24fps，约 0.92 秒）的视频，--show 会在支持的终端（Kitty/Ghostty/iTerm2/WezTerm/Konsole）里实时显示中间帧。不带 -p 参数时，同一个二进制会进入交互式会话：输入 prompt 生成视频，支持 !status、!seed random、!seconds 2、!show、!save output.mp4 等命令，而且会缓存 prompt 条件和 DiT 状态，重复生成时不用重新加载。

条件生成也做得很完整。首尾帧控制可以直接指定锚点：

h3> !first opening.png
h3> !last ending.png
h3> The camera moves slowly around the subject.

更通用的 Ref2VA 参考图支持多张图按顺序追加，模型会以 <Picture 1>、<Picture 2> 的方式理解它们：

h3> !ref-image person.png
h3> Make the person shown in Picture 1 wave to the camera.

性能与内存：SSD 流式是最大亮点

h3.c 最让人眼前一亮的是内存控制。MiniMax-H3 的 DiT（扩散 transformer）部分如果全部驻留内存，在 512×512 分辨率下需要约 36.5 GiB。项目提供了 --ssd-streaming 模式：用原始 BF16 权重（不做转换和量化），同时只保留两个 DiT block 在内存里，GPU 算当前 block 时从 SSD 预读下一个。

实测数据（M5 Max，512 分辨率）：DiT 的存储占用从 36.5 GiB 降到 2.0 GiB（864×480 下是 2.1 GiB），代价是 50-block 完整前向从 1.35 秒变成 2.49 秒（约慢 84%）；在 864×480 下从 2.68 秒变成 2.14 秒反而更快（约 26% 提升，因为内存压力小了）。输出和全驻留路径逐字节一致。注意 2.0-2.1 GiB 只算 DiT 的张量存储，prompt 编码器和两个 VAE 是分阶段加载的，不会叠加峰值；--show 会额外驻留一个预览 VAE 增加约 10 GiB。

速度方面，项目给出了一组参考数据：512 分辨率、22 帧的狐狸测试，4 步去噪（--steps 4）在 M5 Max 上约 3.5 秒完成，对比 29 步参考路径的 26.4 秒；4 步结果对 29 步参考的 SSIM 是 0.556（冲浪测试 0.547）。也就是说，用大约 1/8 的时间能拿到视觉上很接近的结果。

质量与速度的取舍系统

h3.c 的 CLI 参数设计得像一个完整的调优框架，几个关键旋钮互相独立：

另外还有 --use-int8-row-fc2：每行一个激活 scale 的单次全宽 TensorOps 乘积，M5 上完整去噪前向提速约 2.6%，四步狐狸和冲浪视频保持 SSIM 0.919 / 0.828。每个优化开关都配了对应的 --use-slower-* 反向参数用于数值对比，这在推理引擎里是很少见的严谨。

antirez 还解释了一个反直觉的工程决策：他们试过多种"尾部密集"的采样调度，因为大部分可见清理发生在长跑的后期，但这类调度保留的早期构图更新太少，导致织物质感、运动弱、颜色发灰。最终保留的是线性 base grid 加一个终止点的方案。

适合谁用

h3.c 适合三类人：想在 Mac 上本地跑 MiniMax-H3 视频生成的用户（不用碰 Python 和 MLX）；对 Metal 算子优化、扩散模型推理性能感兴趣、想读源码的开发者（项目代码结构清晰，从 host 脚手架到 Metal kernel 分得很开）；以及想了解"单文件 C 工程如何组织大型推理项目"的人。

不适合的场景：需要分布式训练或微调——这是纯推理引擎；Windows/Linux 用户——Metal 绑定死了 macOS；想要一键 GUI 的人——目前是 CLI 和交互式终端。

对比 MLX 方案，h3.c 的优势是内存控制（SSD 流式）和逐字节可控的数值行为；劣势是生态和文档不如 MLX 成熟，且只支持 Apple Silicon。对 Mac 用户来说，这可能是目前把 MiniMax-H3 跑起来的资源占用最低的路径。