# 食谱：CollabLLM

最后更新：2025年9月22日。

> 开源算法实现与实验运行：[Haiquan Chen](https://github.com/chenhaiq), [Shirley Wu](https://github.com/Wuyxin)

🏠 [主页](https://aka.ms/CollabLLM) | 📝 [论文](https://arxiv.org/pdf/2502.00640) | 🤗 [数据集与模型](https://huggingface.co/collabllm) | ⭐️ [原始实现](https://github.com/Wuyxin/collabllm)

`verl` 为 ICML 2025 优秀论文 **“CollabLLM: From Passive Responders to Active Collaborators”** 提供了一个实现方法。 [CollabLLM](https://aka.ms/CollabLLM) 是一个统一的微调框架，可优化大型语言模型 (LLM)，使其能够与用户进行有效且高效的多轮协作。

**核心思想：** 模型将根据其响应在与用户进行**未来**有效协作方面的表现获得奖励。

论文作者：[Shirley Wu](https://cs.stanford.edu/~shirwu/), [Michel Galley](https://www.microsoft.com/en-us/research/people/mgalley/), Baolin Peng, Hao Cheng, Gavin Li, Yao Dou, Weixin Cai, [James Zou](https://www.james-zou.com/), [Jure Leskovec](https://cs.stanford.edu/people/jure/), [Jianfeng Gao](https://www.microsoft.com/en-us/research/people/jfgao/)


---
## 快速开始

### 0. 环境
确保已安装 `verl` 所需的软件包。此外，请安装 `litellm` 并导出所需的 API 密钥。API 模型将用于用户模拟器，并可选择用于 LLM 裁判（请参阅下面的配置部分）。

### 1. 准备你的数据集

首先，使用提供的脚本处理你的数据集（有关示例命令和用法，请参阅 `process_dataset.py`）：

```bash
python process_dataset.py --dataset <> ... --dataset_type <sft or rl>
```


**要求：**
- 输入：一个 Hugging Face 多轮数据集。现有数据集：`collabllm/collabllm-multiturn-$DATASET`，其中 `DATASET` 是 [`math-hard(-large)`, `medium(-large)`, `bigcodebench(-large)`] 中的一个（`-large` 是 CollabLLM 论文中使用的Даные）
- 示例格式：请参阅 [collabllm/collabllm-multiturn-math-hard](https://huggingface.co/datasets/collabllm/collabllm-multiturn-math-hard)
- 生成自己的数据集：使用原始 CollabLLM 存储库中的 [build_dataset.py](https://github.com/Wuyxin/collabllm/blob/main/scripts/engine/build_dataset.py)

### 2. 训练你的模型

（可选）监督微调 (SFT)：
```bash
bash train_sft_collabllm.sh
```

强化学习 (RL)：

```bash
bash train_rl_collabllm.sh
```

RL 脚本展示了一个在 `math-hard-large` 上训练 CollabLLM 的示例。

- 用于采样未来对话的配置位于 `recipe/collabllm/config/collabllm_interaction_config.yaml`。
- 多轮感知奖励 (Multiturn-aware Reward) 从以下三个对话级别奖励中聚合：

    ```
    +reward_model.reward_kwargs.metric_weights.accuracy=1 \
    +reward_model.reward_kwargs.metric_weights.interactivity=1 \
    +reward_model.reward_kwargs.metric_weights.token_amount=-0.0001 \
    ```

    你可以根据你的任务删除、添加或修改权重。你可以在 `recipe/collabllm/metrics` 下添加支持的指标列表。例如，在 `medium-large` 上，你可以通过以下方式将 `accuracy` 替换为 `bleu_score`：
    ```
    +reward_model.reward_kwargs.metric_weights.bleu_score=1
    ```
    这将改为对采样到的未来对话应用 BLEU 分数。

## 算法

| 步骤 | 名称 | 描述 |
|---|---|---|
| 1 | 模型响应生成 | 模型为批处理中的每个提示生成多个响应。 |
| 2 | 协作模拟 | 用户模拟器（例如 GPT 或 Claude）最多模拟 `max_user_turns` 轮，为每个提示采样 `num_repeat_rollouts` 次对话。 |
| 3 | 计算多轮感知奖励 | 将自定义的对话奖励函数应用于采样到的对话。奖励会进行聚合，然后跨模拟次数取平均值。 |
| 4 | 更新模型 | 使用计算出的多轮感知奖励来更新模型权重。 |

---

## 配置

主要配置通过启动脚本 `train_rl_collabllm.sh` 和 YAML 文件 `recipe/collabllm/config/collabllm_interaction_config.yaml` 进行管理。关键配置部分：

| 部分 | 关键参数 / 说明 |
|---|---|
| `data` | 训练/验证文件路径、批处理大小、序列长度。 |
| `actor_rollout_ref` (通用) | 基础模型路径（用于 actor + 初始参考）、FSDP 设置、优化器（学习率、调度器）。 |
| `actor_rollout_ref` (CollabLLM 特有) | `actor_rollout_ref.rollout.multi_turn` 下的超参数：`max_user_turns`、`max_assistant_turns`、`num_repeat_rollouts`。 |
| `interaction` | 在 `collabllm_interaction_config.yaml` 中定义。指定用户模拟器和超参数。需要导出 API 密钥。 |
| `reward_model` | 默认管理器设置为 `collabllm`。修改 `reward_model.reward_kwargs.metric_weights` 来配置对话奖励和权重。LLM 裁判的超参数（例如 `model`、`temperature`）位于 `reward_model.reward_kwargs.llm_judge_kwargs` 下。 |
| `algorithm` | GRPO 特有的超参数，例如 `actor_rollout_ref.rollout.n`。 |
| `trainer` | 分布式训练（节点、每节点 GPU）、日志记录（WandB）、检查点频率。 |

---

## 关键文件

| 文件路径 | 目的 |
|---|---|
| `recipe/collabllm/collabllm_agent_loop.py` | 主要逻辑，用于采样未来对话，使用 `verl/interactions/collabllm_interaction.py` 中的 `CollabLLMInteraction`。 |
| `verl/workers/reward_manager/collabllm.py` | 计算未来对话的奖励，利用 `recipe/collabllm/reward_function.py` 来应用每个指标。 |

---

## 致谢

我们衷心感谢 `verl` 社区和顾问的贡献和指导！