# 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

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.