🧩Documentation avancée sur l’apprentissage par renforcement

Paramètres de documentation avancés lors de l’utilisation d’Unsloth avec GRPO.

Guides détaillés sur la façon de faire du GRPO avec Unsloth pour le lotissement, la génération et les paramètres d'entraînement :

Paramètres d'entraînement

• beta (float, par défaut 0.0): Coefficient KL.

  • 0.0 ⇒ aucun modèle de référence chargé (moins de mémoire, plus rapide).

  • Plus élevé beta contraint la politique à rester plus proche de la politique de référence.

• num_iterations (int, par défaut 1): Époques PPO par lot (μ dans l'algorithme). Relance les données à l'intérieur de chaque étape d'accumulation de gradients ; par ex., 2 = deux passes avant par étape d'accumulation.

• epsilon (float, par défaut 0.2): Valeur de clipping pour les rapports de log-probabilité au niveau des jetons (plage typique du rapport ≈ [-1.2, 1.2] avec ε par défaut).

• delta (float, facultatif): Active borne supérieure de clipping pour GRPO bilatéral lorsqu'il est défini. Si None, le clipping GRPO standard est utilisé. Recommandé > 1 + ε lorsqu'il est activé (selon le rapport INTELLECT-2).

• epsilon_high (float, facultatif): Epsilon de borne supérieure ; vaut par défaut epsilon s'il n'est pas défini. DAPO recommande 0.28.

• importance_sampling_level ("token" | "sequence", par défaut "token"):

  • "token": rapports bruts par jeton (un poids par jeton).

  • "sequence": moyenne des rapports par jeton en un seul rapport au niveau de la séquence. GSPO montre que l'échantillonnage au niveau de la séquence donne souvent un entraînement plus stable pour les récompenses au niveau de la séquence.

• reward_weights (list[float], facultatif): Un poids par récompense. Si None, tous les poids = 1.0.

• scale_rewards (str|bool, par défaut "group"):

  • True ou "group": mise à l'échelle par l'écart-type au sein de chaque groupe (variance unitaire dans le groupe).

  • "batch": mise à l'échelle par écart-type sur l'ensemble du lot (selon PPO-Lite).

  • False ou "none": aucune mise à l'échelle. Dr. GRPO recommande de ne pas mettre à l'échelle afin d'éviter un biais de difficulté dû à la mise à l'échelle par l'écart-type.

• loss_type (str, par défaut "dapo"):

  • "grpo": normalise sur la longueur de la séquence (biais de longueur ; non recommandé).

  • "dr_grpo": normalise par une constante globale (introduite dans Dr. GRPO ; supprime le biais de longueur). Constante ≈ max_completion_length.

  • "dapo" (par défaut): normalise par les jetons actifs dans le lot accumulé global (introduit dans DAPO ; supprime le biais de longueur).

  • "bnpo": normalise par les jetons actifs dans le lot local uniquement (les résultats peuvent varier selon la taille du lot local ; équivaut à GRPO lorsque per_device_train_batch_size == 1).

• mask_truncated_completions (bool, par défaut False): Lorsque True, les complétions tronquées sont exclues de la perte (recommandé par DAPO pour la stabilité). Remarque: ce drapeau pose quelques problèmes de KL, nous recommandons donc de le désactiver.

  # Si mask_truncated_completions est activé, met à zéro les complétions tronquées dans completion_mask
  if self.mask_truncated_completions:
      truncated_completions = ~is_eos.any(dim=1)
      completion_mask = completion_mask * (~truncated_completions).unsqueeze(1).int()

  Cela peut mettre à zéro toutes les completion_mask entrées lorsque de nombreuses complétions sont tronquées, ce qui fait que n_mask_per_reward = 0 et provoque un KL égal à NaN. Voir

• vllm_importance_sampling_correction (bool, par défaut True): Applique l'échantillonnage d'importance tronqué (TIS) pour corriger les effets hors politique lorsque la génération (par ex. vLLM / fast_inference) diffère du backend d'entraînement. Dans Unsloth, ceci est défini automatiquement sur True si vous utilisez vLLM/fast_inference ; sinon False.

• vllm_importance_sampling_cap (float, par défaut 2.0): Paramètre de troncature C pour TIS ; fixe une borne supérieure au rapport d'échantillonnage d'importance afin d'améliorer la stabilité.

• dtype lors du choix de float16 ou bfloat16, voir FP16 vs BF16 pour le RL

RL sur des modèles non pris en charge :

Vous pouvez également exécuter RL avec Unsloth sur des modèles non pris en charge par vLLM, comme Qwen3.5. Il suffit de définir fast_inference=False lors du chargement du modèle.

from unsloth import FastLanguageModel

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

Paramètres de génération

• temperature (float, par défaut 1.0) : Température d'échantillonnage. Plus la température est élevée, plus les complétions sont aléatoires. Assurez-vous d'utiliser une température relativement élevée (1.0) pour avoir de la diversité dans les générations, ce qui aide l'apprentissage.

• top_p (float, facultatif, par défaut 1.0) : Float qui contrôle la probabilité cumulée des meilleurs jetons à prendre en compte. Doit être dans (0, 1]. Définissez-le à 1.0 pour prendre en compte tous les jetons.

• top_k (int, facultatif) : Nombre des jetons du vocabulaire ayant la plus forte probabilité à conserver pour le filtrage top-k. Si None, le filtrage top-k est désactivé et tous les jetons sont pris en compte.

• min_p (float, facultatif) : Probabilité minimale d'un jeton, qui sera mise à l'échelle par la probabilité du jeton le plus probable. Elle doit être une valeur comprise entre 0.0 et 1.0. Les valeurs typiques se situent dans la plage 0.01-0.2.

• repetition_penalty (float, facultatif, par défaut 1.0) : Float qui pénalise les nouveaux jetons selon qu'ils apparaissent dans l'invite et dans le texte généré jusqu'à présent. Les valeurs > 1.0 encouragent le modèle à utiliser de nouveaux jetons, tandis que les valeurs < 1.0 encouragent le modèle à répéter des jetons.

• steps_per_generation : (int, facultatif) : Nombre d'étapes par génération. Si None, la valeur par défaut est gradient_accumulation_steps. Mutuellement exclusif avec generation_batch_size.

Il est un peu déroutant de modifier ce paramètre, il est recommandé de modifier per_device_train_batch_size et l'accumulation de gradients pour les tailles de lot

Paramètres de lot et de débit

Paramètres qui contrôlent les lots

• train_batch_size: Nombre d'échantillons par processus par étape. Si cet entier est inférieur à num_generations, il prendra par défaut num_generations.

• steps_per_generation: Nombre de micro-lots qui contribuent au calcul de la perte d'une génération (passes avant uniquement). Un nouveau lot de données est généré toutes les steps_per_generation étapes ; le moment de la rétropropagation dépend de gradient_accumulation_steps.

• num_processes: Nombre de processus d'entraînement distribués (par ex., GPU / travailleurs).

• gradient_accumulation_steps (alias gradient_accumulation): Nombre de micro-lots à accumuler avant d'appliquer la rétropropagation et la mise à jour de l'optimiseur.

• Taille effective du lot:

  effective_batch_size = steps_per_generation * num_processes * train_batch_size

  Nombre total d'échantillons contribuant aux gradients avant une mise à jour (sur tous les processus et toutes les étapes).

• Étapes de l'optimiseur par génération:

  optimizer_steps_per_generation = steps_per_generation / gradient_accumulation_steps

  Exemple : 4 / 2 = 2.

• num_generations: Nombre de générations produites par invite (appliqué après le calcul de effective_batch_size). Le nombre de invites uniques dans un cycle de génération est :

  unique_prompts = effective_batch_size / num_generations

  Doit être > 2 pour que GRPO fonctionne.

Exemples de lots GRPO

Les tableaux ci-dessous illustrent comment les lots circulent à travers les étapes, quand les mises à jour de l'optimiseur se produisent et comment de nouveaux lots sont générés.

Exemple 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

Cycle de génération A

Étape	Lot	Notes
0	[0,0,0]
1	[1,1,1]	→ mise à jour de l'optimiseur (accum = 2 atteint)
2	[2,2,2]
3	[3,3,3]	mise à jour de l'optimiseur

Cycle de génération B

Étape	Lot	Notes
0	[4,4,4]
1	[5,5,5]	→ mise à jour de l'optimiseur (accum = 2 atteint)
2	[6,6,6]
3	[7,7,7]	mise à jour de l'optimiseur

Exemple 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

Cycle de génération A

Étape	Lot	Notes
0	[0,0,0]
1	[1,1,1]
2	[2,2,2]
3	[3,3,3]	mise à jour de l'optimiseur (accum = 4 atteint)

Cycle de génération B

Étape	Lot	Notes
0	[4,4,4]
1	[5,5,5]
2	[6,6,6]
3	[7,7,7]	mise à jour de l'optimiseur (accum = 4 atteint)

Exemple 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

Cycle de génération A

Étape	Lot	Notes
0	[0,0,0]
1	[0,1,1]
2	[1,1,3]
3	[3,3,3]	mise à jour de l'optimiseur (accum = 4 atteint)

Cycle de génération B

Étape	Lot	Notes
0	[4,4,4]
1	[4,5,5]
2	[5,5,6]
3	[6,6,6]	mise à jour de l'optimiseur (accum = 4 atteint)

Exemple 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

Cycle de génération A

Étape	Lot	Notes
0	[0,0,0, 1,1,1]
1	[2,2,2, 3,3,3]	mise à jour de l'optimiseur (accum = 2 atteint)

Cycle de génération B

Étape	Lot	Notes
0	[4,4,4, 5,5,5]
1	[6,6,6, 7,7,7]	mise à jour de l'optimiseur (accum = 2 atteint)

Référence rapide des formules

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   # doit être > 2