Come fissare una release di llama.cpp sul server

Cosa è cambiato nella gestione delle versioni di llama.cpp

Bloccare una release di llama.cpp significa compilare un tag specifico e registrare quel nome accanto al file del modello. Il tag non cambia autonomamente, quindi il server continua a produrre domani lo stesso risultato prodotto oggi. Per anni era disponibile un solo tipo di tag: un numero di build come b10502, creato automaticamente a partire da master. Dal 2026 esiste un secondo tipo, un tag di versione come v0.1.2, ed entrambi i rami vengono creati nello stesso momento a partire dalla stessa cronologia.

I tag di versione non hanno ancora il significato normalmente associato a un numero di versione. Le note di rilascio su v0.1.2 lo dichiarano in una riga:

La gestione delle versioni semantiche è ancora in corso. Maggiori informazioni sono disponibili in https://github.com/ggml-org/ggml/discussions/1579

Consideralo nel senso letterale. La discussione di ggml alla base di quel link è il luogo in cui lo schema viene ancora definito, compresi la frequenza delle release e i criteri per considerare una modifica una patch. Un tag v0. indica che il progetto ha scelto di contrassegnare un punto della cronologia. Non garantisce che la release successiva sia un aggiornamento sostituibile senza modifiche solo perché l'ultima cifra è aumentata di uno.

Anche il numero in un tag di build non ha un significato di versione. Deriva dal conteggio dei commit, quindi aumenta autonomamente indipendentemente dal fatto che sia cambiato qualcosa di rilevante per la tua configurazione. Al 19 agosto 2026, la pagina iniziale dell'elenco delle release conteneva nove tag di build, da b10455 a b10502, con v0.1.2 tra questi.

Non eseguire mai una build dal branch master su un server che gestisce servizi

git pull seguito da una nuova build ti fornisce tutto ciò che è stato aggiunto nelle ultime ore. Su un laptop può andare bene. Su un server elimina la possibilità di rispondere alla domanda più importante quando il comportamento cambia: che cosa è in esecuzione ora e che cosa era in esecuzione la settimana scorsa. Sia il testo generato dal modello sia la velocità con cui viene generato cambiano in base alla build. Se qualcuno segnala che martedì le risposte sono peggiorate, non è possibile individuare la causa se il commit di martedì non è mai stato registrato.

Usa invece un tag specifico. Il progetto li crea per te e ogni archivio di release precompilato ha il nome corrispondente a uno di questi tag.

A quale tag devi bloccare le release di llama.cpp?

Blocca un build tag quando vuoi usare uno specifico stato noto. È la linea con la cronologia più lunga, quella a cui fanno riferimento gli archivi delle release e che viene citata nella maggior parte delle segnalazioni di bug. Per questo, un numero di build è il riferimento più semplice da confrontare con quello di un altro sistema.

Blocca un version tag se preferisci seguire un elenco più breve di punti definiti intenzionalmente. Leggi le relative note prima di procedere e tieni presente l'avvertenza precedente, perché la numerazione non costituisce ancora un contratto di compatibilità.

In entrambi i casi, la regola operativa è la stessa. La stringa del tag è memorizzata in un file, il sistema viene ricreato soltanto quando quella stringa cambia e la modifica deve essere una decisione intenzionale.

Compilare il tag fissato

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 dovrebbe stampare b10502. Un clone superficiale eseguito su un tag contiene quel commit e nessun commit successivo, quindi in seguito nessuno può spostarlo accidentalmente con un semplice git pull. Se il passaggio di configurazione si interrompe perché manca una dipendenza, installate il pacchetto indicato ed eseguitelo di nuovo.

Compilate con le opzioni richieste dall'hardware. Solo CPU:

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

GPU NVIDIA, con il toolkit CUDA installato in precedenza:

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

OpenBLAS su un sistema con sola CPU:

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

I binari vengono inseriti in build/bin, accanto alle librerie condivise che caricano (libllama.so e i file libggml). Verificate che la compilazione funzioni prima di installarla:

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

Installate l'intera directory in un percorso denominato in base al tag, quindi puntate un symlink a quella directory:

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

Copiate la directory, non il singolo file. Un llama-server isolato non riesce alla prima esecuzione con error while loading shared libraries: libllama.so: cannot open shared object file, perché le librerie necessarie si trovano nella stessa directory.

Configurate il servizio in modo che punti al symlink, mai a una directory del 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 risolve il symlink quando avvia il processo, quindi per cambiare compilazione basta modificare la destinazione del symlink ed eseguire sudo systemctl restart llama-server. Il resto del file dell'unità e del reverse proxy che lo precede sono descritti nella guida completa per un server llama.cpp su un VPS.

Registra il tag accanto al file GGUF e alla quantizzazione

