llama-server: API OpenAI local com llama.cpp

#Por que usar llama-server?

Ollama, LM Studio e Jan usam todos o mesmo motor nos bastidores: llama.cpp. Esse motor inclui seu próprio servidor HTTP, llama-server, que não precisa de nenhuma dessas camadas. Você indica um arquivo GGUF e obtém uma API e uma interface web. Nada além disso.

O benefício não é meramente estético. Enquanto o Ollama decide por você o número de camadas enviadas à GPU, o tamanho do contexto e como dividir o modelo, o llama-server expõe cada parâmetro na linha de comando. Você vê e ajusta o que acontece. É o modo “manual” da IA local — mais verboso, mas sem caixa-preta.

API compatível com OpenAI

Pontos de acesso /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings. Qualquer cliente OpenAI pode se conectar sem alterações.

Controle do offloading

--n-gpu-layers define exatamente quantas camadas são carregadas na VRAM. É indispensável quando o modelo excede a capacidade de memória da sua placa.

Interface web integrada

Um chat servido diretamente na raiz do servidor, sem precisar instalar Open WebUI nem Docker.

Sem dependência pesada

Um único binário (algumas dezenas de MB). Nem Python, nem contêiner, nem serviço de sistema são obrigatórios.

Batching e paralelismo

Batching contínuo ativado por padrão, várias requisições simultâneas por meio de slots.

#Pré-requisitos

Um arquivo GGUF

Formato do llama.cpp. Disponível no Hugging Face, ou baixado diretamente pelo llama-server via -hf (ver abaixo).

VRAM ou RAM

Em Q4_K_M, considere aproximadamente 2 GB para um 3B, 5 GB para um 7B, 9 GB para um 14B, 19 GB para um 32B e 40 GB para um 70B.

Um GPU (fortemente recomendado)

RTX 3060 de 12 GB para começar, RTX 4070/4080 na faixa intermediária, RTX 4090 de 24 GB ou Mac M4 Pro para modelos grandes. Usar apenas a CPU também funciona, mas lentamente.

Um terminal

O llama-server é controlado pela linha de comando. Nada impossível de superar, mas não é um aplicativo que você abre com um clique duplo, como o LM Studio.

#1. Obter llama-server

Três opções, da mais rápida à que oferece melhor desempenho. No macOS, o Homebrew instala o binário com apenas um comando:

brew install llama.cpp

# le binaire s'appelle llama-server
llama-server --version

No Windows e no Linux, a forma mais simples é baixar um binário pré-compilado das releases oficiais do llama.cpp no GitHub (escolha a variante correspondente ao seu hardware: CUDA para NVIDIA, Vulkan para uma GPU genérica ou CPU).

https://github.com/ggml-org/llama.cpp/releases

Para obter o máximo de tokens por segundo, compile a partir do código-fonte com o backend do seu GPU. Exemplo para NVIDIA com CUDA:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# le binaire se trouve dans build/bin/
./build/bin/llama-server --version

#2. Executar com um GGUF usando um único comando

O comando mínimo aponta para um modelo e inicia o servidor. Aqui, um Qwen 3.5 9B em Q4_K_M (a opção de referência para 8 GB em 2026, com contexto de 256k) com todas as camadas enviadas para a GPU:

llama-server -m ./qwen3.5-9b-instruct-q4_k_m.gguf -ngl 99 -c 8192

-m

Caminho para o arquivo GGUF a ser servido.

-ngl 99

Número de camadas transferidas para a GPU. 99 = « todas » (o modelo tem menos camadas; o excedente é ignorado sem erro).

-c 8192

Tamanho do contexto em tokens. Por padrão, geralmente é 4096; ajuste conforme suas necessidades e sua VRAM.

Você não tem o arquivo na mão? O llama-server pode baixá-lo diretamente do Hugging Face e armazená-lo no cache, como um ollama pull mais integrado:

llama-server -hf bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M -ngl 99 -c 8192

Uma vez iniciado, o servidor escuta por padrão em http://127.0.0.1:8080. Verifique se ele está ativo:

curl http://localhost:8080/health
# {"status":"ok"}

#3. A API compatível com a OpenAI: conectar qualquer aplicativo

Esse é o grande trunfo do llama-server. Ele usa o protocolo da OpenAI, então qualquer ferramenta projetada para a API da OpenAI funciona bastando mudar a URL base. Uma chamada direta de chat com curl:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Explique le format GGUF en une phrase."}
    ],
    "temperature": 0.7
  }'

