143 lines
8.4 KiB
Markdown
143 lines
8.4 KiB
Markdown
# Athena Deck · Router 0.7
|
||
|
||
Eigenständige neue Oberfläche, Python-Standardbibliothek und HTML/CSS/JavaScript.
|
||
Keine Installation von Python-Paketen oder Frontend-Builds nötig. Python >= 3.10.
|
||
|
||
## Vorläufige Testinstallation auf Debian
|
||
|
||
Zielprodukt: nativer systemd-Dienst auf Debian. Der derzeitige Docker-Installer dient ausschließlich der isolierten Testphase.
|
||
|
||
Ein eigenständiger Testinstaller ohne WireGuard ist vorhanden: [Debian-Installation](INSTALL.md).
|
||
Auf dem Zielserver: `sudo ./install.sh --check`, anschließend `sudo ./install.sh --install`.
|
||
Vorhandenes Docker wird vorausgesetzt; produktive Dienste werden nicht verändert.
|
||
|
||
## Neu: Modellverwaltung und llama.cpp-Einstellungen
|
||
|
||
Katalog, Datei-Downloads, Bibliothek, serverseitig gespeicherte Profile und
|
||
llama.cpp-Buildverwaltung sind live. Der Download-Reiter erlaubt das Ausblenden
|
||
abgeschlossener Einträge ohne Dateiverlust. Entdecken zeigt Größen und eine
|
||
konservative Gewichts-Speicherprüfung; noch keine vollständige Laufzeitprognose.
|
||
Bildprofile mit vollständigem Qwen-Image-2.1-GGUF-Rezept lassen sich unter „Testen“ ausführen. Textprofile sind am eigenen [OpenAI-kompatiblen Endpunkt](ENDPOINT.md) ausführbar. Audio und Video sind noch nicht angebunden. Details: [Modellverwaltung](STUDIO.md).
|
||
|
||
## Zugang und API-Token
|
||
|
||
Beim ersten Öffnen werden Oberflächenkennwort und separater API-Token eingerichtet.
|
||
Beide sind unter **Zugang & API** änderbar. Der Debian-Installer richtet den Zugang vor dem Serverstart ein. Details und API-Rechte: [Zugangsverwaltung](ACCESS.md).
|
||
|
||
## WireGuard-Einstellungen
|
||
|
||
Das separate [WireGuard-Modul](network/README.md) enthält Conf-Import und
|
||
LAN-/Tunnel-Zugriff. In der aktuellen Debian-Entwicklungsinstanz ist es nicht
|
||
angebunden; der Zugriff erfolgt über SSH-Tunnel. Der bestehende Gateway bleibt unverändert.
|
||
|
||
## Zielsystem und Entwicklung
|
||
|
||
Athena Deck läuft vollständig auf einem Debian-Server mit RTX 5080 und RTX 3060.
|
||
Oberfläche, API, Router und Hardware-Erfassung laufen dort. Der Arbeitsplatz
|
||
benötigt nur Browser und SSH; er ist kein Anwendungsserver. Auch Builds und
|
||
Integrationstests werden auf Athena ausgeführt. Chat- und Qwen-Image-Laufzeiten sind am eigenen Endpunkt angebunden.
|
||
|
||
Die isolierte Entwicklungsinstallation ist in [DEVELOPMENT.md](DEVELOPMENT.md)
|
||
beschrieben. Hardware wird direkt über `/proc`, hwmon und nvidia-smi gelesen;
|
||
Deck benötigt dafür keinen SSH-Schlüssel. Der eigene Router ist in [ENDPOINT.md](ENDPOINT.md) dokumentiert.
|
||
|
||
## Interne API v1
|
||
|
||
Die GUI verwendet eine sitzungsgeschützte Verwaltungs-API. `GET /api/v1/status`
|
||
und `GET /api/v1/hardware` sind auch mit dem separaten API-Token lesbar.
|
||
Die Übersicht steuert den eigenen OpenAI-kompatiblen API-Listener; Demo-Dienst
|
||
und Demo-Routen wurden entfernt. Port, Profilfreigaben, Inferenzrouten,
|
||
Betriebsgrenzen und SSH-Tunnel: **[ENDPOINT.md](ENDPOINT.md)**.
|
||
|
||
Hardware: `available` bezeichnet Erfolg der Hardware-Abfrage, einzelne
|
||
Messwerte können trotzdem fehlen (`null`). Ein Ausfall der Erfassung liefert available=false,
|
||
leere Daten und eine Fehlermeldung, keine alten Werte als vermeintliches Livebild.
|
||
CPU-Auslastung: 250-ms-Differenz aus `/proc/stat` ohne doppelte Guest-Zählung.
|
||
RAM: MemTotal minus MemAvailable aus `/proc/meminfo`, Einheit Bytes.
|
||
CPU-Temperatur: k10temp/coretemp temp1_input, Grad Celsius.
|
||
GPU: nvidia-smi CSV mit Index, UUID, Name, VRAM in MiB, GPU-Auslastung in Prozent,
|
||
Temperatur in Grad Celsius. Keine Zuordnung nach vermuteter GPU-Reihenfolge.
|
||
Die Anzeige rechnet Speicher in GiB um. Fehlende Werte heißen „Nicht verfügbar“.
|
||
Abfrage bedarfsgesteuert mit fünf Sekunden Cache, GUI-Polling alle fünf Sekunden.
|
||
Keine Historie und kein Hintergrund-Collector bei geschlossener Hardware-Seite.
|
||
|
||
## Struktur und Grenzen
|
||
|
||
- `server.py`: Verwaltungs-API und lesende Hardware-Abfragen.
|
||
- `endpoint.py`: separater authentifizierter Inferenz-Listener.
|
||
- `inference.py`: native llama.cpp-Prozesse und gemeinsame GPU-Reservierung.
|
||
- `image_test.py`: eigene ComfyUI-Aufträge, gemeinsam mit dem Router koordiniert.
|
||
- `endpoint-ui.js`: Übersicht, Port und Profilfreigaben.
|
||
|
||
Sprachmodelle und Qwen-Image-Profile sind ausführbar. Audio-/Video-Laufzeiten
|
||
bleiben vorbereitet; weitere Docker-Dienste werden nur mit Deck-Labels angezeigt.
|
||
Der native systemd-Installer ist noch nicht vollständig; aktuell gilt der isolierte
|
||
Docker-Testinstaller. Keine Migration oder Steuerung des bisherigen Routers.
|
||
|
||
## Verifikation am 28.09.2026
|
||
|
||
`python3 -m unittest discover -s . -v`: drei Tests erfolgreich.
|
||
Zusätzlich GUI-Start → Läuft/Erreichbar → Stopp → Gestoppt/Nicht erreichbar geprüft.
|
||
Hardware im Browser mit Ryzen 5 5600, 46,9 GiB RAM, RTX 3060 und RTX 5080 geprüft;
|
||
CPU-/GPU-Temperaturen, VRAM und Auslastung vorhanden. Hardware-Ausfall im Test
|
||
simuliert, ohne Athena oder SSH zu unterbrechen.
|
||
Produktive Router-/Modell-/Bild-/Audio-/Netzwerkdienste nicht verändert.
|
||
Vorhandene ungesicherte Änderungen im übergeordneten Repository unangetastet.
|
||
|
||
### Bildlaufzeit installieren und Profile entfernen
|
||
|
||
Unter **Einstellungen → Laufzeiten → Bildgenerierung** zeigt Deck die Herkunft
|
||
und die festgelegten ComfyUI-/GGUF-Versionen. Fehlt die Umgebung, installiert
|
||
**Bildlaufzeit installieren** sie ohne Rootrechte in `state/image-runtime`.
|
||
Voraussetzungen: Linux, Python mit venv, Git, Internet und 25 GiB freier Speicher;
|
||
ein kompatibler NVIDIA-Treiber muss vom Systeminstaller bereitgestellt sein.
|
||
Die Installation ist abbrechbar, startet kein Modell und aktiviert die neue
|
||
Umgebung erst nach Paketprüfung. Bereits mitgelieferte Umgebungen werden erkannt;
|
||
ein Versionsupdate der Bildlaufzeit ist hier noch nicht vorgesehen.
|
||
|
||
Profile lassen sich in allen Kategorien löschen. Modell- und Komponentendateien
|
||
bleiben erhalten. Die API verhindert das Löschen des gerade ausgeführten
|
||
Bildprofils und prüft die Profilrevision gegen zwischenzeitliche Änderungen.
|
||
|
||
Neue sitzungsgeschützte API-Routen: `GET /api/v1/image-runtime`,
|
||
`POST /api/v1/image-runtime/install` und `/cancel` mit `{}` sowie
|
||
`POST /api/v1/profiles/delete` mit `{ "id": "…", "revision": 1 }`.
|
||
POST benötigt wie die übrigen Verwaltungsaktionen `X-Athena-Deck: 1`.
|
||
|
||
Die Hardware-Seite zeigt GPU-Rechenlast und VRAM-Belegung mit separaten Balken.
|
||
Es sind Host-Gesamtwerte einschließlich anderer Dienste. Der Bild-Textencoder arbeitet auf der RTX 3060, Bildmodell und VAE auf der
|
||
RTX 5080. CPU/System-RAM bleiben für Laden und Offload beteiligt. Beide GPUs
|
||
müssen frei sein; es gibt keinen stillen CPU-Fallback. GPU-Last kann während
|
||
Vorbereitung und Laden null sein. Nach Abschluss beendet Deck den eigenen Worker und gibt dessen VRAM frei.
|
||
|
||
Unter **Entdecken** steht zusätzlich **Neu hinzugefügt** zur Verfügung. Die
|
||
Abfrage sortiert bereits auf Hugging Face nach dem Erstellungsdatum des
|
||
Repositories absteigend; sie sortiert nicht nur die beliebtesten 20 Treffer um.
|
||
Name A–Z sortiert weiterhin die angezeigte Treffermenge.
|
||
|
||
Prüfung vorhandener Studios: [Native Anwendungen und Docker](docs/NATIVE_APPLICATION_AUDIT.md).
|
||
|
||
### Optionale Docker-Anwendungen
|
||
|
||
Einstellungen → Laufzeiten → Docker zeigt Verbindung, Version und gegebenenfalls
|
||
Docker-Erstinstallation. Weitere Dienste zeigt ausschließlich Container mit
|
||
`io.athena-deck.managed=true` **und** `io.athena-deck.role=application`.
|
||
Bestehende Container werden nicht automatisch übernommen. Details zu Systemhelfer,
|
||
Installer und Grenzen: [Docker-Dienste](docs/DOCKER_SERVICES.md).
|
||
|
||
Unter Entdecken blendet **Nur Basismodelle** anhand von `base_model`,
|
||
`base_model_relation` und Hub-Tags gekennzeichnete Ableitungen aus (Finetunes,
|
||
Adapter/LoRAs, Merges und separate Quantisierungen). Es werden bis zu 100 nach
|
||
der gewählten Sortierung gelieferte Kandidaten geprüft und maximal 20 angezeigt.
|
||
Die Einstellung bleibt im Browser über Kategorien hinweg erhalten. Fehlende
|
||
Herausgeber-Metadaten können dazu führen, dass Ableitungen sichtbar bleiben;
|
||
es handelt sich nicht um eine verifizierte Liste offizieller Herausgeber.
|
||
API-Parameter: `GET /api/v1/catalog/search?...&base_only=true`.
|
||
|
||
Die Suche akzeptiert auch `owner/repository` und direkte Hugging-Face-Repository-
|
||
URLs. Eine solche Direktauswahl umgeht Kategorie- und Basismodellfilter mit einem
|
||
sichtbaren Hinweis. Bei GGUF-Dateinamen wird die Endung für die Repositorysuche
|
||
entfernt. Findet die Chat-Suche nichts, werden zusätzlich als `conversational`
|
||
gekennzeichnete GGUF-Repositories ohne `text-generation`-Tag geprüft. Das ist
|
||
keine globale Suche nach beliebigen Dateinamen im Hub.
|