nextrec 0.4.3__tar.gz → 0.4.5__tar.gz

{nextrec-0.4.3 → nextrec-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.3
+Version: 0.4.5
 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
@@ -63,7 +63,7 @@ Description-Content-Type: text/markdown
 ![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.3-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.5-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -84,60 +84,65 @@ English | [中文文档](README_zh.md)
 
 ## Introduction
 
-NextRec is a modern recommendation system framework built on PyTorch, providing researchers and engineering teams with a fast modeling, training, and evaluation experience. The framework adopts a modular design with rich built-in model implementations, data processing tools, and engineering-ready training components, covering various recommendation scenarios. NextRec provides easy-to-use interfaces, command-line tools, and tutorials, enabling recommendation algorithm learners to quickly understand model architectures and train and infer models at the fastest speed.
+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`).
 
 ## Why NextRec
 
-- **Unified feature engineering & data pipeline**: NextRec provides Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching the model training and inference process based on offline `parquet/csv` features in industrial big-data Spark/Hive scenarios.
-- **Multi-scenario recommendation capabilities**: Covers ranking (CTR/CVR), retrieval, multi-task learning and other recommendation/marketing models, with a continuously expanding model zoo.
-- **Developer-friendly experience**: Supports stream preprocessing/distributed training/inference for various data formats (`csv/parquet/pathlike`), GPU acceleration and visual metric monitoring, facilitating experiments for business algorithm engineers and recommendation algorithm learners.
-- **Flexible command-line tool**: Through configuring training and inference config files, start training and inference processes with one command `nextrec --mode=train --train_config=train_config.yaml`, facilitating rapid experiment iteration and agile deployment.
-- **Efficient training & evaluation**: NextRec's standardized training engine comes with various optimizers, learning rate schedulers, early stopping, model checkpoints, and detailed log management built-in, ready to use out of the box.
+- **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.
+- **Efficient training & evaluation**: Standardized engine with optimizers, LR schedulers, early stopping, checkpoints, and detailed logging out of the box.
 
 ## Architecture
 
-NextRec adopts a modular and low-coupling engineering 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.
+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.
 
 ![NextRec Architecture](assets/nextrec_diagram_en.png)
 
-> The project borrows ideas from excellent open-source rec libraries. Early layers referenced [torch-rechub](https://github.com/datawhalechina/torch-rechub) but have been replaced with in-house implementations. torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
+> The project borrows ideas from excellent open-source rec libraries, for example: [torch-rechub](https://github.com/datawhalechina/torch-rechub). torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
 
 ---
 
 ## Installation
 
-You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
+You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required. If you want to run some tutorial codes, pull this project first: 
 
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
 
 ## Tutorials
 
-We provide multiple examples in the `tutorials/` directory, covering ranking, retrieval, multi-task, and data processing scenarios:
+See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
+
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN Deep Interest Network training on e-commerce dataset
+- [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
 
-- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM model training example on MovieLens 100k dataset
-- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN deep interest network training example on e-commerce dataset
-- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training example on e-commerce dataset
-- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model example trained on MovieLens 100k dataset
-- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly verify the availability of all ranking models
-- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly verify the availability of all multi-task models
-- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly verify the availability of all retrieval models
+- [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
 
-If you want to learn more details about the NextRec framework, we also provide Jupyter notebooks to help you understand:
+To dive deeper into NextRec framework details, Jupyter notebooks are available:
 
-- [How to get started with the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
-- [How to use the data processor for data preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
+- [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)
 
 ## 5-Minute Quick Start
 
-We provide a detailed quick start guide and paired datasets to help you become familiar with different features of the NextRec framework. We provide a test dataset from an e-commerce scenario in the `datasets/` path, with data examples as follows:
+We provide a detailed quick-start guide and paired datasets to help you get familiar with different features of NextRec framework. In `datasets/` you'll find an e-commerce scenario test dataset like this:
 
 | 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     |
 
-Next, we'll use a short example to show you how to train a DIN model using NextRec. DIN (Deep Interest Network) is from Alibaba's 2018 KDD Best Paper, used for CTR prediction scenarios. You can also directly execute `python tutorials/example_ranking_din.py` to run the training and inference code.
+Below is a short example showing how to train a DIN (Deep Interest Network) model. You can also run `python tutorials/example_ranking_din.py` directly to execute the training and inference code.
 
-After starting training, you can view detailed training logs in the `nextrec_logs/din_tutorial` path.
+After training starts, you can find detailed training logs at `nextrec_logs/din_tutorial`.
 
 ```python
 import pandas as pd
@@ -215,6 +220,7 @@ metrics = model.evaluate(
 NextRec provides a powerful command-line interface for model training and prediction using YAML configuration files. For detailed CLI documentation, see:
 
 - [NextRec CLI User Guide](/nextrec_cli_preset/NextRec-CLI.md) - Complete guide for using the CLI
+- [NextRec CLI Configuration Examples](/nextrec_cli_preset/) - CLI configuration file examples
 
 ```bash
 # Train a model
@@ -224,11 +230,11 @@ 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.3, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.5, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.3. 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.5. 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 | 
 |----------|---------------|
@@ -299,7 +305,7 @@ We welcome contributions of any form!
 4. Push your branch (`git push origin feature/AmazingFeature`)  
 5. Open a Pull Request  
 
-> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is unified.
+> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is consistent.
 
 ### Code Style
 

{nextrec-0.4.3 → nextrec-0.4.5}/README.md

@@ -7,7 +7,7 @@
 ![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.3-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.5-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -28,60 +28,65 @@ English | [中文文档](README_zh.md)
 
 ## Introduction
 
-NextRec is a modern recommendation system framework built on PyTorch, providing researchers and engineering teams with a fast modeling, training, and evaluation experience. The framework adopts a modular design with rich built-in model implementations, data processing tools, and engineering-ready training components, covering various recommendation scenarios. NextRec provides easy-to-use interfaces, command-line tools, and tutorials, enabling recommendation algorithm learners to quickly understand model architectures and train and infer models at the fastest speed.
+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`).
 
 ## Why NextRec
 
-- **Unified feature engineering & data pipeline**: NextRec provides Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching the model training and inference process based on offline `parquet/csv` features in industrial big-data Spark/Hive scenarios.
-- **Multi-scenario recommendation capabilities**: Covers ranking (CTR/CVR), retrieval, multi-task learning and other recommendation/marketing models, with a continuously expanding model zoo.
-- **Developer-friendly experience**: Supports stream preprocessing/distributed training/inference for various data formats (`csv/parquet/pathlike`), GPU acceleration and visual metric monitoring, facilitating experiments for business algorithm engineers and recommendation algorithm learners.
-- **Flexible command-line tool**: Through configuring training and inference config files, start training and inference processes with one command `nextrec --mode=train --train_config=train_config.yaml`, facilitating rapid experiment iteration and agile deployment.
-- **Efficient training & evaluation**: NextRec's standardized training engine comes with various optimizers, learning rate schedulers, early stopping, model checkpoints, and detailed log management built-in, ready to use out of the box.
+- **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.
+- **Efficient training & evaluation**: Standardized engine with optimizers, LR schedulers, early stopping, checkpoints, and detailed logging out of the box.
 
 ## Architecture
 
-NextRec adopts a modular and low-coupling engineering 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.
+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.
 
 ![NextRec Architecture](assets/nextrec_diagram_en.png)
 
-> The project borrows ideas from excellent open-source rec libraries. Early layers referenced [torch-rechub](https://github.com/datawhalechina/torch-rechub) but have been replaced with in-house implementations. torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
+> The project borrows ideas from excellent open-source rec libraries, for example: [torch-rechub](https://github.com/datawhalechina/torch-rechub). torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
 
 ---
 
 ## Installation
 
-You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
+You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required. If you want to run some tutorial codes, pull this project first: 
 
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
 
 ## Tutorials
 
-We provide multiple examples in the `tutorials/` directory, covering ranking, retrieval, multi-task, and data processing scenarios:
+See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
+
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN Deep Interest Network training on e-commerce dataset
+- [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
 
-- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM model training example on MovieLens 100k dataset
-- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN deep interest network training example on e-commerce dataset
-- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training example on e-commerce dataset
-- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model example trained on MovieLens 100k dataset
-- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly verify the availability of all ranking models
-- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly verify the availability of all multi-task models
-- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly verify the availability of all retrieval models
+- [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
 
-If you want to learn more details about the NextRec framework, we also provide Jupyter notebooks to help you understand:
+To dive deeper into NextRec framework details, Jupyter notebooks are available:
 
-- [How to get started with the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
-- [How to use the data processor for data preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
+- [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)
 
 ## 5-Minute Quick Start
 
-We provide a detailed quick start guide and paired datasets to help you become familiar with different features of the NextRec framework. We provide a test dataset from an e-commerce scenario in the `datasets/` path, with data examples as follows:
+We provide a detailed quick-start guide and paired datasets to help you get familiar with different features of NextRec framework. In `datasets/` you'll find an e-commerce scenario test dataset like this:
 
 | 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     |
 
-Next, we'll use a short example to show you how to train a DIN model using NextRec. DIN (Deep Interest Network) is from Alibaba's 2018 KDD Best Paper, used for CTR prediction scenarios. You can also directly execute `python tutorials/example_ranking_din.py` to run the training and inference code.
+Below is a short example showing how to train a DIN (Deep Interest Network) model. You can also run `python tutorials/example_ranking_din.py` directly to execute the training and inference code.
 
-After starting training, you can view detailed training logs in the `nextrec_logs/din_tutorial` path.
+After training starts, you can find detailed training logs at `nextrec_logs/din_tutorial`.
 
 ```python
 import pandas as pd
@@ -159,6 +164,7 @@ metrics = model.evaluate(
 NextRec provides a powerful command-line interface for model training and prediction using YAML configuration files. For detailed CLI documentation, see:
 
 - [NextRec CLI User Guide](/nextrec_cli_preset/NextRec-CLI.md) - Complete guide for using the CLI
+- [NextRec CLI Configuration Examples](/nextrec_cli_preset/) - CLI configuration file examples
 
 ```bash
 # Train a model
@@ -168,11 +174,11 @@ 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.3, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.5, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.3. 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.5. 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 | 
 |----------|---------------|
@@ -243,7 +249,7 @@ We welcome contributions of any form!
 4. Push your branch (`git push origin feature/AmazingFeature`)  
 5. Open a Pull Request  
 
-> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is unified.
+> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is consistent.
 
 ### Code Style
 

{nextrec-0.4.3 → nextrec-0.4.5}/README_zh.md

@@ -7,7 +7,7 @@
 ![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.3-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.5-orange.svg)
 
 [English Version](README.md) | 中文文档
 
@@ -28,29 +28,35 @@
 
 ## 简介
 
-NextRec是一个基于 PyTorch 构建的现代推荐系统框架，为研究人员与工程团队提供快速的建模、训练与评估体验。框架采用模块化设计，内置丰富的模型实现、数据处理工具和工程化训练组件，覆盖多种推荐场景。NextRec提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构并训练和推理模型。
+NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究与工程团队提供快速的建模、训练与评估流程。框架内置丰富的模型实现、数据处理工具和工程化训练组件，覆盖多种推荐场景。此外提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构，复现学术论文并进行训练和部署。
 
 ## Why NextRec
 
-- **统一的特征工程与数据流水线**：NextRec框架提供了 Dense/Sparse/Sequence 特征定义、可持久化的 DataProcessor、批处理优化的 RecDataLoader，符合工业大数据Spark/Hive场景下，基于离线`parquet/csv`特征的模型训练推理流程。
-- **多场景推荐能力**：同时覆盖排序（CTR/CVR）、召回、多任务学习等推荐/营销模型，并且持续扩充模型库中。
-- **友好的工程体验**：支持各种格式数据(`csv/parquet/pathlike`)的流式预处理/分布式训练/推理，GPU加速与可视化指标监控，方便业务算法工程师和推荐算法学习者进行实验。
-- **灵活的命令行工具**：通过配置训练配置文件和推理配置文件，通过`nextrec --mode=train --train_config=train_config.yaml` 一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
-- **高效训练与评估**：NextRec框架的标准化训练引擎内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
+- **统一的特征工程与数据流水线**：NextRec框架提供了统一的特征定义、可持久化的数据处理、并对批处理进行了优化，符合工业大数据Spark/Hive场景下，基于离线特征的模型训练推理流程。
+- **多场景推荐能力**：覆盖排序（CTR/CVR）、召回、多任务学习、生成式召回等推荐/营销模型，持续跟进业界进展。
+- **友好的工程体验**：支持各种格式数据(`csv/parquet/pathlike`)的流式预处理/分布式训练/推理，GPU加速与可视化指标监控，方便业务算法工程师和推荐算法学习者快速复现实验。
+- **灵活的命令行工具**：支持通过命令行和配置文件，一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
+- **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
 ## 架构
 
-NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据处理 → 模型构建 → 训练评估 → 推理部署 全链路都具备复用性与可扩展性。其中的核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库。
+NextRec采用模块化工程设计，核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库等。
 
 ![NextRec架构](assets/nextrec_diagram_zh.png)
 
-> 项目的架构借鉴了一些优秀的开源推荐算法库，其中最初版的layer层借鉴了DataWhaleChina社区的[torch-rechub](https://github.com/datawhalechina/torch-rechub)，现已替换为了自有实现。torch-rechub在开发架构和模型实现上相对成熟，本人也参与了其中一小部分的维护，欢迎感兴趣的开发者前往了解。
+> 项目的架构借鉴了一些优秀的开源推荐算法库，例如DataWhaleChina社区的[torch-rechub](https://github.com/datawhalechina/torch-rechub)。torch-rechub在开发架构和模型实现上相对成熟，本人也参与了其中一小部分的维护，欢迎感兴趣的开发者前往了解。
 
 ---
 
 ## 安装
 
-你可以通过`pip install nextrec`快速安装NextRec的最新版本，环境要求为Python 3.10+。
+开发者可以通过`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 .
+```
 
 ## 示例代码
 
@@ -60,6 +66,7 @@ NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据
 - [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 召回模型示例
+
 - [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) - 快速校验所有召回模型的可用性
@@ -78,7 +85,7 @@ NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据
 | 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模型。DIN(Deep Interest Network)来自于阿里妈妈2018年KDD最佳论文模型，用于CTR预估场景。你也可以直接执行`python tutorials/example_ranking_din.py`来执行训练推理代码。
+接下来我们将用一个简短的示例，展示如何使用NextRec训练一个DIN(Deep Interest Network)模型。您也可以直接执行`python tutorials/example_ranking_din.py`来执行训练推理代码。
 
 开始训练以后，你可以在`nextrec_logs/din_tutorial`路径下查看详细的训练日志。
 
@@ -157,6 +164,7 @@ metrics = model.evaluate(
 NextRec 提供了强大的命令行界面，支持通过 YAML 配置文件进行模型训练和预测。详细的 CLI 文档请参见：
 
 - [NextRec CLI 使用指南](/nextrec_cli_preset/NextRec-CLI_zh.md) - 完整的 CLI 使用文档
+- [NextRec CLI 配置文件示例](/nextrec_cli_preset/) - CLI 使用配置文件示例
 
 ```bash
 # 训练模型
@@ -166,11 +174,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.3，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.5，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.3，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.5，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.3 → nextrec-0.4.5}/docs/rtd/conf.py

@@ -11,7 +11,7 @@ sys.path.insert(0, str(PROJECT_ROOT / "nextrec"))
 project = "NextRec"
 copyright = "2025, Yang Zhou"
 author = "Yang Zhou"
-release = "0.4.3"
+release = "0.4.5"
 
 extensions = [
     "myst_parser",

nextrec-0.4.5/nextrec/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.5"

{nextrec-0.4.3 → nextrec-0.4.5}/nextrec/models/ranking/xdeepfm.py

@@ -1,12 +1,54 @@
 """
 Date: create on 09/11/2025
 Author:
-    Yang Zhou,zyaztec@gmail.com
+Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Lian J, Zhou X, Zhang F, et al. xdeepfm: Combining explicit and implicit feature interactions
-        for recommender systems[C]//Proceedings of the 24th ACM SIGKDD international conference on
-        knowledge discovery & data mining. 2018: 1754-1763.
-        (https://arxiv.org/abs/1803.05170)
+[1] Lian J, Zhou X, Zhang F, et al. xdeepfm: Combining explicit and implicit feature interactions
+for recommender systems[C]//Proceedings of the 24th ACM SIGKDD international conference on
+knowledge discovery & data mining. 2018: 1754-1763.
+(https://arxiv.org/abs/1803.05170)
+
+xDeepFM is a CTR prediction model that unifies explicit and implicit
+feature interaction learning. It extends DeepFM by adding the
+Compressed Interaction Network (CIN) to explicitly model high-order
+interactions at the vector-wise level, while an MLP captures implicit
+non-linear crosses. A linear term retains first-order signals, and all
+three parts are learned jointly end-to-end.
+
+In the forward pass:
+  (1) Embedding Layer: transforms sparse/sequence fields into dense vectors
+  (2) Linear Part: captures first-order contributions of sparse/sequence fields
+  (3) CIN: explicitly builds higher-order feature crosses via convolution over
+      outer products of field embeddings, with optional split-half connections
+  (4) Deep Part (MLP): models implicit, non-linear interactions across all fields
+  (5) Combination: sums outputs from linear, CIN, and deep branches before the
+      task-specific prediction layer
+
+Key Advantages:
+- Jointly learns first-order, explicit high-order, and implicit interactions
+- CIN offers interpretable vector-wise crosses with controlled complexity
+- Deep branch enhances representation power for non-linear patterns
+- End-to-end optimization eliminates heavy manual feature engineering
+- Flexible design supports both sparse and sequence features
+
+xDeepFM 是一个 CTR 预估模型，将显式与隐式的特征交互学习统一到同一框架。
+在 DeepFM 的基础上，额外引入了 CIN（Compressed Interaction Network）
+显式建模高阶向量级交互，同时 MLP 负责隐式非线性交互，线性部分保留一阶信号，
+三者联合训练。
+
+前向流程：
+  (1) 嵌入层：将稀疏/序列特征映射为稠密向量
+  (2) 线性部分：建模稀疏/序列特征的一阶贡献
+  (3) CIN：通过对字段嵌入做外积并卷积，显式捕获高阶交叉，可选 split-half 以控参
+  (4) 深层部分（MLP）：对所有特征进行隐式非线性交互建模
+  (5) 融合：线性、CIN、MLP 输出求和后进入任务预测层
+
+主要优点：
+- 同时学习一阶、显式高阶、隐式交互
+- CIN 提供可解释的向量级交叉并可控复杂度
+- 深层分支提升非线性表达能力
+- 端到端训练降低人工特征工程需求
+- 兼容稀疏与序列特征的建模
 """
 
 import torch

{nextrec-0.4.3 → nextrec-0.4.5}/nextrec/utils/config.py

@@ -160,8 +160,11 @@ def build_feature_objects(
             SparseFeature(
                 name=name,
                 vocab_size=int(vocab_size),
+                embedding_name=embed_cfg.get("embedding_name", name),
                 embedding_dim=embed_cfg.get("embedding_dim"),
                 padding_idx=embed_cfg.get("padding_idx"),
+                init_type=embed_cfg.get("init_type", "xavier_uniform"),
+                init_params=embed_cfg.get("init_params"),
                 l1_reg=embed_cfg.get("l1_reg", 0.0),
                 l2_reg=embed_cfg.get("l2_reg", 1e-5),
                 trainable=embed_cfg.get("trainable", True),
@@ -184,9 +187,12 @@ def build_feature_objects(
                 name=name,
                 vocab_size=int(vocab_size),
                 max_len=embed_cfg.get("max_len") or proc_cfg.get("max_len", 50),
+                embedding_name=embed_cfg.get("embedding_name", name),
                 embedding_dim=embed_cfg.get("embedding_dim"),
                 padding_idx=embed_cfg.get("padding_idx"),
                 combiner=embed_cfg.get("combiner", "mean"),
+                init_type=embed_cfg.get("init_type", "xavier_uniform"),
+                init_params=embed_cfg.get("init_params"),
                 l1_reg=embed_cfg.get("l1_reg", 0.0),
                 l2_reg=embed_cfg.get("l2_reg", 1e-5),
                 trainable=embed_cfg.get("trainable", True),

{nextrec-0.4.3 → nextrec-0.4.5}/nextrec/utils/initializer.py

@@ -5,10 +5,9 @@ Date: create on 13/11/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-from typing import Any, Dict, Set, cast
+from typing import Any, Dict, Set
 
 import torch.nn as nn
-from torch.nn.init import _NonlinearityType
 
 KNOWN_NONLINEARITIES: Set[str] = {
     "linear",
@@ -27,28 +26,25 @@ KNOWN_NONLINEARITIES: Set[str] = {
 }
 
 
-def resolve_nonlinearity(activation: str | _NonlinearityType) -> _NonlinearityType:
-    if isinstance(activation, str):
-        if activation in KNOWN_NONLINEARITIES:
-            return cast(_NonlinearityType, activation)
-        # Fall back to linear for custom activations (gain handled separately).
-        return "linear"
-    return activation
+def resolve_nonlinearity(activation: str):
+    if activation in KNOWN_NONLINEARITIES:
+        return activation
+    return "linear"
 
 
-def resolve_gain(activation: str | _NonlinearityType, param: Dict[str, Any]) -> float:
+def resolve_gain(activation: str, param: Dict[str, Any]) -> float:
     if "gain" in param:
         return param["gain"]
     nonlinearity = resolve_nonlinearity(activation)
     try:
-        return nn.init.calculate_gain(nonlinearity, param.get("param"))
+        return nn.init.calculate_gain(nonlinearity, param.get("param")) # type: ignore
     except ValueError:
-        return 1.0  # custom activation with no gain estimate available
+        return 1.0
 
 
 def get_initializer(
     init_type: str = "normal",
-    activation: str | _NonlinearityType = "linear",
+    activation: str = "linear",
     param: Dict[str, Any] | None = None,
 ):
     param = param or {}
@@ -62,11 +58,11 @@ def get_initializer(
             nn.init.xavier_normal_(tensor, gain=gain)
         elif init_type == "kaiming_uniform":
             nn.init.kaiming_uniform_(
-                tensor, a=param.get("a", 0), nonlinearity=nonlinearity
+                tensor, a=param.get("a", 0), nonlinearity=nonlinearity # type: ignore
             )
         elif init_type == "kaiming_normal":
             nn.init.kaiming_normal_(
-                tensor, a=param.get("a", 0), nonlinearity=nonlinearity
+                tensor, a=param.get("a", 0), nonlinearity=nonlinearity # type: ignore
             )
         elif init_type == "orthogonal":
             nn.init.orthogonal_(tensor, gain=gain)
@@ -80,4 +76,4 @@ def get_initializer(
             raise ValueError(f"Unknown init_type: {init_type}")
         return tensor
 
-    return initializer_fn
+    return initializer_fn

{nextrec-0.4.3 → nextrec-0.4.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextrec"
-version = "0.4.3"
+version = "0.4.5"
 description = "A comprehensive recommendation library with match, ranking, and multi-task learning models"
 readme = "README.md"
 requires-python = ">=3.10"

nextrec-0.4.3/nextrec/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.4.3"