MiniOneRec 是首个完全开源的 生成式推荐 框架，提供涵盖 SID 构建、监督微调 (SFT) 和面向推荐的 强化学习 (RL) 的端到端工作流。

---

📢 公告

• 2026-01-04 — 关于基于 Instruct 模型复现的结果与我们报告的指标之间可能存在差异的问题，请检查评估日志中的 CC 指标是否为非零值（参考 calc.py）。若该指标非零，则表明模型仍在生成大量无效商品，约束解码并未成功。我们怀疑此问题可能与 transformer 库等依赖项的版本有关，目前仍在调查原因并寻求通用解决方案。在此期间，您可以将 Instruct 模型切换为基础模型，例如 Qwen2.5-base，以避免该问题。

• 2025-12-04 — 我们更新了新脚本，以支持处理 Amazon23 数据集。

• 2025-12-01 — 我们修复了 data.py 中的一个 bug，该 bug 可能导致 SID–商品对齐任务提前看到答案。这是因为我们之前曾尝试使用部分轨迹来指导完整的 SID–商品生成，但这并不影响模型性能。

• 2025-11-20 — RQ-Kmeans+ 中的 SID 构建方法已更新（首次提出于 GPR，这也是首次开源复现）。

• 2025-11-19 — 我们基于 Accelerate 实现了一种多 GPU 并行的文本转嵌入方法，其效率显著高于原始版本：rq/text2emb/amazon_text2emb.py。

• 2025-11-19 — 约束 RQ-Kmeans 中的 SID 构建方法已更新。

• 2025-11-07 — 感谢您提交的问题！根据您的反馈，我们发布了新的实现。如果您在运行代码时遇到任何问题，请先更新至并参考 最新版本。

• 2025-11-07 — 现在您可以在 SFT 阶段选择冻结 LLM 参数，仅训练新增 SID 词汇表的嵌入。

• 2025-10-31 — 您现在可以直接下载我们 MiniOnRec 模型的 检查点 实现。

• 2025-10-31 — RQ-Kmeans 中的 SID 构建方法已更新。

---

🛠️ 核心技术

• SID 构建：MiniOneRec 首先将每件商品转化为一个紧凑且语义上意义明确的标记。 它将商品的标题和描述拼接在一起，将该句子输入到一个冻结的文本编码器中，然后使用三级 RQ-VAE 对生成的嵌入进行量化。

• SFT：当所有商品都被重写为 SID 后，模型首先以监督方式训练。 它将按时间顺序排列的用户历史视为一个标记序列，并通过预测下一个标记的方式，学习生成用户接下来可能消费的商品的 SID。至关重要的是，这一阶段与一组语言对齐目标共同训练，这些目标在自然语言和 SID 空间之间来回映射，使推荐系统能够在离散的商品编码基础上继承大型语言模型中蕴含的世界知识。

• 面向推荐的 RL：在 SFT 之后，MiniOneRec 还会通过基于 GRPO 的面向推荐的 RL 阶段进一步优化。 对每个提示生成多个候选推荐，其奖励在组内进行归一化以稳定梯度，并通过 KL 正则项使更新后的策略保持接近参考策略。由于动作空间是封闭的商品 SID 列表，系统会切换到约束束搜索，这保证了每个束都是唯一且有效的，从而大大提高了采样效率和多样性。奖励信号本身结合了二元正确性项和排名感知组件，后者会对高概率但错误的商品施加更重的惩罚，并可辅以协同过滤得分。这些机制共同使 MiniOneRec 能够融合密集的语言学知识，构建出高性能、轻量级的生成式推荐系统。

---

📊 评估

---

🗂️ 仓库概览

