# Athena – Betriebsanleitung

Stand: **20. September 2026**, auf Athena geprüft. Die fünf Textprofil-Images
tragen **llama.cpp b29c606** (0.4.1).
Der [geprüfte Live-Stand](docs/LIVE_STATE.md) beschreibt Profile, GPUs und die
Abweichung zwischen dem bereitgestellten Stack und dem Git-Checkout.
Der [Updatebericht vom 15. September](docs/UPDATE_AUDIT_20260915.md)
enthält die aktuellen Build- und Testbelege. Der ältere
[b10930-Bericht](docs/LLAMA_B10930_UPDATE_20260912.md) dokumentiert einen
früheren Stand und ist keine aktuelle Startanleitung.


Diese Datei ist der kurze, verbindliche Einstieg für Menschen und Agenten.

## Rolle

Athena ist eine Inferenzmaschine, kein allgemeiner Anwendungsserver.

Sie betreibt:

- llama.cpp mit genau einem aktiven Qwen-Profil,
- den OpenAI-kompatiblen Profile Router,
- FLUX.2 Klein 9B FP8 Beta für Textbilder und Referenzbild-Bearbeitung,
- Qwen3-TTS und TTS-Gateway für Sprache,
- Whisper.cpp und die WebRTC-Brücke für OpenClaw Talk,
- die GPU-lose Mikes-Applio-UI als gesonderten Checkout,
- das Athena-Dashboard,
- Portainer CE als optionale Ansicht auf die laufenden Docker-Container,
- WireGuard-Gateway und Datenbackup,
- den hostgebundenen Athena-Operator.

Hermes, OpenClaw und portable Fach-MCPs laufen auf Unraid. Auf Athena
werden keine zweiten Instanzen dieser Dienste angelegt.

## Pfade

| Pfad | Zweck |
|---|---|
| `/opt/mike-ai/stack` | kanonischer Checkout und Compose-Stack |
| `/data/models` | Modellgewichte |
| `/data/llama-dashboard` | historische Dashboard-Messwerte |
| `/data/docker-backups` | automatische Athena-Backups |
| `/etc/mike-ai` | lokale Konfiguration und Secrets, niemals Git |

Portainer läuft als separater, optionaler Verwaltungscontainer
`mike-ai-portainer`, hat einen eigenen Netzwerk-Namespace im Netz `mike-ai_frontend` und
ist unter `https://192.168.1.212:9443` erreichbar. Seine Einstellungen liegen
im Docker-Volume `portainer_data`, das vom Athena-Backup mitgesichert wird.
Portainer beobachtet beziehungsweise
verwaltet Docker, ist aber keine Abhängigkeit des Inferenz-Stacks.

## Standardbefehle

```bash
cd /opt/mike-ai/stack
./manage.sh validate
./manage.sh deploy SERVICE
./manage.sh deploy core
sudo ./smoke-test.sh
```

`deploy SERVICE` verwendet `--no-deps` und fasst keine anderen Container an.
`deploy core` aktualisiert den vollständigen Athena-Kern. Das aktuell aktive
Qwen-Profil wird vom Profile Controller verwaltet.

## Debian-Updates und NVIDIA

`linux-image-amd64` und `linux-headers-amd64` müssen **beide** installiert
bleiben. Das Header-Metapaket zieht bei Kernel-Updates die passenden Header
mit; erst damit kann DKMS das NVIDIA-Modul für den neuen Kernel bauen.
Der Installer installiert es bereits mit den Basispaketen. Vor einem vom
Betreiber geplanten Neustart nach `apt upgrade` prüfen:

```bash
uname -r
dpkg -l linux-image-amd64 linux-headers-amd64 nvidia-kernel-open-dkms
dkms status
```

Nach dem Neustart müssen `nvidia-smi` beide GPUs anzeigen. Docker-Container,
die beim Boot wegen eines fehlenden Treibers nicht starten konnten, starten
trotz `restart: unless-stopped` nicht zwingend von selbst nach; ihren Status
gesondert prüfen. Das Dashboard läuft im `control`-Netz und wird vom
WireGuard-Gateway auf Port 8099 bereitgestellt; es teilt dessen Namespace
nicht direkt. Kein automatischer Host-Neustart ist vorgesehen.

## Modelle

