diff --git a/README.md b/README.md index b87084b..1495935 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,9 @@ llama.cpp :8080 + profilabhängige MCP-Server - [Architektur](docs/ARCHITECTURE.md) - [Komponentenverzeichnis](docs/COMPONENTS.md) +- [Aktueller produktiver Referenzstand](docs/CURRENT_REFERENCE.md) +- [Noch benötigte Wiederherstellungsartefakte](docs/RECOVERY_REQUIREMENTS.md) +- [Disaster Recovery und Abnahme](docs/DISASTER_RECOVERY.md) - [Saubere Installation](docs/INSTALLATION.md) - [Betrieb und Profilwechsel](docs/OPERATIONS.md) - [Sicherheitsmodell](docs/SECURITY.md) diff --git a/docs/CURRENT_REFERENCE.md b/docs/CURRENT_REFERENCE.md new file mode 100644 index 0000000..10789f8 --- /dev/null +++ b/docs/CURRENT_REFERENCE.md @@ -0,0 +1,163 @@ +# Aktueller produktiver Referenzstand + +Stand: 20. August 2026. Dieses Dokument beschreibt die funktionierende +Referenz vor dem geplanten Neuaufbau. Es ist keine Empfehlung, jede Altlast des +Hosts zu übernehmen. + +## Hardware und Betriebssystem + +| Bereich | Referenz | +|---|---| +| Betriebssystem | Debian 13 `trixie` | +| Kernel | 6.12.101+deb13-amd64 | +| CPU | AMD Ryzen 5 5600, 6 Kerne/12 Threads | +| RAM | 48 GiB DDR4-2666 | +| GPU | NVIDIA GeForce RTX 5080, 16 GiB VRAM | +| NVIDIA-Treiber | 610.57.04 | +| System-SSD | Samsung 980 PRO 1 TB | +| Daten-SSD | Samsung 980 PRO 2 TB | + +Die früher verwendete Radeon RX 470 ist ausgebaut und gehört nicht zur +Zielplattform. + +## Produktiver Text-Stack + +| Eigenschaft | Aktueller Wert | +|---|---| +| Runtime | llama.cpp | +| Repository | `https://github.com/ggml-org/llama.cpp.git` | +| Commit | `4df29be4f4c3673f428170fda944a5b19f743bb8` | +| Compiler | GCC 14.2 | +| Hauptdienst | `mike-ai-llama-ui.service` | +| llama.cpp-Port | 8080, auf dem alten Host noch im LAN gebunden | +| Client-Port | 8081 über den Router | +| MCP-Konfiguration | `/etc/mike-ai/mcp-servers.json` | + +### Aktives Fast-Profil + +- Qwen3.8-27B IQ4-MIX +- Kontext 73.728 +- vollständig auf CUDA0 +- Flash Attention +- KV-Cache Q4_0 für K und V +- MTP Draft, maximal zwei Tokens +- sechs Threads und sechs Batch-Threads +- Batch 64, Micro-Batch 32 +- ein paralleler Slot +- Jinja und automatisches Reasoning +- Temperatur 0,2, Top-p 0,8, Top-k 20 + +### Profile + +| Profil | Virtuelles Modell | Kontext | Besonderheit | +|---|---|---:|---| +| Fast | `qwen-fast` | 73.728 | IQ4-MIX, MTP2, vollständig GPU | +| Medium | `qwen-medium` | 94.208 | IQ4_XS Pure, ohne MTP | +| Long | `qwen-long` | 131.072 | IQ4-MIX, MTP2, FFN-Blöcke 0–11 auf CPU | + +## Router + +- Dienst: `mike-ai-profile-router.service` +- Port: 8081 +- Upstream: `127.0.0.1:8080` +- Commit des Plattform-Repositories: siehe jeweils aktuelles `main` +- Umschaltskript: `/usr/local/bin/llama-profile` +- Timeout für Profilwechsel und Requests: 600 Sekunden + +Der Router übernimmt: + +- OpenAI-kompatibles Chat-Proxying und Streaming +- virtuelle Modelle und automatische Profilumschaltung +- Tool Calls +- Vision-Hotswap mit Cache für Folgefragen +- FLUX-Hotswap zur Bildgenerierung +- Whisper Speech-to-Text +- XTTS Text-to-Speech +- Zustands- und Modellendpunkte + +## Vision + +| Bereich | Referenz | +|---|---| +| Text-/Visionmodell | Qwen3.8-27B Q3_K_M | +| Projektor | BF16-mmproj | +| Kontext | 32.768 | +| temporärer Port | 8086 | +| maximale Ausgabe | 4.096 Tokens | + +Vision wird nicht dauerhaft parallel geladen. Der Router entlädt das +Textprofil, analysiert das Bild und stellt danach das ursprüngliche Profil +wieder her. + +## Bildgenerierung + +- Modell: FLUX.2 klein Base 4B +- Runtime: PyTorch/Diffusers +- CPU-Offload aktiviert +- Standard: 30 Schritte +- High: 50 Schritte +- Worker wird nach jedem Job vollständig beendet +- Qwen wird anschließend mit dem vorherigen Profil wiederhergestellt + +## Sprache + +### Whisper + +- Modell: large-v3-turbo +- lokale Standardsprache: Deutsch +- CPU-Ausführung +- acht Threads im produktiven Worker +- Port 8084, nur localhost +- ffmpeg für Eingabeumwandlung + +### XTTS + +- Modell: Coqui XTTS-v2 +- CPU-only +- Stimme: `claribel` +- Deutsch und Englisch +- Port 8085, auf dem alten Host noch im LAN gebunden +- eigenes Python-3.11-Venv + +## Websuche + +- Docker Compose +- SearXNG, per Digest gepinnt +- TinySearch 0.5.1, per Digest gepinnt +- TinySearch nur auf `127.0.0.1:8000` +- lokale ONNX-Embeddings +- kompakte Web-MCP-Fassade mit vier Werkzeugen +- strukturierte API-Pfade für GitHub und Hugging Face + +## MCP-Referenz + +Aktuell existieren funktionale Adapter für: + +- Websuche +- Home Assistant +- Sonarr/Radarr +- Unraid read-only +- eigener Unraid-Administrationsserver + +Der frühere allgemeine Shell-MCP und doppelte, schreibende Werkzeuge gehören +nicht zum Sicherheitsziel und werden nicht ungeprüft wiederhergestellt. + +## Bekannte Probleme des alten Hosts + +- Systempartition vollständig gefüllt +- Datenpartition nahezu vollständig gefüllt +- etwa 1,27 TB Modelle, darunter Duplikate +- mehrere alte llama.cpp-Builds +- RX-Dienste trotz ausgebauter Karte +- aktivierte Benchmark-/Race-Dienste +- alte systemd-Overrides und Sicherungskopien +- unvollständiger großer Modelldownload +- zu viele MCP-Werkzeuge gleichzeitig im Kontext + +Diese Punkte erklären den Neuaufbau, sind aber keine Bestandteile der neuen +Plattform. + +Zusätzliche bekannte Sicherheitsabweichung: llama.cpp auf Port 8080 und XTTS +auf Port 8085 sind im alten Zustand breiter gebunden als im Zielsystem. Beim +Neuaufbau werden beide auf localhost begrenzt; Clients verwenden ausschließlich +den Router auf Port 8081. diff --git a/docs/DISASTER_RECOVERY.md b/docs/DISASTER_RECOVERY.md new file mode 100644 index 0000000..cdc92c7 --- /dev/null +++ b/docs/DISASTER_RECOVERY.md @@ -0,0 +1,107 @@ +# Disaster Recovery und Abnahme + +## Definition „vollständig wiederhergestellt“ + +Eine Installation gilt erst dann als wiederhergestellt, wenn nicht nur Prozesse +laufen, sondern alle fachlichen Funktionen geprüft wurden. + +## Phase A – Basissystem + +- [ ] Betriebssystem und Kernel dokumentierter Stand +- [ ] Uhrzeit, Zeitzone und NTP korrekt +- [ ] Netzwerk nach Neustart automatisch verfügbar +- [ ] NVIDIA-Treiber geladen +- [ ] RTX und kompletter VRAM sichtbar +- [ ] System- und Modelllaufwerk korrekt gemountet +- [ ] mindestens 15 Prozent frei auf dem Systemlaufwerk +- [ ] Docker und Compose funktionieren +- [ ] keine RX- oder Benchmark-Altlast aktiviert + +## Phase B – Textmodell + +- [ ] llama.cpp entspricht dem festgelegten Commit +- [ ] Modelldateien stimmen mit SHA256 überein +- [ ] Fast startet mit 73.728 Kontext +- [ ] Medium startet mit 94.208 Kontext +- [ ] Long startet mit 131.072 Kontext +- [ ] GPU-/CPU-Verteilung entspricht den Profilen +- [ ] Fast erreicht den festgelegten Geschwindigkeitstoleranzbereich +- [ ] MTP funktioniert und verursacht keine Qualitätsregression +- [ ] Rolling-/Kontextverhalten ist bewusst definiert und getestet + +## Phase C – Router + +- [ ] `/status` meldet den richtigen Upstream +- [ ] `/v1/models` liefert drei virtuelle Modelle +- [ ] `/fast`, `/medium` und `/long` wechseln zuverlässig +- [ ] automatischer Wechsel über virtuellen Modellnamen funktioniert +- [ ] paralleler Wechsel wird sauber gesperrt +- [ ] Streaming funktioniert +- [ ] Tool Calls funktionieren +- [ ] Fehler sind OpenAI-kompatibel +- [ ] ein abgebrochener Client hinterlässt keinen blockierten Job + +## Phase D – Web und MCP + +- [ ] SearXNG und TinySearch gesund +- [ ] Websuche liefert kompakte, quellengebundene Ergebnisse +- [ ] GitHub- und Hugging-Face-Routing geprüft +- [ ] Home Assistant read-only Diagnose geprüft +- [ ] ARR read-only Suche geprüft +- [ ] Unraid read-only Diagnose geprüft +- [ ] schreibende Werkzeuge standardmäßig nicht geladen +- [ ] Tool-Schemas bleiben innerhalb des festgelegten Kontextbudgets +- [ ] kein Secret erscheint in Toolantworten oder Logs + +## Phase E – Vision, Bild und Sprache + +- [ ] neues Bild löst genau einen Vision-Hotswap aus +- [ ] Folgefrage verwendet Cache und keinen zweiten Hotswap +- [ ] Bilddaten werden vor dem Textmodell sanitisiert +- [ ] Qwen-Profil wird nach Vision wiederhergestellt +- [ ] FLUX erzeugt Standard- und High-Bild +- [ ] Qwen-Profil wird nach FLUX wiederhergestellt +- [ ] Whisper transkribiert deutsche und englische Testdatei +- [ ] XTTS erzeugt deutsche WAV- und MP3-Ausgabe +- [ ] STT/TTS blockieren das Textmodell nicht unzulässig + +## Phase F – Sicherheitsprüfung + +- [ ] Port 8080 von normalen Clients nicht erreichbar +- [ ] Hilfsports nur localhost +- [ ] Router nur aus erlaubtem Netz erreichbar +- [ ] Dienste laufen mit minimalen Rechten +- [ ] Environment-Dateien Modus 0600 +- [ ] kein allgemeiner Shell-MCP im Standardprofil +- [ ] Schreibaktionen verlangen Vorschau und Approval Ticket +- [ ] Secret-Restore wurde ohne Klartextausgabe durchgeführt + +## Phase G – Fachlicher Benchmark + +Der gespeicherte Standardbenchmark wird mindestens mit Fast und Long ausgeführt: + +- Home-Assistant-Automatisierung analysieren +- Logs lesen und Fehlerursache begründen +- sichere Korrektur vorschlagen +- Webrecherche mit Quellen durchführen +- Docker-/Unraid-Diagnose simulieren +- Tool-Limits, Halluzinationen und unnötige Aufrufe bewerten + +Die neue Installation muss innerhalb einer vorher festgelegten Toleranz zur +Referenz liegen. Nur „Dienst läuft“ genügt nicht. + +## Recovery-Protokoll + +Für jeden Wiederaufbau werden festgehalten: + +- Datum +- verwendeter Repository-Commit +- Modellmanifest-Version +- Hardware +- Dauer je Phase +- Abweichungen +- Testergebnis +- verantwortliche Freigabe + +Erst nach Abschluss aller Pflichtpunkte darf der alte Host gelöscht oder als +Fallback außer Betrieb genommen werden. diff --git a/docs/RECOVERY_REQUIREMENTS.md b/docs/RECOVERY_REQUIREMENTS.md new file mode 100644 index 0000000..1a741ba --- /dev/null +++ b/docs/RECOVERY_REQUIREMENTS.md @@ -0,0 +1,188 @@ +# Noch benötigte Wiederherstellungsartefakte + +Diese Liste definiert, was vor einer Löschung oder grundlegenden Änderung des +alten Hosts noch gesichert beziehungsweise präzisiert werden muss. + +Statuswerte: + +- **gesichert**: vollständig im Git oder anderweitig reproduzierbar +- **offen**: muss vor dem Neuaufbau erledigt werden +- **lokal geheim**: darf nicht unverschlüsselt ins Git + +## 1. Modelle und Prüfsummen – offen, höchste Priorität + +Für jedes tatsächlich benötigte Modell werden erfasst: + +- exakte Downloadquelle und Repository-ID +- Revision oder Commit +- Dateiname und Splitreihenfolge +- Dateigröße +- SHA256 jeder Datei +- Lizenz +- Zielpfad +- zugehöriger mmproj/MTP-Tensor +- getestete Runtime und Profilzuordnung + +Das Ergebnis wird als `platform/models/manifest.local.yaml` erzeugt. Die Datei +enthält keine Geheimnisse, kann aber wegen möglicher privater Quellen zunächst +lokal bleiben. Eine bereinigte Fassung gehört anschließend ins Git. + +Pflichtrollen: + +- Qwen Fast/Long IQ4-MIX +- Qwen Medium IQ4_XS Pure +- Qwen Q3 Vision +- BF16 Vision-Projektor +- Whisper large-v3-turbo +- FLUX.2 klein +- XTTS-v2 und verwendete Stimme + +## 2. Externe Komponenten und Commits – offen + +Für jedes separate Projekt benötigen wir Repository und Commit: + +- Home-Assistant-MCP +- ARR-MCP +- Unraid read-only MCP +- gegebenenfalls eigener Unraid-Administrations-MCP +- LLama-GUI, falls sie erhalten bleibt + +Jede Komponente bekommt zusätzlich: + +- Installationsbefehl +- Systembenutzer +- systemd-/Docker-Datei +- Health-Check +- benötigte Environment-Namen ohne Werte +- Liste read-only und schreibender Werkzeuge + +## 3. Basissystem-Bootstrap – offen + +Ein idempotentes Bootstrap-Skript muss noch erstellen: + +- Paketquellen und benötigte Debian-Pakete +- NVIDIA-Treiber und exakte Version +- CUDA Toolkit und Buildabhängigkeiten +- Docker und Compose +- Python 3.13 und Python 3.11/uv +- Dienstbenutzer und Gruppen +- Verzeichnisse, Eigentümer und Dateirechte +- Firewallregeln +- Journalgrößenlimit +- automatische Sicherheitsupdates nach bewusstem Freigabemodell + +Das Skript darf weder formatieren noch Modelle löschen. Destruktive +Speicheroperationen bleiben ein separater, ausdrücklich bestätigter Schritt. + +## 4. Secret-Verfahren – lokal geheim + +Benötigt wird ein festes Verfahren für: + +- Home-Assistant-Token +- Sonarr-/Radarr-API-Schlüssel +- Unraid-Zugang +- optionale GitHub-, Hugging-Face- und Brave-Schlüssel +- SSH-Hostschlüssel und bekannte Hosts + +Noch festzulegen: + +- verschlüsseltes Backupformat, beispielsweise age oder ein Passwortmanager +- Besitzer und Rechte je Environment-Datei +- Rotation und Widerruf +- Restore ohne Ausgabe der Werte in Terminal- oder Modellkontext +- Funktionstest mit ausschließlich Statuscode, niemals Tokenanzeige + +## 5. Netzwerk und DNS – offen + +Dokumentiert werden müssen: + +- endgültiger Hostname +- statische Adresse oder DHCP-Reservierung +- DNS-Name +- erlaubte Client-Netze +- Firewallmatrix pro Port +- TLS/Reverse Proxy, sofern verwendet +- Verhalten bei Neustart und fehlendem Netzwerk + +Zielmatrix: + +| Port | Zugriff | +|---:|---| +| 22 | nur Administration | +| 8080 | localhost | +| 8081 | vertrauenswürdiges LAN/VPN | +| 8084 | localhost | +| 8085 | localhost | +| 8000 | localhost | +| 5240 | optional nur Administration | + +## 6. Speicherlayout – offen + +Vor dem Neuaufbau festlegen: + +- System, Modelle, Caches und Ergebnisse auf getrennten Mounts +- Dateisystem des Modelllaufwerks +- Mindestreserve und Warnschwellen +- Docker-Datenpfad +- Hugging-Face- und Python-Cachepfade +- Backupziel +- Aufbewahrungsregeln für Bilder, Audio und Logs + +Empfehlung: System unter 85 Prozent, Modelllaufwerk unter 90 Prozent halten. + +## 7. Runtime-Locks – teilweise gesichert + +Bereits gesichert: + +- llama.cpp-Commit +- zentrale Python-Versionen für FLUX und XTTS +- TinySearch-/SearXNG-Image-Digests + +Noch offen: + +- vollständiges `pip freeze` je produktivem Venv +- CUDA-kompatible Wheel-Quelle +- FLUX-Revision +- XTTS-Modellrevision +- Whisper-Commit und Buildoptionen +- Docker-Engine-/Compose-Version + +## 8. Betriebsdaten und Aufbewahrung – offen + +Festlegen, welche Daten persistent sein sollen: + +- generierte Bilder: standardmäßig zeitlich begrenzt +- Audiodateien: standardmäßig nicht dauerhaft +- Vision-Cache: flüchtig +- Chatverläufe: nicht Bestandteil dieser Plattform +- Benchmarkresultate: eigenes Repository +- Logs: ohne Prompt- und Tool-Antwortinhalte + +## 9. Ende-zu-Ende-Installer – offen + +Der gewünschte Endzustand ist: + +```text +bootstrap-host +install-runtime +verify-model-manifest +install-platform +restore-secrets +enable-selected-mcp-profiles +run-acceptance-tests +``` + +Jeder Schritt muss wiederholbar, einzeln prüfbar und bei Fehlern abbrechbar +sein. Ein fehlgeschlagener Schritt darf keinen halb aktivierten Dienst +hinterlassen. + +## 10. Dokumentations-Abnahmekriterium + +Der alte Host darf erst verworfen werden, wenn eine fachkundige Person mit: + +1. diesem Repository, +2. den dokumentierten Modellquellen, +3. dem verschlüsselten Secret-Backup + +einen leeren Host ohne Wissen aus früheren Chats vollständig in Betrieb nehmen +kann.