GRPO 训练器

概述

TRL 支持 GRPO Trainer，用于训练语言模型，如 Zhihong Shao、Peiyi Wang、Qihao Zhu、Runxin Xu、Junxiao Song、Mingchuan Zhang、Y. K. Li、Y. Wu 和 Daya Guo 在论文 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models 中所述。

该论文的摘要如下：

数学推理因其复杂且结构化的特性，对语言模型构成了重大挑战。在本文中，我们介绍了 DeepSeekMath 7B，该模型使用源自 Common Crawl 的 120B 数学相关 token，并结合自然语言和代码数据，对 DeepSeek-Coder-Base-v1.5 7B 进行继续预训练。在不依赖外部工具包和投票技术的情况下，DeepSeekMath 7B 在竞赛级 MATH 基准测试中取得了 51.7% 的惊人分数，其性能接近 Gemini-Ultra 和 GPT-4 的水平。对 DeepSeekMath 7B 的 64 个样本进行自一致性（Self-consistency）处理，在 MATH 上达到了 60.9%。DeepSeekMath 的数学推理能力归因于两个关键因素：首先，我们通过精心设计的 数据选择 流水线，充分利用了公开网络数据的巨大潜力。其次，我们引入了 Group Relative Policy Optimization (GRPO)，这是 Proximal Policy Optimization (PPO) 的一种变体，它在增强数学推理能力的同时，优化了 PPO 的内存使用。

此训练后方法由 Quentin Gallouédec 贡献。

快速入门

本示例演示了如何使用 GRPO 方法训练模型。我们使用 DeepMath-103K 数据集 中的提示词来训练 Qwen2.5 0.5B Instruct 模型。您可以在此处查看该数据集中的数据：

以下是用于训练模型的脚本。accuracy_reward 需要 math-verify，您可以通过 pip install trl[math_verify] 进行安装。

# train_grpo.py
from datasets import load_dataset
from trl import GRPOTrainer
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)
trainer.train()

使用以下命令执行该脚本：

torchrun --nproc_per_node 8 train_grpo.py

在 8 个 GPU 上分布式训练，大约需要 1 天。

注意： 上述奖励曲线是使用 Qwen/Qwen2-0.5B-Instruct 生成的。使用 Qwen/Qwen2.5-0.5B-Instruct 的结果在定性上相似。

深入了解 GRPO 方法

GRPO 是一种在线学习算法，这意味着它通过利用训练过程中由已训练模型自身生成的数据来迭代地改进。GRPO 目标背后的直觉是最大化生成补全的优势，同时确保模型保持在参考策略附近。为了理解 GRPO 的工作原理，可以将其分解为四个主要步骤：生成补全、计算优势、估计 KL 散度以及计算损失。

生成补全

在每个训练步骤中，我们采样一批提示词，并为每个提示词生成一组 $G$ 补全（记为 $o_i$).

计算优势

对于每个 $G$ 序列，我们使用奖励模型或奖励函数来计算奖励。为了与奖励模型的比较性质保持一致——这些模型通常在针对同一问题的输出比较数据集上进行训练——优势的计算方式旨在反映这些相对比较。其归一化方式如下： $$\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}$$

这种方法赋予了该算法其名称：组相对策略优化（GRPO）。

论文 Understanding R1-Zero-Like Training: A Critical Perspective 指出，按 $\text{std}(\mathbf{r})$ 进行缩放可能会导致问题级别的难度偏差。你可以通过设置 scale_rewards=False 在 GRPOConfig. 中关闭此缩放。请注意，关闭基于 std 的缩放也会移除方差归一化，因此更新幅度将直接取决于原始奖励尺度和批次组成。

如第一部分：技巧还是陷阱？深入探讨用于 LLM 推理的 RL（Lite PPO）所示，在本地（组）级别计算均值，并在全局（批次）级别计算标准差，可以实现更稳健的奖励整形。您可以在GRPOConfig中设置scale_rewards="batch"来使用此缩放策略。

估计 KL 散度

KL 散度使用由 Schulman 等人（2020）. 引入的估计器进行估计。该估计器定义如下： $$\mathbb{D}_{\text{KL}}\left[\pi_\theta \|\pi_{\text{ref}}\right] = \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - \log \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - 1,$$

计算损失

目标是在确保模型保持接近参考策略的同时最大化优势。因此，损失函数定义如下： $$\mathcal{L}_{\text{GRPO}}(\theta) = -\frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],$$

其中第一项表示缩放后的优势值，第二项通过 KL 散度对偏离参考策略的行为进行惩罚。

请注意，与 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, 中的原始公式相比，我们不再乘以 $\frac{1}{|o_i|}$ ，因为论文 Understanding R1-Zero-Like Training: A Critical Perspective 指出这会引入响应级别的长度偏差。更多详情请参阅 损失类型.

请注意，与 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, 中原始的公式相比，我们默认使用 $\beta = 0.0$ ，这意味着不使用 KL 散度项。这一选择受到多项近期研究（例如 Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) ）的启发，这些研究表明 KL 散度项对于使用 GRPO 进行训练并非必不可少。因此，将其排除已成为常见做法（例如 Understanding R1-Zero-Like Training: A Critical Perspective, DAPO: An Open-Source LLM Reinforcement Learning System at Scale). 如果您希望包含 KL 散度项，可以将 beta 中的 GRPOConfig 设置为非零值。

在原始论文中，该公式被推广以考虑每次生成后的多次更新（记为 $\mu$, ，可通过 num_iterations 中的 GRPOConfig) 利用 截断的代理目标: $$\mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \min \left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})} \hat{A}_{i,t}, \, \text{clip}\left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})}, 1 - \epsilon, 1 + \epsilon \right) \hat{A}_{i,t} \right) - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],$$

其中 $\text{clip}(\cdot, 1 - \epsilon, 1 + \epsilon)$ 通过将策略比率限制在 $1 - \epsilon$ 和 $1 + \epsilon$. 当 $\mu = 1$ (（TRL 中的默认值）时，带裁剪的代理目标简化为原始目标。

损失类型

文献中已提出目标函数的多种表述形式。最初，GRPO 的目标函数定义如下： $$\mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} l_{i,t},$$

其中 $$l_{i,t} = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right].$$

这篇 DAPO 论文 指出了 GRPO 算法的样本级损失在长思维链（long-CoT）场景下的局限性：较长的回复受到的惩罚不足，从而导致输出质量下降。提出的解决方案是令牌级归一化，它通过为单个令牌分配更均衡的奖励，更好地处理了较长的序列，而无需考虑回复的长度： $$\mathcal{L}_{\text{DAPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},$$

要使用此公式，请在 GRPOConfig 中设置 loss_type="dapo"。

此外，论文 Understanding R1-Zero-Like Training: A Critical Perspective 证明了初始的 GRPO 公式引入了响应长度偏差。他们指出，虽然 DAPO 公式减轻了这种偏差，但并未完全消除它。为了彻底消除这种偏差，他们提出用常数代替序列长度进行除法运算，从而得到以下公式： $$\mathcal{L}_{\text{Dr. GRPO}}(\theta) = - \frac{1}{LG} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},$$

建议将此常量设置为最大生成长度。要使用此公式，请在 GRPOConfig 中设置 loss_type="dr_grpo"。

或者，在 SAPO 论文中，Qwen 团队提出用一种平滑的、温度可控的软门控机制来替代 GRPO 的“硬”裁剪机制。当策略偏离参考策略过远时，GRPO 会将梯度置零，而 SAPO 则使用一个软信任域来平滑地衰减梯度权重。这使得模型能够保留来自“近策略”（near-on-policy）标记的有用学习信号，同时抑制极端偏差带来的噪声。

损失函数定义为： $$\mathcal{L}_{\text{SAPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} f_{i,t} \left( \frac{\pi_\theta(o_{i,t} | q, o_{i,<t})}{\pi_{\theta_{old}}(o_{i,t} | q, o_{i,<t})} \right) \hat{A}_{i,t}$$

软门控函数 $f_{i,t}$ 使用 sigmoid 函数 $\sigma$ 定义如下： $$f_{i,t}(x) = \sigma \left( \tau_{i,t} (x - 1) \right) \cdot \frac{4}{\tau_{i,t}}$$

温度 $\tau_{i,t}$ 根据优势 $\hat{A}_{i,t}$: $$\tau_{i,t} = \begin{cases} \tau_{\text{pos}}, & \text{if } \hat{A}_{i,t} > 0 \\ \tau_{\text{neg}}, & \text{otherwise} \end{cases}$$

他们建议使用非对称温度， $\tau_{\text{neg}} > \tau_{\text{pos}}$ (默认值为 $\tau_{\text{pos}}=1.0, \tau_{\text{neg}}=1.05$ ). 这确保模型对“不良”动作施加更严格的惩罚以防止不稳定，同时对“良好”动作更加宽容。

要使用此公式，请在 GRPOConfig 中设置 loss_type="sapo"。

记录的指标

在训练和评估过程中，我们记录以下指标：

• num_tokens：迄今为止处理的 token 总数，包括 prompt 和 completion。使用工具时，仅统计非工具 token。
• step_time：每个训练步骤（包括生成）的平均耗时（以秒为单位）。
• completions/mean_length：生成补全的平均长度。使用工具时，仅统计非工具 token。
• completions/min_length：生成补全的最小长度。使用工具时，仅统计非工具 token。
• completions/max_length：生成补全的最大长度。使用工具时，仅计算非工具 token。
• completions/mean_terminated_length：以 EOS 终止的生成补全的平均长度。使用工具时，仅统计非工具 token。
• completions/min_terminated_length：以 EOS 终止的生成补全的最小长度。使用工具时，仅统计非工具 token。
• completions/max_terminated_length：以 EOS 终止的生成补全的最大长度。使用工具时，仅统计非工具 token。
• completions/clipped_ratio：被截断（裁剪）的补全比例。
• tools/call_frequency：生成批次中每次补全的平均工具调用次数。仅在提供 tools 时记录。
• tools/failure_frequency：工具调用失败的比例（工具未找到、抛出异常或调用类型不受支持）。当未调用任何工具时，该值为 0.0。仅在提供 tools 时记录。
• rewards/{reward_func_name}/mean：特定奖励函数的平均奖励。当环境通过 get_reward 拥有奖励时，{reward_func_name} 为环境的类名。
• rewards/{reward_func_name}/std：特定奖励函数的奖励标准差。
• reward：对各个函数的奖励求和（按 reward_weights 加权）后得到的总体平均奖励。
• reward_std：跨函数求和奖励的标准差（按 reward_weights 加权），在完整批次上计算。
• frac_reward_zero_std：生成批次中奖励标准差为零的样本比例，表明该提示词下的多样性较低（所有回答均正确或均错误）。
• sampling/sampling_logp_difference/mean：采样器（vLLM）返回的对数概率与训练模型重新计算的对数概率之间，在补全 token 上的平均绝对差值。该值增大表明训练与推理之间的不匹配正在加剧。仅在 use_vllm=True 且 vllm_importance_sampling_correction=True 时记录。
• sampling/sampling_logp_difference/max：此类绝对差值的最大值。仅在 use_vllm=True 且 vllm_importance_sampling_correction=True 时记录。
• sampling/importance_sampling_ratio/min：用于校正训练与推理不一致的最小重要性采样比率，在应用由 vllm_importance_sampling_mode 选择的约束 之后（对于 *_truncate 模式，裁剪至 [C_min, C_max]；对于 *_mask 模式，设为零）。在 completion tokens 上计算，对于 sequence_* 模式则在序列上计算。仅在 use_vllm=True 且 vllm_importance_sampling_correction=True 时记录。
• sampling/importance_sampling_ratio/mean：平均约束重要性采样比率。仅在 use_vllm=True 且 vllm_importance_sampling_correction=True 时记录。
• sampling/importance_sampling_ratio/max：最大的受限重要性采样比率。仅在 use_vllm=True 且 vllm_importance_sampling_correction=True 时记录。
• policy_loss：策略梯度损失值（未添加任何熵奖励之前）。当 entropy_coef 非零或 use_adaptive_entropy=True 时记录。
• entropy：生成的补全中 token 预测的平均熵。（如果 mask_truncated_completions=True，则排除被掩码序列的 token。）
• entropy_coef：当前的熵正则化系数。当 entropy_coef 非零或 use_adaptive_entropy=True 时记录。当 use_adaptive_entropy=True 时，每个优化器步骤更新一次。
• aux_loss：混合专家（Mixture-of-Experts）模型的负载均衡辅助损失，在乘以 router_aux_loss_coef 并加到总损失之前。仅当模型为 MoE 模型且 router_aux_loss_coef 非零时记录。
• kl：模型与参考模型之间的平均 KL 散度，基于生成的补全内容计算。仅在 beta 非零时记录。
• clip_ratio/region_mean: token（或当 importance_sampling_level="sequence") 时，sequence）的概率中，GRPO 目标被裁剪以保持在信任区域内的比例： $\text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right)\,, \quad r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})}$. 值越高，表示被裁剪的 token 越多，从而限制了策略 $\pi_\theta$ 的变化幅度。
• clip_ratio/low_mean: 被信任区域下界截断的 token（或当 importance_sampling_level="sequence") 时，为序列）概率的平均比率： $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/low_min: 每个 completion 中被截断的 token 的最小比例（如果 importance_sampling_level="sequence") importance_sampling_level="sequence"，则为序列本身）在信任区域下界处被截断： $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/high_mean: 被信任区域上界截断的 token（或当 importance_sampling_level="sequence") 时，为序列）概率的平均比率： $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• clip_ratio/high_max: 每个 completion 中被截断的 token 的最大比例（如果 importance_sampling_level="sequence") importance_sampling_level="sequence"，则为序列本身）在信任区域上界处被截断： $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• cispo_clip_ratio: 被截断的 token（或序列，如果 importance_sampling_level="sequence") 重要性采样权重在 epsilon_high 处被截断且具有正优势的比例： $r_{i,t}(\theta) > \epsilon_\mathrm{high}$. 仅在 loss_type="cispo".
• vespo/phi_seq_mean: VESPO Gamma 权重的平均值 $\varphi(w)$ 应用于序列级重要性权重。低于 1.0 的值表示序列被降权。仅在 loss_type="vespo".

