Introdução rápida ao llama.cpp com CLI e servidor

llama.cpp é um motor de inferência em C/C++ para modelos GGUF: llama-cli para chat interativo, llama-completion para prompts roteirizados e llama-server para uma API HTTP compatível com OpenAI.

Se você ainda está decidindo entre abordagens locais, auto-hospedadas e em nuvem, comece pelo guia pilar Hospedagem de LLM em 2026: Comparação de Infraestrutura Local, Auto-Hospedada e Nuvem.

Por que usar llama.cpp em 2026

llama.cpp é um motor de inferência leve com uma tendência para:

• portabilidade entre CPUs e múltiplos backends de GPU,
• latência previsível em uma única máquina,
• flexibilidade de implantação, de laptops a nós on-prem.

Ele brilha quando você quer privacidade e operação offline, quando precisa de controle determinístico sobre as flags de tempo de execução ou quando deseja incorporar a inferência em um sistema maior sem executar uma pilha pesada em Python.

Também é útil entender llama.cpp mesmo que você escolha posteriormente um runtime de servidor com maior vazão. Por exemplo, se seu objetivo é a vazão máxima de serviço em GPUs, você também pode querer compará-lo com o vLLM usando: vLLM Quickstart: Servindo LLMs de Alto Desempenho e você pode fazer benchmarks de escolhas de ferramentas em: Ollama vs vLLM vs LM Studio: Melhor Jeito de Executar LLMs Localmente em 2026?.

Se especificamente o Ollama for a alternativa que você está ponderando contra llama-server, llama.cpp vs Ollama em 2026 é a comparação dedicada entre os dois, com gatilhos concretos para quando manter o Ollama e quando migrar para o llama.cpp direto.

Instalação do llama.cpp em Windows, macOS e Linux

Os comandos abaixo correspondem ao llama.cpp v0.6.0 (5 de outubro de 2026). Uma entrada de catálogo para o mesmo runtime — inferência GGUF em backends de CPU e acelerador, versionada por commit de build — está na referência do runtime llama.cpp no LLM Systems. Há quatro caminhos práticos de instalação, dependendo se você quer conveniência, portabilidade ou desempenho máximo.

Instalação via gerenciadores de pacotes

Esta é a opção mais rápida de “fazer funcionar”.

# macOS ou Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS ou Linux (Nix)
nix profile install nixpkgs#llama-cpp

# Ubuntu (universe). Este pacote está muito atrás do upstream:
# 8681+dfsg contra o build atual b11433 / v0.6.0, então flags mais novas faltarão.
sudo apt install llama.cpp-tools

Dica: após instalar, verifique se as ferramentas existem:

llama-cli --version
llama-completion --version
llama-server --version

Instalação via binários pré-compilados

Se você deseja uma instalação limpa sem compiladores, use os binários pré-compilados oficiais publicados nos releases do GitHub do llama.cpp. Eles tipicamente cobrem múltiplos alvos de sistema operacional e múltiplos backends (variantes apenas CPU e habilitadas para GPU).

Um fluxo de trabalho comum:

# 1) Baixe o arquivo correto para seu SO e backend
# 2) Extraia-o
# 3) Execute a partir da pasta extraída

./llama-cli --help
./llama-server --help

Executar o container oficial

O projeto publica imagens de servidor no GitHub Container Registry. A imagem de CPU é ghcr.io/ggml-org/llama.cpp:server; a imagem de CUDA é :server-cuda. O container deve ouvir em todas as interfaces, pois o bind padrão ainda é 127.0.0.1:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Compilar do código-fonte para seu hardware exato

Se você se preocupa em extrair o melhor desempenho do seu backend de CPU/GPU, compile a partir do código-fonte com CMake.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Build de CPU
cmake -B build
cmake --build build --config Release

Após o build, os binários tipicamente estão aqui:

ls -la ./build/bin/

Builds de GPU em um único comando

Habilite o backend que corresponda ao seu hardware (exemplos mostrados para CUDA e Vulkan):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + GPU NVIDIA: roteiro completo de build

