KoboldCpp: guia completo para o runtime local de LLM em único binário

KoboldCpp é um arquivo único LLM local runtime construído sobre o llama.cpp. Baixe um único binário, aponte-o para um modelo GGUF e você obterá imediatamente uma interface de chat baseada em navegador e uma API REST compatível com OpenAI — sem gerenciador de pacotes, sem daemon para configurar e sem etapa de instalação necessária. Ele roda no Windows, macOS e Linux, com aceleração opcional por GPU via CUDA, Metal, Vulkan ou OpenCL.

Baixando o KoboldCpp

As versões são publicadas na página de versões do GitHub do KoboldCppCada versão inclui binários específicos para cada plataforma; escolha aquele que corresponde ao seu hardware.

Windows

Baixar koboldcpp.exe para suporte a GPU NVIDIA (as bibliotecas CUDA estão embutidas — nenhuma instalação separada do toolkit CUDA é necessária, apenas o driver padrão de exibição da NVIDIA). Se você não possui uma GPU NVIDIA, baixe koboldcpp_nocuda.exe em vez disso. Ao clicar duas vezes no arquivo .exe, abre-se um assistente gráfico no qual você pode navegar até o arquivo do modelo e configurar as opções antes de iniciar o servidor. Para ignorar o assistente e iniciar diretamente pela linha de comando, utilize a flag --skiplauncher .

macOS

Baixe o binário para macOS na página de versões (normalmente denominado koboldcpp_mac ou distribuído como um arquivo .dmg). A aceleração por GPU via Metal está incluída automaticamente — nenhuma flag adicional é necessária; o KoboldCpp detecta automaticamente os chips Apple Silicon e usa o Metal por padrão. Na primeira execução, o macOS pode exibir um aviso informando que o binário foi criado por um desenvolvedor não identificado; clique com o botão direito e selecione 'Abrir' para contornar o Gatekeeper.

Linux

Baixe o binário para Linux e torne-o executável:

chmod +x koboldcpp
./koboldcpp --model /caminho/para/modelo.gguf

Os binários pré-compilados para Linux incluem suporte para CPU e Vulkan. Para suporte a CUDA em placas NVIDIA, procure um ativo da versão com sufixo cu no nome do arquivo ou compile a partir do código-fonte usando make LLAMA_CUDA=1. Caso seu driver seja muito antigo para a versão de CUDA embutida, a versão com suporte a Vulkan é uma alternativa confiável.

Obtendo um modelo GGUF

O KoboldCpp carrega arquivos GGUF diretamente — o mesmo formato utilizado pelo llama.cpp e pelo Ollama. A principal fonte é o Hugging Face; busque pelo nome do modelo seguido de 'GGUF'. Antes de baixar, utilize o Calculadora de VRAM para confirmar se o modelo caberá na sua GPU com o tamanho de contexto escolhido. Níveis de quantização importantes:

Iniciando o KoboldCpp

O comando mínimo em qualquer plataforma:

./koboldcpp --model /caminho/para/modelo.gguf

Isso inicia o servidor em http://localhost:5001. Abra essa URL no seu navegador para acessar a interface web.

Windows — Assistente gráfico

Clique duas vezes em koboldcpp.exe. A janela do assistente permite navegar até o arquivo do modelo, definir o número de camadas na GPU, o tamanho do contexto e o backend, sem precisar usar a linha de comando. Clique em Iniciar quando terminar; uma janela de terminal será aberta mostrando os logs do servidor e a interface web será lançada automaticamente no navegador.

Linha de comando (todas as plataformas)

Um comando típico de inicialização com descarga para GPU, tamanho de contexto personalizado e porta explícita:

./koboldcpp 
  --model ./models/llama3-8b-q4_k_m.gguf 
  --gpulayers 32 
  --contextsize 8192 
  --port 5001

Referência das principais flags:

Interface web e API compatível com OpenAI

Após iniciar, o KoboldCpp expõe duas interfaces na mesma porta:

• Interface web — http://localhost:5001Uma interface completa de geração de texto com modos de história, bate-papo e instruções. Suporta modelos de prompt, memória, notas do autor e campos de informações sobre o mundo, herdados do projeto KoboldAI.
• API KoboldAI — http://localhost:5001/api/v1Usada por interfaces front-end como SillyTavern e Agnaistic.
• API compatível com OpenAI — http://localhost:5001/v1Implementa /v1/chat/completions e /v1/completions. Qualquer cliente que aceite uma URL base personalizada funciona, incluindo LangChain, o SDK Python da OpenAI e a maioria dos aplicativos de chat de código aberto.

Para configurar o SDK Python da OpenAI para usar o KoboldCpp:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # O KoboldCpp não exige uma chave de API por padrão
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Olá"}]
)

Descarga para GPU: escolhendo o valor correto para --gpulayers

Cada camada transformer transferida para a GPU retira o processamento da CPU e aumenta drasticamente a taxa de tokens por segundo. A contrapartida é o consumo de VRAM. O número total de camadas de um modelo é fixo pela sua arquitetura — valores comuns são 32 para modelos de 7B/8B, 40 para modelos de 13B e 80 para modelos de 70B. Cada camada consome aproximadamente uma parcela igual da memória total da GPU ocupada pelo modelo.

Abordagem prática:

1. Use a Calculadora de VRAM calculadora de camadas para estimar quantas camadas cabem no tamanho de contexto desejado.
2. Comece com --gpulayers 999 para tentar a transferência completa para a GPU. O KoboldCpp ajusta automaticamente esse valor ao número real de camadas do modelo.
3. Se você receber um erro de memória insuficiente ao iniciar, reduza esse valor e tente novamente. O log do servidor exibe a alocação por camada para ajudá-lo a calibrar.

A transferência parcial para a GPU é suportada e útil — mesmo transferir metade das camadas de um modelo grande proporciona uma melhoria significativa de velocidade em comparação com a inferência puramente na CPU. Se você não tem certeza de qual GPU combinar com um determinado modelo, consulte a melhor Placas de vídeo para LLMs locais guia e o divisão dos requisitos de VRAM por modelo.

Tamanho do contexto e configurações de desempenho

Tamanho do contexto (--contextsize) é o fator isolado mais importante no consumo de VRAM além dos pesos do modelo. Um modelo de 7B em Q4_K_M usa cerca de 4 GB apenas para os pesos; estender o contexto de 4096 para 32768 tokens pode acrescentar vários gigabytes adicionais ao cache KV. Ative --flashattention para reduzir a ocupação de memória do cache KV — isso é particularmente eficaz em contextos muito longos e não compromete a qualidade da saída.

Outras configurações que afetam a velocidade:

• --threadsPara inferência exclusivamente na CPU, defina este valor próximo ao número de núcleos físicos do seu processador, não ao número lógico (com hyperthreading).
• --batchsizeValores maiores (por exemplo, 512) melhoram a velocidade de processamento do prompt, mas aumentam o pico de uso de VRAM durante a etapa de prefill.
• --smartcontextQuando o contexto fica cheio, o KoboldCpp desloca os tokens mais antigos em vez de interromper a geração — útil para sessões interativas prolongadas.

KoboldCpp vs Ollama vs llama.cpp

Todos os três são construídos sobre o mesmo mecanismo llama.cpp e suportam modelos GGUF. As diferenças residem no fluxo de trabalho e na interface.

Escolha o KoboldCpp se você deseja uma configuração sem instalação, uma interface integrada de histórias/conversas ou compatibilidade com front-ends do KoboldAI, como o SillyTavern.
Escolha o Ollama se você deseja uma biblioteca de modelos gerenciada, um systemd serviço ou uma integração mais estreita com a CLI — consulte o Guia completo do Ollama para um guia completo.
Escolha diretamente o llama.cpp se você está desenvolvendo uma integração personalizada ou precisa das funcionalidades mais recentes da versão principal (upstream) antes que elas estejam disponíveis em wrappers secundários (downstream).

Se você ainda está decidindo se deseja hospedar localmente ou usar uma API hospedada, o calculadora de ponto de equilíbrio entre autohospedagem e API pode ajudá-lo a modelar o ponto de equilíbrio entre os custos.

Perguntas frequentes

O KoboldCpp exige a instalação separada dos drivers CUDA?

No Windows, o arquivo koboldcpp.exe inclui as bibliotecas de tempo de execução CUDA, portanto, basta ter o driver padrão da NVIDIA para exibição — nenhuma instalação adicional do toolkit CUDA é necessária. No Linux, as compilações CUDA normalmente fazem link com o tempo de execução CUDA instalado, logo a compatibilidade da versão do driver é essencial; se seu driver for muito antigo, a compilação Vulkan é a alternativa mais simples.

O que significa o parâmetro --gpulayers 0?

Zero camadas na GPU significa que toda a computação ocorre na CPU. Esse é o comportamento padrão quando nenhuma flag relacionada à GPU é definida. A inferência na CPU é muito mais lenta — tipicamente 2–10 tokens/segundo em uma CPU moderna, comparado a 40–100+ tokens/segundo em uma GPU de faixa intermediária —, mas funciona em qualquer máquina, independentemente da presença de GPU.

Posso usar o KoboldCpp como substituto direto da API OpenAI em minha aplicação?

Sim. Configure a URL base do cliente OpenAI como base_url para http://localhost:5001/v1 e use qualquer string não vazia como valor da chave api_key (por padrão, ela não é validada). O campo modelo é aceito, mas ignorado — o modelo GGUF carregado será sempre utilizado. Ambas as funcionalidades de conclusão de conversa (chat completions) e conclusão de texto (text completions) funcionam; endpoints para embeddings e imagens não são suportados.

Como executar dois modelos diferentes simultaneamente?

Cada processo do KoboldCpp gerencia um único modelo. Inicie uma segunda instância com um valor diferente para --port (por exemplo, 5002) apontando para um arquivo GGUF distinto. Não há balanceador de carga embutido; o roteamento entre as instâncias deve ser feito na camada de aplicação.

Por que a geração está mais lenta do que o esperado mesmo com uma GPU?

A causa mais comum é a descarga parcial para a CPU: se o valor de --gpulayers for menor que o número total de camadas do modelo, as camadas restantes serão executadas na CPU, criando um gargalo. Verifique o log de inicialização — o KoboldCpp informa exatamente quantas camadas foram alocadas na GPU e quantas na CPU. Confirme também se o backend correto (CUDA/Metal/Vulkan) aparece na saída de inicialização, e não um fallback para CPU.

É seguro expor o KoboldCpp em uma rede?

Por padrão, o KoboldCpp vincula-se apenas a 127.0.0.1 (localhost). Para expô-lo em uma rede local (LAN), adicione a opção --host 0.0.0.0. Não há autenticação embutida; portanto, expô-lo em redes não confiáveis ou na internet pública não é recomendado, a menos que seja protegido por um proxy reverso com autenticação.