Como fixar versões do llama.cpp no servidor

O que mudou no versionamento do llama.cpp

Fixar releases do llama.cpp significa compilar uma tag nomeada e registar esse nome junto do ficheiro do modelo. A tag não muda sozinha, por isso o servidor continua a produzir amanhã o mesmo que produziu hoje. Durante anos, só existia um tipo de tag à escolha: um número de build, como b10502, criado automaticamente a partir de master. Desde 2026, existe um segundo tipo, uma tag de versão como v0.1.2, e ambas as linhas são criadas ao mesmo tempo a partir do mesmo histórico.

As tags de versão ainda não significam o que um número de versão normalmente significa. As notas da release em v0.1.2 dizem isso numa linha:

O versionamento semântico ainda está em desenvolvimento. Há mais informações em https://github.com/ggml-org/ggml/discussions/1579

Considere essa afirmação literalmente. A discussão do ggml por trás dessa ligação é onde o esquema ainda está a ser definido, incluindo a frequência das releases e o que conta como um patch. Uma tag v0. indica que o projeto decidiu assinalar um ponto no histórico. Não garante que a próxima seja uma substituição direta segura só porque o último dígito aumentou uma unidade.

O número numa tag de build também não tem significado de versão. Ele vem da contagem de commits, por isso aumenta sozinho, independentemente de ter mudado alguma coisa relevante para a sua configuração. Em 19 August 2026, a página inicial da lista de releases tinha nove tags de build, de b10455 a b10502, com v0.1.2 entre elas.

Nunca faça builds a partir de master num servidor que disponibiliza qualquer serviço

git pull seguido de um novo build fornece tudo o que entrou nas últimas horas. Isso é aceitável num portátil. Num servidor, elimina a capacidade de responder à pergunta importante quando o comportamento muda: o que está a correr agora e o que estava a correr na semana passada. O texto produzido por um modelo e a velocidade de produção também variam com o build. Uma reclamação de que as respostas pioraram na última terça-feira não pode ser investigada se o commit de terça-feira nunca foi registado.

Em vez disso, fixe uma tag. O projeto cria as tags, e cada arquivo de release pré-compilado recebe o nome de uma delas.

A que tag deve fixar as releases do llama.cpp?

Fixe uma tag de build quando precisar de um estado específico e conhecido. Esta é a linha com o histórico mais longo, a linha usada nos nomes dos arquivos de release e aquela que aparece na maioria dos relatórios de bugs. Por isso, um número de build é a forma mais fácil de comparar o estado com o de outra pessoa.

Fixe uma tag de versão se preferir seguir uma lista mais curta de pontos definidos deliberadamente. Leia as notas antes de atualizar e tenha em mente a ressalva acima, porque a numeração ainda não é um contrato de compatibilidade.

Em qualquer dos casos, a regra operacional é a mesma. A string da tag fica num arquivo. O servidor só é reconstruído quando essa string muda. A alteração é uma decisão tomada deliberadamente.

Compile a tag fixada

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 deve imprimir b10502. Um clone superficial num tag contém esse commit e nada posterior. Assim, ninguém o pode mover mais tarde com um git pull executado por engano. Se a etapa de configuração parar por falta de uma dependência, instale o pacote indicado e execute-a novamente.

Compile com as opções adequadas ao seu hardware. Apenas CPU:

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

GPU NVIDIA, que requer o CUDA toolkit instalado primeiro:

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

OpenBLAS numa máquina apenas com CPU:

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

Os binários ficam em build/bin, junto das bibliotecas partilhadas que carregam (libllama.so e os ficheiros libggml). Confirme que a compilação funciona antes de a instalar:

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

Copie o diretório completo para um caminho com o nome do tag e aponte um único symlink para esse diretório:

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

Copie o diretório, não apenas o ficheiro. Um llama-server isolado falha na primeira execução com error while loading shared libraries: libllama.so: cannot open shared object file, porque as bibliotecas de que precisa estão no mesmo diretório.

Aponte o serviço para o symlink, nunca para um diretório 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

O systemd resolve o symlink quando inicia o processo. Para mudar de compilação, basta alterar o destino do symlink e executar sudo systemctl restart llama-server. O restante do ficheiro da unidade e o reverse proxy à sua frente são explicados em o guia completo para um servidor llama.cpp numa VPS.

Registe a tag junto do ficheiro GGUF e a quantização

A compilação é apenas metade do que determina o resultado. A outra metade é o ficheiro do modelo. GGUF (GGML universal file format) é o contentor onde os pesos são distribuídos, e o mesmo modelo é publicado com vários níveis de quantização. Por isso, dois servidores com a mesma tag ainda podem produzir resultados diferentes se um tiver um ficheiro Q4_K_M e o outro um Q8_0. Mantenha um ficheiro pequeno junto do modelo com tudo o que é necessário para reconstruir exatamente a configuração:

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>

Obtenha o commit com git rev-parse --short HEAD dentro do checkout fixado. Obtenha o checksum com sha256sum model-q4_k_m.gguf e compare-o também com o valor publicado pelo fornecedor no momento da transferência, porque verificar uma transferência contra o checksum publicado deteta um ficheiro truncado antes de este causar um problema difícil de diagnosticar. O impacto do próprio nível de quantização nas respostas é uma questão separada, e o custo de cada nível de quantização explica esse impacto.

Como fazer uma atualização sem avariar o servidor?

Execute a atualização como um ensaio. Compile a nova tag ao lado da antiga, meça ambas e mantenha a antiga até a nova demonstrar que funciona melhor.

1. Clone a nova tag no seu próprio diretório. Não reutilize o checkout antigo.
2. Compile-a com os mesmos argumentos do cmake registados no manifesto.
3. Execute llama-bench em ambas as compilações, usando o mesmo ficheiro de modelo, o mesmo comprimento do prompt e o mesmo número de repetições.
4. Envie para ambos os servidores um prompt cuja resposta conheça bem e leia as duas respostas.
5. Mova o symlink, reinicie o serviço e mantenha o diretório antigo no 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 imprime uma linha por teste, com uma coluna backend, uma coluna ngl e uma coluna de tokens por segundo com o respetivo desvio padrão. Compare a mesma linha entre as duas compilações, não a linha do prompt de uma compilação com a linha de geração da outra. Um valor obtido com um comprimento de prompt diferente é uma medição diferente. Por isso, medir os tokens por segundo sempre da mesma forma é mais importante do que o próprio número.

A reversão requer dois comandos e só funciona porque o diretório antigo continua disponível:

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

Mantenha pelo menos a compilação anterior. Ela ocupa uma fração do espaço em disco que o ficheiro de modelo ao lado dela já utiliza.

O que quebra entre atualizações do llama.cpp

Um ficheiro de modelo deixa de carregar. Normalmente, é isto que leva alguém a atualizar: um modelo publicado recentemente usa uma arquitetura que a compilação fixada não conhece, por isso nunca chega a carregar. llama-server termina durante o arranque e o log contém uma linha failed to load model from /srv/models/model-q4_k_m.gguf. Leia as linhas apresentadas imediatamente antes. Elas mostram até onde o carregador chegou. O GGUF também inclui uma versão do formato no cabeçalho (o valor atual da especificação é 3, e a versão 2 aumentou de 32 para 64 bits o tamanho dos campos), embora, na prática, um nome de arquitetura desconhecido interrompa o processo muito antes de a versão do formato ser verificada. A correção é escolher uma tag mais recente e registá-la.

Uma flag do servidor é renomeada ou descontinuada. Uma flag não reconhecida faz com que llama-server termine durante o arranque, em vez de ser ignorada. Com systemd, isto aparece como um serviço que inicia e termina repetidamente. journalctl -u llama-server -n 50 apresenta a mensagem real. Em 19 August 2026, a documentação do servidor marca --mlock e --mmap como descontinuadas em favor de -lm, --load-mode, que aceita valores como auto, mmap, mlock e dio. A flag de descarga para a GPU está documentada como -ngl, --gpu-layers, enquanto guias mais antigos usam --n-gpu-layers. Antes de mover o symlink, execute /opt/llama.cpp/<new tag>/bin/llama-server --help e confirme todas as flags do ficheiro da unidade.

Uma opção de compilação é renomeada. As opções do CMake passaram de um prefixo LLAMA_ para um prefixo GGML_, e o CMakeLists.txt na raiz ainda contém o mapeamento. LLAMA_CUBLAS é agora um erro fatal que indica GGML_CUDA como substituição, enquanto LLAMA_CUDA e LLAMA_METAL geram um aviso e são convertidas automaticamente. Um script de compilação que para na fase de configuração tem um comportamento adequado. A falha silenciosa é pior: se omitir -DGGML_CUDA=ON por engano, a compilação termina com sucesso, o servidor inicia e tudo é executado na CPU. llama-bench mostra isso imediatamente, porque a coluna backend apresenta CPU.

A compilação para o acelerador não é portável. Em 19 August 2026, os assets Linux associados a uma tag de compilação são as variantes CPU, Vulkan, SYCL e OpenVINO, para x64, arm64 e s390x. Não existe um arquivo CUDA para Linux nessa lista. Portanto, um servidor NVIDIA exige uma compilação a partir do código-fonte ou a execução de uma imagem de contentor. Os arquivos CUDA para Windows são publicados por versão do toolkit. Isto fornece uma indicação útil: a versão do toolkit faz parte da identificação do binário. Registe-a juntamente com os argumentos do cmake.

Fixar a imagem do contentor

A mesma regra, com outro nome. As imagens publicadas (ghcr.io/ggml-org/llama.cpp:server e as suas variantes para aceleradores) usam nomes móveis, por isso obter :server no próximo mês fornece um programa diferente sob a mesma etiqueta. Faça o pull uma vez e leia o digest:

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

docker pull imprime uma linha Digest: sha256:.... Coloque esse digest no ficheiro compose em vez da tag. Assim, a imagem não pode mudar sem aviso quando alguém executar docker compose pull novamente. Mantenha o digest anterior num comentário para que um rollback exija apenas uma edição, tal como a rotina de atualização e rollback de uma stack Compose trata qualquer outro serviço.

O objetivo de fixar versões

Uma fixação permite indicar exatamente o que está em execução e repor a compilação anterior em menos de um minuto quando uma alteração piora o funcionamento. O llama.cpp exige que registe duas coisas para isso: a etiqueta da compilação e o ficheiro do modelo, porque fornece ambos separadamente. Os runtimes que os agrupam funcionam de forma diferente, e a comparação entre Ollama e llama.cpp como servidores aborda essa diferença: um único número de versão para todo o conjunto é mais fácil de registar e oferece menos controlo.

FAQ

Devo fixar a tag de build bNNNN ou a tag v0.x?

Ambas funcionam, desde que fixe uma tag. Tags de build como b10502 correspondem ao ciclo de manutenção contínua: cada arquivo de release pré-compilado recebe esse nome e a maioria dos relatórios de bugs menciona uma delas. Por isso, o número da build é a forma mais simples de comparar a instalação com a de outro operador. Tags de versão como v0.1.2 formam uma lista mais curta de pontos escolhidos deliberadamente. Isto é adequado para um servidor que só é alterado algumas vezes por ano. Mais importante do que a escolha é registar a string da tag junto ao ficheiro do modelo e garantir que uma atualização é uma decisão, não um efeito secundário de git pull.

O llama.cpp já segue o versionamento semântico?

Ainda não, segundo a própria declaração do projeto. As notas de release de v0.1.2 dizem que o versionamento semântico ainda está em desenvolvimento e apontam para uma discussão no ggml onde o esquema está a ser definido, incluindo a cadência de releases e o que conta como patch. Interprete uma tag de versão como um ponto que os maintainers escolheram marcar. Não assuma que uma alteração no último dígito garante uma atualização compatível sem alterações. Teste a nova tag com o seu próprio ficheiro de modelo antes de mudar para ela.

Como identifico qual build do llama.cpp o meu servidor está a executar?

llama-server --version mostra a versão e as informações da build. O log de arranque também começa com uma linha build que contém o número da build, o hash do commit e o compilador utilizado. Assim, journalctl -u llama-server encontra essa informação num serviço em execução. Numa instalação a partir do código-fonte, git describe --tags dentro do checkout fixado mostra a tag, e readlink /opt/llama.cpp/current mostra para que diretório o serviço está efetivamente apontado.

Por que motivo o meu modelo deixou de carregar depois de atualizar o llama.cpp?

Uma falha de carregamento logo após uma atualização indica uma incompatibilidade entre a build e o ficheiro GGUF. O log termina com uma linha failed to load model from que indica o caminho, e as linhas anteriores mostram até que ponto o carregador conseguiu ler o ficheiro. Ao avançar para uma versão mais recente, um ficheiro de modelo muito novo precisa de uma build que conheça a sua arquitetura. Ao recuar para uma versão anterior, um rollback para uma tag anterior àquela para a qual o ficheiro foi criado pode impedir o carregamento de um ficheiro que funcionava no dia anterior. Aponte o symlink para a build anterior, reinicie e confirme qual build e qual ficheiro foram emparelhados corretamente antes de decidir qual dos dois deve alterar.

Existem binários Linux pré-compilados que possa fixar em vez de compilar?

Sim, para algumas configurações. Cada tag de build inclui arquivos de release com o respetivo nome, como llama-b10502-bin-ubuntu-x64.tar.gz, além de variantes arm64, s390x, Vulkan, SYCL e OpenVINO, em 19 August 2026. Esta nomenclatura facilita a fixação, porque a tag aparece no nome do ficheiro. Não havia um arquivo CUDA para Linux nessa lista. Portanto, num servidor NVIDIA, continua a ser necessário compilar a partir do código-fonte com -DGGML_CUDA=ON ou executar uma das imagens de contentor CUDA.