KoboldCpp : guide complet du runtime local LLM mono-binaire

KoboldCpp est un fichier unique LLM local un runtime construit par-dessus llama.cpp. Téléchargez un seul binaire, pointez-le vers un modèle GGUF, et vous obtenez immédiatement une interface de discussion dans le navigateur ainsi qu’une API REST compatible OpenAI — sans gestionnaire de paquets, sans démon à configurer, sans étape d’installation requise. Il fonctionne sous Windows, macOS et Linux, avec accélération GPU optionnelle via CUDA, Metal, Vulkan ou OpenCL.

Téléchargement de KoboldCpp

Les versions sont publiées sur la page des versions GitHub de KoboldCppChaque version fournit des binaires spécifiques à chaque plateforme ; choisissez celui qui correspond à votre matériel.

Windows

Télécharger koboldcpp.exe pour une prise en charge GPU NVIDIA (les bibliothèques CUDA sont intégrées — aucune installation séparée du kit CUDA n’est nécessaire, seul le pilote graphique NVIDIA standard est requis). Si vous ne possédez pas de GPU NVIDIA, téléchargez plutôt koboldcpp_nocuda.exe Un double-clic sur le fichier .exe ouvre un lanceur graphique vous permettant de parcourir vos fichiers de modèle et de configurer les paramètres avant de démarrer le serveur. Pour ignorer ce lanceur et démarrer directement depuis la ligne de commande, passez l’indicateur --skiplauncher .

macOS

Téléchargez le binaire macOS depuis la page des versions (généralement nommé koboldcpp_mac ou distribué sous forme de fichier .dmg). L’accélération GPU Metal est incluse automatiquement — aucun indicateur supplémentaire n’est requis ; KoboldCpp détecte automatiquement les puces Apple Silicon et utilise Metal par défaut. Au premier lancement, macOS peut afficher un avertissement indiquant que le binaire provient d’un développeur non identifié ; faites un clic droit → Ouvrir pour contourner Gatekeeper.

Linux

Téléchargez le binaire Linux et rendez-le exécutable :

chmod +x koboldcpp
./koboldcpp --model /chemin/vers/le_modele.gguf

Les binaires Linux précompilés intègrent la prise en charge CPU et Vulkan. Pour la prise en charge CUDA sur les cartes NVIDIA, recherchez un élément de version comportant le suffixe cu dans son nom de fichier, ou compilez depuis les sources avec la commande make LLAMA_CUDA=1Si votre pilote est trop ancien pour la version CUDA intégrée, la version Vulkan constitue une solution de repli fiable.

Obtention d’un modèle GGUF

KoboldCpp charge directement les fichiers GGUF — le même format utilisé par llama.cpp et Ollama. La source principale est Hugging Face ; recherchez le nom d’un modèle suivi de « GGUF ». Avant de télécharger, utilisez le Calculateur de VRAM pour vérifier que le modèle tiendra dans la mémoire vidéo (VRAM) de votre GPU, compte tenu de la taille de contexte choisie. Niveaux de quantification à connaître :

Lancement de KoboldCpp

La commande minimale sur toute plateforme :

./koboldcpp --model /chemin/vers/le_modele.gguf

Cela démarre le serveur sur http://localhost:5001Ouvrez cette URL dans votre navigateur pour accéder à l’interface web.

Windows — Lanceur graphique

Double-cliquez sur koboldcpp.exeLe fenêtre du lanceur vous permet de sélectionner un fichier de modèle, de définir le nombre de couches GPU, la taille du contexte et le backend, sans passer par la ligne de commande. Cliquez sur Lancer lorsque vous avez terminé ; une fenêtre de terminal s’ouvre, affichant les journaux du serveur, et l’interface web s’ouvre automatiquement dans le navigateur.

Ligne de commande (toutes les plateformes)

Une commande typique de lancement avec dédicace GPU, taille de contexte personnalisée et port explicite :

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

