Démarrage rapide de llama.cpp avec CLI et serveur

Je reviens sans cesse à llama.cpp pour l’inférence locale : il vous offre un contrôle qu’Ollama et autres abstraient, et cela 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 de référence : 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 une orientation vers :

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

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

Il est également utile de comprendre llama.cpp même si vous choisissez ultérieurement un serveur de runtime à plus haut 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 benchmarker les choix d’outils dans : Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Installation de llama.cpp sur Windows, macOS et Linux

Il existe trois chemins d’installation pratiques, selon que vous privilégiez la commodité, la portabilité ou la performance maximale.

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 des binaires préconstruits

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

Un flux de travail courant :

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

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

Construction depuis le source pour votre matériel exact

Si vous tenez à extraire la meilleure performance de votre backend CPU/GPU, construisez depuis le source avec CMake.

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

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

Après la construction, 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 construction

Sur Ubuntu 24.04 avec un 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 (ajouter à ~/.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 OpenSSL (nécessaires pour une construction propre) :

sudo apt update
sudo apt install libssl-dev

4. Construire 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 périphériques à l’exécution. C’est utile si vous déployez la même construction 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 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

Puis exécutez-le par chemin :

llama-cli -m models/my-model.gguf -p "Bonjour ! Expliquez ce qu'est llama.cpp." -n 128

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

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

# Télécharger un modèle depuis HF et exécuter un prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Il était une fois," \
  -n 200

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 "Résumez le concept de quantification en un paragraphe." \
  -n 160

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

Choix de la quantification pour l’inférence locale

La quantification est la réponse pratique à la question « Quelle quantification GGUF devriez-vous choisir pour l’inférence locale » car elle implique directement un compromis entre 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 bête » pour votre tâche, la solution est souvent soit un meilleur modèle, soit une quantification moins agressive, pas seulement des ajustements d’échantillonnage.

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

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

llama-cli est la façon la plus rapide de valider que votre modèle charge, que votre backend fonctionne et que vos prompts se comportent comme prévu.

Exécution minimale

llama-cli \
  -m models/my-model.gguf \
  -p "Rédigez une courte comparaison TCP vs UDP." \
  -n 200

Exécution de chat interactif

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

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Vous êtes un assistant en ingénierie des systèmes concis." \
  --ctx-size 4096

Pour arrêter la génération lorsque le modèle imprime une séquence spécifique, utilisez un prompt inverse. 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 justesse, la latence et la mémoire.

Modèle et téléchargement

Contexte et débit

Offload GPU et sélection de matériel

Échantillonnage et qualité de sortie

Exemples de charges de travail avec llama-cli

Résumer un fichier, pas seulement un prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Vous résumez des documents techniques. Sortie maximale de cinq puces." \
  --file ./docs/incident-report.txt \
  -n 300

Rendre les résultats plus reproductibles

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

llama-cli \
  -m models/my-model.gguf \
  -p "Extrayez les risques clés de cette note de conception." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Démarrage 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 des 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 externalement (par exemple à l’intérieur de Docker ou d’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 du 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": "Vous êtes un assistant serviable." },
      { "role": "user", "content": "Donnez-moi une checklist rapide llama.cpp." }
    ],
    "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": "Vous êtes un assistant concis."},
        {"role": "user", "content": "Expliquez threads vs batch size dans 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 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": ["bonjour", "monde"],
    "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 voulez 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 "votre texte ici" \
  --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 devez basculer entre des modèles sur une base par requête — sans redémarrer le processus — c’est à cela que sert le mode routeur. Voir llama-server router mode: dynamic model switching without restarts.

Performance, monitoring et durcissement en production

La question FAQ « Quelles options de ligne de commande de 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 mémoire est généralement la première contrainte (RAM sur CPU, VRAM sur GPU).
• La taille du contexte est un multiplicateur mémoire majeur.
• L’offload de couches GPU est souvent le chemin le plus rapide vers plus de tokens par seconde.
• Les tailles de lot et les threads peuvent améliorer le débit mais peuvent aussi augmenter la pression mémoire.

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

Si vous voulez des résultats de style llama-cli mesurés sur un 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).

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 configurations de scraping Prometheus et les tableaux de bord Grafana.

Pour les tableaux de bord 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 lier à 0.0.0.0 à moins d’en avoir besoin,
• envisagez TLS via les drapeaux SSL du serveur ou terminez TLS à une passerelle 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 dans le chat

Les endpoints de chat sont meilleurs lorsque le modèle a un modèle de chat pris en charge. 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 le brancher dans une application.

Vous rencontrez une erreur de mémoire

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 lot modérées,
• de valider que vous avez installé une construction 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