☃️ ColdRec is a comprehensive open-source toolkit for cold-start recommendation. In coldrec, models follow a unified pipeline, the datasets follow a unified division, and tasks include cold user/item recommendation, warm user/item recommendation, and overall user/item recommendation, targeting at providing the community with a comprehensive evaluation for cold-start recommendation.
🔧 TODO We are now enhancing the codebase for user-friendly:
- Enforce a consistent code style.
- Add representative new models.
- Redundancies removal and input type standardization.
- Fix bugs and optimize the toolkit efficiency mentioned in the issues. (Thanks for that!)
- 🥳 Add automatic hyper-parameter tuning, you can install one more base library optuna to include this module.
- Toolkit building with related works before 2024.
ColdRec hopes to avoid the complicated and tedious packaging process and uses native pytorch and a small number of necessary libraries to build the codebase.
python >= 3.8.0
torch >= 1.11.0
faiss-gpu >= 1.7.3
pandas >= 2.0.3
numpy >= 1.24.4
scikit-learn >= 1.3.2
pickle >= 0.7.5
optuna >= 3.6.1 (If you need automatic hyper-parameter tuning) 1️⃣ Dataset Preprocess
We have provided the preprocessed datasets in Google Drive. You can download the dataset from the Google Drive link directly, unzip it, and place it into the ./data folder. Then, you can process it into the format for model training with simple two scripts, of which the details can be found in the page of dataset details.
2️⃣ Warm Embedding Pre-Training
This step is not necessary, but since most of the work requires this step, it is recommended to complete this step to fully evaluate all models. We have provided both widely adopted collaborative filtering models as warm recommenders. You can obtain the pre-trained warm user/item embeddings with the following two options:
Options 1: You can directly access the BPR-MF pre-trained embeddings at the Google Drive. Then, the embedding folder associated to each dataset should be placed in the ./emb folder.
Options 2: You can also pre-train the warm embedding by yourself. Specifically, you can simply obtain the pre-trained warm embeddings by running the following script:
python main.py --dataset [DATASET NAME] --model [WARM RECOMMENDER] --cold_object [user/item]In the above script, the [DATASET NAME] for --dataset should be replaced by your target dataset name, such as movielens. Then, the [WARM RECOMMENDER] for --model should be selected as the warm recommender type (MF, NGCF, LightGCN, NCL, SimGCL, and XSimGCL). Finally, the [user/item] for --cold_object should be selected as user or item for the user cold-start setting or item cold-start setting.
3️⃣ Cold-Start Model Training and Evaluation
Coming to this step, you can start to train the cold-start model with one script:
python main.py --dataset [DATASET NAME] --model [MODEL NAME] --cold_object [user/item]In the above script, the [MODEL NAME] for --model is the expected model name, where we have provided 20 representative models as the Supported Models. You can also flexibly register your own model with the ColdRec framework for evaluation.
4️⃣ (Option) Automatic Hyper-parameter Tuning
ColdRec also supports automatic hyper-parameter tuning. You can tune hyper-parameters with optuna with one script:
python param_search.py --dataset [DATASET NAME] --model [MODEL NAME] --cold_object [user/item]You can flexibly set the tuning range in param_search.py.
(* Backbone model)
The codebase architecture of ColdRec on some foundational operators is based on the excellent repo SELFRec. Thanks to their pioneering open-sourced work!
The suggestions provided by open-source community users are of great help in improving this framework. Thanks to them!
