跳转至

仓库地图与依赖边界

顶层目录

genrec/
├── config/                 # Gin 配置;按模型/数据集划分
├── dataset/                # 运行时数据、下载和缓存(不应当进 Git)
├── docs/                   # MkDocs 中英文文档
├── genrec/
│   ├── data/               # 数据读取、协议、样本构造、collator
│   ├── models/             # 模型与量化器
│   ├── modules/            # 可复用网络层、指标、CLI 工具
│   ├── trainers/           # 独立可执行训练脚本
│   └── utils/              # 当前仅为占位包
├── scripts/                # 矩阵、诊断、provenance、179 执行工具
├── tests/                  # 单元、协议和 artifact 合同测试
├── reference/              # 上游论文代码,仅作 parity 参考
└── out/                    # checkpoint、日志与 results.json(运行时)

reference/ 不在生产调用链中。修复 parity 问题时可以比较,但不要让训练入口 import 其中代码。

真实依赖方向

flowchart TD
    C[config/*.gin] --> T[genrec/trainers]
    T --> D[genrec/data]
    T --> M[genrec/models]
    T --> U[genrec/modules]
    D --> M
    D --> U
    M --> U
    S[scripts] --> T
    S --> R[out/**/results.json]
    X[tests] --> D
    X --> M
    X --> T
    X --> S

这里有两个容易误读的地方:

  • 数据层有时加载模型:AmazonSeqDataset、LCRec、COBRA 会加载 RQ-VAE,OneRec 数据集会加载 RQ-KMeans/RQ-VAE,RPG 数据集会拟合或读取 OPQ。这是现有实现,不是纯粹的“data 只能依赖 schema”分层。
  • 训练器之间通常不互相 import;多阶段关系通过磁盘 artifact 连接,例如 RQ-KMeans → OneRec SFT → OneRec GRPO。

genrec/data

文件 当前职责 主要消费者
amazon.py Amazon 2014 下载、元数据 embedding;通用 SID 序列数据 RQ-VAE、TIGER 及若干复用者
evaluation_protocol.py leave-one-out / global-temporal 共享序列选择 Amazon 主路径适配器
schemas.py SeqData、SeqBatch、TokenizedSeqBatch TIGER/旧 token 化路径
amazon_sasrec.py 1-based item 序列、SASRec collator SASRec;NoteLLM 继承其映射/协议
amazon_hstu.py item 序列 + Unix timestamp HSTU
ml1m_hstu.py ML-1M 下载、5-core、HSTU schema HSTU dataset_type="ml1m"
amazon_lcrec.py LCRec 六任务 prompt/response LCRec
amazon_onerec.py OneRec SFT 四任务与 RL prompt OneRec SFT / GRPO
amazon_onerec_clm.py 每用户一个扁平 SID token 流 OneRec CLM
amazon_cobra.py SID 与物品文本 token 的混合样本 COBRA
amazon_rpg.py 文本 embedding、OPQ、并行 code labels RPG
amazon_notellm.py item-to-item 文本对与 catalog 文本 NoteLLM
amazon_gram.py GRAM 预处理文件、FiD passages、lexical ID GRAM
amazon2023.py Amazon Reviews 2023 下载/预处理及早期专用 Dataset 下载工具、遗留路径
p5_amazon.py 基于 PyG/P5 数据的早期适配器 兼容/参考路径

Amazon 主路径的具体 shape 和 ID 约定见数据流水线。

genrec/models

文件 导出对象 工程角色
sasrec.py SASRec softmax/BCE 序列推荐
hstu.py HSTU、HSTULayer、RAB SiLU attention、update gate、位置/时间 bias
rqvae.py RqVae、Quantize* 可学习 residual quantization
rqkmeans.py RqKmeans 无神经网络的 residual K-Means tokenizer
tiger.py Tiger 仓库内纯 PyTorch T5 上的 SID seq2seq
lcrec.py LCRec HF causal LM + SID token + KV-cache beam
onerec.py OneRec HF causal LM;SFT/CLM/GRPO 与受约束生成
cobra.py Cobra、BeamFusion 相关输出 sparse SID + dense vector 联合生成/解析
rpg.py RPGModel GPT-2 backbone + 多个并行 code head
notellm.py Query2Embedding Qwen embedding pooling 与对比学习
gram.py GRAM T5 FiD + lexical ID 受约束生成

