KoboldCpp: installieren, konfigurieren (GGUF, ROCm, API) — und im Vergleich zu Ollama

#Warum KoboldCpp

KoboldCpp ist ein Fork von llama.cpp, der als einzelne, eigenständig ausführbare Datei bereitgestellt wird. Sie laden eine Datei herunter, starten sie und haben sofort eine Weboberfläche zum Chatten in Ihrem Browser sowie eine HTTP-API. Sie müssen keinen Daemon installieren, keine Python-Abhängigkeiten verwalten und keinen proprietären Modellmanager verwenden: Sie geben der ausführbaren Datei den Pfad zu einer von Hugging Face heruntergeladenen GGUF-Datei an, und das ist alles.

Im Vergleich zu Ollama ist der Unterschied im Ansatz deutlich. Ollama verwaltet einen Modellkatalog, einen Daemon im Hintergrund (unter http://localhost:11434) und ein eigenes Paketformat. KoboldCpp hingegen verwaltet nichts: Es führt direkt die GGUF-Datei aus, die Sie ihm geben. Das macht es ideal, wenn Sie eine bestimmte, manuell heruntergeladene Quantisierung testen möchten, wenn Sie einen Rechner nutzen, auf dem Sie nichts installieren können, oder wenn Sie eine AMD-GPU haben, die anderswo schlecht unterstützt wird.

Eine einzige ausführbare Datei

Eine einzige ausführbare Datei, portabel, ohne Installation oder Administratorrechte.

GGUF direkt

Lädt jede von Hugging Face heruntergeladene .gguf-Datei ohne Konvertierung.

Erstklassige AMD-Unterstützung

Spezielle ROCm-Builds und ein Vulkan-Backend, die Radeon-Grafikkarten wirklich ausnutzen.

Alles inklusive

Weboberfläche KoboldAI Lite + API (nativ und OpenAI-kompatibel) in derselben Binärdatei.

#Voraussetzungen

KoboldCpp läuft unter Windows, Linux und macOS. Es funktioniert auch ausschließlich auf der CPU, doch eine GPU beschleunigt die Inferenz erheblich. Entscheidend ist, wie bei jedem GGUF-Runner, der verfügbare VRAM: Er bestimmt, welche Modellgröße und Quantisierung Sie vollständig auf die Grafikkarte laden können.

System-RAM

Mindestens 8 GB für ein kleines Modell im CPU-Betrieb, komfortable 16 GB, 32 GB zum Auslagern großer Modelle in den Arbeitsspeicher.

VRAM (Richtwerte für Q4_K_M)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB.

NVIDIA-GPU

CUDA-Builds. RTX 3060 12 GB (Einstieg), 4070 12 GB, 4080 16 GB, 4090 24 GB.

AMD-GPU

ROCm-Builds (Radeon RX 6000/7000) oder ein universelles Vulkan-Backend.

Eine GGUF-Datei

Von Hugging Face herunterladen (z. B. bei bartowski, einem der wichtigsten Anbieter von GGUF-Quantisierungen).

#Das Binärprogramm herunterladen

Alles läuft über die GitHub-Releases des Projekts (LostRuins/koboldcpp). Sie wählen die zu Ihrem Betriebssystem und Ihrer GPU passende Binärdatei – es gibt kein Installationsprogramm, sondern nur eine Datei, die Sie ausführbar machen müssen.

1. 01
   Die Releases öffnen

   Besuchen Sie github.com/LostRuins/koboldcpp/releases und suchen Sie nach der neuesten stabilen Version.
2. 02
   Die richtige Datei auswählen

   Windows mit NVIDIA: koboldcpp.exe (CUDA-Build). Windows ohne NVIDIA: koboldcpp_nocuda.exe (nutzt Vulkan/CLBlast). Linux: koboldcpp-linux-x64. AMD unter Linux: der ROCm-Build koboldcpp-linux-x64-rocm (siehe Abschnitt AMD).
3. 03
   Ausführbar machen (Linux/macOS)

   Laden Sie die Datei herunter und erteilen Sie ihr anschließend die Ausführungsberechtigung, bevor Sie sie starten.

# Récupérer le binaire (adaptez l'URL à la dernière release)
wget https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64

# Le rendre exécutable
chmod +x koboldcpp-linux-x64

# Vérifier qu'il se lance
./koboldcpp-linux-x64 --help

#Ein GGUF-Modell laden und chatten

Im Kern genügt ein Befehl: Sie übergeben den Pfad zur GGUF-Datei mit --model. KoboldCpp startet einen lokalen Server und öffnet die URL der Weboberfläche oder zeigt sie Ihnen an; standardmäßig lautet sie http://localhost:5001.

# Lancer avec un modèle, en offloadant toutes les couches sur le GPU
./koboldcpp-linux-x64 \
  --model ./qwen3.5-9b-instruct-Q4_K_M.gguf \
  --gpulayers 999 \
  --contextsize 8192

--model

Pfad zur zu ladenden .gguf-Datei.

--gpulayers

Anzahl der auf die GPU ausgelagerten Schichten. 999 = alles, was in den VRAM passt.

--contextsize

Größe des Kontextfensters in Tokens (z. B. 4096, 8192, 16384).

--port

Port, auf dem der Dienst lauscht (Standard: 5001).

--host

Adresse, auf der der Server lauscht. 0.0.0.0, um ihn im lokalen Netzwerk verfügbar zu machen.

Öffnen Sie nach dem Start http://localhost:5001 in Ihrem Browser: Dort finden Sie KoboldAI Lite, eine vollständige Chat-Oberfläche mit Verlauf, Sampling-Einstellungen und Modi (chat, instruct, Schreiben). Eine weitere Installation ist nicht erforderlich.

#AMD-GPU: ROCm und Vulkan

In diesem Bereich hebt sich KoboldCpp am stärksten von Ollama ab. Je nach Ihrem System und Ihrer Grafikkarte gibt es zwei Möglichkeiten, die Verarbeitung auf einer Radeon zu beschleunigen.

#Der ROCm-Weg (Linux, maximale Leistung)

ROCm ist AMDs Software-Stack für GPU-Berechnungen, das Gegenstück zu CUDA. Das Projekt stellt spezielle ROCm-Builds bereit, die auf Radeon RX 6000/7000 die beste Leistung bieten. ROCm muss auf dem System installiert sein; anschließend wird die ROCm-Binärdatei genau wie die anderen gestartet.

# Build ROCm dédié
chmod +x koboldcpp-linux-x64-rocm

# Certaines cartes non officiellement supportées nécessitent de forcer
# la version d'architecture GPU (ex. RX 6700 XT -> gfx1030)
export HSA_OVERRIDE_GFX_VERSION=10.3.0

./koboldcpp-linux-x64-rocm \
  --model ./gemma-4-12b-it-Q4_K_M.gguf \
  --usecublas \
  --gpulayers 999 \
  --contextsize 8192

#Der Weg über Vulkan (universell, einfach)

Wenn Sie ROCm abschreckt oder es nicht verfügbar ist (Windows, zu alte Karte, iGPU), ist das Vulkan-Backend eine hervorragende Alternative. Es ist herstellerunabhängig: Es läuft auf AMD, Intel und NVIDIA ohne einen herstellerspezifischen Software-Stack für Berechnungen, allerdings mit einem leichten Leistungsverlust gegenüber ROCm oder CUDA.

./koboldcpp-linux-x64 \
  --model ./granite-4.2-8b-instruct-Q4_K_M.gguf \
  --usevulkan \
  --gpulayers 999 \
  --contextsize 8192

#Kontext und Offloading

Zwei Einstellungen bestimmen, ob Ihr Modell in den GPU-Speicher passt und wie schnell es antwortet: die Anzahl der auf die GPU ausgelagerten Schichten und die Kontextgröße. Eine gute Abstimmung verhindert das Ausweichen in den System-RAM, wodurch die Geschwindigkeit einbricht.

#Offloading von Schichten (--gpulayers)

Ein Modell besteht aus Schichten (Layers). Jede im VRAM gespeicherte Schicht wird von der GPU berechnet; die übrigen laufen auf der CPU. --gpulayers 999 versucht, alles auf die GPU zu laden. Wenn die Karte nicht genug VRAM hat, reduzieren Sie diese Zahl: Das Modell wird dann auf GPU und CPU verteilt (teilweises Offloading), langsamer, aber funktionsfähig.

Alles passt in den VRAM

--gpulayers 999, maximale Geschwindigkeit, das gesamte Modell auf der GPU.

Zu wenig VRAM

Senken Sie den Wert (z. B. auf 20 oder 30), bis das Laden gelingt, ohne den Speicher der Grafikkarte vollständig auszulasten.

Keine GPU

--gpulayers 0, alles auf der CPU: langsam, funktioniert aber überall.

#Kontextfenster (--contextsize)

Der Kontext ist die Textmenge (in Tokens), die das Modell im Speicher hält: Systemprompt, Verlauf und Frage. Je größer er ist, desto mehr VRAM belegt der KV-Cache. Erhöhen Sie den Kontext nicht über Ihren Bedarf hinaus: 4096 bis 8192 reichen für gewöhnliche Chats, 16384 und mehr für die Analyse langer Dokumente.

#Integrierte API und Webinterface

KoboldCpp stellt zwei APIs auf demselben Port bereit (standardmäßig 5001): seine eigene native KoboldAI-API und eine OpenAI-kompatible API unter /v1. Letztere ermöglicht es Ihnen, KoboldCpp an jedes Tool anzubinden, das das OpenAI-Protokoll unterstützt – genau wie einen Ollama- oder llama-server-Endpunkt.

curl http://localhost:5001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp",
    "messages": [
      {"role": "user", "content": "Explique le offloading GPU en une phrase."}
    ]
  }'

