Transformers ahora soporta modelos GGUF para correr localmente

Resumen

Hugging Face integró soporte para ejecutar modelos en formato GGUF directamente desde la API de transformers. Eso significa que ahora pueden elegir un checkpoint cuantizado del Hub, cargarlo con from_pretrained y generar localmente en su propia máquina sin cambios drásticos en el flujo de trabajo. La integración reutiliza kernels de llama.cpp a través de la librería kernels para acercar el rendimiento al de llama.cpp, con un enfoque inicial en Apple Silicon y la arquitectura Qwen3.5.

¿Qué es GGUF y por qué importa?

GGUF es un formato promovido por el equipo de llama.cpp para empaquetar pesos del modelo y metadatos (incluyendo tokenizador y plantillas de chat) en un solo archivo. Soporta distintos niveles de cuantización, lo que permite reducir el uso de memoria a costa de algo de precisión. Para usuarios que quieren ejecutar modelos en laptops o máquinas con recursos limitados, esto es crucial.

Las variantes de cuantización combinan precisiones diferentes en tensores sensibles y no sensibles. Un ejemplo práctico (tomado del Hub para Qwen3.5-4B de Unsloth) muestra cómo cambia el tamaño según la cuantización:

• BF16: 8.42 GB (referencia no cuantizada)
• Q6_K: 3.53 GB (más precisión que las opciones más pequeñas)
• Q5_K_M: 3.14 GB (punto intermedio entre tamaño y precisión)
• Q4_K_M: 2.74 GB (punto de partida práctico para inferencia local)

Hugging Face recomienda comenzar con Q4_K_M y luego probar Q5_K_M o Q6_K si hay más memoria disponible. La calidad final depende del modelo y la tarea, por lo que es importante evaluar con ejemplos reales de trabajo.

Rendimiento: reutilizando lo mejor de llama.cpp

La compatibilidad por sí sola no basta: el modelo debe ser agradable de ejecutar. Para acercarse al rendimiento de llama.cpp, transformers ahora reutiliza los kernels ggml mediante la librería kernels y reduce overhead en la ruta de generación. Este enfoque permite mantener los pesos empaquetados en Metal (en macOS) y delegar operaciones críticas a implementaciones optimizadas.

El esfuerzo inicial apunta a inferencia local en Apple Silicon, lo que refleja la popularidad de los MacBook con chips M1/M2/M3 entre desarrolladores y profesionales creativos. Aunque la prioridad fue Apple Silicon, la integración con los kernels ggml y la arquitectura de transformers abre la puerta a futuras ampliaciones.

Cómo cargar un GGUF en transformers

Requisitos básicos:

• Un Mac con Apple Silicon.
• Una versión de PyTorch compatible con las compilaciones publicadas de los kernels de ggml (normalmente las dos últimas versiones de PyTorch).
• La versión más reciente de transformers (por ahora en main hasta el próximo release) y una versión compatible de la librería kernels.

Instalación rápida (según la guía oficial):

pip install -U ‘git+https://github.com/huggingface/transformers.git’ kernels

Para cargar un modelo GGUF basta con indicar el identificador del repositorio en el Hub y el nombre del archivo .gguf mediante el argumento gguf_file en from_pretrained. No se requiere configuración extra para comenzar: cuando los pesos permanecen empaquetados en Metal, transformers carga automáticamente los kernels ggml/Metal compatibles y usa ggml-org/ggml-attn como implementación de atención.

Si ese kernel no está disponible, hay una caída (fallback) a la implementación ‘sdpa’ con una advertencia; también pueden forzar explícitamente attn_implementation=‘sdpa’ si lo desean.

Ejemplo de uso (flujo estándar de transformers):

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = 'unsloth/Qwen3.5-4B-GGUF'
filename = 'Qwen3.5-4B-Q4_K_M.gguf'

tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)

messages = [{'role': 'user', 'content': 'Explica por qué el cielo es azul en pocas oraciones.'}]
inputs = tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_dict=True, return_tensors='pt').to(model.device)

with torch.inference_mode():
    outputs = model.generate(**inputs, max_new_tokens=256)

print(tokenizer.decode(outputs[0], skip_special_tokens=True))

Ese paso de especificar gguf_file es lo único específico para GGUF; luego todo sigue con la API conocida de transformers.

Servir GGUF con transformers serve y conectar clientes

Si prefieren exponer el modelo vía API, pueden usar transformers serve, que ofrece una API compatible con OpenAI. La instalación sugiere:

pip install -U ‘transformers[serving] @ git+https://github.com/huggingface/transformers.git’ kernels

Y ejecutar el servidor indicando <model_id>:<archivo.gguf>:

transformers serve ‘unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf’

El argumento model usa el formato repositorio:archivo.gguf para seleccionar una cuantización específica dentro de un repositorio que puede contener varios archivos.

Opciones de reasoning: algunos modelos incluyen plantillas de chat con soporte para ‘thinking’ (razonamiento). Pueden controlar ese comportamiento con —reasoning off para desactivarlo, —reasoning on para activarlo, o dejar —reasoning auto para respetar la configuración por defecto de la plantilla.

Para integrar clientes como Jan o Pi, pueden crear un proveedor compatible con OpenAI usando estos parámetros básicos:

• Base URL: http://localhost:8000/v1
• Model ID: unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf

Transformers ejecutará el modelo localmente y el cliente se encargará de la interfaz conversacional. Este endpoint también puede ser consumido por otros clientes que implementen la API compatible.

Comportamiento ante kernels no disponibles y recomendaciones

Si no se consigue un kernel de cuantización compatible, el cargador puede deshacer la cuantización (dequantize) y así usar más memoria. Esto significa que, para obtener los beneficios de memoria y rapidez de la cuantización, es importante contar con las compilaciones de kernels adecuadas para su PyTorch y su plataforma.

En la práctica, prueben primero con Q4_K_M para modelos que deben ejecutarse en laptops; si disponen de más RAM o prefieren mayor fidelidad, prueben Q5_K_M o Q6_K. La decisión depende del caso de uso real: generación de texto, codificación, chat, etc.

¿Qué significa esto para equipos en América Latina?

La posibilidad de ejecutar modelos cuantizados localmente reduce barreras en entornos con conectividad limitada, restricciones de datos sensibles o presupuestos ajustados para infraestructuras en la nube. Equipos de producto, investigación aplicada y desarrolladores pueden experimentar modelos recientes sin depender exclusivamente de servicios externos, facilitando pruebas de concepto y despliegues privados.

Además, al aprovechar formatos y herramientas populares como GGUF y llama.cpp, la comunidad local puede intercambiar checkpoints optimizados en el Hub y adaptarlos a flujos de trabajo ya conocidos en transformers.

Conclusión

La integración de GGUF en transformers acerca la ejecución local de modelos grandes al flujo de trabajo estándar de los desarrolladores. Reutilizar kernels de llama.cpp y ofrecer opciones de servicio compatibles con OpenAI hacen que sea más sencillo —y práctico— correr modelos cuantizados en laptops, empezando por Apple Silicon. Para equipos en América Latina, esto representa una vía viable para explorar capacidades de IA con mayor control sobre datos y costos, siempre evaluando la cuantización en sus tareas reales.