No Ubuntu 24.04 com uma GPU NVIDIA, você precisa do toolkit CUDA e do OpenSSL antes de compilar. Aqui está uma sequência testada:

1. Instale o toolkit CUDA 13.1. Este roteiro fixa o instalador local 13.1.1. Um toolkit mais novo do repositório Ubuntu 24.04 da NVIDIA segue os mesmos passos de pin-file e de deb local com nomes de arquivos atualizados.

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Adicione o CUDA ao seu ambiente (acrescente ao ~/.bashrc):

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Depois execute source ~/.bashrc ou abra um novo terminal.

3. Instale os cabeçalhos de desenvolvimento do OpenSSL (necessário para um build limpo):

sudo apt update
sudo apt install libssl-dev

4. Compile o llama.cpp (a partir do diretório contendo seu clone do llama.cpp, com CUDA habilitado):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Isso produz llama-cli, llama-mtmd-cli, llama-server, llama-embedding e llama-gguf-split no diretório llama.cpp.

Você também pode compilar múltiplos backends e escolher dispositivos em tempo de execução. Isso é útil se você implantar o mesmo build em máquinas heterogêneas.

Escolha um modelo GGUF e uma quantização

Para executar inferência, você precisa de um arquivo de modelo GGUF (*.gguf). GGUF é um formato de arquivo único que reúne pesos do modelo mais metadados padronizados necessários por motores como llama.cpp.

Duas maneiras de obter um modelo

Opção A: Usar um arquivo GGUF local

Baixe ou copie um GGUF para ./models/:

mkdir -p models
# Coloque seu GGUF em models/my-model.gguf

Depois execute-o por caminho:

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -n 128 -st

Opção B: Deixar o llama.cpp baixar do Hugging Face

Builds modernos do llama.cpp podem baixar do Hugging Face e manter arquivos em um cache local. Isso muitas vezes é o fluxo de trabalho mais fácil para experimentos rápidos.

# Baixe um modelo do HF e execute um prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200 \
  -st

Você também pode especificar a quantização no seletor de repositório e deixar a ferramenta selecionar um arquivo correspondente:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Summarize the concept of quantization in one paragraph." \
  -n 160 \
  -st

Se você precisar de um fluxo de trabalho totalmente offline depois, --offline força o uso do cache e impede o acesso à rede.

Escolha de quantização para inferência local

A quantização é a resposta prática à pergunta “Qual quantização GGUF devo escolher para inferência local” porque ela faz um trade-off direto entre qualidade, tamanho do modelo e velocidade.

Um ponto de partida pragmático:

• comece com uma variante Q4 ou Q5 para máquinas priorizadas em CPU,
• migre para precisão mais alta (ou quantização menos agressiva) quando puder pagar pela RAM ou VRAM,
• quando o modelo “parece burro” para sua tarefa, a correção muitas vezes é um modelo melhor ou uma quantização menos agressiva, não apenas ajustes de amostragem.

Lembre-se também que a janela de contexto importa: tamanhos de contexto maiores aumentam o uso de memória (às vezes dramaticamente), mesmo quando o arquivo GGUF em si cabe.

Quickstart do llama-cli e parâmetros-chave

llama-cli é a maneira mais rápida de validar que seu modelo carrega, que seu backend funciona e que seus prompts se comportam como esperado.

llama-cli tem sido um cliente de chat interativo desde a reescrita de dezembro de 2025. Quando o modelo inclui um template de chat, o modo de conversa está habilitado por padrão e --no-conversation é rejeitado com uma referência para llama-completion. Esse segundo binário é o antigo llama-cli: um prompt de entrada, uma conclusão de saída, adequado para scripts e pipes. A partir do novo cliente, --single-turn (-st) gera uma única resposta e sai.

Uma resposta e depois sair

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  -st

O mesmo prompt através do binário não interativo:

llama-completion \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  --no-conversation

Execução de chat interativo

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You are a concise systems engineering assistant." \
  --ctx-size 4096

