Document production image prompt enhancement

docs/QWEN_IMAGE_21.md

@@ -31,10 +31,14 @@ Ein Bildauftrag läuft transaktional:
 
 1. Der Router merkt sich das aktive Textprofil.
 2. Der Profile Controller stoppt LLM, TTS und andere GPU-Spezialworker.
-3. `mike-ai-image-worker` startet Qwen Image auf der RTX 5080.
-4. Der Adapter erzeugt das Bild oder bearbeitet bis zu vier Referenzbilder.
-5. Der Qwen-Worker wird vollständig gestoppt.
-6. Das vorherige Textprofil und Qwen3-TTS werden wiederhergestellt.
+3. Bei einem Textauftrag startet `mike-ai-image-prompt-enhancer-t2i`, bei
+   Referenzbildern `mike-ai-image-prompt-enhancer-i2i` auf der RTX 3060.
+4. Der offizielle Qwen-Enhancer schreibt den knappen Benutzertext um und wird
+   anschließend vollständig gestoppt.
+5. `mike-ai-image-worker` startet Qwen Image auf der RTX 5080 und erzeugt das
+   Bild oder bearbeitet bis zu vier Referenzbilder.
+6. Der Qwen-Worker wird vollständig gestoppt.
+7. Das vorherige Textprofil und Qwen3-TTS werden wiederhergestellt.
 
 Der Container ist außerhalb eines Auftrags gestoppt. Das ist der Sollzustand.
 
@@ -46,13 +50,14 @@ sudo ./scripts/prepare-qwen-image-21.sh
 ```
 
 Das Skript lädt fehlende Dateien mit festen SHA-256-Prüfsummen, baut den
-produktiven Qwen-Worker und legt Qwen sowie FLUX gestoppt an. Es lädt dabei
-kein Modell in den VRAM.
+produktiven Qwen-Worker und legt Qwen, beide Prompt-Enhancer sowie FLUX
+gestoppt an. Es lädt dabei kein Modell in den VRAM.
 
 ## Funktionsprobe über den echten Routerweg
 
 ```bash
 curl -sS http://127.0.0.1:8081/v1/images/generations \
+  -H "Authorization: Bearer $ROUTER_API_KEY" \
   -H 'Content-Type: application/json' \
   -d '{
     "model":"Qwen-Image-2.1-int8",
