AI-Profile-Router/README.md

Lokale KI-Plattform

Reproduzierbarer Docker-Stack für einen privaten Qwen-/llama.cpp-Host mit Open WebUI, Profilumschaltung, integrierter Vision, lokaler Websuche und WireGuard-Isolation.

Zielbild

• Debian 13 als schlanker GPU-Host
• llama.cpp selbst gebaut und auf einen geprüften Commit festgelegt
• fünf schaltbare Profilcontainer plus ein isolierter Experimentalcontainer; davon ist immer exakt ein Inferenzcontainer aktiv
• /fast, /medium, /large, /ultra und /uncensored über den Profile Router
• verbindliche Standardmatrix: Fast MIX 76,8K, Medium Pure 160K (Default), Large Pure 192K, Ultra Pure 256K sowie Abliterated Q4_K_M 80K als bewusst nicht standardmäßiges Uncensored-Spezialprofil
• /ultra: getestetes text-only 256K-Profil (IQ4_XS Pure, beide GPUs, 80:20); etwa 68 Token/s und erfolgreicher 220K-Prompt-Fülltest
• Open WebUI als einfache Chat-Oberfläche und Hermes Agent als zweite, agentische Oberfläche für lange, werkzeugintensive Aufgaben
• native OpenWebUI-Websuche für allgemeine Recherche; SearXNG/Web-MCP als manueller Spezialadapter ohne externen API-Schlüssel
• zentrale MCP-Werkzeugebene: getrennte Container für Athena-Plattformwissen, den kontrollierten Athena Operator, Web, GitHub, HA, ARR, Unraid, Navidrome und Sandbox, gemeinsam nutzbar durch Open WebUI und andere Clients
• KI-Dienste ausschließlich über den containerisierten WireGuard-Gateway erreichbar
• KI-Ausgangsverkehr über das Heimnetz, bei Tunnelausfall fail-closed
• keine Secrets, Chats, Logs oder Modelldateien im Repository

Die gemessenen Startparameter und Zuständigkeiten stehen in docs/STANDARD_PROFILE_MATRIX.md.

Schnellstart

Auf einem frisch installierten Debian 12/13 amd64:

cp config/install.env.example config/install.env
chmod 600 config/install.env
editor config/install.env
sudo ./install.sh --config config/install.env

Installiert werden Docker CE, NVIDIA Container Toolkit, WireGuard-Werkzeuge, der gepinnt gebaute llama.cpp-Server, die Modelle und der komplette Compose-Stack. Bei einer erstmaligen NVIDIA-Treiberinstallation fordert das Skript einen Neustart an; danach wird derselbe Befehl erneut ausgeführt.

Dienste

Dienst	Erreichbarkeit	Zweck
Open WebUI	<WG-IP>:8080	Chat und Administration
Hermes Dashboard	<WG-IP>:9119	agentischer Chat, Sitzungen, Skills und MCP-Verwaltung
Hermes API	<WG-IP>:8642	authentifizierte Agent-API
Profile Router	<WG-IP>:8081	OpenAI-kompatible API, Profilwahl
llama.cpp	nur Docker-intern	Inferenz und integrierte Vision
Profile Controller	nur Docker-intern	eng begrenzter Profil-/FLUX-Hot-Swap
FLUX Worker	nur Docker-intern, normalerweise gestoppt	Bildgenerierung auf RTX 5080
XTTS-v2	<WG-IP>:8092, RTX 3060	primäre mehrsprachige Sprachausgabe
TTS Gateway	<WG-IP>:8085	Annmarie Nele, Queue und Piper-Fallback
Piper	<WG-IP>:8091, CPU	ausfallsichere deutsche Ersatzstimme
MCP-Tool-Stack	<WG-IP>:8201-8208	Athena-Kontext, Athena Operator, Web, GitHub, Home Assistant, ARR, Unraid und Navidrome

XTTS-v2, TTS-Gateway, Piper-Fallback und der FLUX.2-Klein-Hot-Swap sind reproduzierbare Kerndienste; STT bleibt optional. Web-, Home-Assistant-, GitHub-, ARR-, Unraid- und Navidrome-Werkzeuge besitzen dagegen bereits getrennte Container unter platform/mcp/. Open WebUI erreicht sie über das interne mike-ai-tools-Netz; Pi, Hermes und andere Clients verwenden die direkten WireGuard-Ports aus docs/VPN_SERVICE_PORTS.md. llama.cpp erhält keine MCP-Konfiguration und keine Infrastruktur-Secrets. Die Bildanalyse ist Bestandteil des multimodalen Qwen-Modells.

