dschlueter 3e60a072b4 Update documentation: Add Qwopus3.6 coding variant with multimodal support

2026-05-11 19:17:57 +02:00

10 KiB

Raw Blame History

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.

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

# 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)

# 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

# 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

# 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

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

# 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

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)

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

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

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:

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

~/.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:

{
  "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

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

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

GPU-Verfügbarkeit prüfen: nvidia-smi
Modell-Datei existiert: /home/dschlueter/nvme2n1p7_home/huggingface/models/qwen3/
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

GPU-Zugriff: NVIDIA Container Toolkit installieren
Speicher: Ausreichend VRAM verfügbar?
Port-Konflikt: Anderen Server stoppen

Modell-Datei nicht gefunden

# 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

Neue GGUF-Datei in HF_HOME-Pfad herunterladen
docker-compose.yml oder Shell-Skript -m Parameter aktualisieren
Container neu starten

Konfiguration sichern

# 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.

10 KiB Raw Blame History