Épingler une version de llama.cpp sur votre serveur

Ce qui a changé dans la gestion des versions de llama.cpp

Épingler les releases de llama.cpp consiste à compiler un tag nommé et à enregistrer ce nom à côté du fichier du modèle. Le tag ne change jamais de lui-même. Le serveur continue donc à produire demain ce qu’il produisait aujourd’hui. Pendant des années, il n’existait qu’un seul type de tag : un numéro de build comme b10502, créé automatiquement à partir de master. Depuis 2026, il existe un second type, le tag de version comme v0.1.2. Les deux branches sont créées au même moment à partir du même historique.

Les tags de version n’ont pas encore le sens habituel d’un numéro de version. Les notes de release sur v0.1.2 le précisent en une ligne :

La gestion sémantique des versions est encore en cours. Plus d’informations sont disponibles dans https://github.com/ggml-org/ggml/discussions/1579

Prenez cette phrase au pied de la lettre. La discussion ggml associée à ce lien décrit le schéma encore en cours de définition, notamment la fréquence de création des releases et ce qui constitue un patch. Un tag v0. indique que le projet a choisi de marquer un point dans l’historique. Il ne garantit pas que le suivant soit un remplacement sûr et compatible simplement parce que son dernier chiffre a augmenté de 1.

Le nombre d’un tag de build n’a pas non plus de signification en termes de version. Il correspond au nombre de commits. Il augmente donc automatiquement, même si rien d’utile pour votre configuration n’a changé. Au 19 août 2026, la page d’accueil de la liste des releases affichait neuf tags de build, de b10455 à b10502, avec v0.1.2 parmi eux.

Ne construisez jamais depuis la branche master sur un serveur qui fournit un service

git pull suivi d’une nouvelle compilation vous donne tout ce qui a été intégré au cours des dernières heures. Cela convient sur un ordinateur portable. Sur un serveur, vous ne pouvez plus répondre à la question essentielle lorsqu’un comportement change : qu’est-ce qui fonctionne maintenant, et qu’est-ce qui fonctionnait la semaine dernière ? Le texte produit par un modèle et la vitesse à laquelle il le produit dépendent tous deux du build. Une réclamation indiquant que les réponses se sont dégradées mardi dernier ne peut recevoir aucune réponse si le commit de mardi n’a jamais été consigné.

Épinglez plutôt un tag. Le projet les crée pour vous, et chaque archive de release précompilée porte le nom de l’un d’eux.

À quel tag faut-il épingler les releases de llama.cpp ?

Épinglez un tag de build lorsque vous voulez conserver un état précis et connu. C’est la branche qui possède l’historique le plus long, celle dont reprennent le nom les archives de release et celle que citent la plupart des rapports de bug. Un numéro de build est donc le plus simple à comparer avec celui d’une autre personne.

Épinglez un tag de version si vous préférez suivre une liste plus courte de points choisis. Lisez les notes avant de changer de version et gardez la réserve indiquée plus haut à l’esprit, car la numérotation ne constitue pas encore un contrat de compatibilité.

Dans les deux cas, la règle opérationnelle est identique. La chaîne du tag est stockée dans un fichier, le serveur est reconstruit uniquement lorsque cette chaîne change, et ce changement résulte d’une décision explicite.

Construire le tag épinglé

sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tags

git describe --tags doit afficher b10502. Un clone shallow effectué sur un tag contient ce commit et aucun commit ultérieur. Personne ne peut donc le déplacer plus tard avec un git pull exécuté par inadvertance. Si l’étape de configuration s’arrête parce qu’une dépendance manque, installez le paquet indiqué, puis relancez-la.

Compilez avec les options adaptées à votre matériel. CPU uniquement :

cmake -B build
cmake --build build --config Release -j $(nproc)

GPU NVIDIA, avec le toolkit CUDA installé au préalable :

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

OpenBLAS sur une machine équipée uniquement d’un CPU :

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

Les binaires sont placés dans build/bin, à côté des bibliothèques partagées qu’ils chargent (libllama.so et les fichiers libggml). Vérifiez que le build fonctionne avant de l’installer :

./build/bin/llama-server --version

Installez l’ensemble du répertoire sous un chemin portant le nom du tag, puis faites pointer un seul lien symbolique vers celui-ci :

sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current

Copiez le répertoire, pas le fichier seul. Un llama-server isolé échoue dès sa première exécution avec error while loading shared libraries: libllama.so: cannot open shared object file, car les bibliothèques dont il a besoin se trouvent à côté de lui dans ce répertoire.

Configurez le service pour utiliser le lien symbolique, jamais un répertoire de tag :