In Python lässt sich dank der OpenAI-Kompatibilität das offizielle SDK weiterverwenden, indem Sie einfach die Basis-URL ändern und einen Dummy-Schlüssel einsetzen.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="koboldcpp",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Bonjour en une phrase."}],
)
print(resp.choices[0].message.content)

Webinterface

KoboldAI Lite unter http://localhost:5001: Chat, erweitertes Sampling, Personas, Gedächtnis.

OpenAI-API

Endpoint /v1/chat/completions zum Anbinden von Open WebUI, Skripten oder Agenten.

Native API

KoboldAI-Endpunkte für eine sehr präzise Steuerung von Sampling und Generierung.

#Fehlerbehebung

Laden schlägt auf AMD fehl

Karte wird von ROCm nicht erkannt: Setzen Sie HSA_OVERRIDE_GFX_VERSION auf den Wert einer ähnlichen Architektur (z. B. 10.3.0) oder wechseln Sie zu --usevulkan.

Sehr langsames Generieren

Das Modell wird teilweise auf die CPU ausgelagert. Verringern Sie --contextsize, reduzieren Sie --gpulayers, um eine Überlastung zu vermeiden, oder wechseln Sie zu einer niedrigeren Quantisierungsstufe (Q5 → Q4_K_M).

« out of memory » beim Start

