Document measured MLX performance and tradeoffs

9cb13f7 verified 2 days ago

8.79 kB

---
library_name: mlx
pipeline_tag: text-to-image
license: other
license_name: minimax-h3-image-community-license-agreement
license_link: https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx/blob/v0.4.1/LICENSE-model
base_model: MiniMaxAI/MiniMax-H3-Image
language:
  - en
tags:
  - mlx
  - apple-silicon
  - macos
  - minimax-h3
  - text-to-image
  - image-to-image
  - image-editing
  - image-generation
  - safetensors
inference: false
---
# MiniMax H3 Image on Apple silicon

**Generate and edit images locally with MLX. Choose one weight variant; reuse the shared components.**

**Measured on M5 Pro / 64 GiB:** tuned warm 2048 × 2048 generation took
**62.49 s with BF16** or **64.05 s with lossless packed BF16**. These are
historical tests with cached conditioning and resident weights; see the
[measurement details](#measured-on-m5-pro--64-gib).

[View the generated showcase and comparisons](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-examples)

*The gallery contains AI-generated images from recorded local runs. It uses
manual access review under the model license. [Prompts, seeds and precision
settings](examples/README.md) are also documented here.*

A community port of [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)
by [Devin Lai](https://huggingface.co/devin-lai). Native MLX/Metal inference,
all six distilled PDD steps, reference-image editing, lossless BF16 packing
and optional Q8/Q4 weights. Model operators run locally on your Mac.

[Quick start](#quick-start) · [Choose weights](#choose-your-download) ·
[Usage](USAGE.md) · [Benchmarks](BENCHMARKS.md) ·
[Collection](https://huggingface.co/collections/devin-lai/minimax-h3-image-apple-silicon-mlx-6af64fcd11d7d7a3b17e11d8) · [Repository map](MODEL_INDEX.md) · [简体中文](README.zh-CN.md)

**Start with packed12 on a sufficiently large Mac.** It reconstructs the
original BF16 weight bits before computation. It is storage compression,
not quantization. The tested machine is an **M5 Pro with 64 GiB**;
smaller-memory Macs have not been qualified.

## Choose your download

The main repository contains inference code, documentation and comparison
records. Generated images are in the separately gated example gallery. Each
linked model repository contains one weight choice.
The downloader fetches that choice and its required shared files, then reuses
the same pinned upstream text encoder across variants.

| Variant | Variant weights¹ | Choose it for |
|---|---:|---|
| **[Lossless packed BF16](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-packed12)** | **27.23 GiB** | Recommended exact storage choice; original BF16 payloads |
| [Original BF16](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-bf16) | 61.73 GiB | Unmodified complete transformer storage |
| [Q8](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-q8) | 19.83 GiB | Smaller core; image and detail changes |
| [Q4](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-q4) | 10.50 GiB | Smallest core; stronger fidelity tradeoffs |

¹ Excludes [shared VAE, support tensors, heads and tables](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-shared),
the separate **roughly 62 GiB text encoder**, Python dependencies and runtime
memory. BF16 already includes native support; the downloader omits its redundant
shared copy.
Download sizes are not RAM requirements. Q8/Q4 quantize main and refiner
attention/MLP weights with MLX affine groups of 64; FP32 precision islands stay
native. Quantization has not established a generation-speed advantage here.

**License and access:** model weights retain MiniMax's community agreements,
including territory and commercial restrictions; they are not unrestricted
open-source weights. Model components use manual access review.
[Status and license details](RELEASE.md).

## Quick start

Use an Apple silicon Mac, native arm64 Python 3.12 and
[uv](https://docs.astral.sh/uv/getting-started/installation/). Request access
on the selected model and shared-component pages before downloading weights:

```bash
uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install huggingface-hub==0.36.2
hf auth login
hf download devin-lai/MiniMax-H3-Image-mlx --revision v0.4.1 \
  --include 'h3_mlx/*' config.json pyproject.toml LICENSE NOTICE \
  --local-dir h3-runtime
uv pip install './h3-runtime[native]'
h3-mlx doctor
h3-mlx download --variant packed12 --model-dir models/packed12
h3-mlx generate --model models/packed12 \
  --text-encoder models/packed12/text_encoder \
  'An editorial photograph of a cobalt perfume bottle on pale stone' \
  --width 2048 --height 2048 --seed 731 --output outputs/bottle.png
```

The first download is large because the native text encoder is separate.
Reuse an existing encoder with `--text-encoder-path /path/to/text_encoder`.
Use `--variant q8`, `q4` or `bf16` to select another weight repository.
Each output includes a JSON record with the prompt, seed, schedule, hardware,
precision, timings and memory. [Offline use, tuning and Python API](USAGE.md).

For reference-image editing, add `--image bottle.png` and describe the edit
using `<Picture 1>`. The implementation accepts up to sixteen ordered inputs;
the recorded edit cohort validates one reference. Detailed English prompts are
recommended; the runtime does not silently expand them.

## Measured on M5 Pro / 64 GiB

| Weight storage | Warm control | Warm tuned | Latency reduction | Max sampled parent footprint¹ |
|---|---:|---:|---:|---:|
| BF16 | 65.83 s | **62.49 s** | **5.07%** | 40.50 GiB |
| Lossless packed BF16 | 66.42 s | **64.05 s** | **3.57%** | **32.56 GiB** |

Results are for **2048 × 2048**, all six steps, on an M5 Pro with 16 GPU
cores, 64 GiB unified memory and MLX 0.32.4. Each time is the geometric mean
of product and portrait medians, with three alternating repeats per case.
Conditioning was cached and weights resident; startup and downloads are
excluded. A fresh CLI process includes loading and should not be expected to
match these warm timings.

¹ Maximum sampled parent-process physical footprint over four candidate cases,
including one edit; it is not the minimum required RAM. The BF16 and packed
figures come from separate campaigns. Every output pixel and saved denoising
tensor matched its corresponding MLX control in those four-case suites.
These results do not establish CUDA pixel identity or a universal speed claim.

The tuned profiles use compiled blocks and VAE, bounded prefetch, an exact
Q/K kernel and an M5-specific matrix tile. The default quick start does not
enable all of these options. [Copy the tested tuning flags](USAGE.md#measured-exact-tuning)
and see the [method, raw receipts and limitations](BENCHMARKS.md). Q8 and Q4
reduce weight storage but change images; their downloadable exports have no
established generation-speed advantage.

## Inspect, reproduce, contribute

- [Original examples and provenance](examples/README.md): authentic outputs,
  prompts, seeds and reference images, clearly identified as AI-generated.
- [Native / Q8 / Q4 comparisons](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-examples/blob/v0.4.0/comparisons/product/stack.png): inspect the
  lettering and detail changes before choosing compact weights.
- [Technical guide](docs/TECHNICAL.md): precision rules, resident Python
  pipelines, reference-image processing and experiment reproduction.
- [Validation](docs/VALIDATION.md): release software checks and fresh inference.
- [Community discussions](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx/discussions):
  share a reproducible issue or result with your variant, prompt, seed, canvas,
  Mac configuration and generated JSON record.

If the project helps you, like the variant you use and
[follow devin-lai](https://huggingface.co/devin-lai) for future Mac releases.
Measured contributions and examples from more Apple silicon configurations
are welcome. No hosted inference service is bundled.

## Attribution and terms

Independent community MLX adaptation by Devin Lai, based on MiniMax's released
weights and the inspected SGLang/Transformers inference contracts. This is not
an official MiniMax release or endorsement. Powered by MiniMax-H3-Image.

**Runtime code:** [Apache-2.0](LICENSE).
**Image weights and derivatives:** [MiniMax-H3-Image Community License Agreement](LICENSE-model).
**Separate text encoder:** [MiniMax H3 Community License Agreement](LICENSE-text-encoder).
The published agreements exclude the EU, UK, Republic of Korea and US absent
separate permission and include commercial, redistribution and acceptable-use
conditions. Access review does not grant additional rights.
[Modifications](docs/MODIFICATIONS.md) · [NOTICE](NOTICE) ·
[Pinned source provenance](provenance/sources.json).

	---
	library_name: mlx
	pipeline_tag: text-to-image
	license: other
	license_name: minimax-h3-image-community-license-agreement
	license_link: https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx/blob/v0.4.1/LICENSE-model
	base_model: MiniMaxAI/MiniMax-H3-Image
	language:
	- en
	tags:
	- mlx
	- apple-silicon
	- macos
	- minimax-h3
	- text-to-image
	- image-to-image
	- image-editing
	- image-generation
	- safetensors
	inference: false
	---

	# MiniMax H3 Image on Apple silicon

	Generate and edit images locally with MLX. Choose one weight variant; reuse the shared components.

	Measured on M5 Pro / 64 GiB: tuned warm 2048 × 2048 generation took
	62.49 s with BF16 or 64.05 s with lossless packed BF16. These are
	historical tests with cached conditioning and resident weights; see the
	[measurement details](#measured-on-m5-pro--64-gib).

	[View the generated showcase and comparisons](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-examples)

	*The gallery contains AI-generated images from recorded local runs. It uses
	manual access review under the model license. [Prompts, seeds and precision
	settings](examples/README.md) are also documented here.*

	A community port of [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)
	by [Devin Lai](https://huggingface.co/devin-lai). Native MLX/Metal inference,
	all six distilled PDD steps, reference-image editing, lossless BF16 packing
	and optional Q8/Q4 weights. Model operators run locally on your Mac.

	[Quick start](#quick-start) · [Choose weights](#choose-your-download) ·
	[Usage](USAGE.md) · [Benchmarks](BENCHMARKS.md) ·
	[Collection](https://huggingface.co/collections/devin-lai/minimax-h3-image-apple-silicon-mlx-6af64fcd11d7d7a3b17e11d8) · [Repository map](MODEL_INDEX.md) · [简体中文](README.zh-CN.md)

	Start with packed12 on a sufficiently large Mac. It reconstructs the
	original BF16 weight bits before computation. It is storage compression,
	not quantization. The tested machine is an M5 Pro with 64 GiB;
	smaller-memory Macs have not been qualified.

	## Choose your download

	The main repository contains inference code, documentation and comparison
	records. Generated images are in the separately gated example gallery. Each
	linked model repository contains one weight choice.
	The downloader fetches that choice and its required shared files, then reuses
	the same pinned upstream text encoder across variants.

	\| Variant \| Variant weights¹ \| Choose it for \|
	\|---\|---:\|---\|
	\| [Lossless packed BF16](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-packed12) \| 27.23 GiB \| Recommended exact storage choice; original BF16 payloads \|
	\| [Original BF16](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-bf16) \| 61.73 GiB \| Unmodified complete transformer storage \|
	\| [Q8](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-q8) \| 19.83 GiB \| Smaller core; image and detail changes \|
	\| [Q4](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-q4) \| 10.50 GiB \| Smallest core; stronger fidelity tradeoffs \|

	¹ Excludes [shared VAE, support tensors, heads and tables](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-shared),
	the separate roughly 62 GiB text encoder, Python dependencies and runtime
	memory. BF16 already includes native support; the downloader omits its redundant
	shared copy.
	Download sizes are not RAM requirements. Q8/Q4 quantize main and refiner
	attention/MLP weights with MLX affine groups of 64; FP32 precision islands stay
	native. Quantization has not established a generation-speed advantage here.

	License and access: model weights retain MiniMax's community agreements,
	including territory and commercial restrictions; they are not unrestricted
	open-source weights. Model components use manual access review.
	[Status and license details](RELEASE.md).

	## Quick start

	Use an Apple silicon Mac, native arm64 Python 3.12 and
	[uv](https://docs.astral.sh/uv/getting-started/installation/). Request access
	on the selected model and shared-component pages before downloading weights:

	```bash
	uv venv --python 3.12 .venv
	source .venv/bin/activate
	uv pip install huggingface-hub==0.36.2
	hf auth login

	hf download devin-lai/MiniMax-H3-Image-mlx --revision v0.4.1 \
	--include 'h3_mlx/*' config.json pyproject.toml LICENSE NOTICE \
	--local-dir h3-runtime
	uv pip install './h3-runtime[native]'
	h3-mlx doctor

	h3-mlx download --variant packed12 --model-dir models/packed12
	h3-mlx generate --model models/packed12 \
	--text-encoder models/packed12/text_encoder \
	'An editorial photograph of a cobalt perfume bottle on pale stone' \
	--width 2048 --height 2048 --seed 731 --output outputs/bottle.png
	```

	The first download is large because the native text encoder is separate.
	Reuse an existing encoder with `--text-encoder-path /path/to/text_encoder`.
	Use `--variant q8`, `q4` or `bf16` to select another weight repository.
	Each output includes a JSON record with the prompt, seed, schedule, hardware,
	precision, timings and memory. [Offline use, tuning and Python API](USAGE.md).

	For reference-image editing, add `--image bottle.png` and describe the edit
	using `<Picture 1>`. The implementation accepts up to sixteen ordered inputs;
	the recorded edit cohort validates one reference. Detailed English prompts are
	recommended; the runtime does not silently expand them.

	## Measured on M5 Pro / 64 GiB

	\| Weight storage \| Warm control \| Warm tuned \| Latency reduction \| Max sampled parent footprint¹ \|
	\|---\|---:\|---:\|---:\|---:\|
	\| BF16 \| 65.83 s \| 62.49 s \| 5.07% \| 40.50 GiB \|
	\| Lossless packed BF16 \| 66.42 s \| 64.05 s \| 3.57% \| 32.56 GiB \|

	Results are for 2048 × 2048, all six steps, on an M5 Pro with 16 GPU
	cores, 64 GiB unified memory and MLX 0.32.4. Each time is the geometric mean
	of product and portrait medians, with three alternating repeats per case.
	Conditioning was cached and weights resident; startup and downloads are
	excluded. A fresh CLI process includes loading and should not be expected to
	match these warm timings.

	¹ Maximum sampled parent-process physical footprint over four candidate cases,
	including one edit; it is not the minimum required RAM. The BF16 and packed
	figures come from separate campaigns. Every output pixel and saved denoising
	tensor matched its corresponding MLX control in those four-case suites.
	These results do not establish CUDA pixel identity or a universal speed claim.

	The tuned profiles use compiled blocks and VAE, bounded prefetch, an exact
	Q/K kernel and an M5-specific matrix tile. The default quick start does not
	enable all of these options. [Copy the tested tuning flags](USAGE.md#measured-exact-tuning)
	and see the [method, raw receipts and limitations](BENCHMARKS.md). Q8 and Q4
	reduce weight storage but change images; their downloadable exports have no
	established generation-speed advantage.

	## Inspect, reproduce, contribute

	- [Original examples and provenance](examples/README.md): authentic outputs,
	prompts, seeds and reference images, clearly identified as AI-generated.
	- [Native / Q8 / Q4 comparisons](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx-examples/blob/v0.4.0/comparisons/product/stack.png): inspect the
	lettering and detail changes before choosing compact weights.
	- [Technical guide](docs/TECHNICAL.md): precision rules, resident Python
	pipelines, reference-image processing and experiment reproduction.
	- [Validation](docs/VALIDATION.md): release software checks and fresh inference.
	- [Community discussions](https://huggingface.co/devin-lai/MiniMax-H3-Image-mlx/discussions):
	share a reproducible issue or result with your variant, prompt, seed, canvas,
	Mac configuration and generated JSON record.

	If the project helps you, like the variant you use and
	[follow devin-lai](https://huggingface.co/devin-lai) for future Mac releases.
	Measured contributions and examples from more Apple silicon configurations
	are welcome. No hosted inference service is bundled.

	## Attribution and terms

	Independent community MLX adaptation by Devin Lai, based on MiniMax's released
	weights and the inspected SGLang/Transformers inference contracts. This is not
	an official MiniMax release or endorsement. Powered by MiniMax-H3-Image.

	Runtime code: [Apache-2.0](LICENSE).
	Image weights and derivatives: [MiniMax-H3-Image Community License Agreement](LICENSE-model).
	Separate text encoder: [MiniMax H3 Community License Agreement](LICENSE-text-encoder).
	The published agreements exclude the EU, UK, Republic of Korea and US absent
	separate permission and include commercial, redistribution and acceptable-use
	conditions. Access review does not grant additional rights.
	[Modifications](docs/MODIFICATIONS.md) · [NOTICE](NOTICE) ·
	[Pinned source provenance](provenance/sources.json).