Package: unirec
UniRecIntroductionUniRec is an easy-to-use, lightweight, and scalable implementation of recommender systems. Its primary objective is to enable users to swiftly construct a comprehensive ecosystem of recommenders using a minimal set of robust and practical recommendation models. These models are designed to deliver scalable and competitive performance, encompassing a majority of real-world recommendation scenarios.It is important to note that this goal differs from those of other well-known public libraries, such as Recommender and RecBole, which include missions of providing an extensive range of recommendation algorithms or offering various datasets.The term "Uni-" carries several implications:Unit: Our aim is to employ a minimal set of models to facilitate the recommendation service onboarding process across most real-world scenarios. By maintaining a lightweight and extensible architecture, users can effortlessly modify and incorporate customized models into UniRec, catering to their specific future requirements.United: In contrast to the Natural Language Processing (NLP) domain, it is challenging to rely on a single model to serve end-to-end business applications in recommender systems. It is desirable that various modules or stages (such as retrieval and ranking) within a recommender system are not isolated and trained independently but are closely interconnected.Unified: While we acknowledge that model parameters cannot be unified, we believe there is potential to unify model structures. Consequently, we are exploring the possibility of utilizing a unified Transformer structure to serve different modules within recommender systems.Universal: We aspire for UniRec to support a wide range of recommendation scenarios, including gaming, music, movies, ads, and e-commerce, using a universal data model.InstallationInstallation from PyPIEnsure thatPyTorchwith CUDA supported (version 1.10.0-1.13.1) is installed:pipinstalltorch==1.12.1+cu113torchvision==0.13.1+cu113torchaudio==0.12.1--extra-index-urlhttps://download.pytorch.org/whl/cu113

python-c"import torch; print(torch.__version__)"Installunirecwith pip:pipinstallunirecInstallation from Wheel LocallyEnsure thatPyTorchwith CUDA supported (version 1.10.0-1.13.1) is installed:pipinstalltorch==1.12.1+cu113torchvision==0.13.1+cu113torchaudio==0.12.1--extra-index-urlhttps://download.pytorch.org/whl/cu113

python-c"import torch; print(torch.__version__)"Clone Git Repogitclonehttps://github.com/microsoft/UniRec.gitBuildcdUniRec
pipinstall--user--upgradesetuptoolswheeltwine
pythonsetup.pysdistbdist_wheelAfter building, the wheel package could be found inUniRec/dist.Installpipinstalldist/unirec-*.whlThe specific package name could be find inUniRec/dist.Check ifunirecis installed sucessfully:python-c"from unirec.utils import general; print(general.get_local_time_str())"AlgorithmsAlgorithmTypePaperCodeMFCollaborative FilteringBPRunirec/model/cf/mf.pyUserCFCollaborative Filtering-unirec/model/cf/usercf.pySLIMCollaborative FilteringSLIMunirec/model/cf/slim.pyAdmmSLIMCollaborative FilteringADMMSLIMunirec/model/cf/admmslim.pySARCollaborative FilteringItemCF,SARunirec/model/cf/sar.pyEASECollaborative FilteringEASEunirec/model/cf/ease.pyMultiVAECollaborative FilteringMultiVAEunirec/model/cf/multivae.pySVDPlusPlusSequential ModelSVD++unirec/model/sequential/svdplusplus.pyAvgHistSequential Model-unirec/model/sequential/avghist.pyAttHistSequential Model-unirec/model/sequential/atthist.pyGRU4RecSequential ModelGRU4Recunirec/model/sequential/gru4rec.pySASRecSequential ModelSASRecunirec/model/sequential/sasrec.pyConvFormerSequential ModelConvFormerunirec/model/sequential/convformer.pyFastConvFormerSequential ModelConvFormerunirec/model/sequential/fastconvformer.pyFMRanking ModelFactorization Machineunirec/model/rank/fm.pyBSTRanking ModelBehavior sequence transformerunirec/model/rank/bst.pyExamplesTo go through all the examples listed below, we provide ascriptfor downloading and split forml-100kdataset. Run:pythondownload_split_ml100k.pyThe files for the raw dataset would be saved in your home dir:~/.unirec/dataset/ml-100kNext, it is essential to convert the raw dataset into a format compatible with UniRec. Use thescriptto process and save the files inUniRec/data/ml-100k.cdexamples/preprocess
bashpreprocess_ml100k.shGeneral TrainingTo train an existing model in UniRec, for instance, training SASRec with ml-100k dataset, refer to the script provided inexamples/training/train_ml100k.sh.Multi-GPU TrainingUniRec supports multi-GPU training with the integration ofAccelerate. An example script is available atexamples/training/multi_gpu_train_ml100k.sh. The key arguments in the script could be found in line 3-12 in the script:GPU_INDICES="0,1"# e.g. "0,1"# Specify the number of nodes to use (one node may have multiple GPUs)NUM_NODES=1# Specify the number of processes in each node (the number should equal the number of GPU_INDICES)NPROC_PER_NODE=2For more details about the launching command, please refer toAccelerate Docs.Hyperparameter Tuning with wandbUniRec supports hyperparameter tuning (or hyperparameter optimization, HPO) with the intergration ofWandB. There are three major steps to start a wandb experiment.Compose a training script and enablewandb. An example is provided inexamples/training/train_ml100k_with_wandb.sh. The key arguments are:--use_wandb=1: enable wandb in process--wandb_file=/path/to/configuration_file: the configuration file for wandb, including command, metrics, method, and search space.Define sweep configuration. Write a YAML-format configuration file to set the command, monitor metrics, tuning method and search space.An example is available atexamples/training/wandb.yaml. For more details about the configuration file, refer toWandB DocsInitialize sweeps and start sweep agents. To start an experiment with wandb, first, initialize a sweep controller for selecting hyperparameters and issuing intructions; then an agent would actually perform the runs. An example for launching wandb experiments is provided inexamples/training/wandb_start.sh. Note that we offer a pipeline command in the script to start the agent automatically after sweep initialization. However, we recommend the simpler manual two-step process:## Step 1. Initialize sweeps with CLI using configuration file.## For more details, please refer to https://docs.wandb.ai/guides/sweeps/initialize-sweepswandbsweepconfig.yaml## Step 2. After `wandb sweep`, you would get a sweep id and the hint to use `sweep agent`, like:## wandb: Creating sweep from: ./wandb.yaml## wandb: Created sweep with ID: xxx## wandb: View sweep at: https://wandb.ai/xxx/xxx/xxx/xxx## wandb: Run sweep agent with: wandb agent xxx/xxx/xxx/xxxwandbagententity/project/sweep_IDServing with C# and JavaUniRec supports C# and Java inference based onONNXformat. We provide inference for user embedding, item embedding, and user-item score.For more details, please refer toexamples/serving/READMEContributingThis project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.TrademarksThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must followMicrosoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.