llama-server/BEDIENUNGSANLEITUNG.md

# Bedienungshandbuch für Qwen3.6-MoE-35B-A3B Server

Dieses Handbuch beschreibt die Installation, Konfiguration und den Betrieb der lokalen Qwen3.6-MoE-35B-A3B Inferenzserver mit llama.cpp.

## Inhaltsverzeichnis
1. [Systemvoraussetzungen](#systemvoraussetzungen)
2. [Installation und Start](#installation-und-start)
3. [Server-Verwaltung](#server-verwaltung)
4. [Konfiguration und Parameter](#konfiguration-und-parameter)
5. [Integration mit Pi](#integration-mit-pi)
6. [API-Nutzung](#api-nutzung)
7. [Fehlerbehebung](#fehlerbehebung)

## Systemvoraussetzungen

### Hardware
- **GPU**: NVIDIA RTX 3090 (2x) oder equivalent mit je 24GB+ VRAM
- **RAM**: 64GB+ System-RAM empfohlen
- **Speicher**: 100GB+ für Modell-Dateien und Cache
- **NVIDIA-Treiber**: Mindestens Version 535+ mit CUDA 12.x

### Software
- Docker Engine (Version 20.10+)
- Docker Compose (Version 2.0+)
- NVIDIA Container Toolkit
- curl oder wget für Healthchecks

## Installation und Start

### Voraussetzungen prüfen
```bash
# GPU-Verfügbarkeit prüfen
nvidia-smi

# Docker-Version prüfen
docker --version
docker compose version

# Verzeichnisstruktur erstellen
mkdir -p ~/llama-server
cd ~/llama-server
```

### Server starten

#### Methode 1: Docker Compose (Empfohlen)
```bash
# In das Projektverzeichnis wechseln
cd ~/llama-server

# RAG-optimierten Server starten (Standard)
docker compose up -d --force-recreate

# Coding-optimierten Server starten
docker compose -f docker-compose_Qwen3.6_Tools_coding.yml up -d --force-recreate

# Uncensored-Variante starten
docker compose -f docker-compose_Qwen3.6_Uncensored.yml up -d --force-recreate
```

#### Methode 2: Shell-Skripte
```bash
# Server-Modus (Hintergrunddienst)
./run_qwen35b_server_tools.sh                    # Coding-optimiert
./run_qwen35b_server_uncensored_rag_longctx.sh   # Uncensored + RAG
./run_qwen35b_server_uncensored.sh                # Uncensored (kein RAG)

# CLI-Modus (Kommandozeile)
./run_qwen35b_cli_tools_rag_longctx.sh            # CLI mit RAG
./run_qwen35b_cli_uncensored_rag_longctx.sh       # CLI Uncensored + RAG

# Embedding-Server
./run_bge_m3_embedding_server.sh
```

**Hinweis**: Die Qwopus3.6-Variante wird über Docker Compose gestartet, da sie multimodale Unterstützung benötigt (mmproj-Datei). Container-Name: `qwopus35b-moe-coding`.

**Hinweis**: Alle Shell-Skripte stoppen automatisch existierende Container gleichen Namens vor dem Start.

## Server-Verwaltung

### Wichtige Regel
> **Nur ein Server kann gleichzeitig auf Port 8000 laufen!**

### Container-Namen und Konfigurationen

| Container-Name | Modell | Konfigurationsdatei |
|----------------|--------|---------------------|
| qwen35b-moe-coding | Carnice | docker-compose_Qwen3.6_Tools_coding.yml |
| qwen35b-moe-tools | Carnice | docker-compose_Qwen3.6_Tools.yml |
| qwen35b-moe-rag-longctx | Carnice | docker-compose_Qwen3.6_Tools_RAG_faehig.yml |
| qwopus35b-moe-coding | Qwopus3.6 | docker-compose_Qwen3.6_Qwopus3.6_coding.yml |
| qwen35b-moe-uncensored | Uncensored | docker-compose_Qwen3.6_Uncensored.yml |
| qwen35b-moe-uncensored-rag | Uncensored | docker-compose_Qwen3.6_Uncensored_RAG_faehig.yml |
| qwen35b-moe-uncensored-rag-longctx | Uncensored | run_qwen35b_server_uncensored_rag_longctx.sh |

### Server stoppen und starten

#### Container stoppen
```bash
# Nach Container-Namen stoppen
docker rm -f qwen35b-moe-coding

# Oder via docker-compose
cd ~/llama-server
docker compose -f docker-compose_Qwen3.6_Tools_coding.yml down

# Alle laufenden Container anzeigen
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

#### Server wechseln
```bash
cd ~/llama-server

# Aktuellen Server stoppen
docker rm -f qwen35b-moe-coding

# Anderen Server starten
docker compose -f docker-compose_Qwen3.6_Uncensored.yml up -d
```

### Healthcheck und Status
```bash
# Server-Status prüfen
curl -fs http://localhost:8000/

# Container-Logs anzeigen
docker logs qwen35b-moe-rag-longctx

# Container-Status prüfen
docker inspect --format='{{.State.Health.Status}}' qwen35b-moe-rag-longctx
```

## Konfiguration und Parameter

### Hardware-Konfiguration
```yaml
GPU:
  Haupt-GPU: "0" (erste 3090)
  Tensor-Split: "0.5,0.5" (symmetrisch)
  Alle Layer auf GPU: -ngl 999
  Flash Attention: -fa on

KV-Cache:
  Typ: q8_0 (K und V)
  Unified Cache: --kv-unified
```

**Qwopus3.6-Spezifikationen:**
- **Parallel-Slots**: 4 (statt 2) — KV-Cache ~2.5 GB/Slot, 4 Slots machbar
- **Micro-Batch-Größe**: 1024 (statt 512) — SSM-Layer verarbeitet Micro-Batches effizienter
- **Multimodale Unterstützung**: Erfordert mmproj-Datei (siehe docker-compose für Konfiguration)

### Kontext- und Performance-Parameter
| Parameter | Wert | Beschreibung |
|-----------|------|--------------|
| Kontext-Fenster | 262,144 (256k) | Für lange RAG-Kontexte |
| Max. Ausgabe | 16,384 Token | Verhindert Text-Loops |
| Parallel-Slots | 2 | Spart ~10GB KV-Cache |
| Batch-Größe | 2,048 | Für lange Kontexte |
| Ubatch-Größe | 512 | Passend zu batch-size |

### Sampling-Parameter

#### RAG-Modus (Standard)
```yaml
temperature: 0.2      # Niedriger für faktentreue Antworten
top-p: 0.95           # Qwen-Empfehlung
top-k: 40             # Qwen-Empfehlung
min-p: 0.01           # Stabilisiert Sampling
repeat-penalty: 1.05  # Verhindert Wiederholungen
```

#### Coding-Modus
```yaml
temperature: 0.3      # Kompromiss für Kreativität und Präzision
top-p: 0.95
top-k: 40
min-p: 0.01
repeat-penalty: 1.05
```

#### Qwopus3.6-Modus
```yaml
temperature: 0.3      # Kompromiss für Kreativität und Präzision
top-p: 0.95
top-k: 40
min-p: 0.01
repeat-penalty: 1.05
```

**Qwopus3.6-Spezifikationen:**
- **Multimodale Unterstützung**: Erfordert mmproj-Datei (siehe docker-compose für Konfiguration)
- **Parallel-Slots**: 4 (statt 2) — KV-Cache ~2.5 GB/Slot, 4 Slots machbar
- **Micro-Batch-Größe**: 1024 (statt 512) — SSM-Layer verarbeitet Micro-Batches effizienter
- **Container-Name**: `qwopus35b-moe-coding` (vermeidet Konflikt mit Standard-Coding-Container)

### Laufzeit-Parameter (ohne Neustart)
Diese Parameter können pro API-Request überschrieben werden:
- `temperature`
- `top_p`
- `top_k`
- `min_p`
- `repeat_penalty`
- `max_tokens`

**Beispiel**:
```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "temperature": 0.0,
    "top_k": 20,
    "max_tokens": 512,
    ...
  }'
```

### Parameter mit Neustart erforderlich
| Parameter | Grund |
|-----------|-------|
| `-c` (Kontext) | KV-Cache wird beim Start allokiert |
| `--parallel` | Anzahl KV-Cache-Slots ist fest |
| `-ngl`, `--tensor-split` | Modell wird beim Start auf GPU geladen |
| `--kv-unified`, `--cache-type-*` | Cache-Struktur ist unveränderlich |
| `--batch-size`, `--ubatch-size` | Interne Buffer-Allokation |
| Modell-Datei | Offensichtlich |

## Integration mit Pi

### Architektur
```
MCP-Server ←──┐
Extensions ←──┤
  AGENTS.md ←─┤  Pi  ──→  llama-cpp Docker  ──→  GPU
    Dateien ←──┘  (API-Request mit System-Prompt + Tools)
```

### 1. Dateien übergeben
Pi liest Dateien mit dem `read`-Tool und sendet den Inhalt als Text im Prompt.

**Automatisches Laden**:
- AGENTS.md oder projektspezifische Context-Files beim Session-Start

### 2. Prompts konfigurieren
```bash
~/.pi/agent/SYSTEM.md        # Ersetzt kompletten System-Prompt
~/.pi/agent/APPEND_SYSTEM.md # Wird ans Ende angehängt
```

### 3. Tools verwenden
**Eingebaute Tools**: read, write, edit, bash

**Eigene Tools**: Als Pi-Extensions in `~/.pi/agent/extensions/` registriert. Das Modell sieht Tool-Definitionen im System-Prompt und ruft sie über OpenAI function-calling API auf (deshalb ist `--jinja` wichtig).

### 4. MCP-Server einrichten
In `settings.json`:
```json
{
  "packages": [
    "npm:pi-llama-cpp",
    "npm:@modelcontextprotocol/server-filesystem",
    "npm:irgendein-mcp-server"
  ]
}
```

Der MCP-Server läuft als Prozess neben pi — nicht im llama-cpp-Container.

**Hinweis**: llama.cpp hat ein `--system-prompt`-Flag, aber das ist weniger flexibel als AGENTS.md und kollidiert mit pi's eigenem System-Prompt.

## API-Nutzung

### Chat Completions
```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b-moe",
    "messages": [
      { "role": "system", "content": "Du bist ein hilfreicher deutscher Assistent." },
      { "role": "user",   "content": "Erkläre Quantencomputing in 3 Sätzen." }
    ],
    "max_tokens": 1024,
    "temperature": 0.2,
    "stream": false
  }'
```

### Streaming aktivieren
```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b-moe",
    "messages": [
      { "role": "user", "content": "Schreibe eine kurze Geschichte." }
    ],
    "stream": true
  }'
```

## Fehlerbehebung

### Server antwortet nicht
1. **GPU-Verfügbarkeit prüfen**: `nvidia-smi`
2. **Modell-Datei existiert**: `/home/dschlueter/nvme2n1p7_home/huggingface/models/qwen3/`
3. **Container-Logs prüfen**: `docker logs qwen35b-moe-rag-longctx`

### GPU-Speicher-Probleme
- Parallel-Slots von 2 auf 1 reduzieren
- Batch-Größe von 2048 auf 1024 reduzieren
- Uncensored-Variante verwenden (geringerer VRAM-Bedarf)

### Verbindungsfehler
- **Port 8000 belegt**: `lsof -i :8000` prüfen
- **Firewall**: Firewall-Einstellungen überprüfen
- **Container läuft**: `docker ps | grep qwen35b` prüfen

### Container startet nicht
1. **GPU-Zugriff**: NVIDIA Container Toolkit installieren
2. **Speicher**: Ausreichend VRAM verfügbar?
3. **Port-Konflikt**: Anderen Server stoppen

### Modell-Datei nicht gefunden
```bash
# Pfad prüfen
ls -la /home/dschlueter/nvme2n1p7_home/huggingface/models/qwen3/

# Falls nötig, Modell herunterladen
huggingface-cli download <model-name> --local-dir ./models
```

## Wartung und Backup

### Modell aktualisieren
1. Neue GGUF-Datei in HF_HOME-Pfad herunterladen
2. docker-compose.yml oder Shell-Skript `-m` Parameter aktualisieren
3. Container neu starten

### Konfiguration sichern
```bash
# System-Prompts sichern
cp ~/.pi/agent/SYSTEM.md ~/backup/
cp ~/.pi/agent/APPEND_SYSTEM.md ~/backup/

# Extensions sichern
cp -r ~/.pi/agent/extensions/ ~/backup/

# Docker-Konfigurationen sichern
cp ~/llama-server/docker-compose*.yml ~/backup/
```

### Regelmäßige Wartung
- **Wöchentlich**: Container-Logs prüfen
- **Monatlich**: GPU-Treiber aktualisieren
- **Bei Updates**: Docker und NVIDIA-Treiber updaten

## Lizenz

Dieses Projekt verwendet llama.cpp (Apache 2.0) und das Qwen3.6-MoE Modell. Die Modellnutzung unterliegt den Lizenzbedingungen des ursprünglichen Modells.