v0.3: 6 steps by default, new 9-step setting (7 turbo + 2 base-model steps)

.gitattributes

@@ -197,3 +197,28 @@ examples/qwen_rgba_bride.png filter=lfs diff=lfs merge=lfs -text
 examples/qwen_storyboard.png filter=lfs diff=lfs merge=lfs -text
 examples/qwen_storyboard_in1.webp filter=lfs diff=lfs merge=lfs -text
 examples/t2i_style_file.png filter=lfs diff=lfs merge=lfs -text
+compare/img/case00/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case00/turbo9_t.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case00/turbo_t.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case01/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case02/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case03/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case03/turbo9_t.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case04/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case05/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case06/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case07/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case08/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case09/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case10/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case11/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case12/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case13/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case14/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case15/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case16/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case17/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case18/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case19/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case20/turbo9.webp filter=lfs diff=lfs merge=lfs -text
+compare/img/case21/turbo9.webp filter=lfs diff=lfs merge=lfs -text

NOTICE

@@ -2,7 +2,7 @@ Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 H
 
 Built with Qwen.
 
-This Space demonstrates Viggle/Qwen-Image-2.1-viggle-turbo, a DMD-distilled 6-step LoRA
+This Space demonstrates Viggle/Qwen-Image-2.1-viggle-turbo, a distilled few-step LoRA
 derivative of Qwen/Qwen-Image-2.1. The base weights are downloaded at runtime from
 Qwen/Qwen-Image-2.1 and are unmodified. Use is limited to non-commercial (research or
 evaluation) purposes, per the Qwen RESEARCH LICENSE AGREEMENT included as LICENSE.

README.md

@@ -19,266 +19,63 @@ tags:
   - text-to-image
   - image-editing
   - distillation
-  - dmd
 # Hardware: this Space needs ZeroGPU, set in Space Settings. `suggested_hardware` is deliberately
 # unset, because the only ZeroGPU value the Hub metadata accepts is the legacy `zero-a10g`, and a
 # 24 GB A10G cannot hold this pipeline. `app.py` requests the 96 GB card with
-# @spaces.GPU(size="xlarge") (no VAE tiling); see the Hardware section for the measurements behind that.
+# @spaces.GPU(size="xlarge") (no VAE tiling).
 # Secrets: set HF_TOKEN (read scope) while Viggle/Qwen-Image-2.1-viggle-turbo is private.
 # `hf_oauth` is not needed: the app calls no user-scoped Hub API.
 ---
 
-# Viggle Turbo v0.2.1 — 6-step Qwen-Image-2.1
+# Viggle Turbo v0.3 — 6-step Qwen-Image-2.1
 
