TRL documentation

GRPO Trainer

You are viewing v1.18.0 version. A newer version v1.18.1 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

GRPO Trainer

model badge

概要

TRLは、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に記載されている通り、言語モデルの学習のためのGRPO Trainerをサポートしています。

論文の要旨は以下の通りです:

数学的推論は、その複雑で構造化された性質ゆえに、言語モデルにとって大きな課題となっています。本論文では、Common Crawlから収集した120Bの数学関連トークンと、自然言語およびコードデータを組み合わせて、DeepSeek-Coder-Base-v1.5 7Bの事前学習を継続したDeepSeekMath 7Bを提案します。DeepSeekMath 7Bは、外部ツールキットや投票手法に頼らず、コンペティションレベルのMATHベンチマークで51.7%という優れたスコアを達成し、Gemini-UltraやGPT-4の性能レベルに迫る結果となりました。DeepSeekMath 7Bからの64サンプルに対する自己整合性(Self-consistency)により、MATHでは60.9%を達成しています。DeepSeekMathの数学的推論能力は、主に2つの要因に帰因されます。第一に、綿密に設計されたデータ選択パイプラインを通じて、公開されているWebデータの大きな可能性を引き出しています。第二に、Proximal Policy Optimization (PPO) のバリアントであるGroup Relative Policy Optimization (GRPO) を導入し、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日かかります。

GRPO curves

注: 上記の報酬曲線はQwen/Qwen2-0.5B-Instructを使用して生成されました。Qwen/Qwen2.5-0.5B-Instructの場合の結果も、定性的には類似するものと予想されます。

GRPO手法をより深く掘り下げる

GRPOはオンライン学習アルゴリズムであり、学習中に訓練済みモデル自体が生成したデータを用いて反復的に改善します。GRPOの目的関数の直感は、生成された補完のアドバンテージを最大化しつつ、モデルが参照ポリシーに近いままであることを保証することです。GRPOの動作を理解するには、補完の生成、アドバンテージの計算、KLダイバージェンスの推定、損失の計算という4つの主要なステップに分解できます。

GRPO visual

補完の生成

各トレーニングステップにおいて、プロンプトのバッチをサンプリングし、各プロンプトに対して G G の補完を生成します( oi o_i ).

アドバンテージの計算

各 G G シーケンスについて、報酬モデルまたは報酬関数を使用して報酬を計算します。報酬モデルの比較的特性(同じ質問に対する出力の比較で構成されるデータセットで通常訓練される)に合わせて、アドバンテージはこれらの相対的な比較を反映するように計算されます。以下のように正規化されます: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

このアプローチが、この手法にグループ相対方策最適化(GRPO)という名前を与えています。

論文 Understanding R1-Zero-Like Training: A Critical Perspective では、 std(r) \text{std}(\mathbf{r}) によるスケーリングが、問題レベルの難易度バイアスを引き起こす可能性があることが示されています。 scale_rewards=False の GRPOConfig. で、このスケーリングを無効にできます。ただし、std ベースのスケーリングをオフにすると分散の正規化も無効になるため、更新の大きさが生の報酬スケールとバッチの構成に直接依存する点にご注意ください。

Part I: Tricks or Traps? A Deep Dive into RL for LLM Reasoning (Lite PPO) に示されているように、平均をローカル(グループ)レベルで、標準偏差をグローバル(バッチ)レベルで計算することで、より堅牢な報酬シェーピングが可能になります。GRPOConfig で scale_rewards="batch" を設定することで、このスケーリング戦略を使用できます。

KLダイバージェンスの推定

KL 分散は、 Schulman et al. (2020). によって導入された近似推定器を用いて推定されます。この近似推定器は以下のように定義されます: DKL[πθ∥πref]=πref(oi,t∣q,oi,<t)πθ(oi,t∣q,oi,<t)−log⁡πref(oi,t∣q,oi,<t)πθ(oi,t∣q,oi,<t)−1,\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,

損失の計算

目的は、モデルが参照ポリシーに近くなることを保証しながら、アドバンテージを最大化することです。したがって、損失は以下のように定義されます。 LGRPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣[πθ(oi,t∣q,oi,<t)[πθ(oi,t∣q,oi,<t)]no gradA^i,t−βDKL[πθ∥πref]], \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],

ここで、第1項はスケーリングされたアドバンテージを表し、第2項はKLダイバージェンスを通じて参照ポリシーからの逸脱をペナルティとして課します。

元の DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, とは異なり、 1∣oi∣ \frac{1}{|o_i|} でスケールしていません。これは、論文 Understanding R1-Zero-Like Training: A Critical Perspective で、これによりレスポンスレベルの長さバイアスが生じることが示されているためです。詳細は 損失の種類.

元の DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, では、デフォルトで β=0.0 \beta = 0.0 を使用しており、KL 分散の項は使用されません。この選択は、GRPO による学習において KL 分散の項が必須ではないことを示した最近の複数の研究(例: Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) )によって裏付けられています。その結果、KL 分散の項を除外することが一般的な做法となっています(例: 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) クリップされたサロゲート目的関数 を活用することで設定できます: LGRPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣[min⁡(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t)A^i,t, clip(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t),1−ϵ,1+ϵ)A^i,t)−βDKL[πθ∥πref]], \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],

ここで clip(⋅,1−ϵ,1+ϵ)\text{clip}(\cdot, 1 - \epsilon, 1 + \epsilon) は、ポリシー比を 1−ϵ 1 - \epsilon と 1+ϵ 1 + \epsilon . の間で制限することで、更新が参照ポリシーから過度に逸脱しないようにします。 μ=1 \mu = 1 (TRL のデフォルトである

損失の種類

文献では、目的関数のいくつかの定式化が提案されています。当初、GRPOの目的関数は次のように定義されていました: LGRPO(θ)=−1G∑i=1G1∣oi∣∑t=1∣oi∣li,t, \mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} l_{i,t},

ここで li,t=πθ(oi,t∣q,oi,<t)[πθ(oi,t∣q,oi,<t)]no gradA^i,t−βDKL[πθ∥πref]. 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論文 は、長いCoTシナリオにおけるGRPOアルゴリズムのサンプルレベル損失の限界を指摘しています。このシナリオでは、長い応答が過小にペナルティされ、結果として出力品質が低下します。提案された解決策はトークンレベルの正規化であり、応答の長さに関係なく個々のトークンにバランスの取れた報酬を割り当てることで、長いシーケンスをより適切に扱います。 DAPO LDAPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣li,t, \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 定式化はこのバイアスを軽減しますが、完全に排除するわけではありません。このバイアスを完全に除去するために、シーケンス長ではなく定数で割ることを提案し、以下の定式化が得られます: LDr. GRPO(θ)=−1LG∑i=1G∑t=1∣oi∣li,t, \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はソフトな信頼領域を用いて勾配の重みを滑らかに減衰させます。これにより、モデルは「ほぼオンポリシー」なトークンから有用な学習シグナルを保持しつつ、極端な逸脱によるノイズを抑制できます。

損失関数は以下のように定義されます。 LSAPO(θ)=−1G∑i=1G1∣oi∣∑t=1∣oi∣fi,t(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t))A^i,t \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}

ソフトゲーティング関数 fi,t f_{i,t} は、シグモイド関数 σ \sigma を用いて以下のように定義されます。 fi,t(x)=σ(τi,t(x−1))⋅4τi,t f_{i,t}(x) = \sigma \left( \tau_{i,t} (x - 1) \right) \cdot \frac{4}{\tau_{i,t}}

