非同期GRPO

このトレーナーにはvllm、transformers>=5.2.0、kernels（学習時にこれを通じて Hub から FlashAttention を読み込む）が必要です。分散学習では、FSDP2 のみサポートされています（DeepSpeed ZeRO はサポートされていません）。

現在、vllmとtransformersの依存関係の制約が競合しています。これを回避するには、まずvLLMをインストールし、次にtransformersを強制インストールし、その後TRLのextraを通じてkernelsを追加します。これにより、transformersが受け入れるバージョンが固定されます。

コピーしました

pip install vllm
pip install 'transformers>=5.2.0' --no-deps
pip install 'trl[kernels]'

概要

experimental.async_grpo.AsyncGRPOTrainer は同じ GRPO アルゴリズムを実装していますが、ロールアウトの生成と学習を分離します。バックグラウンドワーカーが vLLM サーバーから補完を継続的にストリーミングで送信し、学習ループがそれらを消費するため、生成と勾配の更新が交互に実行されるのではなく、オーバーラップして実行されます。API は GRPOTrainer と同じ構成です。GRPO 手法自体の詳細（アドバンテージの計算、KL 推定、損失の定式化、報酬関数など）については、GRPO Trainer のドキュメントを参照してください。GRPOTrainer のすべての機能が利用可能というわけではなく、サポートされているパラメータについては experimental.async_grpo.AsyncGRPOConfig を参照してください。

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

GRPOTrainerとの違い

標準的なGRPOTrainerでは、生成と学習が逐次実行されます。バッチを生成し、損失を計算し、重みを更新し、これを繰り返します。vLLM colocate モードのように生成が同じ GPU 上で実行される場合でも、一方のフェーズが完了するまで、もう一方のフェーズは開始できません。

experimental.async_grpo.AsyncGRPOTrainer は、これら2つの関心事を分離します：

• Rollout worker（バックグラウンドプロセス）— vLLMサーバーにプロンプトを送信し、報酬関数で補完をスコアリングし、アドバンテージを計算し、学習可能なサンプルをキューにプッシュします。
• 学習ループ（メインプロセス）— キューからサンプルを取得し、クリップされたサーロゲート損失を計算して、モデルの重みを更新します。

ロールアウトワーカーはトレーナーから生成された別プロセスで実行されるため、報酬の計算はトレーニングループとGILを競合しません。このため、reward_funcs、tools、environment_factory（後者については、OpenEnvガイドを参照してください。このガイドでは、契約と利用可能な統合について説明しています）として渡すことができるものについて、2つの制約が生じます：

ロールアウトワーカーは別プロセスで実行されるため、渡されるすべてのデータはピクルス化されます。したがって、各報酬関数、ツール、environment_factory（およびそれらがクロージャとして保持しているオブジェクト）は、ピクルス化可能である必要があります。モジュールレベルの関数、functools.partial、または呼び出し可能なクラスインスタンスを使用してください。ツールは例外です。モデルはツールをその名前で呼び出すため、各ツールは__name__で登録され、モジュールレベルの関数である必要があります。ラムダ関数やクロージャは、trainer.train()時にTypeErrorを発生させます。これはGRPOTrainerとの違いで、ここでは報酬関数がプロセス内で呼び出されるため、クロージャが使用できます。

ロールアウトプロセスもCUDA_VISIBLE_DEVICES=""で実行されるため、GPUを使用できません。GPUバックの報酬モデル（例: AutoModelForSequenceClassificationスコアラー）はエラーなくロードされますが、CPUにサイレントにフォールバックします（GRPOTrainerでは、そのような報酬モデルはトレーナーのGPUを共有する点に注意してください）。報酬関数はCPU側で軽量なものにしてください（accuracy_rewardのような検証器、形式/長さチェックなど）。

GPU 上の報酬モデルが必要な場合、推奨されるアプローチは、独自の推論エンジン（vLLM、TGI など）の背後で提供し、別の GPU 上で動作させ、軽量で pickle 可能な報酬関数から HTTP 経由で呼び出すことです。これにより、報酬モデルは独自のデバイス上で動作し、ロールアウトプロセスは CPU のみで実行されるため、トレーナーとは独立してスケーリングできます。

