¿Qué es GGUF? El formato de archivo de LLM detrás de Ollama y llama.cpp, explicado

GGUF (normalmente expandido como GPT-Generated Unified Format, o Formato Unificado Generado por GPT) es un formato de archivo binario para almacenar modelos de lenguaje grandes: los pesos, el tokenizador y todos los metadatos de configuración en un único archivo autónomo. Es el formato nativo de llama.cpp, y es el que utilizan Ollama, LM StudioKoboldCpp, Jan y la mayoría de otras aplicaciones locales para LLM. Si alguna vez has descargado un archivo con la extensión .gguf, o has extraído un modelo con ollama runollama run

Qué contiene realmente un archivo GGUF

Un archivo GGUF comienza con los cuatro bytes ASCII GGUF, seguidos de un número de versión, una sección de metadatos clave-valor y, después, los tensores propiamente dichos. Los metadatos representan la decisión de diseño más importante: almacenan la arquitectura del modelo, la longitud del contexto, el vocabulario del tokenizador, la plantilla de chat y los detalles de la cuantización como claves con nombre, de modo que un entorno de ejecución pueda cargar cualquier archivo GGUF sin necesidad de un archivo separado config.json o archivos de tokenizador junto con él.

De este diseño se derivan tres consecuencias prácticas:

• Un único archivo constituye el modelo completo. Puedes copiar un archivo .gguf entre máquinas y funcionará directamente. (Los modelos muy grandes a veces se dividen en partes numeradas, como -00001-of-00002.gguf, pero aún así representan un solo modelo lógico.)
• Es asignable a memoria (memory-mappable). Los entornos de ejecución pueden usar mmap el archivo y cargar los pesos por demanda mediante paginación, lo que acelera la carga y permite iniciar modelos más grandes que la RAM disponible.
• La cuantización está integrada en el formato. Un archivo GGUF almacena los pesos ya comprimidos a 2–8 bits por peso, razón por la cual un modelo de 8 mil millones de parámetros puede ocupar solo 4,9 GB en lugar de 16 GB.

Por qué GGUF reemplazó a GGML

Antes de agosto de 2023, llama.cpp utilizaba un formato denominado GGML (llamado así por la biblioteca de tensores subyacente). GGML funcionaba, pero tenía un defecto estructural: su disposición en el archivo era rígida e invariable. Cada vez que llama.cpp incorporaba una nueva característica —nuevas arquitecturas, mejores métodos de cuantización, parámetros de escalado RoPE—, el formato debía modificarse, y todos los archivos de modelos existentes en todos los discos duros dejaban de funcionar. Los usuarios tuvieron que volver a descargar o convertir íntegramente sus colecciones de modelos varias veces en pocos meses.

GGUF, introducido por el proyecto llama.cpp en agosto de 2023, resolvió este problema mediante dos cambios:

• Control de versiones. El archivo declara explícitamente su versión de formato, de modo que los lectores saben exactamente cómo analizarlo.
• Metadatos extensibles basados en pares clave-valor. Nueva información (un campo para arquitectura, una plantilla de chat, un hiperparámetro adicional) simplemente se añade como una nueva clave. Los archivos antiguos sin esa clave siguen cargando correctamente; los nuevos archivos que la incluyen funcionan en entornos de ejecución actualizados. Nada se rompe retroactivamente.

llama.cpp eliminó el soporte para GGML poco después, y el ecosistema lo siguió. Hoy en día, GGML subsiste únicamente como nombre de la biblioteca de tensores subyacente; si encuentras un archivo de modelo con extensión .ggml o .bin del año 2023, no se cargará en ninguna herramienta actual, por lo que deberías descargar en su lugar una versión en formato GGUF.

Cómo interpretar los sufijos de cuantización

Cada nombre de archivo GGUF incluye un sufijo como Q4_K_M que indica el grado de compresión aplicado a los pesos. El patrón es el siguiente:

• El número tras la letra Q indica aproximadamente los bits por peso: Q4 ≈ 4 bits, Q8 ≈ 8 bits. Menos bits implican un archivo más pequeño y una calidad inferior.
• _K denota los métodos de «cuantización k» más recientes, que destinan bits adicionales a los tensores más críticos para la calidad de salida. A igual tamaño, una cuantización K supera a la versión anterior.
• _S / _M / _L (pequeño/mediano/grande) son variantes dentro de una misma familia K — _M conserva algunos tensores especialmente sensibles con mayor precisión que _S.
• _0 (como en Q8_0, Q4_0) indica la antigua y más sencilla cuantización por bloques. Q8_0 sigue siendo ampliamente utilizada porque, a 8 bits, dicho método simple ya es prácticamente sin pérdida; Q4_0 está casi obsoleto: se recomienda preferir prefijos Q4_K_M.
• IQ (por ejemplo,IQ2_M, IQ3_XS…), conocidos como «i-cuantizaciones», construidos mediante una matriz de importancia, diseñados para comprimir modelos por debajo de 4 bits con menos deterioro que las alternativas.
• F16 / BF16 / F32 indican pesos sin cuantizar de 16 o 32 bits —la calidad de referencia, pero con el tamaño máximo.

A continuación se muestra el coste práctico de las opciones más comunes, tomando como ejemplo modelos instruct de clase Llama de 8 mil millones de parámetros (los tamaños son aproximados y varían ligeramente según el modelo):

Dos reglas útiles: la cuantización afecta más a los modelos pequeños que a los grandes (un modelo de 70B en Q3 se mantiene mucho mejor que uno de 8B en Q3), y por debajo de Q4 la curva de calidad cae bruscamente. En caso de duda, Q4_K_M es el valor predeterminado de la comunidad por una razón.

Elegir una cuantización según tu VRAM

La memoria total necesaria es aproximadamente tamaño del archivo + caché de contexto + sobrecarga. Reserve 1–2 GB adicionales al tamaño del archivo para unos pocos miles de tokens de contexto, y más si utiliza contextos largos. El modelo se ejecuta a máxima velocidad cuando toda esa memoria cabe en la VRAM de la GPU; las herramientas basadas en llama.cpp pueden descargar el resto a la RAM del sistema, lo cual sigue funcionando, pero se vuelve considerablemente más lento cuanto más capas se descarguen.

Para cifras exactas sobre un modelo y una longitud de contexto específicos, la Calculadora de VRAM realiza automáticamente los cálculos, y hay un desglose por modelo en Requisitos de VRAM para cada LLM importante. Si está eligiendo hardware en lugar de una cuantización, comience con las mejores GPUs para LLM locales.

GGUF frente a safetensors

Estos dos formatos coexisten porque sirven a entornos de ejecución distintos, no porque uno esté reemplazando al otro.

La decisión depende realmente del software que utilice: las herramientas de escritorio y Ollama requieren GGUF; las pilas de servicio en GPU y cualquier proceso que implique ajuste fino requieren safetensors. Los editores de modelos suelen publicar primero safetensors, y la comunidad los convierte a GGUF en cuestión de días.

De dónde provienen los archivos GGUF

Casi todos los archivos GGUF se alojan en Hugging Face. Algunos laboratorios publican oficialmente GGUF, pero la mayoría provienen de cuantizadores comunitarios —cuentas como bartowski, unsloth, lmstudio-community y ggml-org — que convierten cada nueva versión en todo el rango de cuantizaciones disponibles. Un repositorio llamado, por ejemplo, Meta-Llama-3.1-8B-Instruct-GGUF contendrá un archivo por nivel de cuantización.

También puede convertir usted mismo un modelo mediante las herramientas de llama.cpp: convert_hf_to_gguf.py convierte un modelo de Hugging Face en un GGUF en F16, y el binario llama-quantize (compilado al construir llama.cpp) lo comprime a la cuantización elegida, p. ej. modelo llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Cargar un GGUF en Ollama

Ollama puede descargar repositorios GGUF directamente desde Hugging Face; la cuantización se especifica después de los dos puntos:

ollama run hf.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF:Q4_K_M

Para un archivo que ya tenga en disco, cree un archivo de texto sin formato denominado Modelfile que contenga:

FROM ./my-model.gguf

y luego regístrelo y ejecute:

ollama create my-model -f Modelfile
ollama run my-model

Las versiones actuales de Ollama leen automáticamente la plantilla de chat integrada en los metadatos del GGUF; si un modelo importado genera una salida distorsionada, normalmente la solución consiste en agregar explícitamente una línea TEMPLATE al Modelfile. La guía completa de Ollama explica detalladamente los Modelfiles.

Cargar un GGUF en LM Studio

El método habitual es usar el descargador integrado: abra la pestaña «Descubrir», busque un modelo y LM Studio mostrará las cuantizaciones GGUF disponibles, indicando cuáles son compatibles con su hardware. Para importar un archivo que ya tenga, use la CLI (lms import path/to/model.gguf) o colóquelo en el directorio de modelos de LM Studio —la ruta predeterminada exacta varía según la versión y el sistema operativo, pero la pestaña «Mis modelos» muestra dicha ruta y permite modificarla. Los archivos deben organizarse en una estructura de subcarpetas del tipo editor/nombre-del-modelo/ para que sean reconocidos. Consulte la guía completa de LM Studio para ver el procedimiento paso a paso.

Preguntas frecuentes

¿GGUF funciona únicamente en CPU o también utiliza la GPU?

Ambas opciones. llama.cpp nació como un proyecto de inferencia en CPU, pero traslada capas del modelo a la GPU (CUDA, Metal, Vulkan, ROCm) y puede ejecutarse completamente en GPU cuando el modelo cabe íntegramente en la VRAM. Ollama y LM Studio gestionan automáticamente la división entre CPU y GPU; al usar llama.cpp directamente, usted controla esta distribución mediante la bandera -ngl (número de capas en GPU).

¿Cuál es la diferencia entre Q4_K_M y Q4_K_S?

Ambas son cuantizaciones k-quants de aproximadamente 4 bits; la letra indica la variante de tamaño. _M «M» (mediana) conserva más tensores sensibles a la calidad con mayor precisión que _S «S» (pequeña), por lo que es ligeramente mayor y ofrece un rendimiento ligeramente mejor. La diferencia es pequeña: elija _M Q4_K_M

a menos que los últimos cientos de megabytes determinen si el modelo cabe en su hardware.

¿Qué pérdida real de calidad implica la cuantización?

En Q8_0 y Q6_K prácticamente no hay pérdida: pruebas ciegas tienen dificultades para distinguirlos de F16. Q4_K_M presenta una ligera pérdida medible que la mayoría de los usuarios no percibe durante conversaciones, aunque puede ser relevante en tareas precisas como generación de código o cálculos matemáticos. Por debajo de Q4 la degradación se vuelve evidente, y los modelos pequeños se ven afectados más que los grandes.

¿Puedo usar GGUF con transformers o vLLM?

Existe cierto soporte, pero es limitado y no constituye el flujo nativo: transformers puede descuantizar algunos archivos GGUF al cargarlos, y vLLM dispone de soporte experimental para GGUF que varía según la arquitectura. Si está desarrollando sobre estas pilas, use safetensors; GGUF debe considerarse principalmente el formato destinado a los entornos de ejecución de la familia llama.cpp.

¿Por qué está mi modelo dividido en varios archivos .gguf? Los modelos muy grandes se dividen en fragmentos (shards) cuyos nombres siguen el patrónmodel-00001-of-00002.gguf

principalmente para respetar los límites de tamaño de archivo en plataformas de alojamiento. Guarde todos los fragmentos en la misma carpeta y apunte su entorno de ejecución al primero: llama.cpp y las herramientas basadas en él cargarán automáticamente los restantes. base de datos de modelos Una vez que sepa qué cuantización se adapta a su hardware, la siguiente pregunta práctica es qué modelo elegir para ella: la lista de los mejores modelos locales para Ollama es una buena selección inicial; además, la