llama.cpp 1.0.0: mudanças de API, cache FP8 e segurança

Atualize o llama.cpp e o ggml para 1.0.0 sem interromper seus agentes de programação locais. Remova funções C e parâmetros de desfragmentação obsoletos, compare o consumo de memória do cache KV FP8, ajuste o cache de especialistas MoE e confira os controles de acesso a ferramentas e URLs privadas no llama-server. Entenda também como fixar versões e quando usuários do Ollama e LM Studio precisam agir.

Conteúdo
llama.cpp 1.0.0: mudanças de API, cache FP8 e segurança

Antes de atualizar para o llama.cpp 1.0.0, revise seus bindings de C, os parâmetros de inicialização e as configurações de segurança do llama-server. A versão lançada em 13 de novembro de 2026 remove APIs obsoletas, adiciona o cache KV FP8 e inclui novos controles para o cache de especialistas MoE. Se você usa um modelo local como backend de um agente de programação, atualize primeiro um servidor de testes e verifique tanto as respostas comuns quanto as chamadas de ferramentas.

O lançamento também estabelece uma política de versionamento para libllama e libggml. A partir de agora, mudanças incompatíveis na API pública de C exigem um aumento na versão principal.

Isso facilita o planejamento de atualizações de dependências. Porém, não garante que as respostas do modelo, o desempenho, os backends de GPU ou todos os endpoints HTTP continuem iguais.

O que mudou no llama.cpp 1.0.0?

As mudanças afetam principalmente quem integra llama.cpp em aplicações, administra llama-server ou precisa otimizar o uso de memória na inferência local.

ÁreaMudança no 1.0.0O que fazer
VersionamentoIncompatibilidades na API pública de C e na ABI passam a exigir versões principaisFixar uma versão ou commit em produção
API de CRemoção de 35 funções obsoletas e llama_set_warmupAtualizar bindings e recompilar
Configuração de contextoRemoção de defrag_thold e --defrag-tholdApagar configurações antigas
Decodificação especulativaNextN API passa para llama.h; uma função é renomeadaAtualizar includes e chamadas
Cache KVSuporte a f8_e4m3 para K e VTestar memória, qualidade e compatibilidade
Inferência MoECache de especialistas na GPU permite processar parte das falhas de cache na CPUVerificar GPU e ajustar tamanho e proporção de CPU
Segurança do servidorRestrições para ferramentas e URLs privadas de mídiaRevisar exposição de rede e autenticação
Suporte a modelosKimi-K3.1-Pro, Ripple, xing4_0 e recursos multimodaisConferir os requisitos de carregamento
API de vozEndpoint /v1/audio/speech compatível com OpenAITestar com um modelo de voz compatível

Os detalhes estão nas notas da versão v1.0.0 e no anúncio oficial sobre versionamento.

O projeto informa suporte a mais de 150 variantes de arquiteturas de modelos. Isso não significa que todos os checkpoints e recursos funcionem em qualquer backend.

O que o versionamento semântico significa depois do 1.0.0?

A nova política de compatibilidade cobre as interfaces públicas de C declaradas em ./include, incluindo as interfaces expostas por llama.cpp e ggml.

Os mantenedores definiram três regras:

ComponenteQuando mudaExemplo
MAJORMudança incompatível na API pública de C1.x.x para 2.0.0
MINORRecurso compatível, novo backend, modelo ou extensão de API1.0.0 para 1.1.0
PATCHCorreção de bug sem mudança na API1.0.0 para 1.0.1

Os exemplos ilustram as regras. Não são anúncios de versões futuras.

Para uma aplicação compilada com libllama, isso reduz o risco de alterações inesperadas nas assinaturas das funções públicas dentro da mesma versão principal.

A promessa, entretanto, não se estende automaticamente a headers internos, símbolos não documentados, argumentos de CLI, detalhes das respostas HTTP ou comportamento dos modelos.

Como fixar a versão do llama.cpp?

Ao compilar llama.cpp como dependência, use uma tag específica de lançamento ou um commit imutável.

