# 教程：CollabLLM

最后更新：09/22/2025。

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

🏠 [Homepage](https://aka.ms/CollabLLM) | 📝 [Paper](https://arxiv.org/pdf/2502.00640) | 🤗 [Datasets & Models](https://huggingface.co/collabllm) | ⭐️ [Original Implementation](https://github.com/Wuyxin/collabllm)

`verl` 提供了一个针对 ICML 2025 优质论文（Outstanding Paper）的教程（或实施指南），论文标题为 **"CollabLLM: 从被动回应者到主动合作者"**。[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-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` 中。
- 多轮对话感知奖励是从以下三个对话级奖励聚合而得：

    ```
    +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）为每个响应采样 `num_repeat_rollouts` 个对话，最多进行 `max_user_turns` 轮额外的用户交互。 |
| 3    | 计算多轮对话感知奖励 | 对采样得到的对话应用定制化的对话奖励函数。奖励会聚合，然后在多个 rollout 中取平均。 |
| 4    | 更新模型                  | 使用计算得到的多轮对话感知奖励来更新模型权重。  |

---

## 配置

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

| 部分              | 关键参数 / 注意事项                                                                 |
|----------------------|-----------------------------------------------------------------------------------------|
| `data`               | 训练/验证文件路径、批次大小、序列长度。                      |
| `actor_rollout_ref` （通用） | 基础模型路径（用于演员 + 初始参考）、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` 社区和顾问们的贡献与指导！