MiniMax-H3-Ref2VA-MLX-pruned-Q4

MLX (Apple Silicon) build of the Ref2VA transformer of MiniMax-H3: 4-bit core, pruned AdaLN kept in float32. 12 GB on disk.

Powered by MiniMax H3.

These files are modified. They are not MiniMax's originals. Converted from the official Ref2VA/transformer (a different fine-tune from FL2VA; this is the one that reads reference pictures, clips and RefMods):

1. The 51 AdaLN projections were re-projected onto a 64-dimensional timestep curve and the time_embedder was removed (the "pruned AdaLN" layout load_dit reads when adaln_curve_grid is set). The curve is almost one-dimensional, and the projected AdaLN outputs match the originals to about 1.7e-6 relative error.
2. The core linears were quantized to 4-bit (group size 64). The small 64-wide AdaLN projections are left in float32; quantizing them to 8-bit measured six times worse on the saved modulation tables.

Licence and territory: read this first

Governed by the MiniMax H3 Community License, a copy of which is in this repository. It is not an open-source licence. In short: the grant is for the Applicable Territory, which is worldwide excluding the European Union, the United Kingdom, the Republic of Korea and the United States of America; redistribution must carry the licence and a NOTICE file and mark modified files; commercial products above US$20M yearly revenue need separate written authorization from MiniMax; the Acceptable Use Policy applies. By downloading you confirm you may do so under those terms.

What it needs

This repository holds the transformer only. The VAEs and the Qwen3-VL-32B text encoder come from the upstream release. Run it with the minimax-h3-mlx runner: load_dit(<this folder>) reads the pruned layout and quantization from config.json / quant_config.json. Reference conditioning (--refmod, --reference) needs a runner with Ref2VA support: draft PR mrbizarro/minimax-h3-mlx#2, or the copy vendored in blackest/immich-ring-visualizer (vendor/minimax_h3_mlx). Use --dit <this folder>.

What we measured (one Mac, one seed: read the limits)

Apple M2 Max, 96 GB, generate_staged.py, 640x384, 5 s, Fast (3-step) adapter, one RefMod, seed 5. Renders are deterministic, so these are exact for that seed.

pack	size	DiT load peak	denoise peak	denoise time
official Ref2VA, Q8 core, AdaLN bf16 (the 47.5 GB build this was made from)	47.5 GB	19.9 GiB	22.2 GiB	242 s
this pack	12 GB	10.6 GiB	12.9 GiB	238 s

• Smaller and lighter on memory, not faster. Denoising is compute-bound; 4-bit and 8-bit matmuls run at about the same speed (the runner's own benchmarks: ~0.88x bf16 for both).
• Same man as the Q8 packs on the test seed, but a visibly different take (this seed showed a doubled pendant lamp).
• The Qwen3-VL-32B text encoder peaks at 25.7 GiB and sets the RAM floor for plain renders whatever the DiT width; reference encoding peaked at 39 GiB in a 2-picture run on the 47.5 GB pack.
• Not tested on 36 or 48 GB Macs. Those numbers are our inference from the logged peaks. Reports welcome.
• For context only (not our measurement, and on FL2VA): PipeNetwork's cards for MiniMax-H3-MLX-8bit / -4bit report teacher-forced video velocity error of 0.033 and 0.165 against bf16. We did not repeat that for Ref2VA.

Rebuild it yourself

Needs the official Ref2VA/transformer download (~66 GB) and, for the prune and quantize steps, only a few GB of RAM:

python scripts/prune_ref2va_adaln.py --runner <minimax-h3-mlx> --src <Ref2VA/transformer> --out Ref2VA-pruned_bf16.safetensors
python scripts/quantize_pruned_stream.py --runner <minimax-h3-mlx> --src Ref2VA-pruned_bf16.safetensors --out <pack> --bits 4

Scripts: blackest/immich-ring-visualizer/scripts. The pruned-AdaLN layout follows the one DeepBeepMeep published for FL2VA; the quantizer follows the runner's quantize_stream.py.

Credits

MiniMax (the model and licence); PipeNetwork's minimax-h3-mlx and Mr Bizarro's fork and Phosphene (the MLX runner, Apache-2.0); DeepBeepMeep (the pruned-AdaLN checkpoint layout); Phosphene for bringing H3 to Apple Silicon.