recommenders README

The project's README from github.com/recommenders-team/recommenders. As one markdown file: README.md.

Documentation status License Black PyPI Version Python Versions


What's New (April, 2025)

We reached 20,000 stars!!

We are happy to announce that we have reached 20,000 stars on GitHub! Thank you for your support and contributions to the Recommenders project. We are excited to continue building and improving this project with your help.

Check out the release Recommenders 1.2.1!

We fixed a lot of bugs due to dependencies, improved security, reviewed the notebooks and the libraries.

Introduction

Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems.

Recommenders is a project under the Linux Foundation of AI and Data.

This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks:

Several utilities are provided in recommenders to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. See the Recommenders documentation.

For a more detailed overview of the repository, please see the documents on the wiki page.

For some of the practical scenarios where recommendation systems have been applied, see scenarios.

Getting Started

We recommend uv for environment management (10-100x faster than conda/pip), and VS Code for development. To install the recommenders package and run an example notebook on Linux/WSL:

# 1. Install gcc if it is not installed already. On Ubuntu, this could done by using the command
# sudo apt install gcc

# 2. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Create and activate a new virtual environment
uv venv ~/.venvs/recommenders --python 3.11
source ~/.venvs/recommenders/bin/activate

# 4. Install the core recommenders package. It can run all the CPU notebooks.
uv pip install recommenders

# 5. Create a Jupyter kernel
uv pip install ipykernel
python -m ipykernel install --user --name recommenders --display-name "Python (recommenders)"

# 6. Clone this repo within VSCode or using command line:
git clone https://github.com/recommenders-team/recommenders.git

# 7. Within VSCode:
#   a. Open a notebook, e.g., examples/00_quick_start/sar_movielens.ipynb;
#   b. Select Jupyter kernel "Python (recommenders)";
#   c. Run the notebook.

For more information about setup on other platforms (e.g., Windows and macOS) and different configurations (e.g., GPU, Spark and experimental features), see the Setup Guide.

In addition to the core package, several extras are also provided, including:

Algorithms

The table below lists the recommendation algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm.

