lenskit.flexmf#

Flexible PyTorch matrix factorization models for LensKit.

The components in this package implement several matrix factorization models for LensKit, and also serve as an example for practical PyTorch recommender training.

Stability: Internal

This API is at the internal or experimental stability level: it may change at any time, and breaking changes will not necessarily be described in the release notes. See Stability Levels for details. FlexMF is provided as a preview release, and may change in the next months as we gain more experience with it.

as we gain more experience with it.

class lenskit.flexmf.FlexMFConfigBase(embedding_size=50, batch_size=8192, learning_rate=0.01, epochs=10, regularization=0.1, reg_method='L2')#

Bases: object

Common configuration for all FlexMF scoring components.

Stability:

Experimental

Parameters:

  • embedding_size (int)

  • batch_size (int)

  • learning_rate (float)

  • epochs (int)

  • regularization (float)

  • reg_method (Literal['AdamW', 'L2'] | None)

batch_size: int = 8192#

The training batch size.

embedding_size: int = 50#

The dimension of the embedding space (number of latent features).

epochs: int = 10#

The number of training epochs.

learning_rate: float = 0.01#

The learning rate for training.

reg_method: Literal['AdamW', 'L2'] | None = 'L2'#

The regularization method to use.

With the default L2 regularization, training will use sparse gradients and the torch.optim.SparseAdam optimizer.

None

Use no regularization.

"L2"

Use L2 regularization on the parameters used in each training batch. The strength is applied to the _mean_ norms in a batch, so that the regularization term scale is not dependent on the batch size.

"AdamW"

Use torch.optim.AdamW with the specified regularization strength. This configuration does not use sparse gradients and may train more slowly.

Note

Regularization values do not necessarily have the same range or meaning for the different regularization methods.

regularization: float = 0.1#

The regularization strength.

class lenskit.flexmf.FlexMFScorerBase(config=None, **kwargs)#

Bases: UsesTrainer, Component

Base class for the FlexMF scorers, providing common Torch support.

Stability:

Experimental

Parameters:
score_items(users, items)#

Score for users and items, after resolivng them and limiting to known users and items.

Parameters:
Return type:

Tensor

to(device)#

Move the model to a different device.

class lenskit.flexmf.FlexMFExplicitConfig(embedding_size=50, batch_size=8192, learning_rate=0.01, epochs=10, regularization=0.1, reg_method='L2')#

Bases: FlexMFConfigBase

Configuration for FlexMFExplicitScorer.

Stability:

Experimental

Parameters:

  • embedding_size (int)

  • batch_size (int)

  • learning_rate (float)

  • epochs (int)

  • regularization (float)

  • reg_method (Literal['AdamW', 'L2'] | None)

class lenskit.flexmf.FlexMFExplicitScorer(config=None, **kwargs)#

Bases: FlexMFScorerBase

Explicit-feedback rating prediction with FlexMF. This realizes a biased matrix factorization model (similar to lenskit.als.BiasedMF) trained with PyTorch.

Stability:

Experimental

Parameters:
create_trainer(data, options)#

Create a model trainer to train this model.

score_items(users, items)#

Score for users and items, after resolivng them and limiting to known users and items.

Parameters:
Return type:

Tensor

class lenskit.flexmf.FlexMFImplicitConfig(embedding_size=50, batch_size=8192, learning_rate=0.01, epochs=10, regularization=0.1, reg_method='L2', loss='logistic', negative_strategy=None, negative_count=1, positive_weight=1.0, user_bias=None, item_bias=True)#

Bases: FlexMFConfigBase

Configuration for FlexMFImplicitScorer. It inherits base model options from FlexMFConfigBase.

Stability:

Experimental

Parameters:

  • embedding_size (int)

  • batch_size (int)

  • learning_rate (float)

  • epochs (int)

  • regularization (float)

  • reg_method (Literal['AdamW', 'L2'] | None)

  • loss (Literal['logistic', 'pairwise', 'warp'])

  • negative_strategy (Literal['uniform', 'popular', 'misranked'] | None)

  • negative_count (Annotated[int, Gt(gt=0)])

  • positive_weight (Annotated[float, Gt(gt=0)])

  • user_bias (bool | None)

  • item_bias (bool)

item_bias: bool = True#

Whether to learn an item bias term.

loss: Literal['logistic', 'pairwise', 'warp'] = 'logistic'#

The loss to use for model training.

negative_count: Annotated[int, Gt(gt=0)] = 1#

The number of negative items to sample for each positive item in the training data. With BPR loss, the positive item is compared to each negative item; with logistic loss, the positive item is treated once per learning round, so this setting effectively makes the model learn on _n_ negatives per positive, rather than giving positive and negative examples equal weight.

negative_strategy: Literal['uniform', 'popular', 'misranked'] | None = None#

The negative sampling strategy. The default is "misranked" for WARP loss and "uniform" for other losses.

positive_weight: Annotated[float, Gt(gt=0)] = 1.0#

A weighting multiplier to apply to the positive item’s loss, to adjust the relative importance of positive and negative classifications. Only applies to logistic loss.

user_bias: bool | None = None#

Whether to learn a user bias term. If unspecified, the default depends on the loss function (False for pairwise and True for logistic).

class lenskit.flexmf.FlexMFImplicitScorer(config=None, **kwargs)#

Bases: FlexMFScorerBase

Implicit-feedback rating prediction with FlexMF. This is capable of realizing multiple models, including:

  • BPR-MF (Bayesian personalized ranking) [RFGSchmidtThieme09] (with "pairwise" loss)

  • Logistic matrix factorization [Joh14] (with "logistic" loss)

All use configurable negative sampling, including the sampling approach from WARP.

Stability:

Experimental

Parameters:
create_trainer(data, options)#

Create a model trainer to train this model.