Hoe zet u llama.cpp releases vast op uw server?

Wat is er veranderd in de versiebeheer van llama.cpp

Het vastzetten (pinning) van llama.cpp-releases betekent dat u één specifieke tag bouwt en die naam noteert bij het modelbestand. De tag verschuift nooit uit zichzelf, waardoor de server morgen hetzelfde blijft produceren als vandaag. Jarenlang was er slechts één type tag om uit te kiezen: een buildnummer zoals b10502, dat automatisch vanuit de master-branch werd gegenereerd. Sinds 2026 is er een tweede type, een versietag zoals v0.1.2, en beide reeksen worden tegelijkertijd vanuit dezelfde geschiedenis gegenereerd.

De versietags betekenen nog niet wat een versienummer doorgaans inhoudt. De release notes op v0.1.2 vermelden dit in één regel:

Semantisch versiebeheer is nog in ontwikkeling. Meer informatie is te vinden op https://github.com/ggml-org/ggml/discussions/1579

Neem dit letterlijk. De ggml-discussie achter die link is de plek waar het schema nog wordt uitgewerkt, inclusief de frequentie van releases en wat als een patch wordt beschouwd. Een v0.-tag geeft aan dat het project ervoor heeft gekozen om een punt in de geschiedenis te markeren. Het biedt geen garantie dat de volgende versie een veilige vervanger is omdat het laatste cijfer met één is verhoogd.

Het nummer in een build-tag bevat evenmin informatie over de versie. Het is afgeleid van het aantal commits, waardoor het nummer oploopt ongeacht of er iets is veranderd dat relevant is voor uw configuratie. Op 19 augustus 2026 bevatte de voorpagina van de releaselijst negen build-tags, van b10455 tot b10502, met v0.1.2 daartussenin.

Bouw nooit vanaf master op een server die in productie is

git pull gevolgd door een rebuild levert u de code op die in de afgelopen uren is toegevoegd. Dit is acceptabel op een laptop. Op een server ontneemt het u de mogelijkheid om de cruciale vraag te beantwoorden wanneer gedrag verandert: wat draait er nu en wat draaide er vorige week? De tekst die een model genereert en de snelheid waarmee dit gebeurt, veranderen met elke build. Een klacht dat antwoorden afgelopen dinsdag slechter werden, is niet te onderzoeken als de commit van dinsdag nergens is vastgelegd.

Gebruik in plaats daarvan een specifieke tag. Het project maakt deze voor u aan en elk vooraf gebouwd release-archief is vernoemd naar een dergelijke tag.

Aan welke tag moet u llama.cpp releases koppelen?

Koppel een build-tag wanneer u één specifieke, bekende status wilt behouden. Dit is het spoor met de lange historie, het spoor waarnaar de release-archieven zijn vernoemd en het spoor dat in de meeste bugrapporten wordt aangehaald. Een buildnummer is daarom het eenvoudigst te vergelijken met dat van anderen.

Koppel een versie-tag als u liever een kortere lijst met weloverwogen punten volgt. Lees de bijbehorende notities voordat u wijzigingen doorvoert en houd rekening met de bovenstaande kanttekening, aangezien de nummering nog geen contract voor compatibiliteit vormt.

In beide gevallen is de operationele regel identiek. De tag-string staat in een bestand, de box wordt alleen opnieuw gebouwd wanneer die string verandert, en die wijziging is een beslissing die bewust door iemand is genomen.

Bouw de vastgezette tag

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 hoort b10502 te tonen. Een shallow clone op een tag bevat alleen die commit en niets daarna, waardoor niemand deze later per ongeluk kan verplaatsen met een onvoorzichtige git pull. Als de configure-stap stopt vanwege een ontbrekende afhankelijkheid, installeer dan wat wordt aangegeven en voer het commando opnieuw uit.

Bouw met de opties die uw hardware vereist. Alleen CPU:

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

NVIDIA GPU, waarvoor eerst de CUDA toolkit moet zijn geïnstalleerd:

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

OpenBLAS op een systeem met alleen CPU:

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

Binaries worden geplaatst in build/bin, naast de gedeelde bibliotheken die ze laden (libllama.so en de libggml bestanden). Controleer of de build werkt voordat u deze installeert:

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

Installeer de volledige map onder een pad dat vernoemd is naar de tag en laat vervolgens één symlink daarnaar verwijzen:

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

Kopieer de map, niet het losse bestand. Een losse llama-server faalt bij de eerste uitvoering met error while loading shared libraries: libllama.so: cannot open shared object file, omdat de benodigde bibliotheken zich in die map ernaast bevinden.

Laat de service naar de symlink verwijzen, nooit direct naar een tag-map:

