.. image:: docs/_static/img/spotlight.png

---

.. inclusion-marker-do-not-remove

.. image:: https://travis-ci.org/maciejkula/spotlight.svg?branch=master :target: https://travis-ci.org/maciejkula/spotlight

.. image:: https://ci.appveyor.com/api/projects/status/jq5e76a7a08ra2ji/branch/master?svg=true :target: https://ci.appveyor.com/project/maciejkula/spotlight/branch/master

.. image:: https://badges.gitter.im/gitterHQ/gitter.png :target: https://gitter.im/spotlight-recommendations/Lobby

.. image:: https://anaconda.org/maciejkula/spotlight/badges/version.svg :target: https://anaconda.org/maciejkula/spotlight

.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat :target: https://maciejkula.github.io/spotlight/

.. image:: https://img.shields.io/badge/progress%20tracker-trello-brightgreen.svg :target: https://trello.com/b/G5iFgS1W/spotlight

|

Spotlight 使用 PyTorch <http://pytorch.org/>_ 来构建深度和浅层的推荐模型。它提供了丰富的损失函数构建模块（各种点对点和成对排序损失）、表示方法（浅层因子分解表示、深度序列模型）以及用于获取（或生成）推荐数据集的工具，旨在成为快速探索和原型化新推荐模型的工具。

有关详细信息，请参阅完整的 文档 <https://maciejkula.github.io/spotlight/>_。

安装

.. code-block:: python

   conda install -c maciejkula -c pytorch spotlight


使用

因子分解模型

要在 MovieLens 数据集中拟合显式反馈模型：

.. code-block:: python

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import rmse_score
from spotlight.factorization.explicit import ExplicitFactorizationModel

dataset = get_movielens_dataset(variant='100K')

train, test = random_train_test_split(dataset)

model = ExplicitFactorizationModel(n_iter=1)
model.fit(train)

rmse = rmse_score(model, test)

要在 MovieLens 数据集中拟合带有 BPR 成对损失的隐式排序模型：

.. code-block:: python

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import mrr_score
from spotlight.factorization.implicit import ImplicitFactorizationModel

dataset = get_movielens_dataset(variant='100K')

train, test = random_train_test_split(dataset)

model = ImplicitFactorizationModel(n_iter=3,
                                   loss='bpr')
model.fit(train)

mrr = mrr_score(model, test)

序列模型

推荐可以被视为一个序列预测任务：给定用户过去交互过的物品，他们接下来会与哪个物品交互呢？Spotlight 提供了一系列模型和工具来拟合下一个物品推荐模型，包括：

• 池化模型，如 YouTube 推荐 <https://pdfs.semanticscholar.org/bcdb/4da4a05f0e7bc17d1600f3a91a338cd7ffd3.pdf>_，
• LSTM 模型，如 基于会话的推荐... <https://arxiv.org/pdf/1511.06939>_，以及
• 因果卷积模型，如 WaveNet <https://arxiv.org/pdf/1609.03499>_。

.. code-block:: python

from spotlight.cross_validation import user_based_train_test_split
from spotlight.datasets.synthetic import generate_sequential
from spotlight.evaluation import sequence_mrr_score
from spotlight.sequence.implicit import ImplicitSequenceModel

dataset = generate_sequential(num_users=100,
                              num_items=1000,
                              num_interactions=10000,
                              concentration_parameter=0.01,
                              order=3)

train, test = user_based_train_test_split(dataset)

train = train.to_sequence()
test = test.to_sequence()

model = ImplicitSequenceModel(n_iter=3,
                              representation='cnn',
                              loss='bpr')
model.fit(train)

mrr = sequence_mrr_score(model, test)

数据集

Spotlight 提供了许多流行的数据集，包括 Movielens 100K、1M、10M 和 20M。它还包含用于创建合成数据集的工具。例如，generate_sequential 会生成一个基于马尔可夫链的交互数据集，其中用户选择的下一个物品是其先前交互的函数：

.. code-block:: python

from spotlight.datasets.synthetic import generate_sequential

# 浓度参数控制链的可预测性；
# 阶数决定马尔可夫链的阶数。
dataset = generate_sequential(num_users=100,
                              num_items=1000,
                              num_interactions=10000,
                              concentration_parameter=0.01,
                              order=3)

示例

1. `在 MovieLens 数据集上进行评分预测 <https://github.com/maciejkula/spotlight/tree/master/examples/movielens_explicit>`_。
2. `使用因果卷积进行序列推荐 <https://github.com/maciejkula/spotlight/tree/master/examples/movielens_sequence>`_。
3. `Bloom 嵌入层 <https://github.com/maciejkula/spotlight/tree/master/examples/bloom_embeddings>`_。


如何引用

如果您在研究中使用了 Spotlight，请予以引用。您可以使用以下 BibTeX 条目：

.. code-block::

@misc{kula2017spotlight, title={Spotlight}, author={Kula, Maciej}, year={2017}, publisher={GitHub}, howpublished={\url{https://github.com/maciejkula/spotlight}}, }

贡献

Spotlight 的设计目标是可扩展的：欢迎提交 Pull Request。开发进度在 `Trello <https://trello.com/b/G5iFgS1W/spotlight>`_ 上跟踪：查看未完成的任务，以了解哪些贡献是有价值的。

我们接受将新的推荐模型实现到 Spotlight 模型库中：如果您刚刚发表了一篇描述您新模型的论文，或者拥有文献中某个模型的实现，请提交 PR！

Spotlight 快速上手指南

Spotlight 是一个基于 PyTorch 构建的推荐系统开源库，旨在帮助用户快速探索和原型化深度及浅层推荐模型。它提供了丰富的损失函数、表示层（如矩阵分解、序列模型）以及数据集工具。

环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：推荐 Python 3.6+
• 核心依赖：
  • PyTorch (必须预先安装或随包安装)
  • conda 包管理器（推荐使用 Anaconda 或 Miniconda）

注意：由于该库主要通过 conda 分发，建议优先使用 Conda 环境进行管理。目前官方未提供专门的国内镜像源，若下载速度较慢，可尝试配置通用的 Conda 国内镜像（如清华源或中科大源）加速通道解析。

安装步骤

使用 conda 进行一键安装是最简便的方式。请在终端或命令行中执行以下命令：

conda install -c maciejkula -c pytorch spotlight

该命令会自动从 maciejkula 和 pytorch 频道获取最新版本及其依赖项。

基本使用

Spotlight 支持多种建模场景，以下展示两个最核心的用法：显式反馈评分预测 和 隐式反馈排序。

1. 显式反馈模型 (Explicit Feedback)

适用于预测用户对物品的具体评分（如 MovieLens 数据集）。以下示例演示如何加载数据、划分训练集/测试集并训练一个矩阵分解模型。

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import rmse_score
from spotlight.factorization.explicit import ExplicitFactorizationModel

# 1. 加载 MovieLens 100K 数据集
dataset = get_movielens_dataset(variant='100K')

# 2. 随机划分训练集和测试集
train, test = random_train_test_split(dataset)

# 3. 初始化并训练模型 (迭代 1 次作为演示)
model = ExplicitFactorizationModel(n_iter=1)
model.fit(train)

# 4. 评估模型 (计算 RMSE)
rmse = rmse_score(model, test)
print(f"RMSE: {rmse}")

2. 隐式反馈模型 (Implicit Feedback)

适用于只有交互行为（如点击、购买）而无具体评分的场景。以下示例使用 BPR (Bayesian Personalized Ranking) 成对损失函数进行训练。

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import mrr_score
from spotlight.factorization.implicit import ImplicitFactorizationModel

# 1. 加载数据集
dataset = get_movielens_dataset(variant='100K')

# 2. 划分数据
train, test = random_train_test_split(dataset)

# 3. 初始化隐式模型，指定使用 'bpr' 损失函数
model = ImplicitFactorizationModel(n_iter=3,
                                   loss='bpr')
model.fit(train)

# 4. 评估模型 (计算 MRR)
mrr = mrr_score(model, test)
print(f"MRR: {mrr}")

3. 序列推荐模型 (Sequential Models)

Spotlight 还支持将推荐视为序列预测任务（预测用户下一个交互物品），支持 LSTM、CNN (Causal Convolution) 等架构。

from spotlight.cross_validation import user_based_train_test_split
from spotlight.datasets.synthetic import generate_sequential
from spotlight.evaluation import sequence_mrr_score
from spotlight.sequence.implicit import ImplicitSequenceModel

# 1. 生成合成序列数据
dataset = generate_sequential(num_users=100,
                              num_items=1000,
                              num_interactions=10000,
                              concentration_parameter=0.01,
                              order=3)

# 2. 基于用户划分数据
train, test = user_based_train_test_split(dataset)

# 3. 转换为序列格式
train = train.to_sequence()
test = test.to_sequence()

# 4. 训练序列模型 (使用 CNN 表示层和 BPR 损失)
model = ImplicitSequenceModel(n_iter=3,
                              representation='cnn',
                              loss='bpr')
model.fit(train)

# 5. 评估
mrr = sequence_mrr_score(model, test)
print(f"Sequence MRR: {mrr}")

更多高级用法、自定义模型结构及完整 API 文档，请访问 Spotlight 官方文档。