TRL examples 目录实战指南：示例组织规范、完整索引与多 GPU 运行方式

TRL examples 目录实战指南：示例组织规范、完整索引与多 GPU 运行方式

【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl

本文基于 TRL 仓库的 examples/README.md 及其索引文档 docs/source/example_overview.md 编写。它完整讲清examples/目录的组织约定（文件夹命名、自包含结构、依赖声明、文档要求）、全部示例的索引清单，以及用 Accelerate / DeepSpeed 以多 GPU 方式运行示例脚本的具体命令。读完后，你既能快速定位并复现仓库中任意一个示例，也能按官方规范贡献一个合格的新示例。

examples 目录的整体布局

TRL 的 examples/ 目录收集了一批自包含（self-contained）示例：每个示例独占一个文件夹，文件夹内放齐该示例所需的一切——脚本、Notebook、prompt 文本、chat 模板、评测代码。文件夹命名遵循“方法 + 亮点”的组合格式，例如grpo_wordle（GRPO + Wordle 任务）、sft_gpt_oss（SFT + 特定模型）、grpo_qlora（GRPO + QLoRA 技术）。

需要与示例区分开的是基础单 Trainer 训练脚本：这类脚本不是示例，而是放在 trl/scripts 中、通过命令行接口暴露（trl sft、trl dpo、trl grpo等，见 docs/source/clis.md）。每个 Trainer 的文档页也各自带有可直接运行的代码片段。示例存在的意义在于讲“一个故事”（比如把 GRPO 接上 OpenEnv 环境、用 vLLM 解耦生成与训练），而不是重复 CLI 已覆盖的通用流程。

共享资源放在examples/根层：

• examples/accelerate_configs：供大量示例复用的 🤗 Accelerate 配置文件，覆盖多 GPU、DeepSpeed ZeRO、FSDP 与上下文并行（context parallel）等布局；
• examples/datasets：生成各示例所用trl-lib数据集的脚本，例如 examples/datasets/ultrafeedback.py 用 LLM 标注生成 UltraFeedback 偏好数据集。

环境安装：安装 TRL 及附加依赖：

pip install --upgrade trl[quantization]

其他可选依赖见 pyproject.toml。Notebook 类示例自包含、可在免费 Colab 上运行；脚本类示例则可在单 GPU、多 GPU 或 DeepSpeed 配置下运行（见下文“分布式运行”）。

新增示例的四条规范

examples/README.md 明确规定了贡献新示例的规范，逐条说明如下：

1. 按“方法 + 差异点”命名文件夹

文件夹名应体现方法以及该示例的独到之处——任务（grpo_wordle）、模型（sft_gpt_oss）或技术（grpo_qlora）。

2. 示例必须讲一个故事

裸的单 Trainer 训练脚本不构成示例。稳定的 Trainer 已有 CLI 命令（trl/scripts），且每个 Trainer 的文档页都有可运行片段。示例应当演示某个 Trainer 之上的额外能力组合，例如环境交互、多模态、量化、异步架构或自定义目标函数。

3. 用# /// script头声明依赖，在 docstring 中给出精确运行命令

脚本顶部用# /// script注释块声明依赖（可被uv run一类工具直接解析），模块 docstring 中则必须写明精确的运行命令（形如python examples/<folder>/<script>.py ...），涉及多 GPU 时给出对应变体。仓库中的 examples/grpo_wordle/grpo_wordle.py 是标准样板：

# /// script # dependencies = [ # "trl", # "trackio", # "openenv-textarena @ git+https://huggingface.co/spaces/openenv/wordle", # ] # ///

其 docstring 依次给出了三种运行选项（vLLM colocate 单卡、vLLM server 双卡、本地环境 + Docker/直跑/HF Space 镜像），每条命令都可直接复制执行：

# Option 1: HF Spaces + Colocated vLLM (1 GPU required) python examples/grpo_wordle/grpo_wordle.py --vllm-mode colocate # Option 2: HF Spaces + Separate vLLM server (2 GPUs required) CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-1.7B --host 0.0.0.0 --port 8000 \ --weight-transfer-config '{"backend": "nccl"}' \ --logprobs-mode processed_logprobs \ --max-logprobs -1 CUDA_VISIBLE_DEVICES=1 python examples/grpo_wordle/grpo_wordle.py --vllm-mode server --vllm-server-url http://localhost:8000

