Importar modelos: GGUF, Safetensors y adapters

Importar un modelo desde un archivo GGUF

Los modelos en formato GGUF (habituales en el ecosistema de llama.cpp) se pueden usar en Ollama sin convertirlos a otro formato. En el Modelfile basta con que FROM apunte a la ruta del archivo .gguf, en absoluta o relativa al propio Modelfile.

Ejemplo con ruta relativa (el GGUF está en la misma carpeta que el Modelfile):

FROM ./modelo.gguf

Con ruta absoluta:

FROM /home/usuario/descargas/mi-modelo-q4.gguf

Guarda el Modelfile (por ejemplo como Modelfile), sitúate en el directorio donde está y ejecuta:

ollama create nombre-del-modelo -f Modelfile

Ollama leerá el GGUF, lo registrará como modelo y podrás usarlo con ollama run nombre-del-modelo. Si el GGUF ya está cuantizado (Q4, Q8, etc.), el modelo creado usará esa cuantización. Si tienes un GGUF en FP16 o FP32, puedes cuantizarlo en la creación con ollama create -f Modelfile --quantize q4_K_M nombre-del-modelo.

Puedes obtener GGUF desde sitios como Hugging Face o generarlos a partir de modelos Safetensors usando scripts de llama.cpp (por ejemplo convert_hf_to_gguf.py). La documentación oficial de importación está en docs.ollama.com/import.

flowchart TD
    A{"Origen del modelo"} -->|"Archivo .gguf"| B["FROM ./modelo.gguf"]
    A -->|"Directorio Safetensors"| C["FROM ./directorio"]
    A -->|"Adapter LoRA"| D["FROM base + ADAPTER ruta"]
    B --> E["ollama create nombre -f Modelfile"]
    C --> E
    D --> E
    E --> F{"¿Pesos en FP16 / FP32?"}
    F -->|"Sí"| G["--quantize q4_K_M<br/>Reducir tamaño"]
    F -->|"Ya cuantizado"| H["Modelo listo"]
    G --> H

Importar un modelo desde Safetensors

Ollama puede construir un modelo a partir de pesos en formato Safetensors siempre que la arquitectura sea soportada. Las soportadas incluyen Phi3, Gemma (1 y 2), Mistral (1, 2 y Mixtral) y Llama (2, 3, 3.1, 3.2). Los pesos deben estar en un directorio (no en un único archivo suelto).

En el Modelfile, FROM debe apuntar a ese directorio:

FROM /ruta/al/directorio/con/safetensors

Si el Modelfile está dentro del mismo directorio que los pesos:

FROM .

Luego, desde ese directorio:

ollama create mi-modelo -f Modelfile

El directorio debe contener los archivos .safetensors (y normalmente el config.json del modelo). Ollama detecta la arquitectura y construye el modelo. Si el modelo está en FP16 o FP32, puedes usar --quantize en ollama create para generar una versión cuantizada (por ejemplo q4_K_M) y ahorrar memoria.

Usar un adapter (LoRA / QLoRA) con FROM y ADAPTER

Un adapter (LoRA o QLoRA) es un conjunto de pesos que se aplican sobre un modelo base para adaptar su comportamiento (por ejemplo un modelo fine-tuned para un dominio concreto). En el Modelfile necesitas:

1. FROM: el modelo base (nombre de modelo en Ollama, ruta a GGUF o directorio Safetensors).
2. ADAPTER: la ruta al adapter (directorio con Safetensors del adapter o archivo .gguf del LoRA).

El modelo base debe coincidir con el que se usó para entrenar el adapter. Si no, los resultados pueden ser incoherentes.

Adapter en formato Safetensors (directorio):

FROM llama3.2
ADAPTER /ruta/al/directorio/del/adapter

Si el Modelfile y el adapter están en el mismo directorio:

FROM llama3.2
ADAPTER .

Adapter en formato GGUF:

FROM llama3.2
ADAPTER ./mi-lora.gguf

Después:

ollama create mi-modelo-adaptado -f Modelfile

Para adapters Safetensors, Ollama recomienda usar adapters no cuantizados (no QLoRA) cuando sea posible, porque los métodos de cuantización pueden variar entre frameworks y dar problemas. Los adapters en GGUF se pueden obtener, por ejemplo, convirtiendo un LoRA Safetensors con convert_lora_to_gguf.py de llama.cpp.

Cuantizar al importar: --quantize

Al importar un modelo en FP16 o FP32 (por ejemplo un Safetensors completo o un GGUF sin cuantizar), puedes cuantizarlo en el momento de ollama create con -q o --quantize:

ollama create -f Modelfile --quantize q4_K_M mi-modelo

Así Ollama genera una versión cuantizada que ocupa menos y suele ir más rápido, con algo de pérdida de fidelidad. Algunas opciones típicas son q8_0, q4_K_M y q4_K_S (estas dos últimas son cuantizaciones K-means). La documentación de importación lista las cuantizaciones soportadas.

Esto aplica al modelo base que importas (FROM con ruta). No aplica cuando FROM es un modelo que ya está en Ollama (esos ya vienen cuantizados desde la librería). Para adapters, normalmente se usan ya en el formato en que los tienes (Safetensors o GGUF) sin un paso extra de cuantización en ollama create.

Resumen de flujos de importación

| Origen | En el Modelfile | Comando típico | |---------------------|------------------------------|-----------------------------------------| | GGUF (modelo) | FROM ./archivo.gguf | ollama create nombre -f Modelfile | | Safetensors (modelo)| FROM ./directorio | ollama create nombre -f Modelfile | | Modelo + adapter | FROM base + ADAPTER ruta | ollama create nombre -f Modelfile | | Cuantizar al crear | FROM ruta a FP16/FP32 | ollama create -f Modelfile -q q4_K_M nombre |

Una vez creado, el modelo se usa como cualquier otro: ollama run nombre, API /api/chat y /api/generate, y ollama list para verlo en el catálogo local.