KoboldCpp: instalar, configurar (GGUF, ROCm, API) — y comparación con Ollama

#¿Por qué KoboldCpp?

KoboldCpp es un fork de llama.cpp empaquetado en un solo ejecutable autónomo. Descargas un archivo, lo ejecutas y tienes inmediatamente una interfaz web de chat en tu navegador y una API HTTP. Ningún demonio que instalar, ninguna dependencia de Python que gestionar, ningún gestor de modelos propietario: indicas al binario un archivo GGUF descargado de Hugging Face y eso es todo.

Frente a Ollama, la diferencia de filosofía es clara. Ollama gestiona un catálogo de modelos, un daemon en segundo plano (en http://localhost:11434) y un formato de empaquetado propio. KoboldCpp, en cambio, no gestiona nada: ejecuta directamente el GGUF que le proporcionas. Esto lo hace ideal cuando quieres probar una cuantización concreta descargada manualmente, cuando estás en una máquina en la que no puedes instalar nada o cuando tu GPU es de AMD y tiene poca compatibilidad con otras herramientas.

Binario único

Un solo archivo ejecutable, portátil, sin instalación ni derechos de administrador.

GGUF directo

Carga cualquier .gguf descargado de Hugging Face, sin conversión.

Soporte de primer nivel para AMD

Compilaciones específicas de ROCm y un backend Vulkan que realmente aprovechan las Radeon.

Todo incluido

Interfaz web KoboldAI Lite + API (nativa y compatible con OpenAI) en el mismo binario.

#Prerrequisitos

KoboldCpp funciona en Windows, Linux y macOS. Puede funcionar solo con la CPU, pero una GPU acelera mucho la inferencia. El punto clave, como en cualquier motor de ejecución GGUF, es la VRAM disponible: determina el tamaño del modelo y la cuantización que podrás cargar por completo en la tarjeta.

RAM del sistema

8 GB como mínimo para un modelo pequeño en CPU, 16 GB para trabajar con comodidad, 32 GB para descargar parte de los modelos grandes en la RAM del sistema.

VRAM (referencias Q4_K_M)

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

GPU NVIDIA

Compilaciones para CUDA. RTX 3060 12GB (entrada), 4070 12GB, 4080 16GB, 4090 24GB.

GPU AMD

Versiones compiladas para ROCm (Radeon RX 6000/7000) o backend Vulkan universal.

Un archivo GGUF

Descargar de Hugging Face (por ejemplo, de bartowski, uno de los principales proveedores de modelos cuantizados en formato GGUF).

#Descargar el binario

Todo se hace desde las versiones publicadas en GitHub del proyecto (LostRuins/koboldcpp). Elige el binario adecuado para tu sistema operativo y tu GPU: no hay instalador, solo un archivo al que debes dar permisos de ejecución.

1. 01
   Abrir la sección de versiones

   Visita github.com/LostRuins/koboldcpp/releases y localiza la última versión estable.
2. 02
   Elegir el archivo correcto

   Windows NVIDIA: koboldcpp.exe (build CUDA). Windows sin NVIDIA: koboldcpp_nocuda.exe (usa Vulkan/CLBlast). Linux: koboldcpp-linux-x64. AMD bajo Linux: el build ROCm koboldcpp-linux-x64-rocm (ver la sección AMD).
3. 03
   Hacer ejecutable (Linux/macOS)

   Descarga y otorga permiso de ejecución al archivo antes de lanzarlo.

# 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

#Cargar un GGUF y conversar

El funcionamiento básico se resume en un comando: pasas la ruta del archivo GGUF mediante --model. KoboldCpp inicia un servidor local y abre (o te indica) la URL de la interfaz web, por defecto 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

Ruta al archivo .gguf que se va a cargar.

--gpulayers

Número de capas transferidas a la GPU. 999 = todas las que caben en la VRAM.

--contextsize

Tamaño de la ventana de contexto en tokens (por ejemplo, 4096, 8192, 16384).

--port

Puerto de escucha (5001 por defecto).

--host

Dirección de escucha. 0.0.0.0 para exponer el servidor en la red local.

Una vez iniciado, abre http://localhost:5001 en tu navegador: te lleva a KoboldAI Lite, una interfaz de chat completa con historial, ajustes de sampling y modos (chat, instruct, escritura). No es necesario instalar nada más.

#GPU AMD: ROCm y Vulkan

Es el terreno donde KoboldCpp se distingue más de Ollama. Existen dos vías para acelerar en una Radeon, según tu sistema y tu tarjeta.

#La ruta ROCm (Linux, rendimiento máximo)

ROCm es la pila de cálculo de GPU de AMD, equivalente a CUDA. El proyecto proporciona builds ROCm dedicados que ofrecen las mejores prestaciones en Radeon RX 6000/7000. Es necesario que ROCm esté instalado en el sistema, luego se ejecuta el binario ROCm exactamente como los demás.

# 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

#La vía Vulkan (universal, sencilla)

Si ROCm te parece incómodo o no está disponible (Windows, tarjeta demasiado antigua, iGPU), el backend Vulkan es una excelente alternativa. Es independiente del fabricante: funciona en AMD, Intel y NVIDIA sin pila de cálculo específica, a costa de un ligero descenso de rendimiento en comparación con ROCm o CUDA.

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

#Contexto y offloading

Dos ajustes determinan si tu modelo cabe en la GPU y a qué velocidad responde: el número de capas descargadas en la GPU y el tamaño del contexto. Ajustarlos bien evita que parte del modelo tenga que pasar a la RAM, lo que hace caer la velocidad.

#Offloading de capas (--gpulayers)

Un modelo está compuesto por capas (layers). Cada capa colocada en VRAM se procesa en la GPU; las demás se ejecutan en la CPU. --gpulayers 999 intenta ponerlo todo en la GPU. Si la tarjeta no tiene suficiente VRAM, reduce este número: el modelo se distribuye entonces entre GPU y CPU (offloading parcial), con un funcionamiento más lento, pero viable.

Todo entra en VRAM

--gpulayers 999, velocidad máxima, todo el modelo en el GPU.

VRAM insuficiente

Reduce el valor (por ejemplo, 20, 30) hasta que la carga se complete sin saturar la tarjeta.

Sin GPU

--gpulayers 0, todo en la CPU: lento, pero funciona en cualquier equipo.

#Ventana de contexto (--contextsize)

El contexto es la cantidad de texto (en tokens) que mantiene el modelo en memoria: prompt de sistema, historial y pregunta. Cuanto mayor sea, más VRAM ocupará el caché KV. No aumentes el contexto más allá de lo que necesites: 4096 a 8192 son suficientes para conversaciones normales, 16384+ para analizar documentos largos.

#API y interfaz web integradas

KoboldCpp expone dos API en el mismo puerto (5001 por defecto): su propia API nativa KoboldAI y una API compatible con OpenAI en /v1. Esta última te permite conectar KoboldCpp como backend de cualquier herramienta que use el protocolo OpenAI, exactamente como un endpoint de Ollama o de 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."}
    ]
  }'

