Model card: hero comparison, quickstart, results table, how it works, limitations

.gitattributes

@@ -34,3 +34,7 @@ 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
 assets/turbo_vs_full.jpg filter=lfs diff=lfs merge=lfs -text
+assets/hero_pebbles.jpg filter=lfs diff=lfs merge=lfs -text
+assets/same_seed.jpg filter=lfs diff=lfs merge=lfs -text
+assets/lichen.jpg filter=lfs diff=lfs merge=lfs -text
+assets/schedule.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -19,61 +19,77 @@ tags:
 
 # MOSS-Image-SFT Turbo for Apple Silicon (MLX)
 
-A few-step sampler for [OpenMOSS-Team/MOSS-Image-SFT](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT) on Macs: **15 network passes instead of 100**, about **2 minutes** per ~1 MP image on an M4 Pro instead of about 12½. It stays close to what the full model draws for the same seed, including its textures and lettering. Runs with [moss-image-mlx](https://github.com/felix-ab/moss-image-mlx) `--turbo`.
+A few-step sampler for [OpenMOSS-Team/MOSS-Image-SFT](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT) on Macs: **15 network passes instead of 100**. That is about **2 minutes** per ~1 MP image on an M4 Pro, instead of about 12½ (**6.2×**). It stays close to what the full 50-step model draws for the same seed, including its textures and lettering, and it does not "stamp" repeated texture the way DMD turbo adapters do.
 
-This repository holds the trained student: a rank-64 LoRA on the SFT transformer (252 projections, fp32, 595 MB).
+**Code:** [moss-image-mlx](https://github.com/felix-ab/moss-image-mlx) (`--turbo`) · **Write-up:** [how it was designed and measured](https://github.com/felix-ab/moss-image-turbo-research/blob/main/docs/technical-writeup.md) · **Base tiers:** [8bit](https://huggingface.co/VisualInference/MOSS-Image-SFT-MLX-8bit), [compact](https://huggingface.co/VisualInference/MOSS-Image-SFT-MLX-compact)
 
-![The original model at 50 steps (top) and --turbo (bottom), same prompts and seeds](assets/turbo_vs_full.jpg)
+![Wet river pebbles, same seed: full model at 50 steps, the new turbo, and a DMD-adapter turbo, with 100% crops](assets/hero_pebbles.jpg)
 
-*Held-out prompts never used in training, seed 101. Most compositions stay close to the full model's; some drift (middle).*
+*A held-out prompt never used in training, seed 101, 8bit tier, 100% crops below. The turbo keeps the full model's pebbles. A DMD-adapter turbo (a community adapter plus 2 original-model steps) turns them into uniform glossy beads.*
+
+This repository holds only the trained student: a rank-64 LoRA on the SFT transformer (252 projections, fp32, 595 MB). The package downloads it automatically.
 
 ## Quickstart
 
 ```bash
-pip install moss-image-mlx
+pip install -U moss-image-mlx     # 0.2.0 or newer
 moss-mlx "A highway LED sign at sunset that reads \"HELLO MLX\"" --turbo -o sign.png
 ```
 
-The first run downloads an 8-bit MOSS-Image tier, this student and the destripe adapter, and caches them.
+- **First run:** it downloads the 8-bit MOSS-Image tier, this student (pinned to a fixed revision) and the destripe adapter, then caches them.
+- **Sizes:** trained at ~1 MP in 9 aspect ratios, from 768×1360 through 1024×1024 to 1360×768. Set them with `--width` and `--height`.
+- **More images:** `--seeds 1,2,3` renders several seeds with one load; `--batch jobs.jsonl` renders many prompts.
+- **Ignored in turbo mode:** `--steps` and `--shift`. `--turbo-weights FILE` uses a local copy of the student.
+- **Requirements:** an Apple Silicon Mac. It was measured on the 8bit tier, the default on Macs with ≥ 24 GB.
 
-## How it works
+## Results
+
+The comparison is against the destriped official sampler (50 steps, CFG 3, block-22 skip) on **32 held-out prompts**, each at its own aspect ratio, seed 101:
 
-1. **Student, 6 steps, no CFG.** It covers the first half of the original model's own 50-step trajectory (σ 1 → .671). It was trained by regression onto that trajectory, with no distribution matching:
-   - teacher data from about 2,000 prompts at ~1 MP in 9 aspect ratios (English and Chinese text, JSON layouts, people, products, places, materials);
-   - targets relabelled from the teacher's own continuation of the student's states.
-2. **One guided original-model step** replaces the student's second step (σ .957 → .919). That is where lettering is decided.
-3. **The original model finishes** with 4 DPM-Solver++(2M) evaluations (σ .671 → 0).
-4. **Destripe throughout:** [nynxz's destripe LoRA](https://huggingface.co/nynxz/MOSS-Image) at 1.5. The teacher data was destriped too.
+| | **This turbo** | DMD-adapter turbo | Full model, 50 steps |
+|---|---|---|---|
+| Network passes | **15** | 10 | 100 |
+| Time per ~1 MP image (M4 Pro, 8bit) | **~119 s** | ~80 s | ~743 s |
+| Peak memory | 9.4 GB | 9.3 GB | 9.3 GB |
+| Stamped texture (DINOv2 repetition, excess over the full model; materials + nature, n = 8) | **−0.006** | +0.063 | 0 |
+| Fine detail (high-frequency energy vs the full model) | **−0.004** | −0.022 | 0 |
+| Mean \|luma difference\| from the full model's image | **0.090** | 0.124 | 0 |
+| Brightness difference | +0.011 | −0.049 | 0 |
+| English text, OCR character recall (n = 4) | 0.947 | 0.951 | 0.934 |
 
-Passes: 5 student + 2 guided + 8 finish = 15.
+The package's sampler reproduces the research images bit for bit. The metrics are defined in [how-the-numbers-work.md](https://github.com/felix-ab/moss-image-turbo-research/blob/main/docs/how-the-numbers-work.md).
 
-## Evaluation
+![Four held-out prompts, full model at 50 steps beside the turbo with the same seed: a croissant, a novel cover, a fox in snow and a Chinese tea wrapper](assets/same_seed.jpg)
+
+![Lichen on a stone wall, same seed: full model, turbo and a DMD-adapter turbo with 100% crops; the DMD turbo stamps identical rosettes](assets/lichen.jpg)
+
+## How it works
 
-The comparison is against the destriped 50-step model (CFG 3, layer-22 skip) on 32 held-out prompts, seed 101:
+![The official sampler's 100 passes vs the turbo's 15: 5 student passes, a 2-pass guided step at slot 2, and an 8-pass original-model finish](assets/schedule.png)
 
-| | This turbo | Earlier distilled turbo (DMD adapter) |
-|---|---|---|
-| Repeated "stamped" texture (DINOv2 recurrence, excess over the full model) | **−0.006** (none) | +0.063 |
-| Fine detail (high-frequency energy vs the full model) | −0.004 | −0.022 |
-| Mean pixel difference from the full model | **0.090** | 0.124 |
-| Brightness difference | +0.011 | −0.049 (darker) |
-| English text (OCR character recall; full model 0.934) | 0.947 | 0.951 |
+1. **Student, 6 steps, no CFG.** It covers the composition part of the original model's own 50-step trajectory (σ 1 → .671).
+   - **Training:** regression onto that trajectory, with no distribution matching. Teacher data comes from about 2,000 prompts at ~1 MP in 9 aspect ratios (English and Chinese text, JSON layouts, people, products, places, materials).
+   - **Targets:** on the student's own drifted states, the teacher is re-run from where the student actually is. In a controlled ablation, targets that snap back to the stored path ghosted a face and garbled Chinese characters; these targets did neither.
+2. **One guided original-model step** replaces the student's third step (slot 2, σ .957 → .919). The step was tried in each of the 6 slots. Only there did it repair both a ghosted shop-sign headline and an infographic title (7 prompts, one seed; confirmed on the held-out set).
+3. **The original model finishes** with 4 DPM-Solver++(2M) evaluations (σ .671 → 0). From an exact mid-trajectory state, this finish is 4.6× closer to the 50-step image than a distilled finish.
+4. **Destripe throughout:** [nynxz's destripe LoRA](https://huggingface.co/nynxz/MOSS-Image) runs at 1.5. The teacher data was destriped too.
 
-Speed and memory, M4 Pro, 8bit tier, ~1 MP: 117 s sampling + 2 s decode; peak memory 9.4 GB (a short prompt; the full model peaks at 9.3 GB).
+Passes: 5 student + 2 guided + 8 finish = 15. The student was trained on rented A100s for about $37.
 
-Design rationale, per-decision evidence and open questions: [technical write-up](https://github.com/felix-ab/moss-image-turbo-research/blob/main/docs/technical-writeup.md). How each number is computed: [the metrics write-up](https://github.com/felix-ab/moss-image-turbo-research/blob/main/docs/how-the-numbers-work.md). The full study is at [felix-ab/moss-image-turbo-research](https://github.com/felix-ab/moss-image-turbo-research): where earlier turbos' stamped textures came from, the training design, and every decision.
+**Why not distill the whole trajectory?** Exact cached 50-step states, finished by a DMD adapter, still stamp. The more distilled steps run in the middle of the trajectory, the more stamping appears. So the distilled network stays out of the band where texture is organized. The [technical write-up](https://github.com/felix-ab/moss-image-turbo-research/blob/main/docs/technical-writeup.md) has the evidence for each decision and what failed. The [research repo](https://github.com/felix-ab/moss-image-turbo-research) has the full lab notebook.
 
 ## Limitations
 
-- **Small, dense text** slips more often than with the full model.
+- **Small, dense text** slips more often than with the full model (OCR 0.957 vs 0.970 on 8 prompts).
 - **Regular geometry** can come out more organic than it should: a chain-link fence shadow, rows of machines.
 - **Compositions** usually follow the full model for the same seed, but not always.
-- **Resolution:** trained for ~1 MP in 9 aspect ratios; other sizes are untested.
-- **Checkpoint:** SFT only.
+- **Untested:** sizes outside ~1 MP and the 9 trained aspect ratios; the compact and bf16 tiers with `--turbo`; the Base checkpoint (the CLI refuses `--transformer` in turbo mode).
+- **Evidence size:** 1–2 seeds and 7–32 prompts per comparison, with visual checks by the author and the project owner. There is no FID or KID at scale.
 
 ## License and credits
 
 Apache-2.0.
 - **Base model:** MOSS-Image SFT, © OpenMOSS, Apache-2.0.
 - **Destripe adapter:** by nynxz, Apache-2.0.
+- **DMD adapter in the comparisons:** by lodestones; used only as a baseline, not shipped here.
 - **This work** is independent and not affiliated with OpenMOSS.