🧩高度な強化学習ドキュメント

Unsloth を GRPO と併用する際の高度なドキュメント設定。

バッチ処理、生成、学習パラメータに関する Unsloth を使った GRPO の詳細ガイド:

学習パラメータ

• beta (float, デフォルト 0.0): KL 係数。

  • 0.0 ⇒ 参照モデルは読み込まれません（メモリ使用量が少なく、より高速）。

  • 高いほど beta 方策が参照方策により近い状態に保たれるよう制約します。

• num_iterations (int, デフォルト 1): バッチごとの PPO エポック数（アルゴリズム中の μ）。 各勾配蓄積ステップ内でデータを再利用します。例: 2 = 蓄積ステップごとに 2 回の順伝播。

• epsilon (float, デフォルト 0.2): トークンレベルの log-prob 比率に対するクリップ値（通常の比率範囲 ≈ [-1.2, 1.2]、デフォルト ε の場合）。

• delta (float, オプション): を有効にします 上側の クリップ境界を 両側 GRPO に対して設定した場合。 Noneの場合、標準の GRPO クリッピングが使用されます。推奨値は > 1 + ε （有効時、INTELLECT-2 レポートによる）。

• epsilon_high (float, オプション): 上限側の epsilon。未設定なら epsilon がデフォルトになります。DAPO では 0.28.

• importance_sampling_level （“token” | “sequence”、デフォルト "token"）:

  • "token": トークンごとの生の比率（トークンごとに 1 つの重み）。

  • "sequence": トークンごとの比率を平均して 1 つのシーケンスレベルの比率にします。 GSPO では、シーケンスレベルのサンプリングの方が、シーケンスレベル報酬に対してより安定した学習になることが多いと示されています。

• reward_weights (list[float], オプション): 報酬ごとに 1 つの重み。 None場合、すべての重み = 1.0。

• scale_rewards (str|bool, デフォルト "group"):

  • True または "group"の場合: 各グループ内の標準偏差でスケールします （グループ内分散が 1）。

  • "batch"の場合: バッチ全体での標準偏差 （PPO-Lite に準拠）。

  • False または "none": スケーリングなし。Dr. GRPO では、標準偏差によるスケーリングに起因する難易度バイアスを避けるため、スケーリングしないことを推奨しています。

• loss_type (str, デフォルト "dapo"):

  • "grpo": シーケンス長で正規化します（長さバイアスあり。推奨されません）。

  • "dr_grpo": で正規化します グローバル定数 （Dr. GRPO で導入；長さバイアスを除去）。定数 ≈ max_completion_length.

  • "dapo" （デフォルト）: で正規化します グローバルに蓄積されたバッチ内のアクティブトークン （DAPO で導入；長さバイアスを除去）。

  • "bnpo": で正規化します ローカルバッチ内のアクティブトークン のみ（結果はローカルバッチサイズによって変わる場合があります。 per_device_train_batch_size == 1).

• mask_truncated_completions (bool, デフォルト False): これを True有効にすると、切り詰められた completion は loss から除外されます（安定性のため DAPO 推奨）。 注: このフラグには KL に関する問題があるため、無効化することを推奨します。

  # mask_truncated_completions が有効なら、completion_mask 内の切り詰められた completion を 0 にする
  if self.mask_truncated_completions:
      truncated_completions = ~is_eos.any(dim=1)
      completion_mask = completion_mask * (~truncated_completions).unsqueeze(1).int()

  これにより、 completion_mask の全エントリが、completion が多数切り詰められた場合に 0 になる可能性があります。 n_mask_per_reward = 0 となり、KL が NaN になる原因になります。 参照:

• vllm_importance_sampling_correction (bool, デフォルト True): 適用します 切り詰め重要度サンプリング (TIS) を、生成（例: vLLM / fast_inference）と学習バックエンドが異なる場合のオフポリシー効果を補正するために使用します。 Unsloth では、これは vLLM/fast_inference を使用している場合は自動的に True に設定されます 。それ以外の場合は False.

• vllm_importance_sampling_cap (float, デフォルト 2.0): TIS の切り詰めパラメータ C 。安定性を向上させるため、importance sampling 比率の上限を設定します。

• dtype float16 または bfloat16 を選ぶ場合は、以下を参照してください RL における FP16 と BF16

未対応モデルでの RL:

vLLM でサポートされていないモデルでも、Unsloth で RL を実行できます。例えば Qwen3.5。単に以下を設定してください fast_inference=False を、モデル読み込み時に指定します。

from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Qwen3.5-4B",
    fast_inference=False,
)

生成パラメータ

• temperature (float, デフォルト 1.0): サンプリングの温度。温度が高いほど、生成結果はよりランダムになります。学習に役立つ多様な生成を得るために、比較的高い (1.0) 温度を使用してください。

• top_p (float, オプション、デフォルト 1.0): 考慮する上位トークンの累積確率を制御する float です。値は (0, 1] の範囲でなければなりません。すべてのトークンを考慮するには 1.0 に設定します。

• top_k (int, オプション): top-k フィルタリングで保持する、最も確率の高い語彙トークンの数。None の場合、top-k フィルタリングは無効になり、すべてのトークンが考慮されます。