文件/目录	描述
sft.sh	用于启动监督微调（SFT）阶段的 Shell 脚本
sft.py	SFT 训练循环的 Python 实现
sft_gpr.py	基于 GPR 思想的价值感知微调（VAFT）的 SFT：实现基于模拟物品价值的加权损失
rl.sh	用于启动强化学习（RL）阶段的 Shell 脚本
rl.py	RL 训练循环的 Python 实现
rl_gpr.py	基于 GPR 思想的层次增强策略优化（HEPO）的强化学习
minionerec_trainer.py	MiniOneRec 训练器——基于 GRPO 的生成式推荐专用训练器
configs/	YAML 配置文件
evaluate.sh	一键离线 Top-K 评估脚本
evaluate.py	用于计算 HR@K 和 NDCG@K 的评估工具。
LogitProcessor.py	用于约束解码的 Logit 处理器（Python 实现）
data.py	SFT 和 RL 训练的数据流水线
convert_dataset.py	将 RQ 训练的数据集转换为先 SFT 后 RL 的格式
convert_dataset_gpr.py	基于 GPR 思想的数据集转换器：注入模拟的异构标记（U/E/I/O），以模拟统一的输入表示
data/amazon18_data_process.sh	用于将 Amazon18 数据筛选并预处理为 RQ 可用格式的 Shell 脚本
data/amazon18_data_process.py	Amazon18 数据预处理流水线的 Python 实现
data/amazon18_data_process_gpr.py	基于 GPR 思想的 Amazon18 预处理：提取异构特征以实现统一的输入表示
data/amazon23_data_process.sh	用于将 Amazon23 数据筛选并预处理为 RQ 可用格式的 Shell 脚本
data/amazon23_data_process.py	Amazon23 数据预处理流水线的 Python 实现
rq/text2emb/amazon_text2emb.sh	用于通过嵌入模型为 Amazon 数据集生成商品嵌入向量（标题 + 描述）的 Shell 脚本
rq/text2emb/amazon_text2emb.py	上述嵌入生成的 Python 实现
rq/text2emb/amazon_text2emb_gpr.py	基于 GPR 思想的文本到嵌入向量转换
rq/generate_indices.py	在训练完 RQ-VAE 模型后生成 SID 文件
rq/rqvae.sh	用于在 Amazon 商品嵌入上训练 RQ-VAE 的 Shell 脚本
rq/rqvae.py	RQ-VAE 训练的 Python 实现
rq/rqkmeans_faiss.py	基于 faiss 的 RQ-Kmeans 训练的 Python 实现
rq/rqkmeans_constrained.py	约束型 RQ-Kmeans 的 Python 实现
rq/rqkmeans_constrained.sh	用于在 Amazon 商品嵌入上训练约束型 RQ-Kmeans 的 Shell 脚本
rq/rqkmeans_plus.py	RQ-Kmeans+ 的 Python 实现
rq/rqkmeans_plus.sh	用于在 Amazon 商品嵌入上训练 RQ-Kmeans+ 的 Shell 脚本
rq/generate_indices_plus.py	在训练完 RQ-Kmeans+ 模型后生成 SID 文件
rq/generate_indices_plus.sh	用于在训练完 RQ-Kmeans+ 模型后生成 SID 文件的 Shell 脚本
requirements.txt	Python 依赖包列表

---

🚀 快速入门

使用我们提供的工业/办公领域预训练 SID，即可快速上手！仅需 4–8 张 A100/H100 显卡即可完成复现。

1. 创建隔离的 Python 环境

conda create -n MiniOneRec python=3.11 -y
conda activate MiniOneRec

2. 安装所需包

pip install -r requirements.txt

3. SFT

bash sft.sh

4. 推荐导向的强化学习

bash rl.sh

5. 运行评估脚本

bash evaluate.sh

---

📜 全流程详解

0. 前置条件

• 显卡：例如 4–8 张 A100/H100 80 GB 或同等性能显卡
• Python 版本：3.11

1. 环境搭建

• 1.1 克隆仓库

git clone https://github.com/AkaliKong/MiniOneRec.git
cd MiniOneRec

• 1.2 创建并激活 Conda 环境

conda create -n MiniOneRec python=3.11 -y
conda activate MiniOneRec

• 1.3 安装依赖

pip install -r requirements.txt

2. 数据准备

• 2.1 下载原始数据集（可选）
  可从官方页面获取： Amazon Reviews 2023、 Amazon Reviews 2018、 Amazon Reviews 2014。 注意：工业与办公类数据集包含在 Amazon 2018 中；而 Amazon 2014 和 2023 版本需要对我们提供的 data/amazon18_data_process.py 脚本进行少量修改。
• 2.2 过滤与预处理

bash data/amazon18_data_process.sh \
     --dataset  your_dataset_type \ # 例如 Industrial
     --user_k 5 \
     --item_k 5 \
     --st_year 2017 \
     --st_month 10 \
     --ed_year 2018 \
     --ed_month 11 \
     --output_path ./data/Amazon18

• 2.3 将商品文本编码为嵌入向量

bash rq/amazon_text2emb.sh \
     --dataset your_dataset_type \ # 例如 Industrial 
     --root your_processed_dataset_path \
     --plm_name qwen \
     --plm_checkpoint your_emb_model_path

3. SID 构建

请从 3.1.1、3.1.2、3.1.3 或 3.1.4 中选择一种方法。

• 3.1.1 在嵌入上训练 RQ-VAE

bash rq/rqvae.sh \
      --data_path xxx/data/Industrial_and_Scientific/Industrial_and_Scientific.emb-qwen-td.npy \
      --ckpt_dir ./output/Industrial_and_Scientific \
      --lr 1e-3 \
      --epochs 10000 \
      --batch_size 20480

• 3.1.2 在嵌入上训练 RQ-Kmeans

conda install faiss-gpu
python rqkmeans_faiss.py --dataset Industrial_and_Scientific # 基于语义嵌入的 RQ-Kmeans 方法存在较高的冲突率。

• 3.1.3 在嵌入上训练约束型 RQ-Kmeans 对于存在冲突的商品，我们增加一层去重处理；同时采用平衡约束以确保 SID 分布均匀。

pip install k_means_constrained
pip install polars
bash rqkmeans_constrained.sh

• 3.1.4 在嵌入上训练 RQ-Kmeans+

pip install k_means_constrained
pip install polars
bash rqkmeans_constrained.sh
bash rqkmeans_plus.sh

• 3.2 生成索引（仅 RQ-VAE 和 RQ-Kmeans+ 需要）

python rq/generate_indices.py
# 或
bash rq/generate_indices_plus.sh

• 3.3 转换数据集格式

python convert_dataset.py \
     --dataset_name Industrial_and_Scientific \
     --data_dir /path/to/Industrial_and_Scientific \
     --output_dir /path/to/ourput_dir \

4. SFT

bash sft.sh \
     --base_model your_model_path \
     --output_dir your_ourput_dir \
     --sid_index_path your_.index.json_path \
     --item_meta_path your_.item.json_path

5. 推荐导向的强化学习

（可选）对于生产规模的数据集，考虑到强化学习的成本以及边际收益递减，可以仅使用数万条样本的较小子集来执行强化学习阶段。

bash rl.sh \
     --model_path your_model_path \
     --output_dir output_dir \

6. 离线评估

bash evaluate.sh \
     --exp_name your_model_path 

---

🤖 支持的 LLM 提供商

MiniOneRec 支持多种 LLM 提供商用于文本增强任务（例如用户偏好和商品特征提取）。请在您的 api_info 字典中配置提供商：

提供商	provider 值	默认基础 URL	示例模型
OpenAI	"openai"	—	text-davinci-003
DeepSeek	"deepseek"	https://api.deepseek.com	deepseek-chat
MiniMax	"minimax"	https://api.minimax.io/v1	MiniMax-M2.7, MiniMax-M2.5

示例 — 使用 MiniMax：

api_info = {
    "provider": "minimax",
    "api_key_list": ["your-minimax-api-key"],
    "base_url": "https://api.minimax.io/v1",  # 可选，默认值
}
get_res_batch("MiniMax-M2.7", prompt_list, max_tokens=512, api_info=api_info)

---

📝 即将推出的功能

我们正在积极扩展 MiniOneRec 的功能。以下改进已列入我们的路线图：

• ⏱️ 更多 SID 构建算法：即将支持 R-VQ、RQ-Kmeans、RQ-OPQ 和 RQ-VAE-v2 (PLUM)。
• ⚙️ MiniOneRec-Think：一个无缝集成对话、推理和个性化推荐的模块，为复杂的交互场景提供一体化解决方案。
• 🔍 更广泛的数据集支持：还将加入 Yelp 等热门公开数据集，进一步验证我们算法的通用性。

---

🏫 合作机构

本项目由以下机构共同开发：

• LDS
• AlphaLab
• NExT

---

🧩 贡献说明

我们欢迎并感谢所有贡献！如果您有任何改进 MiniOneRec 的想法，请随时提交拉取请求（PR）。

---

🙏 致谢

本仓库复用或改编了以下开源项目的部分代码。我们衷心感谢这些项目的作者和贡献者：

• ReRe
• LC-Rec

---

🔖 引用

如果您觉得我们的代码/论文/模型有所帮助，请考虑引用我们的论文 📝 并为我们点亮 ⭐️！

@misc{MiniOneRec,
      title={MiniOneRec: 一个用于扩展生成式推荐的开源框架}, 
      author={Xiaoyu Kong 和 Leheng Sheng 和 Junfei Tan 和 Yuxin Chen 和 Jiancan Wu 和 An Zhang 和 Xiang Wang 和 Xiangnan He},
      year={2025},
      eprint={2510.24431},
      archivePrefix={arXiv},
      primaryClass={cs.IR},
}

@article{ReRe,
      title={用于推荐的强化偏好优化}, 
      author={Junfei Tan 和 Yuxin Chen 和 An Zhang 和 Junguang Jiang 和 Bin Liu 和 Ziru Xu 和 Han Zhu 和 Jian Xu 和 Bo Zheng 和 Xiang Wang},
      journal={arXiv 预印本 arXiv:2510.12211},
      year={2025},
}

@inproceedings{RecZero,
      title={先思考再推荐：自主推理增强型推荐系统}, 
      author={Xiaoyu Kong 和 Junguang Jiang 和 Bin Liu 和 Ziru Xu 和 Han Zhu 和 Jian Xu 和 Bo Zheng 和 Jiancan Wu 和 Xiang Wang},
      year={2025},
      booktitle={NeurIPS},
}

---

MiniOneRec 快速上手指南

MiniOneRec 是首个完全开源的生成式推荐框架，提供从语义 ID（SID）构建、监督微调（SFT）到面向推荐的强化学习（RL）的全流程端到端解决方案。

1. 环境准备

系统要求

• 操作系统: Linux (推荐)
• Python 版本: 3.10+ (官方示例使用 3.11)
• GPU 资源: 复现建议配置 4–8 张 A100/H100 (80GB) 或同等算力显卡
• 依赖库: PyTorch, Transformers, Accelerate, FAISS 等

前置检查

确保已安装 conda 和 git。国内用户建议配置 pip 国内镜像源以加速下载。

2. 安装步骤

2.1 克隆仓库

git clone https://github.com/AkaliKong/MiniOneRec.git
cd MiniOneRec

2.2 创建虚拟环境

conda create -n MiniOneRec python=3.11 -y
conda activate MiniOneRec

2.3 安装依赖

建议使用国内镜像源加速安装：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：若需处理 Amazon 数据集或进行 SID 构建，请确保已安装 faiss-gpu 及相关 NLP 模型依赖。

3. 基本使用

本指南演示如何使用官方提供的预训练 Industrial/Office 语义 ID (SIDs) 进行快速启动和复现。

3.1 监督微调 (SFT)

运行以下脚本启动 SFT 阶段，模型将学习根据用户历史序列预测下一个商品的 SID。

bash sft.sh

3.2 面向推荐的强化学习 (RL)

SFT 完成后，运行以下脚本基于 GRPO 算法进行强化学习微调，以优化推荐排序和多样性。

bash rl.sh

3.3 模型评估

执行一键离线评估脚本，计算 HR@K 和 NDCG@K 指标。

bash evaluate.sh

---

💡 进阶提示

• 数据集准备：若需从头处理数据（如 Amazon23），请参考 data/ 目录下的预处理脚本（如 amazon23_data_process.sh）。
• SID 构建：若需自定义商品编码，可使用 rq/ 目录下的工具链（文本向量化 -> RQ-VAE/Kmeans 聚类 -> 生成 SID）。
• 已知问题：若在使用 Instruct 模型时遇到生成大量无效物品的问题（评估日志中 CC 指标非零），建议暂时切换至 Base 模型（如 Qwen2.5-base）以规避约束解码兼容性问题。