h3.c：MiniMax-H3的Mac原生推理引擎

h3.c 是在 Apple Silicon 上运行 MiniMax-H3 的原生音视频推理引擎。它把模型加载、提示词编码、去噪、图像与音频解码及媒体封装做成命令行与 C 库，适合研究本地模型执行路径。仓库是 antirez/h3.c，代码采用 MIT 许可；它不是一个新的基础模型。

我们在 M4 / 16GB / macOS 26.6.2 上完成源码构建、帮助命令与不依赖已下载大模型的测试。主机测试报告 1768 个检查通过，音频 Metal 基础算子与 FFmpeg 合成样例也通过；11 条需要外部权重或 fixture 的测试分支被跳过。本次没有下载 MiniMax-H3 权重，也没有生成模型视频或测量模型速度。

官方仓库：https://github.com/antirez/h3.c

固定源码：8974cc055ea9c02fcd14cc27dfda3e1027c05153；核验日期：2026 年 10 月 16 日。

它在本地推理栈中负责哪一层？

项目主要由 C、Objective-C 和 Metal 实现，链接 Apple 的 Metal、MPS、MPSGraph、Accelerate 等框架，构建产物包括 h3 与 libh3.a。因此，“没有用 Python 运行前向”不等于完全不使用张量图框架；MPSGraph 正是其中的重要实现路径。

README 描述了文本到视频与音频、首尾帧条件以及有序图像、视频、音频参考。提示词编码、DiT 与两个 VAE 等阶段有独立的内存与执行安排，最终把视频画面和音频交给 FFmpeg 封装。真正的模型能力仍来自所加载的 MiniMax-H3 检查点，不能仅凭引擎名字推断质量提升。

若想看同一模型在另一套 Mac 管线中的位置，可对照我们此前的 Vpipe 介绍： https://blog.mushroom.cv/blog/vpipe-minimax-h3-apple-silicon-video-audio-local-metal-cpp-pipeline/

第一次运行，怎样区分构建成功与生成成功？

git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j4
./h3 --help
# 另行准备模型检查点后再执行：
./h3 --info -d ./MiniMax-H3

--info 检查模型目录并显示设备信息，不映射全部权重，也不生成媒体。我们本次只运行帮助命令，没有用一个不存在或伪造的模型目录冒充模型验收。

没有 -p 时可进入交互会话；源码说明会复用提示词条件、准备好的 DiT 和解码器状态。缓存可以减少重复工作，也意味着资源会继续驻留，不能把交互模式的常驻内存与每次退出进程的模式直接混比。

真实媒体输入与 MP4 输出要求 FFmpeg、FFprobe 可用。项目在运行时编译 Metal 源码，不要求额外安装 Xcode 的离线 Metal 工具链；这并不免除系统 SDK、编译器或具体硬件能力要求。

快速预设到底省掉了什么？

官方入门示例采用 512×512、22 帧、24fps，长度约 0.92 秒，配合 --steps 20 --layers 45 --reuse 2。这是一段很短的调试样例，不能拿它的耗时当成五秒或一分钟成片的速度。

控制项	含义	需要保留的边界
--steps	去噪调度中的实际步数	4 步和 50 步不是同一质量条件
--layers	参与执行的 Transformer 块数	45/50 表示少执行部分块，不是纯粹无损内核优化
--reuse	复用并外推部分去噪结果	20 步、reuse 2 时只有 11 次新鲜 DiT 评估
--core-reuse	降低部分核心计算的刷新频率	与整段去噪复用不同，应分别记录
内部画布与 token reduction	减少内部计算规模	可能影响构图、细节或运动

文档中预设表的“Default”列容易造成误读：当前 h3.h 初始化与教程正文给出的实际缺省是 steps 20、layers 50、reuse 1。45 层、reuse 2 是快速入门选择。对照时显式写参数，比依赖表头更可靠。

参数定义： https://github.com/antirez/h3.c/blob/8974cc055ea9c02fcd14cc27dfda3e1027c05153/h3.h

“2GiB显存”为什么不能等同整机只需2GiB？

作者报告 --ssd-streaming 在 M5 Max 上把 512 方形样例的 DiT 跟踪张量存储从约 36.5GiB 降到 2.0GiB：保留两个块，GPU 算当前块时从 SSD 读取下一个块。原始 BF16 权重不需要先转换或量化，但存储与带宽参与了执行。

这不是完整进程峰值，也不是统一内存总需求。提示词编码、VAE、媒体缓冲和操作系统仍需要空间。作者同一形状的暖启动单次前向对照为 1.35 秒与 2.49 秒，流式路径更慢；864×480 则为 2.14 秒与 2.68 秒。它是用速度换驻留内存，而不是每个维度都更好的开关。这些是作者报告，不是我们的 M4 数据。

