AI-Profile-Router/docs/OPERATIONS.md

Betrieb

Profile

Profil	Virtuelles Modell	Kontext	Zweck
Fast	qwen-fast	73.728	Alltag, Agenten, hohe Geschwindigkeit
Medium	qwen-medium	94.208	mehr Kontext, reine IQ4_XS-Variante
Long	qwen-long	131.072	lange Hermes-/MCP-Sitzungen

Manuell wird mit llama-profile fast|medium|long gewechselt. Über HTTP stehen POST /fast, /medium und /long zur Verfügung. Für eine spätere Version ist large als Alias für long vorgesehen; bestehende Namen bleiben kompatibel.

Clients

Clients verbinden sich mit:

http://HOST:8081/v1

Als API-Key verwenden sie den Inhalt von /etc/mike-ai/router-api-key über Bearer-Authentifizierung. Der Key gehört in den Secret-Store des Clients, nicht in Chat, Repository oder URL. Eine Rotation erfolgt atomar durch Ersetzen der Datei und Neustart des Routerdienstes.

Sie sollen nicht direkt Port 8080 verwenden, weil sie sonst Profilumschaltung, Vision, Bildgenerierung, STT und TTS umgehen.

Status

• GET /health: Routerprozess lebt; bleibt bei geplantem Hotswap grün
• GET /ready: Router und Textmodell sind einsatzbereit
• GET /status: authentifizierter Detailstatus, Profil, Upstream, aktive Jobs
• GET /v1/models: virtuelle Modelle
• llama.cpp-Metriken: Port 8080, nur im administrativen Netz freigeben
• systemd-Journal: nur Metadaten und Fehler prüfen; keine Promptinhalte sammeln

Upgrade-Regel

Niemals Build, Quantisierung und Profil gleichzeitig ändern. Immer genau eine Variable ändern und anschließend denselben Benchmark ausführen.

Profilkontext und Alias werden zusätzlich in /etc/mike-ai/router-profiles.json gepflegt. Änderungen an Override und Registry gehören in denselben getesteten Commit; andernfalls verweigert die Readiness bewusst die Freigabe.

Fehler- und Recovery-Verhalten

• Ein Profilwechsel bricht ab, wenn laufende Chats nicht innerhalb des Drain-Timeouts enden. Er beendet niemals absichtlich einen Chat.
• Nach einem Routerabsturz wird das letzte stabile Profil aus der atomaren Zustandsdatei rekonstruiert.
• /health = 200, aber /ready = 503 bedeutet: Router lebt, Modell ist noch nicht bereit oder wird gerade gewechselt.
• 429 bedeutet, dass die Parallelitätsgrenze erreicht ist; der Client soll mit Backoff erneut versuchen.

Kapazitätsregeln

• Systempartition dauerhaft unter 85 Prozent halten.
• Mindestens 1 GiB Sicherheitsreserve für allgemeine GPU-Profile vorsehen; experimentelle Max-GPU-Profile klar kennzeichnen.
• Nur ein Textmodell gleichzeitig laden.
• Benchmarks sind deaktivierte, manuell gestartete Jobs und keine Boot-Dienste.

Backup

Gesichert werden:

• dieses Repository,
• lokale Modellmanifest-Datei mit Hashes, aber ohne Secrets,
• /etc/mike-ai verschlüsselt,
• systemd-Konfiguration,
• Benchmarkresultate.

Nicht gesichert werden müssen Build-Verzeichnisse, Venvs, Caches oder Modelle, wenn Downloadquelle und Prüfsumme dokumentiert sind.