# 示例

[`examples/`](https://github.com/huggingface/trl/tree/main/examples) 目录包含一系列自包含的示例，展示了如何使用 TRL 库完成各种应用。**每个示例都位于一个独立的文件夹中**，文件夹名称以其演示的方法和任务命名（例如 `grpo_wordle`、`sft_gpt_oss_chess`），并包含该示例所需的全部内容：脚本、笔记本、提示词、聊天模板以及评估代码。

基础单训练器训练脚本并非示例：它们位于 [`trl/scripts`](https://github.com/huggingface/trl/tree/main/trl/scripts) 中，并通过 [命令行界面](clis)（`trl sft`、`trl dpo`、`trl grpo` 等）暴露。每个训练器的文档页面也包含一个完整的可运行代码片段。

共享资源位于`examples/`的根目录下：

- [`examples/deepspeed_configs`](https://github.com/huggingface/trl/tree/main/examples/deepspeed_configs)：DeepSpeed ZeRO 配置文件，通过 `--deepspeed` 传入，被许多示例使用。
- [`examples/fsdp_configs`](https://github.com/huggingface/trl/tree/main/examples/fsdp_configs)：FSDP 配置文件，通过 `--fsdp --fsdp_config` 传入（在命令行中仅使用 `--fsdp` 需要 transformers 5.10 或更高版本；在旧版本中，请在训练配置中设置 `fsdp=True`）。
- [`examples/datasets`](https://github.com/huggingface/trl/tree/main/examples/datasets)：用于生成示例中使用的 `trl-lib` 数据集的脚本。

**入门指南**

按如下方式安装 TRL 及额外依赖项：

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

有关其他可选依赖项，请参见[此处](https://github.com/huggingface/trl/blob/main/pyproject.toml)。基于 Notebook 的示例是独立的，可以在**免费 Colab**上运行；基于脚本的示例则适用于单 GPU、多 GPU 或 DeepSpeed 环境（参见下文[分布式训练](#distributed-training)）。

## 索引

| 示例 | 描述 | 在 Colab 中打开 |
| --- | --- | --- |
| [`async_distillation_math`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_math) | 在 GSM8K 上使用 [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/zh/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) 进行异步在线策略蒸馏：教师模型通过 vLLM 以 HTTP 方式提供服务。 | |
| [`async_distillation_mopd`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_mopd) | 使用 [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/zh/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) 进行多教师在线策略蒸馏（MOPD）：将 Open-MOPD 的数学、代码和指令遵循专家融合到其 SFT 检查点中：在 60 步内，AIME24 得分从 17.5 提升至 24.2，IFEval 得分从 67.5 提升至 73.0（脚本、Hugging Face Jobs 启动器以及包含结果的 README）。 | |
| [`async_grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_harbor) | 通过任意已安装的编码智能体（`mini-swe-agent`、`opencode`、`claude-code` 等）在 [Harbor](https://huggingface.co/docs/openenv/environments/harbor) 任务套件上进行 AsyncGRPO 训练，该智能体通过 [OpenEnv](openenv) 提供服务：智能体在沙箱中拥有自己的循环，而 TRL 则基于捕获代理记录的 token ids 和 logprobs 进行训练。 | |
| [`async_grpo_math`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_math) | 在 GSM8K 上使用 [experimental.async_grpo.AsyncGRPOTrainer](/docs/trl/main/zh/async_grpo_trainer#trl.experimental.async_grpo.AsyncGRPOTrainer) 进行异步 GRPO，将生成（vLLM 服务器）与训练解耦，并包含一个仅将适配器同步到 vLLM 服务器的 LoRA 变体。 | |
| [`dpo_reduce_hallucinations`](https://github.com/huggingface/trl/tree/main/examples/dpo_reduce_hallucinations) | 使用 [openbmb/RLAIF-V-Dataset](https://huggingface.co/datasets/openbmb/RLAIF-V-Dataset) 数据集对视觉语言模型进行 DPO 微调，以减少幻觉。 | |
| [`gold_chatbot_arena`](https://github.com/huggingface/trl/tree/main/examples/gold_chatbot_arena) | 使用 [experimental.gold.GOLDTrainer](/docs/trl/main/zh/gold_trainer#trl.experimental.gold.GOLDTrainer) 在 chatbot_arena_completions 数据集上，将 Qwen2 教师模型通过通用在线 Logit 蒸馏（GOLD）蒸馏到 Llama 3.2 学生模型（跨分词器），包含全量训练和 LoRA 变体。 | |
| [`gold_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/gold_qwen3_vl) | 使用 [experimental.gold.GOLDTrainer](/docs/trl/main/zh/gold_trainer#trl.experimental.gold.GOLDTrainer) 将 Qwen3-VL-8B 通过通用在线 Logit 蒸馏（GOLD）蒸馏到更小的 VLM 学生模型中，涵盖同族（JSD 损失）和跨族（ULD 损失）蒸馏。 | |
| [`grpo_2048`](https://github.com/huggingface/trl/tree/main/examples/grpo_2048) | 使用 GRPO 结合工具调用，训练模型玩 2048 游戏。 | |
| [`grpo_browsergym`](https://github.com/huggingface/trl/tree/main/examples/grpo_browsergym) | 在 BrowserGym [OpenEnv](openenv) 环境中使用 GRPO，包含 LLM 和 VLM 变体。 | |
| [`grpo_carla`](https://github.com/huggingface/trl/tree/main/examples/grpo_carla) | 在 CARLA 自动驾驶 [OpenEnv](openenv) 环境中使用 GRPO，包含 LLM 和 VLM 变体（多模态相机图像工具响应）。 | |
| [`grpo_catch`](https://github.com/huggingface/trl/tree/main/examples/grpo_catch) | 带有陷阱的 GRPO（OpenSpiel）[OpenEnv](openenv) 环境。 | |
| [`grpo_continuous_batching`](https://github.com/huggingface/trl/tree/main/examples/grpo_continuous_batching) | 使用 Transformers 的连续批处理引擎进行 GRPO，以在具有可变完成长度的大批量上实现更快的生成。 | |
| [`grpo_echo`](https://github.com/huggingface/trl/tree/main/examples/grpo_echo) | 在 Echo [OpenEnv](openenv) 环境中进行最小化的 GRPO 训练。 | |
| [`grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor) | 针对 Harbor 任务套件进行 GRPO 训练，支持可插拔的基础智能体（`bash` / `jupyter` / `terminal_notes` 测试框架）。请参阅 [Harbor 集成](harbor) 指南。 | |
| [`grpo_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_ministral3_vl) | 在免费 Colab 上使用 QLoRA 运行 GRPO Ministral 3。 | [![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) | 多环境 GRPO 训练：在同一次训练运行中同时使用 Wordle 和 Catch [OpenEnv](openenv) 环境。 | |
| [`grpo_qlora`](https://github.com/huggingface/trl/tree/main/examples/grpo_qlora) | 在免费的 Colab 上使用 QLoRA 进行 GRPO。 | [![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) | 在免费 Colab 上使用 QLoRA 对 Qwen3-VL 进行 GRPO 训练。 | [![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) | 在 Colab 上使用 QLoRA 对 rnj-1-instruct 进行 GRPO 训练，以添加推理能力。 | [![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) | 在 openreward.ai 目录的 SETA ORS 环境中进行 GRPO 训练。请参阅 [OpenReward 集成](openreward) 指南。 | |
| [`grpo_sql_agent`](https://github.com/huggingface/trl/tree/main/examples/grpo_sql_agent) | 使用 GRPO 训练一个通过查询 SQL 数据库来回答问题的智能体（包含脚本和 notebook；由于内存不足，无法在免费 Colab 上运行）。 | |
| [`grpo_sudoku`](https://github.com/huggingface/trl/tree/main/examples/grpo_sudoku) | 在 [OpenEnv](openenv) 环境中，使用 GRPO 玩数独（TextArena），从 SFT 模型开始：对于基础模型、SFT 模型和 SFT + GRPO 模型，在 26 个空格的情况下，分别解决了 30 个谜题中的 0 个、10 个和 22 个（包含脚本、notebook 以及带有结果的 README）。 | [![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) | 使用 [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified) 数据集对多模态模型进行 GRPO 微调，以实现推理能力。 | |
| [`grpo_wordle`](https://github.com/huggingface/trl/tree/main/examples/grpo_wordle) | 使用 GRPO 在 [OpenEnv](openenv) 环境中玩 Wordle（TextArena）（脚本和笔记本）。 | [![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) | 通过 [GRPOTrainer](/docs/trl/main/zh/grpo_trainer#trl.GRPOTrainer) 在 [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) 数据集上进行数学推理的 GSPO。 | |
| [`gspo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/gspo_visual_math) | 通过 [GRPOTrainer](/docs/trl/main/zh/grpo_trainer#trl.GRPOTrainer) 使用 GSPO 方法，并利用 [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 两步走：首先，在单个 8xH100 节点上，使用 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 对 xLAM 函数调用进行全量 SFT，加载时由 transformers 的 `DistributedConfig` 进行分片（采用带 token 调度的专家并行，外加 FSDP）；然后，使用 [GRPOTrainer](/docs/trl/main/zh/grpo_trainer#trl.GRPOTrainer) 和 `environment_factory`（`search` / `read` 工具，精确匹配奖励）在 HotpotQA 上对多轮研究智能体进行 GRPO。 | |
| [`mpo_visual_preferences`](https://github.com/huggingface/trl/tree/main/examples/mpo_visual_preferences) | 通过 [DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 使用 MPO 方法，基于 [HuggingFaceH4/rlaif-v_formatted](https://huggingface.co/datasets/HuggingFaceH4/rlaif-v_formatted) 数据集和一组损失权重，根据偏好对齐多模态模型。 | |
| [`online_dpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/online_dpo_visual_math) | 使用 [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/main/zh/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer) 对视觉语言模型进行在线 DPO 微调。 | |
| [`rloo_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_math) | 使用 [RLOOTrainer](/docs/trl/main/zh/rloo_trainer#trl.RLOOTrainer) 在 [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) 数据集上结合 vLLM 进行数学推理的 RLOO。 | |
| [`rloo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_visual_math) | 使用 [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified) 数据集对多模态模型进行 RLOO 微调，以增强其推理能力。 | |
| [`sdft_privileged_context`](https://github.com/huggingface/trl/tree/main/examples/sdft_privileged_context) | 使用 [experimental.sdft.SDFTTrainer](/docs/trl/main/zh/sdft_trainer#trl.experimental.sdft.SDFTTrainer) 进行自蒸馏微调，将特权（仅教师可见）上下文蒸馏到模型中。 | |
| [`sdpo_math`](https://github.com/huggingface/trl/tree/main/examples/sdpo_math) | 使用可验证的数学奖励以及针对 [openai/gsm8k](https://huggingface.co/datasets/openai/gsm8k) 的可选环境反馈，通过 [experimental.sdpo.SDPOTrainer](/docs/trl/main/zh/sdpo_trainer#trl.experimental.sdpo.SDPOTrainer) 进行 SDPO。 | |
| [`sft_agent_traces`](https://github.com/huggingface/trl/tree/main/examples/sft_agent_traces) | 在智能体轨迹上对 Qwen3.5-2B 进行 SFT：Qwen3.5-397B-A17B 作为 OpenCode 智能体，在 Hugging Face Sandboxes 中处理数据分析 [Harbor](harbor) 任务，并由 [OpenEnv](openenv) 记录。学生模型在已解决的对话上进行训练，且仅对助手部分计算损失。在数据未被任何轨迹触及的任务上，约 500 条轨迹将其性能从 7.6% 提升至 33.3%（包含 rollout、数据集和训练脚本，以及带有结果的 README）。 | |
| [`sft_beam`](https://github.com/huggingface/trl/tree/main/examples/sft_beam) | 在单个 8xB300 节点上，使用 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 对 reflection/Beam-1.0-501B-A23B 进行 LoRA SFT，并在加载时通过 transformers 的 `DistributedConfig` 进行分片（采用带 token 调度的专家并行）。 | |
| [`sft_diffusion_gemma`](https://github.com/huggingface/trl/tree/main/examples/sft_diffusion_gemma) | 通过扩展 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 以支持块扩散目标，对 DiffusionGemma 块扩散语言模型在 GSM8K 上进行 SFT。 | |
| [`sft_gemma3`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3) | 在 Codeforces COTS 数据集上对 Gemma 3 进行 SFT。 | |
| [`sft_gemma3_vision`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3_vision) | 在视觉到文本任务上对 Gemma 3 进行 SFT。 | |
| [`sft_gpt_oss_chess`](https://github.com/huggingface/trl/tree/main/examples/sft_gpt_oss_chess) | 使用 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 对 openai/gpt-oss-20b 进行国际象棋谜题的全量微调：TRL 会加载其反量化后的 MXFP4 专家，微调后的专家再重新量化为 MXFP4，以便像原始模型一样提供服务。 | |
| [`sft_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_ministral3_vl) | 在免费的 Colab 上使用 QLoRA 对 SFT Ministral 3 进行微调。 | [![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) | 在单个 8xB300 节点上，基于 mistralai/Mistral-Large-4-1T-A52B 的 FP8 权重，使用 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 进行 LoRA SFT，并在加载时通过 transformers 的 `DistributedConfig` 进行分片（采用带 token 调度的专家并行）。 | |
| [`sft_nemotron_3`](https://github.com/huggingface/trl/tree/main/examples/sft_nemotron_3) | NVIDIA Nemotron 3 模型的 SFT（脚本和 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) | 在免费的 Colab 上使用 QLoRA 进行 SFT。 | [![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) | 在单个 8xH100 节点上，使用上下文并行对 Qwen3-8B 进行 1,048,576 个 token 序列的 SFT。 | |
| [`sft_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_vl) | 在免费的 Colab 上使用 QLoRA 对 Qwen3-VL 进行 SFT。 | [![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) | 通过为 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 添加初始策略损失过滤，在 GSM8K 上实现 TailSFT。 | |
| [`sft_muse_spark_open`](https://github.com/huggingface/trl/tree/main/examples/sft_muse_spark_open) | 在 8 个节点上使用 [SFTTrainer](/docs/trl/main/zh/sft_trainer#trl.SFTTrainer) 对 meta-models/Muse-Spark-Open-816B-A42B 进行 LoRA SFT，加载时通过 transformers 的 `DistributedConfig` 进行分片（采用带 token 调度的专家并行）。 | |
| [`sft_tool_calling`](https://github.com/huggingface/trl/tree/main/examples/sft_tool_calling) | 使用 SFT 和 QLoRA 为不支持原生工具调用的模型教授工具调用（脚本、聊天模板和笔记本）。 | [![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。仅在 [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) 和 [Llama-3.2-11B-Vision-Instruct](https://huggingface.co/meta-llama/Llama-3.2-11B-Vision-Instruct) 上进行了测试；在其他模型架构中，用户可能会遇到意外行为。 | |
| [`xtoken`](https://github.com/huggingface/trl/tree/main/examples/xtoken) | 使用 [experimental.gold.GOLDTrainer](/docs/trl/main/zh/gold_trainer#trl.experimental.gold.GOLDTrainer) 进行 X-Token off-policy 跨分词器知识蒸馏，包括投影矩阵的准备工作。 | |

## 分布式训练

您可以使用 torchrun 在多个 GPU 上运行示例脚本：

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

对于 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
```

根据需要调整 `NUM_GPUS` 和 `--all_arguments_of_the_script`。