Prise en main rapide de llama.cpp avec l'interface en ligne de commande et le serveur

llama.cpp est un moteur d’inférence C/C++ pour les modèles GGUF : llama-cli pour le chat interactif, llama-completion pour les invites scriptées, et llama-server pour une API HTTP compatible OpenAI.

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 biais vers :

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

Il brille quand vous souhaitez la confidentialité et le fonctionnement hors ligne, quand vous avez besoin d’un contrôle déterministe sur les drapeaux d’exécution, ou quand vous voulez intégrer l’inférence dans un système plus large sans exécuter une pile Python lourde.

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

Si Ollama est spécifiquement l’alternative que vous envisagez par rapport à llama-server, llama.cpp vs Ollama in 2026 est la comparaison en tête-à-tête dédiée, avec des déclencheurs concrets pour savoir quand conserver Ollama et quand passer au llama.cpp direct.

Installer llama.cpp sur Windows, macOS et Linux

Les commandes ci-dessous correspondent à llama.cpp v0.6.0 (5 octobre 2026). Une entrée de catalogue pour le même runtime — inférence GGUF sur CPU et backends accélérateurs, versionnée par commit de build — se trouve dans la référence runtime llama.cpp sur LLM Systems. Il existe quatre chemins d’installation pratiques, selon que vous souhaitiez la commodité, la portabilité ou les performances maximales.

Installation via des gestionnaires de paquets

C’est l’option la plus rapide pour « se lancer ».

# 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

# Ubuntu (universe). Ce paquet est en grand retard sur l'amont :
# 8681+dfsg contre le build actuel b11433 / v0.6.0, donc des drapeaux plus récents manqueront.
sudo apt install llama.cpp-tools

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

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

Installation via des 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 système d’exploitation et plusieurs backends (variantes CPU uniquement et activées GPU).

Un workflow courant :

# 1) Téléchargez la bonne archive pour votre OS et backend
# 2) Décompressez-la
# 3) Exécutez-la depuis le dossier décompressé

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

Exécuter le conteneur officiel

Le projet publie des images serveur sur GitHub Container Registry. L’image CPU est ghcr.io/ggml-org/llama.cpp:server ; l’image CUDA est :server-cuda. Le conteneur doit écouter sur toutes les interfaces, car le bind par défaut est toujours 127.0.0.1 :

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Compiler depuis la source pour votre matériel exact

Si vous tenez à extraire les meilleures performances de votre backend CPU/GPU, compilez depuis la 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 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 complet de build

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

1. Installer la toolkit CUDA 13.1. Ce guide fixe l’installeur local 13.1.1. Une toolkit plus récente depuis le dépôt Ubuntu 24.04 de NVIDIA suit les mêmes étapes de fichier de pin et de deb local avec des noms de fichiers mis à jour.

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

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

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

sudo apt update
sudo apt install libssl-dev

