File size: 4,522 Bytes
3da88e3 c138412 3da88e3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | # Install and use
Use Apple silicon, native arm64 Python 3.12, and a compatible macOS Metal
installation. The measured environment is M5 Pro / 64 GiB, macOS 27.0.1,
MLX 0.32.4 and Transformers 4.57.6. Smaller Macs have not been qualified.
## Release installation
Request access on the selected variant and shared model pages and read their
licenses. Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
and authenticate with Hugging Face as shown below.
```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 release catalog records immutable component revisions. It rejects
unpublished or unpinned weights. For local development use `uv pip install
-e '.[native]'` and the original checkpoint paths, as in
[the technical guide](docs/TECHNICAL.md).
The `native` extra supplies PyTorch for the original CPU noise stream. Model
operators still run in MLX on Metal. Without that extra, `--rng mlx` uses a
different random stream and does not reproduce the same seeded images.
## Select another variant or reuse existing weights
```bash
h3-mlx download --variant q8 --model-dir models/q8 \
--text-encoder-path /path/to/MiniMax-H3/text_encoder
h3-mlx generate --model models/q8 --text-encoder models/q8/text_encoder \
'A detailed scene description' --output outputs/q8.png
```
Use `q4`, `bf16` or `packed12` in the same way. Use a separate assembly
directory for each variant. Shared files and the encoder are cached once;
no other variant is fetched. The release selects quantization automatically,
so do not add `--quantize` or `--quantized-core` to published variants.
To fetch the image model without the encoder, use `--skip-text-encoder` and
pass your encoder path directly to generation. `--local-files-only` avoids
network access when all required files already exist in the Hub cache.
## Measured exact tuning
On the tested M5 Pro / 64 GiB, add:
```bash
--compile-blocks --eval-every 0 --prefetch-blocks 4 \
--compile-vae --vae-batch 4 --kernel metal-qk-exact --tune-matmul
```
Optional `--wired-gb 32` (packed12) or `--wired-gb 42` (BF16) were tested on
this 64 GiB Mac. The runtime checks Metal's limit. They are not universal
settings for other machines. Q8/Q4 are storage and memory tradeoffs and have
not established a generation-speed advantage. Frozen modulation tables
require MLX 0.32.4 and `MLX_ENABLE_TF32=0`; original checkpoints remain an
alternative when regenerating tables in another supported environment.
## Reference-image editing
```bash
h3-mlx generate --model models/packed12 \
--text-encoder models/packed12/text_encoder \
'Change the bottle in <Picture 1> to emerald glass while preserving its label' \
--image bottle.png --seed 42 --output outputs/edit.png
```
The implementation accepts up to sixteen ordered references. The recorded
image-edit cohort covers one reference. This does not establish quality for
every multi-image composition. Use detailed English prompts. Prompt expansion
is not automatic. The default 2048-square canvas is within the model's usual
4–20 MP working range. Smaller requested images are generated on an enlarged
canvas and resized; development overrides are documented in the technical guide.
Each output has a JSON record with precision, seeds, schedule, timings,
memory and environment. Add `--save-trace` for numerical audits. Report issues
with that record, your command, chip, memory, macOS and package versions.
## Licenses and access
The image weights and derivatives retain the MiniMax-H3-Image Community
License Agreement, including its territory, commercial, redistribution and
acceptable-use conditions. The text encoder has its own MiniMax H3 agreement.
The published agreements exclude the EU, UK, Republic of Korea and US absent
separate permission. A manual Hub gate supports access review; it does not
grant rights outside those agreements. See `LICENSE-model`,
`LICENSE-text-encoder`, `NOTICE` and [release status](RELEASE.md).
|