API 参考¶
本节是当前源码的调用索引,不是一个承诺稳定性的公共 SDK。GenRec 是研究代码库:模型、数据适配器和 trainer 多数按实验独立演进,没有统一的 BaseModel、BaseDataset、DatasetFactory 或 BaseTrainer。以下签名均以当前 genrec/ 源文件为准。
从哪里开始¶
| 需求 | API 页 | 真实入口 |
|---|---|---|
| 查看全部数据类和样本 schema | 数据集 | genrec/data/ |
| 理解共享切分契约 | 数据集基础契约 | evaluation_protocol.py、schemas.py |
| 配置和命令行覆盖 | Gin 与 CLI | parse_config、config/ |
| 模型公用层、loss、metric | Modules | genrec/modules/ |
| 数据预处理实际放在哪里 | 预处理索引 | 数据模块内 helper、scripts/ |
| 替代历史 DatasetFactory | 数据类选择与注入 | Gin dataset=@ClassName 或直接构造 |
| 训练函数、checkpoint、results | 训练入口 | genrec/trainers/ |
| RQ-VAE 的精确返回类型 | RQ-VAE API | genrec/models/rqvae.py |
| TIGER 的 token/beam 接口 | TIGER API | genrec/models/tiger.py |
模型模块¶
仓库有 11 个 genrec/models/*.py 实现模块,其中 RQ-VAE 与 RQ-KMeans 是 tokenizer/quantizer,不是独立推荐器。原理、数据流和论文差异由模型页维护;API 页不再复制这些内容。
| 源模块 / 主类 | 模型说明 |
|---|---|
sasrec.py / SASRec |
SASRec |
hstu.py / HSTU |
HSTU |
rqvae.py / RqVae |
RQVAE;API |
rqkmeans.py / RqKmeans |
RQ-KMeans |
tiger.py / Tiger |
TIGER;API |
lcrec.py / LCRec |
LCRec |
cobra.py / Cobra |
COBRA |
onerec.py / OneRec |
OneRec |
rpg.py / RPGModel |
RPG |
notellm.py / Query2Embedding |
NoteLLM |
gram.py / GRAM |
GRAM |
导入约定¶
genrec.models.__init__ 当前只重导出:
OneRec、RPG、NoteLLM 和 RQ-KMeans 没有从包根重导出,应从实现模块导入:
from genrec.models.onerec import OneRec
from genrec.models.rpg import RPGModel
from genrec.models.notellm import Query2Embedding
from genrec.models.rqkmeans import RqKmeans
genrec.data 只重导出 SeqData、SeqBatch、TokenizedSeqBatch 和 cycle;各 dataset 也应从具体模块导入。genrec.trainers 重导出少量共享工具,但不重导出每个 train* 函数。
当前稳定的跨模型契约¶
跨模型真正共享的接口只有少数几项:
- PyTorch dataset:实现
__len__()与__getitem__(),样本 schema 由对应 trainer 的 collate 函数决定。 - CLI:trainer 的
__main__调用parse_config(),接受一个 gin 文件、--split和重复的--gin。 - 评测:多数 item/SID 路径复用
TopKAccumulator;SID 模型可复用SemanticIdItemMapper。 - 结果:多数 trainer 调用
save_run_results(...)写results.json,但 checkpoint 文件名和格式并不统一。
不要假定“某个 trainer 支持的参数,其他 trainer 也支持”。调用前应同时看目标 trainer 的 @gin.configurable 函数签名和对应 .gin 文件。
符号核验方法¶
本地不必导入 PyTorch 即可用静态搜索确认符号:
rg -n '^class |^def |^@gin.configurable' genrec/models genrec/data genrec/modules genrec/trainers
rg -n 'train\.|train_[a-z]+\.' config
需要运行时签名且环境已安装依赖时:
import inspect
from genrec.models.rqvae import RqVae
print(inspect.signature(RqVae))
print(inspect.signature(RqVae.get_semantic_ids))