O campo model é livre: o llama-server serve apenas um modelo por vez e, em grande parte, ignora esse valor. No SDK Python da OpenAI, basta redirecionar base_url para o seu servidor. A chave de API pode ser qualquer string se você não tiver definido --api-key:

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="local",
    messages=[
        {"role": "user", "content": "Donne-moi trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

/v1/chat/completions

Modo de conversa, com aplicação automática do template de chat do modelo.

/v1/completions

Complementação bruta de texto, sem formatação de papéis.

/v1/models

Lista o modelo carregado — útil para clientes que primeiro consultam os modelos disponíveis.

/v1/embeddings

Gera embeddings se o servidor for iniciado com --embedding (útil para um RAG feito por você).

#4. n-gpu-layers: o controle preciso de offloading que o Ollama oculta

Um modelo é uma pilha de camadas (layers). Cada camada enviada para a VRAM é calculada pelo GPU, muito rápido; as que permanecem na RAM são calculadas pelo CPU, lentamente. --n-gpu-layers (ou -ngl) define quantas camadas vão para o GPU. Esse é o ajuste mais importante para a velocidade.

-ngl 99

Tudo na GPU. Configuração a buscar se o modelo couber inteiramente na VRAM. Velocidade máxima.

-ngl 20

Offloading parcial: 20 camadas na GPU, o restante na CPU. Uma solução de compromisso quando o modelo excede a capacidade da VRAM.

-ngl 0

Tudo na CPU. Lento, mas permite rodar um modelo muito maior do que a sua placa comporta.

A estratégia: aumentar -ngl o máximo possível sem saturar a VRAM. Um 14B em Q4 (≈9 GB) cabe inteiramente em uma RTX 3060 de 12 GB com -ngl 99. Um Qwen 3.8 27B em Q4 (≈18 GB) não cabe; nessa mesma placa, fazemos offload parcial — por exemplo, -ngl 40 — e aceitamos uma redução de velocidade.

# Qwen 3.8 27B Q4 (~18 Go) sur un GPU 12 Go : une partie sur GPU, le reste sur CPU
llama-server -m ./qwen3.8-27b-instruct-q4_k_m.gguf -ngl 40 -c 4096

Para monitorar o que realmente cabe na VRAM durante o carregamento, fique de olho no nvidia-smi em outra janela:

nvidia-smi -l 1

#5. Interface web incluída

Não é preciso usar Open WebUI nem Docker para conversar: o llama-server disponibiliza uma interface de chat diretamente na raiz. Basta abrir o endereço do servidor em um navegador.

http://localhost:8080

Você encontrará ali um chat completo: histórico de conversa, ajuste da temperatura e dos parâmetros de amostragem, recurso de prompt de sistema e renderização em Markdown. Isso é suficiente para uso pessoal diário, sem instalar nenhuma camada adicional.

#Quando preferir llama-server a Ollama (e quando continuar com Ollama)

llama-server e Ollama executam o mesmo motor. A escolha é uma questão de controle versus comodidade.

Escolha o llama-server

Quando você quer ajustar com precisão o offloading, testar um GGUF específico de um determinado quantizador, evitar um daemon permanente ou implantar um único binário sem dependências em um servidor.

Escolha o llama-server

Quando um modelo excede a capacidade da sua VRAM: o controle direto de -ngl e das opções de memória faz a diferença entre “inutilizável” e “lento, mas funcional”.

Permaneça com o Ollama

Quando você quer alternar entre vários modelos dinamicamente, sem reiniciar processos, gerenciar uma biblioteca com ollama pull/list ou carregar e descarregar modelos automaticamente conforme a demanda.

Permaneça com o Ollama

Quando várias aplicações acessam modelos diferentes na mesma porta 11434: o Ollama roteia as solicitações e alterna entre os modelos para você, enquanto o llama-server executa um único modelo por processo.

#Solução de problemas

Erro 'CUDA out of memory' ao carregar

O valor de -ngl está alto demais para a VRAM. Reduza-o (offloading parcial), diminua -c ou passe para uma quantização mais leve (Q4_K_M em vez de Q5/Q8).

O GPU não está sendo usado

O binário pode ser a variante para CPU. Verifique se você está usando um build CUDA/Metal/Vulkan e se -ngl é maior que 0. nvidia-smi deve mostrar VRAM ocupada.

Respostas incoerentes ou tags visíveis

O template de chat não está sendo aplicado. Reinicie com --jinja para usar o template embutido no GGUF.

O aplicativo cliente não encontra o modelo

Alguns clientes consultam /v1/models primeiro. Crie um alias com -a e preencha esse nome exato no campo model da sua aplicação.

Contexto truncado / respostas cortadas

-c é muito pequeno. Aumente o tamanho do contexto, lembrando que um grande contexto consome mais VRAM.

#Para se aprofundar

llama-server mostra todo o seu valor com um llama.cpp bem compilado e um GGUF bem escolhido. Estes guias do site complementam a configuração:

Compilar llama.cpp com CUDA

Para um binário otimizado para NVIDIA e o máximo de tokens por segundo na sua placa.

Q4, Q5, Q8: qual quantização escolher

Para equilibrar qualidade, velocidade e VRAM antes de baixar um GGUF.

llama.cpp vs vLLM vs Exllama

Para situar o llama-server em relação aos outros motores de inferência de acordo com suas necessidades de taxa de processamento.