Gemma 4 fijnstemmen: een volledige walkthrough met een dataset van menselijke emoties

Google heeft zojuist Gemma 4 geïntroduceerd en noemt het hun meest intelligente open modelfamilie tot nu toe, gebouwd voor sterk redeneren en agent‑achtige workflows. Gemma‑modellen zijn ontworpen om flexibel te zijn in verschillende omgevingen, met officiële support en tooling voor lokale ontwikkeling, cloud‑deployment en modelaanpassing. Dat maakt ze een sterke keuze voor fine‑tuningprojecten.

In deze tutorial gaan we Gemma 4 E4B-it fijnstemmen op een dataset voor classificatie van menselijke emoties van Hugging Face. We richten een 3090‑GPU‑omgeving in, laden en inspecteren de dataset, bereiden en formatteren de data voor supervised fine‑tuning, laden het basismodel, voeren een baseline‑evaluatie uit vóór training, stemmen het model fijn en evalueren daarna opnieuw de prestaties.

1. De omgeving instellen

Begin met het starten van een nieuwe Runpod‑instantie en zorg dat je account minstens $5 tegoed heeft voordat je begint. Kies voor deze tutorial een 3090‑GPU‑pod en selecteer de nieuwste PyTorch‑template.

Open vóór het deployen de templatesettings en pas een paar dingen aan. Vergroot zowel de containerdisk als de volumedisk naar 40 GB zodat je genoeg ruimte hebt voor het model, de dataset, cachebestanden en trainingscheckpoints. 

Voeg ook je Hugging Face‑token toe als een omgevingsvariabele. Je kunt dit token genereren via Settings > Access Tokens in je Hugging Face‑account.

Zodra deze instellingen klaar zijn, kun je de pod deployen. Het kan een minuut of twee duren voordat de instantie start. Als deze klaar is, open je de JupyterLab‑interface zodat je in de omgeving aan de slag kunt.

Het eerste wat je in JupyterLab doet, is een nieuw Python‑notebook starten en alle vereiste Python‑packages installeren. Voer het volgende commando uit in een notebookcel:

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

Deze packages dekken de volledige workflow, inclusief het laden van de dataset, het voorbereiden van het model, het fijnstemmen en de evaluatie.

De laatste stap is inloggen bij de Hugging Face Hub met je opgeslagen token. Dit geeft je toegang tot het afgeschermde model en maakt het ook makkelijker om bestanden te uploaden, repositories te maken en je fijngestemde model later te pushen.

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. Laad en bereid de emotiedataset voor

Nu de omgeving klaar is, is de volgende stap het laden van de emotiedataset van Hugging Face en het voorbereiden van kleinere splits voor training en evaluatie. 

Voor deze tutorial gebruiken we niet de volledige dataset. In plaats daarvan maken we beperkte train‑, validatie‑ en testsplits, zodat het fijnstemmingsproces sneller blijft en eenvoudiger op een enkele GPU draait.

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

De uiteindelijke dataset bevat 4.000 trainingsvoorbeelden, 400 validatievoorbeelden en 400 testvoorbeelden.

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
    })
})

Vervolgens bekijken we de labelnamen die in de dataset zijn opgeslagen. Dit zijn de emotieklassen die het model leert voorspellen.

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

Hieruit blijkt dat de taak zes emotiecategorieën heeft: sadness, joy, love, anger, fear en surprise.

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

We kunnen ook een voorbeeld uit de trainingssplit inspecteren om te zien hoe de data is opgebouwd.

dataset["train"][0]

Elk voorbeeld bevat een stuk tekst en een numeriek label. In dit geval mapt label 4 naar fear op basis van de bovenstaande labellijst.

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

3. Data formatteren voor Gemma 4‑fine‑tuning

Voordat we het model kunnen fijnstemmen, moeten we de dataset omzetten naar het formaat dat Gemma 4 tijdens training gebruikt. 

In plaats van alleen ruwe tekst en labels door te geven, structureren we elk voorbeeld als een korte chatinteractie met een systeembericht, een gebruikersbericht en de verwachte assistentrespons.

