KoboldCpp: guía completa sobre el entorno de ejecución local de LLM en un solo binario

KoboldCpp es un archivo único LLM local que funciona sobre llama.cpp. Descargue un solo ejecutable, apúntelo a un modelo GGUF y obtendrá inmediatamente una interfaz de chat basada en navegador y una API REST compatible con OpenAI —sin gestor de paquetes, sin demonio que configurar y sin necesidad de instalar nada. Se ejecuta en Windows, macOS y Linux, con aceleración opcional por GPU mediante CUDA, Metal, Vulkan u OpenCL.

Descargar KoboldCpp

Las versiones se publican en la página de versiones de GitHub de KoboldCpp. Cada versión incluye binarios específicos para cada plataforma; seleccione el que coincida con su hardware.

Windows

Descargar koboldcpp.exe para soporte de GPU NVIDIA (las bibliotecas CUDA están integradas: no se requiere instalar por separado el kit de herramientas CUDA, solo el controlador estándar de visualización de NVIDIA). Si no dispone de una GPU NVIDIA, descargue koboldcpp_nocuda.exe en su lugar. Al hacer doble clic en el archivo .exe se abre un lanzador gráfico donde puede buscar su archivo de modelo y configurar los parámetros antes de iniciar el servidor. Para omitir el lanzador e iniciar directamente desde la línea de comandos, pase la bandera --skiplauncher .

macOS

Descargue el binario para macOS desde la página de versiones (normalmente denominado koboldcpp_mac o distribuido como un archivo .dmg). La aceleración por GPU mediante Metal está incluida automáticamente: no se necesita ninguna bandera adicional; KoboldCpp detecta automáticamente los chips Apple Silicon y utiliza Metal de forma predeterminada. En el primer inicio, macOS podría advertirle de que el binario proviene de un desarrollador no identificado; haga clic derecho → Abrir para omitir Gatekeeper.

Linux

Descargue el binario para Linux y otórguele permisos de ejecución:

chmod +x koboldcpp
./koboldcpp --model /ruta/a/modelo.gguf

Los binarios precompilados para Linux incluyen soporte para CPU y Vulkan. Para usar CUDA en tarjetas NVIDIA, busque un recurso de versión cuyo nombre de archivo contenga el sufijo cu o compile desde el código fuente con el comando make LLAMA_CUDA=1. Si su controlador es demasiado antiguo para la versión de CUDA incluida, la compilación con Vulkan constituye una alternativa fiable.

Obtener un modelo GGUF

KoboldCpp carga directamente archivos GGUF —el mismo formato utilizado por llama.cpp y Ollama. La fuente principal es Hugging Face; busque el nombre del modelo seguido de «GGUF». Antes de descargarlo, utilice la Calculadora de VRAM para confirmar que el modelo cabrá en su GPU con el tamaño de contexto elegido. Niveles de cuantización importantes:

Iniciar KoboldCpp

El comando mínimo en cualquier plataforma es:

./koboldcpp --model /ruta/a/modelo.gguf

Esto inicia el servidor en http://localhost:5001. Abra esa URL en su navegador para acceder a la interfaz web.

Windows — Lanzador gráfico

Haga doble clic en koboldcpp.exe. La ventana del lanzador le permite buscar un archivo de modelo, establecer las capas procesadas por GPU, el tamaño del contexto y el backend, sin necesidad de usar la línea de comandos. Haga clic en Iniciar cuando haya terminado; se abrirá una ventana de terminal que mostrará los registros del servidor y la interfaz web se iniciará automáticamente en el navegador.

Línea de comandos (todas las plataformas)

Un comando típico de inicio con descarga a la GPU, tamaño de contexto personalizado y puerto explícito:

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

Referencia de banderas clave:

Interfaz web y API compatible con OpenAI

Una vez en ejecución, KoboldCpp expone dos interfaces desde el mismo puerto:

• Interfaz web — http://localhost:5001Una interfaz completa de generación de texto con modos de historia, chat e instrucciones. Admite plantillas de indicaciones (prompts), memoria, notas del autor y campos de información del mundo heredados del proyecto KoboldAI.
• API de KoboldAI — http://localhost:5001/api/v1Utilizada por interfaces gráficas (frontends) como SillyTavern y Agnaistic.
• API compatible con OpenAI — http://localhost:5001/v1Implementa /v1/chat/completions y /v1/completions. Cualquier cliente que acepte una URL base personalizada es compatible, incluidos LangChain, el SDK de Python de OpenAI y la mayoría de las aplicaciones de chat de código abierto.

Para configurar el SDK de Python de OpenAI para que apunte a KoboldCpp:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # KoboldCpp no requiere una clave API de forma predeterminada
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Hola"}]
)

Descarga a la GPU: elegir el valor adecuado para --gpulayers

Cada capa transformer descargada a la GPU traslada el procesamiento desde la CPU y aumenta drásticamente los tokens por segundo. El compromiso es el consumo de VRAM. El número total de capas de un modelo está fijado por su arquitectura: valores comunes son 32 para modelos de 7B/8B, 40 para modelos de 13B y 80 para modelos de 70B. Cada capa consume aproximadamente una parte igual de la memoria GPU total del modelo.

Enfoque práctico:

1. Usa la Calculadora de VRAM herramienta de estimación de capas GPU
2. Comience con --gpulayers 999 para intentar descargar completamente el modelo a la GPU. KoboldCpp ajusta automáticamente este valor al número real de capas del modelo.
3. Si obtienes un error de memoria insuficiente al iniciar, reduce el valor y vuelve a intentarlo. El registro del servidor muestra la asignación por capa para ayudarte a calibrar.

Se admite y resulta útil la descarga parcial: incluso descargar la mitad de las capas de un modelo grande ofrece una mejora significativa de velocidad frente a la inferencia puramente en CPU. Si no estás seguro de qué GPU combinar con un modelo, consulta la mejor GPUs para LLM locales guía y la desglose de los requisitos de VRAM por modelo.

Tamaño del contexto y ajustes de rendimiento

Tamaño del contexto (--contextsize) es el factor más determinante del consumo de VRAM, además de los pesos del modelo. Un modelo de 7B en cuantización Q4_K_M usa aproximadamente 4 GB para sus pesos; ampliar el contexto de 4096 a 32768 tokens puede añadir varios gigabytes adicionales a la caché KV. Habilita --flashattention --flashattention

Otras opciones que afectan la velocidad:

• --threads: para inferencia exclusivamente en CPU, configúralo cercano al número de núcleos físicos, no al número lógico (con hyperthreading).
• --batchsize: valores mayores (p. ej., 512) mejoran la velocidad de procesamiento de la indicación (prompt), pero incrementan el pico de VRAM durante la fase de prellenado (prefill).
• --smartcontext--smartcontext

KoboldCpp frente a Ollama frente a llama.cpp

Los tres están construidos sobre el mismo motor llama.cpp y admiten modelos GGUF. Las diferencias radican en el flujo de trabajo y la interfaz.

Elija KoboldCpp si desea una configuración sin instalación, una interfaz integrada para historias o chats, o compatibilidad con frontends de KoboldAI como SillyTavern.
Elija Ollama si desea una biblioteca de modelos gestionada, un systemd servicio o una integración más estrecha con la CLI; consulte la Guía completa de Ollama para una guía completa.
Elija llama.cpp directamente si está desarrollando una integración personalizada o necesita las funciones más recientes del repositorio principal antes de que lleguen a los envoltorios secundarios.

Si aún está decidiendo si autoalojar o bien usar una API alojada, la calculadora de punto de equilibrio entre alojamiento propio y API puede ayudarle a modelar el punto de equilibrio de costos.

Preguntas frecuentes

¿Requiere KoboldCpp instalar los controladores CUDA por separado?

En Windows, koboldcpp.exe incluye las bibliotecas de tiempo de ejecución de CUDA, por lo que solo necesita el controlador estándar de NVIDIA para pantalla; no es necesario instalar por separado el kit de herramientas CUDA. En Linux, las versiones compiladas con soporte CUDA suelen vincularse dinámicamente con el tiempo de ejecución CUDA instalado, por lo que la compatibilidad de la versión del controlador es crucial; si su controlador es demasiado antiguo, la versión Vulkan es la alternativa más sencilla.

¿Qué significa el parámetro --gpulayers 0?

Cero capas en GPU significa que todo el cálculo se ejecuta en la CPU. Este es el comportamiento predeterminado cuando no se especifica ninguna bandera relacionada con la GPU. La inferencia en CPU es mucho más lenta —típicamente entre 2 y 10 tokens/segundo en una CPU moderna frente a 40–100+ tokens/segundo en una GPU de gama media—, pero funciona en cualquier equipo, independientemente de la disponibilidad de GPU.

¿Puedo usar KoboldCpp como sustituto directo de la API de OpenAI en mi aplicación?

Sí. Configure la dirección URL base de su cliente OpenAI como base_url a http://localhost:5001/v1 y utilice cualquier cadena no vacía como valor de la clave api_key (por defecto no se valida). El campo modelo se acepta pero se ignora: siempre se usa el archivo GGUF cargado. Funcionan tanto las finalizaciones de chat como las de texto; no se admiten los puntos finales para incrustaciones (embeddings) ni para imágenes.

¿Cómo ejecuto dos modelos diferentes simultáneamente?

Cada proceso de KoboldCpp gestiona un único modelo. Inicie una segunda instancia con un valor distinto de --port (por ejemplo, 5002) apuntando a un archivo GGUF diferente. No existe un equilibrador de carga integrado; debe gestionar el enrutamiento entre instancias a nivel de aplicación.

¿Por qué la generación es más lenta de lo esperado incluso con una GPU?

La causa más habitual es la descarga parcial a la CPU: si el valor de --gpulayers es menor que el número total de capas del modelo, las capas restantes se ejecutan en la CPU y generan un cuello de botella. Revise el registro de inicio: KoboldCpp indica exactamente cuántas capas se asignaron a la GPU y cuántas a la CPU. Asimismo, confirme que en la salida de inicio aparece el backend correcto (CUDA/Metal/Vulkan) y no una alternativa de respaldo basada únicamente en la CPU.

¿Es seguro exponer KoboldCpp en una red?

De forma predeterminada, KoboldCpp se enlaza únicamente a 127.0.0.1 (localhost). Para exponerlo en una red local (LAN), agregue la opción --host 0.0.0.0. No dispone de autenticación integrada, por lo que no se recomienda exponerlo en redes no confiables ni en Internet público, a menos que se use un proxy inverso con autenticación previo al servicio.