Configurar llama.cpp do zero assusta menos do que parece, e a v0.5.0, lançada em 23 de setembro de 2026, dá motivo para revisitar os parâmetros do llama-server. A versão, disponível na página de releases do projeto no commit 7fe450e, com build noturno associado b11146, atualiza a biblioteca ggml para a 0.25.0, expande o suporte a flash-attention e à fusão MoE/SSM entre os backends e adiciona suporte a novos modelos, como HRM-Text, MiMo-V2.6 e a conversão de HunyuanOCR.
A seguir, as configurações iniciais do llama-server numa GPU de 16 GB de VRAM, parâmetro por parâmetro, com o que mudou de verdade nesta versão. A referência completa das flags está no README oficial do servidor, no repositório do projeto.
O que você precisa antes de começar: binários da v0.5.0, GGUF e 16 GB de VRAM
Além dos binários da v0.5.0, que também têm espelho no SourceForge, você precisa de um modelo em formato GGUF. O llama-server sobe esse modelo com API compatível com OpenAI e uma web UI embutida para conversar sem escrever cliente nenhum.
Com 16 GB de VRAM, o cenário típico é um modelo quantizado na faixa de 12B rodando inteiro na GPU, com contexto folgado. Para quem roda tudo localmente, é a diferença entre depender de API externa e ter o serviço na própria máquina.
O comando completo do llama-server para uma GPU de consumo
Um ponto de partida típico, com valores de exemplo que você ajusta ao seu modelo:
llama-server -m modelo.gguf -ngl 99 -c 16384 --parallel 4 -fa auto -ctk q8_0 -ctv q8_0 -b 2048 -ub 512 --jinjaCada flag desse comando aparece detalhada nas seções seguintes. Se a sua instalação usa caminhos ou nomes de executável diferentes, o lugar para conferir é o README do servidor, que documenta a linha de comando completa.
--n-gpu-layers, tamanho de contexto (-c) e slots paralelos (--parallel)
A flag -ngl (ou --n-gpu-layers) define quantas camadas do modelo são descarregadas para a GPU. Com 16 GB, o objetivo costuma ser descarregar o máximo possível e deixar a CPU só como escape quando a memória aperta.
O -c aumenta o consumo de VRAM do cache KV junto com o contexto. Já o --parallel abre vários slots de inferência simultâneos no mesmo processo, e desde a v0.4.0 o servidor trabalha com limite de contexto por slot, um recurso que entra em cena justamente ao combinar --parallel com --ctx-size: mais slots significam contexto gerenciado por slot.
Flash Attention (--flash-attn) e cache KV quantizado (--cache-type-k / --cache-type-v)
A flag -fa (ou --flash-attn) aceita on, off ou auto, com padrão auto. Como a v0.5.0 expande o suporte a flash-attention entre os backends via ggml 0.25.0, o auto tende a acertar a escolha com mais frequência.
As flags -ctk/--cache-type-k e -ctv/--cache-type-v quantizam o cache KV. Elas aceitam f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0 e q5_1, com padrão f16. Trocar para q8_0 reduz o consumo de memória do cache e libera espaço para um contexto maior sem trocar de modelo.
Batch (-b e -ub), template Jinja (--jinja) e parâmetros de amostragem
As flags -b e -ub controlam o processamento em lote do prompt. O -ub (--ubatch-size) define o batch físico, com padrão de 512 tokens; mexer aqui afeta mais o processamento do prompt do que a geração de tokens.
A mudança silenciosa da versão está no --jinja: o template Jinja para chat agora vem habilitado por padrão no servidor, então o template de conversa do modelo é aplicado sem flag extra. Já os parâmetros de amostragem seguem a API compatível com OpenAI exposta pelo servidor, e a documentação das flags de linha de comando está no README das ferramentas de CLI.
Como testar o servidor pelos endpoints /health, /v1/models e /slots
O GET /health é público, sem checagem de API key, e é o jeito mais rápido de saber se o servidor está pronto: responde 503 enquanto o modelo carrega e 200 com {"status": "ok"} quando dá para trabalhar. O /v1/health também funciona.
Os endpoints /models e /v1/models listam o modelo carregado e devem ser consultados pelos clientes para verificar capacidades do servidor, como suporte multimodal, antes de requisições especiais. Com --parallel ativo, o /slots acompanha o que acontece em cada slot de inferência. E, antes de qualquer endpoint, a web UI embutida já permite conversar com o modelo direto do navegador.
Quando a VRAM estoura ou o modelo é MoE: o que ajustar primeiro
A ordem que costuma pagar a conta: reduzir o -c, quantizar o cache KV com -ctk e -ctv em q8_0 ou menos, e só então baixar o -ngl para descarregar camadas na CPU. Trocar a quantização do modelo para Q4 ou abaixo é o último recurso, porque afeta a qualidade de forma mais direta.
Para modelos MoE, o primeiro ajuste é rodar a v0.5.0: a versão expande a fusão MoE/SSM entre os backends, incluindo o Metal, além de trazer aceleração de convolução em CUDA. O que ainda varia é o comportamento por hardware e por modelo, então não existe número mágico de camadas ou de contexto que valha para toda GPU de 16 GB. A documentação oficial é a referência para limites específicos do seu caso.
Na prática: configurar llama.cpp na minha GPU de 16 GB
Eu deixo o --flash-attn no auto. Faço testes pontuais com outros valores, mas prefiro confiar no padrão da versão atual.
Hoje rodo o Gemma 12B denso em 4 bits inteiro na GPU, com cache KV e contexto de 30K, e ainda consigo rodar o z-image junto. Quando o z-image estoura um pouco a memória, ele cai para a RAM: demora mais, mas não falha a geração nem derruba o Gemma.
Já usei cache KV em q8 e q4, e ajusto a escolha conforme o modelo e a quantização dele, sempre testando antes. A experiência acumulada nesses testes dá uma margem de segurança para rodar modelos quantizados, tanto no cache KV quanto na quantização do modelo (Q4, Q5, Q6 e por aí vai). Só lembrando que quanto mais quantização, mais a qualidade cai um pouco. Vale testar no seu ambiente e ver o que se encaixa melhor.
Perguntas frequentes
Qual é o padrão do --flash-attn no llama-server atual?
A flag aceita on, off ou auto, e o padrão é auto.
Quais valores o --cache-type-k e o --cache-type-v aceitam?
As duas flags aceitam f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0 e q5_1, com padrão f16.
O que o /health responde enquanto o modelo carrega?
Ele retorna 503 durante o carregamento e 200 com {"status": "ok"} quando o servidor está pronto. É um endpoint público, sem checagem de API key, e o /v1/health também funciona.
