TRL documentation

LoRA sans regret

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LoRA sans regret

Des recherches récentes de l’équipe de Thinking Machines Lab (Schulman et al., 2025) montrent que LoRA peut égaler les performances d’un fine-tuning complet lorsqu’il est correctement configuré, tout en n’utilisant que ~67 % de la puissance de calcul. Ces résultats sont enthousiasmants pour les utilisateurs de TRL, car ils sont faciles à mettre en œuvre et peuvent améliorer les performances du modèle avec des budgets plus restreints.

Ce guide fournit des instructions simples pour reproduire les résultats de l'article de blog dans TRL.

Il est recommandé de lire le billet de blog avant de suivre ce guide, ou de consulter les deux ressources en parallèle pour de meilleurs résultats.

Avantages de LoRA par rapport à l'ajustement fin complet

Tout d'abord, rappelons les avantages de LoRA par rapport à l'ajustement complet.

LoRA ajoute des couches d'adaptateurs au-dessus du modèle de base, qui contient un nombre de paramètres nettement inférieur à celui du modèle de base lui-même. Cette conception réduit les exigences en mémoire GPU et permet un entraînement plus efficace. Comme décrit dans le blog, cette approche était initialement considérée comme impliquant un compromis en termes de performance, bien qu'une configuration soignée puisse surmonter ce compromis et égaler les performances d'un fine-tuning complet.

Exemples avec TRL

Implémentons et entraînons des adaptateurs LoRA dans les scripts TRL, en nous appuyant sur les résultats clés de l’article de blog. Ensuite, nous réexaminerons chaque constat à la lumière des résultats obtenus avec TRL.

Ajustement fin supervisé (SFT)

L'article de blog effectue du SFT sur une gamme de modèles et de jeux de données du Hub, que nous pouvons reproduire dans TRL.

ModèleJeu de données
Llama-3.2-1B-Instructallenai/tulu-3-sft-mixture
Llama-3.2-1B-Instructopen-thoughts/OpenThoughts-114k
Llama-3.1-8B-Instructallenai/tulu-3-sft-mixture
Llama-3.1-8B-Instructopen-thoughts/OpenThoughts-114k
python
jobs
local

Nous pouvons intégrer ces résultats avec l'API Python de TRL de la manière suivante :


from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig

dataset = load_dataset("open-thoughts/OpenThoughts-114k", split="train")

peft_config = LoraConfig(r=256, lora_alpha=16, target_modules="all-linear")

training_args = SFTConfig(
    learning_rate=2e-4,
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    num_train_epochs=1,
    report_to=["trackio"],
)

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-3B-Instruct",
    train_dataset=dataset,
    peft_config=peft_config,
    args=training_args,
)

trainer.train()

Une fois l’entraînement démarré, vous pouvez suivre les progrès dans Trackio, qui journalisera l’URL.

Apprentissage par renforcement (GRPO)

L’article de blogue effectue le GRPO sur une gamme de modèles et de jeux de données du Hub, et nous pouvons à nouveau reproduire les résultats dans TRL.

ModèleJeu de données
Llama-3.1-8B-BaseGSM8k
Llama-3.1-8B-BaseDeepMath-103K
Qwen3-8b-baseDeepMath-103K

Pour l'apprentissage par renforcement, le blog utilise une tâche de raisonnement mathématique que nous pouvons reproduire sous forme de fonction Python.

python
jobs
local

Nous pouvons mettre en œuvre ces recommandations avec l’API Python de TRL comme suit :


from datasets import load_dataset
from peft import LoraConfig
from trl import GRPOConfig, GRPOTrainer
from trl.rewards import reasoning_accuracy_reward

dataset = load_dataset("HuggingFaceH4/OpenR1-Math-220k-default-verified", split="train")

peft_config = LoraConfig(
    r=1,
    lora_alpha=32,
    target_modules="all-linear"
)

training_args = GRPOConfig(
    learning_rate=5e-5,
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    num_train_epochs=1,
    num_generations=8,
    generation_batch_size=8,
    report_to=["trackio"],
)

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    reward_funcs=reasoning_accuracy_reward,
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,
)

trainer.train()

Cet extrait omet la fonction de récompense, définie plus haut, afin de garder l’exemple concis.

Le script d'apprentissage par renforcement avec GRPO est implémenté sous forme de script personnalisé dans TRL, qui utilise la fonction de récompense présentée ci-dessus. Vous pouvez le consulter dans grpo.py - Bonnes pratiques pour l'apprentissage par renforcement avec LoRA

Principales conclusions de l’optimisation de LoRA

Les auteurs recommandent d'appliquer LoRA à toutes les matrices de poids plutôt que de le limiter aux couches d'attention, car l'augmentation du rang ne compense pas cette restriction. Dans TRL, cela peut être configuré en utilisant --lora_target_modules all-linear pour appliquer LoRA à toutes les matrices de poids.

