Ollama Modelfile: parâmetros e modelos personalizados

Atualização de 08/06/2026: revisei a lista de instruções com base na documentação oficial do Ollama Modelfile (sete ao todo: FROM, PARAMETER, TEMPLATE, SYSTEM, ADAPTER, LICENSE e MESSAGE; não existe REQUIRES), conferi os valores padrão dos parâmetros, corrigi o link introdutório e acrescentei outras leituras da série.

Depois de explicar no artigo anterior como colocar o modelo para funcionar, uma questão continuou me incomodando: as respostas variavam demais.

Quando eu fazia uma pergunta simples de programação ao llama3.2, às vezes recebia três linhas objetivas; em outras, uma dissertação inteira. Com a temperatura em 0.8, ele começava a “inventar”; em 0.1, ficava rígido, como se recitasse um livro. Pior ainda era precisar redefinir o system prompt em toda conversa, copiando e colando a mesma coisa sem parar.

Foi então que descobri o Modelfile do Ollama. Em termos simples, ele funciona como uma “ficha de personalidade” do modelo: você configura uma vez e os ajustes continuam valendo. Reuni aqui os problemas que encontrei e o que aprendi ao testá-lo, incluindo recomendações para ajustar 10 parâmetros principais e quatro modelos práticos que você pode usar diretamente.

Se você ainda não instalou o Ollama, vale começar pelo guia introdutório do Ollama. Este conteúdo é mais avançado e pressupõe que você já sabe usar ollama run.

1. O que é um Modelfile e por que usá-lo

O Modelfile é como um “projeto de configuração” do modelo, semelhante ao conceito de um Dockerfile. Você informa ao Ollama qual modelo usar como base, quais parâmetros aplicar e qual prompt de sistema adotar, depois dá um nome ao resultado. Sempre que esse nome for usado, todas as configurações serão aplicadas automaticamente.

Na prática, ele resolve três problemas:

Problema 1: repetir a mesma configuração todas as vezes

Você provavelmente já passou por isto: abre o terminal, executa ollama run llama3.2 e digita um system prompt. No dia seguinte, repete. No outro, mais uma vez. O Modelfile registra essas configurações fixas, para que uma única configuração continue valendo.

Problema 2: estilo de saída inconsistente

O mesmo modelo pode produzir respostas muito diferentes conforme os parâmetros. Um assistente de programação precisa de estabilidade; uma ferramenta de escrita criativa precisa de variedade. Não faz sentido depender da memória para lembrar que uma tarefa usa temperature 0.3 e outra usa 0.8: o Modelfile salva cada predefinição.

Problema 3: gerenciar variantes do modelo

Você pode querer uma versão do llama3.2 para revisão de código, outra como assistente de escrita e uma terceira para saída JSON. Seria preciso copiar o modelo três vezes? Não. Basta criar três variantes com nomes diferentes por meio de Modelfiles. O arquivo-base continua sendo o mesmo; apenas a configuração muda.

O fluxo básico tem apenas três etapas:

# 1. Crie um arquivo Modelfile
echo 'FROM llama3.2
SYSTEM "Você é especialista em revisão de código"' > Modelfile

# 2. Gere o novo modelo com ollama create
ollama create my-coder -f Modelfile

# 3. Execute diretamente
ollama run my-coder

É só isso. Agora vamos detalhar o que pode ser escrito em um Modelfile.

2. Estrutura do Modelfile e suas sete instruções

A sintaxe do Modelfile é simples: comentários começam com #, e instruções começam com palavras em letras maiúsculas. Por exemplo:

# Isto é um comentário
FROM llama3.2
PARAMETER temperature 0.8
SYSTEM "Você é um assistente cordial"

O arquivo inteiro é formado por apenas dois tipos de elemento: comentários e instruções. Existem sete instruções; veja primeiro uma visão geral:

