Ollama: Modelos Personalizados com Modelfile

Um Modelfile é a forma que molda um papel de IA — uma configuração define personalidade, habilidades e limites comportamentais.

📋 Pré-requisitos: Você precisa dominar o seguinte primeiro

• Aula 3: Interação Básica via CLI
• Aula 4: Gerenciamento de Modelos

1. O Que Você Vai Aprender

• Sintaxe completa do Modelfile: FROM / SYSTEM / PARAMETER / TEMPLATE / LICENSE
• Configuração de papel do System Prompt na prática
• Ajuste de PARAMETER e templates
• Uso de variáveis TEMPLATE
• Modelfile dedicado do SupportBot da Alice

2. Uma História Real de Uma Fundadora de SaaS

(1) O Problema: Passar System Prompt Toda Vez

Alice percebeu que cada chamada de API exigia um System Prompt longo — fácil de omitir e difícil de manter. Diferentes cenários de atendimento (reembolso, envio, consultas de produto) precisavam de diferentes configurações de papel, e o gerenciamento manual era caótico.

(2) A Solução: Modelfile Resolve de Uma Vez por Todas

Com um Modelfile, o papel, parâmetros e template são incorporados ao Modelo — crie uma vez, reutilize muitas vezes:

# Create SupportBot model from Modelfile
ollama create supportbot -f Modelfile

# Use it directly, no need for system prompt
ollama run supportbot "I want a refund"

3. Sintaxe Completa do Modelfile

(1) Tabela de Referência de Diretivas

flowchart TD
    A[Modelfile] --> B[FROM: Modelo Base]
    B --> C[SYSTEM: Definição de Papel]
    C --> D[PARAMETER: Config de Inferência]
    D --> E[TEMPLATE: Formato do Prompt]
    E --> F[ollama create]
    F --> G[Modelo Personalizado Pronto]

flowchart TD
    A[Modelfile] --> B[FROM: Modelo Base]
    B --> C[SYSTEM: Definição de Papel]
    C --> D[PARAMETER: Config de Inferência]
    D --> E[TEMPLATE: Formato do Prompt]
    E --> F[ollama create]
    F --> G[Modelo Personalizado Pronto]

(2) Aprofundamento na Diretiva FROM

ℹ️ Nota: A diretiva FROM especifica o Modelo base e é a única diretiva obrigatória em um Modelfile. Suporta três fontes: nome de Modelo oficial (por exemplo, FROM llama3.2, herdando da Ollama Library), caminho de arquivo GGUF local (por exemplo, FROM ./model.gguf, importando um Modelo baixado do HuggingFace), ou um Modelo personalizado já criado (por exemplo, FROM my-bot, implementando herança em cadeia de Modelos). Herdar de um Modelo oficial é a abordagem mais comum.

▶ Exemplo 1: Modelfile Mínimo

FROM llama3.2
SYSTEM You are a helpful assistant that only speaks in haikus.
PARAMETER temperature 0.7

# Build the model
ollama create haiku-bot -f Modelfile

# Test it
ollama run haiku-bot "What is debugging?"
# Finding the bug's lair,
# Line by line with patient care,
# Code runs free at last.

4. Configuração de Papel SYSTEM

(1) Padrões de Design de Papel

(2) Melhores Práticas de Configuração de Papel

▶ Exemplo 2: Modelfiles com Diferentes Papéis

# SQL Expert Modelfile
FROM codellama:7b
SYSTEM You are a PostgreSQL expert. Output ONLY valid SQL. No explanations. No markdown.
PARAMETER temperature 0.1
PARAMETER repeat_penalty 1.2

# Translator Modelfile
FROM qwen2.5:7b
SYSTEM You are a professional translator. Translate the given text to the target language. Preserve formatting. Output only the translation, nothing else.
PARAMETER temperature 0.3

# Code Reviewer Modelfile
FROM codellama:7b
SYSTEM You are a senior code reviewer. Analyze the given code for: 1) Bugs, 2) Performance issues, 3) Style violations. Rate severity as HIGH/MEDIUM/LOW. Suggest fixes.
PARAMETER temperature 0.2
PARAMETER num_ctx 8192

5. Ajuste de PARAMETER

(1) Tabela de Configuração de Parâmetros Comuns

(2) Configuração de Parâmetros por Cenário

▶ Exemplo 3: Modelfile com Parâmetros Ajustados

# SupportBot with optimized parameters
FROM qwen2.5:7b
SYSTEM You are SupportBot, an e-commerce customer service agent. Be polite, concise (2-3 sentences max), and helpful. If the question is outside your knowledge, say: "Let me connect you with a human agent."
PARAMETER temperature 0.4
PARAMETER top_p 0.9
PARAMETER num_ctx 4096
PARAMETER num_predict 256
PARAMETER repeat_penalty 1.1
PARAMETER stop "\n\nCustomer:"

6. Variáveis TEMPLATE

(1) Referência de Variáveis de Template

(2) Exemplos de Template Personalizado

▶ Exemplo 4: Modelfile com Template Personalizado

# Custom chat template for SupportBot
FROM qwen2.5:7b
SYSTEM You are SupportBot for e-commerce customer service.
PARAMETER temperature 0.4

TEMPLATE """{{- if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{- end }}
{{- range .Messages }}
<|im_start|>{{ .Role }}
{{ .Content }}<|im_end|>
{{- end }}
<|im_start|>assistant
"""

▶ Exemplo 5: Criar Modelo de Arquivo GGUF

