AI-Profile-Router/docs/OPERATIONS.md

Betrieb

OpenWebUI-Filter und Stabilitätsschutz

Die versionierten Filter liegen unter platform/openwebui/filters/. Ihre Reihenfolge ist absichtlich festgelegt:

1. Reasoning Default Off, Priorität 10: setzt jeden Request zunächst auf reasoning_effort=none.
2. Thinking, Priorität 20: läuft nur bei aktiviertem Brain-Schalter und überschreibt den Standard mit Low, Medium oder High.
3. MikeAI Stability Guard, Priorität 30: begrenzt einzelne und gesamte Werkzeugresultate, verdichtet bei Bedarf zuerst alte Tool-Ausgaben und Dialogteile und stoppt identische beziehungsweise ausufernde Tool-Schleifen.
4. MikeAI Secret Redaction, Priorität 40: entfernt übliche API-Keys, Tokens, Passwörter, JWTs und private Schlüssel aus Tool-Ergebnissen, bevor sie das Modell erreichen, sowie aus fertigen Modellantworten. Nutzereingaben und Authentifizierungswege werden nicht verändert.
5. MikeAI Local Performance Metrics, Priorität 90: erfasst nach Abschluss ausschließlich technische Zahlen wie Laufzeit, Tokenzähler, Token/s und Tool-Anzahl. Nutzer-, Chat- und Nachrichten-IDs sowie sämtliche Textinhalte werden weder geschrieben noch gehasht gespeichert.

OpenWebUI sortiert kleinere Prioritäten zuerst. Nach dem ersten Anlegen eines Admin-Benutzers oder nach einer Datenwiederherstellung werden alle Filter mit einer vorherigen Datenbanksicherung installiert beziehungsweise aktualisiert:

sudo /opt/mike-ai/stack/platform/openwebui/install-filters.sh

Bei mehreren Administratoren muss der gewünschte Eigentümer explizit über OPENWEBUI_FILTER_OWNER_ID gesetzt werden. Das Skript liest oder verändert keine Chats. Es deaktiviert zugleich global die automatisch erzeugten Folgefragen (task.follow_up.enable=false). Dieselbe Vorgabe steht zusätzlich als Container-Umgebungswert im Compose-Stack, damit bereits eine frische OpenWebUI-Datenbank ohne Folgefragen startet.

Der Stabilitätsschutz kennt die vier Profilgrenzen 76.800, 160.000, 192.000 und 262.144 Token. Für unbekannte Modelle gilt Medium (160.000) als sichere Vorgabe. Er reserviert Ausgabetoken und greift vor der harten llama.cpp-Grenze ein. Bilder bleiben unangetastet; JSON-Werkzeugschemas werden niemals abgeschnitten. Sind allein die ausgewählten Schemas zu groß, wird der Werkzeugzugriff nur für diesen Schritt deaktiviert und das Modell erhält eine eindeutige Abschlussanweisung.

Die rotierende, inhaltsfreie Metrikdatei liegt im persistenten OpenWebUI-Volume unter mike-ai-request-metrics.jsonl (maximal 5 MiB plus eine Rotation). Sie darf für Benchmarks ausgewertet werden, ohne Chats auszulesen.

Aktionen an Modellantworten

Die globale Action MikeAI Quick Actions ergänzt die Nachrichtenleiste um:

• Kurzfassung, Als Checkliste, Technische Diagnose und Unsicherheiten prüfen: jeweils ein bewusster zusätzlicher lokaler Modellaufruf, dessen Ergebnis unter der gewählten Antwort ergänzt wird.
• Mit Thinking verbessern: lokale erneute Prüfung mit Medium-Reasoning und festem Thinking-Budget; Werkzeuge werden dabei nicht injiziert.
• Quellen prüfen: erstellt lokal eine knappe Suchanfrage, ruft ausschließlich den internen Web-MCP auf und lässt Qwen die Antwort gegen dessen begrenzte, als unvertrauenswürdig markierte Belege prüfen.
• Markdown kopieren: kopiert den gewählten Antworttext im aktiven Browser ohne Modellaufruf und ohne serverseitige Datei.

Die Aktionen schreiben nicht in Git oder Zielsysteme und schalten keine Routerprofile um. Action-Funktionen laufen mit Serverrechten; deshalb bleibt der geprüfte Quellcode Bestandteil dieses Repositorys und wird nicht aus dem Community Store nachgeladen.

Profile

Profil	Virtuelles Modell	Kontext	Zweck
Fast	qwen-fast	76.800	Alltag, Agenten, hohe Geschwindigkeit, integrierte Vision
Medium (Standard)	qwen-medium	160.000	IQ4_XS Pure, beide GPUs 90:10, MTP3, integrierte Vision
Large	qwen-large	192.000	IQ4_XS Pure, beide GPUs 86:14, MTP3, integrierte Vision
Ultra	qwen-ultra	262.144	maximaler Textkontext, IQ4_XS Pure auf RTX 5080 + RTX 3060 (80:20), ohne Vision-Projektor

Manuell wird mit llama-profile fast|medium|large|ultra gewechselt. Über HTTP stehen POST /fast, /medium, /large und /ultra zur Verfügung. Ultra erreichte im Referenzlauf etwa 68 Token/s; ein Prompt-Fülltest mit rund 220.000 Tokens war erfolgreich. Medium ist das Start- und Standardprofil.

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.