基于语义 ID 的生成式推荐 (GRID)

GRID（基于语义 ID 的生成式推荐）是由来自 Snap Research 的一组科学家和工程师开发的、使用语义 ID 的生成式推荐系统最先进框架。该项目实现了从文本嵌入中学习语义 ID，并通过基于 Transformer 的生成模型生成推荐的新方法。

🚀 概述

GRID 通过三个主要步骤实现生成式推荐：

• 使用 LLM 生成嵌入：利用 Hugging Face 上可用的任何 LLM 将物品文本转换为嵌入。
• 语义 ID 学习：使用残差量化技术（如 RQ-KMeans、RQ-VAE、RVQ）将物品嵌入转换为层次化的语义 ID。
• 生成式推荐：使用 Transformer 架构以语义 ID 令牌的形式生成推荐序列。

📦 安装

先决条件

• Python 3.10+
• 支持 CUDA 的 GPU（推荐）

设置环境

# 克隆仓库
git clone https://github.com/snap-research/GRID.git
cd GRID

# 安装依赖
pip install -r requirements.txt

🎯 快速入门

1. 数据准备

按照预期格式准备数据集：

data/
├── train/       # 用户历史的训练序列 
├── validation/  # 用户历史的验证序列 
├── test/        # 用户历史的测试序列 
└── items/       # 数据集中所有物品的文本

我们提供了在 P5 论文 中探讨的预处理过的 Amazon 数据 [4]。该数据可从此 Google Drive 链接 下载。

2. 使用 LLM 生成嵌入

从 LLM 生成嵌入，这些嵌入随后将被转换为语义 ID。

python -m src.inference experiment=sem_embeds_inference_flat data_dir=data/amazon_data/beauty # 可用的数据包括 'beauty', 'sports', 和 'toys'

3. 训练并生成语义 ID

为步骤 2 中生成的嵌入学习语义 ID 聚类中心：

python -m src.train experiment=rkmeans_train_flat \
    data_dir=data/amazon_data/beauty \
    embedding_path=<步骤2输出路径>/merged_predictions_tensor.pt \ # 这可以在步骤2的日志目录中找到
    embedding_dim=2048 \ # 步骤2中使用的 LLM 的模型维度。本示例中使用 flan-t5-xl，其维度为 2048。
    num_hierarchies=3 \  # 我们训练 3 个码本
    codebook_width=256 \ # 每个码本有 256 行聚类中心  

生成 SIDs：

python -m src.inference experiment=rkmeans_inference_flat \
    data_dir=data/amazon_data/beauty \
    embedding_path=<步骤2输出路径>/merged_predictions_tensor.pt \ 
    embedding_dim=2048 \ 
    num_hierarchies=3 \  
    codebook_width=256 \ 
    ckpt_path=<刚刚获得的检查点> # 这可以在训练 SIDs 的日志目录中找到

4. 使用语义 ID 训练生成式推荐模型

使用学到的语义 ID 训练推荐模型：

python -m src.train experiment=tiger_train_flat \
    data_dir=data/amazon_data/beauty \ 
    semantic_id_path=<步骤3输出路径>/pickle/merged_predictions_tensor.pt \
    num_hierarchies=4 # 请注意，我们将 num_hierarchies 加 1，因为在上一步中，我们添加了一个额外的数字以去重生成的语义 ID。

4. 生成推荐

运行推理以生成推荐：

python -m src.inference experiment=tiger_inference_flat \
    data_dir=data/amazon_data/beauty \ 
    semantic_id_path=<步骤3输出路径>/pickle/merged_predictions_tensor.pt \
    ckpt_path=<刚刚获得的检查点> \ # 这可以在训练 GR 模型的日志目录中找到
    num_hierarchies=4 \ # 请注意，我们将 num_hierarchies 加 1，因为在上一步中，我们添加了一个额外的数字以去重生成的语义 ID。

支持的模型：

语义 ID：

1. One-Rec 中提出的残差 K-means [2]
2. 残差向量量化
3. 带有变分自编码器的残差量化 [3]

生成式推荐：

1. TIGER [1]

📚 引用

如果您在研究中使用 GRID，请引用以下内容：

@inproceedings{grid,
  title     = {Generative Recommendation with Semantic IDs: A Practitioner's Handbook},
  author    = {Ju, Clark Mingxuan and Collins, Liam and Neves, Leonardo and Kumar, Bhuvesh and Wang, Louis Yufeng and Zhao, Tong and Shah, Neil},
  booktitle = {Proceedings of the 34th ACM International Conference on Information and Knowledge Management (CIKM)},
  year      = {2025}
}

🤝 致谢

• 基于 PyTorch 和 PyTorch Lightning 构建
• 配置管理由 Hydra 提供
• 灵感来源于生成式 AI 和推荐系统的最新进展
• 本仓库的部分内容基于 https://github.com/ashleve/lightning-hydra-template 构建

📞 联系方式

如有疑问或需要支持：

• 在 GitHub 上创建问题
• 联系开发团队：Clark Mingxuan Ju (mju@snap.com)、Liam Collins (lcollins2@snap.com)、Bhuvesh Kumar (bhuvesh@snap.com) 和 Leonardo Neves (lneves@snap.com)。

参考文献

[1] Rajput, Shashank, 等. “具有生成式检索的推荐系统。” 神经信息处理系统进展 36（2023）：10299-10315。

[2] Deng, Jiaxin, 等. “Onerec：通过生成式推荐和迭代偏好对齐统一检索与排序。” arXiv 预印本 arXiv:2502.18965（2025）。

[3] Lee, Doyup, 等. “使用残差量化进行自回归图像生成。” IEEE/CVF 计算机视觉与模式识别会议论文集。2022 年。

[4] Geng, Shijie, 等. “作为语言处理的推荐（RLP）：统一的预训练、个性化提示与预测范式（P5）。” 第 16 届 ACM 推荐系统会议论文集。2022 年。

GRID 快速上手指南

GRID (Generative Recommendation with Semantic IDs) 是由 Snap Research 开发的基于语义 ID 的生成式推荐系统框架。它利用大语言模型（LLM）生成嵌入，通过残差量化技术学习分层语义 ID，并使用 Transformer 架构生成推荐序列。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.10 或更高版本
• GPU: 推荐使用支持 CUDA 的 NVIDIA GPU
• 深度学习框架: PyTorch 2.0+

安装步骤

1. 克隆项目

git clone https://github.com/snap-research/GRID.git
cd GRID

2. 安装依赖

建议使用虚拟环境（如 conda 或 venv），然后安装所需包。国内用户可使用清华源加速安装：

# 创建并激活虚拟环境 (可选但推荐)
conda create -n grid python=3.10 -y
conda activate grid

# 使用国内镜像源安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是基于 Amazon Beauty 数据集的最小化运行流程，涵盖从数据准备到生成推荐的四个核心步骤。

1. 数据准备

将数据集解压并放置于 data/ 目录下，结构需如下所示：

data/
├── train/       # 用户历史训练序列
├── validation/  # 用户历史验证序列
├── test/        # 用户历史测试序列
└── items/       # 数据集中所有物品的文本描述

提示: 项目提供了基于 P5 论文处理的 Amazon 数据集（包含 'beauty', 'sports', 'toys'），可从官方 Google Drive 链接下载并放入对应目录。

2. 生成 LLM 嵌入

使用 HuggingFace 上的任意 LLM 将物品文本转换为向量嵌入。以下示例使用默认配置处理 beauty 数据集：

python -m src.inference experiment=sem_embeds_inference_flat data_dir=data/amazon_data/beauty

执行完成后，请在日志目录中找到生成的 merged_predictions_tensor.pt 文件路径，供下一步使用。

3. 学习并生成语义 ID (Semantic IDs)

首先训练残差 K-Means 模型以学习语义 ID 中心点，随后生成具体的语义 ID。

训练语义 ID 模型：

python -m src.train experiment=rkmeans_train_flat \
    data_dir=data/amazon_data/beauty \
    embedding_path=<output_path_from_step_2>/merged_predictions_tensor.pt \
    embedding_dim=2048 \
    num_hierarchies=3 \
    codebook_width=256

注意：embedding_dim 需与步骤 2 中使用的 LLM 输出维度一致（例如 flan-t5-xl 为 2048）。

生成语义 ID：

python -m src.inference experiment=rkmeans_inference_flat \
    data_dir=data/amazon_data/beauty \
    embedding_path=<output_path_from_step_2>/merged_predictions_tensor.pt \
    embedding_dim=2048 \
    num_hierarchies=3 \
    codebook_width=256 \
    ckpt_path=<the_checkpoint_you_just_get_above>

请将 <...> 替换为实际的文件路径，检查点文件位于上一步训练的日志目录中。

4. 训练生成式推荐模型并推理

利用生成的语义 ID 训练 TIGER 推荐模型，并进行推理。

训练推荐模型：

python -m src.train experiment=tiger_train_flat \
    data_dir=data/amazon_data/beauty \ 
    semantic_id_path=<output_path_from_step_3>/pickle/merged_predictions_tensor.pt \
    num_hierarchies=4

注意：此处 num_hierarchies 设为 4，因为在生成语义 ID 时额外添加了一位数字用于去重。

生成推荐结果：

python -m src.inference experiment=tiger_inference_flat \
    data_dir=data/amazon_data/beauty \ 
    semantic_id_path=<output_path_from_step_3>/pickle/merged_predictions_tensor.pt \
    ckpt_path=<the_checkpoint_you_just_get_above> \
    num_hierarchies=4