108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# Architektur
|
|
|
|
## Ziel
|
|
|
|
Die Plattform stellt eine private, lokal betriebene OpenAI-kompatible API
|
|
bereit. Jede Komponente hat genau eine Aufgabe und kann unabhängig ersetzt
|
|
werden. Ein Neuaufbau darf keine Dateien vom alten Host voraussetzen, die nicht
|
|
in diesem Repository oder im Modellmanifest beschrieben sind.
|
|
|
|
## Komponenten
|
|
|
|
| Komponente | Port | Ausführung | Aufgabe |
|
|
|---|---:|---|---|
|
|
| AI Profile Router | 8081 | systemd, gehärtet | zentrale Client-API und Orchestrierung |
|
|
| llama.cpp | 8080 | systemd | Textmodell, Tool Calling und MCP |
|
|
| Whisper | 8084, nur localhost | systemd | Speech-to-Text |
|
|
| XTTS | 8085, nur localhost | systemd | Text-to-Speech |
|
|
| TinySearch | 8000, nur localhost | Docker | kompakte Websuche |
|
|
| SearXNG | intern | Docker | Suchmaschinen-Metasuche |
|
|
| LLama-GUI | 5240, optional | systemd | manuelle Administration |
|
|
| Glances | lokal, optional | systemd | Systemmetriken |
|
|
|
|
## Request-Fluss
|
|
|
|
1. Ein Client verwendet ausschließlich Port 8081.
|
|
2. Der Router veröffentlicht `qwen-fast`, `qwen-medium` und `qwen-long`.
|
|
3. Passt das aktive Profil nicht zum virtuellen Modell, wird llama.cpp kontrolliert
|
|
mit dem passenden Profil neu gestartet.
|
|
4. Der Router wartet auf Modellname und erwartete Kontextgröße.
|
|
5. Erst dann wird die Anfrage an Port 8080 weitergeleitet.
|
|
|
|
Profilwahl und Weiterleitung bilden dabei eine atomare Modell-Lease. Ein
|
|
zweiter Request kann das Profil nicht mehr zwischen Auswahl und Inferenz
|
|
wechseln. Laufende Requests werden vor einem GPU-Hotswap vollständig beendet;
|
|
bei Überschreiten des Drain-Timeouts wird der Wechsel abgebrochen, nicht der
|
|
Chat.
|
|
|
|
## Profilprinzip
|
|
|
|
Die Profile sind vollständige systemd-Overrides. Ein Profilwechsel kopiert die
|
|
gewählte Datei atomar auf `override.conf`, lädt systemd neu und startet genau
|
|
einen llama.cpp-Dienst neu. Es gibt niemals mehrere Textmodelle gleichzeitig.
|
|
Das unabhängige Register `/etc/mike-ai/router-profiles.json` definiert Kontext
|
|
und erwarteten Modellalias. Readiness gilt nur, wenn beides exakt passt; eine
|
|
abweichende oder fehlende Registry verhindert den Start.
|
|
|
|
## GPU-Hotswap
|
|
|
|
Vision und Bildgenerierung teilen sich die RTX mit dem Textmodell. Der Router:
|
|
|
|
1. sperrt die GPU-Orchestrierung,
|
|
2. merkt sich das aktive Textprofil,
|
|
3. stoppt llama.cpp,
|
|
4. startet vorübergehend Vision oder FLUX,
|
|
5. beendet den Hilfsprozess vollständig,
|
|
6. stellt das ursprüngliche Textprofil wieder her,
|
|
7. prüft Modell und Kontext vor der Freigabe.
|
|
|
|
Der zuletzt stabile Zustand und temporäre Worker-PIDs werden atomar unter
|
|
`/var/lib/mike-ai-profile-router/state.json` festgehalten. Beim Routerstart
|
|
werden ausschließlich dort erfasste Prozesse nach zusätzlicher
|
|
Kommandozeilenprüfung beendet und das letzte Profil wiederhergestellt.
|
|
|
|
## Vertrauensgrenzen
|
|
|
|
- Port 8081 verlangt einen eigenen API-Key; nur `/health` und `/ready` sind
|
|
absichtlich anonym und enthalten keine privaten Daten.
|
|
- Der Client-Key wird vor dem lokalen Upstream entfernt.
|
|
- Bild-Uploads sind begrenzt. Remote-Bild-URLs sind standardmäßig aus, damit
|
|
der Vision-Pfad nicht als Zugriff auf Intranet oder Metadatenendpunkte dient.
|
|
- Maximal 16 Requests werden gleichzeitig bearbeitet; weitere erhalten 429.
|
|
- Der Dienst benötigt derzeit wegen systemd-Profilwechsel und GPU-Hotswap noch
|
|
Root-Rechte. Die systemd-Sandbox begrenzt diese, ersetzt aber keine künftige
|
|
Aufteilung in unprivilegierten Proxy und eng begrenzten Root-Helper.
|
|
|
|
## Verzeichnislayout auf dem Zielhost
|
|
|
|
```text
|
|
/opt/mike-ai/
|
|
ai-profile-router/ Routercode und eigenes Venv
|
|
llama.cpp/ exakt ein produktiver Build
|
|
models/ Modelle nach Manifest
|
|
whisper.cpp/ Speech-to-Text Runtime
|
|
xtts/ XTTS Runtime und Cache
|
|
web-search/ Docker Compose für TinySearch/SearXNG
|
|
|
|
/etc/mike-ai/
|
|
mcp-servers.json lokale, geheime produktive Konfiguration
|
|
*.env Credentials, niemals im Git
|
|
|
|
/etc/systemd/system/
|
|
mike-ai-*.service
|
|
mike-ai-llama-ui.service.d/
|
|
override.conf
|
|
profile-fast.conf.disabled
|
|
profile-medium.conf.disabled
|
|
profile-long.conf.disabled
|
|
```
|
|
|
|
## Nicht Teil der Zielarchitektur
|
|
|
|
- parallele llama.cpp-Builds
|
|
- allgemeiner Shell-MCP im Standardprofil
|
|
- doppelte Unraid-MCPs
|
|
- RX-spezifische Dienste ohne eingebaute RX
|
|
- automatisch startende Benchmark-Dienste
|
|
- Modellkopien außerhalb des dokumentierten Modellverzeichnisses
|