Microsoft Recommenders（recommenders 包）：推荐系统通用工具库安装与使用完全指南

Microsoft Recommendersrecommenders 包推荐系统通用工具库安装与使用完全指南【免费下载链接】recommendersBest Practices on Recommendation Systems项目地址: https://gitcode.com/gh_mirrors/re/recommenders本指南以仓库内 recommenders/README.md 为骨架系统讲解recommenders这个 Python 工具包的安装方式含 GPU / Spark / 实验性依赖等可选组合、六大子模块Datasets、Evaluation、Models、Tuning、Utils的核心功能并结合 setup.py 与各子模块源码深入说明参数与底层实现。读完本文你将掌握如何在本机、GPU 环境与 Spark 环境正确安装该包理解数据加载与切分、离线评估指标、模型算法清单和超参调优工具的具体用法并能直接运行仓库中的示例 Notebook 完成一次完整的推荐系统实验。一、包定位为推荐系统开发与评估提供通用工具recommenders是 Microsoft RecommendersBest Practices on Recommendation Systems项目中的核心 Python 包其定位是简化开发与评估推荐系统时的常见任务。它提供了一系列高层次的封装函数覆盖如下高频场景以统一格式加载各类公开数据集并按要求切分为训练 / 测试集在纯 Python 或 PySpark 环境中计算常用离线评估指标提供多种经典与前沿推荐算法的实现供自学习与二次开发提供超参数调优工具与框架管理辅助函数GPU、Spark、Jupyter。包内所有子模块的公开 API 均带有完整 doc-string仓库也维护了在线文档见 docs/ 下的 RST 源文件。包版本信息定义于 recommenders/init.py当前仓库版本为1.2.1该文件同时定义了TITLE、VERSION、AUTHOR、LICENSE等元数据常量供包内其他模块引用。二、安装指南2.1 前置条件Pre-requisites部分依赖在pip安装时需要编译因此不同平台需要先准备编译工具链Linux安装build-essential及与 Python 版本对应的开发包sudo apt-get install -y build-essential libpythonversion其中version应替换为实际的 Python 版本例如3.11。Windows需要安装 Microsoft C Build ToolsVisual Studio C 生成工具。各平台完整的软件前置要求见仓库根目录的 SETUP.md其中包含 GPU、Spark、Databricks、macOS/Windows 专项说明以及面向开发者的 Dev Container / Codespaces 配置.devcontainer/devcontainer.json 与 tools/docker/Dockerfile。2.2 基本安装Basic Installation安装核心工具、CPU 算法及其依赖pip install --upgrade pip setuptools pip install recommenders需要说明的是基础安装不包含Spark、GPU 与 Jupyter 相关依赖仅覆盖recommenders包本身可运行功能所需的最小依赖集。具体的核心依赖清单可在 setup.py 的install_requires中查看例如pandas2.0.0,3.0.0、scikit-learn1.2.0,2、lightgbm4.0.0,5、transformers4.27.0,5、numpy2.0.0等版本约束均经过项目测试验证建议按此约束安装以避免已知兼容性问题。2.3 可选依赖组Optional Dependencies默认安装不会引入仓库所有代码与 Notebook 示例需要的依赖用户可在安装时或后续更新 pip 安装时按需指定依赖组。文档定义的依赖组如下依赖组用途examples运行 示例 NotebookJupyter 相关依赖gpu启用 GPU 功能PyTorch 与 TensorFlowspark启用 Apache Spark 功能数据集、切分、评估及部分算法dev仅开发 / 测试所需如black、pytestall以上所有依赖的并集experimental正在评估中的实验性依赖nniNNI 调优框架依赖注意目前xLearn与Vowpal Wabbit位于experimental组。依赖组可单独或组合安装# 安装核心依赖 CPU 推荐算法 Notebook 支持 pip install recommenders[examples] # 同时支持示例 Notebook 与 GPU 功能 pip install recommenders[examples,gpu]从源码层面看这些依赖组定义于 setup.py 的extras_require字典中gpu组包含tensorflow2.8.4,!2.9.0.*,!2.9.1,!2.9.2,!2.10.0.*,2.16、torch2.0.1,3、nvidia-ml-py与tf-slimspark组包含pyspark3.3.0,4与pyarrow10.0.1dev组包含black、pytest、pytest-cov、pytest-mockexperimental组包含xlearn0.40a1、vowpalwabbit8.9.0,9、nni1.5、pymanopt0.2.5、lightfm1.17,2、scikit-surprise1.1.3。这也解释了文档中xLearn 与 Vowpal Wabbit 在实验组的说法。2.4 GPU 支持GPU Support启用 TensorFlow 与 PyTorch 的 GPU 能力需要系统预先安装CUDA Toolkit v11.2CuDNN v8.1需要特别指出uv现代 Python 环境管理工具无法安装 CUDA 这类系统级依赖CUDA 必须通过系统包管理器安装# Ubuntu/Debian sudo apt install nvidia-cuda-toolkit # 或从 NVIDIA 官网下载安装虚拟环境场景下可使用 SETUP.md 中描述的 Nvidia Docker 容器手动安装则参考 TensorFlow 与 PyTorch 官方安装页的要求。安装带 GPU 支持的包时需要通过--find-links或-f参数指向 PyTorch 的预编译索引确保下载到带 CUDA 支持的 PyTorch 版本pip install recommenders[gpu] -f https://download.pytorch.org/whl/cu111/torch_stable.htmlGPU 环境完整搭建流程含 VS Code Jupyter kernel见 SETUP.md 的 Setup for GPU 一节。2.5 实验性依赖Experimental Dependencies项目正在评估纳入以下依赖vowpalwabbit现有示例展示了在命令行安装 Vowpal Wabbit 后的用法若改用 PyPI 包带 scikit-learn 接口可更便捷地集成进 Python 环境。xlearn在部分平台上xLearn 需要预先安装cmake。2.6 其他依赖Other Dependencies部分依赖无法通过recommenders的 PyPI 包获得需要单独安装pymanoptRLRMC 与 GeoIMC 算法所需兼容 TensorFlow 2 的版本可通过以下命令安装pip install pymanopthttps://github.com/pymanopt/pymanopt/archive/fb36a272cdeecb21992cfd9271eb82baafeb316d.zip2.7 NNI 依赖NNI 依赖可以安装更新版本但未经测试建议按仓库约束nni1.5使用。2.8 从本地副本安装Installing from a Local Copy若需使用尚未发布到 PyPI 的源码版本可以从仓库本地安装。仓库根目录提供了 setup.py在已按 SETUP.md 准备好环境的前提下于仓库主目录执行pip install -e .也可以直接从 GitHub 或指定分支安装pip install -e githttps://github.com/microsoft/recommenders/#eggpkg pip install -e githttps://github.com/microsoft/recommenders/staging#eggpkg注意pip 安装不会自动安装全部前置条件环境仍需按 SETUP.md 提前配置妥当。另外setup.py 还定义了一个便捷机制设置环境变量HASH后会在版本号后追加时间戳形式的.post后缀方便区分本地构建版本。三、包内容总览Contentsrecommenders包由以下子模块构成对应目录为 recommenders/Datasets数据集的拉取、格式化与训练 / 测试切分Evaluation推荐指标计算Python 与 PySparkModels多种推荐算法实现Tuning超参数调优工具Utils常量定义与框架辅助函数GPU、Spark、Jupyter。3.1 Datasets数据加载与切分Datasets 模块包含多个数据集的加载器并提供了训练 / 测试切分工具。数据加载Data Loading模块为多个公开数据集提供加载器。以 MovieLens 为例recommenders/datasets/movielens.py 支持以 pandas 或 Spark DataFrame 格式加载 100k、1M、10M、20M 四种规模的数据用于算法验证与性能基准评测df movielens.load_pandas_df(size100k)load_pandas_df的完整签名见 recommenders/datasets/movielens.py为load_pandas_df(size100k, headerNone, local_cache_pathNone, title_colNone, genres_colNone, year_colNone)各参数含义size数据规模取值范围100k、1m、10m、20m另有仅用于测试的mock100模拟数据header评分数据的列名如(UserId, ItemId, Rating, Timestamp)不传时使用默认列名local_cache_path下载 zip 文件的缓存目录为None时使用临时目录并在使用后清理title_col/genres_col/year_col需要加载电影标题、类型|分隔、上映年份时传入对应的新列名。源码中的DATA_FORMAT字典揭示了不同规模数据的内部差异100k使用制表符分隔且无表头ml-100k/u.data1m/10m使用::分隔20m使用逗号分隔且带表头ml-20m/ratings.csv。加载时评分列会被转换为float若指定了电影信息列还会与load_item_df读取的电影元数据按 movie id 合并。默认列名DEFAULT_HEADER、DEFAULT_USER_COL、DEFAULT_ITEM_COL、DEFAULT_RATING_COL、DEFAULT_TIMESTAMP_COL等统一定义于 recommenders/utils/constants.py。切分技术Splitting Techniques目前提供三种数据集切分方法均支持按用户或按物品切分并能过滤最小样本例如过滤掉评分物品过少的用户或评分用户过少的物品Random随机切分最基础的方式根据设定的比例将样本随机分配到各组。对应实现为 recommenders/datasets/python_splitters.py 中的python_random_split(data, ratio0.75, seed42)支持通过seed控制随机性、ratio控制训练集比例并有配套的 NumPy 版本numpy_stratified_split等。Chronological时序切分利用时间戳对数据排序选择一个截止时间将截止前的数据划为训练集、之后的划为测试集从而保持比例要求。对应实现为python_chrono_splitSpark 版本见 recommenders/datasets/spark_splitters.py。Stratified分层切分与随机抽样类似但切分是分层的。例如按用户切分时会尽量保证训练集与测试集中物品的比例保持一致按物品切分则反之。对应实现为python_stratified_split及其内部的_do_stratification逻辑NumPy 版本为numpy_stratified_split。仓库提供了针对这些切分工具的单元测试可参考 tests/unit/recommenders/datasets/test_python_splitter.py 与 tests/unit/recommenders/datasets/test_spark_splitter.py。3.2 Evaluation离线评估指标Evaluation 子模块提供常用推荐指标的计算功能既支持纯 Python 环境也支持基于 PySpark 的 Spark 环境入口分别为 recommenders/evaluation/python_evaluation.py 与 recommenders/evaluation/spark_evaluation.py。当前支持的指标包括Root Mean Squared ErrorRMSE均方根误差Mean Absolute ErrorMAE平均绝对误差R²决定系数Explained Variance解释方差Precision at KK 处精确率Recall at KK 处召回率Normalized Discounted Cumulative Gain at KnDCGK归一化折损累计增益Mean Average Precision at KMAPK平均精度均值Area Under CurveAUC曲线下面积Logistic Loss对数损失这些指标中RMSE、MAE、R²、Explained Variance 面向显式评分预测rating而 PrecisionK、RecallK、nDCGK、MAPK、AUC、Logistic Loss 面向排序ranking评估可依据预测分数计算。对应的单元测试位于 tests/unit/recommenders/evaluation/test_python_evaluation.py 与 tests/unit/recommenders/evaluation/test_spark_evaluation.py。详细用法可参阅 docs/evaluation.rst 与示例 Notebook examples/03_evaluate/evaluation.ipynb。3.3 Models算法实现Models 子模块包含多种算法的实现可与外部包配合使用用于评估与开发新的推荐系统方案。完整的算法列表与对应示例可在根目录 README.md 的 Algorithms 表中查看其完整清单如下CornacBayesian Personalized Ranking (BPR)、Bilateral Variational Autoencoder (BiVAE) 等见 recommenders/models/cornac/DeepRec见 recommenders/models/deeprec/Convolutional Sequence Embedding RecommendationCASERDeep Knowledge-Aware NetworkDKNExtreme Deep Factorization MachinexDeepFMGRULightGCNNext Item RecommendationNextItNetShort-term and Long-term Preference Integrated RecommenderSLi-RecMulti-Interest-Aware Sequential User ModelingSUMembdotbiasEmbedding Dot Bias见 recommenders/models/embdotbias/GeoIMC见 recommenders/models/geoimc/LightFM见 recommenders/models/lightfm/LightGBM见 recommenders/models/lightgbm/NCFNeural Collaborative Filtering见 recommenders/models/ncf/NewsRec见 recommenders/models/newsrec/Neural Recommendation with Long- and Short-term User RepresentationsLSTURNeural Recommendation with Attentive Multi-View LearningNAMLNeural Recommendation with Personalized AttentionNPANeural Recommendation with Multi-Head Self-AttentionNRMSRestricted Boltzmann MachinesRBM见 recommenders/models/rbm/Riemannian Low-rank Matrix CompletionRLRMC见 recommenders/models/rlrmc/Simple Algorithm for RecommendationSAR见 recommenders/models/sar/Self-Attentive Sequential RecommendationSASRec见 recommenders/models/sasrec/Sequential Recommendation Via Personalized TransformerSSEPTSurpriseSVD 等见 recommenders/models/surprise/Term Frequency - Inverse Document FrequencyTF-IDF见 recommenders/models/tfidf/Variational AutoencodersVAE见 recommenders/models/vae/Multinomial多项 VAEStandard标准 VAEVowpal WabbitVW见 recommenders/models/vowpal_wabbit/Wide and Deep见 recommenders/models/wide_deep/xLearnFactorization MachineFMField-Aware FMFFM每种算法在根目录 README.md 的算法表中都配有 Quick start 或 Deep dive 示例 Notebook位于 examples/例如 SAR 对应 examples/00_quick_start/sar_movielens.ipynbDeepRec 模型配置可参考 recommenders/models/deeprec/config/ 下的 YAML 文件。模型层的单元测试可参考 tests/unit/recommenders/models/ 目录。3.4 Tuning超参数调优Tuning 子模块提供超参数调优工具核心实现位于 recommenders/tuning/parameter_sweep.py并集成了 NNI 框架支持recommenders/tuning/nni/其中包含 NCF 与 SVD 的训练脚本封装ncf_training.py、svd_training.py。典型用法可见示例 examples/04_model_select_and_optimize/ 下的 Notebook如 NNI 调优 NCF / Surprise SVD、Spark ALS 调参等。3.5 Utils通用工具与常量Utils 子模块提供大多数算法通用的常量定义以及面向不同框架GPU、Spark、Jupyter notebook的管理辅助函数主要文件包括recommenders/utils/constants.py默认列名、默认 K 值等常量recommenders/utils/gpu_utils.pyGPU 环境检测与信息查询recommenders/utils/spark_utils.pySpark Session 初始化等recommenders/utils/notebook_utils.pyNotebook 环境判断与执行辅助recommenders/utils/plot.py结果可视化其他通用工具如 recommenders/utils/general_utils.py、recommenders/utils/python_utils.py、recommenders/utils/timer.py 等。这些工具在全部示例 Notebook 中被广泛调用是保证各算法代码风格统一、环境行为一致的基础设施。四、快速上手路径结合根目录 README.md 的 Getting Started 与 SETUP.md推荐的上手流程为使用uv创建 Python 3.11 虚拟环境并安装核心包uv pip install recommenders按需补充依赖组GPU 模型装recommenders[gpu]Spark 模型装recommenders[spark]安装 Jupyter kernelpython -m ipykernel install --user --name recommenders打开示例 Notebook如 examples/00_quick_start/sar_movielens.ipynb依次体验数据加载 → 切分 → 训练 → 评估 → 调优的完整流程。对于希望深入了解算法横向对比的读者根目录 README.md 的 Algorithm Comparison 一节提供了基于 MovieLens 100k 的基准评测 Notebookexamples/06_benchmarks/movielens.ipynb其中使用分层切分75/25、k10的排序指标覆盖 ALS、BiVAE、BPR、embdotbias、LightGCN、NCF、SAR、SVD 等多个算法是验证本包评估工具链的直观入口。五、总结recommenders包以少量通用函数 分层依赖 模块化子包的设计把推荐系统开发中最繁琐的工程环节数据获取与清洗、切分、指标计算、框架环境管理封装为可直接调用的 API同时内置大量算法实现与 Notebook 示例适合研究者、开发者与爱好者用于原型验证、实验对比与生产化落地前的探索。安装时务必按 SETUP.md 结合自身场景CPU / GPU / Spark / 开发选择正确的依赖组以保证运行环境与仓库测试环境一致。【免费下载链接】recommendersBest Practices on Recommendation Systems项目地址: https://gitcode.com/gh_mirrors/re/recommenders创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考