Algorithm Type Description Example
Alternating Least Squares (ALS) Collaborative Filtering Matrix factorization algorithm for explicit or implicit feedback in large datasets, optimized for scalability and distributed computing capability. It works in the PySpark environment. Quick start / Deep dive
Attentive Asynchronous Singular Value Decomposition (A2SVD)* Collaborative Filtering Sequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanism. It works in the CPU/GPU environment. Quick start
Cornac/Bayesian Personalized Ranking (BPR) Collaborative Filtering Matrix factorization algorithm for predicting item ranking with implicit feedback. It works in the CPU environment. Deep dive
Cornac/Bilateral Variational Autoencoder (BiVAE) Collaborative Filtering Generative model for dyadic data (e.g., user-item interactions). It works in the CPU/GPU environment. Deep dive
Convolutional Sequence Embedding Recommendation (Caser) Collaborative Filtering Algorithm based on convolutions that aim to capture both user’s general preferences and sequential patterns. It works in the CPU/GPU environment. Quick start
Deep Knowledge-Aware Network (DKN)* Content-Based Filtering Deep learning algorithm incorporating a knowledge graph and article embeddings for providing news or article recommendations. It works in the CPU/GPU environment. Quick start / Deep dive
Extreme Deep Factorization Machine (xDeepFM)* Collaborative Filtering Deep learning based algorithm for implicit and explicit feedback with user/item features. It works in the CPU/GPU environment. Quick start
Embedding Dot Bias Collaborative Filtering General purpose algorithm with embeddings and biases for users and items. It works in the CPU/GPU environment. Quick start
LightFM/Factorization Machine Collaborative Filtering Factorization Machine algorithm for both implicit and explicit feedbacks. It works in the CPU environment. Quick start
LightGBM/Gradient Boosting Tree* Content-Based Filtering Gradient Boosting Tree algorithm for fast training and low memory usage in content-based problems. It works in the CPU/GPU/PySpark environments. Quick start in CPU / Deep dive in PySpark
LightGCN Collaborative Filtering Deep learning algorithm which simplifies the design of GCN for predicting implicit feedback. It works in the CPU/GPU environment. Deep dive
GeoIMC* Collaborative Filtering Matrix completion algorithm that takes into account user and item features using Riemannian conjugate gradient optimization and follows a geometric approach. It works in the CPU environment. Quick start
GRU Collaborative Filtering Sequential-based algorithm that aims to capture both long and short-term user preferences using recurrent neural networks. It works in the CPU/GPU environment. Quick start
Multinomial VAE Collaborative Filtering Generative model for predicting user/item interactions. It works in the CPU/GPU environment. Deep dive
Neural Recommendation with Long- and Short-term User Representations (LSTUR)* Content-Based Filtering Neural recommendation algorithm for recommending news articles with long- and short-term user interest modeling. It works in the CPU/GPU environment. Quick start
Neural Recommendation with Attentive Multi-View Learning (NAML)* Content-Based Filtering Neural recommendation algorithm for recommending news articles with attentive multi-view learning. It works in the CPU/GPU environment. Quick start
Neural Collaborative Filtering (NCF) Collaborative Filtering Deep learning algorithm with enhanced performance for user/item implicit feedback. It works in the CPU/GPU environment. Quick start / Deep dive
Neural Recommendation with Personalized Attention (NPA)* Content-Based Filtering Neural recommendation algorithm for recommending news articles with personalized attention network. It works in the CPU/GPU environment. Quick start
Neural Recommendation with Multi-Head Self-Attention (NRMS)* Content-Based Filtering Neural recommendation algorithm for recommending news articles with multi-head self-attention. It works in the CPU/GPU environment. Quick start
Next Item Recommendation (NextItNet) Collaborative Filtering Algorithm based on dilated convolutions and residual network that aims to capture sequential patterns. It considers both user/item interactions and features. It works in the CPU/GPU environment. Quick start
Restricted Boltzmann Machines (RBM) Collaborative Filtering Neural network based algorithm for learning the underlying probability distribution for explicit or implicit user/item feedback. It works in the CPU/GPU environment. Quick start / Deep dive
Riemannian Low-rank Matrix Completion (RLRMC)* Collaborative Filtering Matrix factorization algorithm using Riemannian conjugate gradients optimization with small memory consumption to predict user/item interactions. It works in the CPU environment. Quick start
Simple Algorithm for Recommendation (SAR)* Collaborative Filtering Similarity-based algorithm for implicit user/item feedback. It works in the CPU environment. Quick start / Deep dive
Self-Attentive Sequential Recommendation (SASRec) Collaborative Filtering Transformer based algorithm for sequential recommendation. It works in the CPU/GPU environment. Quick start
Short-term and Long-term Preference Integrated Recommender (SLi-Rec)* Collaborative Filtering Sequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanism, a time-aware controller and a content-aware controller. It works in the CPU/GPU environment. Quick start
Multi-Interest-Aware Sequential User Modeling (SUM)* Collaborative Filtering An enhanced memory network-based sequential user model which aims to capture users' multiple interests. It works in the CPU/GPU environment. Quick start
Sequential Recommendation Via Personalized Transformer (SSEPT) Collaborative Filtering Transformer based algorithm for sequential recommendation with User embedding. It works in the CPU/GPU environment. Quick start
Standard VAE Collaborative Filtering Generative Model for predicting user/item interactions. It works in the CPU/GPU environment. Deep dive
Surprise/Singular Value Decomposition (SVD) Collaborative Filtering Matrix factorization algorithm for predicting explicit rating feedback in small datasets. It works in the CPU/GPU environment. Deep dive
Term Frequency - Inverse Document Frequency (TF-IDF) Content-Based Filtering Simple similarity-based algorithm for content-based recommendations with text datasets. It works in the CPU environment. Quick start
Vowpal Wabbit (VW)* Content-Based Filtering Fast online learning algorithms, great for scenarios where user features / context are constantly changing. It uses the CPU for online learning. Deep dive
Wide and Deep Collaborative Filtering Deep learning algorithm that can memorize feature interactions and generalize user features. It works in the CPU/GPU environment. Quick start
xLearn/Factorization Machine (FM) & Field-Aware FM (FFM) Collaborative Filtering Quick and memory efficient algorithm to predict labels with user/item features. It works in the CPU/GPU environment. Deep dive

NOTE: * indicates algorithms invented/contributed by Microsoft.

Independent or incubating algorithms and utilities are candidates for the contrib folder. This will house contributions which may not easily fit into the core repository or need time to refactor or mature the code and add necessary tests.

Algorithm Type Description Example
SARplus * Collaborative Filtering Optimized implementation of SAR for Spark Quick start

Algorithm Comparison

