# LoRA sans regret

Des recherches récentes de l’équipe de [Thinking Machines Lab](https://thinkingmachines.ai/blog/lora/) (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.

> [!TIP]
> 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](https://huggingface.co/docs/trl/en/peft_integration).

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](https://thinkingmachines.ai/blog/lora/), 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 résultat à 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èle | Jeu de données |
| --- | --- |
| [Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B) | [allenai/tulu-3-sft-mixture](https://huggingface.co/datasets/allenai/tulu-3-sft-mixture) |
| [Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B) | [open-thoughts/OpenThoughts-114k](https://huggingface.co/datasets/open-thoughts/OpenThoughts-114k) |
| [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Llama-3.1-8B) | [allenai/tulu-3-sft-mixture](https://huggingface.co/datasets/allenai/tulu-3-sft-mixture) |
| [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Llama-3.1-8B) | [open-thoughts/OpenThoughts-114k](https://huggingface.co/datasets/open-thoughts/OpenThoughts-114k) |

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

```python

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

```

```bash

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](https://huggingface.co/settings/billing) positif. Consultez la [documentation des Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) pour plus de détails.

```bash

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](https://docs.astral.sh/uv/) pour plus de détails.

Une fois l’entraînement démarré, vous pouvez suivre les progrès dans [Trackio](https://huggingface.co/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](https://huggingface.co/meta-llama/Llama-3.2-1B) | [GSM8k](https://huggingface.co/datasets/openai/gsm8k) |
| [Llama-3.1-8B-Base](https://huggingface.co/meta-llama/Llama-3.2-1B) | [DeepMath-103K](https://huggingface.co/datasets/zwhe99/DeepMath-103K) |
| [Qwen3-8b-base](https://huggingface.co/Qwen/Qwen3-8b-base) | [DeepMath-103K](https://huggingface.co/datasets/zwhe99/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 :

```python

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

```

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

```bash

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 trackio
```

Pour utiliser Hugging Face Jobs, connectez-vous au Hub (`hf auth login`) et disposez d'un [solde de crédits](https://huggingface.co/settings/billing) positif. Consultez la [documentation des Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) pour plus de détails.

```bash
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 trackio
```

Pour exécuter le script localement, vous devez avoir `uv` installé. Consultez la [documentation de uv](https://docs.astral.sh/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`](https://huggingface.co/datasets/burtenshaw/lora-without-regrets/blob/main/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](https://huggingface.co/datasets/HuggingFaceH4/OpenR1-Math-220k-default-verified) 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](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/5.png)

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](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/6.png)

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.

![all layers](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/1.png)

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 :

```python
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](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/3.png)

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 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 pouvons utiliser `--learning_rate` pour définir le taux d’apprentissage. L’échelle \\( \frac{1}{r} \\) dans LoRA rend le taux d’apprentissage optimal approximativement indépendant du rang.

![learning rate](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/2.png)

### 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](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/4.png)

## À 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

```bibtex
@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/}  
}  
```

