63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# Router V2 – Migration und Kompatibilität
|
||
|
||
> Historischer Stand: Die damalige Bezeichnung `long` wurde am 22. August
|
||
> 2026 durch `large` ersetzt und um `ultra` ergänzt. Für den aktuellen Betrieb
|
||
> gilt ausschließlich `STANDARD_PROFILE_MATRIX.md`.
|
||
|
||
## Ergebnis
|
||
|
||
V2 behält die OpenAI-kompatible Basis-URL und die virtuellen Modelle
|
||
`qwen-fast`, `qwen-medium` und `qwen-long`. Bestehende Chat-, Tool-, Audio-,
|
||
Vision- und Bildpfade bleiben erhalten. Die Änderungen betreffen absichtlich
|
||
die Stellen, an denen der alte Router unsicher oder nicht deterministisch war.
|
||
|
||
## Bewusste Änderungen
|
||
|
||
| Alt | V2 |
|
||
|---|---|
|
||
| alle LAN-Clients ohne Authentifizierung | API-Key für alle fachlichen Endpunkte |
|
||
| `GET /fast` schaltet ein Modell | nur noch `POST /fast` (analog medium/long) |
|
||
| `/health` hängt am Modellzustand | `/health` = Prozess, `/ready` = Textmodell |
|
||
| Profil durch Textvergleich erkannt | Kontext + Alias aus Profilregister geprüft |
|
||
| Profilwechsel und Request konnten sich überholen | atomare Modell-Lease |
|
||
| Drain-Timeout beendete trotzdem das Modell | Wechsel wird sicher abgebrochen |
|
||
| Workerzustand nur im RAM | atomare Zustandsdatei und Startup-Recovery |
|
||
| beliebige Bild-URL | Data-URL, Größenlimit; Remote standardmäßig aus |
|
||
| unbegrenzte Parallelität und Bildablage | Request- und Retention-Limits |
|
||
| Auth-Header potenziell am Upstream | Router-Credentials werden entfernt |
|
||
|
||
## Client-Migration
|
||
|
||
1. Router-Key aus `/etc/mike-ai/router-api-key` ohne Anzeige in einen lokalen
|
||
Secret-Store des Clients übernehmen.
|
||
2. Basis-URL unverändert auf `http://HOST:8081/v1` lassen.
|
||
3. Den Key als OpenAI-API-Key/Bearer-Token konfigurieren.
|
||
4. `GET /v1/models` testen und anschließend einen kurzen Chat über
|
||
`qwen-fast` senden.
|
||
5. Automationen, die Profile per GET schalten, auf POST umstellen.
|
||
6. Überwachung auf `/health` (Liveness) und `/ready` (Readiness) aufteilen.
|
||
|
||
## Sicheres Rollout
|
||
|
||
V2 wird nicht blind über einen laufenden Router kopiert:
|
||
|
||
1. Repository-Commit und aktuelle produktive Konfiguration sichern.
|
||
2. Profilregister gegen alle drei systemd-Overrides prüfen.
|
||
3. API-Key erzeugen und Clients vorbereiten.
|
||
4. Router installieren und zuerst lokal mit Key prüfen.
|
||
5. Fast, Medium und Long jeweils einmal schalten und Alias/Kontext prüfen.
|
||
6. Streaming und einen Tool Call testen.
|
||
7. Erst danach normale Clients auf V2 freigeben.
|
||
|
||
Ein Rollback stellt Routerdateien und Unit aus dem Installationsbackup wieder
|
||
her. Der neu erzeugte API-Key und die Zustandsdatei enthalten keine
|
||
Modelldateien oder Chatdaten.
|
||
|
||
## Verbleibender Architekturpunkt
|
||
|
||
Der Routerprozess läuft derzeit als root, weil er den systemweiten llama.cpp-
|
||
Dienst und temporäre GPU-Worker steuert. Die Unit ist stark gehärtet, dennoch
|
||
ist das nicht das langfristige Ideal. V3 soll HTTP/API und privilegierte
|
||
Orchestrierung trennen: unprivilegierter Proxy plus kleiner Root-Helper mit
|
||
festen, nicht frei parametrisierbaren Aktionen.
|