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_wordleGRPO Wordle 任务、sft_gpt_ossSFT 特定模型、grpo_qloraGRPO 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 githttps://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_DEVICES0 VLLM_SERVER_DEV_MODE1 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_DEVICES1 python examples/grpo_wordle/grpo_wordle.py --vllm-mode server --vllm-server-url http://localhost:80004. 本地资源一律相对脚本定位加载文件夹内的本地资源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_mathGSM8K 上的异步 on-policy 蒸馏experimental.async_distillation.AsyncDistillationTrainer教师模型经 vLLM 以 HTTP 提供含多教师MOPD数学 代码变体async_grpo_mathGSM8K 上的异步 GRPOexperimental.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_arenaGOLDexperimental.gold.GOLDTrainer在 chatbot_arena_completions 上把 Qwen2 教师蒸馏进 Llama 3.2 学生跨 tokenizer含全量训练与 LoRA 两种变体gold_qwen3_vlGOLD 把 Qwen3-VL-8B 蒸馏进更小 VLM 学生覆盖同族JSD loss与跨族ULD loss蒸馏grpo_2048通过工具调用教模型玩 2048 的 GRPOgrpo_browsergymBrowserGym OpenEnv 环境上的 GRPO含 LLM 与 VLM 两种变体grpo_carlaCARLA 自动驾驶 OpenEnv 环境上的 GRPO含 LLM 与 VLM 变体多模态相机图像工具响应grpo_catchCatchOpenSpielOpenEnv 环境上的 GRPOgrpo_continuous_batching用 transformers 连续批处理continuous batching引擎加速变长批量生成的 GRPOgrpo_echo基于 Echo OpenEnv 环境的最小 GRPO 训练grpo_harbor针对 Harbor 任务套件的 GRPO 训练可插拔基础 Agentbash/jupyter/terminal_notes三种 harness见 Harbor 集成文档grpo_ministral3_vl免费 Colab 上 QLoRA 的 GRPO Ministral 3Notebookgrpo_multi_env多环境 GRPO同一次训练跑 Wordle Catch 两个 OpenEnv 环境grpo_qlora免费 Colab 上 QLoRA 的 GRPONotebookgrpo_qwen3_vl免费 Colab 上 QLoRA 的 GRPO Qwen3-VLNotebookgrpo_rnj_1_instructColab 上对 rnj-1-instruct 用 QLoRA 做 GRPO 以加入推理能力Notebookgrpo_seta针对 openreward.ai 目录中 SETA ORS 环境的 GRPO见 OpenReward 集成文档grpo_sql_agent训练“查 SQL 数据库回答问题”的 Agent脚本 Notebook因 OOM 无法在免费 Colab 运行grpo_sudoku在 OpenEnv 环境上玩数独的 GRPO脚本 Notebookgrpo_visual_math用 multimodal-open-r1 数据集微调多模态模型推理的 GRPOgrpo_wordle在 OpenEnvTextArena环境上玩 Wordle 的 GRPO脚本 Notebookgspo_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 DPOrloo_math配合 vLLM、在 NuminaMath-TIR 上做数学推理的 RLOORLOOTrainerrloo_visual_math多模态推理微调的 RLOOsdft_privileged_context用experimental.sdft.SDFTTrainer做自蒸馏微调把特权仅教师可见上下文蒸馏进模型sdpo_math用可验证数学奖励可选环境反馈在 GSM8K 上跑 SDPOexperimental.sdpo.SDPOTrainersft_diffusion_gemma在 GSM8K 上对 DiffusionGemma 块扩散语言模型做 SFT扩展SFTTrainer的块扩散目标sft_gemma3在 Codeforces COTS 数据集上对 Gemma 3 做 SFTsft_gemma3_vision对 Gemma 3 做视觉到文本任务的 SFTsft_gpt_oss对 openai/gpt-oss-20b 做 SFTsft_ministral3_vl免费 Colab 上 QLoRA 的 SFT Ministral 3Notebooksft_nemotron_3对 NVIDIA Nemotron 3 系列模型做 SFT脚本 LoRA Notebooksft_qlora免费 Colab 上 QLoRA 的 SFTNotebooksft_qwen3_8b_1m_context用上下文并行在一台 8xH100 节点上对 Qwen3-8B 做 1,048,576 token 长序列 SFTsft_qwen3_vl免费 Colab 上 QLoRA 的 SFT Qwen3-VLNotebooksft_tool_calling用 SFT QLoRA 教会无原生工具调用能力的模型工具调用脚本、chat 模板、Notebooksft_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-urlOpenEnv 环境服务器地址默认指向 HF Space、--dataset-size合成数据条数默认 1000、--num-generations每 prompt 的 rollout 数默认 4、--learning-rate默认 1e-6、--gradient-accumulation-steps默认 64、--vllm-modecolocate/server二选一等见 grpo_wordle.py。环境工厂模式GRPO 与环境交互的关键在于environment_factory参数——Trainer 为每个 rollout 实例化一个环境对象模型以工具调用guess驱动环境步进训练结束后由reward_func从环境读取最终奖励见 grpo_wordle.pydef reward_func(environments, **kwargs) - list[float]: return [env.reward for env in environments] trainer GRPOTrainer( modelargs.model, reward_funcsreward_func, train_datasetdataset, argsGRPOConfig( use_vllmTrue, vllm_modeargs.vllm_mode, log_completionsTrue, num_generationsargs.num_generations, max_completion_length1024, chat_template_kwargs{enable_thinking: False}, ... ), environment_factoryWordleEnv, )vLLM 两种部署形态--vllm-mode colocatevLLM 与训练共卡单卡可跑与--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标准多卡 DDPdistributed_type: MULTI_GPU、mixed_precision: bf16、num_processes: 8按机器实际卡数用--num_processes覆盖即可见 multi_gpu.yamldeepspeed_zero1.yaml/deepspeed_zero2.yaml/deepspeed_zero3.yamlDeepSpeed ZeRO 1/2/3 变体fsdp1.yaml/fsdp2.yamlFSDP 1 与 FSDP 2context_parallel_2gpu.yamlFSDP 上下文并行的 2 卡配置开启fsdp_activation_checkpointing并把parallelism_config_cp_size设为 2见 context_parallel_2gpu.yaml——sft_qwen3_8b_1m_context这类百万 token 长序列示例正是依赖这一机制alst_ulysses_4gpu.yaml4 卡 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 在多卡上运行命令模板如下多 GPUaccelerate launch --config_fileexamples/accelerate_configs/multi_gpu.yaml --num_processes {NUM_GPUS} path_to_script.py --all_arguments_of_the_scriptDeepSpeed ZeRO-1/2/3accelerate launch --config_fileexamples/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考