[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080

systemd résout le lien symbolique lorsqu’il démarre le processus. Pour changer de build, il suffit donc de modifier la cible du lien symbolique, puis d’exécuter sudo systemctl restart llama-server. Le reste du fichier d’unité et le reverse proxy placé devant le service sont présentés dans le guide complet consacré à un serveur llama.cpp sur un VPS.

Notez le tag à côté du fichier GGUF et la quantification

Le build ne détermine qu’une partie du résultat. Le fichier du modèle constitue l’autre partie. GGUF (GGML universal file format) est le conteneur dans lequel les poids sont distribués. Le même modèle est publié avec de nombreux niveaux de quantification. Deux serveurs utilisant le même tag peuvent donc produire des résultats différents si l’un contient un fichier Q4_K_M et l’autre un fichier Q8_0. Conservez un petit fichier à côté du modèle. Il doit contenir tout ce qui est nécessaire pour reconstruire exactement la configuration :

tag: b10502
commit: 7c1f2a9
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>

Récupérez le commit avec git rev-parse --short HEAD dans le checkout épinglé. Obtenez la somme de contrôle avec sha256sum model-q4_k_m.gguf et comparez-la également à la valeur publiée par l’éditeur au moment du téléchargement. Vérifier un téléchargement avec sa somme de contrôle publiée permet de détecter un fichier tronqué avant qu’il ne provoque un problème difficile à diagnostiquer. L’impact du niveau de quantification lui-même sur les réponses est une autre question. Le coût de chaque niveau de quantification l’explique.

Comment effectuer une mise à niveau sans casser le serveur ?

Effectuez la mise à niveau comme un exercice. Construisez la nouvelle révision à côté de l’ancienne, mesurez les deux et conservez l’ancienne jusqu’à ce que la nouvelle ait fait ses preuves.

1. Clonez la nouvelle révision dans son propre répertoire. Ne réutilisez pas l’ancien checkout.
2. Construisez-la avec les mêmes arguments cmake que ceux enregistrés dans le manifeste.
3. Exécutez llama-bench sur les deux builds avec le même fichier de modèle, la même longueur de prompt et le même nombre de répétitions.
4. Envoyez aux deux serveurs un prompt dont vous connaissez bien la réponse, puis lisez les deux réponses.
5. Déplacez le lien symbolique, redémarrez le service et laissez l’ancien répertoire sur le disque.

/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5

llama-bench affiche une ligne par test, avec une colonne backend, une colonne ngl et une colonne de tokens par seconde indiquant l’écart type. Comparez la même ligne entre les deux builds, et non la ligne du prompt d’un build avec la ligne de génération de l’autre. Une valeur mesurée avec une longueur de prompt différente constitue une autre mesure. C’est pourquoi mesurer les tokens par seconde toujours de la même manière est plus important que la valeur elle-même.

Le retour arrière nécessite deux commandes et ne fonctionne que parce que l’ancien répertoire est toujours présent :

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

Conservez au moins le build précédent. Il occupe une fraction de l’espace disque déjà utilisé par le fichier de modèle placé à côté.

Ce qui casse lors des mises à niveau de llama.cpp

Un fichier de modèle ne se charge plus. C’est généralement la raison initiale de la mise à niveau : un modèle récemment publié utilise une architecture que le build épinglé ne connaît pas, et il ne se charge donc jamais. llama-server se termine pendant le démarrage et le journal contient une ligne failed to load model from /srv/models/model-q4_k_m.gguf. Lisez les lignes affichées juste avant. Elles indiquent jusqu’où le chargeur est arrivé. GGUF contient également une version de format dans son en-tête (la valeur actuelle de la spécification est 3, et la version 2 a élargi les champs de longueur de 32 à 64 bits), mais en pratique, un nom d’architecture inconnu bloque le chargement bien avant que la version de format n’entre en jeu. La solution consiste à utiliser un tag plus récent, puis à le choisir et à le consigner.

Un flag du serveur est renommé ou obsolète. Un flag non reconnu arrête llama-server au démarrage au lieu d’être ignoré. Sous systemd, cela ressemble à un service qui démarre puis s’arrête en boucle. journalctl -u llama-server -n 50 affiche le message réel. Au 19 août 2026, la documentation du serveur indique que --mlock et --mmap sont obsolètes au profit de -lm, --load-mode, qui accepte notamment les valeurs auto, mmap, mlock et dio. Le flag de déport vers le GPU est documenté sous le nom -ngl, --gpu-layers, tandis que les anciens guides utilisent --n-gpu-layers. Avant de déplacer le symlink, exécutez /opt/llama.cpp/<new tag>/bin/llama-server --help et vérifiez chaque flag de votre unit file par rapport à sa sortie.

Une option de build est renommée. Les options CMake sont passées d’un préfixe LLAMA_ à un préfixe GGML_, et la racine CMakeLists.txt contient toujours la correspondance. LLAMA_CUBLAS génère maintenant une erreur fatale qui indique GGML_CUDA comme remplacement, tandis que LLAMA_CUDA et LLAMA_METAL génèrent un avertissement et sont convertis automatiquement. Un script de build qui s’arrête à l’étape de configuration produit le bon résultat. L’échec silencieux est plus grave : si -DGGML_CUDA=ON est omis par erreur, le build réussit, le serveur démarre et tout s’exécute sur le CPU. llama-bench l’affiche immédiatement, car la colonne backend contient CPU.

Le build de l’accélérateur n’est pas portable. Au 19 août 2026, les assets Linux associés à un tag de build sont les variantes CPU, Vulkan, SYCL et OpenVINO, pour x64, arm64 et s390x. La liste ne contient aucune archive CUDA pour Linux. Sur un serveur NVIDIA, il faut donc compiler depuis les sources ou exécuter une container image. Les archives CUDA pour Windows sont publiées pour chaque version du toolkit. C’est un indice utile : la version du toolkit fait partie des éléments qui identifient votre binaire. Consignez-la avec les arguments cmake.

Épingler l’image du conteneur à la place

Même règle, autre nom. Les images publiées (ghcr.io/ggml-org/llama.cpp:server et leurs variantes avec accélérateur) utilisent des noms qui évoluent. Ainsi, exécuter pull sur :server le mois prochain peut fournir un programme différent sous le même nom. Effectuez le pull une fois, puis lisez le digest :

docker pull ghcr.io/ggml-org/llama.cpp:server

docker pull affiche une ligne Digest: sha256:.... Placez ce digest dans le fichier Compose à la place du tag. L’image ne pourra alors pas changer à votre insu lors de la prochaine exécution de docker compose pull. Conservez le digest précédent dans un commentaire afin qu’un rollback ne nécessite qu’une seule modification, comme pour la procédure de mise à niveau et de rollback d’une stack Compose, qui traite tous les autres services de la même manière.

Le rôle d’un pin

Un pin permet d’identifier précisément ce qui s’exécute. Il permet aussi de remettre la build précédente en service en moins d’une minute lorsqu’une modification aggrave la situation. llama.cpp vous demande de suivre deux éléments pour cela : le tag de build et le fichier de modèle, car il vous les fournit séparément. Les runtimes qui les regroupent fonctionnent différemment. La comparaison entre Ollama et llama.cpp en tant que serveurs présente ce compromis : un seul numéro de version pour l’ensemble demande moins d’éléments à consigner et à contrôler.

FAQ

Dois-je figer le tag de build bNNNN ou le tag v0.x ?

Les deux conviennent, à condition d’en figer un. Les tags de build tels que b10502 correspondent à la branche suivie sur le long terme : chaque archive de release précompilée porte ce nom et la plupart des rapports de bug en citent un. Un numéro de build est donc le plus simple à comparer avec celui d’un autre administrateur. Les tags de version tels que v0.1.2 forment une liste plus courte de jalons choisis, ce qui convient à un serveur que vous ne modifiez que quelques fois par an. Le choix importe moins que le fait d’enregistrer la chaîne du tag à côté du fichier de modèle et de faire de la mise à niveau une décision explicite, plutôt qu’un effet secondaire de git pull.

llama.cpp suit-il désormais le versionnage sémantique ?

Pas encore, d’après le projet lui-même. Les notes de release v0.1.2 indiquent que le versionnage sémantique est toujours en cours d’élaboration et renvoient vers une discussion ggml où le schéma est défini, notamment la cadence des releases et ce qui constitue un patch. Considérez un tag de version comme un jalon choisi par les mainteneurs. Ne supposez pas qu’une modification du dernier chiffre garantit une mise à niveau compatible sans adaptation. Testez le nouveau tag avec votre propre fichier de modèle avant de l’utiliser.

Comment savoir quel build llama.cpp mon serveur utilise-t-il ?

llama-server --version affiche la version et les informations de build. Le journal de démarrage commence également par une ligne build qui contient le numéro de build, le hash du commit et le compilateur utilisé. journalctl -u llama-server permet donc de la retrouver pour un service en cours d’exécution. Dans une installation depuis les sources, git describe --tags exécuté dans le checkout figé affiche le tag, et readlink /opt/llama.cpp/current indique vers quel répertoire le service pointe réellement.

Pourquoi mon modèle ne se charge-t-il plus après la mise à niveau de llama.cpp ?

Un échec du chargement juste après une mise à niveau indique une incompatibilité entre le build et le fichier GGUF. Le journal se termine par une ligne failed to load model from qui indique le chemin. Les lignes précédentes montrent jusqu’où le loader a progressé. Lors d’une mise à niveau, un fichier de modèle très récent nécessite un build qui connaît son architecture. Lors d’un retour en arrière, un rollback vers un tag antérieur à celui utilisé pour créer le fichier peut rendre inutilisable un fichier qui fonctionnait la veille. Pointez le lien symbolique vers le build précédent, redémarrez, puis vérifiez quel build et quel fichier fonctionnent ensemble avant de décider lequel modifier.

Existe-t-il des binaires Linux précompilés que je peux figer au lieu de compiler ?

Oui, pour certaines configurations. Chaque tag de build est associé à des archives de release portant son nom, comme llama-b10502-bin-ubuntu-x64.tar.gz, avec des variantes arm64, s390x, Vulkan, SYCL et OpenVINO au 19 August 2026. Ce nommage simplifie le gel de la version, puisque le tag figure dans le nom du fichier. Cette liste ne comportait aucune archive CUDA pour Linux. Un serveur NVIDIA nécessite donc toujours une compilation depuis les sources avec -DGGML_CUDA=ON ou l’utilisation de l’une des images de conteneur CUDA.