ReChorus2.0 is a modular and task-flexible PyTorch library for recommendation, especially for research purpose. It aims to provide researchers a flexible framework to implement various recommendation tasks, compare different algorithms, and adapt to diverse and highly-customized data inputs. We hope ReChorus2.0 can serve as a more convinient and user-friendly tool for researchers, so as to form a "Chorus" of recommendation tasks and algorithms.
The previous version of ReChorus can be found at ReChorus1.0
- New Tasks: Newly supporting the context-aware top-k recommendation and CTR prediction task. Newly supporting the Impression-based re-ranking task.
- New Models: Adding Context-aware Recommenders and Impression-based Re-ranking Models. Listed below.
- New dataset format: Supporting various contextual feature input. Customizing candidate item lists in training and evaluation. Supporting variable length positive and negative samples.
- Task Flexible: Each model can serve for different tasks, and task switching is conveniently achieved by altering model mode.
This framework is especially suitable for researchers to choose or implement desired experimental settings, and compare algorithms under the same setting. The characteristics of our framework can be summarized as follows:
-
Modular: primary functions modularized into distinct components: runner, model, and reader, facilitating code comprehension and integration of new features.
-
Swift: concentrate on your model design in a single file and implement new models quickly.
-
Efficient: multi-thread batch preparation, special implementations for the evaluation, and around 90% GPU utilization during training for deep models.
-
Flexible: implement new readers or runners for different datasets and experimental settings, and each model can be assigned with specific helpers.
Generally, ReChorus decomposes the whole process into three modules:
- Reader: read dataset into DataFrame and append necessary information to each instance
- Runner: control the training process and model evaluation, including evaluation metrics.
- Model: define how to generate output (predicted labels or ranking scores) and prepare batches.
- Install Anaconda with Python >= 3.5
- Clone the repository
git clone https://github.com/THUwangcy/ReChorus.git
- Install requirements and step into the
src
folder
cd ReChorus
pip install -r requirements.txt
cd src
- Run model with the build-in dataset
python main.py --model_name BPRMF --emb_size 64 --lr 1e-3 --l2 1e-6 --dataset Grocery_and_Gourmet_Food
-
(optional) Run jupyter notebook in
dataset
folder to download and build new datasets, or prepare your own datasets according to Guideline indata
-
(optional) Implement your own models according to Guideline in
src
The tasks & settings are listed below
Tasks | Runner | Metrics | Loss Functions | Reader | BaseModel | Models | Model Modes |
---|---|---|---|---|---|---|---|
Top-k Recommendation | BaseRunner | HitRate NDCG | BPR | BaseReader | BaseModel.GeneralModel | general | '' |
SeqReader | BaseModel.SequentialModel | sequential | '' | ||||
ContextReader | BaseContextModel.ContextModel | context | 'TopK' | ||||
CTR Prediction | CTRRunner | BPR, BCE | AUC Logloss | ContextReader | BaseContextModel.ContextCTRModel | context | 'CTR' |
Impression-based Ranking | 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' |
The main arguments are listed below.
Args | Default | Description |
---|---|---|
model_name | 'BPRMF' | The name of the model class. |
model_mode | '' | The task mode for the model to implement. |
lr | 1e-3 | Learning rate. |
l2 | 0 | Weight decay in optimizer. |
test_all | 0 | Wheter to rank all the items during evaluation. |
metrics | 'NDCG,HR' | The list of evaluation metrics (seperated by comma). |
topk | '5,10,20' | The list of K in evaluation metrics (seperated by comma). |
num_workers | 5 | Number of processes when preparing batches. |
batch_size | 256 | Batch size during training. |
eval_batch_size | 256 | Batch size during inference. |
load | 0 | Whether to load model checkpoint and continue to train. |
train | 1 | Wheter to perform model training. |
regenerate | 0 | Wheter to regenerate intermediate files. |
random_seed | 0 | Random seed of everything. |
gpu | '0' | The visible GPU device (pass an empty string '' to only use CPU). |
buffer | 1 | Whether to buffer batches for dev/test. |
history_max | 20 | The maximum length of history for sequential models. |
num_neg | 1 | The number of negative items for each training instance. |
test_epoch | -1 | Print test set metrics every test_epoch during training (-1: no print). |
We have implemented the following methods (still updating):
General Recommenders
- Bayesian personalized ranking from implicit feedback (BPRMF [UAI'09])
- Neural Collaborative Filtering (NeuMF [WWW'17])
- Learning over Knowledge-Base Embeddings for Recommendation (CFKG [SIGIR'18])
- LightGCN: Simplifying and Powering Graph Convolution Network for Recommendation (LightGCN [SIGIR'20])
- Bootstrapping User and Item Representations for One-Class Collaborative Filtering (BUIR [SIGIR'21])
- Towards Representation Alignment and Uniformity in Collaborative Filtering (DirectAU [KDD'22])
Sequential Recommenders
- Factorizing Personalized Markov Chains for Next-Basket Recommendation (FPMC [WWW'10])
- Session-based Recommendations with Recurrent Neural Networks (GRU4Rec [ICLR'16])
- Neural Attentive Session-based Recommendation (NARM [CIKM'17])
- Personalized Top-N Sequential Recommendation via Convolutional Sequence Embedding (Caser [WSDM'18])
- Self-attentive Sequential Recommendation (SASRec [IEEE'18])
- Modeling Item-specific Temporal Dynamics of Repeat Consumption for Recommender Systems (SLRC [WWW'19])
- Time Interval Aware Self-Attention for Sequential Recommendation (TiSASRec [WSDM'20])
- Make It a Chorus: Knowledge- and Time-aware Item Modeling for Sequential Recommendation (Chorus [SIGIR'20])
- Controllable Multi-Interest Framework for Recommendation (ComiRec [KDD'20])
- Towards Dynamic User Intention: Temporal Evolutionary Effects of Item Relations in Sequential Recommendation (KDA [TOIS'21])
- Sequential Recommendation with Multiple Contrast Signals (ContraRec [TOIS'22])
- Target Interest Distillation for Multi-Interest Recommendation (TiMiRec [CIKM'22])
Context-aware Recommenders
General Context-aware Recommenders
- Factorization Machines (FM [ICDM'10])
- Wide {&} Deep Learning for Recommender Systems (WideDeep [DLRS@Recsys'16])
- Attentional Factorization Machines: Learning the Weight of Feature Interactions via Attention Networks (AFM [IJCAI'17])
- DeepFM: A Factorization-Machine based Neural Network for CTR Prediction (DeepFM [IJCAI'17])
- Deep & Cross Network for Ad Click Predictions (DCN [KDD'17])
- AutoInt: Automatic Feature Interaction Learning via Self-Attentive Neural Networks (AutoInt [CIKM'18])
- xdeepfm: Combining explicit and implicit feature interactions for recommender systems (xDeepFM [KDD'18])
- DCN v2: Improved deep & cross network and practical lessons for web-scale learning to rank systems (DCNv2 [WWW'21])
- Looking at CTR Prediction Again: Is Attention All You Need? (SAM [SIGIR'21])
- FinalMLP: an enhanced two-stream MLP model for CTR prediction (FinalMLP [AAAI'23])
Sequential Context-aware Recommenders
- Deep interest network for click-through rate prediction (DIN [KDD'18])
- End-to-end user behavior retrieval in click-through rateprediction model (ETA [CoRR'18])
- Deep interest evolution network for click-through rate prediction (DIEN [AAAI'19])
- CAN: feature co-action network for click-through rate prediction (CAN [WSDM'22])
- Sampling is all you need on modeling long-term user behaviors for CTR prediction (SDIM[CIKM'22])
Impression-based Re-ranking Models
- Personalized Re-ranking for Recommendatio (PRM [RecSys'19])
- SetRank: Learning a Permutation-Invariant Ranking Model for Information Retrieval (SIGIR [SIGIR'20])
- Multi-Level Interaction Reranking with User Behavior History (MIR[SIGIR'22])
Experimental results and corresponding configurations are shown in XXX.
If you find ReChorus is helpful to your research, please cite either of the following papers. Thanks!
@article{li2024rechorus2,
title={ReChorus2. 0: A Modular and Task-Flexible Recommendation Library},
author={Li, Jiayu and Li, Hanyu and He, Zhiyu and Ma, Weizhi and Sun, Peijie and Zhang, Min and Ma, Shaoping},
journal={arXiv preprint arXiv:2405.18058},
year={2024}
}
@inproceedings{wang2020make,
title={Make it a chorus: knowledge-and time-aware item modeling for sequential recommendation},
author={Wang, Chenyang and Zhang, Min and Ma, Weizhi and Liu, Yiqun and Ma, Shaoping},
booktitle={Proceedings of the 43rd International ACM SIGIR Conference on Research and Development in Information Retrieval},
pages={109--118},
year={2020}
}
@article{王晨阳2021rechorus,
title={ReChorus: 一个综合, 高效, 易扩展的轻量级推荐算法框架},
author={王晨阳 and 任一 and 马为之 and 张敏 and 刘奕群 and 马少平},
journal={软件学报},
volume={33},
number={4},
pages={0--0},
year={2021}
}
This is also our public implementation for the following papers (codes and datasets to reproduce the results can be found at corresponding branch):
- Chenyang Wang, Min Zhang, Weizhi Ma, Yiqun Liu, and Shaoping Ma. Make It a Chorus: Knowledge- and Time-aware Item Modeling for Sequential Recommendation. 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. Towards Dynamic User Intention: Temporal Evolutionary Effects of Item Relations in Sequential Recommendation. 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. Sequential Recommendation with Multiple Contrast Signals. 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. Target Interest Distillation for Multi-Interest Recommendation. In CIKM'22.
git clone -b CIKM22 https://github.com/THUwangcy/ReChorus.git
ReChorus 1.0: Chenyang Wang ([email protected])
ReChorus 2.0: Jiayu Li ([email protected]), Hanyu Li ([email protected])