Hermes läuft als eigener, per OCI-Digest gepinnter Container direkt neben OpenWebUI. Beide sprechen dieselbe Router-API und damit dieselben Qwen-Profile; Hermes ist kein zusätzlicher Modellserver. Seine Sitzungen, Skills, Konfiguration und isolierte Arbeitsfläche liegen unter /data/hermes.

Open WebUI erhält über die vorgesehenen statischen Anpassungspunkte ein globales Dark-Theme namens Midnight Aurora. CSS und Start-Loader liegen unter platform/openwebui/theme/ und werden schreibgeschützt in den Container eingebunden. Der Hintergrund bewegt sich bewusst langsam; Browser mit aktivierter Option „Bewegung reduzieren“ erhalten automatisch eine unbewegte Variante. Kurze Werkzeugbestätigungen werden ebenfalls lokal aus statischen Clips abgespielt. Sie laufen nur bei aktivierter automatischer Sprachausgabe, kosten keine Modell-Tokens und verraten dem Modell keine zusätzlichen Daten.

Dokumentation

API-Schnellreferenz

Für Zettelrobbe und andere OpenAI-kompatible Clients gilt im Heimnetz:

Base URL: http://192.168.1.212:8081/v1
API-Key:  Inhalt von /etc/mike-ai/router-api-key auf Athena

Den Schlüssel auf Athena ausschließlich lokal mit sudo cat /etc/mike-ai/router-api-key anzeigen und direkt in den Secret-Store des Clients kopieren. Er gehört niemals in Git, eine URL oder einen Chat. Die entsprechende Open-WebUI-Adresse auf Port 8080 ist keine API-Basisadresse.

• docs/PLATFORM_OVERVIEW.md – kurze Gesamtsicht

• docs/QWEN_OPERATOR_CONTEXT.md – ausführliches Kontextpaket für das lokale Operator-Modell

• docs/PLATFORM_CONTEXT_MCP.md – profilunabhängiges Plattformwissen und kontrollierte Dokumentationspflege

• docs/GITHUB_MCP.md – sicherer GitHub-Nur-Lesen-Betrieb und bewusst aktivierbarer Wartungsmodus

• docs/TOOLING_RELIABILITY_2026-08-24.md – Werkzeugumbau, Abnahme und Rollback

• config/operator-system-prompt.txt – knapper System-Prompt für ein getrenntes Operator-Profil

• Roadmap für den neuen Host

• Zielarchitektur und Sicherheitsgrenzen

• Installation und Abnahme

• WireGuard-Heimseite

• Checkliste für den unbeaufsichtigten Standort

• Temporärer Notfallzugriff über SSH

• Betrieb und Profilwechsel

• Sicherheitsmodell

• Disaster Recovery

• Vollständige Bare-Metal-Wiederherstellung

• Protokoll des Athena-Leerhostaufbaus

• Komponenten

Wichtige Dateien

install.sh                              kompletter Bootstrap
config/install.env.example              öffentliche Konfigurationsvorlage
compose.yaml                            produktiver Stack
platform/docker/llama-cpp/Dockerfile    CUDA-llama.cpp-Build
platform/docker/profile-controller/     sichere Profilsteuerung
platform/hermes/                         Hermes-Konfiguration und Installer
router/                                 OpenAI-kompatibler Profile Router

Sicherheitsregeln

• config/install.env ist lokal, Modus 0600, und wird ignoriert.
• API-, Controller-, WebUI- und WireGuard-Schlüssel entstehen erst am Host.
• Nur der kleine Profile Controller sieht den Docker-Socket.
• llama.cpp veröffentlicht weder Port noch WebUI.
• Quellrouting ohne alternative Route verhindert Traffic-Leaks bei WireGuard-Ausfall (fail-closed).
• Das Uni-Netz und das Heimnetz dürfen diesen Host nicht als Transit benutzen.

Die Profilwerte wurden auf RTX 5080 und RTX 3060 vermessen und bilden die verbindliche Standardmatrix. Neue Varianten ersetzen sie erst nach demselben Vergleichstest und einer dokumentierten Entscheidung.

Der integrierte Vision-Projektor der Profile Fast, Medium, Large und Uncensored läuft gezielt auf der RTX 3060. Das hält den knappen VRAM der RTX 5080 für Modell und Kontext frei und beschleunigte den dokumentierten synthetischen Vision-Test gegenüber CPU-Vision um etwa den Faktor 8,5 bei der Gesamtzeit.