De systeemprompt vertelt het model precies welke taak het moet uitvoeren. In dit geval willen we dat het model optreedt als een assistent voor emotieclassificatie en slechts één van de zes toegestane labels teruggeeft.

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."""

In deze opzet bevat het gebruikersbericht de invoertekst die we willen classificeren en bevat het assistentbericht het correcte label. Dit is het formaat voor supervised fine‑tuning, waarbij het model leert de juiste respons te genereren voor elk trainingsvoorbeeld.

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)

Na het toepassen van deze formatteringsfunctie worden de oorspronkelijke kolommen text en label vervangen door gestructureerde velden prompt en completion.

We kunnen één voorbeeld inspecteren om te bevestigen dat de dataset correct is geformatteerd.

sft_dataset["train"][0]

De output toont duidelijk de volledige trainingsstructuur. Het model ziet de instructie, leest de invoertekst en leert het juiste emotielabel als antwoord te geven.

{'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. Gemma E4B-it laden met 4‑bit‑kwantisatie

Nu kunnen we Gemma 4 E4B-it laden en voorbereiden op fine‑tuning. Omdat dit een relatief groot model is, laden we het met 4‑bit‑kwantisatie om het geheugengebruik te verlagen en het makkelijker te maken op een 3090‑GPU te draaien. We gebruiken ook bfloat16 als berekeningstype, wat helpt om de setup efficiënt te houden.

We beginnen met het importeren van de vereiste libraries en het definiëren van de belangrijkste modelinstellingen.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

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

Vervolgens schakelen we een paar CUDA‑optimalisaties in en laden we de 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

Nu bereiden we de kwantisatie‑instellingen en argumenten voor het laden van het model voor.

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

Tot slot laden we het model en stemmen we de configuratie af op de 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}.")

Dit laadt het basismodel op het beschikbare device, schakelt caching uit voor training en zorgt dat de speciale token‑ID's correct zijn ingesteld voor zowel de modelconfig als de generatieconfig.

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

5. Het basismodel evalueren

Voordat we fijnstemmen, is het nuttig om eerst het basismodel te evalueren, zodat we later een duidelijke baseline hebben om mee te vergelijken. 

In deze sectie definiëren we een paar helperfuncties die voorspellingen genereren, geldige emotielabels extraheren en evaluatie uitvoeren op de testsplit.

We beginnen met het maken van een eenvoudig patroontje voor labelextractie en helperfuncties voor voorspelling.

Deze functies verzorgen de volledige voorspellingsflow. Het model ontvangt de input in chatformaat, genereert een korte respons en daarna extraheren we het voorspelde label. Als het model extra tekst terugstuurt, probeert de helperfunctie het eerste geldige emotielabel te herstellen.

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)

Nu kunnen we de setup testen op een enkel voorbeeld voordat we de volledige evaluatie draaien.

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

De voorbeeldvoorspelling ziet er goed uit, dus we kunnen doorgaan met evalueren over de testsplit.

'joy'

Deze code evalueert het model op de testsplit en verzamelt verschillende nuttige outputs. Hij slaat de echte en voorspelde labels op, houdt bij of elke voorspelling correct is en retourneert samenvattende statistieken, een classificatierapport en een dataframe met alle voorspellingen.

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,
    )

Nu kunnen we de volledige baseline‑evaluatie op het basismodel draaien.

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

Deze baselineresultaten laten zien dat het niet‑afgestemde model al redelijk presteert, maar dat er nog ruimte is voor verbetering. 

De accuracy ligt rond de 58,25%, de macro‑F1‑score rond de 0,42 en het model produceerde 33 ongeldige voorspellingen, wat betekent dat het soms iets buiten de verwachte labelset teruggaf.

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

Vervolgens kunnen we het volledige classificatierapport per emotiecategorie bekijken.

pd.DataFrame(pre_report).transpose()

Dit geeft ons de precision, recall, F1‑score en support per klasse. Het helpt te zien welke emoties het model goed aan kan en welke lastiger zijn vóór het fijnstemmen.

Tot slot kunnen we de verwarringsmatrix inspecteren.

confusion_matrix_df(pre_preds)

De verwarringsmatrix toont hoe de voorspellingen over de verschillende klassen zijn verdeeld. 

In het notebook wordt dit als tabel weergegeven, zodat je makkelijker ziet welke emoties met elkaar verward worden en waar het basismodel het meest mee worstelt.

6. Gemma 4 fijnstemmen met LoRA

Nu we de baselineresultaten hebben, kunnen we Gemma 4 fijnstemmen met LoRA. 

LoRA is een parameter‑efficiënte fine‑tuningmethode, wat betekent dat we niet het volledige model updaten. In plaats daarvan koppelen we een klein aantal trainbare adaptergewichten bovenop het basismodel. Dit maakt trainen veel lichter en praktischer op een enkele GPU.

We beginnen met het definiëren van de LoRA‑configuratie.

Deze instellingen bepalen hoe de LoRA‑adapters aan het model worden gekoppeld. Hier gebruiken we een rank van 16, een dropout van 0,05, en passen we LoRA toe op alle lineaire lagen. Dit is een gebruikelijke setup voor efficiënte fine‑tuning.

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"
)

Vervolgens definiëren we de trainingsconfiguratie en zetten we de trainer op.

Deze trainingssetup is bedoeld om het geheugengebruik beheersbaar te houden en het model tegelijkertijd genoeg ruimte te geven om van de dataset te leren. We trainen één epoch, gebruiken gradient accumulation om een grotere batchgrootte te simuleren en schakelen opties in zoals gradient checkpointing en 8‑bit‑optimalisatie om het trainen efficiënter te maken.

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",
)

Nu zorgen we dat het basismodel klaar is en initialiseren we de trainer. Deze stap koppelt de LoRA‑adapters aan het basismodel en bereidt de trainer voor supervised fine‑tuning met onze geformatteerde train‑ en validatiesplits.

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,
)

Voordat we met trainen beginnen, is het verstandig te controleren of de LoRA‑parameters correct zijn gekoppeld.

Dit telt het aantal trainbare parameters en geeft een fout als er geen LoRA‑lagen zijn toegevoegd. 

Daarna start de training. 

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

In deze run duurde het trainen bijna 9 minuten en zowel de training loss als de validation loss bleven in de loop van de tijd dalen, wat een goed teken is dat het model van de dataset leerde.

Als de training voltooid is, kunnen we de adapter en tokenizer lokaal opslaan.

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

Tot slot kunnen we het model naar de Hugging Face Hub pushen.

Dit uploadt de fijngestemde adapter en tokenizer naar de Hub zodat je er overal bij kunt, ze kunt delen met anderen of ze rechtstreeks kunt laden in een ander notebook of een applicatie.

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,
)

Je kunt nu kingabzpro/gemma4-emotion-lora bekijken op Hugging Face en het zelf proberen. De repository bevat de modelbestanden, gebruiksinstructies en de resultaten van het fijnstemmen.

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

7. Het fijngestemde model evalueren

Nu de training voltooid is, is de laatste stap het fijngestemde model op dezelfde testsplit te evalueren en de resultaten te vergelijken met het basismodel. Dit helpt te zien of LoRA‑fine‑tuning het vermogen van het model om emoties nauwkeuriger te classificeren heeft verbeterd.

We beginnen met het laden van het fijngestemde model uit de trainer en voeren de evaluatie uit.

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

Dit geeft ons de belangrijkste evaluatiestatistieken voor het fijngestemde model.

Deze resultaten zijn duidelijk sterker dan de baseline. Na het fijnstemmen behaalt het model 77,25% accuracy en een macro‑F1‑score van 0,698. Het aantal ongeldige voorspellingen daalt ook van 33 naar 20, wat laat zien dat het fijngestemde model niet alleen nauwkeuriger is, maar ook consistenter geldige labels teruggeeft.

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

Vervolgens kunnen we het volledige classificatierapport bekijken.

Dit toont het classificatierapport als een pandas DataFrame direct in het notebook. Het bevat de precision, recall, F1‑score en support per emotieklasse, waardoor je makkelijker ziet welke categorieën het meest verbeterden na het fijnstemmen.

pd.DataFrame(post_report).transpose()

Dit wordt in het notebook ook als tabel weergegeven. Het helpt je te zien waar het fijngestemde model nog fouten maakt en welke emotiecategorieën het vaakst met elkaar verward worden.

confusion_matrix_df(post_preds)

Om de vergelijking duidelijker te maken, kunnen we de statistieken vóór en na het fijnstemmen naast elkaar zetten.

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

Dit geeft een snelle samenvatting van hoeveel het model verbeterde na de training.

Opmerking: Als je problemen tegenkomt bij het uitvoeren van de code, kun je het volledige Jupyter‑notebook hier raadplegen: fine-tune-gemma-4-on-emotions_final.ipynb

Tot slot

Het fijnstemmen van Gemma 4 is erg gevoelig voor de setup, vooral de promptstructuur en de trainingsargumenten. Als het promptformaat niet klopt, of je niet consequent de juiste template gebruikt, kan het model de training doorlopen zonder de taak echt goed te leren. Hetzelfde geldt voor de trainingsinstellingen. Dit zijn meestal de hoofdredenen waarom de loss niet daalt, of waarom de loss daalt maar de evaluatieresultaten nauwelijks verbeteren.

Een andere belangrijke les is max_length. Als je die te veel verlaagt, vooral tot onder ongeveer 125, leert het model het patroon mogelijk helemaal niet goed. Ik ben tijdens dit proces tegen verschillende problemen aangelopen, maar die zijn één voor één opgelost en de meeste kwamen neer op dezelfde twee gebieden: promptformattering en trainingsconfiguratie.

Om de resultaten verder te verbeteren, is een goede volgende stap om te fijnstemmen op de volledige dataset en minstens 3 epochs te trainen in plaats van slechts één. Dat geeft het model meer voorbeelden om van te leren en meer tijd om zich aan te passen, wat zou moeten leiden tot hogere accuracy en F1‑scores.