TRL documentation
LoRA sans regret
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.
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()
hf jobs uv run \
--flavor a100-large \
--timeout 8h \
--secrets HF_TOKEN \
"https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
--model_name_or_path Qwen/Qwen2.5-3B-Instruct \
--dataset_name open-thoughts/OpenThoughts-114k \
--learning_rate 2.0e-5 \
--num_train_epochs 1 \
--packing \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 16 \
--use_peft \
--lora_r 256 \
--lora_alpha 16 \
--lora_target_modules all-linear \
--output_dir Qwen2.5-3B-OpenThoughts-LoRA \
--report_to trackio \
--push_to_hub
Pour utiliser Hugging Face Jobs, connectez-vous au Hub (hf auth login) et disposez d'un solde de crédits positif. Consultez la documentation des Jobs pour plus de détails.
uv run "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
--model_name_or_path Qwen/Qwen2.5-3B-Instruct \
--dataset_name open-thoughts/OpenThoughts-114k \
--learning_rate 2.0e-5 \
--num_train_epochs 1 \
--packing \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 16 \
--eval_strategy no \
--use_peft \
--lora_r 256 \
--lora_alpha 16 \
--lora_target_modules all-linear \
--output_dir Qwen2.5-3B-OpenThoughts-LoRA \
--report_to trackio \
--push_to_hub
Pour exécuter le script localement, vous devez avoir uv installé. Consultez la documentation de uv pour plus de détails.
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èle | Jeu de données |
|---|---|
| Llama-3.1-8B-Base | GSM8k |
| Llama-3.1-8B-Base | DeepMath-103K |
| Qwen3-8b-base | DeepMath-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.
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.
hf jobs uv run \
--flavor a100-large \
--timeout 4h \
--secrets HF_TOKEN \
--env PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True \
"https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
--model_name_or_path Qwen/Qwen3-0.6B \
--dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
--output_dir grpo-full-qwen3-0.6b \
--learning_rate 1.0e-6 \
--lr_scheduler_type cosine \
--warmup_steps 0.0 \
--max_grad_norm 1.0 \
--beta 0.0 \
--max_completion_length 4096 \
--num_generations 16 \
--generation_batch_size 16 \
--gradient_accumulation_steps 8 \
--per_device_train_batch_size 1 \
--num_train_epochs 1 \
--lora_r 1 \
--lora_alpha 32 \
--lora_dropout 0.0 \
--lora_target_modules all-linear \
--vllm_mode colocate \
--save_strategy steps \
--save_steps 50 \
--save_total_limit 1 \
--logging_steps 1 \
--max_steps 200 \
--report_to trackioPour utiliser Hugging Face Jobs, connectez-vous au Hub (hf auth login) et disposez d'un solde de crédits positif. Consultez la documentation des Jobs pour plus de détails.
uv run "https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
--model_name_or_path Qwen/Qwen3-0.6B \
--dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
--output_dir grpo-full-qwen3-0.6b \
--learning_rate 1.0e-6 \
--lr_scheduler_type cosine \
--warmup_steps 0.0 \
--max_grad_norm 1.0 \
--beta 0.0 \
--max_completion_length 4096 \
--num_generations 16 \
--generation_batch_size 16 \
--gradient_accumulation_steps 8 \
--per_device_train_batch_size 1 \
--num_train_epochs 1 \
--lora_r 1 \
--lora_alpha 32 \
--lora_dropout 0.0 \
--lora_target_modules all-linear \
--vllm_mode colocate \
--save_strategy steps \
--save_steps 50 \
--save_total_limit 1 \
--logging_steps 1 \
--max_steps 200 \
--report_to trackioPour exécuter le script localement, vous devez avoir uv installé. Consultez la documentation de uv pour plus de détails.
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.

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.

Voici les paramètres que nous avons utilisés pour entraîner les modèles ci-dessus
| Paramètre | LoRA | FT complet |
|---|---|---|
--model_name_or_path | HuggingFaceTB/SmolLM3-3B | HuggingFaceTB/SmolLM3-3B |
--dataset_name | HuggingFaceH4/OpenR1-Math-220k-default-verified | HuggingFaceH4/OpenR1-Math-220k-default-verified |
--learning_rate | 1.0e-5 | 1.0e-6 |
--max_completion_length | 4096 | 4096 |
--lora_r | 1 | - |
--lora_alpha | 32 | - |
--lora_dropout | 0.0 | - |
--lora_target_modules | all-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.

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

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âche | Taille du jeu de données | Rang recommandé |
|---|---|---|
| SFT | Échelle du post-entraînement | 256 |
| RL | Toutes tailles | 1-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 mise à l'échelle dans LoRA rend le taux d'apprentissage optimal approximativement indépendant du rang.

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.

À 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/}
}