docs: umfassende README + BEDIENUNGSANLEITUNG mit llama.cpp-Parametern und Beispielen

README.md

@@ -4,6 +4,8 @@ Dieses Repository enthält die Konfiguration und Skripte für einen automatisier
 Coding-Workflow mit zwei lokalen LLaMA-Modellen: ein Coder-Modell und ein Judge-Modell,
 gesteuert über [pi agent](https://github.com/earendil-works/pi).
 
+---
+
 ## Überblick
 
 ```
@@ -24,45 +26,77 @@ Nutzer gibt Auftrag
   /optimize = Coder→Judge→Fix-Schleife automatisch (bis PASS oder max. N Runden)
 ```
 
+Beide Modelle laufen als **separate llama.cpp-Docker-Container** und sprechen eine
+OpenAI-kompatible API (`/v1/chat/completions`). pi agent wechselt automatisch zwischen
+den Endpunkten wenn du ein `/judge`-, `/fix`- oder `/coder`-Kommando aufrufst.
+
+---
+
 ## Modelle
 
-| Rolle   | Modell                                          | Port | Container           |
-|---------|-------------------------------------------------|------|---------------------|
-| Coder   | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8001 | qwen36-27b-coder    |
-| Judge   | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8002 | qwen36-27b-judge    |
+| Rolle  | Modell                                            | Port | Container        | Alias          |
+|--------|---------------------------------------------------|------|------------------|----------------|
+| Coder  | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8001 | qwen36-27b-coder | qwen3.5-coder  |
+| Judge  | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8002 | qwen36-27b-judge | qwen3.5-judge  |
 
-Beide Modelle laufen als separate llama.cpp-Docker-Container auf GPU 1 und 2 (tensor-split 0.5/0.5).
+Beide Container verwenden dasselbe GGUF-Datei, aber mit unterschiedlichen
+Serverparametern (Kontext, Temperatur, Parallelität).
+
+---
 
 ## Voraussetzungen
 
-- Docker mit NVIDIA-GPU-Support (`nvidia-container-toolkit`)
-- GPU 1 und GPU 2 verfügbar (`nvidia-smi`)
-- GGUF-Modell unter: `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf`
-  - Standard: `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface`
+- Docker mit NVIDIA-GPU-Support:
+  ```bash
+  # NVIDIA Container Toolkit installieren (falls nicht vorhanden)
+  distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
+  curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
+  curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list \
+    | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
+  sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
+  sudo systemctl restart docker
+  ```
+- Mindestens eine NVIDIA-GPU (empfohlen: zwei GPUs mit je ≥ 16 GB VRAM)
+- GGUF-Modell vorhanden unter:
+  `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf`
+  - Standard-Pfad: `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface`
+  - Überschreibbar: `HF_HOME=/anderer/pfad ./start-servers.sh`
 - [pi agent](https://github.com/earendil-works/pi) installiert (`~/.pi/`)
 
-## Setup
+---
+
+## Installation
 
 ```bash
-# 1. Extension und Modell-Config nach ~/.pi/agent/ deployen
+# 1. Repository klonen
+git clone <repo-url> ~/pi_coder
+cd ~/pi_coder
+
+# 2. Extension und Modell-Config nach ~/.pi/agent/ deployen
 ./install.sh
 
-# 2. /reload in pi agent ausführen
+# 3. pi agent neu laden (in der pi-Oberfläche)
+# /reload
+
+# 4. Server starten
+./start-servers.sh
 ```
 
-Nach Änderungen an `pi-coder-judge-extension.ts` oder `models.json`:
+Nach späteren Änderungen an `pi-coder-judge-extension.ts` oder `models.json`:
 ```bash
 ./install.sh   # kopiert nach ~/.pi/agent/
 # dann /reload in pi agent
 ```
 
+---
+
 ## Server starten / stoppen / status
 
 ```bash
-# Beide Server parallel starten (empfohlen)
+# Beide Server parallel starten (empfohlen — dauert 1–3 Minuten)
 ./start-servers.sh
 
-# Einzeln starten (z.B. nach Absturz eines Servers)
+# Einzeln starten (z.B. nur einen neu starten)
 ./start-coder.sh   # Port 8001
 ./start-judge.sh   # Port 8002
 
@@ -74,27 +108,156 @@ Nach Änderungen an `pi-coder-judge-extension.ts` oder `models.json`:
 ```
 
 `start-servers.sh` startet beide Container gleichzeitig und wartet bis beide
-HTTP-ready sind — schneller als sequenziell. Logs werden getrennt gesammelt
-und nur bei Fehler ausgegeben.
+HTTP-ready sind. Logs werden getrennt gesammelt und nur bei Fehler ausgegeben.
+
+Wenn Server bereits laufen und du `start-servers.sh` (oder ein Einzelskript)
+aufrufst, werden die laufenden Container zuerst per `docker rm -f` gestoppt
+und dann neu gestartet — ein laufender Inference-Request wird dabei abgebrochen.
+
+---
+
+## llama.cpp-Serverparameter im Detail
+
+### Gemeinsame Parameter
+
+| Parameter | Wert | Bedeutung |
+|---|---|---|
+| `--jinja` | — | Verwendet das im GGUF eingebettete Jinja-Chat-Template (Qwen-Format). Notwendig für korrekte `<\|im_start\|>`-Tokens. |
+| `--no-context-shift` | — | Kontextfenster wird **nicht** verschoben wenn es voll ist — stattdessen Fehler. Verhindert stille Datenverluste. |
+| `--repeat-penalty 1.05` | — | Leichte Penalty für Wiederholungen. Wert > 1.0 unterdrückt Loops. |
+| `--top-k 40` | — | Nur die 40 wahrscheinlichsten nächsten Tokens werden berücksichtigt. |
+| `--min-p 0.01` | — | Tokens mit Wahrscheinlichkeit < 1 % des wahrscheinlichsten Tokens werden ausgeschlossen. |
+| `-ngl 999` | — | Alle Layer auf die GPU laden (999 = „alle"). Bei zu wenig VRAM reduzieren. |
+| `-fa on` | — | Flash Attention — schnellere Attention-Berechnung, weniger VRAM für den Attention-Pass. |
+| `--kv-unified` | — | Einheitlicher KV-Cache über alle Schichten. Effizienter bei langen Kontexten. |
+| `--cache-type-k q8_0` | — | KV-Cache Keys in 8-Bit quantisiert. Spart ~50 % VRAM gegenüber fp16, minimaler Qualitätsverlust. |
+| `--cache-type-v q8_0` | — | KV-Cache Values ebenfalls 8-Bit quantisiert. |
+| `--cont-batching` | — | Continuous Batching: neue Anfragen werden in laufende Batches eingefügt — höherer Durchsatz bei mehreren parallelen Anfragen. |
+| `--main-gpu 0` | — | GPU-Index (0 = erste der übergebenen GPUs) für Nicht-Tensor-Operationen. |
+| `--tensor-split 0.5,0.5` | — | Modell-Gewichte 50/50 auf zwei GPUs aufteilen. |
+| `--gpus '"device=1,2"'` | — | Docker-Argument: GPU 1 und GPU 2 dem Container übergeben. |
+
+### Coder-Server (Port 8001) — optimiert für Coding-Aufgaben
+
+| Parameter | Wert | Erklärung / Wirkung |
+|---|---|---|
+| `-c 131072` | 128K Tokens | Großes Kontextfenster: gesamte Codebasis + Gesprächsverlauf passt rein. **Hoher VRAM-Bedarf.** Reduziere auf `65536` wenn VRAM knapp. |
+| `-n 16384` | 16K Tokens | Maximale Ausgabelänge pro Anfrage. Für Kommentieraufgaben (`/update_doku`) nötig. |
+| `--temp 0.2` | — | Niedrige Temperatur: deterministisch, konsistenter Code. Erhöhe auf `0.4–0.6` für kreativere Lösungsansätze. |
+| `--top-p 0.95` | — | Nucleus Sampling: 95 % der Wahrscheinlichkeitsmasse. Passend zu temp 0.2. |
+| `--batch-size 1024` | — | Prompt-Verarbeitungs-Batch. Größer = schnelleres Einlesen langer Dateien. |
+| `--ubatch-size 512` | — | Micro-Batch für GPU-Kernel. Muss ≤ batch-size sein. |
+| `--parallel 2` | — | 2 gleichzeitige Request-Slots. Nützlich wenn pi agent schnell Folgeanfragen schickt. |
+
+### Judge-Server (Port 8002) — optimiert für Reviews
+
+| Parameter | Wert | Erklärung / Wirkung |
+|---|---|---|
+| `-c 65536` | 64K Tokens | Mittleres Kontextfenster: reicht für Code-Review des letzten Commits + Konversationshistorie. |
+| `-n 8192` | 8K Tokens | Reviews müssen nicht länger sein. Spart Inferenz-Zeit. |
+| `--temp 0.1` | — | Sehr niedrige Temperatur: maximale Konsistenz und Reproduzierbarkeit der Urteile. |
+| `--top-p 0.9` | — | Etwas enger als beim Coder — weniger Variation im Urteil gewünscht. |
+| `--batch-size 512` | — | Kleiner als beim Coder — Judge bekommt selten sehr lange Prompts. |
+| `--ubatch-size 256` | — | Entsprechend kleiner. |
+| `--parallel 1` | — | Judge-Aufgaben sind immer sequenziell im Workflow, daher 1 Slot ausreichend. |
+
+---
+
+## Anpassung für eine einzelne GPU
+
+Mit einer GPU läuft das Modell vollständig auf dieser GPU statt verteilt.
+Anpassungen in `start-coder.sh` und `start-judge.sh`:
 
-Umgebungsvariable für alternativen Modellpfad:
 ```bash
-HF_HOME=/anderer/pfad ./start-servers.sh
+# Vorher (2 GPUs, device 1 und 2):
+  --gpus '"device=1,2"' \
+  --main-gpu 0 \
+  --tensor-split 0.5,0.5 \
+
+# Nachher (1 GPU, z.B. device 0):
+  --gpus '"device=0"' \
+  --main-gpu 0 \
+# --tensor-split  ← diese Zeile komplett entfernen
 ```
 
-## pi-Kommandos
+### VRAM-Abschätzung für das 27B IQ4_XS-Modell
 
-| Kommando | Beschreibung |
+| Komponente | Größe (ca.) |
 |---|---|
-| `/coder <auftrag>` | TASK.md anlegen, Implementierung starten (Coder-Modell) |
-| `/judge [fokus]` | Code-Review gegen TASK.md + letzten Commit (Judge-Modell) |
-| `/fix [hinweis]` | Judge-Kritik beheben, committen (Coder-Modell) |
-| `/shipit` | Finale Freigabeprüfung (Judge-Modell) |
-| `/optimize <auftrag> [--rounds N] [--with-doku]` | Vollautomatische Schleife bis PASS |
-| `/patch <änderung>` | Gezielte Minimaländerung ohne vollständigen Review |
-| `/quick_check [was]` | Schnelle Prüfung der letzten Änderung (OK/PROBLEM) |
-| `/update_doku` | Code kommentieren + README.md + BEDIENUNGSANLEITUNG.md |
-| `/new_project <pfad>` | Neues Projektverzeichnis + git init anlegen |
+| Modell-Gewichte (IQ4_XS, 27B) | ~14,5 GB |
+| KV-Cache bei 128K Kontext (q8_0) | ~14 GB |
+| KV-Cache bei 64K Kontext (q8_0) | ~7 GB |
+| KV-Cache bei 32K Kontext (q8_0) | ~3,5 GB |
+
+Bei einer **24-GB-GPU** ist nur ein Server gleichzeitig sinnvoll betreibbar:
+- Modell-Gewichte: ~14,5 GB
+- KV-Cache bei 32K Kontext: ~3,5 GB
+- Summe: ~18 GB → passt mit Puffer
+
+**Empfehlung für eine 24-GB-GPU:**
+```bash
+# Coder — Kontext reduzieren
+-c 32768   # statt 131072
+-n 8192    # statt 16384
+
+# Judge — Kontext reduzieren
+-c 32768   # statt 65536
+```
+
+Bei einer **16-GB-GPU** ist die Modellgröße allein schon grenzwertig.
+Entweder ein kleineres Modell verwenden oder die Quantisierung weiter erhöhen (IQ3_XS, Q4_K_M).
+
+### Beide Server auf einer GPU betreiben
+
+Technisch möglich, aber beide Server laden das Modell gleichzeitig → doppelter VRAM-Bedarf.
+Auf einer 24-GB-GPU daher **nicht empfohlen**. Alternativen:
+
+- Nur einen Server gleichzeitig starten (manuell umschalten)
+- Kleinere Quantisierung wählen (IQ3_XS: ~11 GB)
+- `ollama` als Alternative — lädt Modelle bei Bedarf und entlädt sie wieder
+
+---
+
+## Parameter-Tuning-Guide
+
+### Temperatur (`--temp`)
+
+| Wert | Eignung |
+|---|---|
+| `0.0–0.1` | Maximale Reproduzierbarkeit. Gut für Judge/Review. |
+| `0.1–0.3` | Guter Kompromiss für Coding. **Empfohlen für Coder.** |
+| `0.4–0.6` | Kreativere Lösungen, mehr Varianz. Sinnvoll für Prototyping. |
+| `0.7–1.0` | Kreativschreiben, Brainstorming. Für Coding meist zu viel Rauschen. |
+
+### Kontextgröße (`-c`)
+
+Je größer der Kontext, desto mehr VRAM braucht der KV-Cache.
+Faustregel: KV-Cache ≈ `context_size × layers × head_dim × 2 × bytes_per_element`.
+Bei q8_0 (1 Byte/Element) und Qwen3-27B (28 Schichten, 128 Head-Dim, 32 Heads):
+KV-Cache ≈ `context_size × 28 × 128 × 32 × 2 × 1 Byte ≈ context_size × 0,23 MB`
+
+| Kontext | KV-Cache (q8_0) | Empfehlung |
+|---|---|---|
+| 32 768 | ~7,5 GB | 1 × 24-GB-GPU |
+| 65 536 | ~15 GB | 2 × 16-GB-GPU |
+| 131 072 | ~30 GB | 2 × 24-GB-GPU |
+
+### KV-Cache-Quantisierung
+
+| `--cache-type-k/v` | VRAM | Qualität |
+|---|---|---|
+| `f16` | 100 % (Basis) | Referenz |
+| `q8_0` | ~50 % | Kaum merklich schlechter — **empfohlen** |
+| `q4_0` | ~25 % | Sichtbarer Qualitätsverlust bei langen Kontexten |
+
+### Parallelität (`--parallel`)
+
+Mehr parallele Slots erhöhen den Durchsatz bei gleichzeitigen Anfragen, aber jeder Slot
+reserviert Speicher im KV-Cache. Im pi-coder-Workflow sind echte Parallelaufrufe selten,
+daher ist `--parallel 1` für den Judge ausreichend. Coder `--parallel 2` bietet Puffer
+wenn pi agent Folgeanfragen schnell hintereinander schickt.
+
+---
 
 ## Dateien
 
@@ -108,3 +271,21 @@ HF_HOME=/anderer/pfad ./start-servers.sh
 | `stop-servers.sh` | Beide Container stoppen |
 | `status.sh` | Laufstatus beider Server anzeigen |
 | `install.sh` | Extension + models.json nach `~/.pi/agent/` kopieren |
+
+---
+
+## pi-Kommandos (Kurzübersicht)
+
+| Kommando | Modell | Beschreibung |
+|---|---|---|
+| `/coder <auftrag>` | Coder | TASK.md anlegen, Implementierung starten |
+| `/judge [fokus]` | Judge | Code-Review gegen TASK.md + letzten Commit |
+| `/fix [hinweis]` | Coder | Judge-Kritik beheben, committen |
+| `/shipit` | Judge | Finale Freigabeprüfung |
+| `/optimize <auftrag> [--rounds N] [--with-doku]` | beide | Vollautomatische Schleife bis PASS |
+| `/patch <änderung>` | Coder | Gezielte Minimaländerung ohne Review |
+| `/quick_check [was]` | Judge | Schnelle Prüfung der letzten Änderung |
+| `/update_doku` | Coder | Code kommentieren + README + Bedienungsanleitung |
+| `/new_project <pfad>` | — | Neues Projektverzeichnis + git init |
+
+Ausführliche Beschreibung aller Kommandos mit Beispielen: siehe **BEDIENUNGSANLEITUNG.md**.