Démarrage rapide de llama.cpp avec l'interface CLI et le serveur

Je reviens constamment vers llama.cpp pour l’inférence locale — cela vous donne un contrôle que Ollama et d’autres abstraigent, et cela fonctionne parfaitement. Il est facile d’exécuter des modèles GGUF de manière interactive avec llama-cli ou d’exposer une API HTTP compatible avec OpenAI avec llama-server.

Si vous hésitez encore entre les approches locales, auto-hébergées et en cloud, commencez par le guide de base LLM Hosting en 2026 : Comparaison entre les infrastructures locales, auto-hébergées et en cloud.

Pourquoi utiliser llama.cpp en 2026

llama.cpp est un moteur d’inférence léger avec une tendance à :

• la portabilité sur les processeurs et les multiples backends GPU,
• une latence prévisible sur une seule machine,
• une flexibilité de déploiement, des ordinateurs portables aux nœuds on-premises.

Il excelle lorsqu’on souhaite la confidentialité et l’opération hors ligne, lorsqu’on a besoin d’un contrôle déterministe sur les drapeaux d’exécution, ou lorsqu’on souhaite intégrer l’inférence dans un système plus grand sans exécuter une pile Python lourde.

Il est également utile de comprendre llama.cpp même si vous choisissez plus tard un runtime serveur à plus grande throughputs. Par exemple, si votre objectif est la throughputs maximale sur les GPU, vous pouvez également le comparer à vLLM en utilisant : vLLM Quickstart : LLM Serving à haute performance et vous pouvez tester les choix d’outils dans : Ollama vs vLLM vs LM Studio : Meilleure façon de faire tourner les LLM localement en 2026 ?.

Installer llama.cpp sur Windows, macOS et Linux

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

Installer via les gestionnaires de paquets

C’est l’option la plus rapide pour “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

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

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

Installer 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 uniquement et GPU activés).

Un workflow courant :

# 1) Télécharger l'archive adaptée à votre OS et backend
# 2) Extraire l'archive
# 3) Exécuter depuis le dossier extrait

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

Construire à partir de la source pour votre matériel exact

Si vous souhaitez tirer le meilleur rendement de votre backend CPU/GPU, construisez à partir de 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 construction, les binaires sont généralement ici :

ls -la ./build/bin/

Build GPU en une seule commande

Activez le backend correspondant à votre matériel (exemples 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 : walkthrough complet de la 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) :

# toolkit CUDA
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 (nécessaires pour une construction propre) :

sudo apt update
sudo apt install libssl-dev

4. Construire llama.cpp (à partir du répertoire 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
cp llama.cpp/build/bin/llama-* llama.cpp

Cela produit llama-cli, llama-mtmd-cli, llama-server et llama-gguf-split dans le répertoire llama.cpp.

Vous pouvez également compiler plusieurs backends et choisir les appareils à l’exécution. Cela est utile si vous déployez le même build sur des machines hétérogènes.

Choisissez 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 de fichier unique 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 "Bonjour ! Expliquez ce qu'est llama.cpp." -n 128

Option B : Laissez 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 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 repo 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 workflow entièrement hors ligne ultérieurement, --offline force l’utilisation du cache et empêche l’accès réseau.

Choix de 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 échange directement qualité, taille du modèle et vitesse.

Un point de départ pratique :

• commencez avec une variante Q4 ou Q5 pour les machines centrées sur le CPU,
• passez à une précision plus élevée (ou 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, et non seulement des ajustements de sampling.

N’oubliez pas aussi que la taille de contexte compte : les tailles de contexte plus grandes augmentent l’utilisation de la mémoire (souvent de manière dramatique), même si le fichier GGUF lui-même tient.

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

llama-cli est la méthode la plus rapide pour valider que votre modèle se 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 "Écrivez un court comparatif TCP vs UDP." \
  -n 200

Exécution interactive de chat

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

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

Pour terminer la génération lorsqu’un séquence spécifique est imprimée par le modèle, utilisez un prompt inverse. Cela est particulièrement utile en mode interactif.

Principaux drapeaux de llama-cli qui comptent

Au lieu de retenir 200 drapeaux, concentrez-vous sur ceux qui dominent la précision, la latence et la mémoire.

Modèle et téléchargement

Contexte et throughputs

Décharge GPU et sélection matérielle

É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. Sortez au maximum cinq points." \
  --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 une API compatible OpenAI

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

• des points de terminaison compatibles avec OpenAI pour le chat, les complétions, les embeddings et les réponses,
• une interface Web UI pour des tests interactifs,
• des points de terminaison de surveillance optionnels pour une visibilité de 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 à l’extérieur (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 serveur importants mais optionnels

Si vous exécutez dans des conteneurs, de nombreuses 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 utile." },
      { "role": "user", "content": "Donnez-moi rapidement une checklist llama.cpp." }
    ],
    "temperature": 0.7
  }'

Conseil 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 d’autorisation selon votre passerelle).

Client Python OpenAI ciblant llama-server

Avec un serveur compatible OpenAI, de nombreux clients peuvent fonctionner en modifiant 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 les threads vs taille de batch dans llama.cpp."}
    ],
)

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

Embeddings

Les embeddings compatibles avec OpenAI sont exposés à /v1/embeddings, mais le modèle doit supporter un mode de pooling d’embeddings 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 d’embeddings uniquement :

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Performance, surveillance et renforcement de la production

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

• Plafond de mémoire est généralement la première contrainte (RAM sur CPU, VRAM sur GPU).
• Taille de contexte est un multiplicateur majeur de mémoire.
• Décharge des couches GPU est souvent le chemin le plus rapide vers un plus grand nombre de tokens par seconde.
• Tailles de batch et threads peuvent améliorer la throughputs mais peuvent également augmenter la pression mémoire.

Pour une vue plus approfondie, centrée sur l’ingénierie, consultez : Performance des LLM en 2026 : Benchmarks, Bottlenecks & Optimisation.

Surveillance de llama-server avec Prometheus et Grafana

llama-server peut exposer des métriques compatibles avec Prometheus à /metrics lorsque --metrics est activé. Cela s’associe naturellement avec les configurations de scraping de Prometheus et les tableaux de bord Grafana.

Pour des tableaux de bord et des alertes spécifiques à llama.cpp (et vLLM, TGI) : Surveiller l’inférence LLM en production (2026) : Prometheus & Grafana pour vLLM, TGI, llama.cpp. Guides plus larges : Observabilité : Guide de surveillance, métriques, Prometheus & Grafana et Observabilité pour les systèmes LLM.

Checklist de renforcement 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 sauf si nécessaire,
• envisagez le TLS via les drapeaux SSL du serveur ou le terminer au niveau d’un reverse proxy,
• restreignez la concurrence avec --parallel pour protéger la latence sous charge.

Résolutions rapides des problèmes

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

Les endpoints de chat sont les meilleurs lorsque le modèle a un template de chat pris en charge. Si les sorties semblent désordonnées, essayez :

• d’utiliser llama-cli --conversation avec un --system-prompt explicite,
• de vérifier que votre modèle est une variante d’instruction ou de chat optimisée,
• de tester via l’interface Web UI du serveur avant de l’intégrer à une application.

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 le problème est la VRAM,
• changez pour un modèle plus petit ou une quantification plus compressée.

C’est lent sur le CPU

Commencez par :

• --threads égal au nombre de cœurs physiques,
• des tailles de batch modérées,
• vérifier que vous avez installé une build correspondant à votre machine (caractéristiques du CPU et backend).

Références

• Référentiel officiel et documentation de llama.cpp
• Documentation officielle des drapeaux CLI
• Documentation officielle de llama-server et détails API