4. Compiler llama.cpp (depuis le répertoire contenant votre clone 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 répertoire llama.cpp.

Vous pouvez également compiler plusieurs backends et choisir les appareils à l’exécution. C’est utile si vous déployez le 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 à fichier unique qui regroupe les poids du modèle et les métadonnées standardisées nécessaires par des 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

Puis exécutez-le par chemin :

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

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

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

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

Vous pouvez également spécifier la quantification dans le sélecteur de dépôt 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 \
  -st

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 la quantification pour l’inférence locale

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

Un point de départ pragmatique :

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

Souvenez-vous également que la taille de la fenêtre de contexte compte : les tailles de contexte plus grandes augmentent l’utilisation de la mémoire (parfois considérablement), même si le fichier GGUF lui-même correspond.

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

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

llama-cli est devenu un client de chat interactif depuis la réécriture de décembre 2025. Quand le modèle inclut un modèle de chat, le mode conversation est activé par défaut, et --no-conversation est rejeté avec un pointeur vers llama-completion. Ce second binaire est l’ancien llama-cli : une invite en entrée, une complétion en sortie, adapté aux scripts et aux pipelines. Depuis le nouveau client, --single-turn (-st) génère une réponse unique et se termine.

Une réponse, puis sortie

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

La même invite via le binaire non interactif :

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

Exécution de chat interactif

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

--conversation n’est plus requis. Pour mettre fin à la génération lorsque le modèle affiche une séquence spécifique, utilisez une invite inversée.

Principaux drapeaux llama-cli qui comptent

Plutôt que de mémoriser 200 drapeaux, concentrez-vous sur ceux qui dominent la justesse, 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 la sortie

Exemples de charges de travail avec llama-cli

Résumer un fichier, pas juste une invite

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

Rendre les résultats plus reproductibles

Quand vous déboguez des invites, fixez la graine et réduisez l’aléatoire :

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

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

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

• des points de terminaison compatibles OpenAI pour le chat, les complétions, les embeddings et les réponses,
• une interface Web pour les tests interactifs,
• des points de terminaison de surveillance 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 se lier à l’extérieur (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 aussi être contrôlés via des 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 — c’est aussi ainsi que les agents de recherche tels que lukeswade/deep-research parlent directement à llama-server, sans couche d’adaptateur séparée. Self-Hosted Deep Research Systems: 12 Tools Compared couvre ce projet et d’autres visant des points de terminaison locaux compatibles OpenAI.

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 prendre en charge un mode de poolage 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 démarrer 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 changer de modèle à la demande par requête — sans redémarrer le processus — c’est à quoi sert le mode routeur. Voir llama-server router mode: dynamic model switching without restarts. Pour un flux de déchargement de tous les modèles scriptable qui libère la VRAM sans redémarrer le routeur, voir Unload All llama.cpp Router Models Without Restarting.

Performances, surveillance et durcissement de production

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

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

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

Si vous souhaitez des résultats mesurés de type llama-cli sur un GPU de classe 16 GB — 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, llama.cpp prend en charge le décodage spéculatif Multi-Token Prediction intégré. Activez-le avec --spec-type draft-mtp ; --spec-draft-n-max définit combien de tokens la tête de brouillon propose (par défaut 3). v0.6.0 étend ce même chemin MTP à Qwen4Exp. Pour la comparaison des méthodes, voir Speculative Decoding. Pour des chiffres mesurés de Qwen 3.6 sur 16 GB, voir Qwen 3.6 MTP vs Standard on 16GB GPU.

Surveillance de llama-server avec Prometheus et Grafana

llama-server expose des métriques compatibles Prometheus sur /metrics seulement quand --metrics est activé. Pointez un job de scrape Prometheus vers ce chemin. Les tableaux de bord et les seuils d’alerte pour llama.cpp, vLLM et TGI sont dans Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp.

Liste de durcissement de base

Quand 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 le TLS via les drapeaux SSL du serveur ou terminez le TLS sur un proxy inverse,
• restreignez la concurrence avec --parallel pour protéger la latence sous charge,
• laissez --tools et --agent désactivés. Les deux sont expérimentaux et exposent des opérations de fichier et de shell via l’API ; activer l’un ou l’autre restreint aussi les CORS à localhost.

Gains rapides de dépannage

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

Les points de terminaison de chat sont les meilleurs quand le modèle a un modèle de chat pris en charge. Si les sorties semblent non structurées, essayez :

• de passer une invite système explicite --system-prompt (le mode conversation est déjà la valeur par défaut dans llama-cli),
• de vérifier que votre modèle est une variante ajustée pour les instructions ou le chat,
• de tester en utilisant l’interface Web du serveur avant de le connecter à une application. v0.6.0 a reconstruit cette interface avec un navigateur Hugging Face Hub, de sorte qu’un modèle peut être téléchargé depuis la page plutôt que seulement depuis l’CLI.

Les modèles de réflexion enveloppent la réponse dans des traces de raisonnement. --reasoning off supprime cela, et --reasoning-format deepseek déplace la trace dans reasoning_content au lieu de content.

Vous rencontrez un manque de mémoire

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

• réduisez --ctx-size,
• réduisez --n-gpu-layers si la VRAM est le problème, ou définissez --cpu-moe pour que les poids d’expert d’un modèle MoE restent en RAM,
• passez à un modèle plus petit ou à une quantification plus compressée,
• quantifiez le cache KV avec --cache-type-k q8_0 --cache-type-v q8_0.

Le contexte ou la répartition GPU n’est pas ce que vous avez demandé

--fit est activé par défaut et réécrit les paramètres de mémoire que vous avez laissés non définis, visant à laisser 1024 MiB libres sur chaque appareil (--fit-target). Il rétrécira le contexte, mais jamais en dessous de --fit-ctx (4096), et seulement si vous n’avez pas passé -c. Il ne touchera pas à la disposition des couches une fois que vous passez n’importe quel -ngl. --fit off désactive le mécanisme. Si les journaux disent n_gpu_layers already set by user, votre -ngl explicite est ce qui s’est chargé, et fit ne sauvera pas un manque de mémoire de cela.

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é un build qui correspond à votre machine (fonctionnalités CPU et backend).

Références

• Dépôt et documentation officiels de llama.cpp
• Documentation officielle des drapeaux CLI
• Documentation officielle de llama-server et détails de l’API