Como ajustar o Gemma 4: passo a passo completo com um dataset de emoções humanas

O Google acaba de apresentar o Gemma 4, descrevendo-o como sua família de modelos abertos mais inteligente até agora, criada para raciocínio avançado e fluxos de trabalho agentic. Os modelos Gemma foram projetados para serem flexíveis em diferentes ambientes, com suporte e ferramentas oficiais para desenvolvimento local, implantação em nuvem e customização de modelos — o que os torna uma ótima escolha para projetos de fine-tuning.

Neste tutorial, vamos ajustar o Gemma 4 E4B-it em um dataset de classificação de emoções humanas do Hugging Face. Vamos configurar um ambiente com GPU 3090, carregar e inspecionar o dataset, preparar e formatar os dados para fine-tuning supervisionado, carregar o modelo base, rodar uma avaliação baseline antes do treino, ajustar o modelo e, então, avaliar novamente seu desempenho após o treinamento.

1. configurando o ambiente

Comece iniciando uma nova instância do Runpod e verifique se sua conta tem pelo menos US$ 5 de crédito antes de começar. Para este tutorial, escolha um pod com GPU 3090 e selecione o template mais recente do PyTorch.

Antes de fazer o deploy, abra as configurações do template e faça alguns ajustes. Aumente o disco do container e o disco do volume para 40 GB para ter espaço suficiente para o modelo, o dataset, arquivos em cache e checkpoints de treinamento. 

Também vale adicionar seu token do Hugging Face como variável de ambiente. Você pode gerar esse token em Settings > Access Tokens na sua conta do Hugging Face.

Com essas definições aplicadas, faça o deploy do pod. A instância pode levar um ou dois minutos para iniciar. Quando estiver pronta, abra a interface do JupyterLab para começar a trabalhar no ambiente.

A primeira coisa a fazer no JupyterLab é abrir um novo notebook Python e instalar todos os pacotes necessários. Rode o comando abaixo em uma célula:

%%capture
!pip install -U transformers accelerate datasets trl peft bitsandbytes scikit-learn huggingface_hub

Esses pacotes cobrem todo o fluxo: carregar o dataset, preparar o modelo, fazer o fine-tuning e avaliar.

O último passo é entrar no Hugging Face Hub usando seu token salvo. Isso dá acesso ao modelo com acesso restrito e também facilita enviar arquivos, criar repositórios e publicar seu modelo ajustado depois.

import os
from huggingface_hub import login

hf_token = os.environ.get("HF_TOKEN")
if not hf_token:
    raise ValueError("Set HF_TOKEN in the RunPod environment before running this notebook.")

login(token=hf_token)
print("Logged in to Hugging Face.")

2. carregando e preparando o dataset de emoções

Com o ambiente pronto, o próximo passo é carregar o dataset de emoções do Hugging Face e preparar subconjuntos menores para treino e avaliação. 

Para este tutorial, não usamos o dataset completo. Em vez disso, criamos divisões limitadas de treino, validação e teste para que o processo de fine-tuning fique mais rápido e viável em uma única GPU.

from datasets import load_dataset, DatasetDict

TRAIN_LIMIT = 4000    
VALIDATION_LIMIT = 400  
TEST_LIMIT = 400          
EVAL_LIMIT = 400        

raw_dataset = load_dataset("dair-ai/emotion")

def maybe_limit(split, limit):
    split = split.shuffle(seed=42)
    if limit is None:
        return split
    return split.select(range(min(limit, len(split))))

dataset = DatasetDict({
    "train": maybe_limit(raw_dataset["train"], TRAIN_LIMIT),
    "validation": maybe_limit(raw_dataset["validation"], VALIDATION_LIMIT),
    "test": maybe_limit(raw_dataset["test"], TEST_LIMIT),
})

dataset

O dataset final contém 4.000 exemplos de treino, 400 de validação e 400 de teste.

