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

Ein Client verwendet ausschließlich Port 8081.
Der Router veröffentlicht qwen-fast, qwen-medium und qwen-long.
Passt das aktive Profil nicht zum virtuellen Modell, wird llama.cpp kontrolliert mit dem passenden Profil neu gestartet.
Der Router wartet auf Modellname und erwartete Kontextgröße.
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:

sperrt die GPU-Orchestrierung,
merkt sich das aktive Textprofil,
stoppt llama.cpp,
startet vorübergehend Vision oder FLUX,
beendet den Hilfsprozess vollständig,
stellt das ursprüngliche Textprofil wieder her,
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

/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

4.3 KiB Raw Blame History