GCN节点分类实战：Cora数据集完整流程（PyTorch代码）

这个系列走到第二篇，进度自然要往深走一点。上一篇我们把图数据的基本格式、邻接矩阵的存储方式以及一个最简图神经网络上的 demo 流程跑通了。但 demo 归 demo，离拿一个完整的任务练手还有距离。这一篇我们就补上这段路：用引文网络上的 Cora 数据集做一次完整的节点分类实战，从数据加载、邻接矩阵预处理，到两层 GCN 搭模型、训练评估，最后把准确率、F1 和分类报告一起拿出来，走通一条完整的链路。

这篇内容适合两类人：一是刚看完图神经网络原理、想趁热上手动手写的读者；二是已经跑过某些现成库封装好的 GAT 或 GraphSAGE，但还想搞清楚“底层到底怎么算”的人。整篇不会依赖重型的第三方图神经网络库，核心逻辑用 PyTorch 加 SciPy 就能完成。这样写的目的是让每一步都看得见、调得了，而不是在黑盒里改参数。

1. 项目背景与任务设计

1.1 为什么第二篇选“节点分类”这个任务

图神经网络能做的任务大致分三层：节点级、边级、图级。节点分类是最自然、也最容易讲透的切入点。原因也很实际：它的问题定义最清楚，给定一张图，每个节点都带一组特征，已知一部分节点的标签，要预测其余节点的标签。社交网络里的用户兴趣预测、交易网络中的风险节点识别、论文引文网络里的领域分类，本质都是这个形态。

做个生活化类比。想象一个班级：每个学生有自己的成绩单（节点特征），学生之间有同桌、朋友关系（边）。现在班主任只知道部分学生的兴趣标签，要推断其他学生的兴趣。单看成绩单也能猜一点，但更聪明的做法是看看“他的好朋友大多是哪个兴趣圈子”，因为社交影响和信息传播在我们的场景里非常常见。图神经网络做的事情，就是把这个“看看好朋友”的过程做成可学习的层。

这个任务对初学者的价值在于：输入输出都非常直观，评估指标也有公认标准。你在 Cora 上做到 80% 以上的测试准确率，就说明整个链路基本没问题。如果卡在 60% 以下，那大概率不是模型问题，而是数据预处理或者划分 Mask 出了问题。

1.2 技术选型：为什么先用 GCN，而不是 GAT 或 GraphSAGE

很多读者会问：既然现在有 GAT（图注意力网络）、GraphSAGE、GIN 这些更新更花哨的模型，为什么第二篇还要用 GCN？

我的回答是：因为 GCN 的传播逻辑最朴素，适合建立心智模型。GCN 的每一层做的事情，本质就是“所有邻居一视同仁地做加权求和”。这个“邻居等权平均”看起来简单，但它包含了图神经网络最核心的假设：节点特征需要通过邻域传播来平滑和增强。

理解了 GCN，再看 GAT 的注意力权重、GraphSAGE 的采样邻居、GIN 的求和池化，都是在“如何聚合邻居”这个点上做文章。地基不打牢，后面调模型真的会一头雾水。

GCN 的核心更新式是：

H^(l+1) = σ( D̃^(-1/2) Ã D̃^(-1/2) H^(l) W^(l) )

其中 Ã = A + I，I 是自环单位矩阵。这个公式看着吓人，实际上拆开就三件事：

• A 加 I：给每个节点加一个指向自己的边，这样聚合邻居信息时，自己的特征也能保留一份，不然每一层都只聚合别人，自己的信息会越来越弱。
• D̃^(-1/2) 做对称归一化：防止度数高的节点（邻居特别多）在求和后数值变得特别大，造成不同节点的特征尺度差异过大。对称归一化保证在无向图上信息传播是均衡的。
• H^(l) W^(l)：先对当前特征做线性变换，再让邻居信息沿着边流动。

1.3 项目流程与评估方式

这一篇的完整流程我建议这样安排：

