michael/AI-Profile-Router
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/cache24-sync
AI-Profile-Router/for_ki.md
T

13 KiB
Raw Permalink Blame History

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

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
yue2 YuE2-3B + Ladypoly YuE2_WebUI RTX 5080 :8014
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

YuE2 liegt unter /opt/mike-ai/yue2-3b, seine Gewichte unter /data/models/yue2 und Ergebnisse unter /data/music/yue2. Der Container trägt com.mike-ai.music-worker=yue2 und muss mit dem Alias yue2-studio am externen Netz mike-ai_frontend hängen. YuE2 niemals außerhalb der Router-Zustandsmaschine dauerhaft starten: Sonst bleibt sein VRAM belegt und der nächste LLM- oder Separator-Start kann mit OOM scheitern.

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:

/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.

Reference in New Issue View Git Blame Copy Permalink