KoboldCpp: Vollständiger Leitfaden für die Single-Binary-Local-LLM-Laufzeitumgebung

KoboldCpp ist eine Einzel-Datei- lokales LLM Laufzeitumgebung, die auf llama.cpp basiert. Laden Sie eine einzige ausführbare Datei herunter, verweisen Sie sie auf ein GGUF-Modell, und Sie erhalten sofort eine browserbasierte Chat-Oberfläche sowie eine OpenAI-kompatible REST-API – ohne Paketmanager, ohne zu konfigurierenden Hintergrunddienst und ohne Installationsschritt. Es läuft unter Windows, macOS und Linux mit optionaler GPU-Beschleunigung über CUDA, Metal, Vulkan oder OpenCL.

KoboldCpp herunterladen

Veröffentlichungen werden auf der KoboldCpp-GitHub-Release-Seiteveröffentlicht. Jede Version enthält plattformspezifische Binärdateien; wählen Sie diejenige aus, die zu Ihrer Hardware passt.

Windows

Herunterladen koboldcpp.exe für NVIDIA-GPU-Unterstützung (CUDA-Bibliotheken sind integriert – keine separate Installation des CUDA-Toolkits erforderlich, lediglich der aktuelle Standard-NVIDIA-Anzeigetreiber). Falls Sie keine NVIDIA-GPU besitzen, laden Sie stattdessen koboldcpp_nocuda.exe herunter. Ein Doppelklick auf die .exe-Datei öffnet einen grafischen Startassistenten, in dem Sie Ihre Modell-Datei auswählen und Einstellungen vornehmen können, bevor der Server gestartet wird. Um den Assistenten zu überspringen und direkt über die Befehlszeile zu starten, übergeben Sie das Flag --skiplauncher .

macOS

Laden Sie die macOS-Binärdatei von der Release-Seite herunter (üblicherweise benannt als koboldcpp_mac oder als .dmg-Datei verteilt). Die Metal-GPU-Beschleunigung ist automatisch enthalten – kein zusätzliches Flag erforderlich; KoboldCpp erkennt Apple Silicon und nutzt standardmäßig Metal. Beim ersten Start warnt macOS möglicherweise, dass die Binärdatei von einem nicht identifizierten Entwickler stammt; klicken Sie mit der rechten Maustaste → Öffnen, um Gatekeeper zu umgehen.

Linux

Laden Sie die Linux-Binärdatei herunter und machen Sie sie ausführbar:

chmod +x koboldcpp
./koboldcpp --model /pfad/zu/modell.gguf

Vorkompilierte Linux-Binärdateien enthalten CPU- und Vulkan-Unterstützung. Für CUDA auf NVIDIA-Grafikkarten suchen Sie nach einer Release-Ressource mit dem Suffix cu im Dateinamen oder kompilieren Sie aus dem Quellcode mit make LLAMA_CUDA=1. Falls Ihr Treiber zu alt für die integrierte CUDA-Version ist, stellt die Vulkan-Version eine zuverlässige Alternative dar.

Ein GGUF-Modell beschaffen

KoboldCpp lädt GGUF-Dateien direkt – demselben Format, das auch von llama.cpp und Ollama verwendet wird. Die primäre Quelle ist Hugging Face; suchen Sie nach einem Modellnamen plus „GGUF“. Bevor Sie das Modell herunterladen, nutzen Sie den VRAM-Rechner , um sicherzustellen, dass das Modell bei Ihrer gewählten Kontextgröße in den verfügbaren GPU-Speicher passt. Zu beachtende Quantisierungsstufen:

Quantisierung	Qualität	Größe vs. FP16	Wann man verwendet
Q2_K	Wahrnehmbarer Qualitätsverlust	~25%	Nur bei sehr begrenztem VRAM
Q4_K_M	Gut	~45%	Standardwahl für die meisten Hardwarekonfigurationen
Q5_K_M	Sehr gut	~55%	Wenn Sie zusätzlichen VRAM zur Verfügung haben
Q8_0	Nahezu verlustfrei	~80%	Für GPUs mit viel VRAM oder große CPU-Hauptspeicherkapazität

