Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,9 @@ jobs:
- name: Install ANN Libraries
run: pip install annoy nmslib
if: ${{ matrix.python-version != '3.14' && runner.os == 'Linux' }}
- name: Install mlxvs (Apple silicon GPU)
run: pip install mlxvs
if: ${{ matrix.python-version != '3.9' && runner.os == 'macOS' }}
- name: Install wheel
run: |
pip install --force-reinstall --no-deps --no-index --find-links . implicit
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Feedback Collaborative Filtering](https://pdfs.semanticscholar.org/bfdf/7af6cf7f
All models have multi-threaded training routines, using Cython and OpenMP to fit the models in
parallel among all available CPU cores. In addition, the ALS and BPR models both have custom CUDA
kernels - enabling fitting on compatible GPU's. Approximate nearest neighbours libraries such as [Annoy](https://github.com/spotify/annoy), [NMSLIB](https://github.com/searchivarius/nmslib)
and [Faiss](https://github.com/facebookresearch/faiss) can also be used by Implicit to [speed up
, [Faiss](https://github.com/facebookresearch/faiss) and [mlxvs](https://github.com/mikepapadim/mlxvs) (on the GPU of Apple silicon Macs) can also be used by Implicit to [speed up
making recommendations](https://www.benfrederickson.com/approximate-nearest-neighbours-for-recommender-systems/).

#### Installation
Expand Down
6 changes: 6 additions & 0 deletions docs/source/api/ann.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,9 @@ FaissModel
.. autoclass:: implicit.ann.faiss.FaissModel
:members:
:show-inheritance:

MLXVSModel
----------
.. autoclass:: implicit.ann.mlxvs.MLXVSModel
:members:
:show-inheritance:
2 changes: 1 addition & 1 deletion docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ implicit feedback datasets:
All models have multi-threaded training routines, using Cython and OpenMP to fit the models in
parallel among all available CPU cores. In addition, the ALS and BPR models both have custom CUDA
kernels - enabling fitting on compatible GPU's. This library also supports using approximate nearest neighbours libraries such as `Annoy <https://github.com/spotify/annoy>`_, `NMSLIB <https://github.com/searchivarius/nmslib>`_
and `Faiss <https://github.com/facebookresearch/faiss>`_ for `speeding up making recommendations <http://www.benfrederickson.com/approximate-nearest-neighbours-for-recommender-systems/>`_.
`Faiss <https://github.com/facebookresearch/faiss>`_ and `mlxvs <https://github.com/mikepapadim/mlxvs>`_ (on the GPU of Apple silicon Macs) for `speeding up making recommendations <http://www.benfrederickson.com/approximate-nearest-neighbours-for-recommender-systems/>`_.


Basic Usage
Expand Down
267 changes: 267 additions & 0 deletions implicit/ann/mlxvs.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,267 @@
import logging
import warnings

import mlxvs
import numpy as np
from scipy.sparse import csr_matrix

import implicit.gpu
from implicit.recommender_base import RecommenderBase
from implicit.utils import _batch_call, _filter_items_from_results, augment_inner_product_matrix

log = logging.getLogger("implicit")


class _Index:
"""An inner product index of a set of factors: a CAGRA graph searched on the GPU,
or exact search on the GPU for small sets and large result counts"""

def __init__(self, factors, graph_degree, intermediate_graph_degree, itopk_size):
self.factors = np.ascontiguousarray(factors, dtype=np.float32)
self.itopk_size = itopk_size
self.graph = None
if len(self.factors) > intermediate_graph_degree:
self.graph = mlxvs.CagraIndex.build(
self.factors,
graph_degree,
"inner_product",
intermediate_graph_degree=intermediate_graph_degree,
)

def search(self, queries, count):
"""returns (scores, ids) of the count rows of largest inner product with each query"""
count = min(count, len(self.factors))
if self.graph is not None and count <= 1024:
ids, scores = self.graph.search(queries, count, itopk_size=max(self.itopk_size, count))
elif count <= 256:
ids, scores = mlxvs.brute_force_knn(self.factors, queries, count, "inner_product")
else:
# beyond the GPU top-k: exact search with numpy
all_scores = queries @ self.factors.T
ids = np.argsort(-all_scores, axis=1)[:, :count]
scores = np.take_along_axis(all_scores, ids, axis=1)
return np.asarray(scores), np.asarray(ids)


class MLXVSModel(RecommenderBase):
"""
Speeds up inference calls to MatrixFactorization models on the GPU of Apple silicon Macs, by
using `mlxvs <https://github.com/mikepapadim/mlxvs>`_ to build CAGRA graph indices of the
latent factors (the graph search of NVIDIA's cuVS, on Apple's MLX). Needs macOS 14 or later on
Apple silicon.

Parameters
----------
model : MatrixFactorizationBase
A matrix factorization model to use for the factors
approximate_similar_items : bool, optional
whether or not to build an index for computing similar_items
approximate_recommend : bool, optional
whether or not to build an index for the recommend call
graph_degree : int, optional
The number of neighbours of each item in the search graph.
intermediate_graph_degree : int, optional
The number of neighbours in the k-NN graph pruned into the search graph. Item sets of at
most this many items are searched exactly.
itopk_size : int, optional
The length of each query's search list: higher is more accurate and slower.

Attributes
----------
similar_items_index :
Index for looking up similar items in the cosine space formed by the latent item_factors

recommend_index :
Index for looking up similar items in the inner product space formed by the latent
item_factors
"""

def __init__(
self,
model,
approximate_similar_items=True,
approximate_recommend=True,
graph_degree=32,
intermediate_graph_degree=64,
itopk_size=64,
):
self.model = model
self.similar_items_index = None
self.recommend_index = None

self.approximate_similar_items = approximate_similar_items
self.approximate_recommend = approximate_recommend

# hyper-parameters for mlxvs
self.graph_degree = graph_degree
self.intermediate_graph_degree = intermediate_graph_degree
self.itopk_size = itopk_size
super().__init__()

def _index(self, factors):
return _Index(factors, self.graph_degree, self.intermediate_graph_degree, self.itopk_size)

def fit(self, Cui, show_progress=True, callback=None):
self.model.fit(Cui, show_progress, callback=callback)

item_factors = self.model.item_factors
if implicit.gpu.HAS_CUDA and isinstance(item_factors, implicit.gpu.Matrix):
item_factors = item_factors.to_numpy()
item_factors = item_factors.astype("float32")

if self.approximate_recommend:
log.debug("Building mlxvs recommendation index")

# graph search finds the largest inner products poorly when the norms of the items
# vary: add a dimension so that every item has the same norm (queries get a 0 there),
# as the annoy and nmslib models do
_, augmented = augment_inner_product_matrix(item_factors)
self.recommend_index = self._index(augmented)

if self.approximate_similar_items:
log.debug("Building mlxvs similar items index")

# cosine similarity: an inner product index on normalized vectors
norms = np.linalg.norm(item_factors, axis=1)
norms[norms == 0] = 1e-10
self.similar_items_index = self._index((item_factors.T / norms).T)

def similar_items(
self, itemid, N=10, recalculate_item=False, item_users=None, filter_items=None, items=None
):
if items is not None and self.approximate_similar_items:
raise NotImplementedError("using an items filter isn't supported with ANN lookup")

count = N
if filter_items is not None:
count += len(filter_items)

if not self.approximate_similar_items:
return self.model.similar_items(
itemid,
N,
recalculate_item=recalculate_item,
item_users=item_users,
filter_items=filter_items,
items=items,
)

# support recalculate_item if possible
if hasattr(self.model, "_item_factor"):
factors = self.model._item_factor(itemid, item_users, recalculate_item) # pylint: disable=protected-access
elif recalculate_item:
raise NotImplementedError(f"recalculate_item isn't supported with {self.model}")
else:
factors = self.model.item_factors[itemid]
if implicit.gpu.HAS_CUDA and isinstance(factors, implicit.gpu.Matrix):
factors = factors.to_numpy()

factors = np.array(factors, dtype="float32")
if np.isscalar(itemid):
factors = factors.reshape(1, -1)
factors /= np.maximum(np.linalg.norm(factors, axis=1), 1e-10)[:, None]

scores, ids = self.similar_items_index.search(factors, count)

if np.isscalar(itemid):
ids, scores = ids[0], scores[0]

if filter_items is not None:
ids, scores = _filter_items_from_results(itemid, ids, scores, filter_items, N)

return ids, scores

def recommend(
self,
userid,
user_items,
N=10,
filter_already_liked_items=True,
filter_items=None,
recalculate_user=False,
items=None,
):
if (filter_already_liked_items or recalculate_user) and not isinstance(
user_items, csr_matrix
):
raise ValueError("user_items needs to be a CSR sparse matrix")

if items is not None and self.approximate_recommend:
raise NotImplementedError("using a 'items' list with ANN search isn't supported")

# filter_already_liked_items needs a different number of results per user: query one
# user at a time
if filter_already_liked_items and not np.isscalar(userid):
return _batch_call(
self.recommend,
userid,
user_items=user_items,
N=N,
filter_already_liked_items=filter_already_liked_items,
filter_items=filter_items,
recalculate_user=recalculate_user,
items=items,
)

if not self.approximate_recommend:
warnings.warn("Calling recommend on a MLXVSModel with approximate_recommend=False")
return self.model.recommend(
userid,
user_items,
N=N,
filter_already_liked_items=filter_already_liked_items,
filter_items=filter_items,
recalculate_user=recalculate_user,
items=items,
)

if hasattr(self.model, "_user_factor"):
user = self.model._user_factor(userid, user_items, recalculate_user) # pylint: disable=protected-access
elif recalculate_user:
raise NotImplementedError(f"recalculate_user isn't supported with {self.model}")
else:
user = self.model.user_factors[userid]
if implicit.gpu.HAS_CUDA and isinstance(user, implicit.gpu.Matrix):
user = user.to_numpy()

# calculate the top N items, removing the users own liked items from the results
count = N
if filter_items:
count += len(filter_items)
filter_items = np.array(filter_items)

if filter_already_liked_items:
user_likes = user_items[0].indices
filter_items = (
np.append(filter_items, user_likes) if filter_items is not None else user_likes
)
count += len(user_likes)

query = np.array(user, dtype="float32")
if np.isscalar(userid):
query = query.reshape(1, -1)
# the extra dimension of the augmented item factors
query = np.append(query, np.zeros((len(query), 1), dtype="float32"), axis=1)

scores, ids = self.recommend_index.search(query, count)

if np.isscalar(userid):
ids, scores = ids[0], scores[0]

if filter_items is not None:
ids, scores = _filter_items_from_results(userid, ids, scores, filter_items, N)

return ids, scores

def similar_users(self, userid, N=10, filter_users=None, users=None):
raise NotImplementedError(
"similar_users isn't implemented with mlxvs yet. (note: you can call "
" self.model.similar_models to get the same functionality on the inner model class)"
)

def save(self, file):
raise NotImplementedError(".save isn't implemented for mlxvs yet")

@classmethod
def load(cls, file):
raise NotImplementedError(".load isn't implemented for mlxvs yet")
24 changes: 24 additions & 0 deletions implicit/approximate_als.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,27 @@ def FaissAlternatingLeastSquares(
nprobe=nprobe,
use_gpu=use_gpu,
)


def MLXVSAlternatingLeastSquares(
*args,
approximate_similar_items=True,
approximate_recommend=True,
graph_degree=32,
intermediate_graph_degree=64,
itopk_size=64,
**kwargs,
):
# mlxvs searches on the GPU of Apple silicon Macs; the ALS model itself is fit on the CPU
als_model = implicit.als.AlternatingLeastSquares(*args, use_gpu=False, **kwargs)

from implicit.ann.mlxvs import MLXVSModel

return MLXVSModel(
als_model,
approximate_similar_items=approximate_similar_items,
approximate_recommend=approximate_recommend,
graph_degree=graph_degree,
intermediate_graph_degree=intermediate_graph_degree,
itopk_size=itopk_size,
)
45 changes: 45 additions & 0 deletions tests/approximate_als_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from implicit.approximate_als import (
AnnoyAlternatingLeastSquares,
FaissAlternatingLeastSquares,
MLXVSAlternatingLeastSquares,
NMSLibAlternatingLeastSquares,
)
from implicit.gpu import HAS_CUDA
Expand Down Expand Up @@ -159,6 +160,50 @@ def test_serialization_without_fit(self):
except ImportError:
pass

# mlxvs only installs on macOS with Apple silicon
try:
import mlxvs # noqa pylint: disable=unused-import

class MLXVSALSTest(unittest.TestCase, RecommenderBaseTestMixin):
def _get_model(self):
return MLXVSAlternatingLeastSquares(factors=32, regularization=0, random_state=23)

def test_large_recommend(self):
# more results than the graph search returns: falls back to exact search
plays = get_checker_board(2048)
model = self._get_model()
model.fit(plays, show_progress=False)

recs = model.similar_items(0, N=1050)
self.assertEqual(recs[0][0], 0)

recs = model.recommend(0, plays.T.tocsr()[0], N=1050)
self.assertEqual(recs[0][0], 0)

def test_graph_index(self):
# enough items to build the search graph: results match the exact model
plays = get_checker_board(512)
model = self._get_model()
model.fit(plays, show_progress=False)
self.assertIsNotNone(model.recommend_index.graph)

ids, _ = model.similar_items(0, N=10)
exact, _ = model.model.similar_items(0, N=10)
self.assertGreaterEqual(len(set(ids) & set(exact)), 9)

def test_pickle(self):
# pickle isn't supported on mlxvs indices
pass

def test_serialization(self):
pass

def test_serialization_without_fit(self):
pass

except ImportError:
pass


if __name__ == "__main__":
unittest.main()