自定义

使用 vLLM 驱动的生成来加速训练

在使用在线方法训练时，生成过程往往是主要的性能瓶颈。为了加速生成，你可以使用 vLLM，这是一个面向 LLM 的高吞吐量、低延迟推理引擎。要启用它，首先使用以下命令安装该包

pip install trl[vllm]

我们支持在训练期间使用 vLLM 的两种方式：服务器模式和共置模式。

默认情况下，vLLM 生成会启用序列级 Masked Importance Sampling（vllm_importance_sampling_mode="sequence_mask"），以解决使用不同框架时产生的生成-训练不匹配问题。可以通过设置 vllm_importance_sampling_correction=False 将其关闭。更多信息，请参阅 Masked Importance Sampling 和 Sequence-level Importance Sampling

选项 1：Colocate 模式

在此模式下，vLLM 在训练器进程内运行，并与训练模型共享 GPU 内存。这避免了启动单独的服务器，并可能提高 GPU 利用率，但可能导致训练 GPU 上的内存争用。这是默认模式。

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)

选项 2：服务器模式

在此模式下，vLLM 在独立进程中运行（并使用独立的 GPU），并通过 HTTP 与训练器进行通信。如果您拥有专门用于推理的 GPU，则此模式非常理想。

1. 启动 vLLM 服务器：

   已复制

   VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
       --weight-transfer-config '{"backend": "nccl"}' \
       --logprobs-mode processed_logprobs \
       --max-logprobs -1

2. 在训练脚本中启用服务器模式：

   已复制

   from trl import GRPOConfig
   
   training_args = GRPOConfig(
       ...,
       use_vllm=True,
       vllm_mode="server",
   )

请确保服务器使用的 GPU 与训练器不同，否则可能会遇到 NCCL 错误。您可以通过 CUDA_VISIBLE_DEVICES 环境变量来指定要使用的 GPU。

根据模型大小以及训练所需的整体 GPU 内存，您可能需要调整 GRPOConfig 中的 vllm_gpu_memory_utilization 参数，以避免资源利用率不足或内存溢出错误。

我们提供了一个 HF Space，用于根据您的模型配置和实验设置来估算推荐的 GPU 内存利用率。只需按以下方式使用，即可获得 vllm_gpu_memory_utilization 的推荐值：

如果推荐值在您的环境中不起作用，我们建议在推荐值上添加一个小缓冲（例如 +0.05 或 +0.1），以确保稳定性。

如果您仍然遇到内存不足错误，请将 vllm_enable_sleep_mode 设置为 True，这样在优化步骤期间，vllm 参数和缓存将被卸载。有关更多信息，请参阅 使用 vLLM Sleep Mode 减少内存使用。

默认情况下，GRPO 使用 MASTER_ADDR=localhost 和 MASTER_PORT=12345 作为 vLLM 的配置，但你可以通过相应地设置环境变量来覆盖这些值。

有关更多信息，请参阅 使用 vLLM 加速训练。

处理训练与推理之间的不匹配

虽然 vLLM 极大地加速了推理，但它也将推理引擎与训练引擎解耦。理论上，这两个引擎在数学上是完全一致的，但在实践中，由于精度效应和特定于硬件的优化，它们可能会产生不同的输出。这种差异反映了两个系统不同的优化目标。推理引擎旨在最大化采样吞吐量（通常以每秒生成的 token 数衡量），同时保持可接受的采样保真度。而训练框架则侧重于梯度计算的数值稳定性和精度，通常使用 FP32 等更高精度的格式来存储主权重和优化器状态。这些不同的优先级和约束条件，在训练和推理之间引入了不可避免的、尽管细微的失配。

这种不匹配会导致有偏的梯度更新，据观察这会 destabilize 训练（[1][2][3][4][5]). 为简化起见，考虑 REINFORCE 策略梯度： $$\nabla_\theta \mathcal{J}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{train}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right]$$