DatasetDict({
    train: Dataset({
        features: ['text', 'label'],
        num_rows: 4000
    })
    validation: Dataset({
        features: ['text', 'label'],
        num_rows: 400
    })
    test: Dataset({
        features: ['text', 'label'],
        num_rows: 400
    })
})

Em seguida, verificamos os nomes das classes armazenados no dataset. Essas são as emoções que o modelo vai aprender a prever.

label_names = dataset["train"].features["label"].names
label_names

Vemos que a tarefa tem seis categorias de emoção: sadness, joy, love, anger, fear e surprise.

['sadness', 'joy', 'love', 'anger', 'fear', 'surprise']

Também podemos inspecionar um exemplo do conjunto de treino para ver a estrutura dos dados.

dataset["train"][0]

Cada exemplo contém um trecho de texto e um rótulo numérico. Neste caso, o rótulo 4 mapeia para fear de acordo com a lista de rótulos acima.

{'text': 'while cycling in the country', 'label': 4}

3. formatando os dados para o fine-tuning do gemma 4

Antes de ajustar o modelo, precisamos converter o dataset para o formato que o Gemma 4 usará durante o treinamento. 

Em vez de passar apenas texto bruto e rótulos, estruturamos cada exemplo como uma breve interação de chat, com uma mensagem do sistema, uma mensagem do usuário e a resposta esperada do assistente.

O prompt do sistema orienta exatamente qual tarefa o modelo deve executar. Aqui, queremos que o modelo atue como um assistente de classificação de emoções e retorne apenas um dos seis rótulos permitidos.

SYSTEM_PROMPT = """You are an emotion classification assistant.
Read the user's text and answer with exactly one label.
Only choose from: sadness, joy, love, anger, fear, surprise.
Return only the label and nothing else."""

Nesta configuração, a mensagem do usuário contém o texto de entrada que queremos classificar, e a mensagem do assistente traz o rótulo correto. Esse é o formato usado no fine-tuning supervisionado, em que o modelo aprende a gerar a resposta certa para cada exemplo de treino.

def to_prompt_completion(example):
    text = example["text"]
    label = label_names[example["label"]]
    return {
        "prompt": [
            {
                "role": "system",
                "content": SYSTEM_PROMPT,
            },
            {
                "role": "user",
                "content": f"Classify the emotion of this text:\n\n{text}",
            },
        ],
        "completion": [
            {
                "role": "assistant",
                "content": label,
            }
        ],
    }

sft_dataset = dataset.map(to_prompt_completion, remove_columns=dataset["train"].column_names)

Depois de aplicar essa função, as colunas originais de text e label são substituídas pelos campos estruturados de prompt e completion.

Podemos inspecionar um exemplo para confirmar que o dataset foi formatado corretamente.

sft_dataset["train"][0]

A saída mostra claramente toda a estrutura de treino. O modelo vê a instrução, lê o texto de entrada e aprende a produzir o rótulo de emoção correto como resposta.

{'prompt': [{'content': "You are an emotion classification assistant.\nRead the user's text and answer with exactly one label.\nOnly choose from: sadness, joy, love, anger, fear, surprise.\nReturn only the label and nothing else.",
   'role': 'system'},
  {'content': 'Classify the emotion of this text:\n\nwhile cycling in the country',
   'role': 'user'}],
 'completion': [{'content': 'fear', 'role': 'assistant'}]}

4. carregando o gemma e4b-it com quantização em 4 bits

Agora podemos carregar o Gemma 4 E4B-it e prepará-lo para o fine-tuning. Como este é um modelo relativamente grande, vamos carregá-lo com quantização em 4 bits para reduzir o uso de memória e facilitar a execução em uma GPU 3090. Também usamos bfloat16 como tipo de cálculo, o que deixa a configuração mais eficiente.

Começamos importando as bibliotecas necessárias e definindo as principais configurações do modelo.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

