112 lines
5.1 KiB
Markdown
112 lines
5.1 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
|
|
- vier schaltbare Profilcontainer plus ein isolierter Experimentalcontainer;
|
|
davon ist immer exakt ein Inferenzcontainer aktiv
|
|
- `/fast`, `/medium`, `/large` und `/ultra` über den Profile Router
|
|
- verbindliche Standardmatrix: Fast MIX 76,8K, Medium Pure 160K (Default),
|
|
Large Pure 192K und Ultra Pure 256K
|
|
- `/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
|
|
- SearXNG/Web-MCP ohne externen API-Schlüssel
|
|
- zentrale MCP-Werkzeugebene: getrennte Container für Web, HA, ARR, Unraid
|
|
und Sandbox, gemeinsam nutzbar durch Open WebUI und andere Clients
|
|
- KI-Dienste ausschließlich über die WireGuard-Adresse 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, 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 |
|
|
| Piper | nur Docker-intern | lokale deutsche Sprachausgabe |
|
|
| MCP-Tool-Stack | nur Docker-intern | Web, Home Assistant, ARR und Unraid |
|
|
|
|
Piper-TTS und der FLUX.2-Klein-Hot-Swap sind reproduzierbare Kerndienste; STT
|
|
bleibt optional. Web-, Home-Assistant-,
|
|
ARR- und Unraid-Werkzeuge besitzen dagegen bereits getrennte Container unter
|
|
`platform/mcp/`. Open WebUI erreicht sie ausschließlich über das interne
|
|
`mike-ai-tools`-Netz; 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.
|
|
|
|
## Dokumentation
|
|
|
|
- [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)
|
|
- [Betrieb und Profilwechsel](docs/OPERATIONS.md)
|
|
- [Sicherheitsmodell](docs/SECURITY.md)
|
|
- [Disaster Recovery](docs/DISASTER_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.
|
|
- Ein Blackhole-Fallback verhindert Traffic-Leaks bei WireGuard-Ausfall.
|
|
- 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 und Large 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.
|