Référence des indicateurs principaux :

Interface web et API compatible OpenAI

Une fois lancé, KoboldCpp expose deux interfaces sur le même port :

• Interface web — http://localhost:5001Une interface complète de génération de texte, avec modes récit, discussion et instruction. Prend en charge les modèles d’invite, la mémoire, les notes de l’auteur et les champs d’informations mondiales hérités du projet KoboldAI.
• API KoboldAI — http://localhost:5001/api/v1Utilisée par des interfaces clientes telles que SillyTavern et Agnaistic.
• API compatible OpenAI — http://localhost:5001/v1Implémente /v1/chat/completions et /v1/completions. Tout client acceptant une URL de base personnalisée fonctionne, y compris LangChain, le SDK Python OpenAI et la plupart des applications de discussion open source.

Pour configurer le SDK Python OpenAI afin qu’il pointe vers KoboldCpp :

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # KoboldCpp n’exige pas de clé API par défaut
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Bonjour"}]
)

Dédicace GPU : choix de la bonne valeur pour l’option --gpulayers

Chaque couche transformer déchargée sur le GPU déplace le traitement hors du CPU et augmente considérablement le nombre de jetons par seconde. Le compromis est la consommation de VRAM. Le nombre total de couches d’un modèle est fixé par son architecture — des valeurs courantes sont 32 pour les modèles 7B/8B, 40 pour les modèles 13B et 80 pour les modèles 70B. Chaque couche consomme approximativement une part égale de la mémoire GPU totale requise par le modèle.

Approche pratique :

1. Utilisez le Calculateur de VRAM pour estimer combien de couches peuvent être chargées avec votre taille de contexte cible.
2. Commencez par --gpulayers 999 pour tenter un déchargement complet. KoboldCpp limite automatiquement cette valeur au nombre réel de couches du modèle.
3. Si vous obtenez une erreur de mémoire insuffisante au démarrage, diminuez cette valeur et réessayez. Le journal du serveur affiche l’allocation mémoire par couche pour vous aider à calibrer.

Le déchargement partiel est pris en charge et utile — même le déchargement de la moitié des couches d’un modèle volumineux procure une amélioration notable de la vitesse par rapport à une inférence purement CPU. Si vous ne savez pas quel GPU associer à un modèle donné, consultez la meilleur Cartes graphiques pour LLM locaux guide et le répartition des besoins en VRAM selon le modèle.

Taille du contexte et paramètres de performances

Taille du contexte (--contextsize) est le facteur le plus déterminant de la consommation de VRAM, après les poids du modèle. Un modèle 7B en quantification Q4_K_M utilise environ 4 Go pour ses poids ; étendre le contexte de 4096 à 32768 jetons peut ajouter plusieurs gigaoctets supplémentaires au cache KV. Activez --flashattention pour réduire l’empreinte mémoire du cache KV — cette option est particulièrement efficace pour les contextes très longs et n’a aucun impact sur la qualité des sorties.

Autres paramètres influençant la vitesse :

• --threadsEn inférence CPU uniquement, définissez cette valeur proche du nombre de cœurs physiques de votre processeur, et non du nombre de cœurs logiques (avec hyperthreading).
• --batchsizeDes valeurs plus élevées (par exemple 512) améliorent la vitesse de traitement des invites, au prix d’une consommation maximale accrue de VRAM pendant la phase de pré-remplissage.
• --smartcontextLorsque le contexte est saturé, KoboldCpp décale les jetons les plus anciens plutôt que d’interrompre la génération — utile pour les sessions interactives longues.

KoboldCpp contre Ollama contre llama.cpp

Les trois reposent sur le même moteur llama.cpp et prennent en charge les modèles GGUF. Les différences résident dans le flux de travail et l’interface.