此处 $x$ 表示从某个数据分布中采样的提示词，而 $\pi^\text{train}$ 是训练引擎实现的策略。引入 vLLM 后，我们获得了一个独立的推理策略 $\pi^\text{inference}$, 因此，有效的策略梯度变为 $$\nabla_\theta \mathcal{J}_{\text{biased}}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{inference}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right].$$

这将原本属于同策略的强化学习问题转变为异策略问题。

The standard way to correct for this distribution shift is importance sampling (IS). We provide two IS variants: Truncated Importance Sampling (TIS) and Masked Importance Sampling (MIS). Both variants can be applied either at the token level or at the sequence level. Let $\rho$ denote the importance weight, for example $\rho_t$ per token or $\rho_{\text{seq}}$ per sequence. Under TIS, ratios outside of the range [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] are clipped, $$\rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}).$$

原始的 TIS 论文 提出了一种单侧上界裁剪机制，即 $\min(\rho, C_{\max})$. TRL 中的实现对此进行了推广，通过引入下界，得出了上述双侧公式，其灵感来源于 IcePop 方法。
请注意，在 IcePop 中，边界被标记为 $\alpha$ 和 $\beta$ 而在 TRL 中我们使用 $C_{\min}$ 和 $C_{\max}$.

在 MIS 中，超出此范围的比例会被设为零，因此这些样本不会对梯度产生贡献。换句话说，异常样本在 TIS 中会被降权，而在 MIS 中会被丢弃。配置标志 vllm_importance_sampling_mode 同时决定了 IS 变体（掩码或截断）以及粒度（token 级别或序列级别）。

重要性采样是对训练-推理不匹配问题的原则性算法解决方案。然而，也存在一些更直接的方法，试图减少这两个引擎本身之间的不匹配。其中大多数是工程层面的解决方案。例如，MiniMax M1 在推理引擎中使用了 FP32 语言模型头。Thinking Machines 探索了确定性推理内核，但这会带来显著的效率成本。vLLM 通过基于 Thinking Machines 的批不变确定性内核，展示了逐位一致的策略，但截至 2025 年 11 月，与标准 vLLM 推理相比，仍存在相当大的吞吐量惩罚。

使用 transformers 连续批处理加速训练

作为 vLLM 的替代方案，您可以使用 transformers 内置的连续批处理引擎来加速生成。连续批处理会立即从批次中移除已完成的序列，而不是等待最慢的序列完成。对于完成长度不固定的任务（例如数学推理），在大批次大小（N≥32）下，与默认的 generate() 相比，它能带来更快的生成速度和更低的 VRAM 占用。

连续批处理是一种即插即用的升级方案，无需配置服务器或同步权重。它在进程内运行，非常适合单 GPU 训练或内存受限的环境。若要在大规模场景下实现最高的生成吞吐量，请改用 vLLM。

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_transformers_continuous_batching=True,
    transformers_continuous_batching_config={
        "use_cuda_graph": False,
        "max_memory_percent": 0.4,  # lower values leave more VRAM for the training backward pass
    },
)

TRL 将 max_memory_percent 的默认值设为 0.5（而非 Transformers 的 0.9），以便为训练的反向传播留出足够的 VRAM。对于较大的生成批次（N≥32）或出现内存不足错误时，请将其调低至 0.3–0.4。

完整的训练示例，请参阅 examples/grpo_continuous_batching/grpo_continuous_batching.py。

大规模 GRPO：在多节点上训练 70B+ 模型

在训练 Qwen2.5-72B 这样的大模型时，你需要多项关键优化，以确保训练在多 GPU 和多节点环境下高效且可扩展。这些优化包括：

• DeepSpeed ZeRO Stage 3：ZeRO 利用数据并行将模型状态（权重、梯度、优化器状态）分布在多个 GPU 和 CPU 上，从而降低每个设备的内存和计算需求。由于大模型无法装入单个 GPU，训练此类模型必须使用 ZeRO Stage 3。更多详情请参阅 DeepSpeed Integration。
• torchrun：PyTorch 的启动器会在每个节点上的每张 GPU 上启动一个进程，并通过公共的会合点将它们连接起来。更多详情，请参阅 分布式训练。
• vLLM：请参阅上一节，了解如何使用 vLLM 来加速生成。

以下是一个使用 GRPO 在多节点上训练 70B 模型的 SLURM 脚本示例。该脚本在 4 个节点上训练模型，并使用第 5 个节点进行基于 vLLM 的生成。

#!/bin/bash
#SBATCH --nodes=5
#SBATCH --gres=gpu:8

# Get the list of allocated nodes
NODELIST=($(scontrol show hostnames $SLURM_JOB_NODELIST))

# Assign the first 4 nodes for training and the 5th node for vLLM
TRAIN_NODES="${NODELIST[@]:0:4}"  # Nodes 0, 1, 2, 3 for training
VLLM_NODE="${NODELIST[4]}"  # Node 4 for vLLM

# Run training on the first 4 nodes (Group 1)
srun --nodes=4 --ntasks=4 --nodelist="${NODELIST[@]:0:4}" torchrun \
     --nnodes 4 \
     --nproc_per_node 8 \
     --node_rank $SLURM_PROCID \
     --rdzv_backend c10d \
     --rdzv_endpoint ${NODELIST[0]}:29500 \
     train_grpo.py \
     --server_ip $VLLM_NODE &

# Run vLLM server on the 5th node (Group 2)
srun --nodes=1 --ntasks=1 --nodelist="${NODELIST[4]}" env VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-72B --tensor-parallel-size 8 \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1 &

wait

import argparse

from datasets import load_dataset
from trl import GRPOTrainer, GRPOConfig
from trl.rewards import accuracy_reward

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--vllm_server_host", type=str, default="", help="The server IP")
    args = parser.parse_args()

    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

    training_args = GRPOConfig(
        per_device_train_batch_size=4,
        deepspeed="examples/deepspeed_configs/zero3.json",
        use_vllm=True,
        vllm_mode="server",
        vllm_server_host=args.vllm_server_host.replace("ip-", "").replace("-", "."),  # from ip-X-X-X-X to X.X.X.X
    )

    trainer = GRPOTrainer(
        model="Qwen/Qwen2.5-72B",
        args=training_args,
        reward_funcs=accuracy_reward,
        train_dataset=dataset
    )
    trainer.train()

