Prérequis

Un GPU est recommandé, idéalement NVIDIA avec le plus de VRAM possible. Contrairement à Ollama ou vLLM, llama.cpp permet cependant de répartir le modèle entre GPU et CPU si la VRAM est insuffisante, au prix d’une baisse de performances. Voir ce lien pour partager un GPU dans un LXC
Les modèles peuvent fonctionner sur CPU uniquement, mais avec des performances très faibles (souvent inutilisables en pratique pour un usage interactif).
VRAM recommandée : dépend du niveau d’offload GPU. Pour un usage optimal, prévoir environ la taille du modèle (en Q4) + 1 à 3 Go pour le KV cache. Il est toutefois possible de réduire la VRAM nécessaire en déportant une partie du modèle en RAM.
RAM recommandée : au minimum équivalente à la taille du modèle, idéalement 1,5 à 2 fois, notamment si une partie du modèle est exécutée sur CPU.
Espace disque à prévoir en fonction du ou des modèle que vous allez utiliser ou tester, Exemples :
- qwen2.5:7b (Q4) ≈ 4–5 Go
- qwen2.5:14b (Q4) ≈ 8–10 Go
- llama3:70b (Q4) ≈ 35–40 Go
Utiliser un SSD/NVMe améliore fortement les temps de chargement.
CPU / vCPU recommandés :
- Avec GPU : 4 à 8 vCPU recommandés (gestion du KV cache et offload partiel CPU)
- Sans GPU : prévoir au minimum 8 à 16 vCPU, les performances restant très limitées.
Note : Q4 correspond au niveau de "quantization", c’est-à-dire une réduction de la précision numérique du modèle afin de diminuer son utilisation en mémoire (VRAM). Les niveaux vont généralement de Q1 à Q8 : Q8 est le plus précis (proche du modèle original), mais aussi le plus gourmand en ressources. À l’inverse, Q1 est très léger mais fortement dégradé. En pratique, Q4 (voire Q5) est généralement considéré comme le meilleur compromis entre performances, consommation de VRAM et qualité de réponse.

Installation

Prérequis système

Installer les dépendances nécessaires :

# apt update && apt upgrade
# apt install -y git build-essential cmake curl libcurl4-openssl-dev

Support GPU NVIDIA (CUDA)

(Optionnel) Vérifier derniere version :

# curl https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/ | grep keyring

Installer le dépôt CUDA NVIDIA :

# apt install -y wget
# cd /opt
# wget https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/cuda-keyring_1.1-1_all.deb
# dpkg -i cuda-keyring_1.1-1_all.deb
# apt update

Installer le toolkit CUDA :

# apt install -y cuda-toolkit

Récupération du projet

# cd /opt
# git clone https://github.com/ggerganov/llama.cpp.git
# cd llama.cpp

Compilation (avec support CUDA)

Connaitre les versions de nvcc installées :

# find /usr /opt -name nvcc 2>/dev/null

Compilation :

# export CUDACXX=/usr/local/cuda-13.2/bin/nvcc
# cmake -B build -DGGML_CUDA=ON
# cmake --build build -j$(nproc)

Les binaires seront disponibles dans :

/opt/llama.cpp/build/bin/

Téléchargement d’un modèle (format GGUF)

Plateformes de modèles :

Hugging Face Plateforme principale.

Quantization custom (souvent mieux optimisé) :

Créer un dossier pour les modèles :

# mkdir -p /opt/llama.cpp/models

On configure le dossier des modèles :

# echo 'export LLAMA_CACHE=/opt/llama.cpp/models' >> ~/.bashrc
# source ~/.bashrc

Exemple de chargement automatique d’un modèle depuis Hugging Face :

Exemple avec Qwen/Qwen3-8B-GGUF:Q4_K_M :

# /opt/llama.cpp/build/bin/llama-cli -hf Qwen/Qwen3-8B-GGUF:Q4_K_M -n 0

Exemple avec bartowski/Jackrong_Qwen3.5-9B-Neo-GGUF:Q4_K_M :

# /opt/llama.cpp/build/bin/llama-cli -hf bartowski/Jackrong_Qwen3.5-9B-Neo-GGUF:Q4_K_M -n 0

Exemple avec HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive:Q4_K_M :

# /opt/llama.cpp/build/bin/llama-cli -hf HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive:Q4_K_M -n 0

Une fois le modèle téléchargé, faire "/exit" pour quitter le CLI. Le paramètre "-n 0" empêche toute génération de texte : il ne doit être utilisé que pour le téléchargement ou les tests.

Test rapide

Trouver le fichier .gguf :

# find /opt/llama.cpp/models -iname "*.gguf"

Exemple avec Qwen3.5-9B-Uncensored-HauhauCS-Aggressive :

# /opt/llama.cpp/build/bin/llama-cli \
  -m /opt/llama.cpp/models/models--HauhauCS--Qwen3.5-9B-Uncensored-HauhauCS-Aggressive/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf \
  -ngl 35 \
  -c 2048 \
  -p "Explique moi ce qu'est llama.cpp"

Le dossier `snapshots/<hash>` dépend du téléchargement Hugging Face et varie selon les versions. Il est recommandé de créer un lien symbolique vers le fichier `.gguf` pour simplifier son utilisation.

Explication :

-ngl : nombre de couches envoyées au GPU
-c   : taille du contexte

Mode serveur (API compatible OpenAI)

# /opt/llama.cpp/build/bin/llama-server \
  -m /opt/llama.cpp/models/models--HauhauCS--Qwen3.5-9B-Uncensored-HauhauCS-Aggressive/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf \
  -c 2048 \
  -ngl 35 \
  --host 0.0.0.0 \
  --port 8080

0.0.0.0 pour autoriser toutes les interfaces réseau.

Le dossier `snapshots/<hash>` dépend du téléchargement Hugging Face et varie selon les versions. Il est recommandé de créer un lien symbolique vers le fichier `.gguf` pour simplifier son utilisation.

Le serveur est accessible via :

http://IP:8080

Test API

# curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [
      {"role": "user", "content": "Bonjour"}
    ]
  }'

API key

Pour activer une authentification par clé API, ajouter le paramètre --api-key ou --api-key-file :

--api-key masuperclef

ou :

--api-key-file /dossier/clef.txt

Le fichier contenant la clé API doit être stocké dans un emplacement non accessible aux autres utilisateurs, par exemple dans /root/ si le service tourne en root.

Exemple :

# chmod 600 /root/llama-api-key.txt

SSL

Pour que la clé API ne transite pas en clair sur le réseau, il convient d'utiliser HTTPS.

Certains services, comme Hermes, refusent les certificats auto-signés. Il faut alors utiliser soit un certificat émis par une autorité reconnue, soit une CA privée dont le certificat public a été installé sur les machines clientes.

Pour une utilisation avec Hermes, voir Utiliser une CA privée avec Hermes.

Avec certificat auto-signé (déconseillé)

Créer un dossier de configuration :

# mkdir -p /etc/llama-server
# chmod 700 /etc/llama-server

Installer les outils nécessaires :

# apt update && apt upgrade
# apt install openssl curl

Créer le fichier contenant l’API key si nécessaire :

# vi /etc/llama-server/api-keys.txt

masuperclef

# chmod 600 /etc/llama-server/api-keys.txt

Générer les fichiers SSL nécessaires :

# openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout /etc/llama-server/server.key \
  -out /etc/llama-server/server.crt \
  -subj "/CN=IP_SERVEUR" \
  -addext "subjectAltName = IP:IP_SERVEUR"

Sécuriser les fichiers :

# chmod 600 /etc/llama-server/server.key
# chmod 644 /etc/llama-server/server.crt

