Card: curated gallery, honest limitations

ff3aacd verified 1 day ago

10.1 kB

	---
	license: other
	license_name: flux-kommunity-license
	license_link: LICENSE.md
	base_model: black-forest-labs/flux-3-image-klein
	base_model_relation: quantized
	pipeline_tag: text-to-image
	library_name: mlx
	tags:
	- mlx
	- apple-silicon
	- flux
	- flux-3
	- text-to-image
	- image-editing
	- image-to-image
	- quantized
	language:
	- en
	---

	# FLUX 3 Image Klein, MLX 6bit

	[FLUX 3 Image Klein](https://huggingface.co/black-forest-labs/flux-3-image-klein) for Apple Silicon:
	text-to-image, editing with up to 10 reference images, and bounding-box layout, running natively in
	[MLX](https://github.com/ml-explore/mlx) with the [`flux3-mlx`](https://github.com/felix-ab/flux3-mlx) runner.
	The transformer is quantized to 6-bit; the output is validated against Black Forest Labs' reference implementation.

	> An independent community conversion, not affiliated with or endorsed by Black Forest Labs.

	```sh
	pip install "flux3-mlx[pup]"
	flux3-mlx "a ceramicist's studio at golden hour, shelves of glazed bowls" --model 6bit --upsample --out studio.png
	```

	## Gallery

	Generated with this 6bit repo on an M4 Pro, 16 steps; prompts and seeds in `gallery/*.json`. Curated from a 27-prompt test set: edits, multi-reference and layout were consistently strong; some people shots were dropped for hand errors or smooth skin (see Limitations).

	\| \| \|
	\|---\|---\|
	\| ![Edit: remove the car and its shadow](gallery/edit_remove_car_suburban.jpg)<br><sub>Edit: remove the car and its shadow</sub> \| ![Three references -> one gallery wall](gallery/edit_multi_gallery_wall_triptych.jpg)<br><sub>Three references -> one gallery wall</sub> \|
	\| ![Edit: recolor the dress, keep the light](gallery/edit_recolor_dress_greenhouse.jpg)<br><sub>Edit: recolor the dress, keep the light</sub> \| ![Bounding-box layout (boxes drawn on top)](gallery/bbox_still_life_layout.jpg)<br><sub>Bounding-box layout (boxes drawn on top)</sub> \|
	\| ![Portra 400 portrait, overcast window light](gallery/older_man_overcast_window.jpg)<br><sub>Portra 400 portrait, overcast window light</sub> \| ![Unretouched macro, Leica M6 on film](gallery/skin_fragment_resin_wafer.jpg)<br><sub>Unretouched macro, Leica M6 on film</sub> \|
	\| ![Vision3 250D road-movie still, 2.4:1](gallery/vision3_backseat_red_halation.jpg)<br><sub>Vision3 250D road-movie still, 2.4:1</sub> \| ![CineStill 800T, pushed, red halation](gallery/cinestill800t_corner_store_pushed.jpg)<br><sub>CineStill 800T, pushed, red halation</sub> \|
	\| ![Upsampled from "night bus stop in the rain, CineStill 800T, one woman waiting under a red umbrella"](gallery/upsample_rain_bus_stop.jpg)<br><sub>Upsampled from "night bus stop in the rain, CineStill 800T, one woman waiting under a red umbrella"</sub> \| ![Two-color risograph poster: exact typography](gallery/swiss_riso_exhibition_poster.jpg)<br><sub>Two-color risograph poster: exact typography</sub> \|
	\| ![1967 paperback cover, painted](gallery/paperback_cover_glass_orbit.jpg)<br><sub>1967 paperback cover, painted</sub> \| ![Contact sheet with grease-pencil notes](gallery/contact_sheet_grease_pencil.jpg)<br><sub>Contact sheet with grease-pencil notes</sub> \|
	\| ![4x5 still life, hard window light](gallery/pomegranate_plaster_still_life.jpg)<br><sub>4x5 still life, hard window light</sub> \| ![Product macro: chrome and resin](gallery/chrome_cuff_resin_macro.jpg)<br><sub>Product macro: chrome and resin</sub> \|
	\| ![Architectural interior, blue hour](gallery/midcentury_interior_blue_hour.jpg)<br><sub>Architectural interior, blue hour</sub> \| ![65mm landscape, lone walker](gallery/dune_ridge_lone_walker_70mm.jpg)<br><sub>65mm landscape, lone walker</sub> \|
	\| ![Upsampled from 12 words: "a halved pomegranate on a plaster plinth, hard window light, Portra 400"](gallery/upsample_pomegranate_short.jpg)<br><sub>Upsampled from 12 words: "a halved pomegranate on a plaster plinth, hard window light, Portra 400"</sub> \| \|

	## Which repo?

	\| Repo \| Transformer \| Download \| Peak memory, 1024² \| Peak, `--low-memory` \| For \|
	\|---\|---\|---\|---\|---\|---\|
	\| [MLX-8bit](https://huggingface.co/VisualInference/FLUX-3-Image-Klein-MLX-8bit) \| 8-bit, 6.15 GB \| 9.6 GB \| 14.3 GB \| 11.0 GB \| Macs with 24 GB or more. Closest to BF16. \|
	\| [MLX-6bit](https://huggingface.co/VisualInference/FLUX-3-Image-Klein-MLX-6bit) \| 6-bit, 4.83 GB \| 8.4 GB \| 13.0 GB \| 9.6 GB \| 16 GB Macs (low-memory mode is on by default below 24 GB). \|

	Prompt upsampler (recommended for short prompts): [pup-MLX-4bit](https://huggingface.co/VisualInference/FLUX-3-Image-Klein-pup-MLX-4bit) / [pup-MLX-8bit](https://huggingface.co/VisualInference/FLUX-3-Image-Klein-pup-MLX-8bit).

	There is no 4-bit repo on purpose: in our tests 4-bit added 5–23% high-frequency grain and changed design
	details (see Validation).

	## Usage

	```sh
	flux3-mlx "Full-color photograph, ..." --model 6bit --width 1216 --height 832 --seed 7 # long prompts as-is
	flux3-mlx "a red bicycle in the rain" --model 6bit --upsample # short prompts: upsample
	flux3-mlx "put a red bandana around the dog's neck" --model 6bit --image dog.png --upsample # edit
	flux3-mlx "the jacket from image 2 on the person in image 1" --model 6bit --image a.png --image b.png --upsample
	flux3-mlx "balloons over a valley at sunrise" --model 6bit --boxes boxes.json --upsample # layout
	```

	```python
	from flux3_mlx import Flux3Klein
	pipe = Flux3Klein.from_pretrained("6bit", upsampler="4bit")
	image, record = pipe("a ceramicist's studio at golden hour", seed=3)
	```

	Klein works best with fully described scenes: medium, framing, subjects with colors and materials, background,
	lighting. The upsampler writes such captions from short requests, edit instructions and box layouts. Seeds match
	the BFL reference: the same seed gives the same starting noise.

	## Performance (M4 Pro, 48 GB, 1024², 16 steps)

	~114 s per image, 13.0 GB peak (9.6 GB with `--low-memory`). Every reference image adds its own
	tokens: measured on 8-bit, edits take ~200–270 s with one reference, ~290 s with two and ~540 s with three (each about
	1 MP). The upsampler adds ~10–20 s. At 1 MP the model is compute-bound, so quantization saves memory rather than time. Keep the
	16 steps: at 4 steps the output is visibly under-denoised and grainy, in BFL's own code too.

	## Validation

	Compared with BFL's reference code (commit `45e57c9`) and BFL's published example images:

	\| Check \| Result \|
	\|---\|---\|
	\| Text encoder: tokens, template, hidden states (8 layers) \| identical ids; mean cos ≥ 0.9999 \|
	\| VAE encode/decode \| cos 1.000000 \|
	\| Transformer velocity, t2i and edit \| cos 0.9999 \|
	\| BF16 port vs BFL's `man_dog.png` (B200), 1024², seed 7 \| 35.9 dB, visually indistinguishable \|
	\| This repo vs BFL's `man_dog.png` \| 30.1 dB \|
	\| This repo texture vs BF16 (high-frequency energy, 1.00 = identical) \| 1.00 \|

	Quantization study across five cases (photo, typography, fashion, still life, edit):

	\| Transformer \| Texture vs BF16 \| Verdict \|
	\|---\|---\|---\|
	\| 8-bit \| 0.99 \| shipped \|
	\| 6-bit \| 1.00 \| shipped \|
	\| 5-bit \| 0.95 \| blurs \|
	\| 4-bit (g32, g64, mixed 4/6, mixed 4/8) \| 1.05–1.18 \| grain, design changes \|

	## What is in this repo

	\| Path \| Content \|
	\|---\|---\|
	\| `transformer/` \| FLUX 3 Image Klein (distilled, flow map) DiT. Linear layers in the 43 transformer blocks are 6-bit (group size 64, affine). Modulation, time, input embeddings and final layer stay BF16. \|
	\| `text_encoder/` \| Text path of [Qwen3-VL-4B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct) (byte-identical to BFL's bundled encoder), layers 0–31 only (Klein reads layers 4…32), 8-bit. Apache-2.0. \|
	\| `vae/ae.safetensors` \| The FLUX autoencoder, unchanged (fp32). \|
	\| `config.json` \| Repo manifest for the `flux3-mlx` runner (format version, components, sampler defaults) \|
	\| `LICENSE.md`, `NOTICE.md` \| FLUX Kommunity License and Attribution Notice \|
	\| `gallery/` \| Example images with their prompts, seeds and timings \|

	Source: `black-forest-labs/flux-3-image-klein` `model.safetensors` (sha256 `c3e9813c…`, matching BFL's manifest).

	## Limitations

	- Same as the original model (see [BFL's card](https://huggingface.co/black-forest-labs/flux-3-image-klein)):
	- Text rendering can be inaccurate.
	- Edits can change content outside the requested region.
	- Prompt following depends on prompt style.
	- What we saw in our own 27-prompt test (on the BF16 reference as much as here, so these are model traits, not
	conversion artifacts): occasional hand and finger errors, and smooth, slightly waxy skin or a familiar "Flux face"
	on some portraits. Detailed prompts (or `--upsample`) and a few seeds help; edits, multi-reference and layout
	were reliably strong.
	- 16 steps at about 7 s/step on an M4 Pro. 4K output is supported by the code but impractically slow on current Macs.
	- No safety classifier is bundled. Under the license, Qualifying Users who use outputs commercially must apply
	content filtering or review.

	## License

	These weights are a Derivative of FLUX 3 Image Klein and are distributed under the
	[FLUX Kommunity License](LICENSE.md). Any rights to use them are granted directly by Black Forest Labs Inc. under
	that License.
	- Non-commercial use only. Qualifying Users (under US$5M gross annualized revenue) may use Outputs commercially,
	subject to the License.
	- See BFL's [licensing page](https://bfl.ai/licensing) for other commercial uses.
	- The bundled text encoder is Apache-2.0 (`text_encoder/LICENSE`).

	Attribution Notice: This FLUX Model is licensed by Black Forest Labs Inc. under the FLUX Kommunity License. Copyright Black Forest Labs Inc. IN NO EVENT SHALL BLACK FOREST LABS INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH USE OF THIS MODEL.

	Modification: this repository contains a modified version of FLUX 3 Image Klein. The weights were converted to
	the MLX format and the transformer was quantized to 6-bit; the text encoder was truncated to the layers the
	model reads and quantized to 8-bit.