评估指标上，准确率（Accuracy）是大家最容易看懂的，但它有一个小毛病：当类别不均衡时，多数类会主导分数。所以我会同时看 macro-F1，也就是每个类别的 F1 分别计算再取平均，这样能反应模型在少数类上的表现。Cora 一共 7 个类别，各类样本量不太均匀，只看准确率容易被“样本多的类”骗过去。

2. 数据准备：从原始图到可训练的张量

2.1 认识 Cora 数据集的图结构

Cora 是一个经典的引文网络数据集，常被用来做论文分类。它包含约 2708 个节点、1433 维词袋特征、7 个类别。每个节点代表一篇论文，每篇论文的特征向量是对应词表上的词频表示（0/1 值），边代表论文之间的引用关系。

拿到原始数据，我们会看到三块内容：

• features：形状是 (2708, 1433) 的矩阵，每行是论文的词袋特征；
• labels：形状是 (2708,) 的类别标签，取值 0 到 6；
• edges：引文关系列表，每一行是两个节点 ID，表示一条无向边。

在动手写模型之前，第一步是把这三块数据整理成统一的图结构。需要明确一点：Cora 的节点 ID 不一定从 0 连续编号，通常要先做一次映射，把原始 ID 重排成 0 到 N-1 的连续索引，这样后面做张量索引和 Mask 划分才不会错位。

我第一次处理这个数据集时踩过一个坑：直接用原始 ID 做索引，结果训练的时候模型报错“index out of range”。后来查了才发现数据文件里的节点编号有跳跃，不是合法的张量索引。

2.2 邻接矩阵的构建与稀疏存储

边文件通常是一个二维数组，第一列是源节点，第二列是目标节点。构建邻接矩阵有两种思路：一种是用 SciPy 的 coo_matrix 先构建稀疏矩阵，另一种是直接遍历边，在 Python 字典里记录邻居集合。

我建议直接上来就用 coo_matrix。原因很实际：稀疏矩阵后续可以无缝转成 PyTorch 的稀疏张量，在 GCN 前向传播里做高效的稀疏矩阵乘法。如果你用字典存邻居，后面还是要再转一次矩阵，多一步就有多一步出错的可能。

构建代码大概是这样的：

import numpy as np import scipy.sparse as sp import torch def build_adjacency(edge_list, num_nodes): row = edge_list[:, 0] col = edge_list[:, 1] # 用 coo_matrix 快速构建对称邻接矩阵 adj = sp.coo_matrix((np.ones(len(row)), (row, col)), shape=(num_nodes, num_nodes)) # 无向图需要转成对称形式，确保信息双向传播 adj = adj + adj.T.multiply(adj.T > adj) return adj

这里面 adj + adj.T.multiply(adj.T > adj) 是处理无向图的标准写法。它保证如果原始边文件里只有一条有向引用，构造后也能得到对称矩阵。如果你不做对称化，GCN 传播时信息只能从被引论文流向引用论文，结果会差不少。

2.3 对称归一化的数学原理与实现

这一小节是整个预处理里最关键的，很多人学 GCN 就死在这一步。

先说为什么要归一化。假设一个节点的度数（邻居数）是 1000，另一个节点的度数是 2。如果不做归一化，第一跳聚合后，高密度节点的特征数值会被邻居求和放得很大，低密度节点则很小。经过多层传播后，不同节点的特征尺度差异会越来越大，训练会非常不稳定。

GCN 原始论文用的是对称归一化：

A_norm = D^(-1/2) (A + I) D^(-1/2)

这里 D 是加了自环之后的度矩阵。为什么用 -1/2 而不是 -1？因为 -1/2 会同时作用于行和列，相当于“每条边两端的节点各除一次度平方根”。这样处理之后，矩阵的每一行和每一列的尺度都被控制住了，信息在无向图上的传播是均衡的。如果用 D^(-1)，那就是随机游走归一化，信息只按行归一化，更适合有向图或者随机游走类的模型（比如 GraphSAGE 对邻居的聚合逻辑就更接近后者）。

实现代码：

