144 lines
7.8 KiB
Markdown
144 lines
7.8 KiB
Markdown
# Entwicklung auf Athena (Debian)
|
|
|
|
Zielsystem: Debian 13, RTX 5080 und RTX 3060. Der Arbeitsplatz dient nur als
|
|
Editor/SSH-Client und Browser. Die Anwendung und ihre Tests laufen auf Athena.
|
|
|
|
- Quellcode: `/opt/athena-deck-dev/source`
|
|
- Eigener Container: `athena-deck-dev`
|
|
- Zustand und Installationsmanifest: `/opt/athena-deck-dev/runtime`
|
|
- Serverbindung: ausschließlich `127.0.0.1:8108`
|
|
- GPU-Zugriff: NVIDIA `compute,utility` für Telemetrie und Fit-Prüfung; keine Modellstarts.
|
|
|
|
Vom Arbeitsplatz:
|
|
|
|
```sh
|
|
ssh -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes -N -o ExitOnForwardFailure=yes -L 8108:127.0.0.1:8108 root@192.168.1.212
|
|
```
|
|
|
|
Browser: http://127.0.0.1:8108 . Die Adresse führt durch den Tunnel zum Server.
|
|
Beim ersten Öffnen neue Zugangsdaten einrichten. Vorhandene Zugangsdaten werden
|
|
nicht vom Arbeitsplatz übertragen. Browser-Profilentwürfe bleiben bei gleicher
|
|
Adresse erhalten. Nur diese isolierte Entwicklungsinstanz erlaubt die einmalige
|
|
Browser-Einrichtung über den SSH-Tunnel (`development_setup` im Manifest).
|
|
Der normale Debian-Installer provisioniert weiterhin vor dem Start.
|
|
|
|
Auf Athena:
|
|
|
|
```sh
|
|
cd /opt/athena-deck-dev/source
|
|
./install.sh --status --directory /opt/athena-deck-dev/runtime
|
|
./install.sh --stop --directory /opt/athena-deck-dev/runtime
|
|
./install.sh --start --directory /opt/athena-deck-dev/runtime
|
|
# Nach gezielter Aktualisierung der Quelldateien:
|
|
./install.sh --update --directory /opt/athena-deck-dev/runtime
|
|
python3 -m unittest discover -s . -v
|
|
```
|
|
|
|
Diese Befehle verwalten ausschließlich den eigenen, per Label geprüften
|
|
Deck-Container. Produktiver Router, Modelle, WireGuard und Hostkonfiguration
|
|
werden nicht verändert. Kein Docker-Socket im Webcontainer.
|
|
|
|
Profile und llama.cpp-Build/Update sind weiterhin GUI-Entwürfe. Die Netzwerk-Erweiterung ist in dieser Installation deaktiviert.
|
|
Das Verschieben der Entwicklung aktiviert keine dieser Funktionen automatisch.
|
|
|
|
## Verbindliche Zielarchitektur
|
|
|
|
Das Produkt wird ein nativer Debian-systemd-Dienst unter eingeschränktem Benutzer.
|
|
Docker ist ausschließlich die vorläufige Testverpackung. Katalog, Downloads und
|
|
spätere Worker-Adapter dürfen Docker nicht voraussetzen. Kein Docker-Socket und
|
|
keine Hostprozesssteuerung über Docker. Der vorhandene WireGuard-Container bleibt
|
|
unverändert; Zugriff derzeit über SSH-Tunnel.
|
|
|
|
## Live-Funktionen ab 0.5
|
|
|
|
Hugging-Face-Suche nach Bereich, feste Repository-Revision, Dateiauswahl und
|
|
serieller Download öffentlicher GGUF-/Safetensors-/JSON-Dateien. Eigener Ordner
|
|
`runtime/state/models`; Fortschritt, Abbruch, 10 GiB Speicherreserve, Größenprüfung
|
|
und bei vorhandenem LFS-Prüfwert SHA-256-Abgleich. Bei Neustart wird ein laufender
|
|
Download nicht fortgesetzt; unvollständige Dateien sind keine Bibliothekseinträge.
|
|
Keine automatische Ausführung heruntergeladener Dateien. Gated/private Modelle,
|
|
Paketauflösung, VRAM-/Kontextprognose und Worker-Starts fehlen noch.
|
|
|
|
Interne API (nur angemeldeter Administrator):
|
|
- GET `/api/v1/catalog/search?q=...&kind=chat|image|audio|video`
|
|
- GET `/api/v1/catalog/files?repo=owner/name`
|
|
- GET `/api/v1/catalog`: Bibliothek, Downloadstatus, freier Speicher
|
|
- POST `/api/v1/catalog/download`: repo, filename, revision, kind
|
|
- POST `/api/v1/catalog/cancel`: leeres JSON-Objekt
|
|
|
|
Anbieter-Dokumentation: https://huggingface.co/docs/hub/api . Audio-Suche filtert
|
|
zunächst Sprachausgabe; weitere Audioaufgaben folgen. Einzelne Dateien stellen
|
|
noch keine vollständige Installation eines mehrteiligen Modells dar.
|
|
|
|
Update-Sicherungen enthalten den Konfigurationszustand, nicht die heruntergeladenen
|
|
Modelldateien. Diese bleiben im persistenten Zustandsverzeichnis erhalten.
|
|
|
|
## Native Laufzeitverwaltung
|
|
|
|
`runtime.py` verwendet ausschließlich native Prozesse (git, cmake, llama-server),
|
|
keine Docker-API. Die Testverpackung enthält CUDA 12.8.1 und Build-Werkzeuge;
|
|
Debian-Host und Treiber werden nicht verändert. Build-Last ist auf 2 CPUs,
|
|
8 GiB RAM und maximal zwei Compiler-Jobs begrenzt. Builds liegen unter
|
|
`state/runtime`, werden nicht in Konfigurations-Backups dupliziert und bleiben
|
|
bei Updates erhalten. Geprüfte Versionen können als Standard ausgewählt und
|
|
zurückgeschaltet werden; das startet kein Modell.
|
|
|
|
GET `/api/v1/runtime`, `/prerequisites`, `/releases`, `/log`; POST `/build`
|
|
(revision, backend, jobs), `/cancel` ({}), `/activate` (build_id), `/rollback` ({}),
|
|
jeweils unter `/api/v1/runtime`. Nur Administratorsitzungen sind zugelassen.
|
|
Release-Quellen: https://github.com/ggml-org/llama.cpp/releases .
|
|
|
|
Die feste VRAM-Reserve entfällt. Die Buildprüfung ermittelt die tatsächliche
|
|
Unterstützung von `--fit`; modellbezogene Layer-/Kontextprognose wird über das unten beschriebene
|
|
Fit-Werkzeug bereitgestellt. Modellstarts sind noch nicht angebunden. Keine erfundenen Schätzungen,
|
|
keine absichtlichen OOM-Versuche und keine Eingriffe in produktive Worker.
|
|
|
|
### Auto-Einpassung mit den bisherigen Routermodellen
|
|
|
|
`llama-fit-params` wird mitgebaut. GET `/api/v1/runtime/references` liefert die
|
|
am 28.09.2026 aus dem alten Router gelesenen Profile Fast/Medium/Large/Ultra/
|
|
Uncensored. POST `/api/v1/runtime/fit` nimmt profile, context und slots entgegen.
|
|
Die drei GGUF-Dateien werden einzeln und nur lesend in den Testcontainer
|
|
eingebunden (`reference_models` im Entwicklungsmanifest). Keine Kopie der
|
|
Gewichte, kein Zugriff auf Prompts oder Anwendungslogs.
|
|
|
|
Das offizielle Fit-Werkzeug verwendet `no_alloc` für Modellgewichte und liefert
|
|
eine Prognose anhand des aktuellen freien Speichers, q4_0-KV-Cache und explizitem
|
|
Kontext/Slots. Die automatische Reserve beträgt als Sicherheitsregel 5 % des jeweiligen
|
|
Gesamt-VRAM, mindestens 512 MiB. Karten mit weniger als 10 % freiem VRAM
|
|
(mindestens 1 GiB) werden vor CUDA-Initialisierung aus der Prüfung ausgeschlossen.
|
|
Diese Regeln sind Sicherheitsmargen, keine gemessene exakte Modellkapazität. Es findet kein OOM-Stresstest und kein Modellstart statt.
|
|
Eine Prognose ist keine Garantie unter wechselnder Parallelbelegung. Der native
|
|
Betrieb kann dieselben Dateien über DECK_REFERENCE_MODELS bereitstellen.
|
|
|
|
Fit-Adapter: Das Upstream-Fit-CLI bietet die Serveroption `--kv-unified` nicht an.
|
|
Deck setzt deshalb beim Build in `tools/fit-params/fit-params.cpp` vor der
|
|
Backend-Initialisierung explizit `params.kv_unified = true`, entsprechend den
|
|
bestehenden Profilen. Die Anpassung ist als `shared-kv-pool-v1` im Buildstand
|
|
vermerkt; die eigentliche Fit-Berechnung bleibt upstream. Fehlt der erwartete
|
|
Quellanker, bricht der Build ab, statt eine andere Semantik zu verwenden.
|
|
|
|
Die Fit-Prognose gilt zunächst für das Textmodell. Vision-Projektoren und MTP
|
|
der bisherigen Routerprofile sind nicht eingerechnet. Außerdem ersetzt sie keine
|
|
RAM-/Lastprüfung eines späteren Worker-Starts im begrenzten Testcontainer.
|
|
|
|
Verifikation: CUDA-Release b11229 (c2a9e1606807970f4ee3167bacd951699c89caea)
|
|
für 86/120 erfolgreich gebaut. Medium, 160000 Kontext, zwei Slots: echte
|
|
Fit-Prognose erfolgreich. Bei damaliger Parallelbelegung 0 GPU-Modelllayer;
|
|
GPU-Rechenpuffer 1044 MiB, Host Modell 13635 MiB, Kontext 3111 MiB, Compute
|
|
93 MiB. Das überschreitet das 8-GiB-RAM-Limit der Testinstanz und wird als
|
|
nicht startbar markiert. Keine Modellgewichte allokiert, alle zuvor vorhandenen
|
|
Container-Startzeiten unverändert. 46 Tests erfolgreich.
|
|
|
|
Der verifizierte Erstbuild liegt in `state/runtime-verification`;
|
|
`state/runtime/<Build-ID>` verweist intern darauf, damit seine Build-RPATHs
|
|
erhalten bleiben. Beide Verzeichnisse gehören ausschließlich Deck und bleiben
|
|
bei Updates bestehen. Künftige Builds entstehen direkt unter `state/runtime`.
|
|
|
|
## Installation als Produktanforderung
|
|
|
|
Der native Installer muss ein frisches Debian vollständig vorbereiten. Siehe
|
|
[verbindlicher Umfang und Abnahme](deploy/NATIVE_INSTALL_REQUIREMENTS.md).
|
|
Vorhandene Werkzeuge auf Athena dürfen nicht als allgemeine Voraussetzung
|
|
versteckt bleiben. Der Docker-Testinstaller ist kein fertiger nativer Installer.
|