Guide de fine-tuning de Gemma 4 | Documentation Unsloth

Guide de fine-tuning Gemma 4 | Documentation Unsloth

Le fine-tuning d’un modèle de langage ouvert n’est plus une activité réservée à la recherche ; c’est une étape standard dans de nombreuses pipelines de production. Un modèle de base sait générer un texte fluide, mais il ne connaît pas votre format de données, votre vocabulaire métier, ni le ton de votre produit. C’est là que le fine-tuning intervient. Avec la famille Gemma 4 de Google et la pile d’entraînement optimisée d’Unsloth, l’écart entre « modèle pré-entraîné » et « assistant déployable » se réduit à une seule exécution d’entraînement, rapide.

Ce guide est un parcours pratique du flux de travail de fine-tuning Gemma 4 tel que décrit dans la documentation Unsloth. Il couvre l’environnement nécessaire, les étapes d’installation, la préparation du jeu de données, la configuration LoRA, l’entraînement, et enfin l’exécution et l’exportation de votre modèle fine-tuné. La page de documentation sur laquelle se base ce guide a été mise à jour le 2026-07-18T14:46:20.453Z, donc les instructions ci-dessous reflètent l’état actuel de la chaîne d’outils Unsloth.

Ce que ce guide suppose

Unsloth repose sur une proposition simple : le fine-tuning doit être rapide, utiliser le moins de VRAM possible, et ne pas vous obliger à réécrire votre boucle d’entraînement. Il y parvient grâce à un ensemble de noyaux optimisés pour les couches d’attention et les couches linéaires, une gestion automatique de la quantification, et une intégration étroite avec les piles d’entraînement Transformers et TRL de Hugging Face.

Gemma 4, de Google, est la famille de modèles ouverts pour laquelle ce flux de travail est conçu. Selon la taille de la variante que vous choisissez, vous aurez besoin de plus ou moins de mémoire GPU, mais le code d’entraînement reste presque identique.

Vous devez être à l’aise avec Python, avoir une compréhension de base de ce que sont LoRA et QLoRA, et savoir utiliser un terminal. Vous n’avez pas besoin d’être ingénieur en apprentissage automatique — vous avez besoin d’un GPU et de la volonté de suivre quelques commandes.

Prérequis

Avant d’exécuter quoi que ce soit, assurez-vous que votre environnement répond aux exigences minimales.

Matériel

• Un GPU NVIDIA avec prise en charge de CUDA. Les accélérations d’Unsloth proviennent de noyaux personnalisés qui ciblent les architectures GPU modernes. Un GPU de la génération Turing (série RTX 20) ou plus récente est donc recommandé. Les architectures Ampere, Ada Lovelace et Hopper donneront les meilleurs résultats.
• Une VRAM suffisante. La quantité exacte dépend de la variante Gemma 4 que vous souhaitez fine-tuner et du niveau de quantification utilisé. Avec QLoRA en 4 bits, vous pouvez fine-tuner un modèle Gemma 4 plus petit sur du matériel grand public avec 8 à 16 Go de VRAM. Les variantes plus grandes nécessitent une station de travail ou un GPU cloud avec 24 Go ou plus.
• Suffisamment de RAM système et d’espace disque pour contenir les poids du modèle, le jeu de données d’entraînement et les points de contrôle que vous enregistrez.

Logiciels

• Une distribution Linux 64 bits ou le sous-système Windows pour Linux (WSL2). La plupart des instructions supposent un shell de type Unix.
• Python 3.9 ou plus récent.
• Le kit d’outils CUDA et les pilotes NVIDIA. La version exacte nécessaire dépend de la version de PyTorch que vous installez ; le site officiel de PyTorch et la documentation Unsloth listent les combinaisons compatibles.
• Une version récente de PyTorch. Unsloth suit de près les versions de PyTorch, et installer une version récente vous évitera des problèmes d’incompatibilité de version.

Si vous utilisez Google Colab, vous êtes en grande partie couvert : Colab est fourni avec des versions récentes de PyTorch et CUDA, et Unsloth propose un chemin d’installation spécifique pour les environnements Colab.

Installation étape par étape

Le processus d’installation d’Unsloth est volontairement court. La bibliothèque est distribuée comme un paquet Python, et le moyen le plus simple de l’obtenir est via pip.

Ouvrez un terminal et installez le paquet principal :

pip install unsloth

