概述

Surprise 是一个用于构建和分析处理显式评分数据的推荐系统的 Python scikit。

Surprise 的设计宗旨如下：

• 为用户提供对其实验的完全控制。为此，我们非常重视 文档，并力求通过指出算法的每一个细节，使其尽可能清晰、准确。
• 减轻 数据集处理 的繁琐。用户既可以使用 内置 数据集（如 Movielens、Jester），也可以使用自己的 自定义 数据集。
• 提供多种开箱即用的 预测算法，例如 基准算法、基于邻域的方法、基于矩阵分解的算法（如 SVD、PMF、SVD++、NMF）以及其他许多算法。此外，还内置了多种 相似度度量（余弦、MSD、皮尔逊等）。
• 简化 新算法思路 的实现。
• 提供工具来 评估、分析 和 比较 算法性能。借助强大的交叉验证迭代器（灵感来自 scikit-learn 的优秀工具），可以非常方便地运行交叉验证过程，还可以对参数集合进行 穷举搜索。

名称 SurPRISE（大致意为 :) ）代表 Simple Python RecommendatIon System Engine。

请注意，Surprise 不支持隐式评分或基于内容的信息。

快速入门，示例

以下是一个简单的示例，展示如何（下载）加载数据集、将其划分为 5 折交叉验证，并计算 SVD 算法的 MAE 和 RMSE。

from surprise import SVD
from surprise import Dataset
from surprise.model_selection import cross_validate

# 加载 movielens-100k 数据集（如果需要则下载）。
data = Dataset.load_builtin('ml-100k')

# 使用著名的 SVD 算法。
algo = SVD()

# 运行 5 折交叉验证并打印结果。
cross_validate(algo, data, measures=['RMSE', 'MAE'], cv=5, verbose=True)

输出：

正在评估算法 SVD 在 5 个分割上的 RMSE 和 MAE。

                  折1  折2  折3  折4  折5  平均值    标准差     
RMSE (测试集)    0.9367  0.9355  0.9378  0.9377  0.9300  0.9355  0.0029  
MAE (测试集)     0.7387  0.7371  0.7393  0.7397  0.7325  0.7375  0.0026  
拟合时间        0.62    0.63    0.63    0.65    0.63    0.63    0.01    
测试时间        0.11    0.11    0.14    0.14    0.14    0.13    0.02    

Surprise 还能做 更多 的事情（例如， GridSearchCV)！您可以在 文档 中找到 更多使用示例。

基准测试

以下是各种算法（使用默认参数）在 5 折交叉验证中的平均 RMSE、MAE 和总执行时间。数据集为 Movielens 的 100k 和 1M 数据集。所有算法使用的折划分相同。所有实验均在配备 Intel i5 第 11 代 2.60GHz 处理器的笔记本电脑上运行。生成这些表格的代码可在 基准测试示例 中找到。

Movielens 100k	RMSE	MAE	时间
SVD	0.934	0.737	0:00:06
SVD++ (cache_ratings=False)	0.919	0.721	0:01:39
SVD++ (cache_ratings=True)	0.919	0.721	0:01:22
NMF	0.963	0.758	0:00:06
Slope One	0.946	0.743	0:00:09
k-NN	0.98	0.774	0:00:08
Centered k-NN	0.951	0.749	0:00:09
k-NN Baseline	0.931	0.733	0:00:13
Co-Clustering	0.963	0.753	0:00:06
Baseline	0.944	0.748	0:00:02
Random	1.518	1.219	0:00:01

Movielens 1M	RMSE	MAE	时间
SVD	0.873	0.686	0:01:07
SVD++ (cache_ratings=False)	0.862	0.672	0:41:06
SVD++ (cache_ratings=True)	0.862	0.672	0:34:55
NMF	0.916	0.723	0:01:39
Slope One	0.907	0.715	0:02:31
k-NN	0.923	0.727	0:05:27
Centered k-NN	0.929	0.738	0:05:43
k-NN Baseline	0.895	0.706	0:05:55
Co-Clustering	0.915	0.717	0:00:31
Baseline	0.909	0.719	0:00:19
Random	1.504	1.206	0:00:19

安装

使用 pip（需要 C 编译器。Windows 用户可能更倾向于使用 conda）：

$ pip install scikit-surprise

使用 conda：

$ conda install -c conda-forge scikit-surprise

对于最新版本，您也可以克隆仓库并构建源代码 （您首先需要 Cython 和 numpy)：

$ git clone https://github.com/NicolasHug/surprise.git
$ cd surprise
$ pip install .

许可证与引用

本项目采用 BSD 3-Clause 许可证，因此几乎可以用于任何用途，包括商业应用。