[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 volgt de symlink wanneer het proces start, dus het wisselen van builds vereist alleen een nieuw symlink-doel en een sudo systemctl restart llama-server. De rest van het unit-bestand en de reverse proxy ervoor worden behandeld in de volledige handleiding voor een llama.cpp server op een VPS.

Noteer de tag naast het GGUF-bestand en de quant

De build bepaalt voor de helft het resultaat. Het modelbestand vormt de andere helft. GGUF (GGML universal file format) is de container waarin de gewichten worden uitgebracht, en hetzelfde model wordt op vele kwantisatieniveaus gepubliceerd. Twee servers met dezelfde tag kunnen daarom verschillen omdat de een een Q4_K_M-bestand gebruikt en de ander een Q8_0. Bewaar een klein bestand naast het model met alle informatie die nodig is om de configuratie exact te reproduceren:

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>

Haal de commit op met git rev-parse --short HEAD binnen de vastgezette checkout. Haal de checksum op met sha256sum model-q4_k_m.gguf en vergelijk deze bij het downloaden ook met de waarde van de uitgever, omdat het controleren van een download aan de hand van de gepubliceerde checksum een afgebroken bestand opmerkt voordat dit leidt tot een verwarrende bug. In hoeverre het kwantisatieniveau zelf de antwoorden beïnvloedt is een aparte vraag, en wat elk kwantisatieniveau u kost behandelt dit onderwerp.

Hoe voert u een upgrade uit zonder de server te verstoren?

Voer de upgrade uit als een oefening. Bouw de nieuwe tag naast de oude, meet beide en behoud de oude totdat de nieuwe naar behoren functioneert.

1. Kloon de nieuwe tag naar een eigen map. Gebruik de oude checkout niet opnieuw.
2. Bouw deze met dezelfde cmake-argumenten als vastgelegd in het manifest.
3. Voer llama-bench uit op beide builds met hetzelfde modelbestand, met dezelfde promptlengte en hetzelfde aantal herhalingen.
4. Stuur een prompt waarvan u het antwoord goed kent door beide servers en lees de twee antwoorden.
5. Verplaats de symlink, herstart de service en laat de oude map op de schijf staan.

/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 print één rij per test, met een backend-kolom, een ngl-kolom en een kolom voor tokens per seconde inclusief de standaardafwijking. Vergelijk dezelfde rij tussen de twee builds, niet de prompt-rij van de ene build met de generatie-rij van de andere. Een cijfer dat bij een andere promptlengte is verkregen, is een andere meting; daarom is tokens per seconde telkens op dezelfde manier meten belangrijker dan het getal zelf.

Terugdraaien bestaat uit twee commando's en werkt alleen omdat de oude map nog aanwezig is:

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

Bewaar ten minste de vorige build. Dit kost slechts een fractie van de schijfruimte die het modelbestand ernaast al in beslag neemt.

Wat er kapot gaat bij upgrades van llama.cpp

Een modelbestand laadt niet meer. Dit is meestal de reden waarom mensen upgraden: een nieuw gepubliceerd model gebruikt een architectuur die de vastgezette build niet kent, waardoor het niet laadt. llama-server sluit af tijdens het opstarten en het logboek bevat een failed to load model from /srv/models/model-q4_k_m.gguf-regel. Lees de regels die vlak daarvoor worden afgedrukt; deze tonen hoe ver het laadproces is gekomen. GGUF bevat ook een formaatversie in de header (de huidige waarde van de specificatie is 3, en versie 2 breidde de lengtevelden uit van 32 naar 64 bits), hoewel in de praktijk een onbekende architectuurnaam u al lang voor de formaatversie tegenhoudt. De oplossing is een nieuwere tag, die u kiest en noteert.

Een server-flag is hernoemd of verouderd. Een onbekende flag zorgt ervoor dat llama-server stopt bij het opstarten in plaats van dat deze wordt genegeerd. Onder systemd ziet dit eruit als een service die in een lus opstart en weer afsluit. journalctl -u llama-server -n 50 toont de werkelijke melding. Sinds 19 augustus 2026 markeert de serverdocumentatie --mlock en --mmap als verouderd ten gunste van -lm, --load-mode, die waarden accepteert zoals auto, mmap, mlock en dio. De GPU-offload-flag is gedocumenteerd als -ngl, --gpu-layers, terwijl oudere handleidingen --n-gpu-layers gebruiken. Voordat u de symlink verplaatst, voert u /opt/llama.cpp/<new tag>/bin/llama-server --help uit en controleert u elke flag in uw unit-bestand hiertegen.

Een build-optie is hernoemd. De CMake-opties zijn verplaatst van een LLAMA_-prefix naar een GGML_-prefix, en de root CMakeLists.txt bevat nog steeds de mapping. LLAMA_CUBLAS is nu een fatale fout die GGML_CUDA als vervanging noemt, terwijl LLAMA_CUDA en LLAMA_METAL een waarschuwing geven en voor u worden vertaald. Een build-script dat stopt bij de configuratiestap is het gunstige resultaat. De stille fout is erger: laat per ongeluk -DGGML_CUDA=ON weg en de build slaagt, de server start, en alles draait op de CPU. llama-bench toont dit direct, omdat de backend-kolom CPU aangeeft.

De accelerator-build is niet portable. Sinds 19 augustus 2026 zijn de Linux-assets die aan een build-tag zijn gekoppeld de CPU-, Vulkan-, SYCL- en OpenVINO-varianten, voor x64, arm64 en s390x. Er is geen CUDA-archief voor Linux in die lijst, dus een NVIDIA-server betekent bouwen vanuit de broncode of een container-image draaien. De Windows CUDA-archieven worden per toolkit-versie gepubliceerd, wat een nuttige aanwijzing is: de toolkit-versie is onderdeel van wat uw binaire bestand identificeert, dus noteer deze samen met de cmake-argumenten.

De container image vastzetten in plaats daarvan

Dezelfde regel geldt, maar dan voor een ander object. De gepubliceerde images (ghcr.io/ggml-org/llama.cpp:server en de bijbehorende accelerator-varianten) veranderen van inhoud, waardoor het ophalen van :server volgende maand een ander programma onder hetzelfde label oplevert. Haal de image één keer op en lees de digest uit:

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

docker pull toont een Digest: sha256:...-regel. Plaats deze digest in het compose-bestand in plaats van de tag; de image kan dan niet meer veranderen wanneer iemand de volgende keer docker compose pull uitvoert. Bewaar de vorige digest in een commentaar, zodat een rollback slechts één aanpassing vereist, op dezelfde manier als de upgrade- en rollback-procedure voor een Compose-stack elke andere service behandelt.

Het nut van een pin

Met een pin kunt u exact vastleggen wat er draait. Als een wijziging problemen veroorzaakt, kunt u binnen een minuut de vorige build terugzetten. llama.cpp vereist dat u hiervoor twee zaken bijhoudt: de build-tag en het modelbestand, omdat deze afzonderlijk worden aangeleverd. Runtimes die deze bundelen, werken anders, en de vergelijking tussen Ollama en llama.cpp als servers behandelt dit verschil: één versienummer voor het geheel is eenvoudiger te registreren en te beheren.

FAQ

Moet ik de bNNNN build-tag of de v0.x-tag vastzetten?

Beide opties werken, zolang u maar een versie vastzet. Build-tags zoals b10502 vormen het langlopende traject: elk vooraf gecompileerd release-archief is ernaar vernoemd en de meeste bugrapporten vermelden er een, waardoor een buildnummer het makkelijkst te vergelijken is met dat van een andere operator. Versietags zoals v0.1.2 zijn een kortere lijst van bewuste mijlpalen, wat geschikt is voor een server die u slechts enkele keren per jaar beheert. Wat belangrijker is dan de keuze, is dat de tag-string wordt vastgelegd naast het modelbestand en dat upgraden een bewuste beslissing is in plaats van een bijwerking van git pull.

Volgt llama.cpp nu semantische versiebeheer?

Nog niet, volgens de eigen verklaring van het project. De v0.1.2 release notes vermelden dat semantische versiebeheer nog in ontwikkeling is en verwijzen naar een ggml-discussie waar het schema wordt uitgewerkt, inclusief de releasefrequentie en wat als een patch wordt beschouwd. Beschouw een versietag als een punt dat de beheerders hebben gekozen om te markeren. Ga er niet vanuit dat een wijziging in het laatste cijfer een gegarandeerde drop-in upgrade is, en test de nieuwe tag met uw eigen modelbestand voordat u overschakelt.

Hoe zie ik welke llama.cpp-build mijn server draait?

llama-server --version toont de versie- en buildinformatie. Het opstartlogboek begint ook met een build-regel die het buildnummer, de commit-hash en de gebruikte compiler bevat, dus journalctl -u llama-server vindt dit voor een draaiende service. Bij een installatie vanuit de broncode toont git describe --tags in de vastgezette checkout de tag, en readlink /opt/llama.cpp/current laat zien naar welke map de service daadwerkelijk verwijst.

Waarom laadt mijn model niet meer na het upgraden van llama.cpp?

Een laadfout direct na een upgrade duidt op een mismatch tussen de build en het GGUF-bestand. Het logboek eindigt met een failed to load model from-regel die het pad benoemt, en de regels daarboven tonen hoe ver de loader is gekomen. Bij vooruitgang heeft een zeer nieuw modelbestand een build nodig die de architectuur ondersteunt. Bij teruggang kan een rollback naar een versie lager dan de tag waarvoor het bestand is gemaakt, een bestand dat gisteren nog werkte, onbruikbaar maken. Laat de symlink naar de vorige build wijzen, herstart en bevestig welke build en welk bestand correct samenwerken voordat u beslist welke van de twee u wijzigt.

Zijn er vooraf gecompileerde Linux-binaries die ik kan vastzetten in plaats van zelf te compileren?

Ja, voor sommige configuraties. Elke build-tag bevat release-archieven die ernaar zijn vernoemd, zoals llama-b10502-bin-ubuntu-x64.tar.gz, met daarnaast arm64-, s390x-, Vulkan-, SYCL- en OpenVINO-varianten per 19 augustus 2026. De naamgeving maakt vastzetten eenvoudig, aangezien de tag in de bestandsnaam staat. Er was geen CUDA-archief voor Linux in die lijst, dus voor een NVIDIA-server betekent dit nog steeds compileren vanuit de broncode met -DGGML_CUDA=ON of het draaien van een van de CUDA-containerimages.