Cómo importar un modelo GGUF en Ollama

Dos formas de importar un modelo GGUF en Ollama

Hay dos formas de importar un modelo GGUF en Ollama. La adecuada depende de dónde esté el archivo. Si el modelo está en un repositorio de Hugging Face, un único comando ollama run lo descarga y lo ejecuta sin usar un Modelfile. Si el archivo .gguf ya está en el disco del servidor, debe escribir un Modelfile de dos líneas y ejecutar ollama create.

Ambos métodos terminan igual: un modelo con nombre en la biblioteca local de Ollama que ollama run y que la API de Ollama puede ofrecer. Use el primer método cuando otra persona haya publicado el archivo. Use el segundo si ha cuantizado el modelo usted mismo, si el archivo llegó mediante scp o rsync, o si el equipo no puede conectarse a Hugging Face.

Un archivo GGUF es un único archivo binario que contiene los pesos, el tokenizador y los metadatos del modelo. Es el formato que lee llama.cpp. Ollama está basado en llama.cpp, por lo que casi todos los modelos abiertos tienen una conversión GGUF de la comunidad. Ollama también puede importar un directorio de pesos .safetensors, pero ese es un método distinto. La sección sobre --quantize explica dónde encaja.

Todo lo que sigue presupone que Ollama ya está instalado y que su servicio está en ejecución. Si no es así, empiece por instalar Ollama en un VPS y vuelva después. Ejecute ollama list primero. Si devuelve una tabla, aunque esté vacía, en lugar de un error de conexión, el servidor está disponible y el resto de esta guía funcionará.

Ruta uno: ejecutar un GGUF de Hugging Face sin Modelfile

Ollama puede descargar un GGUF directamente desde un repositorio de Hugging Face. El comando consiste en la ruta del repositorio con el prefijo hf.co/:

ollama run hf.co/{username}/{repository}

Tanto hf.co como huggingface.co funcionan como nombre de dominio. Este es un ejemplo real de la documentación de Hugging Face:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

La primera ejecución descarga el archivo, por lo que el indicador de chat no aparece hasta que termina la descarga. Después, el modelo queda en la biblioteca local y se inicia rápidamente. Abra un segundo shell y ejecute ollama list para ver el nombre con el que se almacenó. Ese nombre es la cadena hf.co/... completa con su etiqueta, y es demasiado larga para escribirla cada vez. Asígnele un alias corto:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Esta ruta sólo funciona con repositorios que contienen archivos GGUF. Un repositorio que publica pesos .safetensors y ningún otro formato no ofrece nada que esta ruta pueda descargar. En ese caso, necesita una de las importaciones locales descritas más adelante.

¿Qué cuantización elige Ollama?

La documentación de Ollama para Hugging Face, consultada el 10 de octubre de 2026, es explícita sobre el valor predeterminado: "De forma predeterminada, se usa el esquema de cuantización Q4_K_M cuando está presente en el repositorio del modelo. Si no está presente, elegimos un tipo de cuantización razonable disponible en el repositorio." Por tanto, un repositorio que publica diez cuantizaciones le proporciona Q4_K_M, mientras que en un repositorio sin Q4_K_M Ollama elige una por usted. Vuelva a consultar esa página antes de depender de este comportamiento, porque los valores predeterminados cambian.

Solicite una cuantización específica añadiéndola como etiqueta:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

El nombre de la cuantización no distingue entre mayúsculas y minúsculas, por lo que :iq3_m y :IQ3_M significan lo mismo. También puede pasar el nombre de archivo exacto como etiqueta. Esta es la forma segura cuando los nombres cortos del repositorio son ambiguos. La etiqueta debe identificar un archivo existente en ese repositorio. Abra la pestaña Files and versions y consulte los nombres de archivo reales antes de escribir uno. La cuantización que debe elegir depende de la memoria disponible y de la calidad que necesite. La diferencia entre Q4, Q8 y FP16 explica correctamente ese compromiso.

Ruta dos: importar un archivo .gguf desde el propio disco

Cuando el archivo ya está en el servidor, necesita un Modelfile. Puede contener una sola línea. Cree un directorio, coloque el Modelfile dentro y apunte FROM al archivo:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Guárdelo como Modelfile y cree el modelo:

ollama create my-model

ollama create busca de forma predeterminada un archivo llamado Modelfile en el directorio actual. Use -f cuando el archivo tenga otro nombre o esté en otra ubicación, como en ollama create my-model -f /home/you/models/my-model/Modelfile. Ejecute ollama create --help para ver el indicador y su valor predeterminado en su compilación. La ruta de FROM puede ser absoluta o relativa al Modelfile, por lo que FROM ./my-model-Q4_K_M.gguf funciona cuando ambos están en el mismo directorio. Una ruta absoluta elimina cualquier duda.

