TRL documentation

Entraîneur GRPO asynchrone

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Entraîneur GRPO asynchrone

model badge

Aperçu

AsyncGRPOTrainer implémente le même algorithme GRPO mais découple la génération des rollouts de l’entraînement. Un travailleur en arrière-plan transmet en continu des complétions depuis un serveur vLLM pendant que la boucle d’entraînement les consomme, de sorte que la génération et les mises à jour des gradients se chevauchent au lieu de s’alterner.

Ce formateur a été contribué par Amine Dirhoussi et Quentin Gallouédec.

Démarrage rapide

Cet exemple montre comment entraîner un modèle à l'aide de la méthode GRPO asynchrone. Nous entraînons un modèle Qwen3.5 2B avec les prompts du jeu de données DeepMath-103K. Vous pouvez consulter les données du jeu de données ici :

Voici le script pour entraîner le modèle. Le trainer nécessite vLLM et kernels, et accuracy_reward nécessite math-verify, que vous pouvez installer avec 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()

La génération s'exécute sur un serveur vLLM, sur des GPU différents de ceux de l'entraîneur. Lancez-le sur le 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

Puis exécutez le script sur le GPU 1 à l'aide de la commande suivante :

CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py

Compatibilité et contraintes

Certaines combinaisons d'arguments sont volontairement restreintes dans l'implémentation actuelle de AsyncGRPOTrainer :

  • La génération s'exécute toujours sur un serveur vLLM distinct, démarré avec vllm serve. Il n'existe pas de mode de colocalisation.
  • Prompts from the dataset must be in conversational format. With an environment_factory, the dataset may have no prompt column, and reset() provides it.
  • Les fonctions de récompense doivent être des objets Python appelables. Les modèles de récompense fournis sous forme d’identifiant de modèle ou de PreTrainedModel ne sont pas pris en charge, voir Utiliser une fonction de récompense personnalisée.
  • Le formateur nécessite transformers>=5.2.0.
  • L’entraînement sharded utilise FSDP2. DeepSpeed n’est pas pris en charge, et ni le parallélisme de contexte ni le parallélisme de séquence ne le sont non plus (cp_size > 1 ou sp_size > 1 dans parallelism_config).
  • use_liger_kernel=True n'est pas pris en charge.
  • Les adaptateurs PEFT ciblant lm_head ne sont pas pris en charge.
  • Les modèles avec des puits d'attention ne sont pas pris en charge. Les seules couches non attentionnelles prises en charge sont les couches DeltaNet à porte des modèles hybrides (Qwen3.5, Qwen3.6, Qwen3-Next, …), qui nécessitent transformers>=5.15.0.
  • Les images ne sont pas prises en charge, voir Entraînement des modèles de langage visuels.

L’entraînement charge son noyau d’attention depuis le Hub via la bibliothèque kernels : kernels-community/aiter-flash-attn sur les GPU AMD (ROCm), kernels-community/flash-attn4 sur les GPU NVIDIA Blackwell et kernels-community/flash-attn3 sur les autres GPU NVIDIA. Les modèles qui plafonnent leurs logits d’attention (attn_logit_softcapping), tels que Gemma 2, ne sont pas pris en charge sur les GPU AMD ni sur les GPU NVIDIA Blackwell.

Explorer plus en profondeur la méthode GRPO asynchrone

Dans GRPOTrainer, la génération et l’entraînement sont séquentiels : générer un lot, calculer la perte, mettre à jour les poids, répéter. Même en mode colocate, une phase doit se terminer avant que l’autre ne commence. Dans AsyncGRPOTrainer, un travailleur de déroulement génère et évalue les complétions dans un processus en arrière-plan pendant que la boucle d’entraînement calcule la perte et met à jour le modèle. Pour comprendre son fonctionnement, il peut être décomposé en trois étapes principales : la génération des complétions, le calcul de l’avantage et le calcul de la perte. Il n’y a pas de modèle de référence, donc pas de terme de divergence KL (la valeur par défaut de GRPO, beta=0.0).

Générer des complétions

Le worker de rollout maintient jusqu'à max_concurrent_rollouts requêtes en cours vers le serveur vLLM. Pour chaque invite, il génère un groupe de G G complétions (num_generations) et, une fois le groupe entier terminé, il le note et calcule ses avantages. Les échantillons d'entraînement résultants sont placés dans une file d'attente, dont la boucle d'entraînement puise. La génération n'attend que lorsqu'elle est en avance de max_staleness étapes sur l'entraînement (voir Concurrence), et une étape d'entraînement n'attend que lorsque la file d'attente est vide.

Toutes les weight_sync_steps étapes d’entraînement, le formateur envoie ses poids mis à jour au serveur vLLM via NCCL, afin que les complétions suivantes proviennent de la politique la plus récente. Une complétion peut donc provenir d’une politique quelques étapes plus ancienne que celle en cours d’entraînement : un échantillon qui est en retard de plus de max_staleness mises à jour de poids au moment où le formateur le récupère est écarté.

Les métriques et le reste de cette page utilisent les termes suivants pour les étapes par lesquelles passe une complétion :

  • a groupe est un prompt et ses G G roulages. L'avantage est calculé à l'intérieur de celui-ci.
  • Un rollout est une conversation complète générée pour un prompt, incluant tous les appels d’outils. Il est composé d’un ou plusieurs turns, chacun correspondant à une requête vLLM.
  • Un sample est l'unité sur laquelle la perte est calculée : les tokens d'un rollout, avec son avantage. Un rollout multi-tours peut produire plus d'un sample (voir Multi-turn rollouts).
  • une ligne est ce qu'un processus transmet dans un micro-lot : plusieurs échantillons regroupés ensemble (voir Arborescence de regroupement). Un micro-lot contient une ligne par processus, et gradient_accumulation_steps micro-lots constituent une étape, l'étape de l'optimiseur.

Les compteurs de jetons se déclinent en trois types : les jetons générés sont ceux produits par le modèle, les jetons transmis correspondent à l’ensemble des jetons d’un échantillon (y compris le prompt et les résultats d’outils), et les jetons entraînés sont ceux sur lesquels la perte est calculée.

Calcul de l'avantage

Pour chacune des G G complétions d'un groupe, la récompense est la somme des récompenses de chaque fonction de récompense. L'avantage est normalisé au sein du groupe, comme dans GRPO : A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

Il n’existe pas d’option scale_rewards : l’avantage est toujours mis à l’échelle par l’écart-type du groupe. Une complétion pour laquelle toutes les fonctions de récompense ont retourné None est exclue de la moyenne et de l’écart-type du groupe et reçoit un avantage nul.

Un groupe dont les récompenses sont toutes égales est écarté : avec l’avantage par défaut, celui-ci est nul partout, si bien que l’entraînement sur ce groupe coûterait un passage avant et un passage arrière sans rien modifier. La proportion de tels groupes est journalisée sous la forme frac_zero_std_groups. L’étape est constituée à partir des groupes conservés, de sorte que de nombreux groupes écartés impliquent plus de génération par étape. Un groupe écarté compte toujours pour l’époque, qui reste un seul passage sur les prompts.

Calcul de la perte

Les log-probabilités du serveur vLLM ne correspondent jamais exactement à celles de l'entraîneur : noyaux différents, précision différente et politique en retard de quelques étapes (voir Gérer le décalage entre l'entraînement et l'inférence). L'entraîneur utilise les log-probabilités de l'échantillonneur comme politique précédente, de sorte qu'un seul ratio d'importance couvre à la fois le décalage et l'obsolescence : 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})}.

Les jetons dont le ratio se situe en dehors de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] sont exclus de la perte. Pour plus d’informations, voir Masked Importance Sampling.

Par défaut (score_centering=True), le formateur utilise Score Centering. Les poids d'importance seuls ne suppriment pas le décalage : le score ∇θlog⁡πθ \nabla_\theta \log \pi_\theta d'un jeton échantillonné ne s'annule pas en moyenne sous l'échantillonneur μ \mu , ainsi chaque mise à jour tire également la politique vers l'échantillonneur. Le Score Centering soustrait cette espérance à chaque position : ∇θ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)},

où f(r)=r f(r) = r à l'intérieur de [Cmin⁡,Cmax⁡] [C_{\min}, C_{\max}] et 0 0 à l'extérieur. L'espérance interne est prise sur les num_sampler_logprobs jetons les plus probables à chaque position, que le travailleur de rollout demande au serveur.

Avec score_centering=False, l'entraîneur utilise à la place l'objectif substitut tronqué de GRPO, avec le même ratio masqué : 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),

où ϵlow \epsilon_{\text{low}} est epsilon et ϵhigh \epsilon_{\text{high}} est epsilon_high.

Dans les deux cas, la perte est normalisée par le nombre de jetons entraînés dans le micro-lot, compté sur l’ensemble des processus, et moyennée sur les gradient_accumulation_steps micro-lots d’une étape.

Métriques journalisées