4. 本地资源一律相对脚本定位

加载文件夹内的本地资源（prompt、chat 模板、模板文件等）时，必须用Path(__file__).parent / ...相对脚本自身定位，不能假设工作目录。仓库中已有现成示范：

• examples/sft_tool_calling/sft_tiny_aya_tool_calling.py 用Path(__file__).parent / "tiny_aya_chat_template.jinja"定位同目录下的 Jinja2 模板；
• examples/grpo_sudoku/grpo_sudoku.py 用同样方式加载sudoku_prompt.txt。

5. 在 Index 表格中补一行

新增示例必须在 docs/source/example_overview.md 的 Index 表格中加一行；如果示例带有可在免费 Colab 运行的 Notebook，还要加上 Colab 徽章。这一要求由 CI 测试强制保证：tests/test_examples_index.py 会扫描examples/下所有目录（排除共享目录accelerate_configs、datasets），与 Index 表格中的行做双向集合比对——文件夹少了表格行、或表格行没有对应文件夹都会断言失败。因此贡献者改文件夹名或新增目录时，必须同步更新文档。

示例索引（完整清单）

以下清单继承自 docs/source/example_overview.md 的 Index 表格，覆盖当前examples/下全部示例目录。带 Colab 徽章的条目含可在免费 Colab 运行的 Notebook。