Compruebe el resultado antes de confiar en él:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list debería incluir ahora my-model. ollama show my-model muestra la arquitectura, el número de parámetros, la longitud de contexto y la cuantización que Ollama leyó de los metadatos del propio archivo. Lea esos valores en lugar de confiar en el nombre del archivo, porque un nombre de archivo es una cadena que alguien escribió manualmente. Si el modelo responde a su solicitud de prueba en lenguaje normal y después se detiene, la importación funcionó. Si no lo hace, vaya a la sección sobre plantillas que aparece más abajo, porque esa es casi siempre la causa.

Hay un aspecto que debe tener en cuenta sobre el espacio en disco: ollama create copia el GGUF al almacén de modelos propio de Ollama en lugar de hacer referencia al archivo en su ubicación actual. Los pesos ocupan espacio dos veces hasta que elimine el original. Borre el archivo de origen cuando ollama run my-model funcione o consérvelo en una ubicación cuyo espacio no se contabilice dos veces. dónde guarda Ollama sus modelos en el disco explica la estructura y cómo moverla.

Cuándo se aplica --quantize y cuándo no

ollama create tiene un indicador --quantize, que actualmente sólo se aplica a un caso: un modelo importado desde un directorio de pesos .safetensors. El texto de ayuda de la versión actual del código fuente de Ollama, comprobado el 10 October 2026, dice "Quantize safetensors model to this level (e.g. nvfp4)", y los valores aceptados son int4, int8, nvfp4, mxfp4 y mxfp8. Los nombres de cuantización de GGUF, como q8_0 o q4_K_M, se rechazan como tipos no compatibles. La documentación de Ollama sobre la importación es clara en lo que respecta a GGUF: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Ese comando presupone un Modelfile cuya línea FROM apunta al directorio que contiene los archivos .safetensors.

No pase ese indicador cuando FROM nombre un .gguf, independientemente de su precisión. Un GGUF FP16 o FP32 se rechaza igual que uno Q4_K_M, con un error que comienza por "create-time quantization is only supported for safetensors imports". Un .gguf cuyo nombre contiene Q4_K_M o Q5_K_S ya ha sido cuantizado, y la precisión descartada no se puede recuperar. llama-quantize de llama.cpp puede volver a codificar ese archivo con otro tipo, incluido Q8_0, cuando se pasa --allow-requantize, pero su manual advierte que esto "can severely reduce quality compared to quantizing from 16bit or 32bit", y un archivo Q4 reescrito como Q8 ocupa más espacio sin mejorar. Para reducir el tamaño de un GGUF de precisión completa, ejecute primero llama-quantize sobre él. Esa es la herramienta que recomienda la documentación de Ollama. Después, importe el archivo que escriba. Si el origen es un repositorio de Hugging Face con archivos .safetensors, puede apuntar FROM a ese directorio y dejar que ollama create lo importe, usando --quantize si quiere reducir su tamaño. También puede convertirlo con convert_hf_to_gguf.py del repositorio de llama.cpp e importar el GGUF que escriba ese script. Cómo se relacionan Ollama y llama.cpp explica por qué esas herramientas pertenecen al otro proyecto.

¿Por qué un GGUF importado responde con texto basura o no se detiene?

Este es el fallo que la mayoría de los tutoriales de importación omiten, y es el que probablemente encontrará. Los síntomas parecen indicar que el modelo está dañado. Los tokens de control aparecen como texto visible en la respuesta, por ejemplo cadenas como <|im_start|>assistant o <|end|>. El modelo responde, después escribe una nueva pregunta del usuario y también responde a esa pregunta. La generación continúa hasta que pulsa Ctrl+C.

El modelo está bien. La plantilla de chat es incorrecta. Una plantilla de chat es la envoltura que convierte su mensaje en la secuencia exacta de tokens con la que se entrenó el modelo. También incluye sus propios marcadores para indicar dónde termina el prompt del sistema y dónde comienza el turno del usuario. Ollama selecciona una por usted: la documentación indica que la plantilla «se seleccionará automáticamente de una lista de plantillas de uso común», según los metadatos integrados tokenizer.chat_template almacenados dentro del archivo GGUF. Si faltan esos metadatos o no coinciden con ninguna plantilla de la lista, se usa una envoltura genérica. El modelo recibe entonces un prompt con un formato distinto de todos los que vio durante el entrenamiento. Por eso nunca encuentra el marcador de fin de turno que aprendió a reconocer para detenerse.

Muestre la plantilla que Ollama seleccionó realmente:

ollama show --template my-model
ollama show --modelfile my-model

Una plantilla vacía o claramente genérica lo confirma. Escriba usted mismo la plantilla en el Modelfile:

FROM /home/you/models/my-model-Q4_K_M.gguf

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

PARAMETER stop "<|end|>"

Recompile con ollama create my-model y envíe de nuevo el mismo prompt de prueba. El parámetro stop es su mecanismo de protección: indica a Ollama que detenga la generación cuando aparezca esa cadena. Así se elimina el síntoma de que la generación no se detiene, incluso mientras sigue ajustando la propia plantilla. Si la respuesta continúa porque nunca aparece ninguno de los marcadores que especificó, un límite de num_predict la detiene después de un número fijo de tokens, independientemente de lo que emita la plantilla.

La plantilla debe ser una plantilla de Go, no una plantilla de Jinja. La documentación de Hugging Face lo indica directamente. Esto es importante porque el campo tokenizer.chat_template del repositorio original del modelo contiene Jinja. Pegar ese contenido sin modificarlo no funciona. La sintaxis de Ollama tiene tres variables: {{ .System }} para el prompt del sistema, {{ .Prompt }} para el mensaje del usuario y {{ .Response }} para la respuesta del modelo. Busque los marcadores de turno reales del modelo en su tarjeta del modelo o en su tokenizer_config.json. Después, conviértalos manualmente a esa sintaxis de Go.

Un método abreviado evita la mayor parte de ese trabajo. Muchos modelos comparten un formato de prompt. Si otro modelo de su biblioteca usa el mismo formato, ejecute ollama show --template contra ese modelo y copie el resultado.

Los archivos template, system y params en un repositorio de Hugging Face

La opción de Hugging Face ofrece los mismos controles mediante archivos del repositorio, en lugar de instrucciones en un Modelfile. Si es propietario del repositorio o publica su propia quant, añádalos allí y todos los ollama run hf.co/... los utilizarán.

• Un archivo llamado template contiene la plantilla de Go. Se aplica la misma regla: Go, no Jinja.
• Un archivo llamado system contiene el prompt del sistema.
• Un archivo llamado params contiene los parámetros de muestreo y debe estar en formato JSON.

Un archivo params mínimo:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Si no es propietario del repositorio, no puede añadir esos archivos. Descargue el modelo una vez, ejecute ollama show --modelfile hf.co/... para volcar lo que recibió y guarde esa salida como un Modelfile. Su línea FROM apunta al blob que Ollama ya descargó, por lo que puede editar las líneas TEMPLATE y PARAMETER y ejecutar ollama create para crear una copia local corregida sin volver a descargar nada. Este es el procedimiento estándar para corregir una quant defectuosa de otra persona.

Cómo importar un repositorio GGUF privado

Un repositorio privado necesita la clave SSH de Ollama en tu cuenta de Hugging Face. El método documentado para esta ruta usa una clave SSH en lugar de un token de API, por lo que un token que ya tengas no permitirá acceder al repositorio.

Muestra la clave pública. En un servidor Linux donde Ollama se instaló con el script oficial, el servicio se ejecuta como el usuario ollama, por lo que la clave se encuentra en el directorio de inicio de ese usuario:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Si inicias ollama serve manualmente como tu propio usuario, la ruta es ~/.ollama/id_ed25519.pub. Copia la línea completa, abre la configuración de tu cuenta de Hugging Face en https://huggingface.co/settings/keys y añádela como una clave SSH nueva. Después, el comando normal funciona con tus repositorios privados:

ollama run hf.co/{username}/{repository}

Si la descarga sigue fallando después de añadir la clave, probablemente mostraste el archivo equivocado. El servidor realiza la descarga y presenta su propia clave. Además, un servidor iniciado por systemd nunca lee el archivo ~/.ollama de tu usuario, por lo que la clave de tu directorio de inicio no es la que ve Hugging Face.

¿El modelo cabe en su VPS?

La cifra que determina esto es el tamaño del archivo en disco más la memoria que necesita la ventana de contexto. Los pesos se cargan en memoria y ocupan aproximadamente lo mismo que en el archivo. La asignación para el contexto se añade a esa cifra y aumenta con el número de tokens permitido. Ejecute ollama list para consultar el tamaño que Ollama registró para el modelo. Compárelo con free -h en el servidor y deje margen para el sistema operativo y para los demás servicios que se ejecuten en el servidor. Si prefiere consultar ese cálculo ya realizado con un modelo real, ejecutar Nemotron 3.5 Lightning en un VPS indica la etiqueta exacta que debe descargar, la RAM que necesita y si un servidor con CPU únicamente puede mantener el ritmo.