MODEL_ID = "google/gemma-4-E4B-it"
MODEL_DTYPE = torch.bfloat16
USE_4BIT = True

Depois, habilitamos algumas otimizações de CUDA e carregamos o tokenizer.

if torch.cuda.is_available():
    torch.backends.cuda.matmul.allow_tf32 = True
    torch.backends.cudnn.allow_tf32 = True

processor = AutoTokenizer.from_pretrained(MODEL_ID, use_fast=True)
if processor.pad_token is None:
    processor.pad_token = processor.eos_token

Agora preparamos as configurações de quantização e os argumentos de carregamento do modelo.

bnb_config = None
model_kwargs = {
    "device_map": "auto",
}
if USE_4BIT:
    bnb_config = BitsAndBytesConfig(
        load_in_4bit=True,
        bnb_4bit_quant_type="nf4",
        bnb_4bit_compute_dtype=MODEL_DTYPE,
    )
    model_kwargs["quantization_config"] = bnb_config
else:
    model_kwargs["torch_dtype"] = MODEL_DTYPE

Por fim, carregamos o modelo e alinhamos sua configuração com o tokenizer.

base_model = AutoModelForCausalLM.from_pretrained(MODEL_ID, **model_kwargs)
base_model.config.use_cache = False
base_model.config.pad_token_id = processor.pad_token_id
base_model.config.bos_token_id = processor.bos_token_id
base_model.config.eos_token_id = processor.eos_token_id
base_model.generation_config.pad_token_id = processor.pad_token_id
base_model.generation_config.bos_token_id = processor.bos_token_id
base_model.generation_config.eos_token_id = processor.eos_token_id

print(f"Base model loaded with 4-bit={USE_4BIT} and dtype={MODEL_DTYPE}.")

Isso carrega o modelo base no dispositivo disponível, desativa o cache para treinamento e garante que os IDs dos tokens especiais estejam corretos tanto na config do modelo quanto na de geração.

Base model loaded with 4-bit=True and dtype=torch.bfloat16.

5. avaliando o modelo base

Antes do fine-tuning, é útil avaliar primeiro o modelo base para termos um baseline claro de comparação. 

Nesta seção, definimos algumas funções auxiliares que geram previsões, extraem rótulos válidos de emoção e rodam a avaliação no conjunto de teste.

Começamos criando um padrão simples para extração de rótulos e funções auxiliares de predição.

Essas funções cobrem todo o fluxo de predição. O modelo recebe a entrada em formato de chat, gera uma resposta curta e, então, extraímos o rótulo previsto. Se o modelo retornar texto extra, a função tenta recuperar o primeiro rótulo de emoção válido.

import re

LABEL_PATTERN = re.compile(r"\b(sadness|joy|love|anger|fear|surprise)\b", re.IGNORECASE)

def extract_label(raw_text: str) -> str:
    raw_text = raw_text.strip().lower()
    match = LABEL_PATTERN.search(raw_text)
    if match:
        return match.group(1)

    first_token = raw_text.split()[0].strip(".,!?:;\"'()[]{}") if raw_text.split() else ""
    return first_token

def generate_label(model, processor, user_text, system_prompt, max_new_tokens=4):
    messages = [
        {
            "role": "system",
            "content": system_prompt,
        },
        {
            "role": "user",
            "content": f"Classify the emotion of this text:\n\n{user_text}",
        },
    ]

    device = next(model.parameters()).device
    inputs = processor.apply_chat_template(
        messages,
        tokenize=True,
        add_generation_prompt=True,
        return_dict=True,
        return_tensors="pt",
    ).to(device)

    input_len = inputs["input_ids"].shape[-1]

    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=max_new_tokens,
            do_sample=False,
            pad_token_id=processor.pad_token_id,
            eos_token_id=processor.eos_token_id,
        )

    raw_pred = processor.decode(outputs[0][input_len:], skip_special_tokens=True).strip()
    return extract_label(raw_pred)


