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

Tenho voltado constantemente a llama.cpp para inferência local — ele oferece controle que o Ollama e outros abstraem, e simplesmente funciona. Fácil de 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, autosserviço e em nuvem, comece com o guia principal LLM Hosting em 2026: Local, Self-Hosted & Cloud Infrastructure Comparada.

Por que llama.cpp em 2026

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

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

Também é útil entender llama.cpp mesmo que você depois escolha um tempo de execução de servidor com maior throughput. Por exemplo, se seu objetivo é o máximo de throughput de servidores em GPUs, você também pode querer compará-lo com vLLM usando: vLLM Quickstart: High-Performance LLM Serving e você pode avaliar escolhas de ferramentas em: Ollama vs vLLM vs LM Studio: Melhor forma de executar LLMs localmente em 2026?.

Instale o llama.cpp no Windows, macOS e Linux

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

Instale via gerenciadores de pacotes

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

# 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 instalar, verifique se as ferramentas existem:

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

Instale via binários pré-construídos

Se você quiser uma instalação limpa sem compiladores, use os binários pré-construídos oficiais publicados no llama.cpp releases do GitHub. Eles geralmente cobrem múltiplos alvos de OS e múltiplos backends (variantes apenas de CPU e com GPU).

Um fluxo de trabalho comum:

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

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

Construa a partir da fonte para seu hardware exato

Se você se importa em extrair o melhor desempenho de seu backend de CPU/GPU, construa a partir da fonte com CMake.

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

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

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

ls -la ./build/bin/

Construção para 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: walkthrough completo da construção

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

1. Instale o 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 o CUDA ao seu ambiente (append ao ~/.bashrc):

# toolkit CUDA
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ários para uma construção limpa):

sudo apt update
sudo apt install libssl-dev

4. Construa o llama.cpp (a partir do diretório que contém sua cópia 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
cp llama.cpp/build/bin/llama-* llama.cpp

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

Você também pode compilar múltiplos backends e escolher dispositivos no runtime. Isso é útil se você implantar a mesma construçã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 único arquivo que agrupa pesos do modelo mais metadados padronizados necessários para motores como llama.cpp.

Duas formas de obter um modelo

Opção A: Use 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: Deixe o llama.cpp baixar do Hugging Face

Construções modernas do llama.cpp podem baixar do Hugging Face e manter 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 "Uma vez, em um tempo," \
  -n 200

Você também pode especificar a quantização no seletor de repositórios 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 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 você deve escolher para inferência local”, pois ela troca diretamente qualidade, tamanho do modelo e velocidade.

Um ponto de partida prático:

• comece com uma variante Q4 ou Q5 para máquinas com CPU como principal,
• mude para uma precisão maior (ou menos agressiva) quando você puder pagar o RAM ou VRAM,
• quando o modelo “parecer bobo” para sua tarefa, a solução geralmente é ou um modelo melhor ou uma quantização menos agressiva, não apenas ajustes de amostragem.

Lembre-se também que o contexto importa: tamanhos de contexto maiores aumentam o uso de memória (às vezes dramaticamente), mesmo quando o próprio arquivo GGUF se encaixa.

Quickstart e parâmetros principais do llama-cli

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

Execução mínima

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

Execução de chat interativo

O modo de conversa foi projetado para modelos de chat. Geralmente ativa comportamento interativo e formata prompts de acordo com o 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 imprime 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 corretude, latência e memória.

Modelo e download

Contexto e throughput

Desempenho da GPU e seleção de hardware

Amostragem e qualidade da saída

Exemplos de cargas de trabalho com llama-cli

Resumir um arquivo, não apenas um prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Você resumiu documentos técnicos. Saída de no máximo cinco bullets." \
  --file ./docs/incident-report.txt \
  -n 300

Tornar os resultados mais reprodutíveis

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

llama-cli \
  -m models/my-model.gguf \
  -p "Extraia riscos principais deste documento de design." \
  -n 200 \
  --seed 42 \
  --temp 0.2

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, completions, embeddings e respostas,
• uma interface Web UI 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 um 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 importantes do servidor (opcionais)

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

Exemplos de chamadas API

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 útil." },
      { "role": "user", "content": "Dê-me um rápido checklist 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 continue usando cabeçalhos de autorização dependendo de sua 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 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ê rodar um modelo dedicado a embeddings, considere iniciar o servidor no modo apenas de embeddings:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Desempenho, monitoramento e reforço para produção

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

• Teto de memória geralmente é a primeira restrição (RAM em CPU, VRAM em GPU).
• Tamanho do contexto é um multiplicador importante de memória.
• Offload de camadas da GPU geralmente é 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, com foco em engenharia, veja: Desempenho de LLM em 2026: Benchmarks, Bottlenecks & Otimização.

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

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

Checklist básico de reforço

Quando seu llama-server for 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 encerre TLS em um proxy reverso,
• restrinja a concorrência com --parallel para proteger a latência sob carga.

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

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

Endpoints de chat são melhores quando o modelo tem um modelo 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 de chat ajustado,
• testar usando a interface Web do servidor antes de integrá-lo em um app.

Você atinge a falta de memória

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

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

É lento em CPU

Comece com:

• --threads igual aos núcleos físicos,
• tamanhos de lote moderados,
• validando que instalou uma construção que corresponde à sua máquina (características da CPU e backend).

Referências

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