Formato de modelo GGUF: qué es y cómo ejecutar uno

A modelo GGUF es un modelo de lenguaje grande empaquetado en el formato de archivo GGUF: un contenedor de un solo archivo que contiene los pesos cuantizados, el tokenizador, los hiperparámetros y la plantilla de indicaciones para un modelo. Fue creado por Georgi Gerganov y el proyecto llama.cpp en agosto de 2023 para reemplazar el formato anterior GGML. GGUF es lo que permite descargar un único archivo, apuntar un entorno de ejecución a él y obtener un LLM local funcional en una laptop o estación de trabajo.

Qué es realmente GGUF

GGUF significa GPT-Generated Unified Format. Estructuralmente, es un archivo binario con una cabecera, un bloque de metadatos clave-valor, un índice de tensores y los propios datos tensoriales. La especificación oficial de GGUF en el repositorio ggml define su estructura.

Dos propiedades son fundamentales para los usuarios:

• Autónomo. El archivo incluye el tokenizador, los tokens especiales, los identificadores EOS/BOS, la plantilla de chat y los metadatos de arquitectura. No necesita un archivo separado tokenizer.json o config.json junto a él.
• Mapeable en memoria. Los entornos de ejecución usan mmap() para mapear el archivo, por lo que el inicio es casi instantáneo y el sistema operativo carga los pesos bajo demanda. Por eso un archivo GGUF de 40 GB se abre en segundos incluso en un SSD lento.

GGUF reemplazó a GGML porque GGML carecía de control de versiones, mezclaba metadatos con pesos y dejaba de funcionar cada vez que aparecía una nueva arquitectura. GGUF sí tiene control de versiones y es extensible.

Cuantización: el esquema de nomenclatura

La mayoría de los archivos GGUF que descarga están cuantizados —es decir, los pesos se almacenan con menos bits que el original en FP16. El sufijo del nombre de archivo indica qué esquema se utilizó. Las familias actuales están documentadas en el README de cuantización de llama.cpp.

Cuantización	Bits/peso (aprox.)	Uso típico
Q2_K	~2.6	Más pequeño, pérdida de calidad perceptible
Q3_K_M	~3.9	Compresión agresiva
Q4_K_M	~4.8	Valor predeterminado más común: buen equilibrio entre tamaño y calidad
Q5_K_M	~5.7	Mayor calidad, archivo más grande
Q6_K	~6.6	Casi sin pérdida frente a FP16
Q8_0	~8.5	Efectivamente sin pérdida, ~2× el tamaño de Q4
F16 / BF16	16	Referencia sin cuantizar

El _K Las variantes k-quants usan precisión variable por bloque de tensores. Los sufijos _M / _S / _L indican ajustes preestablecidos de mezcla de bloques: medio, pequeño o grande. Variantes más recientes (por ejemplo, IQ IQ4_XS ) emplean calibración mediante matriz de importancia para lograr mejor calidad con el mismo presupuesto de bits.utiliza la calibración mediante matriz de importancia para obtener una mejor calidad con el mismo presupuesto de bits.

Como regla general para la VRAM, tome el tamaño del archivo en disco y sume aproximadamente 1–3 GB para la caché KV en contextos cortos, y más para contextos largos. Desde la base de datos de modelos Convly: Llama 3.1 8B requiere aproximadamente 5 GB en cuantización de 4 bits, Llama 3.3 70B alrededor de 40 GB y Mistral 7B aproximadamente 4,5 GB. Para modelos más grandes, el tabla de requisitos de VRAM es la búsqueda más rápida.

Dónde conseguir archivos GGUF

Casi toda la distribución de GGUF se realiza en Hugging Face. Busque el nombre del modelo junto con «GGUF». Entre los re-cuantizadores fiables se incluyen bartowski, Qwen (oficial para Qwen3), lmstudio-community, unsloth y MaziyarPanahi. Meta, Google, Mistral y Microsoft publican algunas versiones oficiales de GGUF; para otros modelos, la comunidad realiza la cuantización a partir de los archivos originales en formato safetensors.

Un repositorio suele contener un archivo por nivel de cuantización, por ejemplo: Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf. Para modelos de más de ~50 GB, el archivo se divide en fragmentos (shards) cuyos nombres siguen el patrón -00001-of-00003.gguf; los entornos de ejecución los cargan automáticamente a partir del primer fragmento.

Ejecutar un modelo GGUF

