Importar un modelo GGUF de Hugging Face a Ollama

#¿Por qué importar un GGUF de Hugging Face?

Ollama mantiene una biblioteca de modelos prácticos (ollama.com/library), pero está limitada deliberadamente: los responsables de su mantenimiento publican los modelos más solicitados, con cuantizaciones elegidas para esos modelos. En cuanto buscas un modelo especializado mediante fine-tuning, una versión recién lanzada, un modelo en francés o una cuantización concreta, tienes que buscarlo en Hugging Face, la mayor plataforma para compartir modelos de pesos abiertos.

El formato GGUF (sucesor de GGML) es el que Ollama admite de forma nativa: un archivo único que contiene los pesos cuantizados, el tokenizer y los metadatos del modelo. Colaboradores como TheBloke, bartowski o unsloth publican miles de GGUF listos para usar, a menudo en unas diez cuantizaciones por modelo. Saber importarlos te da acceso a todo este ecosistema desde tu instalación de Ollama.

Modelos recientes

Un modelo publicado ayer en Hugging Face es usable antes incluso de aparecer en la biblioteca oficial de Ollama.

Fine-tunes de nicho

Modelos especializados (código, medicina, juego de rol, francés) que nadie se ha tomado la molestia de empaquetar oficialmente.

Cuantización precisa

Elegir exactamente el nivel (Q4_K_M, Q5_K_M, Q8_0…) que quepa en tu VRAM, en lugar de limitarse a la variante predeterminada.

Modelos privados

Tus propios fine-tunes o GGUF descargados, importados localmente a través de un Modelfile.

#Prerrequisitos

Ollama instalado

Versión reciente (0.5+) para el soporte nativo de hf.co. El daemon escucha por defecto en http://localhost:11434. Compruébalo con «ollama --version».

Una conexión a internet

Para el método directo que descarga desde Hugging Face. Después el modelo corre 100 % localmente.

Suficiente VRAM o RAM

Como referencia, en Q4: un 7B cabe en ~5 GB, un 14B en ~9 GB, un 32B en ~19 GB y un 70B en ~40 GB. Sin GPU, lo que cuenta es la RAM, aunque la ejecución es más lenta.

El nombre de un repositorio GGUF

Por ejemplo, bartowski/Qwen3.5-9B-Instruct-GGUF. Localízalo en la URL de la página del modelo en Hugging Face.

Para encontrar un repositorio GGUF, la búsqueda de Hugging Face permite filtrar por formato. Busca el nombre del modelo y añade «GGUF», o filtra por la biblioteca «GGUF» en la barra lateral. Abre la pestaña «Files and versions»: allí verás la lista de archivos .gguf, uno por cuantización, con su tamaño en GB, una información valiosa para los siguientes pasos.

#Método directo: ollama run hf.co/...

Es, con diferencia, la forma más sencilla de importar un modelo GGUF de Hugging Face a Ollama. Desde la versión 0.5, Ollama puede descargar un GGUF directamente desde un repositorio de Hugging Face con un solo comando, sin descargar el archivo manualmente ni escribir un Modelfile. La sintaxis utiliza la ruta del repositorio con el prefijo hf.co/.

# Format : ollama run hf.co/{utilisateur}/{depot}
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF

Si no especificas ninguna, Ollama elige una cuantización por defecto (generalmente Q4_K_M si existe en el repositorio). Para seleccionar una cuantización concreta, añádela después de dos puntos, exactamente como una etiqueta de modelo convencional. El nombre de la etiqueta corresponde al sufijo del archivo .gguf, sin distinguir entre mayúsculas y minúsculas.

# Choisir explicitement Q5_K_M
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q5_K_M

# Ou une version plus légère pour une petite carte
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M

Ollama descarga el archivo, lo almacena en su almacenamiento local y comienza la conversación. El modelo aparece luego en «ollama list» con su nombre completo hf.co/... y se vuelve a arrancar inmediatamente. Puedes darle un alias más corto con «ollama cp» si el nombre te parece demasiado largo para escribir.

# Copier vers un alias court
ollama cp hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M qwen-fr

# Désormais utilisable simplement
ollama run qwen-fr