温度 τi,t \tau_{i,t} は、アドバンテージ A^i,t \hat{A}_{i,t} : τi,t={τpos,if A^i,t>0τneg,otherwise \tau_{i,t} = \begin{cases} \tau_{\text{pos}}, & \text{if } \hat{A}_{i,t} > 0 \\ \tau_{\text{neg}}, & \text{otherwise} \end{cases}

非対称の温度の使用を推奨しています。 τneg>τpos \tau_{\text{neg}} > \tau_{\text{pos}} (デフォルト値は τpos=1.0,τneg=1.05 \tau_{\text{pos}}=1.0, \tau_{\text{neg}}=1.05 ). これにより、不安定性を防ぐために「悪い」アクションに対してより厳しくペナルティを科し、「良い」アクションに対してはより寛容になるようにモデルが設計されます。

この定式化を使用するには、GRPOConfigでloss_type="sapo"を設定してください。

記録されたメトリクス

学習と評価の実行中、以下のメトリクスを記録します:

  • num_tokens: プロンプトと補完の両方を含む、これまでに処理されたトークンの総数です。ツールを使用している場合、ツール以外のトークンのみがカウントされます。
  • step_time: 1回の学習ステップ(生成を含む)に要する平均時間(秒)。
  • completions/mean_length: 生成された補完の平均長さ。ツールを使用している場合、ツール以外のトークンのみがカウントされます。
  • completions/min_length: 生成される補完の最小長。ツールを使用する場合、ツール以外のトークンのみがカウントされます。
  • completions/max_length: 生成される補完の最大長。ツールを使用する場合、カウントされるのはツール以外のトークンのみです。
  • completions/mean_terminated_length: EOSで終了した生成済み補完の平均長さ。ツールを使用している場合、ツール以外のトークンのみがカウントされます。
  • completions/min_terminated_length: EOSで終了する生成された補完の最小長。ツールを使用している場合、ツール以外のトークンのみがカウントされます。
  • completions/max_terminated_length: EOSで終了する生成された補完の最大長。ツールを使用している場合、カウントされるのはツール以外のトークンのみです。
  • completions/clipped_ratio: 切り詰められた(クリップされた)補完の割合。
  • tools/call_frequency: 生成バッチにおける1回のコンプリーションあたりのツール呼び出しの平均回数。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)が返す対数確率と、学習モデルによって再計算された対数確率の間の、完了トークンにおける平均絶対差。値が増加している場合、学習と推論の不一致が拡大していることを示します。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 モードではゼロに設定されます)。sequence_* モードではシーケンス単位で、それ以外のモードでは completion トークン単位で計算されます。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: 生成された補完全体にわたるトークン予測の平均エントロピー。(mask_truncated_completions=Trueの場合、マスクされたシーケンスのトークンは除外されます。)
  • entropy_coef: 現在のエントロピー正則化係数。entropy_coefがゼロでない場合、またはuse_adaptive_entropy=Trueの場合に記録されます。use_adaptive_entropy=Trueの場合、オプティマイザーステップごとに1回更新されます。
  • aux_loss: Mixture-of-Experts モデルのロードバランス用の補助損失。router_aux_loss_coef によってスケーリングされ、損失に追加される前の値です。モデルが MoE モデルであり、router_aux_loss_coef がゼロでない場合にのみ記録されます。
  • kl: 生成された補完に対して計算される、モデルと参照モデルの間の平均KLダイバージェンス。betaがゼロでない場合のみ記録されます。
  • clip_ratio/region_mean: GRPO の目的関数が信頼領域内に留まるようにクリップされるトークン(または importance_sampling_level="sequence") の確率の比率: clip(ri,t(θ),1−ϵlow,1+ϵhigh) ,ri,t(θ)=πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t) \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})} . 値が高いほど、クリップされるトークンが増え、ポリシー πθ\pi_\theta が変更できる範囲が制限されます。
  • clip_ratio/low_mean: トークン(または、 importance_sampling_level="sequence") が設定されている場合はシーケンス)の確率のうち、トラストリージョンの下限でクリップされたものの平均比率: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: 1回の生成あたりのトークンの最小割合(または、 importance_sampling_level="sequence") が信頼領域の下限でクリップされた場合、シーケンス全体): ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: トークン(または、 importance_sampling_level="sequence") が設定されている場合はシーケンス)の確率のうち、トラストリージョンの上限でクリップされたものの平均比率: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: 1回の生成あたりのトークン(または、 importance_sampling_level="sequence") が信頼領域の上限でクリップされた場合の最大比率: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • cispo_clip_ratio: トークン(または、 importance_sampling_level="sequence") の importance sampling 重みが epsilon_high でクリップされ、かつ正のアドバンテージ( ri,t(θ)>ϵhighr_{i,t}(\theta) > \epsilon_\mathrm{high}. )を持つ割合。 loss_type="cispo".
  • vespo/phi_seq_mean: VESPO ガンマ重みの平均値 φ(w)\varphi(w) シーケンスレベルの重要度重みに適用されます。値が 1.0 未満の場合、シーケンスが下位重み付けされています。 loss_type="vespo".

カスタマイズ

vLLMによる生成でトレーニングを高速化

オンライン手法による学習では、生成が主なボトルネックとなることがよくあります。生成を高速化するには、LLM向けの高スループット・低レイテンシ推論エンジンであるvLLMを使用できます。これを有効にするには、まずパッケージをインストールします。

pip install trl[vllm]

トレーニング中のvLLMの使用方法として、サーバーモードとコロケーションモードの2つをサポートしています。

デフォルトでは、異なるフレームワークを使用した場合に発生する生成と学習の不一致に対処するため、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 エラーが発生する可能性があります。使用する GPU は、CUDA_VISIBLE_DEVICES 環境変数で指定できます。

モデルサイズや学習に必要なGPUメモリ全体の要件に応じて、GRPOConfigのvllm_gpu_memory_utilizationパラメータを調整し、リソースの未活用やメモリ不足エラーを回避する必要がある場合があります。

モデルの構成と実験設定に基づいて、推奨されるGPUメモリ使用率を推定するためのHF Spaceを提供しています。以下のように使用すると、vllm_gpu_memory_utilizationの推奨値を取得できます。

推奨値があなたの環境で機能しない場合、安定性を確保するために、推奨値に小さなバッファ(例:+0.05 または +0.1)を加えることをお勧めします。

それでもメモリ不足エラーが発生する場合は、vllm_enable_sleep_modeをTrueに設定してください。これにより、最適化ステップ中にvllmのパラメータとキャッシュがオフロードされます。詳細については、vLLM Sleep Modeによるメモリ使用量の削減を参照してください。

デフォルトでは、GRPOはvLLMに対してMASTER_ADDR=localhostとMASTER_PORT=12345を使用しますが、環境変数を適切に設定することでこれらの値を上書きできます。

詳細については、vLLMによるトレーニングの高速化を参照してください。

トレーニングと推論の不一致への対処

vLLM は推論を大幅に高速化しますが、同時に推論エンジンと学習エンジンを分離します。理論上、これら 2 つのエンジンは数学的に同一ですが、実際には精度の影響やハードウェア固有の最適化により、異なる出力を生成する可能性があります。この乖離は、2 つのシステムが持つ異なる最適化目標を反映しています。推論エンジンは、許容可能なサンプリングの忠実度を維持しつつ、サンプリングのスループット(通常は秒あたりのトークン数で測定されます)を最大化することを目標とします。一方、学習フレームワークは、勾配計算の数値的安定性と精度に焦点を当てており、マスターウェイトやオプティマイザの状態には FP32 のような高精度なフォーマットを頻繁に使用します。これらの異なる優先順位や制約により、学習と推論の間には、微妙ではあるものの、避けられない不一致が生じます。

この不一致はバイアスのかかった勾配更新を引き起こし、トレーニングの不安定化が観測されています([1][2][3][4][5]). 単純化のため、REINFORCE ポリシー勾配を考えます: ∇θJ(x,θ)=Ey∼πtrain(⋅∣x,θ)[∇θlog⁡πtrain(y∣x,θ)⋅R(x,y)] \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 x は、あるデータ分布からサンプリングされたプロンプトを表し、 πtrain \pi^\text{train} は、学習エンジンによって実装されるポリシーです。vLLM をループに含めることで、独立した推論ポリシー πinference \pi^\text{inference} , が得られ、有効なポリシー勾配は次のようになります ∇θJbiased(x,θ)=Ey∼πinference(⋅∣x,θ)[∇θlog⁡πtrain(y∣x,θ)⋅R(x,y)]. \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 ρt \rho_t per token or ρseq \rho_{\text{seq}} per sequence. Under TIS, ratios outside of the range [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] are clipped, ρ←clip(ρ,Cmin⁡,Cmax⁡). \rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}).

元の TIS論文 では、単一の上限クリッピングメカニズム、すなわち min⁡(ρ,Cmax⁡) \min(\rho, C_{\max}) . TRLでの実装では、 IcePop メソッドに着想を得て、下限も導入することでこれを一般化し、上記の両側式が得られました。
IcePopでは、境界は α \alpha および β \beta としてラベル付けされていますが、TRLでは Cmin⁡ C_{\min} および Cmax⁡ C_{\max} .

MISでは、この範囲外の比率はゼロに設定されるため、それらのサンプルは勾配に寄与しません。言い換えれば、外れ値サンプルはTISでは重みが下げられ、MISでは破棄されます。設定フラグvllm_importance_sampling_modeは、ISのバリアント(マスキングまたは切り詰め)と粒度(トークンレベルまたはシーケンスレベル)の両方を選択します。

インポートサンプリングは、学習と推論の不一致に対する原理的なアルゴリズム的対応です。しかし、2つのエンジン自体の不一致を軽減しようとするより直接的なアプローチも存在します。これらは主にエンジニアリング的な解決策です。例えば、MiniMax M1は推論エンジンでFP32の言語モデルヘッドを使用しています。Thinking Machinesは決定論的な推論カーネルを探索していますが、これは大きな効率上のコストを伴います。vLLMは、Thinking Machinesのバッチ不変決定論カーネルを基盤として構築することで、ビット単位で一致するポリシーを実証しました。ただし、2025年11月時点では、標準的なvLLM推論と比較して、依然としてかなりのスループット上のペナルティが残っています。

transformersの連続バッチ処理でトレーニングを高速化

vLLMの代替として、より高速な生成のためにtransformersの組み込みのcontinuous batchingエンジンを使用できます。Continuous batchingは、最遅のシーケンスの完了を待つのではなく、完了したシーケンスを即座にバッチから削除します。完了長が可変なタスク(例: 数学推論)では、大規模なバッチサイズ(N≥32)において、デフォルトのgenerate()よりも生成が高速になり、VRAM使用量が低減されます。

Continuous batchingは、サーバーのセットアップや重みの同期を必要としないドロップイン方式のアップグレードです。プロセス内で動作し、単一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 は、学習のバックワードパスに十分な VRAM を確保するために、max_memory_percent のデフォルト値を 0.5(transformers の 0.9 ではなく)に設定しています。大きな生成バッチ(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ごとに1つのプロセスを起動し、共通のrendezvousを通じてそれらを接続します。詳細については、トレーニングの分散化を参照してください。
  • vLLM: 生成を高速化するために vLLM を使用する方法については、前のセクションを参照してください。

以下は、複数ノードで70BモデルをGRPOで学習するための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)。例 6 を参照してください。
      • log_metric: スカラー指標をプロットとしてkl、entropyなどとともに記録するための、呼び出し可能なlog_metric(name: str, value: float)。例6を参照してください。
      • environments: 環境インスタンスのリストで、各 completion ごとに 1 つです。environment_factory が提供されている場合のみ存在します。エピソード中に蓄積された状態(例: env.counter)を読み取るために使用します。状態を持つ環境では、代わりに環境が get_reward メソッドを通じて報酬を所有する形を推奨します — Rewardsを参照してください。
      • データセットが持つ可能性のあるすべての列名(promptを除く)。例えば、データセットにground_truthという名前の列が含まれている場合、関数はground_truthをキーワード引数として呼び出されます。

      この要件を満たす最も簡単な方法は、関数シグネチャに**kwargsを使用することです。

    • データセットの形式によって、入力が異なります:

      • 標準形式の場合、promptsとcompletionsは文字列のリストになります。
      • 会話形式の場合、promptsとcompletionsはメッセージの辞書のリストになります。
  2. 戻り値: 関数は float のリストを返す必要があります。各 float は、1つの completion に対応する報酬を表します。

例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: 長い補完を報酬する(文字数に基づく)

前回の例と同様ですが、今回は報酬関数がトークン数ではなく文字数に基づいています。

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関数に着想を得ています。 この例は、標準形式向けに設計されており、データセットには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の損失を以下のように拡張します: L(θ)=LGRPO(θ)−α⋅H(πθ), \mathcal{L}(\theta) = \mathcal{L}_{\text{GRPO}}(\theta) - \alpha \cdot \mathcal{H}(\pi_\theta),

ここでH(πθ)\mathcal{H}(\pi_\theta) はポリシーのトークンごとの平均エントロピーであり、α\alpha はエントロピー係数です。ボーナスは常にトークンごとの平均エントロピーであり、 loss_type; に関係なく、損失タイプのポリシー正規化(例: Dr. GRPO の batch_size * max_completion_length 分母)に合わせて再スケーリングされないため、 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,
    ...
)

一般的な言語モデルのトークンごとのエントロピーは2〜10ナット程度であるため、デフォルトのentropy_target=0.2では正則化がほぼトリガーされません。ボーナスはエントロピーがターゲット以下になった場合、つまりエントロピーがほぼ完全に崩壊した状態でのみ発動します。モデルにとって意味のある値、例えば学習初期に観測されるエントロピー(entropyメトリックとして記録されます)に近い値に設定してください。top_entropy_quantile < 1.0を使用する場合、entropy_targetは高エントロピーのトークン部分集合に適用されます。この部分集合のエントロピーは、記録された全トークンのentropyよりも高くなるため、それに応じて調整してください。

use_adaptive_entropy=True の場合、現在のエントロピー係数 entropy_coef は各チェックポイントとともに保存され、再開時に復元されるため、トレーニングは完全に再開可能です。

GRPOの高速実験

RapidFire AI は、TRL の上に構築されたオープンソースの実験エンジンです。単一の GPU 上でも複数の GRPO 設定を同時に起動できます。設定を順番に試すのではなく、RapidFire を使用すると、すべての学習曲線を早期に確認し、性能が低い実行を停止し、実行中に有望な実行を新しい設定でクローンできます。詳細については、RapidFire AI Integrationを参照してください。

エージェントの学習

GRPOはエージェントの学習をサポートしています。モデルは生成中にツールを呼び出し、その結果から学習します。

  • toolは、モデルに公開される通常のPython関数(同期または非同期)です。ステートレスな呼び出し(電卓やWeb検索など)にはtoolsを使用します。
  • environment はより一般的な形式です。各 rollout ごとに新規に構築されるステートフルなオブジェクトであり、その公開メソッドがツールとして公開されます。さらに、reset ライフサイクルフックと、報酬の所有を環境に委ねるための任意の get_reward を備えています。rollout 単位のステート、reset フック、または環境が所有する報酬が必要な場合は、environment_factory を使用してください。

これらは組み合わせることができます。独立したtoolsをenvironment_factoryと並べて渡すことが可能です。

ツール

tools 引数には、エージェントが利用可能なツールを定義する Python 関数(同期または非同期)のリストを指定します。

from trl import GRPOTrainer

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

各ツールは、型ヒント付きの引数と戻り値を持つ標準的なPython関数である必要があります。また、その目的、引数、戻り値を説明するGoogleスタイルのdocstringが必要です。 詳細については、ツールの渡し方ガイドを参照してください。

GRPOのツール呼び出しループでは、チャットテンプレートがプレフィックスを保持する必要があります(ツールメッセージを追加しても、それ以前のメッセージのレンダリング方法が変わらないこと)。既知のモデルファミリー(例: Qwen3、DeepSeek-V3)では、ツールが有効化されている場合、TRLは自動的にパッチを適用したトレーニング用テンプレートに切り替えます。完全なリストについては、Chat Templatesを参照してください。

GRPOConfig で max_tool_calling_iterations を使用して、ツール呼び出しのターン数を上限設定できます。デフォルトでは上限がなく、モデルがツール呼び出しを含まない応答ターンを生成した場合、コンプリーション(すべてのターンとツール結果)が max_completion_length トークンに達した場合、または完全なシーケンスがモデルの最大長に達した場合(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 はロールアウトごとに1つの環境インスタンスを作成し、環境の公開メソッドをツールとして公開します。

environment_factoryにはtransformers>=5.2.0が必要です。

environment_factory を使用する場合、環境がデータを所有します。外部の train_dataset は存在しません。各ロールアウトにおいて、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という2つの予約メソッドがあります。他の公開メソッドとは異なり、これらはモデルにツールとして公開されません。

  • reset (必須) は、ロールアウトが開始されたときに呼び出されます。None または文字列を返すことができます。GRPO では、文字列を返す場合、その文字列がユーザープロンプトになります。
  • get_reward(任意、同期または非同期)は引数を受け取らず、floatを返します。環境は、内部状態に基づいて、直前に実行したエピソードにスコアを付けます(ゲームは勝利で終了したか?単語は当選したか?)。完了したロールアウトごとに1回呼び出され、報酬のソースとして機能します。

環境は各reset()で自己サンプリングを行うため、GRPOグループのGメンバーは同じ初期状態を共有しない場合があり、グループベースラインがわずかにノイジーになります。グループ内で状態を同一にするには、reset()が共有キーから状態を決定論的に導出するようにしてください。

外部データセットの提供(オプション)

環境が自己サンプリングする代わりに、外部のtrain_datasetを指定できます。例えば、タスクがすでにデータセットに存在する場合や、複数の環境間でルーティングを行う場合などに使用できます。ロールアウトごとに、トレーナーは1行をサンプリングし、その"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()

報酬

Environment 所有の報酬と trainer 所有の報酬は排他的ではありません。completion から計算するのが自然な報酬(テキストの形式チェックなど)には 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 キーワード引数(コンプリートごとに1つのインスタンス)を渡します。これは場合によっては有用ですが、状態に依存する報酬については get_reward を優先してください。

これはAsyncGRPOTrainerでも完全に同じように動作します。

複数の環境

単一のランで複数のタスクの混合(例: コーディングタスクとゲーム)を学習するには、単一の callable ではなく、環境名をファクトリにマッピングする辞書を渡します。各ロールアウトはデータセット内の 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レベルでは相互に交換可能です。タスクに合ったエコシステムを持つものを選択してください:

統合概要使用場面
OpenEnvHugging Face とコミュニティが支援する、オープンな環境標準(Gymnasium スタイルの API、WebSocket 経由での提供またはコンテナ化された実行)。Hubの既存のOpenEnv環境を使用しているか、オープン標準(Wordle、Sudoku、Catchなど)に対して独自の環境を定義しています。
OpenRewardORS対応環境(openreward.aiカタログまたは独自のORSサーバー)との統合。タスクと報酬はHTTP経由で提供されます。ORS環境に対して学習を行いたい場合: カタログ(例: Eigent/SETA)、独自のインフラでセルフホストしたもの、または開発中のローカルサーバー。
HarborHarborタスクスイートとの統合: 各タスクは、指示、実際のサンドボックスイメージ(docker、e2bなど)、およびサンドボックス内での検証器から構成されます。Harborのタスクスイートに対して学習を行いたい場合: タスクのツリーで、各タスクは自己完結型のサンドボックスと検証器で構成されます(例: サンドボックス内のファイルを探索し、採点者が確認する回答を書き出すデータ分析エージェント)。

ビジョン言語モデルの学習

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は、モデルのimage processorを介して、画像からテンソルへの変換を自動的に処理します。

GRPOTrainer

クラス trl.GRPOTrainer

< >

( model: str | PreTrainedModel | PeftModelreward_funcs: str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]] | list[str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]]] | None = Noneargs: trl.trainer.grpo_config.GRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = Nonereward_processing_classes: transformers.tokenization_utils_base.PreTrainedTokenizerBase | list[transformers.tokenization_utils_base.PreTrainedTokenizerBase] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)quantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Nonerollout_func: collections.abc.Callable[[list[str], 'GRPOTrainer'], dict[str, typing.Any]] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset]] | None = None )

パラメータ

  • model (str または PreTrainedModel または PeftModel) — 学習対象のモデル。以下のいずれかです:
    • 文字列。huggingface.co上のモデルリポジトリにホストされている事前学習モデルのmodel id、またはsave_pretrainedを使用してモデルの重みを保存したディレクトリへのパス(例: './my_model_directory/')です。モデルは、モデル設定から導出される<ModelArchitecture>を用いた<ModelArchitecture>.from_pretrainedによって、args.model_init_kwargs内のキーワード引数を使用して読み込まれます。args.model_init_kwargsにdtypeが指定されていない場合、デフォルトはfloat32です。これは、モデル設定からdtypeを推論する(Transformers v5以降)from_pretrainedとは異なります。
    • PreTrainedModelオブジェクト。因果言語モデルのみサポートされています。
    • PeftModelオブジェクト。因果言語モデルのみサポートされています。
  • reward_funcs (RewardFunc | list[RewardFunc], 省略可能) — 報酬の計算に使用する報酬関数です。報酬を計算するには、プロンプトと補完を引数としてすべての報酬関数を呼び出し、その報酬を合計します。 environment_factory ((以下を参照)によって環境から報酬が提供される場合は省略できます。以下のいずれかになります:
    • 単一の報酬関数、例えば次のようなもの:

      • 文字列: huggingface.co上のモデルリポジトリにホストされている事前学習済みモデルのモデルID、またはsave_pretrainedを使用して保存されたモデルの重みを含むディレクトリへのパス。例: './my_model_directory/'。モデルはnum_labels=1およびargs.model_init_kwargs内のキーワード引数を使用して、from_pretrainedで読み込まれます。

      • PreTrainedModel オブジェクト: シーケンス分類モデルのみサポートされています。

      • カスタム報酬関数: 関数には、プロンプトと生成された補完、およびデータセット内の追加の列が渡されます。報酬のリストを返す必要があります。カスタム報酬関数は同期または非同期のいずれかであり、報酬が該当サンプルに適用されない場合はNoneを返すこともできます。これは、異なる報酬関数が異なるタイプのサンプルに適用されるマルチタスク学習に有用です。報酬関数がサンプルに対してNoneを返した場合、その報酬関数はそのサンプルの報酬計算から除外されます。詳細については、カスタム報酬関数の使用を参照してください。

        トレーナーの状態は、報酬関数にも渡されます。トレーナーの状態はTrainerStateのインスタンスであり、報酬関数のシグネチャにあるtrainer_state引数にアクセスすることで取得できます。

    • 報酬関数のリストです。各項目は、上記のいずれかの型を独立して指定できます。リスト内で異なる型を混在させること(例: 文字列のモデルIDとカスタム報酬関数)は許可されています。

  • args (GRPOConfig、任意) — このトレーナーの設定です。None の場合、デフォルトの設定が使用されます。
  • train_dataset (Dataset または IterableDataset, 省略可能) — 学習に使用する Dataset。 "prompt". Dataset 内の追加の列は無視されます。サンプルの形式は次のいずれかです:
    • Standard: 各サンプルにはプレーンテキストが含まれています。
    • 対話形式: 各サンプルには構造化されたメッセージ(例: roleとcontent)が含まれます。

    environment_factory が提供され、環境がデータを所有(または手続き的に生成)し、reset() メソッドからプロンプトを返す場合のみ、省略できます。その場合、max_steps を設定してトレーニングの長さを定義する必要があります。

    train_dataset が IterableDataset(ストリーミングデータセットなど)である場合、その長さを推定できないため、学習ループの上限を定め、学習率スケジューラを設定するために必要な総学習ステップ数を指定するため、max_steps を学習引数で設定する必要があります。

  • eval_dataset (Dataset、IterableDataset、DatasetDict、IterableDatasetDict または dict[str, Dataset | IterableDataset]) — 評価に使用する Dataset です。train_dataset と同じ要件を満たす必要があります。
  • processing_class (PreTrainedTokenizerBase、ProcessorMixin、任意) — データを処理するために使用される処理クラスです。padding side は “left” に設定する必要があります。None の場合、from_pretrained を使用してモデル名から処理クラスを読み込みます。padding トークンである tokenizer.pad_token を設定する必要があります。処理クラスに padding トークンが設定されていない場合、tokenizer.eos_token がデフォルトとして使用されます。
  • reward_processing_classes (PreTrainedTokenizerBase または list[PreTrainedTokenizerBase], 省略可能) — reward_funcs で指定された報酬関数に対応する処理クラスです。 reward_funcs. 以下のいずれかです:
    • 単一の処理クラス: reward_funcsに報酬関数が1つのみ含まれている場合に使用されます。
    • 処理クラスのリスト: reward_funcs内の報酬関数の順序と長さに一致する必要があります。 Noneに設定されている場合、またはPreTrainedModelに対応するリストの要素が Noneの場合、モデルのトークナイザーは from_pretrainedを使用して自動的に読み込まれます。reward_funcs内のカスタム報酬 関数(PreTrainedModelではないもの)に対応するreward_processing_classesの エントリは無視されます。
  • callbacks (のリスト TrainerCallback, 省略可) — トレーニングループをカスタマイズするためのコールバックのリスト。デフォルトのコールバックのリストに追加されます。デフォルトのコールバックの詳細は こちら.

    デフォルトで使用するコールバックの1つを削除したい場合は、remove_callbackメソッドを使用します。

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]、任意、デフォルトは (None, None)) — 使用するオプティマイザーとスケジューラーを含むタプルです。デフォルトでは、モデルに対して AdamW のインスタンスと、args によって制御される get_linear_schedule_with_warmup によって与えられるスケジューラーが使用されます。
  • quantization_config (BitsAndBytesConfig、任意) — モデル識別子からモデルを読み込む際に使用される量子化設定です。QLoRA 学習には peft_config と組み合わせて使用します。モデルがすでにインスタンス化されている場合は無視されます。
  • peft_config (PeftConfig, 任意) — モデルをラップするために使用される PEFT 設定です。None の場合、モデルはラップされません。
  • tools (Callable のリスト、省略可) — モデルが生成中に呼び出すことができる、呼び出し可能なツール関数(同期または非同期)のリストです。各ツールは、適切に型ヒントが付けられた引数と戻り値を持つ標準的な Python 関数であり、その目的、引数、戻り値を説明する Google スタイルのドキュメント文字列(docstring)が必要です。詳細については、https://huggingface.co/docs/transformers/en/chat_extras#passing-toolsを参照してください。モデルは、関数名、型ヒント、ドキュメント文字列を用いて、関数の呼び出し方法を決定します。モデルのチャットテンプレートがツールの使用をサポートしており、ツール呼び出し用にファインチューニングされていることを確認してください。
  • rollout_func (RolloutFunc, 省略可) — 補完を生成するために使用する関数です。現在のプロセスに割り当てられたプロンプトのリストと、トレーナーのインスタンスを受け取ります。"prompt_ids"、"completion_ids"、および"logprobs"フィールドを含む辞書を返す必要があります。また、"logprob_token_ids"("logprobs"と同じ形状)を任意で返すこともできます。その他のフィールドは、報酬関数に転送されます。この関数は、重複なしのプロセスごとの生プロンプトのスライスを受け取ります。プロンプトごとの正しい数の補完を返す責任があります(トレーナーのnum_generations / num_generations_evalを参照)。この機能は実験的であり、事前の通知なしにいつでも変更または削除される可能性があります。
  • environment_factory (EnvironmentFactory または dict[str, EnvironmentFactory], 省略可) — 環境インスタンスを作成して返す呼び出し可能オブジェクト、または環境名をそのような呼び出し可能オブジェクトにマッピングする辞書です。環境クラスには、生成中にツールとして呼び出せるメソッドを定義する必要があります。各メソッドは、上記で説明した tools の要件に準拠する必要があります。環境は、生成間で状態をリセットするために使用できる呼び出し可能な reset メソッドも実装する必要があります。 reset メソッドは None または文字列を返す必要があります。文字列を返す場合、その文字列は生成前に最後のユーザーメッセージに追加されます。環境は、引数を取らず get_reward を返す float: メソッドを定義することもできます。このメソッドが存在する場合、環境が報酬を所有し、 get_reward は完了したロールアウトごとに1回呼び出され、環境の内部状態からスコアを評価します。これは追加の報酬ソースとして機能し(重みは1で、環境のクラス名で記録されます)、同時に、その後の報酬関数である、 reward_funcs, は省略可能になります。

    単一の callable を使用する場合、すべての例は同じ環境を使用し、ロールアウトごとに1つのインスタンスが作成されるため、それらの相互作用は分離された状態に保たれます。辞書を使用する場合、各例には環境を名前で選択するための environment フィールドを含める必要があり、その環境のツールのみがプロンプトに公開されます。これにより、単一のランでタスクを混合(例: コーディング環境とゲーム)できます。この機能は実験的であり、事前の通知なしにいつでも変更または削除される可能性があります。

Group Relative Policy Optimization (GRPO) 手法用の Trainer です。このアルゴリズムは、論文 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models で初めて提案されました。

例:

>>> 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()

train

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

パラメータ

  • resume_from_checkpoint (str または bool、省略可) — str の場合、以前の Trainer インスタンスによって保存されたチェックポイントのローカルパスを指定します。bool で True の場合、以前の Trainer インスタンスによって args.output_dir に保存された最後のチェックポイントを読み込みます。指定がある場合、ここで読み込まれたモデル/オプティマイザ/スケジューラの状態からトレーニングを再開します。
  • trial (optuna.Trial または dict[str, Any]、省略可) — ハイパーパラメータ探索のための試行またはハイパーパラメータの辞書。
  • ignore_keys_for_eval (list[str]、省略可) — モデルの出力が辞書である場合、学習中の評価で予測を収集する際に無視すべきキーのリストです。

戻り値

~trainer_utils.TrainOutput

グローバルステップ数、トレーニング損失、およびメトリクスを含むオブジェクト。

メインの学習エントリポイント。

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

モデルを保存するため、from_pretrained()を使用して再読み込みできます。

メインプロセスからのみ保存します。

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

パラメータ

  • commit_message (str、任意、デフォルトは"End of training") — プッシュ時にコミットするメッセージ。
  • blocking (bool、省略可能、デフォルトはTrue) — git pushが完了した後にのみ関数が返すかどうか。
  • token (str、任意、デフォルトはNone) — Trainer の元の引数を上書きするための書き込み権限を持つトークン。
  • revision (str, 省略可) — コミット元の git リビジョンです。“main” ブランチのヘッドがデフォルトです。
  • private (bool、省略可) — リポジトリ作成時にプライベートにするかどうか。デフォルトはargs.hub_private_repoです。リポジトリが既に存在する場合は、この引数は無効です。
  • kwargs (dict[str, Any]、省略可) — ~Trainer.create_model_card に渡される追加のキーワード引数。

self.args.hub_model_id のリポジトリに、self.model と self.processing_class を 🤗 model hub にアップロードします。

GRPOConfig

クラス trl.GRPOConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool = Truegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 10logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool | None = Falselabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonetrust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonedisable_dropout: bool = Falsecast_lm_head_to_fp32: bool = Falsenum_generations: int | None = 8num_generations_eval: int | None = Nonemax_completion_length: int | None = 512ds3_gather_for_generation: bool = Trueshuffle_dataset: bool | None = Truepad_to_multiple_of: int | str | None = 'auto'generation_batch_size: int | None = Nonesteps_per_generation: int | None = Nonetemperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonegeneration_kwargs: dict | str | None = Nonechat_template_kwargs: dict | str | None = Nonerepetition_penalty: float = 1.0cache_implementation: str | None = Noneuse_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_model_impl: str = 'vllm'vllm_enable_sleep_mode: bool = Falsevllm_structured_outputs_regex: str | None = Nonevllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8000vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.3vllm_max_model_length: int | None = Nonevllm_tensor_parallel_size: int = 1beta: float = 0.0num_iterations: int = 1epsilon: float = 0.2delta: float | None = Noneepsilon_high: float | None = Nonesapo_temperature_neg: float = 1.05sapo_temperature_pos: float = 1.0vespo_k_pos: float = 2.0vespo_lambda_pos: float = 3.0vespo_k_neg: float = 3.0vespo_lambda_neg: float = 2.0importance_sampling_level: str = 'token'reward_weights: list[float] | None = Nonemulti_objective_aggregation: str = 'sum_then_normalize'scale_rewards: str = 'group'loss_type: str = 'dapo'mask_truncated_completions: bool = Falsesync_ref_model: bool = Falseref_model_mixup_alpha: float = 0.6ref_model_sync_steps: int = 512top_entropy_quantile: float = 1.0entropy_coef: float = 0.0use_adaptive_entropy: bool = Falseentropy_coef_min: float = 0.0entropy_coef_max: float = 1.0entropy_coef_delta: float = 0.005entropy_target: float = 0.2max_tool_calling_iterations: int | None = Nonevllm_importance_sampling_correction: bool = Truevllm_importance_sampling_mode: str = 'sequence_mask'vllm_importance_sampling_clip_max: float | None = 3.0vllm_importance_sampling_clip_min: float | None = Noneoff_policy_mask_threshold: float | None = Noneuse_bias_correction_kl: bool = Truelog_completions: bool = Falselog_multimodal: bool = Truenum_completions_to_print: int | None = Nonelog_unique_prompts: bool = Falselog_completions_hub_repo: str | None = Noneuse_transformers_continuous_batching: bool = Falsetransformers_continuous_batching_config: dict | str | None = Noneuse_transformers_paged: bool = Falsevllm_importance_sampling_cap: float | None = None )

モデルと参照モデルを制御するパラメータ

  • model_init_kwargs (str または dict[str, Any]、省略可) — model 引数が文字列として指定された場合、GRPOTrainer の from_pretrained に渡すキーワード引数です。処理クラスの読み込み時にも revision の値が使用されます。
  • trust_remote_code (bool, optional, defaults to False) — Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to from_pretrained and from_pretrained. Also applied to reward-model and reward-tokenizer loads.
  • router_aux_loss_coef (float, 任意) — Mixture-of-Experts (MoE) モデルにおける負荷分散用の補助損失の係数です。この重みで学習損失に追加されます。設定されていない場合、モデル設定で宣言された値が使用されます。0.0 に設定すると無効になります。MoE 以外のモデルで使用するとエラーになります。
  • disable_dropout (bool、任意、デフォルトはFalse) — モデル内の dropout を無効にするかどうか。参照モデルを用いた学習時に有用であり、同じ入力に対してモデルが異なる logprobs を生成することを防ぎます。
  • cast_lm_head_to_fp32 (bool、任意、デフォルトはFalse) — ポリシーモデルおよびリファレンスモデルの言語モデリングヘッドをfloat32にキャストするかどうか。ScaleRLレシピで推奨されています。このフラグは、モデルの単語埋め込み層と言語モデリングヘッド層が分離されている場合、つまりモデル設定のtie_word_embeddingsがFalseの場合にのみサポートされます。

データ前処理を制御するパラメータ

  • remove_unused_columns (bool、任意、デフォルトは False) — データセットで "prompt" 列のみを保持するかどうか。"prompts" と "completions" 以外の列を必要とするカスタムの報酬関数を使用する場合は、この値を False に設定してください。
  • num_generations (int, 省略可能, デフォルトは 8) — プロンプトごとにサンプリングする生成数。実効バッチサイズ (num_processes * per_device_batch_size
    • gradient_accumulation_steps) は、この値で割り切れる必要があります。
  • num_generations_eval (int, 任意) — 評価時にサンプリングする生成回数です。評価時に生成回数を減らすことで計算量を節約できます。None の場合、num_generations の値が使用されます。
  • max_completion_length (int または None、任意、デフォルトは 512) — 生成される補完の最大長。
  • ds3_gather_for_generation (bool、任意、デフォルトは True) — この設定は DeepSpeed ZeRO-3 に適用されます。有効にすると、生成のためにポリシーモデルの重みが集約され、生成速度が向上します。ただし、このオプションを無効にすると、1 つの GPU の VRAM 容量を超えるモデルのトレーニングが可能になりますが、その代わりとして生成速度は低下します。このオプションを無効にすると、vLLM による生成と互換性がありません。
  • shuffle_dataset (bool、任意、デフォルトはTrue) — 学習データセットをシャッフルするかどうか。
  • pad_to_multiple_of (int または str、任意、デフォルトは "auto") — 設定されている場合、プロンプト ID と補完 ID は、この値の倍数にパディングされます。"auto" は Neuron (AWS Trainium) 上で 128 の倍数にパディングします。Neuron は入力形状ごとに一度だけコンパイルされるためです。その他の環境ではパディングは行われません。

生成を制御するパラメータ

  • generation_batch_size (int, 任意) — 生成に使用するバッチサイズ。None の場合、実効的な学習バッチサイズ、すなわち per_device_train_batch_size * num_processes * steps_per_generation がデフォルトとして使用されます。つまり、1回の最適化ステップごとに1つの生成バッチが処理されます。steps_per_generation とは排他的です。
  • steps_per_generation (int, 省略可) — 1回の生成あたりのステップ数。Noneの場合、gradient_accumulation_stepsがデフォルト値として使用されます。generation_batch_sizeとは排他的です。
  • temperature (float、任意、デフォルトは1.0) — サンプリング用の温度です。温度が高いほど、補完はランダムになります。
  • top_p (float、任意、デフォルトは 1.0) — 考慮する上位トークンの累積確率を制御する浮動小数点数です。値は (0, 1] の範囲でなければなりません。すべてのトークンを考慮するには 1.0 を設定してください。
  • top_k (int、任意、デフォルトは0) — トップkフィルタリングのために保持する、確率の高い語彙トークンの数。0の場合、トップkフィルタリングは無効になり、すべてのトークンが対象となります。
  • min_p (float, 省略可) — トークンの最小確率です。最も確率の高いトークンの確率でスケーリングされます。0.0 と 1.0 の間の値である必要があります。一般的な値は 0.01-0.2 の範囲です。
  • generation_kwargs (dict[str, Any], 省略可) — 補完のサンプリング時に GenerationConfig (transformers を使用する場合) または SamplingParams (vLLM を使用する場合) に渡す追加のキーワード引数です。 suppress_tokens や num_beams の設定など、生成の動作をさらにカスタマイズするために使用できます。 他の生成パラメータ (例: min_p、top_p など) と競合するキーが含まれている場合、それらが上書きされます。
  • chat_template_kwargs (dict[str, Any], 省略可) — 補完を生成する際にapply_chat_template関数に渡す追加のキーワード引数。
  • repetition_penalty (float、任意、デフォルト値は1.0) — プロンプトとこれまでに生成されたテキストにトークンが出現しているかどうかに基づいて、新しいトークンをペナルティする浮動小数点数です。 値が1.0より大きい場合、モデルは新しいトークンを使用するよう促され、値が1.0より小さい場合、モデルはトークンを繰り返すよう促されます。
  • cache_implementation (str, 任意) — use_vllm が False に設定されている場合、生成を高速化するためのキャッシュ方式の実装。

vLLM による生成加速を制御するパラメータ

  • use_vllm (bool、省略可、デフォルトは False) — 補完の生成に vLLM を使用するかどうかを指定します。True に設定すると、デフォルトの model.generate() の代わりに、vLLM を生成に使用します。vllm のインストールが必要です。
  • vllm_mode (str, 省略可能, デフォルトは "colocate") — が use_vllm に設定されている場合の vLLM 統合で使用するモード True. のいずれかである必要があります "server" または "colocate".
    • "server": トレーナーは、別の vLLM サーバーに生成リクエストを送信します。vLLM サーバーが実行されていることを確認してください(vllm serveで開始)。
    • "colocate": vLLM は同じプロセス内で実行され、トレーニング用の GPU を共有します。これにより、別のサーバーを必要としない一方で、トレーニングとの間でリソースの競合が発生する可能性があります。
  • vllm_model_impl (str、任意、デフォルトは"vllm") — vLLM に使用するモデル実装です。"transformers" または "vllm" のいずれかである必要があります。"transformers": モデル実装に transformers バックエンドを使用します。"vllm": モデル実装に vllm ライブラリを使用します。
  • vllm_enable_sleep_mode (bool、任意、デフォルトはFalse) — オプティマイザーステップ中に重み/キャッシュをオフロードするために、vLLM のスリープモードを有効にします。GPU メモリ使用率を低く保ちますが、エンジンの復帰時にホストとデバイス間の転送遅延が発生します。
  • vllm_structured_outputs_regex (str, 省略可) — vLLM の構造化出力に使用する正規表現です。None(デフォルト)の場合、構造化出力は無効になります。

vLLM サーバーを制御するパラメータ(`vllm_mode` が `"server"` の場合のみ使用)

  • vllm_server_base_url (str, 省略可) — vLLM サーバーのベース URL (例: "http://localhost:8000")。指定された場合、vllm_server_host および vllm_server_port は無視されます。
  • vllm_server_host (str、任意、デフォルトは "0.0.0.0") — 接続する vLLM サーバーのホストです。vllm_server_base_url が指定されている場合は無視されます。
  • vllm_server_port (int、任意、デフォルトは8000) — 接続する vLLM サーバーのポートです。vllm_server_base_url が指定されている場合は無視されます。
  • vllm_server_timeout (float, 省略可能、デフォルト値は 240.0) — vLLM サーバーの起動を待機する合計タイムアウト時間(秒)です。タイムアウト後にサーバーが起動していない場合、ConnectionError が発生します。
  • vllm_group_port (int, 任意、デフォルトは 51216) — 重み更新グループ用のポート番号です。vLLM サーバーとの通信に使用されます。ポートが占有されていない限り、変更する必要はありません。

colocate された vLLM 実行を制御するパラメータ(`vllm_mode` が `"colocate"` の場合のみ使用)

  • vllm_gpu_memory_utilization (float、任意、デフォルト値は 0.3) — vLLM の GPU メモリ使用率を制御します。この設定は、vllm_mode が "colocate" に設定されている場合にのみ適用されます。vllm_mode="server" を使用している場合は、--vllm_gpu_memory_utilization フラグを指定して vLLM サーバーを起動する際に、このパラメータを別途渡す必要があります。
  • vllm_max_model_length (int, 省略可) — vLLM のコンテキストウィンドウです。データセット内の最大プロンプト長に max_completion_length を加えた値以上を設定してください。省略した場合、モデルの設定から推論されます。
  • vllm_tensor_parallel_size (int、任意、デフォルトは 1) — vLLM のテンソル並列サイズを制御します。この設定は、vllm_mode が "colocate" に設定されている場合にのみ適用されます。vllm_mode="server" を使用している場合は、--vllm_tensor_parallel_size フラグを指定して vLLM サーバーを起動する際に、このパラメータを別途渡す必要があります。

学習を制御するパラメータ

  • beta (float、任意、デフォルトは 0.0) — KL 係数です。0.0(デフォルト)の場合、参照モデルは読み込まれず、メモリ使用量が削減され、トレーニング速度が向上します。DeepSeek-R1 incentivizes reasoning in LLMs through reinforcement learning では、値として 0.001 が使用されています。
  • num_iterations (int、任意、デフォルトは1) — バッチあたりの反復回数(アルゴリズムでは μ と表記されます)。
  • epsilon (float, 任意、デフォルトは 0.2) — クリッピング用のエプシロン値。
  • delta (float, 任意) — delta が float に設定されている場合、両側 GRPO ロスの上限クリッピングを有効にします。None(デフォルト)の場合、標準的な GRPO クリッピングが使用されます。有効にする場合は、1 + ε より大きい値を推奨します。このメソッドは INTELLECT-2 技術レポート で紹介されました。
  • epsilon_high (float, オプション) — クリッピング用の上限エプシロン値です。指定しない場合、引数 epsilon で指定された下限値と同じ値がデフォルトとして使用されます。論文 DAPO では 0.28 が推奨されています。 loss_type='cispo' と組み合わせて使用する場合、これは ScaleRL 論文 で指定されている ε_max パラメータに対応し、デフォルト値は推奨値 5.0 になります。
  • sapo_temperature_neg (float, 任意、デフォルト値は 1.05) — sapo 損失関数で使用される、非正のアドバンテージスコアを持つトークンの温度です。このパラメータは、Soft Adaptive Policy Optimization の論文で導入されました。
  • sapo_temperature_pos (float, 任意、デフォルト値は 1.0) — sapo 損失関数で使用される、正のアドバンテージスコアを持つトークンの温度です。このパラメータは、Soft Adaptive Policy Optimization の論文で導入されました。
  • vespo_k_pos (float、任意、デフォルト値は2.0) — 正のアドバンテージに対する k パラメータです。VESPO ロスのべき乗指数として機能します。重要度重みが低いサンプル(重要度サンプリング比が 1 未満の場合)をどの程度強く減衰させるかを制御します。
  • vespo_lambda_pos (float, 任意、デフォルト値は 3.0) — 正のアドバンテージ用の lambda パラメータです。VESPO ロスの減衰係数として機能します。重要度重みが大きいサンプル(重要度サンプリング比が 1 より大きい場合)をどの程度強く減衰させるかを制御します。
  • vespo_k_neg (float, 任意、デフォルト値は 3.0) — 負のアドバンテージ用の k パラメータです。VESPO ロスのべき乗指数として機能します。重要度重みが低いサンプル(重要度サンプリング比が 1 未満の場合)をどの程度強く減衰させるかを制御します。
  • vespo_lambda_neg (float, 任意、デフォルト値は 2.0) — ネガティブアドバンテージ用のラムダパラメータです。VESPO損失における指数減衰係数として機能します。重要度重みが大きいサンプル(重要度サンプリング比が 1 より大きい場合)をどの程度強く減衰させるかを制御します。
  • importance_sampling_level (str、任意、デフォルトは"token") — 重要度サンプリングの比率を"token"レベルで計算するか、"sequence"レベルで計算するかを制御します。"token" は、トークンごとの生の対数尤度比を保持します(トークンごとに1つの重み)。"sequence"は、有効なトークン全体で対数尤度比を平均化し、シーケンスごとに1つの比率を生成します。GSPO 論文では、シーケンスレベルのサンプリングは、より安定した学習とシーケンスレベルの報酬とのより良い整合性を生み出すことが多いことが示されています。
  • reward_weights (list[float], 任意) — 各報酬関数に対する重み。報酬関数の数と一致する必要があります。None の場合、すべての報酬が重み 1.0 で等しく重み付けされます。
  • multi_objective_aggregation (str, 省略可能, デフォルトは "sum_then_normalize") — 複数の報酬関数を集約する方法。サポートされる値は以下の通りです:
    • "sum_then_normalize" (デフォルト): 各報酬関数からの加重報酬をまず合計し、その後scale_rewardsで指定された報酬のスケーリング/正規化を適用します(詳細はscale_rewardsを参照)。
    • "normalize_then_sum": 各世代(各グループ内)で各報酬関数を正規化/スケーリングしてから、指定された重みを使用して正規化された報酬を合計します。その後、アドバンテージを形成する際に、集約された報酬はバッチレベルで正規化されます。これは論文 GDPO: Group reward-Decoupled Normalization Policy Optimization for Multi-reward RL Optimization で提案されているアプローチです。
  • scale_rewards (str または bool, 省略可, デフォルトは "group") — 報酬のスケーリング戦略を指定します。サポートされる値は以下の通りです:
    • Trueまたは"group"(デフォルト): 報酬は各グループ内の標準偏差でスケーリングされ、グループ内の分散が1になることが保証されます。
    • "batch": PPO Lite論文で推奨されているように、バッチ全体の標準偏差で報酬がスケーリングされます。
    • False または "none": スケーリングは適用されません。Dr. GRPO 論文では、標準偏差によるスケーリングは問題レベルの難易度バイアスを導入するため、報酬のスケーリングをしないことを推奨しています。
  • loss_type (str, 省略可能, デフォルトは "dapo") — 使用する損失関数の形式を指定します。サポートされている値は以下の通りです:
    • "grpo": シーケンス長で正規化することにより、トークン単位の損失を集約します。長さバイアスにより、正のアドバンテージを持つ短い補完や、負のアドバンテージを持つ長い補完を優先する傾向があるため、推奨されていません。
    • "dr_grpo": グローバルな定数で正規化することにより、トークンレベルの損失を集約します。この手法は、長さのバイアスを排除するためにDr. GRPO論文で導入されました。この定数の値はmax_completion_lengthに対応します。
    • "dapo" (デフォルト): アクティブなトークンの数で正規化することにより、グローバルに蓄積されたバッチ内のトークンレベルの損失を集約します。この手法は、長さのバイアスを排除するためにDAPO論文で導入されました。
    • "bnpo": アクティブなトークンの数で正規化することにより、トークンレベルの損失を集約します。正規化はローカルバッチに対してのみ行われるため、実効バッチサイズが一定であっても、ローカルバッチサイズによって結果がわずかに異なる場合があります。per_device_train_batch_size==1を使用する場合、損失はGRPO損失と同等になります。
    • "cispo": 利得スケーリングされた重要性サンプリング重みではなく、重要性サンプリング重み自体をクリップします。クリップされた重みは、利得およびポリシーモデルの対数確率と掛け合わせられます。個々のトークンの損失は、グローバルに蓄積されたバッチ内のアクティブなトークン数で正規化することにより集約されます。この手法は、MiniMax-M1 の論文で導入されました。
    • "sapo": Soft Adaptive Policy Optimization 論文で導入されたSoft Adaptive Policy Optimization損失。ハードクリッピングを、温度で制御される滑らかなゲートに置き換えます。このゲートは、有用な学習シグナルを保持しつつ、オフポリシーの更新を適応的に減衰させます。
    • "luspo": Length-Unbiased Sequence Policy Optimization ロス。シーケンス単位のロスで、各シーケンスのロスをその長さでスケーリングします。これは GSPO の修正版であり、importance_sampling_level="sequence" が必要です。LUSPO 論文 で導入されました。
    • "vespo": Variational Sequence-Level Soft Policy Optimization。ハードクリッピングを置き換え、シーケンスレベルの重要度重みに直接適用される滑らかで非対称なガンマ重み付け関数を使用します。VESPO論文で導入されました。
  • mask_truncated_completions (bool、任意、デフォルトは False) — 有効にすると、切り詰められた補完は損失計算から除外され、誤ってペナルティを課されることによる学習中のノイズの導入を防ぎます。DAPO 論文によると、これは学習の安定性にとって良いプラクティスです。
  • sync_ref_model (bool、任意、デフォルトはFalse) — ref_model_mixup_alpha パラメータを使用して、ref_model_sync_steps ステップごとに参照モデルをアクティブなモデルと同期するかどうか。TR-DPO 論文に由来する同期処理です。
  • ref_model_mixup_alpha (float, 任意、デフォルト値は 0.6) — TR-DPO論文からのαパラメータで、更新時の現在のポリシーと以前の参照ポリシーの間の混合を制御します。参照ポリシーは、以下の方程式に従って更新されます: π_ref = α * π_θ + (1 - α) * π_ref_prev。このパラメータを使用するには、sync_ref_model=True を設定する必要があります。
  • ref_model_sync_steps (int、任意、デフォルトは512) — TR-DPO論文のτパラメータで、現在のポリシーを参照ポリシーと同期する頻度を決定します。このパラメータを使用するには、sync_ref_model=Trueを設定する必要があります。
  • top_entropy_quantile (float、任意、デフォルトは 1.0) — Beyond the 80/20 Rule における ρ パラメータです。各シーケンス位置における確率分布のエントロピーに基づき、上位 ρ 分位点のトークンのみをポリシー損失項に保持することで、結果を改善します。範囲: [0.0-1.0]。0.0 の場合、エントロピーが最も高いトークン以外のすべてをマスクし、1.0 の場合、すべてのトークンを保持します。論文では 0.2 の値が推奨されています。mask_truncated_completions=True と併用する場合、切り詰められていない補完のトークンのみが対象となります。
  • entropy_coef (float、任意、デフォルトは 0.0) — 損失におけるエントロピー正則化項の係数です。正の値を設定するとエントロピーボーナスが加算され、ポリシーがほぼ決定論的な出力に収束することを防ぎ、探索を促進します。このボーナスは loss_type に関係なく常にトークンごとのエントロピーの平均であり、損失タイプのポリシー正規化に合わせて再スケーリングされないため、entropy_coef はすべての損失タイプで同じ意味を持ちます。use_adaptive_entropy=True の場合、これは初期係数として機能し、各オプティマイザステップで更新されます。0.0 (デフォルト) に設定されている場合は効果がありません。
  • use_adaptive_entropy (bool、任意、デフォルトは False) — Skywork-OR1 で導入された適応型エントロピー制御を使用するかどうかを指定します。有効な場合、エントロピー係数 entropy_coef は各オプティマイザーステップで更新されます。現在のエントロピーが entropy_target 未満の場合は entropy_coef_delta だけ増加し、それ以外の場合は減少します。この係数は、エントロピーが entropy_target 以下の場合にのみ適用されます。
  • entropy_coef_min (float、任意、デフォルトは 0.0) — 適応型エントロピー制御を使用する場合のエントロピー係数の下限値。
  • entropy_coef_max (float、任意、デフォルトは 1.0) — 適応型エントロピー制御を使用する場合のエントロピー係数の上限値です。
  • entropy_coef_delta (float、任意、デフォルトは0.005) — 適応型エントロピー制御において、オプティマイザの各ステップでエントロピー係数を調整するためのステップサイズ。
  • entropy_target (float、任意、デフォルトは 0.2) — 適応型エントロピー制御で使用される、トークンごとの平均エントロピーの目標値(nats 単位)です。係数は、現在のエントロピーがこの値以下に低下した場合にのみ適用されます。測定対象はポリシー損失と同じトークンセットで、デフォルトではすべての補完トークン、top_entropy_quantile < 1.0 の場合は高エントロピーのサブセットのみです。一般的な言語モデルのトークンごとのエントロピーは 2〜10 nats の範囲にあり、デフォルトの 0.2 ではほぼ正則化がトリガーされません(エントロピーがほぼ完全に崩壊した場合のみ)。ボーナスがポリシーの崩壊前に発動するように、トレーニング初期に観測されるエントロピー(entropy メトリックとして記録されます)に近い値を設定してください(top_entropy_quantile を使用する場合、トークンサブセットを考慮してください)。
  • max_tool_calling_iterations (int, 任意) — エージェントの学習におけるツール呼び出しのターン数の上限です。None の場合、上限はなく、モデルがツール呼び出しを含まない応答ターンを生成したとき、または補完(すべてのターンとツール結果)が max_completion_length トークンに達したとき、または完全なシーケンスがモデルの最大長(vllm_mode="colocate" の場合は vllm_max_model_length、それ以外の場合はモデルの max_position_embeddings)に達したときに、生成が停止します。
  • vllm_importance_sampling_correction (bool, optional, defaults to True) — Whether to apply Importance Sampling (IS) to correct for the mismatch between vLLM completion logprobs and recomputed training logprobs. If set to False, no IS is applied regardless of vllm_importance_sampling_mode. When True, the selected mode determines how the IS ratios are computed and constrained. With top_p < 1, top_k > 0 or min_p > 0, the recomputed logprobs are normalized over the candidate set each token was sampled from, which requires vLLM 0.28 or later and, in server mode, a server started with --return-sampling-mask (and --enable-scale-out from vLLM 0.30); otherwise, the IS ratios are biased. vLLM bounds that candidate set with top_k, so top_p < 1, min_p > 0 and structured outputs, which restrict it to the tokens the grammar allows, require top_k > 0 (e.g. top_k=512). Structured outputs, which would otherwise stall training, also require that candidate set. vLLM also applies repetition_penalty to the logprobs it returns, so repetition_penalty != 1.0 requires vllm_importance_sampling_correction=False.
  • vllm_importance_sampling_mode (str, 省略可能, デフォルトは "sequence_mask") — が True の場合に、Importance Sampling がどのように実行されるかを指定します。 vllm_importance_sampling_correction=True. 指定可能な値は以下の通りです:
    • "token_truncate": トークンレベルの切り詰めIS。トークンごとの比率が[C_min, C_max]にクリップされます。
    • "token_mask": トークンレベルのマスク付きIS。[C_min, C_max]の範囲外のトークンごとの比率はゼロに設定されます。
    • "sequence_truncate": シーケンスレベルの切り詰め IS。単一のシーケンス比を [C_min, C_max] にクリップし、シーケンス内のすべてのトークンに適用します。
    • "sequence_mask": シーケンスレベルのマスク付きIS。比率が[C_min, C_max]の範囲外にあるシーケンスはマスクされます。
  • vllm_importance_sampling_clip_max (float、任意、デフォルト値は3.0) — vllm_importance_sampling_modeで使用されるインポータンスサンプリングの上限 C_max です。*_truncateモードでは、インポータンス比が C_max で上にクリップされます。*_maskモードでは、C_max を超える比はゼロに設定されます。
  • vllm_importance_sampling_clip_min (float, 任意) — vllm_importance_sampling_mode で使用されるインポータンスサンプリングの下限 C_min です。*_truncate モードでは、比率は C_min で下方クリップされます。*_mask モードでは、C_min 未満の比率はゼロに設定されます。C_min 未満の比率を上限なしで厳密にマスクするには、vllm_importance_sampling_clip_max=None を設定してください。
  • off_policy_mask_threshold (float、省略可) — オフポリシーシーケンスのマスキングの閾値です。None の場合、オフポリシーシーケンスのマスキングは無効になります。値が設定されている場合、負のアドバンテージと高い KL 発散を持つシーケンスがマスクされ、トレーニングが安定化します。このパラメータは、DeepSeek-V3.2 論文の式 9 の delta 閾値に対応します。正の値(例: 0.5)を指定します。
  • use_bias_correction_kl (bool、任意、デフォルトは True) — KL 項に重要性サンプリング比を掛けるかどうかです。これにより、DeepSeek-V3.2 論文に述べられているように、KL の勾配がバイアスのない逆 KL 勾配になります。beta != 0 の場合、オンポリシーであっても KL の勾配が変化します。比は微分可能であるため、その値がちょうど 1 である箇所でも勾配に影響します。バイアスのない逆 KL の性質は importance_sampling_level="token" の場合に成り立ちます。"sequence" の場合は、シーケンスレベルの重みがトークンごとの KL にブロードキャストされます。

ログ出力を制御するパラメータ

  • log_completions (bool、任意、デフォルトはFalse) — logging_steps ステップごとに、(プロンプト、補完) のペアのサンプルをログに記録するかどうか。rich がインストールされている場合、サンプルを出力します。wandb および/または trackio のログ出力が有効な場合、wandb および/または trackio に記録します。
  • log_multimodal (bool、任意、デフォルトはTrue) — 補完と合わせてマルチモーダルコンテンツ(画像、動画など)をログに記録するかどうか。高解像度のマルチモーダルデータを使用する場合、ログサイズを削減するためにこれを無効にできます。
  • num_completions_to_print (int, 省略可) — richで表示する補完の数を指定します。Noneの場合、すべての補完がログに記録されます。
  • log_unique_prompts (bool、任意、デフォルトはFalse) — 一意のプロンプトのみをログに記録するかどうか。Trueの場合、一意のプロンプトのみがログに記録されます。Falseの場合、すべてのプロンプトがログに記録されます。
  • log_completions_hub_repo (str, 省略可) — 補完を保存する Hugging Face Hub リポジトリです。 'username/reponame' や 'orgname/reponame' のような完全なリポジトリ名、または単に 'reponame' を指定します。後者の場合、現在ログイン中の Hugging Face ユーザーのネームスペース内にリポジトリが作成されます。なお、hub_private_repo=True を設定するか、組織のデフォルトがプライベートリポジトリの作成である場合を除き、このリポジトリはパブリックになります。

transformers の連続バッチ処理による生成高速化を制御するパラメータ

  • use_transformers_continuous_batching (bool、任意、デフォルトはFalse) — 補完の生成に transformers の continuous batching エンジンを使用するかどうか。transformers>=5.8.0 が必要です。
  • transformers_continuous_batching_config (dict、省略可) — ContinuousBatchingConfig 用のキーワード引数。

非推奨のパラメータ

  • use_transformers_paged —

    パラメータ use_transformers_paged は非推奨となり、バージョン v2.0.0 で削除されます。代わりに use_transformers_continuous_batching を使用してください。

  • vllm_importance_sampling_cap —

    パラメータ vllm_importance_sampling_cap は非推奨となり、バージョン v2.0.0 で削除されます。代わりに vllm_importance_sampling_clip_max を使用してください。

GRPOTrainer用の設定クラスです。

このクラスには、GRPO学習に固有のパラメータのみが含まれています。学習引数の完全なリストについては、TrainingArgumentsのドキュメントを参照してください。なお、このクラスのデフォルト値は、TrainingArgumentsのものと異なる場合があります。

HfArgumentParser を使用すると、このクラスをコマンドラインで指定できる argparse の引数に変換できます。

これらのパラメータは、TrainingArgumentsとは異なるデフォルト値を持っています:

  • logging_steps: デフォルト値が500ではなく10になります。
  • gradient_checkpointing: デフォルト値がFalseではなくTrueに変更されました。
  • bf16: fp16が設定されていない場合、デフォルトでFalseではなくTrueになります。
  • learning_rate: 5e-5ではなく、デフォルト値が1e-6に変更されました。
Update on GitHub