ツールおよび環境のメソッドは、同期または非同期のいずれかです。同期ツールはmax_concurrent_rolloutsに設定されたサイズのスレッドプール上で実行されるため、遅いツールが他の実行中のvLLMリクエストをブロックすることはありません。1つのアシスタントターン内では、ツール呼び出しはモデルが出力した順序で実行されます。したがって、最大max_concurrent_rollouts個の同期ツールが同時に実行されるため、共有状態を読み書きするツールはスレッドセーフである必要があります。

weight_sync_steps 回の学習ステップごとに、更新された重みが NCCL を介して vLLM サーバーに転送され、その後の生成が最新のポリシーを反映するようにします。

生成と学習が並行して実行されるため、学習サンプルは、やや古いバージョンのモデルによって生成された可能性があります。max_staleness パラメータは、サンプルが破棄される前に、何回の重み更新分遅れていてもよいかを制御します。

並行性

vLLMサーバーに送信される同時リクエストの数はmax_concurrent_rolloutsによって上限が設定されます。デフォルトでは、max(max_staleness, 1) × per_device_train_batch_size × gradient_accumulation_steps × num_processesに自動的に設定されます。これは、トレーナーがサンプルが古くなる前に消費できる最大サンプル数です。これを超えるサンプルを生成しても、余分なサンプルは破棄されるため無駄になります。

max_concurrent_rollouts は上限値であり、実際に処理中のリクエスト数ではありません。ワーカーは数秒ごとにサーバーの /metrics エンドポイントをポーリングし、その上限値の直下でライブキャップ（rollout/concurrency_cap）を維持します。ある一定の並行度を超えると、KV キャッシュが埋まり、シーケンスがプリエンプトされて再計算され、キャッシュされたプレフィックスが追い出されて再プリフィルされるため、リクエストを増やしても vLLM は 遅くなります。キャップは起動時にサーバーから読み取られる KV cache tokens / max_model_len から始まります。これはフルレングスで収まるリクエスト数であり、最初のステップでスラッシングが発生しないようにするためです。キューに何も待機しておらず、使用率が 0.6 未満のままである間、キャップ分のロールアウトが完了するたびにキャップは 25% ずつ増加し、上限値まで引き上げられます。KV キャッシュの使用率が 0.8 を超えると、キャップは 30% 削減されます。実行中のリクエストはキャンセルされず、プールが新しいキャップを下回るまで新規リクエストの受け入れが停止し、それまでさらなる削減は行われません。サーバーが /metrics を公開していない場合、キャップは上限値のまま維持されます。

チェックポイントと再開: ignore_data_skip のデフォルト値は True です。ベースの Trainer のスキップおよびリプレイのループは、ライブのロールアウトキューには適用されません。代わりに、まだ学習されていない最初のプロンプトのインデックスが、各チェックポイントとともに rollout_state.json に保存され、再開時に復元されます。これにより、ワーカーはサンプルをリプレイせずにそのプロンプトまで高速転送します。これは生成器の位置ではなく、学習済みの位置です。ワーカーはロールアウトキューの深さ分だけ学習より先行して動作し、これらのバッファリングされたサンプルは実行終了時に失われるため、生成器の位置から再開すると、生成されたが学習されなかったプロンプトがスキップされてしまいます。ストリーミングデータセット（IterableDataset）は再位置指定できません。そのため、再開時にワーカーはプロンプト 0 から再起動します。FSDP を bf16=True（デフォルト）または fp16=True で使用する場合、マスターウェイトが fp32 であるにもかかわらず、model.safetensors はその dtype で書き出されます。そのため、プッシュされたチェックポイントはサーブされるモデルのサイズであり、その 2 倍ではありません。fp32 のマスターウェイトとオプティマイザの状態は、再開ファイル（pytorch_model_fsdp.bin、optimizer.bin）に保存され、再開時に読み込まれるのはこれらなので、再開には影響しません。FSDP を使用しない場合、チェックポイントは再開ファイルでもあるため、マスターの dtype が保持されます。

