Quick Start

Here are some simple examples that illustrate the usage of RecBole.


Quick-start From Source

With the source code of RecBole, you can run the provided script for initial usage of our library:

python run_recbole.py

This script will run the BPR model on the ml-100k dataset. Typically, this example takes less than one minute. We will obtain some output like:

INFO ml-100k
The number of users: 944
Average actions of users: 106.04453870625663
The number of items: 1683
Average actions of items: 59.45303210463734
The number of inters: 100000
The sparsity of the dataset: 93.70575143257098%

INFO Evaluation Settings:
Group by user_id
Ordering: {'strategy': 'shuffle'}
Splitting: {'strategy': 'by_ratio', 'ratios': [0.8, 0.1, 0.1]}
Negative Sampling: {'strategy': 'full', 'distribution': 'uniform'}

INFO BPRMF(
    (user_embedding): Embedding(944, 64)
    (item_embedding): Embedding(1683, 64)
    (loss): BPRLoss()
)
Trainable parameters: 168128

Begin training:

INFO epoch 0 training [time: 0.27s, train loss: 27.7231]
INFO epoch 0 evaluating [time: 0.12s, valid_score: 0.021900]
INFO valid result:
recall@10: 0.0073  mrr@10: 0.0219  ndcg@10: 0.0093  hit@10: 0.0795  precision@10: 0.0088

...

INFO epoch 63 training [time: 0.19s, train loss: 4.7660]
INFO epoch 63 evaluating [time: 0.08s, valid_score: 0.394500]
INFO valid result:
recall@10: 0.2156  mrr@10: 0.3945  ndcg@10: 0.2332  hit@10: 0.7593  precision@10: 0.1591

INFO Finished training, best eval result in epoch 52
INFO Loading model structure and parameters from saved/***.pth
INFO best valid result:
recall@10: 0.2169  mrr@10: 0.4005  ndcg@10: 0.235  hit@10: 0.7582  precision@10: 0.1598
INFO test result:
recall@10: 0.2368  mrr@10: 0.4519  ndcg@10: 0.2768  hit@10: 0.7614  precision@10: 0.1901

Note that using the quick start pipeline we provide, the original dataset will be divided into training set, validation set and test set by default. We optimize model parameters on the training set, do parameter selection according to the results on the validation set, and finally report the results on the test set.

If you want to change the parameters, such as learning_rate, embedding_size, just set the additional command parameters as you need:

python run_recbole.py --learning_rate=0.0001 --embedding_size=128

If you want to change the models, just run the script by setting additional command parameters:

python run_recbole.py --model=[model_name]

model_name is the model to be run, such as BPR and FM. RecBole covers four major categories of recommendation algorithms, namely general recommendation, context-aware recommendation, sequential recommendation and knowledge based recommendation. More details can be found in Model Introduction.

If you want to change the datasets, please refer to Data Introduction.


Quick-start From API

If RecBole is installed from pip or Conda, you can create a new python file (e.g., named run.py), and write the following code:

from recbole.quick_start import run_recbole
run_recbole()

Then run the following command:

python run.py --dataset=ml-100k --model=BPR

This will perform the training and test of the BPR model on the ml-100k dataset.

If you want to run different models, parameters or datasets, the operations are same with Quick-start From Source.

More usage details can be found in API Doc.