Pcpp/music-transformer

🎵 基于序列建模与图增强的音乐推荐模型（Music Transformer）

---

📊 数据集来源（Dataset Source）

本模型基于公开音乐推荐数据集进行训练与评估，数据包含用户行为序列与音频内容特征，具体如下：

📌 数据来源

• 数据集名称：Yandex Music Dataset
• 发布平台：RecSys Challenge / Academic Dataset
• 数据类型：
  • 用户行为日志（listen / like / skip 等）
  • 音频特征向量（Audio Embedding）

---

📊 数据组成

模型训练所使用的数据包括：

1. 用户交互数据（Multi-event logs）

   • 记录用户与音乐的多种交互行为
   • 包含时间戳信息，用于构建序列

2. 音频特征数据（Audio Embedding）

   • 由 CNN 模型提取
   • 向量维度：128
   • 用于增强内容建模能力

---

⚙️ 数据处理流程

在训练前，对数据进行了如下处理：

• 按时间排序构建用户行为序列
• 去除异常值与缺失数据
• 划分训练集 / 验证集 / 测试集
• 构建负采样机制（1 正样本 + 999 负样本）
• 统计物品流行度用于分析与评估

---

⚠️ 使用声明

• 本数据集仅用于学术研究与学习用途
• 若用于商业用途，请遵循原始数据集的许可协议

---

📌 模型简介

本仓库提供用于音乐推荐系统的深度学习模型，旨在解决序列稀疏与冷启动问题。

模型基于以下三类信息构建：

• 用户行为序列（listen / like / skip）
• 音频内容特征（Audio Embedding）
• 图结构关系（Item-Item Graph）

通过融合多源信息，模型在推荐准确性与泛化能力上均取得显著提升。

---

🧠 模型结构

本项目包含三种模型：

1️⃣ ID-Only 模型（Baseline）

• 仅使用 item ID embedding
• 属于协同过滤范式
• 不具备冷启动能力

---

2️⃣ FDSA 模型（双流序列模型）

• 双流结构：

  • ID embedding 流
  • 内容 embedding 流（音频特征）

• 使用自注意力机制进行建模

• 提升序列建模能力

---

3️⃣ FDSA + Graph 模型（推荐使用 ⭐）

• 在 FDSA 基础上引入图嵌入
• 建模 item-item 高阶关系
• 显著提升冷启动表现

---

📊 输入与输出

输入

• 用户历史行为序列：

[user_id, item_1, item_2, ..., item_n]

• 可选：

  • 音频 embedding
  • 图结构 embedding

---

输出

• 下一首推荐歌曲的概率分布：

scores: [num_items]

---

⚙️ 使用方法

🔹 方法一：直接下载模型

import torch

model = torch.load(
    "https://huggingface.co/Pcpp/music-transformer/resolve/main/best_model_shared_gated_pro.pth",
    map_location="cpu"
)

---

🔹 方法二：使用 Hugging Face Hub（推荐）

from huggingface_hub import hf_hub_download
import torch

path = hf_hub_download(
    repo_id="Pcpp/music-transformer",
    filename="best_model_shared_gated_pro.pth"
)

model = torch.load(path)

---

📈 训练与评估设置

• 任务：Next-item Recommendation
• 候选集：1 正样本 + 999 负样本
• 损失函数：对比学习 + CrossEntropy
• 相似度函数：Cosine Similarity

---

🧪 评价指标

• Recall@K
• NDCG@K
• Coverage@K
• Popularity Bias

---

📌 适用场景

• 🎧 音乐推荐系统
• 🛒 序列推荐（电商 / 内容平台）
• ❄️ 冷启动用户建模

---

⚠️ 注意事项

• 模型基于离线训练数据，不包含实时更新机制

• 使用前需确保：

  • item ID 对齐
  • embedding 维度一致

---

👨‍🎓 作者信息

• 作者：彭乐
• 项目：毕业论文
• 方向：序列推荐 / 图神经网络 / 深度学习

---

📜 License

仅用于学术研究与学习目的

---

@misc{peng_music_recommendation_2026, title={Music Recommendation with Sequential Modeling and Graph Enhancement}, author={Peng Le}, year={2026} }