Athena-Deck/STUDIO.md

# Modellverwaltung in Athena Deck

## Serverprofile, Downloads und Größen (2026-09-28)

Profile sind jetzt echte, serverseitig persistierte Konfigurationen in
`state/profiles.json`. Die Bibliothek bietet „Profil anlegen“ für heruntergeladene
Gewichtsdateien. Alle vier Bereiche unterstützen Anlegen, Bearbeiten und
Duplizieren. Namen sind global eindeutig; Änderungen werden anhand einer
Revisionsnummer gegen versehentliches Überschreiben geprüft. Frühere lokale
Browserentwürfe werden weder gelöscht noch automatisch als echte Profile importiert.

Bildprofile speichern Auflösung, Schritte, Seed und Guidance. Chatprofile
speichern Kontextbudget, Slots, Threads, Batch und Microbatch; Audio derzeit
Sprechgeschwindigkeit, Video Auflösung, Frames, FPS, Schritte und Seed.
Ein Profil startet noch keinen Worker. Fehlende Laufzeiten und bei Qwen-Image-2.1
Textencoder/VAE werden angezeigt. Auf Wunsch des Betreibers werden in diesem
Schritt keine Bildlaufzeiten oder Zusatzmodelle installiert.

Der Reiter Downloads zeigt die persistierte Downloadhistorie (`models/downloads.json`).
„Aus Liste entfernen“ blendet ausschließlich einen beendeten Eintrag aus, auch
über Neustarts hinweg. Es löscht keine Modelldatei und keinen Bibliothekseintrag.
Bestehende Bibliotheksdateien werden einmalig als abgeschlossene Downloads übernommen.
Unterbrochene Downloads bleiben erkennbar; noch kein Fortsetzen/Resume.
Abgeschlossene Downloads belegen nicht mehr dauerhaft die Entdecken-Ansicht.

Entdecken lädt Dateigrößen mit zwei parallelen Metadatenanfragen nach. Angaben
stammen aus Hugging Face und werden fünf Minuten gecacht (maximal 64 Repositories).
Die Übersicht bevorzugt GGUF-Hauptgewichte, schließt erkennbare Encoder/VAE/LoRA-
Dateien aus und summiert vollständig vorhandene Shards einer Variante.
Die angegebene Spanne enthält keine zusätzlichen Pipeline-Komponenten.

Die Speicherprüfung ist bewusst eine **Untergrenze für Gewichte**, keine vollständige
Lauffähigkeitsprognose: Dateigröße gegen jede GPU einzeln, insgesamt und aktuell frei,
mit 5 Prozent / mindestens 512 MiB Reserve. GPUs werden nicht pauschal addiert.
Die Dateiauswahl zeigt GPU-Werte, Messzeit und ein vorhandenes Deck-RAM-Limit.
KV-Cache, Kontext, Aktivierungen, Encoder/VAE und backendabhängige Formate bleiben
als unbekannter Zusatzbedarf gekennzeichnet. Ein positives Gewichts-Ergebnis
bedeutet nicht „Modell kann gestartet werden“.

API (Administrator-Sitzung erforderlich, bestehender CSRF-Schutz):
- `GET /api/v1/catalog/assessment?repo=owner/name`: Größenbereich und Gewichtsprüfung.
- `GET /api/v1/catalog/files?repo=owner/name`: zusätzlich Prüfung pro Datei.
- `GET /api/v1/catalog`: Bibliotheks-IDs und `downloads` neben aktivem `job`.
- `POST /api/v1/catalog/dismiss` mit `{ "id": "download-id" }`: beendeten Eintrag ausblenden.
- `GET /api/v1/profiles`: Profile, Blocker und Parameterschemata.
- `POST /api/v1/profiles/save`: `id` (bei Neuanlage null), `revision` (anfangs 0),
  `name`, `kind`, `model_id` und `parameters`. Die Modelldatei muss tatsächlich
  vollständig in der Bibliothek liegen. Keine beliebigen Pfade/Startbefehle.

