257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
# Athena: verbindlicher Kontext für KI-Agenten
|
|
|
|
Stand: 10. September 2026, nach Integration von TRELLIS.2 als 3D-Studio.
|
|
|
|
Diese Datei ist die erste Lektüre für jede KI, die Athena prüfen oder ändern
|
|
soll. Sie beschreibt den realen Aufbau, die Zuständigkeiten und die Regeln für
|
|
sichere Erweiterungen. Bei Abweichungen zwischen Annahmen und Live-System gilt:
|
|
erst lesend prüfen, dann die Dokumentation und den Code gemeinsam korrigieren.
|
|
|
|
## Unverhandelbare Sicherheitsregeln
|
|
|
|
1. **Athena niemals herunterfahren oder neu starten.** Der Rechner steht in
|
|
einer anderen Stadt und ist nicht kurzfristig physisch erreichbar.
|
|
2. Ohne ausdrücklichen aktuellen Auftrag weder Kernel, Bootloader, BIOS,
|
|
Partitionen, Mounts, SSH, LAN, WireGuard noch Firewall verändern.
|
|
3. Secrets dürfen lokal benutzt, aber niemals ausgegeben, geloggt oder in Git
|
|
aufgenommen werden. Das betrifft besonders `/etc/mike-ai`.
|
|
4. Keine laufende Modellarbeit abbrechen. Vor Änderungen Betriebsmodus,
|
|
Containerzustand und GPU-Prozesse prüfen.
|
|
5. Keine pauschalen Docker-Bereinigungen ausführen. Ein gestoppter Worker ist
|
|
meistens gewollt und kein Müll.
|
|
6. Keine Container anhand zufälliger IDs verdrahten. Stabile Dienstnamen,
|
|
Compose-Netze und eindeutige `com.mike-ai.*`-Labels verwenden.
|
|
7. Änderungen klein und reversibel halten. Nie den gesamten Stack neu erstellen,
|
|
wenn ein einzelner Dienst aktualisiert werden kann.
|
|
|
|
## Physischer und logischer Aufbau
|
|
|
|
```text
|
|
Athena: ASUS PRIME B550-PLUS
|
|
├── Debian 13 (trixie), Kernel 6.12
|
|
├── AMD Ryzen 5 5600, 6 Kerne / 12 Threads
|
|
├── 46 GiB nutzbarer RAM + 47 GiB Swap
|
|
├── System: Samsung 980 PRO 1 TB, ext4 auf /
|
|
├── Daten: WD Blue SN580 1 TB, ext4 auf /data
|
|
├── GPU 0: RTX 3060, 12.288 MiB
|
|
├── GPU 1: RTX 5080, 16.303 MiB
|
|
└── Docker
|
|
├── Kernprojekt /opt/mike-ai/stack
|
|
│ ├── Router, Profile Controller und Dashboard
|
|
│ ├── fünf llama.cpp-Profile
|
|
│ ├── Bild, Qwen3-TTS, TTS-Gateway und Whisper
|
|
│ ├── WireGuard-Gateway, Portainer, Backup
|
|
│ └── Athena-Operator
|
|
├── /opt/mike-ai/acestep-test Musik
|
|
├── /opt/mike-ai/stem-separator Audio-Trennung
|
|
├── /opt/mike-ai/omnivoice-studio Voice Studio
|
|
├── /opt/mike-ai/xvc-studio Voice Changer
|
|
├── /opt/mike-ai/stack/experiments/applio-rvc
|
|
│ Applio/RVC
|
|
├── /opt/mike-ai/Mikes-Applio-UI geführte Applio-UI
|
|
└── /opt/mike-ai/trellis-studio 3D Studio
|
|
```
|
|
|
|
Die beiden GPUs bilden **keinen gemeinsamen VRAM-Pool**. Ein Backend muss
|
|
Mehrkartenbetrieb ausdrücklich unterstützen. Die Nummern oben sind Hostnummern;
|
|
wenn ein Container nur `NVIDIA_VISIBLE_DEVICES=1` erhält, sieht er die RTX 5080
|
|
innerhalb des Containers üblicherweise als GPU 0.
|
|
|
|
## Rollen der dauerhaften Kerndienste
|
|
|
|
| Dienst | Rolle |
|
|
|---|---|
|
|
| `mike-ai-router` | Einzige OpenAI-kompatible Modelladresse; besitzt die Zustandsmaschine für Profile und Betriebsmodi. |
|
|
| `mike-ai-profile-controller` | Darf ausschließlich freigegebene, eindeutig markierte Worker starten und stoppen. |
|
|
| `mike-ai-llama-dashboard` | Telemetrie, Modusumschaltung und Download der portablen Backups. |
|
|
| `mike-ai-wireguard-gateway` | Veröffentlicht interne Dienste an der privaten Adresse `192.168.1.212`; keine öffentliche/LAN-Bindung. |
|
|
| `mike-ai-tts-gateway` | Stabile TTS-API, Textnormalisierung, Formatumwandlung und PCM-Streaming; enthält kein Ersatzmodell. |
|
|
| `mike-ai-whisper` | Dauerhafte CPU-Spracherkennung mit Whisper.cpp `ggml-small`. |
|
|
| `mike-ai-mcp-athena-operator` | Begrenzte Verwaltungsfunktionen für Agenten; kein allgemeiner Root-Ersatz. |
|
|
| `mike-ai-backup` | Lokales Schnellbackup; externe Disaster-Sicherung läuft zusätzlich über systemd-Timer. |
|
|
|
|
## LLM-Profile
|
|
|
|
Es läuft höchstens ein llama.cpp-Profil. Die Standardprofile nutzen
|
|
Qwen3.8-27B in Q4-Quantisierung.
|
|
|
|
| Profil | API-Name | Kontext | Vision |
|
|
|---|---|---:|---|
|
|
| Fast | `qwen-fast` | 76.800 | ja |
|
|
| Medium | `qwen-medium` | 160.000 | ja |
|
|
| Large | `qwen-large` | 192.000 | ja |
|
|
| Ultra | `qwen-ultra` | 262.144 | nein |
|
|
| Uncensored | `qwen-uncensored` | 80.000 | ja, eigener Projektor |
|
|
|
|
Die verbindlichen Parameter stehen in `config/profile-matrix.json`,
|
|
`router/router_profiles.json`, `platform/profiles/` und
|
|
`docs/STANDARD_PROFILE_MATRIX.md`. Diese Quellen dürfen sich nicht
|
|
widersprechen.
|
|
|
|
## Exklusive Betriebsmodi
|
|
|
|
Große GPU-Worker sind gegenseitig exklusiv. Der Router speichert
|
|
`mode`, `last_profile` und `return_profile` persistent. Beim Wechsel in einen
|
|
Spezialmodus werden LLM, Bildworker und Qwen3-TTS soweit nötig gestoppt; beim
|
|
Wechsel zu `llm` wird das zuvor gemerkte Profil wiederhergestellt.
|
|
|
|
| Modus | Worker / Modell | GPU-Nutzung | Oberfläche |
|
|
|---|---|---|---|
|
|
| `llm` | ein Qwen-Profil + Qwen3-TTS | profilabhängig beide GPUs; TTS RTX 3060 | Router `:8081` |
|
|
| Bildauftrag | FLUX.2 Klein 9B FP8 + Qwen3-8B NF4 | RTX 5080 + RTX 3060, transaktional | über Router |
|
|
| `music` | ACE-Step 1.5 XL-SFT | RTX 5080 | `:7862` original, `:7861` Community |
|
|
| `separation` | BS-RoFormer, Demucs, MossFormer2 | RTX 5080 | `:8007` |
|
|
| `voice` | OmniVoice | RTX 5080 | `:8008` |
|
|
| `voicechange` | X-VC + optional Resemble Enhance | RTX 5080 | `:8009` |
|
|
| `applio` | Applio/RVC | RTX 5080 | `:8011`, eigene UI `:8012` |
|
|
| `trellis` | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | ausschließlich RTX 5080 | `:8013` |
|
|
|
|
TRELLIS liegt unter `/opt/mike-ai/trellis-studio`. Seine Q8-Gewichte liegen
|
|
unter `/data/models/trellis2-q8`, die Runtime und Ausgaben unter
|
|
`/data/trellis-studio`. Die Oberfläche liefert GLB. `1024 · cascade` ist der
|
|
Qualitätsstandard für die 16-GiB-RTX-5080; 1536 kann den VRAM überschreiten.
|
|
Ein 512er Ende-zu-Ende-Test erzeugte am 10.09.2026 in 54,2 Sekunden ein
|
|
gültiges 4,4-MB-GLB.
|
|
|
|
## Steuerbefehle und Status
|
|
|
|
Im Dashboard wird über die Modus-API geschaltet. Hermes kann dieselbe
|
|
Zustandsmaschine mit exakten Befehlen bedienen:
|
|
|
|
```text
|
|
/athena music
|
|
/athena stems
|
|
/athena voice
|
|
/athena voicechange
|
|
/athena applio
|
|
/athena 3d
|
|
/athena trellis
|
|
/athena llm
|
|
/athena status
|
|
```
|
|
|
|
Ein Moduswechsel ist asynchron. Eine angenommene Anfrage bedeutet noch nicht,
|
|
dass der Worker bereit ist. Immer warten, bis `GET /status` beziehungsweise das
|
|
Dashboard `phase: ready`, den richtigen `active`-Modus und einen gesunden
|
|
Worker meldet. Bei Fehlern nicht blind erneut starten, sondern `last_error`,
|
|
Containerstatus und Logs lesen.
|
|
|
|
## Netzwerkmodell
|
|
|
|
Anwendungscontainer veröffentlichen ihre Host-Ports nur auf `127.0.0.1` oder
|
|
gar nicht. Das WireGuard-Gateway sitzt im externen Docker-Netz
|
|
`mike-ai_frontend`, bindet die private WireGuard-Adresse `192.168.1.212` und
|
|
leitet mit `socat` auf Compose-Dienstnamen weiter.
|
|
|
|
Wichtige Regeln:
|
|
|
|
- Gateway und Anwendung **nicht** über `network_mode: container:...` koppeln.
|
|
- Ziel ist zum Beispiel `trellis-studio:8080`, niemals eine Container-IP.
|
|
- Der Zielcontainer muss im selben externen Frontend-Netz liegen.
|
|
- Beim Hinzufügen eines Ports den Proxy-Eintrag im Gateway, das Dashboard und
|
|
die Endpunkt-Dokumentation gemeinsam ergänzen.
|
|
- Ein Gateway-Recreate kann eine bestehende SSH-Verbindung unterbrechen. Nur
|
|
kontrolliert und mit automatisch verzögertem Wiederanlauf durchführen.
|
|
- Nach einem Recreate DNS-Auflösung, Listener, Ziel-Healthcheck und Zugriff
|
|
über den WireGuard-Pfad prüfen.
|
|
|
|
## Daten und Sicherung
|
|
|
|
| Pfad | Inhalt |
|
|
|---|---|
|
|
| `/opt/mike-ai` | Deployments, Compose-Projekte und lokale Quellstände |
|
|
| `/etc/mike-ai` | Konfiguration, Schlüssel und Tokens; geheim |
|
|
| `/data/models` | erneut ladbare Modellgewichte und Caches |
|
|
| `/data/voice` | Trainingsdaten, Checkpoints und trainierte Stimmen |
|
|
| `/data/music` | Musikprojekte und Ausgaben |
|
|
| `/data/audio` | Audio-Trennungen |
|
|
| `/data/trellis-studio` | trellis.cpp-Runtime und 3D-Ausgaben |
|
|
| `/data/llama-dashboard` | Telemetriehistorie |
|
|
| `/data/docker-backups` | lokale Schnellbackups |
|
|
|
|
Docker-Volumes: `mike-ai_router-state`, `mike-ai_router-images`,
|
|
`mike-ai_whisper-data`, `portainer_data`.
|
|
|
|
Das lokale Exportbackup läuft etwa alle fünf Stunden, das verschlüsselte
|
|
Disaster-Backup nachts. Ein Backup auf `/data` schützt nicht vor dem Ausfall
|
|
der Datenplatte. Details und alle drei Ausfallszenarien stehen in
|
|
`docs/RECOVERY.md`. **Aktuelle Lücke:** `/data/trellis-studio/output` ist im
|
|
ausgerollten Export- und Disaster-Backup noch nicht enthalten. Wichtige GLB-
|
|
Ausgaben daher zusätzlich extern sichern, bis die Backup-Skripte erweitert und
|
|
getestet wurden.
|
|
|
|
## Neuen GPU-Dienst korrekt hinzufügen
|
|
|
|
1. `docs/TESTED_MODELS.md` vollständig prüfen, damit kein verworfener Kandidat
|
|
erneut geladen wird.
|
|
2. Lizenz, Modellrevision, Runtime-Revision, VRAM, RAM, Ausgabeformat und
|
|
Hardwareunterstützung dokumentieren.
|
|
3. Eigenes Compose-Projekt oder klar abgegrenzten Kernservice anlegen. Image
|
|
und Upstream-Commit pinnen; nicht dauerhaft `latest` als einzige
|
|
Wiederherstellungsinformation verwenden.
|
|
4. Gewichte unter einem eindeutigen Verzeichnis in `/data/models` speichern,
|
|
veränderliche Ergebnisse separat unter `/data`.
|
|
5. `restart: "no"` für exklusive GPU-Worker verwenden. Dauerhafte UIs dürfen
|
|
laufen, dürfen aber im Leerlauf kein großes Modell laden.
|
|
6. Genau ein eindeutiges Label vergeben, zum Beispiel
|
|
`com.mike-ai.trellis-worker=trellis2-q8`. Der Controller muss bei null oder
|
|
mehreren Treffern absichtlich abbrechen.
|
|
7. Worker in **Controller, Router, Dashboard, Compose-Umgebung,
|
|
WireGuard-Proxy, Tests und Dokumentation** ergänzen.
|
|
8. Alle anderen exklusiven Worker sowohl beim Eintritt als auch beim Verlassen
|
|
des neuen Modus behandeln. Den Rückweg zum gespeicherten LLM-Profil testen.
|
|
9. Healthcheck-Werkzeuge tatsächlich im Image installieren. Ein Backendprozess
|
|
kann laufen, während ein fehlerhafter Healthcheck den Modus blockiert.
|
|
10. Bei Web-UIs korrekte MIME-Typen ausliefern. ES-Module benötigen
|
|
`application/javascript`, CSS `text/css`; Browsermodus muss denselben
|
|
Ursprung oder eine sauber konfigurierte API-Adresse verwenden.
|
|
11. Compose validieren, Syntax prüfen, nur den betroffenen Dienst bauen und
|
|
einen echten Ende-zu-Ende-Auftrag ausführen. Danach Rückschaltung testen.
|
|
12. Quellcode, Installer, Wiederaufbau und Dokumentation im selben Git-Stand
|
|
versionieren. Erst dann ist die Erweiterung wiederherstellbar.
|
|
|
|
## Dienst vollständig entfernen
|
|
|
|
1. Belegen, dass der Dienst nicht aktiv ist und keine laufende Arbeit besitzt.
|
|
2. Testergebnis und Ablehnungsgrund zuerst in `docs/TESTED_MODELS.md` sichern.
|
|
3. Routerbefehle, Zustandsfelder, Controller-Labelsuche, Dashboard-Schalter,
|
|
Proxy-Port, Compose-Projekt, Tests und Dokumentation entfernen.
|
|
4. Container und Image gezielt anhand exakter Namen entfernen.
|
|
5. Gewichte, Cache, Ausgaben und Volumes einzeln klassifizieren: reproduzierbar,
|
|
ersetzbar oder unersetzlich. Unersetzliche Daten sichern; keine Globs oder
|
|
pauschalen Prune-Befehle benutzen.
|
|
6. Prüfen, dass kein Labelduplikat, verwaister Proxy, unbenutztes Netz oder
|
|
verwaistes Volume übrig ist.
|
|
7. LLM-Modus wiederherstellen und einen Smoke-Test ausführen.
|
|
|
|
## Häufige Fehlerbilder
|
|
|
|
- **Controller meldet zwei Worker:** Während `docker compose up
|
|
--force-recreate` können alter und neuer Container kurz dasselbe Label
|
|
tragen. Recreate beenden lassen, danach exakt gelabelte Container prüfen und
|
|
erst dann den Modus erneut anfordern.
|
|
- **Webseite ist unformatiert und bleibt auf „connecting“:** MIME-Typen oder
|
|
Asset-Cache prüfen; nicht automatisch das KI-Backend beschuldigen.
|
|
- **Dashboard oder Port fehlt nach Recreate:** Listener im Gateway,
|
|
DNS-Auflösung des Dienstnamens und gemeinsames Frontend-Netz prüfen.
|
|
- **Worker gesund, Modus trotzdem fehlerhaft:** Routerzustand und
|
|
`last_error` können noch den vorherigen fehlgeschlagenen Übergang zeigen;
|
|
nach Beseitigung der Ursache Modus kontrolliert erneut anfordern.
|
|
- **VRAM scheinbar leer:** Manche Runtime lädt Gewichte erst beim ersten
|
|
Auftrag und gibt Speicher anschließend wieder frei. Ein Healthcheck allein
|
|
ist daher kein vollständiger GPU-Test.
|
|
- **Compose verwendet falsche Werte:** Der Kernstack benötigt
|
|
`--env-file /etc/mike-ai/stack.env`.
|
|
|
|
## Definition von „fertig“
|
|
|
|
Eine Änderung ist erst fertig, wenn sie im kanonischen Git-Stand liegt,
|
|
reproduzierbar gebaut werden kann, Compose/Syntax valide sind, der Dienst gesund
|
|
ist, ein echter kleiner Funktionsauftrag erfolgreich war, die Rückschaltung
|
|
funktioniert, Backup und WireGuard-Zugriff gesund geblieben sind und Commit
|
|
sowie Push erfolgt sind.
|
|
|
|
Weiterführend: `ATHENA.md`, `docs/ARCHITECTURE.md`,
|
|
`docs/OPERATING_MODES.md`, `docs/CONTAINER_INVENTORY.md`,
|
|
`docs/TESTED_MODELS.md` und `docs/RECOVERY.md`.
|