pentacoxian-dev/iris-3b-turbo-lora

Iris-3B Turbo LoRA (4-step)

Few-step LoRA adapters for Iris-3B, a 3B-parameter pixel-space text-to-image diffusion transformer. With an adapter merged in, Iris-3B generates a 1024×1024 image in 4 steps with one forward pass per step. Classifier-free guidance (scale 3) is baked in, so no second guidance pass is needed. The default base sampler uses 100 steps with guidance on every step, about 200 forward passes.

Try it: Iris-3B Turbo Space (ZeroGPU, both adapters selectable).

Left: r1-1500. Right: r2-1000. Same prompts, seed 7, 1024×1024, 4 steps.

Adapter	File	Notes
r2-1000 (recommended)	r2-1000/student.safetensors	Resumed from r1-1500 at half the learning rate with an EMA of the student; 2,500 iterations in total.
r1-1500	r1-1500/student.safetensors	First run, iteration 1,500. Occasionally merges subjects (for example two foxes sharing one body) at some seeds.

Both are rank-64 LoRAs (alpha 64, ~115M parameters, 460 MB in fp32). Each file's safetensors metadata records turbo_steps=4, shift=4.0, cfg_scale=3.0 and resolution=1024.

Usage

The adapters need the inference code from the fork that added few-step sampling: pentaCoxian/iris-3b-turbo.

git clone https://github.com/pentaCoxian/iris-3b-turbo && cd iris-3b-turbo
uv sync            # or: pip install -e .
hf download speridlabs/iris-3b model.safetensors config.yaml --local-dir checkpoints/iris-3b   # ~12 GB

python scripts/sample.py --checkpoint checkpoints/iris-3b \
    --lora pentacoxian-dev/iris-3b-turbo-lora \
    --prompt "a red fox sleeping in fresh snow, golden hour"

--lora pentacoxian-dev/iris-3b-turbo-lora loads the default adapter (r2-1000), and --lora pentacoxian-dev/iris-3b-turbo-lora:r1-1500 loads a specific one. The code reads the repo's config.json manifest, then downloads only that adapter. To download manually instead, include the manifest so the download is counted, and pass the file path to --lora:

hf download pentacoxian-dev/iris-3b-turbo-lora config.json r2-1000/student.safetensors --local-dir checkpoints/turbo

sample.py reads the adapter's metadata and switches to the 4-step sampler. It merges the adapter into the weights at load time, so a step costs the same as a plain forward pass. The text encoder (Qwen3-VL-4B-Instruct) is downloaded on first run.

Macs with 16 GB of memory: add --preset mac16. It encodes prompts in a short-lived subprocess, streams the weights onto the GPU with the adapter merged, and applies weight-only int8 to the text encoder and the image trunk. Peak memory is about 7 GB.

Speed

Measured at 1024×1024, end to end including prompt encoding, after warm-up:

Hardware	4-step turbo	Notes
NVIDIA RTX 5090 (bf16)	0.68 s / image	88 images/min at batch 1
Hugging Face ZeroGPU	~1.1 s GPU time	plus ~3 s of ZeroGPU attach overhead per request
Apple M3 Max, 40-core GPU (bf16)	~10–11 s / image
Apple M3 Max, --preset mac16 (int8)	~11 s / image	~7 GB peak memory

For comparison, the base model's default 100-step sampler takes ~9–11 minutes per image on the same M3 Max.

Training

Distribution-matching distillation (DMD2) without the GAN term, data-free: the training data is prompts only.

• Models: the teacher is the frozen base model with CFG 3. The student and the fake-score critic are two LoRA adapters on one shared frozen bf16 copy of the base weights.
• Student schedule: 4 steps at flow times shift(1 − i/4) with shift 4, i.e. t = 1.0, 0.923, 0.8, 0.571, re-noising with fresh noise between steps. Training uses backward simulation: a random number of no-grad student steps, then one step with gradient.
• Updates: 5 critic updates per student update (two time-scale rule). DMD noise levels are t ∈ [0.02, 0.98] before the shift. The DMD gradient is normalised per sample. AdamW with betas (0, 0.999), batch 1, resolution 1024×1024, gradient clipping at 1.0.
• Adapter placement: rank 64 on every linear layer of the patch embedder, timestep embedder, transformer blocks, pixel stage and final layer. The text adapter stays frozen.
• Run 1 (r1-1500): student and critic learning rate 5e-5, from scratch. The student collapsed to texture between iterations 1,500 and 1,750, so iteration 1,500 is released.
• Run 2 (r2-1000): resumed from r1-1500 with student learning rate 2.5e-5 and an EMA of the student (decay 0.99 per student update), with an automatic stop if previews lose contrast. Iteration 1,000 (2,500 in total) is released, using the EMA weights. Run 2 reached iteration 1,500 without collapsing; 1,000 was chosen by visual comparison.
• Prompts: 7,632 prompts: all 1,632 of PartiPrompts (Apache-2.0) plus 6,000 sampled with seed 0 from k-mktr/improved-flux-prompts (MIT).
• Hardware: one RTX 5090 for training (~1.4 s per iteration, ~18 GB), with the text encoder on an RTX 4090.

Training must run at about one megapixel. The base checkpoint shows 16 px block artifacts at 512×512, which a student trained there would learn.

Limitations

• Qualitative evaluation only. No FID, GenEval or other benchmark has been run, and quality was judged by eye on fixed prompts and seeds.
• Typography is weak. Words are often repeated or garbled (see the poster row above).
• Composition errors at some seeds, such as merged or duplicated subjects, more often with r1-1500.
• Narrower variety than the base sampler. DMD-style students favour high-contrast, "typical" images over the base sampler's full variety.
• Tested only at about one megapixel (1024×1024 and nearby aspect ratios).
• Inactive adaLN-core adapters. In these two releases, the adapters on the shared adaLN modulation cores were never in the forward pass due to a bug fixed later in the fork, so they are exactly zero and timestep modulation was not adapted. Future runs train them.

License

Apache-2.0, the same as the Iris-3B base weights, which these adapters modify and which are required to use them. Iris-3B is by speridlabs; this distillation is an independent community release.