def predict_emotion(user_text: str, model=None, proc=None) -> str:
    model = model or base_model
    proc = proc or processor
    return generate_label(model, proc, user_text, SYSTEM_PROMPT)

Agora podemos testar a configuração em um único exemplo antes de rodar a avaliação completa.

predict_emotion("I feel so happy and excited today!")

A predição de exemplo parece correta, então podemos avançar para avaliar o modelo em todo o conjunto de teste.

'joy'

O código abaixo avalia o modelo no split de teste e coleta diversas saídas úteis. Ele armazena os rótulos verdadeiros e previstos, marca se cada previsão está correta e retorna métricas resumidas, um relatório de classificação e um dataframe com todas as previsões.

from sklearn.metrics import accuracy_score, classification_report, confusion_matrix, f1_score
import pandas as pd
from tqdm.auto import tqdm

VALID_LABELS = set(label_names)
ALL_EVAL_LABELS = label_names + ["INVALID"]

def evaluate_model(model, processor, split="test", limit=EVAL_LIMIT):
    y_true, y_pred, rows = [], [], []
    raw_source = dataset[split]
    if limit is not None:
        raw_source = raw_source.select(range(min(limit, len(raw_source))))

    model.eval()

    for ex in tqdm(raw_source, desc=f"Evaluating {split}", leave=False):
        true_label = label_names[ex["label"]]
        raw_pred_label = generate_label(model, processor, ex["text"], SYSTEM_PROMPT)
        pred_label = raw_pred_label if raw_pred_label in VALID_LABELS else "INVALID"

        y_true.append(true_label)
        y_pred.append(pred_label)
        rows.append({
            "text": ex["text"],
            "true_label": true_label,
            "pred_label": pred_label,
            "raw_pred_label": raw_pred_label,
            "correct": true_label == pred_label,
        })

    metrics = {
        "accuracy": accuracy_score(y_true, y_pred),
        "macro_f1": f1_score(y_true, y_pred, labels=label_names, average="macro", zero_division=0),
        "invalid_predictions": sum(1 for p in y_pred if p == "INVALID"),
        "evaluated_examples": len(y_true),
    }

    report = classification_report(
        y_true,
        y_pred,
        labels=label_names,
        output_dict=True,
        zero_division=0,
    )

    df = pd.DataFrame(rows)
    return metrics, report, df

def confusion_matrix_df(pred_df):
    return pd.DataFrame(
        confusion_matrix(pred_df["true_label"], pred_df["pred_label"], labels=ALL_EVAL_LABELS),
        index=ALL_EVAL_LABELS,
        columns=ALL_EVAL_LABELS,
    )

Agora podemos rodar a avaliação baseline completa no modelo base.

pre_metrics, pre_report, pre_preds = evaluate_model(base_model, processor, "test")
pre_metrics

Os resultados iniciais mostram que o modelo sem ajuste já tem um desempenho razoável, mas ainda há espaço para melhorar. 

A acurácia fica em torno de 58,25%, o F1 macro em cerca de 0,42, e o modelo gerou 33 previsões inválidas, ou seja, às vezes retornou algo fora do conjunto esperado de rótulos.

{'accuracy': 0.5825,
 'macro_f1': 0.42112912841373906,
 'invalid_predictions': 33,
 'evaluated_examples': 400}

Em seguida, podemos ver o relatório completo de classificação por categoria de emoção.

pd.DataFrame(pre_report).transpose()

Isso nos dá precisão, revocação, F1 e suporte para cada classe. Ajuda a ver quais emoções o modelo lida melhor e quais são mais desafiadoras antes do ajuste.

Por fim, podemos inspecionar a matriz de confusão.

confusion_matrix_df(pre_preds)

A matriz de confusão mostra como as previsões se distribuem entre as diferentes classes. 

