Comment épingler une release de llama.cpp
Depuis 2026, llama.cpp utilise aussi des tags v0.6.0 en plus des bNNNN. Découvrez quoi enregistrer avec le GGUF et comment annuler chaque upgrade.
Ce qui a changé dans le versionnage 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 : un tag de version comme v0.6.0. Les deux branches n’évoluent pas au même rythme. Les build tags sont créés presque à chaque commit sur master. Les version tags sont créés manuellement par un mainteneur, à un rythme plus lent. Chaque version release indique le build tag qui lui correspond.
Les version tags étaient initialement expérimentaux. Les notes de release de v0.1.2, publiées le 18 August 2026, le précisaient en une ligne :
Le versionnage sémantique est encore en cours d’élaboration. Plus d’informations sont disponibles dans https://github.com/ggml-org/ggml/discussions/1579
Trois jours plus tard, v0.2.0 a clarifié la situation. Ses notes de release indiquent que cette release « marque le début d’un versionnage sémantique cohérent pour llama.cpp ». Elles décrivent les tags vX.Y.Z comme des versions stables, publiées moins fréquemment et recommandées pour la distribution en aval ainsi que pour les utilisateurs occasionnels. Elles décrivent les tags b[NUM] comme des builds nightly ou de développement intégrant les dernières fonctionnalités, recommandés pour les développeurs et les utilisateurs techniques. Au 14 November 2026, le dernier version tag est v1.0.0, publié le 13 November, et ses notes indiquent que b12359 est le build tag correspondant.
La discussion ggml à l’origine de ce lien présente toujours les raisons de ce schéma. Au 21 October 2026, elle est encore ouverte aux retours. La numérotation des versions a atteint 1.x. Consultez donc les notes avant chaque changement, au lieu d’évaluer une mise à niveau uniquement d’après le chiffre qui a changé.
Le nombre présent dans un build tag n’a aucune signification en termes de version. Il provient du nombre de commits. Il augmente donc de lui-même, qu’un changement pertinent pour votre configuration ait eu lieu ou non.
Ne construisez jamais depuis master sur une machine qui héberge un service
git pull suivi d’une reconstruction vous donne tout ce qui a été intégré au cours des dernières heures. C’est acceptable sur un ordinateur portable. Sur un serveur, vous ne pouvez plus répondre à la question essentielle lorsque le comportement change : qu’est-ce qui fonctionne actuellement, 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 signalant que les réponses se sont dégradées mardi dernier reste sans 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 les archives de release précompilées indiquent un build tag dans leur nom de fichier, à l’exception des bundles de runtime CUDA pour Windows (cudart-llama-bin-win-...).
À quel tag devez-vous épingler les releases de llama.cpp ?
Épinglez un build tag lorsque vous voulez conserver un état précis et connu. C’est la branche qui possède l’historique le plus long, celle dont portent 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 facile à comparer avec celui d’une autre personne.
Épinglez un version tag si vous préférez suivre une liste plus courte de points définis explicitement. C’est la branche que le projet recommande désormais pour la distribution en aval. Chaque version indique le build tag correspondant, et les binaires précompilés sont associés à ce build tag. Notez donc le numéro de build à côté de la version. Lisez les notes avant de mettre à niveau, même si la numérotation a atteint 1.x.
Dans les deux cas, la règle opérationnelle est identique. La chaîne du tag se trouve dans un fichier. Le serveur est reconstruit uniquement lorsque cette chaîne change. Le 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 --tagsgit 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 --versionInstallez 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/currentCopiez 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 8080systemd 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.
Consignez le tag à côté du fichier GGUF et de la quantification
Le build ne détermine qu’une partie du résultat. Le fichier du modèle en détermine l’autre. GGUF (GGML universal file format) est le conteneur dans lequel les poids sont fournis. 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 l’environnement :
tag: b10502
commit: 0adcc3b
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. En effet, 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’influence du niveau de quantification lui-même sur les réponses est une autre question. Le coût de chaque niveau de quantification l’aborde.
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.
- Clonez la nouvelle révision dans son propre répertoire. Ne réutilisez pas l’ancien checkout.
- Construisez-la avec les mêmes arguments
cmakeque ceux enregistrés dans le manifeste. - Exécutez
llama-benchsur 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. - Envoyez aux deux serveurs un prompt dont vous connaissez bien la réponse, puis lisez les deux réponses.
- 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 5llama-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-serverConservez 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 cesse de se charger. C’est généralement la raison initiale de la mise à niveau : un modèle publié récemment utilise une architecture que la build figée ne connaît pas, et son chargement échoue. llama-server se termine pendant le démarrage. Au 21 octobre 2026, le code source du serveur journalise failed to load model, '/srv/models/model-q4_k_m.gguf' dans ce cas, avec une virgule et le chemin entre apostrophes, puis affiche exiting due to model loading error en dernière ligne, sans chemin. Recherchez failed to load model dans le journal plutôt que la ligne complète. Lisez les lignes affichées juste avant, notamment la ligne error loading model: du loader, qui indiquent jusqu’où le chargement est allé et pourquoi il s’est arrêté. 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 provoque l’arrêt bien avant la vérification de la version de format. La correction consiste à utiliser un tag plus récent, choisi et documenté.
Un flag du serveur est renommé ou déprécié. Un flag non reconnu arrête llama-server au démarrage au lieu d’être ignoré ; avec 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 indiquait que --mlock et --mmap étaient dépréciés au profit de -lm, --load-mode. Au 21 octobre 2026, aucun de ces deux flags n’apparaît plus dans la documentation du serveur ni dans la liste des arguments de master. Transposez donc le comportement avec --load-mode, qui accepte auto (la valeur par défaut), none, mmap, mlock, mmap+mlock et dio. Le flag d’offload GPU est documenté sous le nom -ngl, --gpu-layers, --n-gpu-layers ; l’ancienne forme longue reste donc acceptée. Les valeurs par défaut évoluent également : depuis v0.7.0, llama-server écoute par défaut sur le port 9931 au lieu de 8080 (les images Docker conservent le port 8080 à l’intérieur du conteneur). Une unit qui omet --port ne répond donc plus à l’emplacement attendu par votre reverse proxy. La release v1.0.0 supprime également le flag déprécié --defrag-thold. 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 par rapport à cette sortie.
Une option de build est renommée. Les options CMake sont passées du préfixe LLAMA_ au préfixe GGML_, et le fichier racine CMakeLists.txt contient toujours la correspondance. LLAMA_CUBLAS provoque désormais une erreur fatale qui indique GGML_CUDA comme remplacement, tandis que LLAMA_CUDA et LLAMA_METAL affichent un avertissement et sont traduits automatiquement. L’arrêt d’un script de build à l’étape de configuration est le bon résultat. L’échec silencieux est plus problématique : si vous omettez -DGGML_CUDA=ON par erreur, la build réussit, le serveur démarre et tout s’exécute sur le CPU. llama-bench le montre immédiatement, car la colonne backend contient CPU.
La build de l’accélérateur n’est pas portable. Au 19 août 2026, les artefacts Linux associés à un tag de build étaient les variantes CPU, Vulkan, SYCL et OpenVINO, pour x64, arm64 et s390x, sans archive CUDA pour Linux. Cela a changé depuis. Au 21 octobre 2026, b11669, le tag de build derrière v0.7.0, contient également des archives CUDA pour Ubuntu, avec CUDA 12.8 et 13.4 sur x64 et CUDA 13.4 sur arm64. Chaque archive est accompagnée d’une archive runtime cudart- correspondante, ainsi que d’une build ROCm. Sous Linux comme sous Windows, les archives CUDA sont publiées pour chaque version du toolkit. Cela indique que la version du toolkit fait partie des éléments qui identifient votre binaire. Notez-la donc 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:serverdocker 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 : les archives de release précompilées en portent un dans leur nom de fichier (à l’exception des bundles du runtime CUDA pour Windows), et la plupart des rapports de bug en mentionnent un. Un numéro de build est donc le plus facile à comparer avec celui d’un autre administrateur. Les tags de version tels que v0.6.0 constituent une liste plus courte de versions choisies que le projet recommande pour la distribution en aval. Ils conviennent à un serveur que vous ne modifiez que quelques fois par an. Chacun indique le tag de build correspondant ; enregistrez donc les deux. Le plus important est que la chaîne du tag soit enregistrée à côté du fichier du modèle et que la mise à niveau résulte d’une décision, plutôt que d’un effet indirect de git pull.
llama.cpp suit-il désormais le versionnage sémantique ?
Oui, depuis v0.2.0, le 21 août 2026. Les notes de release indiquent que cette version marque le début d’un versionnage sémantique cohérent pour llama.cpp et remplace la mention indiquant que le projet était encore en cours de développement, présente dans v0.1.2. Au 14 novembre 2026, la numérotation des versions a atteint 1.x. La dernière version est v1.0.0, publiée le 13 novembre. Consultez les notes de release avant la mise à niveau et testez le nouveau tag avec votre propre fichier de modèle avant de l’utiliser, quel que soit le chiffre qui a changé.
Comment savoir quel build de llama.cpp mon serveur utilise-t-il ?
llama-server --version affiche la version et les informations de build. Exécutez-le donc avec le binaire utilisé par le service : /opt/llama.cpp/current/bin/llama-server --version. Au 21 octobre 2026, la ligne de démarrage contenant le numéro de build, le hash du commit et le compilateur est journalisée au niveau trace. Ne comptez donc pas la trouver dans journalctl -u llama-server avec le niveau de journalisation par défaut. 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 de chargement juste après une mise à niveau indique une incompatibilité entre le build et le fichier GGUF. Le journal contient une ligne failed to load model, '<path>' qui indique le nom du fichier, puis se termine par exiting due to model loading error. Les lignes précédentes montrent jusqu’où le chargeur a progressé. Lors d’une mise à niveau, un fichier de modèle très récent peut nécessiter un build qui connaît son architecture. Lors d’un retour à une version antérieure, un rollback vers un tag antérieur à celui utilisé pour créer le fichier peut rendre inutilisable un fichier qui fonctionnait la veille. Faites pointer le lien symbolique vers le build précédent, redémarrez, puis vérifiez quel build et quel fichier fonctionnent correctement ensemble avant de décider lequel des deux modifier.
Existe-t-il des binaires Linux précompilés que je peux figer au lieu de compiler ?
Oui. Chaque tag de build est associé à des archives de release portant son nom, comme llama-b10502-bin-ubuntu-x64.tar.gz. Le tag figure donc dans le nom du fichier, ce qui facilite le figement. Le 19 août 2026, les variantes Linux disponibles étaient CPU, arm64, s390x, Vulkan, SYCL et OpenVINO, sans archive CUDA. Au 21 octobre 2026, le nouveau b11669 fournit également des archives Ubuntu CUDA 12.8 et 13.4, avec les bundles du runtime cudart- correspondants. Un serveur NVIDIA utilisant un tag récent n’a donc plus besoin d’être compilé depuis les sources avec -DGGML_CUDA=ON ni d’exécuter une image de conteneur CUDA. Si vous figez un tag de version, téléchargez les archives du tag de build indiqué dans ses notes de release.