Choisissez KoboldCpp si vous souhaitez une configuration sans installation, une interface intégrée pour les histoires ou les discussions, ou une compatibilité avec les interfaces clientes KoboldAI telles que SillyTavern.
Choisissez Ollama si vous souhaitez une bibliothèque de modèles gérée, un systemd service ou une intégration plus étroite avec la CLI — consultez le Guide complet d’Ollama pour un guide complet.
Choisissez directement llama.cpp si vous développez une intégration personnalisée ou si vous avez besoin des fonctionnalités les plus récentes issues du dépôt principal, avant qu’elles ne soient disponibles dans les enveloppes logicielles dérivées.

Si vous hésitez encore entre l’auto-hébergement et l’appel d’une API hébergée, le calculateur d’auto-hébergement vs seuil de rentabilité d’API peut vous aider à déterminer le point d’inversion des coûts.

Questions fréquemment posées

KoboldCpp nécessite-t-il l’installation séparée des pilotes CUDA ?

Sous Windows, koboldcpp.exe intègre les bibliothèques runtime CUDA ; vous n’avez donc besoin que du pilote graphique NVIDIA standard — aucune installation séparée du kit CUDA n’est requise. Sous Linux, les versions compilées avec CUDA s’associent généralement à la version runtime CUDA installée localement, ce qui rend la compatibilité entre la version du pilote et celle de CUDA essentielle ; si votre pilote est trop ancien, la version Vulkan constitue la solution de repli la plus simple.

Que signifie l’option « --gpulayers 0 » ?

Zéro couche GPU signifie que tous les calculs s’effectuent sur le processeur (CPU). Il s’agit du comportement par défaut lorsque aucun indicateur GPU n’est spécifié. L’inférence CPU est nettement plus lente — typiquement de 2 à 10 jetons/seconde sur un processeur moderne, contre 40 à plus de 100 jetons/seconde sur un GPU milieu de gamme — mais fonctionne sur n’importe quelle machine, indépendamment de la présence ou non d’un GPU.

Puis-je utiliser KoboldCpp comme remplacement direct de l’API OpenAI dans mon application ?

Oui. Configurez l’URL de base de votre client OpenAI à base_url sur http://localhost:5001/v1 et utilisez n’importe quelle chaîne non vide comme valeur de api_key (celle-ci n’est pas validée par défaut). Le champ modèle est accepté mais ignoré — le modèle GGUF chargé est systématiquement utilisé, quel qu’il soit. Les complétions conversationnelles (chat completions) et les complétions textuelles (text completions) sont prises en charge ; les endpoints d’incorporation (embeddings) et d’images ne le sont pas.

Comment exécuter simultanément deux modèles différents ?

Chaque processus KoboldCpp gère un seul modèle. Lancez une seconde instance avec une valeur différente de --port (par exemple, 5002) pointant vers un autre fichier GGUF. Aucun équilibreur de charge intégré n’est fourni ; la répartition entre les instances doit être gérée au niveau applicatif.

Pourquoi la génération est-elle plus lente que prévu, même avec un GPU ?

La cause la plus fréquente est un déchargement partiel vers le CPU : si la valeur de l’option --gpulayers est inférieure au nombre total de couches du modèle, les couches restantes s’exécutent sur le CPU et créent un goulot d’étranglement. Vérifiez le journal de démarrage — KoboldCpp indique précisément combien de couches ont été affectées au GPU et combien au CPU. Assurez-vous également que le backend correct (CUDA/Metal/Vulkan) apparaît dans la sortie de démarrage, et non un repli vers le CPU.

Est-il sécurisé d’exposer KoboldCpp sur un réseau ?

Par défaut, KoboldCpp écoute uniquement sur 127.0.0.1 (localhost). Pour l’exposer sur un réseau local (LAN), ajoutez l’option --host 0.0.0.0. Aucune authentification intégrée n’est fournie ; il n’est donc pas recommandé d’exposer KoboldCpp sur des réseaux non fiables ou sur Internet public, sauf si un proxy inverse doté d’un mécanisme d’authentification est placé devant lui.