クイックスタート

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

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

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

vLLMサーバーとトレーナーは、別々のGPUで実行する必要があります。CUDA_VISIBLE_DEVICESを使用してGPUを分割してください。例えば、2つのGPUがある場合、vLLMサーバーをGPU 0で、トレーナーをGPU 1で実行するには、次のようにします:

# Terminal 1: vLLM server on GPU 0 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}'

--max-model-len を、想定される最大合計シーケンス長（プロンプト + 補完）に設定してください。値を下げるとサーバーの GPU メモリ使用量が減少し、KV キャッシュに割り当てられるメモリが増えるため、スループットが向上します。適切な初期値は、プロンプトの長さに設定ファイルの max_completion_length を加えたものです。

# Terminal 2: training on GPU 1
CUDA_VISIBLE_DEVICES=1 accelerate launch train_async_grpo.py

AMD GPU

Trainer は AMD GPU (ROCm) で追加のセットアップなしで動作します。上記のコマンドはそのまま使用できます。学習では、AMD GPU には kernels-community/aiter-flash-attn アテンションカーネル、NVIDIA Blackwell GPU には kernels-community/flash-attn4、その他の NVIDIA GPU には kernels-community/flash-attn3 が使用され、これらはすべて kernels ライブラリによって Hub からダウンロードされます。アテンションのロジットに上限を設ける (attn_logit_softcapping) モデル (Gemma 2 など) は、AMD GPU および NVIDIA Blackwell GPU ではサポートされていません。

ビジョン言語モデル

ビジョン言語モデル（Qwen3.5、Qwen3.6、Qwen3-VL など）は、テキストのみのデータセットで学習できます。モデル ID を通常通り渡すだけで、その他の変更は不要です：

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

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

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

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 を設定する必要があります。

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --return-sampling-mask \
    --enable-scale-out

config = 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 では候補セットを返せないため、トレーナーは語彙全体にわたって正規化を継続し、バイアスのかかった比率について警告を発します。

スコアの中央化

サーバーの log-probabilities は、トレーナーのものと完全に一致することはありません。カーネルの違い、精度の違い、数ステップ遅れたポリシーなどが原因です。重要度重みだけではこれを補正できません。なぜなら、サンプリングされたトークンのスコア $\nabla_\theta \log \pi_\theta$ は、サンプラーの下では平均がゼロにならないため、すべての更新がポリシーをサンプラーの方へ引き寄せてしまうからです（スコアの中心化). デフォルトでは、トレーナーは各位置でその期待値を差し引きます（score_centering=True), サンプラーの num_sampler_logprobs 最も可能性の高いトークンで推定し、サンプラーに対する重要度比が [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max]. そのために、ワーカーはサーバーから生成されたすべてのトークンの上位 log-probabilities を要求し、トークンごとにシリアライズします。大きな num_sampler_logprobs はサーバーを遅くし、その --max-logprobs が受け入れる上限を決定します。 score_centering=False クリップされた目的関数のみで学習します。 sampling/masked_mean は、境界によって除外されたトークンの割合であり、 sampling/sampler_mass は、上位トークンでカバーされるサンプラーの確率質量です。

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 によりアップストリームで修正されています。

LoRA

peft_config を渡すことで、モデル全体ではなく LoRA アダプターを学習できます:

from peft import LoraConfig

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-4B",
    reward_funcs=reward_len,
    train_dataset=dataset,
    peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)

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

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --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 の方が依然として良い選択であることが多いです。

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

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

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

from dataclasses import dataclass

import numpy as np

from trl.experimental.async_grpo import AsyncGRPOConfig, AsyncGRPOTrainer, 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 がその experimental.async_grpo.Rollout に設定する reward について、報酬は合計されます。ジャッジでスコアリングする場合は非同期の報酬関数を渡し、generate_one の内部でスコアリングを行ってください。compute_advantages はすべてのグループに対して実行されます。スコアリングされた報酬がすべて等しいため後に除外されるグループも含まれます。除外の判定は報酬に基づき、アドバンテージには基づきません。ループは生成されたプロセス内で構築されるため、サブクラスはモジュールレベルで定義してください。クライアントは __init__ をオーバーライドするのではなく、ループのイベントループ上で実行される setup で作成してください。filter_prompt によって拒否されたプロンプトは、そのエポックではスキップされ、除外されたグループと同様にエポックの回数にカウントされます。あるエポックのプロンプトがすべて拒否された場合、ループは例外を送出します。

設計思想

このトレーナーは意図的に最小限に保たれており、汎用的なソリューションとして拡張されることを想定していません。サポートされていない機能が必要な場合は、リポジトリをクローンし、ご自身のニーズに合わせてトレーナーを直接調整することをお勧めします。新機能の追加は、コミュニティからの需要が顕著な場合のみ検討されます。

記録されたメトリクス

ロールアウトが勾配になるまで、いくつかの段階を通過します。プロンプトから最終的なバッチ構成までの各段階を、まず見ていきましょう。

Dataset row = PROMPT (message list + reward kwargs)
 └─ GROUP                  (1 prompt, `num_generations` rollouts, 1 advantage baseline)
     └─ ROLLOUT            (1 conversation, keyed by `rollout_id`)
         ├─ TURN           (1 vLLM /v1/completions call + tool messages fed back)
         │   └─ TurnRecord (prompt_ids, output_ids, output_log_probs)
         └─ reconcile      (a turn that doesn't extend the held tokens forks a new sequence)
             └─ SEQUENCE   (≥1 per rollout; new one per fork; dropped if no trained token)
                 └─ SAMPLE (Sequence + group advantage + reward + metrics)

════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════

                 └─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
                     └─ ROW            (Planner inserts it into one of `dp` prefix tries, attention-cost-balanced)
                         └─ MICRO-BATCH (`dp` rows, one per rank)
                             └─ PACKED ROW (Collator lays each trie out: unique tokens, depth as `position_ids`)
                                 └─ FORWARD (`compute_loss`, bs=1, padding stripped, FA3 per trie segment)
                     └─ OPTIMIZER STEP (from `grad_accum` micro-batches)

上から下へ読んでいくと:

• groupとは、1つのプロンプトをnum_generations回生成したものです。アドバンテージベースラインはグループ内で計算されるため、グループが採点の単位となります。
• rolloutとは1回の会話です。各ターンではメッセージリスト全体が再トークン化されるため、ターン間のドリフトは最後に調整する必要があります。
• reconciling は 1 つの rollout を複数の sequences に fork できるため、1 つの会話から複数の学習サンプルが生成されることがあります。
• サンプルとは、シーケンスとそのアドバンテージ、報酬、メトリクスからなるものです。これがプロセスの境界を越えて渡されます。
• 境界を越えると、trainer はサンプルを rows（DP ランクごとに 1 つ）に計画し、各行をプレフィックス トライに折りたたんで共有トークンを 1 回だけ転送し、grad_accum のマイクロバッチを 1 つのオプティマイザーステップに集約します。

そのため、メトリクスは、どのステージ（またはエンティティ）に関するものかによって分割されます:

トークン指標を明確にするために、いくつかの用語を定義しておきましょう。

• generated トークンは、モデルが生成したものです(completions/*)。
• forwarded トークンとは、forward パスが処理するすべてのトークンを指します。プロンプト、ツール結果、生成されたトークンすべてが含まれます。
• trainedトークンは、completion_mask == 1のトークンの部分集合であり、損失が計算される対象です。これは、生成されたトークンから、ハーネスのキャプチャによってマスクされたものを除いたものです。

バッチ番号の構成

rowとは、1つの DP rank が 1 つの micro-batch で forward する単位です。複数のサンプルを単一の prefix forest にパックするため、共有されるトークンは 1 回だけ forward されます。Tree packingを参照してください。プランナーはどのサンプルをどの row に配置するかを決定し（attention コストをバランスさせ、どの rank も遅延しないようにします）、データコラテーターがパックを実行します。

すべてのメトリクスにおいて、「step」は常にフルのオプティマイザーステップを指し、マイクロバッチを指すことはありません。gradient_accumulation_steps 個のマイクロバッチで 1 ステップを構成し、_per_step という名前のメトリクスはすべてオプティマイザーステップ単位であり、global_step、logging_steps などの Trainer の用語体系と一致しています。マイクロバッチ単位のメトリクスである場合はその旨が明記されています（batch/microbatches_per_step）、または行単位（サンプル単位）の量です（batch/row_*、batch/samples_per_row）。

したがって、1ステップには固定数のrow-slotsが含まれます:

row-slots per step = gradient_accumulation_steps x world_size

これにより、バッチメトリクスは互いに照合できる階層構造として構成されます。

sample                                     sample/forwarded_tokens_mean
  └─ packed into a ROW                     batch/samples_per_row, batch/row_tokens_mean
      └─ one row per DP rank               = one micro-batch
          └─ gradient_accumulation_steps micro-batches = one STEP
                                           batch/samples_per_step, batch/forwarded_tokens_per_step

したがって、batch/samples_per_step ≈ row-slots x batch/samples_per_row となり、トークンについても同様です。両辺が一致するのは、ステップ内のマイクロバッチ間のばらつきまでです。ステップごとの指標は合計値、行ごとの指標は平均値であるため、完全な一致ではなく、数パーセント未満の誤差が生じることが予想されます。

batch/row_fill_frac は、サンプルが長い場合に注目すべき指標です。10k トークンのサンプルでは 32k の予算へのタイルリングが非常に悪く（3 個は収まるが 4 個は絶対に収まらないため、パッカーは多くの場合 2 個しか詰められず、行の充填率は約 77% になります）、一方、1k トークンのサンプルではほぼ完璧にタイルリングできます。これはバグではなく量子化（切り捨て）によるもので、token_budget が調整レバーです。ただし、アテンションはシーケンスごとに O(L²) であるため、長いシーケンスで構成される行がより満杯であっても、メモリコストは線形に増加しません。

ツリーパッキング

行は連結ではなくプレフィックストライです。複数のサンプルで共有されるトークンは1回だけ転送され、アテンションは各サンプルにそのサンプル自身の履歴のみを正確に表示します。1つのプロンプトのロールアウトはすべてそれを繰り返し、マルチターンロールアウトの各ターンでは会話が再送信されるため、デコーダーの処理量はパッキング比（生トークン数 ÷ 転送トークン数）だけ減少します。これはレイアウトの変更のみであり、学習された各トークンは自身のターゲット、アドバンテージ、旧ログ確率を保持し、そのログ確率はサンプルを単独で転送した場合と一致します。

発生場所:

planner    TreeRow.add            the trie grows sample by sample; a sample is priced by its novel tokens
   │                              (TreeRow.fits), so `token_budget` bounds unique tokens, not raw ones
collator   TreeRow.pack           DFS layout: unique tokens, depth as position_ids, one loss term per
   │                              original trained token (token_index), and per segment its queries and
   │                              the K/V indices of its root-to-segment path, all built on CPU
attention  tree_attention         gather K/V along the paths, one FA3 varlen call, causal

1つのプロンプトの2回のロールアウトにおける動作:

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

2. Trie (one per row)   S0 [p1 p2] ─┬─ S1 [p3 a1 a2]          nodes are keyed on (token, next token),
                                   └─ S2 [p3 b1 b2]          so the fork happens one token early and
                                                              every node predicts exactly one token;
                                                              chains without a fork become segments

3. Packed row           idx           0  1 | 2  3  4 | 5  6  7
   (DFS order)          input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2  8 tokens: MLPs, norms and projections
                        position_ids  0  1 |  2  3  4 |  2  3  4  run once per unique token
                        segment      S0    | S1       | S2

4. Attention            seg   queries      K/V gathered            kv_index
   (one FA3 call)       S0    [p1 p2]      [p1 p2]                 0 1
                        S1    [p3 a1 a2]   [p1 p2 | p3 a1 a2]      0 1 2 3 4
                        S2    [p3 b1 b2]   [p1 p2 | p3 b1 b2]      0 1 5 6 7

                        FA3 aligns the causal mask bottom-right      K:  p1 p2 p3 a1 a2
                        when queries are fewer than keys, so a       Q: p3   ■  ■  ■  ·  ·
                        segment's queries see their ancestors and       a1   ■  ■  ■  ■  ·
                        their own causal past, and nothing else.        a2   ■  ■  ■  ■  ■

5. Loss                 p2 (idx 1) predicts p3 for both rollouts; token_index points every trained
                        token of every rollout at the position that predicts it

いくつかの帰結:

• 共通の接頭辞は共有される: プロンプトのロールアウト、およびプロンプト間で共通のシステムプロンプトやツールスキーマです。プランナーは、サンプルを、そのプロンプトが既に存在するgroup_idを持つ行に送信します。その行が満杯の場合、ランクがまだ空いている行があるか、最も負荷の高い行の負荷が増えない場合は、サンプルは別の行に送られます。これによりマイクロバッチの時間が決まります。それ以外の場合は、マイクロバッチがクローズされます。
• 共有されないものはプレーンなパッキングです。各サンプルは、パスが自身である1つのセグメントとなり、通常のpaddingなしFA3 varlenパッキングになります。
• K/Vのみが複製される: 共有プレフィックスは各降下セグメントごとに1回だけ集められ、これはアンパックされた学習が保持する量とほぼ同じであり、GQAでは小さくなります。
• Gated DeltaNetハイブリッドがサポートされています（Qwen3.5、Qwen3.6、Qwen3-Next など）：その畳み込みは各トークン自身の先行トークンを参照し、チャンク化されたデルタルールは各セグメントを親の最終状態から開始します（trl/experimental/async_grpo/tree_gated_delta_rule.py）。これには、これらのレイヤーがツリーパッキングがパッチを当てるモジュールレベルの関数を呼び出すtransformers>=5.15.0が必要です。他の非アテンションレイヤーを含むモデルは、初期化時に拒否されます。

購入できるもの: 共有なしの場合、通常のpaddingなしパッキングとほぼ同じ速度で動作し、速度向上はパッキング比に概ね比例して増加します(Qwen3-0.6B/1.7B、H100では、比3.4で約2.8〜3倍)。比は共有プレフィックス×行ごとのサンプル数に等しいため、batch/samples_per_rowが主要な指標となります。1に近い場合は何も共有できず、調整レバーはtoken_budgetです。

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

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

ロールアウトキュー

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

最後の2つのメトリクス（perf/rollout_wait_sとrollout/backpressure_s）は鏡像の関係にあり、同時に大きくなることはありません。これらをキューサイズと併せて読むことで、ボトルネックがどちら側にあるかを知ることができます。

• キューがほぼ空で、perf/rollout_wait_sが高い場合 → 生成がボトルネックです。トレーナーが飢えている状態です。rollout/generated_tok_s、rollout/concurrency、rollout/score_queue_sizeを確認してください。
• キューがほぼ満杯で、rollout/backpressure_sが高い場合 → trainer-boundです。生成がスロットリングされ、その出力がキュー内で滞留しているため、sample/staleness_meanの上昇に注意してください。
• どちらもほぼゼロ → バランスがとれている！

補完

completionとは、vLLMが1つのプロンプトに対して生成したもので、ロールアウトのすべてのターンにわたって集計されます。

ロールアウト

rolloutとは、1回の完全な会話です。プロンプトが完了するまで生成されたもので、そこに至るまでに発生したすべてのツールとの往復を含みます。num_generations個のrolloutは同じプロンプトを共有し、1つのグループを形成します。

すべてのロールアウトが同じ報酬を受け取ったグループ（またはスコアリング可能なロールアウトが2つ未満のグループ）は、キューに追加されるのではなく破棄されます。デフォルトのアドバンテージでは、このグループはすべての位置でアドバンテージがゼロになるため、フォワードとバックワードのコストが発生しても何も更新されないからです。バッチ自体には影響がなく、保持されたグループから引き続きsamples_per_stepを埋めるため、多くのグループが破棄される場合は、1ステップあたりの生成時間が長くなります。破棄されたグループもエポックのカウントには含まれ、エポックはプロンプトを1回通すこととして維持されます。

ツール

モデルがツールを実行した場合にのみ記録されます。tools/<name>/* はツール名ごとに繰り返されますが、これは rewards/<func>/* が報酬関数ごとに繰り返されるのと同じです。なぜなら、1つのツールの失敗は、すべてのツールの平均値では見えないからです。組み込みのツールループと OpenEnv ハーネスのトレーナー（HarnessAsyncGRPOTrainer、ハーネスでの学習を参照）は同じ名前を記録するため、1つのダッシュボードで両方を確認できます。path 列は、どのプロセスが各メトリクスを生成しているかを示します。

環境

environment_factory を使用した場合のみ記録されます。両方の呼び出しはワーカーのツールスレッドプールで実行されるため、遅い環境は自身のロールアウトのみを遅延させ、進行中の他のロールアウトには影響しません。

キューから到着するサンプル

各サンプルは1つのRolloutSampleです。グループ内のすべての生成が完了してスコアリングされた時点で、_score_group内のワーカーによって組み立てられる、調整済みのシーケンスとグループのアドバンテージ、報酬、およびサンプルごとのメトリクスです。ワーカーはこれらをrollout_bufferにプッシュします。以下はすべて、学習用にそれらをプルするトレーナー側で測定されます。

報酬とオフポリシー性

バッチ

1つのマイクロバッチはworld_size行です（パッキングにより1つのシーケンスにフラット化されることをお忘れなく）。そのため、DPランクごとに1つずつ割り当てられ、ランクiは行iをフォワードします。これらのgradient_accumulation_steps回分が1回のオプティマイザーステップを構成します。したがって、1ステップでは合計でgradient_accumulation_steps × world_size行をカバーします。以下のすべての_per_stepメトリックは、ステップ全体およびすべてのランクにわたる合計値です。batch/row_*のメトリックは、行にわたる平均値です。

パフォーマンス

スループットは、トレーナーが1秒間に処理するトークン数を測定します。モデルFLOPs利用率（MFU）は、モデルのフォワードパスとバックワードパスに使用される、トレーニングデバイスの理論的な計算能力の割合を推定します。この推定に使用される能力は、ハードウェアとトレーニングの精度によって異なります。

スループットとMFUは、2つの時間基準で報告されます:

• _fwd_bwd は、フォワードパスとバックワードパス中のパフォーマンスを測定します。
• _wall_clock は、オプティマイザーの更新、重みの同期、ロールアウトを待機している時間を含まれた、オプティマイザーステップ全体でのパフォーマンスを測定します。

この差により、計算性能と待機および調整のコストを区別できます。両方のMFU指標はトレーニングデバイスのみを記述しており、外部のロールアウトサーバーや教師サーバーの計算やハードウェア容量は含まれません。Wall-clock MFUは、これらのサービス自体の利用率ではなく、トレーナーがそれらのサービスを待機している時間を反映しています。

MFUは、選択した精度におけるローカルトレーニングデバイスのピーク計算能力が既知の場合にのみ報告されます。それ以外の場合は、MFUは省略されますが、トレーニングは継続され、スループットおよびタイミングのメトリクスは引き続き利用可能です。

AsyncGRPOConfig

AsyncGRPOTrainer

>>> from trl.experimental.async_grpo 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()

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

AsyncRolloutLoop

ロールアウト

TurnRecord

RolloutGroup