最新动态（2025年4月）

我们达到了20,000颗星！！

我们很高兴地宣布，我们在 GitHub 上的项目已获得20,000颗星！感谢您对 Recommenders 项目的大力支持与贡献。我们非常期待在您的帮助下继续构建和完善这个项目。

请查看版本 Recommenders 1.2.1！

我们修复了大量由依赖项引起的 bug，提升了安全性，并对笔记本和库进行了全面审查。

简介

Recommenders 的目标是帮助研究人员、开发者和爱好者快速原型设计、实验并部署一系列经典及最先进推荐系统到生产环境中。

Recommenders 是 Linux 基金会人工智能与数据基金会 下的一个项目。

本仓库包含用于构建推荐系统的示例和最佳实践，以 Jupyter 笔记本的形式提供。这些示例详细记录了我们在五个关键任务上的学习成果：

• 数据准备：为每种推荐算法准备和加载数据。
• 模型构建：使用多种经典及深度学习推荐算法构建模型，例如交替最小二乘法 (ALS) 或极端深度因子分解机 (xDeepFM)。
• 评估：使用离线指标评估算法性能。
• 模型选择与优化：调整和优化推荐模型的超参数。
• 上线部署：在 Azure 生产环境中部署模型。

在 recommenders 中提供了若干实用工具，用于支持常见任务，如以不同算法所需格式加载数据集、评估模型输出以及拆分训练/测试数据。此外，还包含了多个最先进算法的实现，供您自学并在自己的应用中进行定制。更多信息请参阅 Recommenders 文档。

如需更详细的仓库概述，请参阅 wiki 页面上的相关文档。

有关推荐系统实际应用场景的更多信息，请参阅 scenarios。

快速入门

我们推荐使用 uv 进行环境管理（比 conda/pip 快10–100倍），并使用 VS Code 进行开发。要在 Linux/WSL 上安装 Recommenders 包并运行示例笔记本：

# 1. 如果尚未安装 gcc，请先安装。在 Ubuntu 上，可以使用以下命令：
# sudo apt install gcc

# 2. 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 创建并激活一个新的虚拟环境
uv venv ~/.venvs/recommenders --python 3.11
source ~/.venvs/recommenders/bin/activate

# 4. 安装核心 Recommenders 包。该包可运行所有 CPU 笔记本。
uv pip install recommenders

# 5. 创建一个 Jupyter 内核
uv pip install ipykernel
python -m ipykernel install --user --name recommenders --display-name "Python (recommenders)"

# 6. 在 VS Code 或通过命令行克隆此仓库：
git clone https://github.com/recommenders-team/recommenders.git

# 7. 在 VS Code 中：
#   a. 打开一个笔记本，例如 examples/00_quick_start/sar_movielens.ipynb；
#   b. 选择 Jupyter 内核 "Python (recommenders)"；
#   c. 运行笔记本。

有关其他平台（如 Windows 和 macOS）以及不同配置（如 GPU、Spark 和实验性功能）的更多设置信息，请参阅 设置指南。

除了核心包之外，还提供了若干附加组件，包括：

• [gpu]：用于运行 GPU 模型。
• [spark]：用于运行 Spark 模型。
• [dev]：用于仓库的开发。
• [all]：[gpu]|[spark]|[dev]
• [experimental]：指尚未经过充分测试，或可能需要额外安装步骤的模型。

算法

下表列出了当前仓库中可用的推荐算法。示例栏中链接的笔记本分为“快速入门”，展示易于运行的算法示例；或“深入剖析”，详细解释算法的数学原理及实现过程。

