Comment affiner Gemma 4 : guide complet pas à pas avec un jeu de données d'émotions humaines

Google vient de présenter Gemma 4, décrite comme sa famille de modèles open source la plus intelligente à ce jour, conçue pour un raisonnement avancé et des workflows agents. Les modèles Gemma sont pensés pour être flexibles selon les environnements, avec un support et des outils officiels pour le développement local, le déploiement cloud et la personnalisation de modèles : un excellent choix pour des projets de fine-tuning.

Dans ce tutoriel, nous allons affiner Gemma 4 E4B-it sur un jeu de données de classification des émotions humaines depuis Hugging Face. Nous mettrons en place un environnement GPU 3090, chargerons et examinerons le jeu de données, préparerons et formaterons les données pour un apprentissage supervisé, chargerons le modèle de base, exécuterons une évaluation de référence avant entraînement, affinerons le modèle, puis l'évaluerons à nouveau après entraînement.

1. Configuration de l'environnement

Commencez par lancer une nouvelle instance Runpod et vérifiez que votre compte dispose d'au moins 5 $ de crédit avant de commencer. Pour ce tutoriel, choisissez un pod GPU 3090 et sélectionnez le modèle PyTorch le plus récent.

Avant de déployer, ouvrez les paramètres du template et effectuez quelques mises à jour. Augmentez les tailles de disque du conteneur et de volume à 40 Go afin de disposer de suffisamment d'espace pour le modèle, le jeu de données, les fichiers en cache et les checkpoints d'entraînement. 

Ajoutez également votre jeton Hugging Face en tant que variable d'environnement. Vous pouvez générer ce jeton via Settings > Access Tokens dans votre compte Hugging Face.

Une fois ces paramètres en place, déployez le pod. Le démarrage de l'instance peut prendre une ou deux minutes. Lorsqu'elle est prête, ouvrez l'interface JupyterLab pour commencer à travailler dans l'environnement.

La première étape dans JupyterLab consiste à lancer un nouveau notebook Python et à installer tous les packages requis. Exécutez la commande suivante dans une cellule :

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

Ces packages couvrent l'ensemble du flux : chargement du jeu de données, préparation du modèle, fine-tuning et évaluation.

La dernière étape consiste à vous connecter au Hub Hugging Face avec votre jeton enregistré. Cela vous donne accès au modèle sous accès restreint et facilite le téléversement de fichiers, la création de dépôts et la mise en ligne de votre modèle affiné par la suite.

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. Charger et préparer le jeu de données d'émotions

Maintenant que l'environnement est prêt, chargeons le jeu de données d'émotions depuis Hugging Face et préparons des sous-ensembles plus petits pour l'entraînement et l'évaluation. 

Pour ce tutoriel, nous n'utilisons pas l'intégralité du jeu de données. Nous créons des splits limités train, validation et test pour que le fine-tuning reste rapide et facile à exécuter sur un seul 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

Le jeu de données final contient 4 000 exemples d'entraînement, 400 exemples de validation et 400 exemples de test.

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

Ensuite, examinons les noms d'étiquettes stockés dans le jeu de données. Ce sont les classes d'émotions que le modèle devra prédire.

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

On constate que la tâche comporte six catégories d'émotions : sadness, joy, love, anger, fear et surprise.

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

Nous pouvons aussi inspecter un exemple de l'ensemble d'entraînement pour voir la structure des données.

dataset["train"][0]

Chaque exemple contient un extrait de texte et une étiquette numérique. Dans ce cas, l'étiquette 4 correspond à fear d'après la liste ci-dessus.

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

3. Mise en forme des données pour le fine-tuning de Gemma 4

Avant d'affiner le modèle, nous devons convertir le jeu de données dans le format utilisé par Gemma 4 pendant l'entraînement. 

Plutôt que de passer uniquement du texte brut et des étiquettes, nous structurons chaque exemple comme une courte interaction de type chat avec un message système, un message utilisateur et la réponse attendue de l'assistant.

Le prompt système indique au modèle la tâche exacte à réaliser. Ici, nous voulons que le modèle agisse comme un assistant de classification des émotions et renvoie une seule étiquette parmi six autorisées.

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

Dans cette configuration, le message utilisateur contient le texte à classifier et le message assistant contient la bonne étiquette. C'est le format utilisé pour l'apprentissage supervisé, où le modèle apprend à générer la réponse correcte pour chaque exemple d'entraînement.

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)

Après application de cette fonction de formatage, les colonnes text et label d'origine sont remplacées par des champs structurés prompt et completion.

Nous pouvons vérifier un exemple pour confirmer que le format est correct.

sft_dataset["train"][0]

La sortie met en évidence toute la structure d'entraînement : le modèle voit l'instruction, lit le texte en entrée et apprend à produire la bonne étiquette d'émotion comme réponse.

{'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. Charger Gemma E4B-it avec une quantification 4 bits

Nous pouvons maintenant charger Gemma 4 E4B-it et le préparer pour le fine-tuning. Comme il s'agit d'un modèle relativement volumineux, nous le chargeons en quantification 4 bits pour réduire l'empreinte mémoire et faciliter l'exécution sur un GPU 3090. Nous utilisons également le type de calcul bfloat16 pour optimiser l'efficacité.

Nous commençons par importer les bibliothèques requises et définir les principaux paramètres du modèle.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

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

Ensuite, nous activons quelques optimisations CUDA et chargeons le 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

Nous préparons maintenant les paramètres de quantification et les arguments de chargement du modèle.

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

Enfin, nous chargeons le modèle et alignons sa configuration avec celle du 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}.")

Cela charge le modèle de base sur le périphérique disponible, désactive le cache pour l'entraînement et s'assure que les IDs de tokens spéciaux sont correctement définis tant pour la config du modèle que pour la génération.

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

5. Évaluer le modèle de base

Avant le fine-tuning, il est utile d'évaluer d'abord le modèle de base afin de disposer d'un point de comparaison clair pour la suite. 

Dans cette section, nous définissons quelques fonctions utilitaires qui génèrent des prédictions, extraient des étiquettes d'émotions valides et exécutent l'évaluation sur le split de test.

Nous commençons par créer un motif d'extraction d'étiquette simple et des fonctions d'aide pour la prédiction.

Ces fonctions gèrent tout le flux de prédiction : le modèle reçoit l'entrée au format chat, génère une courte réponse, puis nous extrayons l'étiquette prédite. Si le modèle renvoie du texte supplémentaire, la fonction utilitaire tente de récupérer la première étiquette d'émotion valide.

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)

Nous pouvons maintenant tester la configuration sur un seul exemple avant de lancer l'évaluation complète.

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

L'exemple de prédiction semble correct, nous pouvons donc passer à l'évaluation du modèle sur l'ensemble de test.

'joy'

Ce code évalue le modèle sur le split de test et collecte plusieurs sorties utiles : il enregistre les étiquettes réelles et prédites, suit si chaque prédiction est correcte, et renvoie des métriques de synthèse, un rapport de classification et un dataframe avec toutes les prédictions.

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

Nous pouvons maintenant lancer l'évaluation de référence complète sur le modèle de base.

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

Ces résultats de base montrent que le modèle non affiné s'en sort déjà correctement, mais qu'il reste une marge de progression. 

La précision est d'environ 58,25 %, le F1 macro à environ 0,42, et le modèle a produit 33 prédictions invalides, c'est-à-dire en dehors de l'ensemble d'étiquettes attendu.

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

Ensuite, examinons le rapport de classification complet pour chaque catégorie d'émotions.

pd.DataFrame(pre_report).transpose()

Nous obtenons ainsi la précision, le rappel, le score F1 et le support pour chaque classe. Cela nous aide à voir les émotions bien gérées et celles plus difficiles avant l'affinage.

Enfin, inspectons la matrice de confusion.

confusion_matrix_df(pre_preds)

La matrice de confusion montre comment les prédictions se répartissent entre les différentes classes. 

Dans le notebook, cela s'affiche sous forme de tableau, ce qui facilite l'identification des émotions souvent confondues et des zones où le modèle de base peine le plus.

6. Affiner Gemma 4 avec LoRA

Maintenant que nous avons la baseline, nous pouvons affiner Gemma 4 avec LoRA. 

LoRA est une méthode de fine-tuning efficace en paramètres, ce qui signifie que nous n'actualisons pas tout le modèle. Nous ajoutons plutôt un petit nombre de poids d'adaptateurs entraînables par-dessus le modèle de base. L'entraînement est ainsi bien plus léger et réalisable sur un seul GPU.

Commençons par définir la configuration LoRA.

Ces paramètres contrôlent la façon dont les adaptateurs LoRA sont attachés au modèle. Ici, nous utilisons un rang de 16, un dropout de 0,05 et appliquons LoRA à toutes les couches linéaires : une configuration courante pour un fine-tuning efficace.

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

