GNN 图神经网络全详解从 GCN 到 GAT、动态图、异构图一条线串完如果你是搞推荐系统、知识图谱、分子性质预测或者流量异常检测的一定绕不开一个东西图神经网络GNN。这次我们不摆概念而是把整条技术线拆开来讲先看 GNN 要解决什么问题再手写 GCN、GAT 的核心代码最后把动态图、异构图以及因果推理网络这类进阶方向一起收进来。全文基于 PyTorch PyGPyTorch Geometric来跑代码都能直接复制到本地验证。这篇文章适合谁已经会用 PyTorch 做基础分类任务但对图数据还比较陌生想快速理解“节点分类怎么做、消息传递是怎么一回事、GAT 的注意力从哪里来”的读者。读完你会得到一套可运行的 GNN 实验环境以及从基础网络到动态图、异构图的学习路径。1. 核心能力速览能力项说明项目类型图神经网络系统教程覆盖 GCN、GAT、动态图、异构图主要工具PyTorch、PyGPyTorch Geometric、CUDA可选模型覆盖基础 GNN 层、图卷积 GCN、图注意力 GAT、动态图预测、异构图建模运行环境Linux / Windows / macOS 均可推荐 NVIDIA GPU CUDA显存需求以 Cora 等小规模数据集为例2G 即可跑大图需分批采样启动方式Python 脚本运行无需 WebUI是否支持 API教程阶段不涉及服务化接口模型可保存为权重文件供服务化部署是否支持批量任务支持 mini-batch 训练和推理可扩展到大规模图适合场景推荐系统、知识图谱推理、分子性质预测、社交网络分析、流量异常检测学习成本中等需要掌握 PyTorch 基础和图数据结构概念2. 图神经网络要解决什么问题传统的深度学习模型处理的是规整数据图像是二维矩阵文本是一维序列。但现实世界大量数据是“节点 边”的关系型结构比如社交网络中“谁关注谁”、电商场景中“用户和商品的交互”、论文引用网络中“论文之间的引用关系”。这类数据不能直接塞进全连接网络因为每个节点的邻居数量不固定无法用固定尺寸的卷积核去扫描。GNN 的核心思路是消息传递每个节点通过聚合邻居的特征来更新自己的表示。更新一次只看到一跳邻居叠加多层就可以看到多跳邻居。这个机制和卷积神经网络有本质区别CNN 的卷积核在空间上滑动GNN 的聚合过程是跟着图结构走的。学习 GNN 时我建议按下面这条路径走每一步都有明确任务搞懂图数据的两种表示邻接矩阵和边列表。掌握消息传递框架理解message、aggregate、update三个阶段。从最简单的基础 GNN 出发理解如何自定义一个图卷积层。学习 GCN看它如何通过归一化邻接矩阵解决节点度差异问题。学习 GAT看注意力机制如何替代固定权重。扩展到动态图时间维度和异构图多类型节点和边。这条路径走完你基本可以读懂代码仓库里 90% 的经典图模型实现。3. 环境准备与前置条件3.1 硬件与软件要求GNN 模型不像大语言模型那样吃显存小规模数据集比如论文引用网络 Cora、Citeseer在 CPU 上就能跑起来。如果你后续要处理百万节点级别的图建议准备一块独立显卡。配置项建议操作系统Windows 10/11、Ubuntu 20.04、macOS 12内存8G 起步16G 更稳显卡可选NVIDIA 显卡 CUDA 11.8 或 12.xPython3.9 ~ 3.11PyTorch2.0 及以上PyG2.3 及以上具体到 PyG 的安装强烈建议用官方提供的预编译包不要在本地从源码编译否则容易踩坑。安装方式如下# 方式一CPU 版本 pip install torch torchvision torchaudio # 方式二GPU 版本按你的 CUDA 版本选择 index-url # CUDA 11.8 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # CUDA 12.1 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装 PyG pip install torch_geometric # 可选安装辅助库提供常用数据集和可视化工具 pip install torch_scatter torch_sparse torch_cluster torch_spline_conv如果你装torch_scatter这类扩展库时遇到找不到匹配版本先确认 PyTorch 版本和 CUDA 版本一致再更换下载源。实际上 PyG 的核心操作有内置 fallback即使不装这些扩展库小数据集也能运行只是性能会略低。3.2 验证环境是否可用安装完成后运行下面这段代码如果能正常加载 Cora 数据集说明环境没问题from torch_geometric.datasets import Planetoid dataset Planetoid(root./data, nameCora) print(f数据集包含 {len(dataset)} 个图) print(f节点特征维度: {dataset.num_features}) print(f类别数量: {dataset.num_classes}) data dataset[0] print(f节点数: {data.num_nodes}) print(f边数: {data.num_edges})输出类似数据集包含 1 个图 节点特征维度: 1433 类别数量: 7 节点数: 2708 边数: 10556Cora 是论文引用网络2708 篇论文按主题分为 7 类每篇论文用 1433 维的词袋特征表示。这是 GNN 学习的“Hello World”。4. 图数据表示与基础网络组件4.1 PyG 的 Data 对象PyG 里一个图由Data对象表示核心字段包括x节点特征矩阵形状为[num_nodes, num_features]。edge_index边索引形状为[2, num_edges]存储边的源节点和目标节点。y节点标签用于监督学习。train_mask、val_mask、test_mask划分训练、验证、测试节点的掩码。edge_index是理解 GNN 代码的第一个难点。它不是邻接矩阵而是“边列表”格式两行分别表示边的起点和终点。比如[[0, 1], [1, 2]]表示0 - 1和1 - 2两条边。来看一个从零构造图的例子import torch from torch_geometric.data import Data # 4 个节点每个节点 3 维特征 x torch.tensor([[1, 0, 0], [0, 1, 0], [0, 0, 1], [1, 1, 0]], dtypetorch.float) # 4 条边0-1, 0-2, 1-2, 2-3无向图需要按双向存 edge_index torch.tensor([[0, 0, 1, 2], [1, 2, 2, 3]], dtypetorch.long) # 节点标签做 3 分类 y torch.tensor([0, 1, 1, 2], dtypetorch.long) data Data(xx, edge_indexedge_index, yy) print(data) # 转换为邻接矩阵可选 from torch_geometric.utils import to_dense_adj adj to_dense_adj(data.edge_index) print(adj)这里要记住一个关键点edge_index存的是双向边。如果你的原始数据是单向边在使用Data前要先对称化否则信息只能沿一个方向传播模型性能会受影响。4.2 消息传递框架PyG 中所有图卷积层都继承自MessagePassing基类。理解这个基类的三个方法就等于理解了 90% 的 GNN 层实现message()构造从源节点到目标节点传递的消息通常用节点特征或边特征计算。aggregate()把每个节点收到的消息聚合起来常见的有add求和、mean平均、max取最大值。update()更新节点自身的表示一般把聚合结果经过一个非线性变换。消息传递的流程可以这样理解每个节点首先准备好自己的“消息”发给所有邻居然后每个节点将收到的消息汇总最后更新自己的特征。下面实现一个最基础的 GNN 层它做的事情是将邻居特征求和后和自身特征拼接再经过线性变换。import torch from torch import nn from torch_geometric.nn import MessagePassing class BasicGNNLayer(MessagePassing): def __init__(self, in_channels, out_channels): super().__init__(aggradd) # 聚合方式求和 self.lin nn.Linear(in_channels * 2, out_channels) def forward(self, x, edge_index): # x: [num_nodes, in_channels] # edge_index: [2, num_edges] return self.propagate(edge_index, xx) def message(self, x_j): # x_j: 源节点邻居的特征 return x_j def update(self, aggr_out, x): # aggr_out: [num_nodes, in_channels] 聚合后的邻居特征 # x: 节点自身特征 combined torch.cat([x, aggr_out], dim1) return self.lin(combined)这个层虽然简单但它完整展示了 GNN 的骨架。后续 GCN、GAT 都是在message和update两个环节做文章。5. 图卷积网络 GCN从聚合邻居到归一化5.1 GCN 的核心公式GCNGraph Convolutional Network是最经典的图神经网络。它的每一层更新公式可以写成X^{(l1)} σ(D^{-1/2} A D^{-1/2} X^{(l)} W^{(l)})其中 A 是加了自环的邻接矩阵D 是度矩阵。这里最关键的设计是D^{-1/2} A D^{-1/2}它叫对称归一化邻接矩阵。为什么要做归一化因为不同节点的度差别很大有些节点有几百个邻居有些只有几个。如果不做归一化度数高的节点特征会被求和得很大训练不稳定也容易让模型偏向大度节点。对称归一化同时考虑了源节点和目标节点的度是 GCN 性能优于朴素聚合层的关键。在 PyG 里GCN 不仅可以用现成的GCNConv还可以直接手写一个逻辑非常清晰import torch from torch import nn from torch_geometric.nn import MessagePassing from torch_geometric.utils import add_self_loops, degree class GCNConvCustom(MessagePassing): def __init__(self, in_channels, out_channels): super().__init__(aggradd) self.lin nn.Linear(in_channels, out_channels) def forward(self, x, edge_index): # 1. 添加自环让节点能聚合到自身特征 edge_index, _ add_self_loops(edge_index, num_nodesx.size(0)) # 2. 计算对称归一化系数 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] # 3. 线性变换 x self.lin(x) # 4. 传播消息norm 作为边上权重 return self.propagate(edge_index, xx, normnorm) def message(self, x_j, norm): # x_j: 源节点特征norm: 边权重 return norm.view(-1, 1) * x_j5.2 用 GCN 做节点分类有了自定义 GCN 层就可以搭一个两层 GCN 模型在 Cora 数据集上做节点分类实验。import torch import torch.nn.functional as F from torch_geometric.datasets import Planetoid from torch_geometric.nn import GCNConv dataset Planetoid(root./data, nameCora) data dataset[0] class GCN(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, p0.5) 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)训练部分采用半监督方式只有train_mask对应的节点参与损失计算这是 GNN 在引文网络上的标准设定。def train(): model.train() optimizer.zero_grad() out model(data.x, data.edge_index) loss F.nll_loss(out[data.train_mask], data.y[data.train_mask]) loss.backward() optimizer.step() return loss.item() def evaluate(): model.eval() 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() accs.append(correct / mask.sum().item()) return accs for epoch in range(200): loss train() train_acc, val_acc, test_acc evaluate() if epoch % 20 0: print(fEpoch {epoch:03d} | Loss {loss:.4f} | Train {train_acc:.4f} | Val {val_acc:.4f} | Test {test_acc:.4f})在 Cora 上两层 GCN 的测试准确率通常在 0.80 到 0.82 之间。如果你复现出来的结果明显低于这个区间优先检查数据集划分是否一致其次看 dropout 和 weight decay 是否设置正确。6. 图注意力网络 GAT让模型自己决定聚合权重6.1 为什么需要注意力机制GCN 的聚合权重完全由图的度决定一旦图结构固定权重就固定这在很多场景下不够灵活。比如社交网络中有些好友对你的影响力远大于其他好友但 GCN 只能按照“邻居数量”均匀分配权重。GATGraph Attention Network的思路是为每条边计算一个注意力系数节点j对节点i的重要性是多少由它们的特征共同决定而不是由图结构预先定死。这是 GNN 和 Transformer 在思想上的直接对应所以 GAT 经常被称为“图上的 Transformer”。6.2 GAT 核心实现GAT 的计算步骤分为三步对节点特征做线性变换W x。计算注意力系数e_ij LeakyReLU(a^T [W x_i || W x_j])。用 softmax 对注意力系数归一化再按归一化结果加权聚合邻居特征。PyG 内置了GATConv建议先用内置层跑通任务再对照手写实现理解细节。下面是一个手写简化版 GATimport torch from torch import nn from torch_geometric.nn import MessagePassing from torch_geometric.utils import softmax class GATLayer(MessagePassing): def __init__(self, in_channels, out_channels, heads1): super().__init__(aggradd) self.lin nn.Linear(in_channels, out_channels, biasFalse) self.att_src nn.Parameter(torch.Tensor(1, heads, out_channels)) self.att_dst nn.Parameter(torch.Tensor(1, heads, out_channels)) self.heads heads def forward(self, x, edge_index): x self.lin(x) return self.propagate(edge_index, xx) def message(self, x_i, x_j, index): # 这是简化逻辑实际 GAT 要多头计算 attention (x_i * self.att_src).sum(dim-1) (x_j * self.att_dst).sum(dim-1) attention F.leaky_relu(attention, negative_slope0.2) attention softmax(attention, index) return x_j * attention.unsqueeze(-1)如果你第一次接触 GAT建议直接用 PyG 内置版本避免多头注意力维度处理出错import torch.nn.functional as F from torch_geometric.nn import GATConv class GAT(nn.Module): def __init__(self, in_channels, hidden_channels, out_channels, heads8): super().__init__() self.conv1 GATConv(in_channels, hidden_channels, headsheads) self.conv2 GATConv(hidden_channels * heads, out_channels, heads1) def forward(self, x, edge_index): x self.conv1(x, edge_index) x F.relu(x) x F.dropout(x, p0.5, trainingself.training) x self.conv2(x, edge_index) return F.log_softmax(x, dim1)在相同设定下GAT 在 Cora 上的测试准确率会比 GCN 高 1 到 2 个百分点但训练时间也更长因为每个节点的每个邻居都要单独计算注意力系数。如果你的数据集规模很大GAT 的计算开销会明显高于 GCN这时可以做稀疏化或随机采样来降低复杂度。7. 动态图与异构图进阶经典网络7.1 动态图把时间维度加进图前面提到的 GCN、GAT 都是静态图模型假设图结构固定不变。但很多真实场景是动态的社交网络中用户关系不断变化、交易网络中节点和边每时每刻都在新增。动态图模型要同时捕捉图结构和时间演化双重信息。常见思路有两种时间快照法把连续时间切成多个快照每个快照是一个静态图再用时序模型LSTM、GRU串联快照的特征。连续时间法每条边带时间戳建模边事件发生的概率。典型方法是 Temporal Graph Networks用节点的时间邻居做消息聚合并用记忆模块保存节点历史状态。动态图模型适合的典型任务是链接预测给定时间 T 之前的图预测时间 T 之后哪些节点之间会产生新的边。PyG 中常用TemporalData来表示带时间戳的边数据训练集和测试集按照时间切分不能用随机划分。from torch_geometric.data import TemporalData # 假设边带时间戳 src torch.tensor([0, 1, 2, 3]) dst torch.tensor([1, 2, 3, 0]) t torch.tensor([1, 2, 3, 4]) msg torch.randn(4, 16) temporal_data TemporalData( srcsrc, dstdst, tt, msgmsg ) print(temporal_data)动态图模型对显存的消耗比静态图更大因为需要按时间窗口维护节点的历史状态。训练时批次内的时间跨度不要太大否则邻居数量会急剧膨胀。7.2 异构图多种节点和多种边的统一建模比动态图更常见的现实场景是异构图节点类型和边类型不止一种。比如在推荐系统中用户、商品、店铺是不同类型的节点“用户购买商品”和“商品属于店铺”是不同类型的边。如果强行把所有节点当成同一类处理会丢失重要的类型信息。异构图模型的核心能力是按关系类型分别聚合。以 R-GCNRelational Graph Convolutional Network为例它对每种关系类型使用独立的权重矩阵x_i^{(l1)} σ( Σ_{r ∈ R} Σ_{j ∈ N_i^r} W_r x_j^{(l)} )PyG 提供了HeteroData对象来构建异构图模型层可以用to_hetero()或HeteroConv包装普通的 GNN 层。from torch_geometric.data import HeteroData hetero_data HeteroData() # 两种节点类型user 和 item hetero_data[user].x torch.randn(100, 16) hetero_data[item].x torch.randn(50, 16) # 两种边类型user clicks itemitem belongs to category hetero_data[user, clicks, item].edge_index torch.tensor([[0, 1, 2], [1, 2, 3]]) hetero_data[item, belongs_to, category].edge_index torch.tensor([[0, 1], [10, 11]]) print(hetero_data) print(hetero_data.node_types) print(hetero_data.edge_types)实际业务中更常用的方案是 HANHeterogeneous Graph Attention Network它在“节点级注意力”和“语义级注意力”两个维度上做聚合。节点级注意力相当于 GAT 在某种关系下的邻居加权语义级注意力则是在不同元路径meta-path的结果之间做加权融合。HAN 适合需要解释性的场景比如风控系统中的多视角特征融合。异构图模型的实现通常在 API 使用上更繁琐但思路仍然统一每种关系类型都是一个独立的“消息传递通道”最终把各通道的结果融合。玩转异构图的关键不是写模型结构而是定义清楚节点类型、边类型和元路径。8. 模型训练、批量任务与性能观察8.1 小图全量训练与大图批处理Cora 这种几千节点的图可以直接把整张图送进模型这是全量训练。当图规模到达百万节点时全量计算不可行需要引入邻居采样和 mini-batch 训练。PyG 里的NeighborLoader是标准工具from torch_geometric.loader import NeighborLoader from torch_geometric.datasets import Planetoid dataset Planetoid(root./data, nameCora) data dataset[0] # 每个 batch 采样 128 个节点邻居采样数分别是 [25, 10] loader NeighborLoader( data, num_neighbors[25, 10], batch_size128, shuffleTrue, ) batch next(iter(loader)) print(fBatch 节点数: {batch.num_nodes}) print(fBatch 边数: {batch.num_edges})邻居采样会显著减少显存占用但代价是增加了代码复杂度。训练循环里要注意采样出来的子图中batch.train_mask等属性和原始图的掩码不同需要做映射。PyG 通常会自动处理节点索引重映射但边和节点的batch属性需要额外留意。批处理对显存的影响非常直观。以一个 8G 显存的中端显卡为例跑 Cora 全量训练占用不到 1G如果换成 OGB 的 ogbn-arxiv 数据集约 17 万节点全量训练比较容易爆显存而使用NeighborLoader可以把显存占用控制在 2G 到 4G具体看邻居数量和 batch_size。8.2 性能观察方法在训练 GNN 时建议关注两个指标显存占用Windows 用任务管理器 GPU 栏Linux 用nvidia-smi -l 1。单 Epoch 耗时在训练循环里用time.time()记录。如果你要对比不同模型固定相同的 epoch 数和 batch 大小才有意义。GCN 通常是最快的GAT 次之动态图模型一般最耗时。显存开销方面GAT 的多头机制会提升显存占用动态图的记忆机制会额外占用一部分存储。降低显存占用最简单的方法是减少邻居采样数量比如把num_neighbors[25, 10]改成[15, 5]显存占用可以降低一半左右但准确率也会有一定下降。另一个方法是减少注意力 heads 数GAT 从 8 heads 降到 4 heads显存大约能省 30%。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装 PyG 时找不到匹配的 torch_scatterPyTorch 和 CUDA 版本不匹配检查torch.__version__与nvcc -V重新安装与 CUDA 版本一致的 PyTorch再装 PyG训练 loss 不下降学习率过高或特征未归一化打印 loss 和梯度范数降低学习率、检查节点特征需要归一化GCN 测试准确率低于 0.70模型层数太深或过拟合检查是否用了 dropout回退到 2 层网络增大 dropout 比例GAT 训练速度极慢多头注意力和邻接矩阵规模过大单 Epoch 耗时统计减少 heads 数或改用 GCN 验证流程显存不足 OOMbatch_size 或邻居采样数过大查看报错中的 tensor 维度调小 batch_size、num_neighbors或转 CPU 测试异构图数据 loading 报错节点和边的类型名不一致打印HeteroData类型列表检查类型字符串完全一致动态图测试集出现未来信息泄露时间切分不正确检查边的时间戳分布严格按时间排序切分禁止随机划分CUDA out of memory 后重启仍报错进程残留占用显存nvidia-smi查看占用进程杀掉残留进程或重启内核层数增加在 GNN 里并不总是好事。GCN 堆到 5 层以上会出现过平滑问题所有节点表示趋同准确率反而下降。这被称为“深度 GNN 退化”排查准确率问题时要优先考虑。10. 最佳实践与使用建议10.1 从最简单的基线和最小数据集开始不管你是要用 GNN 做推荐还是分子性质预测第一次跑通永远是最重要的事。先用 Cora、Citeseer 这些几百 KB 级别的小数据集把训练流程全部跑通再迁移到自己的数据上。这样可以把“模型代码问题”和“数据问题”分开排查。我推荐的最小实验组合是两层 GCN Cora 数据集 200 epoch。如果这个组合跑不通问题通常在环境而不是模型。跑通之后再按顺序替换成 GAT 和异构图模型。10.2 数据划分要符合业务语义引文网络的标准做法是用掩码划分节点训练集、验证集、测试集的节点互不重叠。但如果你做的是链接预测必须按时间划分否则测试集里出现的边会“泄露”到训练集模型效果虚高。动态图模型尤其要小心这一点。正确做法是取前 80% 时间的边做训练后 20% 做测试等到做推理时再把时间窗口往后移动。这也是热词中“图神经网络与因果推理网络”比较关注的方向——在时间序列图数据上建模因果关系时避免信息泄露是第一原则。10.3 目录与工程化管理图神经网络实验通常涉及多个数据集、多种模型、多组超参数工程化管理能帮你省下大量时间。推荐结构gnn_workdir/ ├── data/ # 原始数据集 │ ├── cora/ │ └── citeseer/ ├── models/ # 模型定义 │ ├── gcn.py │ ├── gat.py │ └── hetero.py ├── scripts/ # 训练入口脚本 ├── logs/ # 训练日志 └── checkpoints/ # 模型权重训练脚本里至少记录三个信息数据集名称、模型名称、测试指标。日志文件用{dataset}_{model}_{time}.log命名后面做论文复现或模型对比时可以快速定位。10.4 合规与安全边界如果你的 GNN 项目涉及用户关系数据、交易网络数据、人脸关系图或社交网络必须注意数据来源合规和数据脱敏。训练数据不要包含未经授权的个人信息发布模型或评测结果前要检查是否泄漏敏感结构比如用户的社交关系链。涉及知识产权的内容应使用授权数据推荐系统项目尤其要注意对用户隐私的匿名化处理。动态图模型在预测用户行为时可能涉及敏感推断上线前应做影响评估。11. 总结与下一步GNN 这条技术线看起来内容很多但核心始终是消息传递机制。从基础 GNN 到 GCN是“聚合邻居特征 度归一化”从 GCN 到 GAT是把固定权重换成注意力权重动态图加的是时间维度异构图加的是类型维度。把这一条主线理清楚后面看到任何带前后缀的图模型都能快速拆解。最先应该跑的实验是两层 GCN 在 Cora 上的节点分类。它验证的是你整个图数据处理流程数据加载、边索引、训练循环、评估逻辑是否全部正确。这个流程不通其他模型没有必要往下试。最容易踩的坑有三个第一是edge_index没有对称化导致信息只能单向传播第二是动态图任务用随机划分产生了时序泄露测试指标虚高第三是盲目堆模型层数两层能达到的效果五层反而下降。如果你觉得本文内容有用建议收藏备用。下一步可以沿着两条线继续深入一条是搞懂 PyG 源码里MessagePassing的完整实现尝试自己写一个图扩散卷积层另一条是尝试在 Hetorogeneous Graph 数据上复现 HAN或者结合时间信息实现一个简单的动态图预测模型。每个方向跑通后你对 GNN 的理解都会上一个台阶。 图神经网络全详解：从GCN到GAT与动态异构图
GNN 图神经网络全详解从 GCN 到 GAT、动态图、异构图一条线串完如果你是搞推荐系统、知识图谱、分子性质预测或者流量异常检测的一定绕不开一个东西图神经网络GNN。这次我们不摆概念而是把整条技术线拆开来讲先看 GNN 要解决什么问题再手写 GCN、GAT 的核心代码最后把动态图、异构图以及因果推理网络这类进阶方向一起收进来。全文基于 PyTorch PyGPyTorch Geometric来跑代码都能直接复制到本地验证。这篇文章适合谁已经会用 PyTorch 做基础分类任务但对图数据还比较陌生想快速理解“节点分类怎么做、消息传递是怎么一回事、GAT 的注意力从哪里来”的读者。读完你会得到一套可运行的 GNN 实验环境以及从基础网络到动态图、异构图的学习路径。1. 核心能力速览能力项说明项目类型图神经网络系统教程覆盖 GCN、GAT、动态图、异构图主要工具PyTorch、PyGPyTorch Geometric、CUDA可选模型覆盖基础 GNN 层、图卷积 GCN、图注意力 GAT、动态图预测、异构图建模运行环境Linux / Windows / macOS 均可推荐 NVIDIA GPU CUDA显存需求以 Cora 等小规模数据集为例2G 即可跑大图需分批采样启动方式Python 脚本运行无需 WebUI是否支持 API教程阶段不涉及服务化接口模型可保存为权重文件供服务化部署是否支持批量任务支持 mini-batch 训练和推理可扩展到大规模图适合场景推荐系统、知识图谱推理、分子性质预测、社交网络分析、流量异常检测学习成本中等需要掌握 PyTorch 基础和图数据结构概念2. 图神经网络要解决什么问题传统的深度学习模型处理的是规整数据图像是二维矩阵文本是一维序列。但现实世界大量数据是“节点 边”的关系型结构比如社交网络中“谁关注谁”、电商场景中“用户和商品的交互”、论文引用网络中“论文之间的引用关系”。这类数据不能直接塞进全连接网络因为每个节点的邻居数量不固定无法用固定尺寸的卷积核去扫描。GNN 的核心思路是消息传递每个节点通过聚合邻居的特征来更新自己的表示。更新一次只看到一跳邻居叠加多层就可以看到多跳邻居。这个机制和卷积神经网络有本质区别CNN 的卷积核在空间上滑动GNN 的聚合过程是跟着图结构走的。学习 GNN 时我建议按下面这条路径走每一步都有明确任务搞懂图数据的两种表示邻接矩阵和边列表。掌握消息传递框架理解message、aggregate、update三个阶段。从最简单的基础 GNN 出发理解如何自定义一个图卷积层。学习 GCN看它如何通过归一化邻接矩阵解决节点度差异问题。学习 GAT看注意力机制如何替代固定权重。扩展到动态图时间维度和异构图多类型节点和边。这条路径走完你基本可以读懂代码仓库里 90% 的经典图模型实现。3. 环境准备与前置条件3.1 硬件与软件要求GNN 模型不像大语言模型那样吃显存小规模数据集比如论文引用网络 Cora、Citeseer在 CPU 上就能跑起来。如果你后续要处理百万节点级别的图建议准备一块独立显卡。配置项建议操作系统Windows 10/11、Ubuntu 20.04、macOS 12内存8G 起步16G 更稳显卡可选NVIDIA 显卡 CUDA 11.8 或 12.xPython3.9 ~ 3.11PyTorch2.0 及以上PyG2.3 及以上具体到 PyG 的安装强烈建议用官方提供的预编译包不要在本地从源码编译否则容易踩坑。安装方式如下# 方式一CPU 版本 pip install torch torchvision torchaudio # 方式二GPU 版本按你的 CUDA 版本选择 index-url # CUDA 11.8 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # CUDA 12.1 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装 PyG pip install torch_geometric # 可选安装辅助库提供常用数据集和可视化工具 pip install torch_scatter torch_sparse torch_cluster torch_spline_conv如果你装torch_scatter这类扩展库时遇到找不到匹配版本先确认 PyTorch 版本和 CUDA 版本一致再更换下载源。实际上 PyG 的核心操作有内置 fallback即使不装这些扩展库小数据集也能运行只是性能会略低。3.2 验证环境是否可用安装完成后运行下面这段代码如果能正常加载 Cora 数据集说明环境没问题from torch_geometric.datasets import Planetoid dataset Planetoid(root./data, nameCora) print(f数据集包含 {len(dataset)} 个图) print(f节点特征维度: {dataset.num_features}) print(f类别数量: {dataset.num_classes}) data dataset[0] print(f节点数: {data.num_nodes}) print(f边数: {data.num_edges})输出类似数据集包含 1 个图 节点特征维度: 1433 类别数量: 7 节点数: 2708 边数: 10556Cora 是论文引用网络2708 篇论文按主题分为 7 类每篇论文用 1433 维的词袋特征表示。这是 GNN 学习的“Hello World”。4. 图数据表示与基础网络组件4.1 PyG 的 Data 对象PyG 里一个图由Data对象表示核心字段包括x节点特征矩阵形状为[num_nodes, num_features]。edge_index边索引形状为[2, num_edges]存储边的源节点和目标节点。y节点标签用于监督学习。train_mask、val_mask、test_mask划分训练、验证、测试节点的掩码。edge_index是理解 GNN 代码的第一个难点。它不是邻接矩阵而是“边列表”格式两行分别表示边的起点和终点。比如[[0, 1], [1, 2]]表示0 - 1和1 - 2两条边。来看一个从零构造图的例子import torch from torch_geometric.data import Data # 4 个节点每个节点 3 维特征 x torch.tensor([[1, 0, 0], [0, 1, 0], [0, 0, 1], [1, 1, 0]], dtypetorch.float) # 4 条边0-1, 0-2, 1-2, 2-3无向图需要按双向存 edge_index torch.tensor([[0, 0, 1, 2], [1, 2, 2, 3]], dtypetorch.long) # 节点标签做 3 分类 y torch.tensor([0, 1, 1, 2], dtypetorch.long) data Data(xx, edge_indexedge_index, yy) print(data) # 转换为邻接矩阵可选 from torch_geometric.utils import to_dense_adj adj to_dense_adj(data.edge_index) print(adj)这里要记住一个关键点edge_index存的是双向边。如果你的原始数据是单向边在使用Data前要先对称化否则信息只能沿一个方向传播模型性能会受影响。4.2 消息传递框架PyG 中所有图卷积层都继承自MessagePassing基类。理解这个基类的三个方法就等于理解了 90% 的 GNN 层实现message()构造从源节点到目标节点传递的消息通常用节点特征或边特征计算。aggregate()把每个节点收到的消息聚合起来常见的有add求和、mean平均、max取最大值。update()更新节点自身的表示一般把聚合结果经过一个非线性变换。消息传递的流程可以这样理解每个节点首先准备好自己的“消息”发给所有邻居然后每个节点将收到的消息汇总最后更新自己的特征。下面实现一个最基础的 GNN 层它做的事情是将邻居特征求和后和自身特征拼接再经过线性变换。import torch from torch import nn from torch_geometric.nn import MessagePassing class BasicGNNLayer(MessagePassing): def __init__(self, in_channels, out_channels): super().__init__(aggradd) # 聚合方式求和 self.lin nn.Linear(in_channels * 2, out_channels) def forward(self, x, edge_index): # x: [num_nodes, in_channels] # edge_index: [2, num_edges] return self.propagate(edge_index, xx) def message(self, x_j): # x_j: 源节点邻居的特征 return x_j def update(self, aggr_out, x): # aggr_out: [num_nodes, in_channels] 聚合后的邻居特征 # x: 节点自身特征 combined torch.cat([x, aggr_out], dim1) return self.lin(combined)这个层虽然简单但它完整展示了 GNN 的骨架。后续 GCN、GAT 都是在message和update两个环节做文章。5. 图卷积网络 GCN从聚合邻居到归一化5.1 GCN 的核心公式GCNGraph Convolutional Network是最经典的图神经网络。它的每一层更新公式可以写成X^{(l1)} σ(D^{-1/2} A D^{-1/2} X^{(l)} W^{(l)})其中 A 是加了自环的邻接矩阵D 是度矩阵。这里最关键的设计是D^{-1/2} A D^{-1/2}它叫对称归一化邻接矩阵。为什么要做归一化因为不同节点的度差别很大有些节点有几百个邻居有些只有几个。如果不做归一化度数高的节点特征会被求和得很大训练不稳定也容易让模型偏向大度节点。对称归一化同时考虑了源节点和目标节点的度是 GCN 性能优于朴素聚合层的关键。在 PyG 里GCN 不仅可以用现成的GCNConv还可以直接手写一个逻辑非常清晰import torch from torch import nn from torch_geometric.nn import MessagePassing from torch_geometric.utils import add_self_loops, degree class GCNConvCustom(MessagePassing): def __init__(self, in_channels, out_channels): super().__init__(aggradd) self.lin nn.Linear(in_channels, out_channels) def forward(self, x, edge_index): # 1. 添加自环让节点能聚合到自身特征 edge_index, _ add_self_loops(edge_index, num_nodesx.size(0)) # 2. 计算对称归一化系数 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] # 3. 线性变换 x self.lin(x) # 4. 传播消息norm 作为边上权重 return self.propagate(edge_index, xx, normnorm) def message(self, x_j, norm): # x_j: 源节点特征norm: 边权重 return norm.view(-1, 1) * x_j5.2 用 GCN 做节点分类有了自定义 GCN 层就可以搭一个两层 GCN 模型在 Cora 数据集上做节点分类实验。import torch import torch.nn.functional as F from torch_geometric.datasets import Planetoid from torch_geometric.nn import GCNConv dataset Planetoid(root./data, nameCora) data dataset[0] class GCN(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, p0.5) 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)训练部分采用半监督方式只有train_mask对应的节点参与损失计算这是 GNN 在引文网络上的标准设定。def train(): model.train() optimizer.zero_grad() out model(data.x, data.edge_index) loss F.nll_loss(out[data.train_mask], data.y[data.train_mask]) loss.backward() optimizer.step() return loss.item() def evaluate(): model.eval() 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() accs.append(correct / mask.sum().item()) return accs for epoch in range(200): loss train() train_acc, val_acc, test_acc evaluate() if epoch % 20 0: print(fEpoch {epoch:03d} | Loss {loss:.4f} | Train {train_acc:.4f} | Val {val_acc:.4f} | Test {test_acc:.4f})在 Cora 上两层 GCN 的测试准确率通常在 0.80 到 0.82 之间。如果你复现出来的结果明显低于这个区间优先检查数据集划分是否一致其次看 dropout 和 weight decay 是否设置正确。6. 图注意力网络 GAT让模型自己决定聚合权重6.1 为什么需要注意力机制GCN 的聚合权重完全由图的度决定一旦图结构固定权重就固定这在很多场景下不够灵活。比如社交网络中有些好友对你的影响力远大于其他好友但 GCN 只能按照“邻居数量”均匀分配权重。GATGraph Attention Network的思路是为每条边计算一个注意力系数节点j对节点i的重要性是多少由它们的特征共同决定而不是由图结构预先定死。这是 GNN 和 Transformer 在思想上的直接对应所以 GAT 经常被称为“图上的 Transformer”。6.2 GAT 核心实现GAT 的计算步骤分为三步对节点特征做线性变换W x。计算注意力系数e_ij LeakyReLU(a^T [W x_i || W x_j])。用 softmax 对注意力系数归一化再按归一化结果加权聚合邻居特征。PyG 内置了GATConv建议先用内置层跑通任务再对照手写实现理解细节。下面是一个手写简化版 GATimport torch from torch import nn from torch_geometric.nn import MessagePassing from torch_geometric.utils import softmax class GATLayer(MessagePassing): def __init__(self, in_channels, out_channels, heads1): super().__init__(aggradd) self.lin nn.Linear(in_channels, out_channels, biasFalse) self.att_src nn.Parameter(torch.Tensor(1, heads, out_channels)) self.att_dst nn.Parameter(torch.Tensor(1, heads, out_channels)) self.heads heads def forward(self, x, edge_index): x self.lin(x) return self.propagate(edge_index, xx) def message(self, x_i, x_j, index): # 这是简化逻辑实际 GAT 要多头计算 attention (x_i * self.att_src).sum(dim-1) (x_j * self.att_dst).sum(dim-1) attention F.leaky_relu(attention, negative_slope0.2) attention softmax(attention, index) return x_j * attention.unsqueeze(-1)如果你第一次接触 GAT建议直接用 PyG 内置版本避免多头注意力维度处理出错import torch.nn.functional as F from torch_geometric.nn import GATConv class GAT(nn.Module): def __init__(self, in_channels, hidden_channels, out_channels, heads8): super().__init__() self.conv1 GATConv(in_channels, hidden_channels, headsheads) self.conv2 GATConv(hidden_channels * heads, out_channels, heads1) def forward(self, x, edge_index): x self.conv1(x, edge_index) x F.relu(x) x F.dropout(x, p0.5, trainingself.training) x self.conv2(x, edge_index) return F.log_softmax(x, dim1)在相同设定下GAT 在 Cora 上的测试准确率会比 GCN 高 1 到 2 个百分点但训练时间也更长因为每个节点的每个邻居都要单独计算注意力系数。如果你的数据集规模很大GAT 的计算开销会明显高于 GCN这时可以做稀疏化或随机采样来降低复杂度。7. 动态图与异构图进阶经典网络7.1 动态图把时间维度加进图前面提到的 GCN、GAT 都是静态图模型假设图结构固定不变。但很多真实场景是动态的社交网络中用户关系不断变化、交易网络中节点和边每时每刻都在新增。动态图模型要同时捕捉图结构和时间演化双重信息。常见思路有两种时间快照法把连续时间切成多个快照每个快照是一个静态图再用时序模型LSTM、GRU串联快照的特征。连续时间法每条边带时间戳建模边事件发生的概率。典型方法是 Temporal Graph Networks用节点的时间邻居做消息聚合并用记忆模块保存节点历史状态。动态图模型适合的典型任务是链接预测给定时间 T 之前的图预测时间 T 之后哪些节点之间会产生新的边。PyG 中常用TemporalData来表示带时间戳的边数据训练集和测试集按照时间切分不能用随机划分。from torch_geometric.data import TemporalData # 假设边带时间戳 src torch.tensor([0, 1, 2, 3]) dst torch.tensor([1, 2, 3, 0]) t torch.tensor([1, 2, 3, 4]) msg torch.randn(4, 16) temporal_data TemporalData( srcsrc, dstdst, tt, msgmsg ) print(temporal_data)动态图模型对显存的消耗比静态图更大因为需要按时间窗口维护节点的历史状态。训练时批次内的时间跨度不要太大否则邻居数量会急剧膨胀。7.2 异构图多种节点和多种边的统一建模比动态图更常见的现实场景是异构图节点类型和边类型不止一种。比如在推荐系统中用户、商品、店铺是不同类型的节点“用户购买商品”和“商品属于店铺”是不同类型的边。如果强行把所有节点当成同一类处理会丢失重要的类型信息。异构图模型的核心能力是按关系类型分别聚合。以 R-GCNRelational Graph Convolutional Network为例它对每种关系类型使用独立的权重矩阵x_i^{(l1)} σ( Σ_{r ∈ R} Σ_{j ∈ N_i^r} W_r x_j^{(l)} )PyG 提供了HeteroData对象来构建异构图模型层可以用to_hetero()或HeteroConv包装普通的 GNN 层。from torch_geometric.data import HeteroData hetero_data HeteroData() # 两种节点类型user 和 item hetero_data[user].x torch.randn(100, 16) hetero_data[item].x torch.randn(50, 16) # 两种边类型user clicks itemitem belongs to category hetero_data[user, clicks, item].edge_index torch.tensor([[0, 1, 2], [1, 2, 3]]) hetero_data[item, belongs_to, category].edge_index torch.tensor([[0, 1], [10, 11]]) print(hetero_data) print(hetero_data.node_types) print(hetero_data.edge_types)实际业务中更常用的方案是 HANHeterogeneous Graph Attention Network它在“节点级注意力”和“语义级注意力”两个维度上做聚合。节点级注意力相当于 GAT 在某种关系下的邻居加权语义级注意力则是在不同元路径meta-path的结果之间做加权融合。HAN 适合需要解释性的场景比如风控系统中的多视角特征融合。异构图模型的实现通常在 API 使用上更繁琐但思路仍然统一每种关系类型都是一个独立的“消息传递通道”最终把各通道的结果融合。玩转异构图的关键不是写模型结构而是定义清楚节点类型、边类型和元路径。8. 模型训练、批量任务与性能观察8.1 小图全量训练与大图批处理Cora 这种几千节点的图可以直接把整张图送进模型这是全量训练。当图规模到达百万节点时全量计算不可行需要引入邻居采样和 mini-batch 训练。PyG 里的NeighborLoader是标准工具from torch_geometric.loader import NeighborLoader from torch_geometric.datasets import Planetoid dataset Planetoid(root./data, nameCora) data dataset[0] # 每个 batch 采样 128 个节点邻居采样数分别是 [25, 10] loader NeighborLoader( data, num_neighbors[25, 10], batch_size128, shuffleTrue, ) batch next(iter(loader)) print(fBatch 节点数: {batch.num_nodes}) print(fBatch 边数: {batch.num_edges})邻居采样会显著减少显存占用但代价是增加了代码复杂度。训练循环里要注意采样出来的子图中batch.train_mask等属性和原始图的掩码不同需要做映射。PyG 通常会自动处理节点索引重映射但边和节点的batch属性需要额外留意。批处理对显存的影响非常直观。以一个 8G 显存的中端显卡为例跑 Cora 全量训练占用不到 1G如果换成 OGB 的 ogbn-arxiv 数据集约 17 万节点全量训练比较容易爆显存而使用NeighborLoader可以把显存占用控制在 2G 到 4G具体看邻居数量和 batch_size。8.2 性能观察方法在训练 GNN 时建议关注两个指标显存占用Windows 用任务管理器 GPU 栏Linux 用nvidia-smi -l 1。单 Epoch 耗时在训练循环里用time.time()记录。如果你要对比不同模型固定相同的 epoch 数和 batch 大小才有意义。GCN 通常是最快的GAT 次之动态图模型一般最耗时。显存开销方面GAT 的多头机制会提升显存占用动态图的记忆机制会额外占用一部分存储。降低显存占用最简单的方法是减少邻居采样数量比如把num_neighbors[25, 10]改成[15, 5]显存占用可以降低一半左右但准确率也会有一定下降。另一个方法是减少注意力 heads 数GAT 从 8 heads 降到 4 heads显存大约能省 30%。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装 PyG 时找不到匹配的 torch_scatterPyTorch 和 CUDA 版本不匹配检查torch.__version__与nvcc -V重新安装与 CUDA 版本一致的 PyTorch再装 PyG训练 loss 不下降学习率过高或特征未归一化打印 loss 和梯度范数降低学习率、检查节点特征需要归一化GCN 测试准确率低于 0.70模型层数太深或过拟合检查是否用了 dropout回退到 2 层网络增大 dropout 比例GAT 训练速度极慢多头注意力和邻接矩阵规模过大单 Epoch 耗时统计减少 heads 数或改用 GCN 验证流程显存不足 OOMbatch_size 或邻居采样数过大查看报错中的 tensor 维度调小 batch_size、num_neighbors或转 CPU 测试异构图数据 loading 报错节点和边的类型名不一致打印HeteroData类型列表检查类型字符串完全一致动态图测试集出现未来信息泄露时间切分不正确检查边的时间戳分布严格按时间排序切分禁止随机划分CUDA out of memory 后重启仍报错进程残留占用显存nvidia-smi查看占用进程杀掉残留进程或重启内核层数增加在 GNN 里并不总是好事。GCN 堆到 5 层以上会出现过平滑问题所有节点表示趋同准确率反而下降。这被称为“深度 GNN 退化”排查准确率问题时要优先考虑。10. 最佳实践与使用建议10.1 从最简单的基线和最小数据集开始不管你是要用 GNN 做推荐还是分子性质预测第一次跑通永远是最重要的事。先用 Cora、Citeseer 这些几百 KB 级别的小数据集把训练流程全部跑通再迁移到自己的数据上。这样可以把“模型代码问题”和“数据问题”分开排查。我推荐的最小实验组合是两层 GCN Cora 数据集 200 epoch。如果这个组合跑不通问题通常在环境而不是模型。跑通之后再按顺序替换成 GAT 和异构图模型。10.2 数据划分要符合业务语义引文网络的标准做法是用掩码划分节点训练集、验证集、测试集的节点互不重叠。但如果你做的是链接预测必须按时间划分否则测试集里出现的边会“泄露”到训练集模型效果虚高。动态图模型尤其要小心这一点。正确做法是取前 80% 时间的边做训练后 20% 做测试等到做推理时再把时间窗口往后移动。这也是热词中“图神经网络与因果推理网络”比较关注的方向——在时间序列图数据上建模因果关系时避免信息泄露是第一原则。10.3 目录与工程化管理图神经网络实验通常涉及多个数据集、多种模型、多组超参数工程化管理能帮你省下大量时间。推荐结构gnn_workdir/ ├── data/ # 原始数据集 │ ├── cora/ │ └── citeseer/ ├── models/ # 模型定义 │ ├── gcn.py │ ├── gat.py │ └── hetero.py ├── scripts/ # 训练入口脚本 ├── logs/ # 训练日志 └── checkpoints/ # 模型权重训练脚本里至少记录三个信息数据集名称、模型名称、测试指标。日志文件用{dataset}_{model}_{time}.log命名后面做论文复现或模型对比时可以快速定位。10.4 合规与安全边界如果你的 GNN 项目涉及用户关系数据、交易网络数据、人脸关系图或社交网络必须注意数据来源合规和数据脱敏。训练数据不要包含未经授权的个人信息发布模型或评测结果前要检查是否泄漏敏感结构比如用户的社交关系链。涉及知识产权的内容应使用授权数据推荐系统项目尤其要注意对用户隐私的匿名化处理。动态图模型在预测用户行为时可能涉及敏感推断上线前应做影响评估。11. 总结与下一步GNN 这条技术线看起来内容很多但核心始终是消息传递机制。从基础 GNN 到 GCN是“聚合邻居特征 度归一化”从 GCN 到 GAT是把固定权重换成注意力权重动态图加的是时间维度异构图加的是类型维度。把这一条主线理清楚后面看到任何带前后缀的图模型都能快速拆解。最先应该跑的实验是两层 GCN 在 Cora 上的节点分类。它验证的是你整个图数据处理流程数据加载、边索引、训练循环、评估逻辑是否全部正确。这个流程不通其他模型没有必要往下试。最容易踩的坑有三个第一是edge_index没有对称化导致信息只能单向传播第二是动态图任务用随机划分产生了时序泄露测试指标虚高第三是盲目堆模型层数两层能达到的效果五层反而下降。如果你觉得本文内容有用建议收藏备用。下一步可以沿着两条线继续深入一条是搞懂 PyG 源码里MessagePassing的完整实现尝试自己写一个图扩散卷积层另一条是尝试在 Hetorogeneous Graph 数据上复现 HAN或者结合时间信息实现一个简单的动态图预测模型。每个方向跑通后你对 GNN 的理解都会上一个台阶。