README.md

---
license: other
library_name: diffusers
pipeline_tag: text-to-image
base_model: microsoft/Mage-Flow
base_model_relation: quantized
tags:
  - ajh
  - mage-flow
  - mage-flow-nvfp4-balanced-ajh
  - nvfp4
  - blackwell
  - qwen3-vl
  - text-to-image
  - quantization
  - balanced
---

# Mage-Flow-NVFP4-Balanced-AJH

**Mage-Flow-NVFP4-Balanced-AJH** is a portable, runnable quantized version of
[`microsoft/Mage-Flow`](https://huggingface.co/microsoft/Mage-Flow).
Standalone Hugging Face Mage-Flow repository with 44 native NVFP4 transformer MLP projections and four late image MLP modules kept in BF16.

This repository is intended to remain discoverable as a quantized
`microsoft/Mage-Flow` derivative while avoiding any runtime dependency on
a separate local `models/` checkout. The complete transformer component,
quantized text encoder, VAE, scheduler, vendored inference code, and
native runtime are all packaged inside the repository layout.

Related releases:

- [Fast / maximum compression](https://huggingface.co/ajh-code/Mage-Flow-NVFP4-AJH)
- [Balanced](https://huggingface.co/ajh-code/Mage-Flow-NVFP4-Balanced-AJH)
- [Quality](https://huggingface.co/ajh-code/Mage-Flow-NVFP4-Quality-AJH)
- [ComfyUI custom nodes](https://github.com/AJH-Code/ComfyUI-MageFlow-NVFP4-AJH)

## Showcase

![Cyborg woman gazing toward a star-filled sky](examples/cyborg_stargaze_balanced.png)

Generated directly with this `balanced` package, without upscaling
or post-processing.

> A 4K resolution high detail photo realistic image of the top half of a cyborg woman with dark black hair, striking blue eyes that have a very subtle glow in the iris, standing side profile, head tilted up towards the sky with a questioning expression, she has subtle gaps in her skin that hint at a robotic nature, outdoor forest night setting, sky filled with bright brilliant stars that glow against the dark setting, nebula visible

Settings: 1280×1280, 20 steps, CFG 5, static shift 6, seed
`3334072683`.

## Transformer policy

- Native NVFP4 transformer projections: `44`
- BF16 passthrough transformer projections: `4`
- Default native runtime activation search: `amax`
- Default up activation multiplier: `1`
- Default down activation multiplier: `0.75`

BF16 passthrough modules:

- `transformer_blocks.9.img_mlp.net.2`
- `transformer_blocks.10.img_mlp.net.2`
- `transformer_blocks.11.img_mlp.net.0.proj`
- `transformer_blocks.11.img_mlp.net.2`

## Notes

- Demotes the last three image down projections plus the final image up projection.
- Carries the packaged native runtime default down activation multiplier of 0.75.
- Intended as the shortest mixed-quality transformer package candidate.

The Qwen3-VL text encoder uses the same mixed policy as the Fast
release: 224 NVFP4 projections in blocks 2–33, 14 FP8 projections in
blocks 1 and 34, with blocks 0 and 35 plus embeddings, norms, biases,
and the vision tower retained in BF16.

## Requirements and generation

The tested stack is Linux x86-64, NVIDIA Blackwell SM120, CUDA 13.1,
Python 3.11, PyTorch `2.13.0+cu130`, `comfy-kitchen==0.2.22`, and
`flash-attn==2.8.3`. Install into a virtual environment using the
included `requirements.txt`; do not install these packages system-wide.

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
CUDA_HOME=/usr/local/cuda-13.1 python -m pip install --no-build-isolation flash-attn==2.8.3

CUDA_VISIBLE_DEVICES=0 .venv/bin/python generate.py \
  --model ajh-code/Mage-Flow-NVFP4-Balanced-AJH \
  --prompt 'A detailed watercolor fox reading under an old oak tree' \
  --output fox.png --height 1024 --width 1024 --steps 20 --seed 1
```

The included binaries target the tested stack. Run `build_native.sh`
after changing PyTorch, CUDA, or the C++ ABI.

## Measured tradeoff

The controlled matched benchmark measured the Balanced transformer at
about `1.43x` BF16 throughput (`30%` less generation time), and the
Quality transformer at about `1.22x` BF16 throughput (`18%` less
generation time). Projected transformer plus text-checkpoint storage
is about `9.89 GB` for Balanced and `10.97 GB` for Quality, versus
`17.12 GB` for BF16. These are policy-level measurements from the
research suite, not universal hardware guarantees.

## Runtime caveats

- Requires an NVIDIA Blackwell SM120 GPU.
- Uses the packaged loader and native runtime; stock Diffusers does not
  natively understand `mage_flow_nvfp4_*` transformer modules.
- The package-level runtime defaults are applied only when the caller has
  not already set the corresponding `MAGE_NVFP4_*` environment variables.
- Generation and text-to-image are tested; Base, Turbo, editing, CUDA
  graph compatibility, and non-SM120 GPUs are not claimed.

## Validate the package

```bash
python validate_release.py
```

## License and attribution

Mage-Flow and the vendored Mage inference source are Copyright (c) 2026
Microsoft and MIT licensed. Qwen3-VL and the mixed NVFP4/FP8 text
checkpoint are Apache-2.0 licensed. See the included license files and
third-party notices for details.