def normalize_adj(adj): # 加自环 adj = adj + sp.eye(adj.shape[0]) # 计算度 deg = np.array(adj.sum(axis=1)).flatten() # 度取 -1/2 次方，注意孤立节点度为 1（因为加了自环），不会出现除零 deg_inv_sqrt = np.power(deg, -0.5) # 转成对角稀疏矩阵 deg_inv_sqrt_mat = sp.diags(deg_inv_sqrt) # 对称归一化：D^-1/2 * A * D^-1/2 adj_norm = deg_inv_sqrt_mat.dot(adj).dot(deg_inv_sqrt_mat) return adj_norm.tocoo()

有个细节值得提：加自环之后，每个节点的度数至少是 1，所以不会出现度为 0 导致除零错误。这个操作看似简单，但如果你在归一化之前不加自环，但凡图里有孤立节点，就会在 np.power(0, -0.5) 处得到 inf 或者 nan，后面训练时梯度直接爆炸。这个坑我在项目里碰见过不止一次。

2.4 训练集、验证集、测试集的正确划分

节点分类和普通图像分类有一个重要区别：训练/验证/测试的划分不是“从所有样本里随机抽”，而是要非常小心，因为你面对的是同一张图上的节点，边会把它们连在一起。如果划分不当，训练集里节点的邻居恰好是测试集节点，那模型在训练时已经“瞥见”了测试节点的信息，结果会虚高。

Cora 上的经典划分是：每个类别取 20 个节点作为训练集（总共 140 个），500 个节点作为验证集，1000 个节点作为测试集。具体怎么分区，我建议这样写：

def split_nodes(labels, num_per_class=20, val_per_class=30): idx_train = [] idx_val = [] idx_test = [] for c in range(int(labels.max()) + 1): class_idx = (labels == c).nonzero(as_tuple=True)[0] class_idx = class_idx[torch.randperm(len(class_idx))] # 打乱顺序 idx_train.append(class_idx[:num_per_class]) idx_val.append(class_idx[num_per_class:num_per_class + val_per_class]) idx_test.append(class_idx[num_per_class + val_per_class:]) return (torch.cat(idx_train), torch.cat(idx_val), torch.cat(idx_test))

这里有两个关键点：

• 每个类都要有训练样本，不能整体随机抽，否则某些类可能一个训练样本都没有，模型根本学不会那个类别。
• 划分要基于节点特征和标签，但绝不能在“已经看到全图传播结果之后再划分”。也就是说，划分 Mask 要在 GCN 前向传播之前固定的。如果你把测试节点的标签也用于早停判断或者超参选择，那测试集就不再干净了。

2.5 特征归一化与稀疏张量转换

特征矩阵在输入模型前，一般还要做一次行归一化。为什么要做？因为 Cora 是词袋特征，不同论文的长度不同，原始特征向量里非零词的个数差异很大。行归一化让每个节点的特征向量都是单位长度，避免“长文”节点的特征天然比“短文”节点特征数值大好几倍。

行归一化实现很直接：

def normalize_features(features): row_sum = np.array(features.sum(axis=1)).flatten() row_sum_inv = 1.0 / row_sum row_sum_inv[np.isinf(row_sum_inv)] = 0.0 return sp.diags(row_sum_inv).dot(features)

特征矩阵也可以用 SciPy 稀疏矩阵存储，然后转换成 PyTorch 稀疏张量：

def sparse_mx_to_torch_sparse_tensor(sparse_mx): sparse_mx = sparse_mx.tocoo().astype(np.float32) indices = torch.from_numpy( np.vstack((sparse_mx.row, sparse_mx.col)).astype(np.int64) ) values = torch.from_numpy(sparse_mx.data) shape = torch.Size(sparse_mx.shape) return torch.sparse_coo_tensor(indices, values, shape)

这里一定要把 indices 转成 int64，values 转成 fp32，这是 PyTorch 稀疏张量的硬性要求。我见过有朋友把 indices 留在 int32，结果前向传播时直接报类型不匹配。