O guia oficial de compilação explica como baixar o código e usar CMake. Combine essas instruções com a tag v1.0.0.

Exemplo em Bash:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git fetch --tags
git checkout v1.0.0

cmake -B build
cmake --build build --config Release

Esses são os comandos documentados para uma compilação básica com CPU. Dependendo da plataforma, outros backends também podem ser habilitados por padrão. Confira a configuração antes de assumir qual dispositivo executará o modelo.

Na compilação padrão, a documentação indica ./build/bin/llama-server como caminho do executável. Alguns geradores do CMake podem produzir uma estrutura diferente.

Se você precisa de GPU, adicione as opções de CMake documentadas para o backend correspondente.

Em produção, registre a tag, o hash do commit, as opções de compilação e o backend usado. Teste cada atualização antes de substituir o binário em funcionamento.

Se sua aplicação inclui uma cópia própria do llama.cpp, fixe também a versão do aplicativo ou wrapper. O número da versão dele pode ser diferente do motor incluído.

Quais APIs e parâmetros de linha de comando foram removidos?

A primeira tarefa da migração é remover as interfaces C obsoletas e a antiga configuração do limite de desfragmentação.

A limpeza de API do PR #30565 remove 35 funções obsoletas, llama_set_warmup e a configuração do limite de desfragmentação.

Verifique estas mudanças:

  • Remova chamadas a llama_set_warmup.
  • Retire defrag_thold da configuração de contexto.
  • Apague --defrag-thold dos scripts de inicialização.
  • Substitua llama_set_embd_state_src por llama_set_ctx_state_src onde for aplicável.
  • Atualize os includes e as declarações de NextN API, agora disponíveis em llama.h.

As 35 funções removidas não têm necessariamente uma substituição individual. Compare os headers de v1.0.0 com os símbolos realmente usados pelo seu binding.

Como remover —defrag-thold dos scripts

Um comando antigo poderia iniciar o servidor assim:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --defrag-thold 0.1

No 1.0.0, retire o argumento:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768

Não é necessário escolher outro valor para o limite. O parâmetro foi removido por completo. Não invente uma opção equivalente sem documentação.

Procure nomes antigos em scripts de shell, configurações do Docker, arquivos de serviço e código-fonte:

grep -RInE \
  'defrag[_-]thold|llama_set_warmup|llama_set_embd_state_src' \
  ./scripts ./config ./src

Ajuste os diretórios ao seu projeto. Se algum caminho não existir, remova-o do comando.

Confira também variáveis de ambiente e wrappers que montam argumentos de inicialização automaticamente.

Como atualizar bindings de C e Python

Se sua aplicação usa llama.h diretamente, compare as declarações do código com os headers de v1.0.0 antes de recompilar.

Depois, compile novamente a aplicação e confira as mensagens do compilador e do linker.

Para Python, primeiro verifique se a versão do wrapper declara suporte ao llama.cpp 1.0.0.

Trocar o executável do llama.cpp não atualiza automaticamente as definições já compiladas em uma extensão Python.

Alguns wrappers incluem uma cópia própria do código-fonte do llama.cpp. Nesse caso, siga o processo de atualização indicado pelo projeto. Não substitua manualmente a biblioteca compartilhada sem verificar a compatibilidade.

Um import bem-sucedido é apenas uma verificação inicial. Carregue um modelo, gere tokens e teste as operações de estado de contexto ou decodificação especulativa usadas pela aplicação.

Como habilitar o cache KV FP8 no llama.cpp 1.0.0?

Use -ctk f8_e4m3 -ctv f8_e4m3 para solicitar armazenamento FP8 para as chaves e os valores de atenção.

O cache KV armazena informações dos tokens anteriores. Assim, o modelo consegue continuar a geração sem recalcular todo o contexto.

Quanto maior o contexto, maior costuma ser a memória necessária para o cache.

