Package: pre-reco-utils
RecommendersWhat's New (February 4, 2021)We have a new relaseRecommenders 2021.2!It comes with lots of bug fixes, optimizations and 3 new algorithms, GeoIMC, Standard VAE and Multinomial VAE. We also added tools to facilitate the use of Microsoft News dataset (MIND). In addition, we publised our KDD2020 tutorial where we built a recommender of COVID papers using Microsoft Academic Graph.We also changed the default branch from master to main. Now when you download the repo, you will get main branch.See past announcements inNEWS.md.IntroductionThis repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks:Prepare Data: Preparing and loading data for each recommender algorithmModel: Building models using various classical and deep learning recommender algorithms such as Alternating Least Squares (ALS) or eXtreme Deep Factorization Machines (xDeepFM).Evaluate: Evaluating algorithms with offline metricsModel Select and Optimize: Tuning and optimizing hyperparameters for recommender modelsOperationalize: Operationalizing models in a production environment on AzureSeveral utilities are provided inreco_utilsto support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. See thereco_utils documentation.For a more detailed overview of the repository, please see the documents on thewiki page.Getting StartedPlease see thesetup guidefor more details on setting up your machine locally, on adata science virtual machine (DSVM)or onAzure Databricks.To setup on your local machine:Install Anaconda with Python >= 3.6.Minicondais a quick way to get started.Clone the repositorygitclonehttps://github.com/Microsoft/RecommendersRun the generate conda file script to create a conda environment: (This is for a basic python environment, seeSETUP.mdfor PySpark and GPU environment setup)cdRecommenders
pythontools/generate_conda_file.py
condaenvcreate-freco_base.yamlActivate the conda environment and register it with Jupyter:condaactivatereco_base
python-mipykernelinstall--user--namereco_base--display-name"Python (reco)"Start the Jupyter notebook serverjupyternotebookRun theSAR Python CPU MovieLensnotebook under the00_quick_startfolder. Make sure to change the kernel to "Python (reco)".NOTE- TheAlternating Least Squares (ALS)notebooks require a PySpark environment to run. Please follow the steps in thesetup guideto run these notebooks in a PySpark environment. For the deep learning algorithms, it is recommended to use a GPU machine.AlgorithmsThe table below lists the recommender algorithms currently available in the repository. Notebooks are linked under the Environment column when different implementations are available.AlgorithmEnvironmentTypeDescriptionAlternating Least Squares (ALS)PySparkCollaborative FilteringMatrix factorization algorithm for explicit or implicit feedback in large datasets, optimized by Spark MLLib for scalability and distributed computing capabilityAttentive Asynchronous Singular Value Decomposition (A2SVD)*Python CPU / Python GPUCollaborative FilteringSequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanismCornac/Bayesian Personalized Ranking (BPR)Python CPUCollaborative FilteringMatrix factorization algorithm for predicting item ranking with implicit feedbackConvolutional Sequence Embedding Recommendation (Caser)Python CPU / Python GPUCollaborative FilteringAlgorithm based on convolutions that aim to capture both user’s general preferences and sequential patternsDeep Knowledge-Aware Network (DKN)*Python CPU / Python GPUContent-Based FilteringDeep learning algorithm incorporating a knowledge graph and article embeddings to provide powerful news or article recommendationsExtreme Deep Factorization Machine (xDeepFM)*Python CPU / Python GPUHybridDeep learning based algorithm for implicit and explicit feedback with user/item featuresFastAI Embedding Dot Bias (FAST)Python CPU / Python GPUCollaborative FilteringGeneral purpose algorithm with embeddings and biases for users and itemsLightFM/Hybrid Matrix FactorizationPython CPUHybridHybrid matrix factorization algorithm for both implicit and explicit feedbacksLightGBM/Gradient Boosting Tree*Python CPU/PySparkContent-Based FilteringGradient Boosting Tree algorithm for fast training and low memory usage in content-based problemsLightGCNPython CPU / Python GPUCollaborative FilteringDeep learning algorithm which simplifies the design of GCN for predicting implicit feedbackGeoIMCPython CPUHybridMatrix completion algorithm that has into account user and item features using Riemannian conjugate gradients optimization and following a geometric approach.GRU4RecPython CPU / Python GPUCollaborative FilteringSequential-based algorithm that aims to capture both long and short-term user preferences using recurrent neural networksMultinomial VAEPython CPU / Python GPUCollaborative FilteringGenerative Model for predicting user/item interactionsNeural Recommendation with Long- and Short-term User Representations (LSTUR)*Python CPU / Python GPUContent-Based FilteringNeural recommendation algorithm with long- and short-term user interest modelingNeural Recommendation with Attentive Multi-View Learning (NAML)*Python CPU / Python GPUContent-Based FilteringNeural recommendation algorithm with attentive multi-view learningNeural Collaborative Filtering (NCF)Python CPU / Python GPUCollaborative FilteringDeep learning algorithm with enhanced performance for implicit feedbackNeural Recommendation with Personalized Attention (NPA)*Python CPU / Python GPUContent-Based FilteringNeural recommendation algorithm with personalized attention networkNeural Recommendation with Multi-Head Self-Attention (NRMS)*Python CPU / Python GPUContent-Based FilteringNeural recommendation algorithm with multi-head self-attentionNext Item Recommendation (NextItNet)Python CPU / Python GPUCollaborative FilteringAlgorithm based on dilated convolutions and residual network that aims to capture sequential patternsRestricted Boltzmann Machines (RBM)Python CPU / Python GPUCollaborative FilteringNeural network based algorithm for learning the underlying probability distribution for explicit or implicit feedbackRiemannian Low-rank Matrix Completion (RLRMC)*Python CPUCollaborative FilteringMatrix factorization algorithm using Riemannian conjugate gradients optimization with small memory consumption.Simple Algorithm for Recommendation (SAR)*Python CPUCollaborative FilteringSimilarity-based algorithm for implicit feedback datasetShort-term and Long-term preference Integrated Recommender (SLi-Rec)*Python CPU / Python GPUCollaborative FilteringSequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanism, a time-aware controller and a content-aware controllerStandard VAEPython CPU / Python GPUCollaborative FilteringGenerative Model for predicting user/item interactionsSurprise/Singular Value Decomposition (SVD)Python CPUCollaborative FilteringMatrix factorization algorithm for predicting explicit rating feedback in datasets that are not very largeTerm Frequency - Inverse Document Frequency (TF-IDF)Python CPUContent-Based FilteringSimple similarity-based algorithm for content-based recommendations with text datasetsVowpal Wabbit (VW)*Python CPU (online training)Content-Based FilteringFast online learning algorithms, great for scenarios where user features / context are constantly changingWide and DeepPython CPU / Python GPUHybridDeep learning algorithm that can memorize feature interactions and generalize user featuresxLearn/Factorization Machine (FM) & Field-Aware FM (FFM)Python CPUContent-Based FilteringQuick and memory efficient algorithm to predict labels with user/item featuresNOTE:*indicates algorithms invented/contributed by Microsoft.Independent or incubating algorithms and utilities are candidates for thecontribfolder. This will house contributions which may not easily fit into the core repository or need time to refactor or mature the code and add necessary tests.AlgorithmEnvironmentTypeDescriptionSARplus*PySparkCollaborative FilteringOptimized implementation of SAR for SparkPreliminary ComparisonWe provide abenchmark notebookto illustrate how different algorithms could be evaluated and compared. In this notebook, the MovieLens dataset is split into training/test sets at a 75/25 ratio using a stratified split. A recommendation model is trained using each of the collaborative filtering algorithms below. We utilize empirical parameter values reported in literaturehere. For ranking metrics we usek=10(top 10 recommended items). We run the comparison on a Standard NC6s_v2Azure DSVM(6 vCPUs, 112 GB memory and 1 P100 GPU). Spark ALS is run in local standalone mode. In this table we show the results on Movielens 100k, running the algorithms for 15 epochs.AlgoMAPnDCG@kPrecision@kRecall@kRMSEMAER2Explained VarianceALS0.0047320.0442390.0484620.0177960.9650380.7530010.2556470.251648BPR0.1053650.3899480.3498410.181807N/AN/AN/AN/AFastAI0.0255030.1478660.1303290.0538240.9430840.7443370.2853080.287671LightGCN0.0885260.4198460.3796260.144336N/AN/AN/AN/ANCF0.1077200.3961180.3472960.180775N/AN/AN/AN/ASAR0.1105910.3824610.3307530.1763851.2538051.048484-0.5693630.030474SVD0.0128730.0959300.0911980.0327830.9386810.7426900.2919670.291971ContributingThis project welcomes contributions and suggestions. Before contributing, please see ourcontribution guidelines.Build StatusThese tests are the nightly builds, which compute the smoke and integration tests.mainis our principal branch andstagingis our development branch. We usepytestfor testing python utilities inreco_utilsandpapermillfor thenotebooks. For more information about the testing pipelines, please see thetest documentation.DSVM Build StatusThe following tests run on a Windows and Linux DSVM daily. These machines run 24/7.Build TypeBranchStatusBranchStatusLinux CPUmainstagingLinux GPUmainstagingLinux SparkmainstagingRelated projectsMicrosoft AI Github: Find other Best Practice projects, and Azure AI design patterns in our central repository.NLP best practices: Best practices and examples on NLP.Computer vision best practices: Best practices and examples on computer vision.Forecasting best practices: Best practices and examples on time series forecasting.Reference papersA. Argyriou, M. González-Fierro, and L. Zhang, "Microsoft Recommenders: Best Practices for Production-Ready Recommendation Systems",WWW 2020: International World Wide Web Conference Taipei, 2020. Available online:https://dl.acm.org/doi/abs/10.1145/3366424.3382692L. Zhang, T. Wu, X. Xie, A. Argyriou, M. González-Fierro and J. Lian, "Building Production-Ready Recommendation System at Scale",ACM SIGKDD Conference on Knowledge Discovery and Data Mining 2019 (KDD 2019), 2019.S. Graham,  J.K. Min, T. Wu, "Microsoft recommenders: tools to accelerate developing recommender systems",RecSys '19: Proceedings of the 13th ACM Conference on Recommender Systems, 2019. Available online:https://dl.acm.org/doi/10.1145/3298689.3346967