TRL documentation

GRPO Trainer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

GRPO Trainer

model badge

Resumen

TRL admite el GRPO Trainer para entrenar modelos de lenguaje, tal como se describe en el artículo DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models de Zhihong Shao, Peiyi Wang, Qihao Zhu, Runxin Xu, Junxiao Song, Mingchuan Zhang, Y. K. Li, Y. Wu, Daya Guo.

El resumen del artículo es el siguiente:

El razonamiento matemático plantea un desafío significativo para los modelos de lenguaje debido a su naturaleza compleja y estructurada. En este artículo, presentamos DeepSeekMath 7B, que continúa el pre-entrenamiento de DeepSeek-Coder-Base-v1.5 7B con 120B de tokens relacionados con matemáticas obtenidos de Common Crawl, junto con datos de lenguaje natural y código. DeepSeekMath 7B ha logrado una puntuación impresionante del 51,7% en el benchmark de nivel competitivo MATH, sin depender de kits de herramientas externos ni técnicas de votación, acercándose al nivel de rendimiento de Gemini-Ultra y GPT-4. La autoconsistencia sobre 64 muestras de DeepSeekMath 7B alcanza el 60,9% en MATH. La capacidad de razonamiento matemático de DeepSeekMath se atribuye a dos factores clave: en primer lugar, aprovechamos el gran potencial de los datos web disponibles públicamente mediante un pipeline de selección de datos meticulosamente diseñado. En segundo lugar, introducimos Group Relative Policy Optimization (GRPO), una variante de Proximal Policy Optimization (PPO), que mejora las capacidades de razonamiento matemático mientras optimiza simultáneamente el uso de memoria de PPO.

Este método de post-entrenamiento fue aportado por Quentin Gallouédec.

Inicio rápido

Este ejemplo demuestra cómo entrenar un modelo utilizando el método GRPO. Entrenamos un modelo Qwen2.5 0.5B Instruct con los prompts del conjunto de datos DeepMath-103K. Puede ver los datos del conjunto de datos aquí:

A continuación se muestra el script para entrenar el modelo. accuracy_reward requiere math-verify, que puede instalar con pip install trl[math_verify].

# train_grpo.py
from datasets import load_dataset
from trl import GRPOTrainer
from trl.rewards import accuracy_reward

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

trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)
trainer.train()

Ejecute el script usando el siguiente comando:

torchrun --nproc_per_node 8 train_grpo.py

Distribuido en 8 GPUs, el entrenamiento tarda aproximadamente 1 día.

GRPO curves

Nota: Las curvas de recompensa anteriores se generaron con Qwen/Qwen2-0.5B-Instruct. Los resultados con Qwen/Qwen2.5-0.5B-Instruct serán cualitativamente similares.

Mirando más a fondo el método GRPO

GRPO es un algoritmo de aprendizaje en línea, lo que significa que mejora de forma iterativa utilizando los datos generados por el propio modelo entrenado durante el entrenamiento. La intuición detrás del objetivo de GRPO es maximizar la ventaja de las completaciones generadas, asegurando al mismo tiempo que el modelo se mantenga cerca de la política de referencia. Para entender cómo funciona GRPO, se puede desglosar en cuatro pasos principales: generar completaciones, calcular la ventaja, estimar la divergencia de KL y calcular la pérdida.

GRPO visual

Generar completiones

En cada paso de entrenamiento, muestreamos un lote de prompts y generamos un conjunto de G G completaciones para cada prompt (denotado como oi o_i ).

Cálculo de la ventaja

Para cada una de las G G secuencias, calculamos la recompensa utilizando un modelo de recompensa o una función de recompensa. Para alinearnos con la naturaleza comparativa de los modelos de recompensa, que generalmente se entrenan con conjuntos de datos de comparaciones entre salidas para la misma pregunta, la ventaja se calcula para reflejar estas comparaciones relativas. Se normaliza de la siguiente manera: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

Este enfoque le da su nombre al método: Group Relative Policy Optimization (GRPO).

Se demostró en el artículo Understanding R1-Zero-Like Training: A Critical Perspective que escalar por std(r) \text{std}(\mathbf{r}) puede causar un sesgo de dificultad a nivel de pregunta. Puedes desactivar este escalado estableciendo scale_rewards=False en GRPOConfig. Ten en cuenta que desactivar el escalado basado en std también elimina la normalización de varianza, por lo que las magnitudes de actualización dependen directamente de la escala bruta de la recompensa y de la composición del lote.

Como se muestra en Parte I: ¿Trucos o trampas? Un análisis profundo del RL para el razonamiento de LLM (Lite PPO), calcular la media a nivel local (grupo) y la desviación estándar a nivel global (lote) permite una formación de recompensas más robusta. Puede utilizar esta estrategia de escalado estableciendo scale_rewards="batch" en GRPOConfig.

Estimación de la divergencia de KL

La divergencia de KL se estima utilizando el aproximador introducido por Schulman et al. (2020). El aproximador se define de la siguiente manera: DKL[πθ∥πref]=πref(oi,t∣q,oi,<t)πθ(oi,t∣q,oi,<t)−log⁡πref(oi,t∣q,oi,<t)πθ(oi,t∣q,oi,<t)−1,\mathbb{D}_{\text{KL}}\left[\pi_\theta \|\pi_{\text{ref}}\right] = \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - \log \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - 1,

Cálculo de la pérdida

El objetivo es maximizar la ventaja garantizando que el modelo se mantenga cerca de la política de referencia. En consecuencia, la pérdida se define de la siguiente manera: LGRPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣[πθ(oi,t∣q,oi,<t)[πθ(oi,t∣q,oi,<t)]no gradA^i,t−βDKL[πθ∥πref]], \mathcal{L}_{\text{GRPO}}(\theta) = -\frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],

donde el primer término representa la ventaja escalada y el segundo término penaliza las desviaciones de la política de referencia a través de la divergencia de KL.

Ten en cuenta que, en comparación con la formulación original en DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, no escalamos por 1∣oi∣ \frac{1}{|o_i|} porque se demostró en el artículo Understanding R1-Zero-Like Training: A Critical Perspective que esto introduce un sesgo de longitud a nivel de respuesta. Más detalles en tipos de pérdida.

Ten en cuenta que, en comparación con la formulación original en DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, usamos β=0.0 \beta = 0.0 de forma predeterminada, lo que significa que no se utiliza el término de divergencia KL. Esta elección está motivada por varios estudios recientes (p. ej., Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) ) que han demostrado que el término de divergencia KL no es esencial para el entrenamiento con GRPO. Como resultado, se ha vuelto una práctica común excluirlo (p. ej. Understanding R1-Zero-Like Training: A Critical Perspective, DAPO: An Open-Source LLM Reinforcement Learning System at Scale). Si deseas incluir el término de divergencia KL, puedes establecer beta en GRPOConfig a un valor no nulo.

En el artículo original, esta formulación se generaliza para tener en cuenta múltiples actualizaciones después de cada generación (denotado μ \mu , se puede configurar con num_iterations en GRPOConfig) aprovechando el objetivo sustituto recortado: LGRPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣[min⁡(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t)A^i,t, clip(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t),1−ϵ,1+ϵ)A^i,t)−βDKL[πθ∥πref]], \mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \min \left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})} \hat{A}_{i,t}, \, \text{clip}\left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})}, 1 - \epsilon, 1 + \epsilon \right) \hat{A}_{i,t} \right) - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],

donde clip(⋅,1−ϵ,1+ϵ)\text{clip}(\cdot, 1 - \epsilon, 1 + \epsilon) asegura que las actualizaciones no se desvíen excesivamente de la política de referencia al acotar la razón de políticas entre 1−ϵ 1 - \epsilon y 1+ϵ 1 + \epsilon . Cuando μ=1 \mu = 1 (valor predeterminado en TRL), el objetivo sustituto recortado se simplifica al objetivo original.

Tipos de pérdida

Se han propuesto varias formulaciones del objetivo en la literatura. Inicialmente, el objetivo de GRPO se definió de la siguiente manera: LGRPO(θ)=−1G∑i=1G1∣oi∣∑t=1∣oi∣li,t, \mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} l_{i,t},

donde li,t=πθ(oi,t∣q,oi,<t)[πθ(oi,t∣q,oi,<t)]no gradA^i,t−βDKL[πθ∥πref]. l_{i,t} = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right].

El artículo de DAPO destaca las limitaciones de la función de pérdida a nivel de muestra del algoritmo GRPO en escenarios de CoT largo, donde las respuestas más largas se penalizan de menos, lo que lleva a una calidad de salida inferior. La solución propuesta es una normalización a nivel de token, que maneja mejor las secuencias más largas al asignar recompensas más equilibradas a los tokens individuales, independientemente de la longitud de la respuesta: LDAPO(θ)=−1∑i=1G∣oi∣∑i=1G∑t=1∣oi∣li,t, \mathcal{L}_{\text{DAPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},

Para usar esta formulación, establezca loss_type="dapo" en GRPOConfig.

Además, se demostró en el artículo Understanding R1-Zero-Like Training: A Critical Perspective que la formulación inicial de GRPO introduce un sesgo de longitud de respuesta. Muestran que, si bien la formulación de DAPO reduce este sesgo, no lo elimina por completo. Para eliminarlo por completo, proponen dividir por una constante en lugar de la longitud de la secuencia, lo que resulta en la siguiente formulación: LDr. GRPO(θ)=−1LG∑i=1G∑t=1∣oi∣li,t, \mathcal{L}_{\text{Dr. GRPO}}(\theta) = - \frac{1}{LG} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},

Se recomienda que esta constante sea la longitud máxima de la finalización. Para usar esta formulación, establezca loss_type="dr_grpo" en GRPOConfig.

Alternativamente, en el artículo de SAPO, el equipo de Qwen propone reemplazar el mecanismo de recorte “duro” de GRPO por un mecanismo de control suave con temperatura. Mientras que GRPO anula los gradientes cuando la política se desvía demasiado de la de referencia, SAPO utiliza una región de confianza suave que atenúa el peso del gradiente de forma gradual. Esto permite al modelo conservar señales de aprendizaje útiles de los tokens “casi en política” mientras suprime el ruido de las desviaciones extremas.

La función de pérdida se define como: LSAPO(θ)=−1G∑i=1G1∣oi∣∑t=1∣oi∣fi,t(πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t))A^i,t \mathcal{L}_{\text{SAPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} f_{i,t} \left( \frac{\pi_\theta(o_{i,t} | q, o_{i,<t})}{\pi_{\theta_{old}}(o_{i,t} | q, o_{i,<t})} \right) \hat{A}_{i,t}

La función de soft-gating fi,t f_{i,t} se define utilizando la función sigmoide σ \sigma como: fi,t(x)=σ(τi,t(x−1))⋅4τi,t f_{i,t}(x) = \sigma \left( \tau_{i,t} (x - 1) \right) \cdot \frac{4}{\tau_{i,t}}

La temperatura τi,t \tau_{i,t} se elige en función del signo de la ventaja A^i,t \hat{A}_{i,t} : τi,t={τpos,if A^i,t>0τneg,otherwise \tau_{i,t} = \begin{cases} \tau_{\text{pos}}, & \text{if } \hat{A}_{i,t} > 0 \\ \tau_{\text{neg}}, & \text{otherwise} \end{cases}

Recomiendan usar temperaturas asimétricas, τneg>τpos \tau_{\text{neg}} > \tau_{\text{pos}} (los valores predeterminados son τpos=1.0,τneg=1.05 \tau_{\text{pos}}=1.0, \tau_{\text{neg}}=1.05 ). Esto garantiza que el modelo se penalice de manera más estricta por las acciones «malas» para evitar la inestabilidad, mientras que es más permisivo con las acciones «buenas».

Para usar esta formulación, establezca loss_type="sapo" en GRPOConfig.

Métricas registradas

Durante el entrenamiento y la evaluación, registramos las siguientes métricas:

  • num_tokens: El número total de tokens procesados hasta el momento, incluyendo tanto los prompts como las completions. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • step_time: Tiempo promedio (en segundos) por paso de entrenamiento (incluida la generación).
  • completions/mean_length: La longitud media de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/min_length: La longitud mínima de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/max_length: La longitud máxima de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/mean_terminated_length: La longitud media de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/min_terminated_length: La longitud mínima de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/max_terminated_length: La longitud máxima de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
  • completions/clipped_ratio: La proporción de completados truncados (recortados).
  • tools/call_frequency: El número medio de llamadas a herramientas por finalización en el lote de generación. Se registra solo cuando se proporcionan tools.
  • tools/failure_frequency: La proporción de llamadas a herramientas que fallaron (la herramienta no se encontró, lanzó una excepción o el tipo de llamada no es compatible). Es 0.0 cuando no se llamó a ninguna herramienta. Se registra solo cuando se proporcionan tools.
  • rewards/{reward_func_name}/mean: La recompensa media de una función de recompensa específica. Cuando un entorno posee la recompensa a través de get_reward, {reward_func_name} es el nombre de la clase del entorno.
  • rewards/{reward_func_name}/std: La desviación estándar de la recompensa de una función de recompensa específica.
  • reward: La recompensa media general tras sumar las recompensas de todas las funciones (ponderadas por reward_weights).
  • reward_std: La desviación estándar de las recompensas sumadas entre funciones (ponderadas por reward_weights), calculada sobre el lote completo.
  • frac_reward_zero_std: La fracción de muestras en el lote de generación con una desviación estándar de recompensa igual a cero, lo que implica que hay poca diversidad para ese prompt (todas las respuestas son correctas o incorrectas).
  • sampling/sampling_logp_difference/mean: La diferencia absoluta media entre las probabilidades logarítmicas devueltas por el muestreador (vLLM) y las recalculadas por el modelo de entrenamiento, sobre los tokens de la finalización. Un valor creciente indica un aumento en la discrepancia entre el entrenamiento y la inferencia. Se registra solo cuando use_vllm=True y vllm_importance_sampling_correction=True.
  • sampling/sampling_logp_difference/max: La mayor diferencia absoluta de este tipo. Se registra solo cuando use_vllm=True y vllm_importance_sampling_correction=True.
  • sampling/importance_sampling_ratio/min: La proporción de muestreo de importancia más pequeña utilizada para corregir la discrepancia entre entrenamiento e inferencia, después de aplicar la restricción seleccionada por vllm_importance_sampling_mode (recortada a [C_min, C_max] para los modos *_truncate y establecida en cero para los modos *_mask). Se calcula sobre los tokens de la respuesta o sobre las secuencias para los modos sequence_*. Se registra solo cuando use_vllm=True y vllm_importance_sampling_correction=True.
  • sampling/importance_sampling_ratio/mean: La media de la ratio de muestreo por importancia restringida. Se registra solo cuando use_vllm=True y vllm_importance_sampling_correction=True.
  • sampling/importance_sampling_ratio/max: La mayor proporción de muestreo por importancia restringida. Se registra solo cuando use_vllm=True y vllm_importance_sampling_correction=True.
  • policy_loss: el valor de la pérdida de gradiente de la política (antes de cualquier bonificación de entropía). Se registra cuando entropy_coef es distinto de cero o use_adaptive_entropy=True.
  • entropy: Entropía media de las predicciones de tokens en las completaciones generadas. (Si mask_truncated_completions=True, se excluyen los tokens de las secuencias enmascaradas.)
  • entropy_coef: El coeficiente actual de regularización de entropía. Se registra cuando entropy_coef es distinto de cero o use_adaptive_entropy=True. Se actualiza una vez por paso del optimizador cuando use_adaptive_entropy=True.
  • aux_loss: La pérdida auxiliar de equilibrio de carga de un modelo Mixture-of-Experts, antes de que se escale por router_aux_loss_coef y se sume a la pérdida. Se registra solo cuando el modelo es un modelo MoE y router_aux_loss_coef es distinto de cero.
  • kl: La divergencia KL media entre el modelo y el modelo de referencia, calculada sobre las completaciones generadas. Se registra solo si beta es distinto de cero.
  • clip_ratio/region_mean: La proporción de tokens (o secuencias, si importance_sampling_level="sequence") las probabilidades donde el objetivo de GRPO se recorta para mantenerse dentro de la región de confianza: clip(ri,t(θ),1−ϵlow,1+ϵhigh) ,ri,t(θ)=πθ(oi,t∣q,oi,<t)πθold(oi,t∣q,oi,<t) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right)\,, \quad r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})} . Un valor más alto significa que se recortan más tokens, lo que limita cuánto puede cambiar la política πθ\pi_\theta .
  • clip_ratio/low_mean: La proporción media de probabilidades de token (o de secuencia, si importance_sampling_level="sequence") fueron recortadas en el límite inferior de la región de confianza: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: La fracción más pequeña de tokens por finalización (o de la secuencia en sí, si importance_sampling_level="sequence") se recorta en el límite inferior de la región de confianza: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: La proporción media de probabilidades de token (o de secuencia, si importance_sampling_level="sequence") fueron recortadas en el límite superior de la región de confianza: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: La mayor fracción de tokens por finalización (o la secuencia en sí, si importance_sampling_level="sequence") se recorta en el límite superior de la región de confianza: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • cispo_clip_ratio: La proporción de pesos de muestreo por importancia de tokens (o de secuencias, si importance_sampling_level="sequence") se recortaron en epsilon_high mientras tenían una ventaja positiva: ri,t(θ)>ϵhighr_{i,t}(\theta) > \epsilon_\mathrm{high}. Se registra solo cuando loss_type="cispo".
  • vespo/phi_seq_mean: El valor promedio de la ponderación Gamma de VESPO φ(w)\varphi(w) aplicada a los pesos de importancia a nivel de secuencia. Los valores por debajo de 1.0 significan que las secuencias se están ponderando a la baja. Se registra solo cuando loss_type="vespo".

Personalización

Acelera el entrenamiento con generación impulsada por vLLM

La generación suele ser el principal cuello de botella al entrenar con métodos en línea. Para acelerar la generación, puedes usar vLLM, un motor de inferencia de alto rendimiento y baja latencia para LLMs. Para habilitarlo, primero instala el paquete con

pip install trl[vllm]

Soportamos dos formas de usar vLLM durante el entrenamiento: modo servidor y modo colocalizado.

Por defecto, el Muestreo de Importancia con Enmascarado a nivel de secuencia (vllm_importance_sampling_mode="sequence_mask") se activa para la generación de vLLM para abordar la discrepancia entre generación y entrenamiento que ocurre al utilizar diferentes marcos de trabajo. Esto se puede desactivar estableciendo vllm_importance_sampling_correction=False. Para obtener más información, consulte Masked Importance Sampling y Sequence-level Importance Sampling

Opción 1: Modo Colocate

En este modo, vLLM se ejecuta dentro del proceso del entrenador y comparte la memoria de GPU con el modelo de entrenamiento. Esto evita iniciar un servidor separado y puede mejorar la utilización de la GPU, pero puede provocar una contención de memoria en las GPUs de entrenamiento. Este es el modo predeterminado.

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)

Opción 2: Modo servidor

En este modo, vLLM se ejecuta en un proceso separado (y usando GPUs separadas) y se comunica con el entrenador a través de HTTP. Esto es ideal si tienes GPUs dedicadas para inferencia.

  1. Iniciar el servidor de vLLM:

    VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
        --weight-transfer-config '{"backend": "nccl"}' \
        --logprobs-mode processed_logprobs \
        --max-logprobs -1
  2. Habilita el modo de servidor en tu script de entrenamiento:

    from trl import GRPOConfig
    
    training_args = GRPOConfig(
        ...,
        use_vllm=True,
        vllm_mode="server",
    )

Asegúrate de que el servidor utilice GPUs diferentes a las del entrenador, de lo contrario es posible que aparezcan errores de NCCL. Puedes especificar las GPUs a utilizar con la variable de entorno CUDA_VISIBLE_DEVICES.

En función del tamaño del modelo y de los requisitos generales de memoria de GPU para el entrenamiento, es posible que necesites ajustar el parámetro vllm_gpu_memory_utilization en GRPOConfig para evitar la subutilización o errores de memoria insuficiente.

Ponemos a disposición un HF Space para ayudar a estimar la utilización de memoria de GPU recomendada en función de la configuración de tu modelo y los ajustes de tu experimento. Simplemente úsalo de la siguiente manera para obtener la recomendación de vllm_gpu_memory_utilization:

Si el valor recomendado no funciona en su entorno, sugerimos añadir un pequeño margen (p. ej., +0.05 o +0.1) al valor recomendado para garantizar la estabilidad.

Si aún obtienes errores de memoria insuficiente, establece vllm_enable_sleep_mode en True y los parámetros y la caché de vllm se descargarán durante el paso de optimización. Para obtener más información, consulta Reducing Memory Usage with vLLM Sleep Mode.

Por defecto, GRPO utiliza MASTER_ADDR=localhost y MASTER_PORT=12345 para vLLM, pero puedes sobrescribir estos valores configurando las variables de entorno de forma correspondiente.

Para obtener más información, consulte Acelerar el entrenamiento con vLLM.

Manejo de la discrepancia entre entrenamiento e inferencia

Aunque vLLM acelera enormemente la inferencia, también desacopla el motor de inferencia del motor de entrenamiento. En teoría, estos motores son matemáticamente idénticos, pero en la práctica pueden producir salidas diferentes debido a efectos de precisión y optimizaciones específicas del hardware. Esta divergencia refleja los distintos objetivos de optimización de los dos sistemas. Los motores de inferencia buscan maximizar el rendimiento de muestreo, generalmente medido en tokens por segundo, manteniendo al mismo tiempo una fidelidad de muestreo aceptable. Los marcos de entrenamiento, en cambio, se centran en la estabilidad numérica y la precisión para el cálculo de gradientes, utilizando a menudo formatos de mayor precisión como FP32 para los pesos maestros y los estados del optimizador. Estas prioridades y restricciones diferentes introducen una discrepancia inevitable, aunque sutil, entre el entrenamiento y la inferencia.

Esta discrepancia conduce a una actualización de gradiente sesgada que se ha observado que desestabiliza el entrenamiento ([1][2][3][4][5]). Por simplicidad, considere el gradiente de política REINFORCE: ∇θJ(x,θ)=Ey∼πtrain(⋅∣x,θ)[∇θlog⁡πtrain(y∣x,θ)⋅R(x,y)] \nabla_\theta \mathcal{J}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{train}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right]

Aquí x x denota los prompts muestreados de alguna distribución de datos, y πtrain \pi^\text{train} es la política implementada por el motor de entrenamiento. Con vLLM en el bucle, obtenemos una política de inferencia separada πinference \pi^\text{inference} , por lo que el gradiente de política efectivo se convierte en ∇θJbiased(x,θ)=Ey∼πinference(⋅∣x,θ)[∇θlog⁡πtrain(y∣x,θ)⋅R(x,y)]. \nabla_\theta \mathcal{J}_{\text{biased}}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{inference}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right].

Esto convierte un problema de RL que de otro modo sería on policy en uno off policy.

La forma estándar de corregir este cambio de distribución es la muestreo por importancia (IS). Ofrecemos dos variantes de IS: Muestreo por Importancia Truncado (TIS) y Muestreo por Importancia con Máscara (MIS). Ambas variantes se pueden aplicar a nivel de token o a nivel de secuencia. Sea ρ \rho el peso de importancia, por ejemplo ρt \rho_t por token o ρseq \rho_{\text{seq}} por secuencia. Bajo TIS, las proporciones fuera del rango [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] se recortan, ρ←clip(ρ,Cmin⁡,Cmax⁡). \rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}).

El artículo original de TIS propuso un mecanismo de recorte de límite superior único, es decir, min⁡(ρ,Cmax⁡) \min(\rho, C_{\max}) . La implementación en TRL generalizó esto introduciendo también un límite inferior, lo que da lugar a la formulación de doble lado mostrada arriba, inspirada en el IcePop método.
Tenga en cuenta que en IcePop, los límites se etiquetan como α \alpha y β \beta mientras que en TRL usamos Cmin⁡ C_{\min} y Cmax⁡ C_{\max} .

