Ollama Modelfile: criar e personalizar o seu modelo

#Por que um Modelfile?

Quando você digita ollama run qwen3.5:9b, obtém um modelo genérico. Às vezes, ele responde em inglês a uma pergunta em francês, comenta suas respostas de código com introduções intermináveis e negocia quando você pede uma tradução literal. Em vez de repetir o mesmo prompt de sistema em cada sessão, você o fixa uma única vez em um Modelfile e obtém uma variante reutilizável.

Concretamente, um Modelfile permite três coisas: (1) anexar um prompt de sistema persistente ao modelo, (2) ajustar os parâmetros de geração (temperatura, contexto, tokens de parada), (3) opcionalmente substituir o template de chat. A variante criada pode ser usada como qualquer modelo Ollama: ollama run mon-assistant.

#Pré-requisitos

Ollama instalado

Versão 0.3+ recomendada. Verifique com o ollama --version. O daemon deve estar rodando em http://localhost:11434.

Um modelo base já baixado

Por exemplo, ollama pull qwen3.5:9b ou ollama pull qwen3-coder:30b. O Modelfile herda desse modelo.

Um editor de texto

VSCode, Notepad++, vim — qualquer um. O arquivo não precisa ter uma extensão específica e, por convenção, costuma ser chamado de Modelfile.

Aproximadamente 5 minutos

O tempo necessário para criar o arquivo e executar ollama create. Nenhum download adicional: reutilizamos um modelo já presente.

#1. Sintaxe do Modelfile

Um Modelfile é um arquivo de texto com instruções em maiúsculas, uma por bloco. A ordem não importa, mas a convenção coloca FROM no início.

FROM qwen3.5:9b

SYSTEM """
Tu es un assistant utile et concis.
"""

PARAMETER temperature 0.7
PARAMETER num_ctx 4096

Instruções principais:

FROM

Modelo base. Obrigatório. Aceita um nome Ollama (qwen3.5:9b, qwen3.8:27b) ou um caminho local para um GGUF.

SYSTEM

O prompt de sistema que será injetado em cada conversa. Use aspas triplas para textos com várias linhas.

PARAMETER

Configurações de amostragem e contexto. Uma instrução por parâmetro. Os mais úteis: temperature, top_p, top_k, num_ctx, repeat_penalty, num_predict, stop.

TEMPLATE

Formato completo do prompt (raro). Alterar apenas se você souber o que está fazendo — cada família de modelos tem seu template.

MESSAGE

Exemplos few-shot. Prefixados por MESSAGE user ou MESSAGE assistant. Úteis para estabelecer um estilo.

ADAPTER

Caminho para um GGUF LoRA a ser aplicado sobre o FROM. Para usuários avançados.

LICENSE

Texto livre, para rastreabilidade. Não afeta a execução.

#2. Criar seu primeiro modelo

O workflow é sempre o mesmo: escrevemos um Modelfile, executamos ollama create e testamos com ollama run.

1. 01
   Criar o arquivo

   Em um diretório de trabalho, crie um arquivo chamado Modelfile (sem extensão). Coloque nele a definição da sua variante.
2. 02
   Iniciar a criação

   Do mesmo diretório: ollama create mon-modele -f ./Modelfile. O Ollama valida a sintaxe, herda os pesos do modelo FROM e registra uma nova entrada. É instantâneo, não baixa nada novamente.
3. 03
   Verificar

   ollama list mostra seu novo modelo ao lado dos outros. O tamanho exibido é idêntico ao do modelo base — isso é uma referência, não uma cópia.
4. 04
   Testar

   ollama run mon-modele. O prompt de sistema e os parâmetros já foram aplicados. Você também pode apontar uma interface (Open WebUI, LM Studio) para essa variante pela API.

# Dans le dossier qui contient le Modelfile
ollama create assistant-fr -f ./Modelfile
ollama list
ollama run assistant-fr

#3. Exemplo: assistente conciso em francês

Objetivo: um assistente que responda sempre em francês, sem preâmbulos do tipo "Bien sûr, voici…", sem expressões de desculpa e com respostas de extensão ajustada.

FROM qwen3.5:9b