KoboldCpp starten

Der minimale Befehl auf jeder Plattform:

./koboldcpp --model /pfad/zu/modell.gguf

Dies startet den Server unter http://localhost:5001. Öffnen Sie diese URL in Ihrem Browser, um die Web-Oberfläche zu erreichen.

Windows – GUI-Startassistent

Doppelklicken Sie auf koboldcpp.exe. Das Assistenten-Fenster ermöglicht es Ihnen, eine Modell-Datei auszuwählen und GPU-Layer, Kontextgröße sowie Backend einzustellen – ganz ohne Befehlszeile. Klicken Sie nach Abschluss auf Starten ; ein Terminalfenster öffnet sich mit den Server-Protokollen, und die Browser-Oberfläche wird automatisch gestartet.

Befehlszeile (alle Plattformen)

Ein typischer Startbefehl mit GPU-Offload, benutzerdefinierter Kontextgröße und explizitem Port:

./koboldcpp 
  --model ./models/llama3-8b-q4_k_m.gguf 
  --gpulayers 32 
  --contextsize 8192 
  --port 5001

Referenz zu wichtigen Flags:

Flagge	Standard	Was es steuert
--model	—	Pfad zur GGUF-Datei (erforderlich)
--gpulayers	0	Anzahl der Transformer-Layer, die auf die GPU ausgelagert werden
--contextsize	4096	Maximales Kontextfenster in Tokens
--port	5001	HTTP-Port
--host	127.0.0.1	Bind-Adresse (verwenden Sie 0.0.0.0, um sie im lokalen Netzwerk verfügbar zu machen)
--threads	automatisch	CPU-Threads für die Inferenz
--flashattention	aus	Verringert den VRAM-Bedarf bei langen Kontexten mittels Flash Attention
--usecublas	aus	Erzwingt das CUDA-Backend (NVIDIA)
--usevulkan	aus	Vulkan-Backend (AMD/Intel/NVIDIA)
--skiplauncher	aus	Nur unter Windows: Umgehung des GUI-Starters
--smartcontext	aus	Verschiebt den Kontext statt der Generierung bei vollständigem Kontext zu stoppen

Die Web-Oberfläche und die OpenAI-kompatible API

Sobald KoboldCpp ausgeführt wird, stellt es zwei Schnittstellen über denselben Port bereit:

• Browser-Oberfläche — http://localhost:5001: Eine voll ausgestattete Textgenerierungs-Oberfläche mit Story-, Chat- und Instruct-Modus. Unterstützt Prompt-Vorlagen, Speicher, Autorenhinweise und World-Info-Felder, die vom KoboldAI-Projekt übernommen wurden.
• KoboldAI-API — http://localhost:5001/api/v1: Wird von Frontends wie SillyTavern und Agnaistic genutzt.
• OpenAI-kompatible API — http://localhost:5001/v1: Implementiert /v1/chat/completions und /v1/completions. Jeder Client, der eine benutzerdefinierte Basis-URL akzeptiert, funktioniert – darunter LangChain, das OpenAI-Python-SDK und die meisten quelloffenen Chat-Anwendungen.

So richten Sie das OpenAI-Python-SDK auf KoboldCpp aus:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # KoboldCpp benötigt standardmäßig keinen API-Schlüssel
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Hallo"}]
)

GPU-Offload: Den richtigen Wert für --gpulayers wählen

Jede Transformer-Schicht, die auf die GPU ausgelagert wird, verlagert die Verarbeitung von der CPU weg und erhöht die Token-pro-Sekunde-Rate drastisch. Der Kompromiss besteht in einem höheren VRAM-Bedarf. Die Gesamtanzahl der Schichten eines Modells ist durch seine Architektur festgelegt – übliche Werte sind 32 für 7B-/8B-Modelle, 40 für 13B-Modelle und 80 für 70B-Modelle. Jede Schicht beansprucht etwa einen gleichen Anteil des gesamten GPU-Speichers des Modells.

