TRL documentation
GRPO Trainer
GRPO Trainer
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.

Nota: Las curvas de recompensa anteriores se generaron con
Qwen/Qwen2-0.5B-Instruct. Los resultados conQwen/Qwen2.5-0.5B-Instructserá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.

Generar completiones
En cada paso de entrenamiento, muestreamos un lote de prompts y generamos un conjunto de completaciones para cada prompt (denotado como ).
Cálculo de la ventaja
Para cada una de las 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:
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 puede causar un sesgo de dificultad a nivel de pregunta. Puedes desactivar este escalado estableciendo
scale_rewards=Falseen 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:
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:
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 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 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
betaen 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 , se puede configurar con num_iterations en GRPOConfig) aprovechando el objetivo sustituto recortado:
donde asegura que las actualizaciones no se desvíen excesivamente de la política de referencia al acotar la razón de políticas entre y . Cuando (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:
donde
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:
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:
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:
La función de soft-gating se define utilizando la función sigmoide como:
La temperatura se elige en función del signo de la ventaja :
Recomiendan usar temperaturas asimétricas, (los valores predeterminados son ). 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 proporcionantools.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). Es0.0cuando no se llamó a ninguna herramienta. Se registra solo cuando se proporcionantools.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 deget_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 porreward_weights).reward_std: La desviación estándar de las recompensas sumadas entre funciones (ponderadas porreward_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 cuandouse_vllm=Trueyvllm_importance_sampling_correction=True.sampling/sampling_logp_difference/max: La mayor diferencia absoluta de este tipo. Se registra solo cuandouse_vllm=Trueyvllm_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 porvllm_importance_sampling_mode(recortada a[C_min, C_max]para los modos*_truncatey establecida en cero para los modos*_mask). Se calcula sobre los tokens de la respuesta o sobre las secuencias para los modossequence_*. Se registra solo cuandouse_vllm=Trueyvllm_importance_sampling_correction=True.sampling/importance_sampling_ratio/mean: La media de la ratio de muestreo por importancia restringida. Se registra solo cuandouse_vllm=Trueyvllm_importance_sampling_correction=True.sampling/importance_sampling_ratio/max: La mayor proporción de muestreo por importancia restringida. Se registra solo cuandouse_vllm=Trueyvllm_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 cuandoentropy_coefes distinto de cero ouse_adaptive_entropy=True.entropy: Entropía media de las predicciones de tokens en las completaciones generadas. (Simask_truncated_completions=True, se excluyen los tokens de las secuencias enmascaradas.)entropy_coef: El coeficiente actual de regularización de entropía. Se registra cuandoentropy_coefes distinto de cero ouse_adaptive_entropy=True. Se actualiza una vez por paso del optimizador cuandouse_adaptive_entropy=True.aux_loss: La pérdida auxiliar de equilibrio de carga de un modelo Mixture-of-Experts, antes de que se escale porrouter_aux_loss_coefy se sume a la pérdida. Se registra solo cuando el modelo es un modelo MoE yrouter_aux_loss_coefes distinto de cero.kl: La divergencia KL media entre el modelo y el modelo de referencia, calculada sobre las completaciones generadas. Se registra solo sibetaes distinto de cero.clip_ratio/region_mean: La proporción de tokens (o secuencias, siimportance_sampling_level="sequence") las probabilidades donde el objetivo de GRPO se recorta para mantenerse dentro de la región de confianza: . Un valor más alto significa que se recortan más tokens, lo que limita cuánto puede cambiar la política .clip_ratio/low_mean: La proporción media de probabilidades de token (o de secuencia, siimportance_sampling_level="sequence") fueron recortadas en el límite inferior de la región de confianza: .clip_ratio/low_min: La fracción más pequeña de tokens por finalización (o de la secuencia en sí, siimportance_sampling_level="sequence") se recorta en el límite inferior de la región de confianza: .clip_ratio/high_mean: La proporción media de probabilidades de token (o de secuencia, siimportance_sampling_level="sequence") fueron recortadas en el límite superior de la región de confianza: .clip_ratio/high_max: La mayor fracción de tokens por finalización (o la secuencia en sí, siimportance_sampling_level="sequence") se recorta en el límite superior de la región de confianza: .cispo_clip_ratio: La proporción de pesos de muestreo por importancia de tokens (o de secuencias, siimportance_sampling_level="sequence") se recortaron enepsilon_highmientras tenían una ventaja positiva: . Se registra solo cuandoloss_type="cispo".vespo/phi_seq_mean: El valor promedio de la ponderación Gamma de VESPO aplicada a los pesos de importancia a nivel de secuencia. Los valores por debajo de1.0significan que las secuencias se están ponderando a la baja. Se registra solo cuandoloss_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 estableciendovllm_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.
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 -1Habilita 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_utilizationen 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_modeen 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=localhostyMASTER_PORT=12345para 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:
Aquí denota los prompts muestreados de alguna distribución de datos, y es la política implementada por el motor de entrenamiento. Con vLLM en el bucle, obtenemos una política de inferencia separada , por lo que el gradiente de política efectivo se convierte en
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 el peso de importancia, por ejemplo por token o por secuencia. Bajo TIS, las proporciones fuera del rango [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] se recortan,
El artículo original de TIS propuso un mecanismo de recorte de límite superior único, es decir, . 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 y mientras que en TRL usamos y .
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_percenten0.5(en lugar de0.9de transformers) para dejar suficiente VRAM para la pasada de retropropagación del entrenamiento. Redúcelo a0.3–0.4para 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 &
waitimport 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.
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ónlog_extra(column: str, values: list)para añadir columnas adicionales a la tabla de completados. Consulte el Ejemplo 6.log_metric: una funciónlog_metric(name: str, value: float)para registrar métricas escalares como gráficos junto akl,entropy, etc. Consulte el Ejemplo 6.environments: una lista de instancias de entorno, una por cada finalización. Solo está presente cuando se proporcionaenvironment_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étodoget_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 llamadaground_truth, la función se llamará conground_truthcomo argumento de palabra clave.
La forma más sencilla de cumplir con este requisito es usar
**kwargsen la firma de la función.Dependiendo del formato del conjunto de datos, la entrada variará:
- Para el formato estándar,
promptsycompletionsserán listas de cadenas de texto. - Para el formato conversacional,
promptsycompletionsserán listas de diccionarios de mensajes.
- Para el formato estándar,
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 rewardsPasar 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:
donde es la entropía media por token de la política y 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.2casi 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étricaentropy). Al usartop_entropy_quantile < 1.0,entropy_targetse 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 comoentropy, 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
toolspara 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
resety unget_rewardopcional que le permite poseer la recompensa. Useenvironment_factorycuando 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_factoryrequieretransformers>=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 devolverNoneo 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 unfloat: 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(), losGmiembros 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 quereset()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ón | En qué consiste | Úsalo cuando |
|---|---|---|
| OpenEnv | El 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). |
| OpenReward | Una 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. |
| Harbor | Una 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_completionsConsejos 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
serverycolocate)
Formato de datos
Cada muestra de entrenamiento debe incluir:
prompt: Texto formateado mediante la plantilla de chat del procesadorimage/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
< source >( 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 (
stro 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 enargs.model_init_kwargs. Sidtypeno se especifica enargs.model_init_kwargs, el valor predeterminado esfloat32. 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.
- 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,
- 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 deenvironment_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 usandonum_labels=1y los argumentos de palabra clave enargs.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
Nonecuando 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 devuelveNonepara 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_statede 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_factoryy el entorno posee (o genera de forma procedural) los datos, devolviendo el prompt desde su métodoreset(). En ese caso,max_stepsdebe establecerse para definir la duración del entrenamiento.Cuando
train_datasetes un IterableDataset (por ejemplo, un dataset de streaming),max_stepsdebe 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 quetrain_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_tokencomo valor predeterminado. - reward_processing_classes (PreTrainedTokenizerBase o
list[PreTrainedTokenizerBase], opcional) — Clases de procesamiento correspondientes a las funciones de recompensa especificadas enreward_funcs. Puede ser:- Una única clase de procesamiento: se utiliza cuando
reward_funcscontiene 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 enNone, o si un elemento de la lista correspondiente a un PreTrainedModel esNone, el tokenizador del modelo se carga automáticamente usando from_pretrained. Para los elementos dereward_funcsque son funciones de recompensa personalizadas (no PreTrainedModel), las entradas correspondientes enreward_processing_classesse ignoran.
- Una única clase de procesamiento: se utiliza cuando
- 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 deAdamWen su modelo y un programador dado por get_linear_schedule_with_warmup controlado porargs. - quantization_config (BitsAndBytesConfig, opcional) —
Configuración de cuantización utilizada al cargar el modelo desde un identificador de modelo. Combínala con
peft_configpara 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 (vernum_generations/num_generations_evalen el trainer). Esta función es experimental y puede cambiar o eliminarse en cualquier momento sin previo aviso. - environment_factory (
EnvironmentFactoryodict[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 lastoolsdescritas anteriormente. El entorno también debe implementar un métodoresetque se pueda usar para restablecer el estado entre generaciones. El métodoresetdebe devolverNoneo 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étodoget_rewardque no tome argumentos y devuelva unfloat: cuando está presente, el entorno posee la recompensa, yget_rewardse 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 areward_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
environmentque 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
< source >( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput
Parámetros
- resume_from_checkpoint (
strobool, opcional) — Si es unastr, ruta local a un punto de control guardado por una instancia anterior deTrainer. Si es unbooly es igual aTrue, carga el último punto de control en args.output_dir guardado por una instancia anterior deTrainer. Si está presente, el entrenamiento se reanudará desde los estados del modelo/optimizador/planificador cargados aquí. - trial (
optuna.Trialodict[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.
Guardará el modelo, por lo que podrás recargarlo usando from_pretrained().
Solo se guardará desde el proceso principal.
push_to_hub
< source >( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )
Parámetros
- commit_message (
str, opcional, valor predeterminado"End of training") — Mensaje para el commit al hacer push. - blocking (
bool, opcional, valor predeterminadoTrue) — Si la función debe devolver el control solo cuando elgit pushhaya terminado. - token (
str, opcional, valor predeterminadoNone) — 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 esargs.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
< source >( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: 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 (
strodict[str, Any], opcional) — Argumentos de palabra clave para from_pretrained, utilizados cuando el argumentomodeldel GRPOTrainer se proporciona como una cadena de caracteres. El valor derevisiontambién se utiliza al cargar las clases de procesamiento. - trust_remote_code (
bool, opcional, valor predeterminadoFalse) — 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. Establezca0.0para desactivarlo. Falla si se utiliza con un modelo que no es MoE. - disable_dropout (
bool, opcional, valor predeterminadoFalse) — 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 predeterminadoFalse) — 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, cuandotie_word_embeddingsen la configuración del modelo es False.
Parámetros que controlan el preprocesamiento de datos
- remove_unused_columns (
bool, opcional, valor predeterminadoFalse) — 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 enFalse. - num_generations (
int, opcional, por defecto8) — 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 esNone, usa el valor denum_generations. - max_completion_length (
intoNone, opcional, valor predeterminado512) — Longitud máxima de la generación completada. - ds3_gather_for_generation (
bool, opcional, valor predeterminadoTrue) — 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 predeterminadoTrue) — Si se debe barajar el conjunto de datos de entrenamiento. - pad_to_multiple_of (
intostr, 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 esNone, 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 consteps_per_generation. - steps_per_generation (
int, opcional) — Número de pasos por generación. Si esNone, el valor predeterminado esgradient_accumulation_steps. Es mutuamente excluyente congeneration_batch_size. - temperature (
float, opcional, valor predeterminado1.0) — Temperatura para el muestreo. A mayor temperatura, más aleatorias son las completaciones. - top_p (
float, opcional, valor predeterminado1.0) — Flotante que controla la probabilidad acumulada de los tokens superiores a considerar. Debe estar en (0, 1]. Establecerlo en1.0para considerar todos los tokens. - top_k (
int, opcional, valor predeterminado0) — Número de tokens del vocabulario con mayor probabilidad que se conservan para el filtrado top-k. Si es0, 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 entre0.0y1.0. Los valores típicos están en el rango0.01-0.2. - generation_kwargs (
dict[str, Any], opcional) — Argumentos de palabra clave adicionales para pasar a GenerationConfig (si se usa transformers) o aSamplingParams(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 establecersuppress_tokens,num_beams, etc. Si contiene claves que entran en conflicto con los otros parámetros de generación (comomin_p,top_p, etc.), los sobrescribirán. - chat_template_kwargs (
dict[str, Any], opcional) — Argumentos de palabra clave adicionales para pasar a la funciónapply_chat_templateal generar las completaciones. - repetition_penalty (
float, opcional, valor predeterminado1.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.0animan al modelo a usar tokens nuevos, mientras que los valores <1.0animan al modelo a repetir tokens. - cache_implementation (
str, opcional) — Implementación del método de caché para una generación más rápida cuandouse_vllmestá establecido enFalse.
Parámetros que controlan la aceleración de la generación impulsada por vLLM
- use_vllm (
bool, opcional, valor predeterminadoFalse) — Si se usa vLLM para generar completions. Si se establece enTrue, el trainer usará vLLM para la generación en lugar del método predeterminado model.generate(). Requiere quevllmesté instalado. - vllm_mode (
str, opcional, por defecto"colocate") — Modo a usar para la integración de vLLM cuandouse_vllmestá establecido enTrue. 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 convllm 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 backendtransformerspara la implementación del modelo."vllm": usa la bibliotecavllmpara la implementación del modelo. - vllm_enable_sleep_mode (
bool, opcional, valor predeterminadoFalse) — 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 esNone(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_hostyvllm_server_portse ignoran. - vllm_server_host (
str, opcional, valor predeterminado"0.0.0.0") — Host del servidor de vLLM al que conectarse. Se ignora si se proporcionavllm_server_base_url. - vllm_server_port (
int, opcional, valor predeterminado8000) — Puerto del servidor vLLM al que conectarse. Se ignora si se proporcionavllm_server_base_url. - vllm_server_timeout (
float, opcional, valor predeterminado240.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 unConnectionError. - vllm_group_port (
int, opcional, valor predeterminado51216) — 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 predeterminado0.3) — Controla la utilización de la memoria de GPU para vLLM. Esta configuración solo se aplica cuandovllm_modeestá establecido en"colocate". Si estás usandovllm_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ásmax_completion_length; si se omite, se infiere desde la configuración del modelo. - vllm_tensor_parallel_size (
int, opcional, valor predeterminado1) — Controla el tamaño de paralelismo de tensores para vLLM. Esta configuración solo se aplica cuandovllm_modeestá establecido en"colocate". Si está utilizandovllm_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 predeterminado0.0) — Coeficiente KL. Si es0.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 de0.001. - num_iterations (
int, opcional, valor predeterminado1) — Número de iteraciones por lote (denotado como μ en el algoritmo). - epsilon (
float, opcional, valor predeterminado0.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 esNone(predeterminado), se utiliza el recorte estándar de GRPO. Se recomienda que sea mayor que1 + ε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 argumentoepsilon. El artículo DAPO recomienda0.28. Cuando se usa conloss_type='cispo', esto corresponde al parámetro ε_max especificado en el artículo ScaleRL y toma por defecto el valor recomendado5.0. - sapo_temperature_neg (
float, opcional, valor predeterminado1.05) — Temperatura para los tokens con puntuaciones de ventaja no positivas, utilizada en la función de pérdidasapo. Este parámetro se introduce en el artículo Soft Adaptive Policy Optimization. - sapo_temperature_pos (
float, opcional, valor predeterminado1.0) — Temperatura para los tokens con puntuaciones de ventaja positivas, utilizada en la función de pérdidasapo. Este parámetro se introduce en el artículo Soft Adaptive Policy Optimization. - vespo_k_pos (
float, opcional, valor predeterminado2.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 predeterminado3.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 predeterminado3.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 predeterminado2.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 esNone, todas las recompensas se ponderan por igual con un peso de1.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 porscale_rewards(consultescale_rewardspara 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 (
strobool, opcional, por defecto"group") — Especifica la estrategia de escalado para las recompensas. Los valores admitidos son:Trueo"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.Falseo"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 amax_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 usarper_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 requiereimportance_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 predeterminadoFalse) — 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 predeterminadoFalse) — Si se sincroniza el modelo de referencia con el modelo activo cadaref_model_sync_stepspasos, utilizando el parámetroref_model_mixup_alpha. Esta sincronización proviene del artículo TR-DPO. - ref_model_mixup_alpha (
float, opcional, valor predeterminado0.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 establecersync_ref_model=True. - ref_model_sync_steps (
int, opcional, valor predeterminado512) — 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 establecersync_ref_model=True. - top_entropy_quantile (
float, opcional, valor predeterminado1.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 de0.0enmascara todos los tokens excepto el de mayor entropía;1.0conserva todos los tokens. El artículo recomienda un valor de0.2. Si se usa conmask_truncated_completions=True, solo se consideran los tokens de las completas no truncadas. - entropy_coef (
float, opcional, valor predeterminado0.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 deloss_type; no se reescala para coincidir con la normalización de la política de un tipo de pérdida, por lo queentropy_coeftiene el mismo significado para cada tipo de pérdida. Cuandouse_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 en0.0(valor predeterminado). - use_adaptive_entropy (
bool, opcional, valor predeterminadoFalse) — Si se debe usar el control de entropía adaptativa, introducido en Skywork-OR1. Cuando está habilitado, el coeficiente de entropíaentropy_coefse actualiza en cada paso del optimizador: se incrementa enentropy_coef_deltacuando la entropía actual es inferior aentropy_target, y se decrementa en caso contrario. El coeficiente solo se aplica cuando la entropía es igual o inferior aentropy_target. - entropy_coef_min (
float, opcional, valor predeterminado0.0) — Límite inferior para el coeficiente de entropía al usar el control adaptativo de entropía. - entropy_coef_max (
float, opcional, valor predeterminado1.0) — Límite superior para el coeficiente de entropía al usar el control adaptativo de entropía. - entropy_coef_delta (
float, opcional, valor predeterminado0.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 predeterminado0.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 cuandotop_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 de0.2casi 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étricaentropy) para que el bono se active antes de que la política colapse (y tenga en cuenta el subconjunto de tokens al usartop_entropy_quantile). - max_tool_calling_iterations (
int, opcional) — Número máximo de turnos de llamada a herramientas al entrenar un agente. Si esNone, 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) alcanzamax_completion_lengthtokens, o cuando la secuencia completa alcanza la longitud máxima del modelo (vllm_max_model_lengthconvllm_mode="colocate", o losmax_position_embeddingsdel modelo en caso contrario). - vllm_importance_sampling_correction (
bool, opcional, valor predeterminadoTrue) — 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 enFalse, no se aplica IS independientemente devllm_importance_sampling_mode. Cuando esTrue, el modo seleccionado determina cómo se calculan y limitan las proporciones de IS. Contop_p < 1,top_k > 0omin_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-outdesde vLLM 0.30); de lo contrario, las proporciones de IS estarán sesgadas. vLLM limita ese conjunto de candidatos contop_k, por lo quetop_p < 1,min_p > 0y las salidas estructuradas, que lo restringen a los tokens que permite la gramática, requierentop_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 aplicarepetition_penaltya los logprobs que devuelve, por lo querepetition_penalty != 1.0requierevllm_importance_sampling_correction=False. - vllm_importance_sampling_mode (
str, opcional, por defecto"sequence_mask") — Especifica cómo se realiza el Importance Sampling cuandovllm_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 predeterminado3.0) — Límite superior de muestreo por importancia C_max utilizado porvllm_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 porvllm_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, establezcavllm_importance_sampling_clip_max=None. - off_policy_mask_threshold (
float, opcional) — Umbral para el enmascaramiento de secuencias fuera de política. Si esNone, 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 umbraldeltade 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 predeterminadoTrue) — 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 quebeta != 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 paraimportance_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 predeterminadoFalse) — Indica si se debe registrar una muestra de pares (prompt, completion) cadalogging_stepspasos. Sirichestá instalado, imprime la muestra. Si el registro dewandby/otrackioestá habilitado, lo registra enwandby/otrackio. - log_multimodal (
bool, opcional, valor predeterminadoTrue) — 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 conrich. Si esNone, se registran todas las completions. - log_unique_prompts (
bool, opcional, valor predeterminadoFalse) — Si se registran los prompts únicos. Si esTrue, solo se registran los prompts únicos. Si esFalse, 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 establezcahub_private_repo=Trueo 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 predeterminadoFalse) — Si se debe utilizar el motor de lotes continuos de transformers para generar completados. Requieretransformers>=5.8.0. - transformers_continuous_batching_config (
dict, opcional) — Argumentos de palabra clave paraContinuousBatchingConfig.
Parámetros obsoletos
- use_transformers_paged —
El parámetro
use_transformers_pagedestá obsoleto y se eliminará en la versión v2.0.0. Utiliceuse_transformers_continuous_batchingen su lugar. - vllm_importance_sampling_cap —
El parámetro
vllm_importance_sampling_capestá obsoleto y se eliminará en la versión v2.0.0. Utilicevllm_importance_sampling_clip_maxen 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 es10en lugar de500.gradient_checkpointing: El valor predeterminado esTrueen lugar deFalse.bf16: Por defecto, esTruesifp16no está establecido, en lugar deFalse.learning_rate: El valor predeterminado es1e-6en lugar de5e-5.