ReChorus2.0 是一个模块化且任务灵活的 PyTorch 推荐库，尤其适用于研究目的。它旨在为研究人员提供一个灵活的框架，用于实现各种推荐任务、比较不同算法，并适应多样化的高度定制数据输入。我们希望 ReChorus2.0 能够成为研究人员更加便捷、友好的工具，从而形成推荐任务与算法的“合奏”。

ReChorus 的上一版本可参见 ReChorus1.0。

ReChorus2.0 新特性：

• 新增任务：新增支持上下文感知的 Top-K 推荐和 CTR 预测任务；新增支持基于曝光的重排序任务。
• 新增模型：增加了上下文感知推荐模型和基于曝光的重排序模型，具体如下。
• 新数据集格式：支持多种上下文特征输入；可在训练和评估中自定义候选物品列表；支持变长的正负样本。
• 任务灵活：每个模型均可服务于不同的任务，通过切换 模型模式 即可方便地完成任务切换。

该框架特别适合研究人员选择或实现所需的实验设置，并在相同设置下比较算法。我们的框架具有以下特点：

• 模块化：主要功能被模块化为独立组件：运行器、模型和读取器，便于代码理解及新功能的集成。

• 快速：只需 在一个文件中 专注于模型设计，即可快速实现新模型。

• 高效：采用多线程批量准备数据，针对评估进行了特殊优化，深度模型训练时 GPU 利用率可达约 90%。

• 灵活：可为不同数据集和实验设置实现新的读取器或运行器，且每个模型都可以分配特定的帮助程序。

结构

总体而言，ReChorus 将整个流程分解为三个模块：

• 读取器：将数据集读入 DataFrame，并为每个实例添加必要信息。
• 运行器：控制训练过程和模型评估，包括评估指标。
• 模型：定义如何生成输出（预测标签或排序分数）以及如何准备批次。

环境要求与入门

详细信息请参阅文档中的 环境要求与入门。

任务与设置

以下是任务与设置的列表：

任务	运行器	指标	损失函数	读取器	基础模型	模型	模型模式
Top-k 推荐	BaseRunner	HitRate NDCG	BPR	BaseReader	BaseModel.GeneralModel	general	''
				SeqReader	BaseModel.SequentialModel	sequential	''
				ContextReader	BaseContextModel.ContextModel	context	'TopK'
CTR 预测	CTRRunner	AUC Logloss	BPR, BCE	ContextReader	BaseContextModel.ContextCTRModel	context	'CTR'
基于曝光的排序	ImpressionRunner	HitRate NDCG MAP	List-level BPR, Listnet loss, Softmax cross entropy loss, Attention rank	ImpressionReader	BaseImpressionModel.ImpressionModel	general	'Impression'
				ImpressionSeqReader	BaseImpressionModel.ImpressionSeqModel	sequential	'Impression'
				ImpressionReader	BaseRerankerModel.RerankModel	reranker	'General'
				ImpressionSeqReader	BaseRerankerModel.RerankSeqModel	reranker	'Sequential'

参数

详细信息请参阅文档中的 主要参数。

模型

详细信息请参阅文档中的 支持的模型。

实验结果及相应配置详见 示例脚本结果。

引用

如果您发现 ReChorus 对您的研究有所帮助，请引用以下任一论文。谢谢！

@inproceedings{li2024rechorus2,
  title={ReChorus2. 0: 一个模块化且任务灵活的推荐库},
  author={李嘉宇、李涵宇、何志宇、马为志、孙培杰、张敏、马少平},
  booktitle={第18届ACM推荐系统会议论文集},
  pages={454--464},
  year={2024}
}

@inproceedings{wang2020make,
  title={让它成为合唱：面向序列推荐的知识与时间感知物品建模},
  author={王晨阳、张敏、马为志、刘奕群、马少平},
  booktitle={第43届国际ACM SIGIR信息检索研究与发展大会论文集},
  pages={109--118},
  year={2020}
}

@article{王晨阳2021rechorus,
  title={ReChorus: 一个综合, 高效, 易扩展的轻量级推荐算法框架},
  author={王晨阳、任一、马为之、张敏、刘奕群、马少平},
  journal={软件学报},
  volume={33},
  number={4},
  pages={0--0},
  year={2021}
}

这也是我们针对以下论文的公开实现（代码和数据集可在相应分支中找到，用于复现结果）：

• Chenyang Wang, Min Zhang, Weizhi Ma, Yiqun Liu, and Shaoping Ma. 让其成为合唱：面向序列推荐的知识与时间感知物品建模. In SIGIR'20.

git clone -b SIGIR20 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Weizhi Ma, Min Zhang, Chong Chen, Yiqun Liu, and Shaoping Ma. 走向动态用户意图：序列推荐中物品关系的时间演化效应. In TOIS'21.

git clone -b TOIS21 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Weizhi Ma, Chong, Chen, Min Zhang, Yiqun Liu, and Shaoping Ma. 具有多重对比信号的序列推荐. In TOIS'22.

git clone -b TOIS22 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Zhefan Wang, Yankai Liu, Yang Ge, Weizhi Ma, Min Zhang, Yiqun Liu, Junlan Feng, Chao Deng, and Shaoping Ma. 面向多兴趣推荐的目标兴趣蒸馏. In CIKM'22.

git clone -b CIKM22 https://github.com/THUwangcy/ReChorus.git

联系方式

ReChorus 1.0: 王晨阳 (THUwangcy@gmail.com)

ReChorus 2.0: 李嘉宇 (lijiayu997@gmail.com)、李涵宇 (l-hy12@outlook.com)

ReChorus 2.0 快速上手指南

ReChorus 2.0 是一个模块化且任务灵活的 PyTorch 推荐系统库，专为科研设计。它支持上下文感知 Top-K 推荐、CTR 预测以及基于曝光的重排序等多种任务，允许研究人员在统一框架下快速实现模型对比与实验验证。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 需通过 WSL 运行)
• Python 版本: Python 3.10
• 核心依赖:
  • PyTorch (建议安装与您的 CUDA 版本匹配的最新版)
  • NumPy, Pandas, SciPy
  • tqdm, tensorboardX

提示：国内用户建议使用清华源或阿里源加速 Python 包和 PyTorch 的安装。

安装步骤

1. 克隆项目

从 GitHub 克隆 ReChorus 2.0 主分支代码：

git clone https://github.com/THUwangcy/ReChorus.git
cd ReChorus

2. 安装依赖

推荐使用 pip 安装所需依赖。国内用户可添加 -i 参数使用镜像源：

# 使用清华源安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果 requirements.txt 未包含 PyTorch，请单独安装（以 CUDA 11.8 为例）：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

基本使用

ReChorus 的核心设计理念是模块化（Reader-Model-Runner）。最简单的使用方式是通过命令行运行已有的演示脚本，或修改配置文件来训练新模型。

1. 目录结构概览

主要代码位于 src 目录：

• src/helpers/BaseReader.py: 数据读取与预处理
• src/models/: 模型定义
• src/helpers/BaseRunner.py: 训练流程控制与评估

2. 运行示例任务

假设您想运行一个基础的序列推荐模型（如 SASRec）在标准数据集上，通常可以在根目录下找到对应的脚本或配置。

通用运行命令格式：

python src/main.py --model [模型名称] --dataset [数据集名称] --task [任务类型]

具体示例（以 Top-K 推荐任务为例）：

# 运行一个序列模型 (sequential) 进行 Top-K 推荐
python src/main.py --model SASRec --dataset Amazon_Beauty --task sequential --mode ''

切换任务模式（例如切换到 CTR 预测）： 只需更改 --task 和 --mode 参数，无需修改模型代码：

# 运行上下文模型进行 CTR 预测
python src/main.py --model DIN --dataset Criteo --task context --mode 'CTR'

3. 自定义开发

若要实现新模型，只需在 src/models 下新建一个 Python 文件，继承对应的基类（如 BaseModel.GeneralModel 或 BaseModel.SequentialModel），并实现 forward 和 prepare_batch 方法即可。框架会自动处理训练循环和评估指标。

# src/models/MyNewModel.py 示例骨架
from models.BaseModel import SequentialModel

class MyNewModel(SequentialModel):
    def __init__(self, args, data_dict):
        super().__init__(args, data_dict)
        # 初始化模型层
        
    def forward(self, batch):
        # 定义前向传播逻辑
        pass

运行新模型：

python src/main.py --model MyNewModel --dataset [您的数据集] --task sequential

更多详细的参数配置、支持的数据集格式及完整模型列表，请参考项目文档中的 Main_Arguments.md 和 Supported_Models.md。