@@ -64,7 +69,7 @@ curl -sS http://127.0.0.1:8081/v1/images/generations \
   }'
 ```
 
-Nach dem Lauf müssen `mike-ai-image-worker` und
+Nach dem Lauf müssen `mike-ai-image-worker`, beide Prompt-Enhancer und
 `mike-ai-flux-image-worker` gestoppt sein und das vorherige LLM-Profil wieder
 gesund laufen.
 
@@ -151,68 +156,76 @@ Historische FLUX-Messwerte und Grenzen stehen in
 [FLUX_9B_BETA.md](FLUX_9B_BETA.md) und
 [FLUX_RESOLUTION_TEST_20260912.md](FLUX_RESOLUTION_TEST_20260912.md).
 
-## Offizieller Prompt Enhancer: Vorabtest vom 21. September 2026
+## Offizielle Prompt-Enhancer im produktiven Router
 
-Qwen veröffentlicht für Referenzbild-Aufträge einen separaten, auf
-Qwen3.5-VL 9B nachtrainierten Prompt Enhancer. Er ist kein Bestandteil der
-Qwen-Image-Gewichte und wird vom ComfyUI-Workflow nicht automatisch geladen.
-Der produktive Router verwendet ihn derzeit noch nicht; der folgende Test
-prüfte zunächst Speicherbedarf, Laufzeit und Wirkung.
+Qwen veröffentlicht zwei getrennte, auf Qwen3.5-VL 9B nachtrainierte
+Prompt-Enhancer. Sie sind kein Bestandteil der Qwen-Image-Gewichte. Athena
+startet automatisch die zum Auftrag passende Variante; OpenClaw ruft weiterhin
+nur sein normales Werkzeug `image_generate` mit dem unveränderten Modellnamen
+`openai/Qwen-Image-2.1-int8` auf.
 
-Geprüft wurde `Qwen/Qwen-Image-2.1-PE-I2I`, Revision
-`72927bc08afc99b7888ceb7d7d51a12db3700bbd`. Der offizielle Systemprompt
-verlangt bei mehreren Eingabebildern eine strukturierte Zuordnung und liefert
-zusätzlich `wh_ratio` beziehungsweise `ratio_follow`.
+- `mike-ai-image-prompt-enhancer-t2i` bereitet reine Textaufträge auf.
+- `mike-ai-image-prompt-enhancer-i2i` wertet ein bis vier Referenzbilder
+  gemeinsam aus und trennt Identität, gewünschte Änderungen und neue Szene.
+- Beide verwenden getrennte offizielle Systemprompts, `Q5_K_M`, llama.cpp
+  Build 10930, 16.384 Token Kontext und höchstens 2.048 Denktokens.
+- Sie laufen ausschließlich und nacheinander auf der RTX 3060. Nach dem Rewrite
+  werden sie gestoppt; Qwen-Image rendert anschließend auf der RTX 5080.
+- Falls der Client keine Größe vorgibt, übernimmt der Router das vom Enhancer
+  vorgeschlagene Seitenverhältnis und bildet es auf eine erlaubte Auflösung ab.
+  Eine ausdrücklich angegebene gültige Größe bleibt unverändert.
+- Das Sidecar jedes PNG enthält `original_prompt`, den tatsächlich verwendeten
+  `prompt` und Modell, Quantisierung, Laufzeit und Verhältnis unter
+  `prompt_enhancer`. Verdeckte Denktokens werden nicht gespeichert.
+- Ein fehlgeschlagener Rewrite bricht den Bildauftrag sichtbar ab. Der Router
+  sendet in diesem Fall keinen unaufbereiteten Ersatzprompt an Qwen-Image.
 
-### FP8 auf der RTX 3060
+### Gepinnte Dateien
 
-Der vorquantisierte Testcheckpoint
-`prithivMLmods/Qwen-Image-2.1-PE-I2I-FP8`, Revision
-`ac9065ce94fdc39b9aecfff7d11f297b77a5c178`, umfasst 13,54 GB und passt
-einschließlich Laufzeit- und Aktivierungsspeicher nicht vollständig in die
-12-GB-RTX-3060:
-
-- mit 11.264 MiB Modellbudget scheiterte das Laden bei nur noch 32 MiB freiem
-  VRAM an einer weiteren 96-MiB-Allokation;
-- mit 9.216 MiB Modellbudget und CPU-Offload scheiterte die Inferenz bei nur
-  noch 78 MiB freiem VRAM an einer 136-MiB-Allokation;
-- mit 7.168 MiB Modellbudget, CPU-Offload und auf 262.144 Pixel verkleinerten
-  Referenzen lief die Inferenz, erzeugte wegen der langsamen Transformers-
-  Referenzkerne aber auch nach mehr als drei Minuten noch keinen Rewrite.
-
-Der FP8-Testcheckpoint wurde anschließend wieder entfernt. FP8 mit CPU-Offload
-ist damit kein sinnvoller Produktionspfad auf dieser 3060.
-
-### Q5 vollständig auf der RTX 3060
-
-Als funktionierender Vergleich wurde dieselbe PE-I2I-Feinabstimmung als
-`Q5_K_M`-GGUF aus
+PE-I2I stammt aus `Qwen/Qwen-Image-2.1-PE-I2I`, Revision
+`72927bc08afc99b7888ceb7d7d51a12db3700bbd`, und dem GGUF-Repository
 `prithivMLmods/Qwen-Image-2.1-PE-I2I-GGUF`, Revision
-`55b9c1a326599e142d59bcad8715d5601ccf8daa`, mit llama.cpp Build 10930
-getestet. Die Dateien liegen vorerst außerhalb von Git unter
-`/data/models/qwen-image-2.1-pe-i2i-q5-test`:
+`55b9c1a326599e142d59bcad8715d5601ccf8daa`. Die Dateien liegen unter
+`/data/models/qwen-image-2.1-pe-i2i-q5`:
 
 | Datei | SHA-256 |
 |---|---|
 | `Qwen-Image-2.1-PE-I2I.Q5_K_M.gguf` | `cb71f71fe5fe5938570d65a7c403fbcb1a9065dff9dd9a021f58aec42785b84e` |
 | `Qwen-Image-2.1-PE-I2I.mmproj-bf16.gguf` | `8dedb71dbc3092dc47de9108ad373d68a12854e2527d59bd9399601738f3bce1` |
+| `system_prompt.txt` | `e378fea686a1431581ba4c654d332ae96adad633f144ae738ec8ce9c4fd66439` |
 
-Mit vier Peter-Maffay-Referenzbildern belegte der Rewriter 7.167 MiB VRAM.
-Der erste Prefill umfasste 10.045 Tokens und lief mit 791,3 Token/s; die
-Ausgabe lief mit 45,9 Token/s. Ohne Denkbudget verbrauchte das Modell mehr als
-4.096 Ausgabetokens. Mit `thinking_budget_tokens: 2048` lieferte es nach 52,0
-Sekunden gültiges JSON mit 2.384 Ausgabetokens. Der Rewrite erkannte die vier
-Bilder als dieselbe Person und formulierte ausdrücklich eine einzelne Person,
-genau eine Gummiente und ein neues 3:4-Motiv.
+PE-T2I stammt aus `Qwen/Qwen-Image-2.1-PE-T2I`, Revision
+`f3ed7985c788ad75b3ab7223e0c4c51e2a43545b`, und dem GGUF-Repository
+`prithivMLmods/Qwen-Image-2.1-PE-T2I-GGUF`, Revision
+`e18d4a3e0830ab157770738b16830e6fcf5f57d4`. Die Dateien liegen unter
+`/data/models/qwen-image-2.1-pe-t2i-q5`:
 
-Der anschließende Ende-zu-Ende-Lauf hielt den Rewriter auf der RTX 3060 und
-Qwen-Image-2.1 auf der RTX 5080. Qwen-Image benötigte 193,18 Sekunden und
-erzeugte ein neues PNG mit 1.312 × 1.824 Pixeln, genau einer Person und genau
-einer gelben Gummiente. Das Ergebnis liegt im Router-Bildvolume als
-`qwen-pe-e2e.png`; SHA-256:
-`931cd3cf46993aee735e95c7c2447c500a498ffb600a26a96f5faab87a0260e9`.
+| Datei | SHA-256 |
+|---|---|
+| `Qwen-Image-2.1-PE-T2I.Q5_K_M.gguf` | `749f5652fd6e8b760ca860091f7a5bffa254a7954203ae5c9bcdf5f93197702f` |
+| `system_prompt.txt` | `a77c9a06c59b120741141d9514b95682bb8761d02bec49ca61def7b2b3d9fb99` |
 
-Nach dem Test wurden beide Testworker gestoppt und Medium sowie Qwen3-TTS
-wieder gesund gestartet. Der Q5-Checkpoint bleibt für die geplante
-Routerintegration liegen, ist aber noch kein automatisch gestarteter
-Produktionsdienst.
+Der zuvor geprüfte PE-I2I-FP8-Checkpoint ist 13,54 GB groß und passt mit
+Aktivierungs- und Laufzeitspeicher nicht in die 12-GB-RTX-3060. CPU-Offload war
+unpraktisch langsam. Er wurde verworfen und entfernt. Der Q5-I2I-Worker belegt
+etwa 7.167 MiB VRAM und ist deshalb der produktive Stand.
+
+### Abnahme vom 21. September 2026
+
+Der vollständige öffentliche Routerweg wurde nach der Integration zweimal
+geprüft:
+
+- Ein kurzer deutscher Textprompt wurde von PE-T2I in 36,6 Sekunden in einen
+  strukturierten englischen Produktionsprompt umgeschrieben. Qwen-Image
+  erzeugte das 1024×1024-PNG anschließend in 49,0 Sekunden.
+- Ein hochgeladenes Referenzbild wurde von PE-I2I in 65,9 Sekunden aufbereitet.
+  Der Rewrite verlangte ausdrücklich eine neue Szene, neue Pose und Kleidung
+  sowie das Entfernen der alten Gegenstände. Qwen-Image erzeugte in 111,3
+  Sekunden ein neues 1024×1536-PNG: genau eine Person in einer Blumenwiese an
+  einer Autobahn, ohne Badewanne, Gitarre oder Gummiente.
+
+Nach beiden Aufträgen waren der Bildworker und beide Enhancer gestoppt. Medium
+und Qwen3-TTS liefen wieder gesund. Der erste I2I-Versuch deckte eine relative
+Pfadauflösung bei temporären Multipart-Uploads auf; der korrigierte Pfad ist mit
+einem eigenen Regressionstest abgedeckt. Insgesamt laufen 96 schnelle
+GPU-freie Release-Tests.