Formato GGUF: guía completa para la inferencia local de LLM

¿Qué es GGUF?

GGUF, siglas de GGML Unified Format, es un formato de archivo binario que empaqueta los pesos del modelo, los datos del tokenizador, metadatos de la arquitectura e información de cuantización en un único archivo portátil para la inferencia con runtimes basados en GGML, especialmente llama.cpp.

GGUF resuelve un problema de despliegue de LLM. Muchos formatos de modelo obligan a mantener varios archivos juntos: pesos del modelo, ficheros del tokenizador, archivos de configuración y código de carga específico de la arquitectura. GGUF simplifica todo esto haciendo que el archivo del modelo sea en gran parte autoexplicativo.

Un archivo GGUF suele contener:

• Tensores del modelo
• Pesos cuantizados o sin cuantizar
• Vocabulario del tokenizador
• Configuración del tokenizador
• Metadatos de la arquitectura del modelo
• Configuración de la longitud de contexto
• Dimensiones de embeddings
• Número de cabezas de atención
• Configuración de RoPE
• Nombres, formas y tipos de datos de los tensores

La idea clave es que el propio archivo se describe a sí mismo. El runtime puede leer los metadatos, entender la arquitectura, cargar el tokenizador y mapear los tensores sin depender de un config.json o una carpeta de tokenizador aparte.

Esto no significa que cualquier archivo GGUF sea compatible para siempre con cualquier runtime. El runtime debe admitir la arquitectura del modelo y los tipos de tensores usados en el archivo. Aun así, GGUF facilita mucho más esa compatibilidad respecto a formatos antiguos porque el archivo aporta mucha más información estructurada.

Cuatro características que definen GGUF:

1. Despliegue en un único archivo
2. Soporte de memory mapping para cargas eficientes
3. Metadatos extensibles tipados en clave-valor
4. Compatibilidad con muchos tipos de cuantización, desde formatos de muy pocos bits hasta precisión completa

GGUF se introdujo en 2023 como parte del ecosistema de llama.cpp y GGML. Hoy es el formato dominante para distribuir LLM cuantizados en local en Hugging Face.

GGUF vs. GGML

GGML (Georgi Gerganov Machine Learning) fue el predecesor de GGUF. Fue clave porque permitió las primeras inferencias locales. Sin embargo, presentó limitaciones prácticas cuando el ecosistema se amplió más allá de los modelos LLaMA originales.

Entre los puntos dolorosos de GGML estaban:

• Gestión de metadatos menos flexible
• Más supuestos específicos de carga por arquitectura
• Gestión del tokenizador y configuración menos autocontenida
• Extensibilidad complicada a medida que aparecían nuevas familias de modelos

GGUF solucionó estas limitaciones con un formato más estructurado. Introdujo metadatos tipados, mejores embeddings de tokenizador y un diseño de archivo más claro. Esto facilitó que llama.cpp y herramientas relacionadas admitieran más arquitecturas sin rediseñar constantemente la canalización de carga.

Para el usuario, la diferencia importante es sencilla: GGUF es el formato moderno. Si descargas modelos hoy, casi siempre deberías elegir GGUF en lugar de los antiguos archivos GGML.

GGUF vs. GPTQ y AWQ

Al investigar formatos de archivo, seguro te has cruzado con GGUF, GPTQ (Generative Post-Training Quantization) y AWQ (Activation-Aware Weight Quantization). A menudo se comentan juntos porque los tres buscan hacer la inferencia de LLM más eficiente. Pero no son categorías idénticas.

GGUF es ante todo un formato de archivo y contenedor de despliegue. Admite muchos tipos de cuantización y está muy asociado a la inferencia local al estilo llama.cpp.

GPTQ y AWQ son métodos de cuantización y ecosistemas empleados habitualmente para inferencia optimizada en GPU, especialmente en hardware NVIDIA mediante frameworks como Transformers, ExLlama, AutoGPTQ y flujos de trabajo compatibles con vLLM.

Si buscas la máxima compatibilidad entre portátiles, sobremesas, Apple Silicon y hardware mixto, GGUF suele ser la opción más segura.

Si tu objetivo es el máximo rendimiento en servidores de inferencia NVIDIA dedicados, GPTQ, AWQ, FP8 u otros formatos optimizados para GPU pueden ser más adecuados.

¿Por qué usar GGUF?

GGUF se popularizó porque resuelve problemas prácticos de despliegue. A mí también me resulta comodísimo al desplegar en local sin todo el lío de configuraciones.

Antes, ejecutar LLM en local implicaba herramientas fragmentadas, pesos sin comprimir muy grandes, formatos de modelo incompatibles y configuraciones complicadas. GGUF te ayuda ahora a estandarizar gran parte de ese flujo.

En lugar de pensar en múltiples archivos y scripts de carga, puedes centrarte en elegir el modelo correcto, seleccionar el nivel de cuantización y ejecutar la inferencia.

Ejecuta modelos en local

GGUF te permite ejecutar LLM en tu propia máquina. Esto implica:

• Sin coste por token en API
• Sin dependencia de un proveedor de inferencia alojado
• Sin necesidad de enviar prompts a una API de terceros
• Posibilidad de inferencia sin conexión tras descargar el modelo

Es especialmente útil para flujos sensibles a la privacidad. Puede que no quieras enviar código propietario, documentos internos, datos de clientes o prompts confidenciales a una API externa.

La inferencia local no es automáticamente segura por sí misma. Debes gestionar bien tu máquina, logs, aplicaciones y controles de acceso. Pero GGUF hace que el despliegue privado en local sea mucho más accesible.

Para practicar de forma práctica, consulta nuestros tutoriales sobre servir Mistral Medium 3.5 con SGLang, ejecutar DeepSeek V4 Flash en local, ejecutar el eficiente modelo Bonsai de 1 bit en un portátil antiguo y ejecutar MiniMax M2 en local como asistente de código.

Flexibilidad de hardware

GGUF es útil porque funciona en muchas configuraciones de hardware.

Según el runtime y el backend, los modelos GGUF pueden ejecutarse en:

• Máquinas solo con CPU
• GPUs NVIDIA mediante CUDA
• Apple Silicon mediante Metal
• GPUs AMD mediante HIP o Vulkan
• GPUs Intel mediante SYCL o Vulkan
• Algunos entornos ARM y móviles

Esta flexibilidad es una gran razón por la que llama.cpp se volvió influyente. No está pensado solo para GPUs de servidor de gama alta, sino para hacer posible la inferencia local en una amplia variedad de hardware.

Por ejemplo, un usuario de Mac puede apoyarse en la aceleración Metal, mientras que uno de Linux en escritorio puede usar CUDA o Vulkan. Un usuario solo con CPU aún puede ejecutar modelos cuantizados más pequeños, aunque la generación será más lenta.

Amplio soporte del ecosistema

Muchas herramientas de inferencia local admiten GGUF. Por ejemplo:

• llama.cpp para línea de comandos y servidor
• Ollama para gestión de modelos desde CLI y acceso por API
• LM Studio como interfaz de escritorio
• GPT4All para chat privado en local
• KoboldCpp para roleplay local y generación de texto
• Jan y Open WebUI como interfaces locales de IA

Esto importa porque no quedas atado a una sola interfaz. El mismo formato de modelo puede usarse en flujos de trabajo distintos.

Un desarrollador podría hacer benchmarks con llama.cpp, chatear en LM Studio, servirlo con Ollama y conectarlo a una interfaz web mediante Open WebUI.

Distribución en Hugging Face

Hugging Face se ha convertido en un gran hub de distribución de modelos GGUF.

Fuente: Hugging Face

Muchos modelos de pesos abiertos populares reciben variantes GGUF subidas por la comunidad poco después de su lanzamiento. Estos repositorios suelen incluir varias opciones de cuantización para que elijas la que mejor encaja con tu hardware.

Variantes comunes de subida:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

Esto significa que, a menudo, no necesitas convertir manualmente. Para los modelos más populares, alguien de la comunidad ya ha creado archivos GGUF con niveles de cuantización habituales.

Control granular del equilibrio tamaño-calidad

GGUF te da control fino sobre el compromiso entre tamaño y calidad. Puedes elegir:

• Cuantizaciones más pequeñas para máquinas con poca memoria
• Cuantizaciones intermedias para un uso diario equilibrado
• Cuantizaciones de más bits para programación, razonamiento o salidas estructuradas
• Precisión total o casi total cuando la memoria no es un límite

Esta flexibilidad es una de sus grandes ventajas. En lugar de un único objetivo de despliegue, GGUF permite adaptar la misma familia de modelos a muchos niveles de hardware.

¿Cómo funciona GGUF?

Un archivo GGUF se organiza en tres partes principales:

1. Cabecera
2. Metadatos e información de tensores
3. Datos de tensores

La estructura exacta la define la especificación de GGUF. Lo importante es que los metadatos y la información de tensores aparecen antes de los datos crudos de tensores, lo que permite al runtime entender qué va a cargar.

La cabecera

