Sintaxis del Modelfile: FROM, PARAMETER, SYSTEM, TEMPLATE y ADAPTER

Qué es un Modelfile

Un Modelfile es el plano con el que Ollama crea y comparte modelos personalizados. Es un archivo de texto en el que se escriben instrucciones seguidas de argumentos. Cada línea suele tener la forma INSTRUCCIÓN valor y las que empiezan por # son comentarios. El orden de las instrucciones no importa, aunque es habitual poner FROM primero para que quede claro cuál es la base del modelo.

Con un Modelfile puedes partir de un modelo existente (o de un archivo GGUF o un directorio Safetensors), fijar un mensaje de sistema, parámetros por defecto (temperatura, contexto, etc.) y, si hace falta, una plantilla de prompt o un adapter (LoRA/QLoRA). Luego usas ollama create para generar el modelo y ollama run para usarlo.

La documentación oficial del Modelfile está en docs.ollama.com/modelfile. Las instrucciones no distinguen mayúsculas de minúsculas, pero en los ejemplos se suelen escribir en mayúsculas para leerlas mejor.

flowchart TD
    A["Modelfile"] --> B["FROM<br/>Modelo base (obligatorio)"]
    A --> C["SYSTEM<br/>Mensaje de sistema"]
    A --> D["PARAMETER<br/>temperature, num_ctx, etc."]
    A --> E["TEMPLATE<br/>Plantilla del prompt"]
    A --> F["ADAPTER<br/>LoRA / QLoRA"]
    B --> G["ollama create nombre -f Modelfile"]
    C --> G
    D --> G
    E --> G
    F --> G

FROM: la base del modelo (obligatorio)

La instrucción FROM es obligatoria y define el modelo base. Puede ser un modelo ya disponible en Ollama (por nombre y opcionalmente tag), la ruta a un archivo GGUF o la ruta a un directorio con pesos en Safetensors.

Partir de un modelo existente en Ollama:

FROM llama3.2

Con tag concreto:

FROM llama3.2:3b

Partir de un archivo GGUF en la misma carpeta que el Modelfile:

FROM ./mi-modelo.gguf

La ruta al GGUF puede ser absoluta o relativa al Modelfile. Para Safetensors se indica el directorio que contiene los pesos (por ejemplo FROM /ruta/al/directorio o FROM . si el Modelfile está en ese directorio). Las arquitecturas soportadas para Safetensors incluyen Phi3, Gemma, Mistral y Llama.

PARAMETER: cómo se ejecuta el modelo

PARAMETER fija parámetros que Ollama usará al ejecutar el modelo. Se escriben como PARAMETER nombre valor. Algunos de los más útiles:

| Parámetro | Descripción breve | Ejemplo | |-------------|-------------------------------------------|----------------| | temperature | Creatividad frente a coherencia (por defecto 0.8) | temperature 0.7 | | num_ctx | Tamaño del contexto en tokens (por defecto 2048) | num_ctx 4096 | | top_p | Muestreo nucleus (junto con top_k) | top_p 0.9 | | top_k | Restringe candidatos por probabilidad | top_k 40 | | seed | Semilla para reproducir salidas | seed 42 | | stop | Secuencias que detienen la generación | stop "AI:" | | num_predict | Máximo de tokens a generar (-1 = sin límite) | num_predict 100 | | repeat_penalty | Penalización por repetición | repeat_penalty 1.1 |

Puedes poner varios PARAMETER en el mismo Modelfile. Para stop se suelen usar varias líneas si quieres varias secuencias de parada.

Ejemplo en un Modelfile:

FROM llama3.2
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
PARAMETER seed 42

Así el modelo creado a partir de este Modelfile tendrá por defecto esa temperatura, contexto y semilla. Quien use el modelo puede seguir sobrescribiendo estos valores desde la API o la CLI.

SYSTEM: el mensaje de sistema

La instrucción SYSTEM define el mensaje de sistema que se inyecta en la plantilla. Ese mensaje orienta el comportamiento del asistente (tono, rol, reglas). Puede ser una sola línea o un bloque entre comillas triples.

Una línea:

SYSTEM Eres un asistente técnico que responde en español de forma clara y concisa.

Varias líneas con comillas triples:

SYSTEM """Eres un experto en documentación.
Responde solo con hechos verificables.
Si no sabes algo, dilo claramente."""

Ese texto se sustituye en la plantilla donde esté la variable {{ .System }}. Si no defines TEMPLATE, Ollama usa la plantilla por defecto del modelo base, que ya suele incluir el hueco para el system message.

TEMPLATE: la plantilla del prompt

TEMPLATE define la plantilla completa del prompt que se envía al modelo. Usa la sintaxis de plantillas de Go (text/template) y variables predefinidas:

| Variable | Uso | |----------------|------------------------------------------| | {{ .System }} | Mensaje de sistema (SYSTEM) | | {{ .Prompt }} | Mensaje del usuario | | {{ .Response }}| Respuesta del modelo (para few-shot, etc.) |

Se pueden usar condicionales como {{ if .System }} ... {{ end }} para incluir o no el bloque de sistema. La plantilla es específica de cada familia de modelos (por ejemplo Llama usa ciertos tokens especiales, otros modelos usan otros). Si no pones TEMPLATE, se usa la del modelo base.

Ejemplo simplificado (el formato real depende del modelo):

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

Solo tiene sentido definir TEMPLATE cuando necesitas un formato distinto al del modelo base o cuando importas un modelo (por ejemplo desde GGUF) que no trae plantilla por defecto.

ADAPTER: adaptadores LoRA o QLoRA

La instrucción ADAPTER aplica un adapter (LoRA o QLoRA) al modelo base indicado en FROM. El valor es la ruta al adapter: un directorio con archivos Safetensors o un archivo GGUF del adapter. La ruta puede ser absoluta o relativa al Modelfile.

Adapter en Safetensors (directorio):

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

Si el adapter está en la misma carpeta que el Modelfile:

ADAPTER .

Adapter en GGUF:

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

El modelo base debe ser el mismo (o compatible) con el que se entrenó el adapter. Si no, el comportamiento puede ser errático. Para Safetensors se suelen recomendar adapters no cuantizados (no QLoRA) para evitar incompatibilidades entre métodos de cuantización.

Ollama soporta adapters Safetensors para Gemma, Mistral y Llama, y también adapters en formato GGUF.

Otras instrucciones: LICENSE, MESSAGE, REQUIRES

LICENSE permite indicar la licencia del modelo en texto libre (por ejemplo para compartir el Modelfile). MESSAGE sirve para definir un historial de ejemplo (user/assistant) y orientar las respuestas con few-shot. REQUIRES fija la versión mínima de Ollama (por ejemplo REQUIRES 0.14.0).

Para ver el Modelfile que Ollama ha generado internamente para un modelo ya creado:

ollama show --modelfile nombre-del-modelo

Así puedes inspeccionar la plantilla y los parámetros por defecto y usarlos como referencia para tus propios Modelfiles.