# Exemplos

O diretório [`examples/`](https://github.com/huggingface/trl/tree/main/examples) contém uma coleção de exemplos autossuficientes que demonstram como usar a biblioteca TRL para diversas aplicações. **Cada exemplo fica em sua própria pasta** nomeada de acordo com o método e a tarefa que demonstra (por exemplo, `grpo_wordle`, `sft_gpt_oss_chess`), e contém tudo o que o exemplo precisa: scripts, notebooks, prompts, modelos de chat e código de avaliação.

Scripts básicos de treinamento com um único trainer não são exemplos: eles estão em [`trl/scripts`](https://github.com/huggingface/trl/tree/main/trl/scripts) e são expostos por meio da [interface de linha de comando](clis) (`trl sft`, `trl dpo`, `trl grpo`, …). A página de documentação de cada trainer também contém um snippet completo e executável.

Os recursos compartilhados estão na raiz de `examples/`:

- [`examples/deepspeed_configs`](https://github.com/huggingface/trl/tree/main/examples/deepspeed_configs): arquivos de configuração do DeepSpeed ZeRO, passados com `--deepspeed`, usados por muitos exemplos.
- [`examples/fsdp_configs`](https://github.com/huggingface/trl/tree/main/examples/fsdp_configs): arquivos de configuração do FSDP, passados com `--fsdp --fsdp_config` (um `--fsdp` simples na linha de comando requer o transformers 5.10 ou posterior; em versões anteriores, defina `fsdp=True` na configuração de treinamento).
- [`examples/datasets`](https://github.com/huggingface/trl/tree/main/examples/datasets): os scripts usados para gerar os conjuntos de dados do `trl-lib` utilizados em todos os exemplos.

**Começando**

Instale o TRL e as dependências adicionais da seguinte forma:

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

Verifique as dependências opcionais adicionais [aqui](https://github.com/huggingface/trl/blob/main/pyproject.toml). Os exemplos baseados em notebook são autossuficientes e podem ser executados no **Colab gratuito**; os exemplos baseados em script são executados em configurações de GPU única, multi-GPU ou DeepSpeed (veja [Training Distribuído](#distributed-training) abaixo).

## Índice

| Exemplo | Descrição | Abrir no Colab |
| --- | --- | --- |
| [`async_distillation_math`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_math) | Destilação on-policy assíncrona no GSM8K com [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.0/pt/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer): o professor é servido via HTTP com vLLM. | |
| [`async_distillation_mopd`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_mopd) | Destilação on-policy com múltiplos professores (MOPD) com [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.0/pt/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer): funde os especialistas em matemática, código e seguimento de instruções do Open-MOPD em seu checkpoint SFT: de 17,5 para 24,2 no AIME24 e de 67,5 para 73,0 no IFEval em 60 passos (script, lançador do Hugging Face Jobs e README com os resultados). | |
| [`async_grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_harbor) | Treinamento AsyncGRPO em uma suíte de tarefas [Harbor](https://huggingface.co/docs/openenv/environments/harbor) por meio de qualquer agente de codificação instalado (`mini-swe-agent`, `opencode`, `claude-code`, ...) servido via [OpenEnv](openenv): o agente possui seu próprio loop em um sandbox e o TRL treina nos ids de tokens e logprobs registrados pelo proxy de captura. | |
| [`async_grpo_math`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_math) | GRPO assíncrono no GSM8K com [AsyncGRPOTrainer](/docs/trl/v1.18.0/pt/async_grpo_trainer#trl.AsyncGRPOTrainer), desacoplando a geração (servidor vLLM) do treinamento, incluindo uma variante LoRA que sincroniza apenas o adaptador com o servidor vLLM. | |
| [`dpo_reduce_hallucinations`](https://github.com/huggingface/trl/tree/main/examples/dpo_reduce_hallucinations) | Fine-tuning DPO de um Vision Language Model para reduzir alucinações usando o dataset [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) | General Online Logit Distillation (GOLD) de um professor Qwen2 para um aluno Llama 3.2 (cross-tokenizer) em chatbot_arena_completions com [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/pt/gold_trainer#trl.experimental.gold.GOLDTrainer), com variantes de treinamento completo e LoRA. | |
| [`gold_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/gold_qwen3_vl) | Destilação de Logits Online Geral (GOLD) do Qwen3-VL-8B para alunos VLM menores com [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/pt/gold_trainer#trl.experimental.gold.GOLDTrainer), abrangendo destilação da mesma família (perda JSD) e entre famílias (perda ULD). | |
| [`grpo_2048`](https://github.com/huggingface/trl/tree/main/examples/grpo_2048) | GRPO com chamadas de ferramentas para ensinar um modelo a jogar o jogo 2048. | |
| [`grpo_browsergym`](https://github.com/huggingface/trl/tree/main/examples/grpo_browsergym) | GRPO com o ambiente [OpenEnv](openenv) do BrowserGym, com variantes de LLM e VLM. | |
| [`grpo_carla`](https://github.com/huggingface/trl/tree/main/examples/grpo_carla) | GRPO com o ambiente de direção autônoma CARLA [OpenEnv](openenv), com variantes de LLM e VLM (respostas de ferramentas de imagens de câmera multimodais). | |
| [`grpo_catch`](https://github.com/huggingface/trl/tree/main/examples/grpo_catch) | GRPO com o Catch (OpenSpiel) [OpenEnv](openenv) ambiente. | |
| [`grpo_continuous_batching`](https://github.com/huggingface/trl/tree/main/examples/grpo_continuous_batching) | GRPO com o motor de loteamento contínuo do Transformers para geração mais rápida em lotes grandes com comprimentos de conclusão variáveis. | |
| [`grpo_echo`](https://github.com/huggingface/trl/tree/main/examples/grpo_echo) | Treinamento mínimo de GRPO com o ambiente [OpenEnv](openenv) Echo. | |
| [`grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor) | Treinamento GRPO contra uma suíte de tarefas do Harbor com um agente base plugável (harnesses `bash` / `jupyter` / `terminal_notes`). Consulte o guia de [Integração com o Harbor](harbor). | |
| [`grpo_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_ministral3_vl) | GRPO Ministral 3 com QLoRA em Colab gratuito. | [![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) | Treinamento GRPO multiambiente: Wordle + Catch [OpenEnv](openenv) ambientes na mesma execução de treinamento. | |
| [`grpo_qlora`](https://github.com/huggingface/trl/tree/main/examples/grpo_qlora) | GRPO usando QLoRA no Colab gratuito. | [![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 com QLoRA no Colab gratuito. | [![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 no rnj-1-instruct com QLoRA no Colab para adicionar capacidades de raciocínio. | [![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) | Treinamento GRPO contra o ambiente SETA ORS no catálogo openreward.ai. Consulte o guia [Integração OpenReward](openreward). | |
| [`grpo_sql_agent`](https://github.com/huggingface/trl/tree/main/examples/grpo_sql_agent) | GRPO para treinar um agente que responde perguntas consultando um banco de dados SQL (script e notebook; não executável no Colab gratuito devido a OOM). | |
| [`grpo_sudoku`](https://github.com/huggingface/trl/tree/main/examples/grpo_sudoku) | GRPO para jogar Sudoku (TextArena) em um ambiente [OpenEnv](openenv), partindo de um modelo SFT: 0, 10 e 22 puzzles resolvidos de 30 com 26 células vazias para os modelos base, SFT e SFT + GRPO (script, notebook e README com os resultados). | [![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 de um modelo multimodal para raciocínio usando o dataset [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 para jogar Wordle (TextArena) em um ambiente [OpenEnv](openenv) (script e 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 o [GRPOTrainer](/docs/trl/v1.18.0/pt/grpo_trainer#trl.GRPOTrainer) para raciocínio matemático no conjunto de dados [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 o [GRPOTrainer](/docs/trl/v1.18.0/pt/grpo_trainer#trl.GRPOTrainer) para ajustar finamente um modelo multimodal para raciocínio usando o conjunto de dados [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 em duas etapas: SFT completo em chamadas de função do xLAM em um nó 8xH100 com [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer), particionado no carregamento pela `DistributedConfig` dos transformers (paralelismo de especialistas com despacho de tokens, além de FSDP), seguido de GRPO de um agente de pesquisa multi-turno no HotpotQA com [GRPOTrainer](/docs/trl/v1.18.0/pt/grpo_trainer#trl.GRPOTrainer) e `environment_factory` (ferramentas `search` / `read`, recompensa por correspondência exata). | |
| [`mpo_visual_preferences`](https://github.com/huggingface/trl/tree/main/examples/mpo_visual_preferences) | MPO por meio do [DPOTrainer](/docs/trl/v1.18.0/pt/dpo_trainer#trl.DPOTrainer) para alinhar um modelo multimodal com base em preferências usando o conjunto de dados [HuggingFaceH4/rlaif-v_formatted](https://huggingface.co/datasets/HuggingFaceH4/rlaif-v_formatted) e um conjunto de pesos de perda. | |
| [`online_dpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/online_dpo_visual_math) | Fine-tuning online DPO de um Vision Language Model com [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/v1.18.0/pt/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer). | |
| [`rloo_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_math) | RLOO com o [RLOOTrainer](/docs/trl/v1.18.0/pt/rloo_trainer#trl.RLOOTrainer) para raciocínio matemático no conjunto de dados [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) com vLLM. | |
| [`rloo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_visual_math) | Fine-tuning RLOO de um modelo multimodal para raciocínio usando o dataset [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) | Fine-tuning por auto-destilação com [experimental.sdft.SDFTTrainer](/docs/trl/v1.18.0/pt/sdft_trainer#trl.experimental.sdft.SDFTTrainer), destilando contexto privilegiado (somente do professor) para o modelo. | |
| [`sdpo_math`](https://github.com/huggingface/trl/tree/main/examples/sdpo_math) | SDPO com [experimental.sdpo.SDPOTrainer](/docs/trl/v1.18.0/pt/sdpo_trainer#trl.experimental.sdpo.SDPOTrainer) usando recompensas matemáticas verificáveis e feedback opcional do ambiente em [openai/gsm8k](https://huggingface.co/datasets/openai/gsm8k). | |
| [`sft_agent_traces`](https://github.com/huggingface/trl/tree/main/examples/sft_agent_traces) | SFT do Qwen3.5-2B em rastros de agentes: o Qwen3.5-397B-A17B executa tarefas de análise de dados do [Harbor](harbor) como um agente OpenCode em Hugging Face Sandboxes, registrado pelo [OpenEnv](openenv), e o aluno treina nas conversas resolvidas com perda apenas do assistente. Em tarefas cujos dados nenhum rastro tocou, cerca de 500 rastros o levam de 7,6% para 33,3% (scripts de rollout, dataset e treinamento, e README com os resultados). | |
| [`sft_beam`](https://github.com/huggingface/trl/tree/main/examples/sft_beam) | SFT com LoRA de reflection/Beam-1.0-501B-A23B em um nó 8xB300 com [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer), fragmentado no momento do carregamento pelo `DistributedConfig` dos transformers (paralelismo de especialistas com despacho de tokens). | |
| [`sft_diffusion_gemma`](https://github.com/huggingface/trl/tree/main/examples/sft_diffusion_gemma) | SFT do modelo de linguagem de difusão por blocos DiffusionGemma no GSM8K, estendendo o [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer) com um objetivo de difusão por blocos. | |
| [`sft_gemma3`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3) | SFT do Gemma 3 no dataset Codeforces COTS. | |
| [`sft_gemma3_vision`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3_vision) | SFT do Gemma 3 em tarefas de visão para texto. | |
| [`sft_gpt_oss_chess`](https://github.com/huggingface/trl/tree/main/examples/sft_gpt_oss_chess) | Fine-tuning completo de openai/gpt-oss-20b em puzzles de xadrez com [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer): o TRL carrega seus especialistas MXFP4 dequantizados, e os especialistas fine-tunados são quantizados de volta para MXFP4 para serem servidos como o original. | |
| [`sft_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_ministral3_vl) | SFT do Ministral 3 com QLoRA no Colab gratuito. | [![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 com LoRA do mistralai/Mistral-Large-4-1T-A52B sobre seus pesos FP8 em um único nó 8xB300, usando [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer), com sharding no momento do carregamento via `DistributedConfig` dos transformers (paralelismo de especialistas com despacho de tokens). | |
| [`sft_nemotron_3`](https://github.com/huggingface/trl/tree/main/examples/sft_nemotron_3) | SFT dos modelos NVIDIA Nemotron 3 (script e notebook de 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 usando QLoRA no Colab gratuito. | [![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 do Qwen3-8B em sequências de 1.048.576 tokens com paralelismo de contexto, em um nó 8xH100. | |
| [`sft_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_vl) | SFT do Qwen3-VL com QLoRA no Colab gratuito. | [![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 no GSM8K estendendo o [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer) com filtragem de perda da política inicial. | |
| [`sft_muse_spark_open`](https://github.com/huggingface/trl/tree/main/examples/sft_muse_spark_open) | SFT com LoRA de meta-modelos/Muse-Spark-Open-816B-A42B em 8 nós com [SFTTrainer](/docs/trl/v1.18.0/pt/sft_trainer#trl.SFTTrainer), fragmentado no momento do carregamento pelo `DistributedConfig` dos transformers (paralelismo de especialistas com despacho de tokens). | |
| [`sft_tool_calling`](https://github.com/huggingface/trl/tree/main/examples/sft_tool_calling) | Ensinando a um modelo a chamar ferramentas sem suporte nativo a chamadas de ferramentas usando SFT com QLoRA (script, modelo de chat e 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 de um modelo de linguagem visual em um ambiente de chat. Testado apenas com [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) e [Llama-3.2-11B-Vision-Instruct](https://huggingface.co/meta-llama/Llama-3.2-11B-Vision-Instruct); os usuários podem observar comportamentos inesperados em outras arquiteturas de modelo. | |
| [`xtoken`](https://github.com/huggingface/trl/tree/main/examples/xtoken) | X-Token destilação de conhecimento cross-tokenizer off-policy com [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/pt/gold_trainer#trl.experimental.gold.GOLDTrainer), incluindo a preparação da matriz de projeção. | |

## Treinamento Distribuído

Você pode executar os scripts de exemplo em várias GPUs com torchrun:

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

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

Ajuste `NUM_GPUS` e `--all_arguments_of_the_script` conforme necessário.