if __name__=="__main__":
    main()

使用自定义奖励函数

GRPOTrainer 支持使用自定义奖励函数，而非稠密奖励模型。为确保兼容性，您的奖励函数必须满足以下要求：

奖励函数可以是同步的 Python 可调用对象，也可以是异步的 async def 协程。当您提供多个异步奖励函数时，它们会被并发等待（通过 asyncio.gather 并行执行），从而使它们的延迟相互重叠。

1. 输入参数：

   • 该函数必须接受以下关键字参数：

     • prompts（包含提示词），
     • completions（包含生成的补全内容），
     • completion_ids（包含分词后的补全内容），
     • trainer_state (TrainerState)：训练器的当前状态。可用于实现动态奖励函数，例如课程学习，其中奖励会根据训练进度进行调整。
     • log_extra：一个可调用对象 log_extra(column: str, values: list)，用于向 completions 表添加额外的列。参见示例 6。
     • log_metric：一个可调用对象 log_metric(name: str, value: float)，用于将标量指标记录为图表，与 kl、entropy 等并列显示。参见示例 6。
     • environments：环境实例列表，每个 completion 对应一个。仅在提供了 environment_factory 时存在。使用此参数来读取回合期间累积的状态（例如 env.counter）。对于有状态的环境，建议通过 get_reward 方法让环境自身管理奖励——参见 奖励。
     • 数据集可能包含的所有列名（prompt 除外）。例如，如果数据集包含名为 ground_truth 的列，则函数将以 ground_truth 作为关键字参数被调用。

     满足此要求的最简单方法是在函数签名中使用 **kwargs。

   • 根据数据集格式的不同，输入会有所不同：

     • 对于标准格式，prompts和completions将是字符串列表。
     • 对于对话格式，prompts和completions将是消息字典的列表。

2. 返回值：该函数必须返回一个浮点数列表。每个浮点数代表对应单个补全的奖励。

示例 1：奖励更长的补全

以下是一个标准格式奖励函数的示例，该函数会奖励更长的补全：

def reward_func(completion_ids, **kwargs):
    """Reward function that assigns higher scores to longer completions (in terms of token count)."""
    return [float(len(ids)) for ids in completion_ids]

您可以按以下方式测试：

>>> prompts = ["The sky is", "The sun is"]  # not used in the reward function, but the trainer will pass it
>>> completions = [" blue.", " in the sky."]  # not used in the reward function, but the trainer will pass it
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[2.0, 4.0]

示例 1.1：奖励更长的补全（基于字符数）

与上一个示例相同，但这次奖励函数基于字符数而非 token 数。

def reward_func(completions, **kwargs):
    """Reward function that assigns higher scores to longer completions (in terms of character count)."""
    return [float(len(completion)) for completion in completions]

您可以按以下方式测试：

>>> prompts = ["The sky is", "The sun is"]
>>> completions = [" blue.", " in the sky."]
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]  # not used in the reward function, but the trainer will pass it
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[6.0, 12.0]

示例 2：奖励具有特定格式的补全

以下是一个奖励函数的示例，用于检查补全内容是否具有特定格式。该示例受论文 DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning 中使用的 format reward 函数启发。 它专为对话格式设计，其中提示和补全内容均由结构化消息组成。

import re

def format_reward_func(completions, **kwargs):
    """Reward function that checks if the completion has a specific format."""
    pattern = r"^<think>.*?</think><answer>.*?</answer>$"
    completion_contents = [completion[0]["content"] for completion in completions]
    matches = [re.match(pattern, content) for content in completion_contents]
    return [1.0 if match else 0.0 for match in matches]

您可以按以下方式测试此函数：

>>> prompts = [
...     [{"role": "user", "content": "What is the result of (1 + 2) * 4?"}],
...     [{"role": "user", "content": "What is the result of (3 + 1) * 2?"}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": "<think>The sum of 1 and 2 is 3, which we multiply by 4 to get 12.</think><answer>(1 + 2) * 4 = 12</answer>"}],
...     [{"role": "assistant", "content": "The sum of 3 and 1 is 4, which we multiply by 2 to get 8. So (3 + 1) * 2 = 8."}],
... ]
>>> format_reward_func(prompts=prompts, completions=completions)
[1.0, 0.0]

示例 3：基于参考的奖励完成

以下是一个奖励函数的示例，用于检查补全内容是否正确。该示例受论文 DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning 中使用的 accuracy reward 函数启发。 此示例针对 standard format 设计，其中数据集包含一个名为 ground_truth 的列。

import re

def reward_func(completions, ground_truth, **kwargs):
    # Regular expression to capture content inside \boxed{}
    matches = [re.search(r"\\boxed\{(.*?)\}", completion) for completion in completions]
    contents = [match.group(1) if match else "" for match in matches]
    # Reward 1 if the content is the same as the ground truth, 0 otherwise
    return [1.0 if c == gt else 0.0 for c, gt in zip(contents, ground_truth)]

您可以按以下方式测试此函数：

>>> prompts = ["Problem: Solve the equation $2x + 3 = 7$. Solution:", "Problem: Solve the equation $3x - 5 = 10$."]
>>> completions = [r" The solution is \boxed{2}.", r" The solution is \boxed{6}."]
>>> ground_truth = ["2", "5"]
>>> reward_func(prompts=prompts, completions=completions, ground_truth=ground_truth)
[1.0, 0.0]

示例 4：多任务奖励函数

以下是在 GRPOTrainer 中使用多个奖励函数的示例。在此示例中，我们定义了两个针对特定任务的奖励函数：math_reward_func 和 coding_reward_func。math_reward_func 根据数学问题的正确性给予奖励，而 coding_reward_func 则根据代码解决方案是否可运行来给予奖励。

from datasets import Dataset
from trl import GRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": "What is 2+2?", "task": "math"},
        {"prompt": "Write a function that returns the sum of two numbers.", "task": "code"},
        {"prompt": "What is 3*4?", "task": "math"},
        {"prompt": "Write a function that returns the product of two numbers.", "task": "code"},
    ]
)