Praktischer Ansatz:

1. Verwenden Sie den VRAM-Rechner VRAM-Rechner, um abzuschätzen, wie viele Schichten bei Ihrer gewünschten Kontextgröße Platz finden.
2. Beginnen Sie mit --gpulayers 999 um eine vollständige Auslagerung zu versuchen. KoboldCpp begrenzt diesen Wert automatisch auf die tatsächliche Schichtanzahl des Modells.
3. Falls beim Start ein Speicherüberlauf-Fehler auftritt, verringern Sie den Wert und versuchen Sie es erneut. Im Server-Log werden die Zuweisungen pro Schicht ausgegeben, um Ihnen die Kalibrierung zu erleichtern.

Eine teilweise Auslagerung wird unterstützt und ist nützlich – selbst das Auslagern der Hälfte der Schichten eines großen Modells führt zu einer deutlichen Geschwindigkeitssteigerung gegenüber einer reinen CPU-Inferenz. Falls Sie unsicher sind, welche GPU sich am besten für ein bestimmtes Modell eignet, sehen Sie sich die bestes GPUs für lokale LLMs Anleitung und das Aufschlüsselung des VRAM-Bedarfs nach Modell.

Kontextgröße und Leistungseinstellungen

Kontextgröße (--contextsize) ist der einzige entscheidende Faktor für den VRAM-Bedarf neben den Modellgewichten. Ein 7B-Modell im Q4_K_M-Format benötigt etwa 4 GB für die Gewichte; die Erweiterung des Kontexts von 4096 auf 32768 Token kann mehrere weitere Gigabyte für den KV-Cache hinzufügen. Aktivieren Sie --flashattention KV-Shift

Weitere Einstellungen, die die Geschwindigkeit beeinflussen:

• --threads: Bei reiner CPU-Inferenz sollten Sie diesen Wert nahe an der Anzahl Ihrer physischen Kerne wählen, nicht an der Anzahl der logischen (Hyperthreading-)Kerne.
• --batchsize: Höhere Werte (z. B. 512) verbessern die Geschwindigkeit der Prompt-Verarbeitung, erhöhen jedoch den maximalen VRAM-Bedarf während der Prefill-Phase.
• --smartcontext„Smart Context“: Sobald der Kontext voll ist, verschiebt KoboldCpp die ältesten Tokens heraus, anstatt die Generierung zu beenden – nützlich für lange interaktive Sitzungen.

KoboldCpp im Vergleich zu Ollama und llama.cpp

All three are built on the same llama.cpp engine and support GGUF-Modelle. The differences are in workflow and interface.

	KoboldCpp	Ollama	llama.cpp (llama-server)
Distribution	Einzelnes Binärprogramm, keine Installation erforderlich	Installer mit Hintergrunds-Daemon	Aus dem Quellcode kompilieren oder vorgefertigte Binärdateien verwenden
Web-Oberfläche	Ja, integriert (umfangreich)	Keine (erfordert externe Drittanbieter-Lösung)	Minimal
Modellverwaltung	Manuell – eigene GGUF-Datei bereitstellen	Integriert: ollama pull	Manuell – eigene GGUF-Datei bereitstellen
OpenAI-kompatible API	Ja (/v1)	Ja	Ja
KoboldAI-API	Ja	Nein	Nein
Am besten geeignet für	Kreatives Schreiben, Rollenspiele, SillyTavern	Entwicklungstools, CLI, systemd-Service	Minimaler Ressourcenverbrauch, benutzerdefinierte Builds

Wählen Sie KoboldCpp wenn Sie ein Setup ohne Installation benötigen, die integrierte Story-/Chat-Benutzeroberfläche oder Kompatibilität mit KoboldAI-Frontends wie SillyTavern.
Wählen Sie Ollama wenn Sie eine verwaltete Modellbibliothek, einen systemd Service oder eine engere Integration in die Befehlszeile (CLI) wünschen – siehe die Kompletter Ollama-Leitfaden für eine ausführliche Anleitung.
Wählen Sie llama.cpp direkt wenn Sie eine benutzerdefinierte Integration entwickeln oder Zugriff auf die aktuellsten Funktionen der upstream-Version benötigen, bevor diese in Downstream-Wrapper übernommen werden.