Bajo MIS, las proporciones fuera de este rango se establecen en cero, por lo que esas muestras no contribuyen al gradiente. En otras palabras, las muestras atípicas se ponderan a la baja bajo TIS y se descartan bajo MIS. El flag de configuración vllm_importance_sampling_mode elige tanto la variante de IS (enmascarado o truncamiento) como la granularidad (nivel de token o nivel de secuencia).

El muestreo de importancia es la respuesta algorítmica fundamentada a la discrepancia entre el entrenamiento y la inferencia. Sin embargo, también existen enfoques más directos que intentan reducir la discrepancia entre los propios motores. La mayoría de estos son soluciones de ingeniería. Por ejemplo, MiniMax M1 utiliza una cabeza de modelo de lenguaje en FP32 en el motor de inferencia. Thinking Machines ha explorado kernels de inferencia deterministas, aunque esto conlleva un costo de eficiencia significativo. vLLM ha demostrado políticas consistentes a nivel de bits construyendo sobre los kernels deterministas invariantes por lote de Thinking Machines, pero a noviembre de 2025 aún existe una penalización sustancial en el rendimiento relativo a la inferencia estándar de vLLM.

Acelera el entrenamiento con el loteo continuo de transformers

Como alternativa a vLLM, puede utilizar el motor de lotes continuos integrado de transformers para una generación más rápida. El lote continuo elimina las secuencias finalizadas del lote de inmediato, en lugar de esperar a que la más lenta termine. En tareas con longitudes de finalización variables (p. ej., razonamiento matemático), esto produce una generación más rápida y un menor uso de VRAM que el generate() predeterminado con tamaños de lote grandes (N≥32).

El loteo continuo es una mejora de reemplazo directo que no requiere configuración del servidor ni sincronización de pesos. Se ejecuta en el proceso y es adecuado para el entrenamiento en una sola GPU o para entornos con restricciones de memoria. Para obtener el máximo rendimiento de generación a gran escala, use vLLM en su lugar.

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_transformers_continuous_batching=True,
    transformers_continuous_batching_config={
        "use_cuda_graph": False,
        "max_memory_percent": 0.4,  # lower values leave more VRAM for the training backward pass
    },
)

TRL establece max_memory_percent en 0.5 (en lugar de 0.9 de transformers) para dejar suficiente VRAM para la pasada de retropropagación del entrenamiento. Redúcelo a 0.3–0.4 para lotes de generación grandes (N≥32) o si ves errores de memoria insuficiente.

Para un ejemplo completo de entrenamiento, consulte examples/grpo_continuous_batching/grpo_continuous_batching.py.

GRPO a gran escala: entrena un modelo de 70B+ en varios nodos

Al entrenar modelos grandes como Qwen2.5-72B, se necesitan varias optimizaciones clave para hacer que el entrenamiento sea eficiente y escalable en varias GPU y nodos. Estas incluyen:

  • DeepSpeed ZeRO Stage 3: ZeRO aprovecha el paralelismo de datos para distribuir los estados del modelo (pesos, gradientes, estados del optimizador) entre varias GPU y CPU, reduciendo los requisitos de memoria y cómputo en cada dispositivo. Dado que los modelos grandes no caben en una sola GPU, es necesario usar ZeRO Stage 3 para entrenar dichos modelos. Para más detalles, consulte DeepSpeed Integration.
  • torchrun: el lanzador de PyTorch inicia un proceso por GPU en cada nodo y los conecta a través de un punto de encuentro común. Para más detalles, consulte Distributing Training.
  • vLLM: Consulte la sección anterior para saber cómo usar vLLM para acelerar la generación.

A continuación se muestra un ejemplo de script de SLURM para entrenar un modelo de 70B con GRPO en varios nodos. Este script entrena un modelo en 4 nodos y utiliza el 5º nodo para la generación impulsada por vLLM.

#!/bin/bash
#SBATCH --nodes=5
#SBATCH --gres=gpu:8

# Get the list of allocated nodes
NODELIST=($(scontrol show hostnames $SLURM_JOB_NODELIST))

# Assign the first 4 nodes for training and the 5th node for vLLM
TRAIN_NODES="${NODELIST[@]:0:4}"  # Nodes 0, 1, 2, 3 for training
VLLM_NODE="${NODELIST[4]}"  # Node 4 for vLLM

# Run training on the first 4 nodes (Group 1)
srun --nodes=4 --ntasks=4 --nodelist="${NODELIST[@]:0:4}" torchrun \
     --nnodes 4 \
     --nproc_per_node 8 \
     --node_rank $SLURM_PROCID \
     --rdzv_backend c10d \
     --rdzv_endpoint ${NODELIST[0]}:29500 \
     train_grpo.py \
     --server_ip $VLLM_NODE &

# Run vLLM server on the 5th node (Group 2)
srun --nodes=1 --ntasks=1 --nodelist="${NODELIST[4]}" env VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-72B --tensor-parallel-size 8 \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1 &

wait
import argparse

from datasets import load_dataset
from trl import GRPOTrainer, GRPOConfig
from trl.rewards import accuracy_reward

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--vllm_server_host", type=str, default="", help="The server IP")
    args = parser.parse_args()

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

    training_args = GRPOConfig(
        per_device_train_batch_size=4,
        deepspeed="examples/deepspeed_configs/zero3.json",
        use_vllm=True,
        vllm_mode="server",
        vllm_server_host=args.vllm_server_host.replace("ip-", "").replace("-", "."),  # from ip-X-X-X-X to X.X.X.X
    )

    trainer = GRPOTrainer(
        model="Qwen/Qwen2.5-72B",
        args=training_args,
        reward_funcs=accuracy_reward,
        train_dataset=dataset
    )
    trainer.train()

if __name__=="__main__":
    main()

Uso de una función de recompensa personalizada

El GRPOTrainer permite el uso de funciones de recompensa personalizadas en lugar de modelos de recompensa densos. Para garantizar la compatibilidad, su función de recompensa debe cumplir con los siguientes requisitos:

Las funciones de recompensa pueden ser funciones Python síncronas o corrutinas asíncronas async def. Cuando se proporcionan varias funciones de recompensa asíncronas, se espera su finalización de forma concurrente (se ejecutan en paralelo mediante asyncio.gather) para que su latencia se solape.

  1. Argumentos de entrada:

    • La función debe aceptar lo siguiente como argumentos de palabra clave:

      • prompts (contiene los prompts),
      • completions (contiene las completaciones generadas),
      • completion_ids (contiene las completas tokenizadas),
      • trainer_state (TrainerState): El estado actual del trainer. Esto se puede usar para implementar funciones de recompensa dinámicas, como el aprendizaje por currículo, donde la recompensa se ajusta en función del progreso del entrenamiento.
      • log_extra: una función log_extra(column: str, values: list) para añadir columnas adicionales a la tabla de completados. Consulte el Ejemplo 6.
      • log_metric: una función log_metric(name: str, value: float) para registrar métricas escalares como gráficos junto a kl, entropy, etc. Consulte el Ejemplo 6.
      • environments: una lista de instancias de entorno, una por cada finalización. Solo está presente cuando se proporciona environment_factory. Úsela para leer el estado acumulado durante el episodio (p. ej., env.counter). Para entornos con estado, es preferible que el propio entorno gestione la recompensa mediante un método get_reward — consulte Recompensas.
      • Todos los nombres de columnas (excepto prompt) que el conjunto de datos puede tener. Por ejemplo, si el conjunto de datos contiene una columna llamada ground_truth, la función se llamará con ground_truth como argumento de palabra clave.

      La forma más sencilla de cumplir con este requisito es usar **kwargs en la firma de la función.

    • Dependiendo del formato del conjunto de datos, la entrada variará:

  2. Valor de retorno: La función debe devolver una lista de floats. Cada float representa la recompensa correspondiente a una única finalización.

Ejemplo 1: Recompensar las finalizaciones más largas

A continuación se muestra un ejemplo de una función de recompensa para un formato estándar que recompensa las finalizaciones más largas:

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]

Puedes probarlo de la siguiente manera:

>>> prompts = ["The sky is", "The sun is"]  # not used in the reward function, but the trainer will pass it
>>> completions = [" blue.", " 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]

Ejemplo 1.1: Recompensar las finalizaciones más largas (basado en el número de caracteres)

Igual que en el ejemplo anterior, pero esta vez la función de recompensa se basa en el número de caracteres en lugar de tokens.

def reward_func(completions, **kwargs):
    """Reward function that assigns higher scores to longer completions (in terms of character count)."""
    return [float(len(completion)) for completion in completions]

Puedes probarlo de la siguiente manera:

>>> prompts = ["The sky is", "The sun is"]
>>> completions = [" blue.", " in the sky."]
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]  # not used in the reward function, but the trainer will pass it
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[6.0, 12.0]

Ejemplo 2: Recompensar las finalizaciones con un formato específico

A continuación se muestra un ejemplo de una función de recompensa que verifica si la finalización tiene un formato específico. Este ejemplo se inspira en la función format reward utilizada en el artículo DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Está diseñada para un formato conversacional, donde los prompts y las finalizaciones consisten en mensajes estructurados.

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]

Puedes probar esta función de la siguiente manera:

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

Ejemplo 3: Recompensar las finalizaciones basándose en una referencia

A continuación se muestra un ejemplo de una función de recompensa que verifica si la finalización es correcta. Este ejemplo se inspira en la función de recompensa de precisión utilizada en el artículo DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Este ejemplo está diseñado para el formato estándar, donde el conjunto de datos contiene una columna llamada ground_truth.

import re

def reward_func(completions, ground_truth, **kwargs):
    # Regular expression to capture content inside \boxed{}
    matches = [re.search(r"\\boxed\{(.*?)\}", completion) 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)]

Puedes probar esta función de la siguiente manera:

>>> prompts = ["Problem: Solve the equation $2x + 3 = 7$. Solution:", "Problem: Solve the equation $3x - 5 = 10$."]
>>> completions = [r" The solution is \boxed{2}.", r" The solution is \boxed{6}."]
>>> ground_truth = ["2", "5"]
>>> reward_func(prompts=prompts, completions=completions, ground_truth=ground_truth)
[1.0, 0.0]

Ejemplo 4: Funciones de recompensa multitarea

A continuación se muestra un ejemplo de uso de múltiples funciones de recompensa en el GRPOTrainer. En este ejemplo, definimos dos funciones de recompensa específicas para cada tarea: math_reward_func y coding_reward_func. La math_reward_func otorga recompensas a los problemas de matemáticas en función de su corrección, mientras que la coding_reward_func otorga recompensas a los problemas de programación en función de si la solución funciona.

from datasets import Dataset
from trl import GRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": "What is 2+2?", "task": "math"},
        {"prompt": "Write a function that returns the sum of two numbers.", "task": "code"},
        {"prompt": "What is 3*4?", "task": "math"},
        {"prompt": "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
trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=[math_reward_func, coding_reward_func],
    train_dataset=dataset,
)

trainer.train()

En este ejemplo, math_reward_func y coding_reward_func están diseñados para funcionar con un conjunto de datos mixto que contiene tanto problemas de matemáticas como de programación. La columna task del conjunto de datos se utiliza para determinar qué función de recompensa aplicar a cada problema. Si no hay una función de recompensa relevante para una muestra del conjunto de datos, la función de recompensa devolverá None y el GRPOTrainer continuará con las funciones y tareas válidas. Esto permite que el GRPOTrainer maneje múltiples funciones de recompensa con diferentes alcances de aplicación.

Tenga en cuenta que GRPOTrainer ignorará las recompensas None devueltas por las funciones de recompensa y solo considerará las recompensas devueltas por las funciones relevantes. Esto garantiza que el modelo se entrene en las tareas relevantes e ignore las tareas para las que no existe una función de recompensa relevante.

Ejemplo 5: Funciones de recompensa asíncronas

Las funciones de recompensa personalizadas también pueden definirse como corrutinas async def. Esto resulta útil si la recompensa depende de una E/S lenta (por ejemplo, al llamar a un servicio remoto). Al pasar varias funciones de recompensa asíncronas, GRPOTrainer las ejecuta de forma concurrente para que su latencia se solape.