# Math-specific reward function
def math_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "math":
            # Calculate math-specific reward
            correct = check_math_solution(prompt, completion)
            reward = 1.0 if correct else -1.0
            rewards.append(reward)
        else:
            # Return None for non-math tasks
            rewards.append(None)
    return rewards

# Coding-specific reward function
def coding_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "code":
            # Calculate coding-specific reward
            works = test_code_solution(prompt, completion)
            reward = 1.0 if works else -1.0
            rewards.append(reward)
        else:
            # Return None for non-coding tasks
            rewards.append(None)
    return rewards

# Use both task-specific reward functions
trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=[math_reward_func, coding_reward_func],
    train_dataset=dataset,
)

trainer.train()

在此示例中，math_reward_func 和 coding_reward_func 旨在配合包含数学和编程问题的混合数据集使用。数据集中的 task 列用于确定对每个问题应用哪个奖励函数。如果数据集中的某个样本没有相关的奖励函数，该奖励函数将返回 None，GRPOTrainer 将继续使用有效的函数和任务。这使得 GRPOTrainer 能够处理具有不同适用性的多个奖励函数。

请注意，GRPOTrainer 会忽略奖励函数返回的 None 奖励，仅考虑相关函数返回的奖励。这确保了模型在相关任务上进行训练，并忽略没有相关奖励函数的任务。

示例 5：异步奖励函数

自定义奖励函数也可以定义为 async def 协程。如果您的奖励依赖于缓慢的 I/O（例如，调用远程服务），这将非常有用。当您传入多个异步奖励函数时，GRPOTrainer 会并发执行它们，从而使它们的延迟相互重叠。

以下是一个异步奖励函数的最小示例，用于模拟 I/O 密集型操作：

import asyncio

async def async_reward_func(prompts, completions, **kwargs):
    # Simulate an I/O-bound call (e.g., HTTP request, database lookup)
    await asyncio.sleep(0.01)
    # Simple toy reward: 1.0 if the completion is non-empty, else 0.0
    return [1.0 if completion else 0.0 for completion in completions]

示例 6：记录额外的列和指标

以下是一个奖励函数的示例，该函数会将额外的列记录到 completions 表中，并将标量指标记录为图表。

import re

def reward_func(completions, ground_truth, log_extra=None, log_metric=None, **kwargs):
    extracted = [re.search(r"\\boxed\{(.*?)\}", c) for c in completions]
    extracted = [m.group(1) if m else None for m in extracted]
    rewards = [1.0 if e == gt else 0.0 for e, gt in zip(extracted, ground_truth)]

    if log_extra:
        log_extra("golden_answer", list(ground_truth))
        log_extra("extracted_answer", [e or "[none]" for e in extracted])

    if log_metric:
        log_metric("accuracy", sum(rewards) / len(rewards))

    return rewards

将奖励函数传递给训练器

要将自定义奖励函数用于 GRPOTrainer，请按以下方式传入：

from trl import GRPOTrainer

trainer = GRPOTrainer(
    reward_funcs=reward_func,
    ...,
)

您可以将多个奖励函数作为列表传入；该列表可以同时包含同步函数和异步函数：

from trl import GRPOTrainer

trainer = GRPOTrainer(
    reward_funcs=[reward_func, async_reward_func1, async_reward_func2],
    ...,
)

奖励将计算为每个函数奖励的总和，或者如果配置中提供了reward_weights，则为加权总和。

请注意，GRPOTrainer 支持多种不同类型的奖励函数。有关更多详细信息，请参阅参数文档。

熵正则化

为了鼓励探索并防止策略坍缩为近确定性输出，您可以在训练目标中添加熵奖励。熵正则化对 GRPO 损失的增强方式如下： $$\mathcal{L}(\theta) = \mathcal{L}_{\text{GRPO}}(\theta) - \alpha \cdot \mathcal{H}(\pi_\theta),$$

其中$\mathcal{H}(\pi_\theta)$ 是策略的平均逐 token 熵，$\alpha$ 是熵系数。无论 loss_type; 为何，该奖励始终为平均逐 token 熵， batch_size * max_completion_length 它不会根据损失类型的策略归一化进行重新缩放（例如 Dr. GRPO 的 entropy_coef 分母），因此

静态熵 — 整个训练过程中保持固定的系数：

from trl import GRPOConfig, GRPOTrainer

training_args = GRPOConfig(entropy_coef=0.05, ...)

自适应熵 — 系数会根据目标熵在每个优化器步骤中更新，如 Skywork-OR1 中所介绍。当当前熵小于或等于 entropy_target 时，系数增加 entropy_coef_delta；否则减少。仅当熵小于或等于目标值时，该系数才会生效（即非零）：

training_args = GRPOConfig(
    entropy_coef=0.01,          # initial coefficient
    use_adaptive_entropy=True,
    entropy_target=5.0,         # target mean per-token entropy (nats); tune for your model
    entropy_coef_delta=0.005,   # step size per optimizer step
    entropy_coef_min=0.0,
    entropy_coef_max=1.0,
    ...
)

典型的语言模型每个 token 的熵通常在 2–10 nats 之间，因此默认的 entropy_target=0.2 几乎不会触发正则化——只有当熵降至目标值或更低时（即接近完全坍缩时），该奖励才会生效。请将其设置为对您的模型有意义的值，例如接近训练初期观察到的熵值（记录为 entropy 指标）。当使用 top_entropy_quantile < 1.0 时，entropy_target 应用于高熵 token 子集——该子集的熵会高于记录的全量 token entropy，因此请据此进行校准。

当 use_adaptive_entropy=True 时，当前的熵系数 entropy_coef 会随每个检查点一起保存，并在恢复时还原，因此训练完全可恢复。

GRPO 的快速实验

RapidFire AI 是一个构建在 TRL 之上的开源实验引擎，允许你同时启动多个 GRPO 配置，即使只有一块 GPU 也是如此。与按顺序尝试配置不同，RapidFire 让你能够更早地查看所有配置的学习曲线，停止表现不佳的运行，并在运行过程中克隆有前景的配置并应用新设置，而无需重启。有关更多信息，请参阅 RapidFire AI Integration。

