RQ-KMeans:非神经残差量化器¶
定位与状态¶
| 项目 | 内容 |
|---|---|
| 任务 | 将 catalog item embedding 离散化为 semantic ID |
| 类型 | 多层 residual K-Means;不是推荐模型,也不是 nn.Module |
| 输入 / 输出 | [N,D] 浮点嵌入 → [N,C] 整数 code |
| 当前消费者 | OneRec SFT、CLM 与 GRPO 数据适配器 |
| 默认配置 | 3 层、每层 256 个 centroid、Qwen3-Embedding-8B |
| 评估 | code usage、最大簇频率、collision;不单独报告推荐 Recall |
RQ-KMeans 是上游 tokenizer。它没有用户历史输入,也不会输出 next-item 排名,因此不能与 SASRec、TIGER 或 OneRec 放在同一推荐效果表。当前实现状态见模型实现状态。
来源与使用边界¶
残差量化是经典向量量化思路:每层量化上一层残差,多个 code 联合近似原向量。当前类是本仓库的轻量工程实现,用来支撑 OneRec 管线;它不是某篇论文官方代码的逐行移植。OpenOneRec 与 MiniOneRec 的公开工作都讨论了生成式推荐中的 SID 构造,但本仓库的 encoder、\(K\)、dead-cluster 修复和拟合范围应按这里的代码理解,而不能从论文默认值反推。
与 RQVAE 最大的区别是:RQ-KMeans 直接在冻结的外部 item embedding 上聚类,没有可训练 encoder/decoder、重构 loss 或 commitment loss。速度更快、状态更简单,但表示能力完全受外部 embedding 空间与 K-Means 假设约束。
核心算法¶
给定 \(N\) 个 \(D\) 维嵌入 \(x_i\),令第一层残差 \(r_i^{(0)}=x_i\)。第 \(\ell\) 层求解
并分配
最终 SID 为 \((c_i^{(0)},\ldots,c_i^{(C-1)})\),重构近似为各层 centroid 之和。assign() 用
构造 [N,K] 距离矩阵后取 argmin,再逐层更新 residual。
backend 选择¶
RqKmeans(backend="auto") 按 \(N\times K\) 选择实现:
- 小于 \(5\times10^7\):scikit-learn
KMeans,k-means++ 初始化,默认n_init=10。 - 否则:
MiniBatchKMeans,batch 默认 4096,仍使用默认 10 次初始化。
trainer 没有把 backend 和 n_init 暴露为 Gin 参数;它只传层数、\(K\)、随机种子、最大迭代数和 batch size,所以常规命令总是走 auto。
dead-cluster 重置¶
每层首次拟合后,实现统计没有任何 item 分配到的 centroid。若 dead_reinit=True:
- 计算每个 item 到当前已分配 centroid 的平方误差;
- 依误差从大到小选择 residual point,覆盖 dead centroid;
- 用修补后的 centroid 重算完整
[N,K]距离并重新分配。
代码注释称其为额外 Lloyd step;精确地说,当前实现只做一次全量 assignment,没有在重新分配后再计算簇均值。因此这是 dead centroid reseeding + reassignment,不是完整收敛的第二轮 K-Means。
数据流¶
flowchart LR
A[Amazon item metadata] --> B[deterministic item text]
B --> C[external text encoder]
C --> D[item embedding cache]
D --> E[layer 0 K-Means]
E --> F[residual]
F --> G[layer 1 ... C-1]
G --> H[rqkmeans.pt]
H --> I[assign every catalog item]
I --> J[SID-aware recommender dataset]
AmazonItemDataset 以 title、price、sales rank、brand 和 categories 等 metadata 组装文本,并缓存 encoder 输出。trainer 以 train_test_split="all" 加载完整 catalog,而不是只量化训练交互出现过的 item。这能给所有候选生成 SID,但也是 transductive catalog tokenizer:即使使用 global-temporal interaction split,未来交互中的 item metadata 仍可能参与聚类。
embedding cache 文件名包含 encoder 路径 basename,避免不同 encoder 的常见混用;但 checkpoint 本身不记录 encoder 身份,资产 provenance 仍须由配置和 run metadata 保存。
代码映射¶
| 层次 | 文件 / 符号 | 职责 |
|---|---|---|
| 核心 | RqKmeans |
fit、assign、保存/加载、collision 统计 |
| 输出类型 | RqKmeansOutput |
sem_ids: np.ndarray[N,C] |
| 数据 | AmazonItemDataset |
构造/缓存完整 catalog 的文本向量 |
| trainer | fit_rqkmeans |
读取 embedding、拟合、打印健康度、保存 |
| 默认配置 | rqkmeans.gin |
3×256 与 Qwen3 embedding 路径 |
| 诊断 | verify_codebook_health.py |
每层 usage、dead codes、最大频率、collision |
| 诊断 | report_sid_collisions.py |
prefix collision、组大小与多来源对比 |
save() 只写 n_layers、codebook_size 和 centroid 数组。load() 包含 NumPy 2.x pickle 名称的兼容别名,然后按 CPU 加载;它不会验证输入 embedding 维度以外的 encoder 语义一致性。
拟合与健康检查¶
# 默认 Amazon Beauty:Qwen3-Embedding-8B,3×256
python genrec/trainers/rqkmeans_trainer.py \
config/onerec/amazon/rqkmeans.gin --split beauty
# 重新从同一 encoder 的 catalog embedding 分配并检查每层健康度
python scripts/verify_codebook_health.py \
--kind rqkmeans \
--checkpoint out/onerec/amazon/beauty/rqkmeans/rqkmeans.pt \
--dataset-folder dataset/amazon \
--split beauty \
--encoder ./models_hub/Qwen3-Embedding-8B
可用 Gin 覆盖直接做 \(K\) 或层数消融:
python genrec/trainers/rqkmeans_trainer.py \
config/onerec/amazon/rqkmeans.gin --split sports \
--gin 'fit_rqkmeans.codebook_size=128' \
--gin 'fit_rqkmeans.n_layers=4' \
--gin 'fit_rqkmeans.save_dir_root="out/onerec/amazon/{split}/rqkmeans_k128_c4"'
改变 \(C\) 或 \(K\) 后,下游 OneRec 的 dataset、模型 code token 数和 checkpoint 目录也必须同步;只覆盖拟合器会让 token 越界或把不同 code 空间误配。
最低健康报告¶
每次新 tokenizer 至少记录:
- 每层
used_codes / K与 dead-code 数; - 每层
max_freq和覆盖 50% item 所需 code 数; - 完整 SID 的 unique 数、collision rate 与最大 collision group;
- prefix depth 1..\(C\) 的 collision rate;
- 最终 residual norm,以及 encoder、catalog 版本、seed 和拟合 backend。
仓库诊断脚本把 usage < 80% 或最大单簇频率 > 10% 标成 collapse signature;这是运维告警阈值,不是统计学定义或论文结论。
项目在 Amazon Beauty 约 1.2 万 item 上曾观察到 \(K=8192\) 的浅 residual 层使用率下降和 super-cluster;改用 \(K=256\) 后健康度明显改善。因此当前配置选择 256。该观察不能推出“所有小 catalog 必然在 8192 崩溃”,新数据必须实测。
输出与依赖¶
默认输出目录为 out/onerec/amazon/<split>/rqkmeans/:
rqkmeans.pt:centroid checkpoint;results.json:collision、unique SID、总 item 数、最大碰撞组与 run config;- stdout:逐层 residual norm、usage 和最大簇频率。
依赖 NumPy、PyTorch(仅用于序列化)、scikit-learn 和外部文本 encoder 所需的 Transformers/Sentence-Transformers 数据路径。核心聚类在 CPU/scikit-learn 上执行;GPU 可用并不会自动切换到 GPU K-Means。
与 RQVAE 及论文式 tokenizer 的差异¶
| 方面 | RQ-KMeans | RQVAE |
|---|---|---|
| 量化空间 | 外部原始 item embedding | learned encoder latent |
| 优化 | 每层独立 K-Means | 重构 + quantization/commitment 的梯度训练 |
| decoder | 无 | 有,可监控重构 |
| 层间训练 | 顺序拟合 residual | 联合前向与训练 |
| 状态 | centroid 数组 | 网络、codebook 与训练状态 |
| 失败模式 | dead/super clusters、外部 embedding 偏置 | codebook collapse、重构与离散目标权衡 |
本仓库实现也没有 OPQ 旋转、product subspace、端到端 recommendation loss 或可学习 codebook。RPG 使用的是另一条 FAISS OPQ 路径,不共享该 checkpoint。
已知限制与常见坑¶
K > N直接失败 → scikit-learn 无法拟合比样本更多的 cluster。先按 catalog 大小选择 \(K\)。- 内存突然升高 →
assign()和 dead reinit 都显式构造[N,K]距离;大 catalog 即使拟合用 MiniBatch,分配仍可能成为内存瓶颈。 - 拟合耗时远超预期 → auto 进入 full K-Means 且
n_init=10。trainer 目前不能从 Gin 设n_init/backend;需要扩展fit_rqkmeans接口,而不是误以为batch_size会强制 MiniBatch。 - 加载成功但 SID 全变 → checkpoint 不记录 encoder;相同维度的不同 encoder 也能运行。核对原始 gin、embedding cache basename 和 run provenance。
- dead code 重置后仍有 dead code → 一次 reassignment 不保证每个新 centroid 最终得到 item。以健康检查结果为准,不要仅凭
dead_reinit=True宣称 100% usage。 - collision 很低却推荐不好 → 离散唯一性不等于语义可预测性;还要检查每层熵、前缀平衡与下游 item-level 指标。
- 修改 tokenizer 后旧 OneRec checkpoint 还能加载 → token 数相同只代表形状相容,centroid 语义已经变化。必须重新训练或建立显式映射,禁止静默复用。
- 把 tokenizer 指标当推荐指标 → collision/usage 只描述 ID 空间,不包含用户偏好学习。
扩展点¶
- 将
backend、n_init、dead_reinit暴露到 trainer/Gin,并把它们写入 checkpoint;需保持旧 checkpoint load 兼容。 - 把距离计算改成 chunked 或 GPU 实现,测试结果需与 NumPy 全量
argmin一致,尤其处理距离并列时。 - 在 dead reinit 后增加真正的 centroid update/多轮 Lloyd 迭代,并用固定 seed 比较 inertia、usage 和 collision。
- 支持 train-visible-only tokenizer 时,必须定义 unseen item 的 assignment、catalog cutoff 和 metadata 可见性。
- 为 checkpoint 增加 encoder identifier、embedding dimension、catalog fingerprint 和归一化设置;加载时 fail fast。
- 新增模型单测应覆盖保存/加载一致性、两层 residual 手算样例、\(K>N\) 错误、dead cluster 与 collision 统计。