GenRec¶
GenRec 是一个基于 PyTorch 与 Gin-config 的**生成式推荐研究框架**。它的目标不是提供线上推荐服务,而是把模型实现、数据协议、语义 ID、训练流水线与 item-level 评估放在同一套可审计的实验框架中,便于复现论文、进行公平比较和验证新想法。
文档口径
中文站点是当前代码的规范文档。文档会明确区分“代码已存在”“端到端已验证”“论文结果已复现”和“仅列入研究全景”,避免把模型目录误当作复现成绩单。具体状态见实现与复现状态。
从哪里开始¶
| 你的目标 | 建议入口 |
|---|---|
| 第一次运行项目 | 快速开始 → 安装指南 |
| 理解当前实现 | 实现架构 → 仓库地图 |
| 选择或比较模型 | 模型总览 → 各模型专页 |
| 了解尚未实现的方法 | GenRec 研究全景 → 模型目录 |
| 做可比实验 | 评估系统 → 复现工作流 |
| 扩展代码或维护文档 | 扩展指南 → 贡献指南 |
当前代码覆盖¶
当前仓库包含 9 个推荐模型,以及 2 个语义 ID/tokenizer 组件。这里按“训练后直接承担推荐任务”区分推荐器与 tokenizer。
| 家族 | 已实现内容 | 核心表示或生成方式 |
|---|---|---|
| 判别式序列基线 | SASRec、HSTU | 单一 item ID,候选集全排序 |
| RQ 语义 ID 推荐 | TIGER、LCRec、COBRA、OneRec | 多层离散 code;OneRec 另含 SFT/CLM/GRPO 路径 |
| 其他生成与 LLM 路线 | RPG、NoteLLM、GRAM | 并行 code heads、文本编码检索、词法 ID 与多粒度融合 |
| 表示学习组件 | RQ-VAE、RQ-KMeans | 把 item embedding 转换成离散语义 ID;本身不是推荐器 |
尚未落地的代表性路线——例如生成式检索、LLM 推荐、离散 tokenizer、扩散式推荐、生成-判别混合系统和推荐推理/RL——统一收录在模型目录。当前目录共 68 个模型/组件条目,每一项均带实现状态与原始资料入口。
系统如何串起来¶
flowchart LR
A[原始交互与元数据] --> B[数据准备与划分]
B --> C[模型专用 Dataset / Collator]
A --> D[item 文本或预训练 embedding]
D --> E[RQ-VAE / RQ-KMeans / OPQ 等]
E --> C
C --> F[Trainer + Gin 配置]
F --> G[Checkpoint 与结果 artifact]
G --> H[item-level 解析、去重与指标]
H --> I[可复现矩阵与 BENCHMARKS]
不同模型并不共享一个强行抽象的通用基类;统一性主要来自命令行/Gin 入口、数据字段契约、输出 artifact 与评估协议。具体边界见训练系统和数据流水线。
最短可运行路径¶
安装开发环境后,可先用无外部 tokenizer 依赖的基线验证数据、训练和评估链路:
python -m venv .venv
source .venv/bin/activate
pip install -e .
python genrec/trainers/sasrec_trainer.py \
config/sasrec/amazon.gin \
--split beauty
需要语义 ID 的模型必须先准备匹配的 tokenizer checkpoint。例如 TIGER:
python genrec/trainers/rqvae_trainer.py \
config/tiger/amazon/rqvae.gin \
--split beauty
python genrec/trainers/tiger_trainer.py \
config/tiger/amazon/tiger.gin \
--split beauty
完整依赖、数据下载行为与模型 hub 约定见安装指南;所有正式训练命令见命令索引。
已完成矩阵(2026-10-22)¶
主矩阵包含 162 个 item-level cell、54 条完整三种子行。下表为 R@10 均值 ± 总体标准差(seed 42/43/44);全部指标、逐 seed 来源与历史配方边界见 BENCHMARKS.md。 序列历史通常为 50,但 LCRec 论文配方为 20;这不是严格等历史长度的对照。
Leave-one-out¶
| Model | Beauty R@10 | Sports R@10 | Toys R@10 |
|---|---|---|---|
| SASRec (CE) | 0.0858 ± 0.0002 | 0.0497 ± 0.0005 | 0.0917 ± 0.0007 |
| HSTU (CE) | 0.0727 ± 0.0008 | 0.0384 ± 0.0011 | 0.0686 ± 0.0007 |
| TIGER (matrix recipe) | 0.0568 ± 0.0010 | 0.0342 ± 0.0017 | 0.0477 ± 0.0004 |
| LCRec (4B, seq20, gb128) | 0.0729 ± 0.0004 | 0.0399 ± 0.0005 | 0.0705 ± 0.0041 |
| COBRA (optimized light) | 0.0454 ± 0.0006 | 0.0290 ± 0.0007 | 0.0412 ± 0.0007 |
| RPG (direct) | 0.0732 ± 0.0007 | 0.0426 ± 0.0007 | 0.0820 ± 0.0003 |
| NoteLLM (GCL+CSFT, I2I) | 0.0693 ± 0.0004 | 0.0351 ± 0.0003 | 0.0917 ± 0.0005 |
| OneRec SFT (3 SID) | 0.0658 ± 0.0016 | 0.0341 ± 0.0007 | 0.0591 ± 0.0004 |
| OneRec + GRPO (selected) | 0.0661 ± 0.0024 | 0.0341 ± 0.0005 | 0.0604 ± 0.0013 |
Global temporal¶
| Model | Beauty R@10 | Sports R@10 | Toys R@10 |
|---|---|---|---|
| SASRec (CE) | 0.0166 ± 0.0010 | 0.0189 ± 0.0008 | 0.0179 ± 0.0005 |
| HSTU (CE) | 0.0163 ± 0.0006 | 0.0192 ± 0.0007 | 0.0165 ± 0.0005 |
| TIGER (matrix recipe) | 0.0206 ± 0.0013 | 0.0205 ± 0.0021 | 0.0184 ± 0.0020 |
| LCRec (4B, seq20, gb128) | 0.0208 ± 0.0025 | 0.0207 ± 0.0007 | 0.0209 ± 0.0011 |
| COBRA (optimized light) | 0.0175 ± 0.0007 | 0.0221 ± 0.0006 | 0.0190 ± 0.0007 |
| RPG (direct) | 0.0173 ± 0.0004 | 0.0182 ± 0.0002 | 0.0226 ± 0.0004 |
| NoteLLM (GCL+CSFT, I2I) | 0.0266 ± 0.0013 | 0.0192 ± 0.0005 | 0.0263 ± 0.0009 |
| OneRec SFT (3 SID) | 0.0239 ± 0.0014 | 0.0220 ± 0.0007 | 0.0208 ± 0.0003 |
| OneRec + GRPO (selected) | 0.0245 ± 0.0018 | 0.0223 ± 0.0004 | 0.0208 ± 0.0005 |
OneRec 主结果保持 3 码,4 码只作 Beauty 消融。GRPO 行允许验证集选回 SFT, 18 格中有 16 格发生回退;评测 prompt 模板尚未冻结,不能把微小分差归因于 RL。 NoteLLM 是排除 query item 的 I2I 评测。这些结果证明本仓库适配链路已完成, 不代表所有模型均复现原论文设置或分数。
Home extension¶
Home 扩展已于 2026-10-31 完成 54/54 格、18 条三种子行,加上原三域后共 216 格、72 条汇总行。下表沿用 item-level 与总体标准差口径。
| Model | LOO R@10 | Global temporal R@10 |
|---|---|---|
| SASRec (CE) | 0.0280 ± 0.0002 | 0.0098 ± 0.0006 |
| HSTU (CE) | 0.0197 ± 0.0001 | 0.0107 ± 0.0008 |
| TIGER (matrix recipe) | 0.0194 ± 0.0004 | 0.0123 ± 0.0001 |
| LCRec (4B, seq20, gb128) | 0.0270 ± 0.0005 | 0.0102 ± 0.0008 |
| COBRA (optimized light) | 0.0152 ± 0.0003 | 0.0089 ± 0.0003 |
| RPG (direct) | 0.0061 ± 0.0007 | 0.0075 ± 0.0014 |
| NoteLLM (GCL+CSFT, I2I) | 0.0272 ± 0.0002 | 0.0083 ± 0.0001 |
| OneRec SFT (3 SID) | 0.0211 ± 0.0001 | 0.0094 ± 0.0005 |
| OneRec + GRPO (selected) | 0.0210 ± 0.0003 | 0.0098 ± 0.0004 |
Home 的 6 个 GRPO 实验全部选回 SFT。RPG 直接迁移 Beauty 配方;未做四码 Home 消融。 原始路径、命令与源码/配置校验和见 Home 来源记录。
阅读结果时的底线¶
- 生成的 SID tuple 不等于唯一 item。存在碰撞时,必须先做训练集可见的 SID→item 解析,再进行 item 去重和指标计算。
- 不同数据划分、候选集合、负采样或解码预算下的 Recall/NDCG 不应直接横比。
- “仓库已实现”不自动意味着“论文配置和论文数字已复现”;应同时检查 checkpoint、日志、数据指纹和评估层级。
- 历史 TIGER、LCRec、OneRec SID-tuple 数字可能受碰撞放大;对外比较应优先使用重新验证过的 item-level 结果。
当前基准快照及协议注释见 BENCHMARKS.md。更完整的检查清单见生成式推荐评测协议。
项目边界与贡献¶
GenRec 面向学术复现与研究原型,不承诺在线服务所需的低延迟检索、多租户、安全、灰度发布或实时特征一致性;相关边界见部署说明。新增模型时请同时提交模型说明、状态证据、命令与评估口径,具体规则见文档维护规范。
项目采用 MIT License。欢迎通过 Issue 或 Pull Request 参与,参见贡献指南。