[doc] SID: add RQ-VAE / RQ-KMeans semantic-ID generation docs - #552
Conversation
Add models/sid_model to the MODEL toctree so the SID generation docs (sid_rqvae / sid_rqkmeans) are included in the Sphinx doc tree instead of being orphaned. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…yle CI - Add the FORGE paper (arXiv 2509.20904) to sid_rqvae.md references. - Run mdformat on sid_rqvae.md and sid_rqkmeans.md so `pre-commit run -a` (Code Style CI) passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| - save_checkpoints_steps / save_checkpoints_epochs: **必须项，设 `0` 关闭周期性保存**; 拟合好的码本只随训练结束时的最终 checkpoint 持久化 (周期性保存可能会忽略checkpoint落盘, 故关闭) | ||
| - feature_configs / feature_groups: 同 RQVAE, 但只需主物品 embedding 一组 (`deep`); 其拼接后的总维度即 K-Means 的向量维度 | ||
| - sid_rqkmeans: RQKMeans 模型参数 | ||
| - codebook: 每层聚类中心数; **列表长度即残差层数 (= SID 的位数)**; 示例 `[256, 256, 256]` (生产常用 `[8192, 8192, 8192]`); 支持非均匀如 `[256, 512, 1024]` (每层独立拟合一个 faiss.Kmeans) |
There was a problem hiding this comment.
需要增加一些描述对用户更加友好：
codebook：[256, 512, 1024]，256相当于一级类目的个数，512 相当于二级类目的个数。
总语义id的数量是：2565121024 = 134217728 。因此需要使用者根据自己的业务情况来设置语义id的数量。
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| > 评估指标自动输出 `mse` (重建均方误差)、`rel_loss` (相对 L1)、`unique_sid_ratio` (每个 batch 内不重复 SID 占比, 反映码本利用/多样性)。 | ||
|
|
||
| ## 示例 |
There was a problem hiding this comment.
这个 ## 示例 只给了配置文件 / 数据 / 模型输出，但没有训练命令也没有预测命令。然而 135-138 行描述的是预测产出 (codes)，且引用了 --reserved_columns（这是 tzrec.predict 的参数）。对比 sid_rqkmeans.md 提供了完整的 tzrec.train_eval 命令。
建议补上 tzrec.train_eval 训练命令（RQVAE 支持多卡，--nproc-per-node 与 RQKMeans 不同，用户无法直接套用）以及生成 SID 的 tzrec.predict 命令，否则读者无法复现训练和 codes 输出。
| 预测输出与输入 `dataset_type` 一致, 每行包含: | ||
|
|
||
| - codes: `array<int64>`, 即该物品的 SID, 长度等于 `codebook` 层数, 每个元素为对应残差层的中心下标 (取值范围 `[0, codebook_i)`)。例如 `[8, 31, 26]`。 | ||
| - item_id: 由 `--reserved_columns` 透传的原始物品 ID。 |
There was a problem hiding this comment.
这里引用了 --reserved_columns、上面 103 行也描述了预测输出，但全文只给了 tzrec.train_eval 命令，没有 tzrec.predict 命令。建议补一个生成 SID 的预测命令示例（含 --reserved_columns），让读者能真正产出 codes。
|
|
||
| ## 示例 | ||
|
|
||
| 模型的训练和评估方式同[local_tutorial](../quick_start/local_tutorial.md)，示例数据和配置参数如下： |
There was a problem hiding this comment.
这里说“训练和评估方式同 local_tutorial”，但 local_tutorial.md 用的是 --nproc-per-node=2，与本文 89/97 行的硬性要求 --nproc-per-node 必须为 1 直接冲突。照搬 tutorial 命令的读者会触发简介里描述的报错。建议在链接处加一句提醒：RQKMeans 须把 --nproc-per-node 改成 1。
Review: SID RQ-VAE / RQ-KMeans docsNice, thorough docs — I verified the config fields, defaults, and behavioral claims against Main actionable items (inline):
Minor / optional: the README supported-models table doesn't list the two new models; and docs aren't built on PR CI (only nightly via ReadTheDocs), so the new links/toctree aren't gated — I manually confirmed they're correct. |
| ### 训练参数 | ||
|
|
||
| ```bash | ||
| OMP_NUM_THREADS=$(nproc) \ |
- sid_rqvae.md: add tzrec.train_eval + tzrec.predict example commands. - sid_rqkmeans.md: add tzrec.predict command + MaxCompute (ODPS) example; expand codebook capacity guidance. - README: add a "Semantic ID (SID) Generation" section listing the two models. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brings in upstream alibaba#551 (v1.3.0: torch 2.12.1 / torchrec 1.7.0 / fbgemm 1.7.0 / numpy 2 / cu130 TRT), alibaba#556 (pandas>=3), alibaba#554 (graphlearn sampler fail-fast), alibaba#552 (SID RQ-VAE/RQ-KMeans docs), alibaba#553 (CI runtime cuts). No conflicts — local work is confined to the SID quantizer subsystem; upstream touched requirements, docs, CI, and framework files that don't overlap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3 participants
What
Adds user documentation for the two semantic-ID (SID) generation models and wires them into the Sphinx docs tree.
docs/source/models/sid_rqvae.mdSidRqvae(RQ-VAE) usage docdocs/source/models/sid_rqkmeans.mdSidRqkmeans(FAISS residual K-Means) usage docdocs/source/models/sid_model.rst语义ID生成toctree grouping the two docsdocs/images/models/rqvae.pngdocs/source/index.rstmodels/sid_modelunder the MODEL sectionDetails
item:embeddingarray columns), everysid_rqvaeconfig field, the train and SID-generation (tzrec.predict) commands, and thecodesoutput, plus the non-contrastive (item-only) variant.on_train_end. Documentsfaiss_kmeans_kwargs, thetrain_configsemantics (optimizers / epochs are framework formalities for this non-gradient model), and theN >= max(codebook)fit requirement.