TRL documentation
Entraîneur GRPO asynchrone
Entraîneur GRPO asynchrone
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 4096Puis 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 nopromptcolumn, andreset()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 > 1ousp_size > 1dansparallelism_config). use_liger_kernel=Truen'est pas pris en charge.- Les adaptateurs PEFT ciblant
lm_headne 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 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 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_stepsmicro-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 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 :
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 :
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 d'un jeton échantillonné ne s'annule pas en moyenne sous l'échantillonneur , ainsi chaque mise à jour tire également la politique vers l'échantillonneur. Le Score Centering soustrait cette espérance à chaque position :
où à l'intérieur de et à 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é :
où est epsilon et 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 journalise0.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 viaget_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_trainedexclut 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_stdde 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 demax_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 avecfrac_zero_std_groupsetreward.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 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 lesnum_sampler_logprobsjetons les plus probables de l'échantillonneur. Journalisé uniquement lorsquescore_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 parrouter_aux_loss_coefet ajoutée à la perte. Journalisée uniquement lorsque le modèle est un modèle MoE et querouter_aux_loss_coefest 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 : . Avecscore_centering=Truela perte n'est pas tronquée, donc lesclip_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 : .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 : .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 : .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 : .
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_meanettools/latency_s, est moyennée sur l’ensemble des déroulements, échantillons ou appels de la fenêtre. Un taux commerollout/generated_tokens_per_sest le nombre total de jetons divisé par le nombre total de secondes. - Sinon, un nom dont la dernière partie contient le mot
countest additionné :sample/dropped_stale_countest 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
maxoumin, commesample/staleness_maxoucompletions/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 de1.0, certains rollouts ont été dupliqués ; en dessous de1.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 pour0). 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 demax_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_runningde vLLM, additionné sur l’ensemble des moteurs). L’écart par rapport àrollout/concurrencycorrespond à 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_waitingde vLLM, additionné sur les moteurs).rollout/vllm_preemption_count: Le nombre de requêtes préemptées par le serveur (num_preemptions_totalde 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_iterationsalors 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éthodereset()de l’environnement avant le début d’un rollout. Journalisé uniquement lorsqueenvironment_factoryest fourni.env/reward_s: le temps passé dansget_reward()de l’environnement après la fin d’un rollout. Journalisé uniquement si l’environnement définitget_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étriquessampling/importance_sampling_ratio/*etsampling/sampling_logp_difference/*combinent cette obsolescence avec l’écart entre l’entraînement et l’inférence : un ratio s’écartant de1.0ou une différence de log-probabilité s’écartant de0.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 demax_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 detoken_budgetutilisé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.0des gradients ;1.0correspond à 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.0lorsque 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 detoken_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 enperf/weight_sync_pause_s(attente de la pause de vLLM),perf/weight_sync_barrier_s(attente des autres processus) etperf/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 4096VLLM_SERVER_DEV_MODE=1et--weight-transfer-configexposent les points de passage par lesquels l’entraîneur transmet ses poids.--logprobs-mode processed_logprobspermet 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 8conserve 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-lenest 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 plusmax_completion_lengthde votre configuration. Avec les outils, chaque tour ajoute jusqu’àmax_completion_lengthjetons 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 plusmax_completion_lengthest plus longue que--max-model-len, le serveur rejette la requête et l’exécution s’arrête avec l’erreur du serveur. Avectop_koutop_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 letoken_budgetpar 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=8divise par deux le débit de génération. Démarrez le serveur avec--api-server-count 8sur 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_ssupé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 faiblerollout/vllm_kv_cache_usage_fracet un élevéperf/rollout_wait_s: le plafond. Augmentezmax_concurrent_rolloutssi 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 demax_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 ; examinezrollout/generated_tokens_per_s,rollout/concurrencyetrollout/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 etsample/staleness_meanse situe près de sa limite. - les deux élevés : la limite
max_stalenesselle-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. Augmentezmax_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étrique | question |
|---|---|
frac_zero_std_groups | quelle proportion de groupes ne porte aucun signal |
reward_zero_std_groups | où 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_frac | si 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_groups | reward_zero_std_groups | reward | diagnostic | que faire |
|---|---|---|---|---|
| low | any (bruité sur quelques groupes) | any | sain : la plupart des groupes produisent un gradient | rien |
| escalade | vers le haut de la plage | escalade | saturation 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éralement | arrêter l'exécution, ou passer à des prompts plus difficiles |
| élevé | vers le bas de la plage | faible et plat | bloqué en bas : les prompts sont trop difficiles, ou la fonction de récompense n'accorde jamais de crédit | Vé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 |
| escalade | en chute | en chute | regression : les groupes qui passaient auparavant échouent désormais ensemble | vérifiez completions/duplicate_frac et entropy pour détecter un effondrement |
| élevé | au milieu | any | un 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 partiel | lire 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_frac | diagnostic |
|---|---|
| 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 hasard | sain : les déroulements d'un groupe sont échantillonnés de manière indépendante |
saut vers (num_generations - 1) / num_generations | l'é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 baisse | collapse : 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 rolloutQuelques 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_rolloutindique 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-outfrom 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 6VLLM_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 : avecsave_strategy="no", une exécution de plusieurs heures se termine sans laisser aucune trace.output_dirdoit é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.
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éeground_truth, la fonction sera appelée avecground_truthen tant qu'argument par mot-clé.
La façon la plus simple de respecter cette exigence est d'utiliser
**kwargsdans la signature de la fonction.Le jeu de données est au format conversationnel, donc
promptsetcompletionssont des listes de dictionnaires de messages.
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.partialou une instance de classe appelables. Les lambdas et les fermetures (closures) lèvent uneTypeErrorlors 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 scoreurAutoModelForSequenceClassification) se charge sans erreur mais bascule silencieusement sur le CPU. Gardez les fonctions de récompense légères (vérificateurs commeaccuracy_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éthode | Appelé | Par défaut |
|---|---|---|
filter_prompt(row_index, row, epoch) | une fois par invite, avant la génération | accepte chaque invite |
generate_one(prompt, tools, group_id) | une fois par déroulement | la boucle d'outils multi-tours |
generate_one_turn(prompt_ids) | une fois par demande d'échantillonnage | une 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.rewards | récompense standardisée au sein du groupe |
setup(), close() | lorsque les boucles commencent et s'arrêtent | rien |
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 = CurriculumRolloutLoopLes 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
toolspour 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
resetet d’une méthode optionnelleget_rewardqui lui permet de gérer la récompense. Utilisezenvironment_factorylorsque 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 soitNone, 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 unfloat: 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(), lesGmembres 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 quereset()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
< source >( 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 (
strou 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.
- 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
- 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 viaenvironment_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
Nonelorsque 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 renvoieNonepour 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
toolsetenvironment_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 avecCUDA_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. - 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
- 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_factoryest fourni et que l'environnement possède (ou génère procéduralement) les données, en renvoyant le prompt depuis sa méthodereset(). Dans ce cas,max_stepsdoit ê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_tokensera 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 deAdamWest utilisée sur votre modèle ainsi qu'un planificateur défini par get_linear_schedule_with_warmup et contrôlé parargs. - peft_config (
PeftConfig, facultatif) — Configuration PEFT utilisée pour envelopper le modèle. SiNone, 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 (
EnvironmentFactoryoudict[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 lestoolsdécrits ci-dessus. L'environnement doit également implémenter un appelableresetqui peut être utilisé pour réinitialiser l'état entre les générations. La méthoderesetdoit renvoyer soitNonesoit 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éthodeget_rewardne prenant aucun argument et renvoyant unfloat: lorsqu'elle est présente, l'environnement possède la récompense, etget_rewardest 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 dereward_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
environmentqui 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 = CurriculumRolloutLooptrain
< source >( 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 (
stroubool, facultatif) — Si c'est unestr, chemin local d'un point de contrôle enregistré par une instance précédente deTrainer. Si c'est unboolet vautTrue, charge le dernier point de contrôle dans args.output_dir enregistré par une instance précédente deTrainer. S'il est présent, l'entraînement reprendra à partir des états du modèle/optimiseur/planificateur chargés ici. - trial (
optuna.Trialoudict[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.
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
< source >( 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éfautTrue) — Indique si la fonction doit ne renvoyer que lorsque legit pushest terminé. - token (
str, facultatif, par défautNone) — 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 estargs.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
< source >( 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]oustr, facultatif) — Arguments par mot-clé pour from_pretrained, utilisés lors de l’instanciation du modèle à partir d’un chemin. La valeur derevisionest é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. Undtypedansmodel_init_kwargsa la priorité.Cela ne définit que le dtype dans lequel les poids sont chargés. Sous FSDP avec précision mixte (
bf16=Trueest 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 dedtype, 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"avecbf16=Trueconserve 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éfautFalse) — 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.0pour 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éfaut8) — Nombre de générations à échantillonner par invite. - max_completion_length (
int, facultatif, par défaut2048) — 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éfaut1.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éfaut1.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 de1.0,top_kdoit é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éfaut0) — Nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. Si la valeur est0, 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 soustop_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 de0.0,top_kdoit également être défini, avec les drapeaux du serveur décrits soustop_p. - chat_template_kwargs (
dict[str, Any], facultatif) — Arguments supplémentaires à passer à la fonctionapply_chat_templatelors 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. SiNone, 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éfaut1800.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éfaut0.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'argumentepsilon. L'article DAPO recommande0.28. - score_centering (
bool, facultatif, par défautTrue) — 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 lesnum_sampler_logprobsjetons 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éfaut0.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éfaut5.0) — Borne supérieure C_max du ratio d'importance. - num_sampler_logprobs (
int, facultatif, valeur par défaut8) — 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-logprobsdu serveur en fixe la limite. - token_budget (
int, facultatif) — Nombre maximal de jetons transmis dans une seule ligne (un avant d’un rang DP). UnTokenBudgetBatcherforme 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. SiNone(par défaut), il est fixé à la valeurmax_model_lendu 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 quetoken_budgetne 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éfaut512) — 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 etmax_staleness. - max_staleness (
int, facultatif, valeur par défaut4) — 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 enmax(max_staleness, 1)étapes. - weight_sync_steps (
int, facultatif, valeur par défaut1) — Nombre d'étapes d'entraînement entre les synchronisations de poids vers le serveur vLLM. - rollout_worker_timeout (
float, facultatif, valeur par défaut300.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éfautFalse) — Indique s'il faut consigner un échantillon de paires (prompt, completion) toutes leslogging_stepsétapes. - num_completions_to_print (
int, facultatif) — Nombre de complétions à afficher avecrich. SiNone, 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 est1au lieu de500.gradient_checkpointing: la valeur par défaut estTrueau lieu deFalse.bf16: passe àTruepar défaut sifp16n’est pas défini, au lieu deFalse.learning_rate: la valeur par défaut est1e-6au lieu de5e-5.lr_scheduler_type: la valeur par défaut estconstantau lieu delinear(voir ci-dessous).ignore_data_skip: la valeur par défaut estTrueau lieu deFalse; 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 estFalseau lieu deTrue, et doit resterFalse: 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_epochslimite 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. Lorsquemax_stepsn’est pas défini, c’est la condition d’arrêt etmax_stepsn’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_typeest défini par défaut surconstantcar 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’unmax_stepsexplicite.
AsyncRolloutLoop
classe trl.trainer.async_grpo_trainer.AsyncRolloutLoop
< source >( 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_generationsrollouts est noté : ses récompenses sont la somme desreward_funcsdu formateur, des environnements qui définissentget_rewardet 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
< source >( 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
< source >( 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 : lestoolsde l’entraîneur, ainsi que les méthodes publiques de l’environnement lors de l’utilisation deenvironment_factory. - group_id (
int, facultatif, par défaut0) — Identifiant du groupe auquel appartient le déroulement.
Retourne
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
< source >( prompt_ids: list[int] ) → TurnRecord
Paramètres
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
< source >( group: RolloutGroup ) → np.ndarray
Paramètres
- group (RolloutGroup) —
Les
num_generationsrollouts d'un prompt, avec leurs récompenses totales dansgroup.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.
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.
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
< source >( 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 ascompletions. - completion_ids (
list[int]) — Identifiants des jetons de la complétion générée. Transmis aux fonctions de récompense en tant quecompletion_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éfaut0) — Nombre d'appels d'outils effectués pendant le déroulement. - tool_failure_count (
int, facultatif, valeur par défaut0) — 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. SiNone, 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
< source >( 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 deoutput_ids. Obligatoire si l’un d’entre eux est entraîné. - output_mask (
list[int], facultatif) — Une valeur par jeton dansoutput_ids:1pour entraîner sur le jeton,0pour le conserver uniquement comme contexte. SiNone, chaque jeton de sortie est utilisé pour l’entraînement. - output_sampling_mask (
list[list[int]], facultatif) — Une liste par jeton dansoutput_ids: les identifiants de jetons que le module d’échantillonnage pouvait tirer sous contrainte detop_k/top_p. SiNone, le vocabulaire complet. - output_sampler_logprobs (
list[dict[int, float]], facultatif) — Un dictionnaire par jeton dansoutput_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
< source >( 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 de0dans 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éfinitget_reward, la classe de l’environnement et sa récompense ; sinonNone. - rollout_rewards (
list[float or None]) — Rollout.rewardde chaque rollout. - queued_at (
float, facultatif, par défaut0.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.