KoboldCpp: instalar, configurar (GGUF, ROCm, API) — e comparação com Ollama

#Por que usar KoboldCpp

KoboldCpp é um fork do llama.cpp empacotado em um único executável autônomo. Você baixa um arquivo, executa-o e tem imediatamente uma interface web de chat no seu navegador, além de uma API HTTP. Nenhum daemon para instalar, nenhuma dependência Python para gerenciar, nenhum gerenciador de modelos proprietário: você aponta o binário para um arquivo GGUF baixado no Hugging Face e é só isso.

Em comparação com o Ollama, a diferença de filosofia é clara. O Ollama gerencia um catálogo de modelos, um daemon em segundo plano (em http://localhost:11434) e um formato de empacotamento próprio. O KoboldCpp, por sua vez, não gerencia nada: executa diretamente o GGUF que você fornece. Isso o torna ideal quando você quer testar uma versão com uma quantização específica baixada manualmente, quando está em uma máquina em que não pode instalar nada ou quando sua GPU é uma AMD com pouco suporte em outros ambientes.

Binário único

Um único arquivo executável, portátil, sem instalação nem permissões de administração.

GGUF direto

Carrega qualquer .gguf baixado do Hugging Face, sem conversão.

Suporte de primeira classe à AMD

Builds dedicadas para ROCm e backend Vulkan que realmente aproveitam as Radeon.

Tudo incluído

Interface web KoboldAI Lite + API (nativa e compatível com OpenAI) no mesmo binário.

#Pré-requisitos

KoboldCpp funciona no Windows, Linux e macOS. Funciona apenas com CPU, mas uma GPU acelera bastante a inferência. O ponto-chave, como em qualquer runner GGUF, é a VRAM disponível: ela determina o tamanho do modelo e a quantização que você poderá carregar inteiramente na placa.

RAM do sistema

No mínimo 8 GB para um modelo pequeno executado na CPU, 16 GB para trabalhar com conforto, 32 GB para fazer offload de modelos grandes para a RAM.

VRAM (referências Q4_K_M)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB.

GPU NVIDIA

Builds com CUDA. RTX 3060 12 GB (entrada), 4070 12 GB, 4080 16 GB, 4090 24 GB.

GPU AMD

Versões compiladas com ROCm (Radeon RX 6000/7000) ou backend Vulkan universal.

Um arquivo GGUF

Baixar no Hugging Face (ex.: bartowski, um dos principais fornecedores de versões quantizadas em GGUF).

#Baixar o binário

Tudo é feito a partir das releases do GitHub do projeto (LostRuins/koboldcpp). Você escolhe o binário adequado ao seu sistema operacional e à sua GPU — não há instalador, apenas um arquivo para tornar executável.

1. 01
   Abrir as releases

   Acesse github.com/LostRuins/koboldcpp/releases e localize a última versão estável.
2. 02
   Escolher o arquivo certo

   Windows com NVIDIA: koboldcpp.exe (build CUDA). Windows sem NVIDIA: koboldcpp_nocuda.exe (usa Vulkan/CLBlast). Linux: koboldcpp-linux-x64. AMD no Linux: o build ROCm koboldcpp-linux-x64-rocm (ver a seção AMD).
3. 03
   Tornar executável (Linux/macOS)

   Baixe e dê permissão de execução ao arquivo antes de executá-lo.

# Récupérer le binaire (adaptez l'URL à la dernière release)
wget https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64

# Le rendre exécutable
chmod +x koboldcpp-linux-x64

# Vérifier qu'il se lance
./koboldcpp-linux-x64 --help

#Carregar um GGUF e conversar

O essencial do funcionamento se resume a um comando: você passa o caminho do arquivo GGUF com --model. O KoboldCpp inicia um servidor local e abre (ou informa a você) a URL da interface web, que por padrão é http://localhost:5001.

# Lancer avec un modèle, en offloadant toutes les couches sur le GPU
./koboldcpp-linux-x64 \
  --model ./qwen3.5-9b-instruct-Q4_K_M.gguf \
  --gpulayers 999 \
  --contextsize 8192

--model

Caminho para o arquivo .gguf a ser carregado.

--gpulayers

Número de camadas transferidas para a GPU. 999 = tudo o que cabe na VRAM.

--contextsize

Tamanho da janela de contexto em tokens (ex. 4096, 8192, 16384).

--port

Porta de escuta (5001 por padrão).

--host

Endereço de escuta. 0.0.0.0 para expor na rede local.

Depois de iniciar, abra http://localhost:5001 no seu navegador: você encontrará o KoboldAI Lite, uma interface de chat completa com histórico, configurações de sampling e modos (chat, instruct, escrita). Nenhuma outra instalação é necessária.

#GPU AMD: ROCm e Vulkan

É o campo onde o KoboldCpp se destaca mais em relação a Ollama. Existem duas opções para acelerar em uma Radeon, dependendo do seu sistema e da sua placa.

#O caminho ROCm (Linux, desempenho máximo)

ROCm é a pilha de computação em GPU da AMD, o equivalente ao CUDA. O projeto fornece builds ROCm dedicados que oferecem o melhor desempenho nas Radeon RX 6000/7000. É necessário ter o ROCm instalado no sistema; depois, executa-se o binário ROCm exatamente como os outros.

# Build ROCm dédié
chmod +x koboldcpp-linux-x64-rocm

# Certaines cartes non officiellement supportées nécessitent de forcer
# la version d'architecture GPU (ex. RX 6700 XT -> gfx1030)
export HSA_OVERRIDE_GFX_VERSION=10.3.0

./koboldcpp-linux-x64-rocm \
  --model ./gemma-4-12b-it-Q4_K_M.gguf \
  --usecublas \
  --gpulayers 999 \
  --contextsize 8192

#A via Vulkan (universal, simples)

Se o ROCm desanima você ou não está disponível (Windows, placa muito antiga, iGPU), o backend Vulkan é uma excelente alternativa. Ele é independente do fabricante: funciona em AMD, Intel e NVIDIA sem uma pilha de computação específica, ao custo de uma pequena perda de desempenho em relação ao ROCm ou ao CUDA.

./koboldcpp-linux-x64 \
  --model ./granite-4.2-8b-instruct-Q4_K_M.gguf \
  --usevulkan \
  --gpulayers 999 \
  --contextsize 8192

#Contexto e offloading

Dois ajustes determinam se o seu modelo cabe na GPU e a velocidade com que ele responde: o número de camadas transferidas para a GPU e o tamanho do contexto. Calibrá-los corretamente evita que parte do modelo precise ficar na RAM do sistema, o que faz a velocidade cair.

#Offloading das camadas (--gpulayers)

Um modelo é composto por camadas (layers). Cada camada colocada na VRAM é processada pela GPU; as demais rodam na CPU. --gpulayers 999 tenta colocar tudo na GPU. Se a placa não tiver VRAM suficiente, reduza esse número: o modelo passa a ser distribuído entre GPU e CPU (offloading parcial), com execução mais lenta, mas funcional.

Tudo cabe na VRAM

--gpulayers 999, velocidade máxima, todo o modelo no GPU.

VRAM insuficiente

Reduza o valor (por exemplo, 20 ou 30) até que o carregamento seja concluído sem saturar a placa.

Sem GPU

--gpulayers 0, tudo na CPU: lento, mas funciona em qualquer lugar.

#Tamanho do contexto (--contextsize)

O contexto é a quantidade de texto (em tokens) que o modelo mantém em memória: prompt de sistema, histórico e pergunta. Quanto maior, mais espaço o cache KV ocupa na VRAM. Não aumente o contexto além do necessário: 4096 a 8192 são suficientes para conversas comuns, 16384+ para analisar documentos longos.

#API e interface web integradas

O KoboldCpp expõe duas APIs na mesma porta (5001 por padrão): sua própria API nativa KoboldAI e uma API compatível com OpenAI no caminho /v1. Esta última permite usar o KoboldCpp como backend de qualquer ferramenta que utilize o protocolo OpenAI — exatamente como um endpoint do Ollama ou do llama-server.

curl http://localhost:5001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp",
    "messages": [
      {"role": "user", "content": "Explique le offloading GPU en une phrase."}
    ]
  }'

No Python, a compatibilidade com a OpenAI permite reutilizar o SDK oficial apenas alterando a URL base e inserindo uma chave fictícia.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="koboldcpp",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Bonjour en une phrase."}],
)
print(resp.choices[0].message.content)

Interface web

KoboldAI Lite no http://localhost:5001 : chat, amostragem avançada, personagens, memória.

API OpenAI

Ponto de extremidade /v1/chat/completions para conectar Open WebUI, scripts ou agentes.

API nativa

Endpoints do KoboldAI para um controle muito preciso da amostragem e da geração.

#Solução de problemas

Falha no carregamento em hardware AMD

Placa não reconhecida pelo ROCm: defina HSA_OVERRIDE_GFX_VERSION com uma arquitetura próxima (por exemplo, 10.3.0) ou mude para --usevulkan.

Geração muito lenta

Parte do modelo está sendo executada na CPU por não caber na GPU. Reduza --contextsize, diminua --gpulayers para evitar a saturação ou passe para uma quantização menor (Q5 → Q4_K_M).

“out of memory” na inicialização

VRAM saturada pelo modelo + o cache KV. Reduza o contexto ou o offloading, ou escolha uma quantização mais leve.

Porta já em uso

Mude com --port (ex. --port 5002) se o 5001 estiver ocupado.

Acesso a partir de outra máquina

Adicione --host 0.0.0.0 para escutar na rede local e abra a porta no firewall.

Em resumo, KoboldCpp é a escolha prática quando você quer dispensar a instalação, ter controle direto sobre o arquivo GGUF e o offloading, ou simplesmente fazer uma placa AMD finalmente trabalhar de verdade. Para um catálogo de modelos e uma integração com o sistema pronta para uso, Ollama continua sendo mais confortável; para portabilidade e ajuste fino, KoboldCpp ganha.

#Para se aprofundar

Esses guias dão continuidade a este e abordam componentes relacionados:

Ollama com GPU AMD (ROCm)

A outra abordagem da AMD, do lado Ollama, para comparar o ROCm nos dois ecossistemas.

Escolher sua quantização (Q4, Q5, Q8, FP16)

Para equilibrar tamanho do modelo, VRAM e qualidade antes de baixar um GGUF.

llama-server: uma API OpenAI local com llama.cpp

A alternativa mais próxima, baseada no mesmo llama.cpp, se você priorizar a API.