Fine-tuning: treinando um modelo de IA para o seu contexto

Uma das perguntas que mais recebo de outros desenvolvedores quando falo sobre uso de IA no trabalho é: "mas você não fica preocupado em mandar código de cliente para uma API externa?". Essa preocupação é legítima. E foi ela que me motivou a explorar fine-tuning de modelos locais.

A ideia é simples: pegar um modelo pequeno e eficiente, treinar com dados específicos do contexto que você trabalha, e rodar tudo localmente. Sem dependência de API externa, sem custo por token, sem dados saindo da sua máquina.

Por que fine-tuning?

Modelos de linguagem grandes como GPT-4 ou Claude são treinados com dados gerais da internet. Eles conhecem Laravel, PHP, Node.js, mas não conhecem a versão específica que você usa, as convenções do seu time ou os padrões do seu projeto.

O fine-tuning resolve isso. Você pega um modelo base e o ajusta com dados que representam exatamente o conhecimento que você quer que ele tenha.

Quando fine-tuning faz sentido?

Fine-tuning não deve ser a primeira resposta para todo problema com IA. Em muitos casos, uma boa busca semântica com RAG (Retrieval-Augmented Generation) resolve melhor: você mantém os documentos atualizados, busca os trechos relevantes e entrega esse contexto para o modelo responder.

O fine-tuning começa a fazer mais sentido quando você precisa mudar o comportamento do modelo, não apenas fornecer informação. Alguns exemplos:

• Responder sempre em um formato específico
• Usar uma linguagem técnica ou tom de comunicação recorrente
• Aprender padrões internos de código e arquitetura
• Classificar entradas com critérios muito particulares
• Reduzir dependência de prompts enormes e repetitivos

Minha regra prática é simples: se o problema é conhecimento que muda com frequência, começo por RAG. Se o problema é comportamento, estilo, padrão de resposta ou especialização em um domínio estável, considero fine-tuning.

O experimento: Laravel 13 + Qwen 3

Escolhi o Qwen 3 de 0.6B parâmetros pelo tamanho — pequeno o suficiente para rodar em uma GPU modesta, mas capaz o suficiente para entender código.

Construindo o dataset

A primeira etapa foi construir um dataset de qualidade. Usei a documentação oficial do Laravel 13 como fonte primária, convertendo as páginas em pares de pergunta e resposta no formato JSONL:

{"messages": [
  {"role": "user", "content": "Como criar uma migration no Laravel 13?"},
  {"role": "assistant", "content": "Use o comando Artisan: php artisan make:migration create_users_table. A migration será criada em database/migrations/ com os métodos up() e down()..."}
]}

O processo de coletar, limpar e estruturar os dados foi a parte mais trabalhosa. Documentação técnica tem muito ruído: exemplos quebrados, referências cruzadas, conteúdo duplicado.

Qualidade dos exemplos

Um erro comum é achar que basta gerar milhares de pares de pergunta e resposta. Quantidade ajuda, mas exemplos ruins ensinam o modelo a errar de forma consistente.

Passei a tratar cada item do dataset como se fosse um teste automatizado: a pergunta precisa ser clara, a resposta precisa ser objetiva e a informação precisa estar alinhada com a versão do framework usada como referência. Quando havia dúvida, preferi descartar o exemplo em vez de treinar o modelo com conteúdo frágil.

Também evitei respostas longas demais. Para um assistente técnico, a melhor resposta nem sempre é a mais completa. Muitas vezes é a resposta que resolve o problema do desenvolvedor com o menor atrito possível.

Treinando com LoRA

Para fine-tuning eficiente em hardware limitado, usei LoRA (Low-Rank Adaptation). Em vez de ajustar todos os pesos do modelo, o LoRA adiciona camadas adaptadoras pequenas e treina apenas elas. O resultado é um modelo ajustado com uma fração do custo computacional.

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import get_peft_model, LoraConfig, TaskType

config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.1,
)

model = get_peft_model(base_model, config)