Ajouter à la configuration de llama.cpp :

...
 --port 8080 \
 --api-key-file /etc/llama-server/api-keys.txt \
 --ssl-key-file /etc/llama-server/server.key \
 --ssl-cert-file /etc/llama-server/server.crt
...

Optimisation (KV cache, performances, latence)

Le paramètre de contexte (`-c`) influence directement la quantité de mémoire utilisée par le KV cache. Plus il est élevé, plus la consommation de VRAM augmente, ainsi que la latence de traitement du prompt.
En pratique, une valeur de `2048` constitue souvent un bon compromis sur un GPU de 12 Go. Augmenter à `4096` peut améliorer la mémoire conversationnelle, mais au prix d’une consommation de VRAM plus importante.
Le paramètre `-ngl` détermine le nombre de couches envoyées au GPU.
- Plus la valeur est élevée, plus les performances augmentent.
- Si la VRAM est insuffisante, réduire cette valeur permet de déporter une partie du modèle sur CPU.
- Il est possible d’utiliser `-ngl 999` afin de laisser llama.cpp charger automatiquement le maximum de couches possible sur le GPU.
Le paramètre `-fa` active Flash Attention.
- Cette option améliore généralement les performances de traitement du prompt et réduit légèrement la latence.
- Elle est recommandée sur GPU NVIDIA récents.
Le paramètre `-b` (batch size) influence la vitesse de traitement du prompt.
- Une valeur plus élevée peut améliorer les performances, mais augmente également la consommation de mémoire.
- En cas de manque de VRAM, réduire cette valeur peut stabiliser le serveur.
Le paramètre `-ub` (micro-batch size) permet d’ajuster plus finement l’utilisation mémoire.
- Une valeur plus faible réduit les pics de consommation mémoire.
- Une valeur plus élevée peut améliorer légèrement les performances si la VRAM le permet.
Le paramètre `-np` (n_parallel) détermine le nombre de requêtes pouvant être traitées en parallèle.
- Une valeur élevée augmente la consommation de VRAM.
- Pour un usage personnel ou mono-utilisateur, `-np 1` est généralement recommandé.
- Des valeurs supérieures sont surtout utiles pour une API ou un usage multi-utilisateurs.

Exemple de configuration optimisée pour un GPU de 12 Go :

# /opt/llama.cpp/build/bin/llama-server \
  -m /opt/llama.cpp/models/models--HauhauCS--Qwen3.5-9B-Uncensored-HauhauCS-Aggressive/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf \
  -c 2048 \
  -ngl 999 \
  -fa on \
  -b 1024 \
  -ub 512 \
  -np 1 \
  --host 0.0.0.0 \
  --port 8080

Explication :

-c    : taille du contexte
-ngl  : nombre de couches envoyées au GPU
-fa   : active Flash Attention
-b    : taille du batch de traitement
-ub   : taille du micro-batch
-np   : nombre de requêtes traitées en parallèle

Si le serveur démarre correctement et qu’il reste de la marge en VRAM, il est possible d’augmenter progressivement `-b` ou le contexte.
En cas d’erreur mémoire ou de performances instables :
- réduire `-b`
- réduire `-ngl`
- réduire `-c`

Méthode d’ajustement recommandée

Commencer avec :
- `-c 2048`
- `-ngl 999`
- `-fa on`
- `-b 512`
- `-ub 256`
- `-np 1`
Vérifier ensuite l’utilisation mémoire :

# nvidia-smi

Si la VRAM est presque saturée :
- réduire `-b`
- puis `-ub`
- puis réduire `-ngl` si nécessaire
Si au contraire une marge importante reste disponible :
- essayer `-b 1024`
- ou augmenter légèrement le contexte

Remarques

Contrairement à Ollama, llama.cpp ne décharge pas automatiquement le modèle après inactivité lorsque le serveur reste lancé.
Le meilleur réglage dépend du modèle utilisé, du niveau de quantization, du contexte choisi et de la quantité de VRAM disponible.
Sur un petit GPU, il est généralement préférable de privilégier un contexte raisonnable et un nombre limité de requêtes parallèles.

