#Pourquoi KoboldCpp

KoboldCpp est un fork de llama.cpp packagé en un seul exécutable autonome. Vous téléchargez un fichier, vous le lancez, et vous avez immédiatement une interface web de chat sur votre navigateur plus une API HTTP. Aucun daemon à installer, aucune dépendance Python à gérer, aucun gestionnaire de modèles propriétaire : vous pointez le binaire vers un fichier GGUF récupéré sur Hugging Face et c'est tout.

Face à Ollama, la différence de philosophie est nette. Ollama gère un catalogue de modèles, un daemon en arrière-plan (sur http://localhost:11434) et un format d'empaquetage maison. KoboldCpp, lui, ne gère rien : il exécute directement le GGUF que vous lui donnez. Cela le rend idéal quand vous voulez tester un quant précis téléchargé à la main, quand vous êtes sur une machine où vous ne pouvez rien installer, ou quand votre GPU est un AMD mal pris en charge ailleurs.

Binaire unique: Un seul fichier exécutable, portable, sans installation ni droits admin.
GGUF direct: Charge n'importe quel .gguf téléchargé sur Hugging Face, sans conversion.
AMD de première classe: Builds ROCm dédiés et backend Vulkan qui exploitent vraiment les Radeon.
Tout inclus: Interface web KoboldAI Lite + API (native et compatible OpenAI) dans le même binaire.

Origines côté roleplay

KoboldCpp vient de l'écosystème KoboldAI, très orienté écriture et jeu de rôle. Résultat : des réglages de sampling et de mémoire plus riches que la moyenne. Mais il reste un excellent runner généraliste pour du chat, du code ou du RAG.

#Prérequis

KoboldCpp tourne sur Windows, Linux et macOS. Il fonctionne en CPU pur, mais un GPU accélère fortement l'inférence. Le point clé, comme pour tout runner GGUF, c'est la VRAM disponible : elle détermine la taille de modèle et la quantification que vous pourrez charger entièrement sur la carte.

RAM système: 8 Go minimum pour un petit modèle en CPU, 16 Go confortable, 32 Go pour offloader de gros modèles.
VRAM (repères Q4_K_M): 3B ≈ 2 Go · 7B ≈ 5 Go · 14B ≈ 9 Go · 32B ≈ 19 Go · 70B ≈ 40 Go.
GPU NVIDIA: Builds CUDA. RTX 3060 12GB (entrée), 4070 12GB, 4080 16GB, 4090 24GB.
GPU AMD: Builds ROCm (Radeon RX 6000/7000) ou backend Vulkan universel.
Un fichier GGUF: À récupérer sur Hugging Face (ex. bartowski, un des principaux fournisseurs de quants GGUF).

→

Quelle quantification prendre

Q4_K_M est le meilleur compromis qualité/taille pour la plupart des usages. Montez en Q5_K_M ou Q8_0 si la VRAM le permet et que vous voulez plus de précision. Le guide « Choisir sa quantification » détaille les arbitrages.

#Télécharger le binaire

Tout se fait depuis les releases GitHub du projet (LostRuins/koboldcpp). Vous choisissez le binaire adapté à votre OS et à votre GPU — il n'y a pas d'installeur, juste un fichier à rendre exécutable.

01
Ouvrir les releases
Rendez-vous sur github.com/LostRuins/koboldcpp/releases et repérez la dernière version stable.
02
Choisir le bon fichier
Windows NVIDIA : koboldcpp.exe (build CUDA). Windows sans NVIDIA : koboldcpp_nocuda.exe (utilise Vulkan/CLBlast). Linux : koboldcpp-linux-x64. AMD sous Linux : le build ROCm koboldcpp-linux-x64-rocm (voir la section AMD).
03
Rendre exécutable (Linux/macOS)
Téléchargez puis donnez le droit d'exécution au fichier avant de le lancer.

Terminal (Linux)

# 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

Windows : double-clic possible

Sur Windows, lancer le .exe sans argument ouvre une interface graphique de configuration (le « launcher »). Vous y choisissez le modèle, le backend GPU et le contexte à la souris, sans ligne de commande.

#Charger un GGUF et discuter

Le cœur du fonctionnement tient en une commande : vous passez le chemin du fichier GGUF avec --model. KoboldCpp démarre un serveur local et ouvre (ou vous indique) l'URL de l'interface web, par défaut http://localhost:5001.

Terminal

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

--model: Chemin vers le fichier .gguf à charger.
--gpulayers: Nombre de couches déchargées sur le GPU. 999 = tout ce qui rentre en VRAM.
--contextsize: Taille de la fenêtre de contexte en tokens (ex. 4096, 8192, 16384).
--port: Port d'écoute (5001 par défaut).
--host: Adresse d'écoute. 0.0.0.0 pour exposer sur le réseau local.

Une fois lancé, ouvrez http://localhost:5001 dans votre navigateur : vous tombez sur KoboldAI Lite, une interface de chat complète avec historique, réglages de sampling et modes (chat, instruct, écriture). Aucune autre installation n'est nécessaire.

#GPU AMD : ROCm et Vulkan

C'est le terrain où KoboldCpp se distingue le plus d'Ollama. Deux voies existent pour accélérer sur une Radeon, selon votre système et votre carte.

#La voie ROCm (Linux, performances max)

ROCm est la pile de calcul GPU d'AMD, l'équivalent de CUDA. Le projet fournit des builds ROCm dédiés qui offrent les meilleures performances sur Radeon RX 6000/7000. Il faut que ROCm soit installé sur le système, puis on lance le binaire ROCm exactement comme les autres.

Terminal (AMD ROCm)

# 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 ./qwen2.5-14b-instruct-Q4_K_M.gguf \
  --usecublas \
  --gpulayers 999 \
  --contextsize 8192

HSA_OVERRIDE_GFX_VERSION

Beaucoup de Radeon grand public ne sont pas dans la liste officielle ROCm et échouent au démarrage. La variable HSA_OVERRIDE_GFX_VERSION force une architecture compatible proche (ex. 10.3.0 pour la génération RDNA2). C'est le réglage qui débloque la plupart des cartes.

#La voie Vulkan (universelle, simple)

Si ROCm vous rebute ou n'est pas disponible (Windows, carte trop ancienne, iGPU), le backend Vulkan est une excellente alternative. Il est vendor-agnostic : il tourne sur AMD, Intel et NVIDIA sans pile de calcul spécifique, au prix d'un léger surcoût de performance par rapport à ROCm ou CUDA.

Terminal (Vulkan)

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

→

Que choisir

Sur Linux avec une Radeon récente et ROCm installé : prenez ROCm pour la vitesse. Partout ailleurs (Windows, iGPU, matériel mixte) : Vulkan marche du premier coup. Comparez le débit tokens/sec sur votre machine, l'écart varie selon les modèles.

#Contexte et offloading

Deux réglages déterminent si votre modèle tient sur le GPU et à quelle vitesse il répond : le nombre de couches offloadées et la taille du contexte. Bien les calibrer évite le débordement en RAM, qui fait chuter la vitesse.

#Offloading des couches (--gpulayers)

Un modèle est composé de couches (layers). Chaque couche placée en VRAM est calculée par le GPU ; celles qui restent tournent sur le CPU. --gpulayers 999 tente de tout mettre sur le GPU. Si la carte n'a pas assez de VRAM, réduisez ce nombre : le modèle se répartit alors entre GPU et CPU (offloading partiel), plus lent mais fonctionnel.

Tout rentre en VRAM: --gpulayers 999, vitesse maximale, tout le modèle sur le GPU.
VRAM insuffisante: Baissez la valeur (ex. 20, 30) jusqu'à ce que le chargement passe sans saturer la carte.
Pas de GPU: --gpulayers 0, tout en CPU : lent mais fonctionne partout.

#Fenêtre de contexte (--contextsize)

Le contexte est la quantité de texte (en tokens) que le modèle garde en mémoire : prompt système, historique et question. Plus il est grand, plus le cache KV occupe de VRAM. Ne montez pas le contexte au-delà de ce dont vous avez besoin : 4096 à 8192 suffisent pour du chat courant, 16384+ pour analyser de longs documents.

Le piège du contexte gonflé

Passer --contextsize à 32768 « au cas où » réserve un cache KV énorme qui peut à lui seul déborder la VRAM et forcer l'offload CPU. Résultat : le modèle rentrait à 8k mais rame à 32k. Ajustez le contexte à votre usage réel.

#API et interface web intégrées

KoboldCpp expose deux API sur le même port (5001 par défaut) : sa propre API native KoboldAI, et une API compatible OpenAI sous /v1. Cette dernière vous permet de brancher KoboldCpp derrière n'importe quel outil qui parle le protocole OpenAI — exactement comme un endpoint Ollama ou llama-server.

Terminal (test API OpenAI)

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."}
    ]
  }'