算法	类型	描述	示例
交替最小二乘法 (ALS)	协同过滤	针对大规模数据集中显式或隐式反馈的矩阵分解算法，优化了可扩展性和分布式计算能力。适用于 PySpark 环境。	快速入门 / 深入解析
注意力异步奇异值分解 (A2SVD)*	协同过滤	基于序列的算法，利用注意力机制捕捉用户的长期和短期偏好。适用于 CPU/GPU 环境。	快速入门
Cornac/贝叶斯个性化排序 (BPR)	协同过滤	针对隐式反馈进行物品排名预测的矩阵分解算法。适用于 CPU 环境。	深入解析
Cornac/双边变分自编码器 (BiVAE)	协同过滤	用于二元数据（如用户-物品交互）的生成模型。适用于 CPU/GPU 环境。	深入解析
卷积序列嵌入推荐 (Caser)	协同过滤	基于卷积的算法，旨在同时捕捉用户的总体偏好和序列模式。适用于 CPU/GPU 环境。	快速入门
深度知识感知网络 (DKN)*	基于内容的过滤	结合知识图谱和文章嵌入的深度学习算法，用于新闻或文章推荐。适用于 CPU/GPU 环境。	快速入门 / 深入解析
极端深度因子分解机 (xDeepFM)*	协同过滤	基于深度学习的算法，适用于包含用户/物品特征的隐式和显式反馈。适用于 CPU/GPU 环境。	快速入门
嵌入点积偏差	协同过滤	一种通用算法，使用用户和物品的嵌入及偏差。适用于 CPU/GPU 环境。	快速入门
LightFM/因子分解机	协同过滤	适用于隐式和显式反馈的因子分解机算法。适用于 CPU 环境。	快速入门
LightGBM/梯度提升树*	基于内容的过滤	针对基于内容的问题，具有快速训练和低内存占用特点的梯度提升树算法。适用于 CPU/GPU/PySpark 环境。	CPU 快速入门 / PySpark 深入解析
LightGCN	协同过滤	一种简化了 GCN 设计的深度学习算法，用于预测隐式反馈。适用于 CPU/GPU 环境。	深入解析
GeoIMC*	协同过滤	一种考虑用户和物品特征的矩阵补全算法，采用黎曼共轭梯度优化，并遵循几何方法。适用于 CPU 环境。	快速入门
GRU	协同过滤	基于序列的算法，利用循环神经网络捕捉用户的长期和短期偏好。适用于 CPU/GPU 环境。	快速入门
多项式变分自编码器	协同过滤	用于预测用户/物品交互的生成模型。适用于 CPU/GPU 环境。	深入解析
具有长短期用户表征的神经推荐 (LSTUR)*	基于内容的过滤	用于推荐新闻文章的神经推荐算法，能够建模用户的长短期兴趣。适用于 CPU/GPU 环境。	快速入门
具有注意力多视角学习的神经推荐 (NAML)*	基于内容的过滤	用于推荐新闻文章的神经推荐算法，采用注意力多视角学习。适用于 CPU/GPU 环境。	快速入门
神经协同过滤 (NCF)	协同过滤	针对用户/物品隐式反馈的性能增强型深度学习算法。适用于 CPU/GPU 环境。	快速入门 / 深入解析
具有个性化注意力的神经推荐 (NPA)*	基于内容的过滤	用于推荐新闻文章的神经推荐算法，采用个性化注意力网络。适用于 CPU/GPU 环境。	快速入门
具有多头自注意力的神经推荐 (NRMS)*	基于内容的过滤	用于推荐新闻文章的神经推荐算法，采用多头自注意力机制。适用于 CPU/GPU 环境。	快速入门
下一个物品推荐 (NextItNet)	协同过滤	基于扩张卷积和残差网络的算法，旨在捕捉序列模式。同时考虑用户/物品的交互与特征。适用于 CPU/GPU 环境。	快速入门
受限玻尔兹曼机 (RBM)	协同过滤	基于神经网络的算法，用于学习显式或隐式用户/物品反馈背后的概率分布。适用于 CPU/GPU 环境。	快速入门 / 深入解析
黎曼低秩矩阵补全 (RLRMC)*	协同过滤	使用黎曼共轭梯度优化、内存消耗小的矩阵分解算法，用于预测用户/物品的交互。适用于 CPU 环境。	快速入门
推荐简单算法 (SAR)*	协同过滤	基于相似性的隐式用户/物品反馈算法。适用于 CPU 环境。	快速入门 / 深入解析
自注意力序列推荐 (SASRec)	协同过滤	基于 Transformer 的序列推荐算法。适用于 CPU/GPU 环境。	快速入门
短期与长期偏好融合推荐 (SLi-Rec)*	协同过滤	基于序列的算法，利用注意力机制、时间感知控制器和内容感知控制器，同时捕捉用户的长期和短期偏好。适用于 CPU/GPU 环境。	快速入门
多兴趣感知的序列用户建模 (SUM)*	协同过滤	一种增强的记忆网络基序列用户模型，旨在捕捉用户的多种兴趣。适用于 CPU/GPU 环境。	快速入门
基于个性化 Transformer 的序列推荐 (SSEPT)	协同过滤	基于 Transformer 的序列推荐算法，结合用户嵌入。适用于 CPU/GPU 环境。	快速入门
标准变分自编码器	协同过滤	用于预测用户/物品交互的生成模型。适用于 CPU/GPU 环境。	深入解析
Surprise/奇异值分解 (SVD)	协同过滤	用于在小规模数据集中预测显式评分反馈的矩阵分解算法。适用于 CPU/GPU 环境。	深入解析
词频-逆文档频率 (TF-IDF)	基于内容的过滤	适用于文本数据集的基于相似性的简单内容推荐算法。适用于 CPU 环境。	快速入门
Vowpal Wabbit (VW)*	基于内容的过滤	快速的在线学习算法，非常适合用户特征/上下文不断变化的场景。使用 CPU 进行在线学习。	深入解析
宽而深	协同过滤	一种能够记忆特征交互并泛化用户特征的深度学习算法。适用于 CPU/GPU 环境。	快速入门
xLearn/因子分解机 (FM) 和场感知 FM (FFM)	协同过滤	一种快速且内存高效的算法，用于根据用户/物品特征预测标签。适用于 CPU/GPU 环境。	深入解析

注意: ^* 表示由微软发明/贡献的算法。

独立或孵化中的算法和工具是放入 contrib 文件夹的候选对象。该文件夹将存放那些可能不易融入核心仓库，或者需要时间重构代码、完善功能并添加必要测试的贡献内容。

算法	类型	描述	示例
SARplus *	协同过滤	针对 Spark 的优化版 SAR 实现	快速入门

算法比较

我们提供了一个 基准测试笔记本，用于展示如何评估和比较不同的算法。在这个笔记本中，MovieLens 数据集按照 75/25 的比例进行分层拆分，得到训练集和测试集。我们使用下面列出的每一种协同过滤算法来训练推荐模型。参数值采用文献这里中报告的经验值。对于排序指标，我们使用 k=10（前 10 个推荐项）。比较实验在一台配备 4 核 CPU、30GB 内存和 1 块 GeForce GTX 1660 Ti 显卡（6GB 显存）的机器上运行。Spark ALS 以本地独立模式执行。下表展示了在 MovieLens 100k 数据集上运行 15 个 epoch 后的结果。

算法	MAP	nDCG@k	Precision@k	Recall@k	RMSE	MAE	R2	解释方差
ALS	0.004732	0.044239	0.048462	0.017796	0.965038	0.753001	0.255647	0.251648
BiVAE	0.146126	0.475077	0.411771	0.219145	N/A	N/A	N/A	N/A
BPR	0.132478	0.441997	0.388229	0.212522	N/A	N/A	N/A	N/A
embdotbias	0.018954	0.117810	0.104242	0.042450	0.992760	0.776040	0.223344	0.223393
LightGCN	0.088526	0.419846	0.379626	0.144336	N/A	N/A	N/A	N/A
NCF	0.107720	0.396118	0.347296	0.180775	N/A	N/A	N/A	N/A
SAR	0.110591	0.382461	0.330753	0.176385	1.253805	1.048484	-0.569363	0.030474
SVD	0.012873	0.095930	0.091198	0.032783	0.938681	0.742690	0.291967	0.291971

贡献说明

本项目欢迎各位的贡献与建议。在提交贡献之前，请先阅读我们的 贡献指南。

为营造一个包容且富有激励性的社区，本项目遵循此 行为准则。

参考文献

