nextrec 0.4.4__tar.gz → 0.4.6__tar.gz

{nextrec-0.4.4 → nextrec-0.4.6}/.github/workflows/tests.yml

@@ -45,10 +45,6 @@ jobs:
       run: |
         python -c "import torch; print(f'PyTorch version: {torch.__version__}')"
         python -c "import nextrec; print('NextRec imported successfully')"
-
-    - name: Format codebase
-      run: |
-        python scripts/format_code.py
                 
     - name: Run tutorial multi-task models
       run: |

nextrec-0.4.6/PKG-INFO

@@ -0,0 +1,371 @@
+Metadata-Version: 2.4
+Name: nextrec
+Version: 0.4.6
+Summary: A comprehensive recommendation library with match, ranking, and multi-task learning models
+Project-URL: Homepage, https://github.com/zerolovesea/NextRec
+Project-URL: Repository, https://github.com/zerolovesea/NextRec
+Project-URL: Documentation, https://github.com/zerolovesea/NextRec/blob/main/README.md
+Project-URL: Issues, https://github.com/zerolovesea/NextRec/issues
+Author-email: zerolovesea <zyaztec@gmail.com>
+License-File: LICENSE
+Keywords: ctr,deep-learning,match,pytorch,ranking,recommendation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy<2.0,>=1.21; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: numpy<3.0,>=1.26; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: numpy>=1.23.0; sys_platform == 'win32'
+Requires-Dist: numpy>=1.24.0; sys_platform == 'darwin'
+Requires-Dist: pandas<2.0,>=1.5; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: pandas<2.3.0,>=2.1.0; sys_platform == 'win32'
+Requires-Dist: pandas>=2.0.0; sys_platform == 'darwin'
+Requires-Dist: pandas>=2.1.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: pyarrow<13.0.0,>=10.0.0; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: pyarrow<15.0.0,>=12.0.0; sys_platform == 'win32'
+Requires-Dist: pyarrow>=12.0.0; sys_platform == 'darwin'
+Requires-Dist: pyarrow>=16.0.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn<2.0,>=1.2; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'darwin'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'win32'
+Requires-Dist: scipy<1.12,>=1.8; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: scipy>=1.10.0; sys_platform == 'darwin'
+Requires-Dist: scipy>=1.10.0; sys_platform == 'win32'
+Requires-Dist: scipy>=1.11.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: transformers>=4.38.0
+Provides-Extra: dev
+Requires-Dist: jupyter>=1.0.0; extra == 'dev'
+Requires-Dist: matplotlib>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-html>=3.2.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: seaborn>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+<img align="center" src="assets/logo.png" width="40%">
+<p>
+
+<div align="center">
+
+![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
+![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
+![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
+![Version](https://img.shields.io/badge/Version-0.4.6-orange.svg)
+
+中文文档 | [English Version](README_en.md) | 
+
+**统一、高效、可扩展的推荐系统框架**
+
+</div>
+
+## 目录
+
+- [简介](#简介)
+- [NextRec进展](#NextRec进展)
+- [安装](#安装)
+- [架构](#架构)
+- [5分钟快速上手](#5分钟快速上手)
+- [命令行工具](#命令行工具)
+- [兼容平台](#兼容平台)
+- [支持模型](#支持模型)
+- [贡献指南](#贡献指南)
+
+## 简介
+
+NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程团队提供快速的建模、训练与评估流。框架内置丰富的模型库、数据处理工具和工程化训练组件。此外提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构，复现学术论文并进行训练和部署。
+
+## Why NextRec
+
+- **统一的特征工程与数据流水线**：NextRec框架提供了统一的特征定义、可持久化的数据处理、并对批处理进行了优化，符合工业大数据Spark/Hive场景下，基于离线特征的模型训练推理流程。
+- **多场景推荐能力**：覆盖排序（CTR/CVR）、召回、多任务学习、生成式召回等推荐/营销模型，持续跟进业界进展。
+- **友好的工程体验**：支持各种格式数据(`csv/parquet/pathlike`)的流式预处理/分布式训练/推理，GPU加速与可视化指标监控，方便业务算法工程师和推荐算法学习者快速复现实验。
+- **灵活的命令行工具**：支持通过命令行和配置文件，一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
+- **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
+
+## NextRec近期进展
+
+- **12/12/2025** 在v0.4.6中加入了生成式召回中常见的[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
+- **03/12/2025** NextRec获得100颗🌟，感谢大家的支持
+- **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
+- **23/11/2025** 在v0.2.2中对basemodel进行了逻辑上的大幅重构和流程统一，并且对listwise/pairwise/pointwise损失进行了统一
+- **11/11/2025** NextRec v0.1.0发布，我们提供了10余种Ranking模型，4种多任务模型和4种召回模型，以及统一的训练/日志/指标管理系统
+
+## 架构
+
+NextRec采用模块化工程设计，核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库等。
+
+![NextRec架构](assets/nextrec_diagram_zh.png)
+
+> 项目的架构借鉴了一些优秀的开源推荐算法库，例如DataWhaleChina社区的[torch-rechub](https://github.com/datawhalechina/torch-rechub)。torch-rechub在开发架构和模型实现上相对成熟，本人也参与了其中一小部分的维护，欢迎感兴趣的开发者前往了解。
+
+---
+
+## 安装
+
+开发者可以通过`pip install nextrec`快速安装NextRec的最新版本，环境要求为Python 3.10+。如果需要执行示例代码，则需要先拉取仓库：
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
+
+## 示例代码
+
+我们在`tutorials/` 目录提供了多个示例，覆盖排序、召回、多任务、数据处理等场景：
+
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) - movielen 100k数据集上的 DeepFM 模型训练示例
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) - 电商数据集上的DIN 深度兴趣网络训练示例
+- [example_multitask.py](/tutorials/example_multitask.py) - 电商数据集上的ESMM多任务学习训练示例
+- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) - 基于movielen 100k数据集训练的 DSSM 召回模型示例
+
+- [example_distributed_training.py](/tutorials/distributed/example_distributed_training.py) - 使用NextRec进行单机多卡训练的代码示例
+
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) - 快速校验所有排序模型的可用性
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) - 快速校验所有多任务模型的可用性
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) - 快速校验所有召回模型的可用性
+
+如果想了解更多NextRec框架的细节，我们还提供了Jupyter notebook来帮助你了解：
+
+- [如何上手NextRec框架](/tutorials/notebooks/zh/Hands%20on%20nextrec.ipynb)
+- [如何使用数据处理器进行数据预处理](/tutorials/notebooks/zh/Hands%20on%20dataprocessor.ipynb)
+- [使用RQ-VAE构建语义ID](/tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)
+
+## 5分钟快速上手
+
+我们提供了详细的上手指南和配套数据集，帮助您熟悉NextRec框架的不同功能。我们在`datasets/`路径下提供了一个来自电商场景的测试数据集，数据示例如下：
+
+| user_id | item_id | dense_0     | dense_1     | dense_2     | dense_3    | dense_4     | dense_5     | dense_6     | dense_7     | sparse_0 | sparse_1 | sparse_2 | sparse_3 | sparse_4 | sparse_5 | sparse_6 | sparse_7 | sparse_8 | sparse_9 | sequence_0                                               | sequence_1                                                | label |
+|--------|---------|-------------|-------------|-------------|------------|-------------|-------------|-------------|-------------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|-----------------------------------------------------------|-----------------------------------------------------------|-------|
+| 1      | 7817    | 0.14704075  | 0.31020382  | 0.77780896  | 0.944897   | 0.62315375  | 0.57124174  | 0.77009535  | 0.3211029   | 315      | 260      | 379      | 146      | 168      | 161      | 138      | 88       | 5        | 312      | [170,175,97,338,105,353,272,546,175,545,463,128,0,0,0]   | [368,414,820,405,548,63,327,0,0,0,0,0,0,0,0]              | 0     |
+| 1      | 3579    | 0.77811223  | 0.80359334  | 0.5185201   | 0.91091245 | 0.043562356 | 0.82142705  | 0.8803686   | 0.33748195 | 149      | 229      | 442      | 6        | 167      | 252      | 25       | 402      | 7        | 168      | [179,48,61,551,284,165,344,151,0,0,0,0,0,0,0]            | [814,0,0,0,0,0,0,0,0,0,0,0,0,0,0]                          | 1     |
+
+接下来我们将用一个简短的示例，展示如何使用NextRec训练一个DIN(Deep Interest Network)模型。您也可以直接执行`python tutorials/example_ranking_din.py`来执行训练推理代码。
+
+开始训练以后，你可以在`nextrec_logs/din_tutorial`路径下查看详细的训练日志。
+
+```python
+import pandas as pd
+from nextrec.models.ranking.din import DIN
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+
+df = pd.read_csv('dataset/ranking_task.csv')
+
+for col in df.columns and 'sequence' in col: # csv默认将列表读取成文本，我们需要将其转化为对象
+    df[col] = df[col].apply(lambda x: eval(x) if isinstance(x, str) else x)
+
+# 我们需要将不同特征进行定义
+dense_features = [DenseFeature(name=f'dense_{i}', input_dim=1) for i in range(8)]
+
+sparse_features = [SparseFeature(name='user_id', embedding_name='user_emb', vocab_size=int(df['user_id'].max() + 1), embedding_dim=32), SparseFeature(name='item_id', embedding_name='item_emb', vocab_size=int(df['item_id'].max() + 1), embedding_dim=32),]
+
+sparse_features.extend([SparseFeature(name=f'sparse_{i}', embedding_name=f'sparse_{i}_emb', vocab_size=int(df[f'sparse_{i}'].max() + 1), embedding_dim=32) for i in range(10)])
+
+sequence_features = [
+    SequenceFeature(name='sequence_0', vocab_size=int(df['sequence_0'].apply(lambda x: max(x)).max() + 1), embedding_dim=32, padding_idx=0, embedding_name='item_emb'),
+    SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
+
+mlp_params = {
+    "dims": [256, 128, 64],
+    "activation": "relu",
+    "dropout": 0.3,
+}
+
+model = DIN(
+    dense_features=dense_features,
+    sparse_features=sparse_features,
+    sequence_features=sequence_features,
+    mlp_params=mlp_params,
+    attention_hidden_units=[80, 40],
+    attention_activation='sigmoid',
+    attention_use_softmax=True,
+    target=['label'],                                     # 目标变量
+    device='mps',                                         
+    embedding_l1_reg=1e-6,
+    embedding_l2_reg=1e-5,
+    dense_l1_reg=1e-5,
+    dense_l2_reg=1e-4,
+    session_id="din_tutorial",                            # 实验id，用于存放训练日志
+)
+
+# 编译模型，设置优化器和损失函数
+model.compile(
+            optimizer = "adam",
+            optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
+            loss = "focal",
+            loss_params={"gamma": 2.0, "alpha": 0.25},
+        )
+
+model.fit(
+    train_data=df,
+    metrics=['auc', 'gauc', 'logloss'],  # 添加需要查看的指标
+    epochs=3,
+    batch_size=512,
+    shuffle=True,
+    user_id_column='user_id'             # 用于计算GAUC的id列 
+)
+
+# 训练完成后进行指标评估
+metrics = model.evaluate(
+    df,
+    metrics=['auc', 'gauc', 'logloss'],
+    batch_size=512,
+    user_id_column='user_id'
+)
+```
+
+## 命令行工具
+
+NextRec 提供了强大的命令行界面，支持通过 YAML 配置文件进行模型训练和预测。详细的 CLI 文档请参见：
+
+- [NextRec CLI 使用指南](/nextrec_cli_preset/NextRec-CLI_zh.md) - 完整的 CLI 使用文档
+- [NextRec CLI 配置文件示例](/nextrec_cli_preset/) - CLI 使用配置文件示例
+
+```bash
+# 训练模型
+nextrec --mode=train --train_config=path/to/train_config.yaml
+
+# 运行预测
+nextrec --mode=predict --predict_config=path/to/predict_config.yaml
+```
+
+> 截止当前版本0.4.6，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+
+## 兼容平台
+
+当前最新版本为0.4.6，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+
+| 平台 | 配置 | 
+|------|------|
+| MacOS latest| MacBook Pro M4 Pro 24G内存 |
+| Ubuntu latest| AutoDL 4070D 双卡 |
+| Ubuntu 24.04| NVIDIA TITAN V 5卡 |
+| CentOS 7 | Intel Xeon 5138Y 96核 377G内存 | 
+
+## 支持模型
+
+### 排序模型
+
+| 模型 | 论文 | 年份 | 状态 |
+|------|------|------|------|
+| [FM](nextrec/models/ranking/fm.py) | Factorization Machines | ICDM 2010 | 已支持 |
+| [AFM](nextrec/models/ranking/afm.py) | Attentional Factorization Machines: Learning the Weight of Feature Interactions via Attention Networks | IJCAI 2017 | 已支持 |
+| [DeepFM](nextrec/models/ranking/deepfm.py) | DeepFM: A Factorization-Machine based Neural Network for CTR Prediction | IJCAI 2017 | 已支持 |
+| [Wide&Deep](nextrec/models/ranking/widedeep.py) | Wide & Deep Learning for Recommender Systems | DLRS 2016 | 已支持 |
+| [xDeepFM](nextrec/models/ranking/xdeepfm.py) | xDeepFM: Combining Explicit and Implicit Feature Interactions | KDD 2018 | 已支持 |
+| [FiBiNET](nextrec/models/ranking/fibinet.py) | FiBiNET: Combining Feature Importance and Bilinear Feature Interaction for CTR Prediction | RecSys 2019 | 已支持 |
+| [PNN](nextrec/models/ranking/pnn.py) | Product-based Neural Networks for User Response Prediction | ICDM 2016 | 已支持 |
+| [AutoInt](nextrec/models/ranking/autoint.py) | AutoInt: Automatic Feature Interaction Learning | CIKM 2019 | 已支持 |
+| [DCN](nextrec/models/ranking/dcn.py) | Deep & Cross Network for Ad Click Predictions | ADKDD 2017 | 已支持 |
+| [DCN v2](nextrec/models/ranking/dcn_v2.py) | DCN V2: Improved Deep & Cross Network and Practical Lessons for Web-scale Learning to Rank Systems | KDD 2021 | 开发中 |
+| [DIN](nextrec/models/ranking/din.py) | Deep Interest Network for Click-Through Rate Prediction | KDD 2018 | 已支持 |
+| [DIEN](nextrec/models/ranking/dien.py) | Deep Interest Evolution Network for Click-Through Rate Prediction | AAAI 2019 | 已支持 |
+| [MaskNet](nextrec/models/ranking/masknet.py) | MaskNet: Introducing Feature-wise Gating Blocks for High-dimensional Sparse Recommendation Data | 2020 | 已支持 |
+
+### 召回模型
+
+| 模型 | 论文 | 年份 | 状态 |
+|------|------|------|------|
+| [DSSM](nextrec/models/match/dssm.py) | Learning Deep Structured Semantic Models | CIKM 2013 | 已支持 |
+| [DSSM v2](nextrec/models/match/dssm_v2.py) | DSSM with pairwise BPR-style optimization | - | 已支持 |
+| [YouTube DNN](nextrec/models/match/youtube_dnn.py) | Deep Neural Networks for YouTube Recommendations | RecSys 2016 | 已支持 |
+| [MIND](nextrec/models/match/mind.py) | Multi-Interest Network with Dynamic Routing | CIKM 2019 | 已支持 |
+| [SDM](nextrec/models/match/sdm.py) | Sequential Deep Matching Model | - | 已支持 |
+
+### 多任务模型
+
+| 模型 | 论文 | 年份 | 状态 |
+|------|------|------|------|
+| [MMOE](nextrec/models/multi_task/mmoe.py) | Modeling Task Relationships in Multi-task Learning | KDD 2018 | 已支持 |
+| [PLE](nextrec/models/multi_task/ple.py) | Progressive Layered Extraction | RecSys 2020 | 已支持 |
+| [ESMM](nextrec/models/multi_task/esmm.py) | Entire Space Multi-Task Model | SIGIR 2018 | 已支持 |
+| [ShareBottom](nextrec/models/multi_task/share_bottom.py) | Multitask Learning | - | 已支持 |
+| [POSO](nextrec/models/multi_task/poso.py) | POSO: Personalized Cold-start Modules for Large-scale Recommender Systems | 2021 | 已支持 |
+
+### 生成式模型
+
+| 模型 | 论文 | 年份 | 状态 |
+|------|------|------|------|
+| [TIGER](nextrec/models/generative/tiger.py) | Recommender Systems with Generative Retrieval | NeurIPS 2023 | 开发中 |
+| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | 已支持 |
+
+---
+
+## 贡献指南
+
+我们欢迎任何形式的贡献！
+
+### 如何贡献
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 创建 Pull Request
+
+> 在提交 PR 之前，请运行 `python test/run_tests.py` 和 `python scripts/format_code.py` 确保所有测试通过并统一代码风格。
+
+### 代码规范
+
+- 遵循 PEP 8 Python 代码风格
+- 为新增功能补充单元测试
+- 同步更新相关文档
+
+### 报告错误
+
+在 [Issues](https://github.com/zerolovesea/NextRec/issues) 页面提交问题时，请包含：
+
+- 错误描述
+- 重现步骤
+- 期望行为
+- 实际行为
+- 环境信息（Python 版本、PyTorch 版本等）
+
+---
+
+## 许可证
+
+本项目采用 [Apache 2.0 许可证](./LICENSE)。
+
+---
+
+## 联系方式
+
+- **GitHub Issues**: [提交问题](https://github.com/zerolovesea/NextRec/issues)
+- **邮箱**: zyaztec@gmail.com
+
+---
+
+## 致谢
+
+NextRec 的开发受到以下优秀项目的启发：
+
+- [torch-rechub](https://github.com/datawhalechina/torch-rechub) - 灵活且易于扩展的推荐系统框架
+- [FuxiCTR](https://github.com/reczoo/FuxiCTR) - 可配置、可调优、可复现的 CTR 预测库
+- [RecBole](https://github.com/RUCAIBox/RecBole) - 统一、全面、高效的推荐库
+
+感谢开源社区的所有贡献者！
+
+---
+
+<div align="center">
+
+**[返回顶部](#nextrec)**
+
+</div>

nextrec-0.4.4/README_zh.md → nextrec-0.4.6/README.md

@@ -7,9 +7,9 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.4-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.6-orange.svg)
 
-[English Version](README.md) | 中文文档
+中文文档 | [English Version](README_en.md) | 
 
 **统一、高效、可扩展的推荐系统框架**
 
@@ -18,6 +18,7 @@
 ## 目录
 
 - [简介](#简介)
+- [NextRec进展](#NextRec进展)
 - [安装](#安装)
 - [架构](#架构)
 - [5分钟快速上手](#5分钟快速上手)
@@ -28,7 +29,7 @@
 
 ## 简介
 
-NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究与工程团队提供快速的建模、训练与评估流程。框架内置丰富的模型实现、数据处理工具和工程化训练组件，覆盖多种推荐场景。此外提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构，复现学术论文并进行训练和部署。
+NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程团队提供快速的建模、训练与评估流。框架内置丰富的模型库、数据处理工具和工程化训练组件。此外提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构，复现学术论文并进行训练和部署。
 
 ## Why NextRec
 
@@ -38,6 +39,15 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究与工
 - **灵活的命令行工具**：支持通过命令行和配置文件，一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
 - **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
+## NextRec近期进展
+
+- **12/12/2025** 在v0.4.6中加入了生成式召回中常见的[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
+- **03/12/2025** NextRec获得100颗🌟，感谢大家的支持
+- **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
+- **23/11/2025** 在v0.2.2中对basemodel进行了逻辑上的大幅重构和流程统一，并且对listwise/pairwise/pointwise损失进行了统一
+- **11/11/2025** NextRec v0.1.0发布，我们提供了10余种Ranking模型，4种多任务模型和4种召回模型，以及统一的训练/日志/指标管理系统
+
 ## 架构
 
 NextRec采用模块化工程设计，核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库等。
@@ -67,6 +77,8 @@ pip install nextrec # or pip install -e .
 - [example_multitask.py](/tutorials/example_multitask.py) - 电商数据集上的ESMM多任务学习训练示例
 - [movielen_match_dssm.py](/tutorials/example_match_dssm.py) - 基于movielen 100k数据集训练的 DSSM 召回模型示例
 
+- [example_distributed_training.py](/tutorials/distributed/example_distributed_training.py) - 使用NextRec进行单机多卡训练的代码示例
+
 - [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) - 快速校验所有排序模型的可用性
 - [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) - 快速校验所有多任务模型的可用性
 - [run_all_match_models.py](/tutorials/run_all_match_models.py) - 快速校验所有召回模型的可用性
@@ -75,6 +87,7 @@ pip install nextrec # or pip install -e .
 
 - [如何上手NextRec框架](/tutorials/notebooks/zh/Hands%20on%20nextrec.ipynb)
 - [如何使用数据处理器进行数据预处理](/tutorials/notebooks/zh/Hands%20on%20dataprocessor.ipynb)
+- [使用RQ-VAE构建语义ID](/tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)
 
 ## 5分钟快速上手
 
@@ -174,16 +187,17 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.4，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.6，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.4，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.6，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|
 | MacOS latest| MacBook Pro M4 Pro 24G内存 |
 | Ubuntu latest| AutoDL 4070D 双卡 |
+| Ubuntu 24.04| NVIDIA TITAN V 5卡 |
 | CentOS 7 | Intel Xeon 5138Y 96核 377G内存 | 
 
 ## 支持模型

nextrec-0.4.4/README.md → nextrec-0.4.6/README_en.md

@@ -7,9 +7,9 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.4-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.6-orange.svg)
 
-English | [中文文档](README_zh.md)
+English | [中文文档](README.md)
 
 **A Unified, Efficient, and Scalable Recommendation System Framework**
 
@@ -18,8 +18,10 @@ English | [中文文档](README_zh.md)
 ## Table of Contents
 
 - [Introduction](#introduction)
+- [NextRec Progress](#nextrec-progress)
 - [Installation](#installation)
 - [Architecture](#architecture)
+- [Tutorials](#tutorials)
 - [5-Minute Quick Start](#5-minute-quick-start)
 - [CLI Usage](#cli-usage)
 - [Platform Compatibility](#platform-compatibility)
@@ -28,15 +30,25 @@ English | [中文文档](README_zh.md)
 
 ## Introduction
 
-NextRec is a modern recommendation framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. Design with rich model implementations, data-processing utilities, and engineering-ready training components. NextRec focuses on large-scale industrial recommendation scenarios on Spark clusters, training on massive offline features(`parquet/csv`).
+NextRec is a modern recommendation framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. Designed with rich model implementations, data-processing utilities, engineering-ready training components, and easy-to-use CLI/tools/tutorials, NextRec helps research/engineering teams quickly build, train, reproduce, and deploy recommendation models.
 
 ## Why NextRec
 
 - **Unified feature engineering & data pipeline**: NextRec provide unified Dense/Sparse/Sequence feature definitions, DataProcessor, and batch-optimized RecDataLoader, matching offline feature training/inference in industrial big-data settings.
 - **Multi-scenario coverage**: Ranking (CTR/CVR), retrieval, multi-task learning, and more marketing/rec models, with a continuously expanding model zoo.
 - **Developer-friendly experience**: `Stream processing/distributed training/inference` for `csv/parquet/pathlike` data, plus GPU/MPS acceleration and visualization support.
+- **Flexible CLI tooling**: Start training and inference via command line and config files for rapid experiment iteration and agile deployment.
 - **Efficient training & evaluation**: Standardized engine with optimizers, LR schedulers, early stopping, checkpoints, and detailed logging out of the box.
 
+## NextRec Progress
+
+- **12/12/2025** Added [RQ-VAE](/nextrec/models/generative/rqvae.py), a common module for generative retrieval. Paired [dataset](/dataset/ecommerce_task.csv) and [notebook code](tutorials/notebooks/en/Build%20semantic%20ID%20with%20RQ-VAE.ipynb) are available.
+- **07/12/2025** Released the NextRec CLI tool to run training/inference from configs. See the [guide](/nextrec_cli_preset/NextRec-CLI.md) and [reference code](/nextrec_cli_preset).
+- **03/12/2025** NextRec reached 100 ⭐—thanks for the support!
+- **06/12/2025** Added single-machine multi-GPU DDP training in v0.4.1 with supporting [code](tutorials/distributed).
+- **23/11/2025** Major logical refactor of basemodel and unification of listwise/pairwise/pointwise losses in v0.2.2.
+- **11/11/2025** NextRec v0.1.0 released with 10+ ranking models, 4 multi-task models, 4 retrieval models, and a unified training/logging/metrics system.
+
 ## Architecture
 
 NextRec adopts a modular design, enabling full-pipeline reusability and scalability across data processing → model construction → training & evaluation → inference & deployment. Its core components include: a Feature-Spec-driven Embedding architecture, the BaseModel abstraction, a set of independent reusable Layers, a unified DataLoader for both training and inference, and a ready-to-use Model Zoo.
@@ -66,6 +78,8 @@ See `tutorials/` for examples covering ranking, retrieval, multi-task learning,
 - [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training on e-commerce dataset
 - [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model training on MovieLens 100k dataset
 
+- [example_distributed_training.py](/tutorials/distributed/example_distributed_training.py) — Single-machine multi-GPU training with NextRec
+
 - [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly validate availability of all ranking models
 - [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly validate availability of all multi-task models
 - [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly validate availability of all retrieval models
@@ -74,6 +88,7 @@ To dive deeper into NextRec framework details, Jupyter notebooks are available:
 
 - [Hands on the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
 - [Using the data processor for preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
+- [Build semantic ID with RQ-VAE](/tutorials/notebooks/en/Build%20semantic%20ID%20with%20RQ-VAE.ipynb)
 
 ## 5-Minute Quick Start
 
@@ -174,16 +189,17 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> As of version 0.4.4, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.6, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.4. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
+The current version is 0.4.6. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
 
 | Platform | Configuration | 
 |----------|---------------|
 | MacOS latest | MacBook Pro M4 Pro 24GB RAM |
 | Ubuntu latest | AutoDL 4070D Dual GPU |
+| Ubuntu 24.04 | NVIDIA TITAN V x5 |
 | CentOS 7 | Intel Xeon 5138Y 96 cores 377GB RAM |
 
 ---