llama.cpp: Guia Rápido com CLI e Servidor

Eu continuo voltando a llama.cpp para inferência local — ela oferece um controle que o Ollama e outros abstraem, e simplesmente funciona. É fácil executar modelos GGUF interativamente com llama-cli ou expor uma API HTTP compatível com OpenAI com llama-server.

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

Por que llama.cpp em 2026

llama.cpp é um mecanismo de inferência leve com foco em:

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

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

Também é útil entender llama.cpp mesmo que você escolha posteriormente um tempo de execução de servidor com maior throughput. Por exemplo, se seu objetivo é o throughput máximo de serviço em GPUs, você pode querer compará-lo ao vLLM usando: Início rápido do vLLM: Servindo LLMs de Alto Desempenho e você pode benchmarkar escolhas de ferramentas em: Ollama vs vLLM vs LM Studio: A Melhor Maneira de Executar LLMs Localmente em 2026?.

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

Instale o llama.cpp em Windows, macOS e Linux

Há três 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

Dica: após a instalação, verifique se as ferramentas existem:

llama-cli --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 lançamentos do GitHub do llama.cpp. Eles normalmente 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

Compile a partir do código-fonte para seu hardware exato

Se você se importa 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 para CPU
cmake -B build
cmake --build build --config Release

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

ls -la ./build/bin/

Builds de GPU em um comando

Habilite o backend que corresponde 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: guia completo de build

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

1. Instale a toolkit CUDA 13.1

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 a CUDA ao seu ambiente (adicione 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

Em seguida, execute source ~/.bashrc ou abra um novo terminal.

3. Instale os cabeçalhos de desenvolvimento do OpenSSL (necessários 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 agrupa pesos do modelo além dos metadados padronizados necessários por mecanismos 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

Em seguida, execute-o pelo caminho:

llama-cli -m models/my-model.gguf -p "Hello! Explique o que é o llama.cpp." -n 128

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. Este é 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 "Era uma vez," \
  -n 200

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

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Resuma o conceito de quantização em um parágrafo." \
  -n 160

Se você precisar de um fluxo de trabalho totalmente offline mais tarde, --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 você deve escolher para inferência local”, pois ela troca diretamente qualidade, tamanho do modelo e velocidade.

Um ponto de partida pragmático:

• comece com uma variante Q4 ou Q5 para máquinas focadas em CPU,
• passe para uma precisão maior (ou quantização menos agressiva) quando você puder suportar a RAM ou VRAM,
• quando o modelo “parece burro” para sua tarefa, a correção geralmente é 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 maiores de contexto aumentam o uso de memória (às vezes dramaticamente), mesmo quando o próprio arquivo GGUF cabe.

Início rápido do llama-cli e parâmetros principais

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

Execução mínima

llama-cli \
  -m models/my-model.gguf \
  -p "Escreva uma curta comparação entre TCP e UDP." \
  -n 200

Execução interativa de chat

O modo de conversa é projetado para templates de chat. Ele geralmente habilita comportamento interativo e formata prompts de acordo com o template do modelo.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Você é um assistente conciso de engenharia de sistemas." \
  --ctx-size 4096

Para encerrar a geração quando o modelo imprimir uma sequência específica, use um prompt reverso. Isso é especialmente útil no modo interativo.

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 throughput

Offload de GPU e seleção de hardware

Amostragem e qualidade de 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 "Você resume documentos técnicos. Saída: no máximo cinco itens." \
  --file ./docs/incident-report.txt \
  -n 300

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 "Extraia riscos-chave desta nota de design." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Início rápido 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, completions, embeddings e respostas,
• uma interface Web para testes interativos,
• endpoints de monitoramento opcionais para visibilidade em produção.

Inicie um servidor com um modelo local

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

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

Para vincular externamente (por exemplo, dentro de Docker ou 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 contêineres, muitas configurações também podem ser controladas através das 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": "Você é um assistente prestativo." },
      { "role": "user", "content": "Dê-me uma lista de verificação rápida do llama.cpp." }
    ],
    "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 Authorization dependendo do seu gateway).

Cliente Python OpenAI apontando para llama-server

Com um servidor compatível com OpenAI, muitos clientes podem funcionar mudando apenas base_url.

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": "Você é um assistente conciso."},
        {"role": "user", "content": "Explique threads vs batch size no 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 um 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 "seu texto aqui" \
  --pooling last \
  --verbose-prompt

Servindo 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 com base em cada solicitação — sem reiniciar o processo — é para isso que o modo router serve. Veja llama-server router mode: comutação dinâmica de modelos sem reinícios. Para um fluxo scriptável de descarregar-tudo que libera VRAM sem reiniciar o router, veja Descarregar Todos os Modelos do Router do llama.cpp Sem Reiniciar.

Desempenho, monitoramento e endurecimento para produção

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

• O limite de memória geralmente é a primeira restrição (RAM na CPU, VRAM na GPU).
• O tamanho do contexto é um multiplicador de memória significativo.
• O offload de camadas de GPU é frequentemente o caminho mais rápido para mais tokens por segundo.
• Tamanhos de lote e threads podem melhorar o throughput, mas também podem aumentar a pressão de memória.

Para uma visão mais aprofundada, focada em engenharia, veja: Desempenho de LLM em 2026: Benchmarks, Gargalos e Otimização.

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

Especificamente para Qwen 3.6, o llama.cpp agora suporta Decodificação Especulativa Multi-Token Prediction (MTP) embutida que pode aumentar significativamente o throughput de geração. Para um guia abrangente cobrindo todos os métodos de decodificação especulativa no llama.cpp, veja Decodificação Especulativa. Para benchmarks específicos de MTP do Qwen 3.6, veja Qwen 3.6 MTP vs Padrão em GPU 16GB.

Monitorando llama-server com Prometheus e Grafana

llama-server pode expor métricas compatíveis com Prometheus em /metrics quando --metrics está habilitado. Isso combina naturalmente com configurações de scrape do Prometheus e dashboards do Grafana.

Para dashboards e alertas específicos para llama.cpp (e vLLM, TGI): Monitorar Inferência de LLM em Produção (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp. Guias mais amplos: Observabilidade: Guia de Monitoramento, Métricas, Prometheus & Grafana e Observabilidade para Sistemas de LLM.

Lista de verificação básica de endurecimento

Quando seu llama-server é alcançável além do localhost:

• use --api-key (ou --api-key-file) para que as solicitações sejam autenticadas,
• evite vincular a 0.0.0.0 a menos que você precise,
• considere TLS via flags SSL do servidor ou termine TLS em um proxy reverso,
• restrinja a concorrência com --parallel para proteger a latência sob carga.

Soluções rápidas de solução de problemas

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

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

• usar llama-cli --conversation mais um --system-prompt explícito,
• verificar se seu modelo é uma variante ajustada para instruções ou chat,
• testar usando a interface Web do servidor antes de integrá-lo em um aplicativo.

Você atingiu falta de memória

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

• diminua --ctx-size,
• reduza --n-gpu-layers se VRAM for o problema,
• mude para um modelo menor ou uma quantização mais comprimida.

É lento na CPU

Comece com:

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

Referências

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