• 免费课程: M. González-Fierro, “推荐系统：实用入门”, LinkedIn Learning, 2024。可通过此链接观看。
• D. Li, J. Lian, L. Zhang, K. Ren, D. Lu, T. Wu, X. Xie, “推荐系统：前沿与实践”, Springer, 北京, 2024。可通过此链接购买。
• A. Argyriou, M. González-Fierro 和 L. Zhang, “Microsoft Recommenders：生产就绪推荐系统的最佳实践”, WWW 2020：国际万维网大会，台北, 2020。在线获取：https://dl.acm.org/doi/abs/10.1145/3366424.3382692
• S. Graham, J.K. Min, T. Wu, “Microsoft recommenders：加速推荐系统开发的工具”, RecSys '19：第 13 届 ACM 推荐系统会议论文集, 2019。在线获取：https://dl.acm.org/doi/10.1145/3298689.3346967
• L. Zhang, T. Wu, X. Xie, A. Argyriou, M. González-Fierro 和 J. Lian, “大规模生产就绪推荐系统的构建”, ACM SIGKDD 知识发现与数据挖掘大会 2019 (KDD 2019), 2019。

Recommenders 快速上手指南

Recommenders 是一个由 Linux Foundation AI & Data 托管的开源项目，旨在帮助研究人员和开发者构建、评估及部署经典与前沿的推荐系统。本项目提供了丰富的 Jupyter Notebook 示例，涵盖数据准备、模型构建、评估、调优及生产环境部署全流程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐), WSL (Windows Subsystem for Linux), 或 macOS。
  • 注：Windows 原生支持有限，建议通过 WSL 运行。
• Python 版本: 推荐 Python 3.11。
• 编译器: 需要安装 gcc (Ubuntu/Debian 系统通常预装，若未安装需执行 sudo apt install gcc)。
• 开发工具: 推荐使用 VS Code 进行开发。
• 包管理工具: 官方强烈推荐使用 uv，其速度比 conda/pip 快 10-100 倍。

安装步骤

以下是在 Linux/WSL 环境下使用 uv 安装核心包并运行示例的标准流程：

1. 安装 uv (如果尚未安装):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 创建并激活虚拟环境 (指定 Python 3.11):

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

3. 安装 Recommenders 核心包:

   uv pip install recommenders
   

   可选扩展: 如需使用 GPU 加速或 Spark，可安装额外依赖：

   • GPU 支持: uv pip install "recommenders[gpu]"
   • Spark 支持: uv pip install "recommenders[spark]"
   • 全部功能: uv pip install "recommenders[all]"

4. 配置 Jupyter Kernel:

   uv pip install ipykernel
   python -m ipykernel install --user --name recommenders --display-name "Python (recommenders)"
   

5. 克隆项目代码库:

   git clone https://github.com/recommenders-team/recommenders.git
   cd recommenders
   

基本使用

安装完成后，您可以通过运行官方提供的 Jupyter Notebook 快速体验推荐算法。以下以经典的 SAR (Simple Algorithm for Recommendation) 在 MovieLens 数据集上的应用为例：

1. 启动 VS Code 并打开克隆后的目录。
2. 打开示例 Notebook: 导航至 examples/00_quick_start/sar_movielens.ipynb 并打开。
3. 选择内核: 在 Notebook 右上角点击内核选择器，选择刚才创建的 Python (recommenders)。
4. 运行单元格: 依次运行代码单元格。该示例将演示：
   • 加载 MovieLens 数据集。
   • 训练 SAR 模型。
   • 生成顶部 K 个物品推荐列表。
   • 评估模型效果。

核心代码逻辑示例 (源自 Notebook):

from recommenders.models.sar import SAR
from recommenders.datasets import movielens

# 1. 加载数据
df = movielens.load_pandas_df(size="100k")

# 2. 初始化模型
model = SAR(
    user_col="userID",
    item_col="itemID",
    rating_col="rating",
    time_col="timestamp",
)

# 3. 拟合模型
model.fit(df)

# 4. 获取推荐结果
top_k = model.recommend_k_items(
    user_ids=[1], 
    top_k=10, 
    remove_seen=True
)
print(top_k)

更多算法（如 ALS, xDeepFM, LightGCN 等）的详细用法请参考 examples 目录下的其他 Notebook，分为 "Quick start" (快速入门) 和 "Deep dive" (深度解析) 两类。