recommenders

recommenders-teamMIT活跃维护有专家点评

微软出品的推荐系统实践库，提供从数据准备、模型训练到部署上线的完整示例和最佳实践，帮算法工程师快速搭建推荐与排序模型。

Best Practices on Recommendation Systems

1.2.1发布于 2024-12-24 07:39 UTC21,987star +6 / 7 天3,330fork同步于 2026-11-10 23:25 UTC

推荐系统排序模型模型训练部署上线 Python

对比 GitHub 官网 ai artificial-intelligence data-science deep-learning jupyter-notebook

专家点评

上手难度：进阶更新于 2026-11-11

推荐系统从 notebook 到上线的参考实现集合，用来替代自己从零搭一套算法基线

适用场景

新项目要快速拉起一个可对比的基线：ALS/BPR/NCF 这些实现和评估工具都在，省掉自己写 train/test split 和离线指标；换别的就得从论文或零散 repo 拼
做算法选型评审：同一套数据加载和评估口径下横向跑多个模型，比各模型各自 repo 的指标更有可比性
教学或团队内训：notebook 按数据准备→建模→评估→调参→上线分节，能直接当教材走一遍
需要 Spark 侧的大规模召回/排序实验：装了 [spark] extra 后能复用同一套工具函数，不用另起一套代码

踩坑

只 pip install recommenders 跑不了 GPU 和 Spark 模型，得按模型选 [gpu]/[spark] extra；装之前先确认目标 notebook 属于哪类，否则会在 import 阶段才发现缺依赖
notebook 不是装完包就能开：要先 clone 仓库、注册 ipykernel 内核，Linux/WSL 还得先有 gcc，纯 pip 安装的用户会卡在这一步
issue 里 OOM 类问题（NCFDataset、RBM affinity matrix）被反复提出，跑这些模型时对内存的预期要留余量；具体阈值 README 没写，得自己按数据规模试

怎么上手

由 README 提炼，执行前请确认

原文

uv venv ~/.venvs/recommenders --python 3.11
source ~/.venvs/recommenders/bin/activate
uv pip install recommenders

硬件要求按 README 说明

核心包可在 CPU 上运行全部 CPU notebook；GPU 模型需安装 [gpu] extra，Spark 模型需 [spark] extra；README 未给出具体显存或 GPU 型号要求。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

微软开源的推荐系统最佳实践库，用 Jupyter notebook 演示从数据准备到上线的完整流程

微软出品的推荐系统实践库，提供从数据准备、模型训练到部署上线的完整示例和最佳实践，帮算法工程师快速搭建推荐与排序模型。

核心能力

用 Jupyter notebook 演示数据准备、建模、评估、调参与上线五个环节
内置 ALS、xDeepFM、BPR、BiVAE、Caser 等经典与深度学习算法实现
提供数据加载、训练测试集划分、离线指标评估等通用工具函数
通过 gpu、spark、dev、all、experimental 等 extras 按需安装依赖
附带 Azure 上模型运营化的示例流程

容易踩的坑

GPU 和 Spark 模型需额外安装 [gpu]、[spark] 等 extras，只装核心包跑不了；Linux/WSL 上需先装 gcc；示例 notebook 需先克隆仓库并注册 ipykernel 内核才能运行。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

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:

Prepare Data: Preparing and loading data for each recommendation algorithm.
Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares (ALS) or eXtreme Deep Factorization Machines (xDeepFM).
Evaluate: Evaluating algorithms with offline metrics.
Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models.
Operationalize: Operationalizing models in a production environment on Azure.

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:

[gpu]: Needed for running GPU models.
[spark]: Needed for running Spark models.
[dev]: Needed for development for the repo.
[all]: [gpu]|[spark]|[dev]
[experimental]: Models that are not thoroughly tested and/or may require additional steps in installation.

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

D. Li, J. Lian, L. Zhang, K. Ren, D. Lu, T. Wu, X. Xie, "Recommender Systems: Frontiers and Practices", Springer, Beijing, 2024. Available on this link.
A. Argyriou, M. González-Fierro, and L. Zhang, "Microsoft Recommenders: Best Practices for Production-Ready Recommendation Systems", WWW 2020: International World Wide Web Conference Taipei, 2020. Available online: https://dl.acm.org/doi/abs/10.1145/3366424.3382692
S. Graham, J.K. Min, T. Wu, "Microsoft recommenders: tools to accelerate developing recommender systems", RecSys '19: Proceedings of the 13th ACM Conference on Recommender Systems, 2019. Available online: https://dl.acm.org/doi/10.1145/3298689.3346967
L. Zhang, T. Wu, X. Xie, A. Argyriou, M. González-Fierro and J. Lian, "Building Production-Ready Recommendation System at Scale", ACM SIGKDD Conference on Knowledge Discovery and Data Mining 2019 (KDD 2019), 2019.

专家点评

适用场景

踩坑

同类对比

怎么上手

项目说明

核心能力

容易踩的坑

最近发版

New algorithms or improvements

New utilities or improvements

New notebooks or improvements

Other features

New Contributors

New algorithms or improvements

New utilities or improvements

New notebooks or improvements

Other features

New algorithms or improvements

New utilities or improvements

New notebooks or improvements

Other features

New algorithms or improvements

New utilities or improvements

New notebooks or improvements

Other features

Backwards incompatible changes

New algorithms or improvements

New utilities or improvements

New notebooks or improvements

Other features

用户点评

README 原文

What's New (April, 2025)

Introduction

Getting Started

Algorithms

Algorithm Comparison

Contributing

References

相关项目