Côté Python, la compatibilité OpenAI permet de réutiliser le SDK officiel en changeant simplement l'URL de base et en mettant une clé factice.

Python (SDK OpenAI)

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)

Interface web: KoboldAI Lite sur http://localhost:5001 : chat, sampling avancé, personas, mémoire.
API OpenAI: Endpoint /v1/chat/completions pour brancher Open WebUI, des scripts ou des agents.
API native: Endpoints KoboldAI pour un contrôle très fin du sampling et de la génération.

→

Combiner avec Open WebUI

Comme l'endpoint est compatible OpenAI, vous pouvez utiliser KoboldCpp comme backend derrière Open WebUI : renseignez http://localhost:5001/v1 comme connexion OpenAI dans les réglages de l'interface.

#Dépannage

Chargement qui échoue sur AMD: Carte non reconnue par ROCm : définissez HSA_OVERRIDE_GFX_VERSION avec l'architecture proche (ex. 10.3.0), ou basculez sur --usevulkan.
Génération très lente: Le modèle déborde en CPU. Baissez --contextsize, réduisez --gpulayers pour éviter la saturation, ou descendez d'une quantification (Q5 → Q4_K_M).
« out of memory » au démarrage: VRAM saturée par le modèle + le cache KV. Diminuez le contexte ou l'offloading, ou prenez un quant plus léger.
Port déjà utilisé: Changez avec --port (ex. --port 5002) si 5001 est occupé.
Accès depuis une autre machine: Ajoutez --host 0.0.0.0 pour écouter sur le réseau local, et ouvrez le port dans le pare-feu.

En résumé, KoboldCpp est le choix pragmatique quand vous voulez zéro installation, un contrôle direct sur le fichier GGUF et l'offloading, ou simplement faire enfin travailler sérieusement une carte AMD. Pour un catalogue de modèles et une intégration système clé en main, Ollama reste plus confortable ; pour la portabilité et le réglage fin, KoboldCpp gagne.

#Pour aller plus loin

Ces guides prolongent celui-ci et couvrent les briques voisines :

Ollama avec GPU AMD (ROCm): L'autre approche AMD, côté Ollama, pour comparer ROCm dans les deux écosystèmes.
Choisir sa quantification (Q4, Q5, Q8, FP16): Pour arbitrer taille de modèle, VRAM et qualité avant de télécharger un GGUF.
llama-server : une API OpenAI locale avec llama.cpp: L'alternative la plus proche, issue du même socle llama.cpp, si vous privilégiez l'API.

Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.

Suite logique

Installation · 12 min

KoboldCpp : installation et prise en main (GGUF, ROCm, API)