Service systemd

Création d'un service pour automatiser le lancement du serveur llama.cpp, tout d'abord créer un lien propre vers le modèle si nécessaire :

# ln -s /opt/llama.cpp/models/models--HauhauCS--Qwen3.5-9B-Uncensored-HauhauCS-Aggressive/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf /opt/llama.cpp/models/qwen35-9b-uncensored-q4km.gguf

Créer le service :

# vi /etc/systemd/system/llama-server.service

[Unit]
Description=llama.cpp server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/llama.cpp
ExecStart=/opt/llama.cpp/build/bin/llama-server -m /opt/llama.cpp/models/qwen35-9b-uncensored-q4km.gguf -c 2048 -ngl 999 -fa on -b 1024 -ub 512 -np 1 --host 0.0.0.0 --port 8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

# systemctl daemon-reload
# systemctl enable llama-server
# systemctl start llama-server

Proxy OpenClaw

Source

Il est possible d'utiliser un proxy Python afin de contourner certaines incompatibilités (rôles, outils, gestion du « thinking ») entre OpenClaw et llama.cpp.

Cependant, pour un usage stable, il est recommandé d’utiliser un backend nativement compatible tel que Ollama (usage personnel) ou vLLM (usage avancé / multi-utilisateurs).

Exemple de configuration d’un modèle MoE avec déchargement des experts en RAM

Machine de test :

LXC Debian 13
8 vCPU (E5-2667 v2)
RTX 3060 12GB (PCIe 3.0 x8)
DDR3-1866
- À noter que la mémoire des experts déchargés en RAM est consommée sur l’hôte, et non comptabilisée dans le LXC, car elle transite via le pilote Nvidia.
- Dans une VM ou sur une machine physique, prévoir au minimum la taille du modèle en RAM, avec idéalement 30 à 50 % de marge supplémentaire selon le contexte, le KV cache et les buffers.

Qwen3.6-35B-A3B-GGUF:UD-Q5_K_XL

# /opt/llama.cpp/build/bin/llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q5_K_XL
# ln -s /opt/llama.cpp/models/models--unsloth--Qwen3.6-35B-A3B-GGUF/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.6-35B-A3B-UD-Q5_K_XL.gguf /opt/llama.cpp/models/Qwen3.6-35B-A3B-UD-Q5_K_XL.gguf
# ln -s /opt/llama.cpp/models/models--unsloth--Qwen3.6-35B-A3B-GGUF/snapshots/1234567890abcdef1234567890abcdef12345678/mmproj-BF16.gguf /opt/llama.cpp/models/mmproj-F16.gguf

ExecStart=/opt/llama.cpp/build/bin/llama-server \
  -m /opt/llama.cpp/models/Qwen3.6-35B-A3B-UD-Q5_K_XL.gguf \
  --mmproj /opt/llama.cpp/models/mmproj-F16.gguf \
  -ngl 999 \
  -t 8 \
  -tb 16 \
  -b 4096 \
  -ub 4096 \
  -c 131072 \
  --cache-ram 2048 \
  -np 1 \
  --kv-unified \
  -fa on \
  --no-mmproj-offload \
  --no-mmap \
  -ncmoe 35 \
  -ctk q8_0 \
  -ctv q8_0 \
  --reasoning on \
  --jinja \
  --chat-template-kwargs '{"preserve_thinking": true}' \
  --reasoning-budget 8096 \
  --reasoning-budget-message "D'accord, assez réfléchi, plus d'attente. Passons à l'action." \
  --temp 0.6 \
  --top-k 20 \
  --top-p 0.95 \
  --min-p 0.0 \
  --presence-penalty 0.0 \
  --repeat-penalty 1.0 \
  --swa-full \
  --cache-reuse 512 \
  --host 192.168.1.123 \
  --port 8080