Die eigenständig implementierte Galerie orientiert sich an [LocalAIs Explore-/Detailansicht](https://github.com/mudler/LocalAI/blob/master/core/http/react-ui/src/pages/Models.jsx). Kein LocalAI-Frontendcode wurde übernommen. llama.cpp-Buildverwaltung und Einpassung der alten Referenzprofile sind unter Einstellungen verfügbar; Details in DEVELOPMENT.md.

Validiert: 54 Python-Tests; JavaScript-Syntaxprüfung; isolierter Browsertest mit echten Katalogdaten und einer temporären Testdatei für Profilanlage, Komponentenhinweise und Download-Ausblenden. Keine produktiven Modellstarts.

## Laufzeiten und Zusatzkomponenten

Einstellungen → Laufzeiten bündelt `#runtime` (llama.cpp, bestehende aktive
Buildverwaltung) und `#image-runtime` (Bildgenerierung). Die Bildseite beschreibt
ComfyUI + ComfyUI-GGUF als vorgesehene Umgebung und zeigt ausdrücklich, dass noch
kein Deck-Bildworker installiert ist. Dieser Schritt installiert keine Laufzeit.

Bildgenerierung → Profile → Komponenten bietet für
`abenzerps/Qwen-Image-2.1-Uncensored-GGUF` ein explizites Rezept gemäß Modellkarte:
Textencoder INT8 ConvRot oder BF16, dazu Qwen-Image-2.1-VAE BF16. Größen und feste
Quellrevision werden beim Öffnen aus dem öffentlichen Repository gelesen.
Downloads laufen über die vorhandene geprüfte Katalog-API und erscheinen unter
Downloads. Danach „Bibliothek aktualisieren“, je eine Datei auswählen und
„Zuordnung auf Athena speichern“. Mehrere Profile können dieselben Dateien nutzen.

Die Zuordnung ist kein Nachweis eines funktionierenden Workers. Andere Modelle
bekommen ohne hinterlegtes Rezept keine behauptete automatische Kompatibilität.
Textencoder/VAE werden nicht als Hauptmodell des Qwen-Profils zugelassen.
Zuordnungen bleiben bei Parameteränderungen erhalten; bei Wechsel des Hauptmodells
werden sie zurückgesetzt. Fehlende Dateien bleiben als Blocker sichtbar.

API (nur Administrator-Sitzung):
- `GET /api/v1/profiles/components?model_id=<Bibliotheks-ID>` liefert Rezept,
  verfügbare Dateien und Quellkandidaten.
- `POST /api/v1/profiles/components` mit `id`, `revision`, `components`
  (`text_encoder` und/oder `vae`: Bibliotheks-ID, leer zum Entfernen) speichert
  atomar mit Konfliktprüfung. Rollen und tatsächliche Dateien werden geprüft.

Validiert: 55 Tests und Browserprüfung der neuen Navigation und realen
Komponentenmetadaten. Keine Zusatzgewichte heruntergeladen, keine Modelle gestartet.

### Bibliotheksrollen

Bibliothek, Profilauswahl und Profil-API verwenden dieselbe serverseitige
Dateiklassifikation (`role`, `role_label`, `profile_eligible`). Erkannte
Textencoder, VAE, Projektoren und Adapter bleiben als Zusatzdateien sichtbar,
bieten aber kein „Profil anlegen“ und können nicht als Hauptmodell gespeichert
werden. Bestehende Komponenten-Zuordnungen und Dateien bleiben unverändert.

## Bildgenerierung → Testen

Der Reiter Testen startet jetzt echte Qwen-Image-2.1-GGUF-Aufträge über einen
eigenen ComfyUI-Prozess. Profil wählen, Prompt eingeben, Bild generieren; danach
erscheinen Vorschau und PNG-Download. Auflösung, Schritte, CFG und Seed kommen
aus dem Profil. Zunächst ein Bild pro Auftrag, maximal 1024 × 1024, keine
Referenzbilder und keine öffentliche OpenAI-Bild-API. Der interne Admin-Endpunkt
ist ausreichend für die GUI.

- `GET /api/v1/image-tests`: Status der eigenen Laufzeit und des letzten Tests.
- `POST /api/v1/image-tests/start`: `{profile_id, prompt}`; Prompt 1–4000 Zeichen.
- `POST /api/v1/image-tests/cancel`: `{}`; beendet ausschließlich den eigenen Worker.
- `GET /api/v1/image-tests/image?id=<job-id>`: letztes fertiges PNG, Sitzung erforderlich.

Serialisierte Aufträge, eigene Prozessgruppe, 30-Minuten-Generierungslimit,
Abbruch und Entladen auch bei Fehlern. Der Textencoder läuft auf CPU; Diffusion
und VAE nutzen eine einzelne GPU. Vor dem Start werden RAM und GPU-Speicher
geprüft. Eine GPU mit vorhandenen Compute-Prozessen wird nicht verwendet; bei
einem weiteren Compute-Prozess während des Tests bricht Deck seinen Auftrag ab.
Das ist eine Schutzprüfung, keine exklusive Hardware-Reservierung gegenüber
fremden Prozessen. Produktive Router/Modelle werden nicht gesteuert.

Die eigene ComfyUI-HTTP-Schnittstelle bindet nur Container-/Prozess-Loopback auf
einem freien Port, ohne Host-Portfreigabe. Es werden keine Produktionspfade
verwendet. ComfyUI-Ausgaben werden nicht als Logs gespeichert. PNG-Promptmetadaten
sind deaktiviert; Jobstatus enthält keinen Prompt. Ergebnisse und temporäre
Worker-Dateien liegen privat unter `state/image-tests/`; die GUI zeigt nur das
letzte Ergebnis. Frühere Jobverzeichnisse bleiben bislang auf dem Datenträger.

Versionsgebundene Quellen: ComfyUI `8d534945ebd53cff61e8def81757c6a6c1b9cf2d`,
ComfyUI-GGUF `373048b8403a7820620065210a691263d4da0a61`, PyTorch 2.11.0 CUDA 12.8.
Python-Pakete sind in `deploy/image-requirements.lock` festgehalten. Eigenes
Virtualenv `/opt/deck-image-python`, ComfyUI `/opt/deck-comfy`. Der Docker-Installer
baut diese Umgebung mit ein; `image_runtime: true` im eigenen Installationsmanifest
setzt dafür 32 GiB RAM-Limit und 256 PIDs. CPU-Limit bleibt zwei Kerne.
Bestehende Installationen behalten ihre Ressourceneinstellung bis zur expliziten
Aktivierung. Keine NVIDIA-Treiber-/Hostinstallation im Container-Update.

Validierung: 63 Tests; reale isolierte Generierungen 512 × 512 / 2 Schritte und
1024 × 1024 / 25 Schritte. Letztere dauerte ca. 99 Sekunden, PNG visuell geprüft,
GPU danach wieder frei. Nutzerprofile unverändert. Die einfache Profil-/Prompt-/
Ergebnisanordnung orientiert sich an LocalAIs ImageGen-Seite, ohne deren Code zu kopieren.


### Chatprofile: GPU- und Sampling-Einstellungen

Der Profileditor speichert Kontextbudget, Slots, Batch/Microbatch, Temperature,
Top-p und Top-k sowie geordnete GPU-UUIDs, Split-Modus (`none`, `layer`, `row`)
und relative Verteilungsgewichte. Zwei GPU-Auswahlen zeigen die echten Kartennamen;
die Reihenfolge definiert die vorgesehenen logischen CUDA0/CUDA1-Geräte. UUIDs
verhindern Verwechslungen mit wechselnden nvidia-smi-Indizes. CPU-Threads stehen
unter „Erweitert“. Die Auswahl startet keinen Worker. Nach expliziter Freigabe am Endpunkt lädt
der eigene Router das Profil bei einer Chat-Anfrage; siehe [ENDPOINT.md](ENDPOINT.md). Die GPU-Verteilung ist keine Speicherzusage.

Medium aus der Referenztabelle: Kontext 160000 insgesamt für zwei Slots,
RTX 5080 zuerst, RTX 3060 danach, Layer-Split 85,15, Batch 2048, Microbatch 256,
Temperature 1.0, Top-p 0.95, Top-k 20. Fast: 76800, ein Slot, nur RTX 5080,
keine Aufteilung, Batch 2048, Microbatch 64, Temperature 0.2, Top-p 0.8, Top-k 20.

API `profiles/save`: zusätzliche Chat-Parameter `gpu_devices` (geordnete UUID-Liste),
`split_mode`, `tensor_split` (Zahlenliste), `temperature`, `top_p`, `top_k`.
Leere Geräte-/Gewichtelisten bedeuten automatische Auswahl/Verteilung.
Alte Profile bleiben lesbar; fehlende neue Felder erhalten bei Anzeige/Speichern
Standardwerte (automatische Geräte, keine Aufteilung, Temperature 0.8, Top-p 0.95,
Top-k 40). Bestehende Dateien werden beim Lesen nicht umgeschrieben.

Sprachmodelle besitzen jetzt den Reiter **Testen**: interner Textchat mit Streaming, Profilauswahl und Speicherdiagnose. Öffentliche Profilfreigabe ist dafür nicht erforderlich. Details: [ENDPOINT.md](ENDPOINT.md#sprachmodelle--testen).

### MTP bei Sprachmodellprofilen

Im Profileditor kann MTP aktiviert werden, mit 1–8 Draft-Token und Mindestwahrscheinlichkeit 0–1. Medium-Referenz: 2 und 0,05; Draft-KV ist f16. Bestehende Profile bleiben standardmäßig ohne MTP. Das Modell muss eingebettete MTP-Gewichte enthalten. Der CUDA-Build benötigt den Deck-MTP-Fit-Adapter; neue GUI-Builds installieren ihn automatisch. Die Prognose zählt die gemeinsamen Gewichte einmal sowie Haupt- und MTP-Kontext und deren Compute-Puffer. Ein inkompatibles Modell oder ein alter Build wird nicht still ohne MTP gestartet. MTP garantiert keinen Geschwindigkeitsgewinn.

GPU-Ausführung: „Automatisch“ darf bei Platzmangel Schichten auf die CPU verlagern. „Vollständig auf GPU“ verlangt alle Schichten einschließlich Ausgabe und bricht sonst vor dem Laden ab. Die Prognose lässt je GPU mindestens 512 MiB bzw. 2,5 % Gesamtspeicher frei (der größere Wert gilt); keine Garantie für beliebige Last. Die Chat-Diagnose kennzeichnet eine begrenzte Layerzahl.