RecBole Documentation

RecBole is a unified, comprehensive, and efficient recommendation framework built on PyTorch. It is designed to help researchers reproduce and develop recommendation models across four major categories:

• General Recommendation
• Sequential Recommendation
• Context-aware Recommendation
• Knowledge-based Recommendation

Key features include an extensible data structure for unifying various datasets, support for 94 recommendation algorithms, efficient GPU-accelerated execution, and extensive standard evaluation protocols.

RecBole supports distributed training and evaluation using several key concepts to manage computing units across nodes:

• rank: The sequence number of a process (computing unit). The entire distribution is composed of multiple ranks.
• node: A physical machine or container, which may contain multiple GPUs.
• local rank: The relative sequence number of a process within a specific node, independent of other nodes.
• world size: The total number of ranks in the entire global distributed task.

RecBole supports several training strategies depending on the model type:

• Non-gradient training: Used for traditional CPU-based collaborative filter models.
• Automatic gradient descent: The default strategy for mainstream neural-based models.
• Two-stage training: Prepared for pretraining-based models.

Users can customize the training process by implementing a custom Trainer. For hyper-parameter optimization, RecBole uses hyperopt. You can define hyper-parameter ranges in a configuration file using the hyperopt format to output optimal parameters and results.

RecBole is a one-stop managed framework for the full lifecycle of recommendation systems, including data processing, model development, algorithm training, and scientific evaluation. The ecosystem consists of several specialized sub-packages and datasets:

Core Versions

• RecBole 1.0
• RecBole 2.0

Extension Tools

• RecBole-MetaRec: Meta-learning for recommendation.
• RecBole-DA: Data Augmentation.
• RecBole-Debias: Debias techniques.
• RecBole-FairRec: Fairness in recommendation.
• RecBole-CDR: Counterfactual Data Reasoning.
• RecBole-TRM: Transformer-based models.
• RecBole-GNN: Graph Neural Networks.
• RecBole-PJF: Pattern-based Joint Filtering.

Datasets

• RecSysDatasets: A dedicated repository for recommendation system datasets.

RecBole uses 'Atomic Files' to format input for recommendation tasks. Files are identified by their suffixes. Use these suffixes to organize your data files:

• .inter: User-item interaction (e.g., user_id, item_id, rating)
• .user: User features (e.g., user_id, age)
• .item: Item features (e.g., item_id, category)
• .kg: Knowledge graph triplets (e.g., head_entity, tail_entity, relation)
• .link: Item-entity linkage data (e.g., entity, item_id)
• .net: Social graph data (e.g., source, target)

RecBole uses a structured data flow to transform raw data into model inputs, facilitating extensibility and reusability. The pipeline consists of four main stages:

1. Raw Input: Unprocessed raw input datasets.
2. Atomic Files: Basic components used to characterize the input for various recommendation tasks.
3. Dataset: A structure primarily based on pandas.DataFrame. This stage includes preprocessing functions such as k-core data filtering and missing value imputation.
4. DataLoader: The final stage that feeds data into recommendation algorithms. It utilizes the Interaction data structure.

RecBole allows you to control experiment setups—including data processing, data splitting, training, and evaluation—by configuring various parameters. Settings are categorized into five main groups:

1. Environment settings: Global environment configurations.
2. Data settings: Parameters related to data loading and processing.
3. Model settings: Parameters specific to the chosen recommendation model (refer to the specific model's documentation for these).
4. Training settings: Parameters controlling the training process.
5. Evaluation settings: Parameters for evaluating model performance.

If you have cloned the source code, you can run a quick demonstration using the provided script. By default, this runs the BPR model on the ml-100k dataset.

To customize parameters like learning_rate or embedding_size, pass them as command-line arguments. To change the model, use the --model flag.

To tune SHAN hyper-parameters using RecBole's HyperTuning, create a configuration file (e.g., hyper.test) with the desired parameter ranges.

Example hyper.test content:

learning_rate choice [0.001]
embedding_size choice [64]
short_item_length choice [1,2,4,8]
reg_weight choice ['[0.0,0.0]','[0.01,0.0001]']

Then, execute the tuning process using run_hyper.py from the RecBole source directory.

python run_hyper.py --model=[model_name] --dataset=[dataset_name] --config_files=[config_files_path] --params_file=hyper.test

You can use RecBole's HyperTuning to optimize CDAE.

1. Create a file named hyper.test containing the parameter ranges. For example, to tune the learning rate:

learning_rate choice [0.01,0.005,0.001,0.0005,0.0001]

2. Run the tuning script run_hyper.py using the following command structure:

python run_hyper.py --model=[model_name] --dataset=[dataset_name] --config_files=[config_files_path] --params_file=hyper.test