# MiniMax 分享 antirez 打造的 MiniMax-H3 Metal 推論引擎，讓模型原生執行於 Apple Silicon

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 原作者：MiniMax (official) (@MiniMax_AI) · 策展與摘要：EasyVibeCoding · 平台：X (Twitter) · 熱度：🔥🔥🔥 · 日期：2026-08-12

> 原始來源：https://x.com/MiniMax_AI/status/2086940119324565748

## 證據與延伸閱讀

- [MiniMax 分享 antirez 打造的 MiniMax-H3 Metal 推論引擎，讓模型原生執行於 Apple Silicon](https://x.com/MiniMax_AI/status/2086940119324565748)
- [h3-metal是Apple Silicon原生執行專案](https://github.com/antirez/h3.c) — 官方 Repository

## 中文摘要

MiniMax 分享 antirez 打造的 MiniMax-H3 Metal 推論引擎，讓模型原生執行於 Apple Silicon。

**分享背景** MiniMax 在 2026 年 8 月 11 日表示，Redis 創作者 antirez 為 Mac 電腦撰寫了 H3 inference engine，並認為這類成果無法單靠招聘取得，只能透過開源讓社群自行發生。antirez 前一天發布「Fast H3 implementation for Metal」，邀請使用者享受、修改與延伸，程式碼位於 [antirez/h3.c](https://github.com/antirez/h3.c)。他也說明，其中包含來自 liuliu 的程式碼；若 @liuliu 對 `drawthingsapp` 的 H3 計畫有需要，可以取回相關部分。MiniMax 的貼文重點不是宣稱官方推出另一套產品，而是推薦這項社群實作，並把它視為 open weights 促成硬體適配與開源協作的案例。

**專案定位** `h3-metal` 是在 Apple Silicon 上原生執行 MiniMax-H3 inference 的專案，採用 working vertical slices，先建立 deterministic host/model metadata，再逐步完成 portable Metal block parity、prompt encoding、prompt-to-video/audio、first/last-frame conditioning，最後加入 ordered references。目前 prompt-to-video/audio、first/last-frame conditioning，以及 ordered Ref2VA image/video/audio references 都已能端到端執行；開發重心則放在 M3 Max、M5 Max 的 H3-specific Metal 效能與記憶體最佳化。

**快速開始** 假設 Hugging Face snapshot 位於 `./MiniMax-H3`，且 FFmpeg、FFprobe 已在 `PATH`，可先檢查 model layout 與 Metal device，再執行 512×512 影片生成：

```sh
make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3
./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6
```

`--info` 不會 mapping 全部 weights，也不會產生 media；`./h3 --help` 可查看完整 CLI。互動模式會保留 BF16 prompt conditioning、prepared DiT 與 video decoder，因此只換 seed 時，不必重新 loading 或 encoding。可用的互動指令包括 `!status`、`!seed random`、`!seconds 2`、`!show`、`!save output.mp4`、`!cache`、`!first`、`!last`、`!ref-image`、`!refs`、`!ref-remove N`。Ref2VA 圖片會依序顯示為 `<Picture 1>`、`<Picture 2>`，不能與 `!first` 或 `!last` 混用。

**品質與速度取捨** validated balanced preset 是 512×512、22 frames、24 fps，長度約 0.92 秒。`--steps 20` 代表 20 次 denoising，`--reuse 2` 只計算 11 次 fresh denoiser velocities，`--layers 45` 則是在 50 個 transformer blocks 中執行 45 個。slow、default 與 aggressive preset 分別為：

- slow：`--steps 50`、`--reuse 1`、`--layers 50`。
- default：`--steps 20`、`--reuse 2`、`--layers 45`。
- aggressive：`--steps 4..7`、`--reuse 3`、`--layers 40`。

20 steps 下，三者的 fresh DiT evaluations 分別是 20、11、8。4-pass 模式固定做 4 次 denoising；4 至 7 passes 採用低預算測試中較好的 schedule，從 4 增至 7 可改善 detail 與 motion。512-square、22-frame fox 測試中，4-pass 相較 29-pass reference 的 full-video SSIM 是 0.556，獨立 surfer 測試是 0.547；M5 Max denoise 約 3.5 秒，reference 則為 26.4 秒。tail-heavy schedules 因 early composition updates 太少，會出現 woven texture、weak motion 或 clipped colors，因此被捨棄。

`--core-reuse` 可設為 1、4、6，但與 `--reuse` 互斥；`--token-reduction` 能加速，卻可能改變 composition。512×512、45 layers 加 reuse 2 時，M5 Max IT profile 從 16.69 秒降至 12.60 秒；但 `--layers 40 + --reuse 3 + --token-reduction` 曾產生 color ringing、outlines 與 ghosted limbs，不建議使用。`--core-reuse 6` 僅適合 aggressive preview，超過 6 會流失 subject fidelity。

**解析度與影片長度** H3-Base 是 768p model。`width`、`height` 必須是至少 32 且可被 32 整除，乘積不可超過 `768 * 1344`。512×512 是最安全的開發尺寸，768×768 是 validated close-quality；1344×768、768×1344 是 released 768p-class limit，1024×768 與 768×1024 也合法。256×256 僅適合 native fast preview，128×128 不支援。

H3 以 24 fps 輸出，frame shape 會向上對齊 `5 + 17*n`：

- 22 frames：0.917 秒。
- 39 frames：1.625 秒。
- 56 frames：2.333 秒。
- 107 frames：4.458 秒。
- 243 frames：10.125 秒。
- 362 frames：15.083 秒。

因此 `--seconds 10` 會產生 243 frames，也就是 10.125 秒；`--frames 23` 會升至 39 frames，released workflow 目標約為 4–15 秒。256 square 只有 `8x8` effective spatial-token grid，fine detail 與複雜構圖受限；系統會在恰為 256 square 時將 spatial RoPE coordinates 減半，以消除長 fox render 的 repeating lattice artifacts。`--use-reference-rope` 可恢復 released／MLX 座標，而該尺寸應關閉 token reduction。

`--render-width` 與 `--render-height` 必須同時設定、維持相同 aspect ratio，且不可超過輸出尺寸。它們讓 model 與 VAE 在較小 canvas 執行，再用 high-quality vImage 放大；384→512 的 prompt render 使 M5 DiT 快 33%、video-VAE 快 18%，320 是 validated aggressive point。320×320 walking fox 仍保持 coherent，DiT 耗時 8.02 秒，native 約 15.82 秒，但會損失 fine detail、改變 framing。VAE tile 預設自動選擇 256–320 pixels，也可用 `H3_VAE_TILE_PIXELS=256` 恢復 conservative plan。

**SSD 與量化** `--ssd-streaming` 使用未 conversion、未 quantization 的原始 BF16 checkpoint，只讓兩個 DiT blocks 留在記憶體，GPU 執行目前 block 時由 SSD 讀取下一個。M5 Max 的 tracked DiT storage 在 512 square 從約 36.5 GiB 降至 2.0 GiB，864×480 則為 2.1 GiB；warm 50-block forward 分別是 1.35 對 2.49 秒，以及 2.14 對 2.68 秒，速度慢 84% 與 26%，但兩次都 byte-identical。這只是 tracked tensor storage，不是 total system RAM；`--show` 仍會增加約 10 GiB temporary model residency，且不能與 `--use-int8-row-fc2` 合用。

M5 的 native int8 MLP 是最快路徑之一。固定 50-layer、19-transition、512×512 render 中，BF16 MPS 從 36.30 秒降至 25.80 秒；再量化 DiT QKV 後降至 19.32 秒，fox walking through snow 的前、中、後畫面仍 coherent detailed，但 framing 與 fine detail 可能改變。`--use-slower-bf16-qkv`、`--use-slower-bf16-attention-output`、`--use-slower-bf16-mlp` 可分別恢復較慢的 BF16 路徑。正常 int8 loading 會在 quantization submit 後釋放 BF16 FC1/FC2，peak tensor storage 從 36.4 GiB 降至 25.9 GiB，但會增加啟動時間。

**token reduction 與一致性** `--token-reduction` 會在 block 3 後合併相鄰 horizontal target-video tokens，text、audio、conditions 與 reference tokens 保持不變。前 10 次 noisy evaluations 會在 block 40 前 restore，之後在 block 30 前 restore。thermal-balanced 512×512×22、19-forward、M5 Max A/B 測試將 denoise 從 39.13 秒降至 28.06 秒，提升 28.3%；video/audio latent relative L2 為 5.56%／15.14%，fox 與 surfer 仍 coherent，但 composition 會改變，因此預設為 opt-in。

與 `--layers 45 --reuse 2` 合用時，16.69 秒降至 12.60 秒，marginal 改善為 24.5%；不能與 `--layers 40`、`--reuse 3` 同用，因 6.47 秒實驗出現 chromatic ringing 與 ghosted limbs。`H3_TOKEN_REDUCTION_BLOCKS` 可覆寫 `4:30`，`H3_TOKEN_REDUCTION_EARLY=STEPS:END` 可覆寫 early schedule，設為 `0` 可停用；`H3_DISABLE_TOKEN_REDUCTION=1`、`H3_DISABLE_FUSED_TOKEN_POOL_ADALN=1`、`H3_DISABLE_FUSED_TOKEN_ADALN=1` 則提供 exact 或 two-kernel oracle。

**Ref2VA 與條件輸入** Ref2VA 會依序選擇不同 checkpoint，reference flags 可重複並保留命令列順序。standalone audio 必須搭配 image 或 video，音訊長度為 2–15 秒，最多 3 個輸入，解碼總長度上限為 15 秒：

```sh
# image
./h3 -d ./MiniMax-H3 -p "Use the animal and setting in the reference." --width 512 --height 512 --frames 22 --steps 20 --ref-image fox.png -o outputs/fox-reference.mp4
# silent video
./h3 -d ./MiniMax-H3 -p "Continue the motion in this clip." --width 512 --height 512 --frames 22 --steps 20 --ref-silent-video fox.mp4 -o outputs/fox-video-reference.mp4
# video with audio
./h3 -d ./MiniMax-H3 -p "Continue this audiovisual scene." --width 512 --height 512 --frames 56 --steps 20 --ref-video fox-with-audio.mp4 -o outputs/fox-video-audio.mp4
# replace audio
./h3 -d ./MiniMax-H3 -p "Continue the scene with the supplied music." --width 512 --height 512 --frames 56 --steps 20 --ref-video-audio silent-fox.mp4 replacement.wav -o outputs/fox-replaced-audio.mp4
# image plus audio
./h3 -d ./MiniMax-H3 -p "Use the animal and music from the references." --width 512 --height 512 --frames 56 --steps 20 --ref-image fox.png --ref-audio music.wav -o outputs/fox-image-audio.mp4
```

`--first-frame`、`--last-frame` 使用 released visual VAE encoder、Qwen3-VL vision tower、three-deepstack multimodal presentation、0.999 condition augmentation 與 fixed condition rows；first image 會 stretch 到 target canvas，last image 則採 aspect-cover、center crop。`--ref-image` 使用 distinct Ref2VA transformer，保留有序 `<Picture N>` presentation；`--ref-silent-video` 進行 bounded 24 fps decoding、visual VAE causal `ceil(T/4)` compression、two-frame Qwen sampling 與 timestamped `<Video N>` presentation。

`--ref-video` 會保留 embedded soundtrack；`--ref-video-audio VIDEO AUDIO` 可替換音訊；`--ref-audio` 則追加有序 standalone clip。音訊輸出是 32 kHz stereo F32，經 native AudioVAE posterior-mean path，並以 0.999 clean latent 加 0.001 seeded noise 建立條件。Native audio encoder 在 real two-second stereo fixture 的 relative L2 為 `3.59e-6`；修正原因是原 MLX reshape 會交錯 left/right samples，而官方 PyTorch／SGLang 是將完整 stereo channels fold 入 batch dimension。

**Metal 實作與記憶體最佳化** DiT 核心拆成兩個有序 Metal command buffers，讓 GPU 執行第一段時，CPU 可同時 encoding 第二段。M5 採 60% depth split，即 30/50、27/45、24/40，提升約 0.5–1.8%；M3 只自動採用驗證過的 30/50，速度快 1.2%，24/40 反而退步。`H3_DIT_COMMAND_BLOCKS=0` 可恢復單一 command buffer，1–50 可覆寫 split，且 operation order、generated bytes 與輸出不變。

其他最佳化包括：

- activation buffers 依 intra-block lifetime alias，512-class 省 61.25 MiB，864-class 省 99.63 MiB；`H3_DISABLE_DIT_ACTIVATION_ALIAS=1` 可恢復獨立診斷 buffers。
- immutable DiT weights/biases 的 MPSGraph tensor-data wrappers 會被快取，M3 Max 快 1.6%，M5 Max 快 0.4–1.1%；`H3_DISABLE_GRAPH_DATA_CACHE=1` 可恢復 transient wrappers。
- M3／舊硬體共用 MPSCommandBuffer wrapper，M3 Max 快 1.0–1.6%；`H3_REUSE_MPS_COMMAND=0` 或 `1` 可覆寫，結果皆 byte-identical。
- M5 的 GPU sampler 保留 patch-packed F32 latents 與 cached BF16 velocities，僅快 0.1%、0.3%，但 final latents byte-identical，並為每個 video-latent element 省約 16 bytes transient host state；768p 約省 136 MB。
- M5 將 37 GiB transformer safetensor shards 設為 file-backed／reclaimable；`H3_ZERO_COPY_WEIGHTS=0` 可停用。Qwen prefetch ring depth 在 M3／舊硬體為 2、M5 為 3，`H3_QWEN_PREFETCH=0` 可恢復 synchronous path，worker 可設 1–8，`H3_QWEN_PREFETCH_DEPTH=1`–`6` 可覆寫 ring。
- `H3_PROFILE=1` 會顯示 SSD bytes、throughput 與未被 GPU work 隱藏的 read wait；`--profile` 則回報 phase wall time、Metal encoding／wait time、peak live tensor storage、cumulative allocation 與 dispatch counts。

**測試與效能驗證** 專案提供 deterministic host suite，以及 Metal／MLX parity 檢查：

```sh
make test
make parity
```

`make test` 若發現 `misc/fixtures/` 中被忽略的 MLX fixture，會在 runtime 編譯 Metal source，並以 named MLX outputs 檢查完整 toy H3 block；`make parity` 只執行 Metal／MLX checks。runtime compilation 遵循 Iris，不需要 Xcode optional offline Metal toolchain；wide BF16 matrix products 與 SDPA 使用 cached MPSGraph graphs，並保留 direct Metal correctness fallback。

512×512、22 frames、20 steps 的 profiling/render 可使用：

```sh
./h3 --profile -d ./MiniMax-H3 \
  -p "A red fox walks through fresh snow." \
  --width 512 --height 512 --frames 22 --steps 20 \
  --layers 50 --reuse 1 -o outputs/fox-int8.mp4
```

在 128 GB M5 Max 上，end-to-end image+audio 與 embedded-video+audio 分別耗時 74.58 與 76.99 秒，兩者 peak physical footprint 約 40.1 GB，且 zero swaps。輸出同步 H.264 與 32 kHz stereo AAC；native waveform 相較 corrected MLX oracle 的 relative L2 為 `6.94e-5`。整體來看，antirez 的實作展示了 open weights 的另一種價值：模型不只被下載與使用，也能由社群成員針對特定晶片、記憶體限制與媒體流程重新拆解，形成可驗證、可修改且持續演進的 Metal 執行路徑。

## 標籤

開源專案, 硬體, macOS, Apple, GitHub