Agent 训练

GRPO 支持智能体训练：模型在生成过程中调用工具，并根据结果进行学习。

• 工具是暴露给模型的普通 Python 函数（同步或异步）。对于无状态调用（如计算器、网络搜索），请使用 tools。
• 环境是更通用的形式：一个在每次 rollout 时全新构建的有状态对象，其公开方法作为工具暴露，并包含一个 reset 生命周期钩子以及一个可选的 get_reward，使其能够自行管理奖励。当您需要每次 rollout 的独立状态、重置钩子或由环境管理的奖励时，请使用 environment_factory。

它们可以组合使用——你可以在 environment_factory 旁边传入独立的 tools。

工具

tools 参数需要一个 Python 函数（同步或异步）列表，用于定义智能体可用的工具：

from trl import GRPOTrainer

trainer = GRPOTrainer(
    tools=[tool1, tool2],
    ...,
)

每个工具必须是一个标准的 Python 函数，具有带类型提示的参数和返回类型，并附带一个Google 风格的 docstring，用于描述其用途、参数和返回值。 有关更多详细信息，请参阅传递工具指南。

GRPO 工具调用循环要求聊天模板是前缀保持的（追加一条工具消息时，不得改变之前消息的渲染方式）。对于已知的模型系列（例如 Qwen3、DeepSeek-V3），当启用工具时，TRL 会自动替换为经过修补的训练模板。完整的列表请参阅聊天模板。

在 GRPOConfig 中使用 max_tool_calling_iterations 来限制工具调用轮次的数量。默认情况下没有上限，生成会在以下情况停止：模型生成了一轮不包含任何工具调用的响应；补全内容（所有轮次和工具结果）达到 max_completion_length 个 token；或者完整序列达到模型的最大长度（在 vllm_mode="colocate" 下为 vllm_max_model_length，否则为模型的 max_position_embeddings）。

示例：

from trl import GRPOTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

async def async_add(a: int, b: int) -> int:
    """
    Asynchronously adds two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The sum of the two integers.
    """
    return a + b

trainer = GRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

环境

你还可以通过 environment_factory 提供工具。在此模式下，GRPOTrainer 会为每个 rollout 创建一个环境实例，并将该环境的公开方法作为工具暴露出来。

environment_factory 需要 transformers>=5.2.0。

使用 environment_factory 时，环境拥有数据：不存在外部的 train_dataset。在每次 rollout 中，reset() 会生成任务——从环境持有的语料库中自采样，或以程序化方式生成状态——并返回提示词。max_steps 设置训练长度。以下是一个最小示例，展示了一个自采样目标并暴露 increment 方法（作为工具暴露）的环境。

import random

from trl import GRPOConfig, GRPOTrainer

class IncrementEnv:
    # Reserved methods
    def reset(self, **kwargs) -> str | None:  # required; called at the start of each rollout
        self.counter = 0
        self.target = random.randint(1, 6)  # self-sample the task
        return f"Increment the counter by {self.target}."  # returned string becomes the prompt

    def get_reward(self) -> float:  # optional: the environment scores itself from its own state
        return float(self.counter == self.target)

    # Public methods (exposed as tools)
    def increment(self, step: int) -> int:
        """
        Increment the internal counter.

        Args:
            step: Value to add to the counter.

        Returns:
            The updated counter value.
        """
        self.counter += step
        return self.counter

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
    environment_factory=IncrementEnv,
)
trainer.train()

环境类有两个保留方法：reset 和 get_reward。与其他任何公共方法不同，这些方法不会作为工具暴露给模型。

• reset（必需）在 rollout 开始时被调用。它可以返回 None 或一个字符串。在 GRPO 中，当它返回一个字符串时，该字符串即为用户提示词。
• get_reward（可选，同步或异步）不接收任何参数，并返回一个 float：环境根据其自身的内部状态对刚刚运行的回合进行评分（游戏是否以胜利结束？单词是否被猜中？）。它在每个完成的 rollout 中被调用一次，并作为奖励来源。

由于环境在每次 reset() 时进行自采样，GRPO 组中的 G 个成员可能不共享相同的初始状态，这使得组基线略微更具噪声。对于组内相同的状态，请让 reset() 从共享的键中确定性地派生状态。

提供外部数据集（可选）

与其让环境自行采样，您可以提供一个外部的 train_dataset。例如，当您的任务已经存在于数据集中，或者需要在 多个环境 之间进行路由时。在每次 rollout 中，训练器会采样一行，将其 "prompt" 列用作提示，并将该行的其他列作为关键字参数传递给 reset()（以便环境从数据集中读取任务）。

from datasets import Dataset
from trl import GRPOTrainer

# Each row carries the prompt and the task data (here, the counter target to reach).
dataset = Dataset.from_dict(
    {
        "prompt": [[{"role": "user", "content": f"Increment the counter to {i}."}] for i in range(1, 7)],
        "target": list(range(1, 7)),
    }
)

class IncrementEnv:
    def reset(self, target, **kwargs) -> None:  # the row's `target` column arrives as a keyword argument
        self.counter = 0
        self.target = target

    def get_reward(self) -> float:
        return float(self.counter == self.target)

    def increment(self, step: int) -> int:  # exposed as a tool (see the full docstring above)
        self.counter += step
        return self.counter

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=dataset,  # the dataset owns the task; the "target" column reaches reset(target=...)
    environment_factory=IncrementEnv,
)
trainer.train()

奖励

环境拥有的奖励和训练器拥有的奖励并非互斥。对于从补全结果中自然计算得出的奖励（例如对文本进行格式检查），请传入 reward_funcs，并让环境通过 get_reward 返回其状态相关的奖励。所有来源的奖励将被求和；reward_weights 仅适用于 reward_funcs（环境拥有自己的缩放比例）。

def format_reward(completions, **kwargs):  # trainer-owned: scores the completion text
    ...

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(max_steps=1000),
    reward_funcs=format_reward,          # trainer-owned: scores the completion
    environment_factory=IncrementEnv,    # env-owned: scores its internal state via `get_reward`
)