诚实地说，Cora 这么小的图（2708 节点），其实直接把邻接矩阵转成稠密矩阵也吃得消，大概 2708×2708 的 float32 也就 27MB 左右。但我不建议这么干，因为一旦你换到几百万节点的真实图，稠密矩阵就是天文数字。趁早养成“用稀疏矩阵”的习惯，后面接大数据集不吃亏。

3. GCN 模型搭建与训练全流程

3.1 亲手实现一个 GCNLayer

不依赖现成的图神经网络库，我们自定义一个 GCNLayer。这个类做的事情就是刚才公式里的两步：线性变换 + 邻居聚合。

import torch import torch.nn as nn import torch.nn.functional as F class GCNLayer(nn.Module): def __init__(self, in_dim, out_dim, dropout=0.5): super().__init__() self.weight = nn.Parameter(torch.randn(in_dim, out_dim) * 0.01) self.bias = nn.Parameter(torch.zeros(out_dim)) self.dropout = nn.Dropout(dropout) def forward(self, x, adj_norm): # 先做线性变换：x -> xW support = torch.mm(x, self.weight) # 再用稀疏邻接矩阵聚合邻居信息 out = torch.sparse.mm(adj_norm, support) out = out + self.bias return out

这里的初始化我特意用了 0.01 倍的标准正态分布，而不是 PyTorch 默认的 kaiming 初始化。原因是图卷积层的输出直接进入多层传播，初始权重太大会让第一层的聚合结果发散，早期损失那一下会飞得很高。小方差初始化在 GCN 这种浅层网络上是我比较习惯的做法。

torch.sparse.mm 是稀疏矩阵和稠密矩阵相乘的算子。adj_norm 是稀疏的归一化邻接矩阵，support 是稠密的线性变换结果。这一步的数学含义就是：每个节点把邻居变换后的特征按边权重加起来。

3.2 两层 GCN 网络结构

单层 GCN 只能看到一跳邻居，表达能力有限；两层 GCN 可以看到两跳邻居，足够让每个节点聚合到周围“社区”的信息。我在这篇里用两层做演示，这也是 GCN 论文里的标准配置。

class GCN(nn.Module): def __init__(self, in_dim, hidden_dim, out_dim, dropout=0.5): super().__init__() self.layer1 = GCNLayer(in_dim, hidden_dim, dropout) self.layer2 = GCNLayer(hidden_dim, out_dim, dropout) def forward(self, x, adj_norm): h = self.layer1(x, adj_norm) h = torch.relu(h) out = self.layer2(h, adj_norm) return torch.log_softmax(out, dim=1)

第二层输出后接 log_softmax，因为后面我们搭配 nn.NLLLoss 使用。如果你更喜欢用 nn.CrossEntropyLoss，那 forward 里就不需要 log_softmax，直接输出原始 logits 就行。这里选 log_softmax 只是我个人的习惯，没有本质区别。

隐藏层维度我选了 16。这个数字看起来很小，但在 Cora 上足够用了，因为类别只有 7 个，特征传播的主要贡献来自图结构而不是宽大的隐藏层。盲目把 hidden_dim 加到 256 或者 512，反而容易过拟合，训练集准确率很高，测试集却上不去。

3.3 训练循环与早停机制

模型定义好之后，训练循环本身其实不复杂，但有几个细节决定最终效果。

超参数配置：

学习率 0.01 配上权重衰减 5e-4 是 GCN 开山论文里验证过的组合，我在几个不同的图上试过，直接沿用非常稳。Dropout 开 0.5 在节点分类任务上几乎是默认值，因为图数据的训练节点往往很少（Cora 上只有 140 个），模型非常容易过拟合，过高的 Dropout 反而能抑制过拟合。