La cabecera identifica el archivo como GGUF e indica al runtime cómo parsear el resto del archivo. Incluye:

• Número mágico de GGUF
• Versión del formato
• Número de tensores
• Número de pares clave-valor de metadatos

Los archivos GGUF modernos suelen usar la versión 3.

Los motores de inferencia revisan primero el número mágico. Si el archivo no empieza con el identificador esperado de GGUF, el runtime puede rechazarlo antes de intentar parsear tensores o asignar memoria.

Es un paso sencillo pero importante para la seguridad y la fiabilidad. Evita que el runtime trate por accidente un binario no relacionado como si fuera un modelo.

Pares clave-valor de metadatos

Los metadatos de GGUF son un almacén tipado de clave-valor. Estos metadatos pueden describir:

• Información general del modelo
• Familia de arquitectura
• Longitud de contexto
• Tamaño de embeddings
• Número de capas
• Número de cabezas de atención
• Parámetros de RoPE
• Vocabulario del tokenizador
• Tokens especiales
• Información de cuantización

Las claves suelen estar espaciadas por nombres. Ejemplos:

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

El namespacing es importante porque permite a GGUF admitir muchas arquitecturas sin cambiar todo el formato de archivo. Un modelo de la familia LLaMA puede usar claves llama.*, mientras que otras familias usarán sus propios metadatos específicos.

Por eso GGUF se adaptó bien a modelos más allá de LLaMA, incluyendo arquitecturas como Qwen, Mistral, Gemma, DeepSeek, Phi y otras.

Información de tensores y datos de tensores

Tras los metadatos, el archivo almacena la información de tensores y los datos de tensores.

La información de tensores describe:

• Nombre del tensor
• Forma
• Tipo de dato
• Desplazamiento dentro de la sección de datos de tensores

La sección de datos de tensores contiene los pesos reales del modelo. Pueden almacenarse en precisión completa o en alguno de los tipos de tensor cuantizados que admite GGUF.

GGUF usa un valor de alineación definido en metadatos, habitualmente general.alignment. Muchos archivos GGUF usan alineación de 32 bytes, pero lo correcto es decir que la alineación la controlan los metadatos y no está codificada de forma permanente.

La alineación importa porque permite a los runtimes acceder eficientemente a los bloques de tensores.

Memory mapping

Una de las ventajas prácticas de GGUF es el memory mapping, a menudo llamado mmap.

Con memory mapping, el sistema operativo puede mapear el archivo del modelo en memoria virtual en lugar de obligar al runtime a copiarlo entero en RAM desde el principio.

Esto puede hacer que el arranque del modelo sea mucho más rápido, especialmente con SSD. También permite que el sistema operativo pagine los datos del modelo según se necesiten.

Sin embargo, el memory mapping no es magia. El modelo sigue necesitando ancho de banda de memoria suficiente y RAM o VRAM disponible para rendir bien. Si tu sistema está paginando constantemente desde disco, la inferencia será lenta.

Mejor piensa en mmap así:

• Mejora la eficiencia de carga
• Reduce copias innecesarias
• Deja la paginación en manos del SO
• No elimina los requisitos de memoria de la inferencia

Entendiendo los tipos de cuantización de GGUF

La cuantización comprime los pesos del modelo a representaciones de menor precisión.

En lugar de guardar cada peso como un valor en coma flotante de 16 bits, un modelo cuantizado almacena valores aproximados usando menos bits. Esto reduce el tamaño en disco, el uso de RAM y VRAM, y la presión sobre el ancho de banda de memoria.

La idea clave es que muchos pesos de redes neuronales no necesitan precisión completa de coma flotante durante la inferencia. Un modelo cuantizado con cuidado puede conservar gran parte del comportamiento original y a la vez ser mucho más pequeño.

Nomenclatura de cuantización en GGUF

Los nombres de cuantización en GGUF suelen seguir este patrón:

• Q indica que está cuantizado
• El número sugiere los bits aproximados por peso
• K se refiere a la familia k-quant
• S, M y L suelen significar variantes pequeña, media y grande

Ejemplos:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

El nombre orienta, pero no siempre refleja exactamente el tamaño total del archivo. El tamaño real depende de la mezcla de tensores, la arquitectura, los metadatos, el tamaño del tokenizador y de si algunos tensores se mantienen a mayor precisión.

Tipos de cuantización comunes en GGUF

Estas cifras son aproximaciones para modelos densos de clase 7B. Arquitecturas nuevas, modelos de mixture-of-experts, tokenizadores más grandes y distintos layouts de tensores pueden alterar el tamaño real.

