166 lines
5.8 KiB
Markdown
166 lines
5.8 KiB
Markdown
# 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. Während des exklusiven GPU-Wechsels ist TTS vorübergehend nicht verfügbar.
|
||
|
||
## 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
|
||
}'
|
||
```
|
||
|
||
Ohne `response_format` enthält die Antwort sowohl die abrufbare `url` als
|
||
auch `b64_json`. Das hält URL-basierte Clients kompatibel und unterstützt
|
||
OpenClaw, dessen OpenAI-Bildprovider Inline-Bilddaten erwartet. Mit explizitem
|
||
`response_format: "url"` oder `"b64_json"` liefert der Router weiterhin nur
|
||
das angeforderte Format.
|
||
|
||
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).
|
||
|
||
## OpenClaw
|
||
|
||
OpenClaw verwendet den offiziellen `image_generate`-Provider mit
|
||
`openai/FLUX.2-klein-9B-fp8-beta`. Der OpenAI-kompatible Bildparser von
|
||
OpenClaw sendet kein `response_format`, benötigt in der Antwort aber
|
||
`data[].b64_json`. Deshalb liefert der Router im Standardfall zusätzlich zur
|
||
URL auch die Inline-Bilddaten. Hermes bleibt davon unberührt.
|
||
|
||
## Rollback
|
||
|
||
Die lokalen 4B-Gewichte und die kurzfristigen Rückfall-Images wurden am
|
||
8. September 2026 nach erfolgreicher 9B-Abnahme gezielt entfernt. Ein Rollback
|
||
auf 4B ist deshalb weiterhin reproduzierbar, aber nicht mehr unmittelbar: Das
|
||
4B-Modell muss erneut geladen und die ältere Stack-Fassung neu gebaut werden.
|
||
|
||
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.
|