We provide a benchmark notebook to illustrate how different algorithms could be evaluated and compared. In this notebook, the MovieLens dataset is split into training/test sets at a 75/25 ratio using a stratified split. A recommendation model is trained using each of the collaborative filtering algorithms below. We utilize empirical parameter values reported in literature here. For ranking metrics we use k=10 (top 10 recommended items). We run the comparison on a machine with 24 CPUs, 30Gb of RAM, and 1 GPU GeForce RTX 5090 GPU with 24Gb of memory. Spark ALS is run in local standalone mode. In this table we show the results on Movielens 100k. For BPR, ratings are binarized with a threshold of 3.5 (ratings ≥ 4 treated as positive implicit feedback) for both training and evaluation.

Algo MAP nDCG@k Precision@k Recall@k RMSE MAE R2 Explained Variance
ALS 0.010400 0.032800 0.038100 0.013200 0.966732 0.752552 0.267438 0.263534
BiVAE 0.330000 0.471700 0.411300 0.224300 N/A N/A N/A N/A
BPR 0.229200 0.362300 0.285500 0.251700 N/A N/A N/A N/A
embdotbias 0.054900 0.119000 0.107000 0.042300 0.992760 0.776040 0.223344 0.223393
LightGCN 0.277200 0.419100 0.359900 0.197100 N/A N/A N/A N/A
NCF 0.260300 0.393100 0.346900 0.181900 N/A N/A N/A N/A
SAR 0.258500 0.393800 0.340600 0.185400 1.229103 1.035996 -0.487843 0.097283

Contributing

This project welcomes contributions and suggestions. Before contributing, please see our contribution guidelines.

This project adheres to this Code of Conduct in order to foster a welcoming and inspiring community for all.

References

recommenders (recommenders-team/recommenders)

Searching Database…

22K ·GitHub
Recommenders
这是做什么的？一个开源的 Python 库和 notebook 合集，提供构建、评估和部署推荐系统的最佳实践——它是 Linux Foundation of AI & Data 基金会的项目，最初由微软发起。
它是 Python 库，还是一堆示例 notebook？两者都是：既有可以通过 pip 安装的 'recommenders' 包，里面包含工具函数和算法实现；也有一批 Jupyter notebook，覆盖五大任务——数据准备、建模、评估、超参数调优和上线部署。
我怎么把它跑起来？先用 uv 搭建 Python 环境（团队说它比 conda/pip 快 10 到 100 倍），安装 recommenders 包，然后运行其中一个 Quick start notebook；官方文档给出的路径是 Linux/WSL 配合 VS Code。
里面所有算法都能直接用于生产环境吗？大部分可以，但有一个 [experimental] 附加部分，收录未经充分测试、可能需要额外安装步骤的模型；社区孵化中的贡献也单独放在 contrib 文件夹里。
它在 Windows 和 macOS 上能用吗，还是只支持 Linux？三个平台都支持：入门示例针对 Linux/WSL，Setup Guide 则覆盖了 Windows、macOS 等其他平台，还包括 GPU、Spark 和实验性配置。
它包含哪些推荐算法？超过 30 种，既有 ALS、SAR、SVD、LightGBM、TF-IDF 这类经典算法，也有 NCF、xDeepFM、LightGCN、SASRec、Wide & Deep 等深度学习模型，还有一整套新闻推荐算法（NRMS、NPA、LSTUR、NAML）。这些算法涵盖协同过滤和基于内容的过滤，每个都配有 Quick start 或 Deep dive notebook。
针对我的数据，该怎么在这些算法里选？项目自带一个基准测试 notebook，在 MovieLens 100k 数据集上训练各协同过滤算法（75/25 分层切分，按 k=10 计算排序指标），并比较 MAP、nDCG、Precision、Recall、RMSE 和 MAE；这个包还提供离线评估工具，可以在你自己的数据上打分。
训练出的模型能上线到生产环境吗？可以——上线部署（operationalization）是五大核心任务之一，项目提供了在 Azure 生产环境中部署模型的指南。另外还有 SARplus，一个针对 Spark 优化的 SAR 实现。
这是微软的官方项目吗？它起源于微软——README 会标注哪些算法由微软发明或贡献——但现在归属 Linux Foundation of AI & Data。最新版本是 1.2.1，项目在 2025 年 4 月突破了 20000 个 GitHub star。
What are similar projects?metaflow, the-algorithm-ml, amazon-sagemaker-examples, skypilot, deeplearning4j, ray, spaCy, Made-With-ML
Which topics is it in?ranking, recommendation-system, spark, mlops, jupyter-notebook, azure, microsoft, best-practices, evaluation, data-science, artificial-intelligence, kubernetes
Creator
recommenders-team
Size
228.9 MB
Stars
22K
Updated
CommitSep 28Release1.2.1Dec 24
Age
8y
Commits · 90 Days