SYSTEM """
Tu es un assistant francophone précis et concis.

Règles strictes :
- Réponds toujours en français, jamais en anglais, même si l'utilisateur écrit en anglais.
- Pas de préambule ("Bien sûr", "Voici", "Absolument"). Va directement au fait.
- Pas d'excuses ni de disclaimers sauf si l'information est réellement incertaine.
- Réponses courtes par défaut (3-5 phrases). Détaille uniquement si on te le demande explicitement.
- Si tu ne sais pas, dis-le en une phrase. N'invente pas.
"""

PARAMETER temperature 0.6
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER repeat_penalty 1.15

Criação e teste:

ollama create assistant-fr -f ./Modelfile-assistant-fr
ollama run assistant-fr "Quels sont les avantages d'un LLM local ?"

O repeat_penalty em 1.15 (em vez do valor padrão de 1.1) interrompe as repetições dos modelos. O num_ctx em 8192 permite colar documentos um pouco longos sem estourar o contexto padrão de 2048.

#4. Exemplo: programador Python silencioso

Objetivo: um assistente de programação que retorna código Python pronto para colar, com o mínimo de texto ao redor. Ideal para fluxos de trabalho em que se deseja enviar a saída por um pipe para um editor ou um script.

FROM qwen3-coder:30b

SYSTEM """
Tu es un assistant de code Python expert. Tu suis ces règles :

1. Réponds uniquement avec du code Python valide, dans un bloc fenced ```python.
2. Pas d'explication avant ou après le code, sauf si l'utilisateur demande explicitement une explication.
3. Le code doit être complet, exécutable, avec les imports nécessaires en haut.
4. Privilégie la stdlib quand c'est possible. Si une dépendance externe est nécessaire, mets un commentaire en tête : # pip install <package>.
5. Type hints quand c'est raisonnable (Python 3.10+).
6. Si la demande est ambiguë, choisis l'interprétation la plus probable et code-la, sans poser de questions.
"""

PARAMETER temperature 0.2
PARAMETER top_p 0.95
PARAMETER num_ctx 16384
PARAMETER stop "```\n\n"

Algumas escolhas técnicas que se destacam:

FROM qwen3-coder:30b

Modelo especializado em código de 2026 (MoE 30B-A3B, apenas 3B de parâmetros ativos, 256k de contexto, ~19 GB em Q4). Em uma placa de 24 GB (RTX 4090) ou em um Mac com 32 GB, ele roda a 50-80 tokens/s graças aos 3B ativos. Se você tiver apenas 16 GB de VRAM, substitua por gpt-oss:20b (14 GB) ou devstral:24b.

temperature 0.2

Baixa para código. Com 0.7 (padrão), o modelo improvisa nomes de variáveis e às vezes inventa APIs. Para código, queremos determinismo.

num_ctx 16384

Janela ampliada para analisar arquivos inteiros. Cuidado: multiplica a VRAM consumida pelo contexto.

stop

O modelo para após o primeiro bloco de código. Isso evita explicações após o código que poluem a saída.

ollama create coder-py -f ./Modelfile-coder-py
ollama run coder-py "Lire un CSV avec pandas et retourner la moyenne de la colonne 'prix'"

#5. Exemplo: tradutor estrito EN→FR

Objetivo: um tradutor que retorne EXCLUSIVAMENTE a tradução, sem aspas, sem "Tradução:", sem variação estilística. Caso de uso típico: integração em um pipeline n8n ou em um script bash em que a saída será consumida em formato bruto.

FROM qwen3.5:9b

SYSTEM """
Tu es un traducteur professionnel anglais → français.

Règles ABSOLUES :
- Tu reçois un texte en anglais. Tu retournes UNIQUEMENT la traduction française.
- Pas de préfixe ("Traduction :", "Voici :"), pas de guillemets autour de ta réponse, pas de commentaire.
- Conserve la mise en forme exacte du texte source (sauts de ligne, listes, ponctuation).
- Conserve les noms propres, marques, URLs et identifiants techniques tels quels.
- Si le texte est déjà en français, renvoie-le inchangé.
- Si le texte est dans une autre langue que l'anglais, renvoie : ERREUR_LANGUE_NON_SUPPORTÉE
"""

PARAMETER temperature 0.3
PARAMETER num_ctx 4096
PARAMETER num_predict 2048

A adição de MESSAGE para estabelecer o formato com few-shot torna o comportamento ainda mais previsível:

FROM qwen3.5:9b

SYSTEM """
Tu traduis de l'anglais vers le français. Tu renvoies UNIQUEMENT la traduction, sans préfixe ni guillemets.
"""

MESSAGE user "The meeting starts at 3 PM."
MESSAGE assistant "La réunion commence à 15 heures."

MESSAGE user "Please check the attached document."
MESSAGE assistant "Merci de consulter le document ci-joint."

PARAMETER temperature 0.3

Uso em pipeline:

echo "The deployment is scheduled for tomorrow morning." | ollama run translator-en-fr

#6. Gerenciar seus modelos personalizados

Ao longo do tempo, você vai acumular várias variantes. Algumas comandos úteis para manter o controle:

# Lister tous les modèles (originaux + variantes)
ollama list

# Voir le Modelfile d'une variante (utile pour récupérer un Modelfile perdu)
ollama show --modelfile assistant-fr

# Voir les paramètres effectifs
ollama show --parameters assistant-fr

# Voir le system prompt seul
ollama show --system assistant-fr

# Supprimer une variante (libère uniquement l'entrée, pas les poids du modèle de base)
ollama rm assistant-fr

#7. Qual modelo base escolher?

Todo Modelfile começa com FROM: é a escolha do modelo base que determina 90% do resultado final. Um prompt de sistema perfeito nunca compensará uma base inadequada para seu uso ou grande demais para sua VRAM.

Assistente geral

Um modelo recente de 8 a 14B (família Qwen ou Gemma) em Q4: rápido nas respostas, bom em francês e com margem para o contexto.

Código

Um modelo especializado em código — os modelos MoE do tipo Qwen3-Coder 30B-A3B são muito rápidos a partir de 20 GB de memória; abaixo disso, um modelo de código de 7 a 9B continua relevante.

Francês formal / redação

Os modelos Mistral (Nemo, Magistral) mantêm a vantagem na língua francesa quando comparados a modelos do mesmo tamanho.

Configuração modesta (8 GB de VRAM)

Fique com modelos de 4 a 9B em Q4: um modelo que precisa ser parcialmente carregado na RAM compromete muito a capacidade de resposta, independentemente do Modelfile.

Para comparar as bases por VRAM, licença e uso, o catálogo QuelLLM filtra os modelos compatíveis com sua máquina — cada ficha fornece o comando ollama run exacte para incluir no seu FROM.

#Solução de problemas

O modelo ignora o system prompt

Verifique se você está realmente executando sua variante (ollama run mon-modele) e não o modelo base. Confirme com ollama show --system mon-modele.

Respostas truncadas

Aumente num_predict (padrão 128 em algumas configurações) para 2048 ou mais. Ou adicione PARAMETER num_predict -1 para desativar a limitação.

O modelo não segue uma regra estrita

Reformule a regra em caixa alta, adicione "ABSOLUTAMENTE" ou "JAMAIS" e inclua um exemplo via MESSAGE. Modelos pequenos (menos de ~10B) têm dificuldade com negações isoladas.

Erro "Error: invalid model reference"

O modelo FROM não está instalado localmente. Execute ollama pull <modele> antes do ollama create.

VRAM saturada após criação

O num_ctx elevado multiplica o consumo. Se você passar de 2048 para 16384, considere +1 a +3 GB de VRAM de acordo com o tamanho do modelo. Reduza para 8192 se ficar apertado.

#Para se aprofundar

O Modelfile é a base para especializar Ollama sem tocar nos pesos. Três direções naturais a explorar em seguida:

Dominar os prompts de sistema com mais profundidade

O guia sobre system prompts detalha como estruturar papéis, restrições e exemplos para comportamentos realmente confiáveis — útil a partir do momento em que você ultrapassar 5 linhas de SYSTEM.

Ajustar temperatura, top-p e top-k

Antes de mexer no modelo, saber exatamente o que cada parâmetro de amostragem altera evita muitas idas e vindas. O guia dedicado abrange todos os ajustes úteis.

Disponibilizar suas variantes via Open WebUI

Após criar seus modelos personalizados, o Open WebUI os lista automaticamente. Você pode alternar entre assistant-fr, coder-py e translator-en-fr com apenas um clique a partir da interface.