Feature/vector rank params (#218)

`recommend_n_threads` and `recommend_use_gpu_ranking` arguments to EASEModel and vector models
Closes #199

Author: blondered

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - `ImplicitBPRWrapperModel` model ([#232](https://github.com/MobileTeleSystems/RecTools/pull/232))
+- All vector models and `EASEModel` support for enabling ranking on GPU and selecting number of threads for CPU ranking. Added `recommend_n_threads` and `recommend_use_gpu_ranking` parameters to `EASEModel`, `ImplicitALSWrapperModel`, `ImplicitBPRWrapperModel`, `PureSVDModel` and `DSSMModel`. Added `recommend_use_gpu_ranking` to `LightFMWrapperModel`. GPU and CPU ranking may provide different ordering of items with identical scores in recommendation table, so this could change ordering items in recommendations since GPU ranking is now used as a default one. ([#218](https://github.com/MobileTeleSystems/RecTools/pull/218))
 
 ## [0.9.0] - 11.12.2024
 

examples/9_model_configs_and_saving.ipynb

@@ -27,7 +27,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -36,6 +36,7 @@
     "from rectools.models import (\n",
     "    ImplicitItemKNNWrapperModel, \n",
     "    ImplicitALSWrapperModel, \n",
+    "    ImplicitBPRWrapperModel, \n",
     "    EASEModel, \n",
     "    PopularInCategoryModel, \n",
     "    PopularModel, \n",
@@ -329,7 +330,7 @@
     "- \"ItemItemRecommender\"\n",
     "- A path to a class (including any custom class) that can be imported. Like \"implicit.nearest_neighbours.TFIDFRecommender\"\n",
     "\n",
-    "Specify wrapped model hyper-params under the \"model.params\" key"
+    "Specify wrapped model hyper-params under the \"model\" dict relevant keys."
    ]
   },
   {
@@ -381,9 +382,9 @@
     "\n",
     "Specify which model you want to wrap under the \"model.cls\" key. Since there is only one default model, you can skip this step. \"implicit.als.AlternatingLeastSquares\" will be used by default. Also you can pass a path to a class (including any custom class) that can be imported.\n",
     "\n",
-    "Specify wrapped model hyper-params under the \"model.params\" key.  \n",
+    "Specify wrapped model hyper-params under the \"model\" dict relevant keys.  \n",
     "\n",
-    "Specify wrapper hyper-params under relevant keys."
+    "Specify wrapper hyper-params under relevant config keys."
    ]
   },
   {
@@ -440,6 +441,73 @@
     "model.get_params(simple_types=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### BPR-MF\n",
+    "`ImplicitBPRWrapperModel` is a wrapper.  \n",
+    "Use \"model\" key in config to specify wrapped model class and params:  \n",
+    "\n",
+    "Specify which model you want to wrap un\\der the \"model.cls\" key. Since there is only one default model, you can skip this step. \"implicit.bpr.BayesianPersonalizedRanking\" will be used by default. Also you can pass a path to a class (including any custom class) that can be imported.\n",
+    "\n",
+    "Specify wrapped model hyper-params under the \"model\" dict relevant keys.  \n",
+    "\n",
+    "Specify wrapper hyper-params under relevant config keys."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config = {\n",
+    "    \"model\": {\n",
+    "        # \"cls\": \"BayesianPersonalizedRanking\",  # will work too\n",
+    "        # \"cls\": \"implicit.bpr.BayesianPersonalizedRanking\",  # will work too\n",
+    "        \"factors\": 16,\n",
+    "        \"num_threads\": 2,\n",
+    "        \"iterations\": 2,\n",
+    "        \"random_state\": 32\n",
+    "    },\n",
+    "    \"recommend_use_gpu_ranking\": False,\n",
+    "}\n",
+    "model = ImplicitBPRWrapperModel.from_config(config)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'cls': 'ImplicitBPRWrapperModel',\n",
+       " 'verbose': 0,\n",
+       " 'model.cls': 'BayesianPersonalizedRanking',\n",
+       " 'model.factors': 16,\n",
+       " 'model.learning_rate': 0.01,\n",
+       " 'model.regularization': 0.01,\n",
+       " 'model.dtype': 'float64',\n",
+       " 'model.iterations': 2,\n",
+       " 'model.verify_negative_samples': True,\n",
+       " 'model.random_state': 32,\n",
+       " 'model.use_gpu': True,\n",
+       " 'recommend_n_threads': None,\n",
+       " 'recommend_use_gpu_ranking': False}"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model.get_params(simple_types=True)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -535,9 +603,9 @@
     "\n",
     "Specify which model you want to wrap under the \"model.cls\" key. Since there is only one default model, you can skip this step. \"LightFM\" will be used by default. Also you can pass a path to a class (including any custom class) that can be imported. Like \"lightfm.lightfm.LightFM\"\n",
     "\n",
-    "Specify wrapped model hyper-params under the \"model.params\" key.  \n",
+    "Specify wrapped model hyper-params under the \"model\" dict relevant keys.  \n",
     "\n",
-    "Specify wrapper hyper-params under relevant keys."
+    "Specify wrapper hyper-params under relevant config keys."
    ]
   },
   {
@@ -736,8 +804,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "rectools",
+   "language": "python",
+   "name": "rectools"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.12"
   }
  },
  "nbformat": 4,

rectools/models/dssm.py

@@ -215,7 +215,7 @@ def inference_users(self, dataloader: DataLoader[tp.Any]) -> np.ndarray:
         return vectors
 
 
-class DSSMModel(VectorModel):
+class DSSMModel(VectorModel):  # pylint: disable=too-many-instance-attributes
     """
     Wrapper for `rectools.models.dssm.DSSM`
 
@@ -267,6 +267,17 @@ class DSSMModel(VectorModel):
     deterministic : bool, default ``False``
         If ``True``, sets whether PyTorch operations must use deterministic algorithms.
         Use `pytorch_lightning.seed_everything` together with this param to fix the random state.
+    recommend_n_threads: int, default 0
+        Number of threads to use for recommendation ranking on CPU.
+        Specifying ``0`` means to default to the number of cores on the machine.
+        If you want to change this parameter after model is initialized,
+        you can manually assign new value to model `recommend_n_threads` attribute.
+    recommend_use_gpu_ranking: bool, default ``True``
+        Flag to use GPU for recommendation ranking. Please note that GPU and CPU ranking may provide
+        different ordering of items with identical scores in recommendation table.
+        If ``True``, `implicit.gpu.HAS_CUDA` will also be checked before ranking.
+        If you want to change this parameter after model is initialized,
+        you can manually assign new value to model `recommend_use_gpu_ranking` attribute.
     """
 
     recommends_for_warm = True
@@ -292,6 +303,8 @@ def __init__(
         loggers: tp.Union[Logger, tp.Iterable[Logger], bool] = True,
         verbose: int = 0,
         deterministic: bool = False,
+        recommend_n_threads: int = 0,
+        recommend_use_gpu_ranking: bool = True,
     ) -> None:
         super().__init__(verbose=verbose)
         self.model: DSSM
@@ -313,6 +326,8 @@ def __init__(
         self.train_dataset_type = train_dataset_type
         self.user_dataset_type = user_dataset_type
         self.item_dataset_type = item_dataset_type
+        self.recommend_n_threads = recommend_n_threads
+        self.recommend_use_gpu_ranking = recommend_use_gpu_ranking
 
     def _fit(self, dataset: Dataset, dataset_valid: tp.Optional[Dataset] = None) -> None:  # type: ignore
         self.trainer = deepcopy(self._trainer)

rectools/models/ease.py

@@ -15,9 +15,11 @@
 """EASE model."""
 
 import typing as tp
+import warnings
 
 import numpy as np
 import typing_extensions as tpe
+from implicit.gpu import HAS_CUDA
 from scipy import sparse
 
 from rectools import InternalIds
@@ -33,7 +35,8 @@ class EASEModelConfig(ModelConfig):
     """Config for `EASE` model."""
 
     regularization: float = 500.0
-    num_threads: int = 1
+    recommend_n_threads: int = 0
+    recommend_use_gpu_ranking: bool = True
 
 
 class EASEModel(ModelBase[EASEModelConfig]):
@@ -51,10 +54,22 @@ class EASEModel(ModelBase[EASEModelConfig]):
     ----------
     regularization : float
         The regularization factor of the weights.
+    num_threads: Optional[int], default ``None``
+        Deprecated, use `recommend_n_threads` instead.
+        Number of threads used for recommendation ranking on CPU.
+    recommend_n_threads: int, default 0
+        Number of threads to use for recommendation ranking on CPU.
+        Specifying ``0`` means to default to the number of cores on the machine.
+        If you want to change this parameter after model is initialized,
+        you can manually assign new value to model `recommend_n_threads` attribute.
+    recommend_use_gpu_ranking: bool, default ``True``
+        Flag to use GPU for recommendation ranking. Please note that GPU and CPU ranking may provide
+        different ordering of items with identical scores in recommendation table.
+        If ``True``, `implicit.gpu.HAS_CUDA` will also be checked before ranking.
+        If you want to change this parameter after model is initialized,
+        you can manually assign new value to model `recommend_use_gpu_ranking` attribute.
     verbose : int, default 0
         Degree of verbose output. If 0, no output will be provided.
-    num_threads: int, default 1
-        Number of threads used for `recommend` method.
     """
 
     recommends_for_warm = False
@@ -65,23 +80,45 @@ class EASEModel(ModelBase[EASEModelConfig]):
     def __init__(
         self,
         regularization: float = 500.0,
-        num_threads: int = 1,
+        num_threads: tp.Optional[int] = None,
+        recommend_n_threads: int = 0,
+        recommend_use_gpu_ranking: bool = True,
         verbose: int = 0,
     ):
 
         super().__init__(verbose=verbose)
         self.weight: np.ndarray
         self.regularization = regularization
-        self.num_threads = num_threads
+
+        if num_threads is not None:
+            warnings.warn(
+                """
+            `num_threads` argument is deprecated and will be removed in future releases.
+            Please use `recommend_n_threads` instead.
+            """
+            )
+            recommend_n_threads = num_threads
+
+        self.recommend_n_threads = recommend_n_threads
+        self.recommend_use_gpu_ranking = recommend_use_gpu_ranking
 
     def _get_config(self) -> EASEModelConfig:
         return EASEModelConfig(
-            cls=self.__class__, regularization=self.regularization, num_threads=self.num_threads, verbose=self.verbose
+            cls=self.__class__,
+            regularization=self.regularization,
+            recommend_n_threads=self.recommend_n_threads,
+            recommend_use_gpu_ranking=self.recommend_use_gpu_ranking,
+            verbose=self.verbose,
         )
 
     @classmethod
     def _from_config(cls, config: EASEModelConfig) -> tpe.Self:
-        return cls(regularization=config.regularization, num_threads=config.num_threads, verbose=config.verbose)
+        return cls(
+            regularization=config.regularization,
+            recommend_n_threads=config.recommend_n_threads,
+            recommend_use_gpu_ranking=config.recommend_use_gpu_ranking,
+            verbose=config.verbose,
+        )
 
     def _fit(self, dataset: Dataset) -> None:  # type: ignore
         ui_csr = dataset.get_user_item_matrix(include_weights=True)
@@ -117,7 +154,8 @@ def _recommend_u2i(
             k=k,
             filter_pairs_csr=ui_csr_for_filter,
             sorted_object_whitelist=sorted_item_ids_to_recommend,
-            num_threads=self.num_threads,
+            num_threads=self.recommend_n_threads,
+            use_gpu=self.recommend_use_gpu_ranking and HAS_CUDA,
         )
 
         return all_user_ids, all_reco_ids, all_scores