简介：这是一份面向推荐系统研究人员和本科毕业设计学生的项目资源，围绕基于属性与图神经网络（GNN）的推荐算法（AGNN）展开，旨在解决传统推荐算法难以捕捉用户与商品间复杂非线性关系的问题，可用于毕设参考、课题复现或算法优化。压缩包共19个文件，以Python脚本（模型、工具、数据处理等）、文本说明、CSV数据及npy中间文件为主，整体仅4.19MB，结构紧凑；其中脚本覆盖数据处理、模型搭建、训练与测试环节，README.md和文本文件提供使用指引。已有62人学习该资源，适合想要系统理解AGNN原理并动手实践的学习者。资源内包含完整的AGNN项目代码与说明，读者可基于自带数据快速跑通流程，并结合自身场景修改属性和图结构，进而提升推荐的个性化与精准度，具有较高的可操作性和参考价值。
1. 基于属性和图神经网络的推荐算法到底在解决什么问题
拿到“基于属性和图神经网络推荐算法”这个题目时，很多准备本科毕业设计的同学第一反应是：图神经网络我大概听过，属性又是什么？其实 AGNN（Attribute-aware Graph Neural Network）要解决的是一个非常具体的业务痛点：用户和物品之间不只有交互记录，还有大量画像属性，这些属性恰恰是纯行为序列模型最容易丢掉的冷启动线索。抖音首页和 B 站首页的推荐算法之所以能做到“新用户刷两条就能推得差不离”，靠的不只是日志里的点击，而是把注册时选的属性、视频标题里的标签一并喂进了模型。这篇笔记按我实际做过推荐算法项目的方法，把 AGNN 的数据构造、模型选型、训练评估和踩坑经验一条线讲全，新手能跟着复现，做毕设的人能直接从这份思路里找到自己的工作量。
2. AGNN 的模型结构是这么定的：属性嵌入、邻居聚合与打分预测
2.1 为什么纯交互图不够，要把属性单独拉出来
最常见的推荐基线是把用户和物品当成二部图里的两类节点，只有“买过”“点过”的边，然后用 GCN 之类的模型做消息传递。这个做法在行为稠密的场景下效果不差，但对本科毕设来说有两个硬伤：一是新用户新物品没有边，消息传递根本无处开始，输出全靠随机初始化；二是属性完全没用上，比如图书推荐里“作者”和“出版社”明明比一次偶然点击更能说明问题。
把属性引入图神经网络，常见做法有两种。第一种叫属性作为节点：把用户的年龄、性别、职业，物品的类别、标签、品牌，都建成独立节点，再与对应的用户或物品连边。第二种叫属性作为特征：每个节点维护一个属性向量，作为 GNN 的初始特征矩阵，在每一层聚合邻居时参与计算。AGNN 这类模型通常以前者为核心思路，因为它的优势在可解释性——你能够看出某个用户节点是通过“程序员”这个属性节点走到了“机械键盘”这个物品上。而纯特征式 GNN 虽然实现便宜，却很难在论文里画出一条清晰的推理链。
推荐系统的图神经网络研究里，有个老生常谈的结论：属性能带来协同过滤拿不到的泛化能力。协同过滤只在已知交互上做相似性传播，属性却能把两个从未有过共同行为的用户连起来，只要他们共享了同一批属性节点。这是 AGNN 值得做成毕设题目的根本原因。
2.2 属性向量化：one-hot、embedding 与数值归一化怎么选
属性节点和用户/物品节点都要变成向量才能进入图卷积。不同属性类型要分开处理，不能一把梭：
第一个是类别型属性，例如性别、学历、商品类目。当取值数量可控时，one-hot 是安全的，缺点是维度会膨胀，所以更多时候我建议直接套 embedding。给每个离散取值分配一个可学习的稠密向量，维度取 16 或 32，让模型自己去学习“理工科”和“程序员”在语义上的关联。注意 embedding 必须设在 torch.nn.Embedding 里，和模型一起参与训练，不能用 Word2vec 离线得到后冻死。
第二个是数值型属性，比如年龄、商品价格、观看时长。数值特征要归一化到 0-1 或做 z-score，否则图卷积里邻居求和会把量级大的特征放大到淹没其他维度。年龄这种周期性的特征，可以试试分桶再做 embedding，效果往往比直接拿原始数值好。
第三个是文本型属性，比如商品标题、用户简介。毕设级别不用上 BERT，把文本切词后做 TF-IDF 向量化就已经够用；如果跑的是小数据集，直接统计高频词做成多热向量（multi-hot）也不丢人。
把属性处理完后，每一个节点会有一个统一的初始特征向量。我的习惯是让初始维度对齐，例如用户与物品的特征维度都设为 64，属性节点按自己的类别单独建 embedding 层，最后通过一个线性层把属性向量投影到 64 维，保持整个图里的特征空间一致，后续卷积才能稳定。
2.3 AGNN 的前向计算：聚合、更新、预测三个步骤
AGNN 的前向过程可以拆成 predictable 的三段。第一段是邻居聚合：每个节点从自己的邻居那里收集信息，用求和或平均把邻居的特征向量揉成一个中间表示。第二段是更新：把中心节点自己的特征和聚合结果拼接，过一个带非线性激活的全连接层，得到这一层的输出。第三段是打分预测：把最后一次卷积得到的用户向量和物品向量做内积，或者过一层 MLP，得到用户对物品的偏好得分。
用公式写出来，第 l 层卷积对节点 i 的更新是：
$$ h_i^{(l+1)} = \sigma\left(W \cdot \text{CONCAT}\left(h_i^{(l)}, \sum_{j \in N(i)} \frac{1}{\sqrt{|N(i)||N(j)|}} h_j^{(l)}\right)\right) $$
这个形式和 GraphSAGE 的聚合很像，区别在于邻居集合 N(i) 不仅包含交互过的物品，还包含用户或物品挂着的属性节点。所以第 2 章第一小节说的“把属性单独建节点”，本质上就是扩大邻居集合的定义，让属性节点参与每一次消息传递。层数一般选两层：第一层让用户看到自己直接交互过的物品，第二层让用户通过共同物品或共同属性看到二跳邻居。更高层的收益在公开数据集上不明显，还会加重过平滑，后续避坑章节会专门说明。
3. 在做图训练之前：把原始数据表整理成 AGNN 需要的边表和属性矩阵
3.1 一份标准的输入清单：用户表、物品表、交互表、属性表
开始写模型代码之前，先要把原始数据整理成四份结构清晰的输入。对本科毕设来说，拿 MovieLens-1M 或者 Book-Crossing 这类公开数据集做实验是最常见的，因为它们自带用户属性和物品属性。我一般会把数据预处理拆成四个阶段：
第一步，用户表拆出用户 ID 和属性字段；第二步，物品表拆出物品 ID 和属性字段；第三步，交互表只保留 user_id、item_id、rating 或 timestamp；第四步，把属性字段抽出来创建属性节点，并生成“用户-属性”和“物品-属性”两类边。
下面这段代码演示了如何构造属性节点和边表：
import pandas as pd # 假设 users.csv 有: user_id, gender, age, occupation users = pd.read_csv("users.csv") items = pd.read_csv("items.csv") attr_node_id = 0 attr_dict = {} # 属性取值 -> 全局节点 ID # 给每个属性取值分配一个节点 ID for col in ["gender", "age", "occupation"]: for value in users[col].unique(): attr_dict[f"{col}:{value}"] = attr_node_id attr_node_id += 1 # 生成 用户 -> 属性 的边 user_attr_edges = [] for _, row in users.iterrows(): u = row["user_id"] for col in ["gender", "age", "occupation"]: attr = f"{col}:{row[col]}" user_attr_edges.append((u, attr_dict[attr])) print(f"属性节点数量: {attr_node_id}, 用户-属性边: {len(user_attr_edges)}")这段代码的核心思想是：每个属性取值都单独成为一个节点，用字符串映射保证同一个取值共享同一个节点 ID。注意不要每行数据都新建一个属性节点，“年龄=25”这个节点全图只能一个，否则属性节点之间无法形成语义共享。边表存成两个数组 src 和 dst 即可，之后可以直接转成 PyTorch Geometric 的 edge_index。
3.2 负采样策略：随机采样、热门打压与批次内采样
推荐模型训练需要正样本和负样本。正样本是用户真实交互过的物品；负样本是用户没交互过的物品，需要人工构造。最简单的是均匀随机采样，但对热门物品不公平，因为热门物品被选作负样本的概率也高，会让模型误以为热门物品“不好”。这里有个毕设答辩常被问的点：热门物品曝光多、正样本也多，负采样如果不做修正，模型对热门物品的打分会被过度打压。
我一般用下面这种简单有效的负采样策略：每个正样本配 K 个负样本，K 取 4 到 8；负样本从“当前用户没交互过”的物品里按非均匀概率抽取，概率与物品流行度的 0.75 次幂成正比。这个 0.75 来自 word2vec 负采样的经典做法，能缓解热门物品被过度采样的问题。代码层面只需要在采样前算一个物品流行度列表，再按概率取数即可：
import numpy as np # 统计物品流行度 item_count = interaction.groupby("item_id").size() item_pop = item_count / item_count.sum() sample_prob = item_pop ** 0.75 sample_prob = sample_prob / sample_prob.sum() def sample_negatives(user_id, pos_items, num_neg=4): """为单个用户采样负样本，排除已交互的正样本""" candidates = sample_prob.index.difference(pos_items).to_numpy() neg = np.random.choice(candidates, size=num_neg, replace=False, p=sample_prob.loc[candidates].to_numpy()) return neg.tolist()这里的 p 参数就是采样权重，已经被 0.75 次幂平滑过。需要注意 replace=False 要求候选物品数比负样本数大，冷门数据集上容易报错，可以把负样本数调小或允许有放回采样。
3.3 时间切分和时间泄漏：毕设答辩最容易被追问的点
数据划分是推荐系统里最容易被轻视、也最容易被答辩老师抓住破绽的环节。很多毕设项目直接对交互记录做随机切分，这是不对的。推荐系统关心的是预测未来行为，训练集里的交互时间如果在测试集之后，模型就是在“用未来预测过去”，指标虚高得离谱。
正确做法是按时间戳切分。训练集取所有时间戳前 80% 的交互，测试集取后 20% 的交互。用户和物品属性不受时间切分影响，可以全量使用。如果要更严谨，还可以做 leave-one-out：对每个用户，把最后一次交互拿出来当测试，其余当训练。这种划分方式能比较真实地模拟“用户行为到某一刻为止”的推荐场景。
4. 用 PyTorch 把 AGNN 跑起来：最小可复现代码与训练配置
4.1 基于 PyG 的模型骨架：两层卷积加一个预测头
现在进入核心代码环节。我习惯用 PyTorch Geometric 搭建图神经网络模型，因为它把 edge_index 的稀疏计算封装好了，不需要自己写消息传递，但又能通过重写 forward 理解内部逻辑。下面是一个最小可用的 AGNN 模型：
import torch import torch.nn as nn import torch.nn.functional as F from torch_geometric.nn import SAGEConv class AGNN(nn.Module): def __init__(self, in_dim, hidden_dim, out_dim): super().__init__() self.conv1 = SAGEConv(in_dim, hidden_dim) self.conv2 = SAGEConv(hidden_dim, out_dim) # 打分 MLP：把用户和物品向量拼起来，映射到偏好得分 self.score_mlp = nn.Sequential( nn.Linear(out_dim * 2, 64), nn.ReLU(), nn.Linear(64, 1) ) def forward(self, x, edge_index): # 第一层邻居聚合 x = self.conv1(x, edge_index) x = F.relu(x) x = F.dropout(x, p=0.2, training=self.training) # 第二层聚合 x = self.conv2(x, edge_index) return xSAGEConv 是 GraphSAGE 的聚合算子，对属性节点和交互边混在一起的图比较友好，因为它对邻居做的是可学习权重的聚合，比 GCNConv 的均值池化多了一个线性变换。in_dim 是初始特征维度，hidden_dim 我习惯取 64，out_dim 取 32。注意 edge_index 的构建方式：把用户-物品边、用户-属性边、物品-属性边三类边全部拼接，节点编号要统一映射到同一个空间。
4.2 训练循环：BCE 损失、负样本配对与批次遍历
训练循环的关键是把正负样本组织成二分类任务。对每个用户，把正样本和负样本都送进模型，计算用户向量与物品向量的内积或 MLP 分数，优化目标让正样本分数高、负样本分数低。我用 BCEWithLogitsLoss 而不是普通 BCELoss，因为前者内部做了 sigmoid 的数值稳定处理，梯度更稳：
def train_one_epoch(model, x, edge_index, train_data, optimizer, device): model.train() total_loss = 0 for user_id, pos_items, neg_items in train_data: user_id = torch.tensor([user_id] * (len(pos_items) + len(neg_items))).to(device) item_ids = torch.tensor(pos_items + neg_items).to(device) labels = torch.tensor([1] * len(pos_items) + [0] * len(neg_items)).float().to(device) emb = model(x.to(device), edge_index.to(device)) user_vec = emb[user_id] item_vec = emb[item_ids] # 拼接后过 MLP，得到每个样本的偏好得分 score = model.score_mlp(torch.cat([user_vec, item_vec], dim=1)).squeeze() loss = F.binary_cross_entropy_with_logits(score, labels) optimizer.zero_grad() loss.backward() optimizer.step() total_loss += loss.item() return total_loss / len(train_data)这份代码里有一个隐性前提：用户向量和物品向量都来自同一个 embedding 矩阵 emb，也就是图卷积的输出。所以你不需要单独做 user embedding 和 item embedding，节点 ID 查表即可。负样本数量与正样本数量要配对，否则标签比例失衡；这里用拼接的方式把正负样本放进同一次 forward，节省计算。
训练配置上，优化器选 Adam，学习率从 1e-3 起步，每个 epoch 结束后监控损失是否下降，如果下降太慢再调。Cora 这种小图用全图训练没压力，但 MovieLens 加上属性节点后全图的边数会到百万级，必须用 batch 或邻居采样，否则显存不够，这点在第 5 章会展开。
4.3 评估指标：HitRate、Recall@K 与 NDCG@K 怎么算
推荐系统评估不能只看准确率，因为负样本是采样出来的，准确率会被采样比例直接影响。我常用的指标有三个：HitRate@K 表示测试集里的正样本是否出现在 Top-K 推荐列表里；Recall@K 表示用户的所有正交互里被推荐出来的比例；NDCG@K 则在 Recall 基础上加了位置折扣，推荐列表中正样本排得越靠前得分越高。
def evaluate(model, x, edge_index, test_dict, K=10): model.eval() emb = model(x, edge_index) hr_sum, ndcg_sum, num_users = 0, 0, len(test_dict) with torch.no_grad(): for user_id, pos_items in test_dict.items(): if not pos_items: continue scores = [] for item_id in range(num_items): user_vec = emb[user_id] item_vec = emb[item_id] score = model.score_mlp(torch.cat([user_vec, item_vec], dim=0)).item() scores.append((item_id, score)) scores.sort(key=lambda x: x[1], reverse=True) top_k = [item_id for item_id, _ in scores[:K]] hit = 1 if set(pos_items) & set(top_k) else 0 hr_sum += hit # 简化 NDCG：只计算命中的位置贡献 max_dcg = sum(1.0 / math.log2(i + 2) for i in range(min(len(pos_items), K))) dcg = 0.0 for i, item_id in enumerate(top_k): if item_id in pos_items: dcg += 1.0 / math.log2(i + 2) ndcg_sum += dcg / max_dcg if max_dcg > 0 else 0 return hr_sum / num_users, ndcg_sum / num_users这里有个明显的效率问题：对每个用户遍历全部物品打分，毕设数据量可以接受，但真实场景要用 faiss 这类向量检索库。答辩时如果说清楚这是简化实现，同时点明大规模场景需要替换为近似最近邻检索，老师会认可你的工程认知。
5. 训练 AGNN 最常见的 5 个坑：过平滑、稀疏邻居、负采样与数据泄漏
5.1 过平滑：层数一深，所有节点向量都变得差不多
现象：把 GNN 层数从两层加到四层，验证集 Recall@10 不升反降，而且每层可视化出来几乎是一团浆糊。
原因：图卷积每一层都让节点聚合邻居信息，层数加深后每个节点的表示变成了一大片邻域的“叠加平均”，个性化信息被磨平，这就是经典的过平滑问题。对推荐场景来说，用户的兴趣差异恰恰是个性化的核心，过平滑等于把兴趣差异抹掉了。
解决：控制在两层以内，最多三层；用残差连接把上一层的表示传下来；或者在归一化系数上做调整，降低邻居信息的权重。AGNN 里属性节点本身会放大邻居聚合的范围，所以层数更要保守。如果一定要加深，可以用 DropEdge——训练时随机丢掉一部分边，破坏过平滑的收敛路径。
5.2 冷启动用户根本走不出第一步
现象：新注册用户只有少量属性、没有任何交互，模型对这类用户给出的推荐列表几乎是随机物品。
原因：图神经网络的消息传递依赖边，没有交互边就没有邻居，属性边虽然能连到属性节点，但聚合到的信息有限。这其实是属性感知模型的典型边界：属性只能缓解冷启动，不能消灭冷启动。
解决：对冷启动用户单独走一个分支，直接拿属性节点作为输入，跳过交互聚合。做法是在 forward 里判断用户节点是否有邻居，如果有邻居就走图卷积，没有就直接用属性向量过 MLP。这个小分支写进模型，既能提升冷启动指标，又是毕设论文里一个很完整的创新点。
5.3 负样本数量翻车：正负比失衡让模型学成“全盘皆负”
现象：训练损失降得很低，但评估时 HitRate 几乎为 0，模型把绝大多数候选项都打成了低分。
原因：负采样数量过大或采样时误把用户未交互但实际喜欢的物品当成了负样本。正负比 1:10 会让模型倾向输出负分，而 BCEWithLogitsLoss 的决策面又比较敏感，最终推荐列表里全是“安全”的低分物品。
解决：把负样本数控制在 1:4 到 1:8，先跑通再往上加。负样本采样的另一个细节是避免把测试集的正样本当作负样本，所以采样前一定要用训练集交互记录排除掉测试正样本。你可以把测试集的 user-item 配对集合显式传进负采样函数，再做一次差集运算。
5.4 数据泄漏：全局随机切分让你成了“假冠军”
现象：切分方式从时间切分改成全局随机切分之后，HitRate@10 涨了 10 个点，论文写出来很好看。
原因：随机切分把同一个用户的交互同时放进训练和测试，模型在训练时其实“见过”测试物品的邻居信息，相当于提前知道了答案。这是推荐系统里最典型的标尺翻车，答辩时被问一句“你的测试集用户是否出现在训练集里”就容易暴露。
解决：用时间切分或 leave-one-out，保证测试样本的时间戳晚于任何一条训练交互。属性数据和图谱结构可以用全量，但交互边的切分必须按时间。建议把两种划分方式都做一遍，在论文里对比，证明时间切分下指标更稳健，这也是加分项。
5.5 显存爆炸：全图训练百万边，CUDA 直接 Out of Memory
现象：模型代码没问题，一跑 MovieLens 全量数据，GPU 直接报 CUDA out of memory 或者运行到一半被 kill。
原因：全图卷积把所有节点和边的中间表示都放在显存里，百万级边数对显存压力非常大。开源数据集还能勉强跑，一旦你自己爬了电商或视频网站的数据，边数到千万级就基本不可能全图训练。
解决：换成 NeighborLoader 做邻居采样，每个 batch 只取目标节点的固定数量邻居，例如第一层采样 10 个邻居，第二层采样 5 个。这样计算图被限制在小范围，显存占用稳定，还能顺便缓解过平滑。NeighborLoader 的 num_neighbors 参数设成 [10, 5] 是我常用的配置，训练速度也明显快于全图。
6. 毕业设计验收前：用三组对照实验证明 AGNN 真的有用
到了论文和答辩环节，最重要的是用实验证明“属性”和“图神经网络”这两个关键词缺一不可。我的习惯是固定同一个数据集、同一个负采样配置，跑三组对照：第一组去掉属性节点，只保留用户-物品交互边，用普通 GraphSAGE 做基线；第二组保留属性节点但把图卷积换成 MLP，验证属性是否真正通过图结构发挥作用；第三组才是完整的 AGNN。三组之间只允许模型结构变化，训练轮数、学习率、损失函数全部保持一致，否则对比无效。
记录指标时不要只看最终 HitRate，还要拆出冷启动子集：把训练交互数小于 5 的用户单独算一组指标。如果 AGNN 在正常用户上提升 5 个点、在冷启动用户上提升 15 个点，这比整体指标更有说服力。调参记录里保存好每组实验的随机种子和超参数，答辩老师问“你这个结果是不是每次跑都不一样”的时候，你能直接翻出种子给他看。
我最后的一个习惯是：跑完实验后把用户向量和物品向量各抽两个样本做 t-SNE 可视化。不是给老师看美观图，而是确认同类属性的用户向量确实聚到了一起——这能证明图卷积利用到了属性信息，而不只是模型结构变复杂带来的随机提升。如果可视化出来一团乱，说明属性嵌入或聚合方式有问题，赶紧回头调。希望这些踩坑经验能帮你的 AGNN 从“跑起来”走到“讲得清”，毕业设计这条路走顺了，后面做推荐算法相关工作也会轻松很多。
本文还有配套的精品资源，点击获取