我很想知道 Surprise 对您的帮助有多大。请随时提交 issue 并描述您是如何使用它的！

如果您在研究中使用 Surprise，请务必引用以下论文：

@article{Hug2020,
  doi = {10.21105/joss.02174},
  url = {https://doi.org/10.21105/joss.02174},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {52},
  pages = {2174},
  author = {Nicolas Hug},
  title = {Surprise: A Python library for recommender systems},
  journal = {Journal of Open Source Software}
}

贡献者

以下人员为 Surprise 做出了贡献：

ashtou, Abhishek Bhatia, bobbyinfj, caoyi, Chieh-Han Chen, Raphael-Dayan, Олег Демиденко, Charles-Emmanuel Dias, dmamylin, Lauriane Ducasse, Marc Feger, franckjay, Lukas Galke, Tim Gates, Pierre-François Gimenez, Zachary Glassman, Jeff Hale, Nicolas Hug, Janniks, jyesawtellrickson, Doruk Kilitcioglu, Ravi Raju Krishna, lapidshay, Hengji Liu, Ravi Makhija, Maher Malaeb, Manoj K, James McNeilis, Naturale0, nju-luke, Pierre-Louis Pécheux, Jay Qi, Lucas Rebscher, Craig Rodrigues, Skywhat, Hercules Smith, David Stevens, Vesna Tanko, TrWestdoor, Victor Wang, Mike Lee Williams, Jay Wong, Chenchen Xu, YaoZh1918.

非常感谢！ :)

开发状态

自 1.1.0 版本（2019 年 9 月）起，我将仅维护该包，提供错误修复，或许偶尔会进行性能优化。现在我投入的时间较少，因此无法考虑新增功能。

如遇 Surprise 的 bug、问题或疑问，请勿发送邮件给我（我很可能无法回复）。请改用 GitHub 上的项目页面，以便其他人也能从中受益。

Surprise 快速上手指南

Surprise (Simple Python RecommendatIon System Engine) 是一个用于构建和分析推荐系统的 Python 库，专门处理显式评分数据（如电影评分、商品打分）。它内置了多种经典算法（如 SVD、NMF、KNN），并提供完善的交叉验证和参数调优工具。

注意：Surprise 不支持隐式反馈（如点击流）或基于内容的推荐。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.8 及以上
• 前置依赖：
  • 安装时需要 C 编译器（Windows 用户建议直接使用 Conda 以避免配置编译环境的麻烦）。
  • 核心依赖包括 numpy, scipy, Cython 等，包管理器会自动处理。

安装步骤

推荐使用 pip 或 conda 进行安装。国内用户若遇到下载速度慢的问题，可指定清华或阿里镜像源。

方式一：使用 pip 安装（推荐）

# 使用默认源
pip install scikit-surprise

# 或使用国内镜像加速（推荐）
pip install scikit-surprise -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Conda 安装（Windows 用户首选）

conda install -c conda-forge scikit-surprise

方式三：从源码安装（获取最新版）

如需体验最新功能，可克隆仓库并编译（需先安装 Cython 和 numpy）：

git clone https://github.com/NicolasHug/surprise.git
cd surprise
pip install .

基本使用

以下示例演示了如何加载内置的 MovieLens-100k 数据集，使用经典的 SVD 算法，并进行 5 折交叉验证以评估模型性能（RMSE 和 MAE）。

from surprise import SVD
from surprise import Dataset
from surprise.model_selection import cross_validate

# 1. 加载内置数据集 (ml-100k)，如果本地不存在会自动下载
data = Dataset.load_builtin('ml-100k')

# 2. 初始化 SVD 算法
algo = SVD()

# 3. 运行 5 折交叉验证并输出结果
# measures: 评估指标 (RMSE, MAE)
# cv: 交叉验证折数
# verbose: 是否打印详细过程
cross_validate(algo, data, measures=['RMSE', 'MAE'], cv=5, verbose=True)

预期输出示例：

Evaluating RMSE, MAE of algorithm SVD on 5 split(s).

                  Fold 1  Fold 2  Fold 3  Fold 4  Fold 5  Mean    Std     
RMSE (testset)    0.9367  0.9355  0.9378  0.9377  0.9300  0.9355  0.0029  
MAE (testset)     0.7387  0.7371  0.7393  0.7397  0.7325  0.7375  0.0026  
Fit time          0.62    0.63    0.63    0.65    0.63    0.63    0.01    
Test time         0.11    0.11    0.14    0.14    0.14    0.13    0.02    

除了内置数据集，Surprise 也支持加载自定义数据集、使用 GridSearchCV 进行超参数网格搜索以及对比不同算法的性能。更多高级用法请参考官方文档。