Fehlerbehebung: Symptom → Ursache → Fix

Lokale Inferenz scheitert in Mustern. Dieselben Dutzend Symptome erklären fast jede Hilfeanfrage, und jedes hat eine langweilige Ursache und einen Zwei-Minuten-Fix. Scannen Sie die Tabelle, wenden Sie den Fix an und lesen Sie dann die Zahlen, um zu bestätigen, dass Sie wirklich repariert sind.

Die Diagnosetabelle

Symptom	Wahrscheinliche Ursache	Fix
Ausgabe enthält Rollen-Tokens (`user:`, `<	im_start	>`)
Sofort leere Antwort	Template rendert einen „beendeten“ Chat, oder falsches EOS-Token	Template reparieren; EOS prüfen: Prompting
Wiederholt Ihre Frage, statt zu antworten	Base-Modell, kein Instruct-Modell	Ein Instruct-/Chat-GGUF nutzen
Out of Memory beim Laden	Gewichte + Quant übersteigen den VRAM	Kleineres Quant oder kleineres Model: VRAM-Mathematik
Out of Memory mitten in der Generierung	KV-Cache wächst über die Reserve hinaus	Kürzerer Kontext, KV-Cache q8_0: KV-Cache
1–3 tok/s trotz GPU	Layer liegen noch auf der CPU	Voller Offload (`n_gpu_layers`): Engine-Regler
Langsames erstes Token, schneller Stream danach	Prefill-limitiert: sehr lange Prompts	Prompts kürzen, batchen, schnellerer Prefill: Geschwindigkeit
Endlose Wiederholung, Phrasen-Schleifen	Sampler zu freizügig, Strafen aus	Temperatur ≤ 0,8, repeat_penalty 1,05–1,1: Sampling
Koreanische Ausgabe ist Zeichensalat oder steif	Model schwach in Koreanisch	Multilinguale Familien (Qwen, Gemma): Modellfamilien
Ausgabe mitten im Satz gekappt	Kontextfenster voll oder max_tokens zu niedrig	Kontext stutzen oder das Ausgabelimit erhöhen
Ungültiges JSON von einem guten Model	Freies Sampling	Beschränkte Dekodierung: Strukturierte Ausgabe
Model ignoriert Ihre Anweisungen	Lost in the Middle bei langen Prompts	Ziel zuerst, Nutzlast zuletzt, die Bitte wiederholen: Prompting
Absturz oder Coredump beim Laden	Beschädigter Download	Prüfsumme verifizieren, neu herunterladen

Lesen Sie symptom-zuerst, nicht ursache-zuerst: Gleichen Sie ab, was Sie sehen, wenden Sie den Fix an, messen Sie erneut. Die meisten „mein Model ist kaputt“-Berichte enden bei Zeile 1, 2 oder 6.

Der Fünf-Minuten-Preflight

Vor jedem tiefen Debuggen sammeln Sie die Fakten:

nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv   # GPU + VRAM
ls -lh model.gguf                                                   # Größe vs. VRAM
llama-server --version                                              # Engine-Build

Ist die Modelldatei größer als der freie VRAM, ist Zeile 4 Ihre Antwort, und kein Flag rettet Sie. Klettert memory.used während der Generierung stetig, ist es der KV-Cache, kein Leak.

Wie normal aussieht

Bevor Sie Leistung debuggen, kennen Sie die Größenordnung. Decode-Geschwindigkeit für ein 7–8B-Q4_K_M-Modell, Batch 1:

Hardware	Decode-tok/s
Mittelklasse-GPU (RTX-3060/4060-Klasse)	30–60
High-End-GPU (RTX-3090/4090-Klasse)	100–150
Apple M-Serie (Unified Memory)	20–40
Nur CPU (moderner 8-Kerner)	3–8

Zwei Formeln erklären das meiste:

decode tok/s ≈ memory bandwidth (GB/s) ÷ model size (GB)
VRAM needed  ≈ weights + KV cache + 1–2 GB overhead

Ein 4,5-GB-7B-Quant auf einer 288-GB/s-Karte toppt theoretisch bei nahe 64 tok/s aus; erwarten Sie real ~45–55. Liegen Sie innerhalb des Zweifachen der Tabelle, ist Ihre Hardware nicht der Bug.

Time-to-First-Token (TTFT) sollte für kurze Prompts deutlich unter einer Sekunde liegen; es wächst mit der Prompt-Länge geteilt durch den Prefill-Durchsatz (der mit 10–100× Decode-Geschwindigkeit läuft). Ein 10k-Token-Prompt, der 20 s vor dem ersten Token braucht, ist Prefill-limitiert, nicht kaputt.

VRAM-Buchhaltung: Ladeten die Gewichte fein, aber Sie treffen später auf OOM, ist es der KV-Cache oder die Kontextlänge, nicht das Quant — KV-Cache.

Der Arbeitsablauf: eine Variable tauschen

Bugs verstecken sich, wenn Sie zwei Dinge zugleich ändern. Isolieren Sie entlang dieser Kette — Model → Engine → Konfiguration → Prompt:

Baseline. Bekannt-gutes Model, bekannt-gute Engine, Default-Flags. Funktioniert Chat? Dann ist der Stack fein.
Das Model tauschen (gleiche Engine, gleiche Flags). Bricht es? Dann ist es die Datei oder ihr Template.
Die Engine tauschen (gleiches Model). Bricht es? Engine-Bug oder Flag-Übersetzung.
Flags bisecten. Defaults wiederherstellen, Flags einzeln zurückgeben, bis es bricht.
Den gerenderten Prompt ausgeben. Wenn die Ausgabe seltsam, aber laufend ist, lebt die Wahrheit im gerenderten Template.

Machen Sie unterwegs Notizen — „funktioniert bei Temperatur 0,8, bricht mit min_p 0,2“ ist eine Diagnose; „habe Sachen probiert, immer noch schlecht“ ist keine.

Wie man gut um Hilfe bittet

Ein guter Hilfepost ist ein Laborbericht. Schließen Sie ein:

Modell-Datei: exakter Name, Quant und Quelle (qwen2.5-7b-instruct-q4_k_m.gguf, welches Repo).
Engine und Version: llama.cpp-Build-Datum, Ollama-Version, vLLM-Release — Engines ändern sich wöchentlich.
Exakte Flags oder der API-Aufruf: die ganze Befehlszeile oder der Anfragekörper, keine Paraphrase.
Hardware: GPU + VRAM (oder Mac + RAM), CPU, falls sie Layer trägt.
Beobachtete Zahlen: tok/s, TTFT, benutzter VRAM und der exakte Fehlertext, falls vorhanden.
Was Sie schon probierten und was sich dadurch änderte.

Kopier-Einfüge-Gerüst:

Model:    qwen2.5-7b-instruct-q4_k_m.gguf (bartowski repo)
Engine:   llama.cpp b4321 (llama-server)
Flags:    -ngl 99 -c 8192 --temp 0.7
Hardware: RTX 4060 8GB / Ryzen 7 / 32GB RAM
Beobachtet: lädt in 21 s, ~35 tok/s, TTFT ~1,2 s, dann OOM bei ~6k Ctx
Probiert: -c 4096 → kein Absturz; q8_0 KV → kein Absturz

Mit diesen sechs Fakten mappen sich die meisten Probleme in einer Antwort auf eine Zeile der Tabelle oben. Dieses Forum existiert genau für diese Posts — bringen Sie den Laborbericht, und Sie bekommen den Fix.

Verwandt: Engine-Regler · VRAM-Mathematik · KV-Cache · Sampling