> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Entrenamiento GRPO
> Optimización de Política Relativa de Grupo con Entornos Personalizados
# Entrenamiento GRPO
Entrena modelos de lenguaje usando Group Relative Policy Optimization (GRPO) con entornos de recompensa personalizados. En lugar de un modelo de recompensa, proporcionas un módulo Python con una clase de entorno que ejecuta episodios multi-turno y retorna puntuaciones.
## Visión General
GRPO se diferencia de PPO de una manera clave:
* **PPO** requiere un modelo de recompensa pre-entrenado para puntuar respuestas
* **GRPO** usa un entorno personalizado que tú escribes — genera múltiples completaciones por prompt, las puntúa mediante tu entorno, y optimiza la política relativa al grupo
Esto hace que GRPO sea ideal para **entrenamiento agéntico** donde las recompensas provienen de la ejecución de tareas (uso de herramientas, ejecución de código, interacciones multi-turno) en lugar de un modelo de recompensa estático.
## Inicio Rápido
```bash theme={null}
aitraining llm --train \
--model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
--trainer grpo \
--rl-env-module my_envs.hotel_env \
--rl-env-class HotelEnv \
--rl-num-generations 4 \
--rl-max-new-tokens 256
```
## Python API
```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams
from autotrain.project import AutoTrainProject
params = LLMTrainingParams(
model="deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B",
project_name="grpo-agent",
trainer="grpo",
rl_env_module="my_envs.hotel_env",
rl_env_class="HotelEnv",
rl_num_generations=4,
# Parámetros RL compartidos
rl_max_new_tokens=256,
rl_temperature=1.0,
rl_kl_coef=0.1,
rl_clip_range=0.2,
epochs=1,
batch_size=4,
lr=1e-5,
peft=True,
lora_r=16,
lora_alpha=32,
)
project = AutoTrainProject(params=params, backend="local", process=True)
project.create()
```
## Interfaz del Entorno
Implementas una clase Python con 3 métodos:
```python theme={null}
from datasets import Dataset
class MyEnv:
def build_dataset(self, tokenizer) -> Dataset:
"""Retorna un Dataset de HuggingFace con una columna 'prompt'.
Puede incluir columnas extras (ej: case_idx) que se pasan
como kwargs a score_episode().
"""
return Dataset.from_dict({
"prompt": ["Eres un agente de reservas de hotel...", ...],
"case_idx": [0, 1, ...],
})
def score_episode(self, model, tokenizer, completion, case_idx) -> float:
"""Ejecuta un episodio multi-turno desde la completación y retorna un score.
Args:
model: El modelo actual siendo entrenado
tokenizer: El tokenizador
completion: El texto generado por el modelo
case_idx: Índice del dataset (o cualquier columna extra)
Returns:
Float entre 0.0 y 1.0
"""
return score
def get_tools(self) -> list[dict]:
"""Retorna schemas de herramientas para generación (opcional).
Returns:
Lista de dicts de definición de herramientas (formato OpenAI function calling)
"""
return []
```
### Entorno con Configuración
Pasa configuración JSON a tu entorno mediante `--rl-env-config`:
```bash theme={null}
aitraining llm --train \
--trainer grpo \
--rl-env-module my_envs.hotel_env \
--rl-env-class HotelEnv \
--rl-env-config '{"max_turns": 5, "difficulty": "hard"}'
```
El JSON se parsea y se pasa como `**kwargs` al constructor de tu entorno:
```python theme={null}
class HotelEnv:
def __init__(self, max_turns=3, difficulty="normal"):
self.max_turns = max_turns
self.difficulty = difficulty
```
## Requisitos
El entrenamiento GRPO requiere que se especifiquen tanto `--rl-env-module` como `--rl-env-class`. Se validan al inicio — si falta alguno, el entrenamiento fallará con un mensaje de error claro.
GRPO usa `GRPOTrainer` de TRL (requiere TRL >= 0.28.0). El lado de padding del tokenizador se establece automáticamente a `left` como requiere GRPO.
## Parámetros
### Parámetros Específicos de GRPO
| Parámetro | Flag CLI | Por Defecto | Descripción |
| ------------------------------- | --------------------------------- | ----------- | ----------------------------------------------------------------------------- |
| `rl_env_module` | `--rl-env-module` | None | Ruta del módulo Python para el entorno (requerido) |
| `rl_env_class` | `--rl-env-class` | None | Nombre de la clase en el módulo del entorno (requerido) |
| `rl_num_generations` | `--rl-num-generations` | `4` | Número de completaciones por prompt |
| `rl_loss_type` | `--rl-loss-type` | `grpo` | Variante de pérdida: `grpo`, `dr_grpo`, `dapo`, `bnpo`, `cispo`, `sapo` |
| `rl_mask_truncated_completions` | `--rl-mask-truncated-completions` | `False` | Excluir completaciones truncadas de la pérdida (recomendado para estabilidad) |
| `use_vllm` | `--use-vllm` | `False` | Usar vLLM para generación más rápida |
| `vllm_mode` | `--vllm-mode` | `colocate` | Modo vLLM: `colocate` o `server` |
| `vllm_gpu_memory_utilization` | `--vllm-gpu-memory-utilization` | `0.3` | Fracción de memoria GPU para vLLM (modo colocate) |
| `vllm_server_url` | `--vllm-server-url` | None | URL del servidor vLLM externo (modo server) |
| `vllm_tensor_parallel_size` | `--vllm-tensor-parallel-size` | `1` | GPUs para paralelismo tensorial de vLLM |
| `vllm_server_gpus` | `--vllm-server-gpus` | `1` | GPUs dedicadas al servidor vLLM (restadas del entrenamiento) |
### Parámetros RL Compartidos (PPO + GRPO)
| Parámetro | Flag CLI | Por Defecto | Descripción |
| ------------------- | --------------------- | ----------- | ---------------------------------------------------- |
| `rl_kl_coef` | `--rl-kl-coef` | `0.1` | Penalización de divergencia KL (beta en GRPOConfig) |
| `rl_clip_range` | `--rl-clip-range` | `0.2` | Rango de recorte (epsilon en GRPOConfig) |
| `rl_env_config` | `--rl-env-config` | None | Configuración JSON pasada al constructor del entorno |
| `rl_max_new_tokens` | `--rl-max-new-tokens` | `128` | Máximo de tokens a generar por completación |
| `rl_top_k` | `--rl-top-k` | `50` | Muestreo top-k |
| `rl_top_p` | `--rl-top-p` | `1.0` | Muestreo top-p (núcleo) |
| `rl_temperature` | `--rl-temperature` | `1.0` | Temperatura de generación |
## Aceleración con vLLM
Usa vLLM para generación de completaciones significativamente más rápida durante el entrenamiento GRPO:
```bash theme={null}
aitraining llm --train --trainer grpo \
--model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
--rl-env-module my_envs.hotel_env \
--rl-env-class HotelEnv \
--use-vllm \
--vllm-gpu-memory-utilization 0.3
```
Dos modos disponibles:
* **`colocate`** (predeterminado) — vLLM comparte la GPU con el entrenamiento. Ajusta `--vllm-gpu-memory-utilization` (predeterminado 0.3) para controlar la división de memoria.
* **`server`** — vLLM se ejecuta en GPUs dedicadas. Los procesos de entrenamiento se reducen automáticamente por `--vllm-server-gpus`.
```bash theme={null}
# Modo server: 8 GPUs total, 2 para vLLM, 6 para entrenamiento
aitraining llm --train --trainer grpo \
--model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
--rl-env-module my_envs.hotel_env \
--rl-env-class HotelEnv \
--use-vllm \
--vllm-mode server \
--vllm-server-gpus 2 \
--vllm-tensor-parallel-size 2
```
vLLM requiere instalación separada: `pip install aitraining[vllm]` (requiere `vllm>=0.14.0`).
GRPO no requiere `--data-path` — el dataset es construido por el método `build_dataset()` de tu entorno.
## Cómo Funciona
1. **Carga del entorno** — Tu módulo se importa vía `importlib.import_module()`, la clase se instancia con config opcional
2. **Construcción del dataset** — `env.build_dataset(tokenizer)` retorna prompts
3. **Modelo genera** — GRPO genera `rl_num_generations` completaciones por prompt
4. **Entorno puntúa** — `env.score_episode()` se llama para cada completación, retornando 0.0-1.0
5. **GRPO optimiza** — La política se actualiza relativa a las puntuaciones del grupo (mejores completaciones reciben mayor peso)
## GRPO vs PPO
| Característica | PPO | GRPO |
| ------------------------- | ------------------------------------- | -------------------------------------------------------- |
| Fuente de recompensa | Modelo de recompensa pre-entrenado | Entorno personalizado (tu código) |
| Señal de entrenamiento | Puntuaciones del modelo de recompensa | Puntuaciones de episodios del entorno (0-1) |
| Completaciones por prompt | 1 | Múltiples (`rl_num_generations`) |
| Ideal para | RLHF general | Entrenamiento agéntico, uso de herramientas, multi-turno |
| Requiere | Ruta del modelo de recompensa | Módulo Python env + clase |
| Versión TRL | >= 0.26.0 | >= 0.28.0 |
## Mejores Prácticas
1. **Comienza con entornos simples** — Valida que la puntuación funcione antes de lógica multi-turno compleja
2. **Usa `rl_num_generations` pequeño** — Comienza con 4, aumenta si necesitas más diversidad
3. **Puntúa entre 0 y 1** — Usa el rango completo; evita retornar siempre 0 o 1
4. **Prueba tu entorno independientemente** — Asegúrate de que `build_dataset()` y `score_episode()` funcionen antes de entrenar
5. **Usa LoRA** — GRPO con fine-tuning completo requiere memoria significativa; LoRA lo hace práctico
6. **Tasas de aprendizaje pequeñas** — Comienza con 1e-5, misma guía que PPO
## Próximos Pasos
RLHF con modelos de recompensa
Bloques de construcción RL de bajo nivel
Alternativa más simple con datos de preferencia
Fine-tuning eficiente