Add dual-GPU FLUX 9B image pipeline

2026-09-07 15:42:45 +02:00
parent 61aa20cb52
commit 1844551534
19 changed files with 945 additions and 51 deletions
@@ -0,0 +1,153 @@
+# FLUX.2 Klein 9B FP8 Beta auf Athena
+
+Stand: 7. September 2026
+
+## Zweck und Status
+
+Der Bildpfad ersetzt testweise FLUX.2 Klein 4B durch das größere
+FLUX.2-Klein-9B-Modell. Ziel sind bessere Prompttreue, räumliche Beziehungen,
+Objektkonsistenz und Referenzbild-Bearbeitung. Der Pfad ist technisch
+funktionsfähig, bleibt aber bis zu weiteren Qualitäts- und Editing-Tests als
+Beta bezeichnet.
+
+Der OpenAI-kompatible Modellname lautet:
+
+```text
+FLUX.2-klein-9B-fp8-beta
+```
+
+## Modellartefakte und Lizenz
+
+Verwendet werden zwei gepinnte, zugriffsbeschränkte Hugging-Face-Repositories:
+
+| Zweck | Repository | Revision | Lokaler Pfad |
+|---|---|---|---|
+| Pipeline-Komponenten, Qwen3-Textencoder und VAE | `black-forest-labs/FLUX.2-klein-9B` | `92196c8e11f7b6cf2b7493e037d8c5345c559216` | `/data/models/FLUX.2-klein-9B-components` |
+| FP8-Transformer | `black-forest-labs/FLUX.2-klein-9b-fp8` | `902d9d510b51533e07729f19211414a3648b77d2` | `/data/models/FLUX.2-klein-9B-fp8` |
+
+FLUX.2 Klein 9B steht unter der FLUX Non-Commercial License. Vor dem Download
+müssen die Bedingungen beider Repositories im verwendeten Hugging-Face-Konto
+akzeptiert werden. Ein Token gehört ausschließlich in die durch
+`HF_TOKEN_FILE` angegebene, für root lesbare Datei; niemals in Git oder
+`stack.env`.
+
+## GPU-Aufteilung
+
+| Phase | RTX 5080, 16 GB | RTX 3060, 12 GB |
+|---|---|---|
+| Text-/Sprachbetrieb | aktives Qwen3.8-27B-Profil | Qwen3-TTS; Vision je nach Profil |
+| Prompt-Encoding | FLUX-Transformer und VAE | Qwen3-8B-Textencoder, NF4 |
+| Denoising | FLUX-Transformer | Textencoder wird nicht mehr benötigt |
+| VAE-Decoding | VAE; Transformer zuvor freigegeben | Textencoder zuvor freigegeben |
+
+Der Profile Controller stoppt vor dem Start des Bild-Workers alle
+llama.cpp-Profile und den mit `com.mike-ai.tts-worker=qwen3` markierten
+Qwen3-TTS-Container. Dadurch bleibt genügend VRAM für beide Bildkomponenten.
+Nach dem Bildauftrag startet er Qwen3-TTS und das zuvor aktive Textprofil
+wieder. Der TTS-Gateway kann während des Wechsels auf Piper ausweichen.
+
+## Aktuelle Grenzen
+
+- genau 1024 × 1024 Pixel
+- genau vier Inferenzschritte
+- Guidance Scale 1,0
+- ein Bildauftrag gleichzeitig
+- höchstens vier bereits lokal gespeicherte Referenzbilder
+- Textencoder-Maximum 128 Token
+- Bildbearbeitung wird vom Worker angenommen, ist aber noch gesondert
+  Ende-zu-Ende zu qualifizieren
+
+## Installation und Aktualisierung
+
+In `/root/mike-ai-install.env` müssen diese Werte gesetzt sein:
+
+```bash
+HF_TOKEN_FILE=/root/.cache/huggingface/token
+FLUX_COMPONENT_DIR=/data/models/FLUX.2-klein-9B-components
+FLUX_TRANSFORMER_DIR=/data/models/FLUX.2-klein-9B-fp8
+```
+
+Anschließend lädt der normale Installer nur die benötigten Komponenten und die
+gepinnten FP8-Gewichte. Bestehende, vollständige Dateien werden nicht erneut
+geladen:
+
+```bash
+cd /opt/mike-ai/stack
+sudo ./install.sh --config /root/mike-ai-install.env
+```
+
+## Funktionsprobe
+
+Der Router ist nur über das private Netz erreichbar. Ein minimaler Test lautet:
+
+```bash
+curl -fsS http://192.168.1.212:8081/v1/images/generations \
+  -H "Authorization: Bearer $ROUTER_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model":"FLUX.2-klein-9B-fp8-beta",
+    "prompt":"A yellow toy excavator on the left and a red toy truck on the right, studio photo",
+    "size":"1024x1024",
+    "steps":4,
+    "guidance":1.0,
+    "seed":9072026
+  }'
+```
+
+Danach müssen folgende Zustände wiederhergestellt sein:
+
+```bash
+docker ps --format '{{.Names}} {{.Status}}' \
+  --filter name=mike-ai-router \
+  --filter name=mike-ai-qwen3-tts \
+  --filter name=mike-ai-llama
+docker ps -a --filter name=mike-ai-image-worker \
+  --format '{{.Names}} {{.Status}}'
+nvidia-smi
+```
+
+Erwartet werden ein gesunder Router, gesundes Qwen3-TTS, genau ein gesundes
+llama.cpp-Profil und ein mit Exit-Code 0 beendeter Bild-Worker.
+
+## Hermes
+
+Hermes auf Unraid verwendet einen persistenten Benutzer-Provider
+`athena-local`. Seine Konfiguration muss auf denselben Modellnamen zeigen:
+
+```yaml
+image_gen:
+  provider: athena-local
+  model: FLUX.2-klein-9B-fp8-beta
+  max_parallel_requests: 1
+```
+
+Der Provider lebt in Hermes-Appdata und bleibt bei normalen Container-Updates
+erhalten. Er gehört nicht in die Desktop-App und muss auf weiteren Clients
+nicht erneut installiert werden. Die versionierte Quellfassung liegt unter
+[`integrations/hermes-athena-image`](../integrations/hermes-athena-image).
+
+## Rollback
+
+Vor der Beta-Bereitstellung wurden auf Athena diese Rückfall-Images angelegt:
+
+```text
+mike-ai/image-worker:4b-rollback-20260907
+mike-ai/profile-controller:rollback-20260907
+```
+
+Die zugehörige Deployment-Sicherung liegt auf Athena unter:
+
+```text
+/data/deploy-backups/20260907-flux9b-beta
+```
+
+Die vorherige Hermes-Konfiguration und der alte Provider liegen auf Unraid
+unter:
+
+```text
+/mnt/nvme-storage/appdata/Hermes-Agent/backups/flux9b-beta-20260907
+```
+
+Ein Rollback darf nicht blind erfolgen: Zuerst aktives Profil, laufende
+Anfragen und vorhandene Image-Tags prüfen, dann nur Image-Worker,
+Profile Controller und Hermes-Provider auf den gesicherten Stand zurücksetzen.