RecBole

1.2.1 · active · verified Fri Apr 17

RecBole is a unified, comprehensive, and efficient Python library for recommendation systems, built on PyTorch. It provides a wide array of state-of-the-art recommendation models and datasets, featuring standardized data processing, training, and evaluation pipelines. The library undergoes active development, with major updates and new versions typically released every few months, incorporating user feedback and architectural improvements.

Common errors

```
ModuleNotFoundError: No module named 'torch'
```
cause PyTorch is not installed or not correctly linked. RecBole depends heavily on PyTorch.

fix Install PyTorch: `pip install torch` for CPU, or follow the PyTorch official website for GPU-compatible installation commands (`pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8 as an example).
```
FileNotFoundError: [Errno 2] No such file or directory: 'dataset/your_dataset_name/your_dataset_name.inter'
```
cause The specified dataset or its interaction file is not found in the expected location. RecBole looks for datasets in a 'dataset' folder by default.

fix Either ensure the dataset files (e.g., `ml-100k.inter`, `ml-100k.item`) are in `dataset/ml-100k/`, or specify `config['data_path'] = '/path/to/your/dataset'` in your configuration.
```
RuntimeError: CUDA error: device-side assert triggered
```
cause This typically indicates an issue with GPU memory, invalid input to a CUDA kernel, or an incorrect PyTorch-CUDA installation mismatch.

fix Check GPU memory usage, reduce batch size. Ensure PyTorch and your CUDA driver are compatible. Reinstall `recbole[gpu]` and PyTorch, making sure to use the correct `pip` command for your CUDA version.

Warnings

breaking Major architectural overhauls in versions like v1.0.0, v1.1.0, and v1.2.0 introduced significant changes to the framework, especially affecting the data module and configuration API.
Fix: Review the official documentation for the specific version you are upgrading to. Pay close attention to changes in data loading, dataset preparation (e.g., `create_dataset`), and how configuration objects (`Config`) are initialized and passed.
gotcha RecBole often requires specific versions of PyTorch. Installing `recbole[gpu]` ensures GPU dependencies are pulled, but manual CUDA setup and matching PyTorch-CUDA versions are critical.
Fix: For GPU usage, ensure your system has a compatible CUDA toolkit installed. Then, use `pip install recbole[gpu]` or `pip install recbole torch==X.Y.Z+cuXXX` where `X.Y.Z` and `cuXXX` match your CUDA version and desired PyTorch build. Always check the official PyTorch installation guide for the correct command.
gotcha Configuring datasets and data preprocessing can be complex. Incorrect paths, invalid split ratios, or missing necessary dataset files (like `.inter`, `.item`, `.user` files) are common sources of errors.
Fix: Ensure your dataset files are correctly placed in the `dataset` directory (e.g., `dataset/ml-100k/ml-100k.inter`). For custom datasets, carefully follow the data format specification in the RecBole documentation. Use `config['data_path']` if your dataset is not in the default location.

Install

pip install recbole Basic installation (CPU)
pip install recbole[gpu] Installation with GPU support (requires CUDA setup)

Imports

run_recbole

from recbole.quick_start import run_recbole

Config
wrong:
```
from recbole.model.abstract_recommender import AbstractRecommender
```
correct:
```
from recbole.config import Config
```
While AbstractRecommender is a base class, most users will start with `run_recbole` or `Config` to define their model/dataset.

Quickstart

This quickstart demonstrates how to run a basic BPR recommendation model on the `ml-100k` dataset using `run_recbole`. RecBole will automatically download and preprocess the dataset if not found. The configuration dictionary allows for inline specification of model, dataset, and evaluation parameters without needing a separate YAML file.

import os
import torch
from recbole.quick_start import run_recbole

# Ensure you have a 'dataset' folder in the current directory
# and 'ml-100k' dataset downloaded/prepared, or RecBole will download it.

# Basic configuration for running a BPR model on ml-100k dataset
# Using CPU by default, or GPU if available and recbole[gpu] was installed.
config_dict = {
    'model': 'BPR',
    'dataset': 'ml-100k',
    'eval_args': {
        'split_ratio': '0.8:0.1:0.1', # Train:Valid:Test split
        'group_by': 'user' # Ensure evaluation is fair per user
    },
    'use_gpu': torch.cuda.is_available() # Dynamically check for GPU
}

print(f"Running RecBole with config: {config_dict}")

# Run the recommendation experiment
run_recbole(config_dict=config_dict)

view raw JSON →