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

Ambas rutas terminan igual: en un modelo con nombre dentro de la biblioteca local de Ollama, que ollama run y la API de Ollama pueden servir. Use la primera ruta cuando otra persona haya publicado el archivo. Use la segunda si cuantificó el modelo usted mismo, si el archivo llegó mediante scp o rsync, o si el equipo no puede acceder a Hugging Face.

Un archivo GGUF es un único binario que contiene los pesos, el tokenizador y los metadatos del modelo. Es el formato que lee llama.cpp, y Ollama está basado en llama.cpp. Por eso, casi todos los modelos abiertos tienen una conversión GGUF creada por la comunidad. Ollama no carga directamente una carpeta de pesos .safetensors, por lo que el paso de conversión tiene una razón.

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á activo 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 usa la ruta del repositorio con un 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 otra shell y ejecute ollama list para ver el nombre con el que se almacenó. Ese nombre es toda la cadena hf.co/... con su etiqueta, y es 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 únicamente pesos .safetensors no proporciona nada que Ollama pueda descargar, por lo que debe realizar la conversión descrita más adelante.

¿Qué cuantización elige Ollama?

La documentación de Ollama de Hugging Face, consultada el 25 de agosto 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 lo está, elegimos un tipo de cuantización razonable disponible en el repositorio». Por tanto, un repositorio que publica diez cuantizaciones le proporciona Q4_K_M, y un repositorio sin Q4_K_M le proporciona una opción que Ollama eligió por usted. Vuelva a consultar esa página antes de basarse en este comportamiento, porque los valores predeterminados cambian.

Solicite una cuantización concreta 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, por lo que debe abrir la pestaña Files and versions y leer los nombres de archivo reales antes de escribir uno. La cuantización que necesita depende de la memoria disponible y de la calidad, y la diferencia entre Q4, Q8 y FP16 explica correctamente esa relación.

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 allí el Modelfile y haga que FROM apunte 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 flag 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 del contexto y la cuantización que Ollama leyó de los metadatos del propio archivo. Compruebe esos valores en lugar de confiar en el nombre del archivo, porque el nombre es una cadena que alguien escribió manualmente. Si el modelo responde a su prompt 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.

Tenga en cuenta el espacio en disco: ollama create copia el GGUF en el 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. Elimine el archivo de origen cuando ollama run my-model funcione o guárdelo en una ubicación por la que no pague dos veces. dónde guarda Ollama sus modelos en disco describe la estructura y cómo moverlo.

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

ollama create tiene un flag --quantize, que existe para un solo caso: un modelo de origen en FP16 o FP32, es decir, con pesos de precisión completa. La documentación de importación de Ollama enumera q8_0 y las variantes de k-means q4_K_S y q4_K_M como destinos.

ollama create --quantize q4_K_M my-model

No use ese flag con un archivo que ya esté cuantizado. Un .gguf cuyo nombre incluya Q4_K_M o Q5_K_S ya ha pasado por este proceso, por lo que el flag no tiene ningún efecto. La cuantización es una conversión en un solo sentido desde una precisión mayor, por lo que no existe una ruta de Q4 a Q8. Si el origen es un repositorio de Hugging Face con archivos .safetensors, conviértalo primero con convert_hf_to_gguf.py del repositorio de llama.cpp, que es la herramienta indicada por la documentación de Ollama, y después importe el GGUF que genere ese script. Cómo se relacionan Ollama y llama.cpp explica por qué el script de conversión pertenece 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 específica. Sólo necesita un Modelfile 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 25 August 2026, indica que se usa Q4_K_M cuando esa cuantización está presente en el repositorio. Si no lo está, 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 faltan esos metadatos o no se reconocen, usa un contenedor genérico. Por eso, el modelo nunca recibe 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 convierte una fuente FP16 o FP32 durante ollama create. Un archivo cuyo nombre ya incluye una cuantización, como Q4_K_M, ya se ha convertido. La precisión no se puede recuperar cuantizando de nuevo y no existe una conversión inversa a una precisión superior. Use esta opción sólo cuando haya convertido usted mismo safetensors en un GGUF de precisión completa y ahora quiera generar uno más pequeño.

¿Cómo puedo descargar un repositorio privado de GGUF?

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