示例	说明
async_distillation_math	GSM8K 上的异步 on-policy 蒸馏（experimental.async_distillation.AsyncDistillationTrainer）：教师模型经 vLLM 以 HTTP 提供，含多教师（MOPD）数学 + 代码变体
async_grpo_math	GSM8K 上的异步 GRPO（experimental.async_grpo.AsyncGRPOTrainer），用 vLLM 服务器把生成与训练解耦
async_grpo_opencode	用 AsyncGRPO 训练真实opencode编码 Agent，跑在 OpenEnv 环境上（loop-owning：外部 Agent 自持工具循环，TRL 训练其捕获的 proxy trace），支持本地子进程沙箱或远程沙箱
dpo_reduce_hallucinations	用 RLAIF-V 数据集对 VLM 做 DPO 微调以减少幻觉
gold_chatbot_arena	GOLD（experimental.gold.GOLDTrainer）在 chatbot_arena_completions 上把 Qwen2 教师蒸馏进 Llama 3.2 学生（跨 tokenizer），含全量训练与 LoRA 两种变体
gold_qwen3_vl	GOLD 把 Qwen3-VL-8B 蒸馏进更小 VLM 学生，覆盖同族（JSD loss）与跨族（ULD loss）蒸馏
grpo_2048	通过工具调用教模型玩 2048 的 GRPO
grpo_browsergym	BrowserGym OpenEnv 环境上的 GRPO，含 LLM 与 VLM 两种变体
grpo_carla	CARLA 自动驾驶 OpenEnv 环境上的 GRPO，含 LLM 与 VLM 变体（多模态相机图像工具响应）
grpo_catch	Catch（OpenSpiel）OpenEnv 环境上的 GRPO
grpo_continuous_batching	用 transformers 连续批处理（continuous batching）引擎加速变长批量生成的 GRPO
grpo_echo	基于 Echo OpenEnv 环境的最小 GRPO 训练
grpo_harbor	针对 Harbor 任务套件的 GRPO 训练，可插拔基础 Agent（bash/jupyter/terminal_notes三种 harness），见 Harbor 集成文档
grpo_ministral3_vl	免费 Colab 上 QLoRA 的 GRPO Ministral 3（Notebook）
grpo_multi_env	多环境 GRPO：同一次训练跑 Wordle + Catch 两个 OpenEnv 环境
grpo_qlora	免费 Colab 上 QLoRA 的 GRPO（Notebook）
grpo_qwen3_vl	免费 Colab 上 QLoRA 的 GRPO Qwen3-VL（Notebook）
grpo_rnj_1_instruct	Colab 上对 rnj-1-instruct 用 QLoRA 做 GRPO 以加入推理能力（Notebook）
grpo_seta	针对 openreward.ai 目录中 SETA ORS 环境的 GRPO，见 OpenReward 集成文档
grpo_sql_agent	训练“查 SQL 数据库回答问题”的 Agent（脚本 + Notebook；因 OOM 无法在免费 Colab 运行）
grpo_sudoku	在 OpenEnv 环境上玩数独的 GRPO（脚本 + Notebook）
grpo_visual_math	用 multimodal-open-r1 数据集微调多模态模型推理的 GRPO
grpo_wordle	在 OpenEnv（TextArena）环境上玩 Wordle 的 GRPO（脚本 + Notebook）
gspo_math	通过GRPOTrainer实现的 GSPO，在 NuminaMath-TIR 上做数学推理
gspo_visual_math	通过GRPOTrainer实现的 GSPO 多模态推理微调
mpo_visual_preferences	通过DPOTrainer实现的 MPO，基于偏好对齐多模态模型（rlaif-v 数据集 + 一组 loss 权重）
online_dpo_visual_math	用experimental.online_dpo.OnlineDPOTrainer微调 VLM 的 Online DPO
rloo_math	配合 vLLM、在 NuminaMath-TIR 上做数学推理的 RLOO（RLOOTrainer）
rloo_visual_math	多模态推理微调的 RLOO
sdft_privileged_context	用experimental.sdft.SDFTTrainer做自蒸馏微调，把特权（仅教师可见）上下文蒸馏进模型
sdpo_math	用可验证数学奖励（可选环境反馈）在 GSM8K 上跑 SDPO（experimental.sdpo.SDPOTrainer）
sft_diffusion_gemma	在 GSM8K 上对 DiffusionGemma 块扩散语言模型做 SFT（扩展SFTTrainer的块扩散目标）
sft_gemma3	在 Codeforces COTS 数据集上对 Gemma 3 做 SFT
sft_gemma3_vision	对 Gemma 3 做视觉到文本任务的 SFT
sft_gpt_oss	对 openai/gpt-oss-20b 做 SFT
sft_ministral3_vl	免费 Colab 上 QLoRA 的 SFT Ministral 3（Notebook）
sft_nemotron_3	对 NVIDIA Nemotron 3 系列模型做 SFT（脚本 + LoRA Notebook）
sft_qlora	免费 Colab 上 QLoRA 的 SFT（Notebook）
sft_qwen3_8b_1m_context	用上下文并行在一台 8xH100 节点上对 Qwen3-8B 做 1,048,576 token 长序列 SFT
sft_qwen3_vl	免费 Colab 上 QLoRA 的 SFT Qwen3-VL（Notebook）
sft_tool_calling	用 SFT + QLoRA 教会无原生工具调用能力的模型工具调用（脚本、chat 模板、Notebook）
sft_visual_chat	聊天场景下对 VLM 做 SFT（仅验证过 LLaVA 1.5 / LLaVA 1.6 / Llama-3.2-11B-Vision-Instruct，其他架构可能行为异常）
ssd_codegen	用experimental.ssd.SSDTrainer做代码生成的简单自蒸馏，并在 LiveCodeBench 上评测
tpo_ultrafeedback	用experimental.tpo.TPOTrainer做三元偏好优化（Triple Preference Optimization）

示例脚本剖析：以 grpo_wordle 为例

以最常被引用的 examples/grpo_wordle/grpo_wordle.py 为例，说明一个合格示例的内部结构。

参数即文档：脚本用argparse暴露全部可调项，默认值与用途一一对应，包括--model（默认Qwen/Qwen3-1.7B）、--env-url（OpenEnv 环境服务器地址，默认指向 HF Space）、--dataset-size（合成数据条数，默认 1000）、--num-generations（每 prompt 的 rollout 数，默认 4）、--learning-rate（默认 1e-6）、--gradient-accumulation-steps（默认 64）、--vllm-mode（colocate/server二选一）等（见 grpo_wordle.py）。

环境工厂模式：GRPO 与环境交互的关键在于environment_factory参数——Trainer 为每个 rollout 实例化一个环境对象，模型以工具调用（guess）驱动环境步进，训练结束后由reward_func从环境读取最终奖励（见 grpo_wordle.py）：

