GGUF Format Guide

Specification

GGUF (GPT-Generated Unified Format) es un formato de archivo binario diseñado para almacenar modelos de lenguaje grandes cuantizados para inferencia local eficiente. Desarrollado por Georgi Gerganov como parte del proyecto llama.cpp, GGUF sucedió al formato GGML más antiguo en agosto de 2023, agregando un sistema de metadatos autodescriptivo que incorpora detalles de la arquitectura del modelo, configuración del tokenizador y parámetros de cuantización directamente en el archivo. Esto hace que los archivos GGUF sean portátiles y autónomos — todo lo necesario para cargar y ejecutar un modelo está en un solo archivo.

El formato GGUF consta de tres secciones: un encabezado que contiene la versión del formato y el conteo de tensores, un almacén de metadatos clave-valor con la configuración del modelo (tipo de arquitectura, longitud de contexto, tamaño de vocabulario, dimensiones de embedding, conteo de cabezas de atención y datos del tokenizador), y la sección de datos de tensores que contiene los pesos reales del modelo en su representación cuantizada. El sistema de metadatos usa pares clave-valor tipados que soportan enteros, flotantes, booleanos, cadenas y arreglos, permitiendo descripciones ricas del modelo sin archivos de configuración externos.

GGUF soporta numerosos tipos de cuantización que van desde precisión completa F32 y F16 hasta cuantizaciones agresivas como Q2_K e IQ1_S. Los niveles de cuantización más comúnmente usados son Q4_K_M (ofreciendo un buen balance entre calidad y tamaño), Q5_K_M (ligeramente más grande pero de mayor calidad) y Q8_0 (casi sin pérdida). Las variantes K-quant (Q4_K_S, Q4_K_M, Q5_K_S, etc.) usan un enfoque sofisticado de precisión mixta donde diferentes capas se cuantizan a diferentes niveles según su sensibilidad, produciendo mejor calidad que la cuantización uniforme con tamaños de archivo similares.

When to Use GGUF

GGUF es el formato de elección siempre que necesites ejecutar inferencia de LLM localmente — en computadoras personales, dispositivos de borde o servidores on-prem sin frameworks de inferencia dependientes de GPU. Es el formato nativo para llama.cpp y es soportado por un amplio ecosistema de herramientas de inferencia local incluyendo Ollama, LM Studio, GPT4All, koboldcpp y text-generation-webui. Si tu objetivo es desplegar un modelo ajustado para uso local sin dependencias de la nube, GGUF debería ser tu formato de exportación objetivo.

Elige GGUF cuando necesites inferencia eficiente en CPU o cuando tu objetivo de despliegue tenga memoria GPU limitada. Las opciones de cuantización de GGUF te permiten intercambiar calidad del modelo por archivos más pequeños e inferencia más rápida, permitiendo que modelos grandes se ejecuten en hardware de consumo. Un modelo de 7B parámetros que requiere 14 GB en FP16 puede reducirse a aproximadamente 4 GB con cuantización Q4_K_M mientras retiene la mayor parte de su capacidad. Esto hace que GGUF sea esencial para despliegues sensibles a la privacidad donde los datos no pueden salir de la máquina local.

GGUF es menos adecuado cuando necesitas máximo rendimiento de inferencia en clústeres de GPU (usa SafeTensors con vLLM o TensorRT-LLM en su lugar) o cuando necesitas continuar entrenando un modelo (GGUF es un formato solo de inferencia — usa SafeTensors o checkpoints de PyTorch para entrenamiento). Tampoco es la opción correcta para arquitecturas no-transformer que llama.cpp no soporta.

Schema / Structure

GGUF File Structure:
┌─────────────────────────────────────┐
│ Header                              │
│  - Magic number: 0x46475547 "GGUF"  │
│  - Version: uint32 (currently 3)    │
│  - Tensor count: uint64             │
│  - Metadata KV count: uint64        │
├─────────────────────────────────────┤
│ Metadata Key-Value Pairs            │
│  - general.architecture: string     │
│  - general.name: string             │
│  - llama.context_length: uint32     │
│  - llama.embedding_length: uint32   │
│  - llama.block_count: uint32        │
│  - llama.attention.head_count: u32  │
│  - tokenizer.ggml.model: string     │
│  - tokenizer.ggml.tokens: [string]  │
│  - ... (additional metadata)        │
├─────────────────────────────────────┤
│ Tensor Info (for each tensor)       │
│  - Name: string                     │
│  - Dimensions: uint32[]             │
│  - Type: enum (F32/F16/Q4_K/...)    │
│  - Offset: uint64                   │
├─────────────────────────────────────┤
│ Tensor Data (aligned, contiguous)   │
│  - Raw quantized weight data        │
└─────────────────────────────────────┘

Example Data

# Convert a HuggingFace model to GGUF using llama.cpp
python convert_hf_to_gguf.py ./my-fine-tuned-model \
  --outfile model-f16.gguf \
  --outtype f16

# Quantize to Q4_K_M for efficient local inference
./llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

# Run inference with llama.cpp
./llama-cli -m model-q4_k_m.gguf \
  -p "Explain quantum computing in simple terms:" \
  -n 256 --temp 0.7

# Inspect GGUF metadata
python -c "
from gguf import GGUFReader
reader = GGUFReader('model-q4_k_m.gguf')
for field in reader.fields.values():
    print(f'{field.name}: {field.parts[-1].tolist()}')"