Linux

Compile llama.cpp desde el código fuente o instale el binario precompilado. Con CUDA:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j
./build/bin/llama-cli -m ~/models/llama-3.1-8b-instruct-Q4_K_M.gguf 
    -p "Explica GGUF en un párrafo." -n 256 -ngl 99

El -ngl La bandera «n-gpu-layers» determina cuántas capas del transformador se trasladan a la GPU. Establézcala lo suficientemente alta como para que todo el modelo quepa en la VRAM; si se queda sin memoria, reduzca su valor y el resto permanecerá en la CPU. Para ofrecer una API HTTP compatible con OpenAI, use llama-server en el puerto 8080 de forma predeterminada.

macOS

En Apple Silicon, llama.cpp utiliza automáticamente el backend Metal. Instálelo mediante Homebrew:

brew install llama.cpp
llama-cli -m ~/models/qwen3-8b-Q5_K_M.gguf -p "Hola" -ngl 99

La memoria unificada significa que el límite es su RAM total menos la sobrecarga del sistema operativo. Un Mac de la serie M con 32 GB de RAM ejecuta cómodamente Qwen3 de 14B o -ngl el límite es su RAM total menos la sobrecarga del sistema operativo. Una Mac de la serie M con 32 GB de RAM ejecuta cómodamente Qwen3 14B o Gemma 3 12B en cuantización Q4_K_M —la base de datos indica que estos modelos ocupan aproximadamente 9 GB y 8 GB de VRAM respectivamente.

Para una interfaz gráfica (GUI), LM Studio es la opción habitual en Mac. Descarga automáticamente los archivos GGUF desde Hugging Face y expone un servidor local compatible con la API de OpenAI.

Windows

Tres vías prácticas:

• Ollama. Instálelo desde ollama.com/download, entonces ollama run llama3.1:8b. Ollama descarga sus propias versiones curadas de GGUF. Para cargar un archivo arbitrario, cree un archivo Modelfile con una línea FROM ./mymodel.gguf y ejecute ollama create mymodel -f Modelfile. Consulte nuestra Guía de instalación de Ollama.
• LM Studio. Instalación en un solo clic, exploración y descarga de GGUF desde una interfaz gráfica, control deslizante para la descarga de carga a la GPU.
• binarios precompilados de llama.cpp. El proyecto proporciona paquetes comprimidos precompilados para Windows (CPU, CUDA y Vulkan) en la versiones de GitHub. Descomprímalos y ejecute llama-cli.exe de la misma manera que en Linux.

En cuanto a la elección de GPU, la guía local de GPUs para LLM cubre las opciones actuales en términos de precio y VRAM disponibles.

GGUF frente a Safetensors frente a AWQ frente a GPTQ

Formato	Entorno de ejecución principal	Precisión	Ideal para
GGUF	llama.cpp, Ollama, LM Studio	2–8 bits + F16	CPU, CPU/GPU mixto, Apple Silicon, usuario único
Safetensors (FP16/BF16)	Transformers, vLLM	16 bits	Entrenamiento, investigación, inferencia en precisión completa
AWQ	vLLM, AutoAWQ	4 bits	Servicio GPU de alto rendimiento
GPTQ	vLLM, ExLlamaV2	3–8 bits	Inferencia exclusiva en GPU con agrupamiento (batching)
MLX	MLX (Apple)	4–16 bits	Exclusivo para Apple Silicon

Elija GGUF cuando el destino sea un único usuario en hardware heterogéneo o cuando necesite que el modelo se ejecute incluso en CPU. Elija vLLM con safetensors AWQ/GPTQ cuando esté atendiendo a muchos usuarios concurrentes en una GPU de centro de datos.

Cuándo GGUF no es la respuesta adecuada

GGUF asume inferencia secuencial con tamaño de lote igual a uno (batch-size-1). Su rendimiento es mucho menor que el de vLLM o TensorRT-LLM bajo carga concurrente, y no dispone de atención paginada (paged attention). Si está ofreciendo una API para tráfico real, una implementación en FP16 o AWQ sobre vLLM superará a GGUF en tokens/segundo/dólar, incluso antes de considerar el tiempo de desarrollo invertido.

Además, su rendimiento se deteriora notablemente en los modelos de mayor tamaño. Kimi K3 requiere ~1,4 TB de VRAM en cuantización de 4 bits y DeepSeek V4-Pro alrededor de 800 GB: se trata de despliegues multi-nodo, no cargas de trabajo GGUF para escritorio. Y para modelos de vanguardia alojados, como Claude Sonnet 4.6 a 3 dólares por entrada / 15 dólares por salida por cada millón de tokens o Gemini 3.6 Flash a 1,50 dólares por entrada / 7,50 dólares por salida, no existen pesos locales que convertir. Calcule los costos con precisión antes de comprometerse con la compra de una GPU. calculadora de autohospedaje frente a API antes de comprometerse con la compra de una GPU.

Convertir un modelo a GGUF

Si un modelo está disponible en Hugging Face en formato safetensors pero aún nadie lo ha cuantizado, el flujo de trabajo es:

# en el repositorio llama.cpp
pip install -r requirements.txt
python convert_hf_to_gguf.py /ruta/a/modelo-hf --outfile modelo-f16.gguf
./build/bin/llama-quantize modelo-f16.gguf modelo-Q4_K_M.gguf Q4_K_M

El script de conversión solo admite las arquitecturas que llama.cpp ya conoce: llama, mistral, qwen2/3, gemma, phi y una lista creciente de otras. Para arquitecturas novedosas es necesario modificar primero el código. Los nombres de archivo y las banderas del script han cambiado entre versiones de llama.cpp, así que consulte python convert_hf_to_gguf.py --help en relación con el commit con el que compiló.

Preguntas frecuentes

¿Es GGUF lo mismo que GGML?

No. GGML era el formato anterior utilizado por llama.cpp hasta mediados de 2023. GGUF lo reemplazó en agosto de 2023 con un encabezado versionado, metadatos integrados y una disposición estable de tensores. Los archivos antiguos en formato .bin GGML ya no se cargan en la versión actual de llama.cpp; debe buscar una versión re-cuantizada en formato GGUF.

¿Qué cuantización debo descargar?

Comience con Q4_K_M. Es el formato que mejor se adapta a la mayor variedad de hardware, y la pérdida de calidad frente a FP16 es pequeña para la mayoría de los modelos con más de 7 mil millones de parámetros. Pase a Q5_K_M o Q6_K si dispone de VRAM adicional y le importa especialmente la precisión en programación o razonamiento. Reduzca a Q3_K_M o a una variante IQ3 únicamente si el modelo, de otro modo, no cabe en su hardware.

¿Puede modelos GGUF usar mi GPU?

Sí. llama.cpp admite CUDA (NVIDIA), ROCm (AMD), Metal (Apple), Vulkan (multi-fabricante) y SYCL (Intel). La bandera -ngl descarga capas a la GPU. Si el modelo cabe íntegramente en la VRAM, el rendimiento es cercano al de entornos GPU dedicados; si la descarga es parcial, la velocidad queda limitada por la capa más lenta, sea cual sea su ubicación física.

¿Funciona GGUF con modelos de visión o audio?

Parcialmente. llama.cpp admite modelos visuales multimodales tipo LLaVA mediante un archivo mmproj GGUF emparejado que contiene el proyector visual. El soporte para Qwen-VL, Gemma 3 Vision y similares se ha ido incorporando progresivamente, aunque sigue rezagado respecto a las versiones exclusivamente textuales. Los modelos de audio como Whisper utilizan su propio formato relacionado, gestionado por whisper.cpp, no por el binario principal de llama.cpp.

¿Cómo elijo un modelo GGUF que se adapte a mi hardware?

Busque el modelo en la base de datos de modelos Convly para conocer su requerimiento de VRAM en cuantización de 4 bits, luego reste 1–3 GB como margen de seguridad para el contexto y la sobrecarga del sistema operativo. En una tarjeta de 24 GB, Qwen3 32B (~20 GB) o Gemma 3 27B (~16 GB) en cuantización Q4 son opciones cómodas. El Calculadora de VRAM maneja contextos más largos, lo que incrementa significativamente la caché KV.

¿Son seguros los archivos GGUF para ejecutarlos?

Los pesos son simplemente números: a diferencia de los puntos de control basados en pickle de Python, GGUF no ejecuta código al cargarlos. El riesgo radica en que un archivo maliciosamente diseñado active un error en el analizador del entorno de ejecución. Confíe únicamente en cargadores conocidos de Hugging Face (bartowski, unsloth, lmstudio-community, cuentas oficiales de proveedores) y mantenga actualizados llama.cpp, Ollama y LM Studio .