FP8 utiliza 8 bits por valor, enquanto FP16 utiliza 16 bits. Para tensores de dimensões equivalentes, o armazenamento bruto de K/V pode cair aproximadamente pela metade.

Essa estimativa não inclui pesos do modelo, metadados, fatores de escala, alinhamento de memória nem buffers de computação. Portanto, não significa uma redução de 50% em todo o consumo de VRAM.

Comece medindo uma configuração FP16

Use o mesmo modelo e o mesmo tamanho de contexto nas duas execuções.

Inicie o servidor com FP16:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f16 \
  -ctv f16

Anote o tamanho do buffer KV informado nos logs. Registre também a memória livre do dispositivo, a velocidade de processamento do prompt e a velocidade de geração.

Pare o servidor e execute com FP8:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f8_e4m3 \
  -ctv f8_e4m3

A versão também adiciona suporte opcional a escalas estáticas por tensor no cache FP8.

Confira nos logs os tipos de cache selecionados e a memória efetivamente alocada.

O fato de um argumento ser reconhecido não comprova que seu backend de GPU suporta todos os caminhos otimizados de execução com esse formato.

FP8 permite dobrar o tamanho do contexto?

Não necessariamente. FP8 reduz o armazenamento dos tensores KV, mas os limites de contexto do modelo e de memória disponível continuam valendo.

Imagine uma carga hipotética em que o cache KV FP16 consome 8 GiB. Uma representação FP8 com as mesmas dimensões poderia reduzir os dados brutos para aproximadamente 4 GiB.

Esse é um cálculo teórico, não um resultado medido no llama.cpp.

A memória liberada pode permitir um contexto maior ou mais requisições simultâneas. Ela não amplia a capacidade efetiva do modelo além dos limites suportados.

FP8 também usa menor precisão. A documentação do lançamento não apresenta um resultado universal sobre qualidade de código ou precisão de chamadas de ferramentas com cache KV FP8.

Para agentes de programação, compare FP16 e FP8 nas mesmas tarefas:

  1. Localize um símbolo importante em um arquivo-fonte longo.
  2. Prepare uma alteração que envolva vários arquivos.
  3. Gere uma chamada estruturada de ferramenta.
  4. Continue a tarefa depois de vários turnos longos de conversa.

Avalie a correção do código e os argumentos das ferramentas. Não compare somente tokens por segundo.

Como funciona o novo cache de especialistas MoE?

O cache MoE pode ajudar quando um modelo Mixture-of-Experts mantém pesos de especialistas na RAM do sistema, em vez de armazenar tudo na GPU.

Modelos MoE selecionam alguns especialistas para processar cada token. Transferir os pesos deles da RAM para a GPU pode tornar a decodificação mais lenta.

O cache mantém na memória da GPU os especialistas residentes na CPU usados com mais frequência. Outro controle permite processar parte das falhas de cache diretamente na CPU.

Esse mecanismo é separado do cache KV FP8. O cache MoE trabalha com pesos de especialistas; o cache KV guarda estados de atenção.

O guia oficial do cache MoE documenta os seguintes parâmetros:

OpçãoFunçãoPadrão
-cmoeManter todos os pesos de especialistas MoE na memória da CPUDesativado até ser selecionado
--moe-cache-mib NReservar N MiB de cache na GPU para especialistas residentes na CPU0, desativado
--moe-cache-cpu-share FProcessar na CPU a proporção F de falhas depois que o cache estiver cheio0

O intervalo documentado para CPU share é de 0 a 1.

O funcionamento segue estas regras:

  • Acertos de cache são processados na GPU.
  • Antes de o cache encher, os especialistas ausentes são transferidos para a GPU.
  • Depois de cheio, a CPU processa a proporção configurada de falhas.
  • As demais falhas envolvem transferência dos pesos para execução na GPU.
  • Lotes grandes ainda podem precisar transferir especialistas.

A execução na CPU pode ser vantajosa quando ler pesos da RAM é mais rápido do que transferi-los para a GPU.