-A DMD-distilled student of **Qwen-Image-2.1** that generates and edits images in **6 sampling steps**
-with **no classifier-free guidance**, against the teacher's 40 steps: about **5× faster**. On most prompts it is
-hard to tell apart from the base model; small, dense text (8 steps narrows the gap) and complicated edits
-(multi-reference composition, face swaps, identity-preserving edits) can still fall short of it. The **Comparison**
-tab shows it side by side with the base model on the official Qwen examples.
+A distilled [Qwen-Image-2.1](https://huggingface.co/Qwen/Qwen-Image-2.1) that generates and edits images in
+**6 steps** with **no classifier-free guidance**, about **5× faster** than the 40-step base model. On most prompts it
+is hard to tell apart from the base model; small, dense text and complicated edits (multi-reference composition, face
+swaps, identity-preserving edits) can still fall short of it.
 
-**v0.2 (2026-09-23):** much better sample diversity than v0.1 — intra-prompt diversity 0.93× the 40-step base
-model, up from 0.75× — and composition / prompt adherence much closer to the base model (see the model card
-for the numbers).
+**v0.3 (2026-09-29):** at 6 steps, less grain than v0.2.1 and a little softer on fine texture. We think 6 steps is
+close to its capacity: every further gain we found cost something elsewhere. The new **9-step** setting runs 7 turbo
+steps and lets the base model finish the last two: finer detail and small text right more often, at about 1.4–1.5× the
+time of 6 steps.
+Weights, numbers and ComfyUI workflows are on the
+[model card](https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo).
 
-**2026-09-24: 6 steps instead of 5, same weights.** The extra step splits the highest-noise segment once more
-(raw nodes `1, 0.9375, 0.875` instead of `1, 0.875`; the low-noise nodes are unchanged). Composition drift
-against the base model goes from 4% of prompts to 0%, diversity from 0.93× to 0.97×, and the images are a
-little sharper.
+**Generate:** leave **References** empty for text-to-image, or add one to six images for editing, composition or
+style transfer; the prompt refers to them as image 1, image 2, … in the order they were added. **Steps** runs from 3
+to 9, 6 is the default. The **Examples** rows are pre-rendered by this exact app; clicking one loads its prompt,
+references, settings and seed. The reference photos `woman1/cat_window/bird.webp` and the three-reference prompt come
+from the [black-forest-labs/flux-klein-9b-kv](https://huggingface.co/spaces/black-forest-labs/flux-klein-9b-kv) Space;
+the `qwen_*` rows come from the [Qwen/Qwen-Image-2.1](https://huggingface.co/spaces/Qwen/Qwen-Image-2.1) Space.
 
-**v0.2.1 (2026-09-24):** the step-700 checkpoint of the same training run (v0.2 was step 600): a little
-sharper and marginally more diverse (0.98× the base model), still 0% composition drift. The examples below are
-rendered with it on the 6-step schedule.
-
-One model does both tasks, exactly as the base does: leave **References** empty for text-to-image,
-or add one to six images (drop them on it, or use **+ Add image**) for editing / composition / style
-transfer. The prompt refers to them as image 1, image 2, … in the order they were added, the number shown
-on each thumbnail.
-
-The **Examples** table below the form is pre-rendered: every row carries the output this exact
-app produced for it (fixed seed, 6 steps, prompt sent as written unless the row's status line says
-otherwise — the three-reference row has prompt enhancement on, and the launch-graphic row is 8 steps at the
-3:2 2048² size), so you can see what the model
-does without spending GPU time — click a row to load the prompt, the references, the result, and the
-steps / size / enhancement settings and seed that produced it (with *Randomize seed* switched off), so
-**Generate** reproduces the row (except the three-reference row, whose stored prompt came from the earlier
-on-GPU rewriter; Generate rewrites it again with DeepSeek). `release/render_examples.py` regenerates the rows
-and `examples/manifest.json` whenever the weights change. The reference photos
-`woman1/cat_window/bird.webp` and the three-reference prompt come from the
-[black-forest-labs/flux-klein-9b-kv](https://huggingface.co/spaces/black-forest-labs/flux-klein-9b-kv) Space;
-the prompts and input images of the `qwen_*` rows come from the
-[Qwen/Qwen-Image-2.1](https://huggingface.co/spaces/Qwen/Qwen-Image-2.1) Space; the character style-file
-row is the image of our promo video.
-
-The **Comparison** tab needs no GPU: 32 of the 37 examples of the Qwen/Qwen-Image-2.1 Space, pre-rendered with
-this model in 6 steps (and in 8 steps on the 5 dense-text examples) and with the base model in 40 steps — same
-prompt, input images and seed 42, prompt enhancement off, one sample each — shown in an image slider with the
-render times, plus Qwen's own API output where their Space ships one. Its images (`compare/`) are built from
-the renders by `release/build_compare_space.py` when `release/upload_space.sh` uploads the Space. Of the five
-examples left out, four are Chinese infographics / a subtitled storyboard whose short prompts leave the on-image
-text to prompt enhancement, and one asks for a named third-party character.
-
-**Built with Qwen.** Distilled from [Qwen/Qwen-Image-2.1](https://huggingface.co/Qwen/Qwen-Image-2.1).
-
-> **Known limits.** Complicated edits (multi-reference composition, face swaps, identity-preserving edits,
-> instructions with several constraints) can still fall short of the 40-step base model, and at 6 steps very
-> small dense text can print less cleanly (8 steps helps). We keep updating the weights as the distillation improves.
-
-## What the app loads
-
-The Space runs the **v0.2.1 LoRA (rank 256)** by default, loaded at runtime on top of the base transformer with
-`pipe.load_lora_weights(STUDENT_REPO, weight_name=LORA_FILE)` and never merged (merging into bf16 keeps only ~47 %
-of the adapter delta). `LORA_FILE` defaults to `Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r256.safetensors`; the
-v0.2 and v0.1 adapters are still in the model repo and can be selected with it. The v0.1 **full fine-tuned transformer**
-is still selectable with `STUDENT=full`:
-
-```python
-transformer = QwenImage21Transformer2DModel.from_pretrained(STUDENT_REPO, subfolder="transformer", torch_dtype=torch.bfloat16)
-pipe = QwenImage21Pipeline.from_pretrained(BASE_MODEL_ID, transformer=transformer, dtype=torch.bfloat16)
-```
-
-`transformer/` is the v0.1 full-parameter fine-tune of the base transformer (bf16, 14.2 GB); passing it as a
-component means the base transformer is never downloaded. The status line under each result names the
-student in use.
-
-Environment: `STUDENT` (`lora`, default, or `full`), `LORA_FILE`, `STUDENT_REPO` (default
-`Viggle/Qwen-Image-2.1-viggle-turbo`; `LORA_REPO` is still accepted), `BASE_MODEL_ID` (default
-`Qwen/Qwen-Image-2.1`), `HF_TOKEN`, `OPENROUTER_API_KEY` (prompt enhancement; without it every prompt is sent
-as written). **`HF_TOKEN` is required while the model repo is private** — add it as a Space secret with read
-scope; it can be removed once the repo is public.
-
-## The 6-step contract
-
-The student is sampled on a specific schedule, and the demo reproduces it exactly:
-
-- **6 Euler steps**, raw sigma nodes `[1, 0.9375, 0.875, 0.75, 0.5, 0.25]` passed as `sigmas=` — the 4-step
-  training nodes `linspace(1, 1/4, 4)` with the first (highest-noise) segment `1 → 0.75` cut into three.
-  The composition is decided in that segment, and a single Euler step across it ghosts and drifts the
-  layout; the low-noise nodes `0.75, 0.5, 0.25` are the ones the student was trained to land on, and moving
-  them (e.g. to `0.625, 0.375`) makes every image visibly softer. The pipeline shifts whatever it is given, so these raw nodes
-  get the same resolution-dependent shift as its defaults.
-- **Extra steps always go to the high-noise end.** The **Steps** slider (3–8) follows `raw_nodes(steps)`
-  in `app.py`: the nodes `0.875, 0.75, 0.5, 0.25` are fixed and the segment `1 → 0.875` is split evenly
-  into `steps − 4` pieces (5: `1, 0.875, …`, the schedule v0.2 launched with; 6: `1, 0.9375, 0.875, …`;
-  7: `1, 0.958, 0.917, 0.875, …`, also validated; 8 untested). 4 is the training schedule (a little less
-  detail and diversity), 3 falls back to the pipeline's uniform `linspace(1, 1/3, 3)` and is off-contract.
-- **Resolution-dependent time shift only.** `mu = calculate_shift((H/16)*(W/16))` with the base
-  scheduler's `base_image_seq_len=256, max_image_seq_len=8192, base_shift=0.5, max_shift=0.9`.
-- **`shift_terminal` must be `null`.** The stock Qwen-Image-2.1 scheduler ships `shift_terminal: 0.02`,
-  which stretches the final sigma node to 0.02 instead of 0 and costs the last step. `app.py` rebuilds
-  the scheduler from the base config with the key cleared, so the contract holds no matter which repo
-  `BASE_MODEL_ID` points at:
-  `pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, shift_terminal=None)`
-- **No CFG.** `true_cfg_scale=1.0` and no negative prompt. (Qwen-Image-2.1 has no `guidance_scale`
-  argument at all; CFG needs both `true_cfg_scale > 1` and a negative prompt.)
-- Condition images are encoded at 1024-area (`output_resolution=1024`), matching distillation.
-
-Verified against `dmd_common.student_sigmas(..., terminal="none")` with the split nodes on a 1024²-bucket
-text-to-image case and a 1024²-bucket edit: max absolute gap **0.0**, and the public
-`load_lora_weights` path is bit-exact against the training code's own adapter path.
-
-## Output sizes
-
-Text-to-image and editing were distilled on different target buckets, so the size menu follows the
-mode and rewrites itself as soon as a reference image is attached:
-
-| mode | target areas | why |
-|---|---|---|
-| text-to-image (no references) | 1024² and 2048² | `build_user_manifest.py` draws T2I targets 50/50 from these |
-| editing (1–6 references) | 1024² and 1536², plus *auto* | editing targets are drawn 70/30 from these |
-
-Every entry is `calculate_dimensions(area, ratio)` rounded to a multiple of 32 — the pipeline's own
-rule — for 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3. *Auto* takes the aspect ratio of the **last**
-reference at 1024² area, which is what the pipeline does when `height`/`width` are left unset.
-`generate()` additionally snaps any editing call whose size is not one of the offered editing
-dimensions onto the 1536² bucket of the nearest aspect ratio, and says so in the status line, so an
-API client or a stale dropdown cannot push a multi-reference call out of budget.
-
-**Custom** (last entry of both menus) shows Width / Height sliders, 512 to 2720 in steps of 32, pre-filled
-with the last preset picked. A custom size above **2048² area for text-to-image** or **1536² area for editing**
-(the largest trained bucket of each mode) is scaled down to that area keeping its ratio, floored to multiples
-of 32, and the status line says so; smaller sizes are used as given. Sizes off the trained buckets work but
-were not evaluated.
-
-Reference images are always resized to **1024² area** before encoding regardless of the output size,
-so extra references cost VRAM and time but not output resolution.
+**Comparison** (no GPU needed): 32 of the 37 examples of the Qwen/Qwen-Image-2.1 Space, pre-rendered with this model
+and with the base model in 40 steps (same prompt, inputs and seed 42, prompt enhancement off, one sample each), in an
+image slider, plus Qwen's own API output where their Space ships one.
 
 ## Prompt enhancement
 
-**Enhance prompt** has three settings: **Auto** (default) rewrites prompts shorter than 30 tokens (Qwen
-tokenizer) and sends longer ones as written, **On** always rewrites, **Off** never does. The rewrite is done by
-DeepSeek V4.1 Flash through OpenRouter (`deepseek/deepseek-v4.1-flash`; low reasoning effort for text-to-image,
-reasoning off for edits; providers sorted by throughput), prompted with shortened versions of the system prompts published with `Qwen/Qwen-Image-2.1-PE-T2I`
-and `-PE-I2I` (`pe_t2i_system_prompt.txt`, `pe_i2i_system_prompt.txt`) that ask for plain text instead of JSON.
-Text-to-image prompts become one English scene paragraph of about 150 words that is told the chosen aspect ratio;
-text to be rendered stays in the request's language. Editing instructions become one to three sentences in the
-instruction's language that spell out what to keep, and the reference images go along, each downscaled to at
-most **0.5 MP**. Measured from our cluster: median 2.0 s for text-to-image, 0.5 s for edits, about $0.0003 per call.
-The request runs before, and outside, the `@spaces.GPU` function, so waiting on it holds no GPU and costs no
-ZeroGPU quota. The rewritten prompt is shown under **Prompt sent to the model**; if the call fails (no
-`OPENROUTER_API_KEY` secret, 30 s timeout, API error), the original prompt is used and the status line says so.
-
-**Privacy.** When enhancement runs, the prompt and the downscaled reference images are sent to OpenRouter and the
-third-party provider it routes the request to; the request only allows providers that neither train on nor retain
-the data (OpenRouter's `data_collection: deny` and zero-data-retention filters). With **Off**, nothing leaves the Space.
-
-Caveats. The student was distilled on raw user prompts, so enhancement is a convenience layered on top of the
-recipe, not part of it. The rewrite is sampled, so the same prompt can come back different, and it sometimes adds
-things the request did not ask for, on-image text included (in testing, one café sign gained an invented
-opening-date line). Switch it **Off** when the wording matters (exact text to render, deliberately terse
-prompts). Until this version the Space ran the same official system prompts on its own Qwen3-VL text encoder
-(on the GPU, ~9 s per call); the three-reference example was rendered with that rewriter.
-
-## Hardware
-
-Weights are ~31.5 GiB resident in bf16 (13.25 transformer + 16.33 text encoder + 0.63 VAE + the r=256
-adapter, 1.3 GiB, loaded in bf16). Measured on one B200 with the v0.2 LoRA at 5 steps (the 6-step default adds one transformer forward, about
-+20% on the sampling time and no extra memory), with the earlier on-GPU prompt rewrite on (it ran before the
-denoise and did not raise the peak), around a single `generate()` call including the VAE encode/decode, with the allocator
-cache dropped before each measurement (`release/measure_mem.py`; the two 2048² rows are the v0.1 full-transformer
-measurements at 4 steps plus the adapter). **No VAE tiling anywhere**: `vae.enable_tiling()` also tiles the
-*encode* of the reference images (256 px tiles), and tiled reference latents wreck an edit - duplicated subjects,
-wrong scale - while a tiled decode is not the validated pipeline either.
-
-| call | output | peak allocated | peak reserved | wall clock (B200) |
-|---|---|---|---|---|
-| text-to-image | 1024×1024 | 38.24 GiB | 40.05 GiB | 0.8 s |
-| text-to-image | 2048×2048 | ~58.3 GiB | ~66 GiB | 3.4 s (v0.1) |
-| edit, 1 reference, auto | 1024×1024 | 40.13 GiB | 42.68 GiB | 1.1 s |
-| edit, 2 references, auto | 832×1248 | 42.04 GiB | 44.71 GiB | 1.5 s |
-| edit, 3 references, auto (the 3-reference example) | 928×1152 | 44.29 GiB | 47.84 GiB | 2.9 s |
-| edit, 3 references (largest) | 1760×1344 | ~52.8 GiB | ~59 GiB | 2.9 s (v0.1) |
-| edit, 6 references, auto | 1024×1024 | 50.17 GiB | 51.95 GiB | see below |
-| edit, 6 references (largest, the `MAX_REFS` limit) | 1760×1344 | 58.41 GiB | 62.29 GiB | see below |
-
-The two 6-reference rows are v0.2.1 at 6 steps on a B200 shared with other jobs, so their times are not
-comparable with the rows above: warm, the denoise took 3.7 s at auto and 6.0 s at 1760×1344 while the node was
-lightly loaded (9-22 s while it was busy), and the first call at a new output size 2-6 s longer. Each reference
-is resized to 1024² area before encoding, so memory grows by ~2 GiB per reference whatever the upload size
-(3 → 6 references: +5.9 GiB at auto, +6.0 GiB at 1760×1344).
-
-The turbo was distilled on edits with at most three references (`build_user_manifest.py` drops samples with
-more), so four to six are outside its training data. In one spot check with six distinct references (two women,
-a cat, a bird, a pony and a shop front; seeds 1-3, enhancement on) all six appeared in every output, at auto and
-at 1760×1344.
-
-ZeroGPU `large` is a 48 GB card with 44.7 GiB usable, so the three-reference edit at the 1024² bucket is
-exactly the call that failed there (the CUDA OOM surfaces on ZeroGPU as `NVML_SUCCESS == r INTERNAL ASSERT
-FAILED` from the caching allocator, because the container cannot query NVML for the OOM report), and the
-2048² text-to-image and 1536² editing buckets never fit untiled. `app.py` therefore requests
-`@spaces.GPU(duration=90, size="xlarge")`: the full 96 GB RTX Pro 6000 Blackwell, at **2× quota** (an
-unauthenticated visitor's 2 min/day covers about three of the largest calls, a free account's 5 min about
-seven; PRO 40 min). `app.py` also sets `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True`. Prompt enhancement
-is an API call made before the `@spaces.GPU` function is entered, so it uses no GPU time. Wall-clock on the
-ZeroGPU card will be slower than the B200 numbers above; `duration=90` covers the largest call.
-
-**Cold start** is dominated by the download: ~30.9 GiB of base safetensors from
-`Qwen/Qwen-Image-2.1` (13.25 transformer + 16.33 text encoder + 1.26 VAE + 0.02 processor) plus
-**1.3 GiB** for the LoRA — the shipped root adapter is bf16, and `load_lora_weights(weight_name=…)`
-fetches that single file, not the F32 `peft_v0.2.1/` copy — then ~30–40 s to load and pack the pipeline
-onto the GPU. Only the adapter changes
-between releases, so a cached Space restarts far faster than it first boots.
-
-### Alpha channels
-
-`gr.Image(..., image_mode="RGB")` drops any alpha channel on upload. The pipeline then calls
-`img.convert("RGBA")` on every condition image itself — the Qwen-Image-2.1 VAE genuinely has
-`in_channels=4` — so what it actually sees is your image with a **fully opaque** alpha. A
-transparent PNG is therefore not composited onto a background: PIL's `RGBA→RGB` keeps the raw colour
-of transparent pixels (often black), and those colours become visible content. Flatten transparent
-images onto the background you want before uploading.
-
-### The vision patch-embed workaround
+**Enhance prompt**: **Auto** (default) rewrites prompts shorter than 30 tokens, **On** always rewrites, **Off** never
+does. The rewrite is done by DeepSeek V4.1 Flash through OpenRouter, prompted with shortened versions of the system
+prompts published with `Qwen/Qwen-Image-2.1-PE-T2I` / `-PE-I2I`. The rewritten prompt is shown under **Prompt sent to
+the model**; if the call fails, the original prompt is used. The rewrite can add things the request did not ask for,
+on-image text included, so switch it **Off** when the wording matters.
 
-`app.py` rebinds `Qwen3VLVisionPatchEmbed.forward` to a matmul. That module applies an `nn.Conv3d`
-whose `kernel_size` equals its `stride`, which is exactly a linear map over each flattened patch, but
-cuDNN has no usable bf16 Conv3d kernel for the shape: it costs **29.9 s per reference image** in this
-pipeline (356 ms in isolation with memory to spare; the same conv in fp32 is 2.9 ms). The matmul is
-**0.8 ms** and its output is bitwise equal to the conv's — all verification images are unchanged
-byte-for-byte. Without it, a 1-reference edit takes 32.3 s and a 2-reference edit 63.1 s, which is why
-`@spaces.GPU(duration=90)` is enough only with the fix in place. Remove it if transformers ever ships
-a fast path here.
+**Privacy.** When enhancement runs, the prompt and the reference images (downscaled to at most 0.5 MP) are sent to
+OpenRouter and the provider it routes the request to; the request only allows providers that neither train on nor
+retain the data. With **Off**, nothing leaves the Space.
 
-## Dependencies
+## Running it
 
-`QwenImage21Pipeline` is **not in any released diffusers** — 0.40.0, the latest on PyPI, contains no
-`qwenimage21` files. `requirements.txt` therefore installs diffusers from git at a pinned commit
-(`80c7ed262aeffbeb43ef13ae04baeb9b84515a69`, upstream `main`, 2026-09-20), and pins
-`transformers==5.17.0` (the pipeline installs a forward hook on the text encoder's final RMSNorm to
-undo the transformers>=5.0 hidden-state tying; a different major may break it), plus
-`accelerate==1.15.0`, `peft==0.18.0` and `spaces==0.51.3` — the versions this release was validated
-against. `peft` is required: without it `load_lora_weights` has no runtime to attach the adapter to.
-`torch` and `gradio` are **not** listed: `sdk_version` above owns the Gradio version, and the
-ZeroGPU image provides torch (its docs list 2.8.0–2.13.0 as supported, which includes the 2.9.1 this
-release was validated on). That last point is an assumption about the image, not a measurement —
-check the first build log and pin `torch==2.9.1` if it resolves something outside that range.
+Environment: `LORA_FILE` (default the v0.3 r256 adapter; the v0.2.1 and v0.2 adapters in the model repo also work),
+`STUDENT_REPO`, `BASE_MODEL_ID`, `HF_TOKEN` (read scope, needed only while the model repo is private),
+`OPENROUTER_API_KEY` (prompt enhancement; without it every prompt is sent as written). The app needs ZeroGPU `xlarge`
+(96 GB): the largest calls do not fit on the 48 GB card untiled, and tiling the VAE breaks edits.
 
 ## License
 
-The base model is released under the
-[Qwen RESEARCH LICENSE AGREEMENT](./LICENSE) — **Non-Commercial: research or evaluation purposes
-only** (§1.i, §2.a). This distilled derivative and this demo inherit that restriction. Commercial use
-requires a separate license from Alibaba (`model-business@notice.qwencloud.com`). See `NOTICE` for
-the attribution required by §3.c.
+The base model is released under the [Qwen RESEARCH LICENSE AGREEMENT](./LICENSE) — **non-commercial: research or
+evaluation purposes only**. This distilled derivative and this demo inherit that restriction. Commercial use requires
+a separate license from Alibaba (`model-business@notice.qwencloud.com`). See `NOTICE` for the required attribution.
 
 > Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou Tongyi
 > Laboratory Technology Co., Ltd. All Rights Reserved.

app.py

@@ -1,4 +1,4 @@
-"""Gradio demo for the DMD-distilled Qwen-Image-2.1 student (v0.2.1: LoRA r256 sampled in 6 steps; v0.2 / v0.1 students still selectable)."""
+"""Gradio demo for the distilled Qwen-Image-2.1 turbo (v0.3: LoRA r256 sampled in 6 steps; 9 steps = 7 turbo + 2 base-model steps)."""
 
 # ZeroGPU patches torch at import time, so `spaces` must be imported before torch or any CUDA use.
 # find_spec keeps this file runnable off-Spaces, where the package is absent.
@@ -34,20 +34,17 @@ import httpx
 import torch
 import compare
 from PIL import Image, ImageOps
-from diffusers import FlowMatchEulerDiscreteScheduler, QwenImage21Pipeline, QwenImage21Transformer2DModel
+from diffusers import FlowMatchEulerDiscreteScheduler, QwenImage21Pipeline
 from diffusers.pipelines.qwenimage21.pipeline_qwenimage21 import calculate_dimensions
 from huggingface_hub import CommitScheduler
 
-# Students in the model repo. STUDENT="lora" (default): the v0.2.1 LoRA (r256) at the repo root, applied at runtime on
-# top of the base transformer and never merged (merging into bf16 keeps only ~47% of the adapter delta, the
-# per-element deltas sit below the bf16 ULP of the base weights). LORA_FILE selects the adapter file; the v0.2 and
-# v0.1 adapters are still in the repo. STUDENT="full": the v0.1 full fine-tune in transformer/ (bf16, exact, no
-# adapter) replaces the base transformer at load time - the base transformer is then not downloaded at all.
+# The v0.3 LoRA (r256) at the model repo root, applied at runtime on top of the base transformer and never merged
+# (merging into bf16 keeps only ~47% of the adapter delta, the per-element deltas sit below the bf16 ULP of the base
+# weights). LORA_FILE selects the adapter file; the v0.2.1 and v0.2 adapters are still in the repo.
 BASE_MODEL_ID = os.environ.get("BASE_MODEL_ID", "Qwen/Qwen-Image-2.1")
 STUDENT_REPO = os.environ.get("STUDENT_REPO", os.environ.get("LORA_REPO", "Viggle/Qwen-Image-2.1-viggle-turbo"))
-STUDENT = os.environ.get("STUDENT", "lora")
-LORA_FILE = os.environ.get("LORA_FILE", "Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r256.safetensors")
-STUDENT_TAG = {"full": "v0.1 full fine-tune (transformer/)", "lora": "v0.2.1 LoRA r256" if "v0.2.1" in LORA_FILE else f"LoRA {LORA_FILE}"}[STUDENT]
+LORA_FILE = os.environ.get("LORA_FILE", "Qwen-Image-2.1-viggle-turbo-v0.3-6step-lora-r256.safetensors")
+STUDENT_TAG = "v0.3 LoRA r256" if "v0.3" in LORA_FILE else f"LoRA {LORA_FILE}"
 HF_TOKEN = os.environ.get("HF_TOKEN")  # only needed while the model repo is private
 # Usage counter. The Space autoscales to several replicas and its log view shows only one of them, so the [gen] log lines
 # undercount. Every generate() call that reaches the GPU also appends one JSON line (metadata only: no prompt, no images)
@@ -81,7 +78,10 @@ def record(**row):
 # launched with, 6 = default, 7 also validated; 4 = the training nodes; 3 is the pipeline's default linspace and
 # off-contract). Passing sigmas= to the pipeline is the whole recipe - it applies the same resolution-dependent
 # shift it applies to its default nodes.
+# 9 is different: the 7-step schedule, one more student step 0.25 -> 1/6, then the base model (LoRA disabled) for the
+# last two steps 1/6 -> 1/12 -> 0 (BASE_FROM = first base-model step).
 STEPS = 6
+BASE_FROM = 7
 
 
 def raw_nodes(steps):
@@ -90,6 +90,8 @@ def raw_nodes(steps):
         return None  # pipeline default linspace(1, 1/steps, steps); off-contract
     if steps == 4:
         return [1.0, 0.75, 0.5, 0.25]
+    if steps == 9:
+        return raw_nodes(7) + [1 / 6, 1 / 12]
     return [1.0 - 0.125 * i / (steps - 4) for i in range(steps - 4)] + [0.875, 0.75, 0.5, 0.25]
 
 
@@ -104,8 +106,8 @@ EXAMPLES_DIR = Path(__file__).parent / "examples"
 EXAMPLES = json.loads((EXAMPLES_DIR / "manifest.json").read_text(encoding="utf-8")) if (EXAMPLES_DIR / "manifest.json").exists() else []
 
 # Output sizes are calculate_dimensions(area, ratio) — the pipeline's own rule, rounded to multiples
-# of 32 — over the target areas the student was distilled on. build_user_manifest.py buckets targets
-# at 1024^2 / 2048^2 for text-to-image and 1024^2 / 1536^2 for editing, so the two modes get
+# of 32 — over the target areas the student was distilled on: 1024^2 / 2048^2 for text-to-image and
+# 1024^2 / 1536^2 for editing, so the two modes get
 # different menus. Reference images are always encoded at 1024^2 area regardless.
 RATIOS = [("1:1", 1.0), ("16:9", 16 / 9), ("9:16", 9 / 16), ("4:3", 4 / 3), ("3:4", 3 / 4), ("3:2", 3 / 2), ("2:3", 2 / 3)]
 AUTO = "Auto · match the last reference (1024² area)"
@@ -131,18 +133,11 @@ EDIT_DIMS = [SIZES[label] for label in EDIT_CHOICES if SIZES[label]]
 CUSTOM_CAP = {False: 2048, True: 1536}  # keyed by "has references"
 MAX_SIDE = max(max(size) for size in SIZES.values() if size)
 
-if STUDENT == "full":
-    transformer = QwenImage21Transformer2DModel.from_pretrained(
-        STUDENT_REPO, subfolder="transformer", torch_dtype=torch.bfloat16, token=HF_TOKEN
-    )
-    pipe = QwenImage21Pipeline.from_pretrained(BASE_MODEL_ID, transformer=transformer, dtype=torch.bfloat16, token=HF_TOKEN)
-else:
-    pipe = QwenImage21Pipeline.from_pretrained(BASE_MODEL_ID, dtype=torch.bfloat16, token=HF_TOKEN)
-    pipe.load_lora_weights(STUDENT_REPO, weight_name=LORA_FILE, token=HF_TOKEN)
+pipe = QwenImage21Pipeline.from_pretrained(BASE_MODEL_ID, dtype=torch.bfloat16, token=HF_TOKEN)
+pipe.load_lora_weights(STUDENT_REPO, weight_name=LORA_FILE, token=HF_TOKEN)
 # The stock Qwen-Image-2.1 scheduler config carries shift_terminal=0.02, which stretches the last
 # sigma node to 0.02 instead of 0 and silently costs the final step. The student was distilled
-# against the unstretched schedule, so rebuild the scheduler with shift_terminal=None; then
-# pipe(num_inference_steps=4) alone reproduces dmd_common.student_sigmas(terminal="none") exactly.
+# against the unstretched schedule, so rebuild the scheduler with shift_terminal=None.
 pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, shift_terminal=None)
 pipe.to("cuda")
 
@@ -214,12 +209,37 @@ def enhance_prompt(prompt, images, ratio_name):
         return None
 
 
+# The pipeline computes the text/reference K/V once at step 0 ("extract") and reuses them ("cached"). In 9-step mode
+# those K/V come from the student, so the first base-model step extracts them again with the LoRA off. The output is
+# bitwise equal to running without the cache, at the cost of one extra extract instead of one per step.
+_transformer_forward = pipe.transformer.forward
+reextract = [False]
+
+
+def transformer_forward(*args, kv_cache_mode=None, **kwargs):
+    if reextract[0] and kv_cache_mode == "cached":
+        kv_cache_mode, reextract[0] = "extract", False
+    return _transformer_forward(*args, kv_cache_mode=kv_cache_mode, **kwargs)
+
+
+pipe.transformer.forward = transformer_forward
+
+
+def base_tail(pipe, i, t, kwargs):
+    if i == BASE_FROM - 1:  # runs after step i, so steps BASE_FROM.. are the base model's
+        pipe.disable_lora()
+        reextract[0] = True
+    return kwargs
+
+
 @gpu
 def denoise(prompt, images, width, height, steps, seed):
     # No VAE tiling anywhere (xlarge card): tiling the reference encode wrecks edits, and tiled decodes are not the
     # validated pipeline either.
     generator = torch.Generator(device="cuda").manual_seed(seed)
     started = time.perf_counter()
+    pipe.enable_lora()  # every call starts on the student, even if an earlier 9-step call died with the LoRA off
+    reextract[0] = False
     result = pipe(
         prompt=prompt,
         image=images or None,
@@ -230,13 +250,15 @@ def denoise(prompt, images, width, height, steps, seed):
         true_cfg_scale=1.0,  # the student is distilled without classifier-free guidance; keep it off
         output_resolution=1024,  # condition images are encoded at 1024-area, as in distillation
         generator=generator,
+        callback_on_step_end=base_tail if steps == 9 else None,
     ).images[0]
+    pipe.enable_lora()
     return result, time.perf_counter() - started
 
 
 def generate(prompt, refs, size_label, seed, randomize_seed, enhance="Auto", steps=STEPS, custom_width=1024, custom_height=1024):
     t0 = time.perf_counter()
-    steps = min(max(int(steps), 3), 8)  # 6 (RAW_NODES) is the validated schedule; 3-8 are accepted, fewer or more degrade quickly
+    steps = min(max(int(steps), 3), 9)  # 6 (RAW_NODES) is the default; 9 = 7 student steps + 2 base-model steps; fewer than 6 degrade quickly
     # refs: the gallery's (filepath, caption) pairs in upload order, which is the order the prompt's "image 1, 2, ..." refer
     # to. EXIF rotation + RGB is what the gr.Image slots used to do.
     if len(refs or []) > MAX_REFS:
@@ -357,9 +379,9 @@ REFS_CSS = """
 #add-ref { display: none; }
 """ + f"body:has(#refs .gallery-item):not(:has(#refs .gallery-item:nth-child({MAX_REFS}))) #add-ref {{ display: flex; }}"
 
-with gr.Blocks(title="Viggle Turbo v0.2.1 · Qwen-Image-2.1 6-step", theme=THEME, head=FONT_HEAD + REFS_HEAD, css=REFS_CSS) as demo:
+with gr.Blocks(title="Viggle Turbo v0.3 · Qwen-Image-2.1 6-step", theme=THEME, head=FONT_HEAD + REFS_HEAD, css=REFS_CSS) as demo:
     gr.Markdown(
-        "# Viggle Turbo v0.2.1 — 6-step Qwen-Image-2.1\n"
+        "# Viggle Turbo v0.3 — 6-step Qwen-Image-2.1\n"
         "Text-to-image and image editing in **6 steps**: about **5× faster** than the 40-step Qwen-Image-2.1 and very "
         "competitive with it in quality — see the **Comparison** tab. Leave the references empty for text-to-image, "
         f"or add up to {MAX_REFS} to edit, compose or transfer style.\n\n"
@@ -368,12 +390,14 @@ with gr.Blocks(title="Viggle Turbo v0.2.1 · Qwen-Image-2.1 6-step", theme=THEME
     )
     with gr.Accordion("About this model", open=False):
         gr.Markdown(
-            "A DMD-distilled student of **Qwen-Image-2.1**, sampled with no classifier-free guidance. On most prompts it "
-            "is hard to tell apart from the base model; small, dense text (8 steps narrows the gap) and complicated edits "
-            "(multi-reference composition, face swaps, identity-preserving edits) can still fall short of it. The **Comparison** tab has 32 examples of the official "
+            "A distilled Qwen-Image-2.1 that runs with no classifier-free guidance. On most prompts it is hard to tell "
+            "apart from the base model; small, dense text and complicated edits (multi-reference composition, face swaps, "
+            "identity-preserving edits) can still fall short of it. The **Comparison** tab has 32 examples of the official "
             "Qwen Space side by side, turbo vs base, same seed.\n\n"
-            "**v0.2.1 (2026-09-24):** the step-700 checkpoint of the v0.2 run on the 6-step schedule — intra-prompt diversity "
-            "0.98× the base model, 0% composition drift; earlier versions and the numbers are on the model card. "
+            "**v0.3 (2026-09-29):** at 6 steps, less grain than v0.2.1 and a little softer on fine texture. We think 6 steps "
+            "is close to its capacity: every further gain we found cost something elsewhere. **9 steps** runs 7 turbo "
+            "steps and lets the base model finish the last two: finer detail and small text right more often, at about 1.4–1.5× the "
+            "time of 6 steps. "
             f"Weights: **{STUDENT_TAG}** from [{STUDENT_REPO}](https://huggingface.co/{STUDENT_REPO})."
         )
     with gr.Tabs() as tabs:
@@ -406,8 +430,8 @@ with gr.Blocks(title="Viggle Turbo v0.2.1 · Qwen-Image-2.1 6-step", theme=THEME
                         "sent to the image model is shown under the result.",
                     )
                     with gr.Accordion("Advanced settings", open=False) as advanced:
-                        steps = gr.Slider(label="Steps", minimum=3, maximum=8, step=1, value=STEPS,
-                                          info="6 is the validated schedule; extra steps are added at the high-noise end.")
+                        steps = gr.Slider(label="Steps", minimum=3, maximum=9, step=1, value=STEPS,
+                                          info="6 is the default; 7-8 add steps at the high-noise end; 9 = 7 turbo + 2 base-model steps (finer detail; ~1.4–1.5× the time).")
                         with gr.Row():
                             seed = gr.Number(label="Seed", value=0, precision=0, interactive=False)
                             randomize_seed = gr.Checkbox(label="Randomize seed", value=True)