model = GCN(in_dim=features.shape[1], hidden_dim=16, out_dim=7) optimizer = torch.optim.Adam(model.parameters(), lr=0.01, weight_decay=5e-4) criterion = nn.NLLLoss() best_val_acc = 0.0 patience = 10 bad_counter = 0 train_losses = [] for epoch in range(200): model.train() optimizer.zero_grad() output = model(features, adj_norm) loss = criterion(output[idx_train], labels[idx_train]) loss.backward() optimizer.step() train_losses.append(loss.item()) model.eval() with torch.no_grad(): output = model(features, adj_norm) preds = output.argmax(dim=1) val_acc = (preds[idx_val] == labels[idx_val]).float().mean().item() if val_acc > best_val_acc: best_val_acc = val_acc bad_counter = 0 torch.save(model.state_dict(), "best_gcn.pt") print(f"Epoch {epoch}: loss={loss.item():.4f}, val_acc={val_acc:.4f} (best)") else: bad_counter += 1 if bad_counter >= patience: print(f"Early stopping at epoch {epoch}, best_val_acc={best_val_acc:.4f}") break

早停的逻辑是：验证集准确率连续多少轮不涨，就停止训练并恢复最佳模型。这里不是简单地把最后一个 epoch 的权重拿来用，而是用 torch.save 保存了验证集表现最好的那一份权重。很多初学者忽略这一点，训练完之后直接拿最后一个 epoch 的模型去测测试集，结果往往不如 best 模型稳定。

实现时注意一个细节：每次 epoch 结束评估验证集前，一定要切到 model.eval() 模式，否则 Dropout 层还在做随机丢神经元，验证集指标会上下抖动，早停判断就不准了。

3.4 测试集评估与指标解读

训练结束后，加载最佳模型权重，在测试集上做一次完整评估：

model.load_state_dict(torch.load("best_gcn.pt")) model.eval() with torch.no_grad(): output = model(features, adj_norm) preds = output.argmax(dim=1) test_acc = (preds[idx_test] == labels[idx_test]).float().mean().item() print(f"Test accuracy: {test_acc:.4f}")

光是准确率一个数字还不够，我会同时输出 macro-F1 和每个类别的分类报告，这样才能看到模型在各类别上的具体表现。

from sklearn.metrics import f1_score, classification_report print("Macro F1:", f1_score(labels[idx_test].cpu(), preds[idx_test].cpu(), average="macro")) print(classification_report(labels[idx_test].cpu(), preds[idx_test].cpu()))

在 Cora 的标准划分下，GCN 的测试准确率一般能到 0.80 到 0.82 之间，macro-F1 也基本在同一水平。如果你第一次跑出 0.80 左右，说明链路通了，模型本身没有大问题。如果只有 0.6 左右，最可能的问题出在数据预处理，尤其是邻接矩阵有没有对称化、归一化有没有正确执行、Mask 划分有没有错误。

3.5 可视化训练损失与节点嵌入

训练损失曲线是最直接的监控手段。我通常会在训练结束后用 matplotlib 画一下，确认损失确实在下降而不是来回震荡。

import matplotlib.pyplot as plt plt.plot(train_losses) plt.xlabel("Epoch") plt.ylabel("Training Loss") plt.title("GCN Training Loss") plt.savefig("training_loss.png", dpi=120)

如果你想把模型产出的中间表示也可视化，可以把两层 GCN 的输出节点嵌入拿下来，用 TSNE 降维到二维画个散点图。这一步不是必需的，但对理解“图神经网络到底有没有把同类节点聚在一起”很有帮助。我会在第二层 ReLU 激活之后拿节点表示，注意层数别太深，深层输出的过平滑会让所有点糊成一团。

4. 常见问题与调优经验

4.1 过平滑问题：为什么 GCN 不宜叠太深

GCN 层数越多，每个节点聚合的邻居范围越大，但代价是不同节点的表征会越来越相似。这种现象叫过平滑（over-smoothing）。在图像任务里，网络越深越强；在图任务里，GCN 到三到四层以上性能就明显下降。Cora 上用两层效果最好，三层就有点危险，再往上测试准确率会加速下滑。

我接过的某个项目里有位同事把 GCN 叠了八层，结果测试集准确率还不如单层，当时怎么调都上不去。后来把层数压到两层之后，效果立刻恢复。这说明图模型的深度和宽度跟 CV 模型不是一个套路，不能盲目“深度至上”。