Cela installe le paquet Unsloth principal ainsi que ses dépendances, y compris transformers, datasets, trl, peft et accelerate. Si votre environnement possède déjà une version spécifique de PyTorch et que vous souhaitez empêcher Unsloth de la remplacer, vous pouvez ignorer la résolution des dépendances et n’installer que la bibliothèque elle-même :

pip install --no-deps unsloth

Sur Google Colab, le chemin recommandé est d’installer l’extension colab-new, qui résout automatiquement les versions de dépendances spécifiques à l’environnement :

pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"

Pour une installation de pointe directement depuis le dépôt, vous pouvez utiliser la même commande avec l’extension colab-new sur n’importe quelle machine Linux :

pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"

Une fois l’installation terminée, vérifiez que la bibliothèque s’importe correctement et que la version semble cohérente :

python -c "import unsloth; print(unsloth.__version__)"

Vous devriez voir une chaîne de version s’afficher sans avertissement concernant des extensions CUDA manquantes. Si vous recevez une erreur mentionnant un runtime CUDA manquant, vérifiez votre installation PyTorch et la version de votre pilote CUDA avant de continuer.

Certains utilisateurs préfèrent également installer d’abord une version spécifique de PyTorch, puis ajouter Unsloth par-dessus. C’est une bonne approche si votre projet est épinglé à une version particulière de transformers :

pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install unsloth

N’oubliez pas : installez PyTorch d’abord, puis Unsloth, et laissez Unsloth aligner le reste de la pile d’entraînement.

Chargement de Gemma 4 avec Unsloth

Toute l’API d’Unsloth est centrée sur deux fonctions : FastLanguageModel.from_pretrained et FastLanguageModel.get_peft_model. La première charge un modèle et applique des optimisations et la quantification ; la seconde transforme le modèle chargé en un modèle LoRA entraînable et efficace en paramètres.

Le bloc de chargement standard ressemble à ceci :

import torch
from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/gemma-4-...",  # pick the Gemma 4 variant you need
    max_seq_length=2048,
    dtype=None,
    load_in_4bit=True,
)

Trois arguments méritent une attention particulière :

• model_name — c’est l’identifiant Hugging Face du point de contrôle Gemma 4 que vous souhaitez fine-tuner. L’identifiant exact dépend de la taille du modèle et de savoir si vous voulez le modèle de base ou une version instruite. Unsloth héberge des variantes pré-quantifiées et optimisées de ces modèles sur son hub Hugging Face, et ce sont celles-là que vous devez utiliser pour bénéficier des améliorations de vitesse.
• max_seq_length — définit la fenêtre de contexte pour l’entraînement. La famille Gemma 4 prend en charge de longs contextes, mais vous devez définir cette valeur en fonction de vos données réelles. Une valeur de 2048 convient à la plupart des jeux de données de chat, tandis que des tâches sur documents plus longs peuvent nécessiter 4096 ou plus. Gardez à l’esprit que l’utilisation mémoire augmente avec la longueur de séquence.
• load_in_4bit — active la quantification de type QLoRA. Cela réduit considérablement l’empreinte VRAM du modèle, vous permettant de fine-tuner sur des GPU grand public qui seraient autrement trop petits. Si vous disposez d’un GPU haut de gamme avec beaucoup de mémoire, vous pouvez définir cette option sur False et fine-tuner en précision complète ou en 8 bits.

La variable dtype peut être laissée à None, ce qui permet à Unsloth de choisir le type flottant optimal en fonction de votre matériel. Sur les GPU Ampere et plus récents, ce sera généralement bfloat16, qui est plus stable que float16 pendant l’entraînement.

Préparation de votre jeu de données

Unsloth ne vous force pas à utiliser un format de jeu de données unique. Si vous avez déjà utilisé la bibliothèque datasets de Hugging Face ou le SFTTrainer de TRL, vous savez déjà comment fournir des données. Le format le plus courant pour le fine-tuning de chat est une structure de type conversation, où chaque conversation est une liste de messages avec des champs role et content.

Par exemple, le format populaire de type ShareGPT ressemble à ceci :

{
    "conversations": [
        {"from": "human", "value": "Explain what a vector database is."},
        {"from": "gpt", "value": "A vector database stores embeddings..."}
    ]
}

Vous pouvez charger un tel jeu de données avec la bibliothèque datasets de Hugging Face :

from datasets import load_dataset

dataset = load_dataset("json", data_files="my_data.json", split="train")

Si vos données sont en texte brut, vous pouvez définir un modèle de chat simple et reformater votre jeu de données directement :

