- KoboldCpp ist eine einzelne ausführbare Datei – laden Sie sie herunter, geben Sie die GGUF-Modell-Datei an, und sofort starten eine Browser-Benutzeroberfläche sowie eine OpenAI-kompatible API auf Port 5001.
- Die GPU-Offload-Steuerung erfolgt über
--gpulayers N; beginnen Sie mit 999, um einen vollständigen Offload zu versuchen, und verringern Sie den Wert, falls Sie auf Speicherüberlauf-Fehler stoßen. - Use it when you want a built-in story/chat UI or need KoboldAI-compatible endpoints; use Ollama if you prefer a managed model library and CLI-first workflow.
- Kein Installationsvorgang, kein Paketmanager, kein Hintergrunddienst – lediglich eine einzelne ausführbare Datei und eine GGUF-Datei.
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.ggufVorkompilierte 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.ggufDies 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 5001Referenz 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-UI und 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/completionsund/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:
- Verwenden Sie den VRAM-Rechner VRAM-Rechner, um abzuschätzen, wie viele Schichten bei Ihrer gewünschten Kontextgröße Platz finden.
- Beginnen Sie mit
--gpulayers 999um eine vollständige Auslagerung zu versuchen. KoboldCpp begrenzt diesen Wert automatisch auf die tatsächliche Schichtanzahl des Modells. - 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 Leitfaden zu den besten GPUs für lokale LLMs 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
Alle drei basieren auf derselben llama.cpp-Engine und unterstützen GGUF-Modelle. Die Unterschiede liegen im Workflow und in der Benutzeroberfläche.
| 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 |
| Ideal 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.