应对过平滑常见手段包括：加残差连接（把输入特征直接加到输出上）、跳连结构（中间层特征跨层传递）、或者换成 GAT 这种可以学习邻居权重的模型。第二篇里暂且先用两层 GCN 打底，之后扩展时再考虑这些变体。

4.2 数据泄漏：Mask 设置里的隐形陷阱

数据泄漏是图节点分类里最容易犯、也最隐蔽的错误。举例来说，如果我在训练过程中用验证集准确率来调整学习率、Dropout、层数，而且验证集和测试集划分不够干净，那测试集指标就是虚高的。更严重的错误是：有人先在所有节点上跑一遍模型，选出置信度高的节点作为训练集再训练，这等于模型已经提前看到了测试节点的信息，结果是假的。

正确做法是：数据划分在训练前一次性固定，之后任何超参调整只能看验证集，测试集只能碰一次。如果你反复用测试集调参，即使没有显式标签泄漏，也会因为“测试集选择偏差”让结果失真。我自己的习惯是，测试集指标只在最后阶段跑一次，其他时候都用验证集替代。

4.3 稀疏矩阵操作的坑

用 PyTorch 稀疏张量有几点要特别注意：

• 稀疏张量的 indices 必须是 int64，values 必须是 fp32，否则报类型错误；
• 训练过程中不要调用 to_dense() 转成稠密矩阵，在节点数大的图上会直接吃满内存；
• 反向传播时，邻接矩阵本身是常量，不参与梯度更新，只有 W 和 bias 需要梯度；
• 如果图很大，建议把邻接矩阵固定在显存里，不在每个 epoch 重建。

我调试过程中还遇到过一个诡异问题：训练时偶尔出现 NaN loss。排查到最后，发现是有一次把邻接矩阵的 values 写成了 int，然后稀疏矩阵乘法里隐式转换出了问题。这个类型问题很隐蔽，报错不一定直接指着你的 values 说事，有时候表现为 loss 突然变成 nan。如果遇到这种情况，第一反应就是去检查稀疏矩阵的 dtype。

4.4 随机种子与可复现性

图神经网络训练结果会受到三种随机源影响：PyTorch 的权重初始化与 Dropout、NumPy 的数据打乱、Python 内置 random 的随机行为。为了实验结果可复现，我建议在训练脚本开头统一固定种子：

import random import numpy as np import torch def set_seed(seed=42): random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) torch.backends.cudnn.deterministic = True torch.backends.cudnn.benchmark = False

固定种子之后，同一份代码在不同时间跑出来的结果应该基本一致，浮动通常在 0.001 以内。这在写技术博客或者给合作方复现结果时非常重要，不然你报一个准确率，人家复现不出来就尴尬了。

4.5 调参心得与问题速查表

实际操作中，我遇到过不少初学者反复问同样的问题，这里整理一个速查表：

这条速查表不只是给 Cora 用，你换到其他数据集的节点分类任务，排查方向基本一致。很多图神经网络项目上线前的问题，最后都落在数据预处理和 Mask 划分上，而不是模型结构本身。

结尾：这套链路跑通之后还能干什么

做完 Cora 节点分类这个实战，我个人最大的收获不是那个 0.81 的准确率，而是把 GCN 的传播过程彻底从“公式”变成了“手感”。再往后扩展时，很多事就顺了。比如把这个模型的 GCNLayer 换成 GATLayer，你只需要把“等权聚合”改成“注意力加权聚合”；做边预测时，只要把两层 GCN 输出的节点嵌入拿去算相似度；做图分类时，再加一个全局读出层把节点表示池化成图表示。这个第二篇相当于给后续所有图模型标了一个基准点，后续的每一篇都会以它能跑的代码为起点。

另外提一个我在多个项目里验证过的小建议：正式开始调参之前，先把数据链路和指标脚本固化下来，确保每次跑模型都不会因为数据预处理不一致而产生偏差。图神经网络的坑很多都在“看不见的边上”，把数据准备工作做扎实，后面模型怎么改都有底气。