185 lines
8.7 KiB
Markdown
185 lines
8.7 KiB
Markdown
# Athena / MikeAI – technische Detailübersicht
|
||
|
||
> Einstieg und verbindlicher Kurzstand: [`../ATHENA.md`](../ATHENA.md). Dieses
|
||
> Dokument enthält zusätzliche technische und historische Details und wird
|
||
> nicht vollständig in einen normalen Modellkontext geladen.
|
||
|
||
Stand: 23. August 2026. Diese Datei erklärt die Plattform in kurzer Form. Für
|
||
operative Änderungen gilt zusätzlich `QWEN_OPERATOR_CONTEXT.md`.
|
||
|
||
## Zweck
|
||
|
||
Athena ist ein selbst betriebener, datenschutzorientierter KI-Host. Er steht
|
||
physisch an einem entfernten Standort ohne KVM und wird ausschließlich remote
|
||
administriert. Open WebUI ist die einfache Benutzeroberfläche; Hermes Agent
|
||
ist der zweite Client für lange agentische Aufgaben. Ein eigener Profile
|
||
Router stellt eine OpenAI-kompatible API bereit und schaltet zwischen mehreren
|
||
reproduzierbaren llama.cpp-Profilen um. Fachwerkzeuge laufen als getrennte MCP-
|
||
Container; Zugangsdaten gelangen weder in llama.cpp noch in Modellprompts.
|
||
|
||
Der zuschaltbare `mike-ai-mcp-platform-context` stellt allen Textprofilen das
|
||
gleiche versionierte Plattformwissen zur Verfügung. Ein begrenzter
|
||
Host-Snapshot ersetzt einen Docker-Socket. Dokumentationsänderungen laufen nur
|
||
über Vorschau, ausdrückliche Freigabe und atomare Sicherung; Git und Recovery
|
||
bleiben getrennte, nachzuweisende Abschlussarbeiten. Details stehen in
|
||
`PLATFORM_CONTEXT_MCP.md`.
|
||
|
||
Das versionierte, secret-freie Diensteverzeichnis
|
||
`config/service-catalog.json` dokumentiert bereits vorhandene externe
|
||
Abhängigkeiten. Vor der Planung eines neuen Backends muss es gelesen und der
|
||
Bestand mit dem dort genannten Fachwerkzeug geprüft werden. Ein nicht
|
||
erreichbares Werkzeug bedeutet „nicht verifiziert“, niemals „nicht vorhanden“.
|
||
|
||
## Hardware
|
||
|
||
- Debian 13 `trixie`, Kernel 6.12
|
||
- AMD Ryzen 5 5600, 6 Kerne / 12 Threads
|
||
- 48 GiB DDR4-RAM
|
||
- RTX 5080 mit 16 GiB VRAM
|
||
- RTX 3060 mit 12 GiB VRAM
|
||
- System-SSD und getrennte `/data`-SSD, jeweils ungefähr 1 TB
|
||
- keine RX 470 mehr im System
|
||
|
||
GPU-Indizes auf dem Host sind nicht stabil genug für Konfigurationen. Wo eine
|
||
eindeutige Karte benötigt wird, werden GPU-UUIDs verwendet. Innerhalb eines
|
||
Containers kann `CUDA0` aufgrund von `NVIDIA_VISIBLE_DEVICES` eine andere Karte
|
||
bezeichnen als Index 0 von `nvidia-smi` auf dem Host.
|
||
|
||
## Hauptfluss
|
||
|
||
```text
|
||
Browser / OpenWebUI / Hermes Agent
|
||
|
|
||
| WireGuard, ausschließlich VPN
|
||
v
|
||
Open WebUI ---> Profile Router ---> Profile Controller ---> genau ein llama.cpp-Profil
|
||
| |
|
||
| +-- Vision direkt über Qwen + mmproj
|
||
| +-- FLUX-Hotswap für Bildgenerierung
|
||
| +-- Whisper für Speech-to-Text
|
||
| +-- TTS-Gateway -> XTTS-v2 -> Piper-Fallback
|
||
|
|
||
+-- internes MCP-Netz
|
||
+-- Athena Plattformwissen
|
||
+-- Web
|
||
+-- GitHub Repository read-only
|
||
+-- Home Assistant
|
||
+-- Sonarr/Radarr
|
||
+-- Navidrome
|
||
+-- Unraid
|
||
```
|
||
|
||
Hermes hängt parallel zu OpenWebUI direkt am Router und an denselben
|
||
MCP-Containern. Es betreibt kein zweites Qwen und verändert die Profilmatrix
|
||
nicht. Dashboard und Agent-API sind nur über WireGuard erreichbar; dauerhafte
|
||
Hermes-Daten liegen unter `/data/hermes` und sind Bestandteil des
|
||
verschlüsselten Recovery-Bundles.
|
||
|
||
Deemix läuft bereits als Container auf dem Unraid-HomeServer. Eine künftige
|
||
Deemix-MCP-Integration auf Athena verwendet dieses Backend über WireGuard und
|
||
erzeugt nicht ungefragt eine zweite Deemix-Instanz.
|
||
|
||
Automatische Unraid-Abfragen verwenden einen eigenen MUA-Read-only-Zugang, der
|
||
in Open WebUI ausschließlich Diagnosewerkzeuge sichtbar macht. Der vollständige
|
||
MUA-Verwaltungszugang bleibt davon getrennt und muss bewusst gewählt werden.
|
||
Beide Verbindungen sprechen denselben MCP-Endpunkt des MUA-Plugins auf dem
|
||
HomeServer an. Athena betreibt keinen zusätzlichen Unraid-GraphQL-MCP; die
|
||
GraphQL-API von Unraid darf deaktiviert bleiben.
|
||
|
||
Open WebUI und Router veröffentlichen keinen normalen Host-Port. Der
|
||
WireGuard-Gateway-Container stellt nur die vorgesehenen VPN-Endpunkte bereit.
|
||
Anwendungscontainer erreichen Heimnetz und Internet fail-closed über WireGuard;
|
||
ein Tunneldefekt darf nicht auf das Universitätsgateway zurückfallen. SSH auf
|
||
dem Debian-Host ist davon getrennt.
|
||
|
||
## Inferenzprofile
|
||
|
||
| Profil | Kontext | Modell/Verteilung | Zweck |
|
||
|---|---:|---|---|
|
||
| Fast | 76.800 | IQ4-MIX, Text auf RTX 5080 | schnell; Visionprojektor auf RTX 3060 |
|
||
| Medium | 160.000 | IQ4_XS Pure, 90:10 | Standardprofil; Vision; MTP3 |
|
||
| Large | 192.000 | IQ4_XS Pure, 86:14 | große Agentensitzungen; Vision |
|
||
| Ultra | 262.144 | IQ4_XS Pure, 80:20 | maximaler Textkontext, keine Vision |
|
||
| Uncensored | 80.000 | Abliterated Q4_K_M, 90:10 | weniger Verweigerungen; Rechte unverändert |
|
||
| Experimental | variabel | isoliert | Tests, niemals automatisch Produktion |
|
||
|
||
Es darf immer nur ein Textprofil aktiv sein. Medium ist der verbindliche
|
||
Standard. Ein „unkonditionierteres“ Modell hebt niemals Werkzeugrechte,
|
||
Bestätigungspflichten oder Netzwerkgrenzen auf.
|
||
|
||
## MCP-Prinzip
|
||
|
||
Ein Container entspricht einem Fachbereich und einer Vertrauensgrenze. Breite
|
||
Grundfähigkeiten werden jedoch nicht künstlich in Site-spezifische Werkzeuge
|
||
zerlegt: allgemeines Web ist immer verfügbar und der zentrale Athena Operator
|
||
besitzt ein begrenztes Terminal für neue Aufgaben. Fach-MCPs bleiben für kurze,
|
||
strukturierte API-Ergebnisse der bevorzugte Weg.
|
||
|
||
Der offizielle GitHub-MCP bietet nur drei Werkzeuge:
|
||
|
||
- Repository suchen
|
||
- Dateiinhalt lesen
|
||
- Code suchen
|
||
|
||
Rekursive Komplettbäume sind absichtlich ausgeschlossen, weil sie bei großen
|
||
Repositories den gesamten Modellkontext verdrängen können.
|
||
|
||
Andere GitHub-Werkzeuge sowie Schreibzugriffe sind serverseitig deaktiviert.
|
||
|
||
Für Entwicklung und Betrieb der KI-Plattform existiert ein zentraler Athena
|
||
Operator MCP. Eine unprivilegierte MCP-Fassade spricht ausschließlich über
|
||
einen Unix-Socket mit einem rootseitigen Executor. Dadurch kann Qwen MCPs,
|
||
Docker-Dienste, Modelle, Profile, OpenWebUI, Tests, Git und Recovery selbst
|
||
pflegen. Strukturierte Mutationen behalten Vorschau und Ticket; ein breites
|
||
Terminal deckt unvorhergesehene Arbeiten ab. Nur Strombefehle und Änderungen an
|
||
Athenas SSH, LAN, WireGuard, Firewall, Boot, Kernel, Mounts und Partitionen
|
||
bleiben zum Schutz der entfernten Erreichbarkeit blockiert.
|
||
|
||
## Verbindliche Quellen
|
||
|
||
1. aktuell mit einem zuständigen Werkzeug gemessener Laufzeitzustand
|
||
2. `CURRENT_REFERENCE.md` und `STANDARD_PROFILE_MATRIX.md`
|
||
3. Compose-, Installer- und Konfigurationsdateien im Repository
|
||
4. Architektur-, Sicherheits- und Betriebsdokumentation
|
||
5. frühere Chatangaben nur als Hinweis, niemals als aktueller Nachweis
|
||
|
||
Widersprechen Laufzeit und Dokumentation einander, wird nichts vorschnell
|
||
geändert. Die Abweichung wird benannt und zuerst geklärt.
|
||
|
||
## Unverhandelbare Sicherheitsregeln
|
||
|
||
- Keine Secrets, Tokens, privaten Schlüssel, Chats oder Promptinhalte auslesen
|
||
oder ausgeben, sofern das nicht ausdrücklich und eng begrenzt verlangt wurde.
|
||
- Kein Shutdown, Reboot, Netzwerk-, SSH-, Firewall-, WireGuard-, Kernel- oder
|
||
Bootloader-Eingriff ohne ausdrückliche Freigabe und belastbaren Rückweg.
|
||
- Keine Änderung direkt im Livecontainer als dauerhafte Lösung.
|
||
- Zuerst Bestand prüfen, dann versionierte Quelle ändern, testen, deployen,
|
||
verifizieren, dokumentieren und sichern.
|
||
- Bestehende fremde Änderungen und Dirty Worktrees erhalten.
|
||
- Niemals behaupten, etwas geprüft oder ausgeführt zu haben, wenn kein
|
||
zuständiges Werkzeug erfolgreich war.
|
||
|
||
## Wichtige Pfade
|
||
|
||
```text
|
||
/opt/mike-ai/stack einziger Git-Working-Tree und laufender Stack
|
||
/data/models produktive Modelle; für Inferenz read-only eingehängt
|
||
/etc/mike-ai root-only Secrets und Standortkonfiguration
|
||
/data persistente Daten- und Recovery-SSD
|
||
/var/lib/docker/volumes Docker-Volumes, darunter OpenWebUI-Daten
|
||
```
|
||
|
||
Kleine Quelländerungen erfolgen direkt über `athena_operator_change` mit
|
||
`patch_update`. Ein normaler MCP-Release kann mit `mcp_release` Tests, Deploy,
|
||
Client-Sync, Git-Publish und Recovery zusammenfassen.
|
||
|
||
Seit Operator 2.3 übernimmt `mcp_release.imports` bereits geprüfte UTF-8-Dateien
|
||
aus freigegebenen Staging-Verzeichnissen anhand ihrer SHA-256-Prüfsumme. Das
|
||
Modell muss lange vorbereitete MCP-Quellen weder erneut lesen noch im Chat
|
||
rekonstruieren. `hermes_sync: true` verteilt eine geänderte verwaltete
|
||
Hermes-Konfiguration ohne Containerneustart. Ein interner MCP benötigt keinen
|
||
neuen VPN-Port: Hermes und OpenWebUI erreichen ihn per Docker-DNS im Toolnetz.
|
||
|
||
Secrets unter `/etc/mike-ai` werden ausschließlich verschlüsselt gesichert und
|
||
gehören nie in Git, ein Wissensdokument oder einen Modellkontext.
|