From 43321b67974f9987c9b03f040f890769b4e67207 Mon Sep 17 00:00:00 2001 From: Mikei386 <44135113+Mikei386@users.noreply.github.com> Date: Thu, 10 Sep 2026 18:31:44 +0200 Subject: [PATCH] Document Athena 3D mode and agent operations --- ATHENA.md | 9 ++ Erklärung.txt | 15 +- README.md | 9 +- docs/ARCHITECTURE.md | 21 ++- docs/CONTAINER_INVENTORY.md | 1 + docs/CURRENT_RUNTIME_NOTES.md | 11 +- docs/OPERATING_MODES.md | 20 ++- docs/RECOVERY.md | 10 ++ docs/SPECIALIZED_MODEL_ROADMAP.md | 3 +- docs/TESTED_MODELS.md | 8 +- for_ki.md | 256 ++++++++++++++++++++++++++++++ 11 files changed, 353 insertions(+), 10 deletions(-) create mode 100644 for_ki.md diff --git a/ATHENA.md b/ATHENA.md index c7a802f..35fb7a0 100644 --- a/ATHENA.md +++ b/ATHENA.md @@ -13,6 +13,7 @@ Sie betreibt: - FLUX.2 Klein 9B FP8 Beta für Textbilder und Referenzbild-Bearbeitung, - Qwen3-TTS für Sprache, - ACE-Step 1.5 XL-SFT als exklusiven Musikstudio-Modus, +- TRELLIS.2 4B Q8 als exklusives Bild-zu-3D-Studio, - das Athena-Dashboard, - Portainer CE als optionale Ansicht auf die laufenden Docker-Container, - WireGuard-Gateway und Datenbackup, @@ -29,6 +30,7 @@ werden keine zweiten Instanzen dieser Dienste angelegt. | `/data/models` | Modellgewichte | | `/data/llama-dashboard` | historische Dashboard-Messwerte | | `/data/docker-backups` | automatische Athena-Backups | +| `/data/trellis-studio` | trellis.cpp-Runtime und erzeugte 3D-Modelle | | `/etc/mike-ai` | lokale Konfiguration und Secrets, niemals Git | Portainer läuft als separater, optionaler Verwaltungscontainer @@ -72,6 +74,10 @@ Qwen-Profil wird vom Profile Controller verwaltet. - ACE-Step 1.5 XL-SFT: exklusiver Musikmodus auf der RTX 5080. Dashboard und die Routerbefehle `/athena music`, `/athena llm`, `/athena status` bedienen dieselbe persistente Zustandsmaschine; siehe `docs/OPERATING_MODES.md`. +- TRELLIS.2 4B Q8: exklusives Bild-zu-3D-Profil auf der RTX 5080. Die + browserbasierte Oberfläche läuft unter `http://192.168.1.212:8013`, erzeugt + GLB und verwendet standardmäßig `1024 · cascade`. Der 1536er Pfad kann die + 16 GiB VRAM überschreiten. Die verbindlichen Werte stehen in `config/profile-matrix.json` und `docs/STANDARD_PROFILE_MATRIX.md`. @@ -100,6 +106,9 @@ Bootloader, Partitionen, Mounts, SSH, LAN, WireGuard oder Firewall ändern. Secrets dürfen lokal verwendet, aber nie in Git, Logs oder Chatantworten veröffentlicht werden. +Vor Änderungen durch einen Agenten ist [for_ki.md](for_ki.md) vollständig zu +lesen. Dort stehen insbesondere Modus-, Label-, Netzwerk- und Aufräumregeln. + ## Fertig bedeutet - Änderung ist im kanonischen Git-Checkout, diff --git a/Erklärung.txt b/Erklärung.txt index 24c13d0..a842a26 100644 --- a/Erklärung.txt +++ b/Erklärung.txt @@ -1,7 +1,8 @@ ATHENA – AUFBAU VON UNTEN NACH OBEN ==================================== -Stand: 10.09.2026 nach Entfernung von Beta 1 und Piper. +Stand: 10.09.2026 nach Entfernung von Beta 1 und Piper sowie Integration von +TRELLIS.2 als 3D-Studio. Athena besitzt derzeit 23 Container, fünf auswählbare LLM-Profile und vier verwendete Docker-Volumes. Verwaiste Docker-Volumes gibt es nicht. @@ -95,6 +96,9 @@ Betriebsmodus gestartet. Zum Zeitpunkt der Aufnahme war Applio/RVC aktiv. | mike-ai-stem-separator | gestoppt/bereit | Trennt Gesang, Begleitung und Instrumente | | | | mit BS-RoFormer und Demucs. | +-----------------------------------+-------------------+----------------------------------------------+ +| mike-ai-trellis-studio | läuft/bedarfsgest.| TRELLIS.2 4B Q8 erzeugt aus einem Bild ein | +| | | texturiertes GLB-Modell auf der RTX 5080. | ++-----------------------------------+-------------------+----------------------------------------------+ | mike-ai-voice-studio | gestoppt/bereit | Voice Studio für Text-zu-Stimme und | | | | referenzbasierte Stimmerzeugung. | +-----------------------------------+-------------------+----------------------------------------------+ @@ -133,6 +137,7 @@ aber gemeinsam als Athena-Docker-Stack betrachtet: - Spurentrennung: /opt/mike-ai/stem-separator - Voice Studio: /opt/mike-ai/omnivoice-studio - X-VC: /opt/mike-ai/xvc-studio +- 3D Studio: /opt/mike-ai/trellis-studio LLM-PROFILE @@ -188,11 +193,18 @@ benötigten Modelle. +---------------+------------------------------------------------------------+ | Applio / RVC | RVC-Inferenz, Modellverwaltung und Stimmtraining. | +---------------+------------------------------------------------------------+ +| 3D Studio | TRELLIS.2 4B Q8 über trellis.cpp auf der RTX 5080. | ++---------------+------------------------------------------------------------+ Qwen3-TTS läuft nur im LLM-Modus. In einem exklusiven Spezialmodus bleibt das leichte TTS-Gateway als API-Dienst gesund, meldet aber "ready: false", weil das eigentliche Qwen3-TTS-Modell absichtlich entladen ist. +Das 3D-Studio ist im privaten WireGuard-Netz unter +http://192.168.1.212:8013 erreichbar. Es erzeugt GLB-Dateien; empfohlen ist +1024 · cascade. Runtime und Ausgaben liegen unter /data/trellis-studio, die +Q8-Gewichte unter /data/models/trellis2-q8. + TTS-AUFBAU =========== @@ -252,6 +264,7 @@ Die wichtigsten davon sind: - /data/voice/applio Applio-Datensätze, Logs und Stimmenmodelle - /data/music Musikprojekte und generierte Titel - /data/audio/separation Ergebnisse der Audio- und Spurentrennung +- /data/trellis-studio trellis.cpp-Runtime und erzeugte GLB-Dateien - /data/llama-dashboard Verlauf und Zustandsdaten des Dashboards - /etc/mike-ai betriebliche Konfiguration und Geheimnisse - /data/docker-backups erzeugte Sicherungsarchive diff --git a/README.md b/README.md index a5768ff..5fda660 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,9 @@ Bild- und Sprachausgabe. **Hermes und die Fach-MCPs laufen auf Unraid.** - Whisper.cpp `ggml-small` auf der CPU für lokale deutsche Spracherkennung - Live-Dashboard mit 21 Tagen Detailhistorie auf Port 8099 - Dashboard-Umschaltung zwischen LLM-Betrieb, ACE-Step-Musikstudio, - BS-RoFormer-Stimmtrennung, OmniVoice, X-VC und Applio/RVC + BS-RoFormer-Stimmtrennung, OmniVoice, X-VC, Applio/RVC und TRELLIS.2 +- TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 für lokale Bild-zu-3D-Erzeugung + auf der RTX 5080 - Portainer CE als optionale Container-Ansicht auf Port 9443 - WireGuard-Gateway, Datenbackup und Athena-Operator - keine produktive Hermes-, OpenWebUI- oder portable Fach-MCP-Instanz @@ -129,10 +131,12 @@ Details, Installation, Prüfung und Rollback stehen in - Voice Changer (X-VC, Audio zu Audio; native 16 kHz plus optional restaurierte 44,1 kHz): `http://192.168.1.212:8009` - Applio (RVC-Inferenz, Modelle und Training): `http://192.168.1.212:8011` - Mikes Applio UI (geführte RVC-Oberfläche): `http://192.168.1.212:8012` +- 3D Studio (TRELLIS.2 Q8, GLB-Ausgabe): `http://192.168.1.212:8013` Der Betriebsmodus lässt sich dort direkt umschalten. In Hermes funktionieren außerdem `/athena music`, `/athena stems`, `/athena voice`, -`/athena voicechange`, `/athena applio`, `/athena llm` und `/athena status`; Details stehen in +`/athena voicechange`, `/athena applio`, `/athena 3d`, `/athena llm` und +`/athena status`; Details stehen in [docs/OPERATING_MODES.md](docs/OPERATING_MODES.md). Der Router stellt Sprache OpenAI-kompatibel bereit: Sprachausgabe über @@ -189,6 +193,7 @@ Szenarien stehen in [docs/RECOVERY.md](docs/RECOVERY.md). ## Verbindliche Dokumentation - [ATHENA.md](ATHENA.md) – kurze Betriebsanleitung +- [for_ki.md](for_ki.md) – verbindlicher System- und Änderungsleitfaden für KI-Agenten - [docs/STANDARD_PROFILE_MATRIX.md](docs/STANDARD_PROFILE_MATRIX.md) – Profile - [docs/CONTAINER_INVENTORY.md](docs/CONTAINER_INVENTORY.md) – alle Container, Modelle und Aufgaben - [docs/TESTED_MODELS.md](docs/TESTED_MODELS.md) – zentrale Testhistorie und Sperrliste gegen Doppeltests diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1b938f4..962e447 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -10,6 +10,8 @@ flowchart LR I --> E[Qwen3-8B NF4 Textencoder
RTX 3060 während Bildauftrag] R --> T[Qwen3-TTS RTX 3060
Normalisierungs- und Streaming-Gateway] R --> STT[Whisper.cpp ggml-small
CPU, lokale Spracherkennung] + P --> SP[Exklusive Spezialworker
Musik / Trennung / Voice / RVC / 3D] + SP --> TR[TRELLIS.2 4B Q8
trellis.cpp, RTX 5080] H --> U[MUA / Unraid MCP] H --> A[ARR-MCP] @@ -17,11 +19,12 @@ flowchart LR H --> N[Navidrome-MCP] H --> S[STRATO-MCP] H --> X[Nginx-Proxy-Manager-MCP] - U --> M[Media-Tools
ffmpeg / ffprobe / yt-dlp] + U --> MT[Media-Tools
ffmpeg / ffprobe / yt-dlp] W[WireGuard-Gateway
Athena] -->|DNS-Proxy| R W -->|DNS-Proxy :8099| B[Athena Dashboard
internes Frontend-Netz] W -->|DNS-Proxy :9443| PRT[Portainer
internes Frontend-Netz] + W -->|DNS-Proxy :8013| TRUI[Trellis Studio
Bild zu GLB] W -->|DNS-Proxy| O[Athena Operator] K[Backup alle 5 Stunden] --> DATA[/data und /etc/mike-ai] ``` @@ -34,6 +37,9 @@ flowchart LR - **MUA** verwaltet Unraid. **Athena Operator** bleibt auf den Athena-Host begrenzt. - Der Router ist die einzige Modelladresse, die Hermes kennen muss. +- GPU-intensive Spezialdienste sind gegenseitig exklusiv. Der Router speichert + Modus und Rückkehrprofil; der Profile Controller startet nur eindeutig + gelabelte Worker. - 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. @@ -75,3 +81,16 @@ 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. + +## TRELLIS.2 3D-Modus + +Der Modus `trellis` stoppt die anderen GPU-Worker und startet genau den mit +`com.mike-ai.trellis-worker=trellis2-q8` markierten Container. trellis.cpp +0.6.0 sieht ausschließlich die Host-GPU 1, die RTX 5080. Q8-Gewichte liegen +unter `/data/models/trellis2-q8`, Runtime und Ausgaben unter +`/data/trellis-studio`. Die UI ist intern `trellis-studio:8080` und wird vom +WireGuard-Gateway auf `192.168.1.212:8013` weitergeleitet. Sie erzeugt GLB; +regulärer Qualitätsmodus ist 1024 Pixel. + +Die vollständigen Regeln für Erweiterungen, Rückbau und Fehlersuche stehen in +[`../for_ki.md`](../for_ki.md). diff --git a/docs/CONTAINER_INVENTORY.md b/docs/CONTAINER_INVENTORY.md index 5f2124b..09a6761 100644 --- a/docs/CONTAINER_INVENTORY.md +++ b/docs/CONTAINER_INVENTORY.md @@ -27,6 +27,7 @@ nicht automatisch ein ungenutzter Rest. | `mike-ai-qwen3-tts` | `Qwen/Qwen3-TTS-12Hz-1.7B-Base`, Stimme Serena | Hochwertige deutsche Sprachausgabe auf der RTX 3060 im LLM-Betrieb. | | `mike-ai-router` | kein eigenes Modell | Einzige OpenAI-kompatible Modelladresse; koordiniert Profile, Bildaufträge, Sprache und Betriebsarten. | | `mike-ai-stem-separator` | BS-RoFormer Viperx 1297, `htdemucs_ft`, `htdemucs_6s`, `MossFormer2_SE_48K` | Trennt Gesang, Instrumente oder Sprache/Hintergrundgeräusche im exklusiven Separationsmodus. | +| `mike-ai-trellis-studio` | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | Erzeugt im exklusiven 3D-Modus aus einem Bild ein texturiertes, geschlossen aufbereitetes GLB-Mesh. Nutzt ausschließlich die RTX 5080 und wird über Port 8013 bedient. | | `mike-ai-tts-gateway` | kein eigenes Modell | Normalisiert Text, konvertiert Ausgabeformate und stellt Qwen3-TTS sowie natives PCM-Streaming über eine stabile interne API bereit. | | `mike-ai-voice-studio` | `k2-fsa/OmniVoice` 0.2.1 mit Whisper-ASR | Erzeugt Text-to-Speech mit einer Referenzstimme; kein Audio-to-Audio-Voice-Changer. | | `mike-ai-whisper` | Whisper.cpp `ggml-small` | Lokale deutsche Spracherkennung auf der CPU über `/v1/audio/transcriptions`. | diff --git a/docs/CURRENT_RUNTIME_NOTES.md b/docs/CURRENT_RUNTIME_NOTES.md index 3ecfc36..d21d130 100644 --- a/docs/CURRENT_RUNTIME_NOTES.md +++ b/docs/CURRENT_RUNTIME_NOTES.md @@ -1,6 +1,15 @@ # Aktueller produktiver Laufzustand -Stand: 8. September 2026 +Stand: 10. September 2026 + +## TRELLIS.2 3D-Studio + +TRELLIS.2 4B läuft über trellis.cpp 0.6.0 als exklusiver Q8-Worker auf der +RTX 5080. Runtime und Q8-Gewichte liegen getrennt unter +`/data/trellis-studio` und `/data/models/trellis2-q8`; die Browseroberfläche +ist im WireGuard-Netz unter `http://192.168.1.212:8013` erreichbar. Ein realer +512er Ende-zu-Ende-Test erzeugte in 54,2 Sekunden ein gültiges 4,4-MB-GLB. +Für reguläre Qualitätsläufe ist `1024 · cascade` vorgesehen. ## Fotorestaurierung verworfen diff --git a/docs/OPERATING_MODES.md b/docs/OPERATING_MODES.md index 8f5d629..268510e 100644 --- a/docs/OPERATING_MODES.md +++ b/docs/OPERATING_MODES.md @@ -1,6 +1,6 @@ # Athena-Betriebsmodi -Athena besitzt sechs gegenseitig exklusive Betriebsmodi: +Athena besitzt sieben gegenseitig exklusive Betriebsmodi: - `llm`: ein llama.cpp-Profil und Qwen3-TTS laufen; Spezialdienste sind gestoppt. - `music`: ACE-Step 1.5 XL-SFT läuft; alle LLM-, Bild-, TTS- und Separator-Worker sind gestoppt. @@ -13,6 +13,9 @@ Athena besitzt sechs gegenseitig exklusive Betriebsmodi: GPU-Dienste sind gestoppt. - `applio`: Applio stellt RVC-Inferenz, Modellverwaltung und Training bereit. Alle anderen GPU-Dienste sind gestoppt. +- `trellis`: TRELLIS.2 4B Q8 erzeugt über trellis.cpp aus einem Eingabebild ein + texturiertes GLB. Der Worker läuft ausschließlich auf der RTX 5080; alle + anderen GPU-Dienste sind gestoppt. Die Zustandsmaschine lebt im Athena-Router. Das Dashboard und Chat-Clients wie Hermes sind nur Bedienoberflächen derselben API. Der zuletzt aktive LLM-Modus @@ -21,7 +24,7 @@ wird persistent gespeichert und beim Verlassen eines Spezialmodus wieder geladen ## Bedienung Im Athena-Dashboard stehen **LLM-Betrieb**, **Musikstudio**, **Audio trennen**, -**Voice Studio**, **X-VC** und **Applio / RVC** bereit. Im Musikmodus werden zwei Oberflächen angeboten: +**Voice Studio**, **X-VC**, **Applio / RVC** und **3D Studio** bereit. Im Musikmodus werden zwei Oberflächen angeboten: - **Original UI · stabil** öffnet die zum laufenden ACE-Step-Image gehörende Gradio-Oberfläche. Sie ist für Cover, Remix und erweiterte Workflows der @@ -80,6 +83,13 @@ benötigt zwingend ein zuvor importiertes oder trainiertes RVC-Stimmenmodell nicht. Der Code ist auf Commit `7fa68ec2166ab1331c539704159fa14901e94e5a` fixiert. +Das TRELLIS.2-3D-Studio ist unter `http://192.168.1.212:8013` erreichbar. Es +verwendet trellis.cpp 0.6.0 und die Q8-Variante von TRELLIS.2 4B. Das Modell +läuft ausschließlich auf der RTX 5080; `1024 · cascade`, automatische +Hintergrundentfernung und `xatlas` sind die empfohlenen Standardwerte. Die UI +exportiert GLB. Ein nachgelagerter STL-/3MF-Export ist noch nicht Bestandteil +der Oberfläche. + Hermes benötigt dafür kein Plugin. Exakt eingegebene Steuerbefehle werden vom Router lokal beantwortet, auch wenn gerade kein LLM geladen ist: @@ -89,6 +99,8 @@ Router lokal beantwortet, auch wenn gerade kein LLM geladen ist: /athena voice /athena voicechange /athena applio +/athena 3d +/athena trellis /athena llm /athena status ``` @@ -102,6 +114,7 @@ POST /mode {"mode":"separation"} POST /mode {"mode":"voice"} POST /mode {"mode":"voicechange"} POST /mode {"mode":"applio"} +POST /mode {"mode":"trellis"} POST /mode {"mode":"llm"} ``` @@ -111,7 +124,8 @@ Der Wechsel läuft asynchron. Fortschritt und Fehler stehen unter `mode` in `com.mike-ai.stem-separator=bs-roformer` oder `com.mike-ai.voice-worker=vevo2` beziehungsweise `com.mike-ai.voice-change-worker=xvc` oder -`com.mike-ai.applio-worker=applio` markierten Container; freie +`com.mike-ai.applio-worker=applio` oder +`com.mike-ai.trellis-worker=trellis2-q8` markierten Container. Freie Container- oder Docker-Befehle werden nicht entgegengenommen. ## Wiederanlauf diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md index 31f3f7d..8cec926 100644 --- a/docs/RECOVERY.md +++ b/docs/RECOVERY.md @@ -41,6 +41,16 @@ werden außerdem: - Audio-Trennungen unter `/data/audio`, - Dashboard-, Operator-, Benchmark- und Projektdaten. +### Aktuelle TRELLIS-Lücke + +Das am 10.09.2026 ergänzte 3D-Studio speichert seine Ausgaben unter +`/data/trellis-studio/output`. Dieser Pfad ist im derzeit ausgerollten +Export- und Disaster-Backup **noch nicht enthalten**. Wichtige GLB-Dateien +müssen bis zur Erweiterung der Backup-Skripte zusätzlich extern gesichert +werden. Runtime und Q8-Gewichte sind erneut ladbar; die vom Benutzer erzeugten +GLB-Dateien sind es nicht. Der Live-Code unter `/opt/mike-ai/trellis-studio` +wird vom lokalen Schnellbackup über `/opt/mike-ai` erfasst. + Die rund 100 GB reproduzierbaren Modellgewichte unter `/data/models` werden nicht extern dupliziert. Kerngewichte lädt `install.sh` anhand URL und SHA256 neu. Spezialmodelle laden ihre gepinnten Container beim ersten Start erneut. diff --git a/docs/SPECIALIZED_MODEL_ROADMAP.md b/docs/SPECIALIZED_MODEL_ROADMAP.md index ea8a46b..99e5024 100644 --- a/docs/SPECIALIZED_MODEL_ROADMAP.md +++ b/docs/SPECIALIZED_MODEL_ROADMAP.md @@ -1,6 +1,6 @@ # Roadmap fuer spezialisierte lokale KI-Dienste -Stand: 8. September 2026 +Stand: 10. September 2026 Diese Liste sammelt Nischenmodelle, die wir auf Athena nacheinander testen. Ein Eintrag ist erst produktiv, wenn er auf der realen Hardware abgenommen und @@ -14,6 +14,7 @@ im zentralen Register `TESTED_MODELS.md` dokumentiert wurde. | 4 | Objekte lokalisieren und zaehlen | Grounding DINO oder RF-DETR | optionaler Vision-Worker; normales Erkennen bleibt beim vorhandenen Qwen-Vision-Projektor | offen | | 5 | Bildort schaetzen | GeoAgent 8B | exklusives Vision-Profil; Ergebnis nur als Wahrscheinlichkeitsrangliste | offen | | 6 | Eigene Orte/Bilder wiederfinden | AnyLoc oder GME-Qwen2-VL-7B | Embedding-Index mit eigener Referenzdatenbank | offen | +| 7 | Bild zu texturiertem 3D-Modell | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | exklusiver Worker auf RTX 5080; GLB; Standard 1024 | **integriert; technischer Ende-zu-Ende-Test bestanden** | ## Grundsaetze diff --git a/docs/TESTED_MODELS.md b/docs/TESTED_MODELS.md index 4de4bf5..16463fa 100644 --- a/docs/TESTED_MODELS.md +++ b/docs/TESTED_MODELS.md @@ -1,6 +1,6 @@ # Register getesteter Modelle -Stand: 9. September 2026 +Stand: 10. September 2026 Dieses Dokument ist die zentrale Sperrliste gegen doppelte Modelltests. Vor jedem Download müssen Repository, Dateiname, Basismodell, Fine-Tune und @@ -64,6 +64,12 @@ Titelgenerierung und Kontextkompression in Hermes. | 09.09.2026 | `Plachtaa/seed-vc` V1, Code `51383efd921027683c89e5348211d93ff12ac2a8` | Technisch vollständig lauffähig: gepinntes CUDA-Image, persistente Gewichte und reale WAV-Konvertierung mit etwa 3,6 GiB VRAM. Im deutschen Hörtest erhielt die Ausgabe jedoch einen deutlich chinesischen Akzent | **qualitativ verworfen und vollständig entfernt**; nicht erneut für deutsche Sprachwandlung einplanen | | 09.09.2026 | `IAHispano/Applio`, Code `7fa68ec2166ab1331c539704159fa14901e94e5a` | Gepinntes CUDA-12.8-fähiges Image auf RTX 5080 gestartet; vollständige Applio/RVC-Oberfläche antwortet und CUDA ist verfügbar. Rund 1,8 GiB Basisgewichte und die Konfiguration wurden persistent ausgelagert. Es ist kein Zielstimmenmodell installiert; Applio kann aus einer Referenzaufnahme allein kein Modell ableiten | **technischer Start- und Persistenztest bestanden**; Konvertierung erst nach Import oder Training einer `.pth`-Stimme möglich | +## 3D-Erzeugung + +| Datum | Modell | Test | Ergebnis | Status / Entscheidung | Beleg | +|---|---|---|---|---|---| +| 10.09.2026 | TRELLIS.2 4B Q8, zehn GGUF-Komponenten, trellis.cpp 0.6.0 | Bild-zu-3D bei 512, ausschließlich RTX 5080, Hintergrundentfernung `auto`, UV `xatlas` | HTTP 200 nach 54,2 s; gültiges GLB 2 mit 4,4 MB; Container und Browseroberfläche gesund | **technisch integriert**; 1024 ist der vorgesehene Qualitätsstandard, Druck- und subjektive Geometrieabnahme noch offen | Athena: `/opt/mike-ai/trellis-studio`, Gewichte: `/data/models/trellis2-q8` | + ## Musikgenerierung | Datum | Modell | Test | Ergebnis | Status / Entscheidung | Beleg | diff --git a/for_ki.md b/for_ki.md new file mode 100644 index 0000000..6d33b5d --- /dev/null +++ b/for_ki.md @@ -0,0 +1,256 @@ +# 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`.