La build determina solo in parte l’output. L’altra parte è il file del modello. GGUF (GGML universal file format) è il contenitore in cui vengono distribuiti i pesi, e lo stesso modello viene pubblicato a molti livelli di quantizzazione. Di conseguenza, due server con lo stesso tag possono comunque produrre risultati diversi se uno contiene un file Q4_K_M e l’altro un file Q8_0. Conserva accanto al modello un piccolo file con tutte le informazioni necessarie per ricreare esattamente la configurazione:

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>

Recupera il commit con git rev-parse --short HEAD all’interno del checkout bloccato. Calcola il checksum con sha256sum model-q4_k_m.gguf e confrontalo anche con il valore pubblicato dal fornitore al momento del download, perché verificare un download rispetto al checksum pubblicato consente di rilevare un file troncato prima che si trasformi in un problema difficile da diagnosticare. Quanto il livello di quantizzazione modifichi le risposte è una questione distinta, descritta in quale costo comporta ogni livello di quantizzazione.

Come aggiornare senza compromettere il server?

Eseguire l’aggiornamento come una prova operativa. Compilare il nuovo tag accanto a quello precedente, misurare entrambi e conservare il precedente finché il nuovo non ha dimostrato di funzionare correttamente.

1. Clonare il nuovo tag in una directory dedicata. Non riutilizzare il checkout precedente.
2. Compilarlo usando gli stessi argomenti cmake registrati nel manifest.
3. Eseguire llama-bench su entrambe le build usando lo stesso file del modello, la stessa lunghezza del prompt e lo stesso numero di ripetizioni.
4. Inviare a entrambi i server un prompt con una risposta già nota e leggere le due risposte.
5. Spostare il link simbolico, riavviare il servizio e lasciare la directory precedente sul disco.

/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 stampa una riga per ogni test, con una colonna backend, una colonna ngl e una colonna di token al secondo con la relativa deviazione standard. Confrontare la stessa riga tra le due build, non la riga del prompt di una build con la riga della generazione dell’altra. Un valore ottenuto con una lunghezza del prompt diversa è una misurazione diversa. Per questo misurare i token al secondo sempre nello stesso modo è più importante del valore in sé.

Il rollback richiede due comandi e funziona soltanto perché la directory precedente è ancora presente:

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

Conservare almeno la build precedente. Occupa una frazione dello spazio su disco già utilizzato dal file del modello che la accompagna.

Cosa si rompe tra gli aggiornamenti di llama.cpp

Un file del modello smette di essere caricato. Di solito è questo il motivo per cui si esegue l'aggiornamento: un modello pubblicato di recente usa un'architettura che la build fissata non conosce, quindi non viene mai caricato. llama-server termina durante l'avvio e nel log compare una riga failed to load model from /srv/models/model-q4_k_m.gguf. Leggere le righe stampate subito prima: mostrano fino a quale punto è arrivato il caricatore. GGUF include anche una versione del formato nell'header (il valore corrente nella specifica è 3 e la versione 2 ha esteso i campi di lunghezza da 32 a 64 bit), ma nella pratica il caricatore si arresta per un nome di architettura sconosciuto molto prima di verificare la versione del formato. La correzione consiste nell'usare un tag più recente, scelto e documentato.

Un flag del server viene rinominato o deprecato. Un flag non riconosciuto arresta llama-server all'avvio invece di essere ignorato; con systemd questo appare come un servizio che si avvia e termina in un ciclo continuo. journalctl -u llama-server -n 50 mostra il messaggio effettivo. Al 19 agosto 2026 la documentazione del server indica --mlock e --mmap come deprecati a favore di -lm, --load-mode, che accetta valori come auto, mmap, mlock e dio. Il flag per l'offload sulla GPU è documentato come -ngl, --gpu-layers, mentre nelle guide meno recenti è indicato come --n-gpu-layers. Prima di spostare il symlink, eseguire /opt/llama.cpp/<new tag>/bin/llama-server --help e verificare ogni flag nel file dell'unità rispetto all'output.

Un'opzione di build viene rinominata. Le opzioni CMake sono passate dal prefisso LLAMA_ al prefisso GGML_ e il file root CMakeLists.txt contiene ancora la mappatura. LLAMA_CUBLAS ora genera un errore irreversibile che indica GGML_CUDA come sostituzione, mentre LLAMA_CUDA e LLAMA_METAL generano un avviso e vengono convertiti automaticamente. Uno script di build che si arresta durante il passaggio di configurazione produce il risultato corretto. Il problema più grave è un errore silenzioso: se si omette accidentalmente -DGGML_CUDA=ON, la build termina correttamente, il server si avvia e tutto viene eseguito sulla CPU. llama-bench lo mostra immediatamente, perché la colonna backend contiene CPU.

La build per l'acceleratore non è portabile. Al 19 agosto 2026, gli asset Linux associati a un tag di build sono le varianti CPU, Vulkan, SYCL e OpenVINO per x64, arm64 e s390x. In quell'elenco non esiste un archivio CUDA per Linux; su un server NVIDIA è quindi necessario compilare dai sorgenti oppure eseguire un'immagine container. Gli archivi CUDA per Windows vengono pubblicati per versione del toolkit. Questo fornisce un'indicazione utile: la versione del toolkit contribuisce a identificare il binario, quindi va registrata insieme agli argomenti cmake.

Bloccare invece l'immagine del container

Stessa regola, nome diverso. Le immagini pubblicate (ghcr.io/ggml-org/llama.cpp:server e le relative varianti con acceleratore) hanno nomi mobili, quindi eseguendo il pull di :server il mese prossimo si otterrà un programma diverso con la stessa etichetta. Eseguire il pull una volta e leggere il digest:

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

docker pull stampa una riga Digest: sha256:.... Inserire quel digest nel file Compose al posto del tag: l'immagine non potrà cambiare senza preavviso la prossima volta che qualcuno esegue docker compose pull. Conservare il digest precedente in un commento, così un rollback richiede una sola modifica, come nella procedura di aggiornamento e rollback per uno stack Compose, che applica lo stesso approccio a ogni altro servizio.

Il significato del pin

Un pin consente di indicare con precisione che cosa è in esecuzione e di ripristinare la build precedente in meno di un minuto quando una modifica causa problemi. Per farlo, llama.cpp richiede di tracciare due elementi: il tag della build e il file del modello, perché li fornisce separatamente. I runtime che li includono in un unico pacchetto funzionano in modo diverso; il confronto tra Ollama e llama.cpp come server analizza questo compromesso: un unico numero di versione per l'intero insieme è più semplice da registrare e da controllare.

FAQ

Devo fissare il tag di build bNNNN o il tag v0.x?

Entrambe le opzioni sono valide, purché venga fissato un riferimento. I tag di build come b10502 rappresentano il ramo seguito nel tempo: ogni archivio di release precompilato usa uno di questi nomi e molti report di bug ne citano uno. Per questo, il numero di build è il riferimento più semplice da confrontare con quello usato da un altro amministratore. I tag di versione come v0.1.2 costituiscono invece un elenco più breve di punti scelti intenzionalmente, adatto a un server che viene aggiornato alcune volte all'anno. La scelta conta meno del fatto che la stringa del tag sia registrata accanto al file del modello e che l'aggiornamento sia una decisione, non un effetto collaterale di git pull.

llama.cpp segue ora il versionamento semantico?

Non ancora, secondo quanto dichiarato dal progetto. Le note di release v0.1.2 indicano che il versionamento semantico è ancora in fase di definizione e rimandano a una discussione su ggml in cui vengono elaborati lo schema, la cadenza delle release e i criteri per definire una patch. Considera un tag di versione come un punto scelto dai manutentori. Non presumere che una modifica dell'ultima cifra garantisca un aggiornamento compatibile senza modifiche e verifica il nuovo tag con il tuo file del modello prima di adottarlo.

Come posso sapere quale build di llama.cpp è in esecuzione sul server?

llama-server --version stampa la versione e le informazioni sulla build. Anche il log di avvio inizia con una riga build che contiene il numero di build, l'hash del commit e il compilatore utilizzato; journalctl -u llama-server consente quindi di trovarla per un servizio in esecuzione. In un'installazione dal codice sorgente, git describe --tags eseguito all'interno del checkout fissato stampa il tag, mentre readlink /opt/llama.cpp/current mostra a quale directory punta effettivamente il servizio.

Perché il modello ha smesso di essere caricato dopo l'aggiornamento di llama.cpp?

Un errore di caricamento subito dopo un aggiornamento indica una mancata corrispondenza tra la build e il file GGUF. Il log termina con una riga failed to load model from che indica il percorso; le righe precedenti mostrano fino a quale punto è arrivato il caricatore. Procedendo verso una build più recente, un file di modello molto nuovo richiede una build che ne conosca l'architettura. Tornando a una build precedente, un rollback a un tag antecedente a quello con cui è stato creato il file può impedire il caricamento di un file che funzionava il giorno prima. Punta il link simbolico alla build precedente, riavvia il servizio e verifica quale combinazione di build e file funziona correttamente prima di decidere quale dei due modificare.

Esistono binari Linux precompilati che posso fissare invece di compilare?

Sì, per alcune configurazioni. Ogni tag di build include archivi di release con quel nome, come llama-b10502-bin-ubuntu-x64.tar.gz, insieme alle varianti arm64, s390x, Vulkan, SYCL e OpenVINO disponibili al 19 agosto 2026. La convenzione di denominazione semplifica il pinning, perché il tag è incluso nel nome del file. In quell'elenco non era presente alcun archivio CUDA per Linux. Su un server NVIDIA è quindi ancora necessario compilare dal codice sorgente con -DGGML_CUDA=ON oppure eseguire una delle immagini container CUDA.