# Exemples

Le répertoire [`examples/`](https://github.com/huggingface/trl/tree/main/examples) contient une collection d’exemples autonomes qui illustrent l’utilisation de la bibliothèque TRL pour diverses applications. **Chaque exemple est situé dans son propre dossier** nommé d’après la méthode et la tâche qu’il démontre (par exemple `grpo_wordle`, `sft_gpt_oss_chess`), et regroupe tout ce dont l’exemple a besoin : scripts, notebooks, prompts, modèles de chat et code d’évaluation.

Les scripts d’entraînement de base à un seul formateur ne sont pas des exemples : ils se trouvent dans [`trl/scripts`](https://github.com/huggingface/trl/tree/main/trl/scripts) et sont exposés via l’[interface en ligne de commande](clis) (`trl sft`, `trl dpo`, `trl grpo`, …). La page de documentation de chaque formateur contient également un extrait de code complet et exécutable.

Les ressources partagées se trouvent à la racine de `examples/` :

- [`examples/deepspeed_configs`](https://github.com/huggingface/trl/tree/main/examples/deepspeed_configs) : fichiers de configuration DeepSpeed ZeRO, passés avec `--deepspeed`, utilisés par de nombreux exemples.
- [`examples/fsdp_configs`](https://github.com/huggingface/trl/tree/main/examples/fsdp_configs) : fichiers de configuration FSDP, passés avec `--fsdp --fsdp_config` (un simple `--fsdp` sur la ligne de commande nécessite transformers 5.10 ou une version ultérieure ; avec des versions antérieures, définissez `fsdp=True` dans la configuration d’entraînement).
- [`examples/datasets`](https://github.com/huggingface/trl/tree/main/examples/datasets) : les scripts utilisés pour générer les jeux de données `trl-lib` utilisés dans les exemples.

**Commencer**

Installez TRL et les dépendances supplémentaires comme suit :

```bash
pip install --upgrade trl[quantization]
```

Vérifiez les dépendances optionnelles supplémentaires [ici](https://github.com/huggingface/trl/blob/main/pyproject.toml). Les exemples basés sur des notebooks sont autonomes et peuvent s’exécuter sur **Colab gratuit** ; les exemples basés sur des scripts s’exécutent sur des configurations mono-GPU, multi-GPU ou DeepSpeed (voir [Entraînement distribué](#distributed-training) ci-dessous).

## Index

| Exemple | Description | Ouvrir dans Colab |
| --- | --- | --- |
| [`async_distillation_math`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_math) | Distillation asynchrone on-policy sur GSM8K avec [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/fr/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) : l'enseignant est servi via HTTP avec vLLM. | |
| [`async_distillation_mopd`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_mopd) | Distillation sur politique multi-enseignants (MOPD) avec [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/fr/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) : fusionne les experts mathématiques, code et suivi d'instructions d'Open-MOPD dans leur point de contrôle SFT : de 17,5 à 24,2 sur AIME24 et de 67,5 à 73,0 sur IFEval en 60 étapes (script, lanceur Hugging Face Jobs et README avec les résultats). | |
| [`async_grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_harbor) | Entraînement AsyncGRPO sur une suite de tâches [Harbor](https://huggingface.co/docs/openenv/environments/harbor) via n'importe quel agent de codage installé (`mini-swe-agent`, `opencode`, `claude-code`, ...) servi par [OpenEnv](openenv) : l'agent gère sa propre boucle dans un bac à sable et TRL s'entraîne sur les identifiants de jetons et les logprobs enregistrés par le proxy de capture. | |
| [`async_grpo_math`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_math) | GRPO asynchrone sur GSM8K avec [AsyncGRPOTrainer](/docs/trl/main/fr/async_grpo_trainer#trl.AsyncGRPOTrainer), découplant la génération (serveur vLLM) de l’entraînement, y compris une variante LoRA qui ne synchronise que l’adaptateur avec le serveur vLLM. | |
| [`dpo_reduce_hallucinations`](https://github.com/huggingface/trl/tree/main/examples/dpo_reduce_hallucinations) | Ajustement fin DPO d'un modèle Vision Language pour réduire les hallucinations à l'aide du jeu de données [openbmb/RLAIF-V-Dataset](https://huggingface.co/datasets/openbmb/RLAIF-V-Dataset). | |
| [`gold_chatbot_arena`](https://github.com/huggingface/trl/tree/main/examples/gold_chatbot_arena) | Distillation de logit en ligne générale (GOLD) d’un enseignant Qwen2 vers un élève Llama 3.2 (tokeniseurs croisés) sur chatbot_arena_completions avec [experimental.gold.GOLDTrainer](/docs/trl/main/fr/gold_trainer#trl.experimental.gold.GOLDTrainer), avec des variantes d’entraînement complet et LoRA. | |
| [`gold_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/gold_qwen3_vl) | Distillation en ligne générale des logits (GOLD) de Qwen3-VL-8B vers des étudiants VLM plus petits à l'aide de [experimental.gold.GOLDTrainer](/docs/trl/main/fr/gold_trainer#trl.experimental.gold.GOLDTrainer), couvrant la distillation intra-famille (perte JSD) et inter-famille (perte ULD). | |
| [`grpo_2048`](https://github.com/huggingface/trl/tree/main/examples/grpo_2048) | GRPO avec l'appel d'outils pour apprendre à un modèle à jouer au jeu 2048. | |
| [`grpo_browsergym`](https://github.com/huggingface/trl/tree/main/examples/grpo_browsergym) | GRPO avec l'environnement [OpenEnv](openenv) de BrowserGym, avec des variantes LLM et VLM. | |
| [`grpo_carla`](https://github.com/huggingface/trl/tree/main/examples/grpo_carla) | GRPO avec l'environnement de conduite autonome CARLA [OpenEnv](openenv), avec des variantes LLM et VLM (réponses d'outils multimodales à partir d'images de caméra). | |
| [`grpo_catch`](https://github.com/huggingface/trl/tree/main/examples/grpo_catch) | GRPO avec le piège (OpenSpiel) [OpenEnv](openenv) environnement. | |
| [`grpo_continuous_batching`](https://github.com/huggingface/trl/tree/main/examples/grpo_continuous_batching) | GRPO avec le moteur de lotissement continu de Transformers pour une génération plus rapide sur de grands lots avec des longueurs de complétion variables. | |
| [`grpo_echo`](https://github.com/huggingface/trl/tree/main/examples/grpo_echo) | Entraînement minimal de GRPO avec l'environnement [OpenEnv](openenv) Echo. | |
| [`grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor) | Entraînement GRPO face à une suite de tâches Harbor avec un agent de base modulaire (harnais `bash` / `jupyter` / `terminal_notes`). Consultez le guide [Harbor Integration](harbor). | |
| [`grpo_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_ministral3_vl) | GRPO Ministral 3 avec QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_ministral3_vl/grpo_ministral3_vl.ipynb) |
| [`grpo_multi_env`](https://github.com/huggingface/trl/tree/main/examples/grpo_multi_env) | Entraînement GRPO multi-environnements : Wordle + Catch [OpenEnv](openenv) dans la même session d'entraînement. | |
| [`grpo_qlora`](https://github.com/huggingface/trl/tree/main/examples/grpo_qlora) | GRPO utilisant QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_qlora/grpo_qlora.ipynb) |
| [`grpo_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_qwen3_vl) | GRPO Qwen3-VL avec QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_qwen3_vl/grpo_qwen3_vl.ipynb) |
| [`grpo_rnj_1_instruct`](https://github.com/huggingface/trl/tree/main/examples/grpo_rnj_1_instruct) | GRPO sur rnj-1-instruct avec QLoRA sur Colab pour ajouter des capacités de raisonnement. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_rnj_1_instruct/grpo_rnj_1_instruct.ipynb) |
| [`grpo_seta`](https://github.com/huggingface/trl/tree/main/examples/grpo_seta) | Entraînement GRPO contre l’environnement SETA ORS du catalogue openreward.ai. Consultez le guide [Intégration OpenReward](openreward). | |
| [`grpo_sql_agent`](https://github.com/huggingface/trl/tree/main/examples/grpo_sql_agent) | GRPO pour entraîner un agent qui répond à des questions en interrogeant une base de données SQL (script et notebook ; non exécutable sur Colab gratuit en raison d'un OOM). | |
| [`grpo_sudoku`](https://github.com/huggingface/trl/tree/main/examples/grpo_sudoku) | GRPO pour jouer au Sudoku (TextArena) dans un environnement [OpenEnv](openenv), à partir d'un modèle SFT : 0, 10 et 22 grilles sur 30 résolues avec 26 cellules vides pour les modèles de base, SFT et SFT + GRPO (script, notebook et README avec les résultats). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_sudoku/grpo_sudoku.ipynb) |
| [`grpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/grpo_visual_math) | Fine-tuning GRPO d'un modèle multimodal pour le raisonnement à l'aide du jeu de données [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified). | |
| [`grpo_wordle`](https://github.com/huggingface/trl/tree/main/examples/grpo_wordle) | GRPO pour jouer à Wordle (TextArena) dans un environnement [OpenEnv](openenv) (script et notebook). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_wordle/grpo_wordle.ipynb) |
| [`gspo_math`](https://github.com/huggingface/trl/tree/main/examples/gspo_math) | GSPO via le [GRPOTrainer](/docs/trl/main/fr/grpo_trainer#trl.GRPOTrainer) pour le raisonnement mathématique sur le jeu de données [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR). | |
| [`gspo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/gspo_visual_math) | GSPO via le [GRPOTrainer](/docs/trl/main/fr/grpo_trainer#trl.GRPOTrainer) pour l’ajustement fin d’un modèle multimodal de raisonnement en utilisant le jeu de données [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified). | |
| [`lfm2_5_moe_research_agent`](https://github.com/huggingface/trl/tree/main/examples/lfm2_5_moe_research_agent) | LiquidAI/LFM2.5-8B-A1B en deux étapes : SFT complet sur le function calling de xLAM sur un nœud 8xH100 avec [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer), sharding au chargement via `DistributedConfig` de transformers (parallélisme d'experts avec dispatch de tokens, plus FSDP), puis GRPO d'un agent de recherche multi-tours sur HotpotQA avec [GRPOTrainer](/docs/trl/main/fr/grpo_trainer#trl.GRPOTrainer) et `environment_factory` (outils `search` / `read`, récompense par correspondance exacte). | |
| [`mpo_visual_preferences`](https://github.com/huggingface/trl/tree/main/examples/mpo_visual_preferences) | MPO via le [DPOTrainer](/docs/trl/main/fr/dpo_trainer#trl.DPOTrainer) pour aligner un modèle multimodal basé sur les préférences en utilisant le jeu de données [HuggingFaceH4/rlaif-v_formatted](https://huggingface.co/datasets/HuggingFaceH4/rlaif-v_formatted) et un ensemble de poids de perte. | |
| [`online_dpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/online_dpo_visual_math) | Ajustement fin en ligne par DPO d'un modèle Vision Language avec [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/main/fr/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer). | |
| [`rloo_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_math) | RLOO avec le [RLOOTrainer](/docs/trl/main/fr/rloo_trainer#trl.RLOOTrainer) pour le raisonnement mathématique sur le jeu de données [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) avec vLLM. | |
| [`rloo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_visual_math) | Fine-tuning RLOO d'un modèle multimodal pour le raisonnement à l'aide du jeu de données [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified). | |
| [`sdft_privileged_context`](https://github.com/huggingface/trl/tree/main/examples/sdft_privileged_context) | Ajustement fin par auto-distillation avec [experimental.sdft.SDFTTrainer](/docs/trl/main/fr/sdft_trainer#trl.experimental.sdft.SDFTTrainer), distillant le contexte privilégié (réservé à l'enseignant) dans le modèle. | |
| [`sdpo_math`](https://github.com/huggingface/trl/tree/main/examples/sdpo_math) | SDPO avec [experimental.sdpo.SDPOTrainer](/docs/trl/main/fr/sdpo_trainer#trl.experimental.sdpo.SDPOTrainer) en utilisant des récompenses mathématiques vérifiables et un retour d'environnement facultatif sur [openai/gsm8k](https://huggingface.co/datasets/openai/gsm8k). | |
| [`sft_agent_traces`](https://github.com/huggingface/trl/tree/main/examples/sft_agent_traces) | SFT de Qwen3.5-2B sur des traces d’agent : Qwen3.5-397B-A17B traite des tâches d’analyse de données [Harbor](harbor) en tant qu’agent OpenCode dans les Hugging Face Sandboxes, enregistré par [OpenEnv](openenv), et l’élève s’entraîne sur les conversations résolues avec une perte uniquement sur les réponses de l’assistant. Sur des tâches dont les données n’ont été touchées par aucune trace, environ 500 traces le font passer de 7,6 % à 33,3 % (scripts de rollout, de jeu de données et d’entraînement, ainsi que le README avec les résultats). | |
| [`sft_beam`](https://github.com/huggingface/trl/tree/main/examples/sft_beam) | SFT LoRA de reflection/Beam-1.0-501B-A23B sur un nœud 8xB300 avec [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer), sharding au chargement via `DistributedConfig` de transformers (parallélisme d'experts avec dispatch de tokens). | |
| [`sft_diffusion_gemma`](https://github.com/huggingface/trl/tree/main/examples/sft_diffusion_gemma) | SFT du modèle de langage à diffusion par blocs DiffusionGemma sur GSM8K en étendant le [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer) avec un objectif de diffusion par blocs. | |
| [`sft_gemma3`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3) | SFT de Gemma 3 sur le jeu de données Codeforces COTS. | |
| [`sft_gemma3_vision`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3_vision) | SFT de Gemma 3 sur des tâches de vision vers texte. | |
| [`sft_gpt_oss_chess`](https://github.com/huggingface/trl/tree/main/examples/sft_gpt_oss_chess) | Ajustement complet de openai/gpt-oss-20b sur des puzzles d'échecs avec [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer) : TRL charge ses experts MXFP4 déquantifiés, et les experts ajustés sont re-quantifiés en MXFP4 pour être servis comme l'original. | |
| [`sft_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_ministral3_vl) | SFT Ministral 3 avec QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_ministral3_vl/sft_ministral3_vl.ipynb) |
| [`sft_mistral_large_4`](https://github.com/huggingface/trl/tree/main/examples/sft_mistral_large_4) | SFT LoRA de mistralai/Mistral-Large-4-1T-A52B sur ses poids FP8 sur un nœud 8xB300 avec [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer), sharding au chargement via `DistributedConfig` de transformers (parallélisme d'experts avec dispatch de tokens). | |
| [`sft_nemotron_3`](https://github.com/huggingface/trl/tree/main/examples/sft_nemotron_3) | SFT des modèles NVIDIA Nemotron 3 (script et notebook LoRA). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_nemotron_3/sft_nemotron_3.ipynb) |
| [`sft_qlora`](https://github.com/huggingface/trl/tree/main/examples/sft_qlora) | SFT avec QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_qlora/sft_qlora.ipynb) |
| [`sft_qwen3_8b_1m_context`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_8b_1m_context) | SFT de Qwen3-8B sur des séquences de 1 048 576 jetons avec parallélisme de contexte, sur un nœud 8xH100. | |
| [`sft_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_vl) | SFT de Qwen3-VL avec QLoRA sur Colab gratuit. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_qwen3_vl/sft_qwen3_vl.ipynb) |
| [`tail_sft_gsm8k`](https://github.com/huggingface/trl/tree/main/examples/tail_sft_gsm8k) | TailSFT sur GSM8K en étendant [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer) avec un filtrage de la perte de politique initiale. | |
| [`sft_muse_spark_open`](https://github.com/huggingface/trl/tree/main/examples/sft_muse_spark_open) | SFT LoRA des méta-modèles/Muse-Spark-Open-816B-A42B sur 8 nœuds avec [SFTTrainer](/docs/trl/main/fr/sft_trainer#trl.SFTTrainer), fractionné au chargement par `DistributedConfig` de transformers (parallélisme d'experts avec dispatch de jetons). | |
| [`sft_tool_calling`](https://github.com/huggingface/trl/tree/main/examples/sft_tool_calling) | Enseigner l'appel d'outils à un modèle sans support natif de l'appel d'outils à l'aide de SFT avec QLoRA (script, modèle de discussion et notebook). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_tool_calling/sft_tool_calling.ipynb) |
| [`sft_visual_chat`](https://github.com/huggingface/trl/tree/main/examples/sft_visual_chat) | SFT d'un modèle de vision-langage dans un contexte de chat. Testé uniquement avec [LLaVA 1.5](https://huggingface.co/llava-hf/llava-1.5-7b-hf), [LLaVA 1.6](https://huggingface.co/llava-hf/llava-v1.6-mistral-7b-hf) et [Llama-3.2-11B-Vision-Instruct](https://huggingface.co/meta-llama/Llama-3.2-11B-Vision-Instruct) ; les utilisateurs peuvent rencontrer un comportement inattendu avec d'autres architectures de modèles. | |
| [`xtoken`](https://github.com/huggingface/trl/tree/main/examples/xtoken) | X-Token distillation de connaissances cross-tokenizer hors politique avec [experimental.gold.GOLDTrainer](/docs/trl/main/fr/gold_trainer#trl.experimental.gold.GOLDTrainer), y compris la préparation de la matrice de projection. | |

## Entraînement distribué

Vous pouvez exécuter les scripts d'exemple sur plusieurs GPU avec torchrun :

```shell
torchrun --nproc_per_node {NUM_GPUS} path_to_script.py --all_arguments_of_the_script
```

Pour DeepSpeed ZeRO-{1,2,3} :

```shell
torchrun --nproc_per_node {NUM_GPUS} path_to_script.py --deepspeed examples/deepspeed_configs/zero{1,2,3}.json --all_arguments_of_the_script
```

Ajustez `NUM_GPUS` et `--all_arguments_of_the_script` selon vos besoins.