Instrução	Função	Obrigatória?	Quando usar
FROM	Define o modelo-base	Sim	Deve aparecer em todos os arquivos
PARAMETER	Define parâmetros de inferência	Não	Para ajustar temperatura, contexto e outros parâmetros
TEMPLATE	Define o template do prompt	Não	Para personalizar o formato da conversa
SYSTEM	Define a mensagem de sistema	Não	Para estabelecer papel e comportamento
ADAPTER	Carrega um adaptador LoRA	Não	Ao trabalhar com fine-tuning do modelo
LICENSE	Declara a licença	Não	Ao publicar um modelo
MESSAGE	Predefine o histórico da conversa	Não	Para fornecer exemplos few-shot

Na prática, em 90% dos usos cotidianos, FROM, PARAMETER e SYSTEM são suficientes. As demais podem ficar para quando surgir uma necessidade específica.

Três formas de usar a instrução FROM

FROM é a única instrução obrigatória e admite três formatos:

Forma 1: usar o nome do modelo (a mais comum)

FROM llama3.2
FROM llama3.2:3b
FROM mistral:latest

Basta usar um nome de modelo compatível com o Ollama. O texto depois dos dois-pontos é a tag da versão; sem ela, o padrão é latest.

Forma 2: usar um arquivo GGUF local

FROM ./my-model.gguf

Se você baixou de outra fonte um arquivo de modelo no formato GGUF, pode apontar diretamente para ele.

Forma 3: usar um diretório Safetensors

FROM ./my-safetensors-dir

Esse caso é menos comum e, em geral, envolve o formato original de um modelo baixado do Hugging Face.

Com a estrutura básica pronta, vamos à parte principal: os parâmetros de PARAMETER.

3. Parâmetros de PARAMETER em detalhes

Esta é a parte mais prática do artigo. Organizei os problemas que encontrei ao ajustar os parâmetros em uma tabela que você pode usar como referência imediata.

Primeiro, veja a lista completa:

Parâmetro	Valor padrão	Tipo	Para que serve	Como ajustar
temperature	0.8	float	Controla a aleatoriedade; quanto maior, mais livre é a resposta	0.3 para código; 1.0 para criatividade
num_ctx	2048	int	Define o tamanho da janela de contexto	4096–8192 para documentos longos
top_k	40	int	Limita a escolha às K palavras de maior probabilidade	Em geral, não altere, a menos que a saída esteja muito dispersa
top_p	0.9	float	Aplica nucleus sampling para controlar a diversidade	Use em conjunto com temperature
min_p	0.0	float	Filtra palavras com probabilidade muito baixa	Use 0.05 para melhorar a qualidade da saída
seed	0	int	Fixa a semente aleatória para reproduzir uma saída	Use 42 ou outro valor fixo durante testes
stop	Nenhum	string	Interrompe a geração ao encontrar a sequência	É possível combinar várias sequências stop
num_predict	-1	int	Define o tamanho máximo da saída; -1 significa sem limite	Use 100–500 para limitar a resposta
repeat_penalty	1.1	float	Penaliza conteúdo repetido	Aumente para 1.5 em textos longos
repeat_last_n	64	int	Verifica se houve repetição nas últimas N palavras	Use em conjunto com repeat_penalty

A seguir, vou detalhar alguns dos parâmetros mais importantes.

temperature: criatividade ou estabilidade

Este é o parâmetro mais fácil de entender. Com temperature alta, como 1.0, o modelo fica mais livre e escolhe palavras menos prováveis, mas potencialmente mais criativas. Com temperature baixa, como 0.1, ele se torna conservador, seleciona apenas as palavras mais prováveis e produz respostas mais estáveis.

Testei como o llama3.2 respondia à mesma pergunta com diferentes valores de temperature:

Pergunta: como ler um arquivo em Python?

• temperature 0.1: a resposta parece um livro didático e traz apenas a solução mais convencional
• temperature 0.5: acrescenta dicas práticas, como cuidados com a codificação de caracteres
• temperature 0.8: pode explicar métodos diferentes para cenários distintos e incluir exemplos
• temperature 1.0: as respostas variam bastante e às vezes fogem do assunto

Minha experiência:

• Programação e dúvidas técnicas: cerca de 0.3, para manter a estabilidade
• Escrita criativa e brainstorming: 0.8–1.0, para obter variedade
• Saída JSON e formatos fixos: 0.1–0.2, para ganhar precisão

num_ctx: janela de contexto

Este parâmetro determina quanto conteúdo o modelo consegue “lembrar”. O padrão é 2048 tokens, aproximadamente 1.500 a 2.000 caracteres chineses.

Quer que o modelo leia um artigo longo e o resuma? Talvez 2048 não seja suficiente. Ele esqueceu o início de uma conversa longa? Provavelmente num_ctx está baixo demais.

Aviso importante: aumentar num_ctx consome mais memória. Nos meus testes com o llama3.2, elevar num_ctx de 2048 para 8192 mais do que dobrou o consumo de memória. Se a máquina tiver apenas 8 GB, 4096 já é um limite razoável.

Minha experiência:

• Conversas curtas e perguntas simples: o padrão de 2048 é suficiente
• Revisão de código e discussões técnicas: 4096 oferece uma margem confortável
• Documentos longos e escrita de ficção: 8192, desde que haja memória disponível

stop: sequência de parada

Este parâmetro é bastante útil: ele informa ao modelo quando parar.

Por exemplo, se você solicitar uma saída JSON e quiser impedir texto desnecessário:

PARAMETER stop "\n\n"
PARAMETER stop "```"

O modelo interrompe a saída ao encontrar duas quebras de linha ou o marcador de bloco de código, deixando o resultado mais limpo.

É possível combinar várias instruções stop, algo que muita gente não sabe.

repeat_penalty: reduzir repetições

Modelos costumam repetir a mesma ideia. O repeat_penalty serve justamente para penalizar esse comportamento.

O valor padrão é 1.1, mas para mim já é insuficiente. Ao gerar textos longos, costumo usar de 1.3 a 1.5, o que reduz expressões redundantes como “conforme mencionado anteriormente” e “em resumo”.

Comparação de parâmetros para cenários diferentes

Resumi as melhores configurações para quatro cenários comuns. Você pode copiá-las diretamente:

Cenário	temperature	num_ctx	Outros parâmetros recomendados
Assistente de programação	0.3	4096	stop ”```”, seed 42 (para reproduzir resultados)
Escrita criativa	1.0	2048	top_p 0.95, repeat_penalty 1.5
Dúvidas técnicas	0.5	4096	min_p 0.05 (para filtrar palavras de baixa qualidade)
Saída JSON	0.1	2048	stop “\n\n”, stop ”```”

Neste ponto, você já deve ter uma ideia do que cada parâmetro faz. Vamos agora à prática, com quatro modelos de Modelfile prontos para usar.

4. Exemplos práticos: quatro Modelfiles completos

Depois da teoria, vamos direto ao código. Testei todos estes quatro modelos; você pode copiá-los, colá-los e executá-los.

Exemplo 1: interpretação de personagem — assistente Zhu Bajie

Este é um modelo divertido que criei para imitar o jeito de falar de Zhu Bajie, personagem de Jornada ao Oeste:

# Modelfile do assistente Zhu Bajie
FROM llama3.2

SYSTEM """Você é Zhu Bajie, personagem de Jornada ao Oeste, e fala com humor e simplicidade.
Ao responder:
- Às vezes, reclame que seu mestre fala demais
- Fique animado quando a conversa envolver comida
- Refira-se a si mesmo como "este velho porco"
- Diante de uma dificuldade, diga "melhor cada um seguir seu caminho""""

PARAMETER temperature 0.8
PARAMETER num_ctx 2048

Por que usar essa configuração:

temperature em 0.8 dá mais “personalidade” às respostas de Zhu Bajie e evita um tom rígido. O SYSTEM traz regras concretas de comportamento — animar-se ao falar de comida e usar “este velho porco” para se referir a si mesmo — que tornam o personagem mais vivo.

Como usar:

ollama create pig-bajie -f Modelfile
ollama run pig-bajie

Experimente perguntar: “Como aprender programação?” e veja como ele responde.

Exemplo 2: assistente profissional — revisão de código Python

Esta é a configuração que uso no trabalho para revisar código:

# Modelfile do assistente de revisão de código Python
FROM llama3.2:3b

SYSTEM """Você é um desenvolvedor Python experiente. Ao revisar código, observe:
1. Segurança de tipos — existem possíveis erros de tipo?
2. Tratamento de exceções — os casos-limite estão cobertos?
3. Gargalos de desempenho — há loops ou cálculos repetidos desnecessários?
4. Riscos de segurança — algum dado sensível está exposto?

Formato da resposta:
Problema → Impacto → Recomendação → Exemplo de código"""

PARAMETER temperature 0.3
PARAMETER num_ctx 8192
PARAMETER seed 42

Por que usar essa configuração:

temperature em 0.3 mantém a saída estável — revisão de código não precisa de “liberdade criativa”. num_ctx fica em 8192 porque os arquivos podem ser longos. seed 42 permite reproduzir o resultado: a mesma pergunta gera a mesma recomendação, o que facilita comparações durante os testes.

Resultado prático: ao enviar algumas centenas de linhas de Python, recebo um relatório claro no formato “problema → impacto → recomendação → exemplo”.

Exemplo 3: saída estruturada — formato JSON

Se a saída do modelo será consumida por outro programa, JSON costuma ser o formato mais conveniente:

# Modelfile do assistente de saída JSON
FROM llama3.2

SYSTEM """Sua saída deve ser um JSON válido.
Formato do resultado da análise:
{"result": "conteúdo da análise", "confidence": 0-100, "tags": ["tag1", "tag2"]}

Não escreva nenhum outro conteúdo nem use marcadores de bloco de código."""

PARAMETER temperature 0.1
PARAMETER num_ctx 2048
PARAMETER stop "\n\n"
PARAMETER stop "```"

MESSAGE user Analise os riscos de segurança deste código
MESSAGE assistant {"result": "Há risco de injeção de SQL porque a entrada do usuário não é filtrada", "confidence": 85, "tags": ["segurança", "SQL"]}

Por que usar essa configuração:

temperature em 0.1 busca a saída mais estável possível, pois o formato JSON não admite desvios. Os parâmetros stop filtram quebras de linha e marcadores de blocos de código, impedindo que o modelo produza conteúdo extra. A parte MESSAGE fornece um exemplo few-shot e mostra ao modelo como a saída deve ser.

Uso esta configuração em um fluxo automatizado: envio logs de erro ao modelo, ele devolve uma análise estruturada e o programa processa o resultado automaticamente.

Exemplo 4: contexto longo — resumo de documentos

Para processar um artigo longo, a janela de contexto precisa ser suficiente:

# Modelfile do assistente de resumo de documentos
FROM llama3.2

SYSTEM """Você é especialista em resumo de documentos. Requisitos da saída:
- Resuma em no máximo cinco tópicos
- Cada tópico deve ter no máximo 50 caracteres
- Primeiro extraia as ideias centrais e depois acrescente detalhes
- Escreva a saída em chinês"""

PARAMETER temperature 0.5
PARAMETER num_ctx 8192
PARAMETER num_predict 300

Por que usar essa configuração:

temperature em 0.5: um resumo precisa ser estável, mas não rígido demais, pois valores muito baixos podem deixá-lo como uma simples lista mecânica. num_ctx em 8192 permite processar documentos longos. num_predict em 300 limita o tamanho da resposta — um resumo não deve ser maior que o texto original.

Usei esta configuração para processar artigos técnicos: ao enviar um texto de 3.000 caracteres chineses, recebi cinco pontos com até 50 caracteres cada, o que tornou a leitura muito mais eficiente.

Em resumo

Esses quatro modelos cobrem necessidades comuns. Você pode alterar o conteúdo de SYSTEM ou ajustar os parâmetros como preferir. Depois de editar o Modelfile, basta executar novamente ollama create; o custo de experimentar é baixo.

5. Uso avançado de TEMPLATE e MESSAGE

Os exemplos anteriores não usaram TEMPLATE porque esse parâmetro é mais avançado e só se torna necessário quando você precisa controlar com precisão o formato da conversa.

Sintaxe Go template de TEMPLATE

O Ollama usa a sintaxe de templates da linguagem Go, com três variáveis principais:

• {{ .System }} — conteúdo de SYSTEM
• {{ .Prompt }} — entrada do usuário
• {{ .Response }} — saída do modelo, usada para definir o formato da resposta

Um exemplo simples:

FROM llama3.2

TEMPLATE """{{ .System }}

Pergunta do usuário: {{ .Prompt }}

Resposta: {{ .Response }}"""

SYSTEM "Você é especialista em tecnologia"

Esse TEMPLATE define a estrutura da conversa: primeiro o conteúdo de SYSTEM, depois a pergunta do usuário e, por fim, a resposta do modelo.

Na maioria dos casos, não é necessário personalizar TEMPLATE, pois o template padrão do Ollama é suficiente. Quando vale a pena alterá-lo?

Cenário 1: integração com outras ferramentas

Ao conectar o Ollama a um sistema de chat com requisitos específicos de formato de entrada, use TEMPLATE para fazer a adaptação.

Cenário 2: formato especial de conversa

Se quiser adicionar um prefixo às falas, como [AI] ou [USER], você pode fazer isso com TEMPLATE.

MESSAGE: histórico de conversa predefinido

MESSAGE serve para “mostrar alguns exemplos ao modelo”. O exemplo de saída JSON já usou essa instrução:

MESSAGE user Analise os riscos de segurança deste código
MESSAGE assistant {"result": "Há risco de injeção de SQL", "confidence": 85}

É como dizer ao modelo: “quando o usuário fizer esse tipo de pergunta, responda desta maneira”. Esse é o conceito de aprendizado few-shot.

Você pode predefinir várias mensagens no histórico:

MESSAGE user Olá
MESSAGE assistant Olá, como posso ajudar?
MESSAGE user Como está o tempo?
MESSAGE assistant Não tenho acesso ao clima em tempo real. Consulte um aplicativo de previsão do tempo.

O modelo “se lembrará” dessas mensagens ao iniciar e manterá o mesmo estilo nas conversas seguintes.

Como consultar o Modelfile de um modelo

Para ver como foi escrito o Modelfile de um modelo, use este comando:

ollama show --modelfile llama3.2

A saída é longa e contém toda a configuração padrão do modelo. Você pode copiá-la, modificá-la e criar sua própria versão.

Esse comando é especialmente útil quando você encontra um modelo com bom desempenho, como uma versão personalizada compartilhada por outra pessoa. Use ollama show para exportar o Modelfile e entender a configuração.

6. Problemas comuns e como evitá-los

Ao ajustar parâmetros, é inevitável encontrar alguns problemas. Reuni aqui os casos mais comuns para ajudar você a evitá-los.

Problema 1: temperature muito baixa deixa a saída rígida

Algumas pessoas partem da ideia de que quanto menor a temperature, melhor, já que a saída fica estável. Eu também pensava assim e configurei temperature em 0.05 no meu assistente de programação.

O resultado? O modelo passou a responder como se recitasse uma resposta padrão, sem nenhuma flexibilidade. Ao perguntar “como ler um arquivo em Python?”, ele mostrou três métodos, mas todos em formato de livro didático e sem nenhuma dica prática.

O que aprendi: temperature não melhora simplesmente por ser menor. Para revisão de código, 0.3 é suficiente; abaixo de 0.2, a resposta tende a ficar rígida. Saídas que exigem precisão, como JSON, realmente pedem valores baixos, mas isso não é necessário em conversas comuns.

Problema 2: num_ctx muito alto esgota a memória

Certa vez, resolvi configurar num_ctx em 16384 para processar um documento muito longo. Depois de alguns minutos, o sistema começou a usar swap sem parar e a máquina inteira travou.