En la práctica, Q4_K_M se hizo popular porque equilibra muy bien tamaño y calidad. A muchos les basta para chat general, resúmenes, reescritura y trabajo exploratorio con IA en local.

Q5_K_M y Q6_K suelen ser mejores para cargas más exigentes, como programación o seguimiento de instrucciones en varios pasos

La razón es sencilla: estas tareas son más sensibles a degradaciones pequeñas de calidad.

K-quants vs. I-quants

Los K-quants son la familia de cuantización más extendida detrás de formatos como Q4_K_M, Q5_K_M y Q6_K.

Usan esquemas de cuantización por grupos con información de escalado que ayuda a conservar el comportamiento del modelo reduciendo los requisitos de memoria. Son populares porque son fiables, están muy soportados y son fáciles de encontrar en las publicaciones GGUF de la comunidad.

Los I-quants, a menudo escritos como formatos IQ, son tipos más recientes de cuantización como:

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

Los I-quants buscan mejor calidad con tamaños muy pequeños. Pueden usar técnicas como cuantización sensible a la importancia y codebooks de cuantización no lineales. Algunos flujos usan una matriz de importancia, o imatrix, para preservar mejor los pesos más relevantes durante la cuantización.

La contrapartida es la complejidad. Los I-quants pueden lograr una relación tamaño-calidad excelente, sobre todo a tasas muy bajas de bits, pero pueden requerir flujos de cuantización más cuidados y soporte específico en el runtime.

Para la mayoría de principiantes, los K-quants siguen siendo el mejor punto de partida.

Elegir un nivel de cuantización para tu hardware

La siguiente tabla ofrece puntos de partida prácticos. Tómalos como reglas generales, no garantías estrictas. La longitud de contexto, la sobrecarga del sistema operativo, el offload a GPU, el tamaño de la caché KV y la arquitectura concreta del modelo pueden cambiar los requisitos de memoria.

Reglas generales:

• Usa Q4_K_M como valor seguro por defecto para la inferencia local.
• Usa Q5_K_M cuando la calidad pese más que ahorrar cada gigabyte.
• Usa Q6_K o Q8_0 cuando tengas memoria y quieras mayor fidelidad.
• Evita Q2_K para trabajo serio salvo pruebas en escenarios extremadamente limitados por memoria.
• Deja memoria extra para la caché KV, sobre todo con ventanas de contexto largas.

La caché KV es fácil de pasar por alto. Un modelo puede caber en RAM con contexto corto pero fallar o ir lento con contextos más largos porque la caché crece con la secuencia.

El ecosistema de GGUF

La adopción de GGUF viene tanto por las herramientas como por el formato.

Un formato solo resulta útil cuando puedes descargar, ejecutar, inspeccionar, convertir y servir modelos con facilidad. GGUF se beneficia de un ecosistema sólido en herramientas de línea de comandos, apps de escritorio, APIs y repositorios alojados.

1. llama.cpp

llama.cpp es el runtime GGUF original y más importante. Es un motor de inferencia ligero en C/C++ creado por Georgi Gerganov y mantenido por la comunidad de GGML. Su objetivo es habilitar una inferencia eficiente de LLM con una configuración mínima en muchas plataformas de hardware.

La versión actual de llama.cpp admite varios backends, entre ellos:

• CPU
• CUDA para GPUs NVIDIA
• Metal para dispositivos Apple
• Vulkan
• HIP para GPUs AMD mediante ROCm
• SYCL para GPUs Intel
• OpenCL en entornos seleccionados
• Otros backends especializados como CANN, OpenVINO y WebGPU, según la plataforma

También incluye herramientas para conversión, cuantización, servicio, benchmarking e inferencia por línea de comandos. Herramientas comunes:

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

Los comandos para crear una build básica de CMake para CPU son:

cmake -B build
cmake --build build --config Release

En algunas configuraciones, hay que añadir flags al primero de esos dos comandos:

• Desactivar Apple Metal en macOS (activado por defecto): -DGGML_METAL=OFF
• Build con Vulkan: -DGGML_VULKAN=1
• Build con CUDA para GPUs NVIDIA: -DGGML_CUDA=ON

Ten en cuenta que las builds actuales usan opciones CMake GGML_* como GGML_CUDA, GGML_VULKAN y GGML_HIP.

2. Ollama

Ollama es una de las formas más sencillas de ejecutar modelos locales. Ofrece:

• Una CLI simple
• Descarga y gestión de modelos
• Una API REST local
• Bibliotecas oficiales de Python y JavaScript
• Integración con muchas interfaces locales de IA