reward_func 也可以直接读取环境状态：当设置了 environment_factory 时，训练器会传入一个 environments 关键字参数（每个 completion 对应一个实例）。这在某些情况下有用，但对于依赖状态的奖励，建议优先使用 get_reward。

对于 AsyncGRPOTrainer，其工作方式完全相同。

多个环境

要在单次运行中混合训练多种任务（例如编码任务和游戏任务），请传入一个将环境名称映射到工厂的字典，而不是单个可调用对象。每次 rollout 都会通过数据集中的 environment 字段选择其环境，并且 仅暴露该环境的工具。这可以避免泄露无关工具（例如将游戏的 move 工具暴露给编码示例，反之亦然）。每个环境仍然拥有自己的数据，并从 reset() 返回提示，因此数据集只需要 environment 列来在它们之间进行路由。

import random

from datasets import Dataset
from trl import GRPOConfig, GRPOTrainer


class CodingEnv:
    def reset(self, **kwargs) -> str:
        n = random.randint(1, 20)
        return f"Compute the {n}th Fibonacci number."

    def run_code(self, code: str) -> str:  # exposed as a tool only for "coding" examples
        """Run the given Python code and return its stdout.

        Args:
            code: The Python source to execute.

        Returns:
            The captured standard output.
        """
        ...

class GameEnv:
    def reset(self, **kwargs) -> str:
        return "Reach the goal tile."

    def move(self, action: str) -> str:  # exposed as a tool only for "game" examples
        """Apply an action to the game and return the new observation.

        Args:
            action: One of "up", "down", "left", "right".

        Returns:
            The observation after the move.
        """
        ...

# The dataset only routes: each row picks the environment for that rollout
dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(chat_template_kwargs={"enable_thinking": False}),
    train_dataset=dataset,
    reward_funcs=reward_func,
    environment_factory={"coding": CodingEnv, "game": GameEnv},
)
trainer.train()

奖励函数仍然通过 reward_kwargs["environments"] 接收每个示例的环境，因此可以根据环境类型进行分支处理（例如 isinstance(env, CodingEnv)）。环境实例会在多个步骤之间复用（在回合之间重置），因此昂贵的 __init__ 只需支付一次，而不是每个步骤都支付。environment 字段由训练器消费，并且 不会 转发给 reset。

多模态工具响应

工具可以通过返回内容块列表，在文本之外同时返回图像。这在 VLM 智能体训练中非常有用，因为工具可以提供视觉反馈（例如，屏幕截图、图表、摄像头捕获）。

from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]

返回的图像会自动注入到对话中，并传递给 VLM 用于后续的生成轮次。

支持的模型

已测试：

• Beam — 例如 reflection/Beam-1.0-501B-A23B
• DeepSeek-R1 — 例如 deepseek-ai/DeepSeek-R1
• Gemma4 — 例如 google/gemma-4-E2B-it
• GLM-4-MoE（4.5、4.6 或 4.7）——例如 zai-org/GLM-4.7
• GPT-OSS — 例如 openai/gpt-oss-20b
• Llama 3.1 — 例如 meta-llama/Llama-3.1-8B-Instruct
• Llama 3.2 — 例如 meta-llama/Llama-3.2-3B-Instruct
• Qwen2.5 — 例如 Qwen/Qwen2.5-0.5B-Instruct
• Qwen3 — 例如 Qwen/Qwen3-0.6B
• Qwen3-VL — 例如 Qwen/Qwen3-VL-2B-Instruct
• Qwen3.5 — 例如 Qwen/Qwen3.5-2B
• Qwen3.6 — 例如 Qwen/Qwen3.6-35B-A3B

不保证与所有 LLM 兼容。如果您认为某个模型应当被支持，欢迎在 GitHub 上提交 issue——或者更好的是，提交一个包含所需更改的 pull request。

环境集成

所有环境都接入同一个 environment_factory 插槽，因此在 TRL 层面它们可以互换——选择与你的任务生态相匹配的那个即可：

训练视觉语言模型

GRPO 支持在包含文本和图像的多模态数据集上训练视觉语言模型（VLM）。

支持的模型

已测试：

• Gemma3 — 例如 google/gemma-3-4b-it
• LLaVA-NeXT — 例如 llava-hf/llava-v1.6-mistral-7b-hf
• Qwen2-VL — 例如 Qwen/Qwen2-VL-2B-Instruct
• Qwen2.5-VL — 例如 Qwen/Qwen2.5-VL-3B-Instruct
• SmolVLM2 — 例如 HuggingFaceTB/SmolVLM2-2.2B-Instruct

无法保证与所有 VLM 的兼容性。如果您认为某个模型应当被支持，欢迎在 GitHub 上提交 issue——或者更好的是，提交一个包含所需更改的 pull request。

快速入门

使用 grpo_vlm.py 对 VLM 进行微调。在 lmms-lab/multimodal-open-r1-8k-verified 上训练的示例命令：

torchrun --nproc_per_node 8 examples/grpo_visual_math/grpo_visual_math.py \
  --deepspeed examples/deepspeed_configs/zero3.json \
  --model_name_or_path Qwen/Qwen2.5-VL-3B-Instruct \
  --output_dir grpo-Qwen2.5-VL-3B-Instruct \
  --learning_rate 1e-5 \
  --dtype bfloat16 \
  --max_completion_length 1024 \
  --use_vllm \
  --vllm_mode colocate \
  --use_peft \
  --lora_target_modules "q_proj", "v_proj" \
  --log_completions

配置技巧

• 在视觉-语言投影层上使用 LoRA
• 启用 4 位量化以降低内存使用
• VLM 对内存需求较高 — 请从较小的批处理大小开始
• 大多数模型都兼容 vLLM（server 和 colocate 模式）

数据集格式

每个训练样本应包含：

• prompt：通过处理器的聊天模板格式化的文本
• image/images：PIL Image 或 PIL Image 列表

Trainer 会通过模型的图像处理器自动处理图像到张量的转换。

GRPOTrainer

>>> from trl import GRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

>>> trainer = GRPOTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     reward_funcs=accuracy_reward,
...     train_dataset=dataset,
... )
>>> trainer.train()

GRPOConfig