- Fast: kurze, interaktive Aufgaben
- Medium/Large/Ultra: steigende Kontextgrößen desselben lokalen Qwen-Modells
- Uncensored: separates lokales Profil
- FLUX.2 Klein 9B FP8 Beta: Bildgenerierung und Editing; Qwen wird dafür kurz entladen und danach
  automatisch wiederhergestellt
- Qwen3-TTS 1.7B: RTX 3060; kein Piper-Fallback

Die geprüften Live-Werte stehen in [docs/LIVE_STATE.md](docs/LIVE_STATE.md).
`config/profile-matrix.json` und `docs/STANDARD_PROFILE_MATRIX.md` im Repository
enthalten zusätzlich `beta1`, das auf Athena nicht installiert ist.

Die [Optimierungs-TODO](docs/INFERENCE_OPTIMIZATION_TODO_20260920.md) hält die
nächsten vier Inferenzvergleiche fest. Der
[ByteShape-A/B-Bericht](docs/QWEN38_BYTESHAPE_AB_20260920.md) dokumentiert
Qualität, Prefill, Generierung und getestete Textkontexte auf einer und zwei
GPUs. Die bestehenden Produktivprofile werden dadurch nicht ersetzt.

## Globale Modellrichtlinie

`config/global-system-policy.txt` wird vom Profile Router allen Textanfragen
über `/v1/chat/completions` und `/v1/responses` vorangestellt. Sie gilt damit
für alle Hermes-Profile und andere Clients, die den Athena-Router verwenden.
Der Router liest die Datei bei jeder Anfrage neu; spätere Textänderungen
benötigen nach der erstmaligen Bereitstellung keinen Container-Neustart.
Clients außerhalb des Routers und Werkzeuge, die ein Frontend nicht anbietet,
werden dadurch nicht erfasst.

## Werkzeuge

Portable Werkzeuge gehören auf Unraid in eigene, per DockerMan verwaltete
Container. Der einzige MCP auf Athena ist der Athena-Operator, weil nur er den
Athena-Host verwalten muss. Neue Fach-MCPs werden nicht in diesen Stack
eingebaut.

## Sicherheitsgrenze

**Athena niemals herunterfahren oder neu starten. Die Erreichbarkeit darf
nicht gefährdet werden.** Keine Änderungen an Host, Treibern, SSH, LAN oder
WireGuard im Rahmen eines Modell- oder Dokumentationsupdates.
Verbindlich sind die [Remote-Host-Regeln](docs/REMOTE_HOST_RULES.md).
Secrets dürfen lokal verwendet, aber nie in Git, Logs oder Chatantworten
veröffentlicht werden.

## Fertig bedeutet

- Änderung ist im kanonischen Git-Checkout,
- Compose und Syntax sind gültig,
- betroffener Dienst ist gesund,
- eine kleine Funktionsprobe war erfolgreich,
- Commit und Push sind erfolgt,
- das automatische Backup bleibt gesund.

## Verbindliche Benchmark-Referenz

Bei neuen Modelltests die [gesicherte Qwen-Referenz vom 20.09.2026](benchmarks/athena-qwen38-reference-20260920/README.md) verwenden. **Qwen nicht automatisch erneut benchmarken.** Das Paket enthält sieben Pure-/MIX-Fälle, Originalantworten, feste Requests, Modell-SHA256 und Laufzeit-/GPU-Konfiguration. Neue Kandidaten separat messen; notwendige Abweichungen dokumentieren. Nur bei begründetem Rekalibrierungsbedarf eine neue Referenzversion anlegen, bestehende Ergebnisse unverändert erhalten.

Abschluss des 20.09.: [Effizienz-/NVFP4-Prüfung](docs/ATHENA_EFFICIENCY_REVIEW_20260920.md). Pure/MIX bleiben produktiv; Medium startet nach abgefangenem GPU-Pufferfehler ohne Pipeline-Parallelisierung. Bei künftigem Tuning zuerst Speicherreserve und tatsächlichen Durchsatz prüfen. Native NVIDIA-NVFP4-Gewichte wurden nur auf Kapazität geprüft, nicht benchmarked.

[Microbatch-Folgetest](docs/MEDIUM_MICROBATCH_20260920.md): 256 lädt, unterschreitet aber die VRAM-Reserve (461 MiB frei auf 5080); keine Inferenzmessung mit 256. Produktiv bleibt 512, kein belegter Gewinn und keine automatische Folgeänderung.