A memória de host fixada, ou pinned memory, pode alterar essa relação. Se a transferência já usa a largura de banda disponível com eficiência, aumentar CPU share pode trazer pouco benefício.

Exemplo: cache de especialistas MoE mantidos na RAM

Você precisa de um backend de GPU compatível e memória livre suficiente para armazenar o cache de especialistas.

Uma compilação exclusiva para CPU não consegue fornecer esse cache na GPU.

Em um sistema NVIDIA com o ambiente de desenvolvimento CUDA necessário, as instruções oficiais para CUDA indicam:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

Para outras GPUs compatíveis, use as instruções de compilação documentadas para o respectivo backend.

Exemplo com um modelo MoE compatível e uma compilação com suporte a GPU:

./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --moe-cache-mib 2048 \
  --moe-cache-cpu-share 0.5

-cmoe mantém os pesos dos especialistas na RAM. --moe-cache-mib 2048 solicita 2,048 MiB de memória da GPU para os especialistas selecionados.

O valor 0.5 atribui à CPU 50% das falhas de cache depois que ele estiver cheio.

Antes disso, as falhas continuam provocando transferências para a GPU. Os acertos também são processados na GPU.

É um exemplo de configuração, não uma recomendação universal para qualquer hardware.

A GPU também precisa de memória para camadas do modelo, cache KV e buffers de computação. Reservar mais espaço para especialistas reduz a memória disponível para esses componentes.

Se a alocação não couber, diminua o cache ou revise a distribuição dos pesos. O cache MoE não garante que um modelo grande demais consiga rodar.

Use o script de ajuste do cache

O projeto disponibiliza uma ferramenta para encontrar parâmetros adequados ao seu equipamento.

No repositório do llama.cpp, execute:

python3 scripts/moe-cache-tune.py -- \
  ./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -t 8 \
  -c 32768

O script de ajuste inicia o servidor com diferentes tamanhos de cache e proporções de CPU.

O guia oficial descreve seis medições: dois tamanhos de cache combinados com valores 0, 0.5 e 0.95 para CPU share.

Com esses resultados, o script estima outras configurações. Ele apresenta velocidades medidas, throughput previsto e argumentos recomendados.

Mantenha as opções reais de modelo, threads de CPU, tamanho de contexto e posicionamento dos especialistas. Elas afetam tanto o desempenho quanto a memória livre.

O cache documentado é voltado principalmente à decodificação de lotes pequenos. Lotes grandes ainda podem exigir transferência de especialistas para a GPU.

Se o modelo é denso ou todos os especialistas já cabem na GPU, provavelmente esse cache não será útil. Comece com o valor padrão desativado.

O que mudou na segurança do llama-server?

A versão 1.0.0 acrescenta permissões explícitas para expor ferramentas sem autenticação e para acessar URLs de mídia em redes privadas.

Essas opções merecem atenção especial quando outros computadores conseguem acessar o servidor.

—allow-unauthenticated-tools

--allow-unauthenticated-tools permite usar ferramentas do servidor, servidores MCP ou um proxy MCP em um endereço diferente de loopback sem API key.

A referência oficial de parâmetros informa que essa permissão fica desativada por padrão e deve ser usada somente em redes confiáveis.

O endereço 127.0.0.1 restringe as conexões à própria máquina. Já escutar em 0.0.0.0 pode permitir conexões por outras interfaces de rede.

Por isso, revise qualquer combinação de acesso não local, ferramentas do servidor ou MCP habilitados e ausência de API key.

O parâmetro que concede essa permissão é:

--allow-unauthenticated-tools

Não o adicione automaticamente para resolver dificuldades após atualizar. Ele permite acesso sem autenticação a capacidades sensíveis do servidor.

Essa configuração trata de ferramentas executadas pelo servidor e de MCP. O modelo retornar uma estrutura tool_calls é outra etapa do fluxo do agente.

Para desenvolvimento na mesma máquina, prefira um servidor local:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

Para clientes remotos, configure autenticação pelo parâmetro documentado --api-key e aplique restrições de rede adequadas.

