Model card, examples and sampling recipes

.gitattributes

@@ -34,3 +34,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 processor/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+media/examples.jpg filter=lfs diff=lfs merge=lfs -text
+media/recipes.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,133 @@
+---
+language:
+- en
+- zh
+- ru
+license: other
+license_name: qwen-research
+license_link: LICENSE
+base_model:
+- Qwen/Qwen-Image-2.1
+- Viggle/Qwen-Image-2.1-viggle-turbo
+- madebyollin/texture-fix-vae-for-qwen-image-2.1
+base_model_relation: merge
+library_name: diffusers
+pipeline_tag: text-to-image
+tags:
+- diffusers
+- text-to-image
+- image-editing
+- qwen-image
+- turbo
+- few-step
+- distillation
+---
+
+# Image21 Turbo
+
+[Qwen-Image-2.1](https://huggingface.co/Qwen/Qwen-Image-2.1) with the
+[Viggle turbo v0.2.1](https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo) distillation LoRA merged into the
+transformer and the [Texture-Fix VAE](https://huggingface.co/madebyollin/texture-fix-vae-for-qwen-image-2.1) in place
+of the stock decoder. Text-to-image and editing with reference images in **6 steps without guidance**, loaded by the
+stock `QwenImage21Pipeline`. Built with Qwen.
+
+A 4-bit build with a quantized text encoder is published as
+[WaveCut/Image21-Turbo-OrbitQuant-W4A4](https://huggingface.co/WaveCut/Image21-Turbo-OrbitQuant-W4A4).
+
+![examples](media/examples.jpg)
+
+| Component | Contents | Size |
+| --- | --- | ---: |
+| `transformer/` | Qwen-Image-2.1 DiT, Viggle turbo v0.2.1 (rank 256) merged in fp32 and stored in fp16 | 14.2 GB |
+| `text_encoder/` | Qwen3-VL-8B, unchanged | 17.5 GB |
+| `vae/` | Texture-Fix VAE, fp32 | 1.35 GB |
+| `scheduler/` | Viggle turbo config: dynamic shift, `shift_terminal` null | |
+
+## Run
+
+```bash
+pip install -U torch "transformers>=5.17,<6" accelerate safetensors pillow
+pip install "git+https://github.com/huggingface/diffusers.git@80c7ed262aeffbeb43ef13ae04baeb9b84515a69"
+```
+
+```python
+import torch
+from diffusers import QwenImage21Pipeline
+
+pipe = QwenImage21Pipeline.from_pretrained("WaveCut/Image21-Turbo", torch_dtype=torch.float16)
+pipe.enable_model_cpu_offload()
+
+SIGMAS = [1.0, 0.9375, 0.875, 0.75, 0.5, 0.25]
+image = pipe(
+    prompt="A studio portrait of an old fisherman mending a net, warm rim light, 85mm",
+    width=1024, height=1024,
+    num_inference_steps=6, sigmas=SIGMAS,
+    generator=torch.Generator("cuda").manual_seed(0),
+).images[0]
+
+edited = pipe(
+    prompt="Replace the background of <image1> with a sunset beach; keep the man unchanged.",
+    image=[image], output_resolution=1024,
+    num_inference_steps=6, sigmas=SIGMAS,
+    generator=torch.Generator("cuda").manual_seed(0),
+).images[0]
+```
+
+Load the pipeline in **fp16**. The merge keeps 99.7 % of the LoRA update in fp16; loading the same weights in bf16
+rounds away about a third of it (64 % kept). The text encoder and the VAE work in fp16 as well: text embeddings match
+bf16 at cosine 0.998–0.9997, VAE decodes match fp32 at 58–64 dB PSNR.
+
+All weights together are 33 GB, so a 32 GB card needs `enable_model_cpu_offload()` (≈22 s per 1024² image on an
+RTX 5090, most of it host transfers). Encoding a batch of prompts first and then running the transformer and the VAE
+takes 2.69 s per 1024² image hot (6 steps, peak 22.5 GB) and 17.9 s at 2048². The
+[OrbitQuant build](https://huggingface.co/WaveCut/Image21-Turbo-OrbitQuant-W4A4) keeps every component resident in
+13.6 GB and needs 2.25 s.
+
+Keep the VAE untiled in fp16. Tiled decoding in fp16 produces non-finite pixels; for 2048² text-to-image cast it
+first: `pipe.vae.to(torch.bfloat16); pipe.vae.enable_tiling()` (54 dB PSNR against fp32).
+
+## Sampling recipes
+
+Tested at 1024² on 8 prompts (photo, poster, anime, product, night scene, two Russian-text prompts) with fixed
+seeds, plus 4 edits. Times are transformer + VAE on an RTX 5090.
+
+![recipes](media/recipes.jpg)
+
+*Columns: default, 8 steps, 4 steps, static shift 3, CFG 2.*
+
+| Recipe | Settings | Result | Time |
+| --- | --- | --- | ---: |
+| **Default** | 6 steps, `sigmas=[1, 0.9375, 0.875, 0.75, 0.5, 0.25]`, shipped scheduler, no CFG | Sharpest detail and textures; Latin and Cyrillic text mostly right | 2.9 s |
+| **Text, posters, natural skin** | the same 6 sigmas with a static shift of 3: `pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, use_dynamic_shifting=False, shift=3.0)` | Cleanest lettering in the set (long Russian paragraph almost error-free), smoother skin, calmer micro-texture | 2.9 s |
+| Dense text | 8 steps, `sigmas=[1, 0.9375, 0.875, 0.75, 0.625, 0.5, 0.25, 0.125]` | Same composition as the default, small print slightly cleaner | 3.8 s |
+| Guidance | 6 steps, `true_cfg_scale=2` with a negative prompt | Higher contrast and saturation, bolder type | 5.8 s |
+| Avoid | 4 steps `[1, 0.75, 0.5, 0.25]` | Ghosted double contours, garbled text | 2.0 s |
+| Avoid | static shift 5 | Soft, smeared detail | |
+
+Editing: reference images are `<image1>`, `<image2>`, … in the prompt, in the order passed; the canvas follows the last
+reference unless `width`/`height` are given; references are encoded at `output_resolution`² area.
+
+## Merge
+
+| | Value |
+| --- | --- |
+| LoRA | Viggle turbo v0.2.1, rank 256, alpha 256, 227 projections (attention, image MLP, modulation, timestep embedder) |
+| Factors | F32 from `peft_v0.2.1/` |
+| Update size | median 0.11 % of the weight norm, max 1.6 % |
+| Kept after rounding | fp16 99.7 % (rounding noise 18.7 % of the update); bf16 would keep 64 % |
+| Output vs runtime LoRA | 0.4–2.8 % latent difference at the same precision and seed |
+
+Everything outside the 227 projections is the upstream bf16 value stored in fp16.
+
+## Files
+
+`transformer/`, `text_encoder/`, `processor/`, `vae/`, `scheduler/`, `model_index.json` — the diffusers pipeline;
+`media/` — example images; `LICENSE`, `NOTICE` — license and attribution.
+
+## License
+
+Derivative of Qwen-Image-2.1 under the Qwen RESEARCH LICENSE AGREEMENT (`LICENSE`): non-commercial research and
+evaluation only. `NOTICE` lists the modified files and the upstream notices of Viggle and madebyollin.
+
+> Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou Tongyi Laboratory Technology
+> Co., Ltd. All Rights Reserved.