No notebook, ela aparece como uma tabela, o que facilita identificar quais emoções estão sendo confundidas entre si e onde o modelo base mais erra.

6. fazendo fine-tuning do gemma 4 com lora

Com os resultados baseline em mãos, podemos ajustar o Gemma 4 usando LoRA. 

LoRA é um método de fine-tuning eficiente em parâmetros, o que significa que não atualizamos o modelo completo. Em vez disso, anexamos um pequeno conjunto de pesos de adaptadores treináveis sobre o modelo base. Isso torna o treino muito mais leve e prático em uma única GPU.

Começamos definindo a configuração do LoRA.

Essas configurações controlam como os adaptadores LoRA são anexados ao modelo. Aqui usamos rank 16, dropout de 0,05 e aplicamos LoRA a todas as camadas lineares — uma configuração comum para fine-tuning eficiente.

from peft import LoraConfig

lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules="all-linear"
)

Depois, definimos a configuração de treinamento e preparamos o trainer.

A configuração de treino foi pensada para manter o uso de memória sob controle e, ao mesmo tempo, dar espaço para o modelo aprender com o dataset. Treinamos por uma época, usamos acumulação de gradiente para simular um batch maior e habilitamos opções como gradient checkpointing e otimização em 8 bits para ganhar eficiência.

from trl import SFTConfig, SFTTrainer

training_args = SFTConfig(
    output_dir="./gemma4-emotion-lora",
    per_device_train_batch_size=8,
    per_device_eval_batch_size=8,
    gradient_accumulation_steps=2,
    learning_rate=1e-4,
    weight_decay=0.01,
    lr_scheduler_type="linear",
    warmup_steps=50,
    num_train_epochs=1,
    logging_steps=50,
    eval_strategy="steps",
    metric_for_best_model="eval_loss",
    greater_is_better=False,
    gradient_checkpointing=True,
    bf16=True,
    fp16=False,
    tf32=True,
    max_length=256,
    packing=False,
    completion_only_loss=True,
    remove_unused_columns=False,
    dataloader_num_workers=2,
    optim="paged_adamw_8bit",
    report_to="none",
)

Agora garantimos que o modelo base está pronto e inicializamos o trainer. Este passo anexa os adaptadores LoRA ao modelo base e prepara o trainer de fine-tuning supervisionado usando nossos splits formatados de treino e validação.

from peft import PeftModel

if isinstance(base_model, PeftModel):
    base_model = base_model.unload()
    base_model.config.use_cache = False

trainer = SFTTrainer(
    model=base_model,
    train_dataset=sft_dataset["train"],
    eval_dataset=sft_dataset["validation"],
    peft_config=lora_config,
    args=training_args,
    processing_class=processor,
)

Antes de começar o treino, vale confirmar se os parâmetros do LoRA foram anexados corretamente.

O código a seguir conta o número de parâmetros treináveis e gera um erro se nenhuma camada LoRA tiver sido adicionada. 

Depois disso, o treinamento começa. 

trainable_params = 0
for param in trainer.model.parameters():
    if param.requires_grad:
        trainable_params += param.numel()

if trainable_params == 0:
    raise RuntimeError("No trainable LoRA parameters were attached. Check target_modules before training.")

print(f"Trainable LoRA parameters: {trainable_params:,}")
train_result = trainer.train()
trainer.model.eval()
trainer.model.config.use_cache = True
train_result

Nesta execução, o treinamento levou quase 9 minutos, e tanto a loss de treino quanto a de validação caíram ao longo do tempo — um bom sinal de que o modelo estava aprendendo com o dataset.

Com o treino concluído, salvamos o adaptador e o tokenizer localmente.

trainer.model.save_pretrained("./gemma4-emotion-lora")
processor.save_pretrained("./gemma4-emotion-lora")

Por fim, podemos enviar o modelo para o Hugging Face Hub.