Desde Python, la compatibilidad con OpenAI permite reutilizar el SDK oficial simplemente cambiando la URL base y agregando una clave ficticia.

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)

Interfaz web

KoboldAI Lite en http://localhost:5001 : chat, muestreo avanzado, personajes, memoria.

API OpenAI

Punto de acceso /v1/chat/completions para conectar Open WebUI, scripts o agentes.

API nativa

Endpoints de KoboldAI para un control muy fino del sampling y de la generación.

#Solución de problemas

Carga que falla en AMD

Tarjeta no reconocida por ROCm: configura HSA_OVERRIDE_GFX_VERSION con una arquitectura similar (por ejemplo, 10.3.0) o cambia a --usevulkan.

Generación muy lenta

Parte del modelo pasa a ejecutarse en la CPU. Reduce --contextsize, disminuye --gpulayers para evitar la saturación o baja un nivel de cuantización (Q5 → Q4_K_M).

«out of memory» al iniciar

VRAM saturada por el modelo + la caché KV. Reduce el contexto o el offloading, o elige una cuantización más ligera.

Puerto ya en uso

Cambia con --port (por ejemplo --port 5002) si 5001 está ocupado.

Acceso desde otra máquina

Agrega --host 0.0.0.0 para escuchar en la red local y abre el puerto en el firewall.

En resumen, KoboldCpp es la opción práctica cuando quieres evitar cualquier instalación, tener un control directo sobre el archivo GGUF y el offloading, o simplemente aprovechar por fin de verdad una tarjeta AMD. Para disponer de un catálogo de modelos y una integración con el sistema lista para usar, Ollama sigue siendo más cómodo; para la portabilidad y el ajuste fino, KoboldCpp gana.

#Para ir más allá

Estas guías complementan esta y cubren los componentes relacionados:

Ollama con GPU AMD (ROCm)

La otra opción para AMD, con Ollama, para comparar ROCm en los dos ecosistemas.

Elegir tu cuantización (Q4, Q5, Q8, FP16)

Para equilibrar tamaño del modelo, VRAM y calidad antes de descargar un GGUF.

llama-server: una API OpenAI local con llama.cpp

La alternativa más cercana, basada también en llama.cpp, si das prioridad a la API.