def format_chat(example):
    text = ""
    for turn in example["conversations"]:
        if turn["from"] == "human":
            text += f"<|user|>\n{turn['value']}\n"
        elif turn["from"] == "gpt":
            text += f"<|assistant|>\n{turn['value']}\n"
    return {"text": text}

dataset = dataset.map(format_chat, remove_columns=dataset.column_names)

Le SFTTrainer que nous utiliserons plus tard accepte un argument dataset_text_field et gère le reste. L’important est que votre jeu de données contienne un champ texte représentant la conversation entièrement formatée, y compris les jetons spéciaux qui séparent les rôles.

Configuration des adaptateurs LoRA

Le modèle chargé et le jeu de données préparé, l’étape suivante consiste à configurer la configuration de fine-tuning efficace en paramètres. Unsloth expose une fine couche d’abstraction autour de PEFT qui rend cela simple :

model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    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",
    random_state=3407,
)

Les hyperparamètres clés sont :

• r — le rang des matrices LoRA. Un rang de 16 est une bonne valeur par défaut pour la plupart des tâches. Des valeurs plus grandes augmentent l’expressivité mais utilisent aussi plus de VRAM pendant l’entraînement.
• lora_alpha — le facteur d’échelle pour les poids LoRA. Le maintenir égal au rang est un point de départ courant.
• lora_dropout — défini sur 0 car les noyaux Unsloth et les optimiseurs fusionnés ajoutent déjà leur propre régularisation pendant l’entraînement ; le dropout sur les couches d’adaptation est rarement nécessaire.
• target_modules — les couches de projection sur lesquelles les adaptateurs LoRA sont attachés. Couvrir les quatre projections d’attention plus les projections MLP est standard pour les modèles de classe Gemma.
• use_gradient_checkpointing="unsloth" — active l’implémentation de checkpointing de gradient économe en mémoire d’Unsloth. C’est l’une des raisons pour lesquelles vous pouvez entraîner des modèles plus grands sur des GPU plus petits.

Entraînement avec le SFT Trainer

Maintenant que le jeu de données et le modèle sont prêts, nous entraînons. Unsloth fonctionne directement avec trl.SFTTrainer, vous bénéficiez donc de toute la puissance de l’écosystème d’entraînement Hugging Face sans apprendre une nouvelle API.

from trl import SFTTrainer
from transformers import TrainingArguments

training_args = TrainingArguments(
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    warmup_steps=5,
    max_steps=60,
    learning_rate=2e-4,
    fp16=True,
    logging_steps=1,
    output_dir="gemma4-finetuned",
    optim="adamw_8bit",
    seed=3407,
)

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    args=training_args,
)

Notez le choix de optim="adamw_8bit", qui réduit la mémoire de l’état de l’optimiseur. Combiné à la quantification en 4 bits et au checkpointing de gradient, c’est ce qui permet à un GPU grand public modeste de fine-tuner un modèle Gemma 4.

Lancez l’exécution d’entraînement :

trainer.train()

Pendant l’entraînement, vous verrez la perte diminuer dans les journaux. Si vous rencontrez une erreur CUDA de mémoire insuffisante, réduisez per_device_train_batch_size à 1 ou 2 et augmentez gradient_accumulation_steps pour compenser. Une petite taille de lot avec accumulation produit presque le même résultat qu’un grand lot tout en utilisant beaucoup moins de mémoire.

Pour la plupart des jeux de données de petite et moyenne taille, quelques centaines d’étapes suffisent. Vous n’avez pas besoin d’entraîner pendant de nombreuses époques ; LoRA converge rapidement, et il est facile de surentraîner un petit adaptateur sur un petit jeu de données.

Sauvegarde et rechargement de votre modèle

Une fois l’entraînement terminé, vous avez deux options : sauvegarder uniquement les poids de l’adaptateur, ou fusionner l’adaptateur dans le modèle complet et l’exporter vers un format standard.

L’option la plus simple est de sauvegarder uniquement l’adaptateur LoRA :

model.save_pretrained("gemma4-lora")
tokenizer.save_pretrained("gemma4-lora")

Cela vous donne un petit ensemble de fichiers, généralement quelques dizaines de mégaoctets, contenant uniquement les adaptateurs entraînés. Pour réutiliser le modèle fine-tuné, rechargez le modèle Gemma 4 de base avec Unsloth, puis chargez l’adaptateur par-dessus :

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/gemma-4-...",
    max_seq_length=2048,
    load_in_4bit=True,
)

from peft import PeftModel

model = PeftModel.from_pretrained(model, "gemma4-lora")

