GGUF, safetensors: entender los formatos de modelos

#¿Por qué existen estos formatos?

Un LLM, una vez entrenado, es simplemente una gran bolsa de números: los pesos (weights), es decir, los miles de millones de parámetros que codifican lo que el modelo «sabe». El formato de archivo es simplemente la forma en que estos números están organizados en el disco. Hay que decidir cómo almacenarlos, cómo leerlos rápidamente y qué información adicional (el vocabulario, la arquitectura, los ajustes) incluir junto con ellos.

Históricamente, estos pesos se guardaban en el formato .bin de PyTorch (pickle de Python), práctico pero lento de cargar y, sobre todo, peligroso: un archivo pickle puede ejecutar código arbitrario al abrirlo. Dos formatos se han impuesto para resolver problemas diferentes. safetensors responde a las necesidades de investigadores y plataformas: un almacenamiento seguro y rápido, fiel a la precisión original. GGUF responde a las necesidades de la inferencia local: un archivo único, compacto, cuantizado, listo para ejecutarse en una CPU o GPU de consumo.

#safetensors: el formato Hugging Face

safetensors es el formato predeterminado del ecosistema Hugging Face. Creado para sustituir el formato pickle de PyTorch, su principal ventaja está en su nombre: la seguridad. El archivo solo contiene datos (los tensores de pesos) y una pequeña cabecera JSON que describe su forma y su tipo. No contiene código ejecutable, por lo que no hay riesgo de abrir un archivo malicioso. Ventaja adicional: la carga es más rápida gracias al mapeo de memoria, que permite leer los pesos directamente desde el disco sin copiarlos todos primero a la RAM.

Seguro por diseño

Sin código ejecutable, a diferencia de los antiguos .bin/.pt en pickle. Se puede descargar un safetensors sin temor a la ejecución de código.

Precisión completa

Los pesos se almacenan generalmente en FP16 o BF16 (16 bits), o incluso en FP32. Es la precisión de entrenamiento, la que sirve de referencia.

Hecho para ser transformado

Es el formato de partida para el fine-tuning, la fusión de modelos (merge), la cuantización o la conversión a otros formatos.

A menudo dividido

Un gran modelo se divide en varios archivos (shards) acompañados de un índice JSON, porque un solo archivo de decenas de GB sería inmanejable.

El lado negativo: un safetensors en FP16 es voluminoso. Un modelo de 7B pesa aproximadamente 14 GB (2 bytes por parámetro), uno de 70B alrededor de 140 GB. Para el entrenamiento y la investigación en GPU de servidor, es la opción adecuada. Para ejecutar un modelo en tu máquina, suele ser demasiado pesado; de ahí la utilidad de la cuantización y del GGUF.

#GGUF: el formato de inferencia local

GGUF (GPT-Generated Unified Format) es el formato nacido del proyecto llama.cpp, el motor de inferencia que ejecuta LLM de forma eficiente tanto en CPU como en GPU. Sustituyó al antiguo formato GGML en 2023. Su idea principal: ponerlo todo en un solo archivo. Los pesos, el vocabulario del tokenizer, los metadatos de arquitectura (número de capas, tamaño de contexto), la plantilla de chat: todo se empaqueta junto. Descargas un archivo, lo ejecutas y funciona.

Archivo único y autónomo

Pesos + tokenizador + metadatos en un solo .gguf. Sin necesidad de montar un directorio de configuración ni de instalar dependencias de Python.

Cuantizado

Diseñado para incorporar pesos comprimidos (4, 5, 6, 8 bits). Esto es lo que permite ejecutar modelos grandes en hardware de consumo.

CPU + GPU + offload

llama.cpp puede distribuir las capas entre GPU y RAM del sistema. Se puede ejecutar un modelo más grande que la VRAM, a costa de un poco de velocidad.

Portátil

El mismo archivo .gguf funciona en Windows, macOS (Metal) y Linux, con Ollama, LM Studio, Jan o directamente con llama.cpp.

La cuantización es el núcleo del tema. Consiste en almacenar cada peso con menos bits (por ejemplo, 4 en lugar de 16), lo que divide el tamaño por un factor de entre 3 y 4 con una pérdida de calidad mínima si se elige bien. Es lo que permite que un modelo de 7B quepa en aproximadamente 5 GB de VRAM en lugar de 14. Los niveles habituales son: Q4_K_M (el mejor equilibrio, recomendado por defecto), Q5_K_M (un nivel superior en calidad), Q8_0 (casi sin pérdida, más pesado) y FP16 (sin cuantizar, referencia).