模型论文语义和实现差异应由模型文档维护;本章只记录调用接口。

genrec/modules

文件 应优先复用的能力 备注
utils.py Gin CLI、logger、mode/cache 装饰器 parse_config 只做字符串替换,不解析环境变量
metrics.py SemanticIdItemMapper、TopKAccumulator 当前公平评估的核心
t5.py 纯 PyTorch、可兼容 T5 权重的实现 TIGER 使用;不是 HF T5ForConditionalGeneration
encoder.py LightT5、SentenceT5、Ernie、BGE、MLP encoder COBRA/RQ-VAE 等选择性使用
transformer.py 仓库早期自定义 Transformer/T5 组件 不应与 t5.py 混称
loss.py reconstruction / contrastive 辅助损失 模型局部调用
kmeans.py Torch K-Means 辅助 与 sklearn RqKmeans 是不同实现
gumbel.py Gumbel quantization 辅助 RQ-VAE 路径
normalize.py normalization 层 模型局部调用
scheduler.py inverse-square-root scheduler 不是所有 trainer 的默认 scheduler
embedding.py 较早期 embedding 工具 先查调用方再改动

genrec/trainers

入口函数并不统一命名:

脚本 Gin 顶层函数 是否使用 Accelerate
sasrec_trainer.py train 是
hstu_trainer.py train 是
tiger_trainer.py train 否,直接选择单个 device
rqvae_trainer.py train 是
rqkmeans_trainer.py fit_rqkmeans 否,CPU/sklearn
lcrec_trainer.py train 是
onerec_sft_trainer.py train_sft 是,包含 FSDP 保存分支
onerec_clm_trainer.py train_clm 是
onerec_grpo_trainer.py train_grpo 是
cobra_trainer.py train 是
rpg_trainer.py train_rpg 是
notellm_trainer.py train 是
gram_trainer.py train_gram 是

trainer_utils.py 提供 set_seed、setup_accelerator、setup_wandb、save_run_results 和通用 checkpoint helpers;其中 TrainerConfig 目前不是所有训练器采用的总配置对象,通用 save_checkpoint/load_checkpoint 也没有统一现有 checkpoint 格式。

scripts:运行与审计工具

推荐的维护入口:

仓库还有实验诊断、绘图和一次性编排脚本。修改它们前先用 rg 查调用方和文档;文件名存在不等于仍是推荐入口。

测试覆盖的合同

tests/ 当前重点保护的是:

  • 数据协议不泄露未来交互;
  • SID tuple 指标与解析后 item 指标不能混用;
  • TopKAccumulator 在候选数小于请求 K 时不会把 miss 算成 hit;
  • NoteLLM 全目录评估排除 query item 且 item ID 唯一;
  • RQ-VAE checkpoint 几何和加载安全;
  • matrix 命令、结果聚合/验证、artifact provenance;
  • 179 source/cell/GPU 锁脚本。

测试不是对所有模型数值 parity 的完整保证。增加新路径时,至少补充输入 shape、评估层级、checkpoint round-trip 和 results.json 合同测试。

遗留与兼容区

以下代码不能直接视为当前推荐主路径:

  • p5_amazon.py 的 PyG/P5 下载与早期数据对象;
  • TokenizedSeqBatch 及部分自定义 Transformer 工具;
  • amazon2023.py 内的专用 Amazon2023ItemDataset / Amazon2023SASRecDataset;当前配置主要复用 Amazon 风格适配器,且专用类预期 processed/<split>,而下载预处理函数写入 raw/<category>,接入前必须核对目录迁移步骤;
  • 各类 diagnose_*、历史 grid 和一次性修复脚本。

“遗留”不表示可以删除。应先确认配置、测试、已有 artifact 的反序列化路径以及外部实验脚本。