# Arbeitsentwurf

**Dokumenten-ID:** GNENC-001-PLAN
**Titel:** CPU-basiertes Video-Encoding auf dem KI-Server
**Stand:** 2026-10-05
**Status:** Nicht finaler Arbeitsentwurf zur Persistierung der Planungsentscheidung

## 1. Zweck und Abgrenzung

Der physische Server `ghostnet-ki` soll neben den KI-Workloads einen getrennten
Workload zum Encoding von Videodateien ausführen. Der Encoding-Workload gehört
nicht zum LLM-Stack. Seine fachliche Architektur, Bedienung und späteren SOPs
werden deshalb in diesem eigenen Dokumentationsbereich geführt.

Ansible, Podman, Betriebssystem und hostweite Ressourcenregeln bleiben
gemeinsame Plattformbestandteile. Sie werden weiterhin ausschließlich im
Infrastructure-Repository verwaltet, damit nicht mehrere Repositories
unabhängig konkurrierende Sollzustände auf denselben Host anwenden.

## 2. Bestätigte Entscheidungen

| Thema | Entscheidung | Nachweisgrenze |
| --- | --- | --- |
| Repository | Host- und Deployment-Ansible bleibt im bestehenden Infrastructure-Repository | angenommen |
| Dokumentation | Encoding liegt unter `docs/platform/llm-server/encoding/` und verwendet die Kennung `GNENC` | umgesetzt |
| Ausführungsidentität | eigenes gesperrtes Konto `gn-encoding`, UID/GID 982 | eingerichtet und mit rootless Podman geprüft |
| Containertrennung | eigener rootless Podman-Store und eigener rootverwalteter Quadlet-Pfad | eingerichtet; noch keine Workload definiert |
| Rechenressource | Encoding ist nach Betreiberfestlegung rein CPU-basiert und erhält keinen GPU-Zugriff | Planungsentscheidung; reale Last noch nicht gemessen |
| Parallelität | darf parallel zu AI Production oder AI Testing laufen | Planungsentscheidung |
| Zeitsteuerung | automatische Ausführung ausschließlich außerhalb der Stoßzeiten, zunächst nachts | Richtung festgelegt; konkrete Uhrzeiten fehlen |
| Anwendungen | konkrete Encoder, Images, Profile und Queue sind noch nicht gewählt | offen |

## 3. Zielbild

```mermaid
flowchart LR
    HOST[ghostnet-ki]
    PROD[gnai-production\nrootless Podman]
    TEST[gnai-testing\nrootless Podman]
    ENC[gn-encoding\nrootless Podman]
    GPU[beide GPUs]
    CPU[CPU / I-O Budget]
    TIMER[nächtliche systemd-Zeitsteuerung]

    HOST --> PROD
    HOST --> TEST
    HOST --> ENC
    PROD --> GPU
    TEST --> GPU
    ENC --> CPU
    TIMER --> ENC
```

AI Production und AI Testing bleiben untereinander exklusiv. Der
Encoding-Workload ist von dieser KI-Umschaltung unabhängig und darf parallel
zur jeweils aktiven KI-Umgebung laufen. Hostwartung kann weiterhin einen Stopp
aller Workloads erfordern.

## 4. Ressourcen- und Zeitsteuerung

Die nächtliche Einplanung allein schützt Production nicht vollständig: Ein
Encoding-Lauf kann länger dauern als sein Startfenster, und Inferenz benötigt
trotz GPU-Schwerpunkt CPU für Tokenisierung, Netzwerk und Begleitdienste. Die
spätere Encoding-Unit soll deshalb mindestens verwalten:

- ein eindeutig definiertes Zeitfenster mit Zeitzone;
- Verhalten bei verpasstem Start, Neustart und überlangem Lauf;
- maximale CPU-Nutzung oder CPU-Gewichtung;
- niedrigere Scheduling-Priorität gegenüber interaktiven Diensten;
- I/O-Gewichtung und freien Speicher;
- geordneten Abbruch beziehungsweise Abschluss am Ende des erlaubten Fensters;
- Begrenzung auf genau einen gleichzeitigen Encoding-Job.

Konkrete Grenzwerte werden erst nach einem repräsentativen Encoding-Test unter
gleichzeitiger Inferenzlast festgelegt. `gn-encoding` erhält keine Mitgliedschaft
in GPU-Gruppen und keine `/dev/kfd`- oder `/dev/dri`-Weitergabe.

## 5. Repository-Grenzen

Vorgesehene Ansible-Struktur:

```text
llm-server/ansible/
├── playbooks/
│   ├── host.yml
│   ├── ai.yml
│   ├── video-encoding.yml
│   └── site.yml
└── roles/
    ├── host_baseline/
    ├── podman_runtime/
    ├── workload_accounts/
    ├── ai_stack/
    ├── ai_environment_switch/
    └── video_encoding/
```

`host.yml` verwaltet ausschließlich gemeinsame Plattformzustände.
`ai.yml` darf nur KI-Zustände verändern. `video-encoding.yml` verwaltet nur das
Konto `gn-encoding`, seine Pfade, Images, Quadlets, Timer und Health Checks. Ein
späteres `site.yml` kann die unterstützte Gesamtkonfiguration in definierter
Reihenfolge anwenden.

Ein separates Quellcode-Repository wird erst benötigt, wenn eigene
Encoding-Software, eine Oberfläche oder ein Queue-Dienst entwickelt wird. Ein
solches Repository erzeugt ein versioniertes Artefakt oder Image; ausschließlich
das Infrastructure-Repository legt fest, welche Version auf dem Server läuft.

## 6. Aktueller Implementierungsstand

Die gemeinsame Rolle `workload_accounts` hat am 20.09.2026 eingerichtet:

```text
Konto:       gn-encoding (UID/GID 982)
Konfiguration: /etc/ghostnet-encoding
Daten:         /var/lib/ghostnet-encoding
Eingang:       /var/lib/ghostnet-encoding/input
Ausgang:       /var/lib/ghostnet-encoding/output
Arbeitsdaten:  /var/lib/ghostnet-encoding/work
Quadlets:      /etc/containers/systemd/users/982
Podman-Store:  /var/lib/ghostnet-encoding/.local/share/containers/storage
```

Passwort und interaktive Shell sind gesperrt. Der systemd-User-Manager läuft
dank Linger unabhängig von einer Anmeldung. Der Podman-Store wurde als
rootless und getrennt von beiden KI-Stores geprüft. Es wurden noch keine Images
oder Container angelegt.

## 7. Offene Entscheidungen

1. Welcher Encoder und welches fest versionierte Container-Image werden genutzt?
2. Welche Codecs, Qualitätsprofile und Hardwarekompatibilitäten sind erforderlich?
3. Woher kommen Eingabedateien, und wie werden fertige Dateien abgeholt?
4. Welches konkrete nächtliche Zeitfenster und welche Zeitzone gelten?
5. Darf ein laufender Job das Zeitfenster überschreiten oder wird er gestoppt?
6. Welche CPU-, Speicher- und I/O-Grenzen schützen die KI-Dienste?
7. Wie werden Warteschlange, Wiederholung, Teilresultate und Fehler behandelt?
8. Welche Aufbewahrungs-, Backup- und Löschregeln gelten für Video- und
   Arbeitsdateien?
9. Welche Statusanzeige oder Benachrichtigung benötigen Nutzer?

Diese Werte werden nicht vorab in Playbooks angenommen.