简介这是一份以图神经网络为核心的完整代码资源面向具备一定深度学习基础、希望入门或进阶GNN的开发者与研究人员可用于解决图数据建模、节点分类与嵌入表示学习等问题。资源包为ZIP格式共323个文件绝大多数为JSON数据文件另有少量存储配置文件整体约2.17MBJSON文件多用于存储图结构、节点属性与边信息便于快速构造实验数据。目前已有2711人参与学习具备一定的实践参考价值。压缩包内代码涵盖图数据的读取与预处理、GNN模型构建、消息传递与聚合操作、节点嵌入生成以及训练验证流程并涉及GCN、GAT等常见变体思路可帮助读者从零搭建一个可运行的GNN项目理解邻居聚合与特征更新的核心原理适合作为算法学习与实验复现的参考资料。1. GNN图神经网络到底在解决什么问题从一次反欺诈特征工程说起我最早被GNN图神经网络吸引是做反欺诈特征工程时传统机器学习怎么调参都用不上“谁给谁转了钱”这种关系。一个用户是否异常往往看的是他的钱流入了哪些人的账户那些账户又连着哪些设备——这种关系推理正好是图神经网络的看家本领。GNN的核心构想一句话能讲完每个节点的表示由自己和邻居的特征反复聚合而成。这篇笔记以“GNN图神经网络代码完整”为主干从建图、选模型到跑通训练给出一套本地可复现的最小代码。适合刚看完论文想动手、又不想一上来啃源码的同学也适合跑过图像或序列模型、想对比图模型效果的工程师。读完你能回答三个问题数据长什么样才能喂给GNN、三种主流模型怎么选、训练时哪些报错值得先查。2. 图的表示与消息传递先搞懂数据格式再谈模型选型2.1 图的三种基本表示邻接矩阵、边索引与特征矩阵GNN的输入和图像、文本完全不同。图像是规则的网格文本是变长序列图则是一堆节点和一堆边的集合。最常见的落库方式有三种邻接矩阵、邻接表、COO边索引。邻接矩阵直观但社交网络动辄百万节点一个邻接矩阵需要n的平方量级的内存完全存不下。所以PyG里约定用COO格式也就是2×E的边索引一行存起点、一行存终点。E条边有多少条就存多少列内存随边数线性增长这才是图数据该有的形态。import torch from torch_geometric.data import Data # 5个节点7条边按COO格式组织 edge_index torch.tensor([ [0, 1, 1, 2, 3, 3, 4], # 起点行 [1, 0, 2, 1, 4, 2, 3] # 终点行 ], dtypetorch.long) # 每个节点带8维特征维度自己定文本、向量、统计特征都行 x torch.randn(5, 8) data Data(xx, edge_indexedge_index) print(data)这段代码定义了一张有5个节点、7条有向边的图。PyG的Data对象会把x和edge_index打包edge_index[0]是源节点edge_index[1]是目标节点。注意这里有向边是成对出现的[0,1]和[1,0]各一条模拟的是无向关系。真实项目里如果从数据库导入边表通常一条记录只存一次跑模型前要记得把反向边补上不然消息只能朝一个方向传精度会打折扣。特征矩阵x是GNN和传统图算法的分水岭。DeepWalk、Node2Vec那一代方法只学拓扑结构拿到的是节点编号对应的嵌入新来的节点没法直接推。而GNN的输入特征可以是任意数值向量用户画像、文本embedding、时序统计都往里塞。**没有特征也能跑但效果会退化到“只按结构聚类”的程度。**另外还要注意节点编号必须是0到N-1的连续整数业务表里的用户ID动辄十几位不能直接当索引喂给PyG。2.2 GCN、GAT、GraphSAGE三种主流模型怎么选很多教程上来就贴GCNConv的代码但选型才是决定效果上限的一步。三种模型的消息聚合机制完全不同适用的图结构也不一样。我整理过一张对比表直接照着选就行模型核心机制适合的场景主要代价GCN按度归一化的均值聚合同质图、层数浅、所有邻居一视同仁邻居权重固定无法区分重要性GAT注意力机制动态加权邻居重要性差异大、异质图显存占用高训练明显更慢GraphSAGE采样固定数量邻居再聚合支持inductive超大图、节点会新增的生产环境采样随机性带来方差需调采样数GAT拆开看就是Transformer里的自注意力套到图上每个节点对每个邻居算一个注意力分数再用softmax归一化后加权求和。你如果看过Transformer代码再看GAT几乎零门槛唯一的区别是Transformer算的是序列位置之间的注意力GAT算的是沿边传播的注意力。GraphSAGE则是为大图而生的它不再把整张图塞进显存而是每层为每个目标节点随机采样固定数量的邻居所以新节点到来时不用重新训练全图这也是它在工业界更常见的原因。GCN最经典的定位是“快速拿到baseline”。它的归一化逻辑是对称拉普拉斯归一化也就是同时除以源节点和目标节点的度的平方根数学上能保证数值稳定但代价是每个邻居的贡献被固定成了度相关的常数。在社区发现、分子性质预测这类同质图任务上GCN不输GAT。我的建议是第一版永远先用GCN跑通链路再换GAT看能不能涨点别一上来就上注意力。2.3 用PyG写一个最小消息传递层PyG的核心抽象叫MessagePassing所有图卷积都可以拆成三件事每条边发消息、每个节点收消息、更新自身表示。理解这三步后面调参出问题就知道该去哪一层排查。下面这个MyGCNConv是GCN卷积的最小实现import torch from torch_geometric.nn import MessagePassing from torch_geometric.utils import add_self_loops, degree class MyGCNConv(MessagePassing): def __init__(self, in_channels, out_channels): super().__init__(aggradd) # 聚合方式sum self.lin torch.nn.Linear(in_channels, out_channels) def forward(self, x, edge_index): # 第一步每条边加上自环保证节点能收到自己的特征 edge_index, _ add_self_loops(edge_index, num_nodesx.size(0)) # 第二步计算对称归一化系数 1/sqrt(deg(src) * deg(dst)) row, col edge_index deg degree(col, x.size(0), dtypex.dtype) deg_inv_sqrt deg.pow(-0.5) deg_inv_sqrt[deg_inv_sqrt float(inf)] 0 norm deg_inv_sqrt[row] * deg_inv_sqrt[col] return self.propagate(edge_index, xx, normnorm) def message(self, x_j, norm): # 第三步线性变换后乘归一化系数发给目标节点 return norm.view(-1, 1) * self.lin(x_j)这段代码把GCN的消息传递拆得很清楚aggradd决定邻居消息如何聚合add是求和也可以换mean或maxadd_self_loops给每个节点补一条指向自己的边否则第一轮聚合时节点完全看不到自己的特征norm就是对称归一化系数防止高度数节点主导聚合结果。message函数里先做线性变换再乘系数这一步的顺序会影响数值稳定性实测先变换后归一化比先归一化后变换更稳。官方GCNConv比这个实现多一个可选的bias和缓存机制但核心逻辑完全一致。你在自定义层里想加跳跃连接、加边权重都是在message函数里动手。**这一段代码建议自己敲一遍而不是复制跑通就完事。**你能徒手写出来说明真的理解了消息是怎么在图上流动的后面换任何新模型都只是改聚合函数和更新公式而已。3. 环境准备与最小训练循环让Cora在本地跑起来3.1 安装PyG版本对齐比想象中重要PyG不是纯Python库它依赖torch_scatter和torch_sparse这两个CUDA/C扩展算子。pip直接装torch-geometric通常能成功但一import就报undefined symbol或者找不到算子多半是扩展版本和torch版本对不上。常见做法是去PyG官方提供的wheel列表里找对应torch版本的预编译包别让pip自己猜。# Python 3.8-3.11下CPU版够跑Cora pip install torch2.0.1 pip install torch-geometric2.3.1 # 如果import报错按torch版本补装扩展 pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1cpu.html-f参数后面的URL指向预编译wheel仓库PyG官方按torch版本生成对应包。这里的关键是torch2.0.1和torch-sparse必须严格匹配错一个字节都可能直接闪退。装完后在Python里执行from torch_geometric.nn import GCNConv验证不报错就说明环境通了。一条血泪经验不要用conda混装torch和PyG依赖解析经常把两者拆成不同版本。我一般单独建一个虚拟环境只给图模型用避免和业务项目的包互相污染。3.2 加载Cora先看清数据长什么样Cora是图节点分类的MNIST2708篇论文、5429条引用边、7个类别、每篇论文一个1433维的词袋特征。PyG的Planetoid数据集类可以一行下载并处理成标准格式from torch_geometric.datasets import Planetoid # root指定数据存放目录第一次运行会下载到本地 dataset Planetoid(root./data, nameCora) data dataset[0] print(data) # 输出类似Data(x[2708, 1433], edge_index[2, 10556], y[2708], train_mask[2708], val_mask[2708], test_mask[2708]) print(节点数:, data.num_nodes) print(边数:, data.num_edges) print(类别数:, data.num_classes) print(训练节点:, data.train_mask.sum().item())train_mask、val_mask、test_mask是PyG自带的划分Cora的标准划分是训练140个、验证500个、测试1000个。这里必须先划重点不要自己重新划分数据。论文里所有公开精度都基于这个固定划分自己随机划分会导致测出来的分数和论文对不上进而怀疑模型写错了实际上只是对比基准错了。data对象里还内置了num_node_features等属性print(data)输出里能看到每个字段的维度这些信息在写模型时有用。3.3 最小训练循环从定义模型到跑通Epoch下面这段代码是PyG官方示例的简化版两层GCN、隐藏维度16、dropout 0.5、学习率0.01。它能够在三十秒内跑完两百轮迭代并给出测试精度是验证环境、验证安装的最佳脚本import torch import torch.nn.functional as F from torch_geometric.nn import GCNConv class GCN(torch.nn.Module): def __init__(self, in_channels, hidden_channels, out_channels): super().__init__() self.conv1 GCNConv(in_channels, hidden_channels) self.conv2 GCNConv(hidden_channels, out_channels) def forward(self, x, edge_index): x self.conv1(x, edge_index) x F.relu(x) x F.dropout(x, trainingself.training) x self.conv2(x, edge_index) return F.log_softmax(x, dim1) model GCN(dataset.num_features, 16, dataset.num_classes) optimizer torch.optim.Adam(model.parameters(), lr0.01, weight_decay5e-4) criterion torch.nn.NLLLoss() def train(): model.train() optimizer.zero_grad() out model(data.x, data.edge_index) loss criterion(out[data.train_mask], data.y[data.train_mask]) loss.backward() optimizer.step() return loss.item() for epoch in range(200): loss train() if epoch % 20 0: print(fEpoch {epoch:3d}, Loss {loss:.4f})损失函数用NLLLoss配合log_softmax效果等价于CrossEntropyLoss直接接原始logits这是PyG示例的传统写法。注意out[data.train_mask]这一步模型输出的是全部2708个节点的类别分布但我们只取训练掩码为真的那140个节点来算损失这正是“半监督”的含义——标签极少但特征和边是全图共享的。图卷积层在forward里会同时更新所有节点的表示即使某些节点没有标签。weight_decay5e-4这个正则强度在Cora上是经过反复验证的不要随便去掉。去掉后测试精度通常会掉三到五个百分点。这是图模型和普通MLP一个很大的区别正则项的收益非常明显。如果跑出来的loss不降或者爆成NaN优先检查edge_index里是否有超出节点范围的编号大概率是数据预处理时漏了编号映射。3.4 训练细节显存、Epoch数与验证时机Cora规模极小单卡训练无压力但换成自己的业务图就要注意三点。第一图卷积一次forward会更新全图节点显存随节点数线性增长不像CV可以靠batch size控制。第二训练轮数不是越多越好GCN的测试精度通常在200轮前就到顶了后面出现过平滑反而下降。第三验证集的作用是选模型不是调学习率。很多新手用验证集反复试学习率最后测出来比论文低就是因为验证集的信息被“偷看”了。标准做法是固定模型结构和超参数只在验证集上做早停。验证集精度最高的那个checkpoint才是最终模型而不是最后一个epoch的模型。我在工程里会更进一步把训练过程分成三份前三分之一只看训练loss是否下降中间三分之一看验证loss是否背离训练loss最后三分之一才测测试集。一套完整流程跑完基本能定位出问题是出在数据、模型还是训练配置上。4. 半监督节点分类完整代码模型定义、训练与评估4.1 两层GCN的完整模型定义上一章的模型只够跑通流程要拿得出手、能对比论文精度还要补上评估逻辑和推理逻辑。一个完整可复用的两层GCN模型长这样多了一个dropout开关控制训练和推理行为的切换import torch import torch.nn.functional as F from torch_geometric.nn import GCNConv class GCN(torch.nn.Module): def __init__(self, in_channels, hidden_channels, out_channels, dropout0.5): super().__init__() self.conv1 GCNConv(in_channels, hidden_channels) self.conv2 GCNConv(hidden_channels, out_channels) self.dropout dropout def forward(self, x, edge_index): x self.conv1(x, edge_index) x F.relu(x) x F.dropout(x, pself.dropout, trainingself.training) x self.conv2(x, edge_index) return x # 返回原始logits损失函数用CrossEntropyLoss def encode(self, x, edge_index): # 推理时取embedding供下游任务复用 x self.conv1(x, edge_index) x F.relu(x) return x这里返回原始logits而不是log_softmax后的结果是为了和CrossEntropyLoss直接配合。encode方法是给下游任务留的口子有时候你想把GNN当特征提取器节点embedding喂给其他模型这时候把第一层的输出导出来就行。隐藏维度hidden_channels是个关键超参数Cora上用16大图上建议128或256起但也要相应加大weight_decay防止过拟合。4.2 训练、测试与指标统计训练循环本身不复杂但评估逻辑要写严谨必须用model.eval()切到推理模式关闭dropout和batch normalization的统计更新。测试时要用torch.no_grad()包裹否则会额外计算梯度图白占显存。下面这段是完整可跑的训练加评估代码def train(): model.train() optimizer.zero_grad() out model(data.x, data.edge_index) loss F.cross_entropy(out[data.train_mask], data.y[data.train_mask]) loss.backward() optimizer.step() return loss.item() def test(): model.eval() with torch.no_grad(): out model(data.x, data.edge_index) pred out.argmax(dim1) accs [] for mask in [data.train_mask, data.val_mask, data.test_mask]: correct (pred[mask] data.y[mask]).sum().item() acc correct / mask.sum().item() accs.append(acc) return accs best_val_acc 0 best_state None for epoch in range(1, 201): loss train() train_acc, val_acc, test_acc test() if val_acc best_val_acc: best_val_acc val_acc best_state {k: v.clone() for k, v in model.state_dict().items()} if epoch % 20 0: print(fEpoch {epoch:3d}, Loss {loss:.4f}, Train {train_acc:.4f}, Val {val_acc:.4f}, Test {test_acc:.4f}) model.load_state_dict(best_state) _, _, final_test_acc test() print(fBest Val {best_val_acc:.4f}, Final Test {final_test_acc:.4f})best_state在验证集最优时保存模型参数这是图模型训练的标准手段。因为GNN在验证集上通常有个“先升后降”的过程拿最后一个epoch的参数去测测试集会错过最好的表现。在Cora上跑出来验证集精度大约在0.79-0.82之间测试精度在0.81-0.83之间取决于torch版本和随机种子。4.3 评估指标注意点Accuracy不够时看F1和混淆矩阵节点分类里类别分布往往不均衡。Cora是balanced dataset所以Accuracy够用但社交网络异常检测里异常节点可能只占千分之一。这时候Accuracy会骗人——全预测正常类也能拿99.9%。我一般会先看macro-F1再看每个类别的precision和recall。在PyG里计算F1不复杂from sklearn.metrics import f1_score, confusion_matrix model.eval() with torch.no_grad(): out model(data.x, data.edge_index) pred out.argmax(dim1) y_true data.y[data.test_mask].cpu().numpy() y_pred pred[data.test_mask].cpu().numpy() print(Macro F1:, f1_score(y_true, y_pred, averagemacro)) print(confusion_matrix(y_true, y_pred))混淆矩阵能直接看出哪些类别互相混淆。Cora的7个类别里神经网络相关的两个子类经常被互相误判这是数据本身的性质不代表模型写错了。如果某个类别的recall显著低优先怀疑的是这个类别训练样本太少而不是模型结构有问题。半监督设定下每个类的训练样本只有20个左右类别间的方差本来就很大。5. 图神经网络5个常见坑从过平滑到精度对不上5.1 层数加深精度反而暴跌过平滑现象两层GCN测试精度81%改成四层直接掉到68%再加层数掉到接近随机猜测。原因GCN本质上是一个低通滤波器每次聚合都在把邻居的特征拉近。层数越多所有节点的表示越趋同最终收敛到同一个点这叫过平滑。解决图模型的深度不是越高越好Cora这种规模的图两层就够了。如果需要建模多跳关系优先考虑残差连接、JK-Net或APPNP这类带“跳跃”的架构让浅层特征直接传到深层。5.2 测试精度和论文对不上数据划分不一致现象跑出来测试精度71%论文里写的是82%怎么看怎么不对。原因数据划分和论文不一致。Cora有公开的标准划分但网上有些教程用random_split重新分把部分测试节点划进了训练集精度自然虚高。解决用Planetoid自带的mask不要自己划分。如果自己从原始数据构建数据集必须提前固定test_mask并保存到文件任何实验都复用同一份划分。5.3 损失正常下降但测试指标不动现象训练loss从1.8降到0.4测试精度却一直卡在20%左右类别数的随机水平。原因模型只拟合了有标签的节点没有学到可泛化的结构规律。最常见的是特征和标签之间本来就没关系或者图的边太稀疏消息传不了几步。解决先去跑一个不带图结构的MLP做对比。如果MLP精度和GNN一样说明图结构没有提供额外信息如果MLP比GNN还高说明图结构在帮倒忙问题出在建图方式而不是模型。5.4 显存溢出邻居爆炸现象加载小图没问题换自己的大图一跑就OOM。原因全图GCN在forward时要把所有节点的中间表示驻留在显存。社交网络千万节点每层都存一份显存自然爆掉。解决换GraphSAGE思路用NeighborLoader做mini-batch采样。核心参数是num_neighbors[15, 10]分别控制第一层和第二层每个节点采样的邻居数。采样数越小显存越少但太小会丢失结构信息一般从[25, 10]开始调。5.5 结果反复横跳随机种子与复现现象同一个脚本跑三次测试精度一次81%、一次78%、一次83%。原因模型初始化、dropout、数据加载的随机性没有固定。图模型对初始化和dropout非常敏感Cora规模小方差尤其明显。解决在脚本开头统一设置随机种子import random import numpy as np import torch def set_seed(seed42): random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) # PyG的数据加载也有随机性必要时固定worker torch.backends.cudnn.deterministic True torch.backends.cudnn.benchmark False设置完种子后跑三次应该得到完全相同的精度。如果仍然有波动检查数据加载部分是不是用了num_workers多线程多线程会引入额外随机性。复现图模型实验必须连数据加载线程一起固定否则后面排查问题时会多一个变量。我自己的习惯是每次实验记录三个值seed、最终精度、最优epoch数三件套齐全才叫一次可复现的实验。6. 把GNN用在自己的业务数据上转换、图诊断与结构验证6.1 业务表转成PyG格式的通用代码真实业务数据一般在关系型数据库里一张用户表、一张转账记录表。转成PyG格式要做的只有三件事节点编号重映射、特征对齐、边表去重。下面这段代码直接从两个DataFrame构造Data对象import pandas as pd import torch from torch_geometric.data import Data # 假设user_df有user_id和特征列transfer_df有src_id和dst_id user_df pd.read_csv(users.csv) transfer_df pd.read_csv(transfers.csv) # 第一步把业务ID映射成连续的0..N-1 unique_ids pd.Index(pd.concat([user_df[user_id], transfer_df[src_id], transfer_df[dst_id]]).unique()) id_map {uid: i for i, uid in enumerate(unique_ids)} # 第二步特征矩阵按映射后的顺序排列 x torch.tensor(user_df.set_index(user_id).reindex(unique_ids).values, dtypetorch.float) # 第三步边表映射并转成COO格式 src transfer_df[src_id].map(id_map).values dst transfer_df[dst_id].map(id_map).values edge_index torch.tensor(np.vstack([src, dst]), dtypetorch.long) data Data(xx, edge_indexedge_index)这里的reindex保证了特征行顺序和节点编号一致这是最隐蔽的坑。如果直接用user_df.values当特征顺序是按原始表的行排的跟映射后的编号对不上模型性能会非常差但不会报错。边表里可能还有自环自己转自己、重复边、孤立节点建议在构造后打印data看一眼再进模型。6.2 图结构诊断度分布、孤立点与连通分量在训练之前先检查图的质量。孤立节点和超大连通分量都会影响GNN的行为。一小段代码就能发现问题from torch_geometric.utils import degree, is_undirected # 每个节点的度 deg degree(data.edge_index[0], num_nodesdata.num_nodes) print(孤立节点数:, (deg 0).sum().item()) print(最大度:, deg.max().item()) print(平均度:, deg.mean().item()) print(是否为无向图:, is_undirected(data.edge_index)) # 找最大连通分量 from torch_geometric.utils import to_networkx import networkx as nx G to_networkx(data) components sorted(nx.connected_components(G), keylen, reverseTrue) print(连通分量数量:, len(components)) print(最大分量节点占比:, len(components[0]) / data.num_nodes)孤立节点在消息传递时永远不会收到邻居消息它的表示经过两层线性变换后相当于一个普通MLP。如果孤立点占比太高GNN的效果会接近MLP这时候应先考虑补边或用其他特征工程兜底。最大连通分量占比如果低于60%说明图碎片化严重要考虑是否需要超节点连接或用GraphSAGE的采样能力来覆盖。6.3 怎么验证模型真的学到了图结构消融对比与可视化这是最后一关。很多同学训练完看测试精度不错就收工了但无法回答“模型是真的用了图结构还是只靠特征硬扛”。一个标准做法是训练一个不加edge_index的MLP做对比。如果两者精度差不多说明你的边携带的信息极少或者建图方式有问题。另一种更严格的做法是把边随机打乱后重训精度如果不掉同样说明边没用。# 打乱边重新构造图保持节点数不变 import torch num_edges data.edge_index.size(1) perm torch.randperm(num_edges) shuffled_edge_index data.edge_index[:, perm] # 用同一模型、同一种子重训 # 如果精度和原始图几乎一样说明图结构对任务没有帮助还可以把GNN输出的embedding用t-SNE降到二维可视化按真实类别着色。如果同类节点聚成团说明模型学到了理想的结构表示如果完全混在一起就是聚合失效。我看embedding可视化比看精度曲线更直观它能一眼看出消息传播是否真的把同类节点拉近了。这里再补充一个偏技巧的操作不光在最终模型上做验证在训练到一半时也存一版embedding对比。你会发现第一轮聚合后节点已经部分聚拢随着层数增加逐渐拉近。如果训练初期就完全分不开那后面怎么调参都很难救回来。做GNN这行最怕的就是把模型当黑匣子只看最后指标就宣称成功。把图结构消融、embedding可视化这两步加进你的标准流程能少走很多弯路希望帮到你。本文还有配套的精品资源点击获取