# 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:

```bash
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 drei Profilgrenzen 76.800, 94.208 und 131.072
Token. 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 | `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:

```text
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.