Pendant l'entraînement, nous enregistrons les métriques suivantes :

  • num_tokens : le nombre total de jetons transmis jusqu'à présent, prompts et complétions. Avec l'empilement arborescent, un préfixe partagé par plusieurs échantillons est compté une seule fois.
  • completions/mean_length : La longueur moyenne des complétions générées. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/min_length : La longueur minimale des complétions générées. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/max_length : La longueur maximale des complétions générées. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/mean_terminated_length : La longueur moyenne des complétions générées qui se terminent par EOS. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/min_terminated_length : La longueur minimale des complétions générées qui se terminent par EOS. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/max_terminated_length : La longueur maximale des complétions générées qui se terminent par EOS. Lors de l'utilisation d'outils, seuls les jetons non-outils sont comptés.
  • completions/clipped_ratio : Le ratio des complétions tronquées (clippées), dont le dernier tour ne se termine pas par un jeton EOS.
  • completions/duplicate_frac : La proportion de rollouts qui répètent un rollout antérieur de leur groupe, jeton par jeton. Voir Saturation et doublons.
  • tools/call_frequency : nombre moyen d'appels d'outils par complétion, sur l'ensemble des déroulements, y compris les groupes qui sont ensuite écartés. Journalisé uniquement lorsque l'entraîneur dispose d'outils.
  • tools/failure_frequency : La proportion d’appels d’outils qui ont échoué (l’outil n’a pas été trouvé ou a levé une exception), par rapport à l’ensemble des appels d’outils, y compris les groupes qui sont ensuite écartés. Elle est NaN dans une fenêtre de journalisation sans appel d’outil, où GRPO journalise 0.0. Journalisé uniquement lorsque l’entraîneur dispose d’outils.
  • rewards/{reward_func_name}/mean : la récompense moyenne issue d’une fonction de récompense spécifique, sur l’ensemble des complétions qu’elle a évaluées, y compris les groupes qui sont ensuite écartés. Lorsqu’un environnement possède la récompense via get_reward, {reward_func_name} est le nom de la classe de l’environnement.
  • rewards/{reward_func_name}/group_std : l'écart-type de la récompense issue d'une fonction de récompense spécifique, calculé au sein de chaque groupe et moyenné sur les échantillons entraînés.
  • reward : la récompense moyenne globale après sommation des récompenses sur les différentes fonctions, pour toutes les complétions notées, y compris les groupes qui sont ensuite écartés. C’est la récompense de la politique, c’est donc celle qu’il faut suivre : reward_trained exclut les groupes dont les récompenses sont toutes égales.
  • reward_group_std : l'écart-type des récompenses cumulées sur les fonctions, calculé au sein de chaque groupe puis moyenné sur les échantillons entraînés. C'est la valeur par laquelle l'avantage est divisé, contrairement à reward_std de GRPO, qui est calculée sur l'ensemble du lot.
  • reward_trained : la récompense moyenne des échantillons sur lesquels l’entraîneur a été entraîné. Elle exclut les groupes dont les récompenses sont toutes égales ainsi que les échantillons écartés pour dépassement de max_staleness.
  • reward_zero_std_groups : la récompense moyenne des groupes dont les récompenses sont toutes égales et qui sont écartés : la valeur de récompense à laquelle ils sont bloqués. Consultez Saturation et doublons pour l’interpréter avec frac_zero_std_groups et reward.
  • frac_zero_std_groups : La proportion de groupes dont l'écart-type de la récompense est nul (toutes les réponses sont correctes ou incorrectes), ou qui comptent moins de deux complétions notables. Ces groupes sont écartés.
  • sampling/sampling_logp_difference/mean : Différence absolue moyenne entre les probabilités logarithmiques renvoyées par le module d'échantillonnage (vLLM) et celles recalculées par le modèle d'entraînement, sur les jetons entraînés.
  • sampling/sampling_logp_difference/max : La plus grande différence absolue de ce type.
  • sampling/importance_sampling_ratio/min: Le plus petit ratio d'échantillonnage par importance ri,t(θ) r_{i,t}(\theta) entre le modèle et l'échantillonneur, sur les jetons entraînés, avant que les jetons hors de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] ne soient supprimés.
  • sampling/importance_sampling_ratio/mean : Le ratio moyen d'échantillonnage par importance.
  • sampling/importance_sampling_ratio/max : le plus grand ratio d'échantillonnage d'importance.
  • sampling/masked_mean : la proportion de jetons entraînés exclus de la perte car leur ratio d’échantillonnage d’importance se situe en dehors de [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max].
  • sampling/sampler_mass : la masse de probabilité moyenne couverte par les num_sampler_logprobs jetons les plus probables de l'échantillonneur. Journalisé uniquement lorsque score_centering=True.
  • entropy : Entropie moyenne des prédictions de jetons sur l’ensemble des jetons entraînés.
  • aux_loss : perte auxiliaire d'équilibrage de charge d'un modèle Mixture-of-Experts, avant d'être mise à l'échelle par router_aux_loss_coef et ajoutée à la perte. Journalisée uniquement lorsque le modèle est un modèle MoE et que router_aux_loss_coef est non nul.
  • clip_ratio/region_mean: Le ratio des probabilités de jetons pour lesquelles l'objectif GRPO est tronqué afin de rester dans la région de confiance : clip(ri,t(θ),1−ϵlow,1+ϵhigh) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) . Avec score_centering=True la perte n'est pas tronquée, donc les clip_ratio/* métriques comptent les jetons situés en dehors de la région de confiance.
  • clip_ratio/low_mean: Le ratio moyen des probabilités de jetons qui ont été rognées sur la borne inférieure de la région de confiance : ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: La plus petite fraction de jetons par complétion, rognée sur la borne inférieure de la région de confiance : ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: Le ratio moyen des probabilités de jetons qui ont été rognées sur la borne supérieure de la région de confiance : ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: La plus grande fraction de jetons par complétion, tronquée à la borne supérieure de la région de confiance : ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.

Les autres métriques décrivent le pipeline asynchrone.

Les métriques sont journalisées une fois par fenêtre de journalisation : tout ce qui a été enregistré depuis le dernier journal, couvrant les logging_steps dernières étapes d’optimiseur. Sur la fenêtre :

  • Une moyenne mesurée par déroulement, échantillon ou appel, comme reward, rollout/turns_mean et tools/latency_s, est moyennée sur l’ensemble des déroulements, échantillons ou appels de la fenêtre. Un taux comme rollout/generated_tokens_per_s est le nombre total de jetons divisé par le nombre total de secondes.
  • Sinon, un nom dont la dernière partie contient le mot count est additionné : sample/dropped_stale_count est le nombre d’échantillons abandonnés depuis le dernier journal, et non depuis le début de l’entraînement.
  • Un nom dont la dernière partie contient le mot max ou min, comme sample/staleness_max ou completions/max_length, conserve la valeur la plus grande ou la plus petite.
  • Toute autre métrique est la moyenne des valeurs enregistrées dans la fenêtre.

Unités :

  • _s : secondes.
  • tokens_per_s : jetons par seconde.
  • _frac : fraction comprise entre 0 et 1.
  • _per_step : quantité par pas d'optimiseur, moyenne des pas de la fenêtre.

Métriques de déroulement

  • rollout/duration_s : durée réelle d'un rollout, du moment de la distribution jusqu'à ce que la boucle de collecte le récupère.
  • rollout/generated_tokens_per_s : le débit de génération, en jetons générés par seconde, depuis le dernier rapport.
  • rollout/concurrency : Le nombre de rollouts en cours d'exécution vers le serveur vLLM.
  • rollout/concurrency_cap : la limite actuelle des rollouts en cours, qui suit la charge du serveur. Voir Concurrency.
  • rollout/turns_mean, rollout/turns_max : le nombre moyen et maximal de tours par rollout.
  • rollout/samples_per_rollout : Le nombre d'échantillons d'entraînement par rollout. Au-dessus de 1.0, certains rollouts ont été dupliqués ; en dessous de 1.0, certains n'ont produit aucun jeton entraîné. Voir Multi-turn rollouts.
  • rollout/fork_frac : La proportion de transitions de tour dont le prompt ne commence pas par les jetons conservés, indiquant que le tour a démarré un nouvel échantillon.
  • rollout/drift_tokens_mean, rollout/drift_tokens_max : le nombre de jetons conservés que fourche a re-rendus, en moyenne sur les transitions de tour (une transition sans fourche compte pour 0). L’échantillon nouveau partage les jetons avant la divergence, c’est donc ce que chaque fourche ajoute au calcul en avant.
  • rollout/score_queue_size : Le nombre de groupes terminés en attente d'être notés.
  • rollout/queue_size : Le nombre d'échantillons notés en attente dans la file d'attente de rollout, mesuré à l'endroit où l'entraîneur les récupère. Voir La file d'attente de rollout.
  • rollout/score_s : Le temps nécessaire pour évaluer un groupe.
  • rollout/score_wait_s : Le temps pendant lequel un groupe terminé a attendu avant d'être noté.
  • rollout/score_block_s : le temps pendant lequel la génération a été bloquée car la file de scoring était pleine.
  • rollout/backpressure_s : le temps pendant lequel la génération a attendu avant de démarrer un rollout car elle était en avance de max_staleness étapes par rapport à l’entraînement, en moyenne sur les attentes de la fenêtre de journalisation. Voir Concurrence.
  • rollout/vllm_retry_count : Le nombre de requêtes vLLM réessayées. Un serveur dégradé ressemble sinon à une lenteur inexpliquée.
  • rollout/vllm_kv_cache_usage_frac : Utilisation du cache KV de vLLM (valeur maximale sur les moteurs), moyennée sur les relevés effectués dans la fenêtre de journalisation.
  • rollout/vllm_running_requests : le nombre de requêtes que les moteurs du serveur sont en train de décoder (num_requests_running de vLLM, additionné sur l’ensemble des moteurs). L’écart par rapport à rollout/concurrency correspond à ce qui se trouve dans le processus du serveur API, en train de construire les réponses.
  • rollout/vllm_queued_requests : le nombre de requêtes acceptées par le serveur mais pas encore planifiées (num_requests_waiting de vLLM, additionné sur les moteurs).
  • rollout/vllm_preemption_count : Le nombre de requêtes préemptées par le serveur (num_preemptions_total de vLLM, additionné sur l’ensemble des moteurs). Une synchronisation des poids réinitialise les caches du serveur, ce qui préempte toutes les requêtes en cours d’exécution ; ce n’est donc pas un indicateur de pression.

Métriques des outils

  • tools/latency_s, tools/{tool_name}/latency_s : le temps passé à exécuter un appel d’outil, pour l’ensemble des outils et par outil.
  • tools/{tool_name}/call_count, tools/{tool_name}/failure_count : le nombre d'appels et d'appels en échec par outil.
  • tools/unknown_name_count : Le nombre d'appels à un outil qui n'existe pas. Contrairement à un outil qui s'est exécuté et a levé une exception, il s'agit d'une erreur de politique.
  • tools/parallel_calls_mean : Le nombre moyen d'appels d'outils dans un message d'assistant qui appelle des outils.
  • tools/loop_exhausted_frac : La fraction de rollouts interrompus à max_tool_calling_iterations alors qu’ils appelaient encore des outils, sur l’ensemble des rollouts, y compris ceux sans appel et les groupes qui sont ensuite écartés. Journalisé uniquement lorsque le formateur dispose d’outils.

HarnessAsyncGRPOTrainer journalise la plupart de ces éléments sous les mêmes noms. Consultez Entraînement sur des harnais pour les différences.

Métriques de l'environnement

  • env/reset_s : le temps passé dans la méthode reset() de l’environnement avant le début d’un rollout. Journalisé uniquement lorsque environment_factory est fourni.
  • env/reward_s : le temps passé dans get_reward() de l’environnement après la fin d’un rollout. Journalisé uniquement si l’environnement définit get_reward.

Métriques d'exemple

  • sample/forwarded_tokens_mean, sample/forwarded_tokens_max : le nombre moyen et maximal de jetons transmis par échantillon.
  • sample/trained_tokens_mean : Le nombre moyen de tokens entraînés par échantillon.
  • sample/time_in_queue_s : Le temps pendant lequel un échantillon a attendu dans la file d'attente de rollout avant d'être utilisé pour l'entraînement.
  • sample/staleness_mean, sample/staleness_max : le nombre de mises à jour de poids entre la politique qui a généré un échantillon et celle qui s’entraîne dessus. Les métriques sampling/importance_sampling_ratio/* et sampling/sampling_logp_difference/* combinent cette obsolescence avec l’écart entre l’entraînement et l’inférence : un ratio s’écartant de 1.0 ou une différence de log-probabilité s’écartant de 0.0 à obsolescence nulle indique cet écart, par exemple une différence de dtype avec le serveur.
  • sample/dropped_stale_count : le nombre d'échantillons supprimés pour dépassement de max_staleness.

Métriques par lot

  • batch/forwarded_tokens_per_step, batch/trained_tokens_per_step : le nombre de tokens transmis et entraînés par étape, sur l’ensemble des processus.
  • batch/samples_per_step, batch/groups_per_step : le nombre d'échantillons et de groupes distincts par étape. Ils diffèrent du nombre d'échantillons par groupe.
  • batch/microbatches_per_step : Le nombre de micro-lots par étape.
  • batch/masked_token_frac : La proportion de tokens transmis qui ne sont pas entraînés.
  • batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max : le nombre d'échantillons par ligne, ainsi que le nombre moyen et maximal de jetons transmis par ligne.
  • batch/row_fill_frac : La fraction de token_budget utilisée par les lignes.
  • batch/row_imbalance : le ratio entre le coût d’attention de la ligne la plus coûteuse et le coût moyen. Le processus possédant la ligne la plus coûteuse bloque les autres lors de l’1.0 des gradients ; 1.0 correspond à un équilibre parfait.
  • batch/packing_ratio : le nombre de jetons avant l’empaquetage par jeton transmis : le facteur par lequel l’empaquetage réduit le calcul en avant, 1.0 lorsque rien n’est partagé.
  • batch/pad_frac : La fraction de bourrage ajoutée pour uniformiser la longueur des lignes. Elle ne coûte que du transfert et est retirée avant le passage avant.
  • batch/dropped_oversize_count : le nombre d'échantillons supprimés pour dépassement de token_budget.

Métriques de performance

  • perf/step_s : le temps réel d'une étape, incluant l'optimiseur, la synchronisation des poids et le temps d'attente des échantillons.
  • perf/fwd_bwd_s, perf/fwd_s : le temps passé dans les passes avant et arrière d'une étape, et dans ses passes avant uniquement.
  • perf/optimizer_s : le temps passé dans l'étape de l'optimiseur.
  • perf/rollout_wait_s : le temps pendant lequel l’entraînement a attendu parce que la file de rollout était vide. Voir La file de rollout.
  • perf/weight_sync_s : la durée d'une synchronisation des poids, découpée en perf/weight_sync_pause_s (attente de la pause de vLLM), perf/weight_sync_barrier_s (attente des autres processus) et perf/weight_sync_transfer_s (envoi des poids).
  • perf/fwd_bwd_forwarded_tokens_per_s, perf/wall_clock_forwarded_tokens_per_s : le nombre de tokens transmis par seconde, sur les passes avant et arrière ou sur l’ensemble de l’étape.
  • perf/wall_clock_trained_tokens_per_s : Le nombre de jetons entraînés par seconde, sur l'ensemble de l'étape.
  • perf/fwd_bwd_mfu, perf/wall_clock_mfu : l’utilisation des FLOPs du modèle sur les dispositifs d’entraînement, sur les passes avant et arrière ou sur l’ensemble de l’étape. Ils excluent le serveur vLLM. Journalisés uniquement lorsque la puissance de calcul de pointe du dispositif d’entraînement à la précision d’entraînement est connue, et lorsque l’estimation des FLOPs prend en charge l’architecture du modèle (telles que Llama, Qwen2, Qwen3, Qwen3-MoE ou Qwen3-VL).

Personnalisation

Configurer le serveur vLLM

Le formateur génère avec un serveur vLLM, auquel il accède à l’adresse vllm_server_base_url (http://localhost:8000 par défaut) :

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 et --weight-transfer-config exposent les points de passage par lesquels l’entraîneur transmet ses poids.
  • --logprobs-mode processed_logprobs permet au serveur de renvoyer les log-probabilités de la distribution d’où l’échantillonnage a été effectué, après application de la température et de top-k/top-p, ce qui correspond à la valeur de référence utilisée pour le calcul du ratio d’importance.
  • --api-server-count 8 conserve les probabilités de log les plus élevées, ce qui permet de traiter les demandes de centrage des scores à moindre coût (voir l'avertissement ci-dessous).
  • --max-model-len est la longueur totale maximale de séquence (invite et complétion) que vous prévoyez. Une valeur plus faible réduit l’utilisation de la mémoire GPU sur le serveur, libérant ainsi plus de mémoire pour le cache KV et augmentant le débit. Un bon point de départ est la longueur de l’invite plus max_completion_length de votre configuration. Avec les outils, chaque tour ajoute jusqu’à max_completion_length jetons plus les résultats des outils, il convient donc de le régler à la conversation la plus longue que vous prévoyez. Si l’invite d’un tour plus max_completion_length est plus longue que --max-model-len, le serveur rejette la requête et l’exécution s’arrête avec l’erreur du serveur. Avec top_k ou top_p, le serveur arrête plutôt ce tour lorsqu’il atteint --max-model-len, et ne rejette qu’une invite qui est déjà aussi longue. C’est également le token_budget par défaut.

Assurez-vous que le serveur utilise des GPU différents de ceux du formateur, sinon vous risquez de rencontrer des erreurs NCCL. Vous pouvez spécifier les GPU à utiliser avec la variable d’environnement CUDA_VISIBLE_DEVICES.

La sérialisation des log-probabilités supérieures est une tâche CPU dans le serveur API de vLLM, et avec son serveur API unique par défaut, num_sampler_logprobs=8 divise par deux le débit de génération. Démarrez le serveur avec --api-server-count 8 sur vLLM 0.32 ou ultérieur : mesuré sur une H100 avec des modèles de 1,5 à 7 Md, les log-probabilités supérieures (top-8) coûtent alors moins de 3 % du débit de génération. Sur vLLM 0.31, le même drapeau laisse encore une perte de 20 à 40 %, corrigée en amont par vllm-project/vllm#58181.

Concurrence

Trois limites déterminent le nombre de rollouts exécutés simultanément. Les deux premières s’adaptent automatiquement ; la troisième est à définir par vous.

Obsolètes. max_staleness définit le nombre d'étapes d'entraînement que la génération peut devancer par rapport à l'entraîneur. Le travailleur suit cette valeur en jetons, car le nombre d'échantillons par étape varie selon que les compléments s'allongent ou se raccourcissent. Après chaque étape, l'entraîneur compte les jetons utilisés et autorise le travailleur à maintenir en file d'attente ou en cours d'exécution jusqu'à max(max_staleness, 1) fois ce nombre de jetons. Avant la première étape, il suppose que chaque ligne est pleine. Le travailleur ne démarre un nouveau groupe de déploiements que s'il est sous cette limite. Au tout début, il ne sait pas encore combien de jetons un déploiement produit, il en démarre donc un groupe à la fois jusqu'à ce que le premier groupe soit terminé. Un échantillon qui finit par être plus ancien de plus de max_staleness étapes est supprimé.

Chargement de vLLM. Envoyer trop de requêtes à vLLM en même temps le ralentit : le cache KV se remplit et vLLM doit mettre en pause et refaire certaines requêtes. Le worker maintient donc une limite en direct sur le nombre de rollouts exécutés simultanément, journalisée sous rollout/concurrency_cap, et vérifie les /metrics du serveur toutes les 5 secondes pour l’ajuster. La limite démarre au nombre de requêtes qui tiennent dans le cache KV à pleine longueur (KV cache tokens / max_model_len), afin que le serveur ne soit pas surchargé au démarrage. Tant que l’utilisation du cache KV reste inférieure à 60 % et qu’aucune requête n’attend, la limite augmente de 25 %, au maximum une fois par lot de rollouts terminés équivalent à la limite. Quand l’utilisation dépasse 80 %, elle diminue de 30 % : les requêtes en cours continuent et les nouvelles attendent. Si le serveur n’a pas de point d’accès /metrics, la limite est max_concurrent_rollouts.

Ressources. max_concurrent_rollouts (par défaut 512) est la limite supérieure du nombre de rollouts exécutés simultanément. C’est la seule limite que vous définissez vous-même, car l’entraîneur ne peut pas savoir ce que vos environnements et outils peuvent supporter. Chaque rollout en cours d’exécution utilise un environnement, peut exécuter des appels d’outils synchrones sur un pool de threads de cette taille et maintient une connexion ouverte avec le serveur vLLM. Réglez cette valeur sur ce que ces composants peuvent supporter, par exemple le nombre de sessions acceptées par votre serveur d’environnement :

from trl import AsyncGRPOConfig

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

S’il est trop bas, la génération ralentit. Un déroulement conserve son emplacement pendant qu’il exécute des outils ou qu’il attend entre les tours, et non seulement pendant que vLLM génère, de sorte que les déroulements qui appellent de nombreux outils ont besoin de plus d’emplacements pour maintenir vLLM occupé. S’il est beaucoup plus élevé que la valeur par défaut, le serveur vLLM peut commencer à abandonner les connexions.

Les métriques journalisées indiquent quelle limite freine la génération :

  • rollout/backpressure_s supérieur à zéro : la limite de vétusté. La génération est en avance sur l’entraînement, ce qui est attendu lorsque l’inférence est plus rapide que l’entraînement.
  • rollout/concurrency à rollout/concurrency_cap, inférieur à max_concurrent_rollouts : la charge du serveur vLLM.
  • rollout/concurrency à max_concurrent_rollouts, avec un faible rollout/vllm_kv_cache_usage_frac et un élevé perf/rollout_wait_s : le plafond. Augmentez max_concurrent_rollouts si vos environnements et outils le permettent.

La file d'attente de déploiement

Le worker pousse les échantillons notés dans une file d'attente et le trainer en tire. Quatre métriques décrivent cette file d'attente :

  • rollout/queue_size : nombre d'échantillons en attente.
  • sample/time_in_queue_s : durée d'attente d'un échantillon unique avant d'être entraîné, la composante temporelle de son ancienneté.
  • perf/rollout_wait_s : durée pendant laquelle l'entraînement a attendu en raison d'une file vide.
  • rollout/backpressure_s : durée pendant laquelle la génération a attendu car elle était en avance de max_staleness étapes sur l'entraînement.

Les deux derniers sont des images miroir. Lues conjointement avec la taille de la file d’attente, elles vous indiquent quel côté est le goulot d’étranglement :

  • File d'attente presque vide, perf/rollout_wait_s élevé : limité par la génération. Le formateur est en manque de données ; examinez rollout/generated_tokens_per_s, rollout/concurrency et rollout/score_queue_size.
  • file d’attente contenant environ max_staleness étapes de jetons, rollout/backpressure_s élevé : limité par l’entraîneur. La génération est freinée et sample/staleness_mean se situe près de sa limite.
  • les deux élevés : la limite max_staleness elle-même est trop stricte. Les déroulements en cours la remplissent avant que leurs échantillons n’atteignent la file d’attente, si bien que l’entraîneur attend pendant que la génération est retenue. Augmentez max_staleness.
  • les deux proches de zéro : équilibré.

Saturation et doublons

La politique apprend à partir des différences entre les déroulements d’un groupe : chaque avantage est calculé par rapport à la récompense moyenne du groupe. Lorsque tous les déroulements d’un groupe reçoivent la même récompense, ils obtiennent tous un avantage nul, le groupe est donc écarté (voir Métriques journalisées) et n’enseigne rien à la politique. À mesure qu’une exécution sature, de plus en plus de groupes finissent dans cette situation, soit parce que tous les déroulements résolvent le prompt, soit parce qu’aucun ne le fait. Quatre métriques permettent de distinguer ces cas, et chacune répond à sa propre question, de sorte que vous pouvez les lire directement sur leurs graphiques :

métriquequestion
frac_zero_std_groupsquelle proportion de groupes ne porte aucun signal
reward_zero_std_groupsoù ces groupes sont bloqués : leur récompense moyenne. Avec des récompenses 0/1, il s’agit de la proportion d’entre eux pour laquelle tous les rollouts ont réussi, de sorte que 0,9 signifie que presque tous sont résolus, et 0,1 que presque tous échouent à chaque rollout
rewardà quel point la politique performe sur chaque groupe noté, y compris ceux qui ont été écartés
completions/duplicate_fracsi l'échantillonnage produit toujours des déroulements différents pour le même prompt

Lisez les trois premiers ensemble, par rapport à l'étendue de votre récompense :

frac_zero_std_groupsreward_zero_std_groupsrewarddiagnosticque faire
lowany (bruité sur quelques groupes)anysain : la plupart des groupes produisent un gradientrien
escaladevers le haut de la plageescaladesaturation en haut : les prompts sont devenus trop faciles pour la politique, ce qui est la façon dont une exécution réussie se termine généralementarrêter l'exécution, ou passer à des prompts plus difficiles
élevévers le bas de la plagefaible et platbloqué en bas : les prompts sont trop difficiles, ou la fonction de récompense n'accorde jamais de créditVérifiez d'abord completions/clipped_ratio, car une complétion coupée avant sa réponse reçoit un score de 0, puis lisez quelques complétions pour vérifier que la fonction de récompense les analyse correctement
escaladeen chuteen chuteregression : les groupes qui passaient auparavant échouent désormais ensemblevérifiez completions/duplicate_frac et entropy pour détecter un effondrement
élevéau milieuanyun mélange : avec des récompenses 0/1, certains prompts sont trop faciles et d’autres trop difficiles. Avec des récompenses à crédit partiel, les groupes peuvent également rester bloqués sur le même score partiellire les déroulements

completions/duplicate_frac représente la proportion de rollouts qui répètent, jeton par jeton, un rollout antérieur de leur groupe, sur l’ensemble de leurs tours. Les rollouts identiques reçoivent des récompenses identiques, si bien que les doublons font également augmenter frac_zero_std_groups.

completions/duplicate_fracdiagnostic
proche de 0, avec une légère valeur de base sur les tâches dont les complétions sont suffisamment courtes pour être reproduites par hasardsain : les déroulements d'un groupe sont échantillonnés de manière indépendante
saut vers (num_generations - 1) / num_generationsl'échantillonnage n'est plus aléatoire : chaque groupe revient en copies d'un seul déroulement. Par exemple, une température de 0, ou des moteurs vLLM en parallélisme de données qui décodent le même texte parce qu'ils partagent une graine d'échantillonnage (le travailleur envoie une graine unique avec chaque requête pour éviter cela)
monte lentement, avec entropy en baissecollapse : la politique converge vers une seule réponse par invite

Ces métriques sont enregistrées lorsque le worker évalue un groupe, et non lorsque ses échantillons sont entraînés, elles sont donc légèrement en avance sur l’entraînement et incluent des groupes dont les échantillons sont ensuite écartés pour avoir dépassé max_staleness. Un groupe pour lequel aucun rollout n’a pu être évalué, parce que chaque fonction de récompense a renvoyé None, est écarté et comptabilisé dans frac_zero_std_groups, mais comme il n’a pas de récompense, reward_zero_std_groups ne l’inclut pas.

Empaquetage d'arbres

Les échantillons d'un micro-lot sont regroupés dans une seule ligne par processus, sans bourrage. Une ligne est un préfixe trie, et non une concaténation : un jeton partagé par plusieurs échantillons est transmis une seule fois, et l'attention montre à chaque échantillon exactement son propre historique. Les déroulements d'un groupe répètent tous son invite, et chaque tour d'un déroulement multi-tours répète la conversation jusqu'à présent, de sorte que la propagation avant est réduite par le ratio de regroupement (batch/packing_ratio). Il s'agit uniquement d'un changement de disposition : chaque jeton entraîné conserve sa propre cible, son avantage et son ancienne log-probabilité, et sa log-probabilité correspond à celle obtenue en transmettant l'échantillon seul.

Sur deux déroulements d’un même prompt, où p est le prompt et a, b les deux complétions :

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

Quelques conséquences :

  • Tout préfixe commun est partagé : les déroulements d’un prompt, et entre prompts, un prompt système ou un schéma d’outil commun. Un échantillon est envoyé vers la ligne qui contient déjà son groupe, où son prompt est déjà présent. Lorsque cette ligne est pleine, l’échantillon est envoyé vers une autre ligne si un processus en possède encore une vide, ou si cela n’augmente pas la charge de la ligne la plus sollicitée, qui détermine la durée du micro-lot ; sinon, le micro-lot est clôturé.
  • Aucun partage n’est effectué, il s’agit d’un simple empilement : chaque échantillon constitue alors son propre segment, ce qui correspond à un empilement classique sans bourrage.
  • Seuls les K/V sont dupliqués : un préfixe partagé est collecté une fois par segment descendant, ce qui correspond à peu près à ce que contiendrait un entraînement non dépaqueté, et reste faible avec l’attention à requêtes groupées.
  • Les hybrides Gated DeltaNet sont pris en charge (Qwen3.5, Qwen3.6, Qwen3-Next, …) : leur convolution lit les prédécesseurs propres à chaque jeton, et leur règle delta par segments démarre chaque segment à partir de l’état final de son parent.

token_budget limite le nombre de jetons d’une ligne, en comptant un jeton partagé une seule fois. Par défaut, il correspond à la valeur max_model_len du serveur, de sorte qu’aucun échantillon ne peut la dépasser. En l’absence de jetons partagés, le tree packing fonctionne à une vitesse proche de celle du padding-free packing classique, et le gain de vitesse augmente approximativement avec le taux de packing (environ 2,8 à 3x pour un taux de 3,4 sur Qwen3-0.6B et 1.7B, sur H100). Ce taux correspond au préfixe partagé multiplié par le nombre d’échantillons par ligne, si bien que batch/samples_per_row est l’indicateur principal : s’il est proche de 1, rien ne peut être partagé et la variable d’ajustement est token_budget. batch/row_fill_frac devient important lorsque les échantillons sont longs : un échantillon de 10k jetons remplit mal un budget de 32k (trois tiennent, quatre ne tiennent jamais, le planificateur en obtient donc souvent deux et la ligne est remplie à environ 77 %), tandis que des échantillons de 1k jetons le remplissent presque parfaitement.

Jugez le tree packing sur le débit, batch/trained_tokens_per_step / perf/fwd_bwd_s. Un micro-lot compacté contient plus d’échantillons, donc perf/fwd_bwd_s augmente et perf/fwd_bwd_mfu, qui divise par les jetons transmis, diminue : aucun des deux n’est une régression. Plus d’échantillons par ligne signifie aussi plus de rollouts tirés par étape, ce qui rend une exécution limitée par la génération encore plus limitée par celle-ci.

Les métriques par lot se composent ainsi : une étape contient gradient_accumulation_steps × num_processes lignes, de sorte que batch/samples_per_step est environ ce nombre de fois supérieur à batch/samples_per_row, et de même pour les jetons. Les deux côtés ne concordent qu’à la variation près entre les micro-lots d’une étape, car les métriques par étape sont des sommes et celles par ligne sont des moyennes.

Tout ce qui allonge les lignes ou en réduit le nombre supprime le partage. Une conversation multi-tours qui ne se bifurque jamais constitue un seul échantillon long, et rollout/samples_per_rollout indique le nombre d’échantillons qu’une conversation produit.

Échantillonnage top-k et top-p

Top-k et top-p renormalisent la distribution d’échantillonnage sur un ensemble restreint de candidats plutôt que sur tout le vocabulaire. Les log-probabilités du serveur en tiennent compte (--logprobs-mode processed_logprobs), le formateur doit donc normaliser sur le même ensemble, sinon tous les rapports d’importance sont biaisés : la probabilité d’un jeton sur l’ensemble du vocabulaire est inférieure à celle sur l’ensemble de candidats d’où il a été tiré (DeepSeek-V3.2, section 3.1). Avec top_p < 1 ou top_k > 0, le travailleur demande au serveur l’ensemble de candidats de chaque jeton échantillonné et le formateur renormalise ses log-probabilités sur cet ensemble. Cela nécessite deux drapeaux supplémentaires côté serveur, et top_k doit être défini, car vLLM borne la taille de l’ensemble de candidats avec ce paramètre :

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 permet à vLLM d’enregistrer l’ensemble des candidats (vLLM 0.28 ou ultérieur, sur son exécuteur de modèle V2 : VLLM_USE_V2_MODEL_RUNNER=1 si le serveur refuse le drapeau), et --enable-scale-out expose le point de terminaison token-in-token-out qui le renvoie. Le travailleur vérifie les deux sur le serveur au démarrage. Une version plus ancienne de vLLM ne peut pas renvoyer l’ensemble, le formateur continue donc de normaliser sur tout le vocabulaire et émet un avertissement concernant le ratio biaisé.

Entraîner des adaptateurs avec PEFT

Nous prenons en charge une intégration étroite avec la bibliothèque 🤗 PEFT, vous permettant d’entraîner des adaptateurs et de les partager sur le Hub plutôt que d’entraîner le modèle entier.

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

Chaque synchronisation des poids doit transmettre la politique mise à jour au serveur. Par défaut, l’entraîneur fusionne l’adaptateur dans le modèle de base et envoie les poids fusionnés complets, soit environ 15 Go pour un modèle de 7B à chaque synchronisation. Démarrez le serveur vLLM avec --enable-lora et il n’enverra que l’adaptateur, soit environ 160 Mo à r=32 :

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 expose l’endpoint vers lequel l’entraîneur envoie chaque nouvel adaptateur. Conservez --weight-transfer-config même avec --enable-lora : l’entraîneur ne choisit un mode de synchronisation qu’au démarrage, à un moment où le serveur est déjà actif, et la synchronisation fusionnée est le mode par défaut.

--max-lora-rank doit être l’un des éléments de 1, 8, 16, 32, 64, 128, 256, 320, 512. Il définit le rang maximal que le serveur peut servir, et non le rang qu’il servira effectivement, de sorte qu’un adaptateur r=4 fonctionne parfaitement sous 8. --max-loras doit être au moins égal à max_staleness + 2 : l’entraîneur conserve max_staleness + 1 versions d’adaptateurs enregistrées afin qu’un déroulement ayant démarré sous une politique plus ancienne puisse se terminer sous celle-ci, plutôt que de changer de politique en cours de génération, et chaque synchronisation charge la version suivante avant de décharger la plus ancienne. L’entraîneur vérifie les deux valeurs au démarrage et vous indique avec quelles valeurs relancer le serveur.

vLLM charge les adaptateurs depuis le disque plutôt que via le réseau, le formateur écrit donc chaque version sous <output_dir>/.vllm_lora/ et transmet le chemin au serveur. Si le serveur s’exécute sur une machine différente, ce répertoire doit se trouver sur un système de fichiers accessible aux deux.

<output_dir>/.vllm_lora/ est un cache de service, et non l’endroit où votre adaptateur entraîné est conservé. Il ne contient que les versions les plus récentes, et chacune est supprimée peu après avoir quitté la fenêtre de fraîcheur. Les points de contrôle sont ce qui préserve l’adaptateur que vous avez entraîné, il ne faut donc pas les désactiver : avec save_strategy="no", une exécution de plusieurs heures se termine sans laisser aucune trace. output_dir doit également être lisible par le serveur et doit survivre à la tâche, de sorte qu’un espace de travail local au nœud ne fonctionnera pas, même s’il permettrait d’éviter les synchronisations sur un système de fichiers partagé lent.

La synchronisation d’adaptateurs n’est pas toujours plus rapide. vLLM génère environ 1,33 à 1,39 fois plus lentement par jeton lorsqu’il sert un adaptateur LoRA par rapport à des poids fusionnés, et la génération est généralement ce qui domine le temps réel en RL. En contrepartie, vous obtenez une pause beaucoup plus courte à chaque synchronisation et environ 1 % de la bande passante de synchronisation. Si le débit de génération est votre goulot d’étranglement, la synchronisation fusionnée reste souvent le meilleur choix.

Utiliser une fonction de récompense personnalisée

Le AsyncGRPOTrainer prend en charge l'utilisation de fonctions de récompense personnalisées. Pour garantir la compatibilité, votre fonction de récompense doit satisfaire aux exigences suivantes :

Les fonctions de récompense peuvent être des fonctions Python synchrones ou des coroutines asynchrones async def. Lorsque vous fournissez plusieurs fonctions de récompense, elles s'exécutent de manière concurrente : les fonctions asynchrones sont attendues ensemble et les fonctions synchrones s'exécutent dans des threads, de sorte que leur latence se chevauche.

  1. Arguments d'entrée :

    • La fonction doit accepter les éléments suivants en tant qu'arguments nommés :

      • prompts (contient les prompts),
      • completions (contient les complétions générées),
      • completion_ids (contient les complétions tokenisées),
      • Tous les noms de colonnes (sauf prompt) que le jeu de données peut contenir. Par exemple, si le jeu de données contient une colonne nommée ground_truth, la fonction sera appelée avec ground_truth en tant qu'argument par mot-clé.

      La façon la plus simple de respecter cette exigence est d'utiliser **kwargs dans la signature de la fonction.

    • Le jeu de données est au format conversationnel, donc prompts et completions sont des listes de dictionnaires de messages.

  2. Valeur de retour : La fonction doit retourner une liste de flottants. Chaque flottant représente la récompense correspondant à une seule complétion.

Les fonctions de récompense s’exécutent dans le worker de rollout, un processus distinct, de sorte que tout ce qui lui est transmis est picklé. Chaque fonction de récompense, outil et environment_factory (ainsi que tout ce qu’ils referment) doit être picklable : utilisez une fonction au niveau du module, functools.partial ou une instance de classe appelables. Les lambdas et les fermetures (closures) lèvent une TypeError lors de l’appel à trainer.train(). C’est une différence par rapport à GRPOTrainer, où les fonctions de récompense sont appelées dans le processus et où les fermetures fonctionnent.

Le processus de déroulement s’exécute également avec CUDA_VISIBLE_DEVICES="", il ne peut donc pas utiliser le GPU. Un modèle de récompense basé sur GPU (par exemple un scoreur AutoModelForSequenceClassification) se charge sans erreur mais bascule silencieusement sur le CPU. Gardez les fonctions de récompense légères (vérificateurs comme accuracy_reward, contrôles de format ou de longueur). Si vous avez besoin d’un modèle de récompense sur GPU, servez-le derrière son propre moteur d’inférence (vLLM, TGI, …) sur des GPU distincts et faites en sorte qu’une fonction de récompense sérialisable l’appelle via HTTP.

Exemple 1 : Récompenser les complétions plus longues

Voici un exemple de fonction de récompense qui récompense les complétions plus longues :

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]

Vous pouvez le tester comme suit :

>>> 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]

Exemple 2 : Récompenser les complétions avec un format spécifique

Voici un exemple de fonction de récompense qui vérifie si l’achèvement respecte un format spécifique. Cet exemple s’inspire de la fonction format reward utilisée dans l’article DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Elle est conçue pour un format conversationnel, où les invites et les achèvements sont constitués de messages structurés.

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]

Vous pouvez tester cette fonction comme suit :

>>> 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]

Exemple 3 : Récompenser les complétions sur la base d'une référence

Voici un exemple de fonction de récompense qui vérifie si la complétion est correcte. Cet exemple s’inspire de la fonction accuracy reward utilisée dans l’article DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Le jeu de données contient une colonne nommée 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)]

Vous pouvez tester cette fonction comme suit :

>>> 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]

Exemple 4 : Fonctions de récompense multi-tâches

Voici un exemple d'utilisation de plusieurs fonctions de récompense dans le AsyncGRPOTrainer. Dans cet exemple, nous définissons deux fonctions de récompense spécifiques à la tâche : math_reward_func et coding_reward_func. La fonction math_reward_func attribue une récompense aux problèmes de mathématiques en fonction de leur exactitude, tandis que la fonction coding_reward_func attribue une récompense aux problèmes de codage en fonction du fait que la solution fonctionne.

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

Dans cet exemple, math_reward_func et coding_reward_func sont conçus pour fonctionner avec un jeu de données mixte contenant à la fois des problèmes de mathématiques et de codage. La colonne task du jeu de données est utilisée pour déterminer quelle fonction de récompense appliquer à chaque problème. S'il n'existe pas de fonction de récompense pertinente pour un échantillon du jeu de données, la fonction de récompense renvoie None, et le AsyncGRPOTrainer poursuit avec les fonctions et tâches valides. Cela permet au AsyncGRPOTrainer de gérer plusieurs fonctions de récompense avec des domaines d'application différents.

Notez que le AsyncGRPOTrainer ignore les récompenses None renvoyées par les fonctions de récompense et ne prend en compte que les récompenses renvoyées par les fonctions pertinentes. Cela garantit que le modèle est entraîné sur les tâches pertinentes et ignore celles pour lesquelles il n’existe pas de fonction de récompense appropriée.

Exemple 5 : Fonctions de récompense asynchrones

Les fonctions de récompense personnalisées peuvent également être définies sous forme de coroutines async def. Cela est utile si votre récompense dépend d'une E/S lente (par exemple, l'appel d'un service distant). Lorsque vous transmettez plusieurs fonctions de récompense asynchrones, AsyncGRPOTrainer les exécute de manière concurrente afin que leur latence se superpose.

Voici un exemple minimal d'une fonction de récompense asynchrone qui simule une opération limitée par l'E/S :

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]

Passer la fonction de récompense à l'entraîneur

Pour utiliser votre fonction de récompense personnalisée, transmettez-la à AsyncGRPOTrainer comme suit :

from trl import AsyncGRPOTrainer

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

Vous pouvez passer plusieurs fonctions de récompense sous forme de liste ; cette liste peut inclure à la fois des fonctions synchrones et asynchrones :

from trl import AsyncGRPOTrainer

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

et la récompense sera calculée comme la somme des récompenses de chaque fonction.

Personnalisation de la boucle de déroulement

La génération, les récompenses, les avantages et le filtrage s’exécutent dans le processus de déroulement, dans AsyncRolloutLoop. Pour modifier l’un d’entre eux, sous-classez la boucle, surchargez la méthode correspondant à cette étape et définissez la sous-classe comme loop_cls sur une sous-classe du formateur. Le constructeur du formateur ne change pas.

MéthodeAppeléPar défaut
filter_prompt(row_index, row, epoch)une fois par invite, avant la générationaccepte chaque invite
generate_one(prompt, tools, group_id)une fois par déroulementla boucle d'outils multi-tours
generate_one_turn(prompt_ids)une fois par demande d'échantillonnageune requête vLLM avec les paramètres d'échantillonnage de la configuration
compute_advantages(group)une fois par groupe, après que les récompenses ont été additionnées dans group.rewardsrécompense standardisée au sein du groupe
setup(), close()lorsque les boucles commencent et s'arrêtentrien

Par exemple, un curriculum qui cesse d’échantillonner les prompts que la politique résout déjà, avec son seuil dans une sous-classe de configuration :

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

Les récompenses sont additionnées sur reward_funcs, les environnements qui définissent get_reward et la reward qu'un generate_one personnalisé définit sur son Rollout : pour évaluer avec un juge, passez une fonction de récompense asynchrone, ou évaluez à l'intérieur de generate_one. compute_advantages s'exécute pour chaque groupe, y compris celui qui est ensuite écarté parce que toutes ses récompenses notées sont égales ; l'écartement examine les récompenses, et non les avantages. La boucle est construite dans un processus généré, définissez donc la sous-classe au niveau du module et maintenez le code d'entraînement sous if __name__ == "__main__":. Créez les clients dans setup, qui s'exécute sur la boucle d'événements de la boucle, plutôt que de surcharger __init__. Un prompt rejeté par filter_prompt est ignoré pour cet epoch et compte pour celui-ci, comme un groupe écarté. S'il rejette tous les prompts d'un epoch, la boucle lève une exception.

Reprendre depuis un point de contrôle

Le Trainer de base reprend en sautant et en rejouant les lots sur lesquels il a déjà entraîné, ce qui ne s’applique pas à une file de déroulement en direct, si bien que ignore_data_skip est toujours True. En revanche, l’indice de la première invite non encore entraînée est enregistré dans rollout_state.json avec chaque point de contrôle et restauré lors de la reprise, ce qui permet au travailleur de se positionner directement sur cette invite sans rejouer les échantillons. Il s’agit de la position trained, et non de celle du générateur : le travailleur avance sur l’entraînement d’une profondeur de file de déroulement, et ces échantillons mis en mémoire tampon sont perdus à la fin de l’exécution, de sorte qu’une reprise depuis la position du générateur sauterait des invites qui ont été générées mais jamais entraînées. Les jeux de données en flux (IterableDataset) ne peuvent pas être repositionnés, si bien que leur travailleur redémarre depuis la première invite lors de la reprise.

Entraînement des agents

GRPO asynchrone prend en charge l'entraînement d'agents : le modèle appelle des outils pendant la génération et apprend à partir du résultat.

  • Un outil est une fonction Python simple (synchrone ou asynchrone) exposée au modèle. Utilisez tools pour les appels sans état (une calculatrice, une recherche web).
  • Un environnement est la forme plus générale : un objet avec état, créé à neuf pour chaque déroulement, dont les méthodes publiques sont exposées en tant qu’outils, accompagné d’un hook de cycle de vie reset et d’une méthode optionnelle get_reward qui lui permet de gérer la récompense. Utilisez environment_factory lorsque vous avez besoin d’un état par déroulement, d’un hook de réinitialisation ou d’une récompense gérée par l’environnement.

Ils se composent — vous pouvez passer des tools autonomes aux côtés d'une environment_factory.

Outils

L'argument tools attend une liste de fonctions Python (synchrone ou asynchrone) qui définissent les outils disponibles pour l'agent :

from trl import AsyncGRPOTrainer

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

Chaque outil doit être une fonction Python standard avec des arguments et types de retour annotés, accompagnée d'une docstring au style Google décrivant son objectif, ses arguments et sa valeur de retour. Pour plus de détails, consultez le guide sur la transmission d'outils.

Le modèle appelle un outil par son nom, chaque outil est donc enregistré sous son __name__ et doit être une fonction de niveau module, ce qui le rend également sérialisable pour le travailleur de rollout. Les outils synchrones s’exécutent sur un pool de threads dimensionné selon max_concurrent_rollouts, de sorte qu’un outil lent ne bloque jamais les autres rollouts en cours. Au sein d’un tour de l’assistant, les appels d’outils s’exécutent dans l’ordre où le modèle les a émis. Jusqu’à max_concurrent_rollouts outils synchrones peuvent donc s’exécuter simultanément, si bien qu’un outil qui lit ou écrit un état partagé doit être sûr en environnement multithreadé.

La boucle d’appel d’outils exige que le modèle de discussion soit préfixe-préservant (l’ajout d’un message d’outil ne doit pas modifier la façon dont les messages précédents sont rendus). Pour les familles de modèles connues (par ex. Qwen3, DeepSeek-V3), TRL remplace automatiquement le modèle d’entraînement par un modèle corrigé lorsque les outils sont activés. Consultez Chat Templates pour la liste complète.

Utilisez max_tool_calling_iterations dans AsyncGRPOConfig pour limiter le nombre de tours d’appel d’outils. Par défaut, il n’y a pas de limite et la génération s’arrête lorsque le modèle produit un tour de réponse sans appel d’outils.

Exemple :

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],
    ...,
)

Environnements

Vous pouvez également fournir des outils via environment_factory. Dans ce mode, AsyncGRPOTrainer crée une instance d’environnement par rollout et expose les méthodes publiques de l’environnement en tant qu’outils.

Lorsque vous utilisez une environment_factory, l'environnement possède les données : il n'y a pas de train_dataset externe. À chaque rollout, reset() génère la tâche — par auto-échantillonnage à partir d'un corpus détenu par l'environnement, ou en générant un état de manière procédurale — et renvoie le prompt. max_steps définit la durée de l'entraînement. Voici un exemple minimal d'un environnement qui s'auto-échantillonne une cible et expose une méthode increment (exposée en tant qu'outil).

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

Une classe d’environnement possède deux méthodes réservées : reset et get_reward. Contrairement à toute autre méthode publique, celles-ci ne sont pas exposées au modèle en tant qu’outils.

  • reset (obligatoire) est appelé au démarrage du déroulement. Il peut renvoyer soit None, soit une chaîne de caractères. S’il renvoie une chaîne, celle-ci constitue le prompt utilisateur.
  • get_reward (facultatif, synchrone ou asynchrone) ne prend aucun argument et renvoie un float : l’environnement évalue l’épisode qu’il vient d’exécuter à partir de son état interne (la partie s’est-elle terminée par une victoire ? le mot a-t-il été deviné ?). Il est appelé une fois par déroulement terminé et sert de source de récompense.

Les deux s’exécutent sur le pool de threads d’outils du worker, de sorte qu’un environnement lent retarde son propre déploiement, mais pas les autres en cours. Leurs durées sont journalisées sous la forme env/reset_s et env/reward_s.

Comme l’environnement se rééchantillonne à chaque reset(), les G membres d’un groupe GRPO ne partagent pas nécessairement le même état initial, ce qui rend la référence du groupe légèrement plus bruitée. Pour des états identiques au sein d’un groupe, faites en sorte que reset() dérive l’état de manière déterministe à partir d’une clé partagée.

Fournir un jeu de données externe (facultatif)

Plutôt que de laisser l’environnement s’échantillonner lui-même, vous pouvez fournir un train_dataset externe. Par exemple, lorsque vos tâches sont déjà présentes dans un jeu de données, ou pour router entre plusieurs environnements. À chaque rollout, le formateur échantillonne une ligne, utilise sa colonne "prompt" comme invite et transmet les colonnes de la ligne à reset() en tant qu’arguments nommés (afin que l’environnement lise la tâche depuis le jeu de données).

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

Récompenses

Les récompenses gérées par l’environnement et celles gérées par l’entraîneur ne sont pas mutuellement exclusives. Passez reward_funcs pour les récompenses qui se calculent naturellement à partir de la complétion (par exemple, une vérification du format du texte) et laissez l’environnement retourner sa récompense dépendante de l’état via get_reward. Toutes les sources sont additionnées avec un poids de 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`
)

Plusieurs environnements

Pour entraîner sur un mélange de tâches dans une seule exécution (par exemple, une tâche de codage et un jeu), passez un dictionnaire associant les noms d’environnements à des fabriques, plutôt qu’un seul appelable. Chaque déroulement sélectionne son environnement via un champ environment dans le jeu de données, et seuls les outils de cet environnement sont exposés. Cela évite de divulguer des outils non pertinents (l’outil move du jeu à un exemple de codage, et inversement). Chaque environnement possède toujours ses propres données et renvoie le prompt depuis reset(), de sorte que le jeu de données n’a besoin que de la colonne environment pour router entre eux.

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

Les instances d’environnement sont réutilisées d’une étape à l’autre (réinitialisées entre les épisodes), de sorte qu’un __init__ coûteux n’est payé qu’une seule fois plutôt qu’à chaque étape. Le champ environment est consommé par l’entraîneur et n’est pas transmis à reset.

Déroulements multi-tours

À chaque tour, l’intégralité de la conversation est rendue via le modèle de chat et une génération est effectuée à partir de celui-ci. Un modèle de chat ne rend pas toujours une conversation croissante de la même manière (certains suppriment par exemple le raisonnement des tours précédents), de sorte que les jetons de l’invite d’un tour peuvent différer des jetons conservés jusqu’alors. À la fin du déroulement, le travailleur réconcilie les tours en échantillons d’entraînement : un tour dont l’invite commence par les jetons conservés est ajouté au même échantillon, et tout autre tour en démarre un nouveau. Chaque jeton généré est entraîné dans exactement un échantillon, de sorte qu’une bifurcation coûte des jetons de propagation avant mais aucun signal d’entraînement.

Chaque échantillon d'un déroulement reçoit l'avantage de ce déroulement. rollout/fork_frac et rollout/drift_tokens_* indiquent comment les tours ont été réconciliés.

Intégrations d'environnement

Pour entraîner des agents qui s'exécutent dans leur propre harnais, tels que des agents de codage dans des sandbox Harbor, consultez Training on harnesses dans le guide OpenEnv.

Entraînement des modèles de vision et de langage

Les modèles de vision-langage (Qwen3.5, Qwen3.6, Qwen3-VL, …) peuvent être entraînés sur des jeux de données text-only. Passez l’identifiant du modèle comme d’habitude ; rien d’autre ne change.

La tour de vision est figée. Un jeu de données textuel ne génère jamais de jetons d’image, la tour n’est donc jamais sollicitée par le passage avant. Tout ce qui se trouve en dehors du modèle de texte (tour de vision, projecteur multimodal) a requires_grad=False : il ne reçoit ni gradients ni état d’optimiseur, et la synchronisation des poids l’ignore, si bien que le serveur conserve les valeurs chargées depuis le point de contrôle. La tour est tout de même chargée, ce qui lui consomme de la mémoire GPU pour ses poids.

Les images ne sont pas encore prises en charge. Les prompts contenant des images ne sont pas transmis au serveur vLLM ni à la passe avant d'entraînement. L'entraînement multimodal nécessite également le chemin de packing sans padding pour construire les positions M-RoPE 3D à partir de la grille d'image, ce qui n'est pas implémenté ici.

AsyncGRPOTrainer

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

Paramètres

  • model (str ou PreTrainedModel) — Modèle à entraîner. Peut être soit :
    • Une chaîne de caractères, correspondant à l'identifiant du modèle d'un modèle pré-entraîné hébergé dans un dépôt de modèles sur huggingface.co, ou à un chemin vers un dossier contenant les poids du modèle enregistrés à l'aide de save_pretrained, par exemple './my_model_directory/'. Le modèle est chargé avec l'architecture déclarée dans sa configuration : AutoModelForImageTextToText pour un point de contrôle vision-langage (dont la tour vision est chargée mais gelée, voir Training Vision Language Models), AutoModelForCausalLM sinon.
    • Un objet PreTrainedModel. Son implémentation d'attention est basculée sur le backend d'attention arborescente de l'entraîneur pour l'entraînement groupé.

    Le nom du modèle issu de la configuration est utilisé pour identifier le modèle sur le serveur vLLM utilisé pour la génération.

  • reward_funcs (RewardFunc | list[RewardFunc], facultatif) — Fonctions de récompense à utiliser pour le calcul des récompenses. Pour calculer les récompenses, nous appelons toutes les fonctions de récompense avec les prompts et les complétions, puis nous additionnons les récompenses. Peut être omis lorsque la récompense est fournie par l'environnement via environment_factory ((voir ci-dessous). Peut être soit :
    • Une seule fonction de récompense : la fonction reçoit les prompts et les complétions générées, ainsi que toutes les colonnes supplémentaires du jeu de données. Elle doit renvoyer une liste de récompenses. Les fonctions de récompense peuvent être synchrones ou asynchrones et peuvent également renvoyer None lorsque la récompense ne s'applique pas à ces échantillons. Cela est utile pour l'entraînement multi-tâches où différentes fonctions de récompense s'appliquent à différents types d'échantillons. Lorsqu'une fonction de récompense renvoie None pour un échantillon, cette fonction de récompense est exclue du calcul de la récompense pour cet échantillon. Pour plus de détails, voir Utiliser une fonction de récompense personnalisée.
    • Une liste de fonctions de récompense, où chaque élément est une fonction de récompense telle que décrite ci-dessus. Les récompenses de toutes les fonctions sont additionnées.

    Contrairement à GRPOTrainer, les récompenses sont calculées dans un processus enfant généré, de sorte que chaque fonction de récompense (ainsi que tools et environment_factory) doit être sérialisable (picklable) : utilisez une fonction au niveau du module, functools.partial, ou une instance de classe appelable — les lambdas et les fermetures échoueront au démarrage. Les outils sont enregistrés sous leur __name__, ils doivent donc être des fonctions au niveau du module. Le processus enfant s’exécute également avec CUDA_VISIBLE_DEVICES="", de sorte qu’un modèle de récompense basé sur GPU s’exécute sur CPU (lent), et non sur le GPU de l’entraîneur.

  • args (AsyncGRPOConfig, facultatif) — Configuration de ce formateur. Si None, une configuration par défaut est utilisée.
  • train_dataset (Dataset ou IterableDataset, facultatif) — Jeu de données à utiliser pour l'entraînement. Il doit inclure une colonne "prompt". Toutes les colonnes supplémentaires du jeu de données sont ignorées. Les échantillons doivent être au format conversationnel : chaque échantillon contient des messages structurés (par exemple, le rôle et le contenu).

    Peut être omis uniquement lorsqu'un environment_factory est fourni et que l'environnement possède (ou génère procéduralement) les données, en renvoyant le prompt depuis sa méthode reset(). Dans ce cas, max_steps doit être défini pour fixer la durée de l'entraînement.

  • processing_class (PreTrainedTokenizerBase, facultatif) — Classe de traitement utilisée pour traiter les données. Le côté de bourrage doit être défini sur « left ». Si None, la classe de traitement est chargée à partir du nom du modèle avec from_pretrained. Un jeton de bourrage, tokenizer.pad_token, doit être défini. Si la classe de traitement n’a pas défini de jeton de bourrage, tokenizer.eos_token sera utilisé par défaut.
  • callbacks (liste de TrainerCallback, facultatif) — Liste de callbacks pour personnaliser la boucle d'entraînement. Ils seront ajoutés à la liste des callbacks par défaut détaillée ici.

    Si vous souhaitez supprimer l'un des callbacks par défaut utilisés, utilisez la méthode remove_callback.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], facultatif, par défaut (None, None)) — Un tuple contenant l'optimiseur et le planificateur à utiliser. Par défaut, une instance de AdamW est utilisée sur votre modèle ainsi qu'un planificateur défini par get_linear_schedule_with_warmup et contrôlé par args.
  • peft_config (PeftConfig, facultatif) — Configuration PEFT utilisée pour envelopper le modèle. Si None, le modèle n’est pas enveloppé. Lorsque le serveur vLLM a été démarré avec --enable-lora, un adaptateur LoRA y est synchronisé en tant qu’adaptateur plutôt qu’en tant que poids fusionnés ; voir la section LoRA de la documentation d’AsyncGRPO.
  • tools (liste de Callable, facultatif) — Une liste de fonctions d’outils appelables (synchrones ou asynchrones) que le modèle peut invoquer pendant la génération. Chaque outil doit être une fonction Python standard avec des arguments et des valeurs de retour correctement annotés par des types, ainsi qu’une docstring au style Google décrivant son objectif, ses arguments et sa valeur de retour. Pour plus de détails, voir : https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. Le modèle utilise le nom de la fonction, ses annotations de types et sa docstring pour déterminer comment l’appeler. Assurez-vous que le modèle de chat du modèle prend en charge l’utilisation d’outils et qu’il a été affiné pour l’appel d’outils.
  • environment_factory (EnvironmentFactory ou dict[str, EnvironmentFactory], facultatif) — Un appelable qui crée et renvoie une instance d'environnement, ou un dictionnaire associant des noms d'environnements à de tels appelables. La classe d'environnement doit définir des méthodes qui peuvent être invoquées comme outils pendant la génération. Chaque méthode doit respecter les mêmes exigences que les tools décrits ci-dessus. L'environnement doit également implémenter un appelable reset qui peut être utilisé pour réinitialiser l'état entre les générations. La méthode reset doit renvoyer soit None soit une chaîne de caractères : lorsqu'elle renvoie une chaîne, celle-ci est ajoutée au dernier message utilisateur avant la génération. L'environnement peut également définir une méthode get_reward ne prenant aucun argument et renvoyant un float: lorsqu'elle est présente, l'environnement possède la récompense, et get_reward est appelée une fois par déroulement terminé pour l'évaluer à partir de l'état interne de l'environnement. Elle agit comme une source de récompense supplémentaire (avec un poids de 1, enregistrée sous le nom de la classe de l'environnement) aux côtés de reward_funcs, devient alors facultatif.

    Avec un seul objet appelable, chaque exemple utilise le même environnement, avec une instance par déroulement afin que leurs interactions restent isolées. Avec un dictionnaire, chaque exemple doit comporter un champ environment qui sélectionne son environnement par son nom, et seuls les outils de cet environnement sont exposés dans son prompt — ce qui permet à une seule exécution de mélanger des tâches (par exemple, un environnement de codage et un jeu). Cette fonctionnalité est expérimentale et peut être modifiée ou supprimée à tout moment sans préavis.

Trainer pour la méthode Group Relative Policy Optimization (GRPO). Cet algorithme a été initialement proposé dans l’article DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. Ce trainer est la version asynchrone de GRPO, où la génération est déléguée à un serveur vLLM externe qui s’exécute de manière asynchrone en parallèle de l’entraînement, découplant le rollout de la boucle de mise à jour des gradients.

Exemple :

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

Pour personnaliser les prompts échantillonnés, la génération d'un déroulement ou le calcul des avantages, sous-classez AsyncRolloutLoop et définissez-le comme loop_cls de l'entraîneur. TRL construit la boucle dans

processus de déroulement :

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

Paramètres

  • resume_from_checkpoint (str ou bool, facultatif) — Si c'est une str, chemin local d'un point de contrôle enregistré par une instance précédente de Trainer. Si c'est un bool et vaut True, charge le dernier point de contrôle dans args.output_dir enregistré par une instance précédente de Trainer. S'il est présent, l'entraînement reprendra à partir des états du modèle/optimiseur/planificateur chargés ici.
  • trial (optuna.Trial ou dict[str, Any], facultatif) — L’exécution de l’essai ou le dictionnaire d’hyperparamètres pour la recherche d’hyperparamètres.
  • ignore_keys_for_eval (list[str], facultatif) — Une liste de clés dans la sortie de votre modèle (s’il s’agit d’un dictionnaire) qui doivent être ignorées lors de la collecte des prédictions pour l’évaluation pendant l’entraînement.

Retourne

~trainer_utils.TrainOutput

Objet contenant le nombre d'étapes globales, la perte d'entraînement et les métriques.

Point d'entrée principal de l'entraînement.

save_model

< >

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

Enregistrera le modèle, ce qui vous permettra de le recharger à l'aide de from_pretrained().

N'enregistrera que depuis le processus principal.

push_to_hub

< >

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

Paramètres

  • commit_message (str, facultatif, par défaut "End of training") — Message à committer lors de la poussée.
  • blocking (bool, facultatif, par défaut True) — Indique si la fonction doit ne renvoyer que lorsque le git push est terminé.
  • token (str, facultatif, par défaut None) — Jeton avec permission d’écriture pour écraser les arguments originaux du Trainer.
  • revision (str, facultatif) — La révision git à partir de laquelle effectuer le commit. Par défaut, il s'agit de la tête de la branche « main ».
  • private (bool, facultatif) — Indique s'il faut rendre le dépôt privé lors de sa création. La valeur par défaut est args.hub_private_repo. N'a aucun effet si le dépôt existe déjà.
  • kwargs (dict[str, Any], facultatif) — Arguments supplémentaires passés à ~Trainer.create_model_card.

Téléchargez self.model et self.processing_class sur le hub de modèles 🤗 dans le dépôt self.args.hub_model_id.

AsyncGRPOConfig

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

Paramètres qui contrôlent le modèle

  • model_init_kwargs (dict[str, Any] ou str, facultatif) — Arguments par mot-clé pour from_pretrained, utilisés lors de l’instanciation du modèle à partir d’un chemin. La valeur de revision est également utilisée lors du chargement de la classe de traitement.
  • dtype (str, facultatif, par défaut "float32") — Type de données pour charger le modèle, l'un des "auto", "bfloat16", "float16" ou "float32". La valeur par défaut est "float32" car le décalage entraînement-inférence auquel ce formateur est confronté (Defeating the Training-Inference Mismatch via FP16) ) est sensible à la précision du formateur lui-même. Fermer cet écart de bout en bout nécessite également de servir le serveur vLLM avec le mêmevllm serve --dtype); un décalage est signalé par un avertissement au démarrage de l'entraînement. Un dtype dans model_init_kwargs a la priorité.

    Cela ne définit que le dtype dans lequel les poids sont chargés. Sous FSDP avec précision mixte (bf16=True est la valeur par défaut), accelerate convertit chaque paramètre entraînable en fp32 avant le sharding, de sorte que les poids maîtres et l'état de l'optimiseur sont en fp32, indépendamment de la valeur de dtype, tandis que les passes avant et arrière s'exécutent en bf16 ou fp16. Les points de contrôle sont ensuite écrits dans ce dtype de précision mixte, et non en fp32. Sans FSDP, aucune conversion ascendante n'est effectuée : dtype="bfloat16" avec bf16=True conserve les poids et les états de l'optimiseur en bf16, ce qui correspond à un entraînement en bf16 pur.

  • trust_remote_code (bool, facultatif, valeur par défaut False) — Indique s'il faut autoriser le chargement de modèles et de tokenizers qui incluent du code Python personnalisé depuis le Hub. Transmis à from_pretrained et from_pretrained.
  • router_aux_loss_coef (float, facultatif) — Coefficient de la perte auxiliaire d’équilibrage de charge pour les modèles Mixture-of-Experts (MoE), ajoutée à la perte d’entraînement avec ce poids. Si non défini, la valeur déclarée par la configuration du modèle est utilisée. Définissez-le à 0.0 pour le désactiver. Échoue s’il est utilisé avec un modèle non-MoE.

Paramètres qui contrôlent la génération

  • num_generations (int, facultatif, par défaut 8) — Nombre de générations à échantillonner par invite.
  • max_completion_length (int, facultatif, par défaut 2048) — Nombre maximal de jetons générés par requête vLLM, donc par tour dans un déroulement multi-tours.
  • temperature (float, facultatif, par défaut 1.0) — Température pour l'échantillonnage. Plus la température est élevée, plus les complétions sont aléatoires.
  • top_p (float, facultatif, valeur par défaut 1.0) — Flottant qui contrôle la probabilité cumulée des jetons de tête à prendre en compte. Doit être dans (0, 1]. Définir à 1.0 pour prendre en compte tous les jetons. En dessous de 1.0, top_k doit également être défini, et le serveur vLLM (>= 0.28) démarré avec --return-sampling-mask --enable-scale-out : l’entraîneur renormalise ses log-probabilités sur l’ensemble des candidats à partir duquel chaque jeton a été échantillonné, comme le fait le serveur. Une version plus ancienne de vLLM conserve tout le vocabulaire.
  • top_k (int, facultatif, valeur par défaut 0) — Nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. Si la valeur est 0, le filtrage top-k est désactivé et tous les jetons sont pris en compte. Toute autre valeur nécessite les drapeaux du serveur décrits sous top_p.
  • min_p (float, facultatif) — Probabilité minimale du 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. Au-dessus de 0.0, top_k doit également être défini, avec les drapeaux du serveur décrits sous top_p.
  • chat_template_kwargs (dict[str, Any], facultatif) — Arguments supplémentaires à passer à la fonction apply_chat_template lors de la génération des complétions.
  • max_tool_calling_iterations (int, facultatif) — Nombre maximal de tours d’appel d’outils lors de l’entraînement d’un agent. Si None, il n’y a pas de limite et la génération s’arrête lorsque le modèle génère un tour de réponse sans appels d’outils.

Paramètres qui contrôlent le serveur vLLM

  • vllm_server_base_url (str, facultatif, par défaut "http --//localhost:8000") : URL de base du serveur vLLM utilisé pour la génération (par exemple, "http://localhost:8000").
  • vllm_server_timeout (float, facultatif, valeur par défaut 1800.0) — Délai d’attente en secondes pour les appels au serveur vLLM : en attente de sa disponibilité au démarrage, pour chaque requête de génération et pour chaque appel de synchronisation des poids. L’attente du serveur et les appels de synchronisation des poids lèvent une exception en cas d’expiration ; une requête de génération expirée est réessayée.

Paramètres qui contrôlent l'entraînement

  • epsilon (float, facultatif, valeur par défaut 0.2) — Valeur pour le clipping.
  • epsilon_high (float, facultatif) — Valeur epsilon supérieure pour le rognage. Si elle n'est pas spécifiée, elle prend par défaut la même valeur que la borne inférieure spécifiée dans l'argument epsilon. L'article DAPO recommande 0.28.
  • score_centering (bool, facultatif, par défaut True) — Indique s'il faut entraîner avec le centrage des scores (article) plutôt que l'objectif tronqué : le score pondéré par l'importance de chaque jeton échantillonné, moins son espérance sous l'échantillonneur vLLM, afin qu'un avantage constant ne tire pas la politique vers l'échantillonneur. L'espérance est prise sur les num_sampler_logprobs jetons les plus probables à chaque position, dont les log-probabilités sont rapportées par l'échantillonneur.
  • vllm_importance_sampling_clip_min (float, facultatif, valeur par défaut 0.5) — Borne inférieure C_min du ratio d’importance entre la politique et le sampleur vLLM. Les jetons dont le ratio se situe en dehors de l’intervalle [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] sont exclus de la perte (échantillonnage d’importance masqué).
  • vllm_importance_sampling_clip_max (float, facultatif, valeur par défaut 5.0) — Borne supérieure C_max du ratio d'importance.
  • num_sampler_logprobs (int, facultatif, valeur par défaut 8) — Nombre de log-probabilités supérieures demandées au sampler vLLM pour chaque jeton généré, utilisé par le centrage des scores. Plus il y en a, plus la masse de probabilité du sampler est couverte, mais plus la sérialisation est coûteuse ; le paramètre --max-logprobs du serveur en fixe la limite.
  • token_budget (int, facultatif) — Nombre maximal de jetons transmis dans une seule ligne (un avant d’un rang DP). Un TokenBudgetBatcher forme des micro-lots équilibrés en coût d’attention dont les lignes restent chacune dans cette limite, bornant ainsi la mémoire de pointe indépendamment du nombre d’échantillons (le nombre d’échantillons par ligne devient dynamique). La limite borne les jetons uniques plutôt que les jetons bruts, de sorte que les jetons partagés par plusieurs échantillons ne comptent qu’une fois, et elle borne également les termes de perte de la ligne. Si None (par défaut), il est fixé à la valeur max_model_len du serveur vLLM (interrogée au démarrage de l’entraînement) — la limite de longueur du prompt + complétion — de sorte qu’aucun échantillon de déroulement ne puisse jamais dépasser la limite. Un échantillon plus long que token_budget ne tient dans aucune ligne et est abandonné avec un avertissement.

Paramètres qui contrôlent le pipeline de déploiement asynchrone

  • max_concurrent_rollouts (int, facultatif, valeur par défaut 512) — Nombre maximal de rollouts exécutés simultanément. Chacun d’entre eux détient un environnement, peut exécuter des appels d’outils synchrones et maintient une connexion au serveur vLLM ; réglez donc cette valeur en fonction de ce que ces ressources peuvent supporter. En dessous de ce seuil, le nombre de rollouts en cours suit l’utilisation du cache KV du serveur vLLM et max_staleness.
  • max_staleness (int, facultatif, valeur par défaut 4) — Nombre maximal d'étapes de mise à jour des poids qu'un échantillon de rollout peut retarder par rapport à la version actuelle du modèle avant d'être écarté. La génération est limitée en conséquence : un nouveau groupe de rollouts ne démarre que si les tokens en file d'attente et en cours de traitement tiennent dans ce que le formateur consomme en max(max_staleness, 1) étapes.
  • weight_sync_steps (int, facultatif, valeur par défaut 1) — Nombre d'étapes d'entraînement entre les synchronisations de poids vers le serveur vLLM.
  • rollout_worker_timeout (float, facultatif, valeur par défaut 300.0) — Nombre de secondes écoulées depuis le dernier battement de cœur du worker de rollout après lesquelles le formateur le considère comme bloqué et interrompt le processus.

Paramètres qui contrôlent la journalisation

  • log_completions (bool, facultatif, par défaut False) — Indique s'il faut consigner un échantillon de paires (prompt, completion) toutes les logging_steps étapes.
  • num_completions_to_print (int, facultatif) — Nombre de complétions à afficher avec rich. Si None, toutes les complétions sont journalisées.

Classe de configuration pour le AsyncGRPOTrainer.

Cette classe ne contient que les paramètres spécifiques à l’entraînement asynchrone GRPO. Pour la liste complète des arguments d’entraînement, veuillez consulter la documentation de TrainingArguments. Notez que les valeurs par défaut de cette classe peuvent différer de celles de TrainingArguments.

Ces paramètres ont des valeurs par défaut différentes de TrainingArguments :

  • logging_steps : la valeur par défaut est 1 au lieu de 500.
  • gradient_checkpointing : la valeur par défaut est True au lieu de False.
  • bf16 : passe à True par défaut si fp16 n’est pas défini, au lieu de False.
  • learning_rate : la valeur par défaut est 1e-6 au lieu de 5e-5.
  • lr_scheduler_type : la valeur par défaut est constant au lieu de linear (voir ci-dessous).
  • ignore_data_skip : la valeur par défaut est True au lieu de False ; la boucle de saut et de rejouage du Trainer de base ne s’applique pas à la file d’attente de déroulement asynchrone.
  • remove_unused_columns : la valeur par défaut est False au lieu de True, et doit rester False : chaque colonne du jeu de données est transmise aux fonctions de récompense.

Durée d'entraînement et taux d'apprentissage en mode de réconciliation par messages : Une conversation multi-tours peut se diviser en un nombre variable de lignes d'entraînement (une réécriture de la conversation démarre une nouvelle ligne), de sorte que le nombre d'échantillons, et donc le nombre d'étapes d'optimiseur, par époque n'est pas connu à l'avance. En conséquence :

  • num_train_epochs limite l’entraînement par des passages complets sur le jeu de données prompt, comptés en nombre de prompts distincts réellement utilisés pour l’entraînement. Cela est indépendant du nombre de lignes produites par les fourchettes, de sorte que demander N époques entraîne toujours N passages sur les données. Lorsque max_steps n’est pas défini, c’est la condition d’arrêt et max_steps n’est qu’une limite de sécurité.
  • max_steps, s'il est défini explicitement (> 0), devient la condition d'arrêt (limitée par les étapes de l'optimiseur plutôt que par les époques) et désactive l'arrêt basé sur les époques.
  • lr_scheduler_type est défini par défaut sur constant car l’horizon de décroissance est mesuré en pas d’optimiseur, ce qui ne peut pas être connu à l’avance lorsque le nombre de pas dépend du taux de fourche. Pour un taux d’apprentissage décroissant, définissez un planning de décroissance ainsi qu’un max_steps explicite.

AsyncRolloutLoop

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

Génère et évalue les déroulements pour AsyncGRPOTrainer, dans un processus de déroulement généré.

L’implémentation par défaut met en œuvre GRPO. Pour personnaliser une exécution, créez une sous-classe, ne surchargez que les méthodes qui changent et définissez la sous-classe comme loop_cls de l’entraîneur. Chaque prompt passe, dans l’ordre, par :

  • filter_prompt() : s'il faut générer pour le prompt ou non.
  • generate_one() : un déroulement complet, qui appelle generate_one_turn() pour chaque requête d’échantillonnage.
  • Le groupe de num_generations rollouts est noté : ses récompenses sont la somme des reward_funcs du formateur, des environnements qui définissent get_reward et de Rollout.reward. Ensuite, compute_advantages() est exécuté une fois par groupe.

setup() et close() créent et libèrent des ressources sur la boucle d’événements de la boucle, comme un client HTTP. Un hook peut lire self.config (une sous-classe de AsyncGRPOConfig peut transporter ses propres champs) et self.tokenizer. Étant donné que la boucle est construite dans un processus généré, la sous-classe doit être importable (définie au niveau du module).

filter_prompt

< >

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

Paramètres

  • row_index (int) — Index de la ligne dans le jeu de données d'entraînement.
  • row (dict[str, Any]) — La ligne du jeu de données.
  • epoch (int) — Nombre de passages complets sur le jeu de données avant celui-ci.

Retourne

bool

True pour générer num_generations déroulements pour le prompt, False pour les ignorer.

Indique s'il faut générer pour un prompt. Un prompt rejeté est ignoré pour cette époque et compte comme consommé, comme un groupe abandonné. Par défaut, tous les prompts sont acceptés. Rejeter tous les prompts d'une époque complète provoque une erreur, car aucun lot ne peut atteindre le formateur après cela.

generate_one

< >

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

Paramètres

  • prompt (list[dict[str, Any]]) — Messages de l’invite.
  • tools (list[Callable]) — Outils disponibles pour ce déroulement : les tools de l’entraîneur, ainsi que les méthodes publiques de l’environnement lors de l’utilisation de environment_factory.
  • group_id (int, facultatif, par défaut 0) — Identifiant du groupe auquel appartient le déroulement.

Retourne

Rollout

Le déroulement terminé.

Générer un seul déroulement pour un prompt.

Par défaut, une boucle d’outils multi-tours est utilisée : à chaque tour, la conversation entière est rendue avec le modèle de chat, une réponse est échantillonnée avec generate_one_turn() et les appels d’outils qu’elle contient sont exécutés, jusqu’à ce que le modèle cesse d’appeler des outils ou que max_tool_calling_iterations soit atteint. Surchargez-la pour générer différemment, par exemple avec un framework d’agent. Renvoyez chaque demande d’échantillonnage dans Rollout.turns, car les séquences d’entraînement sont construites à partir de celles-ci, et définissez Rollout.reward pour évaluer le déroulement ici.

generate_one_turn

< >

( prompt_ids: list[int] ) → TurnRecord

Paramètres

  • prompt_ids (list[int]) — Identifiants des jetons du prompt complet.

Retourne

TurnRecord

Le prompt et les jetons échantillonnés avec leurs log-probabilités. Avec top_k ou top_p, il contient également l’ensemble des candidats de chaque jeton échantillonné, et avec num_sampler_logprobs, les log-probabilités les plus élevées de l’échantillonneur.

Échantillonnez une réponse du serveur vLLM, avec les paramètres d’échantillonnage de la configuration (temperature, top_p, top_k, min_p, repetition_penalty et max_completion_length).

compute_advantages

< >

( group: RolloutGroup ) → np.ndarray

Paramètres

  • group (RolloutGroup) — Les num_generations rollouts d'un prompt, avec leurs récompenses totales dans group.rewards.

Retourne

np.ndarray

Un avantage par déroulement, dans l'ordre de group.rewards.

Calcule un avantage par déroulement d'un groupe. Par défaut, chaque récompense est standardisée au sein du groupe ; un déroulement avec une récompense NaN reçoit un avantage 0 et est exclu de la moyenne et de l'écart-type.

Il s'exécute pour chaque groupe. Un groupe dont les récompenses notées sont toutes égales est alors écarté, quelles que soient les valeurs d'avantage que cela renvoie.

setup

< >

( )

Crée les ressources dont les autres hooks ont besoin, telles qu’un client HTTP. S’exécute sur la boucle d’événements de la boucle avant le premier prompt. Ne fait rien par défaut.

fermer

< >

( )

Libère ce que setup() a créé. S'exécute lorsque les boucles s'arrêtent, y compris en cas d'échec. Ne fait rien par défaut.

Rollout

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

Paramètres

  • completion (list[dict[str, Any]]) — Messages generated after the prompt, in conversational format. Passed to the reward functions as completions.
  • completion_ids (list[int]) — Identifiants des jetons de la complétion générée. Transmis aux fonctions de récompense en tant que completion_ids.
  • turns (list[TurnRecord]) — Les requêtes d’échantillonnage ayant produit le déroulement, dans l’ordre. Les séquences d’entraînement sont construites à partir d’elles : les jetons échantillonnés font l’objet de l’entraînement, le reste de chaque invite sert de contexte.
  • tool_call_count (int, facultatif, valeur par défaut 0) — Nombre d'appels d'outils effectués pendant le déroulement.
  • tool_failure_count (int, facultatif, valeur par défaut 0) — Nombre d’appels d’outils qui ont échoué.
  • reward (float, facultatif) — Récompense calculée pendant la génération, par exemple par un correcteur externe. Elle est ajoutée aux récompenses des fonctions de récompense et des environnements. Si None, ce déroulement ne reçoit aucune récompense de cette source.
  • rollout_id (str, facultatif) — Identifie le rollout dans ses lignes d’entraînement, pour le débogage. Par défaut, une nouvelle identifiante hexadécimale aléatoire est utilisée.

Un déroulement terminé, tel que renvoyé par generate_one().

TurnRecord

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

Paramètres

  • prompt_ids (list[int]) — Identifiants des jetons du prompt complet envoyé pour ce tour, incluant tous les tours précédents de la conversation.
  • output_ids (list[int]) — Identifiants des jetons générés par l'échantillonneur.
  • output_log_probs (list[float], facultatif, par défaut []) — Probabilités logiques du sampler pour chaque jeton de output_ids. Obligatoire si l’un d’entre eux est entraîné.
  • output_mask (list[int], facultatif) — Une valeur par jeton dans output_ids : 1 pour entraîner sur le jeton, 0 pour le conserver uniquement comme contexte. Si None, chaque jeton de sortie est utilisé pour l’entraînement.
  • output_sampling_mask (list[list[int]], facultatif) — Une liste par jeton dans output_ids : les identifiants de jetons que le module d’échantillonnage pouvait tirer sous contrainte de top_k / top_p. Si None, le vocabulaire complet.
  • output_sampler_logprobs (list[dict[int, float]], facultatif) — Un dictionnaire par jeton dans output_ids : les log-probabilités des jetons les plus probables du sampler, indexées par identifiant de jeton. Utilisé par le centrage des scores (num_sampler_logprobs).

Une demande d'échantillonnage : le prompt envoyé à l'échantillonneur et les jetons qu'il a générés.

RolloutGroup

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

Paramètres

  • prompts (list[list[dict[str, Any]]]) — Prompt de chaque rollout.
  • reward_kwargs (dict[str, list[Any]]) — Les autres colonnes de la ligne du jeu de données du prompt, transmises aux fonctions de récompense en tant qu’arguments nommés.
  • completions (list[list[dict[str, Any]]]) — Messages de complétion de chaque déroulement.
  • completions_ids (list[list[int]]) — Identifiants des jetons de complétion de chaque déroulement.
  • completions_sequences (list[list[TrainingSequence]]) — Séquences d’entraînement construites à partir de chaque rollout. Un rollout dont l’historique re-tokenisé a changé entre les tours en produit plus d’une.
  • tool_call_counts (list[int]) — Nombre d'appels d'outils dans chaque déroulement.
  • tool_failure_counts (list[int]) — Nombre d'appels d'outils échoués dans chaque déroulement.
  • model_version (int) — Version du modèle au moment du début du premier déroulement du groupe.
  • group_id (int) — Identifiant du groupe, compté à partir de 0 dans le processus de déroulement.
  • row_index (int) — Index de la ligne du prompt dans le jeu de données d'entraînement.
  • env_rewards (list[tuple[type, float] or None]) — Pour un rollout dont l’environnement définit get_reward, la classe de l’environnement et sa récompense ; sinon None.
  • rollout_rewards (list[float or None]) — Rollout.reward de chaque rollout.
  • queued_at (float, facultatif, par défaut 0.0) — time.monotonic() au moment où le groupe a été mis en file d’attente pour l’évaluation.
  • rewards (np.ndarray, facultatif) — Récompense totale de chaque rollout, additionnée sur toutes les sources de récompense, NaN si aucune source ne l’a évaluée. Définie avant l’appel de compute_advantages().

Les num_generations déroulements d'un prompt, notés ensemble. Chaque liste contient une entrée par déroulement.

Update on GitHub