llama.cpp sans surcouche : servir un modèle GGUF avec llama-server

Ollama gère les modèles à votre place. llama-server, le serveur HTTP livré avec llama.cpp, prend le chemin inverse : on lui donne un fichier GGUF, chaque réglage se passe en ligne de commande, et l’API répond au format OpenAI.

Ce que fait llama-server

Son README le décrit comme un serveur HTTP léger en C/C++. Il fait de l’inférence CPU et GPU sur des modèles F16 ou quantifiés, expose des routes compatibles OpenAI et Anthropic Messages, traite plusieurs requêtes en parallèle et sert une interface web à la même adresse que l’API.

Le README du dépôt propose un script d’installation, des binaires précompilés, une image Docker et la compilation depuis les sources. Son démarrage rapide emploie llama serve ; la documentation du serveur décrit le binaire llama-server, utilisé ici.

Charger un GGUF

# fichier local
llama-server -m <chemin>/modele.gguf -c 8192

# dépôt Hugging Face, quantification facultative
llama-server -hf <utilisateur>/<modele>-GGUF:Q4_K_M

Avec -hf, la quantification est facultative, insensible à la casse, et vaut Q4_K_M par défaut. --hf-file désigne un fichier précis du dépôt et prend le pas sur la quantification.

Les options qui comptent

• -c, --ctx-size : taille du contexte. Le défaut, 0, reprend la valeur du modèle. Le cache KV grossit avec le contexte (détail ici) : le fixer explicitement évite les surprises.
• -ngl, --n-gpu-layers : nombre maximal de couches placées en VRAM, soit un nombre exact, soit auto, soit all. Défaut : auto.
• -np, --parallel : nombre de slots servis en parallèle, -1 (automatique) par défaut.
• -fa, --flash-attn : on, off ou auto, défaut auto.
• -a, --alias : nom du modèle tel que l’API le présente.
• --host et --port : 127.0.0.1 et 9931 par défaut pour le binaire.

La plupart des options ont une variable d’environnement (LLAMA_ARG_CTX_SIZE, LLAMA_ARG_PORT… ; LLAMA_API_KEY pour la clé). Si drapeau et variable coexistent, le drapeau l’emporte.

llama-server -m <chemin>/modele.gguf -c 8192 -ngl all -a local

L’API

Les routes /v1/chat/completions, /v1/completions, /v1/models et /v1/embeddings suivent le format OpenAI ; les embeddings exigent un modèle dont le pooling n’est pas none. /health sert de sonde : HTTP 503 avec « Loading model » pendant le chargement, HTTP 200 et {"status": "ok"} une fois prêt.

curl http://localhost:9931/health

curl http://localhost:9931/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLE_API" \
  -d '{"model": "local", "messages": [{"role": "user", "content": "Explique le RF2 en deux phrases."}]}'

Un client OpenAI existant n’a qu’à pointer base_url sur http://localhost:9931/v1.

Clé d’API et exposition

Par défaut, aucune clé n’est définie. --api-key en accepte une ou plusieurs, séparées par des virgules ; --api-key-file lit un fichier à une clé par ligne, ce qui évite d’écrire la clé dans la ligne de commande.

chmod 600 <chemin>/llama-keys
llama-server -m <chemin>/modele.gguf --api-key-file <chemin>/llama-keys

/health reste public, sans contrôle de clé. Pour un déploiement public, le README recommande une clé d’API et un reverse proxy, --cors-origins en option : par défaut, le serveur renvoie tout en-tête Origin avec les credentials autorisés. TLS natif possible avec --ssl-key-file et --ssl-cert-file, à condition d’avoir compilé avec -DLLAMA_OPENSSL=ON.

Interface d’écoute et pare-feu : même démarche qu’avec Ollama.

llama.cpp ou Ollama ?

Le README d’Ollama cite llama.cpp dans ses backends. Ollama apporte la gestion des modèles (pull, ls, rm, déchargement automatique), mais son API locale n’a pas d’authentification. llama-server se justifie pour piloter finement contexte, couches GPU et slots, servir un GGUF par son chemin, ou disposer d’une clé d’API sans composant supplémentaire.

Ce qu’il faut retenir

• llama-server -m modele.gguf ou -hf dépôt:quant : un fichier, une API, 127.0.0.1:9931 par défaut pour le binaire, 0.0.0.0:8080 dans l’image Docker.
• -c fixe le contexte (0 = celui du modèle), -ngl les couches en VRAM (auto par défaut, all pour tout).
• La plupart des options ont une variable LLAMA_ARG_*, le drapeau gagnant en cas de conflit.
• Aucune clé par défaut : --api-key-file avant toute écoute hors de 127.0.0.1, et /health reste public.
• Ollama pour gérer un catalogue de modèles, llama-server pour maîtriser chaque réglage.

In English

llama-server loads a GGUF file and exposes it through an OpenAI-compatible API. Useful options (context, GPU layers, slots), API key, service health, and when to prefer it over Ollama. Authentication is not enforced by default and is enabled with –api-key or –api-key-file, /health stays public, and -hf downloads a GGUF from Hugging Face.

Sources & vérification

Relevé sur : Documentation llama.cpp, relevé 2026-10

• llama.cpp, README du dépôt github.com
• llama.cpp, README de llama-server github.com
• llama.cpp, Dockerfile CPU (cible server) github.com
• Hugging Face, Optimizing LLMs for Speed and Memory (cache KV) huggingface.co
• Ollama, dépôt GitHub (backends) github.com
• Ollama, CLI reference docs.ollama.com
• Ollama, FAQ docs.ollama.com
• Ollama, Authentication docs.ollama.com

Comment les billets sont vérifiés et corrigés