No Bash, leia a chave sem exibir o que foi digitado:

read -rs LLAMA_SERVER_API_KEY && export LLAMA_SERVER_API_KEY

Inicie o servidor usando a variável de ambiente:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --jinja \
  --api-key "$LLAMA_SERVER_API_KEY"

Mantenha o serviço protegido por controles de rede. Uma API key, sozinha, não garante a segurança de qualquer implantação pública.

—media-allow-private-urls

A segunda mudança afeta URLs HTTP(S) de mídia recebidas pelo servidor, como links para imagens.

Por padrão, o servidor não permite carregar mídias a partir de endereços locais ou privados.

O parâmetro para permitir esse acesso é:

--media-allow-private-urls

Quando habilitado, ele permite que o servidor acesse recursos HTTP(S) hospedados em endereços locais ou privados.

Isso pode ser necessário quando uma aplicação confiável hospeda imagens em um serviço interno.

Por outro lado, aumenta o risco de SSRF se um cliente não confiável controlar as URLs. Um invasor poderia induzir o servidor a solicitar recursos internos que não deveriam ser acessados.

Sempre que possível, envie os dados da imagem diretamente em um formato compatível ou use hospedagem de mídia controlada.

Se URLs privadas forem necessárias, restrinja quem pode enviar requisições e quais destinos o servidor pode acessar. Não habilite o parâmetro apenas para carregar um link desconhecido.

Outras correções de segurança

O lançamento também inclui mudanças relacionadas a:

  • Validação de --cors-origins e comparação de origens.
  • Proteção contra DNS rebinding.
  • Correções de SSRF pelo proxy CORS.
  • Restrição de acesso direto do navegador a instâncias filhas do servidor.
  • Limitação dos destinos que podem receber HF_TOKEN.
  • Cancelamento de chamadas MCP após desconexão do cliente ou timeout.

O envio de HF_TOKEN passa a ser limitado aos hosts de huggingface.co.

Para agentes de programação, cancelar chamadas MCP ajuda a evitar que ferramentas desnecessárias continuem executando depois que o cliente se desconecta.

Entretanto, a notificação de cancelamento não garante reverter operações que uma ferramenta externa já tenha concluído.

Confira PR #32113, PR #32115 e as notas da versão v1.0.0 para os detalhes.

Como verificar um backend local para agentes de programação?

Teste primeiro a geração de respostas no servidor. Só depois conecte Claude Code, OpenCode ou outro cliente.

Inicie llama-server em loopback com um modelo de instruções adequado:

./build/bin/llama-server \
  -m /path/to/coding-model.gguf \
  --alias local-coder \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

O modelo precisa oferecer o comportamento de chamadas de ferramentas esperado pelo cliente.

--jinja habilita o processamento de templates de chat. Ele não cria capacidade de usar ferramentas em um modelo que não tenha esse suporte.

Consulte o endpoint de modelos com curl:

curl --fail-with-body \
  http://127.0.0.1:8080/v1/models

A resposta deve incluir o alias configurado para o modelo.

Depois, envie uma requisição simples de chat:

curl --fail-with-body \
  http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-coder",
    "messages": [
      {
        "role": "user",
        "content": "Explain what a Git diff shows in one sentence."
      }
    ],
    "max_tokens": 100
  }'

Confira se a resposta do modelo aparece em choices.

Quando funcionar, configure seu cliente pelo mecanismo documentado de provedor personalizado. A URL base da API local compatível com OpenAI é:

http://127.0.0.1:8080/v1

Ser compatível com OpenAI Chat Completions não significa oferecer compatibilidade completa com Anthropic Messages API ou OpenAI Responses API.

Claude Code pode precisar de um adaptador de protocolo ou outra integração suportada para se conectar ao servidor local.

OpenCode pode usar um provedor personalizado compatível quando a API e o modelo correspondem às configurações do cliente.

Antes de trabalhar em um repositório real, confirme que o agente consegue ler um arquivo, propor uma edição e executar uma chamada de ferramenta.