#Elegir la cuantización adecuada según tu VRAM

Un mismo modelo se publica con varias cuantizaciones: es el compromiso central entre calidad y memoria. Cuanto más agresiva es la cuantización (menos bits por peso), más pequeño es el archivo y más fácil resulta que quepa en una tarjeta modesta, a costa de una ligera pérdida de precisión. Lo recomendable es elegir la cuantización más alta que quepa cómodamente en tu VRAM.

Q4_K_M — recomendado

El mejor equilibrio para la gran mayoría de los usos. Pérdida de calidad casi imperceptible, huella de memoria reducida. Elegir por defecto si dudas.

Q5_K_M — un paso más arriba

Ligeramente más pesado, ligeramente más preciso. Interesante si tu VRAM tiene margen y quieres la máxima calidad sin pasar a 8 bits.

Q8_0 — casi sin pérdida

Muy cercano al modelo no cuantizado, pero ocupa aproximadamente el doble de memoria que el Q4. Reservado para los casos en los que incluso la más mínima degradación importa y no falta VRAM.

FP16 — precisión completa

El modelo no cuantizado, el más pesado. Raramente necesario para inferencia local: Q8_0 es suficiente casi siempre y reduce la memoria a la mitad.

Para estimar si una cuantización cabe en memoria, guíate por el tamaño del archivo .gguf mostrado en Hugging Face y añade un margen de aproximadamente 1 a 2 GB para el contexto y el sistema. Estos son los valores de referencia de VRAM en Q4_K_M según el tamaño del modelo y las GPU típicas que permiten ejecutarlos.

3B ≈ 2 GB

Funciona en cualquier equipo, incluso con una tarjeta de gama de entrada o en CPU. Ideal para una RTX 3060 de 12 GB, con margen de sobra para el contexto.

7B ≈ 5 GB

Funciona con holgura en una RTX 3060 de 12 GB o una RTX 4070 de 12 GB. El formato más versátil para el uso diario.

14B ≈ 9 GB

RTX 4070 de 12 GB (muy justa), RTX 4080 de 16 GB con margen. Un buen nivel de calidad para el razonamiento y el código.

32B ≈ 19 GB

RTX 4090 de 24 GB, o Mac M4 Pro con memoria unificada. La gama alta accesible en una estación de trabajo.

70B ≈ 40 GB

Necesita 48 GB o más: un Mac Studio con mucha memoria unificada o una configuración multi-GPU. Pasa a Q4 o incluso a una cuantización más agresiva.

#Método Modelfile: FROM fichier.gguf

El método directo supone que el GGUF está en Hugging Face y es accesible en línea. Pero si ya has descargado un archivo .gguf a mano, has generado el tuyo con llama.cpp o quieres personalizar el modelo (system prompt, parámetros), debes usar un Modelfile. Es un pequeño archivo de texto, al estilo de un Dockerfile, que describe cómo construir un modelo Ollama a partir de un GGUF local.

La directiva central es FROM, que apunta hacia la ruta del archivo .gguf. Crea un archivo llamado « Modelfile » (sin extensión) al lado de tu GGUF, con al menos esta línea.

FROM ./mon-modele.Q4_K_M.gguf

Luego crea el modelo con «ollama create», dándole el nombre que quieras. Ollama lee el GGUF, lo guarda en su almacenamiento y lo pone a disposición como cualquier otro modelo.

# Construire le modèle depuis le Modelfile du dossier courant
ollama create mon-modele -f ./Modelfile

# Le lancer
ollama run mon-modele

Un Modelfile completo puede ir mucho más allá: establecer un prompt de sistema, ajustar los parámetros de muestreo y, sobre todo, definir el TEMPLATE —el formato de chat que espera el modelo—. Ahí se resuelven la mayoría de los problemas de calidad, como se ve en la sección siguiente.

FROM ./mon-modele.Q4_K_M.gguf

# System prompt par défaut
SYSTEM """Tu es un assistant francophone concis et précis."""

# Paramètres d'inférence
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"

# Template de chat (exemple format ChatML)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

#Corregir una plantilla de chat defectuosa