--mmproj : Charge le fichier projecteur multimodal. Il est utilisé pour les modèles capables de traiter des images ou d’autres entrées multimodales.

-ngl : Nombre de couches à offloader sur le GPU. Une valeur très élevée comme 999 revient en pratique à dire « mets sur le GPU tout ce qui peut y être placé ».

-t : Nombre de threads CPU utilisés pour l’inférence principale.

-tb : Nombre de threads CPU utilisés pour le traitement par batch. Cela peut améliorer le débit de préremplissage du contexte.

-b : Taille du batch logique. Plus elle est élevée, plus le traitement du prompt peut être rapide, mais cela augmente aussi les besoins en mémoire.

-ub : Taille du micro-batch. C’est une sous-division du batch principal, utile pour ajuster plus finement l’équilibre entre débit et mémoire.

-c : Taille du contexte actif utilisée par le serveur. Elle détermine combien de tokens peuvent être conservés en mémoire dans la fenêtre de contexte.

--cache-ram : Taille maximale du cache en RAM, exprimée en MiB. Ce cache permet de conserver des états utiles pour éviter de tout recalculer inutilement.

-np : Nombre de slots serveur. Avec 1, une seule requête est traitée activement à la fois.

--kv-unified : Utilise un buffer KV unifié partagé entre les séquences. Cela peut améliorer la gestion du cache dans certains scénarios serveur.

-fa : Active Flash Attention, ce qui améliore généralement les performances mémoire et la vitesse sur GPU compatibles.

--no-mmproj-offload : Empêche l’offload du projecteur multimodal sur le GPU. Le mmproj reste alors côté CPU/RAM.

--no-mmap : Désactive le memory mapping du fichier modèle. Le modèle est alors chargé plus directement en mémoire, ce qui peut parfois être préférable selon le stockage ou le comportement recherché.

-ncmoe : Définit combien d’experts MoE sont forcés côté CPU/RAM. C’est un réglage particulièrement utile pour les modèles Mixture-of-Experts sur des GPU limités en VRAM.

-ctk : Type de quantification du cache KV pour les clés. Ici q8_0 privilégie une bonne qualité tout en réduisant la pression mémoire.

-ctv : Type de quantification du cache KV pour les valeurs. Même logique que pour -ctk.

--reasoning : Active le mode de raisonnement pris en charge par le serveur pour les modèles/templates compatibles.

--jinja : Active l’utilisation des chat templates Jinja, afin de formater correctement les messages pour les modèles qui en ont besoin.

--chat-template-kwargs : Passe des paramètres supplémentaires au template de chat. Ici, {"preserve_thinking": true} demande au template de préserver la partie de raisonnement lorsqu’elle est supportée.

--reasoning-budget : Définit le budget maximal de tokens alloués au raisonnement interne.

--reasoning-budget-message : Message injecté lorsque le budget de raisonnement est atteint, afin d’inciter le modèle à conclure et passer à la réponse utile.

--temp : Température d’échantillonnage. Plus elle est basse, plus la réponse est déterministe.

--top-k : Limite l’échantillonnage aux K tokens les plus probables.

--top-p : Active un échantillonnage nucleus en conservant uniquement la masse de probabilité cumulée visée.

--min-p : Écarte les tokens dont la probabilité est trop faible.

--presence-penalty : Pénalité de présence. Elle pousse le modèle à introduire de nouveaux tokens ou idées plutôt que de répéter ce qui a déjà été dit.

--repeat-penalty : Pénalité de répétition. Elle réduit la probabilité de répéter les mêmes tokens.

--swa-full : Active le mode SWA complet lorsqu’il est pris en charge par le modèle ou le backend.

--cache-reuse : Définit un seuil de réutilisation du cache. Cela peut améliorer les performances sur des requêtes proches ou répétées.

Test :

# journalctl -u llama-server -n 200 --no-pager | grep -E "offloaded|model buffer|KV buffer|compute buffer|n_ctx|n_batch|n_ubatch"

print_info: n_ctx_train           = 262144
print_info: n_ctx_orig_yarn       = 262144
load_tensors: offloaded 41/41 layers to GPU
load_tensors:        CUDA0 model buffer size =  4972.80 MiB
load_tensors:    CUDA_Host model buffer size = 20377.31 MiB
llama_context: n_ctx         = 131072
llama_context: n_ctx_seq     = 131072
llama_context: n_batch       = 4096
llama_context: n_ubatch      = 4096
llama_context: n_ctx_seq (131072) < n_ctx_train (262144) -- the full capacity of the model will not be utilized
llama_kv_cache:      CUDA0 KV buffer size =  1360.00 MiB
sched_reserve:      CUDA0 compute buffer size =  3976.02 MiB
sched_reserve:  CUDA_Host compute buffer size =  2112.42 MiB
alloc_compute_meta:        CPU compute buffer size =   248.10 MiB
slot   load_model: id  0 | task -1 | new slot, n_ctx = 131072

Explique pourquoi un système peut sembler rapide en usage normal, mais devenir frustrant dans un workflow réel.
Je veux une réponse qui distingue clairement :

vitesse brute ;
latence initiale ;
fluidité perçue ;
fiabilité ;
confort à long terme.

Termine par une conclusion pratique en 5 lignes maximum.

Vitesse :

prompt eval time =    5194.60 ms /  2896 tokens (    1.79 ms per token,   557.50 tokens per second)
eval time =   16383.19 ms /   284 tokens (   57.69 ms per token,    17.33 tokens per second)
total time =   21577.79 ms /  3180 tokens

Qwen3.6-35B-A3B-APEX-I-Balanced

# /opt/llama.cpp/build/bin/llama-cli --hf-repo mudler/Qwen3.6-35B-A3B-APEX-GGUF --hf-file Qwen3.6-35B-A3B-APEX-I-Balanced.gguf
# ln -s /opt/llama.cpp/models/models--mudler--Qwen3.6-35B-A3B-APEX-GGUF/snapshots/1234567890abcdef1234567890abcdef12345678/Qwen3.6-35B-A3B-APEX-I-Balanced.gguf /opt/llama.cpp/models/Qwen3.6-35B-A3B-APEX-I-Balanced.gguf
# ln -s /opt/llama.cpp/models/models--mudler--Qwen3.6-35B-A3B-APEX-GGUF/snapshots/1234567890abcdef1234567890abcdef12345678/mmproj.gguf /opt/llama.cpp/models/mmproj-F16.gguf

ExecStart=/opt/llama.cpp/build/bin/llama-server \
  -m /opt/llama.cpp/models/Qwen3.6-35B-A3B-APEX-I-Balanced.gguf \
  --mmproj /opt/llama.cpp/models/mmproj-F16.gguf \
  -ngl 999 \
  -t 8 \
  -tb 16 \
  -b 4096 \
  -ub 4096 \
  -c 131072 \
  --cache-ram 2048 \
  -np 1 \
  --kv-unified \
  -fa on \
  --no-mmproj-offload \
  --no-mmap \
  -ncmoe 35 \
  -ctk q8_0 \
  -ctv q8_0 \
  --reasoning on \
  --jinja \
  --chat-template-kwargs '{"preserve_thinking": true}' \
  --reasoning-budget 8096 \
  --reasoning-budget-message "D'accord, assez réfléchi, plus d'attente. Passons à l'action." \
  --temp 0.6 \
  --top-k 20 \
  --top-p 0.95 \
  --min-p 0.0 \
  --presence-penalty 0.0 \
  --repeat-penalty 1.0 \
  --swa-full \
  --cache-reuse 512 \
  --host 192.168.1.123 \
  --port 8080