147 lines
7.3 KiB
Markdown
147 lines
7.3 KiB
Markdown
# 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 einzige normale Oberfläche
|
||
- 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`](docs/STANDARD_PROFILE_MATRIX.md).
|
||
|
||
## Schnellstart
|
||
|
||
Auf einem frisch installierten Debian 12/13 amd64:
|
||
|
||
```bash
|
||
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 |
|
||
| 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.
|
||
|
||
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:
|
||
|
||
```text
|
||
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`](docs/PLATFORM_OVERVIEW.md) – kurze Gesamtsicht
|
||
- [`docs/QWEN_OPERATOR_CONTEXT.md`](docs/QWEN_OPERATOR_CONTEXT.md) – ausführliches Kontextpaket für das lokale Operator-Modell
|
||
- [`docs/PLATFORM_CONTEXT_MCP.md`](docs/PLATFORM_CONTEXT_MCP.md) – profilunabhängiges Plattformwissen und kontrollierte Dokumentationspflege
|
||
- [`docs/GITHUB_MCP.md`](docs/GITHUB_MCP.md) – sicherer GitHub-Nur-Lesen-Betrieb und bewusst aktivierbarer Wartungsmodus
|
||
- [`docs/TOOLING_RELIABILITY_2026-08-24.md`](docs/TOOLING_RELIABILITY_2026-08-24.md) – Werkzeugumbau, Abnahme und Rollback
|
||
- [`config/operator-system-prompt.txt`](config/operator-system-prompt.txt) – knapper System-Prompt für ein getrenntes Operator-Profil
|
||
|
||
- [Roadmap für den neuen Host](docs/NEW_HOST_ROADMAP.md)
|
||
- [Zielarchitektur und Sicherheitsgrenzen](docs/ARCHITECTURE.md)
|
||
- [Installation und Abnahme](docs/INSTALLATION.md)
|
||
- [WireGuard-Heimseite](docs/WIREGUARD_HOME_PEER.md)
|
||
- [Checkliste für den unbeaufsichtigten Standort](docs/REMOTE_SITE_CHECKLIST.md)
|
||
- [Temporärer Notfallzugriff über SSH](docs/EMERGENCY_UNI_ACCESS.md)
|
||
- [Betrieb und Profilwechsel](docs/OPERATIONS.md)
|
||
- [Sicherheitsmodell](docs/SECURITY.md)
|
||
- [Disaster Recovery](docs/DISASTER_RECOVERY.md)
|
||
- [Vollständige Bare-Metal-Wiederherstellung](docs/BARE_METAL_RECOVERY.md)
|
||
- [Protokoll des Athena-Leerhostaufbaus](docs/ATHENA_REBUILD_LOG.md)
|
||
- [Komponenten](docs/COMPONENTS.md)
|
||
|
||
## Wichtige Dateien
|
||
|
||
```text
|
||
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
|
||
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.
|