Nous avons pu reproduire les résultats de l’article de blog en utilisant TRL et le modèle SmolLM3. Nous avons entraîné le modèle pendant 500 étapes sur le jeu de données Math 220k avec la fonction de récompense et la configuration ci-dessus. Comme vous pouvez le voir sur la figure ci-dessous, la courbe de récompense moyenne d’entraînement du modèle LoRA correspond à la courbe de l’ajustement fin complet.

train reward

Et surtout, le modèle LoRA utilise nettement moins de mémoire que le modèle de fine-tuning complet, comme nous pouvons le voir sur la figure ci-dessous.

memory usage

Voici les paramètres que nous avons utilisés pour entraîner les modèles ci-dessus

ParamètreLoRAFT complet
--model_name_or_pathHuggingFaceTB/SmolLM3-3BHuggingFaceTB/SmolLM3-3B
--dataset_nameHuggingFaceH4/OpenR1-Math-220k-default-verifiedHuggingFaceH4/OpenR1-Math-220k-default-verified
--learning_rate1.0e-51.0e-6
--max_completion_length40964096
--lora_r1-
--lora_alpha32-
--lora_dropout0.0-
--lora_target_modulesall-linear-

Décomposons les résultats clés de l’article de blog et la manière dont nous avons pu les reproduire.

1. LoRA offre de meilleures performances lorsqu'il est appliqué à toutes les matrices de poids

Les auteurs recommandent d'appliquer LoRA à toutes les matrices de poids plutôt que de le limiter aux couches d'attention, car l'augmentation du rang ne compense pas cette restriction.

all layers

LoRA appliqué uniquement aux couches d'attention donne des performances inférieures, même en utilisant un rang plus élevé pour correspondre au nombre de paramètres. Dans TRL, cela peut être configuré en utilisant --lora_target_modules all-linear pour appliquer LoRA à toutes les matrices de poids. En Python, nous pouvons le faire ainsi :

from peft import LoraConfig  

peft_config = LoraConfig(target_modules="all-linear")  

2. L'adaptateur doit disposer d'une capacité suffisante pour apprendre à partir du jeu de données

L’article de blog recommande d’utiliser un rang LoRA suffisant pour apprendre à partir du jeu de données. Le rang détermine le nombre de paramètres entraînables dans l’adaptateur LoRA. Par conséquent, « pour les jeux de données qui dépassent la capacité de LoRA, LoRA sous-performe par rapport à FullFT ».

learning rate

Dans le script TRL, nous pouvons utiliser --lora_r pour définir le rang et l’adapter en fonction de la tâche et du jeu de données sur lequel nous entraînons. L’article de blog recommande les rangs suivants en fonction de la tâche et de la taille du jeu de données :

Les tâches d'apprentissage par renforcement nécessitent généralement une capacité moindre, ce qui permet d'utiliser des rangs LoRA plus petits. En effet, les algorithmes de gradient de politique extraient environ ~1 bit d'information par épisode, ce qui exige une capacité paramétrique minimale.

L’article de blog définit la taille idéale du jeu de données pour LoRA afin d’égaler le fine-tuning complet comme « Post-training scale ». Nous pouvons l’utiliser pour déterminer le rang recommandé pour les LoRA de SFT et de RL comme suit :

Type de tâcheTaille du jeu de donnéesRang recommandé
SFTÉchelle du post-entraînement256
RLToutes tailles1-32

3. « FullFT et les LoRAs de rang élevé présentent des courbes d'apprentissage similaires »

Contre-intuitivement, l'article de blog recommande d'utiliser un taux d'apprentissage plus élevé que pour l'ajustement complet. Dans le tableau ci-dessus, nous avons utilisé 1.0e-5 pour LoRA et 1.0e-6 pour l'ajustement complet. Dans le script TRL, nous pourrions utiliser --learning_rate pour définir le taux d'apprentissage. Le 1r \frac{1}{r} mise à l'échelle dans LoRA rend le taux d'apprentissage optimal approximativement indépendant du rang.

learning rate

4. « Dans certains scénarios, LoRA est moins tolérant aux grandes tailles de lot que le fine-tuning complet. »

L’article de blog recommande d’utiliser une taille de lot effective < 32, car les auteurs ont constaté que LoRA est moins tolérant aux grandes tailles de lot. Ce problème ne pouvait pas être atténué en augmentant le rang de LoRA. Dans le script TRL, nous pouvons utiliser --per_device_train_batch_size et --gradient_accumulation_steps pour définir la taille de lot.

learning rate

À retenir

Avec TRL, vous pouvez implémenter efficacement des adaptateurs LoRA pour égaler les performances d'un fine-tuning complet, en appliquant les principes clés (cibler toutes les matrices de poids, choisir le bon rang, et gérer la taille du lot et le taux d'apprentissage) sans le coût de calcul élevé du FullFT.

Citation

@article{schulman2025lora,  
    title        = {{LoRA Without Regret}},  
    author       = {John Schulman and Thinking Machines Lab},  
    year         = 2025,  
    journal      = {Thinking Machines Lab: Connectionism},  
    doi          = {10.64434/tml.20250929},  
    note         = {https://thinkingmachines.ai/blog/lora/}  
}  
Update on GitHub