GGUF (GGML Universal File) es un formato de archivo binario diseñado para almacenar tanto tensores como metadatos en un solo archivo, lo que permite guardar y cargar datos de modelos de forma rápida. Introducido en agosto de 2023 por el proyecto llama.cpp, fue creado para mejorar la compatibilidad hacia atrás a medida que se añadía soporte para arquitecturas de modelos adicionales. GGUF reemplazó a formatos anteriores utilizados por el proyecto, como GGML, y normalmente se produce convirtiendo modelos desarrollados con otras bibliotecas de aprendizaje automático como PyTorch. El formato se ha convertido en el estándar para distribuir grandes modelos de lenguaje cuantizados para inferencia local, con soporte nativo de herramientas como llama.cpp, Ollama, LM Studio, GPT4All, Jan y koboldcpp. A partir de 2026, decenas de miles de puntos de control GGUF están alojados en Hugging Face, que ofrece una integración de primera clase que incluye un visor de metadatos, un servicio de puntos de conexión de inferencia y una biblioteca de análisis sintáctico en JavaScript.
Historia
Los formatos de archivo de modelo utilizados por el proyecto llama.cpp evolucionaron a través de cuatro etapas con nombre: GGML, GGMF, GGJT y GGUF. El formato GGML original era un contenedor de tensores delgado que codificaba de forma fija los hiperparámetros del modelo y la información del tokenizador dentro del cargador; añadir soporte para una nueva arquitectura de modelo o esquema de cuantización normalmente requería cambios de código que rompían la compatibilidad con los archivos existentes.
A medida que llama.cpp creció durante 2023 para soportar arquitecturas adicionales más allá de Llama - incluyendo Mistral, Falcon y otras - estas limitaciones se volvieron cada vez más difíciles de gestionar. GGUF se introdujo el 21 de agosto de 2023 como un sucesor incompatible con versiones anteriores, con la especificación formalizada a través de la solicitud de extracción #302 en el repositorio ggerganov/ggml. El formato hereda el diseño general de GGJT pero reemplaza su lista plana de hiperparámetros con un sistema estructurado de metadatos clave-valor, lo que permite añadir nuevos campos - detalles de arquitectura, vocabularios de tokenizador, parámetros de entrenamiento - sin modificar el cargador ni romper modelos más antiguos.
El formato en sí ha pasado por tres versiones internas. La versión 1 estableció la estructura básica; la versión 2 añadió relleno de alineación explícito para soportar el mapeo de memoria; y la versión 3, la versión actual, añadió soporte opcional para big-endian.
Diseño
GGUF se centra en la cuantización, el acto de reducir la precisión en los pesos del modelo. Esto puede conducir a un menor uso de memoria y una mayor velocidad, aunque a costa de una precisión reducida del modelo. El formato está diseñado para ser:
- Autocontenido - un solo archivo contiene los tensores, el tokenizador y todos los metadatos necesarios para cargar y ejecutar el modelo, eliminando la necesidad de archivos de configuración adjuntos.
- Mapeable en memoria - los datos de los tensores están alineados (por defecto a un límite de 32 bytes) para que los pesos puedan accederse directamente a través de punteros sin cargar todo el archivo en la RAM, lo que permite servir modelos más grandes que la memoria disponible mediante la paginación del sistema operativo.
- Extensible - el bloque de metadatos clave-valor permite añadir nuevos campos sin romper la compatibilidad con lectores más antiguos.
GGUF soporta tipos enteros cuantizados de 2 a 8 bits, formatos de datos de coma flotante comunes como float32, float16 y bfloat16, y cuantización de 1.58 bits. Varias variantes "K-quant" (como Q4_K, Q5_K y Q6_K) utilizan un esquema basado en bloques con valores de escala y mínimo separados por superbloque, dando generalmente mejor calidad a un ancho de bit dado que las cuantizaciones heredadas más simples como Q4_0 y Q8_0. GGUF contiene la información necesaria para ejecutar un modelo de lenguaje tipo GPT, como el vocabulario del tokenizador, la longitud de contexto, la información de los tensores y otros atributos.
Estructura del archivo
Un archivo GGUF consta de cuatro secciones secuenciales: un encabezado de tamaño fijo, un bloque de metadatos clave-valor, un bloque de información de tensores y los datos de los tensores en sí.
Estructura a nivel de bytes (little-endian)
Antes de la versión 3, los archivos eran implícitamente little-endian; la versión 3 permite el almacenamiento big-endian pero no incluye una marca que indique el endianness, por lo que debe inferirse del contexto.
#### Bloque de metadatos
El bloque de metadatos es una secuencia de pares clave-valor tipados. Las claves son cadenas con espacio de nombres (por ejemplo, general.*, tokenizer.* o un prefijo específico de arquitectura como llama.*), y los valores pueden ser escalares, cadenas o matrices - incluyendo matrices multidimensionales.
#### Bloque de información de tensores
Para cada tensor, el bloque de información almacena su nombre, número de dimensiones, forma, tipo de datos y desplazamiento de bytes dentro de la región posterior tensor_data[]. El esquema de nombres está estandarizado entre arquitecturas (por ejemplo, blk.0.ffn_gate.weight), de modo que los cargadores puedan localizar los pesos independientemente del marco de origen.
#### Datos de los tensores
Los datos de los tensores siguen al bloque de información y comienzan en el siguiente límite de alineación. El valor de alineación se almacena en los metadatos bajo la clave general.alignment; si está ausente, se establece por defecto en 32 bytes. Alinear los datos de esta manera es lo que permite que el archivo se mapee directamente en memoria: los pesos de los tensores pueden leerse a través de punteros sin una copia adicional, lo cual es importante para operaciones SIMD, transferencias DMA de GPU y eficiencia de caché de CPU.
Herramientas
Los modelos almacenados en otros marcos se convierten típicamente a GGUF utilizando el script convert_hf_to_gguf.py incluido con llama.cpp, que lee los puntos de control de Hugging Face (comúnmente en forma de safetensors) y emite un archivo GGUF en una precisión base elegida como f16 o bf16. El archivo resultante puede luego re-cuantizarse a uno de los formatos enteros GGUF con la utilidad llama-quantize, y los modelos muy grandes pueden dividirse en múltiples archivos con llama-gguf-split.
El proyecto llama.cpp también expone una API C/C++ (declarada en ggml/include/gguf.h) y un paquete de Python, gguf-py, para leer y escribir archivos GGUF programáticamente.
Adopción
GGUF es el formato de modelo nativo de llama.cpp y de Ollama, que utiliza llama.cpp como su backend de inferencia; los modelos de Ollama extraídos de su registro son archivos GGUF internamente, y archivos GGUF arbitrarios de Hugging Face pueden cargarse referenciándolos como hf.co/{usuario}/{repositorio}. Otras aplicaciones de inferencia que consumen GGUF directamente incluyen LM Studio, GPT4All, Jan y koboldcpp.
Hugging Face soporta el formato como ciudadano de primera clase en su centro de modelos, proporcionando un visor de metadatos GGUF, filtrado por la etiqueta gguf, una integración de puntos de conexión de inferencia y una gran colección de puntos de control GGUF subidos por la comunidad.