Falls Sie noch unsicher sind, ob Sie LLMs überhaupt selbst hosten oder stattdessen eine gehostete API nutzen sollen, kann die Selbsthosting- versus-API-Kosten-Grenzwert-Rechner helfen, den Kostenbreakeven-Punkt zu ermitteln.

Häufig gestellte Fragen

Erfordert KoboldCpp eine separate Installation der CUDA-Treiber?

Unter Windows enthält koboldcpp.exe die CUDA-Runtime-Bibliotheken; es ist daher lediglich der Standard-NVIDIA-Anzeigetreiber erforderlich – eine separate Installation des CUDA-Toolkits ist nicht nötig. Unter Linux verweisen CUDA-Builds normalerweise auf die installierte CUDA-Runtime, sodass die Kompatibilität der Treiberversion entscheidend ist; bei zu alten Treibern stellt der Vulkan-Build die einfachste Alternative dar.

Was bedeutet „--gpulayers 0“?

Null GPU-Schichten bedeutet, dass die gesamte Berechnung auf der CPU erfolgt. Dies ist die Standardeinstellung, wenn kein GPU-Flag angegeben wird. Die Inferenz auf der CPU ist deutlich langsamer – typischerweise 2–10 Tokens/Sekunde auf einer modernen CPU im Vergleich zu 40–100+ Tokens/Sekunde auf einer Mittelklasse-GPU – funktioniert jedoch auf jedem Rechner, unabhängig von der Verfügbarkeit einer GPU.

Kann ich KoboldCpp als OpenAI-API-Ersatz für meine Anwendung verwenden?

Ja. Legen Sie in Ihrem OpenAI-Client die base_url auf http://localhost:5001/v1 fest und verwenden Sie als api_key eine beliebige nicht-leere Zeichenkette (standardmäßig wird dieser Schlüssel nicht validiert). Das Feld Modell wird akzeptiert, aber ignoriert – es wird stets das jeweils geladene GGUF-Modell verwendet. Sowohl Chat- als auch Text-Vervollständigungen funktionieren; Endpunkte für Embeddings und Bilder werden nicht unterstützt.

Wie führe ich zwei verschiedene Modelle gleichzeitig aus?

Jeder KoboldCpp-Prozess verarbeitet genau ein Modell. Starten Sie eine zweite Instanz mit einem anderen --port -Wert (z. B. 5002), die auf eine andere GGUF-Datei verweist. Es gibt keinen integrierten Lastverteiler; die Verteilung auf die Instanzen muss auf Anwendungsebene erfolgen.

Warum ist die Generierung trotz GPU langsamer als erwartet?

Die häufigste Ursache ist eine teilweise Offloadung auf die CPU: Falls --gpulayers kleiner ist als die Gesamtanzahl der Modellschichten, werden die verbleibenden Schichten auf der CPU ausgeführt und bilden einen Engpass. Prüfen Sie das Startprotokoll – KoboldCpp gibt dort exakt an, wie viele Schichten auf die GPU bzw. auf die CPU verteilt wurden. Stellen Sie außerdem sicher, dass die korrekte Backend-Engine (CUDA/Metal/Vulkan) in der Startausgabe erscheint und keine CPU-Fallback-Lösung aktiviert wurde.

Ist es sicher, KoboldCpp im Netzwerk freizugeben?

Standardmäßig bindet KoboldCpp an 127.0.0.1 (ausschließlich localhost). Um es im lokalen Netzwerk (LAN) zugänglich zu machen, fügen Sie --host 0.0.0.0hinzu. Da keine integrierte Authentifizierung vorhanden ist, wird die Freigabe im LAN oder gar im öffentlichen Internet ohne vorgeschalteten Reverse-Proxy mit Authentifizierung nicht empfohlen.