AI-Profile-Router/docs/ARCHITECTURE.md

Aktuelle Architektur

flowchart LR
    C[Hermes Desktop / Web / Mobil] --> H[Hermes Agent<br/>Unraid]
    H -->|OpenAI API| R[Profile Router<br/>Athena :8081]
    R --> P[Profile Controller]
    P --> Q[genau ein llama.cpp-Profil<br/>Qwen Fast / Medium / Large / Ultra / Uncensored]
    R --> I[FLUX.2 Klein 9B FP8 Beta<br/>RTX 5080 Transformer]
    I --> E[Qwen3-8B NF4 Textencoder<br/>RTX 3060 während Bildauftrag]
    R --> T[Qwen3-TTS RTX 3060<br/>Piper CPU-Fallback]
    R --> STT[Whisper.cpp ggml-small<br/>CPU, lokale Spracherkennung]

    H --> U[MUA / Unraid MCP]
    H --> A[ARR-MCP]
    H --> D[Deemix-MCP]
    H --> N[Navidrome-MCP]
    H --> S[STRATO-MCP]
    H --> X[Nginx-Proxy-Manager-MCP]
    U --> M[Media-Tools<br/>ffmpeg / ffprobe / yt-dlp]

    W[WireGuard-Gateway<br/>Athena] -->|DNS-Proxy| R
    W -->|DNS-Proxy :8099| B[Athena Dashboard<br/>internes Frontend-Netz]
    W -->|DNS-Proxy :9443| PRT[Portainer<br/>internes Frontend-Netz]
    W -->|DNS-Proxy| O[Athena Operator]
    K[Backup alle 5 Stunden] --> DATA[/data und /etc/mike-ai]

Verantwortung

• Unraid hält Hermes, Chats, Skills, Fach-MCPs und deren Appdata.
• Athena rechnet: Text, Bild und Sprache; Router und Dashboard koordinieren und beobachten die Inferenz.
• MUA verwaltet Unraid. Athena Operator bleibt auf den Athena-Host begrenzt.
• Der Router ist die einzige Modelladresse, die Hermes kennen muss.
• Dashboard und Portainer besitzen eigene Netzwerk-Namespaces. Das WireGuard-Gateway löst ihre stabilen Compose-Dienstnamen bei jeder Verbindung neu auf; seine konkrete Container-ID ist damit irrelevant.

Dynamische Qwen-Profile

Der Profile Router hält immer nur ein Qwen-Profil aktiv. Ein Wechsel lädt dasselbe 27B-Modell mit der zum Profil gehörenden GPU-Aufteilung und Kontextgröße:

Profil	Kontextfenster
Fast	76.800 Token
Medium	160.000 Token
Large	192.000 Token
Ultra	262.144 Token
Beta 1	112.000 Token
Uncensored	80.000 Token

Exklusiver Bildmodus

Text- und Bildinferenz teilen sich dieselben GPUs und laufen deshalb nicht gleichzeitig. Der Wechsel ist transaktional:

1. Router merkt sich das aktive Textprofil.
2. Profile Controller stoppt alle llama.cpp-Profile und Qwen3-TTS.
3. Bild-Worker lädt Qwen3-8B als NF4-Textencoder auf die RTX 3060 und den FLUX.2-Klein-9B-FP8-Transformer auf die RTX 5080.
4. Nach dem Prompt-Encoding werden die Embeddings zur RTX 5080 übertragen.
5. Vor dem VAE-Decoding werden Textencoder und Transformer freigegeben.
6. Der Worker wird gestoppt; anschließend starten Qwen3-TTS und das vorherige Textprofil wieder. Piper bleibt als CPU-Fallback verfügbar.

Der Bild-Worker ist lazy und besitzt restart: "no"; im normalen Textbetrieb belegt er daher keinen VRAM. Container werden über eindeutige Docker-Labels gefunden, nicht über zufällige Container-IDs.

Die visuelle Fassung liegt als athena-architecture-map.png neben dieser Datei. Eine zweite Detailkarte, athena-gpu-allocation-map.png, zeigt die profilabhängige Layer-Verteilung auf RTX 5080 und RTX 3060. Die PNG-Karten zeigen noch den Stand vor dem 9B-Bildpfad; die aktuelle textuelle Beschreibung in diesem Dokument ist verbindlich.