Modelos GGUF: qué son y cómo ejecutarlos

GGUF (GPT-Generated Unified Format) es el formato de archivo que utiliza el ecosistema llama.cpp/ggml para almacenar un modelo listo para inferencia. Un único .gguf archivo contiene los tensores cuantizados, además de todo lo necesario para usarlos: vocabulario, configuración del tokenizador, plantilla de chat y metadatos de la arquitectura. Reemplazó al antiguo formato GGML en agosto de 2023 y ahora es el estándar de facto para ejecutar modelos en portátiles, equipos de sobremesa y CPUs.

¿Qué contiene realmente un archivo .gguf?

Un archivo GGUF consta de un encabezado, un bloque de metadatos clave-valor y, a continuación, los datos de los tensores. Los metadatos son la parte que prácticamente importa: por eso un modelo GGUF no requiere archivos auxiliares. La documentación oficial de GGUF de Hugging Face describe su estructura y el visor integrado de metadatos GGUF del Hub, que permite inspeccionar el tipo de cuantización, la longitud de contexto y la plantilla de chat de un archivo antes de descargar varios gigabytes.

Las claves de metadatos típicas incluyen la arquitectura (llama, qwen3, gemma3, phi3), la longitud de contexto de entrenamiento, la configuración RoPE, el vocabulario completo y la plantilla de chat Jinja. Un cargador lee ese bloque y se configura automáticamente; no es necesario pasar manualmente un tokenizador ni un formato de indicación.

GGUF frente a safetensors

	GGUF	safetensors
Entorno de ejecución principal	llama.cpp, Ollama, LM Studio	PyTorch, vLLM, Transformers, TGI
Archivos por modelo	Uno (o fragmentos numerados)	Pesos más carpeta de configuración/tokenizador
Cuantización	Incorporada (Q4_K_M, Q8_0, IQ…)	Normalmente FP16/BF16, o variantes GPTQ/AWQ
CPU + descarga parcial a GPU	Sí, objetivo central de diseño	Limitada y lenta
Servicio simultáneo por lotes	Débil	Fuerte
Ajuste fino	No (primero debe convertirse de nuevo)	Sí

Cómo interpretar el nombre de un archivo GGUF

Los archivos suelen nombrarse Modelo-Nombre-8B-Instruct-Q4_K_M.gguf. El sufijo indica la combinación de cuantización. El número representa el ancho de bits nominal; _K significa k-quants, que mantienen los tensores de atención y de incrustación (embeddings) con mayor precisión que los pesos principales de la capa de retroalimentación (feed-forward); S/M/L son variantes pequeñas/medianas/grandes de esa combinación.

Quant	Aprox. bits/peso	Tamaño aproximado, modelo de 8B	Cuándo usarlo
Q8_0	~8.5	~8,5 GB	Referencia casi sin pérdida; solo para modelos pequeños
Q6_K	~6.6	~6,6 GB	Tienes VRAM de sobra
Q5_K_M	~5.7	~5,7 GB	Predeterminado orientado a la calidad
Q4_K_M	~4.9	~4,9 GB	El valor predeterminado habitual
Q4_0	~4.5	~4,5 GB	Herencia; algunos aceleradores lo prefieren
Q3_K_M	~3.9	~4,0 GB	Apretar un modelo más grande en poca VRAM
Q2_K / IQ2	~2,5–3,4	~2,5–3,4 GB	Último recurso; degradación notable

Trate la columna de bits por peso como aproximada. Los tamaños reales varían según la arquitectura del modelo (un vocabulario amplio infla los tensores de incrustación) y según la versión de llama.cpp, ya que las combinaciones de cuantización se ajustan con el tiempo. La IQ familia (IQ2_XXS hasta IQ4_NL) emplea una calibración basada en matrices de importancia para mantener mejor su rendimiento a anchos de bit muy bajos, y cuantizadores como Bartowski y Unsloth publican variantes IQ junto con los K-quants estándar.

El consenso comunitario —no una medición de Convly— es que Q4_K_M representa el punto óptimo y que la calidad disminuye bruscamente por debajo de aproximadamente 3 bits por peso: los modelos pequeños se degradan más rápido que los grandes a la misma cuantización.

Tamaño: ¿qué modelos GGUF caben en tu GPU?

El tamaño del archivo es el límite inferior, no el total. Añada la caché KV correspondiente a su longitud de contexto, más unos 500 MB–1 GB de sobrecarga. Estas cifras de 4 bits provienen de la base de datos de modelos Convly:

Modelo	VRAM en 4 bits	Contexto	GPU realista
Gemma 3 4B	~3 GB	128 K	Cualquier tarjeta de 6 GB o GPU integrada
Mistral 7B	~4,5 GB	32K	Tarjeta de 8 GB
Llama 3.1 8B	~5 GB	128 K	Tarjeta de 8 GB
Qwen3 14B	~9 GB	128 K	Tarjeta de 12 GB
Phi-4	~9 GB	16K	Tarjeta de 12 GB
Gemma 3 27B	~16 GB	128 K	Tarjeta de 24 GB
Qwen3 32B	~20 GB	128 K	Tarjeta de 24 GB
Llama 3.3 70B	~40 GB	128 K	2×24 GB o memoria unificada de 48 GB
DeepSeek R1 (completo)	~400 GB	128 K	Solo para servidores multi-GPU

Los modelos de mezcla de expertos son la trampa aquí. Qwen3 30B-A3B activa únicamente ~3 mil millones de parámetros por token, pero aún necesita tener residentes todos los ~18 GB. En el extremo, la base de datos sitúa a Kimi K3 en ~1,4 TB a 4 bits: existe un GGUF en principio, pero ninguna máquina individual que usted posea podrá alojarlo. Para obtener una cifra exacta con su longitud de contexto, use el Calculadora de VRAM o el desglose por modelo en Requisitos de VRAM para cada LLM importante. Si aún está eligiendo hardware, mejores GPUs para LLMs locales analiza el compromiso entre VRAM y precio.

Dónde descargar modelos GGUF

• Hugging Face — filtre la lista de modelos con library=gguf. La mayoría de los repositorios incluyen todas las cuantizaciones en un mismo repositorio; descargue únicamente el archivo que necesite, no todo el repositorio.
• biblioteca de Ollama — ollama.com/library ofrece GGUF preempaquetados con la plantilla de chat ya configurada. Consulte la Lista de modelos de Ollama.
• LM Studio — la pestaña Descubrir de la aplicación busca repositorios de GGUF en Hugging Face y señala qué cuantizaciones caben en la RAM/VRAM detectada. Tutorial: guía completa de LM Studio.

Los modelos grandes llegan fragmentados como model-00001-of-00003.gguf y así sucesivamente. Descargue todos los fragmentos en la misma carpeta y apunte el cargador al fragmento 00001: este encontrará automáticamente los demás.

Ejecutar modelos GGUF en Linux

Compile llama.cpp con soporte 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

Los binarios se ubican en build/bin/. Inicie un servidor compatible con OpenAI:

./build/bin/llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 -ngl 99 --port 8080

-ngl (--n-gpu-layers) es el control de descarga: 99 significa «todas las capas en la GPU»; 0 significa solo CPU, y los valores intermedios dividen el modelo cuando este no cabe íntegramente. -c establece el contexto; dejarlo en el contexto completo entrenado del modelo puede consumir más VRAM que los propios pesos. El punto final es entonces http://localhost:8080/v1/chat/completions.

Dos advertencias sobre versiones: la bandera de CMake era LLAMA_CUBLAS en versiones anteriores, y los binarios fueron renombrados (main → llama-cli, server → llama-server) en 2024. Consulte el README del repositorio para la versión que haya clonado. Para GPUs AMD o Intel, sustituya la bandera del backend ROCm/Vulkan/SYCL documentada allí, en lugar de adivinar.

Si usa Ollama en su lugar, los modelos residen en /usr/share/ollama/.ollama/models cuando se ejecuta como servicio del sistema, o ~/.ollama/models para una instalación por usuario. Consulte cómo instalar Ollama.

Ejecutar modelos GGUF en macOS

Apple Silicon es inusualmente eficiente con GGUF porque su memoria unificada permite que la GPU acceda a la mayor parte de la RAM del sistema: un Mac de 64 GB puede alojar un modelo de 70B cuantizado a 4 bits de ~40 GB, que en un PC requeriría dos tarjetas gráficas de 24 GB.

brew install llama.cpp
llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 --port 8080

La descarga a Metal está habilitada en la compilación de Homebrew, por lo que generalmente no necesita -ngl. macOS limita la cantidad de RAM que la GPU puede asignar (ajustable mediante un iogpu sysctl, cuyo valor varía según la versión de macOS), así que deje margen suficiente para el sistema operativo. Ollama almacena los modelos en ~/.ollama/models; LM Studio utiliza ~/.lmstudio/models en versiones actuales y ~\/\.cache\/lm-studio\/models en versiones anteriores — la pestaña «Mis modelos» muestra y permite modificar la ruta real.

Ejecutar modelos GGUF en Windows

Tres vías, de más sencilla a más compleja:

1. LM Studio — Instalador gráfico, búsqueda integrada de modelos dentro de la aplicación y activador para servidor local. Es la opción predeterminada más adecuada para usuarios no desarrolladores.
2. Ollama — Instalador nativo para Windows; los modelos se guardan en C:Users.ollamamodels. Establezca la variable de entorno OLLAMA_MODELS para ubicarlos fuera de la unidad del sistema. Antecedentes: qué es Ollama.
3. Binarios precompilados de llama.cpp — La página de versiones (Releases) de GitHub publica paquetes comprimidos para Windows, específicos para cada backend (CUDA, Vulkan, CPU). Descomprima y ejecute llama-server.exe -m model.gguf -ngl 99 desde PowerShell. Elija la versión CUDA para GPUs NVIDIA; Vulkan es la alternativa segura multiplataforma para AMD e Intel Arc.

Aspectos particulares de Windows: el escaneo en tiempo real de Windows Defender ralentiza la primera carga de archivos de varios gigabytes, y ejecutar llama.cpp dentro de WSL2 le resta una porción de RAM a la máquina virtual. Las compilaciones nativas para Windows suelen ser la opción más sencilla.

Cargar un archivo GGUF arbitrario en Ollama

Versiones recientes de Ollama pueden descargar directamente desde Hugging Face:

ollama run hf.co//:Q4_K_M

Para un archivo local, cree un archivo Modelfile en el mismo directorio:

FROM ./model-Q4_K_M.gguf

entonces ollama create my-model -f Modelfile y ollama run my-model. Si el GGUF carece de una plantilla de chat utilizable, agregue una línea TEMPLATE y PARAMETER stop — las directivas exactas admitidas en Modelfile han evolucionado con las versiones, así que consulte ollama help create para su versión específica. Selecciones recomendadas: mejores LLMs locales para Ollama.

Cuándo GGUF no es la solución adecuada

GGUF optimizes one user at a time. Serving many concurrent requests, or needing tensor parallelism across GPUs, points to safetensors with vLLM or SGLang. And running locally is not automatically cheaper: hosted Llama 3.3 70B is $0.10 in / $0.32 out per 1M tokens, while frontier hosted models like Claude Sonnet 5 cuestan $2,00 por entrada y $10,00 por salida por cada millón de tokens para contextos de 1 millón. Calcule su volumen estimado con la Calculadora de costos de API y la Calculadora de punto de equilibrio entre auto-alojamiento e API antes de adquirir una GPU.

GGUF frente a safetensors, AWQ y 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.

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ó.

Para conocer el origen del formato y cómo GGUF reemplazó a GGML, consulte ¿Qué es GGUF?.

Preguntas frecuentes

¿Qué significa GGUF y en qué se diferencia de GGML?

GGUF significa Formato Unificado Generado por GPT. GGML fue el formato anterior del mismo proyecto; rompía la compatibilidad cada vez que se requerían nuevos metadatos. GGUF incorporó un bloque extensible de metadatos clave-valor, lo que permite añadir nuevas arquitecturas y opciones sin invalidar archivos antiguos. Los archivos .bin GGML anteriores a GGUF ya no se cargan en las versiones actuales de llama.cpp.

¿Qué cuantización debo descargar?

Comience con Q4_K_M. Si el modelo aún deja varios GB de VRAM libres, pruebe Q5_K_M o Q6_K. Si no cabe en la memoria disponible, prefiera un modelo más pequeño en Q4_K_M antes que el mismo modelo en Q2_K: un modelo de 14B a 4 bits suele superar ampliamente a uno de 32B degradado a 2 bits. Verifique el ajuste con la Calculadora de VRAM para su longitud de contexto prevista.

¿Puedo ejecutar modelos GGUF sin GPU?

Yes — CPU-only inference is what GGUF was built for. Speed is bound by memory bandwidth, so expect single-digit tokens per second for a 7B–8B model at Q4_K_M on typical dual-channel desktop RAM, and slower for anything larger. Small models like Gemma 3 4B (~3 GB at 4-bit) are the practical CPU-only choice.

¿Puedo convertir yo mismo un modelo de Hugging Face a GGUF?

Sí. llama.cpp incluye un script de conversión (convert_hf_to_gguf.py en versiones actuales; en versiones anteriores el nombre del archivo usaba guiones) que genera un GGUF en F16, y luego el binario llama-quantize lo comprime a la cuantización objetivo. Revise la ayuda del script con --help en la copia que clonó, y confirme que su arquitectura es compatible antes de comenzar: las arquitecturas no soportadas fallan durante la conversión.

¿Admiten los modelos GGUF visión o llamadas a herramientas?

La invocación de herramientas (tool calling) funciona cuando la plantilla de chat del modelo lo define y su cargador respeta dicha plantilla. Los modelos multimodales requieren un segundo archivo: un mmproj GGUF que contiene el proyector visual, cargado junto con los pesos del texto. Las herramientas multimodales de llama.cpp han sido renombradas y reorganizadas varias veces, así que siga siempre la documentación actual del repositorio y no tutoriales obsoletos.

¿La cuantización modifica la ventana de contexto?

No. El contexto es una propiedad del modelo, no de la cuantización: Llama 3.3 70B tiene 128K y Llama 4 Scout tiene 10M, independientemente de que ejecute en F16 o Q4_K_M. Lo que cambia es si puede permitirse la caché KV para ese contexto en memoria. Compare contexto y precios entre modelos en la Clasificación de modelos de lenguaje grande (LLM).