El contexto es la parte que se suele olvidar. Un modelo que se carga con la ventana predeterminada puede fallar al aumentar num_ctx, porque esa asignación crece según el tamaño de ventana solicitado. Configurar num_ctx y su coste de memoria incluye los cálculos de dimensionamiento. Cuando el total es demasiado grande, normalmente la solución es usar un quant más pequeño del mismo modelo. Esta es la disyuntiva que se explica en la comparación entre Q4 y Q8.

El fallo es evidente. En un VPS que sólo usa CPU, el kernel detiene el proceso mediante el asesino de procesos por falta de memoria. journalctl -u ollama -n 50 junto con dmesg muestra la terminación. En un servidor con GPU, ollama ps imprime una columna PROCESSOR que indica si el modelo cargado se almacenó en la memoria de la GPU, en la memoria del sistema o repartido entre ambas. Un modelo que se desborda a la memoria del sistema sigue respondiendo, pero lentamente. Medir tokens por segundo convierte «lentamente» en una cifra que puede comparar entre quants.

Compruebe lo que ha importado

Ejecute estos cuatro comandos después de cualquier importación, en este orden:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list confirma que el modelo existe y muestra el tamaño que registró Ollama. ollama show confirma que Ollama ha leído del GGUF los metadatos que necesita. ollama show --modelfile confirma qué plantilla y parámetros utilizará realmente. Esta comprobación detecta el fallo de salida basura antes que sus usuarios. El mensaje de prueba comprueba toda la cadena, porque un modelo con una plantilla dañada falla incluso con la solicitud más corta. Cuando el mensaje se procese correctamente, el nombre que ha asignado al modelo será el mismo que proporcione a cualquier otra herramienta que se comunique con la API de Ollama, incluido un agente de programación dirigido a su propio servidor. Elimine una importación defectuosa con ollama rm my-model y vuelva a compilarla. Este comando elimina la copia de Ollama y deja intacto el archivo fuente .gguf.

FAQ

¿Puedo importar un GGUF en Ollama sin escribir un Modelfile?

Sí, cuando el archivo se encuentra en un repositorio de Hugging Face. ollama run hf.co/{username}/{repository} lo descarga y lo ejecuta directamente, y ollama run hf.co/{username}/{repository}:{quantization} selecciona una cuantización concreta. Un Modelfile sólo es necesario para un .gguf que ya esté en su propio disco. En ese caso, puede contener la línea única FROM /path/to/file.gguf seguida de ollama create my-model.

¿Qué cuantización descarga Ollama si no especifico ninguna?

La documentación de Hugging Face, consultada el 10 de octubre de 2026, indica que se usa Q4_K_M cuando esa cuantización está presente en el repositorio. Si no, Ollama elige un tipo de cuantización razonable disponible en el repositorio. Añada una etiqueta como :Q8_0 para controlarlo. Confirme qué recibió realmente con ollama show <model>. Este comando muestra la cuantización de los metadatos del archivo, no de su nombre.

¿Por qué mi modelo importado repite el texto o nunca deja de generar?

La plantilla de chat no coincide con el modelo. Ollama selecciona automáticamente una plantilla a partir de los metadatos tokenizer.chat_template del GGUF. Si esos metadatos faltan o no se reconocen, usa un contenedor genérico. Por eso, el modelo nunca ve el marcador de fin de turno con el que se entrenó. Muestre la plantilla actual con ollama show --template <model>. Después, añada un bloque TEMPLATE y una línea PARAMETER stop al Modelfile, y vuelva a ejecutar ollama create. Escríbala como una plantilla de Go. La plantilla Jinja del repositorio original no funcionará.

¿Debo usar --quantize en un GGUF que he descargado?

No. --quantize sólo funciona con importaciones de safetensors durante ollama create. Rechaza cualquier origen GGUF, incluido uno FP16 o FP32, y muestra un error que indica que los modelos GGUF deben cuantizarse antes de importarlos. Si el nombre del archivo ya incluye una cuantización como Q4_K_M, el archivo ya se ha convertido. Volver a cuantizarlo no recupera la precisión perdida: llama-quantize --allow-requantize puede reescribirlo como Q8_0, pero el resultado será más grande y no mejorará. Para obtener un archivo más pequeño a partir de un GGUF de precisión completa, ejecute llama-quantize de llama.cpp y luego importe el resultado.

¿Cómo puedo descargar un repositorio GGUF privado?

Añada la clave pública SSH de Ollama a su cuenta de Hugging Face. Muéstrela con sudo cat /usr/share/ollama/.ollama/id_ed25519.pub en una instalación estándar de Linux, o con ~/.ollama/id_ed25519.pub cuando ejecute el servidor con su propio usuario. Después, añádala en la página de configuración de claves SSH de su cuenta. A partir de ese momento, ollama run hf.co/{username}/{repository} funciona con sus propios repositorios privados y con los repositorios de una organización a la que pertenezca.