#¿Por qué Ollama y LM Studio necesitan GGUF?

Ollama y LM Studio están construidos sobre llama.cpp (o un motor equivalente), y llama.cpp admite GGUF de forma nativa. No es un capricho: es lo que hace que estas herramientas sean tan sencillas. Como GGUF ya contiene el tokenizer, la arquitectura y la plantilla de chat, la herramienta no tiene nada que adivinar. Lee el archivo, asigna la memoria y te responde. Sin entorno de Python, sin dependencias que resolver, sin configuración que escribir.

Cuando ejecutas `ollama pull llama3.2`, Ollama descarga en realidad un GGUF desde su registro y lo guarda en su almacén de modelos. Nunca ves el archivo, pero internamente se trata de un GGUF. LM Studio, en cambio, te muestra explícitamente los archivos GGUF disponibles y sus cuantizaciones en el momento de la descarga.

# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags

#Leer un nombre de archivo sin equivocarse

En Hugging Face, los nombres de archivos GGUF siguen una convención legible una vez que se conoce el código. Tomemos un ejemplo típico: `Qwen2.5-7B-Instruct-Q4_K_M.gguf`. Cada parte contiene información.

Qwen2.5

La familia y la versión del modelo.

7B

El número de parámetros: 7 mil millones. Es el primer indicador de la VRAM necesaria.

Instruct

La variante entrenada para seguir instrucciones y dialogar (a diferencia de la variante -base, en bruto y no alineada para el chat).

Q4_K_M

La cuantización: 4 bits, variante K_M (medium). El equilibrio calidad/tamaño recomendado por defecto.

.gguf

El formato. Sabes que funcionará en Ollama, LM Studio o llama.cpp sin necesidad de conversión.

El sufijo de cuantización es la parte más útil que conviene descifrar. El número indica la cantidad de bits por peso; las letras K_S / K_M / K_L designan variantes (Small, Medium, Large) que protegen en mayor o menor medida las capas sensibles. Cuanto mayor es el número, mayor es el archivo y mayor es su fidelidad.

Q4_K_M

~4 bits, medio. La opción predeterminada: la mejor calidad para su tamaño en la inmensa mayoría de los casos.

Q5_K_M

~5 bits. Algo más de calidad, archivo un poco más pesado. Buena opción si la VRAM lo permite.

Q8_0

8 bits. Casi indistinguible del no cuantizado, pero dos veces más pesado que Q4. Para puristas o tareas exigentes.

Q2_K / Q3_K

2-3 bits. Muy compacto, pero con una pérdida de calidad perceptible. Reservar para los casos en los que la memoria sea realmente crítica.

FP16 / F16

No cuantizado, precisión completa de 16 bits. La referencia, pero pesado — mejor quedarse con safetensors en este caso.

#Cuál descargar según tu herramienta

La cuestión práctica se reduce a: ¿qué herramienta voy a usar? El formato se deriva de la respuesta, no al revés.

Ollama, LM Studio, Jan, llama.cpp

→ GGUF. Estas herramientas están hechas para eso. Elige la cuantización según tu VRAM (Q4_K_M por defecto).

vLLM, TGI, Transformers (Python)

→ safetensors. Estos motores de servidor cargan el formato nativo de Hugging Face, generalmente en FP16 o con su propia cuantización (AWQ, GPTQ).

Fine-tuning, fusión, cuantización propia

→ safetensors. Es el formato de trabajo: partimos de la precisión completa para transformar el modelo.

Aún no sabes

→ GGUF cuantizado si es para un uso local en tu máquina. Es el más sencillo y más económico.

Para elegir la cuantización adecuada, ajústate a tu VRAM. Referencias en Q4: un modelo 3B cabe en ~2 GB, un 7B en ~5 GB, un 14B en ~9 GB, un 32B en ~19 GB, un 70B en ~40 GB. Una RTX 3060 de 12 GB ejecuta cómodamente modelos de 7B a 14B en Q4; una RTX 4090 de 24 GB permite apuntar a modelos de 32B; para modelos de 70B, hay que optar por una tarjeta con mucha VRAM o un Mac con memoria unificada (M4 Pro 24-48 GB).

#Convertir safetensors a GGUF