Meu computador tinha apenas 16 GB de memória. O llama3.2:3b consumia cerca de 2 GB por conta própria; ao aumentar num_ctx de 2048 para 16384, o consumo passou de 8 GB. Somando os outros programas em execução, não havia margem.

O que aprendi: não aumente num_ctx sem considerar a memória disponível:

• 8 GB de memória: num_ctx de até 4096
• 16 GB de memória: num_ctx pode chegar a 8192
• 32 GB ou mais: há condições para testar 16384

Problema 3: confundir SYSTEM e MESSAGE

Essas duas instruções têm funções diferentes e são fáceis de confundir:

• SYSTEM: definição permanente do papel, aplicada a todas as conversas
• MESSAGE: histórico de conversa predefinido, equivalente a exemplos few-shot

Por exemplo, para fazer o modelo atuar como especialista em revisão de código, escreva a definição do papel em SYSTEM e alguns exemplos de perguntas e respostas em MESSAGE.

Muita gente usa apenas SYSTEM. O modelo então “sabe que é especialista em revisão de código”, mas não entende como responder a uma questão concreta. Depois de incluir alguns exemplos com MESSAGE, a qualidade da saída melhora bastante.

Problema 4: como atualizar depois de criar o modelo

Como alterar a configuração de um modelo criado por um Modelfile?

É simples: execute ollama create novamente com o mesmo nome para substituí-lo:

# Primeira criação
ollama create my-coder -f Modelfile

# Quer mudar a configuração? Edite o Modelfile e execute outra vez
ollama create my-coder -f Modelfile

O Ollama substitui diretamente o modelo de mesmo nome, sem que você precise excluí-lo antes. Para manter a versão anterior, basta usar outro nome:

ollama create my-coder-v2 -f Modelfile

Problema 5: como reproduzir o Modelfile de outra pessoa

Encontrou um modelo personalizado compartilhado por outra pessoa e quer entender como ele foi configurado?

# Primeiro, baixe o modelo
ollama pull someone-elses-model

# Exporte o Modelfile
ollama show --modelfile someone-elses-model > learned-modelfile

# Examine, estude e modifique
cat learned-modelfile

Uso esse comando com frequência e já aprendi muitas técnicas de ajuste de parâmetros estudando modelos personalizados da comunidade.

Leituras relacionadas

• Guia introdutório do Ollama: primeiros passos com modelos locais
• Como usar a API do Ollama: interface compatível com OpenAI
• Guia de quantização GGUF no Ollama

Conclusão

Depois de todos esses detalhes, a lógica central do Modelfile cabe em uma frase: fixe a configuração para não precisar ajustá-la manualmente toda vez.

Três coisas que você pode fazer agora:

1. Criar um modelo de interpretação de personagem

Teste o modelo do assistente Zhu Bajie ou troque-o por um personagem de que você goste, como Doraemon ou Homem de Ferro. Faça algumas rodadas de conversa e observe como o parâmetro temperature muda o estilo das respostas.

2. Comparar saídas com parâmetros diferentes

Faça a mesma pergunta com temperature em 0.3 e em 0.8 e compare as respostas. Já repeti esse experimento muitas vezes e sempre noto alguma diferença nova.

3. Escolher um cenário que você usa com frequência

Revisão de código, resumo de documentos ou escrita criativa: escolha uma situação do dia a dia e adapte um dos modelos acima. Depois de algumas rodadas de ajustes, você terá um modelo personalizado para seu próprio uso.

No próximo artigo, vou tratar da integração com a API do Ollama: como conectar o modelo local ao seu programa e chamá-lo por uma interface compatível com a OpenAI. Depois de preparar o Modelfile, as chamadas de API ficam mais estáveis, pois os parâmetros não precisam mais ser passados no código; basta usar o modelo personalizado.

Se tiver alguma dúvida, deixe um comentário. Talvez os problemas que encontrei ajudem você a evitar alguns deles.