Introduction à llama.cpp avec CLI et Serveur

Je reviens sans cesse à llama.cpp pour l’inférence locale : il vous offre un contrôle que Ollama et d’autres solutions abstraissent, et il fonctionne simplement. Il est facile d’exécuter des modèles GGUF de manière interactive avec llama-cli ou d’exposer une API HTTP compatible OpenAI avec llama-server.

Si vous hésitez encore entre les approches locales, auto-hébergées et cloud, commencez par le guide principal : LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Pourquoi llama.cpp en 2026

llama.cpp est un moteur d’inférence léger avec un parti pris en faveur de :

• la portabilité sur les CPU et plusieurs backends GPU,
• une latence prévisible sur une machine unique,
• une flexibilité de déploiement, des laptops aux nodes sur site (on-prem).

Il brille lorsque vous souhaitez privacité et fonctionnement hors ligne, lorsque vous avez besoin d’un contrôle déterministe sur les drapeaux de runtime, ou lorsque vous voulez intégrer l’inférence dans un système plus large sans exécuter une stack lourde en Python.

Il est également utile de comprendre llama.cpp même si vous choisissez plus tard un runtime serveur à plus haut débit. Par exemple, si votre objectif est le débit maximal de service sur GPU, vous pourriez également vouloir le comparer à vLLM en utilisant : vLLM Quickstart: High-Performance LLM Serving et vous pouvez comparer les choix d’outils dans : Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Installer llama.cpp sur Windows, macOS et Linux

Il existe trois méthodes d’installation pratiques, selon que vous recherchiez la commodité, la portabilité ou les performances maximales.

Installation via les gestionnaires de paquets

C’est l’option la plus rapide pour « mettre en route ».

# macOS ou Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS ou Linux (Nix)
nix profile install nixpkgs#llama-cpp

Astuce : après l’installation, vérifiez que les outils existent :

llama-cli --version
llama-server --version

Installation via les binaires pré-compilés

Si vous souhaitez une installation propre sans compilateurs, utilisez les binaires pré-compilés officiels publiés dans les releases GitHub de llama.cpp. Ils couvrent généralement plusieurs cibles OS et plusieurs backends (variantes CPU-only et GPU-enabled).

Un workflow courant :

# 1) Télécharger l'archive appropriée pour votre OS et backend
# 2) L'extraire
# 3) Exécuter depuis le dossier extrait

./llama-cli --help
./llama-server --help

Compiler depuis le source pour votre matériel exact

Si vous tenez à extraire les meilleures performances de votre backend CPU/GPU, compilez depuis le source avec CMake.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Build CPU
cmake -B build
cmake --build build --config Release

Après la compilation, les binaires se trouvent généralement ici :

ls -la ./build/bin/

Builds GPU en une seule commande

Activez le backend qui correspond à votre matériel (exemples montrés pour CUDA et Vulkan) :

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + GPU NVIDIA : guide de construction complet

Sur Ubuntu 24.04 avec une GPU NVIDIA, vous avez besoin du toolkit CUDA et d’OpenSSL avant de construire. Voici une séquence testée :

1. Installer le toolkit CUDA 13.1

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Ajouter CUDA à votre environnement (ajoutez à ~/.bashrc) :

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Ensuite, exécutez source ~/.bashrc ou ouvrez un nouveau terminal.

3. Installer les en-têtes de développement OpenSSL (requis pour une construction propre) :

sudo apt update
sudo apt install libssl-dev

4. Construire llama.cpp (dossier contenant votre clone de llama.cpp, avec CUDA activé) :

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Cela produit llama-cli, llama-mtmd-cli, llama-server, llama-embedding et llama-gguf-split dans le dossier llama.cpp.

Vous pouvez également compiler plusieurs backends et choisir les appareils au runtime. C’est utile si vous déployez la même build sur des machines hétérogènes.

Choisir un modèle GGUF et une quantification

Pour exécuter l’inférence, vous avez besoin d’un fichier de modèle GGUF (*.gguf). GGUF est un format monofichier qui regroupe les poids du modèle ainsi que les métadonnées standardisées nécessaires aux moteurs comme llama.cpp.

Deux façons d’obtenir un modèle

Option A : Utiliser un fichier GGUF local

