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

Continuo voltando 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 interativamente com llama-cli ou expor uma API HTTP compatível com a OpenAI com llama-server.

Se você ainda está decidindo entre abordagens locais, auto-hospedadas e em nuvem, comece pelo guia principal: LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Por que usar llama.cpp em 2026

llama.cpp é um motor de inferência leve com viés 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-premises.

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

Também é útil entender llama.cpp, mesmo que você opte mais tarde por um runtime 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 comparar as escolhas de ferramentas em: Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Instalar llama.cpp no Windows, macOS e Linux

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

Instalação via gerenciadores de pacotes

Esta é a opção mais rápida para “colocar em funcionamento”.

# 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 geralmente cobrem vários alvos de sistema operacional e vários backends (variantes apenas de 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 do código-fonte para seu hardware exato

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

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

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

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

ls -la ./build/bin/

Compilações de GPU em um único comando

Ative 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 compilação

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. Instalar o 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 o CUDA ao seu ambiente (anexar 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. Instalar os cabeçalhos de desenvolvimento do OpenSSL (necessários para uma compilação limpa):

sudo apt update
sudo apt install libssl-dev

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

Em seguida, execute-o por caminho:

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -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. Esta é frequentemente a workflow 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

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

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 priorizadas em CPU,
• passe para maior precisão (ou quantização menos agressiva) quando puder arcar com 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 o tamanho da 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 se seu modelo carrega, seu backend funciona e seus prompts se comportam.

Execução mínima

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -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 "You are a concise systems engineering assistant." \
  --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, concentre-se naquelas 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 "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300

Tornar os resultados mais reproduzíveis

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

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, 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 escuta em 127.0.0.1:8080.

Para vincular externamente (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 do servidor opcionais, mas importantes

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

Chamadas de API de exemplo

Conclusões 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": "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, poderá enviá-lo via cabeçalho x-api-key (ou continuar usando cabeçalhos Authorization, dependendo de 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": "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 no modo apenas de 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 o 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 a partir de um processo

Os exemplos acima vinculam llama-server a um único modelo na inicialização. Se você precisar alternar entre modelos em uma base por solicitação — sem reiniciar o processo — é para isso que serve o modo roteador. Veja llama-server router mode: dynamic model switching without restarts. Para um fluxo de descarga de todos os modelos que libera VRAM sem reiniciar o roteador, veja Unload All llama.cpp Router Models Without Restarting.

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” torna-se muito mais fácil quando você trata a inferência como um sistema:

• O teto de memória geralmente é a primeira restrição (RAM na CPU, VRAM na GPU).
• O tamanho do contexto é um multiplicador de memória significativo.
• 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 na memória.

Para uma visão mais profunda, focada em engenharia, veja: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Se você deseja resultados medidos 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) em GGUFs densos e MoE — veja 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

Para o Qwen 3.6 especificamente, o llama.cpp agora suporta decodificação especulativa de Previsão de Múltiplos Tokens (MTP) integrada que pode aumentar significativamente o throughput de geração. Veja Qwen 3.6 27B and 35B MTP vs Standard on 16GB GPU para velocidades de geração medidas, overhead de VRAM e valores recomendados de --spec-draft-n-max.

Monitoramento do 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 coleta do Prometheus e painéis do Grafana.

Para painéis e alertas específicos do 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.

Lista básica de endurecimento

Quando seu llama-server estiver acessí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 as 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ção de problemas rápida

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

Os endpoints de chat são melhores 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 de instrução ou ajustada para chat,
• testar usando a interface web do servidor antes de conectá-lo a um aplicativo.

Você atingiu o limite de memória

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

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

Está lento na CPU

Comece com:

• --threads igual aos seus núcleos físicos,
• tamanhos de lote moderados,
• validando se você instalou uma compilação que corresponde à sua máquina (recursos da 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