Isso publica o adaptador ajustado e o tokenizer no Hub para que você possa acessá-los de qualquer lugar, compartilhar com outras pessoas ou carregar direto em outro notebook ou aplicação.

repo_id = "kingabzpro/gemma4-emotion-lora"

# Push adapter + processor to the Hub
trainer.model.push_to_hub(
    repo_id,
    private=False,
)

processor.push_to_hub(
    repo_id,
    private=False,
)

Agora você pode ver kingabzpro/gemma4-emotion-lora no Hugging Face e testar por conta própria. O repositório inclui os arquivos do modelo, instruções de uso e os resultados do fine-tuning.

Fonte: kingabzpro/gemma4-emotion-lora · Hugging Face

7. avaliando o modelo ajustado

Com o treinamento concluído, o passo final é avaliar o modelo ajustado no mesmo split de teste e comparar os resultados com o modelo base. Assim vemos se o fine-tuning com LoRA melhorou a capacidade do modelo de classificar emoções com mais precisão.

Começamos carregando o modelo ajustado a partir do trainer e rodando a avaliação.

ft_model = trainer.model
ft_model.eval()
ft_model.config.use_cache = True
post_metrics, post_report, post_preds = evaluate_model(ft_model, processor, "test")
post_metrics

Isso nos dá as métricas principais de avaliação do modelo ajustado.

Os resultados são claramente melhores que o baseline. Após o fine-tuning, o modelo atinge 77,25% de acurácia e F1 macro de 0,698. O número de previsões inválidas também caiu de 33 para 20, mostrando que o modelo ajustado não só ficou mais preciso, como também mais consistente ao retornar rótulos válidos.

{'accuracy': 0.7725,
 'macro_f1': 0.697702361480462,
 'invalid_predictions': 20,
 'evaluated_examples': 400}

Depois, podemos ver o relatório completo de classificação.

Ele aparece como um pandas DataFrame direto no notebook, incluindo precisão, revocação, F1 e suporte para cada classe de emoção, facilitando enxergar quais categorias mais melhoraram após o fine-tuning.

pd.DataFrame(post_report).transpose()

Ele também é exibido como tabela no notebook. Isso ajuda a ver onde o modelo ajustado ainda erra e quais emoções são mais confundidas entre si.

confusion_matrix_df(post_preds)

Para deixar a comparação mais clara, podemos colocar as métricas de antes e depois do fine-tuning lado a lado.

comparison_df = pd.DataFrame([
    {"stage": "pre_finetuning", **pre_metrics},
    {"stage": "post_finetuning", **post_metrics},
])
comparison_df

Isso dá um resumo rápido de quanto o modelo evoluiu após o treinamento.

Observação: se você tiver qualquer problema ao rodar o código, consulte o notebook completo do Jupyter aqui: fine-tune-gemma-4-on-emotions_final.ipynb

considerações finais

O fine-tuning do Gemma 4 é bastante sensível à configuração, especialmente à estrutura do prompt e aos argumentos de treino. Se o formato do prompt estiver errado, ou se você não usar o template adequado de forma consistente, o modelo pode até treinar sem, de fato, aprender bem a tarefa. O mesmo vale para as configurações de treino. Geralmente, esses são os principais motivos para a loss não cair ou para a loss cair, mas os resultados de avaliação mal melhorarem.

Outra lição importante é o max_length. Se você reduzi-lo demais, especialmente abaixo de cerca de 125, o modelo pode nem aprender o padrão corretamente. Enfrentei vários problemas durante o processo, mas foram sendo resolvidos um a um — e a maioria estava relacionada a essas duas áreas: formatação do prompt e configuração de treino.

Para melhorar ainda mais os resultados, um bom próximo passo é ajustar no dataset completo e treinar por pelo menos 3 épocas em vez de apenas uma. Isso dá ao modelo mais exemplos para aprender e mais tempo para se adaptar, o que deve levar a acurácias e escores de F1 mais altos.