--show 还会保留预览 VAE，文档估算额外增加约 10GiB，因此不能一边宣传最低内存，一边不说明演示中开了预览。SSD streaming 不是默认选项，且不能与指定的 --use-int8-row-fc2 路径组合；不同 M 系列芯片的 TensorOps 优化也不可直接互换。

我的判断是，评估这类引擎至少要同时记录硬件、分辨率、帧数、步数、执行层数、复用率、精度、是否预览及权重驻留策略。缺其中几项，所谓“快了多少”很容易是在比较不同的工作。

首尾帧与参考素材，不能混成一个开关

交互会话用 !first / !last 设置首尾锚点，用 !ref-image 添加一般参考图。参考按添加顺序命名为 Picture 1、Picture 2，文件名本身没有模型语义。作者明确说明一般 Ref2VA 参考不能和首尾帧锚点混用。

这些接口提供不同条件路径，不能直接推出跨片段人物永远一致或每个参考约束都会严格满足。我们本次没有用真实模型检查这些效果。

本机验证结果与尚未覆盖的部分

M4 / 16GB / macOS 26.6.2 上，原始源码 make -j4 成功，产生可执行文件与静态库；h3 --help 正常。make test 成功退出，主机确定性测试报告 1768 个检查；此外，六类 AudioVAE Metal 基础运算与主机参考对照通过，FFmpeg 并行视频/PCM 管道写出了一个 51,750 字节的合成测试 MP4。

这里的 MP4 来自封装测试的合成输入，不是 MiniMax 生成。完整测试输出还有 11 条明确的 skip：包括 MLX toy-block、tokenizer、Qwen、真实 VAE、视觉与多模态参考 fixture 等缺失分支。不能把成功退出码改写为所有权重路径或 MLX 完整数值对齐已测过，也不能把 1768 个断言说成 1768 次真实模型测试。

我们没有测端到端 H3 效果、完整模型内存、长片或模型速度。16GB 的本机能构建和运行这些小测试，不构成真实 H3 在16GB上完整可用的结论。

谁更适合研究这个项目？

需要命令行、C 接口、内核与内存策略可见性的开发者，可以从它入手。它提供了可检查的阶段分解、参数入口与测试工具。偏好图形工作台、素材管理和时间线的用户，应另看 Valtz 或 Vpipe 的产品界面；它们是独立项目，不能把许可和功能互相套用。

h3.c 的 MIT 许可覆盖其代码，模型权重和第三方组成仍分别适用各自条款。安装引擎并不等于拿到了模型本身的任意使用许可。

常见问题

make test成功就说明真实H3已跑通了吗？

不说明。我们的日志同时包含基础检查成功与缺失模型 fixture 的跳过记录。

layers 45与reuse 2是无损加速吗？

它们改变实际计算路径，应与相同步数和完整执行的结果做质量对照，不能只比较耗时。

能直接采用作者的M5 Max数据估算我的M4吗？

不能。内核能力、统一内存、SSD、形状和预设不同，本篇没有做这种外推。

---

© 2026 Author: Mycelium Protocol. 本文采用 CC BY 4.0 授权——欢迎转载和引用，须注明作者姓名及原文链接，不得去除署名后以原创发布。

h3.c is a native MiniMax-H3 audiovisual inference engine for Apple Silicon. It exposes model loading, prompt encoding, denoising, video/audio decoding and media muxing through a CLI and C library. The repository is antirez/h3.c, licensed under MIT. It is an execution engine, not a new foundation model.

On an M4/16GB/macOS 26.6.2, we built the source, checked CLI help and ran tests that did not require downloaded model weights. The host suite reported 1,768 checks; AudioVAE Metal primitives and a synthetic FFmpeg mux test passed. Eleven fixture-dependent branches were skipped. We did not download MiniMax-H3 weights, generate model video or benchmark model speed.

Repository: https://github.com/antirez/h3.c

Source pin: 8974cc055ea9c02fcd14cc27dfda3e1027c05153. Review date: October 16, 2026.

What does the engine contain?

C, Objective-C and Metal implement the pipeline, linked with Apple’s Metal, MPS, MPSGraph and Accelerate frameworks. Builds produce h3 and libh3.a. Avoiding a Python forward path does not mean avoiding tensor-graph frameworks: MPSGraph is part of the implementation.

The README describes prompt-to-video/audio, first/last-frame conditioning and ordered image/video/audio references. Prompt encoding, DiT and the two VAEs have separate execution and residency phases, followed by FFmpeg output. Model capabilities still come from the loaded H3 checkpoint.

Related Vpipe overview: https://blog.mushroom.cv/blog/vpipe-minimax-h3-apple-silicon-video-audio-local-metal-cpp-pipeline/

Build success and generation success are separate checkpoints

git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j4
./h3 --help
# After separately preparing a model checkpoint:
./h3 --info -d ./MiniMax-H3

Info inspects the model layout and device without mapping all weights or generating media. We ran help, not a fabricated-model-directory acceptance test. An interactive session without -p can retain prompt conditioning, prepared DiT and decoder state, trading repeated work for residency. FFmpeg and FFprobe are needed for media. Runtime Metal compilation avoids the optional offline Metal toolchain, while compiler, SDK and hardware requirements remain.

What does a fast preset skip?

The tutorial’s balanced example is 512×512, 22 frames at 24fps, about 0.92 seconds, with steps 20, layers 45 and reuse 2. Its timing cannot stand in for a five-second or minute-long production clip.

Control	Effect	Comparison boundary
steps	Actual denoising schedule length	Four and 50 steps are different quality conditions
layers	Active transformer blocks	45/50 omits blocks rather than only optimizing a kernel
reuse	Reuse/extrapolate denoiser results	20 steps and reuse 2 make 11 fresh DiT evaluations
core-reuse	Refresh the expensive core less often	Separate from whole-denoiser reuse
Internal canvas / token reduction	Reduce internal work	Can alter details, composition and motion

The preset table’s Default column is ambiguous: current initialization in h3.h and the tutorial text use steps 20, layers 50 and reuse 1. Layers 45 and reuse 2 are a faster chosen preset. Set these explicitly in comparisons.

Definitions: https://github.com/antirez/h3.c/blob/8974cc055ea9c02fcd14cc27dfda3e1027c05153/h3.h

Why is 2GiB of tracked storage not a 2GiB computer?

The author reports that SSD streaming reduces tracked DiT tensor storage from roughly 36.5GiB to 2.0GiB on an M5 Max at the 512-square shape, keeping two blocks while prefetching the next from SSD. It uses original BF16 weights rather than requiring conversion or quantization.

That number excludes total process/system demand. Prompt encoding, VAEs, buffers and the operating system need headroom. The author’s matched warm forward took 1.35 seconds fully resident versus 2.49 seconds streamed at 512, and 2.14 versus 2.68 at 864×480. This exchanges residency for speed; these are the author’s measurements, not our M4 benchmark.

Preview also keeps a VAE resident, with approximately 10GiB extra reported by the README. Streaming is explicit, not default, and is incompatible with the specified use-int8-row-fc2 path. TensorOps capabilities also vary by chip. Record hardware, shape, frames, steps, blocks, reuse, precision, preview and residency before comparing timings.

Conditioning paths are distinct

First and last anchors use !first and !last. General images use !ref-image in ordered Picture 1, Picture 2 references; filenames do not carry model semantics. The documented general Ref2VA references cannot be mixed with first/last anchors. Interfaces for conditioning do not guarantee perfect cross-clip identity or satisfaction of every reference constraint; we did not validate real model outputs.

What did our local checks establish?

Unmodified source built the executable and static library, and help worked. Make test exited successfully. The host suite reported 1,768 checks; six categories of AudioVAE Metal primitives matched host references. Concurrent FFmpeg video/PCM pipes produced a 51,750-byte synthetic test MP4, not a model-generated clip.

Eleven skip messages identify absent toy-block, tokenizer, Qwen, released VAE, visual and multimodal fixtures. A zero exit code does not establish every weight path or complete MLX parity, and 1,768 checks are not 1,768 real-model evaluations. We did not measure full-model memory, generation quality, duration or speed. Building small tests on a 16GB Mac does not prove complete H3 inference fits that machine.

Who should investigate it?

Developers needing a CLI, C interface and visible native-kernel or residency controls can study this engine. Users who need a graphical asset/timeline workspace should evaluate Valtz or Vpipe’s interfaces separately; the projects do not share all features or licenses. MIT covers h3.c code, while model weights and third-party components retain their own terms.

Frequently asked questions

Does make test success prove real H3 generation?

No. Our log contains both successful foundational checks and skipped model-fixture branches.

Are 45 layers and reuse 2 lossless optimizations?

They change the computation. Compare quality against matching full-execution conditions as well as timing.

Can M5 Max timings predict this M4’s performance?

No. Hardware capabilities, memory, SSD, shapes and presets differ, and we made no such extrapolation.

---

© 2026 Author: Mycelium Protocol. Licensed under CC BY 4.0 — free to share and adapt with attribution. You must credit the author and link to the original; removing attribution and republishing as original is not permitted.