Téléchargez ou copiez un GGUF dans ./models/ :

mkdir -p models
# Placez votre GGUF à models/my-model.gguf

Ensuite, exécutez-le par chemin :

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -n 128

Option B : Laisser llama.cpp télécharger depuis Hugging Face

Les builds modernes de llama.cpp peuvent télécharger depuis Hugging Face et conserver les fichiers dans un cache local. C’est souvent le workflow le plus simple pour des expériences rapides.

# Télécharger un modèle de HF et exécuter un prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200

Vous pouvez également spécifier la quantification dans le sélecteur de repo et laisser l’outil sélectionner un fichier correspondant :

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Summarize the concept of quantization in one paragraph." \
  -n 160

Si vous avez besoin d’un workflow entièrement hors ligne plus tard, --offline force l’utilisation du cache et empêche l’accès au réseau.

Choix de quantification pour l’inférence locale

La quantification est la réponse pratique à la question « Quelle quantification GGUF choisir pour l’inférence locale » car elle échange directement qualité, taille du modèle et vitesse.

Un point de départ pragmatique :

• commencez par une variante Q4 ou Q5 pour les machines orientées CPU,
• passez à une précision plus élevée (ou une quantification moins agressive) lorsque vous pouvez vous permettre la RAM ou la VRAM,
• lorsque le modèle « semble stupide » pour votre tâche, la solution est souvent soit un meilleur modèle, soit une quantification moins agressive, et non seulement des ajustements d’échantillonnage.

N’oubliez pas également que la fenêtre de contexte compte : des tailles de contexte plus importantes augmentent l’utilisation de la mémoire (parfois de manière dramatique), même lorsque le fichier GGUF lui-même tient.

Début rapide de llama-cli et paramètres clés

llama-cli est le moyen le plus rapide de valider que votre modèle charge, que votre backend fonctionne et que vos prompts se comportent.

Exécution minimale

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200

Exécution de chat interactif

Le mode conversation est conçu pour les templates de chat. Il active généralement un comportement interactif et formate les prompts selon le template du modèle.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "You are a concise systems engineering assistant." \
  --ctx-size 4096

Pour terminer la génération lorsque le modèle imprime une séquence spécifique, utilisez un reverse prompt. C’est particulièrement utile en mode interactif.

Principaux drapeaux llama-cli qui comptent

Plutôt que de mémoriser 200 drapeaux, concentrez-vous sur ceux qui dominent la correction, la latence et la mémoire.

Modèle et téléchargement

Contexte et débit

Offload GPU et sélection du matériel

Échantillonnage et qualité de sortie

Exemples de charges de travail avec llama-cli

Résumer un fichier, pas juste un prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300

Rendre les résultats plus reproductibles

Lors du débogage des prompts, fixez la seed et réduisez le hasard :

llama-cli \
  -m models/my-model.gguf \
  -p "Extract key risks from this design note." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Début rapide de llama-server avec API compatible OpenAI

llama-server est un serveur HTTP intégré qui peut exposer :

• des endpoints compatibles OpenAI pour le chat, les complétions, les embeddings et les réponses,
• une interface Web pour les tests interactifs,
• des endpoints de monitoring optionnels pour la visibilité en production.

Démarrer un serveur avec un modèle local

llama-server \
  -m models/my-model.gguf \
  -c 4096

Par défaut, il écoute sur 127.0.0.1:8080.

Pour lier extérieurement (par exemple dans Docker ou un LAN), spécifiez l’hôte et le port :

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Drapeaux serveur optionnels mais importants

Si vous exécutez dans des conteneurs, de nombreux paramètres peuvent également être contrôlés via les variables d’environnement LLAMA_ARG_*.

Exemples d’appels API

Complétions de chat avec curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a quick llama.cpp checklist." }
    ],
    "temperature": 0.7
  }'

Astuce pour les déploiements réels : si vous définissez --api-key, vous pouvez l’envoyer via un en-tête x-api-key (ou continuer à utiliser les en-têtes Authorization selon votre passerelle).

Client Python OpenAI ciblant llama-server

Avec un serveur compatible OpenAI, de nombreux clients peuvent fonctionner en changeant uniquement base_url.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain threads vs batch size in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Embeddings