Der VRAM ist durch das Modell und den KV-Cache vollständig belegt. Verringern Sie den Kontext oder das GPU-Offloading, oder wählen Sie eine speichersparendere Quantisierung.

Port bereits verwendet

Ändern Sie den Port mit --port (z. B. --port 5002), wenn 5001 belegt ist.

Zugriff von einem anderen Gerät

Fügen Sie --host 0.0.0.0 hinzu, damit der Dienst auf Verbindungen aus dem lokalen Netzwerk lauscht, und öffnen Sie den Port in der Firewall.

Zusammenfassend ist KoboldCpp die pragmatische Wahl, wenn Sie ohne Installation auskommen möchten, direkte Kontrolle über die GGUF-Datei und das Offloading wünschen oder einfach endlich eine AMD-Grafikkarte richtig auslasten wollen. Für einen Modellkatalog und eine sofort nutzbare Systemintegration bleibt Ollama komfortabler; bei Portabilität und Feinabstimmung gewinnt KoboldCpp.

#Weiterführende Informationen

Diese Anleitungen ergänzen die vorliegende Anleitung und behandeln verwandte Bausteine:

Ollama mit AMD-GPU (ROCm)

Der andere AMD-Ansatz mit Ollama, um ROCm in beiden Ökosystemen zu vergleichen.

Quantisierung wählen (Q4, Q5, Q8, FP16)

Um Modellgröße, VRAM-Bedarf und Qualität gegeneinander abzuwägen, bevor Sie eine GGUF-Datei herunterladen.

llama-server: eine lokale OpenAI-API mit llama.cpp

Die nächstliegende Alternative basierend auf dem gleichen Grundgerüst llama.cpp, falls Sie die API bevorzugen.