> ## 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.
# GRPO 训练
> 使用自定义环境进行群组相对策略优化
# GRPO 训练
使用 Group Relative Policy Optimization（GRPO）和自定义奖励环境训练语言模型。与奖励模型不同，您提供一个包含环境类的 Python 模块，该类运行多轮对话并返回分数。
## 概述
GRPO 与 PPO 的关键区别：
* **PPO** 需要预训练的奖励模型来评分响应
* **GRPO** 使用您编写的自定义环境 — 它为每个提示生成多个补全，通过您的环境评分，并相对于组进行策略优化
这使得 GRPO 非常适合**智能体训练**，其中奖励来自任务执行（工具使用、代码执行、多轮交互），而不是静态奖励模型。
## 快速开始
```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,
# 共享 RL 参数
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()
```
## 环境接口
您需要实现一个包含 3 个方法的 Python 类：
```python theme={null}
from datasets import Dataset
class MyEnv:
def build_dataset(self, tokenizer) -> Dataset:
"""返回包含 'prompt' 列的 HuggingFace Dataset。
可以包含额外列（如 case_idx），这些列会作为
kwargs 传递给 score_episode()。
"""
return Dataset.from_dict({
"prompt": ["你是一个酒店预订代理...", ...],
"case_idx": [0, 1, ...],
})
def score_episode(self, model, tokenizer, completion, case_idx) -> float:
"""从补全开始运行多轮对话并返回分数。
Args:
model: 正在训练的当前模型
tokenizer: 分词器
completion: 模型生成的文本
case_idx: 数据集中的索引（或任何额外列）
Returns:
0.0 到 1.0 之间的浮点数
"""
return score
def get_tools(self) -> list[dict]:
"""返回用于生成的工具模式（可选）。
Returns:
工具定义字典列表（OpenAI function calling 格式）
"""
return []
```
### 带配置的环境
通过 `--rl-env-config` 将 JSON 配置传递给您的环境：
```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"}'
```
JSON 被解析并作为 `**kwargs` 传递给环境构造函数：
```python theme={null}
class HotelEnv:
def __init__(self, max_turns=3, difficulty="normal"):
self.max_turns = max_turns
self.difficulty = difficulty
```
## 要求
GRPO 训练需要同时指定 `--rl-env-module` 和 `--rl-env-class`。这些在启动时进行验证 — 如果缺少任何一个，训练将以清晰的错误消息失败。
GRPO 使用 TRL 的 `GRPOTrainer`（需要 TRL >= 0.28.0）。分词器的填充方向会自动设置为 `left`，这是 GRPO 的要求。
## 参数
### GRPO 特定参数
| 参数 | CLI 标志 | 默认值 | 描述 |
| ------------------------------- | --------------------------------- | ---------- | -------------------------------------------------- |
| `rl_env_module` | `--rl-env-module` | None | 环境的 Python 模块路径（必需） |
| `rl_env_class` | `--rl-env-class` | None | 环境模块中的类名（必需） |
| `rl_num_generations` | `--rl-num-generations` | `4` | 每个提示的补全数量 |
| `rl_loss_type` | `--rl-loss-type` | `grpo` | 损失变体：`grpo`、`dr_grpo`、`dapo`、`bnpo`、`cispo`、`sapo` |
| `rl_mask_truncated_completions` | `--rl-mask-truncated-completions` | `False` | 从损失中排除截断的补全（推荐以提高稳定性） |
| `use_vllm` | `--use-vllm` | `False` | 使用 vLLM 加速生成 |
| `vllm_mode` | `--vllm-mode` | `colocate` | vLLM 模式：`colocate` 或 `server` |
| `vllm_gpu_memory_utilization` | `--vllm-gpu-memory-utilization` | `0.3` | vLLM 的 GPU 内存占比（colocate 模式） |
| `vllm_server_url` | `--vllm-server-url` | None | 外部 vLLM 服务器 URL（server 模式） |
| `vllm_tensor_parallel_size` | `--vllm-tensor-parallel-size` | `1` | vLLM 张量并行的 GPU 数量 |
| `vllm_server_gpus` | `--vllm-server-gpus` | `1` | vLLM 服务器专用 GPU（从训练中扣除） |
### 共享 RL 参数（PPO + GRPO）
| 参数 | CLI 标志 | 默认值 | 描述 |
| ------------------- | --------------------- | ----- | --------------------------- |
| `rl_kl_coef` | `--rl-kl-coef` | `0.1` | KL 散度惩罚（GRPOConfig 中的 beta） |
| `rl_clip_range` | `--rl-clip-range` | `0.2` | 裁剪范围（GRPOConfig 中的 epsilon） |
| `rl_env_config` | `--rl-env-config` | None | 传递给环境构造函数的 JSON 配置 |
| `rl_max_new_tokens` | `--rl-max-new-tokens` | `128` | 每个补全的最大生成 token 数 |
| `rl_top_k` | `--rl-top-k` | `50` | Top-k 采样 |
| `rl_top_p` | `--rl-top-p` | `1.0` | Top-p（核）采样 |
| `rl_temperature` | `--rl-temperature` | `1.0` | 生成温度 |
## vLLM 加速
使用 vLLM 在 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
```
两种模式可用：
* **`colocate`**（默认）— vLLM 与训练共享 GPU。调整 `--vllm-gpu-memory-utilization`（默认 0.3）控制内存分配。
* **`server`** — vLLM 在专用 GPU 上运行。训练进程会自动减少 `--vllm-server-gpus` 个。
```bash theme={null}
# Server 模式：共 8 个 GPU，2 个给 vLLM，6 个给训练
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 需要单独安装：`pip install aitraining[vllm]`（需要 `vllm>=0.14.0`）。
GRPO 不需要 `--data-path` — 数据集由环境的 `build_dataset()` 方法构建。
## 工作原理
1. **环境加载** — 通过 `importlib.import_module()` 导入您的模块，使用可选配置实例化类
2. **构建数据集** — `env.build_dataset(tokenizer)` 返回提示
3. **模型生成** — GRPO 为每个提示生成 `rl_num_generations` 个补全
4. **环境评分** — 对每个补全调用 `env.score_episode()`，返回 0.0-1.0
5. **GRPO 优化** — 策略相对于组分数进行更新（更好的补全获得更高权重）
## GRPO 与 PPO 对比
| 特征 | PPO | GRPO |
| -------- | --------- | ------------------------ |
| 奖励来源 | 预训练奖励模型 | 自定义环境（您的代码） |
| 训练信号 | 奖励模型分数 | 环境对话分数（0-1） |
| 每个提示的补全数 | 1 | 多个（`rl_num_generations`） |
| 最适合 | 通用 RLHF | 智能体训练、工具使用、多轮对话 |
| 需要 | 奖励模型路径 | Python 环境模块 + 类 |
| TRL 版本 | >= 0.26.0 | >= 0.28.0 |
## 最佳实践
1. **从简单环境开始** — 在复杂的多轮逻辑之前验证评分是否有效
2. **使用较小的 `rl_num_generations`** — 从 4 开始，如需更多补全多样性再增加
3. **评分在 0 到 1 之间** — 使用完整范围；避免总是返回 0 或 1
4. **独立测试您的环境** — 确保 `build_dataset()` 和 `score_episode()` 在训练前能正常工作
5. **使用 LoRA** — 完整微调的 GRPO 需要大量内存；LoRA 使其可行
6. **小学习率** — 从 1e-5 开始，与 PPO 相同的指导
## 下一步
使用奖励模型的 RLHF
底层 RL 构建模块
使用偏好数据的更简单替代方案
高效微调