Ensuite, nous définissons la configuration d'entraînement et mettons en place le trainer.

Cette configuration vise à contenir l'usage mémoire tout en laissant au modèle la place d'apprendre. Nous entraînons sur une époque, utilisons l'accumulation de gradients pour simuler un batch plus grand et activons des options comme le gradient checkpointing et l'optimisation 8 bits pour plus d'efficacité.

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

Nous vérifions maintenant que le modèle de base est prêt et initialisons le trainer. Cette étape attache les adaptateurs LoRA et prépare l'entraînement supervisé avec nos splits d'entraînement et de validation formatés.

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

Avant de démarrer l'entraînement, il est préférable de confirmer que les paramètres LoRA ont bien été attachés.

Ce code compte le nombre de paramètres entraînables et lève une erreur si aucune couche LoRA n'a été ajoutée. 

Après cela, l'entraînement commence. 

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

Dans cette exécution, l'entraînement a pris un peu moins de 9 minutes, et les pertes d'entraînement et de validation ont diminué en continu : un bon signe que le modèle apprend bien du jeu de données.

Une fois l'entraînement terminé, nous pouvons enregistrer localement l'adaptateur et le tokenizer.

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

Enfin, nous pouvons pousser le modèle sur le Hub Hugging Face.

Cela téléverse l'adaptateur affiné et le tokenizer sur le Hub, afin que vous puissiez y accéder partout, les partager ou les charger directement dans un autre notebook ou une application.

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

Vous pouvez maintenant consulter kingabzpro/gemma4-emotion-lora sur Hugging Face et l'essayer. Le dépôt inclut les fichiers du modèle, les instructions d'usage et les résultats du fine-tuning.

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

7. Évaluer le modèle affiné

Maintenant que l'entraînement est terminé, la dernière étape consiste à évaluer le modèle affiné sur le même split de test et à comparer les résultats avec le modèle de base. Cela permet de vérifier si l'affinage LoRA a amélioré la précision de classification des émotions.

Nous commençons par charger le modèle affiné depuis le trainer et exécutons l'évaluation.

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

Nous obtenons ainsi les principales métriques d'évaluation du modèle affiné.

Ces résultats sont clairement meilleurs que la baseline. Après fine-tuning, le modèle atteint 77,25 % de précision et un F1 macro de 0,698. Le nombre de prédictions invalides passe de 33 à 20, ce qui montre que le modèle affiné est non seulement plus précis mais aussi plus constant dans le renvoi d'étiquettes valides.

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

Ensuite, affichons le rapport de classification complet.

Celui-ci s'affiche dans le notebook sous forme de pandas DataFrame. Il comprend la précision, le rappel, le score F1 et le support pour chaque émotion, ce qui facilite l'analyse des catégories qui ont le plus progressé après fine-tuning.

pd.DataFrame(post_report).transpose()

Cette vue s'affiche également dans le notebook sous forme de tableau. Elle aide à identifier les erreurs restantes et les émotions encore fréquemment confondues.

confusion_matrix_df(post_preds)

Pour rendre la comparaison plus lisible, plaçons côte à côté les métriques avant et après fine-tuning.

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

Vous obtenez un récapitulatif rapide des progrès du modèle après entraînement.

Remarque : en cas de problème lors de l'exécution du code, vous pouvez consulter le notebook Jupyter complet ici : fine-tune-gemma-4-on-emotions_final.ipynb

Conclusion

Le fine-tuning de Gemma 4 est très sensible à la configuration, notamment la structure du prompt et les paramètres d'entraînement. Si le format du prompt est incorrect ou si vous n'utilisez pas systématiquement le bon template, le modèle peut s'entraîner sans vraiment apprendre la tâche. Même constat pour les paramètres d'entraînement : ce sont généralement les raisons pour lesquelles la loss ne diminue pas, ou diminue sans améliorer sensiblement l'évaluation.

Autre point crucial : max_length. Si vous le réduisez trop, notamment en dessous d'environ 125, le modèle peut ne pas apprendre correctement le schéma. J'ai rencontré plusieurs problèmes au cours du processus, résolus au fur et à mesure, et la plupart étaient liés à ces deux volets : formatage du prompt et configuration d'entraînement.

Pour aller plus loin, la prochaine étape pertinente serait d'affiner sur le jeu de données complet et d'entraîner au moins 3 époques au lieu d'une seule. Le modèle disposerait ainsi de plus d'exemples et de temps pour s'adapter, ce qui devrait améliorer la précision et les scores F1.