def reward_func(environments, **kwargs) -> list[float]: return [env.reward for env in environments] trainer = GRPOTrainer( model=args.model, reward_funcs=reward_func, train_dataset=dataset, args=GRPOConfig( use_vllm=True, vllm_mode=args.vllm_mode, log_completions=True, num_generations=args.num_generations, max_completion_length=1024, chat_template_kwargs={"enable_thinking": False}, ... ), environment_factory=WordleEnv, )

vLLM 两种部署形态：--vllm-mode colocate（vLLM 与训练共卡，单卡可跑）与--vllm-mode server（独立 vLLM 服务器 + NCCL 权重同步，双卡），这正是该示例“讲故事”的部分——它演示了 TRL 与 vLLM 的 colocate/server 双模式集成。

另一个典型是 examples/sft_tool_calling/sft_tiny_aya_tool_calling.py：依赖头声明trl[peft]、bitsandbytes、liger-kernel、trackio；示例的“故事”是用 SFT + QLoRA 教会无原生工具调用能力的 tiny-aya 模型输出工具调用——通过扩展其 Jinja2 chat 模板，把工具 schema 序列化进 system 前言、把工具调用渲染为结构化 XML，并随 tokenizer 保存模板，使推理端无需手工拼 system prompt。

共享资源：Accelerate 配置与数据集脚本

accelerate_configs 一览

examples/accelerate_configs 下的配置可被任意示例直接引用，涵盖：

• multi_gpu.yaml：标准多卡 DDP，distributed_type: MULTI_GPU、mixed_precision: bf16、num_processes: 8，按机器实际卡数用--num_processes覆盖即可（见 multi_gpu.yaml）；
• deepspeed_zero1.yaml/deepspeed_zero2.yaml/deepspeed_zero3.yaml：DeepSpeed ZeRO 1/2/3 变体；
• fsdp1.yaml/fsdp2.yaml：FSDP 1 与 FSDP 2；
• context_parallel_2gpu.yaml：FSDP + 上下文并行的 2 卡配置，开启fsdp_activation_checkpointing，并把parallelism_config_cp_size设为 2（见 context_parallel_2gpu.yaml）——sft_qwen3_8b_1m_context这类百万 token 长序列示例正是依赖这一机制；
• alst_ulysses_4gpu.yaml：4 卡 Ulysses 序列并行布局。

datasets 脚本

examples/datasets 中的脚本用于（重新）生成trl-lib组织下的公开数据集，例如ultrafeedback.py以 HfArgumentParser 暴露--model_name、--aspect、--push_to_hub、--repo_id等参数，方便用户自选标注模型并决定回传 Hub。多数示例直接load_dataset("trl-lib/...")使用其产物，脚本本身只在需要定制标注时才运行。

用 Accelerate / DeepSpeed 多 GPU 运行示例

所有脚本类示例都可以用 🤗 Accelerate 在多卡上运行，命令模板如下：

多 GPU：

accelerate launch --config_file=examples/accelerate_configs/multi_gpu.yaml --num_processes {NUM_GPUS} path_to_script.py --all_arguments_of_the_script

DeepSpeed ZeRO-1/2/3：

accelerate launch --config_file=examples/accelerate_configs/deepspeed_zero{1,2,3}.yaml --num_processes {NUM_GPUS} path_to_script.py --all_arguments_of_the_script

按机器实际情况调整{NUM_GPUS}和脚本自身的命令行参数即可。FSDP 或上下文并行场景则换成对应的fsdp2.yaml/context_parallel_2gpu.yaml配置。

小结

examples/的约定可以浓缩为四句话：每个示例一个自包含文件夹（命名体现方法 + 差异点）、脚本用# /// script声明依赖并在 docstring 里写死可复制的运行命令、本地资源用Path(__file__).parent定位、新示例必须同步登记到 docs/source/example_overview.md 的 Index 表格（由 tests/test_examples_index.py 的 CI 测试强制一致性）。配合accelerate_configs/与datasets/两个共享目录，任何示例都能从免费 Colab 的单卡 Notebook 平滑扩展到 8 卡 DDP、DeepSpeed ZeRO 乃至百万 token 的上下文并行训练。

【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl