TRL documentation

非同期 GRPO トレーナー

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

非同期 GRPO トレーナー

model badge

概要

AsyncGRPOTrainer は同じ GRPO アルゴリズムを実装していますが、ロールアウトの生成と学習を分離します。バックグラウンドワーカーが vLLM サーバーから補完を継続的にストリーミングで送信し、学習ループがそれらを消費するため、生成と勾配の更新が交互に実行されるのではなく、オーバーラップして実行されます。

このトレーナーは、Amine Dirhoussi氏とQuentin Gallouédec氏によって提供されました。

クイックスタート

この例では、非同期GRPO手法を用いてモデルを学習する方法を示します。DeepMath-103K データセットのプロンプトを使用して、Qwen3.5 2B モデルを学習します。データセットのデータは以下で確認できます:

以下はモデルを学習するためのスクリプトです。TrainerにはvLLMとkernelsが必要であり、accuracy_rewardにはmath-verifyが必要です。これらはpip install trl[vllm,kernels,math_verify]でインストールできます。

# train_async_grpo.py
from datasets import load_dataset
from trl import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

if __name__ == "__main__":  # the rollout worker is a spawned process that re-imports this script
    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3.5-2B",
        reward_funcs=accuracy_reward,
        train_dataset=dataset,
    )
    trainer.train()

Generationは、トレーナーとは異なるGPU上のvLLMサーバーで実行されます。GPU 0で開始します:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3.5-2B \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096

次に、次のコマンドを使用して GPU 1 でスクリプトを実行します:

CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py

互換性と制約

現在のAsyncGRPOTrainer実装では、一部の引数の組み合わせが意図的に制限されています:

  • Generationは常に、vllm serveで起動される別のvLLMサーバー上で実行されます。colocateモードはありません。
  • データセットのプロンプトはconversational形式である必要があります。environment_factoryを使用する場合、データセットにpromptカラムがなくてもよく、reset()がそれを提供します。
  • 報酬関数はPythonの呼び出し可能オブジェクトである必要があります。モデルIDまたはPreTrainedModelとして指定された報酬モデルはサポートされていません。カスタム報酬関数の使用を参照してください。
  • Trainerにはtransformers>=5.2.0が必要です。
  • Sharded trainingではFSDP2を使用します。DeepSpeedはサポートされておらず、コンテキスト並列およびシーケンス並列(parallelism_config内のcp_size > 1またはsp_size > 1)もサポートされていません。
  • use_liger_kernel=True はサポートされていません。
  • lm_headをターゲットとするPEFTアダプターはサポートされていません。
  • アテンションシンクを持つモデルはサポートされていません。サポートされている非アテンションレイヤーは、ハイブリッドモデル(Qwen3.5、Qwen3.6、Qwen3-Next など)のゲート付き DeltaNet レイヤーのみであり、これにはtransformers>=5.15.0が必要です。
  • 画像はサポートされていません。ビジョン言語モデルの学習を参照してください。

Training は kernels ライブラリを介して Hub からアテンションカーネルを読み込みます: AMD GPU (ROCm) では kernels-community/aiter-flash-attn、NVIDIA Blackwell GPU では kernels-community/flash-attn4、その他の NVIDIA GPU では kernels-community/flash-attn3 です。Gemma 2 のようにアテンションロジットに上限を設ける (attn_logit_softcapping) モデルは、AMD GPU および NVIDIA Blackwell GPU ではサポートされていません。

非同期GRPO手法の詳細

GRPOTrainerでは、生成と学習が逐次実行されます。バッチを生成し、損失を計算し、重みを更新し、これを繰り返します。colocate モードであっても、一方のフェーズが完了するまで、もう一方のフェーズは開始できません。AsyncGRPOTrainerでは、ロールアウトワーカーがバックグラウンドプロセスで補完を生成・採点する一方で、学習ループが損失を計算し、モデルを更新します。その仕組みを理解するために、3つの主要なステップに分解できます。補完の生成、アドバンテージの計算、そして損失の計算です。参照モデルが存在しないため、KL 発散項はありません(GRPO のデフォルトはbeta=0.0です)。

補完の生成

ロールアウトワーカーは、vLLMサーバーに対して最大 max_concurrent_rollouts 個のリクエストを同時に処理します。各プロンプトに対して、 G G 個の補完(num_generations) )を生成し、グループ全体が完了すると、スコアを計算してアドバンテージを求めます。得られたトレーニングサンプルはキューに格納され、トレーニングループから取り出されます。生成は、トレーニングより max_staleness ステップ先行した場合にのみ待機します( 並行性), を参照)。また、トレーニングステップはキューが空の場合にのみ待機します。

weight_sync_steps 回の学習ステップごとに、トレーナーは NCCL を介して更新された重みを vLLM サーバーに送信し、次の補完が最新のポリシーから生成されるようにします。そのため、補完は、学習中のポリシーより数ステップ古いポリシーから生成される可能性があります。トレーナーがサンプルを取得した時点で、max_staleness 回の重み更新分以上古いサンプルは破棄されます。

メトリクスおよびこのページの残りの部分では、補完が通過する段階について、以下の用語を使用します。

  • a グループ は1つのプロンプトとその G G ロールアウトから構成されます。アドバンテージはグループ内で計算されます。
  • rolloutとは、プロンプトに対して生成される1回の完全な会話であり、すべてのツール呼び出しを含みます。1つ以上のturnで構成され、各turnは1つのvLLMリクエストに対応します。
  • サンプルとは、損失が計算される対象であり、ロールアウトのトークンとそのアドバンテージです。マルチターンロールアウトでは、複数のサンプルが生成されることがあります(マルチターンロールアウトを参照)。
  • rowとは、1つのプロセスが1つのマイクロバッチで転送するもので、複数のサンプルがパックされたものです(Tree packingを参照)。micro-batchはプロセスごとに1つのrowを持ち、gradient_accumulation_steps個のマイクロバッチで1つのstep、つまりオプティマイザーステップを構成します。

トークン数は3種類あります。generatedトークンはモデルが生成したもので、forwardedトークンはサンプルのすべてのトークン(プロンプトとツール結果を含む)を指し、trainedトークンは損失が計算される対象のトークンです。

アドバンテージの計算

グループの各 G G の補完について、報酬は各報酬関数からの報酬の合計です。アドバンテージは、GRPOと同様にグループ内で正規化されます: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

scale_rewards オプションはありません。アドバンテージは常にグループの標準偏差でスケーリングされます。すべての報酬関数がNoneを返した補完は、グループの平均と標準偏差の計算から除外され、アドバンテージはゼロになります。

報酬がすべて等しいグループは除外されます。デフォルトのアドバンテージではどこもゼロになるため、このグループで学習を行うとフォワードパスとバックワードパスのコストが発生するだけで、パラメータは更新されません。このようなグループの割合はfrac_zero_std_groupsとして記録されます。ステップは保持されたグループから埋められるため、除外されるグループが多いほど、1ステップあたりの生成量が増えます。除外されたグループもエポックのカウントには含まれ、エポックはプロンプトを1回通すこととして維持されます。

損失の計算

vLLM サーバーの log-probabilities は、トレーナーのものと完全に一致しません。カーネルの違い、精度の違い、そして数ステップ遅れたポリシーが原因です( Training-Inference Mismatch の対処法). トレーナーは、サンプラーの log-probabilities を旧ポリシーとして使用するため、単一の重要性比で、不一致と staleness の両方をカバーできます: ri,t(θ)=πθ(oi,t∣q,oi,<t)πsampler(oi,t∣q,oi,<t). r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\text{sampler}}(o_{i,t} \mid q, o_{i,< t})}.

[vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] の範囲外に比率が収まるトークンは、損失から除外されます。詳細については、Masked Importance Samplingを参照してください。

デフォルトでは (score_centering=True), トレーナーは Score Centering. 重要度重みだけでは不一致を解消できません。サンプリングされたトークンのスコア ∇θlog⁡πθ \nabla_\theta \log \pi_\theta は、サンプラー μ \mu , の下で平均がゼロになりません。そのため、すべての更新がポリシーをサンプラーの方へ引き寄せてしまいます。Score centering は、各位置でその期待値を引きます: ∇θL=−Eo∼μ[A^(f(rt)∇θlog⁡πθ(ot)−Ev∼μ[f(rv)∇θlog⁡πθ(v)])],rv=πθ(v)μ(v), \nabla_\theta \mathcal{L} = - \mathbb{E}_{o \sim \mu} \left[ \hat{A} \left( f(r_t) \nabla_\theta \log \pi_\theta(o_t) - \mathbb{E}_{v \sim \mu} \left[ f(r_v) \nabla_\theta \log \pi_\theta(v) \right] \right) \right], \quad r_v = \frac{\pi_\theta(v)}{\mu(v)},

ここで f(r)=r f(r) = r 内部 [Cmin⁡,Cmax⁡] [C_{\min}, C_{\max}] および 0 0 外部です。内部の期待値は、サンプラーの num_sampler_logprobs 最も確率の高いトークンに対して、各位置で取得されます。これはロールアウトワーカーがサーバーに要求するものです。

が score_centering=False, の場合、トレーナーは同じマスク付き比率を用いて、GRPO のクリップ付きサロゲート目的関数を使用します: L(θ)=−1∑i∣oi∣∑i∑t=1∣oi∣1[Cmin⁡≤ri,t(θ)≤Cmax⁡]min⁡(ri,t(θ)A^i,t, clip(ri,t(θ),1−ϵlow,1+ϵhigh)A^i,t), \mathcal{L}(\theta) = - \frac{1}{\sum_{i} |o_i|} \sum_{i} \sum_{t=1}^{|o_i|} \mathbb{1}\left[ C_{\min} \le r_{i,t}(\theta) \le C_{\max} \right] \min \left( r_{i,t}(\theta) \hat{A}_{i,t}, \, \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_{\text{low}}, 1 + \epsilon_{\text{high}} \right) \hat{A}_{i,t} \right),

ここで ϵlow \epsilon_{\text{low}} は epsilon 、 ϵhigh \epsilon_{\text{high}} は epsilon_high.

どちらの場合も、損失は、すべてのプロセスにわたって集計されたマイクロバッチ内の学習済みトークン数で正規化され、gradient_accumulation_stepsのマイクロバッチにわたって平均化されます。

記録されたメトリクス

学習中に、以下のメトリクスを記録します:

  • num_tokens: これまで転送されたトークンの総数(プロンプトと補完を含む)。ツリーパッキングを使用する場合、複数のサンプルで共有されるプレフィックスは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: 最後のターンが EOS トークンで終わっていない、切り詰められた(クリップされた)補完の割合。
  • completions/duplicate_frac: グループ内の以前のロールアウトをトークン単位で完全に繰り返すロールアウトの割合。飽和と重複を参照してください。
  • tools/call_frequency: 全ロールアウト(その後除外されるグループを含む)における、1回のコンプリーションあたりのツール呼び出しの平均回数。トレーナーにツールがある場合のみ記録されます。
  • tools/failure_frequency: ツール呼び出しの失敗率(ツールが見つからなかったか、例外が発生した場合)です。ここで、失敗率は、その後除外されるグループも含めたすべてのツール呼び出しに対する割合として計算されます。ツール呼び出しが1件もないログウィンドウでは NaN となり、GRPO は 0.0 を記録します。トレーナーにツールがある場合のみ記録されます。
  • rewards/{reward_func_name}/mean: 特定の報酬関数による平均報酬です。スコアリングされたすべての完了に対して計算され、その後除外されるグループも含みます。環境がget_rewardを通じて報酬を管理している場合、{reward_func_name}は環境のクラス名になります。
  • rewards/{reward_func_name}/group_std: 特定の報酬関数からの報酬の標準偏差。各グループ内で計算され、学習済みサンプル全体で平均化されます。
  • reward: 各関数にわたる報酬を合計した全体の平均報酬です。スコアリングされたすべての完了(その後除外されるグループを含む)を対象とします。これはポリシーの報酬であるため、追跡すべき指標です。reward_trainedは、報酬がすべて等しいグループを除外します。
  • reward_group_std: 各グループ内で計算され、学習サンプル全体で平均化された、関数間の合計報酬の標準偏差です。GRPOのreward_stdがバッチ全体で取得されるのとは異なり、アドバンテージはこの値で割られます。
  • reward_trained: トレーナーが学習に使用したサンプルの平均報酬です。報酬がすべて等しいグループと、max_staleness を超えて除外されたサンプルは除外されています。
  • reward_zero_std_groups: 報酬がすべて等しく、除外されるグループの平均報酬。つまり、そのグループが停滞している報酬値です。frac_zero_std_groups と reward を用いて読み解くには、飽和と重複を参照してください。
  • frac_zero_std_groups: 報酬の標準偏差がゼロ(すべての回答が正解または誤解)であるグループ、または採点可能な補完が2件未満のグループの割合。これらのグループは除外されます。
  • sampling/sampling_logp_difference/mean: トレーニング済みトークンにおいて、サンプラー(vLLM)が返す対数確率と、学習モデルによって再計算された対数確率の間の平均絶対差。
  • sampling/sampling_logp_difference/max: 最大絶対差
  • sampling/importance_sampling_ratio/min: 最小の重要性サンプリング比 ri,t(θ) r_{i,t}(\theta) モデルとサンプラーの間で、学習済みトークンにわたる、 [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] の範囲外のトークンが除外される前の
  • sampling/importance_sampling_ratio/mean: 重要性サンプリング比の平均値。
  • sampling/importance_sampling_ratio/max: 最大のリサンプリング比率。
  • sampling/masked_mean: 重要度サンプリング比率が[vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max]の範囲外にあり、損失から除外された学習済みトークンの割合。
  • sampling/sampler_mass: サンプラーの最も確率の高いnum_sampler_logprobsトークンがカバーする平均確率質量。score_centering=Trueの場合にのみ記録されます。
  • entropy: 学習済みトークン全体における、トークン予測の平均エントロピー。
  • aux_loss: Mixture-of-Experts モデルのロードバランス用の補助損失。router_aux_loss_coef によってスケーリングされ、損失に追加される前の値です。モデルが MoE モデルであり、router_aux_loss_coef がゼロでない場合にのみ記録されます。
  • clip_ratio/region_mean: GRPO の目的関数が信頼領域内に留まるようクリップされるトークン確率の比率: clip(ri,t(θ),1−ϵlow,1+ϵhigh) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) . が score_centering=True の場合、損失はクリップされないため、 clip_ratio/* メトリックは信頼領域外のトークンをカウントします。
  • clip_ratio/low_mean: トラストリージョンの下限でクリップされたトークン確率の平均比率: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: トラストリージョンの下限でクリップされるトークンの完了ごとの最小割合: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: トラストリージョンの上限でクリップされたトークン確率の比率の平均値: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: トラストリージョンの上限でクリップされたトークンの完了ごとの最大割合: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.

その他のメトリクスは、非同期パイプラインを説明しています。

メトリクスは、ログウィンドウごとに1回記録されます。これは、直前のログ以降に記録されたすべての値を指し、直近のlogging_steps回のオプティマイザーステップをカバーします。ウィンドウ全体について:

  • reward、rollout/turns_mean、tools/latency_s などのように、ロールアウトごと、サンプルごと、または呼び出しごとに測定される平均値は、ウィンドウ内のすべてのロールアウト、サンプル、呼び出しに対して平均化されます。rollout/generated_tokens_per_s などのレートは、トークン総数を秒総数で割った値です。
  • それ以外の場合、最後の部分にcountという単語を含む名前は合計されます。sample/dropped_stale_countは、トレーニング開始時ではなく、直前のログ以降に破棄されたサンプルの数です。
  • maxまたはminという単語を含む名前の最後の部分を持つもの、例えばsample/staleness_maxやcompletions/max_lengthなどは、最大値または最小値を保持します。
  • その他のメトリックは、ウィンドウ内で記録された値の平均です。

単位:

  • _s: 秒。
  • tokens_per_s: 1秒あたりのトークン数。
  • _frac: 0から1の間の割合。
  • _per_step: 1回のオプティマイザーステップあたりの量。ウィンドウ内のステップで平均化されます。

ロールアウト指標

  • rollout/duration_s: 1回のロールアウトの経過時間。ディスパッチからロールアウトループが収集するまでの時間です。
  • rollout/generated_tokens_per_s: 前回のレポート以降の生成スループット(1秒あたりの生成トークン数)。
  • rollout/concurrency: vLLMサーバーに実行中(in-flight)のロールアウトの数。
  • rollout/concurrency_cap: 現在実行中のロールアウトの上限。サーバーの負荷に応じて変化します。並行性を参照してください。
  • rollout/turns_mean、rollout/turns_max: 1回のロールアウトあたりのターン数の平均値と最大値。
  • rollout/samples_per_rollout: 1回のロールアウトあたりの学習サンプル数。1.0を超える場合、一部のロールアウトがフォークされます。1.0未満の場合、学習トークンを生成しないロールアウトが発生します。マルチターンロールアウトを参照してください。
  • rollout/fork_frac: 保持トークンで始まらないプロンプトを持つターン遷移の割合。つまり、そのターンが新しいサンプルを開始した割合です。
  • rollout/drift_tokens_mean、rollout/drift_tokens_max: フォークが再レンダリングした保持トークンの数です。ターン遷移で平均化されます(フォークしない場合は0とカウントされます)。新しいサンプルは分岐点までのトークンを共有するため、これは各フォークがフォワードに追加する量です。
  • rollout/score_queue_size: スコアリングを待っている完了したグループの数。
  • rollout/queue_size: トレーナーが取得する位置で測定される、rollout キューで待機している採点済みサンプルの数。rollout キューを参照してください。
  • rollout/score_s: グループをスコアリングする時間。
  • rollout/score_wait_s: スコアリングの前に完了したグループが待機していた時間。
  • rollout/score_block_s: スコアリングキューが満杯だったため、生成がブロックされた時間。
  • rollout/backpressure_s: 生成が、トレーニングよりmax_stalenessステップ先行していたため、ロールアウトの開始を待っていた時間。ログ出力ウィンドウ内の待機時間の平均値です。並行性を参照してください。
  • rollout/vllm_retry_count: 再試行された vLLM リクエストの数。サーバーが劣化している場合、原因不明の遅延のように見えます。
  • rollout/vllm_kv_cache_usage_frac: vLLMのKVキャッシュ使用率(エンジン間の最大値)を、ログ出力ウィンドウ内のポーリングで平均した値。
  • rollout/vllm_running_requests: サーバーのエンジンがデコードしているリクエストの数(vLLMのnum_requests_runningをエンジン全体で合計した値)です。rollout/concurrencyとの差は、APIサーバープロセス内でレスポンスを構築している分です。
  • rollout/vllm_queued_requests: サーバーが受け入れたが、まだスケジュールされていないリクエストの数(vLLMのnum_requests_waitingをエンジン全体で合計したもの)。
  • rollout/vllm_preemption_count: サーバーがプリエンプトしたリクエストの数(vLLMのnum_preemptions_totalをエンジン全体で合計したもの)。ウェイト同期によりサーバーのキャッシュがリセットされ、実行中のすべてのリクエストがプリエンプトされるため、これは負荷のシグナルではありません。

ツールメトリクス

  • tools/latency_s、tools/{tool_name}/latency_s: ツール呼び出しの実行に費やされた時間。全ツール合計およびツールごとの値です。
  • tools/{tool_name}/call_count、tools/{tool_name}/failure_count: ツールごとの呼び出し回数と失敗した呼び出しの回数です。
  • tools/unknown_name_count: 存在しないツールへの呼び出し回数。実行されて例外を送出したツールとは異なり、これはポリシーエラーです。
  • tools/parallel_calls_mean: ツールを呼び出すアシスタントメッセージにおける、ツール呼び出しの平均回数。
  • tools/loop_exhausted_frac: ツールを呼び出し続けている状態でmax_tool_calling_iterationsで打ち切られたロールアウトの割合です。呼び出しのないロールアウトや、その後除外されるグループも含めた全ロールアウトに対する割合として記録されます。トレーナーにツールがある場合のみ記録されます。

HarnessAsyncGRPOTrainer は、これらの大部分を同じ名前でログに記録します。違いについては、ハーネスでの学習を参照してください。

環境メトリクス

  • env/reset_s: ロールアウト開始前に、環境のreset()に費やされた時間。environment_factoryが提供されている場合のみ記録されます。
  • env/reward_s: ロールアウト終了後、環境のget_reward()に費やされた時間。環境がget_rewardを定義している場合のみ記録されます。

サンプルメトリクス

  • sample/forwarded_tokens_mean、sample/forwarded_tokens_max: サンプルあたりの転送トークン数の平均値と最大値。
  • sample/trained_tokens_mean: サンプルあたりの学習済みトークンの平均数。
  • sample/time_in_queue_s: サンプルが学習対象となる前に、ロールアウトキューで待機していた時間。
  • sample/staleness_mean、sample/staleness_max: サンプルを生成したポリシーと、そのサンプルで学習を行うポリシーの間の重み更新回数。sampling/importance_sampling_ratio/* および sampling/sampling_logp_difference/* メトリクスは、この staleness と学習・推論の不一致を組み合わせます。staleness がゼロの状態で、比率が 1.0 から乖離しているか、対数尤度の差が 0.0 から乖離している場合は、不一致を示唆します。例えば、サーバーとの dtype の違いなどが該当します。
  • sample/dropped_stale_count: max_stalenessを超えたために破棄されたサンプルの数。

バッチメトリクス

  • batch/forwarded_tokens_per_step、batch/trained_tokens_per_step: 全プロセスにわたる、ステップあたりのフォワードされたトークン数と学習されたトークン数です。
  • batch/samples_per_step、batch/groups_per_step: ステップあたりのサンプル数と、異なるグループの数です。グループあたりのサンプル数によって値が異なります。
  • batch/microbatches_per_step: 1ステップあたりのマイクロバッチ数。
  • batch/masked_token_frac: 転送されたトークンのうち、学習対象とならないものの割合。
  • batch/samples_per_row、batch/row_tokens_mean、batch/row_tokens_max: 1行あたりのサンプル数、および1行あたりの平均と最大フォワードトークン数。
  • batch/row_fill_frac: 各行がtoken_budgetのどの割合を使用しているかを示します。
  • batch/row_imbalance: 最もコストの高い行のattentionコストと平均コストの比率です。最もコストの高い行を持つプロセスが勾配のall-reduceで他のプロセスを待たせます。1.0が完全なバランスです。
  • batch/packing_ratio: 1つの転送トークンあたりのパッキング前のトークン数: パッキングによってフォワードが縮小される係数。何も共有されていない場合は1.0です。
  • batch/pad_frac: 行の長さを揃えるために追加されるパディングの割合です。転送のコストのみ発生し、フォワードの前に削除されます。
  • batch/dropped_oversize_count: token_budgetを超えたために破棄されたサンプルの数。

パフォーマンス指標

  • perf/step_s: ステップの壁時計時間。オプティマイザー、重みの同期、サンプルの待機時間を含みます。
  • perf/fwd_bwd_s、perf/fwd_s: ステップのフォワードパスとバックワードパスにかかった時間、およびフォワードパスのみにかかった時間。
  • perf/optimizer_s: オプティマイザーステップに費やされた時間。
  • perf/rollout_wait_s: rolloutキューが空だったため、トレーニングが待機した時間。rolloutキューを参照してください。
  • perf/weight_sync_s: 重みの同期にかかった時間。perf/weight_sync_pause_s(vLLM の一時停止を待っている時間)、perf/weight_sync_barrier_s(他のプロセスを待っている時間)、perf/weight_sync_transfer_s(重みを転送している時間)に分割されます。
  • perf/fwd_bwd_forwarded_tokens_per_s、perf/wall_clock_forwarded_tokens_per_s: 前向きパスと後向きパス全体、またはステップ全体における、1秒あたりの転送トークン数。
  • perf/wall_clock_trained_tokens_per_s: ステップ全体における、1秒あたりの学習済みトークン数。
  • perf/fwd_bwd_mfu、perf/wall_clock_mfu: 学習デバイスにおけるモデルのFLOPs利用率です。前者はフォワードパスとバックワードパス全体、後者はステップ全体に対する値です。vLLMサーバーは除外されます。学習精度での学習デバイスのピーク計算量が既知であり、かつFLOPsの推定がモデルのアーキテクチャ(Llama、Qwen2、Qwen3、Qwen3-MoE、Qwen3-VLなど)をサポートしている場合のみ記録されます。

カスタマイズ

vLLMサーバーの構成

Trainer は vllm_server_base_url(デフォルトは http://localhost:8000)でアクセスする vLLM サーバーを使用して生成を行います:

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096
  • VLLM_SERVER_DEV_MODE=1 および --weight-transfer-config は、トレーナーが重みを転送するために使用するエンドポイントを公開します。
  • --logprobs-mode processed_logprobs を指定すると、サーバーは、温度および top-k/top-p の適用後にサンプリングした分布の対数尤度を返します。これは、重要度比と比較される対象です。
  • --api-server-count 8 は、スコアリングの中心化リクエストを低コストで提供できるように、上位の log-probabilities を保持します(以下の警告を参照してください)。
  • --max-model-len は、想定される最大合計シーケンス長(プロンプトと補完)です。値を下げるとサーバーの GPU メモリ使用量が減少し、KV キャッシュに割り当てられるメモリが増えるため、スループットが向上します。適切な初期値は、プロンプトの長さに設定ファイルの max_completion_length を加えたものです。ツールを使用する場合、各ターンで最大 max_completion_length トークンとツール結果が追加されるため、想定される最長の会話に合わせて設定してください。あるターンのプロンプトと max_completion_length の合計が --max-model-len を超えると、サーバーはリクエストを拒否し、実行はサーバーのエラーで停止します。top_k または top_p を使用している場合、サーバーは --max-model-len に達した時点でそのターンを停止し、すでにその長さのプロンプトのみを拒否します。また、token_budget のデフォルト値でもあります。

サーバーがトレーナーとは異なる GPU を使用していることを確認してください。そうでない場合、NCCL エラーが発生する可能性があります。使用する GPU は、CUDA_VISIBLE_DEVICES 環境変数で指定できます。

vLLM の API サーバーでは、上位の log-probabilities のシリアライズは CPU での処理であり、デフォルトの単一 API サーバー構成では num_sampler_logprobs=8 により生成スループットが半減します。vLLM 0.32 以降では、サーバーを --api-server-count 8 で起動してください。1.5B から 7B のモデルを 1 台の H100 で測定したところ、この設定により上位 8 件の log-probabilities のコストは生成スループットの 3% 未満に抑えられます。vLLM 0.31 では同じフラグを使用しても 20% から 40% の損失が残りますが、これは vllm-project/vllm#58181 によりアップストリームで修正されています。

並行性

同時に実行されるロールアウトの数は、3つの制限によって決定されます。最初の2つは自動的に調整されますが、3つ目はユーザーが設定します。

Staleness(鮮度)。 max_staleness は、生成がトレーナーより最大で何ステップ先行してよいかを設定します。ワークラーはこれをトークン単位で追跡します。これは、ステップごとのサンプル数が、コンプリートの長さの変化に伴って変わるためです。各ステップの終了後、トレーナーは使用したトークン数をカウントし、ワークラーがそのトークン数の max(max_staleness, 1) 倍までキューイング中または進行中のトークンを保持することを許可します。最初のステップの前に、すべての行が満杯であると仮定します。ワークラーは、その上限を下回っている場合のみ、新しいロールアウトのグループを開始します。開始直後は、ロールアウトが何トークン生成するかまだ不明なため、最初のグループが完了するまで、一度に 1 グループずつ開始します。それでもなお max_staleness ステップ以上古いサンプルは破棄されます。

vLLM の負荷。 vLLM に一度にリクエストを多数送信すると、KV キャッシュが埋まり、vLLM がリクエストの一部を一時停止して再実行する必要が生じるため、処理が遅くなります。そのため、ワーカーは同時に実行されるロールアウトの数をリアルタイムで制限し、rollout/concurrency_cap として記録します。また、サーバーの /metrics を 5 秒ごとに確認して、この制限を調整します。制限の初期値は、KV キャッシュに最大長で収まるリクエスト数(KV cache tokens / max_model_len)に設定されており、開始時にサーバーが過負荷にならないようにしています。KV キャッシュの使用率が 60% 未満で、待機中のリクエストがない場合、完了したロールアウトが 1 回のキャップ分溜まるごとに最大 1 回、制限を 25% 引き上げます。使用率が 80% を超えると、制限を 30% 引き下げます。実行中のリクエストは継続し、新しいリクエストは待機します。サーバーに /metrics エンドポイントがない場合、制限は max_concurrent_rollouts になります。

リソース。 max_concurrent_rollouts(デフォルトは512)は、同時に実行されるロールアウトの上限です。これは、トレーナーが環境やツールが処理できる容量を把握できないため、ユーザー自身が設定する唯一の制限値です。実行中の各ロールアウトは環境を使用し、このサイズのスレッドプール上で同期ツール呼び出しを実行でき、vLLMサーバーへの接続を保持します。環境サーバーが受け入れるセッション数など、それらが処理できる容量に合わせて設定してください。

from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    max_concurrent_rollouts=64,
)

低すぎると、生成が遅くなります。ロールアウトは、vLLM が生成している間だけでなく、ツールを実行中やターン間の待機中もスロットを保持し続けます。そのため、多くのツールを呼び出すロールアウトは、vLLM を常に稼働させるためにより多くのスロットを必要とします。デフォルト値よりもはるかに高く設定すると、vLLM サーバーが接続をドロップし始める可能性があります。

記録されたメトリクスは、生成を妨げている制約が何かを示しています:

  • rollout/backpressure_s がゼロより大きい場合: ストレステネスの上限です。生成が学習よりも先行していることを示しており、推論が学習よりも速い場合に想定される状態です。
  • rollout/concurrency_cap における rollout/concurrency が max_concurrent_rollouts 未満の場合: vLLM サーバーの負荷。
  • rollout/concurrencyがmax_concurrent_rolloutsに達し、rollout/vllm_kv_cache_usage_fracが低く、perf/rollout_wait_sが高い場合: 上限に達しています。環境やツールが許可している場合は、max_concurrent_rolloutsを上げてください。

ロールアウトキュー

ワーカーはスコア付きサンプルをキューにプッシュし、トレーナーはそこからプルします。そのキューを説明する4つのメトリクスがあります。

  • rollout/queue_size: キューを待っているサンプルの数。
  • sample/time_in_queue_s: 1つのサンプルが学習対象となる前に待機していた時間。staleness(鮮度)の時間成分です。
  • perf/rollout_wait_s: キューが空だったため、トレーニングが待機した時間。
  • rollout/backpressure_s: 生成が、学習よりmax_stalenessステップ先行していたため待機した時間。

最後の2つはミラーイメージです。キューサイズと併せて読むことで、ボトルネックがどちら側にあるかを示します。

  • キューがほぼ空で、perf/rollout_wait_s が高い場合: 生成がボトルネックです。トレーナーが飢餓状態にあります。rollout/generated_tokens_per_s、rollout/concurrency、rollout/score_queue_size を確認してください。
  • max_staleness ステップ分のトークンを保持するキュー、rollout/backpressure_s が高い: trainer-bound。生成が抑え込まれ、sample/staleness_mean が上限値付近に留まっています。
  • 両方が高い場合: max_staleness の上限自体が厳しすぎます。進行中のロールアウトが、そのサンプルがキューに到達する前に上限に達するため、生成が抑制されたままトレーナーが待機してしまいます。max_staleness を引き上げてください。
  • どちらもほぼゼロ: バランスがとれている。

飽和と重複

ポリシーは、グループ内のロールアウト間の差分から学習します。各アドバンテージは、グループの平均報酬に対する相対値として計算されます。グループ内のすべてのロールアウトが同じ報酬を得た場合、すべてのアドバンテージはゼロとなり、そのグループは除外されます(記録されたメトリクスを参照)。これにより、ポリシーには何も学習されません。実行が飽和状態に近づくと、すべてのロールアウトがプロンプトを解決するか、あるいはどのロールアウトも解決できないかのいずれかにより、このようなグループが増加していきます。4つのメトリクスがこれらのケースを区別し、それぞれが独自の質問に答えるため、プロットから直接読み取ることができます。

メトリック質問
frac_zero_std_groupswhat share of groups carry no signal
reward_zero_std_groups…
rewardスコアリング対象のグループ全体(除外されたグループを含む)におけるポリシーの性能
completions/duplicate_frac同じプロンプトに対してサンプリングが異なるロールアウトを生成し続けるかどうか

報酬の範囲に対して、最初の3つをまとめてお読みください:

frac_zero_std_groupsreward_zero_std_groupsreward診断対処方法
低any (少数のグループに対するノイズ)anyhealthy: ほとんどのグループが勾配を生成nothing
クライミング範囲の上部付近クライミング上限に飽和する: プロンプトがポリシーにとって容易になりすぎており、これが成功した実行の典型的な終了パターンですランを停止するか、より難しいプロンプトに移行します
高範囲の下部付近低く平坦最下部で停滞: プロンプトが難しすぎるか、報酬関数が信用を付与しないまずcompletions/clipped_ratioを確認してください。回答が得られる前に切り詰められたcompletionはスコアが0になるためです。その後、いくつかのcompletionを読み、reward functionがそれらを正しくパースできることを確認してください。
クライミング低下低下regression: 以前は合格していたグループが、まとめて失敗するcollapseを確認するには、completions/duplicate_fracとentropyをチェックしてください。
高中央にany混合:0/1の報酬では、一部のプロンプトが簡単すぎたり、難しすぎたりします。部分採点の報酬では、グループが同じ部分点に留まることもあります。ロールアウトを読み取る

completions/duplicate_frac は、グループ内の各ターン全体を通じて、以前のロールアウトとトークン単位で完全に一致するロールアウトの割合です。同一のロールアウトには同一のリワードが付与されるため、重複は frac_zero_std_groups の値を押し上げます。

completions/duplicate_frac診断
0に近い値で、完了が短すぎて偶然に繰り返し得るほど短いタスクにはわずかなベースラインがありますhealthy: グループのロールアウトは独立してサンプリングされます
(num_generations - 1) / num_generations に向かってジャンプしますサンプリングはもはやランダムではありません:すべてのグループが1つのロールアウトのコピーとして返されます。例えば、温度が0である場合、またはデータ並列のvLLMエンジンがサンプリングシードを共有しているため同じテキストをデコードする場合(これを防ぐために、ワーカーはすべてのリクエストで一意のシードを送信します)
ゆっくりと上昇し、entropyは低下しますcollapse: ポリシーが各プロンプトに対して1つの回答に収束している

これらのメトリクスは、サンプルの学習時ではなく、ワーカーがグループをスコアリングした時点で記録されるため、学習よりわずかに先行して実行され、max_staleness を超えて後で破棄されるサンプルを含むグループも対象となります。すべての報酬関数が None を返したためスコアリングできなかったグループは破棄され、frac_zero_std_groups にカウントされますが、報酬が存在しないため、reward_zero_std_groups には含まれません。

ツリーパッキング

マイクロバッチのサンプルは、パディングなしでプロセスごとに1行にパッキングされます。行は連結ではなくプレフィックストライです。複数のサンプルで共有されるトークンは1回だけフォワードされ、アテンションは各サンプルにそのサンプル自身の履歴のみを正確に表示します。グループのロールアウトはすべてそのプロンプトを繰り返し、マルチターンロールアウトの各ターンはそれまでの会話を繰り返すため、フォワードはパッキング比(batch/packing_ratio)だけ縮小されます。これはレイアウトの変更のみです。学習対象の各トークンは、自身のターゲット、アドバンテージ、旧ログ確率を保持し、そのログ確率はサンプルを単独でフォワードした場合と一致します。

プロンプト1つに対する2回のロールアウトにおいて、pがプロンプト、aとbが2つの補完です:

1. Rollouts         r0:  p1 p2 p3 a1 a2                10 tokens
                    r1:  p1 p2 p3 b1 b2

2. Trie             S0 [p1 p2] ─┬─ S1 [p3 a1 a2]       p3 is not shared: a position predicts
                                └─ S2 [p3 b1 b2]       one token, and p3 predicts a1 or b1

3. Packed row       index         0  1 |  2  3  4 |  5  6  7
   (depth-first)    input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2    8 tokens: everything but attention
                    position_ids  0  1 |  2  3  4 |  2  3  4    runs on 8 instead of 10
                    segment      S0    | S1       | S2

4. Attention        segment   queries    keys and values: the segment's path in the trie
   (one call)       S0        p1 p2      p1 p2              index 0 1
                    S1        p3 a1 a2   p1 p2 p3 a1 a2     index 0 1 2 3 4
                    S2        p3 b1 b2   p1 p2 p3 b1 b2     index 0 1 5 6 7

5. Loss             r0: a1 a2 predicted at index 2 3   each trained token is predicted at the index
                    r1: b1 b2 predicted at index 5 6   of the token before it in its rollout

いくつかの帰結:

  • 共通の接頭辞は共有される: プロンプトのロールアウト、およびプロンプト間で共通のシステムプロンプトやツールスキーマです。サンプルは、そのグループがすでに保持されている行、つまりそのプロンプトがすでに存在する行に配置されます。その行が満杯になった場合、プロセスにまだ空の行がある場合、または最も負荷の高い行(マイクロバッチの時間を決定する行)の負荷が増えない場合は、サンプルは別の行に配置されます。それ以外の場合は、マイクロバッチがクローズされます。
  • 共有なしの場合は通常のパッキングです。各サンプルが独立したセグメントとなり、通常のpaddingなしのパッキングになります。
  • K/Vのみが複製される: 共有プレフィックスは各降下セグメントごとに1回だけ集められ、これはアンパックされた学習が保持する量とほぼ同じであり、グループクエリアテンションを使用する場合、そのサイズは小さくなります。
  • Gated DeltaNetハイブリッドがサポートされています(Qwen3.5、Qwen3.6、Qwen3-Next、…):その畳み込みは各トークン自身の先行トークンを参照し、チャンク化されたデルタルールは各セグメントを親の最終状態から開始します。

token_budget は行のトークン数を制限し、共有トークンは1回のみカウントします。デフォルトではサーバーの max_model_len となり、サンプルがこの値を超えることはありません。共有部分が何もない場合、ツリーパッキングは通常の padding-free パッキングとほぼ同じ速度で動作し、速度向上の幅はパッキング比率に概ね比例して大きくなります(Qwen3-0.6B と 1.7B、H100 上で、比率 3.4 のとき約 2.8 倍から 3 倍)。比率は共有プレフィックスの長さに行ごとのサンプル数を掛けたものなので、batch/samples_per_row が主要な指標となります。この値が 1 に近いと共有できるものがなく、調整のレバーは token_budget になります。batch/row_fill_frac はサンプルが長い場合に重要になります。10k トークンのサンプルでは 32k の予算にうまく収まりません(3 個は収まりますが 4 個は収まらず、プランナーは多くの場合 2 個を取得し、行の充填率は約 77% になります)。一方、1k トークンのサンプルではほぼ完璧に収まります。

スループットでツリーパッキングを評価してください。batch/trained_tokens_per_step / perf/fwd_bwd_s。パッキングされたマイクロバッチはより多くのサンプルを含むため、perf/fwd_bwd_sは上昇し、フォワードされたトークン数で割るperf/fwd_bwd_mfuは低下します。どちらもリグレッションではありません。1行あたりのサンプル数が増えることは、ステップごとに抽出されるロールアウト数が増えることを意味するため、生成がボトルネックとなる実行は、さらにその傾向が強まります。

バッチメトリクスは次のように構成されています: 1ステップはgradient_accumulation_steps × num_processes行を保持するため、batch/samples_per_stepはbatch/samples_per_rowの約その倍数となり、トークンについても同様です。ステップごとのメトリクスは合計値であり、行ごとのメトリクスは平均値であるため、両者は1ステップ内のマイクロバッチ間のばらつきを除いて一致します。

行が長くなったり、数が減ったりする処理は共有を解除します。分岐しないマルチターン会話では、1つの長いサンプルとなり、rollout/samples_per_rolloutは1つの会話から得られるサンプル数を示します。

Top-kおよびTop-pサンプリング

Top-k と top-p は、語彙全体ではなく、制限された候補セット上でサンプリング分布を再正規化します。サーバーの対数確率はそれを反映しており(--logprobs-mode processed_logprobs)、トレーナーも同じセット上で正規化する必要があります。そうしないと、すべての重要度比がバイアスを持ちます。語彙全体でのトークンの確率は、それが抽出された候補セットでの確率よりも低くなるためです(DeepSeek-V3.2、セクション 3.1)。top_p < 1 または top_k > 0 の場合、ワーカーはサーバーに各サンプリングされたトークンの候補セットを要求し、トレーナーはその上で対数確率を再正規化します。これにはサーバーのフラグがさらに 2 つ必要であり、vLLM が候補セットのサイズを top_k で制限するため、top_k を設定する必要があります。

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --return-sampling-mask \
    --enable-scale-out
from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    top_p=0.95,
    top_k=512,
)

--return-sampling-mask は、vLLM に候補セットを記録させるオプションです(vLLM 0.28 以降、V2 モデルランナー上で動作します。サーバーがこのフラグを拒否する場合は VLLM_USE_V2_MODEL_RUNNER=1 を設定してください)。また、--enable-scale-out は、その候補セットを返すトークンイン・トークンアウトエンドポイントを公開します。ワーカーは起動時にサーバーで両方の設定を確認します。古いバージョンの vLLM では候補セットを返せないため、トレーナーは語彙全体に対して正規化を継続し、バイアスのかかった比率について警告を発します。

PEFTでアダプターを学習

🤗 PEFT ライブラリとの緊密な統合をサポートしており、モデル全体を学習するのではなく、アダプターを学習して Hub で共有できます。

from datasets import load_dataset
from peft import LoraConfig
from trl import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

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

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3.5-2B",
        reward_funcs=accuracy_reward,
        train_dataset=dataset,
        peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
    )
    trainer.train()

すべてのウェイト同期では、更新されたポリシーをサーバーに送信する必要があります。デフォルトでは、トレーナーはアダプターをベースモデルにマージし、マージ後の完全なウェイトを送信します。7Bモデルの場合、1回の同期あたり約15 GBになります。--enable-loraオプションでvLLMサーバーを起動すると、アダプターのみが送信され、r=32の場合には約160 MBになります。

VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6

VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 を設定すると、トレーナーが各新しいアダプターを POST するエンドポイントが公開されます。--enable-lora を使用する場合でも、--weight-transfer-config を維持してください。トレーナーは起動時にのみ同期モードを選択しますが、その時点ではサーバーはすでに起動済みであり、マージされた同期がフォールバックとして使用されるためです。

--max-lora-rank は 1, 8, 16, 32, 64, 128, 256, 320, 512 のいずれかである必要があります。これはサーバーが提供できる最大のランクを設定するものであり、実際に提供するランクを指定するものではありません。そのため、r=4 のアダプターは 8 以下で問題なく動作します。--max-loras は少なくとも max_staleness + 2 である必要があります。トレーナーは max_staleness + 1 個のアダプターバージョンを登録したまま保持し、古いポリシーで開始されたロールアウトが生成の途中でポリシーを切り替えることなく、そのポリシーの下で完了できるようにします。また、各同期では、最も古いバージョンをアンロードする前に次のバージョンを読み込みます。トレーナーは起動時にこれらの値の両方をチェックし、サーバーを再起動するために必要な設定を通知します。

vLLM はネットワーク経由ではなくディスクからアダプターを読み込むため、トレーナーは各バージョンを<output_dir>/.vllm_lora/の下に書き出し、そのパスをサーバーに渡します。サーバーが別のマシンで実行される場合、そのディレクトリは両方のマシンからアクセス可能なファイルシステム上に存在する必要があります。

<output_dir>/.vllm_lora/ はサービング用キャッシュであり、学習したアダプタが保存される場所ではありません。ここには最新のバージョンのみが保持され、staleness window から外れた直後に削除されます。学習したアダプタを保持するのはチェックポイントです。そのため、チェックポイントの保存を無効にしないでください。save_strategy="no" を設定すると、数時間かけて実行しても何も残らずに終了してしまいます。output_dir はサーバーから読み取れる必要があり、ジョブの終了後も残存する必要があります。そのため、ノードローカルのスクラッチ領域は、遅い共有ファイルシステムでの同期を回避できる利点があっても機能しません。

Adapter sync が常に高速であるとは限りません。vLLM は、マージ済み重みをサーブする場合と比べて、LoRA アダプタをサーブする場合にトークンあたり約 1.33 倍から 1.39 倍遅くなります。RL では、生成が実時間(wall-clock time)を支配するケースが一般的です。その代わりとして得られるのは、各 sync 時の停止時間が大幅に短くなることと、sync 帯域幅が約 1% になることです。生成スループットがボトルネックとなっている場合は、マージ済み sync の方が依然として良い選択であることが多いです。

カスタム報酬関数を使用する

AsyncGRPOTrainerは、カスタム報酬関数の使用をサポートしています。互換性を確保するために、報酬関数は以下の要件を満たす必要があります。

報酬関数は、同期の Python コール可能オブジェクトまたは非同期の async def コルーチンのいずれかとして定義できます。複数の報酬関数を指定した場合、それらは並行して実行されます。非同期の関数はまとめて await され、同期の関数はスレッド内で実行されるため、レイテンシが重なり合います。

  1. 入力引数:

    • この関数は、次のものをキーワード引数として受け取らなければなりません:

      • prompts(プロンプトを含む)
      • completions(生成された補完を含む)
      • completion_ids(トークン化された補完を含む)
      • データセットが持つ可能性のあるすべての列名(promptを除く)。例えば、データセットにground_truthという名前の列が含まれている場合、関数はground_truthをキーワード引数として呼び出されます。

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

    • データセットは会話形式なので、promptsとcompletionsはメッセージの辞書のリストです。

  2. 戻り値: 関数は float のリストを返す必要があります。各 float は、1つの completion に対応する報酬を表します。

Reward 関数は、別プロセスである rollout worker で実行されるため、渡されるすべてのオブジェクトは pickled されます。各 Reward 関数、ツール、および environment_factory(それらがクロージャとして保持しているオブジェクトを含む)は pickle 可能である必要があります。モジュールレベルの関数、functools.partial、または callable なクラスインスタンス を使用してください。ラムダ関数やクロージャは、trainer.train() 呼び出し時に TypeError を引き起こします。これは GRPOTrainer との違いで、GRPOTrainer では Reward 関数がプロセス内で呼び出されるため、クロージャが使用できます。

ロールアウトプロセスもCUDA_VISIBLE_DEVICES=""で実行されるため、GPUを使用できません。GPUバックの報酬モデル(AutoModelForSequenceClassificationスコアラーなど)はエラーなくロードされますが、サイレントにCPUへフォールバックします。報酬関数は軽量なものにしてください(accuracy_rewardのような検証器、形式や長さのチェックなど)。GPU報酬モデルが必要な場合は、別のGPU上で独自の推論エンジン(vLLM、TGI、…)の背後で提供し、ピクルス化可能な報酬関数からHTTP経由で呼び出す構成にしてください。

例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 = [[{"role": "user", "content": "The sky is"}], [{"role": "user", "content": "The sun is"}]]  # not used in the reward function, but the trainer will pass it
>>> completions = [[{"role": "assistant", "content": " blue."}], [{"role": "assistant", "content": " 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]

例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[0]["content"]) 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 = [
...     [{"role": "user", "content": "Solve the equation $2x + 3 = 7$."}],
...     [{"role": "user", "content": "Solve the equation $3x - 5 = 10$."}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": r"The solution is \boxed{2}."}],
...     [{"role": "assistant", "content": 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: マルチタスク報酬関数

以下は、AsyncGRPOTrainerで複数の報酬関数を使用する例です。この例では、タスク固有の報酬関数としてmath_reward_funcとcoding_reward_funcを定義しています。math_reward_funcは数学問題の正答性に基づいて報酬を与え、coding_reward_funcはコーディング問題の解答が動作するかどうかに基づいて報酬を与えます。

from datasets import Dataset
from trl import AsyncGRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": [{"role": "user", "content": "What is 2+2?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "Write a function that returns the sum of two numbers."}], "task": "code"},
        {"prompt": [{"role": "user", "content": "What is 3*4?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "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
if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        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 を返し、AsyncGRPOTrainer は有効な関数とタスクで処理を続行します。これにより、AsyncGRPOTrainer は、適用範囲が異なる複数の報酬関数を処理できるようになります。

AsyncGRPOTrainerは、報酬関数が返すNoneの報酬を無視し、関連する関数が返した報酬のみを考慮します。これにより、モデルは関連するタスクで学習され、関連する報酬関数がないタスクは無視されるようになります。

例5: 非同期報酬関数

カスタム報酬関数は、async def コルーチンとして定義することもできます。報酬が低速な I/O に依存する場合(リモートサービスの呼び出しなど)に便利です。複数の非同期報酬関数を渡すと、AsyncGRPOTrainer はそれらを並行して実行し、レイテンシを重複させます。

以下は、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]

報酬関数をトレーナーに渡す

カスタム報酬関数を使用するには、AsyncGRPOTrainerに次のように渡します:

from trl import AsyncGRPOTrainer

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

リストとして複数の報酬関数を渡すことができます。このリストには、同期関数と非同期関数の両方が含まれる場合があります。

from trl import AsyncGRPOTrainer

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

報酬は、各関数からの報酬の合計として計算されます。

ロールアウトループのカスタマイズ

生成、報酬、アドバンテージ、フィルタリングは、AsyncRolloutLoop内のロールアウトプロセスで実行されます。これらを変更するには、ループをサブクラス化し、対象のステップのメソッドをオーバーライドして、そのサブクラスをトレーナーのサブクラスでloop_clsに設定します。トレーナーのコンストラクタは変更されません。

メソッド呼び出されましたデフォルト
filter_prompt(row_index, row, epoch)プロンプトごとに1回、生成の前にすべてのプロンプトを受け入れます
generate_one(prompt, tools, group_id)ロールアウトごとに1回マルチターンツールループ
generate_one_turn(prompt_ids)サンプリングリクエストごとに1回設定のサンプリング設定を含む1つのvLLMリクエスト
compute_advantages(group)group.rewards に報酬が合計された後、グループごとに1回グループ内で標準化された報酬
setup(), close()ループが開始し、停止するタイミングnothing

例えば、ポリシーがすでに解いているプロンプトのサンプリングを停止するカリキュラムは、そのしきい値をconfigのサブクラスに設定できます。

from dataclasses import dataclass

import numpy as np

from trl import AsyncGRPOConfig, AsyncGRPOTrainer
from trl.trainer.async_grpo_trainer import AsyncRolloutLoop


@dataclass
class CurriculumConfig(AsyncGRPOConfig):
    pass_rate_cap: float = 0.9


class CurriculumRolloutLoop(AsyncRolloutLoop):
    def filter_prompt(self, row_index, row, epoch):
        return self.pass_rates.get(row_index, 0.0) < self.config.pass_rate_cap

    async def setup(self):
        self.pass_rates = {}

    def compute_advantages(self, group):
        scored = group.rewards[~np.isnan(group.rewards)]
        if len(scored):
            self.pass_rates[group.row_index] = float(np.mean(scored > 0))
        return super().compute_advantages(group)


class CurriculumTrainer(AsyncGRPOTrainer):
    loop_cls = CurriculumRolloutLoop

reward_funcs、get_reward を定義する環境、およびカスタムの generate_one がその Rollout に設定する reward を合計して報酬を計算します。ジャッジでスコアリングする場合は非同期の報酬関数を渡し、generate_one の内部でスコアリングを行ってください。compute_advantages はすべてのグループに対して実行されます。スコアリングされた報酬がすべて等しいため後に除外されるグループも含まれます。除外の判定はアドバンテージではなく報酬に基づきます。ループは生成されたプロセス内で構築されるため、サブクラスはモジュールレベルで定義し、学習コードは if __name__ == "__main__": の下に配置してください。クライアントは __init__ をオーバーライドするのではなく、ループのイベントループ上で実行される setup で作成してください。filter_prompt によって拒否されたプロンプトは、そのエポックではスキップされ、除外されたグループと同様にエポックの回数にカウントされます。あるエポックのプロンプトがすべて拒否された場合、ループは例外を送出します。

チェックポイントからの再開

ベースのTrainerは、すでに学習済みのバッチをスキップして再生することで再開しますが、これはライブのロールアウトキューには適用されないため、ignore_data_skipは常にTrueです。代わりに、まだ学習されていない最初のプロンプトのインデックスが、各チェックポイントとともにrollout_state.jsonに保存され、再開時に復元されます。これにより、ワーカーはサンプルを再生せずにそのプロンプトまで高速転送します。これは生成器の位置ではなく、trainedの位置です。ワーカーはロールアウトキューの深さ分だけ学習より先行して動作し、これらのバッファリングされたサンプルは実行終了時に失われるため、生成器の位置から再開すると、生成されたが学習されなかったプロンプトがスキップされてしまいます。ストリーミングデータセット(IterableDataset)は再位置指定できないため、再開時にはワーカーが最初のプロンプトから再開します。

エージェントの学習

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

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

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

ツール

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

from trl import AsyncGRPOTrainer

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

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

モデルはツールをその名前で呼び出すため、各ツールは__name__で登録され、モジュールレベルの関数である必要があります。これにより、rollout worker に対して pickle 可能になります。同期ツールはmax_concurrent_rolloutsに設定されたサイズのスレッドプールで実行されるため、遅いツールが進行中の他の rollout をブロックすることはありません。1 つの assistant ターン内では、ツール呼び出しはモデルが出力した順序で実行されます。したがって、最大max_concurrent_rollouts個の同期ツールが同時に実行される可能性があるため、共有状態を読み書きするツールはスレッドセーフである必要があります。

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

AsyncGRPOConfig の max_tool_calling_iterations を使用して、ツール呼び出しのターン数を上限設定できます。デフォルトでは上限がなく、モデルがツール呼び出しを含まない応答ターンを生成した時点で生成が停止します。

例:

from trl import AsyncGRPOTrainer

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 = AsyncGRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

環境

environment_factory を通じてツールを提供することもできます。このモードでは、AsyncGRPOTrainer はロールアウトごとに1つの環境インスタンスを作成し、環境の公開メソッドをツールとして公開します。

environment_factory を使用する場合、環境がデータを所有します。外部の train_dataset は存在しません。各ロールアウトにおいて、reset() がタスクを生成します。これは、環境が保持するコーパスからの自己サンプリング、または状態の手続き的生成です。その後、プロンプトを返します。max_steps はトレーニングの長さを設定します。以下は、ターゲットを自己サンプリングし、increment メソッド(ツールとして公開)を公開する環境の最小限の例です。

import random

from trl import AsyncGRPOConfig, AsyncGRPOTrainer

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

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        args=AsyncGRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
        environment_factory=IncrementEnv,
    )
    trainer.train()

環境クラスには、resetとget_rewardという2つの予約メソッドがあります。他の公開メソッドとは異なり、これらはモデルにツールとして公開されません。

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

どちらもワーカーのツールスレッドプールで実行されるため、遅い環境は自身のロールアウトのみを遅延させ、進行中の他の環境には影響しません。それぞれの所要時間はenv/reset_sおよびenv/reward_sとして記録されます。

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

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

環境が自己サンプリングする代わりに、外部のtrain_datasetを指定できます。例えば、タスクがすでにデータセットに存在する場合や、複数の環境間でルーティングを行う場合などに使用できます。ロールアウトごとに、トレーナーは1行をサンプリングし、その"prompt"列をプロンプトとして使用し、行の各列をreset()へのキーワード引数として渡します(これにより、環境はデータセットからタスクを読み取ります)。

from datasets import Dataset
from trl import AsyncGRPOTrainer

# 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

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        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 経由で返すようにします。すべてのソースは重み 1 で合計されます。

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

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

複数の環境

単一のランで複数のタスクの混合(例: コーディングタスクとゲーム)を学習するには、単一の callable ではなく、環境名をファクトリにマッピングする辞書を渡します。各ロールアウトはデータセット内の environment フィールドを通じて環境を選択し、その環境のツールのみが公開されます。これにより、関連のないツールの漏洩(ゲームの move ツールがコーディングの例に、その逆がゲームに漏れること)を回避できます。各環境は引き続き自分のデータを所有し、reset() からプロンプトを返すため、データセットにはそれらの間でルーティングするための environment 列のみが必要です。

import random

from datasets import Dataset
from trl import AsyncGRPOConfig, AsyncGRPOTrainer


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
if __name__ == "__main__":
    dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

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

Environment インスタンスはステップ間で再利用されます(エピソード間でリセットされるため)、コストの高い __init__ は各ステップごとではなく一度だけ実行されます。environment フィールドはトレーナーによって消費され、reset には 転送されません。

マルチターンロールアウト

各ターンでは、チャットテンプレートを通じて会話全体がレンダリングされ、そこから生成が行われます。チャットテンプレートは、成長する会話を常に同じ方法でレンダリングするとは限りません(例えば、以前のターンの推論をドロップするものもあります)。そのため、あるターンのプロンプトトークンは、それまで保持されているトークンと異なる場合があります。ロールアウトの終了時、ワーカーは各ターンをトレーニングサンプルに調整します。保持されているトークンで始まるプロンプトを持つターンは同じサンプルに追加され、それ以外のターンは新しいサンプルを開始します。生成された各トークンは正確に1つのサンプル内でトレーニングされるため、フォークはフォワードトークンのコストは発生しますが、トレーニングシグナルのコストは発生しません。

ロールアウトの各サンプルには、そのロールアウトのアドバンテージが割り当てられます。rollout/fork_fracおよびrollout/drift_tokens_*は、ターンがどのように調整されたかを示しています。

環境統合

Harborサンドボックス内で動作するコーディングエージェントなど、独自のハーネス内で実行されるエージェントの学習については、OpenEnvガイドのハーネスでの学習を参照してください。

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

ビジョン言語モデル(Qwen3.5、Qwen3.6、Qwen3-VL など)は、テキストのみのデータセットで学習できます。モデル ID は通常どおり渡してください。その他の変更は不要です。

ビジョンタワーは凍結されています。テキストのみのデータセットでは画像トークンは生成されないため、フォワードパスによってタワーは実行されません。テキストモデル以外のすべて(ビジョンタワー、マルチモーダルプロジェクター)はrequires_grad=Falseが設定されており、勾配もオプティマイザの状態も取得しません。また、重みの同期ではスキップされるため、サーバーはチェックポイントから読み込んだ値を保持します。タワー自体は読み込まれるため、その重み分だけ GPU メモリを消費します。

画像はまだサポートされていません。画像を含むプロンプトは、vLLMサーバーや学習のフォワードパスには渡されません。マルチモーダル学習には、画像グリッドから3次元のM-RoPE位置を構築するために、パディングなしのパッキングパスが必要ですが、ここでは実装されていません。

AsyncGRPOTrainer

クラス trl.AsyncGRPOTrainer

< >

( model: str | PreTrainedModelreward_funcs: collections.abc.Callable[..., list[float]] | list[collections.abc.Callable[..., list[float]]] | None = Noneargs: trl.trainer.async_grpo_config.AsyncGRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneprocessing_class: 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)peft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset]] | None = None )

パラメータ

  • model (str または PreTrainedModel) — 学習対象のモデル。以下のいずれかです:
    • 文字列。huggingface.co のモデルリポジトリにホストされている事前学習モデルの model id、または save_pretrained を使用して保存されたモデルの重みを含む ディレクトリ へのパス。例: './my_model_directory/'。モデルは、その設定で宣言されたアーキテクチャで読み込まれます。ビジョン言語チェックポイントの場合は AutoModelForImageTextToText(ビジョンタワーは読み込まれますが凍結されます。Training Vision Language Models を参照)、それ以外の場合は AutoModelForCausalLM です。
    • PreTrainedModelオブジェクトです。そのアテンション実装は、パックトレーニング用に、トレーナーのツリーアテンションバックエンドに切り替えられます。

    config のモデル名は、生成に使用される vLLM サーバー上でモデルを識別するために使用されます。

  • reward_funcs (RewardFunc | list[RewardFunc], 省略可能) — 報酬の計算に使用する報酬関数です。報酬を計算するには、プロンプトと補完を引数としてすべての報酬関数を呼び出し、その報酬を合計します。 environment_factory (以下を参照) によって環境から報酬が供給される場合は省略できます。以下のいずれかの形式を指定できます:
    • 単一の報酬関数: 関数には、プロンプトと生成された補完、およびデータセット内の追加の列が渡されます。報酬のリストを返す必要があります。報酬関数は同期または非同期のいずれかであり、報酬が該当サンプルに適用されない場合はNoneを返すこともできます。これは、異なる報酬関数が異なるタイプのサンプルに適用されるマルチタスク学習に有用です。報酬関数がサンプルに対してNoneを返した場合、その報酬関数はそのサンプルの報酬計算から除外されます。詳細については、カスタム報酬関数の使用を参照してください。
    • …は報酬関数のリストです。各項目は上記で説明した報酬関数です。すべての関数からの報酬は合計されます。

    GRPOTrainer とは異なり、報酬は生成された子プロセス内で計算されるため、各報酬関数(tools および environment_factory を含む)は picklable である必要があります。モジュールレベルの関数、functools.partial、または callable なクラスインスタンスを使用してください。ラムダやクロージャは起動時に失敗します。ツールは __name__ によって登録されるため、モジュールレベルの関数である必要があります。また、子プロセスは CUDA_VISIBLE_DEVICES="" で実行されるため、GPU ベースの報酬モデルはトレーナーの GPU ではなく CPU(低速)で実行されます。

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

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

  • processing_class (PreTrainedTokenizerBase、任意) — データを処理するために使用される処理クラスです。パディング側は “left” に設定する必要があります。None の場合、from_pretrained を使用してモデル名から処理クラスを読み込みます。パディングトークン tokenizer.pad_token が設定されている必要があります。処理クラスにパディングトークンが設定されていない場合、tokenizer.eos_token がデフォルトとして使用されます。
  • 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 によって与えられるスケジューラーが使用されます。
  • peft_config (PeftConfig, 任意) — モデルをラップするために使用される PEFT 設定です。None の場合、モデルはラップされません。vLLM サーバーが --enable-lora を指定して起動された場合、LoRA アダプターはマージされた重みとしてではなく、アダプターとして同期されます。詳細は、AsyncGRPO ドキュメントの LoRA セクションを参照してください。
  • tools (Callable のリスト、省略可) — モデルが生成中に呼び出すことができる、呼び出し可能なツール関数(同期または非同期)のリストです。各ツールは、適切に型ヒントが付けられた引数と戻り値を持つ標準的な Python 関数であり、その目的、引数、戻り値を説明する Google スタイルのドキュメント文字列(docstring)が必要です。詳細については、https://huggingface.co/docs/transformers/en/chat_extras#passing-toolsを参照してください。モデルは、関数名、型ヒント、ドキュメント文字列を用いて、関数の呼び出し方法を決定します。モデルのチャットテンプレートがツールの使用をサポートしており、ツール呼び出し用にファインチューニングされていることを確認してください。
  • 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 で初めて提案されました。この Trainer は GRPO の非同期版であり、生成を外部の vLLM サーバーにオフロードします。このサーバーは学習と並行して非同期に動作し、ロールアウトを勾配更新ループから分離します。

例:

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

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

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

サンプリングするプロンプト、ロールアウトの生成方法、アドバンテージの計算方法をカスタマイズするには、AsyncRolloutLoopをサブクラス化し、それをトレーナーのloop_clsとして設定します。TRLはループを

ロールアウトプロセス:

>>> class CurriculumTrainer(AsyncGRPOTrainer):
...     loop_cls = CurriculumRolloutLoop

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 にアップロードします。

AsyncGRPOConfig

クラス trl.AsyncGRPOConfig

< >

( 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: str = 'constant'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 = 1logging_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 = Truerestore_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 = 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 = Nonedtype: str = 'float32'trust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonenum_generations: int = 8max_completion_length: int = 2048temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonechat_template_kwargs: dict | str | None = Nonemax_tool_calling_iterations: int | None = Nonevllm_server_base_url: str = 'http://localhost:8000'vllm_server_timeout: float = 1800.0epsilon: float = 0.2epsilon_high: float | None = Nonescore_centering: bool = Truevllm_importance_sampling_clip_min: float = 0.5vllm_importance_sampling_clip_max: float = 5.0num_sampler_logprobs: int = 8token_budget: int | None = Nonemax_concurrent_rollouts: int = 512max_staleness: int = 4weight_sync_steps: int = 1rollout_worker_timeout: float = 300.0log_completions: bool = Falsenum_completions_to_print: int | None = None )

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

  • model_init_kwargs (dict[str, Any] または str、省略可) — パスからモデルをインスタンス化する場合に from_pretrained に渡すキーワード引数です。revision の値は、処理クラスの読み込み時にも使用されます。
  • dtype (str, 省略可, デフォルトは "float32") — モデルを読み込む際のデータ型。 "auto", "bfloat16", "float16" または "float32". デフォルトは "float32" です。このトレーナーが基準とする学習・推論の不一致(FP16による学習・推論の不一致の克服) )は、トレーナー自体の精度に敏感です。このギャップをエンドツーエンドで解消するには、vLLMサーバーも同じdtypeで提供する必要があります(vllm serve --dtype); 。不一致が発生すると、学習開始時に警告としてログに記録されます。 dtype 内の model_init_kwargs が優先されます。

    これは、重みがロードされる際のdtypeのみを設定します。FSDPによる混合精度(bf16=Trueがデフォルト)の場合、accelerateはシャーディングの前に、すべての学習可能なパラメータをfp32にアップキャストします。そのため、dtypeの値に関わらず、マスターの重みとオプティマイザの状態はfp32となり、フォワードとバックワードはbf16またはfp16で実行されます。その結果、チェックポイントはfp32ではなく、その混合精度のdtypeで書き出されます。FSDPを使用しない場合は、アップキャストは行われません。dtype="bfloat16"とbf16=Trueを組み合わせると、重みとオプティマイザの状態がbf16のまま保持され、純粋なbf16での学習となります。

  • 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.
  • router_aux_loss_coef (float, 任意) — Mixture-of-Experts (MoE) モデルにおける負荷分散用の補助損失の係数です。この重みで学習損失に追加されます。設定されていない場合、モデル設定で宣言された値が使用されます。0.0 に設定すると無効になります。MoE 以外のモデルで使用するとエラーになります。

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

  • num_generations (int、任意、デフォルトは8) — プロンプトごとにサンプリングする生成の回数。
  • max_completion_length (int、任意、デフォルトは2048) — vLLM リクエストごとに生成されるトークンの最大数です。マルチターン・ロールアウトでは、ターンごとに適用されます。
  • temperature (float、任意、デフォルトは1.0) — サンプリング用の温度です。温度が高いほど、補完はランダムになります。
  • top_p (float、任意、デフォルト値は1.0) — 考慮する上位トークンの累積確率を制御する浮動小数点数です。値は (0, 1] の範囲でなければなりません。すべてのトークンを考慮するには 1.0 に設定します。1.0 未満の場合、top_k も設定する必要があり、--return-sampling-mask --enable-scale-out を指定して vLLM サーバー (>= 0.28) を起動する必要があります。サーバーと同様に、トレーナーは各トークンがサンプリングされた候補セットに対して対数確率を再正規化します。古いバージョンの vLLM では、語彙全体が保持されます。
  • top_k (int、任意、デフォルトは0) — トップkフィルタリングのために保持する、確率の高い語彙トークンの数。0の場合、トップkフィルタリングは無効になり、すべてのトークンが対象となります。その他の値には、top_pの項で説明されているサーバーフラグが必要です。
  • min_p (float, 省略可) — トークンの最小確率です。最も確率の高いトークンの確率でスケーリングされます。0.0 から 1.0 までの値である必要があります。一般的な値は 0.01 から 0.2 の範囲です。0.0 以上の場合、top_p の下に説明されているサーバーフラグとともに、top_k も設定する必要があります。
  • chat_template_kwargs (dict[str, Any], 省略可) — 補完を生成する際にapply_chat_template関数に渡す追加のキーワード引数。
  • max_tool_calling_iterations (int, 任意) — エージェントの学習におけるツール呼び出しのターン数の上限です。None の場合、上限はなく、モデルがツール呼び出しを含まない応答ターンを生成した時点で生成が停止します。

vLLMサーバーを制御するパラメータ

  • vllm_server_base_url (str, 任意、デフォルトは "http --//localhost:8000"): 生成に使用される vLLM サーバーのベース URL (例: "http://localhost:8000")。
  • vllm_server_timeout (float、任意、デフォルトは1800.0) — vLLM サーバーへの呼び出しのタイムアウト(秒)です。起動時のサーバーの準備完了待ち、各生成リクエスト、および各ウェイト同期呼び出しに適用されます。サーバーの待機とウェイト同期呼び出しでは、タイムアウト時に例外が発生します。生成リクエストがタイムアウトした場合は、リトライされます。

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

  • epsilon (float, 任意、デフォルトは 0.2) — クリッピング用のエプシロン値。
  • epsilon_high (float, オプション) — クリッピング用の上限エプシロン値です。指定しない場合、引数 epsilon で指定された下限値と同じ値がデフォルトとして使用されます。論文 DAPO では 0.28 が推奨されています。
  • score_centering (bool、任意、デフォルトは True) — クリップされた目的関数の代わりに、スコアセンタリング (論文) を用いて学習するかどうかです。これは、サンプリングされた各トークンの重要度重み付きスコアから、vLLM サンプラー下での期待値を引いたものとし、一定のアドバンテージがポリシーをサンプラー側に引き寄せるのを防ぐことを目的としています。期待値は、各位置における num_sampler_logprobs 個の最尤トークンに対して取り、その対数確率はサンプラーが報告します。
  • vllm_importance_sampling_clip_min (float、任意、デフォルト値は0.5) — ポリシーと vLLM サンプラー間の重要性比の下限 C_min です。比が [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] の範囲外にあるトークンは、損失から除外されます(マスクされた重要性サンプリング)。
  • vllm_importance_sampling_clip_max (float、任意、デフォルトは5.0) — 重要度比の上限 C_max。
  • num_sampler_logprobs (int、任意、デフォルトは8) — 生成された各トークンについて、vLLM のサンプラーから要求する上位の対数尤度の数です。スコア中心化に使用されます。数を増やすとサンプラーの確率質量をより多くカバーできますが、シリアライズのコストが増加します。サーバーの--max-logprobsによって上限が設定されます。
  • token_budget (int, 任意) — 1 行 (1 つの DP ランクの forward) で転送されるトークンの最大数です。TokenBudgetBatcher は、アテンションコストがバランスの取れたマイクロバッチを形成し、各行がこの予算内に収まるようにします。これにより、サンプル数 (1 行あたりのサンプル数は動的になります) に依存せずにピークメモリを制限できます。この予算は生トークンではなくユニークなトークンを制限するため、複数のサンプルで共有されるトークンは 1 回のみカウントされます。また、行の損失項も制限されます。None (デフォルト) の場合、vLLM サーバーの max_model_len (学習開始時にクエリされます) に設定されます。これはプロンプト + 補完の長さの上限であり、どのロールアウトサンプルも予算を超えないことを保証します。token_budget より長いサンプルはどの行にも収まらず、警告とともに破棄されます。

非同期ロールアウトパイプラインを制御するパラメータ

  • max_concurrent_rollouts (int、任意、デフォルト値は512) — 同時に実行されるロールアウトの最大数です。各ロールアウトは環境を保持し、同期ツール呼び出しを実行する可能性があり、vLLM サーバーへの接続を維持するため、これらのリソースが処理できる量に合わせて設定してください。この値を下回る場合、実行中のロールアウト数は、vLLM サーバーの KV キャッシュ使用量とmax_stalenessによって決まります。
  • max_staleness (int、任意、デフォルトは4) — ロールアウトサンプルが破棄される前に、現在のモデルバージョンに対して許容される最大ウェイト更新ステップ数です。生成はこれに制約されます。キューに入れられたトークンと処理中のトークンが、トレーナーがmax(max_staleness, 1)ステップで消費する量に収まる場合のみ、新しいロールアウトグループが開始されます。
  • weight_sync_steps (int、任意、デフォルトは1) — vLLMサーバーへの重みの同期の間隔となる学習ステップ数。
  • rollout_worker_timeout (float、任意、デフォルト値は300.0) — rollout workerの最後のハートビートから、トレーナーがハングと判断して処理を中断するまでの秒数。

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

  • log_completions (bool、任意、デフォルトはFalse) — logging_steps ステップごとに、(プロンプト、補完) のペアのサンプルをログに記録するかどうか。
  • num_completions_to_print (int, 省略可) — richで表示する補完の数を指定します。Noneの場合、すべての補完がログに記録されます。

AsyncGRPOTrainerの構成クラスです。

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

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

  • logging_steps: デフォルト値が500ではなく1になります。
  • gradient_checkpointing: デフォルト値がFalseではなくTrueに変更されました。
  • bf16: fp16が設定されていない場合、デフォルトでFalseではなくTrueになります。
  • learning_rate: 5e-5ではなく、デフォルト値が1e-6に変更されました。
  • lr_scheduler_type: linear ではなく、デフォルトが constant になっています(下記を参照)。
  • ignore_data_skip: 既定値がFalseではなくTrueに変更されました。ベースのTrainerのスキップおよびリプレイのループは、非同期のロールアウトキューには適用されません。
  • remove_unused_columns: デフォルト値がTrueではなくFalseに変更され、Falseのままにする必要があります。すべてのデータセットの列が報酬関数に渡されるためです。

メッセージモードの調整における学習期間と学習率: マルチターン会話では、書き換えによって新しい行が開始されるため、1つの会話が可変数の学習行に分岐します。そのため、エポックあたりのサンプル数、ひいてはオプティマイザーステップ数は事前には確定しません。その結果:

  • num_train_epochs は、prompt データセットに対する完全なパスの数でトレーニングを制限します。これは、実際にトレーニングに使用された個別のプロンプトの数としてカウントされます。これはフォークが生成する行数とは独立しており、N エポックを要求すると、常にデータを N 回パスしてトレーニングが行われます。max_steps が設定されていない場合、これが停止条件となり、max_steps は安全上の上限としてのみ機能します。
  • max_stepsが明示的に設定されている場合(> 0)、停止条件として優先的に適用され(エポックではなくオプティマイザのステップ数で上限を定める)、エポックベースの停止が無効になります。
  • lr_scheduler_typeのデフォルト値はconstantです。減衰の期間(ホライズン)はオプティマイザーステップ数で測定されるため、ステップ数がフォークレートに依存して事前には確定できない場合があるためです。減衰する学習率を使用するには、減衰スケジュールと明示的なmax_stepsをセットで設定してください。

AsyncRolloutLoop

クラス trl.trainer.async_grpo_trainer.AsyncRolloutLoop

< >

( config: AsyncGRPOConfigmodel_name: strdataset: Datasetreward_funcs: list[collections.abc.Callable[..., list[float]]]processing_class: PreTrainedTokenizerBaseeos_token_ids: list[int]rollout_buffer: Queuemodel_version_value: Synchronizedtoken_allowance: Synchronizedheartbeat_value: Synchronizedfailed_event: Eventexception_info_queue: Queuemetrics_queue: Queuetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], object] | dict[str, collections.abc.Callable[[], object]] | None = Nonescore_queue_maxsize: int = 16lora_name: str | None = Nonedataset_start_index: int = 0 )

スポンされたロールアウトプロセス内で、AsyncGRPOTrainerのロールアウトを生成してスコアリングします。

デフォルトではGRPOを実装しています。実行をカスタマイズするには、サブクラスを作成し、変更するメソッドのみをオーバーライドして、そのサブクラスをトレーナーのloop_clsに設定します。各プロンプトは、以下の順序で処理されます。

  • filter_prompt(): プロンプトに対して生成を行うかどうか。
  • generate_one(): 1回の完全なロールアウト。各サンプリングリクエストに対してgenerate_one_turn()を呼び出します。
  • num_generations 個のロールアウトからなるグループにスコアが付けられます。その報酬は、トレーナーの reward_funcs、get_reward を定義する環境、および Rollout.reward の合計です。その後、compute_advantages() がグループごとに 1 回実行されます。

setup() と close() は、HTTP クライアントのように、ループのイベントループ上でリソースの作成と解放を行います。フックは self.config(AsyncGRPOConfig のサブクラスは独自のフィールドを持つことができます)と self.tokenizer を読み取ることができます。ループはスポンされたプロセス内で構築されるため、サブクラスはインポート可能である必要があります(モジュールレベルで定義されている必要があります)。

filter_prompt

< >

( row_index: introw: dict[str, typing.Any]epoch: int ) → bool

パラメータ

  • row_index (int) — 学習データセット内の行のインデックス。
  • row (dict[str, Any]) — データセットの行です。
  • epoch (int) — このエポックの前に完了した、データセット全体を1周するパスの回数。

戻り値

bool

True を指定するとプロンプトに対して num_generations 回のロールアウトを生成し、False を指定するとスキップします。

プロンプトに対して生成を行うかどうかを指定します。拒否されたプロンプトは、このエポックではスキップされ、ドロップされたグループと同様に消費済みとしてカウントされます。デフォルトではすべてのプロンプトを許可します。エポック全体のプロンプトを拒否すると、その後バッチがトレーナーに到達できなくなるため、例外が発生します。

generate_one

< >

( prompt: list[dict[str, str]]tools: list[collections.abc.Callable]group_id: int = 0 ) → Rollout

パラメータ

  • prompt (list[dict[str, Any]]) — プロンプトメッセージ。
  • tools (list[Callable]) — このロールアウトで利用可能なツール: トレーナーの tools に加えて、environment_factory を使用する場合の環境のパブリックメソッド。
  • group_id (int、任意、デフォルトは0) — ロールアウトが属するグループの識別子。

完成したロールアウト。

プロンプトに対して1つのロールアウトを生成します。

デフォルトでは、マルチターンのツールループが実行されます。各ターンでは、チャットテンプレートを使用して会話全体をレンダリングし、generate_one()で応答をサンプリングし、含まれるツール呼び出しを実行します。モデルがツール呼び出しを停止するか、max_tool_calling_iterationsに達するまで続行します。エージェントフレームワークなどを使用して異なる方法で生成する場合は、このループをオーバーライドしてください。学習シーケンスはこれらから構築されるため、Rollout.turnsにすべてのサンプリングリクエストを返してください。また、ここでロールアウトをスコアリングするためにRollout.rewardを設定してください。

generate_one_turn

< >

( prompt_ids: list[int] ) → TurnRecord

パラメータ

  • prompt_ids (list[int]) — プロンプト全体のトークン ID。

戻り値

TurnRecord

プロンプトと、サンプリングされたトークンとその対数確率。top_kまたはtop_pを使用する場合、各サンプリングされたトークンの候補セットも保持されます。num_sampler_logprobsを使用する場合、サンプラーの上位の対数確率も保持されます。

vLLMサーバーから1つの応答をサンプリングします。設定のサンプリング設定(temperature、top_p、top_k、min_p、repetition_penaltyおよびmax_completion_length)を使用します。

compute_advantages

< >

( group: RolloutGroup ) → np.ndarray

パラメータ

  • group (RolloutGroup) — 1つのプロンプトのnum_generations個のロールアウトで、その総報酬はgroup.rewardsに格納されています。

戻り値

np.ndarray

group.rewardsの順序に従って、ロールアウトごとの1つの利点。

グループの各ロールアウトごとに1つのアドバンテージを計算します。デフォルトでは、各報酬はグループ内で標準化されます。報酬がNaNのロールアウトにはアドバンテージ0が割り当てられ、平均と標準偏差の計算から除外されます。

It runs for every group. スコア付き報酬がすべて等しいグループは、この処理がどのようなアドバンテージを返すかを問わず、除外されます。

セットアップ

< >

( )

他のフックが必要とするリソース(HTTPクライアントなど)を作成します。最初のプロンプトの前に、ループのイベントループ上で実行されます。デフォルトでは何も行いません。

閉じる

< >

( )

setup() が作成したものを解放します。ループが停止したときに実行されます。失敗した場合にも実行されます。デフォルトでは何も行いません。

ロールアウト

クラス trl.trainer.async_grpo_trainer.Rollout

< >

( completion: list[dict[str, str]]completion_ids: list[int]turns: list[trl.trainer.async_grpo_trainer.TurnRecord]tool_call_count: int = 0tool_failure_count: int = 0reward: float | None = Nonerollout_id: str = <factory> )

パラメータ

  • completion (list[dict[str, Any]]) — Messages generated after the prompt, in conversational format. Passed to the reward functions as completions.
  • completion_ids (list[int]) — 生成された completion のトークン ID です。completion_ids として報酬関数に渡されます。
  • turns (list[TurnRecord]) — ロールアウトを生成したサンプリングリクエストを、順序どおりに並べたものです。学習シーケンスはこれらから構築されます。サンプリングされたトークンは学習対象となり、各プロンプトの残りはコンテキストとして扱われます。
  • tool_call_count (int、任意、デフォルトは0) — ロールアウト中に実行されたツール呼び出しの回数です。
  • tool_failure_count (int、任意、デフォルトは0) — 失敗したツール呼び出しの数。
  • reward (float, 任意) — 生成中に計算される報酬です。例えば、外部のグレーダーによって計算されたものなどが該当します。この値は、報酬関数や環境の報酬に追加されます。None の場合、このロールアウトにはこのソースからの報酬が与えられません。
  • rollout_id (str, 任意) — デバッグ用に、学習行におけるロールアウトを識別します。デフォルトでは、新しいランダムな16進IDが使用されます。

generate_one()によって返される、1回のロールアウトの完了結果。

TurnRecord

クラス trl.trainer.async_grpo_trainer.TurnRecord

< >

( prompt_ids: list[int]output_ids: list[int]output_log_probs: list[float] = <factory>output_mask: list[int] | None = Noneoutput_sampling_mask: list[list[int]] | None = Noneoutput_sampler_logprobs: list[dict[int, float]] | None = None )

パラメータ

  • prompt_ids (list[int]) — このターンに送信されたプロンプト全体のトークン ID。会話の以前のすべてのターンを含みます。
  • output_ids (list[int]) — サンプラーが生成したトークンIDです。
  • output_log_probs (list[float]、任意、デフォルトは []) — output_ids 内の各トークンの Sampler の対数確率。いずれかが学習対象の場合に必要です。
  • output_mask (list[int]、省略可) — output_ids の各トークンに対応する値: トークンを学習対象にする場合は 1、コンテキストとしてのみ保持する場合は 0。None の場合、すべての出力トークンが学習対象になります。
  • output_sampling_mask (list[list[int]], 省略可) — output_ids の各トークンに対応するリスト: top_k / top_p による切り詰めにおいて、サンプラーが選択し得たトークン ID です。None の場合は、語彙全体です。
  • output_sampler_logprobs (list[dict[int, float]], 任意) — output_ids の各トークンに対応する辞書: トークン ID をキーとして、サンプラーが最も可能性が高いと判断したトークンの対数確率を格納します。スコア中心化 (num_sampler_logprobs) に使用されます。

1つのサンプリングリクエスト: サンプラーに送信されたプロンプトと、それによって生成されたトークン。

RolloutGroup

クラス trl.trainer.async_grpo_trainer.RolloutGroup

< >

( prompts: list[list[dict[str, str]]]reward_kwargs: dict[str, list[typing.Any]]completions: list[list[dict[str, str]]]completions_ids: list[list[int]]completions_sequences: list[list[trl.trainer.async_grpo_trainer.TrainingSequence]]tool_call_counts: list[int]tool_failure_counts: list[int]model_version: intgroup_id: introw_index: intenv_rewards: list[tuple[type, float] | None]rollout_rewards: list[float | None]queued_at: float = 0.0rewards: numpy.ndarray | None = None )

パラメータ

  • prompts (list[list[dict[str, Any]]]) — 各ロールアウトのプロンプト。
  • reward_kwargs (dict[str, list[Any]]) — プロンプトのデータセット行の他のカラムで、キーワード引数として報酬関数に渡されます。
  • completions (list[list[dict[str, Any]]]) — 各ロールアウトの補完メッセージ。
  • completions_ids (list[list[int]]) — 各ロールアウトの補完トークンIDです。
  • completions_sequences (list[list[TrainingSequence]]) — 各ロールアウトから構築されたトレーニングシーケンスです。ターン間で再トークナイズされた履歴が変更されたロールアウトでは、1つ以上のシーケンスが生成されます。
  • tool_call_counts (list[int]) — 各ロールアウトにおけるツール呼び出しの数。
  • tool_failure_counts (list[int]) — 各ロールアウトにおける失敗したツール呼び出しの数。
  • model_version (int) — グループの最初のロールアウトが開始された時点のポリシーバージョン。
  • group_id (int) — ロールアウトプロセスにおいて0から数えたグループの識別子。
  • row_index (int) — 学習データセットにおけるプロンプトの行のインデックス。
  • env_rewards (list[tuple[type, float] or None]) — get_rewardを定義している環境を持つロールアウトの場合、環境クラスとその報酬。それ以外の場合はNone。
  • rollout_rewards (list[float or None]) — 各ロールアウトのRollout.reward。
  • queued_at (float、任意、デフォルトは0.0) — グループがスコアリング用にキューに投入された時点のtime.monotonic()。
  • rewards (np.ndarray, 任意) — 各ロールアウトの総報酬。すべての報酬ソースで合計された値で、どのソースもスコアリングしなかった場合は NaN になります。compute_advantages() が呼び出される前に設定されます。

1つのプロンプトのnum_generations回のロールアウトをまとめてスコアリングします。各リストには、ロールアウトごとに1つのエントリが含まれます。

Update on GitHub