TIGER¶
TIGER 把 next-item recommendation 改写为短 token 序列生成:先用 RQ-VAE 把每个 item 编成多层 Semantic ID,再让 T5 encoder–decoder 根据历史 SID 自回归生成目标 SID。
定位与状态¶
| 项目 | 内容 |
|---|---|
| 原论文 | Recommender Systems with Generative Retrieval,NeurIPS 2023 |
| 官方参考代码 | google-research/google-research/tree/master/tiger |
| 任务 | next-item generative retrieval |
| 表示 | RQ-VAE Semantic ID,默认 3 × 256 codes |
| backbone | 仓库内纯 PyTorch T5 encoder–decoder |
| 解码 | 当前代码为普通 beam search;未硬接 Trie |
| 主评测 | training-only SID→item 解析、item 去重后的 Recall/NDCG |
| 复现 | 历史 SID-level checkpoint 需按当前 item-level 代码重评 |
| 最近核验 | 2026-08-30 |
两阶段流水线¶
flowchart LR
M[item metadata] --> E[sentence-t5-xl]
E --> R[RQ-VAE]
R --> S[item to SID catalog]
H[user item history] --> X[replace each item by SID]
S --> X
X --> T[T5 encoder-decoder]
T --> B[beam candidates]
B --> D[offset decode]
D --> P[training-only SID to item]
P --> U[item deduplication]
U --> K[Recall / NDCG]
第一阶段只看 item 内容 embedding;第二阶段才使用用户行为序列。两个阶段必须使用同一个 item 顺序、sentence encoder 和 RQ-VAE 几何。
SID token 编码¶
原始 SID 的每层 code 都在 [0,K-1],如果直接共用 token 范围,模型无法知道 code 属于哪一层。collate 使用位置偏移:
0 保留给 padding / decoder start;词表大小为 C*K+1。例如 K=256、SID [12,7,99] 会变成 [13,264,612]。历史中每个 item 的 C 个 token 依次展平,最长输入 token 数是 max_seq_len * C。
层数必须同步
AmazonSeqDataset 生成的 SID 宽度、trainer 的 sem_id_dim、词表大小和 max_length 必须一致。若 dataset 追加第 4 个 disambiguation code,却仍用 sem_id_dim=3,会造成 token layer 错位。
T5 目标¶
给定历史 token 序列 \(x\) 与目标 SID token \(y_{1:C}\),模型优化 teacher-forcing 交叉熵:
encoder 双向编码全部历史 token;decoder 用 causal self-attention 和 cross-attention 逐层生成目标 code。input/output embedding 与 LM head 按 T5 方式共享。
当前 Tiger 包装的是 genrec/modules/t5.py 中的纯 PyTorch 实现,不是运行时直接实例化 Hugging Face T5。该实现以 weight-compatible 为目标,并有 verify_t5_equivalence.py / verify_pure_t5.py 辅助检查;旧 trainer docstring 中的 “HF T5-based” 是历史描述。
当前模型配置¶
默认 Amazon Gin:
| 参数 | 值 |
|---|---|
| encoder / decoder layers | 4 / 4 |
d_model / d_ff |
128 / 1024 |
heads / d_kv |
6 / 64 |
| dropout | 0.1 |
| SID | 3 × 256 |
| history | 50 items = 150 tokens |
| beam size | 30 |
| optimizer | Adam, lr 1e-4, no scheduler |
注意 num_heads * d_kv 不要求等于 d_model;T5 会把 Q/K/V 投影到多头内部维度。
数据样本¶
AmazonSeqDataset 默认按用户时间排序,并在 leave-one-out 下:
- train:排除最后两个 item,使用 sliding window;每个剩余 item(首项除外)都做一次 target;
- valid:倒数第二项为 target;
- test:最后一项为 target;
- history 只保留最近
max_seq_len个 item; SeqData.item_ids是已经展平但尚未 offset 的历史 codes;SeqData.target_ids是原始 target SID,target_item保存真实 item ID。
训练样本策略与 SASRec 不同:TIGER 每个用户产生多条 prefix 样本,而当前 SASRec 每用户一条序列、在 collate 内做多位置监督。比较时需要意识到 I/O 和 sample count 不同。
碰撞处理选项¶
dataset 提供两个互斥策略:
add_disambiguation=True:为同 SID item 追加组内序号,SID 从 C 层变 C+1 层;dedup_sinkhorn=True:保持层数,用 RQ-VAE 最后一层 Sinkhorn 重分配碰撞组。
默认配置两者都关闭,并在评测时诚实解析碰撞。若同时打开,代码优先 Sinkhorn 并忽略 suffix。使用 suffix 时必须同步 sem_id_dim 和 vocab;suffix 最大值还必须小于 codebook_size。
解码:代码事实与旧文档差异¶
Tiger.generate() 调用纯 PyTorch T5 的 beam search,设置:
返回的第一个 decoder-start token 被移除,剩下 [B,beam,C]。
当前没有 Trie 约束
当前实现没有向 generate() 传 prefix callback,也没有 catalog Trie。模型可能在第 j 步生成属于其他 codebook offset 区间的 token,或产生目录中不存在的 SID。item mapper 会丢弃无法解析的候选,但这会降低有效候选数。项目概览中曾写“TIGER 使用 Trie 约束”,那描述的是预期/常见范式,不是当前代码事实。
若后续加入 Trie,应复用 genrec/utils/generation_trie.py 的接口思想,并同时增加“所有输出合法”“batch beam reorder 正确”“有效候选不足时补齐”的测试;不能只在文档中改状态。
诚实 item-level 评测¶
SID 可能碰撞。SemanticIdItemMapper.from_sequences 只根据训练前缀统计 item popularity,对每个 SID 选择一个确定代表 item,流行度相同时取较小 item ID:
评测依次:
- 把 offset token 还原成 raw SID;
- 用 \(g\) 映射到唯一 item;目录外 SID 丢弃;
- 同一 item 多次出现只保留第一次;
- 从更深 beam 继续补候选,不足位置填
-1; - 对真实
target_item计算 item-level Recall@5/10 与 NDCG@5/10。
trainer 仍记录 pre-dedup SID-level 指标,但日志明确标为 diagnostic,results.json 的主 metrics、valid 早停与 best checkpoint 选择均使用 item-level Recall@10。
代码映射¶
| 层次 | 文件 | 对象 | 职责 |
|---|---|---|---|
| wrapper | genrec/models/tiger.py |
Tiger |
T5 构造、forward、beam generate |
| T5 | genrec/modules/t5.py |
T5ForConditionalGeneration |
纯 PyTorch encoder–decoder 与 generation |
| tokenizer | genrec/models/rqvae.py |
RqVae |
item embedding → SID |
| 数据 | genrec/data/amazon.py |
AmazonSeqDataset |
SID catalog、序列样本、碰撞策略 |
| collate | genrec/trainers/tiger_trainer.py |
t5_collate |
offset encoding、左 padding、raw targets |
| resolver | genrec/modules/metrics.py |
SemanticIdItemMapper |
training-only SID→item 与去重 |
| trainer | genrec/trainers/tiger_trainer.py |
train |
单设备训练、早停、双口径日志 |
| config | config/tiger/amazon/*.gin |
— | RQ-VAE 与 TIGER 两阶段参数 |
运行¶
# Stage 1:训练匹配几何的 RQ-VAE
python genrec/trainers/rqvae_trainer.py \
config/tiger/amazon/rqvae.gin --split beauty
# Stage 2:训练 TIGER
python genrec/trainers/tiger_trainer.py \
config/tiger/amazon/tiger.gin --split beauty
checkpoint 默认依赖:
覆盖路径时同时检查 encoder 和几何:
python genrec/trainers/tiger_trainer.py \
config/tiger/amazon/tiger.gin --split beauty \
--gin 'train.pretrained_rqvae_path="/abs/path/checkpoint.pt"'
训练器目前直接选择 cuda 或 cpu,没有用 Accelerate 包装 TIGER model/data loader;多 GPU 命令不能类推 OneRec 的 accelerate launch。W&B 可关闭:--gin 'train.wandb_logging=False'。
checkpoint 与结果¶
- 最佳 item-level valid Recall@10 权重:
best_model.pt(仅 model state dict); results.json:主 item metrics、seed、config、best epoch、sid_resolution=most_popular_training_only;sid_reference_metrics:旧 SID-level 诊断,不能进入 headline 表格;- RQ-VAE checkpoint 另存 optimizer/scheduler/model_config,与 TIGER checkpoint 格式不同。
与论文/参考实现的差异¶
| 方面 | TIGER 工作 | 本仓库当前实现 |
|---|---|---|
| item tokenizer | RQ-VAE semantic IDs | RQ-VAE,多种量化模式及碰撞诊断 |
| backbone | T5 类 encoder–decoder | 仓库内 pure-PyTorch T5 |
| candidate validity | 生成目录 SID 的范式 | 普通 beam;没有硬 Trie,非法 SID 后过滤 |
| collision | 论文协议不等同当前诚实解析 | training-only most-popular resolver + item dedup |
| model selection | 依原实验协议 | item-level valid Recall@10 |
| distributed | 参考环境不同 | 当前 trainer 为单进程设备路径 |
本仓库历史表中的 TIGER SID-tuple 数字不能与当前 item-level 数字混用。只有按新代码重评 checkpoint 后,结果才可重新进入主对比表。
常见问题¶
- 大量候选被丢弃:统计每个 code position 的 offset 区间合法率和 catalog SID 命中率;当前无 Trie。
- 加载 RQ-VAE 后 SID 全变:使用
RqVae.from_pretrained或已修复的load_pretrained,防止第一次前向重新 K-Means 初始化。 - 输入维度不匹配:检查 parquet encoder、
rqvae_input_dim、latent/hidden dims、codebook size/layers。 - SID Recall 高而 item Recall 低:报告 collision group、resolver retention 与去重前后候选;这是表示歧义,不是指标实现 bug。
- 设置
add_disambiguation=True后训练异常:同步将sem_id_dim改为 C+1,并确保 suffix 落在合法 code 范围。 - 评测很慢:成本约随 test users、beam size 和自回归层数增长;当前没有批量 Trie/KV-cache 专项优化。
- 和 SASRec 比较时结果漂移:确认两者使用同一目标切分、
max_seq_len=50和 item-level full-catalog 定义。