--conversation não é mais necessário. Para encerrar a geração quando o modelo imprime uma sequência específica, use um prompt reverso.

Principais flags do llama-cli que importam

Em vez de memorizar 200 flags, foque nas que dominam correção, latência e memória.

Modelo e download

Contexto e vazão

Offload de GPU e seleção de hardware

Amostragem e qualidade da saída

Cargas de trabalho de exemplo com llama-cli

Resumir um arquivo, não apenas um prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300 \
  -st

Tornar resultados mais reproduzíveis

Quando você está depurando prompts, fixe a seed e reduza a aleatoriedade:

llama-cli \
  -m models/my-model.gguf \
  -p "Extract key risks from this design note." \
  -n 200 \
  --seed 42 \
  --temp 0.2 \
  -st

Quickstart do llama-server com API compatível com OpenAI

llama-server é um servidor HTTP embutido que pode expor:

• endpoints compatíveis com OpenAI para chat, conclusões, embeddings e respostas,
• uma interface Web para testes interativos,
• endpoints de monitoramento opcionais para visibilidade em produção.

Iniciar um servidor com um modelo local

llama-server \
  -m models/my-model.gguf \
  -c 4096

Por padrão, ele ouve em 127.0.0.1:8080.

Para bind externo (por exemplo dentro do Docker ou em uma LAN), especifique host e porta:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Flags opcionais, mas importantes do servidor

Se você executar em containers, muitas configurações também podem ser controladas através de variáveis de ambiente LLAMA_ARG_*.

Chamadas de API de exemplo

Chat completions com curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a quick llama.cpp checklist." }
    ],
    "temperature": 0.7
  }'

Dica para implantações reais: se você definir --api-key, pode enviá-lo via um cabeçalho x-api-key (ou continuar usando cabeçalhos de Authorization dependendo do seu gateway).

Cliente Python OpenAI apontando para llama-server

Com um servidor compatível com OpenAI, muitos clientes podem funcionar apenas mudando base_url — esta também é a forma como agentes de pesquisa como lukeswade/deep-research se comunicam diretamente com o llama-server, sem uma camada de adaptador separada. Sistemas de Pesquisa Profunda Auto-Hospedados: 12 Ferramentas Comparadas cobre esse projeto e outros apontados para endpoints locais compatíveis com OpenAI.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain threads vs batch size in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Embeddings

Embeddings compatíveis com OpenAI são expostos em /v1/embeddings, mas o modelo deve suportar um modo de pooling de embedding que não seja none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Se você executar um modelo de embedding dedicado, considere iniciar o servidor em modo apenas embeddings:

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

ou se você quiser executar o llama-cpp com modelo de embedding na CPU:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

tente assim:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "your text here" \
  --pooling last \
  --verbose-prompt

Servir múltiplos modelos de um único processo

Os exemplos acima vinculam llama-server a um único modelo na inicialização. Se você precisar alternar entre modelos base em requisição — sem reiniciar o processo — é para isso que serve o modo router. Veja Modo router do llama-server: troca dinâmica de modelos sem reinicialização. Para um fluxo de descarregamento de todos scriptável que libera VRAM sem reiniciar o router, veja Descarregar Todos os Modelos do Router llama.cpp Sem Reiniciar.

Desempenho, monitoramento e fortalecimento para produção

A pergunta da FAQ “Quais opções de linha de comando do llama.cpp importam mais para velocidade e memória” torna-se muito mais fácil quando você trata a inferência como um sistema:

• Limite de memória é geralmente a primeira restrição (RAM na CPU, VRAM na GPU).
• Tamanho do contexto é um multiplicador de memória importante.
• Offload de camadas para GPU é muitas vezes o caminho mais rápido para mais tokens por segundo.
• Tamanhos de lote e threads podem melhorar a vazão, mas também podem aumentar a pressão de memória.

Para uma visão mais profunda, centrada em engenharia, veja: Desempenho de LLM em 2026: Benchmarks, Gargalos & Otimização.

