Atmosphère 定制固件架构解析：Nintendo Switch 多层组件体系与实现原理
2026/9/13 18:06:07
TRL Examples 全览：从 GRPO 游戏智能体到异步蒸馏的 40+ 可运行示例
【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl
examples/目录是 TRL（Transformer Reinforcement Learning）仓库的"实战案例集"，收录了 40 余个覆盖监督微调（SFT）、偏好优化（DPO/MPO/TPO）、在线强化学习（GRPO/RLOO）、知识蒸馏（GOLD/SDPO/SSD/SDFT）以及异步训练（AsyncGRPO/AsyncDistillation）等方法的自包含示例。每个示例都拥有独立文件夹，内含脚本、Notebook、提示词、对话模板与评测代码，可直接运行复现论文方法或作为二次开发的起点。读完本文，你将掌握 Examples 目录的组织逻辑、完整示例清单、安装与分布式启动方式，并能借助源码读懂环境交互、vLLM 加速、奖励函数设计等关键实现细节。
Examples 目录的设计理念：一例一目录
examples/下每个示例都以"方法 + 任务/模型/技术特征"命名并独占一个文件夹，例如grpo_wordle（方法 + 游戏任务）、sft_gpt_oss（方法 + 模型）、grpo_qlora（方法 + 微调技术）。文件夹内包含该示例所需的全部内容：训练脚本、Notebook、prompt 文本、对话模板（如 sft_tool_calling/tiny_aya_chat_template.jinja）、评测代码（如 ssd_codegen/ssd_eval.py）等，做到"开箱即用、自包含"。
目录的维护约定记录在 examples/README.md 中：
- 命名：按方法 + 任务的区分点命名，如任务（
grpo_wordle）、模型（sft_gpt_oss）、技术（grpo_qlora）； - 资源定位：文件夹内的资产应相对于脚本定位（
Path(__file__).parent / ...），而非依赖当前工作目录； - 讲一个完整故事：裸的单 trainer 训练脚本不算示例——稳定的 trainer 已有对应的 CLI 命令（见下文），且每个 trainer 的文档页都提供了可运行的代码片段；
- 依赖与运行方式显式声明：脚本在
# /// script（PEP 723）头中声明依赖，并在模块 docstring 中写明精确的运行命令（含多 GPU 变体）； - 索引同步：新增示例必须在 docs/source/example_overview.md 的索引表中补一行。
与
trl/scripts的边界：基础的"单 trainer 训练脚本"不属于 Examples，它们位于 trl/scripts（如 trl/scripts/sft.py、trl/scripts/dpo.py、trl/scripts/grpo.py），并通过命令行接口对外暴露：trl sft、trl dpo、trl grpo、trl rloo、trl kto、trl reward、trl distillation、trl env等。CLI 的完整用法见 docs/source/clis.md。Examples 的价值在于展示"单一训练脚本之外"的完整实战形态：多轮环境交互、vLLM 异步服务、自建奖励函数、上下文并行等。
共享资源：accelerate_configs 与 datasets
所有示例共享两份根级资源：
- examples/accelerate_configs：🤗 Accelerate 配置文件，覆盖多 GPU、DeepSpeed ZeRO-{1,2,3}、FSDP（
fsdp1.yaml/fsdp2.yaml）、上下文并行（context_parallel_2gpu.yaml）、单卡等场景。例如 multi_gpu.yaml 声明distributed_type: MULTI_GPU、mixed_precision: 'bf16'、num_processes: 8；deepspeed_zero3.yaml 则开启zero_stage: 3、zero3_init_flag: true、zero3_save_16bit_model: true。 - examples/datasets：生成
trl-lib数据集的脚本，例如 ultrafeedback.py、hh-rlhf-helpful-base.py、math_shepherd.py 等，供各示例复用。
环境准备与安装
安装 TRL 及其量化相关依赖：
pip install --upgrade trl[quantization]更细粒度的可选依赖组（deepspeed、peft、quantization、vllm等）定义在 pyproject.toml 的[project.optional-dependencies]一节（例如peft>=0.13.0、vllm>=0.19.1,<=0.28.0），可按需选择。
- Notebook 类示例：自包含，可在免费 Colab 上直接运行（如
grpo_qlora、grpo_qwen3_vl、sft_qlora、sft_qwen3_vl、sft_tool_calling、sft_nemotron_3、grpo_ministral3_vl、grpo_sudoku、grpo_wordle、sft_ministral3_vl均含.ipynb）；grpo_sql_agent因显存限制（OOM）不适合免费 Colab，但提供了脚本与 Notebook 两种形态。 - 脚本类示例：支持单卡、多卡或 DeepSpeed 环境，需按后续章节配置启动方式。
- 环境类示例：如
grpo_echo、grpo_wordle等依赖 OpenEnv 环境，通常通过pip install "openenv-xxx @ git+https://huggingface.co/spaces/..."安装环境客户端，也可借助脚本内的 PEP 723 元数据直接uv run examples/grpo_echo/grpo_echo.py自动解析依赖。详见 docs/source/openenv.md。
完整示例索引
原文档以索引表形式列出的全部 44 个示例，此处按方法类别重新分组整理（文件夹路径均以examples/开头）。标注 "Colab" 的示例自带 Notebook 且可在免费 Colab 运行。
异步训练与蒸馏（Async / Distillation）
| 示例 | 说明 |
|---|---|
async_distillation_math | 在 GSM8K 上使用experimental.async_distillation.AsyncDistillationTrainer做异步 on-policy 蒸馏，teacher 通过 vLLM 以 HTTP 服务形式提供，含多 teacher（MOPD）的数学 + 代码变体（async_distillation_mopd.py）。 |
async_grpo_math | 使用experimental.async_grpo.AsyncGRPOTrainer在 GSM8K 上做异步 GRPO，将生成（vLLM 服务）与训练解耦。 |
async_grpo_opencode | 在 OpenEnv 环境中对真实opencode编程智能体做 AsyncGRPO 训练（loop-owning 模式：外部智能体自行运行工具循环，TRL 基于其捕获的代理轨迹训练），支持本地子进程沙箱或远程 Hugging Face 沙箱。 |
gold_chatbot_arena | 使用experimental.gold.GOLDTrainer将 Qwen2 teacher 跨 tokenizer 蒸馏到 Llama 3.2 student（chatbot_arena_completions 数据），含全量训练与 LoRA 两种变体。 |
gold_qwen3_vl | 将 Qwen3-VL-8B 蒸馏为更小的 VLM student，覆盖同族（JSD loss）与跨族（ULD loss）蒸馏。 |
sdft_privileged_context | 使用experimental.sdft.SDFTTrainer做自蒸馏微调，把仅 teacher 可见的"特权上下文"蒸馏进模型。 |
sdpo_math | 使用experimental.sdpo.SDPOTrainer在 GSM8K 上做 SDPO，使用可验证的数学奖励与可选的环境反馈。 |
ssd_codegen | 使用experimental.ssd.SSDTrainer做代码生成的简单自蒸馏（Simple Self-Distillation），附带 LiveCodeBench 评测（ssd_eval.py）。 |
偏好对齐（Preference Optimization）
| 示例 | 说明 |
|---|---|
dpo_reduce_hallucinations | 使用 RLAIF-V 数据集对视觉语言模型（VLM）做 DPO 微调以减少幻觉。 |
mpo_visual_preferences | 通过DPOTrainer实现 MPO，基于 rlaif-v_formatted 偏好数据与一组损失权重对齐多模态模型。 |
online_dpo_visual_math | 使用experimental.online_dpo.OnlineDPOTrainer对 VLM 做在线 DPO 微调。 |
tpo_ultrafeedback | 使用experimental.tpo.TPOTrainer在 triple-preference-ultrafeedback-40K 数据集上做三重偏好优化（Triple Preference Optimization）。 |
GRPO 游戏与环境智能体（OpenEnv）
| 示例 | 说明 |
|---|---|
grpo_2048 | GRPO + 工具调用，教模型玩 2048 游戏。 |
grpo_browsergym | GRPO + BrowserGym OpenEnv 环境，含 LLM 与 VLM 两种变体。 |
grpo_carla | GRPO + CARLA 自动驾驶 OpenEnv 环境，含 LLM 与 VLM 变体（多模态摄像头图像工具响应）。 |
grpo_catch | GRPO + Catch（OpenSpiel）OpenEnv 环境。 |
grpo_echo | 使用 Echo OpenEnv 环境的最小 GRPO 训练示例。 |
grpo_harbor | 针对 Harbor 任务套件做 GRPO 训练，支持可插拔基础智能体（bash/jupyter/terminal_notes三种 harness，见 grpo_harbor/harnesses）。集成指南见 docs/source/harbor.md。 |
grpo_multi_env | 多环境 GRPO：在同一轮训练中同时使用 Wordle + Catch 两个 OpenEnv 环境。 |
grpo_seta | 在 openreward.ai 目录的 SETA ORS 环境上做 GRPO 训练，集成指南见 docs/source/openreward.md。 |
grpo_sql_agent | GRPO 训练一个通过查询 SQL 数据库回答问题的智能体（脚本 + Notebook；免费 Colab 因 OOM 不可运行）。 |
grpo_sudoku | 在 OpenEnv 环境上做 GRPO 玩数独（脚本 + Notebook，可 Colab）。 |
grpo_wordle | 在 OpenEnv（TextArena）环境上做 GRPO 玩 Wordle（脚本 + Notebook，可 Colab）。 |
GRPO 数学推理、视觉与效率（Colab 友好）
| 示例 | 说明 |
|---|---|
grpo_continuous_batching | 使用 transformers 的 continuous batching 引擎加速大批量、变长 completion 的 GRPO 生成。 |
grpo_ministral3_vl | 在免费 Colab 上用 QLoRA 对 Ministral 3 做 GRPO（Notebook）。 |
grpo_qlora | 在免费 Colab 上用 QLoRA 做 GRPO（Notebook）。 |
grpo_qwen3_vl | 在免费 Colab 上用 QLoRA 对 Qwen3-VL 做 GRPO（Notebook）。 |
grpo_rnj_1_instruct | 在 Colab 上用 QLoRA 对 rnj-1-instruct 做 GRPO 以增强推理能力（Notebook）。 |
grpo_visual_math | 使用 multimodal-open-r1-8k-verified 数据集对多模态模型做 GRPO 推理微调。 |
gspo_math | 通过GRPOTrainer实现 GSPO（广义采样偏好优化，见 docs/source/gspo_token.md），在 NuminaMath-TIR 上做数学推理。 |
gspo_visual_math | 通过GRPOTrainer做 GSPO，微调多模态模型进行推理（multimodal-open-r1-8k-verified）。 |
rloo_math | 使用RLOOTrainer在 NuminaMath-TIR 上做数学推理，生成端由 vLLM 提供。 |
rloo_visual_math | 使用 multimodal-open-r1-8k-verified 对多模态模型做 RLOO 推理微调。 |
SFT 监督微调
| 示例 | 说明 |
|---|---|
sft_diffusion_gemma | 扩展SFTTrainer引入 block-diffusion 目标，在 GSM8K 上微调 DiffusionGemma 块扩散语言模型。 |
sft_gemma3 | 在 Codeforces COTS 数据集上微调 Gemma 3。 |
sft_gemma3_vision | 在视觉转文本任务上微调 Gemma 3。 |
sft_gpt_oss | 微调 openai/gpt-oss-20b。 |
sft_ministral3_vl | 在免费 Colab 上用 QLoRA 对 Ministral 3 做 SFT（Notebook）。 |
sft_nemotron_3 | 微调 NVIDIA Nemotron 3 系列模型（脚本 + LoRA Notebook，可 Colab）。 |
sft_qlora | 在免费 Colab 上用 QLoRA 做 SFT（Notebook）。 |
sft_qwen3_8b_1m_context | 在单个 8xH100 节点上，借助上下文并行（context_parallel_8gpu.yaml）对 Qwen3-8B 做 1,048,576 token 长序列 SFT。 |
sft_qwen3_vl | 在免费 Colab 上用 QLoRA 对 Qwen3-VL 做 SFT（Notebook）。 |
sft_tool_calling | 用 SFT + QLoRA 给不具备原生工具调用能力的模型教会工具调用（含脚本、对话模板 tiny_aya_chat_template.jinja 与 Notebook，可 Colab）。 |
sft_visual_chat | 在聊天场景下微调 VLM，仅针对 LLaVA 1.5 / LLaVA 1.6 / Llama-3.2-11B-Vision-Instruct 验证过，其他架构可能出现意外行为。 |
分布式训练：用 Accelerate 启动示例脚本
脚本类示例支持多卡 / DeepSpeed 分布式运行。多 GPU 场景：
accelerate launch --config_file=examples/accelerate_configs/multi_gpu.yaml --num_processes {NUM_GPUS} path_to_script.py --all_arguments_of_the_scriptDeepSpeed 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}替换为实际 GPU 数，将--all_arguments_of_the_script替换为目标示例脚本的参数； - 仓库提供的 deepspeed_zero1.yaml、deepspeed_zero2.yaml、deepspeed_zero3.yaml 均以 bf16 混合精度 + 8 进程为默认；ZeRO-3 额外开启
zero3_init_flag（延迟初始化）与zero3_save_16bit_model（保存 16 位模型权重）； - 1M 上下文的长序列示例还需配合上下文并行配置（context_parallel_2gpu.yaml、context_parallel_8gpu.yaml），详见 docs/source/long_context_training.md。
从源码看示例的三种典型形态
1. 最小环境交互：grpo_echo
grpo_echo.py 演示了 GRPO + OpenEnv 环境的最简写法：
- 自定义
EchoToolEnv类：__init__中创建远程环境客户端EchoEnv(base_url=...)；reset每轮把self.reward归零；工具方法echo调用self.env.step(EchoAction(message=message))并从observation.observation.reward取回奖励； - 奖励函数只做一件事：
return [env.reward for env in environments]，把环境状态里的奖励透传给 trainer； GRPOTrainer通过environment_factory=EchoToolEnv注入环境，并通过GRPOConfig(chat_template_kwargs={"enable_thinking": False}, log_completions=True, ...)关闭思考 token、开启 completion 日志打印。
运行命令（脚本 docstring 中给出）：
python examples/grpo_echo/grpo_echo.py python examples/grpo_echo/grpo_echo.py --model Qwen/Qwen2.5-0.5B-Instruct --env-host https://qgallouedec-echo-env.hf.space2. 环境 + vLLM 加速：grpo_wordle
grpo_wordle.py 展示了更完整的"游戏智能体"工程形态：系统提示词（prompt变量）定义了 Wordle 的 6 次猜测规则与 G/Y/X 颜色反馈语义；WordleEnv.guess解析环境返回的累积反馈并切片出"本轮新增"部分，同时识别非法移动并置零奖励；训练配置里通过use_vllm=True、vllm_mode=colocate|server、vllm_server_base_url=...接入 vLLM 生成后端。
运行方式（脚本 docstring 中给出）：
# Option 1: HF Spaces + 同卡 vLLM（需 1 GPU） python examples/grpo_wordle/grpo_wordle.py --vllm-mode colocate # Option 2: HF Spaces + 独立 vLLM 服务（需 2 GPU） # 终端 1 启动 vLLM： 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 # 终端 2 启动训练： CUDA_VISIBLE_DEVICES=1 python examples/grpo_wordle/grpo_wordle.py --vllm-mode server --vllm-server-url http://localhost:8000本地部署环境时还有 Docker 镜像、uvicorn 直启、HF Space 预构建镜像等多种选项，见脚本 docstring。GRPO 的 agent 训练模式（tools 与 environments）对比详见 docs/source/grpo_trainer.md。
3. 异步训练与自建奖励：async_grpo_math/grpo_sql_agent
async_grpo_math.py 演示了异步范式：先用vllm serve启动生成服务（--weight-transfer-config '{"backend":"nccl"}'用于权重同步），再用accelerate launch examples/async_grpo_math/async_grpo_math.py启动训练进程，AsyncGRPOConfig中通过report_to="trackio"、trackio_space_id=...上报实验。数据侧用dataset.map(format_sample, ...)把 GSM8K 转为{"prompt": ..., "solution": ...}结构。
grpo_sql_agent.py 则示范了"规则化奖励函数"的精细设计：从 completion 的多轮工具调用轨迹中抽取 SQL 查询与工具结果，惩罚查询超过 3 次（-1.5）、LIMIT 1泛化查询（-1.0）、不含WHERE（-0.5）与查询报错（-2.0），奖励WHERE使用（每条 +0.4，封顶 3 条）与证据支撑的 yes/no 回答（+2.0）。这类奖励函数可直接复用于其他"工具调用 + 可验证结果"的任务。
索引一致性保障：测试如何守护文档
示例索引并非手写即可——仓库用测试 tests/test_examples_index.py 保证文档与目录严格同步：测试遍历examples/下所有文件夹（排除共享目录accelerate_configs、datasets），再从 docs/source/example_overview.md 的索引表中正则提取示例名做双向比对，任何"文档有而目录无"或"目录有而文档无"的情况都会导致断言失败。这意味着你阅读的这份索引始终与实际代码保持一致，是可信的导航依据。
下一步
- 想快速跑通第一个示例，从 grpo_echo（最小环境）或 grpo_qlora（Colab 零成本）入手；
- 需要环境类任务的完整选型，参考 docs/source/openenv.md、docs/source/openreward.md 与 docs/source/harbor.md 三份集成指南；
- 想理解 GRPO 配置与 agent 训练细节，阅读 docs/source/grpo_trainer.md 与 trl/trainer/grpo_trainer.py；
- 需要 CLI 快速启动基线训练，参见 docs/source/clis.md 与 trl/scripts。
【免费下载链接】trlTrain transformer language models with reinforcement learning.项目地址: https://gitcode.com/GitHub_Trending/tr/trl
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考