A veces, un modelo solo se publica en safetensors (algo frecuente el día de su lanzamiento) y quieres ejecutarlo en Ollama. Entonces hay que convertirlo a GGUF y, opcionalmente, cuantizarlo. La herramienta de referencia es el script `convert_hf_to_gguf.py` proporcionado por llama.cpp. El proceso se realiza en dos fases: primero convertir a GGUF de precisión completa y después cuantizar con la herramienta `llama-quantize`.

1. 01
   Obtener llama.cpp y sus dependencias

   Clona el repositorio llama.cpp e instala las dependencias de Python del script de conversión. El repositorio contiene convert_hf_to_gguf.py.
2. 02
   Descargar el modelo safetensors

   Recupera el directorio completo del modelo desde Hugging Face (pesos .safetensors + config.json + archivos del tokenizer). Todo debe estar presente, no solo los pesos.
3. 03
   Convertir a GGUF FP16

   Ejecuta convert_hf_to_gguf.py en el directorio del modelo. Obtienes un .gguf en plena precisión (16 bits), voluminoso pero fiel.
4. 04
   Cuantizar en Q4_K_M

   Pasa el GGUF FP16 a llama-quantize eligiendo el nivel deseado (Q4_K_M por defecto). El archivo final es 3 a 4 veces más ligero.
5. 05
   Importar en Ollama

   Escribe un Modelfile que apunte al .gguf cuantizado y crea el modelo con ollama create. Entonces será usable como cualquier otro modelo Ollama.

# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M

# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele

#Otros formatos que se encuentran

GGUF y safetensors cubren lo esencial, pero irás encontrando algunos otros nombres a medida que descargues modelos. Conocerlos evita sorpresas desagradables.

.bin / .pt (pickle)

El formato antiguo de PyTorch. Funcional pero no seguro (puede ejecutar código). Progresivamente reemplazado por safetensors —evítalo si existe una alternativa.

GPTQ / AWQ

Cuantizaciones para GPU destinadas a vLLM y Transformers, almacenadas en safetensors. Rápidas en GPU NVIDIA, pero Ollama/llama.cpp no pueden leerlas.

MLX

Formato de Apple para su framework MLX, optimizado para el chip Apple Silicon. Usado por algunas aplicaciones nativas de Mac, distinto del GGUF.

ONNX

Un formato de intercambio compatible con varios frameworks, sobre todo para despliegues industriales y en el edge. Poco habitual para el uso de LLM locales por parte del público general.

GGML

Antecesor de GGUF (mismo proyecto). Obsoleto: si encuentras un archivo .ggml, busca su versión equivalente en formato .gguf.

#Preguntas frecuentes

GGUF o safetensors, ¿cuál es mejor?

Ninguno de los dos es mejor en términos absolutos: sirven para usos diferentes. GGUF para ejecutar un modelo en local (Ollama, LM Studio), safetensors para el ecosistema Hugging Face, el fine-tuning y los motores de servidor. El «mejor» depende de tu herramienta.

¿Es un GGUF peor que un safetensors?

Un GGUF cuantizado pierde un poco de precisión en comparación con el safetensors FP16 original. En Q4_K_M o Q5_K_M, la diferencia es mínima y raramente perceptible en uso. En Q2 o Q3, se vuelve visible.

¿Puedo usar un safetensors directamente en Ollama?

No directamente en la mayoría de los casos: Ollama requiere GGUF. Es necesario convertir el safetensors a GGUF con llama.cpp antes. Algunas versiones recientes permiten importar safetensors, pero GGUF sigue siendo la vía confiable.

¿Por qué tantos archivos en una página de Hugging Face?

Un modelo suele dividirse en varios shards (safetensors o GGUF), además de los archivos de configuración y del tokenizer. Para GGUF, normalmente necesitas un solo archivo por cuantización (o todos los fragmentos de una serie dividida).

#Para ir más allá

Ahora que los formatos ya no tienen secretos para ti, estas guías amplían el tema de forma natural.

Elegir tu cuantización (Q4, Q5, Q8, FP16)

Guía detallada para elegir el nivel de cuantización de un GGUF según tu VRAM y tus necesidades de calidad.

Qué es Ollama y cómo funciona

Entender la herramienta que descarga y sirve modelos GGUF en local, con los comandos básicos.

Comprender la ventana de contexto

El otro parámetro que influye en el consumo de memoria: los tokens y el contexto, que hay que considerar junto con la elección de la cuantización.