# Import a custom GGUF model from HuggingFace
FROM ./my-model-q4_K_M.gguf
SYSTEM You are a specialized medical QA assistant.
PARAMETER temperature 0.3
PARAMETER num_ctx 4096
LICENSE "Apache 2.0"

# Create from the Modelfile
ollama create medical-bot -f Modelfile

# Verify
ollama show medical-bot

# Run
ollama run medical-bot "What are common cold symptoms?"

7. Exemplo Abrangente: Modelfile Dedicado do SupportBot da Alice

# ============================================
# Comprehensive: SupportBot Custom Modelfile
# Multi-language e-commerce customer service
# ============================================

FROM qwen2.5:7b

# Role definition with clear boundaries
SYSTEM """You are SupportBot, an AI customer service agent for GlobalShop e-commerce.

Your capabilities:
- Answer questions about orders, returns, shipping, and products
- Respond in the customer's language (auto-detect)
- Be polite, concise, and empathetic

Your rules:
- Keep responses under 3 sentences
- For order-specific queries, ask for the order number
- If you cannot answer, say: "Let me connect you with a human agent."
- Never share internal pricing or competitor information
- Never process refunds directly; guide the customer to the refund portal

Common policies:
- Returns: 30 days, original condition, free return shipping
- Shipping: Free for orders over $50, 3-5 business days
- International: Available to 50+ countries, duties may apply
"""

# Inference parameters
PARAMETER temperature 0.4
PARAMETER top_p 0.9
PARAMETER num_ctx 4096
PARAMETER num_predict 256
PARAMETER repeat_penalty 1.1

# Stop generation at customer input marker
PARAMETER stop "Customer:"
PARAMETER stop "<|im_end|>"

# Chat template (ChatML format)
TEMPLATE """{{- if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{- end }}
{{- range .Messages }}
<|im_start|>{{ .Role }}
{{ .Content }}<|im_end|>
{{- end }}
<|im_start|>assistant
"""

# Pre-seed with example exchanges
MESSAGE user What is your return policy?
MESSAGE assistant Our return policy allows returns within 30 days of delivery in original condition. Free return shipping is provided. Would you like to start a return?

MESSAGE user Do you ship internationally?
MESSAGE assistant Yes, we ship to over 50 countries. Shipping times vary by destination, typically 7-14 business days. Import duties may apply depending on your location.

# Build SupportBot model
ollama create supportbot -f ./Modelfile

# Test different scenarios
ollama run supportbot "I want to return order #12345"
ollama run supportbot "How much does shipping cost?"  # English
ollama run supportbot "What is the return policy?"     # English

❓ Perguntas Frequentes

P: Qual é a relação entre um Modelo criado por Modelfile e o Modelo original? R: Um Modelo criado por Modelfile é uma "view" do Modelo original — compartilha arquivos de peso subjacentes e apenas acrescenta configurações de System Prompt e parâmetros. Não consome espaço adicional em disco.

P: Preciso recriar o Modelo após modificar o Modelfile? R: Sim. Após modificar o Modelfile, você precisa executar ollama create novamente. Conversas existentes não são afetadas; novas conversas usam a nova configuração.

P: O que acontece quando PARAMETER conflita com opções de chamada de API? R: Opções de chamada de API sobrescrevem valores de PARAMETER do Modelfile. Valores do Modelfile são padrões; opções da API são sobrescritas em tempo de execução.

P: O que acontece se não especificar um TEMPLATE? R: O Ollama usa o template padrão do Modelo base. O template padrão é suficiente na maioria dos casos. Templates personalizados são necessários principalmente ao importar Modelos GGUF.

P: Para que servem as mensagens pré-definidas MESSAGE? R: Servem como exemplos few-shot, guiando o Modelo a responder no formato esperado. Complementam o System Prompt mas não contam como rodadas de conversa do usuário.

P: Como depuro o efeito de um Modelfile? R: Teste com --system e --parameter no CLI primeiro, depois finalize no Modelfile uma vez confirmado. ollama show <model> --modelfile exibe o Modelfile completo de um Modelo criado.

📖 Resumo

• Diretivas centrais do Modelfile: FROM (Modelo base), SYSTEM (papel), PARAMETER (parâmetros), TEMPLATE (template)
• Configuração de papel SYSTEM segue: definir papel → especificar formato → definir limites → controlar comprimento
• Ajuste de PARAMETER por cenário: temperatura baixa para SQL, média para atendimento, alta para criatividade
• Variáveis TEMPLATE (.System/.Prompt/.Messages) controlam formato do prompt
• Diálogos pré-definidos MESSAGE servem como exemplos few-shot para guiar a saída
• Modelos criados por Modelfile compartilham pesos com o original, sem consumo extra de espaço

📝 Exercícios

1. Básico (Dificuldade ⭐): Crie um Modelfile baseado em llama3.2 com System Prompt definido como "assistente de tradução", construa e teste.
2. Intermediário (Dificuldade ⭐⭐): Crie um Modelfile completo para o SupportBot da Alice, incluindo SYSTEM + PARAMETER + MESSAGE, e teste diálogos de atendimento em inglês e chinês.
3. Avançado (Dificuldade ⭐⭐⭐): Desenhe um sistema de Modelfile multi-papel — especialista em reembolso, especialista em logística, especialista em produto — com parâmetros ajustados individualmente, e escreva um script Python que roteia automaticamente perguntas para o Modelo apropriado.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós