SII-ChengqiLi/paper_rl

# Paper Conclusion RL Training

基于 EasyR1（verl）框架的论文结论强化学习训练，训练模型为 `Qwen3-VL-8B-Thinking`，使用外部 judge 模型（`Qwen3-4B-Instruct-2507`）对预测结论与 235B 教师模型参考结论进行打分。

## 目录结构

```
paper_conclusion_rl/
├── EasyR1/ # 训练框架（verl）
│ ├── verl/ # 核心代码
│ ├── examples/
│ │ ├── paper_conclusion_grpo.yaml # GRPO 训练配置
│ │ ├── format_prompt/
│ │ │ └── paper_conclusion_json.jinja # prompt 模板
│ │ ├── reward_function/
│ │ │ ├── paper_conclusion_list_judge.py # HTTP 模式 reward
│ │ │ ├── paper_conclusion_file_queue_judge.py # 双机文件队列 reward
│ │ │ ├── paper_conclusion_judge_common.py # 共用 judge 逻辑
│ │ │ └── file_queue_judge_worker.py # 文件队列 worker
│ │ ├── qwen3_vl_8b_paper_conclusion_grpo.sh # 训练启动脚本
│ │ ├── start_qwen3_4b_judge_vllm.sh # judge 服务启动（HTTP）
│ │ └── start_qwen3_4b_judge_file_queue.sh # judge 服务启动（双机）
│ ├── setup.py
│ ├── requirements.txt
│ └── ...
├── images_part00.tar # 图片分片压缩包（每个 ~2GB）
├── images_part01.tar
├── ...
├── paper_conclusion_rl_train.jsonl # 训练集（4599 条）
├── paper_conclusion_rl_test.jsonl # 测试集（1152 条）
└── README.md
```

> **注意**：图片以 tar 分片形式存储，下载后需要先解压才能开始训练。

## 新机器环境准备

### 1. 硬件要求

- **单机模式**：至少 8 张 GPU（4 张跑 judge 服务，4 张跑训练）
- **双机模式**：每台机器至少 4 张 GPU（一台专跑训练，一台专跑 judge）
- GPU 显存建议 >= 80GB（A100/H100），训练和 judge 同时运行时显存需求较高

### 2. 软件环境

```bash
# Python >= 3.10
python3 --version

# CUDA >= 12.1
nvidia-smi
```

### 3. 下载并解压数据集

```bash
# 下载数据集
huggingface-cli download <repo_id> --local-dir ./paper_conclusion_rl
cd paper_conclusion_rl

# 解压图片（解压后生成 images/ 目录）
for f in images_part*.tar; do tar xf "$f"; done

# 验证图片数量
ls images/ | wc -l # 应该约 19659 个文件
```

### 4. 安装 EasyR1 依赖

```bash
cd EasyR1
pip install -e .
```

如果 `pip install -e .` 报错，可手动安装核心依赖：

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install vllm>=0.8
pip install transformers accelerate
pip install hydra-core omegaconf
pip install pyarrow
```

### 5. 准备模型文件

需要下载两个模型到本地（不包含在此数据集中）：

| 用途 | 模型 | 建议 HuggingFace 路径 |
|------|------|----------------------|
| RL 训练 | `Qwen3-VL-8B-Thinking` | `Qwen/Qwen3-VL-8B-Thinking` |
| Judge 服务 | `Qwen3-4B-Instruct-2507` | `Qwen/Qwen3-4B-Instruct-2507` |

```bash
# 示例：下载模型
huggingface-cli download Qwen/Qwen3-VL-8B-Thinking --local-dir /path/to/Qwen3-VL-8B-Thinking
huggingface-cli download Qwen/Qwen3-4B-Instruct-2507 --local-dir /path/to/Qwen3-4B-Instruct-2507
```

## 配置环境变量

训练脚本和 judge 脚本通过环境变量控制路径和行为，**无需手动修改脚本内容**。

### 必须设置

```bash
# 项目根目录（即本 README 所在目录）
export PROJECT_ROOT=/path/to/paper_conclusion_rl

# 训练模型路径（新机器上的实际路径）
export MODEL_PATH=/path/to/Qwen3-VL-8B-Thinking

# Judge 模型路径（新机器上的实际路径）
# 注意：这个变量在 judge 启动脚本中名为 MODEL_PATH，需要在启动 judge 时设置
```

### 可选设置

```bash
# Judge 服务的 API key（如果 judge 需要鉴权，通常设为 EMPTY 即可）
export OPENAI_API_KEY=EMPTY

# CUDA 可见设备（默认脚本中有内置分配，也可手动覆盖）
# 单机模式示例：4卡 judge + 4卡训练
# export CUDA_VISIBLE_DEVICES=0,1,2,3 # judge 启动时
# export CUDA_VISIBLE_DEVICES=4,5,6,7 # 训练启动时
```

## 启动训练

### 方式一：单机 8 卡（4 卡 judge + 4 卡训练）

**终端 1 — 启动 judge 服务：**

```bash
cd $PROJECT_ROOT/EasyR1

CUDA_VISIBLE_DEVICES=0,1,2,3 \
MODEL_PATH=/path/to/Qwen3-4B-Instruct-2507 \
SERVED_MODEL_NAME=qwen3-4b-judge \
TP_SIZE=4 \
PORT=8000 \
bash examples/start_qwen3_4b_judge_vllm.sh
```

等待 judge 服务完全启动（看到 `Uvicorn running on` 日志）后，再启动训练。

**终端 2 — 启动 RL 训练：**

```bash
cd $PROJECT_ROOT/EasyR1

CUDA_VISIBLE_DEVICES=4,5,6,7 \
MODEL_PATH=/path/to/Qwen3-VL-8B-Thinking \
JUDGE_BASE_URL=http://127.0.0.1:8000/v1 \
JUDGE_MODEL=qwen3-4b-judge \
bash examples/qwen3_vl_8b_paper_conclusion_grpo.sh
```

### 方式二：双机（训练机和 judge 机分离）

适用于单机 GPU 显存不足的情况。两台机器需要能访问同一个共享文件系统（如 NFS）。

**机器 B（Judge 机）— 启动 judge 服务 + 文件队列 worker：**

```bash
cd $PROJECT_ROOT/EasyR1

QUEUE_ROOT=$PROJECT_ROOT/EasyR1/shared_judge_queue \
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
MODEL_PATH=/path/to/Qwen3-4B-Instruct-2507 \
TP_SIZE=8 \
bash examples/start_qwen3_4b_judge_file_queue.sh
```

**机器 A（训练机）— 启动 RL 训练：**

```bash
cd $PROJECT_ROOT/EasyR1

TRANSPORT_MODE=file_queue \
QUEUE_ROOT=$PROJECT_ROOT/EasyR1/shared_judge_queue \
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
TRAIN_GPUS_PER_NODE=8 \
ROLLOUT_TP_SIZE=8 \
MODEL_PATH=/path/to/Qwen3-VL-8B-Thinking \
bash examples/qwen3_vl_8b_paper_conclusion_grpo.sh
```

> **启动顺序**：必须先启动 judge 机，确认 vLLM 服务和队列 worker 都就绪后，再启动训练机。否则训练会在等待 judge 结果时阻塞。

## 关键参数说明

### 训练配置（`paper_conclusion_grpo.yaml`）

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `data.max_prompt_length` | 8192 | 最大 prompt 长度，超长样本会被过滤 |
| `data.max_response_length` | 2048 | 最大生成长度 |
| `data.rollout_batch_size` | 24 | 每 rollout 批次大小 |
| `worker.rollout.n` | 16 | 每个样本的 rollout 数量 |
| `worker.rollout.limit_images` | 12 | 每个样本最大图片数 |
| `worker.rollout.max_model_len` | 40960 | rollout 模型最大上下文 |
| `worker.actor.model.lora.rank` | 32 | LoRA 秩 |
| `worker.actor.optim.lr` | 1e-6 | 学习率 |
| `trainer.total_epochs` | 3 | 训练总轮数 |
| `trainer.save_freq` | 40 | 每 40 步保存 checkpoint |
| `trainer.val_freq` | 40 | 每 40 步验证一次 |

### Reward 计算

- 使用 `max(0, matched - wrong) / reference_count` 公式
- `format_weight=0.05`：格式正确性奖励权重
- Judge 模型对每个样本的预测结论列表与 235B 教师参考结论进行逐一匹配打分

## 双机文件队列行为

使用双机模式时，训练和 judge 通过共享目录通信：

```
shared_judge_queue/
├── requests/
│ ├── pending/ # 训练写入请求，等待 judge 处理
│ └── processing/ # judge 正在处理的请求
└── results/
├── ok/ # 处理成功的结果
└── error/ # 处理出错的结果
```

- 确保 `QUEUE_ROOT` 在两台机器上指向同一个共享目录
- 确保共享文件系统支持原子 rename 操作
- 如果 `requests/pending` 中文件持续堆积，说明 judge worker 未正常消费
- 如果 `requests/processing` 中文件持续堆积，说明 judge 服务可能已崩溃

## 数据集格式

每条训练样本格式：

```json
{
"id": "PMC12345",
"md5": "abc123...",
"query": "<prompt>\n\n<paper content with <image> placeholders>",
"images": ["images/xxx.jpg", "images/yyy.jpg"],
"answer": {
"reference_conclusions": ["conclusion 1", "conclusion 2", ...],
"rubrics": "...",
"paper_id": "PMC12345",
"md5": "abc123..."
}
}
```

- `images` 字段为相对路径，相对于项目根目录
- `reference_conclusions` 来自 235B 教师模型，用于 judge 打分
- 训练时学生模型只看到 `query` 和 `images`，不直接看到参考结论

## 常见问题

**Q: vLLM 报 `AssertionError: Failed to apply prompt replacement for mm_items['image'][13]`**

A: 图片数超过 vLLM 处理上限。当前数据集已过滤掉图片数 > 12 的样本。如果仍有问题，降低 `data.max_prompt_length` 或 `worker.rollout.limit_images`。

**Q: OOM（显存不足）**

A: 尝试以下方法：
- 降低 `worker.rollout.gpu_memory_utilization`（默认 0.5）
- 减小 `data.rollout_batch_size`
- 切换到双机模式，将 judge 和训练分到不同机器

**Q: 训练阻塞在等待 reward**

A: 检查 judge 服务是否正常运行。单机模式确认 `http://127.0.0.1:8000/v1` 可访问；双机模式检查 `shared_judge_queue/` 中文件流转情况。

**Q: 图片解压后找不到**

A: 确保在项目根目录下执行 `for f in images_part*.tar; do tar xf "$f"; done`，解压后会生成 `images/` 目录，与 JSONL 中的 `images/xxx.jpg` 路径对应。