Es el principal problema al importar GGUF. Un modelo importado puede responder de cualquier manera: frases que nunca terminan, etiquetas extrañas en la salida (<|im_end|>, [INST], <end_of_turn>), respuestas que ignoran la pregunta o entran en bucle. Nueve de cada diez veces, el problema no es que el modelo sea malo: es que la plantilla de chat no coincide con la utilizada durante su entrenamiento.

Cada familia de modelos requiere un formato de conversación preciso: ChatML (<|im_start|>) para Qwen y muchos modelos ajustados, [INST]...[/INST] para Mistral y Llama 2, <start_of_turn> para Gemma y un formato específico para Llama 3. Si el GGUF incorpora una plantilla incorrecta en sus metadatos, o si Ollama infiere una incorrecta, las respuestas empeoran. El síntoma más habitual: las etiquetas de fin de turno aparecen como texto literal en la respuesta en lugar de detener la generación.

Síntoma: etiquetas visibles

El modelo muestra <|im_end|> o <|eot_id|> en su respuesta. Falta un PARAMETER stop correspondiente, o la plantilla no emite el token de fin correcto.

Síntoma: generación infinita

El modelo nunca se detiene y encadena los turnos por sí solo. El token de finalización esperado no está declarado.

Síntoma: respuestas incoherentes

El modelo ignora el prompt de sistema o responde fuera de tema. El formato de los roles (system/user/assistant) no coincide con el del entrenamiento.

La corrección consiste en proporcionar el TEMPLATE correcto y los PARAMETER stop adecuados en un Modelfile. La fuente de referencia es la «model card» de Hugging Face del modelo original: busca la sección «prompt format» o «chat template», que indica el formato exacto. Para un modelo ChatML (Qwen y derivados), la plantilla y las secuencias de parada tienen un aspecto similar al siguiente.

FROM ./mon-modele.Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"

Reconstrúyelo después con «ollama create» y pruébalo. Un truco eficaz para recuperar la plantilla correcta sin reescribirla: parte de un modelo oficial de la misma familia que ya esté presente en Ollama e inspecciona su Modelfile generado; después, reutiliza su bloque TEMPLATE.

# Voir le Modelfile complet d'un modèle officiel de la même famille
ollama show --modelfile qwen3.5:9b

# Copiez-en le bloc TEMPLATE et les PARAMETER stop
# dans votre propre Modelfile, puis reconstruisez
ollama create mon-modele -f ./Modelfile

#Solución de problemas

« Error: pull model manifest »

La ruta hf.co está mal escrita, el repositorio es privado o tiene acceso restringido (gated), o tu versión de Ollama es demasiado antigua. Revisa la URL exacta del repositorio y actualiza Ollama.

El tag de cuantización no existe

Ollama indica que no se encuentra la etiqueta: abre «Files and versions» en Hugging Face y copia el sufijo exacto del archivo .gguf (por ejemplo, Q4_K_M, IQ4_XS). No se distingue entre mayúsculas y minúsculas, pero el nombre debe coincidir.

Modelo muy lento / respuestas intermitentes

Por falta de VRAM, parte del modelo se carga en la RAM y se ejecuta en la CPU. Comprueba con «ollama ps» si se ejecuta en la GPU o en la CPU y baja un nivel de cuantización o elige un modelo de menor tamaño.

El repositorio solo contiene safetensors

No hay .gguf disponible: busca una versión « GGUF » convertida por la comunidad o convierte tú mismo el modelo con los scripts de llama.cpp.

Salidas contaminadas por etiquetas

Plantilla de chat incorrecta: consulta la sección anterior y proporciona el TEMPLATE correcto y los PARAMETER stop mediante un Modelfile.

#Para ir más allá

Importar un GGUF se basa en dos habilidades básicas del ecosistema Ollama. Estas guías del sitio amplían esta guía:

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

Comprender en detalle el equilibrio calidad/memoria para elegir la variante GGUF adecuada según tu tarjeta.

Personalizar un modelo con Ollama Modelfile

Ir más allá con el Modelfile: prompts de sistema, parámetros, plantillas y múltiples variantes de un mismo modelo.

Instalar Ollama: Windows, macOS y Linux

Guía de instalación básica, actualizada, si empiezas desde cero antes de importar tus primeros GGUF.