Si vous voulez un modèle entièrement fusionné qui puisse fonctionner sans Unsloth ni PEFT, vous pouvez fusionner l’adaptateur dans les poids de base :

model = model.merge_and_unload()
model.save_pretrained("gemma4-merged")
tokenizer.save_pretrained("gemma4-merged")

Le répertoire résultant contient un point de contrôle Transformers standard qui peut être chargé comme n’importe quel autre modèle.

Exemples d’utilisation

Exécution d’inférence

Après le fine-tuning, passez le modèle en mode inférence avec une simple fonction d’aide Unsloth :

model = FastLanguageModel.for_inference(model)

Puis transmettez votre invite avec le même format de chat que celui utilisé pendant l’entraînement :

messages = [
    {"role": "user", "content": "Write a support response for a user whose order is delayed."},
]
inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
).to("cuda")

outputs = model.generate(input_ids=inputs, max_new_tokens=512)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

La sortie doit refléter le style, le format et les connaissances que vous avez entraînés dans le modèle — c’est tout l’intérêt de l’exercice.

Exportation vers GGUF pour un déploiement local

L’une des tâches post-entraînement les plus courantes est d’exporter le modèle fine-tuné vers GGUF afin de l’utiliser avec des outils comme llama.cpp ou Ollama. Unsloth fournit une commande unique pour cela :

model.save_pretrained_gguf(
    "gemma4-gguf",
    tokenizer,
    quantization_method="q8_0",
)

Vous pouvez choisir d’autres méthodes de quantification comme f16, q4_k_m ou q5_k_m. La méthode q8_0 préserve l’essentiel de la qualité du modèle tout en produisant un fichier de taille raisonnable qui fonctionne bien sur des hôtes CPU.

Bonnes pratiques et résolution de problèmes

Les deux problèmes les plus courants pendant une exécution de fine-tuning sont les erreurs de mémoire insuffisante et un entraînement lent. Voici comment Unsloth aborde ces deux points :

• Utilisez la quantification en 4 bits. Si load_in_4bit=True n’est pas défini, définissez-le. Cela peut à lui seul réduire l’utilisation de la VRAM jusqu’à trois quarts.
• Activez `use_gradient_checkpointing="unsloth"`. Cela échange une petite quantité de temps d’entraînement contre une grande réduction de mémoire.
• Utilisez l’optimiseur AdamW 8 bits. L’état de l’optimiseur est souvent le consommateur de mémoire caché ; l’état en 8 bits le réduit considérablement.
• Réduisez la fenêtre de contexte. Si votre tâche ne nécessite pas de longs documents, gardez max_seq_length modeste.
• Augmentez l’accumulation de gradient plutôt que la taille de lot. Une taille de lot de 1 avec un nombre d’accumulations élevé est plus sûre qu’un grand lot qui pourrait ne pas tenir en mémoire.

Du côté de la vitesse, assurez-vous de charger les points de contrôle hébergés par Unsloth plutôt que les points de contrôle Google d’origine. Les versions Unsloth disposent d’optimisations précalculées et de poids quantifiés conçus pour fonctionner avec les noyaux rapides de la bibliothèque. Charger un point de contrôle standard depuis le Hub fonctionnera, mais vous perdrez la plus grande partie de l’avantage de performance.

Conclusion

La documentation Unsloth pour Gemma 4 décrit un flux de travail court, reproductible et facile à adapter à différentes tailles de modèles et jeux de données. Installez la bibliothèque, chargez un modèle Gemma 4 quantifié, attachez un adaptateur LoRA, entraînez avec le SFT trainer, et sauvegardez le résultat — c’est tout le cycle. Ce qui compte plus que le code, c’est la discipline qui l’accompagne : préparer un jeu de données propre avec un formatage cohérent, choisir un rang LoRA adapté à la complexité de votre tâche, garder des longueurs de séquence honnêtes, et résister à l’envie de surentraîner.

Le modèle fine-tuné que vous obtiendrez ne sera pas simplement une copie de Gemma 4 avec un nouveau texte. Ce sera une version du modèle qui connaît votre format spécifique, votre domaine spécifique et vos contraintes spécifiques. Et, avec la boucle d’entraînement économe en mémoire d’Unsloth, vous pouvez y arriver sur du matériel que la plupart des équipes possèdent déjà. Que vous construisiez un assistant de support client, un outil d’aide à la génération de code ou un résumeur de documents interne, ce guide vous donne le chemin documenté qui va du modèle de base au fine-tune déployable.