llama-server/FAQs.md

# FAQ - Häufig gestellte Fragen

## Server-Verwaltung

### Wie stoppe und starte ich einen dieser Llama-Server?

⚠️ **Wichtig**: Da alle Container Port 8000 belegen, kann immer nur einer gleichzeitig laufen.

#### Server stoppen

```bash
# Laufenden Container nach Name stoppen (egal womit er gestartet wurde)
docker rm -f qwen35b-moe-coding

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

# Welche Container gerade laufen:
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

#### Server starten

**Via Docker Compose (empfohlen — hat Healthcheck und restart: unless-stopped):**
```bash
cd ~/llama-server
docker compose -f docker-compose_Qwen3.6_Tools_coding.yml up -d
```

**Via Shell-Script (mit Readiness-Check und Test-Request):**
```bash
cd ~/llama-server
bash run_qwen35b_server_tools.sh
```

#### Wechsel zwischen zwei Servern

```bash
cd ~/llama-server

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

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

### Übersicht: Container-Namen ↔ Dateien

| 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` |

---

### Wie beende ich einen laufenden Docker-Server und erzeuge und starte ich einen neuen?

#### Beenden und löschen (Beispiel):
```bash
docker compose -f docker-compose_Qwen3.6_Tools_coding.yml rm -s -f qwen35b
```

#### Erzeugen und starten (Beispiel):
```bash
docker compose -f docker-compose_Qwen3.6_Tools_coding.yml up -d --force-recreate
```

---

## Integration mit Pi

### Wie kann ich diesen Docker-Containern mit Pi Dateien, Prompts, Tools oder MCP-Server übergeben?

Das ist eine Architekturfrage. Die Docker-Container sind reine Inferenz-Backends — sie empfangen API-Requests und liefern Text zurück. Alles andere (Dateien, Prompts, Tools, MCP) wird auf der pi-Ebene verwaltet:

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

#### Die vier Wege im Detail:

**1. Dateien → per pi-Kontext**
Pi liest Dateien mit dem `read`-Tool und schickt den Inhalt als Text im Prompt. Für automatisches Laden: AGENTS.md oder projektspezifische Context-Files (die pi beim Session-Start einliest).

**2. Prompts → AGENTS.md / SYSTEM.md**
Bereits eingerichtet. Zusätzlich gibt es:
```bash
~/.pi/agent/SYSTEM.md        # ersetzt den kompletten System-Prompt
~/.pi/agent/APPEND_SYSTEM.md # wird ans Ende angehängt
```

**3. Tools**
Pi hat eingebaute Tools (read, write, edit, bash). Eigene Tools werden als Pi-Extensions im Verzeichnis `~/.pi/agent/extensions/` registriert — du hast dort bereits eine (fact-checker). Das Modell sieht die Tool-Definitionen im System-Prompt und ruft sie über die OpenAI function-calling API auf (deshalb ist `--jinja` wichtig).

**4. MCP-Server → Pi-Packages**
Pi unterstützt MCP-Server als Packages. In deiner `settings.json` ist `npm:pi-llama-cpp` bereits eingetragen. Weitere MCP-Server werden analog hinzugefügt:
```json
{
  "packages": [
    "npm:pi-llama-cpp",
    "npm:@modelcontextprotocol/server-filesystem",
    "npm:irgendein-mcp-server"
  ]
}
```
Der MCP-Server läuft dann als Prozess neben pi — nicht im llama-cpp-Container.

> **Einzige Ausnahme**: Statischer System-Prompt direkt im Container
> llama.cpp hat einen `--system-prompt`-Flag, der einen festen Prompt beim Serverstart einbrennt. Das ist aber weniger flexibel als AGENTS.md und kollidiert mit pi's eigenem System-Prompt — daher eher nicht empfehlenswert.

---

## Server-Einstellungen

### Kann ich die Server-Einstellungen im laufenden Betrieb ändern?

**Größtenteils nein** — llama.cpp lädt alle Parameter beim Start und allokiert KV-Cache, GPU-Layer-Verteilung und Kontextfenster fest. Ein Neustart ist für Infrastruktur-Änderungen nötig.

#### Was sich zur Laufzeit ändern lässt

**Sampling-Parameter — pro API-Request überschreibbar:**
Pi (und jeder andere API-Client) kann `temperature`, `top_p`, `top_k`, `repeat_penalty`, `max_tokens` in jedem einzelnen Request überschreiben — unabhängig vom Server-Default:

```bash
POST /v1/chat/completions
{
  "temperature": 0.0,
  "top_k": 20,
  "max_tokens": 512,
  ...
}
```

Der Server-Default gilt nur, wenn der Request den Parameter weglässt.

**/props-Endpoint** — llama.cpp hat eine undokumentierte API zum Ändern weniger Server-Properties zur Laufzeit (z.B. `default_generation_settings`), aber das ist instabil und von pi nicht genutzt.

#### Was einen Neustart erfordert

| 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 nach dem Laden unveränderlich |
| `--batch-size`, `--ubatch-size` | Interne Buffer-Allokation |
| Modell-Datei | Offensichtlich |

#### Fazit

Für Experimente mit Sampling-Parametern (temp, top_k etc.) brauchst du keinen Neustart — du kannst sie direkt im pi-Prompt oder per API-Call testen. Für alles andere gilt: stoppen, Datei anpassen, neu starten.