Se você quer resultados medidos no estilo llama-cli em uma GPU de classe 16 GB—tokens por segundo, VRAM e carga da GPU enquanto varre o contexto (19K / 32K / 64K) através de GGUFs densos e MoE—veja Benchmarks de LLM com VRAM de 16 GB com llama.cpp (velocidade e contexto).

Para o Qwen 3.6, o llama.cpp suporta decodificação especulativa de Multi-Token Prediction integrada. Ative-a com --spec-type draft-mtp; --spec-draft-n-max define quantos tokens a cabeça de rascunho propõe (padrão 3). A v0.6.0 estende esse mesmo caminho MTP para o Qwen4Exp. Para a comparação de métodos, veja Decodificação Especulativa. Para números medidos do Qwen 3.6 em 16 GB, veja Qwen 3.6 MTP vs Padrão em GPU de 16GB.

Monitoramento do llama-server com Prometheus e Grafana

llama-server expõe métricas compatíveis com Prometheus em /metrics apenas quando --metrics está habilitado. Aponte um job de scrape do Prometheus nesse caminho. Dashboards e limiares de alerta para llama.cpp, vLLM e TGI estão em Monitoramento de Inferência de LLM em Produção (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp.

Lista de verificação básica de fortalecimento

Quando seu llama-server está acessível além do localhost:

• use --api-key (ou --api-key-file) para que as requisições sejam autenticadas,
• evite bind em 0.0.0.0 a menos que você precise,
• considere TLS via as flags SSL do servidor ou termine TLS em um proxy reverso,
• restrinja a concorrencia com --parallel para proteger a latência sob carga,
• mantenha --tools e --agent desligados. Ambos são experimentais e expõem operações de arquivo e shell pela API; habilitar qualquer um também restringe CORS para localhost.

Vitórias rápidas na solução de problemas

O modelo carrega, mas as respostas são estranhas no chat

Endpoints de chat são melhores quando o modelo tem um template de chat suportado. Se as saídas parecerem desestruturadas, tente:

• passar um --system-prompt explícito (o modo de conversa já é o padrão no llama-cli),
• verificar se seu modelo é uma variante ajustada para instruções ou chat,
• testar usando a interface Web do servidor antes de integrá-lo a um aplicativo. A v0.6.0 reconstruiu essa interface com um navegador do Hugging Face Hub, de modo que um modelo pode ser baixado da página, e não apenas da CLI.

Modelos de raciocínio envolvem a resposta em rastros de raciocínio. --reasoning off suprime isso e --reasoning-format deepseek move o rastro para reasoning_content em vez de content.

Você atingiu limite de memória

Reduza o contexto ou escolha uma quantização menor:

• abaixe --ctx-size,
• reduza --n-gpu-layers se o problema for VRAM, ou defina --cpu-moe para que os pesos de especialistas de um modelo MoE fiquem na RAM,
• mude para um modelo menor ou uma quantização mais compressa,
• quantize o cache KV com --cache-type-k q8_0 --cache-type-v q8_0.

O contexto ou divisão de GPU não é o que você pediu

--fit está habilitado por padrão e reescreve configurações de memória que você deixou indefinidas, visando deixar 1024 MiB livres em cada dispositivo (--fit-target). Ele reduzirá o contexto, mas nunca abaixo de --fit-ctx (4096), e apenas quando você não passou -c. Ele não tocará na colocação de camadas uma vez que você passe qualquer -ngl. --fit off desabilita o mecanismo. Se os logs disserem n_gpu_layers already set by user, seu -ngl explícito é o que foi carregado, e fit não resgatará um erro de falta de memória dele.

Está lento na CPU

Comece com:

• --threads igual aos seus núcleos físicos,
• tamanhos de lote moderados,
• validando se você instalou um build que corresponde à sua máquina (recursos de CPU e backend).

Referências

• Repositório e documentação oficial do llama.cpp
• Documentação oficial das flags da CLI
• Documentação oficial do llama-server e detalhes da API