# Projektplan — Setup phy-z-srv-gpu01 (LLM-Server mit SMB-Wissensbasis)

Date: 2026-07-10
Status: Plan — Server-Lieferung in einigen Monaten erwartet
Basiert auf: `20260706-hardware-assessment.md`, `20260706-software-assessment.md`, `20260707-deep-dive.md`

---

## 0. Rahmenbedingungen (fixiert)

| Punkt | Entscheidung |
|---|---|
| Hardware | HPE DL380 Gen12, 2× Xeon 6714P, 128 GB RAM, RTX PRO 6000 96 GB, 2× 960 GB NVMe — s. `HW.md` |
| Betrieb | **Bare Metal**, keine Virtualisierung des LLM-Stacks |
| Nutzer | ~25, gemischt (technisch versiert + Nicht-Techniker) |
| Auth | **AD/LDAP** (Details Service-Account/Basis-DN als Pre-Work klären) |
| Berechtigungen | **Einfach: alle Nutzer sehen den gesamten indizierten Bestand** (Kunde bestätigt; Shares ohne HR-/Personal-Inhalte halten) |
| Sprache | Dokumente & Nutzer überwiegend **Deutsch** → Modell- und Embedding-Wahl daran ausrichten |
| Inference | **vLLM** mit fester GPU-Auslastung (kein Ollama als Basis) |
| Wissensbasis | SMB-Shares (einige TB, PDF/Office), **Sync ist die Kernanforderung** |
| Später | Jira-Anbindung u. a. Workloads; dafür ggf. **MIG** |
| Vorgehen | Setup vollständig über **Ansible** (dieses Repo), PoC vorab: nein — reine Planung |

## 1. Produktentscheidung: Open WebUI statt Onyx

**Empfehlung: Open WebUI** (bestätigt und verschärft die Empfehlung aus dem
Deep Dive §4.7). Ausschlaggebend, Stand 2026-07-10 verifiziert:

1. **Onyx' File-Connector ist reiner manueller Upload** — kein Verzeichnis-Watching,
   kein periodischer Re-Sync eines gemounteten Shares
   ([Doku](https://docs.onyx.app/admins/connectors/official/file)). Die
   Kernanforderung „Shares synchron halten" hieße bei Onyx: Eigenbau gegen
   deren API. Open WebUI hat dafür das offizielle Sync-Tool
   [`oikb`](https://github.com/open-webui/oikb) (inkrementell, Löschungen,
   Cron-fähig — Deep Dive §4.3).
2. **Onyx: SSO (OIDC/SAML), User Groups, RBAC, Permission-Sync = Enterprise
   Edition (kostenpflichtig)**
   ([Doku](https://docs.onyx.app/deployment/miscellaneous/enterprise_edition)).
   Open WebUI: LDAP/AD-Anbindung und Gruppen sind frei.
3. Onyx bringt einen zweiten schweren Stack mit (Vespa-Index, Postgres,
   Worker) — auf 128 GB RAM **neben** vLLM spürbar; widerspricht „it just works".
4. Bedienung: ein UI im ChatGPT-Stil, vorkonfigurierte Assistenten mit fester
   Knowledge Base → passt für den gemischten Nutzerkreis.

**Wann die Entscheidung zu revidieren ist** (Trigger, nach der Share-Analyse §2.1):

- Der *relevante* Bestand liegt deutlich über ~10⁵ Dokumenten und lässt sich
  nicht sinnvoll filtern → Suchqualität/Skalierung von Open WebUI prüfen,
  Onyx (mit Eigenbau-Sync) oder Eigenbau-Pipeline (Deep Dive §4.5) neu bewerten.
- Datei-genaue NTFS-ACLs werden doch Anforderung → Neubewertung (Deep Dive §4.4/4.5).

Jira später: für *Indizierung* von Jira-Inhalten hat Onyx zwar native
Konnektoren, Open WebUI deckt das aber über Tools/MCP (Atlassian-MCP) bzw.
API-Workloads direkt gegen vLLM ab — kein Entscheidungskriterium für heute.

## 2. Phase 0 — Pre-Work (jetzt, ohne Server)

### 2.1 Share-Analyse (wichtigster Punkt — ja, unbedingt vorab)

Read-only-Skript auf einer beliebigen Maschine mit Share-Zugriff (kein
GPU-Server nötig). Zu erheben:

- Volumen & Dateianzahl **pro Share und Dateityp** (pdf/docx/xlsx/…)
- Anteil **gescannter PDFs** (Stichprobe: PDFs ohne Textlayer) → OCR-Bedarf
- Duplikate/Altversionen („Kopie von …", Versionsordner) → Filterregeln
- Änderungsrate (mtime-Verteilung) → Sync-Frequenz
- Anteil nicht extrahierbarer Formate (CAD, Bilder, Archive) → Erwartungsmanagement
- Sonderzeichen/Pfadlängen, Encoding (Umlaute!)

Ergebnis bestimmt: Korpus-Umfang (→ §1-Trigger), OCR-Pipeline ja/nein,
Index-Größe (→ Storage-Check §2.3), Erst-Indexierungsdauer.

### 2.2 Mit dem Kunden zu klären (Checkliste)

- [ ] AD/LDAP: Bind-Service-Account, Basis-DN, Gruppe „LLM-Nutzer"
- [ ] **SMB-Service-Account read-only** für die Mounts (kein Nutzer-Account)
- [ ] Welche Shares/Unterordner genau in den Index? Ausschlussliste (HR o. ä.)
- [ ] DNS-Name (z. B. `ki.phytron.local`) + TLS (internes CA-Zertifikat?)
- [ ] Internetzugang des Servers (Modell-/Container-Downloads bei Installation;
      danach einschränkbar)
- [ ] Protokollierung/Datenschutz: werden Chats gespeichert? Betriebsrat/DSGVO
      früh einbinden
- [ ] Update-/Wartungsfenster und wer den Betrieb nach Übergabe verantwortet
- [ ] „Andere Workloads" konkretisieren (Jira: Inhalte durchsuchen vs.
      Aktionen ausführen?) → bestimmt MIG-Layout später

### 2.3 Storage-Check (⚠️ vor Bestellung ggf. nachsteuern)

2× 960 GB NVMe, vermutlich RAID1 → **~960 GB nutzbar** für OS + Docker +
Modelle (~100 GB) + Vektor-DB + Extraktions-Cache. Strategie: **kein lokaler
Spiegel der Shares** — nur Index (extrahierter Text + Embeddings, erfahrungsgemäß
wenige % des Rohvolumens). Nach der Share-Analyse gegenrechnen; wenn eng:
zwei weitere NVMe nachordern (Slots frei) — das ist **vor** Lieferung am
billigsten zu ändern.

### 2.4 Ansible vorbereiten (im Repo, testbar ohne GPU)

- `run.yml`: Play für `phy_z_srv_gpu01` ergänzen
- Rollen-Skelett unter `ansible/roles/` (Details erst bei Umsetzung):
  - `nvidia_gpu` — Treiber (≥ 580), Container Toolkit, optional MIG, DCGM
  - `cifs_mounts` — ro-Mounts, Credentials aus `group_vars/secrets.yml`
  - `llm_stack` — Docker Compose: vLLM (feste `--gpu-memory-utilization`),
    Embedding-Server, Open WebUI + pgvector, Reverse Proxy (TLS), oikb-Timer
  - Bestehendes nachnutzen: `geerlingguy.security` (Basis-Härtung),
    `geerlingguy.docker`
- `group_vars/phy_z_srv_gpu01.yml`: nur Overrides (Modellname, VRAM-Quote,
  Share-Liste, LDAP-Parameter)
- Alles außer GPU-Rolle ist vorab in einer Wegwerf-VM testbar (`just run`-Pfad)

### 2.5 Modell-Shortlist (finale Wahl erst bei Installation!)

Kandidaten heute: Qwen3-32B FP8 (Favorit: Deutsch, Durchsatz), gpt-oss-120b
(mehr Qualität, weniger Parallelität), Embeddings bge-m3 / multilingual-e5.
**Nicht jetzt festlegen** — Modell-Landschaft und vLLM-Support in einigen
Monaten neu sichten (§ Wiedereinstieg). Kleines deutsches Eval-Set (20–30
Fragen mit erwarteten Antworten aus dem Bestand) schon jetzt mit dem Kunden
sammeln — das ist später das Abnahmekriterium.

## 3. Phasen ab Server-Lieferung

| Phase | Inhalt | Ergebnis/Abnahme |
|---|---|---|
| **1. Basis** (Woche 1) | Rack/Strom (600-W-GPU!), iLO, Firmware, RAID, Ubuntu 24.04 LTS, Eintrag in Ansible-Basis-Setup (Security, Pakete, Nutzer) | `just run phy_z_srv_gpu01` läuft grün |
| **2. GPU-Stack** (Woche 1–2) | Rolle `nvidia_gpu`: Treiber, Container Toolkit, DCGM; **Burn-in unter Dauerlast** (SM120-Risiken, Deep Dive §1.6); MIG erst mal **aus** | `nvidia-smi` ok, 48 h-Lasttest ohne Reset |
| **3. Inference** (Woche 2) | vLLM-Container (NVIDIA-Build) mit gewähltem Modell, feste VRAM-Quote, Embedding-Server daneben; Benchmark mit Eval-Set | deutsche Antworten ok, Ziel-Parallelität erreicht |
| **4. UI + Auth** (Woche 2–3) | Open WebUI + pgvector, LDAP-Login, Reverse Proxy + TLS, vorkonfigurierter „Phytron-Assistent" | Login mit AD-Konto, Chat läuft |
| **5. Wissensbasis** (Woche 3–5) | CIFS-Mounts (ro), Extraktion inkl. OCR-Engine (Tika/Docling), oikb-Sync erst auf **einen Teilbestand**, Qualität prüfen, dann Vollindex (Dauer aus §2.1 abschätzen) | Fragen aus dem Eval-Set werden mit korrekten Quellen beantwortet |
| **6. Pilot → Rollout** (Woche 5–7) | 3–5 Pilotnutzer (gemischt), Feedback, dann alle 25; Onboarding-Einseiter (was kann es, was nicht — CAD/Scans!) | Abnahme durch Kunden |
| **7. Betrieb** | Monitoring (GPU/DCGM, Dienste), Backup (Konfig + DBs — Modelle nicht), Update-Runbook `manuals/`, Doku im README | Runbooks vorhanden |
| **später** | Jira & weitere Workloads; **erst dann MIG-Layout** festlegen (bis 4 Instanzen) statt jetzt raten | — |

## 4. Risiken

| Risiko | Umgang |
|---|---|
| Storage zu klein für Index (§2.3) | Share-Analyse → ggf. NVMe nachordern **vor** Lieferung |
| Viele gescannte PDFs → OCR-Aufwand & -Qualität | Analyse-Stichprobe; OCR-Phase einplanen; Erwartungen dämpfen |
| SM120/Treiber-Kinderkrankheiten (Deep Dive §1.6) | Treiber ≥ 580, NVIDIA-vLLM-Container, Burn-in in Phase 2, HPE-Support |
| Software-Stand veraltet bis Lieferung | Versionen **erst bei Installation pinnen**; Wiedereinstiegs-Checkliste |
| Erst-Indexierung dauert Tage | Teilbestand zuerst; Sync nachts; Dauer vorab abschätzen |
| RAM-Konkurrenz Extraktion/OCR vs. vLLM | vLLM hat feste VRAM-Quote; Indexer-Jobs drosseln (nice/cgroups); 128 GB reichen für OWUI-Stack |
| Datenschutz/Betriebsrat bei Chat-Logs | Früh klären (§2.2), Logging-Policy dokumentieren |
| Kein HA — ein Server | Erwartung managen: Wartungsfenster = Dienst weg; Backup-Restore-Runbook |

## 5. Wiedereinstiegs-Checkliste (wenn der Server da ist)

1. Dieses Dokument + Deep Dive lesen; offene Punkte aus §2.2 abhaken
2. Ergebnis der Share-Analyse vorliegen? (sonst zuerst!)
3. Neu sichten & **dann erst pinnen**: vLLM-Version (RTX-PRO-6000-Support),
   Open WebUI + oikb Release Notes, NVIDIA-Treiber, Modell-Shortlist §2.5
4. Storage-Entscheidung §2.3 umgesetzt?
5. Dann Phasenplan §3 von oben abarbeiten; jede Phase = Ansible-Commit + ggf.
   Runbook unter `manuals/`

## 6. Bewusst offen gelassen (kein Jetzt-Entscheid nötig)

- Exaktes Modell & Quantisierung, vLLM-Flags, MIG-Layout, OCR-Engine-Wahl,
  Monitoring-Stack-Details, Reverse-Proxy-Produkt — alles bei Umsetzung mit
  aktuellem Stand entscheiden; Rahmen steht oben.