| --- |
| license: mit |
| library_name: mlx |
| tags: |
| - text-to-image |
| - image-to-image |
| - mlx |
| - quantized |
| base_model: microsoft/Mage-Flow-Base |
| --- |
| |
| # Mage-Flow — shared components (MLX, per-tier) |
|
|
| The **Qwen3-VL-4B text encoder** and **Mage-VAE** shared by every |
| [Mage-Flow](https://huggingface.co/microsoft/Mage-Flow) variant, re-hosted for |
| [SceneWorks](https://github.com/SceneWorks/SceneWorks) as physically distinct MLX quantization tiers. |
|
|
| ## Why this repo exists |
|
|
| Microsoft publishes six Mage-Flow checkpoints (`Base`, RL, `Turbo`, and the three `Edit` twins). The |
| text encoder (8.875 GB) and VAE (0.345 GB) are **bit-identical across all six** — only the 8.232 GB |
| DiT differs. Mirroring each variant as a complete snapshot would cost **105.04 GB** for a full |
| install. Hosting the shared components once here, and only the per-tier DiT in each variant mirror, |
| brings that to **58.65 GB**, and makes a second variant an ~8.2 GB delta rather than another 17.5 GB. |
|
|
| ## Layout |
|
|
| Each tier directory is self-contained: |
|
|
| ``` |
| <tier>/text_encoder/ Qwen3-VL-4B — config, tokenizer/processor assets, model.safetensors |
| <tier>/vae/ Mage-VAE |
| ``` |
|
|
| | tier | text_encoder | vae | total | |
| |---|---|---|---| |
| | `bf16` | 8.876 GB | 0.345 GB | 9.232 GB | |
| | `q8` | 4.720 GB | 0.345 GB | 5.076 GB | |
| | `q4` | 2.503 GB | 0.345 GB | 2.860 GB | |
| |
| **The VAE is dense in every tier, deliberately.** 59 of its 60 quantizable 2-D weights are |
| `adaLN_modulation` projections that the decoder *folds away at load* (adaLN depends only on `t`, and |
| the one-step decode always runs `t = 0`). Packing them on disk would fold quantized codes and |
| silently corrupt the decode. The disk cost of that correctness is ~0 — the VAE is conv-dominated, and |
| the comparable Z-Image VAE shrinks only 1.8% under q4. |
|
|
| Quantization is MLX `q4`/`q8` at group size 64, packed with the same |
| `mlx_rs::ops::quantize(bf16, 64)` call the load-time path uses — a pre-quantized tier is |
| **bit-identical** to quantizing the dense weights at load. |
|
|
| ## Provenance |
|
|
| Converted from `microsoft/Mage-Flow-Base` at revision |
| `59a9cfd58cf6ecef28245852c6bdace3f12428a2` with |
| [`mlx-gen-mage`](https://github.com/SceneWorks/inference)'s `examples/mage_prequant.rs`. The text |
| encoder and VAE tensors are identical in all six upstream repos, so the choice of source variant is |
| immaterial. |
|
|
| Upstream: [microsoft/Mage](https://github.com/microsoft/Mage) · arXiv:2607.19064 · MIT. |
|
|