Ollama almacena y gestiona los modelos por ti, así que normalmente no interactúas con archivos .gguf directamente. Sin embargo, Ollama se basa en inferencia local compatible con llama.cpp y también puede importar archivos GGUF mediante un flujo con Modelfile.

Ollama expone una API local en:

http://localhost:11434/api

Dos endpoints muy usados son:

• /api/generate para completado de prompts
• /api/chat para mensajes estilo chat

Para principiantes, Ollama suele ser el camino más rápido de cero a inferencia local.

3. LM Studio

Fuente: LM Studio

LM Studio es una aplicación de escritorio para descubrir, descargar y chatear con modelos locales. Es útil si prefieres una interfaz gráfica en lugar de herramientas de línea de comandos.

4. GPT4All

Fuente: GPT4All

GPT4All es otra aplicación local multiplataforma centrada en flujos de chatbot privados en local. Admite modelos GGUF y ofrece un entorno amigable para iniciarse.

Estas herramientas acercan GGUF a cualquier perfil. No necesitas entender CMake, layouts de tensores o los entresijos de la cuantización para probar un modelo local.

Cómo empezar con modelos GGUF

Hay dos formas prácticas de empezar:

1. Usa Ollama para la experiencia más simple.
2. Usa llama.cpp directamente para tener más control.

Ejecutar un modelo con Ollama

El flujo más sencillo es descargar el modelo e iniciar una sesión de chat interactiva:

ollama pull llama3.3
ollama run llama3.3

Para llamar al modelo desde Python mediante la API REST:

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

Para aplicaciones estilo chat, usa /api/chat:

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

El campo stream: false es importante en scripts sencillos. Sin él, Ollama devuelve un stream de objetos JSON en lugar de una única respuesta JSON final.

También puedes usar la biblioteca oficial de Python de Ollama:

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

Ejecutar un archivo GGUF con llama.cpp

Si ya tienes un archivo .gguf, puedes ejecutarlo directamente con llama.cpp tras compilar el proyecto.

Ejemplo:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

Si tienes soporte de GPU activado, puedes hacer offload de capas a la GPU:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

La flag -ngl controla el número de capas que se descargan a la GPU. Un valor alto como 99 se usa para descargar lo máximo posible, suponiendo que el modelo quepa en la VRAM.

Para servir por API, usa llama-server:

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

Esto te da una interfaz de servidor local para integrar llama.cpp en aplicaciones.

Convertir un modelo de Hugging Face a GGUF

La mayoría no necesita convertir modelos manualmente porque hay muchas publicaciones GGUF de la comunidad.

Aun así, convertir a mano es útil cuando:

• Has ajustado finamente tu propio modelo
• Todavía no existe versión en GGUF
• Quieres controlar tú mismo la cuantización
• Necesitas un tipo de cuantización específico

Un flujo típico sería:

1. Descargar un modelo de Hugging Face.
2. Convertirlo a GGUF.
3. Cuantizar el archivo GGUF.

Ejemplo:

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

Después, conviértelo a GGUF:

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

Luego cuantiza:

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

En los flujos actuales de llama.cpp, convert_hf_to_gguf.py y llama-quantize son las herramientas relevantes. Tutoriales antiguos pueden referirse a scripts de conversión obsoletos o a binarios antiguos.

Ventajas y limitaciones del formato GGUF

GGUF está optimizado para la inferencia local práctica. No sustituye universalmente a todos los formatos de modelo ni a todos los stacks de serving.

Para inferencias centradas en CPU, Apple Silicon, hardware mixto y privacidad, GGUF suele ser una opción excelente.

Para despliegues en servidores NVIDIA de alto rendimiento, otros formatos y motores pueden ser más rápidos según el modelo, el tamaño de lote, el método de cuantización y el framework de serving.

Reflexiones finales

GGUF hace viable la inferencia local de LLM al empaquetar en un único archivo portátil todo lo que un runtime necesita (pesos, tokenizador, metadatos, info de cuantización). Su verdadera fuerza es el ecosistema: llama.cpp, Ollama, LM Studio y Hugging Face lo han convertido en el formato por defecto para desplegar IA en local.

Para la mayoría, el camino es simple: instala Ollama, descarga un modelo y ejecútalo. Q4_K_M es un valor seguro; sube a Q5_K_M o Q6_K cuando necesites mejor razonamiento o código y tengas memoria de sobra.

Si quieres profundizar en despliegue de LLM, optimización de modelos y flujos de inferencia local, explora el itinerario profesional Associate AI Engineer for Data Scientists o el Associate AI Engineer for Developers.