GGUF
GGUF es el formato de archivo único que usa llama.cpp para almacenar los pesos, el tokenizador y los metadatos de un LLM, a menudo cuantizados a 4-8 bits para hardware local.
GGUF es un formato de archivo binario para almacenar modelos que se ejecutan en GGML, la biblioteca de tensores C que hay detrás de llama.cpp, y en las herramientas basadas en ella. Un archivo GGUF contiene todo lo necesario para ejecutar un modelo de lenguaje grande (LLM): la arquitectura y los hiperparámetros, el vocabulario del tokenizador, la plantilla de chat y los pesos del modelo, normalmente comprimidos mediante la cuantización del modelo a entre 2 y 8 bits por peso. El proyecto llama.cpp introdujo GGUF en agosto de 2023 para sustituir sus formatos anteriores GGML, GGMF y GGJT, y se ha convertido en la forma estándar de compartir modelos de pesos abiertos para la inferencia local en la CPU de un portátil, un Mac con Apple Silicon o una GPU de consumo, con miles de repositorios GGUF en Hugging Face.
Dentro de un archivo GGUF#
La especificación GGUF define cuatro partes en orden. Una cabecera contiene los bytes mágicos GGUF, la versión del formato (actualmente la 3) y el número de tensores y entradas de metadatos. A continuación aparecen metadatos de clave-valor tipados, como general.architecture, llama.context_length, tokenizer.ggml.tokens y tokenizer.chat_template, que incorporan la tokenización y el formato de prompt del modelo al propio archivo. Después, una tabla enumera el nombre, la forma, el tipo de datos y el desplazamiento de cada tensor, y los datos de los tensores aparecen al final, con un relleno hasta una alineación de 32 bytes por defecto para que el entorno de ejecución pueda asignar el archivo a la memoria y cargarlo casi al instante. Los lectores buscan los metadatos por clave, por lo que se pueden añadir arquitecturas y campos nuevos sin romper los archivos antiguos.
Cada tensor tiene su propio tipo, así que un archivo puede combinar distintas precisiones. El paquete Python gguf, mantenido en el repositorio de llama.cpp, escribe y lee el formato e implementa varios tipos de cuantización:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")Enumera las dos claves de metadatos, general.architecture y llama.context_length, y después indica 16,0 bits por peso con un error medio de 0,0001 para F16, 8,5 bits y 0,0045 para Q8_0, y 4,5 bits y 0,0719 para Q4_0. Q8_0 y Q4_0 almacenan bloques de 32 pesos con una escala FP16 por bloque, de ahí el medio bit adicional.
Tipos de cuantización#
Los tipos de cuantización de GGUF pertenecen a tres generaciones. Los formatos de bloque originales, como Q4_0 y Q8_0, usan una escala por cada 32 pesos. Los cuantizadores K, como Q4_K y Q6_K, agrupan bloques en superbloques de 256 pesos con escalas cuantizadas, y nombres de archivo como Q4_K_M indican una combinación que mantiene los tensores más sensibles a una precisión superior. Los cuantizadores I, como IQ2_XXS e IQ4_XS, alcanzan unos 2 a 4 bits por peso, normalmente con la guía de una matriz de importancia que llama-imatrix calcula a partir de texto de muestra, para que los pesos más influyentes conserven la mayor precisión. Entre las incorporaciones más recientes está MXFP4, el formato de coma flotante de 4 bits que OpenAI utilizó para publicar gpt-oss. La mayoría de los archivos GGUF publicados proceden del mismo proceso de conversión:
GGUF frente a otros formatos de modelo#
- GGML, GGMF y GGJT: Los formatos anteriores de llama.cpp almacenaban los hiperparámetros en una lista sin tipos y sin un campo de arquitectura, por lo que añadir un parámetro rompía los archivos existentes.
- Safetensors: Formato de Hugging Face para almacenar tensores sin procesar de forma segura, normalmente con precisión completa o media, y con la configuración y el tokenizador en archivos separados.
- ONNX: Almacena un grafo de cálculo completo junto con los pesos, de modo que cualquier entorno de ejecución compatible con ONNX puede ejecutar el modelo sin código específico para la arquitectura.
Ejecución de modelos GGUF#
llama.cpp ejecuta archivos GGUF desde la línea de comandos o como llama-server, que expone una API compatible con OpenAI, y puede descargar cualquier número de capas a una GPU mientras el resto se ejecuta en la CPU, lo que permite ejecutar modelos que superan la memoria de la GPU. Ollama y LM Studio ejecutan modelos GGUF mediante una biblioteca de modelos y una interfaz de chat, y Hugging Face Hub muestra en el navegador los metadatos y tipos de tensor de cada archivo GGUF. La inferencia local mantiene los prompts en el dispositivo, algo importante para la privacidad de los datos y los usos de IA en el borde sin conexión. La interfaz LLM de Ultralytics puede llamar a un modelo GGUF servido por llama-server o Ollama mediante sus endpoints Chat Completions compatibles con OpenAI, así que un flujo de YOLO26 puede pedir a un modelo local que describa sus detecciones sin enviar datos a una API en la nube. El formato también va más allá de los modelos de lenguaje: los nodos personalizados de ComfyUI-GGUF cargan modelos de difusión cuantizados, como FLUX.1, desde archivos GGUF para que quepan en la memoria de las GPU de consumo.