• min_p (float, オプション): 最小トークン確率で、最も可能性の高いトークンの確率によりスケールされます。0.0 から 1.0 の値である必要があります。典型的な値は 0.01〜0.2 の範囲です。

• repetition_penalty (float, オプション、デフォルト 1.0): プロンプトやこれまでに生成されたテキストに現れたかどうかに基づいて、新しいトークンにペナルティを与える float です。1.0 より大きい値は新しいトークンの使用を促し、1.0 未満の値はトークンの繰り返しを促します。

• steps_per_generation: (int, オプション): 生成あたりのステップ数。None の場合、デフォルトは gradient_accumulation_stepsになります。 generation_batch_size.

このパラメータをいじるのは少し分かりにくいので、編集することを推奨します per_device_train_batch_size と、バッチサイズ用の勾配蓄積を。

バッチ & スループット パラメータ

バッチを制御するパラメータ

• train_batch_size: サンプル数 プロセスごとの 1 ステップあたり。 この整数が より小さい num_generations場合、デフォルトで num_generations.

• steps_per_generation: の数 マイクロバッチ が 1 回の生成の loss 計算に寄与します（順伝播のみ）。 新しいデータバッチは steps_per_generation ステップごとに生成されます。逆伝播のタイミングは gradient_accumulation_steps.

• num_processes: 分散学習プロセス数（例: GPU / ワーカー）。

• gradient_accumulation_steps （別名 gradient_accumulation）: 蓄積するマイクロバッチ数 の前に 逆伝播とオプティマイザ更新を適用します。

• 有効バッチサイズ:

  effective_batch_size = steps_per_generation * num_processes * train_batch_size

  更新前に勾配へ寄与する総サンプル数（全プロセス・全ステップにわたる）。

• 1 生成あたりのオプティマイザステップ数:

  optimizer_steps_per_generation = steps_per_generation / gradient_accumulation_steps

  例: 4 / 2 = 2.

• num_generations: 生成される回数 プロンプトごとに （適用は 後で 計算する effective_batch_size）。 生成サイクル内の 一意のプロンプト の数は次の通りです:

  unique_prompts = effective_batch_size / num_generations

  GRPO が機能するには 2 より大きい必要があります 。

GRPO バッチ例

以下の表は、バッチがステップをどのように流れ、いつオプティマイザ更新が発生し、新しいバッチが生成されるかを示しています。

例 1

num_gpus = 1
per_device_train_batch_size = 3
gradient_accumulation_steps = 2
steps_per_generation = 4

effective_batch_size = 4 * 3 * 1 = 12
num_generations = 3

生成サイクル A

ステップ	バッチ	備考
0	[0,0,0]
1	[1,1,1]	→ オプティマイザ更新（accum = 2 に到達）
2	[2,2,2]
3	[3,3,3]	オプティマイザ更新

生成サイクル B

ステップ	バッチ	備考
0	[4,4,4]
1	[5,5,5]	→ オプティマイザ更新（accum = 2 に到達）
2	[6,6,6]
3	[7,7,7]	オプティマイザ更新

例 2

num_gpus = 1
per_device_train_batch_size = 3
steps_per_generation = gradient_accumulation_steps = 4

effective_batch_size = 4 * 3 * 1 = 12
num_generations = 3

生成サイクル A

ステップ	バッチ	備考
0	[0,0,0]
1	[1,1,1]
2	[2,2,2]
3	[3,3,3]	オプティマイザ更新（accum = 4 に到達）

生成サイクル B

ステップ	バッチ	備考
0	[4,4,4]
1	[5,5,5]
2	[6,6,6]
3	[7,7,7]	オプティマイザ更新（accum = 4 に到達）

例 3

num_gpus = 1
per_device_train_batch_size = 3
steps_per_generation = gradient_accumulation_steps = 4

effective_batch_size = 4 * 3 * 1 = 12
num_generations = 4
unique_prompts = effective_batch_size / num_generations = 3

生成サイクル A

ステップ	バッチ	備考
0	[0,0,0]
1	[0,1,1]
2	[1,1,3]
3	[3,3,3]	オプティマイザ更新（accum = 4 に到達）

生成サイクル B

ステップ	バッチ	備考
0	[4,4,4]
1	[4,5,5]
2	[5,5,6]
3	[6,6,6]	オプティマイザ更新（accum = 4 に到達）

例 4

num_gpus = 1
per_device_train_batch_size = 6
steps_per_generation = gradient_accumulation_steps = 2

effective_batch_size = 2 * 6 * 1 = 12
num_generations = 3
unique_prompts = 4

生成サイクル A

ステップ	バッチ	備考
0	[0,0,0, 1,1,1]
1	[2,2,2, 3,3,3]	オプティマイザ更新（accum = 2 に到達）

生成サイクル B

ステップ	バッチ	備考
0	[4,4,4, 5,5,5]
1	[6,6,6, 7,7,7]	オプティマイザ更新（accum = 2 に到達）

クイック数式リファレンス

effective_batch_size = steps_per_generation * num_processes * train_batch_size
optimizer_steps_per_generation = steps_per_generation / gradient_accumulation_steps
unique_prompts = effective_batch_size / num_generations   # 2 より大きくなければならない