RQ-VAE¶
RQ-VAE(Residual-Quantized Variational Autoencoder)在 GenRec 中是 item tokenizer:它把连续文本 embedding 压缩成多层离散 Semantic ID(SID),供 TIGER、LCRec 和 COBRA 使用。它不读取用户历史,也不应作为独立 recommender 报 Recall@K。
定位与状态¶
| 项目 | 内容 |
|---|---|
| 角色 | 可学习 SID tokenizer / quantizer |
| 输入 | item semantic embedding [B,input_dim] |
| 输出 | 重构向量、逐层 code、残差与量化损失 |
| 下游 | TIGER、LCRec、COBRA;不同下游使用不同几何配置 |
| 代码 | 完整训练与 checkpoint 恢复 |
| 主诊断 | reconstruction loss、quantization loss、逐层 usage/perplexity、完整 SID collision |
| 最近核验 | 2026-08-30 |
为什么需要离散 item token¶
自回归推荐器需要有限词表。直接为每个 item 分配唯一 token 无法利用内容结构,也不利于新 item 表示。RQ-VAE 先用 MLP 把 item 文本向量映射到低维空间,再用多个 codebook 依次拟合残差:
完整 SID 是 \((k_1,\ldots,k_C)\),重构使用量化向量之和:
相邻 code 不是自然语言 token;codebook 层号是表示的一部分,code=7 在第 0 层和第 1 层不是同一个 token。
flowchart LR
X[item text] --> S[sentence encoder]
S --> Z[MLP encoder]
Z --> Q1[codebook 1]
Q1 -->|residual| Q2[codebook 2]
Q2 -->|residual| Q3[codebook C]
Q1 --> SUM[sum quantized vectors]
Q2 --> SUM
Q3 --> SUM
SUM --> D[MLP decoder]
Q1 --> SID[semantic ID tuple]
Q2 --> SID
Q3 --> SID
损失¶
连续特征默认使用逐样本平方误差;decoder 输出在比较前做 L2 normalize:
每层量化损失由 codebook loss 与 commitment loss 组成:
总损失为:
若 n_cat_features > 0,最后若干维使用 BCE-with-logits,其余维仍用重构误差;当前推荐 pipeline 的文本 embedding 配置把它设为 0。
四种量化前向模式¶
| 模式 | 训练时行为 | 适用说明 |
|---|---|---|
GUMBEL_SOFTMAX |
对负距离做带温度 Gumbel-softmax,按软权重合成 code vector | 可微软分配 |
STE |
最近邻硬分配,x + (q-x).detach() 直通梯度 |
TIGER/LCRec/COBRA 前几层默认 |
ROTATION_TRICK |
最近邻前向,用 rotation trick 改善 encoder 梯度方向 | 实验消融 |
SINKHORN |
batch 内平衡 optimal-transport assignment,再做硬分配与 STE | 下游配置的最后一层默认 |
训练/评测的最近邻距离当前为 L2。codebook_normalize=True 时只对第 0 层 codebook 输出和 encoder 输出做 L2 normalize;sim_vq=True 会在 codebook 后加共享线性投影。两者不是所有层自动生效的全局开关。
输出张量¶
RqVae.get_semantic_ids(x) 返回 RqVaeOutput:
| 字段 | shape | 说明 |
|---|---|---|
embeddings |
[B,D,C] |
各层量化向量,最后一维为层 |
residuals |
[B,D,C] |
每层量化前的残差 |
sem_ids |
[B,C] |
每个 item 的完整 SID |
quantize_loss |
[B](逐层累计) |
codebook + commitment loss |
RqVae.forward(batch,gumbel_t) 返回总损失、重构损失、RQ loss,以及仅用于调试的 embedding norm 和 batch 内 unique 比例。正式全目录碰撞率不能用单个 batch 的 p_unique_ids 替代。
三套下游几何¶
当前配置不能共享 checkpoint:
| 下游 | input | latent | hidden dims | codebook | 层数 | 典型 SID |
|---|---|---|---|---|---|---|
| TIGER | 768 | 32 | 512,256,128,64 | 256 | 3 | 256³ 空间 |
| LCRec | 768 | 64 | 512,256,128 | 256 | 5 | 256⁵ 空间 |
| COBRA | 768 | 32 | 512,256,128,64 | 32 | 3 | 32³ 空间 |
三者默认都以 sentence-t5-xl item embedding 为输入、前层 STE、最后层 Sinkhorn。文件名相同不代表几何兼容;下游 dataset 中的 rqvae_* 参数必须与 checkpoint 的 model_config 一致。
数据与缓存¶
AmazonItemDataset 从 review 首次出现顺序建立 item mapping,把 metadata 拼成文本,经 SentenceTransformer 编码后保存:
缓存文件名包含 encoder 短名,并用文件锁与原子替换保护并发生成。RQ-VAE 使用固定 seed 把 item embedding 做 95% train / 5% eval 随机切分;这只用于 tokenizer 重构监控,不是用户序列的 valid/test 协议。
训练¶
# TIGER tokenizer
python genrec/trainers/rqvae_trainer.py \
config/tiger/amazon/rqvae.gin --split beauty
# LCRec tokenizer(5 层、64-dim latent)
python genrec/trainers/rqvae_trainer.py \
config/lcrec/amazon/rqvae.gin --split beauty
# COBRA tokenizer(3 × 32)
python genrec/trainers/rqvae_trainer.py \
config/cobra/amazon/rqvae.gin --split beauty
trainer 支持互斥的 epoch 模式和 iteration 模式。当前下游配置使用 5000 epochs、前 50 epochs linear warmup、batch 1024。首次训练会聚合最多约 20,000 个样本做 codebook K-Means bootstrap;恢复 checkpoint 时不能再次初始化。
checkpoint 保存:
{
"epoch" or "iter": ...,
"model": model.state_dict(),
"model_config": model.config,
"optimizer": ...,
"scheduler": ...,
}
推理推荐使用:
from genrec.models.rqvae import RqVae
rqvae = RqVae.from_pretrained(checkpoint, map_location="cpu")
rqvae.eval()
sem_ids = rqvae.get_semantic_ids(item_embeddings).sem_ids # [N, C]
from_pretrained 会从 model_config 重建几何,并在第一次前向前禁用 K-Means bootstrap。手动构造后调用 load_pretrained 也会设置每层的初始化标志。不要使用旧文档曾出现的 load_from_checkpoint;代码中没有这个 API。
碰撞、去重与 codebook health¶
必须区分:
- layer usage:某层用了多少 code;
- dead code:某层未使用的 prototype;
- full-SID collision:多个 item 的完整 code tuple 相同;
- max collision group:一个 SID 桶最多包含多少 item。
每层 100% usage 仍可能有大量完整 SID collision。下游 headline 必须解析到 item;仅比较 SID tuple 会把同一碰撞桶里的错误 item 计作命中。
诊断命令:
python scripts/verify_codebook_health.py \
--kind rqvae \
--checkpoint out/tiger/amazon/beauty/rqvae/checkpoint_epoch_4999.pt \
--dataset-folder dataset/amazon --split beauty \
--encoder ./models_hub/sentence-t5-xl
具体参数以脚本 --help 为准。也可用 scripts/dump_sem_ids.py 和 scripts/report_sid_collisions.py 生成跨 tokenizer 对照。
get_semantic_ids_dedup 提供 LC-Rec 风格的后处理:固定前 C-1 层,对碰撞组的最后一层残差做 Sinkhorn 重分配。它可能仍无法拆开真正相同的 embedding,也可能制造与原唯一 item 的新碰撞,因此函数会检查并告警;不能把它描述为绝对唯一保证。
代码映射¶
| 层次 | 文件 | 对象 | 职责 |
|---|---|---|---|
| 模型 | genrec/models/rqvae.py |
RqVae |
encoder、residual quantization、decoder、checkpoint |
| 单层量化 | 同上 | Quantize |
距离、分配、四种 gradient path |
| 损失 | genrec/modules/loss.py |
ReconstructionLoss, QuantizeLoss |
重构与 commitment |
| 数据 | genrec/data/amazon.py |
AmazonItemDataset |
metadata embedding 与缓存 |
| 训练 | genrec/trainers/rqvae_trainer.py |
train |
epoch/iteration、warmup、eval、保存 |
| 健康检查 | scripts/verify_codebook_health.py |
— | usage、perplexity、collision |
| checkpoint 测试 | tests/test_rqvae_checkpoint.py |
— | 防止加载后重初始化码本 |
已知限制¶
- tokenizer 与下游 recommender 分阶段训练,目标并未端到端对齐;
- Sinkhorn 是 batch 级平衡,不等价于全目录全局均匀;
torch.compile包装 forward,对不支持的平台/调试器可能需要额外配置;- item embedding 与用户序列基于同一全目录 metadata,
global_temporal仍不是严格 inductive cold-item 协议; - 在 item 数只有一万级时使用 8192 等超大 codebook,浅残差层极易出现死簇/超级簇;本仓库相关结论见研究路线图;
- 更低 collision 不必然带来更高下游 Recall,必须同时报告 tokenizer health 与 item-level 推荐质量。