Uma resposta de texto correta não comprova que argumentos estruturados, alterações de arquivos e sessões longas também funcionarão.

Se você está avaliando Kimi, consulte o guia de configuração do Kimi K3.1 Pro com Claude Code e Codex. O guia de pesos abertos e licença do Kimi K3.1 Pro ajuda a comparar os requisitos de execução local e de acesso por API hospedada.

Usuários do Ollama e LM Studio precisam atualizar?

Se você utiliza Ollama ou LM Studio como aplicação pronta, não substitua manualmente as bibliotecas internas do llama.cpp.

Esses programas gerenciam suas próprias versões do motor, distribuição de binários e testes de compatibilidade.

O lançamento do llama.cpp 1.0.0 não significa que todas as aplicações dependentes já incluíram essa versão.

Consulte as notas de lançamento e use o mecanismo de atualização de cada aplicativo para identificar o runtime realmente incluído.

Preste atenção quando ocorrer uma destas mudanças:

  • A nova versão mencionar explicitamente llama.cpp 1.0.0 ou mudanças relacionadas ao motor.
  • Aparecerem novos formatos de cache KV ou parâmetros de cache MoE.
  • Mudarem as exigências de autenticação para ferramentas do servidor ou MCP.
  • O carregamento do modelo ou as chamadas de ferramentas mudarem de comportamento após atualizar.

Para uso comum de chat no desktop, você pode continuar em uma versão compatível que funciona bem se não precisar de uma correção ou recurso novo.

Se Ollama ou LM Studio funciona como backend de um agente, teste toda a integração entre cliente e servidor depois de cada atualização.

Quando vale a pena usar uma API hospedada?

A inferência local é útil enquanto seu computador consegue executar o modelo escolhido com o contexto e a velocidade necessários.

O cache KV FP8 pode reduzir o consumo de memória. O cache MoE pode ajudar em algumas cargas com especialistas mantidos na RAM. Nenhum dos dois resolve todos os limites de hardware nem garante programação mais rápida.

Se os pesos, o cache de atenção ou as requisições simultâneas ultrapassarem a memória disponível, compare um modelo local menor com um modelo hospedado.

Uma API hospedada elimina a necessidade de administrar diretamente a memória GPU desse modelo. Em troca, surgem dependência de rede, custos de uso e condições do provedor.

BetterToken é uma opção de acesso a vários modelos por API com pagamento conforme o uso. Ele não substitui a execução local do llama.cpp nem fornece seus recursos de segurança do servidor.

Antes de escolher um serviço hospedado, confira o preço do modelo e o custo da sua carga na página de preços atualizados.

Se você precisa alternar entre modelo local e hospedado, mantenha duas configurações de provedor testadas separadamente.

Não presuma que o mesmo ID de modelo, formato de ferramentas ou mecanismo de autenticação funcionará nos dois endpoints.

Checklist para atualizar com segurança

Antes de migrar um backend de programação em produção para llama.cpp 1.0.0, verifique:

  1. Fixe os fontes de v1.0.0 ou um artefato de compilação exato.
  2. Remova --defrag-thold e chamadas de API de C obsoletas.
  3. Recompile os bindings nativos com os novos headers públicos.
  4. Comece com a configuração anterior de cache KV FP16.
  5. Teste o cache KV FP8 separadamente, comparando memória, velocidade, correção do código e chamadas de ferramentas.
  6. Ajuste o cache MoE apenas com um backend GPU compatível e especialistas residentes na CPU.
  7. Revise autenticação de ferramentas e restrições de URLs privadas.
  8. Confira /v1/models, geração de chat, chamadas de ferramentas e o cliente de programação.
  9. Guarde o binário e a configuração anteriores para permitir rollback.

O llama.cpp 1.0.0 estabelece limites mais claros para a compatibilidade das suas bibliotecas públicas de C. Mesmo assim, uma atualização segura depende de testar seus bindings, hardware, exposição de rede e fluxo real do agente.

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.

Começar grátis