O treino levou algumas horas em uma GPU modesta. A perda de treino caiu de forma estável, o que é um bom sinal.

Resultados

O modelo treinado passou a responder perguntas sobre o Laravel 13 com mais precisão do que o modelo base, especialmente em:

• Novos helpers e métodos adicionados na versão 13
• Mudanças de comportamento em relação a versões anteriores
• Padrões específicos de organização de código

Não é perfeito — ainda alucina em perguntas muito específicas — mas para uso assistido durante o desenvolvimento, funciona muito bem.

Como avaliei o resultado

Além de acompanhar a loss do treino, montei um conjunto pequeno de perguntas manuais para comparar o modelo base com o modelo ajustado. Esse conjunto tinha perguntas simples, perguntas sobre mudanças de versão, perguntas ambíguas e perguntas fora do escopo.

O objetivo não era provar que o modelo ficou "inteligente". Era responder perguntas mais práticas:

• Ele usa a terminologia correta do Laravel?
• Ele inventa menos métodos?
• Ele sabe dizer quando não tem informação suficiente?
• Ele mantém respostas curtas quando a pergunta é simples?
• Ele melhora nos casos que motivaram o fine-tuning?

Essa etapa é importante porque uma curva de treino bonita pode esconder um modelo pior para uso real. O que importa é comportamento em casos concretos.

Cuidados antes de levar para produção

Mesmo com um modelo local, ainda existem responsabilidades de engenharia:

• Controlar versão do dataset usado no treino
• Registrar qual modelo base e quais hiperparâmetros foram usados
• Criar testes de regressão com perguntas críticas
• Medir latência e consumo de memória
• Definir fallback quando a resposta for ruim ou insuficiente
• Separar claramente resposta assistiva de decisão automática

Fine-tuning não elimina revisão humana. Ele reduz atrito em tarefas específicas, mas o desenvolvedor continua responsável por validar código, segurança e decisões de arquitetura.

O que aprendi

Dataset é tudo. A qualidade do modelo treinado é diretamente proporcional à qualidade dos dados. Vale investir mais tempo aqui do que em hiperparâmetros.

LoRA é o caminho para hardware limitado. Treinar o modelo completo em uma GPU consumer é inviável. LoRA muda esse cenário completamente.

Avaliação é subestimada. É fácil olhar para a loss curve e achar que está tudo certo. Teste manual com casos reais é insubstituível.

Modelos pequenos têm limitações reais. Um modelo de 0.6B parâmetros não vai substituir um GPT-4 para raciocínio complexo. Mas para um domínio específico e bem definido, ele é surpreendentemente eficaz.

Próximos passos

Quero expandir o dataset com código real de projetos Laravel, não apenas documentação. E explorar outros domínios: um modelo treinado com os padrões do próprio projeto do time, por exemplo, poderia ser muito útil para onboarding e code review automatizado.

Também quero comparar esse caminho com uma abordagem híbrida: RAG para documentação que muda com frequência e fine-tuning para padronizar comportamento, formato e estilo das respostas. Acredito que essa combinação seja mais realista para times de software do que tentar colocar todo conhecimento dentro do modelo.

Conclusão

Fine-tuning é uma ferramenta poderosa, mas precisa ser usada com critério. Ele não substitui documentação bem escrita, não corrige dataset ruim e não transforma um modelo pequeno em um especialista universal. O valor aparece quando o problema é bem delimitado e quando existe um conjunto de exemplos confiável para ensinar o comportamento esperado.

Para mim, o maior aprendizado desse experimento foi perceber que treinar o modelo é apenas uma parte do trabalho. O mais importante é preparar dados bons, avaliar com casos reais e entender exatamente o que você espera melhorar.

Se você quiser explorar essa área, comece pequeno. Escolha um domínio restrito, monte um dataset enxuto, teste contra perguntas reais e compare com alternativas mais simples antes de aumentar a complexidade. O ecossistema Python está maduro o suficiente para experimentar com Hugging Face Transformers, PEFT e datasets próprios, mas a qualidade do resultado continua dependendo de boas decisões de engenharia.