A continuación se muestra un ejemplo mínimo de una función de recompensa asíncrona que simula una operación limitada por 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]

Ejemplo 6: Registro de columnas y métricas adicionales

A continuación se muestra un ejemplo de una función de recompensa que registra columnas adicionales en la tabla de completados y métricas escalares como gráficos.

import re

def reward_func(completions, ground_truth, log_extra=None, log_metric=None, **kwargs):
    extracted = [re.search(r"\\boxed\{(.*?)\}", c) for c in completions]
    extracted = [m.group(1) if m else None for m in extracted]
    rewards = [1.0 if e == gt else 0.0 for e, gt in zip(extracted, ground_truth)]

    if log_extra:
        log_extra("golden_answer", list(ground_truth))
        log_extra("extracted_answer", [e or "[none]" for e in extracted])

    if log_metric:
        log_metric("accuracy", sum(rewards) / len(rewards))

    return rewards

Pasar la función de recompensa al entrenador

Para usar su función de recompensa personalizada, pásela al GRPOTrainer de la siguiente manera:

from trl import GRPOTrainer

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

Puedes pasar varias funciones de recompensa como una lista; esta lista puede incluir tanto funciones síncronas como asíncronas:

from trl import GRPOTrainer

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

y la recompensa se calculará como la suma de las recompensas de cada función, o como la suma ponderada si se proporciona reward_weights en la configuración.

Tenga en cuenta que GRPOTrainer admite múltiples funciones de recompensa de diferentes tipos. Consulte la documentación de los parámetros para obtener más detalles.

Regularización de entropía

Para fomentar la exploración y evitar que la política colapse en salidas casi deterministas, puedes añadir un bono de entropía al objetivo de entrenamiento. La regularización de entropía aumenta la pérdida de GRPO de la siguiente manera: L(θ)=LGRPO(θ)−α⋅H(πθ), \mathcal{L}(\theta) = \mathcal{L}_{\text{GRPO}}(\theta) - \alpha \cdot \mathcal{H}(\pi_\theta),

dondeH(πθ)\mathcal{H}(\pi_\theta) es la entropía media por token de la política yα\alpha es el coeficiente de entropía. La bonificación siempre es la entropía media por token, independientemente de loss_type; no se reescala para coincidir con la normalización de la política de un tipo de pérdida (p. ej., el denominador batch_size * max_completion_length de Dr. GRPO), por lo que entropy_coef tiene el mismo significado para todos los tipos de pérdida.

Entropía estática — un coefijo fijo durante todo el entrenamiento:

from trl import GRPOConfig, GRPOTrainer

training_args = GRPOConfig(entropy_coef=0.05, ...)

Entropía adaptativa — el coeficiente se actualiza en cada paso del optimizador en función de una entropía objetivo, tal como se introdujo en Skywork-OR1. Cuando la entropía actual es igual o inferior a entropy_target, el coeficiente se incrementa en entropy_coef_delta; de lo contrario, se decrementa. El coeficiente solo se aplica (es decir, es no nulo) mientras la entropía sea igual o inferior a la objetivo:

training_args = GRPOConfig(
    entropy_coef=0.01,          # initial coefficient
    use_adaptive_entropy=True,
    entropy_target=5.0,         # target mean per-token entropy (nats); tune for your model
    entropy_coef_delta=0.005,   # step size per optimizer step
    entropy_coef_min=0.0,
    entropy_coef_max=1.0,
    ...
)

Los modelos de lenguaje típicos tienen entropías por token de 2 a 10 nats, por lo que el valor predeterminado entropy_target=0.2 casi nunca activa la regularización: el bono solo se aplica cuando la entropía es igual o inferior al objetivo, es decir, en caso de colapso casi completo. Establezca un valor significativo para su modelo, por ejemplo, cercano a la entropía que observe al inicio del entrenamiento (registrada como la métrica entropy). Al usar top_entropy_quantile < 1.0, entropy_target se aplica al subconjunto de tokens de alta entropía; la entropía de ese subconjunto será mayor que la entropía de todos los tokens registrada como entropy, por lo que calibre en consecuencia.

Cuando use_adaptive_entropy=True, el coeficiente de entropía actual entropy_coef se guarda junto con cada punto de control y se restaura al reanudar, de modo que el entrenamiento es totalmente reanudable.

Experimentación rápida para GRPO

RapidFire AI es un motor de experimentación de código abierto que se integra sobre TRL y permite lanzar múltiples configuraciones de GRPO a la vez, incluso en una sola GPU. En lugar de probar las configuraciones de forma secuencial, RapidFire permite ver todas sus curvas de aprendizaje antes, detener las ejecuciones con bajo rendimiento y clonar las prometedoras con nuevas configuraciones en curso sin reiniciar. Para obtener más información, consulte RapidFire AI Integration.

Entrenamiento de agentes

GRPO admite entrenamiento de agentes: el modelo llama a herramientas durante la generación y aprende del resultado.

  • Una herramienta es una función Python simple (síncrona o asíncrona) expuesta al modelo. Utilice tools para llamadas sin estado (una calculadora, una búsqueda web).
  • Un environment es la forma más general: un objeto con estado creado de nuevo para cada rollout, cuyos métodos públicos se exponen como herramientas, más un hook de ciclo de vida reset y un get_reward opcional que le permite poseer la recompensa. Use environment_factory cuando necesite estado por rollout, un hook de reset o una recompensa poseída por el environment.

Se combinan: puedes pasar tools independientes junto con un environment_factory.

Herramientas

El argumento tools espera una lista de funciones de Python (síncronas o asíncronas) que definen las herramientas disponibles para el agente:

from trl import GRPOTrainer

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

Cada herramienta debe ser una función de Python estándar con argumentos y tipos de retorno con anotaciones de tipo, junto con una docstring en estilo Google que describa su propósito, sus argumentos y su valor de retorno. Para más detalles, consulte la guía para pasar herramientas.

El bucle de llamadas a herramientas de GRPO requiere que la plantilla de chat sea de prefijo conservador (añadir un mensaje de herramienta no debe cambiar cómo se renderizan los mensajes anteriores). Para las familias de modelos conocidas (p. ej., Qwen3, DeepSeek-V3), TRL cambia automáticamente a una plantilla de entrenamiento parcheada cuando se habilitan las herramientas. Consulte Plantillas de chat para obtener la lista completa.

Use max_tool_calling_iterations en GRPOConfig para limitar el número de turnos de llamada a herramientas. Por defecto no hay límite, y la generación se detiene cuando el modelo produce un turno de respuesta sin llamadas a herramientas, cuando la finalización (todos los turnos y resultados de herramientas) alcanza max_completion_length tokens, o cuando la secuencia completa alcanza la longitud máxima del modelo (vllm_max_model_length con vllm_mode="colocate", o los max_position_embeddings del modelo en caso contrario).

Ejemplo:

from trl import GRPOTrainer

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 = GRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

Entornos

También puede proporcionar herramientas a través de environment_factory. En este modo, GRPOTrainer crea una instancia de entorno por rollout y expone los métodos públicos del entorno como herramientas.

environment_factory requiere transformers>=5.2.0.

Cuando se utiliza un environment_factory, el entorno posee los datos: no existe un train_dataset externo. En cada rollout, reset() genera la tarea —muestreando de forma autónoma de un corpus que el entorno mantiene, o generando un estado de forma procedural— y devuelve el prompt. max_steps establece la duración del entrenamiento. Lo siguiente es un ejemplo mínimo de un entorno que muestrea de forma autónoma un objetivo y expone un método increment (expuesto como una herramienta).

import random

from trl import GRPOConfig, GRPOTrainer

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

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
    environment_factory=IncrementEnv,
)
trainer.train()

Una clase de entorno tiene dos métodos reservados: reset y get_reward. A diferencia de cualquier otro método público, estos no se exponen al modelo como herramientas.

  • reset (obligatorio) se llama cuando comienza el rollout. Puede devolver None o una cadena de caracteres. En GRPO, cuando devuelve una cadena de caracteres, esa cadena es el prompt del usuario.
  • get_reward (opcional, síncrono o asíncrono) no toma argumentos y devuelve un float: el entorno puntúa el episodio que acaba de ejecutar a partir de su propio estado interno (¿el juego terminó en una victoria? ¿se adivinó la palabra?). Se llama una vez por cada rollout completado y actúa como fuente de recompensa.

Dado que el entorno se muestrea a sí mismo en cada reset(), los G miembros de un grupo GRPO pueden no compartir el mismo estado inicial, lo que hace que la línea base del grupo sea ligeramente más ruidosa. Para estados idénticos dentro de un grupo, haz que reset() derive el estado de forma determinista a partir de una clave compartida.

Proporcionar un conjunto de datos externo (opcional)

En lugar de dejar que el entorno muestreea por sí mismo, puedes proporcionar un train_dataset externo. Por ejemplo, cuando tus tareas ya están en un conjunto de datos, o para enrutar entre múltiples entornos. Por cada rollout, el entrenador muestrea una fila, usa su columna "prompt" como prompt y pasa las demás columnas de la fila a reset() como argumentos de palabra clave (de modo que el entorno lea la tarea del conjunto de datos).

from datasets import Dataset
from trl import GRPOTrainer

# 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

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=dataset,  # the dataset owns the task; the "target" column reaches reset(target=...)
    environment_factory=IncrementEnv,
)
trainer.train()

Recompensas

Los recompensas gestionadas por el entorno y las gestionadas por el entrenador no son excluyentes. Pasa reward_funcs para recompensas que es natural calcular a partir de la finalización (p. ej., una comprobación de formato del texto) y deja que el entorno devuelva su recompensa dependiente del estado a través de get_reward. Se suman todas las fuentes; reward_weights se aplica solo a reward_funcs (el entorno gestiona su propia escala).

def format_reward(completions, **kwargs):  # trainer-owned: scores the completion text
    ...

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(max_steps=1000),
    reward_funcs=format_reward,          # trainer-owned: scores the completion
    environment_factory=IncrementEnv,    # env-owned: scores its internal state via `get_reward`
)

Una reward_func también puede leer el estado del entorno directamente: cuando environment_factory está configurado, el entrenador pasa un argumento environments (una instancia por cada finalización). Esto es útil ocasionalmente, pero para recompensas dependientes del estado se prefiere get_reward.

Esto funciona de manera idéntica para AsyncGRPOTrainer.

Varios entornos

Para entrenar con una mezcla de tareas en una sola ejecución (por ejemplo, una tarea de programación y un juego), pase un diccionario que mapee nombres de entornos a fábricas en lugar de un único invocable. Cada rollout selecciona su entorno a través de un campo environment en el conjunto de datos, y solo se exponen las herramientas de ese entorno. Esto evita filtrar herramientas irrelevantes (la herramienta move del juego a un ejemplo de programación, y viceversa). Cada entorno sigue siendo propietario de sus datos y devuelve el prompt desde reset(), por lo que el conjunto de datos solo necesita la columna environment para enrutar entre ellos.

import random

from datasets import Dataset
from trl import GRPOConfig, GRPOTrainer


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
dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(chat_template_kwargs={"enable_thinking": False}),
    train_dataset=dataset,
    reward_funcs=reward_func,
    environment_factory={"coding": CodingEnv, "game": GameEnv},
)
trainer.train()

La función de recompensa sigue recibiendo el entorno de cada ejemplo a través de reward_kwargs["environments"], por lo que puede ramificar la lógica según el tipo de entorno (p. ej. isinstance(env, CodingEnv)). Las instancias de entorno se reutilizan entre pasos (se reinician entre episodios), por lo que un __init__ costoso se ejecuta una vez en lugar de en cada paso. El campo environment lo consume el entrenador y no se reenvía a reset.

Respuestas de herramientas multimodales

Las herramientas pueden devolver imágenes junto con texto devolviendo una lista de bloques de contenido. Esto es útil para el entrenamiento de agentes VLM donde la herramienta proporciona retroalimentación visual (p. ej., capturas de pantalla, gráficos, capturas de cámara).

from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]

Las imágenes devueltas se inyectan automáticamente en la conversación y se pasan al VLM para los turnos de generación posteriores.

Modelos compatibles

Probado con:

  • Beam — p. ej., reflection/Beam-1.0-501B-A23B
  • DeepSeek-R1 — por ejemplo, deepseek-ai/DeepSeek-R1
  • Gemma4 — p. ej., google/gemma-4-E2B-it
  • GLM-4-MoE (4.5, 4.6 o 4.7) — p. ej., zai-org/GLM-4.7
  • GPT-OSS — p. ej., openai/gpt-oss-20b
  • Llama 3.1 — por ejemplo, meta-llama/Llama-3.1-8B-Instruct
  • Llama 3.2 — por ejemplo, meta-llama/Llama-3.2-3B-Instruct
  • Qwen2.5 — por ejemplo, Qwen/Qwen2.5-0.5B-Instruct
  • Qwen3 — p. ej., Qwen/Qwen3-0.6B
  • Qwen3-VL — por ejemplo, Qwen/Qwen3-VL-2B-Instruct
  • Qwen3.5 — p. ej., Qwen/Qwen3.5-2B
  • Qwen3.6 — p. ej., Qwen/Qwen3.6-35B-A3B

No se garantiza la compatibilidad con todos los LLM. Si crees que un modelo debería ser compatible, no dudes en abrir un issue en GitHub o, mejor aún, enviar un pull request con los cambios necesarios.

Integraciones de entorno

Todos los entornos se conectan al mismo slot environment_factory, por lo que son intercambiables a nivel de TRL: elige el cuyo ecosistema se ajuste a tu tarea:

IntegraciónEn qué consisteÚsalo cuando
OpenEnvEl estándar de entorno abierto (API de estilo Gymnasium, servida a través de WebSocket o ejecución en contenedores), respaldado por Hugging Face y la comunidad.Estás usando un entorno OpenEnv listo para usar del Hub, o definiendo el tuyo propio según el estándar abierto (p. ej., Wordle, Sudoku, Catch).
OpenRewardUna integración con entornos que hablan ORS (el catálogo de openreward.ai o su propio servidor ORS); las tareas y las recompensas se sirven a través de HTTP.Deseas entrenar contra un entorno ORS: el catálogo (por ejemplo, Eigent/SETA), uno que alojes en tu propia infraestructura, o un servidor local que estés desarrollando.
HarborUna integración con los conjuntos de tareas de Harbor: cada tarea es una instrucción, una imagen de sandbox real (docker, e2b, …) y un verificador dentro del sandbox.Deseas entrenar contra una suite de tareas de Harbor: un árbol de tareas, cada una un sandbox autónomo más un verificador (p. ej., un agente de análisis de datos que explora archivos en un sandbox y escribe una respuesta que un corrector verifica).

Entrenamiento de modelos de visión y lenguaje

GRPO admite el entrenamiento de modelos de visión-lenguaje (VLM) en conjuntos de datos multimodales que contienen tanto texto como imágenes.

Modelos compatibles

Probado con:

  • Gemma3 — p. ej., google/gemma-3-4b-it
  • LLaVA-NeXT — p. ej., llava-hf/llava-v1.6-mistral-7b-hf
  • Qwen2-VL — por ejemplo, Qwen/Qwen2-VL-2B-Instruct
  • Qwen2.5-VL — por ejemplo, Qwen/Qwen2.5-VL-3B-Instruct
  • SmolVLM2 — por ejemplo, HuggingFaceTB/SmolVLM2-2.2B-Instruct

No se garantiza la compatibilidad con todos los VLM. Si crees que un modelo debería ser compatible, no dudes en abrir un issue en GitHub o, mejor aún, enviar un pull request con los cambios necesarios.

Inicio rápido

Use grpo_vlm.py para afinar un VLM. Comando de ejemplo para entrenar en lmms-lab/multimodal-open-r1-8k-verified:

torchrun --nproc_per_node 8 examples/grpo_visual_math/grpo_visual_math.py \
  --deepspeed examples/deepspeed_configs/zero3.json \
  --model_name_or_path Qwen/Qwen2.5-VL-3B-Instruct \
  --output_dir grpo-Qwen2.5-VL-3B-Instruct \
  --learning_rate 1e-5 \
  --dtype bfloat16 \
  --max_completion_length 1024 \
  --use_vllm \
  --vllm_mode colocate \
  --use_peft \
  --lora_target_modules "q_proj", "v_proj" \
  --log_completions

Consejos de configuración

  • Usar LoRA en las capas de proyección de visión-lenguaje
  • Habilitar la cuantización de 4 bits para reducir el uso de memoria
  • Los VLM son intensivos en memoria: comience con tamaños de lote más pequeños
  • La mayoría de los modelos son compatibles con vLLM (modos server y colocate)

Formato de datos

Cada muestra de entrenamiento debe incluir:

  • prompt: Texto formateado mediante la plantilla de chat del procesador
  • image/images: Imagen PIL o lista de Imágenes PIL

El trainer maneja automáticamente la conversión de imagen a tensor a través del procesador de imágenes del modelo.

GRPOTrainer

clase trl.GRPOTrainer

< >

( model: str | PreTrainedModel | PeftModelreward_funcs: str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]] | list[str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]]] | None = Noneargs: trl.trainer.grpo_config.GRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = Nonereward_processing_classes: transformers.tokenization_utils_base.PreTrainedTokenizerBase | list[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)quantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Nonerollout_func: collections.abc.Callable[[list[str], 'GRPOTrainer'], dict[str, typing.Any]] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset]] | None = None )

Parámetros

  • model (str o PreTrainedModel o PeftModel) — Modelo que se va a entrenar. Puede ser:
    • Una cadena, que es el model id de un modelo preentrenado alojado en un repositorio de modelos en huggingface.co, o una ruta a un directorio que contiene los pesos del modelo guardados con save_pretrained, por ejemplo, './my_model_directory/'. El modelo se carga usando <ModelArchitecture>.from_pretrained (donde <ModelArchitecture> se deriva de la configuración del modelo) con los argumentos de palabra clave en args.model_init_kwargs. Si dtype no se especifica en args.model_init_kwargs, el valor predeterminado es float32. Esto difiere de from_pretrained, donde (desde Transformers v5) el dtype se infiere de la configuración del modelo.
    • Un objeto PreTrainedModel. Solo se admiten modelos de lenguaje causales.
    • Un objeto PeftModel. Solo se admiten modelos de lenguaje causales.
  • reward_funcs (RewardFunc | list[RewardFunc], opcional) — Funciones de recompensa que se usarán para calcular las recompensas. Para calcular las recompensas, llamamos a todas las funciones de recompensa con los prompts y las completions y sumamos las recompensas. Puede omitirse cuando la recompensa se proporciona por el entorno a través de environment_factory (ver abajo). Puede ser:
    • Una única función de recompensa, como

      • Una cadena: el ID del modelo de un modelo preentrenado alojado en un repositorio de modelos en huggingface.co, o una ruta a un directorio que contiene los pesos del modelo guardados con save_pretrained, por ejemplo, './my_model_directory/'. El modelo se carga con from_pretrained usando num_labels=1 y los argumentos de palabra clave en args.model_init_kwargs.

      • Un objeto PreTrainedModel: solo se admiten modelos de clasificación de secuencias.

      • Una función de recompensa personalizada: la función recibe los prompts y las completaciones generadas, además de cualquier columna adicional del conjunto de datos. Debe devolver una lista de recompensas. Las funciones de recompensa personalizadas pueden ser síncronas o asíncronas y también pueden devolver None cuando la recompensa no es aplicable a esas muestras. Esto es útil para el entrenamiento multitarea, donde diferentes funciones de recompensa se aplican a diferentes tipos de muestras. Cuando una función de recompensa devuelve None para una muestra, esa función de recompensa se excluye del cálculo de la recompensa para esa muestra. Para más detalles, consulte Usar una función de recompensa personalizada.

        El estado del trainer también se pasa a la función de recompensa. El estado del trainer es una instancia de TrainerState y se puede acceder a él mediante el argumento trainer_state de la firma de la función de recompensa.

    • Una lista de funciones de recompensa, donde cada elemento puede ser independientemente cualquiera de los tipos anteriores. Se permite mezclar diferentes tipos dentro de la lista (p. ej., un ID de modelo en formato de cadena y una función de recompensa personalizada).

  • args (GRPOConfig, opcional) — Configuración para este entrenador. Si es None, se utiliza una configuración predeterminada.
  • train_dataset (Dataset o IterableDataset, opcional) — Dataset para usar en el entrenamiento. Debe incluir una columna "prompt". Cualquier columna adicional en el dataset se ignora. El formato de las muestras puede ser:
    • Estándar: Cada muestra contiene texto plano.
    • Conversacional: Cada muestra contiene mensajes estructurados (p. ej., rol y contenido).

    Puede omitirse solo cuando se proporciona un environment_factory y el entorno posee (o genera de forma procedural) los datos, devolviendo el prompt desde su método reset(). En ese caso, max_steps debe establecerse para definir la duración del entrenamiento.

    Cuando train_dataset es un IterableDataset (por ejemplo, un dataset de streaming), max_steps debe establecerse en los argumentos de entrenamiento, ya que su longitud no se puede inferir y se requiere el número total de pasos de entrenamiento para acotar el bucle de entrenamiento y configurar el programador de tasa de aprendizaje.

  • eval_dataset (Dataset, IterableDataset, DatasetDict, IterableDatasetDict o dict[str, Dataset | IterableDataset]) — Conjunto de datos para usar en la evaluación. Debe cumplir los mismos requisitos que train_dataset.
  • processing_class (PreTrainedTokenizerBase, ProcessorMixin, opcional) — Clase de procesamiento utilizada para procesar los datos. El lado de relleno debe estar configurado en “left”. Si es None, la clase de procesamiento se carga desde el nombre del modelo con from_pretrained. Debe establecerse un token de relleno, tokenizer.pad_token. Si la clase de procesamiento no ha establecido un token de relleno, se utilizará tokenizer.eos_token como valor predeterminado.
  • reward_processing_classes (PreTrainedTokenizerBase o list[PreTrainedTokenizerBase], opcional) — Clases de procesamiento correspondientes a las funciones de recompensa especificadas en reward_funcs. Puede ser:
    • Una única clase de procesamiento: se utiliza cuando reward_funcs contiene solo una función de recompensa.
    • Una lista de clases de procesamiento: debe coincidir con el orden y la longitud de las funciones de recompensa en reward_funcs. Si se establece en None, o si un elemento de la lista correspondiente a un PreTrainedModel es None, el tokenizador del modelo se carga automáticamente usando from_pretrained. Para los elementos de reward_funcs que son funciones de recompensa personalizadas (no PreTrainedModel), las entradas correspondientes en reward_processing_classes se ignoran.
  • callbacks (lista de TrainerCallback, opcional) — Lista de callbacks para personalizar el bucle de entrenamiento. Se añadirán a la lista de callbacks predeterminados detallada en aquí.

    Si deseas eliminar uno de los callbacks predeterminados, utiliza el método remove_callback.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], opcional, por defecto (None, None)) — Una tupla que contiene el optimizador y el programador a utilizar. Por defecto, se utilizará una instancia de AdamW en su modelo y un programador dado por get_linear_schedule_with_warmup controlado por args.
  • quantization_config (BitsAndBytesConfig, opcional) — Configuración de cuantización utilizada al cargar el modelo desde un identificador de modelo. Combínala con peft_config para el entrenamiento QLoRA. Se ignora si el modelo ya está instanciado.
  • peft_config (PeftConfig, opcional) — Configuración de PEFT utilizada para envolver el modelo. Si es None, el modelo no se envuelve.
  • tools (lista de Callable, opcional) — Una lista de funciones de herramientas invocables (síncronas o asíncronas) que el modelo puede invocar durante la generación. Cada herramienta debe ser una función de Python estándar con argumentos y valores de retorno con anotaciones de tipo adecuadas, y una docstring en estilo Google que describa su propósito, argumentos y valor de retorno. Para más detalles, consulte: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. El modelo utiliza el nombre de la función, las anotaciones de tipo y la docstring para determinar cómo llamarla. Asegúrese de que la plantilla de chat del modelo admita el uso de herramientas y de que haya sido afinada para la invocación de herramientas.
  • rollout_func (RolloutFunc, opcional) — Función que se utilizará para generar las completaciones. Recibe la lista de prompts asignados al proceso actual y la instancia del trainer. Debe devolver un dict con los campos "prompt_ids", "completion_ids" y "logprobs", y puede devolver opcionalmente "logprob_token_ids" (con la misma forma que "logprobs"). Cualquier otro campo se reenvía a las funciones de recompensa. La función recibe la porción de prompts por proceso sin duplicación; es responsable de devolver el número correcto de completaciones por prompt (ver num_generations / num_generations_eval en el trainer). Esta función es experimental y puede cambiar o eliminarse en cualquier momento sin previo aviso.
  • environment_factory (EnvironmentFactory o dict[str, EnvironmentFactory], opcional) — Un callable que crea y devuelve una instancia de entorno, o un diccionario que mapea nombres de entornos a tales callables. La clase de entorno debe definir métodos que se puedan invocar como herramientas durante la generación. Cada método debe cumplir con los mismos requisitos que las tools descritas anteriormente. El entorno también debe implementar un método reset que se pueda usar para restablecer el estado entre generaciones. El método reset debe devolver None o una cadena de texto: cuando devuelve una cadena, esta se añade al último mensaje de usuario antes de la generación. El entorno también puede definir un método get_reward que no tome argumentos y devuelva un float: cuando está presente, el entorno posee la recompensa, y get_reward se llama una vez por cada rollout completado para puntuarlo desde el estado interno del entorno. Actúa como una fuente de recompensa adicional (con peso 1, registrada bajo el nombre de la clase del entorno) junto a reward_funcs, que luego se vuelve opcional.

    Con un único callable, todos los ejemplos utilizan el mismo entorno, con una instancia por rollout para que sus interacciones permanezcan aisladas. Con un diccionario, cada ejemplo debe incluir un campo environment que seleccione su entorno por nombre, y solo las herramientas de ese entorno se exponen en su prompt, lo que permite mezclar tareas en una sola ejecución (p. ej., un entorno de programación y un juego). Esta función es experimental y puede cambiar o eliminarse en cualquier momento sin previo aviso.

Trainer para el método de Group Relative Policy Optimization (GRPO). Este algoritmo fue propuesto inicialmente en el artículo DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models.

Ejemplo:

>>> from trl import GRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

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

>>> trainer = GRPOTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     reward_funcs=accuracy_reward,
...     train_dataset=dataset,
... )
>>> trainer.train()

entrenar

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

Parámetros

  • resume_from_checkpoint (str o bool, opcional) — Si es una str, ruta local a un punto de control guardado por una instancia anterior de Trainer. Si es un bool y es igual a True, carga el último punto de control en args.output_dir guardado por una instancia anterior de Trainer. Si está presente, el entrenamiento se reanudará desde los estados del modelo/optimizador/planificador cargados aquí.
  • trial (optuna.Trial o dict[str, Any], opcional) — La ejecución del ensayo o el diccionario de hiperparámetros para la búsqueda de hiperparámetros.
  • ignore_keys_for_eval (list[str], opcional) — Una lista de claves en la salida de tu modelo (si es un diccionario) que deben ignorarse al recopilar predicciones para la evaluación durante el entrenamiento.

Devuelve

~trainer_utils.TrainOutput

Objeto que contiene el número de pasos globales, la pérdida de entrenamiento y las métricas.

Punto de entrada principal del entrenamiento.

save_model

< >

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

Guardará el modelo, por lo que podrás recargarlo usando from_pretrained().

Solo se guardará desde el proceso principal.

push_to_hub

< >

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

Parámetros

  • commit_message (str, opcional, valor predeterminado "End of training") — Mensaje para el commit al hacer push.
  • blocking (bool, opcional, valor predeterminado True) — Si la función debe devolver el control solo cuando el git push haya terminado.
  • token (str, opcional, valor predeterminado None) — Token con permiso de escritura para sobrescribir los argumentos originales de Trainer.
  • revision (str, opcional) — La revisión de git desde la que se realizará el commit. Por defecto, es la cabecera de la rama “main”.
  • private (bool, opcional) — Si se debe hacer el repositorio privado cuando se crea. El valor predeterminado es args.hub_private_repo. No tiene efecto si el repositorio ya existe.
  • kwargs (dict[str, Any], opcional) — Argumentos de palabra clave adicionales que se pasan a ~Trainer.create_model_card.

Sube self.model y self.processing_class al hub de modelos de 🤗 en el repositorio self.args.hub_model_id.

GRPOConfig

clase trl.GRPOConfig

< >

( 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: transformers.trainer_utils.SchedulerType | str = 'linear'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 | None = Nonegradient_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 = 10logging_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 = Falserestore_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 | None = 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 = Nonetrust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonedisable_dropout: bool = Falsecast_lm_head_to_fp32: bool = Falsenum_generations: int | None = 8num_generations_eval: int | None = Nonemax_completion_length: int | None = 512ds3_gather_for_generation: bool = Trueshuffle_dataset: bool | None = Truepad_to_multiple_of: int | str | None = 'auto'generation_batch_size: int | None = Nonesteps_per_generation: int | None = Nonetemperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonegeneration_kwargs: dict | str | None = Nonechat_template_kwargs: dict | str | None = Nonerepetition_penalty: float = 1.0cache_implementation: str | None = Noneuse_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_model_impl: str = 'vllm'vllm_enable_sleep_mode: bool = Falsevllm_structured_outputs_regex: str | None = Nonevllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8000vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.3vllm_max_model_length: int | None = Nonevllm_tensor_parallel_size: int = 1beta: float = 0.0num_iterations: int = 1epsilon: float = 0.2delta: float | None = Noneepsilon_high: float | None = Nonesapo_temperature_neg: float = 1.05sapo_temperature_pos: float = 1.0vespo_k_pos: float = 2.0vespo_lambda_pos: float = 3.0vespo_k_neg: float = 3.0vespo_lambda_neg: float = 2.0importance_sampling_level: str = 'token'reward_weights: list[float] | None = Nonemulti_objective_aggregation: str = 'sum_then_normalize'scale_rewards: str = 'group'loss_type: str = 'dapo'mask_truncated_completions: bool = Falsesync_ref_model: bool = Falseref_model_mixup_alpha: float = 0.6ref_model_sync_steps: int = 512top_entropy_quantile: float = 1.0entropy_coef: float = 0.0use_adaptive_entropy: bool = Falseentropy_coef_min: float = 0.0entropy_coef_max: float = 1.0entropy_coef_delta: float = 0.005entropy_target: float = 0.2max_tool_calling_iterations: int | None = Nonevllm_importance_sampling_correction: bool = Truevllm_importance_sampling_mode: str = 'sequence_mask'vllm_importance_sampling_clip_max: float | None = 3.0vllm_importance_sampling_clip_min: float | None = Noneoff_policy_mask_threshold: float | None = Noneuse_bias_correction_kl: bool = Truelog_completions: bool = Falselog_multimodal: bool = Truenum_completions_to_print: int | None = Nonelog_unique_prompts: bool = Falselog_completions_hub_repo: str | None = Noneuse_transformers_continuous_batching: bool = Falsetransformers_continuous_batching_config: dict | str | None = Noneuse_transformers_paged: bool = Falsevllm_importance_sampling_cap: float | None = None )

Parámetros que controlan el modelo y el modelo de referencia

  • model_init_kwargs (str o dict[str, Any], opcional) — Argumentos de palabra clave para from_pretrained, utilizados cuando el argumento model del GRPOTrainer se proporciona como una cadena de caracteres. El valor de revision también se utiliza al cargar las clases de procesamiento.
  • trust_remote_code (bool, opcional, valor predeterminado False) — Si se permite cargar modelos y tokenizadores que incluyen código Python personalizado desde el Hub. Se reenvía a from_pretrained y from_pretrained. También se aplica a la carga de modelos de recompensa y tokenizadores de recompensa.
  • router_aux_loss_coef (float, opcional) — Coeficiente de la pérdida auxiliar de equilibrado de carga para modelos Mixture-of-Experts (MoE), que se añade a la pérdida de entrenamiento con este peso. Si no se establece, se utiliza el valor declarado en la configuración del modelo. Establezca 0.0 para desactivarlo. Falla si se utiliza con un modelo que no es MoE.
  • disable_dropout (bool, opcional, valor predeterminado False) — Si se deshabilita el dropout en el modelo. Esto es útil para el entrenamiento con un modelo de referencia, ya que evita que el modelo genere logprobs diferentes para la misma entrada.
  • cast_lm_head_to_fp32 (bool, opcional, valor predeterminado False) — Si se debe convertir la cabeza de modelado de lenguaje de los modelos de política y referencia a float32. Como se recomienda en la receta ScaleRL. Esta opción solo se admite cuando el modelo tiene capas de incrustación de palabras y cabeza de modelado de lenguaje no vinculadas, es decir, cuando tie_word_embeddings en la configuración del modelo es False.

Parámetros que controlan el preprocesamiento de datos

  • remove_unused_columns (bool, opcional, valor predeterminado False) — Indica si se debe conservar únicamente la columna "prompt" en el conjunto de datos. Si utiliza una función de recompensa personalizada que requiere cualquier columna distinta de "prompts" y "completions", debe mantener este valor en False.
  • num_generations (int, opcional, por defecto 8) — Número de generaciones por prompt para muestrear. El tamaño de lote efectivo (num_processes * per_device_batch_size * gradient_accumulation_steps) debe ser divisible exactamente por este valor.
    • gradient_accumulation_steps) debe ser divisible exactamente por este valor.
  • num_generations_eval (int, opcional) — Número de generaciones para muestrear durante la evaluación. Esto permite usar menos generaciones durante la evaluación para ahorrar cómputo. Si es None, usa el valor de num_generations.
  • max_completion_length (int o None, opcional, valor predeterminado 512) — Longitud máxima de la generación completada.
  • ds3_gather_for_generation (bool, opcional, valor predeterminado True) — Esta configuración se aplica a DeepSpeed ZeRO-3. Si está habilitada, los pesos del modelo de política se recogen para la generación, mejorando la velocidad de generación. Sin embargo, deshabilitar esta opción permite entrenar modelos que superan la capacidad de VRAM de una sola GPU, aunque a costa de una generación más lenta. Deshabilitar esta opción no es compatible con la generación de vLLM.
  • shuffle_dataset (bool, opcional, valor predeterminado True) — Si se debe barajar el conjunto de datos de entrenamiento.
  • pad_to_multiple_of (int o str, opcional, valor predeterminado "auto") — Si se establece, los ids de los prompts y los ids de las completions se rellenarán hasta un múltiplo de este valor. "auto" rellena hasta un múltiplo de 128 en Neuron (AWS Trainium), que compila una vez por forma de entrada, y no rellena en otros entornos.

Parámetros que controlan la generación

  • generation_batch_size (int, opcional) — Tamaño de lote a utilizar para la generación. Si es None, el valor predeterminado es el tamaño de lote efectivo de entrenamiento: per_device_train_batch_size * num_processes * steps_per_generation. En otras palabras, se procesa un lote de generación por paso de optimización. Es mutuamente excluyente con steps_per_generation.
  • steps_per_generation (int, opcional) — Número de pasos por generación. Si es None, el valor predeterminado es gradient_accumulation_steps. Es mutuamente excluyente con generation_batch_size.
  • temperature (float, opcional, valor predeterminado 1.0) — Temperatura para el muestreo. A mayor temperatura, más aleatorias son las completaciones.
  • top_p (float, opcional, valor predeterminado 1.0) — Flotante que controla la probabilidad acumulada de los tokens superiores a considerar. Debe estar en (0, 1]. Establecerlo en 1.0 para considerar todos los tokens.
  • top_k (int, opcional, valor predeterminado 0) — Número de tokens del vocabulario con mayor probabilidad que se conservan para el filtrado top-k. Si es 0, el filtrado top-k se desactiva y se consideran todos los tokens.
  • min_p (float, opcional) — Probabilidad mínima del token, que se escala por la probabilidad del token más probable. Debe ser un valor entre 0.0 y 1.0. Los valores típicos están en el rango 0.01-0.2.
  • generation_kwargs (dict[str, Any], opcional) — Argumentos de palabra clave adicionales para pasar a GenerationConfig (si se usa transformers) o a SamplingParams (si se usa vLLM) al muestrear las completaciones. Esto se puede usar para personalizar aún más el comportamiento de la generación, como establecer suppress_tokens, num_beams, etc. Si contiene claves que entran en conflicto con los otros parámetros de generación (como min_p, top_p, etc.), los sobrescribirán.
  • chat_template_kwargs (dict[str, Any], opcional) — Argumentos de palabra clave adicionales para pasar a la función apply_chat_template al generar las completaciones.
  • repetition_penalty (float, opcional, valor predeterminado 1.0) — Flotante que penaliza los nuevos tokens en función de si aparecen en el prompt y en el texto generado hasta el momento. Los valores > 1.0 animan al modelo a usar tokens nuevos, mientras que los valores < 1.0 animan al modelo a repetir tokens.
  • cache_implementation (str, opcional) — Implementación del método de caché para una generación más rápida cuando use_vllm está establecido en False.

Parámetros que controlan la aceleración de la generación impulsada por vLLM

  • use_vllm (bool, opcional, valor predeterminado False) — Si se usa vLLM para generar completions. Si se establece en True, el trainer usará vLLM para la generación en lugar del método predeterminado model.generate(). Requiere que vllm esté instalado.
  • vllm_mode (str, opcional, por defecto "colocate") — Modo a usar para la integración de vLLM cuando use_vllm está establecido en True. Debe ser uno de "server" o "colocate".
    • "server": El trainer enviará solicitudes de generación a un servidor vLLM separado. Asegúrate de que un servidor vLLM esté en ejecución (inícialo con vllm serve).
    • "colocate": vLLM se ejecutará en el mismo proceso y compartirá las GPU de entrenamiento. Esto evita la necesidad de un servidor separado, pero puede provocar una contención de recursos con el entrenamiento.
  • vllm_model_impl (str, opcional, valor predeterminado "vllm") — Implementación del modelo a usar para vLLM. Debe ser "transformers" o "vllm". "transformers": usa el backend transformers para la implementación del modelo. "vllm": usa la biblioteca vllm para la implementación del modelo.
  • vllm_enable_sleep_mode (bool, opcional, valor predeterminado False) — Activa el modo de suspensión de vLLM para descargar los pesos y la caché durante el paso del optimizador. Mantiene bajo el uso de memoria de GPU, pero despertar el motor añade latencia de transferencia entre el host y el dispositivo.
  • vllm_structured_outputs_regex (str, opcional) — Expresión regular para las salidas estructuradas de vLLM. Si es None (valor predeterminado), las salidas estructuradas están deshabilitadas.

Parámetros que controlan el servidor de vLLM (solo se usan cuando `vllm_mode` es `"server"`)

  • vllm_server_base_url (str, opcional) — URL base del servidor vLLM (p. ej., "http://localhost:8000"). Si se proporciona, vllm_server_host y vllm_server_port se ignoran.
  • vllm_server_host (str, opcional, valor predeterminado "0.0.0.0") — Host del servidor de vLLM al que conectarse. Se ignora si se proporciona vllm_server_base_url.
  • vllm_server_port (int, opcional, valor predeterminado 8000) — Puerto del servidor vLLM al que conectarse. Se ignora si se proporciona vllm_server_base_url.
  • vllm_server_timeout (float, opcional, valor predeterminado 240.0) — Duración total del tiempo de espera, en segundos, para que el servidor vLLM esté en funcionamiento. Si el servidor no está en funcionamiento después del tiempo de espera, se lanza un ConnectionError.
  • vllm_group_port (int, opcional, valor predeterminado 51216) — Número de puerto para el grupo de actualización de pesos. Se utiliza para comunicarse con el servidor de vLLM. A menos que el puerto esté ocupado, no es necesario cambiarlo.

Parámetros que controlan la ejecución de vLLM colocada (solo se usan cuando `vllm_mode` es `"colocate"`)

  • vllm_gpu_memory_utilization (float, opcional, valor predeterminado 0.3) — Controla la utilización de la memoria de GPU para vLLM. Esta configuración solo se aplica cuando vllm_mode está establecido en "colocate". Si estás usando vllm_mode="server", este parámetro debe pasarse por separado al iniciar el servidor de vLLM mediante la bandera --vllm_gpu_memory_utilization.
  • vllm_max_model_length (int, opcional) — Ventana de contexto para vLLM. Establézcala al menos en la longitud máxima de los prompts del conjunto de datos más max_completion_length; si se omite, se infiere desde la configuración del modelo.
  • vllm_tensor_parallel_size (int, opcional, valor predeterminado 1) — Controla el tamaño de paralelismo de tensores para vLLM. Esta configuración solo se aplica cuando vllm_mode está establecido en "colocate". Si está utilizando vllm_mode="server", este parámetro debe pasarse por separado al iniciar el servidor de vLLM mediante la bandera --vllm_tensor_parallel_size.

Parámetros que controlan el entrenamiento

  • beta (float, opcional, valor predeterminado 0.0) — Coeficiente KL. Si es 0.0 (predeterminado), el modelo de referencia no se carga, lo que reduce el uso de memoria y mejora la velocidad de entrenamiento. DeepSeek-R1 incentiviza el razonamiento en LLMs mediante el aprendizaje por refuerzo utiliza un valor de 0.001.
  • num_iterations (int, opcional, valor predeterminado 1) — Número de iteraciones por lote (denotado como μ en el algoritmo).
  • epsilon (float, opcional, valor predeterminado 0.2) — Valor para el recorte.
  • delta (float, opcional) — Habilita el límite superior de recorte en la pérdida de GRPO de doble lado cuando se establece como un float. Si es None (predeterminado), se utiliza el recorte estándar de GRPO. Se recomienda que sea mayor que 1 + ε cuando está habilitado. Este método se introduce en el informe técnico de INTELLECT-2.
  • epsilon_high (float, opcional) — Valor superior de epsilon para el recorte. Si no se especifica, toma por defecto el mismo valor que el límite inferior especificado en el argumento epsilon. El artículo DAPO recomienda 0.28. Cuando se usa con loss_type='cispo', esto corresponde al parámetro ε_max especificado en el artículo ScaleRL y toma por defecto el valor recomendado 5.0.
  • sapo_temperature_neg (float, opcional, valor predeterminado 1.05) — Temperatura para los tokens con puntuaciones de ventaja no positivas, utilizada en la función de pérdida sapo. Este parámetro se introduce en el artículo Soft Adaptive Policy Optimization.
  • sapo_temperature_pos (float, opcional, valor predeterminado 1.0) — Temperatura para los tokens con puntuaciones de ventaja positivas, utilizada en la función de pérdida sapo. Este parámetro se introduce en el artículo Soft Adaptive Policy Optimization.
  • vespo_k_pos (float, opcional, valor predeterminado 2.0) — parámetro k para ventajas positivas, es el exponente de potencia en la pérdida VESPO. Controla con qué agresividad se reduce el peso de las muestras con pesos de importancia bajos (cuando la razón de muestreo de importancia < 1).
  • vespo_lambda_pos (float, opcional, valor predeterminado 3.0) — parámetro lambda para ventajas positivas, es el factor de decaimiento en la pérdida VESPO. Controla con qué agresividad se reduce el peso de las muestras con pesos de importancia altos (cuando la razón de muestreo de importancia > 1).
  • vespo_k_neg (float, opcional, valor predeterminado 3.0) — parámetro k para las ventajas negativas, es el exponente de potencia en la pérdida VESPO. Controla con qué agresividad se reduce el peso de las muestras con pesos de importancia bajos (cuando la razón de muestreo de importancia < 1).
  • vespo_lambda_neg (float, opcional, valor predeterminado 2.0) — parámetro lambda para las ventajas negativas, es el factor de decaimiento exponencial en la pérdida VESPO. Controla la agresividad con la que se reduce el peso de las muestras con pesos de importancia altos (cuando la proporción de muestreo de importancia > 1).
  • importance_sampling_level (str, opcional, valor predeterminado "token") — Controla si las proporciones de muestreo de importancia se calculan a nivel de "token" o a nivel de "sequence". "token" mantiene las proporciones crudas de log-probabilidad por token (un peso por token). "sequence" promedia las proporciones de log-probabilidad entre los tokens válidos para producir una única proporción por secuencia. El artículo de GSPO muestra que el muestreo a nivel de secuencia suele producir un entrenamiento más estable y una mejor alineación con las recompensas a nivel de secuencia.
  • reward_weights (list[float], opcional) — Pesos para cada función de recompensa. Debe coincidir con el número de funciones de recompensa. Si es None, todas las recompensas se ponderan por igual con un peso de 1.0.
  • multi_objective_aggregation (str, opcional, por defecto "sum_then_normalize") — Método para agregar múltiples funciones de recompensa. Los valores admitidos son:
    • "sum_then_normalize" (predeterminado): primero suma las recompensas ponderadas de cada función de recompensa y luego aplica la escalada/normalización de recompensas especificada por scale_rewards (consulte scale_rewards para más detalles).
    • "normalize_then_sum": Primero normaliza/escala cada función de recompensa a lo largo de las generaciones (dentro de cada grupo), luego suma las recompensas normalizadas utilizando los pesos especificados. La recompensa agregada se normaliza a nivel de lote al formar las ventajas. Este es el enfoque sugerido en el artículo GDPO: Group reward-Decoupled Normalization Policy Optimization for Multi-reward RL Optimization.
  • scale_rewards (str o bool, opcional, por defecto "group") — Especifica la estrategia de escalado para las recompensas. Los valores admitidos son:
    • True o "group" (predeterminado): las recompensas se escalan por la desviación estándar dentro de cada grupo, garantizando una varianza unitaria dentro de un grupo.
    • "batch": las recompensas se escalan por la desviación estándar de todo el lote, tal como se recomienda en el artículo PPO Lite.
    • False o "none": no se aplica ninguna escalado. El artículo de Dr. GRPO recomienda no escalar las recompensas, ya que escalar por la desviación estándar introduce un sesgo de dificultad a nivel de pregunta.
  • loss_type (str, opcional, por defecto "dapo") — Especifica la formulación de pérdida a utilizar. Los valores admitidos son:
    • "grpo": Agrega las pérdidas a nivel de token normalizando sobre la longitud de la secuencia. No se recomienda debido al sesgo de longitud: este enfoque tiende a favorecer las finalizaciones más cortas con ventajas positivas y las más largas con ventajas negativas.
    • "dr_grpo": Agrega las pérdidas a nivel de token normalizando con una constante global. Este método se introdujo en el artículo Dr. GRPO para eliminar el sesgo de longitud. El valor de la constante corresponde a max_completion_length.
    • "dapo" (predeterminado): Agrega las pérdidas a nivel de token normalizando con el número de tokens activos en el lote acumulado global. Este método se introdujo en el artículo de DAPO para eliminar el sesgo de longitud.
    • "bnpo": Agrega las pérdidas a nivel de token normalizando con el número de tokens activos en el lote local. Tenga en cuenta que la normalización se realiza solo sobre el lote local, por lo que los resultados pueden variar ligeramente dependiendo del tamaño del lote local, a pesar de un tamaño de lote efectivo constante. Al usar per_device_train_batch_size==1, la pérdida es equivalente a la pérdida de GRPO.
    • "cispo": Recorta los pesos de muestreo por importancia en lugar de los pesos de muestreo por importancia escalados por la ventaja. Los pesos recortados se multiplican luego por las ventajas y los log probs del modelo de política. Las pérdidas de tokens individuales se agregan normalizando con el número de tokens activos en el lote acumulado global. Este método fue introducido en el artículo de MiniMax-M1.
    • "sapo": pérdida de Soft Adaptive Policy Optimization, tal como se introduce en el artículo de Soft Adaptive Policy Optimization. Sustituye el recorte duro por una compuerta suave y controlada por temperatura que atenúa de forma adaptativa las actualizaciones fuera de la política, al tiempo que preserva las señales de aprendizaje útiles.
    • "luspo": Pérdida de Length-Unbiased Sequence Policy Optimization. Una pérdida a nivel de secuencia que escala la pérdida de cada secuencia por su longitud. Esta es una modificación de GSPO y requiere importance_sampling_level="sequence". Introducida en el artículo de LUSPO.
    • "vespo": Variational Sequence-Level Soft Policy Optimization. Sustituye el recorte duro por una función de ponderación Gamma suave y asimétrica aplicada directamente a los pesos de importancia a nivel de secuencia. Introducida en el artículo de VESPO.
  • mask_truncated_completions (bool, opcional, valor predeterminado False) — Cuando está habilitado, las completas truncadas se excluyen del cálculo de la pérdida, evitando que se penalicen incorrectamente y se introduzca ruido durante el entrenamiento. Según el DAPO paper, esta es una buena práctica para la estabilidad del entrenamiento.
  • sync_ref_model (bool, opcional, valor predeterminado False) — Si se sincroniza el modelo de referencia con el modelo activo cada ref_model_sync_steps pasos, utilizando el parámetro ref_model_mixup_alpha. Esta sincronización proviene del artículo TR-DPO.
  • ref_model_mixup_alpha (float, opcional, valor predeterminado 0.6) — parámetro α del artículo TR-DPO, que controla la mezcla entre la política actual y la política de referencia anterior durante las actualizaciones. La política de referencia se actualiza según la ecuación: π_ref = α * π_θ + (1 - α) * π_ref_prev. Para usar este parámetro, debe establecer sync_ref_model=True.
  • ref_model_sync_steps (int, opcional, valor predeterminado 512) — parámetro τ del artículo TR-DPO, que determina la frecuencia con la que la política actual se sincroniza con la política de referencia. Para usar este parámetro, debes establecer sync_ref_model=True.
  • top_entropy_quantile (float, opcional, valor predeterminado 1.0) — Parámetro ρ de Beyond the 80/20 Rule. Mantiene en el término de pérdida de la política solo el cuantil superior-ρ de tokens según la entropía de la distribución de probabilidad en cada posición de la secuencia, mejorando los resultados. Rango: [0.0-1.0]. Un valor de 0.0 enmascara todos los tokens excepto el de mayor entropía; 1.0 conserva todos los tokens. El artículo recomienda un valor de 0.2. Si se usa con mask_truncated_completions=True, solo se consideran los tokens de las completas no truncadas.
  • entropy_coef (float, opcional, valor predeterminado 0.0) — Coeficiente del término de regularización de entropía en la pérdida. Un valor positivo añade un bono de entropía que fomenta la exploración evitando que la política colapse en salidas casi deterministas. El bono es siempre la entropía media por token, independientemente de loss_type; no se reescala para coincidir con la normalización de la política de un tipo de pérdida, por lo que entropy_coef tiene el mismo significado para cada tipo de pérdida. Cuando use_adaptive_entropy=True, este parámetro actúa como coeficiente inicial y se actualiza en cada paso del optimizador. No tiene efecto si se establece en 0.0 (valor predeterminado).
  • use_adaptive_entropy (bool, opcional, valor predeterminado False) — Si se debe usar el control de entropía adaptativa, introducido en Skywork-OR1. Cuando está habilitado, el coeficiente de entropía entropy_coef se actualiza en cada paso del optimizador: se incrementa en entropy_coef_delta cuando la entropía actual es inferior a entropy_target, y se decrementa en caso contrario. El coeficiente solo se aplica cuando la entropía es igual o inferior a entropy_target.
  • entropy_coef_min (float, opcional, valor predeterminado 0.0) — Límite inferior para el coeficiente de entropía al usar el control adaptativo de entropía.
  • entropy_coef_max (float, opcional, valor predeterminado 1.0) — Límite superior para el coeficiente de entropía al usar el control adaptativo de entropía.
  • entropy_coef_delta (float, opcional, valor predeterminado 0.005) — Tamaño del paso para ajustar el coeficiente de entropía en cada paso del optimizador durante el control adaptativo de la entropía.
  • entropy_target (float, opcional, valor predeterminado 0.2) — Entropía media por token objetivo (en nats) utilizada por el control adaptativo de la entropía. El coeficiente solo se aplica cuando la entropía actual cae por debajo o iguala este valor. Se mide sobre el mismo conjunto de tokens que la pérdida de la política: todos los tokens de la finalización por defecto, o solo el subconjunto de alta entropía cuando top_entropy_quantile < 1.0. Los modelos de lenguaje típicos tienen entropías por token en el rango de 2 a 10 nats, por lo que el valor predeterminado de 0.2 casi nunca activa la regularización (solo en caso de un colapso casi completo de la entropía); establézcalo cerca de la entropía que observe al inicio del entrenamiento (registrada como la métrica entropy) para que el bono se active antes de que la política colapse (y tenga en cuenta el subconjunto de tokens al usar top_entropy_quantile).
  • max_tool_calling_iterations (int, opcional) — Número máximo de turnos de llamada a herramientas al entrenar un agente. Si es None, no hay límite y la generación se detiene cuando el modelo genera un turno de respuesta sin llamadas a herramientas, cuando la finalización (todos los turnos y resultados de herramientas) alcanza max_completion_length tokens, o cuando la secuencia completa alcanza la longitud máxima del modelo (vllm_max_model_length con vllm_mode="colocate", o los max_position_embeddings del modelo en caso contrario).
  • vllm_importance_sampling_correction (bool, opcional, valor predeterminado True) — Indica si se debe aplicar Importance Sampling (IS) para corregir la discrepancia entre los logprobs de las finalizaciones de vLLM y los logprobs de entrenamiento recalculados. Si se establece en False, no se aplica IS independientemente de vllm_importance_sampling_mode. Cuando es True, el modo seleccionado determina cómo se calculan y limitan las proporciones de IS. Con top_p < 1, top_k > 0 o min_p > 0, los logprobs recalculados se normalizan sobre el conjunto de candidatos del que se muestreó cada token, lo que requiere vLLM 0.28 o posterior y, en modo servidor, un servidor iniciado con --return-sampling-mask (y --enable-scale-out desde vLLM 0.30); de lo contrario, las proporciones de IS estarán sesgadas. vLLM limita ese conjunto de candidatos con top_k, por lo que top_p < 1, min_p > 0 y las salidas estructuradas, que lo restringen a los tokens que permite la gramática, requieren top_k > 0 (p. ej. top_k=512). Las salidas estructuradas, que de otro modo harían estancarse el entrenamiento, también requieren ese conjunto de candidatos. vLLM también aplica repetition_penalty a los logprobs que devuelve, por lo que repetition_penalty != 1.0 requiere vllm_importance_sampling_correction=False.
  • vllm_importance_sampling_mode (str, opcional, por defecto "sequence_mask") — Especifica cómo se realiza el Importance Sampling cuando vllm_importance_sampling_correction=True. Los valores posibles son:
    • "token_truncate": IS truncado a nivel de token. Las proporciones por token se recortan a [C_min, C_max].
    • "token_mask": IS enmascarado a nivel de token. Las proporciones por token que están fuera de [C_min, C_max] se establecen en cero.
    • "sequence_truncate": IS truncada a nivel de secuencia. Una única proporción de secuencia se recorta a [C_min, C_max] y se aplica a todos los tokens de la secuencia.
    • "sequence_mask": IS con máscara a nivel de secuencia. Las secuencias con ratios fuera de [C_min, C_max] se excluyen.
  • vllm_importance_sampling_clip_max (float, opcional, valor predeterminado 3.0) — Límite superior de muestreo por importancia C_max utilizado por vllm_importance_sampling_mode. En los modos *_truncate, las proporciones de importancia se recortan por arriba en C_max. En los modos *_mask, las proporciones mayores que C_max se establecen en cero.
  • vllm_importance_sampling_clip_min (float, opcional) — Límite inferior de muestreo por importancia C_min utilizado por vllm_importance_sampling_mode. En los modos *_truncate, las proporciones se recortan por debajo en C_min. En los modos *_mask, las proporciones inferiores a C_min se establecen en cero. Para enmascarar estrictamente las proporciones inferiores a C_min sin límite superior, establezca vllm_importance_sampling_clip_max=None.
  • off_policy_mask_threshold (float, opcional) — Umbral para el enmascaramiento de secuencias fuera de política. Si es None, el enmascaramiento de secuencias fuera de política se desactiva. Cuando se establece, las secuencias con ventajas negativas y una alta divergencia de KL se enmascaran para estabilizar el entrenamiento. Este parámetro corresponde al umbral delta de la Ecuación 9 del artículo de DeepSeek-V3.2. Espera un valor positivo (p. ej., 0.5).
  • use_bias_correction_kl (bool, opcional, valor predeterminado True) — Si se debe multiplicar el término KL por la proporción de muestreo por importancia, de modo que el gradiente de KL se convierta en el gradiente no sesgado de KL inversa, tal como se describe en el paper de DeepSeek-V3.2. Esto cambia el gradiente de KL siempre que beta != 0, incluido en la política: la proporción es diferenciable, por lo que afecta al gradiente incluso donde su valor es exactamente 1. La propiedad de KL inversa no sesgada se cumple para importance_sampling_level="token"; con "sequence" se difunde un peso a nivel de secuencia sobre el KL por token.

Parámetros que controlan el registro

  • log_completions (bool, opcional, valor predeterminado False) — Indica si se debe registrar una muestra de pares (prompt, completion) cada logging_steps pasos. Si rich está instalado, imprime la muestra. Si el registro de wandb y/o trackio está habilitado, lo registra en wandb y/o trackio.
  • log_multimodal (bool, opcional, valor predeterminado True) — Si se registran o no los contenidos multimodales (imágenes, vídeos, etc.) junto con las completaciones. Desactive esta opción para reducir el tamaño del registro al usar datos multimodales de alta resolución.
  • num_completions_to_print (int, opcional) — Número de completions que se imprimen con rich. Si es None, se registran todas las completions.
  • log_unique_prompts (bool, opcional, valor predeterminado False) — Si se registran los prompts únicos. Si es True, solo se registran los prompts únicos. Si es False, se registran todos los prompts.
  • log_completions_hub_repo (str, opcional) — Repositorio de Hugging Face Hub donde se guardarán las completions. Debe ser un nombre de repositorio completo como 'username/reponame' o 'orgname/reponame', o simplemente 'reponame', en cuyo caso el repositorio se creará en el espacio de nombres del usuario de Hugging Face actualmente conectado. Tenga en cuenta que este repositorio será público a menos que establezca hub_private_repo=True o que el valor predeterminado de su organización sea crear repositorios privados.

Parámetros que controlan la aceleración de la generación mediante el lotes continuo de transformers

  • use_transformers_continuous_batching (bool, opcional, valor predeterminado False) — Si se debe utilizar el motor de lotes continuos de transformers para generar completados. Requiere transformers>=5.8.0.
  • transformers_continuous_batching_config (dict, opcional) — Argumentos de palabra clave para ContinuousBatchingConfig.

Parámetros obsoletos

  • use_transformers_paged —

    El parámetro use_transformers_paged está obsoleto y se eliminará en la versión v2.0.0. Utilice use_transformers_continuous_batching en su lugar.

  • vllm_importance_sampling_cap —

    El parámetro vllm_importance_sampling_cap está obsoleto y se eliminará en la versión v2.0.0. Utilice vllm_importance_sampling_clip_max en su lugar.

Clase de configuración para GRPOTrainer.

Esta clase incluye solo los parámetros específicos del entrenamiento con GRPO. Para obtener la lista completa de argumentos de entrenamiento, consulte la documentación de TrainingArguments. Tenga en cuenta que los valores predeterminados de esta clase pueden diferir de los de TrainingArguments.

Con HfArgumentParser podemos convertir esta clase en argumentos de argparse que se pueden especificar en la línea de comandos.

Estos parámetros tienen valores predeterminados diferentes de TrainingArguments:

  • logging_steps: El valor predeterminado es 10 en lugar de 500.
  • gradient_checkpointing: El valor predeterminado es True en lugar de False.
  • bf16: Por defecto, es True si fp16 no está establecido, en lugar de False.
  • learning_rate: El valor predeterminado es 1e-6 en lugar de 5e-5.
Update on GitHub