Como fazer Fine-Tuning do Gemma 4 com Unsloth: Guia Passo a Passo

O Unsloth possui suporte desde o lançamento para todas as quatro variantes do Gemma 4 — E2B, E4B, 26B-A4B e 31B. Ele treina modelos 2x mais rápido e usa até 70% menos VRAM em comparação com o treinamento padrão do Hugging Face, o que o torna a escolha prática para qualquer pessoa que trabalhe com hardware de consumo.

Este guia cobre tudo, desde a escolha da variante certa do modelo até a exportação do seu adaptador finalizado para uso no Ollama, llama.cpp ou LM Studio.

Qual modelo Gemma 4 você deve ajustar (fine-tune)?

A resposta depende do seu hardware e do que você deseja realizar.

Modelo	VRAM para treinamento (LoRA, bf16)	Ideal para
E4B	~8–10 GB	Laptops, RTX 3060/4060, Colab gratuito
E2B	~6–8 GB	Tarefas multimodais + áudio, orçamentos apertados
26B-A4B	~24+ GB (16-bit LoRA)	Equilíbrio velocidade/qualidade, RTX 3090/4090
31B	~20 GB (QLoRA 4-bit)	Qualidade máxima, NVIDIA A100 / GPU dupla

Algumas observações importantes:

O E4B é o ponto de partida certo para a maioria das pessoas. Ele roda no Google Colab gratuito (GPU T4), cabe em qualquer GPU RTX com 12 GB ou mais e suporta ajuste fino de texto e multimodal (imagem + áudio). O Unsloth fornece notebooks gratuitos no Colab para ele.

Evite QLoRA no 26B-A4B MoE. Como o 26B-A4B é um modelo Mixture-of-Experts, o Unsloth recomenda LoRA de 16 bits em vez de QLoRA de 4 bits. Roteamento MoE e quantização de 4 bits interagem mal. Use load_in_16bit=True em vez de load_in_4bit=True para esta variante.

O 31B é um excelente alvo para ajuste fino quando a qualidade é essencial. É um modelo denso (QLoRA funciona bem) e atualmente ocupa o 3º lugar no ranking LMArena de modelos abertos.

Antes de começar: instale e atualize o Unsloth

Se você não tem o Unsloth instalado, comece aqui. Existem duas maneiras de usá-lo: Unsloth Studio (uma interface web no-code) e Unsloth Core (a biblioteca Python para fluxos de trabalho baseados em código).

Opção A — Unsloth Studio (no-code, recomendado para iniciantes)

macOS, Linux ou WSL:

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell:

irm https://unsloth.ai/install.ps1 | iex

Uma vez instalado, inicie o Studio:

unsloth studio -H 0.0.0.0 -p 8888

Em seguida, abra http://localhost:8888 no seu navegador. No primeiro lançamento, você criará uma senha e usará o assistente para pesquisar o Gemma 4, selecionar um tamanho de modelo e escolher um conjunto de dados (dataset). O Unsloth Studio cuida do resto — você monitora o progresso do treinamento pela interface e exporta quando terminar.

Opção B — Unsloth Core (baseado em código)

Se você já possui uma instalação existente do Unsloth, atualize-a primeiro:

pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo

Para uma nova instalação com detecção automática do backend PyTorch:

pip install unsloth --torch-backend=auto

Preparando seu conjunto de dados (dataset)

O Gemma 4 utiliza o formato de conversação padrão com as funções user e model — não os formatos antigos específicos do Gemma 1/2/3. Seus dados de treinamento devem se parecer com isto:

{
  "messages": [
    {
      "role": "user",
      "content": "Classifique o sentimento desta avaliação: 'O envio atrasou, mas o produto é excelente.'"
    },
    {
      "role": "model",
      "content": "Misto — sentimento negativo em relação ao envio, positivo em relação ao produto."
    }
  ]
}

Algumas regras de formatação específicas para o Gemma 4:

Use "role": "model" (e não "assistant") para as respostas do Gemma 4. Isso corresponde ao chat template do tokenizer.
O suporte nativo a prompts de sistema (system prompts) é novo no Gemma 4. Você pode incluir uma mensagem {"role": "system", "content": "..."} no início de cada conversa.
Para ativar o modo de pensamento (thinking mode) durante o treinamento, coloque <|think|> no início do seu prompt de sistema. Se você deseja preservar a capacidade de raciocínio do modelo, misture exemplos de estilo de raciocínio com respostas diretas — o Unsloth recomenda manter pelo menos 75% de exemplos de raciocínio se você se preocupa com essa capacidade.
Para conversas de vários turnos, inclua apenas a resposta visível final no alvo de treinamento. Não alimente blocos de pensamento anteriores de volta em turnos subsequentes.

Diretrizes de tamanho de dataset:

Ajuste fino de estilo ou tom: 200–1.000 exemplos de alta qualidade
Adaptação de domínio (médico, jurídico, técnico): 10.000–50.000 exemplos
Seguimento de instruções: 5.000–20.000 exemplos
Tarefas de classificação ou extração: 500–5.000 exemplos

Sempre reserve de 10 a 20% dos seus dados para avaliação. Um exemplo ruidoso ou mal rotulado pode desfazer o benefício de dezenas de exemplos limpos.

Ajuste fino de texto: passo a passo do código

Este exemplo faz o ajuste fino do Gemma 4 E4B com LoRA para uma tarefa de texto. Substitua a URL do conjunto de dados por sua própria fonte de dados.

from unsloth import FastLanguageModel
import torch
from datasets import load_dataset
from trl import SFTTrainer, SFTConfig

max_seq_length = 2048  # Comece de forma conservadora. Aumente assim que o pipeline funcionar.

# Carregue seu dataset — ele precisa de uma coluna "text", ou use um dataset formatado para chat
dataset = load_dataset("json", data_files={"train": "seu_dataset.jsonl"}, split="train")

# Carregue o modelo
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = max_seq_length,
    load_in_4bit = False,    # Para E4B e 31B denso: QLoRA (4-bit) também funciona
    load_in_16bit = True,    # bf16 LoRA — ponto de partida recomendado
    full_finetuning = False,
)

# Anexe adaptadores LoRA
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,                  # Rank do LoRA — maior = mais capacidade, mais VRAM
    target_modules = [
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",  # Necessário para contexto longo ou VRAM apertada
    random_state = 3407,
    max_seq_length = max_seq_length,
)

# Treinamento
trainer = SFTTrainer(
    model = model,
    train_dataset = dataset,
    tokenizer = tokenizer,
    args = SFTConfig(
        max_seq_length = max_seq_length,
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        warmup_steps = 10,
        max_steps = 100,        # Substitua por num_train_epochs para uma execução real
        logging_steps = 1,
        output_dir = "outputs_gemma4",
        optim = "adamw_8bit",
        seed = 3407,
        dataset_num_proc = 1,
    ),
)

trainer.train()

Sem memória de vídeo (VRAM)? Duas coisas para tentar primeiro: baixe per_device_train_batch_size para 1 e reduza max_seq_length. Mantenha use_gradient_checkpointing="unsloth" — ele foi projetado especificamente para reduzir o uso de VRAM e estender a janela de contexto durante o treinamento.

Fine-tuning do modelo MoE 26B-A4B

O modelo MoE precisa de um carregador ligeiramente diferente. Use FastModel em vez de FastLanguageModel e mantenha o LoRA de 16 bits:

import os
import torch
from unsloth import FastModel

model, tokenizer = FastModel.from_pretrained(
    model_name = "unsloth/Gemma-4-26B-A4B-it",
    max_seq_length = 2048,
    load_in_4bit = False,     # QLoRA não recomendado para MoE
    load_in_16bit = True,     # bf16 LoRA
    full_finetuning = False,
)

Uma vez carregado, anexe os adaptadores LoRA e treine da mesma forma que o exemplo E4B acima. Para ajuste fino de MoE, o Unsloth recomenda começar com rank 16 e comprimentos de contexto curtos, escala apenas depois que o pipeline estiver estável.

Fine-tuning multimodal (E2B e E4B)

E2B e E4B são as variantes do Gemma 4 projetadas para tarefas multimodais — elas processam nativamente imagens e áudio. Se sua tarefa envolve imagens, use FastVisionModel:

from unsloth import FastVisionModel
from unsloth.trainer import UnslothVisionDataCollator
from trl import SFTTrainer, SFTConfig

model, tokenizer = FastVisionModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = 2048,
    load_in_4bit = False,
    use_gradient_checkpointing = "unsloth",
)

model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers     = False,  # Comece apenas com texto para economizar VRAM
    finetune_language_layers   = True,
    finetune_attention_modules = True,
    finetune_mlp_modules       = True,
    r = 16,
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    target_modules = "all-linear",
)

trainer = SFTTrainer(
    model = model,
    tokenizer = tokenizer,
    data_collator = UnslothVisionDataCollator(model, tokenizer),
    train_dataset = dataset,
    args = SFTConfig(
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        learning_rate = 2e-4,
        output_dir = "outputs_gemma4_vision",
    ),
)

trainer.train()

Importante: Nos prompts multimodais do Gemma 4, a imagem deve vir antes da instrução de texto na lista de conteúdo da mensagem. O formato se parece com este:

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image", "image": "path/to/image.jpg"},
        {"type": "text",  "text": "Descreva o que está acontecendo nesta imagem."}
      ]
    },
    {
      "role": "model",
      "content": "..."
    }
  ]
}

Para ajuste fino de áudio (apenas E2B / E4B): mantenha os clipes de áudio curtos e específicos para a tarefa. O Unsloth recomenda seguir os exemplos de notebook de Vision RL para fluxos de áudio.

Salvando e exportando seu modelo ajustado

Após o treinamento, você tem vários caminhos de exportação, dependendo de onde planeja implantar.

Salvar como adaptador LoRA (mais rápido, menor)

model.save_pretrained("gemma4_e4b_adapter")
tokenizer.save_pretrained("gemma4_e4b_adapter")

Isso salva apenas os pesos do adaptador — alguns centenas de MB em vez do modelo completo. Você precisará do modelo base no momento da inferência.

Mesclar e exportar para GGUF (para llama.cpp / Ollama / LM Studio)

model.save_pretrained_gguf(
    "gemma4_e4b_finetuned",
    tokenizer,
    quantization_method = "q4_k_m"   # ou "q8_0", "f16"
)

O arquivo .gguf resultante pode ser carregado diretamente no llama.cpp, importado no Ollama com um Modelfile personalizado ou carregado no LM Studio.

Exportar pelo Unsloth Studio

Se você usou a interface do Studio, vá para a guia Export após a conclusão do treinamento. Selecione GGUF, safetensors ou ambos. O Studio cuida da mesclagem automaticamente.

Um detalhe a observar: se o modelo exportado se comportar de forma inesperada em outro runtime (Ollama, llama.cpp), a causa mais comum é um chat template ou token EOS desalinhado. Use sempre o mesmo chat template na inferência que você usou durante o treinamento.

Notebooks gratuitos no Colab

O Unsloth fornece notebooks gratuitos no Google Colab para todos os tamanhos de Gemma 4. Os notebooks E2B/E4B rodam em uma GPU T4 gratuita. Os notebooks 26B-A4B e 31B exigem uma A100 (Colab Pro).

Modelo	Tarefa	Link
E2B	Texto	Abrir no Colab
E2B	Visão	Abrir no Colab
E2B	Áudio	Abrir no Colab
26B-A4B	Visão (A100)	Abrir no Colab
31B	Visão (A100)	Abrir no Colab

Problemas comuns

Falta de memória durante o treinamento. Reduza primeiro max_seq_length e depois baixe per_device_train_batch_size para 1. Certifique-se de que use_gradient_checkpointing="unsloth" está definido — ele foi projetado especificamente para aumentar a janela de contexto e reduzir a VRAM.

Usando QLoRA no 26B-A4B. A arquitetura MoE e a quantização de 4 bits interagem mal. Utilize LoRA de 16 bits (load_in_16bit=True) para o modelo MoE.

Desalinhamento de chat template após exportação. Se o modelo exportado responder incorretamente no Ollama ou llama.cpp, verifique se o runtime de inferência está usando o mesmo chat template do Gemma 4 com o qual você treinou. Esta é a causa mais comum de degradação do comportamento pós-exportação.

Capacidade de raciocínio degradada após o fine-tuning. Se você deseja preservar a capacidade de raciocínio nativa do Gemma 4, misture exemplos de estilo de raciocínio com exemplos de resposta direta em seus dados de treinamento. O Unsloth recomenda pelo menos 75% de exemplos de raciocínio para manter o comportamento de pensamento (thinking behavior).

Para a referência oficial de treinamento, consulte a documentação do Unsloth.