Início Rápido do llama.cpp com CLI e Servidor

Volto constantemente ao llama.cpp para inferência local – ele oferece um controle que o Ollama e outros abstraem, e simplesmente funciona. É fácil executar modelos GGUF de forma interativa com o llama-cli ou expor uma API HTTP compatível com OpenAI com o llama-server.

Se você ainda está decidindo entre abordagens locais, autohospedadas e em nuvem, comece com o guia pilar LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Por que llama.cpp em 2026

llama.cpp é um mecanismo de inferência leve com uma inclinação para:

• 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-premise.

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 o llama.cpp, mesmo que você escolha posteriormente um tempo de execução de servidor com maior throughput. Por exemplo, se seu objetivo é o máximo de throughput de serviço em GPUs, você também pode querer compará-lo com o vLLM usando: vLLM Quickstart: High-Performance LLM Serving e você pode realizar benchmarks das escolhas de ferramentas em: Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Instalando llama.cpp no Windows, macOS e Linux

Há três caminhos práticos de instalação, dependendo se você quer conveniência, portabilidade ou desempenho máximo.

Instalar via gerenciadores de pacotes

Esta é a opção mais rápida para “fazer rodar”.

# 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

Instalar via binários pré-compilados

Se você quer uma instalação limpa sem compiladores, use os binários pré-compilados oficiais publicados nas releases do llama.cpp no GitHub. Eles geralmente cobrem múltiplos sistemas operacionais e 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

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

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

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

# Compilação CPU
cmake -B build
cmake --build build --config Release

Após a compilação, os binários geralmente estão aqui:

ls -la ./build/bin/

Compilações de GPU em um 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: walkthrough completo de compilação

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

1. Instalar CUDA toolkit 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. Adicionar CUDA ao seu ambiente (anexar a ~/.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. Instalar os cabeçalhos de desenvolvimento OpenSSL (necessário para uma compilação limpa):

sudo apt update
sudo apt install libssl-dev

4. Compilar llama.cpp (a partir do diretório contendo seu clone 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 a mesma compilação 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 mais 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

Depois, execute-o pelo caminho:

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

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

Compilações modernas do llama.cpp podem baixar do Hugging Face e manter os arquivos em um cache local. Isso é frequentemente 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 de repositório e deixar a ferramenta selecionar um arquivo correspondente:

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 posteriormente, --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” porque 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,
• mova-se para precisão maior (ou quantização menos agressiva) quando puder pagar pela RAM ou VRAM,
• quando o modelo “parece burro” para sua tarefa, a correção geralmente é ou um modelo melhor ou uma quantização menos agressiva, não apenas ajustes de amostragem.

Também lembre-se que a janela de contexto importa: tamanhos de contexto maiores 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-chave

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 breve comparação TCP vs UDP." \
  -n 200

Execução de chat interativo

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 de engenharia de sistemas conciso." \
  --ctx-size 4096

Para encerrar a geração quando o modelo imprimir uma sequência específica, use um prompt inverso. 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

Descarregamento 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 máxima de cinco tópicos." \
  --file ./docs/incident-report.txt \
  -n 300

Tornar os resultados mais reproduzíveis

Quando você está depurando prompts, fixe a semente e reduza 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 integrado 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.

Iniciar 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 o host e a porta:

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

Flags de servidor opcionais, mas importantes

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

Chamadas de API de exemplo

Completions de chat 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 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 alterando 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 tamanho de lote 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 no 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 "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 por requisição — sem reiniciar o processo — é para isso que o modo roteador serve. Veja llama-server router mode: dynamic model switching without restarts.

Desempenho, monitoramento e endurecimento para produção

A pergunta de 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:

• Teto de memória geralmente é a primeira restrição (RAM na CPU, VRAM na GPU).
• Tamanho de contexto é um multiplicador de memória importante.
• Descarregamento 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 profunda, voltada para engenharia, veja: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Se você quer resultados no estilo llama-cli medidos em uma GPU de classe 16 GB — tokens por segundo, VRAM e carga de GPU enquanto varre o contexto (19K / 32K / 64K) em GGUFs densos e MoE — veja 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

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 configs de scrape Prometheus e dashboards do Grafana.

Para dashboards e alertas específicos para llama.cpp (e vLLM, TGI): Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp. Guias mais amplos: Observability: Monitoring, Metrics, Prometheus & Grafana Guide e Observability for LLM Systems.

Checklist básico de endurecimento

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 vincular a 0.0.0.0 a menos que precise,
• considere TLS via flags SSL do servidor ou termine TLS em um proxy reverso,
• restrinja concorrência com --parallel para proteger a latência sob carga.

Soluções rápidas 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 não estruturadas, tente:

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

Você atingiu limite de memória (out of memory)

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 uma compilação que corresponde à sua máquina (recursos de CPU e backend).

Referências

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