Les embeddings compatibles OpenAI sont exposés à /v1/embeddings, mais le modèle doit supporter un mode de pooling d’embedding qui n’est pas none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Si vous exécutez un modèle d’embedding dédié, envisagez de lancer le serveur en mode embeddings uniquement :

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

ou si vous souhaitez exécuter llama-cpp avec un modèle d’embedding sur CPU :

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

essayez comme ceci :

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "your text here" \
  --pooling last \
  --verbose-prompt

Servir plusieurs modèles depuis un seul processus

Les exemples ci-dessus lient llama-server à un seul modèle au démarrage. Si vous avez besoin de basculer entre modèles à la volée — sans redémarrer le processus — c’est à cela que sert le mode router. Voir llama-server router mode: dynamic model switching without restarts. Pour un flux scriptable de déchargement de tous les modèles qui libère la VRAM sans redémarrer le routeur, voir Unload All llama.cpp Router Models Without Restarting.

Performance, monitoring et durcissement en production

La question FAQ « Quelles options de ligne de commande llama.cpp comptent le plus pour la vitesse et la mémoire » devient beaucoup plus facile lorsque vous traitez l’inférence comme un système :

• Le plafond de mémoire est généralement la première contrainte (RAM sur CPU, VRAM sur GPU).
• La taille du contexte est un multiplicateur de mémoire majeur.
• L’offload des couches GPU est souvent le chemin le plus rapide vers des tokens par seconde plus élevés.
• Les tailles de batch et les threads peuvent améliorer le débit mais peuvent aussi augmenter la pression sur la mémoire.

Pour une vue plus approfondie, orientée ingénierie, voir : LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Si vous voulez des résultats mesurés de style llama-cli sur une GPU de classe 16 Go — tokens par seconde, VRAM et charge GPU en balayant le contexte (19K / 32K / 64K) sur des GGUF denses et MoE — voir 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

Pour Qwen 3.6 spécifiquement, llama.cpp prend maintenant en charge la prédiction multi-token (MTP) de décodage spéculatif intégrée qui peut augmenter significativement le débit de génération. Voir Qwen 3.6 27B and 35B MTP vs Standard on 16GB GPU pour les vitesses de génération mesurées, la surcharge VRAM et les valeurs recommandées de --spec-draft-n-max.

Monitoring de llama-server avec Prometheus et Grafana

llama-server peut exposer des métriques compatibles Prometheus à /metrics lorsque --metrics est activé. Cela s’accorde naturellement avec les configs de scrape Prometheus et les dashboards Grafana.

Pour des dashboards et alertes spécifiques à llama.cpp (et vLLM, TGI) : Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp. Guides plus larges : Observability: Monitoring, Metrics, Prometheus & Grafana Guide et Observability for LLM Systems.

Checklist de durcissement de base

Lorsque votre llama-server est accessible au-delà de localhost :

• utilisez --api-key (ou --api-key-file) pour que les requêtes soient authentifiées,
• évitez de vous lier à 0.0.0.0 sauf si vous en avez besoin,
• envisagez TLS via les drapeaux SSL du serveur ou terminez TLS sur un proxy inverse,
• restreignez la concurrence avec --parallel pour protéger la latence sous charge.

Gains rapides de dépannage

Le modèle charge mais les réponses sont étranges en chat

Les endpoints de chat sont meilleurs lorsque le modèle a un template de chat supporté. Si les sorties semblent non structurées, essayez :

• d’utiliser llama-cli --conversation plus un --system-prompt explicite,
• de vérifier que votre modèle est une variante instruction ou chat-tuned,
• de tester en utilisant l’interface Web du serveur avant de l’intégrer dans une application.

Vous rencontrez une erreur de mémoire insuffisante (out of memory)

Réduisez le contexte ou choisissez une quantification plus petite :

• baissez --ctx-size,
• réduisez --n-gpu-layers si la VRAM est le problème,
• passez à un modèle plus petit ou à une quantification plus compressée.

C’est lent sur CPU

Commencez par :

• --threads égal à vos cœurs physiques,
• des tailles de batch modérées,
• valider que vous avez installé une build qui correspond à votre machine (fonctionnalités CPU et backend).

Références

• Official llama.cpp repository and docs
• Official CLI flags documentation
• Official llama-server documentation and API details