PyG 半监督节点分类基准指南在 Cora / CiteSeer / PubMed 上评估 GCN、GAT、Cheb、SGC、ARMA 与 APPNP【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric本指南围绕 PyTorch GeometricPyG仓库中的 benchmark/citation 目录系统讲解如何在 Cora、CiteSeer、PubMed 三大经典引文网络上对 GCN、GAT、Cheb、SGC、ARMA、APPNP 六类图神经网络进行标准化评测。读完本文你将掌握这套基准脚本的完整运行方式、每个模型的命令行参数与默认值、固定划分与随机划分两种实验协议的差异以及如何复用其统一的训练 / 推理 / 性能剖析流水线做自己的对比实验。一、基准要回答的问题benchmark/citation是一套**半监督节点分类Semi-supervised Node Classification**评测脚本在图结构已知、仅少量节点带标签的前提下衡量模型对未标注节点类别的预测能力。其核心实验协议如下数据集Cora、CiteSeer、PubMed 三个经典引文网络均通过 PyG 的 Planetoid 数据集加载。方法GCN、GAT、ChebyChebyshev 卷积、SGC、ARMA、APPNP 共 6 种。重复次数每个实验重复 100 次--runs默认 100报告验证损失、测试精度的均值与标准差以体现随机初始化下的稳定性。划分协议既可以基于固定的 train/val/test 划分Planetoid 官方划分也可以使用--random_splits生成多个随机划分并报告跨多次重复实验的统计结果。从 run.sh 可以看出脚本面向的用户是需要在统一环境、统一协议下横向对比多种 GNN 架构的研究者与工程师目标是得到可复现、可统计的对比基线。二、目录结构与运行方式benchmark/citation目录下的每个模型对应一个独立可执行的 Python 脚本脚本核心算子torch_geometric.nn单独运行命令gcn.pyGCNConvpython gcn.py --datasetCoragat.pyGATConvpython gat.py --datasetCoracheb.pyChebConvpython cheb.py --datasetCora --num_hops3sgc.pySGConvpython sgc.py --datasetCora --K3arma.pyARMAConvpython arma.py --datasetCora --num_stacks2 --num_layers1 --shared_weightsappnp.pyAPPNPpropagation 模块python appnp.py --datasetCora --alpha0.1三个数据集名分别为Cora、CiteSeer、PubMed脚本中的--dataset参数是必填项。如需运行完整测试套件3 个数据集 × 6 种模型 × 固定 / 随机划分直接执行$ ./run.sh注意所有脚本默认会自动归一化节点特征NormalizeFeatures变换数据集缓存目录位于benchmark/data/数据集名由 datasets.py 中的osp.join(osp.dirname(osp.realpath(__file__)), .., data, name)决定首次运行会自动下载。三、数据集加载与特征归一化所有脚本统一通过 datasets.py 中的get_planetoid_dataset加载数据def get_planetoid_dataset(name, normalize_featuresFalse, transformNone): path osp.join(osp.dirname(osp.realpath(__file__)), .., data, name) dataset Planetoid(path, name) if transform is not None and normalize_features: dataset.transform T.Compose([T.NormalizeFeatures(), transform]) elif normalize_features: dataset.transform T.NormalizeFeatures() elif transform is not None: dataset.transform transform return dataset几个值得注意的细节底层使用torch_geometric.datasets.Planetoid加载的是经典的引文网络数据图节点为论文、边为引用关系。当--no_normalize_features未被指定时脚本传入normalize_featuresTrue为数据集挂上T.NormalizeFeatures()变换见 gcn.py 等处的调用将每行特征向量归一化为单位范数。dataset[0]返回单个Data对象包含x特征、edge_index边、y标签以及train_mask/val_mask/test_mask划分掩码这正是半监督设置的直接载体。四、固定划分与随机划分--random_splits的语义这是该基准区别于“单次训练”实验的关键设计。Planetoid 数据集自带官方固定划分而当传入--random_splits时每个 run 都会重新生成一套划分。划分逻辑实现在 train_eval.py 的random_planetoid_splits中遵循经典的半监督设置训练集每类随机抽取20个样本i[:20]即20 × num_classes个标注样本验证集其余样本中随机抽取500个测试集再取1000个。其实现先用(data.y i).nonzero()按类别取出样本索引并随机打乱再通过index_to_mask来自torch_geometric.utils将索引列表转换为布尔掩码写入data.train_mask/data.val_mask/data.test_mask。训练循环中每个 run 都会执行一次permute_masks(data, dataset.num_classes)见 train_eval.py保证 100 次重复各自独立采样。两种协议的定位协议命令特点固定划分python gcn.py --datasetCora划分固定仅随机初始化与数据顺序变化便于与文献中的官方结果对齐随机划分python gcn.py --datasetCora --random_splits每个 run 重新采样划分度量模型对划分选择的鲁棒性五、统一的训练 / 评估 / 推理流水线所有模型共享 train_eval.py 中的流水线这是本基准可复现性的基石。5.1 设备自动选择脚本启动时按优先级自动选择计算设备train_eval.pyCUDA GPU → Apple MPS → CPU无需手动指定。5.2 训练循环run_train核心流程train_eval.py若开启--compile对模型执行torch.compile(model)加速每个 run加载数据可选随机划分、model.reset_parameters()重置权重、用Adam优化器lr、weight_decay可配训练每轮 epoch 调用train()做一次前向 / 反向 / 更新def train(model, optimizer, data): model.train() optimizer.zero_grad() out model(data) loss F.nll_loss(out[data.train_mask], data.y[data.train_mask]) loss.backward() optimizer.step()每个 epoch 结束后调用evaluate()train_eval.py在train/val/test三套掩码上分别计算nll_loss与 argmax 预测精度早停策略--early_stopping默认 10仅当epoch epochs // 2后生效若当前验证损失高于此前early_stopping个 epoch 的平均验证损失则提前终止记录 100 次 run 中验证损失最低时对应的测试精度最终输出Val Loss: 0.xxxx, Test Accuracy: 0.xxx ± 0.xxx, Duration: x.xxxs即验证损失均值、测试精度均值 ± 标准差、单次 run 平均耗时——这份汇总正是横向对比六种模型的依据。5.3 推理基准模式run_inference与--inference--inference模式跳过训练只跑前向传播用于衡量纯推理开销见 train_eval.py全程torch.no_grad()可选--bf16将特征data.x转为torch.bfloat16并在 CPU 上启用torch.cpu.amp.autocast最后一个 epoch 用timeit()计时输出单次推理耗时。5.4 性能剖析--profile开启 PyG 的torch_profile来自torch_geometric.profile对训练或推理做算子级剖析并在结束后调用rename_profile_file(citation, 卷积类名, 数据集, 是否随机划分, train|inference)为 profile 文件命名见各脚本末尾便于批量对比不同模型、不同数据集下的算子耗时分布。六、六种模型的网络结构与参数速查六种模型均使用log_softmaxnll_loss的输出头差异集中在中间层架构与超参数。下表汇总各脚本的全部命令行参数与默认值供配置时对照。GCNgcn.py——两层GCNConv16 隐藏单元ReLU Dropout(0.5)lr0.01200 epochs早停 10参数类型默认值说明--datasetstr必填Cora / CiteSeer / PubMed--random_splitsflagFalse使用随机划分--runsint100重复实验次数--epochsint200训练轮数--lrfloat0.01学习率--weight_decayfloat0.0005Adam 权重衰减--early_stoppingint10早停耐心值--hiddenint16隐藏层维度--dropoutfloat0.5Dropout 概率--no_normalize_featuresflagFalse关闭特征归一化--inference/--profile/--bf16/--compileflagFalse推理 / 剖析 / bf16 / torch.compileGATgat.py——两层GATConv8 隐藏单元、8 头注意力输出层concatFalseELU Dropout(0.6)lr0.0051000 epochs早停 100。与 GCN 相比多出参数类型默认值说明--headsint8第一层注意力头数--output_headsint1输出层头数PubMed 建议 8Chebcheb.py——两层ChebConv--num_hops阶切比雪夫多项式ReLU Dropout(0.5)默认--num_hops3。SGCsgc.py——单层SGConvK2步图卷积后接线性分类cachedTrue缓存传播矩阵无中间激活lr0.1。它验证了“去除非线性、只保留线性传播”的简化模型在同任务上的竞争力。ARMAarma.py——两层ARMAConvARMA 滤波器参数参数类型默认值说明--num_stacksint1ARMA 堆叠数run.sh 中 2~3--num_layersint1每堆内部层数--shared_weightsflagFalse各层共享权重--skip_dropoutfloat0.75skip 连接上的 dropoutAPPNPappnp.py——先做两层 MLP64 隐藏单元预测再通过APPNP(K10, alpha0.1)进行个性化 PageRank 式传播K为传播步数、alpha为保留自身信息的概率把“预测”与“传播”解耦。七、完整测试套件run.sh的推荐配置run.sh 内置了社区调校过的超参数组合每种模型在每个数据集上分别跑一次固定划分 一次随机划分。将其展开可看到若干关键经验值CoraCheb 用--num_hops3SGC 用--K3 --weight_decay0.0005ARMA 用--num_stacks2随机划分时--num_stacks3--shared_weightsAPPNP 用--alpha0.1。CiteSeerCheb 固定划分用--num_hops2、随机划分用--num_hops3SGC 调为--K2 --weight_decay0.005权重衰减放大 10 倍ARMA 统一--num_stacks3。PubMedGAT 调整为--lr0.01 --weight_decay0.001 --output_heads8输出头数从 1 提到 8Cheb / SGC 用--num_hops2/--K2ARMA 用--num_stacks2固定划分时--skip_dropout0、随机划分时--skip_dropout0.5。可以看到同一模型在不同数据集上的最优超参差异显著如 SGC 的K、ARMA 的num_stacks这正是该套件存在的意义给出统一但各自调优的对比基线而不是“一套参数打天下”。八、推理基准inference.shinference.sh 提供纯推理方向的评测矩阵对每个数据集 × 模型分别跑 4 种组合——固定划分推理、随机划分推理、以及二者各自的--profile剖析版本。例如 Cora 上的 GCN 推理基准python gcn.py --datasetCora --inference python gcn.py --datasetCora --random_splits --inference python gcn.py --datasetCora --inference --profile python gcn.py --datasetCora --random_splits --inference --profile它可与benchmark/inference目录如 inference_benchmark.py配合用于评估模型部署前的推理延迟与算子瓶颈。九、如何扩展这套基准该目录的设计高度模块化扩展新模型只需三步无需改动共享代码新建脚本如my_model.py引入from citation import get_planetoid_dataset, random_planetoid_splits, run定义网络类实现reset_parameters()保证 100 次重复实验独立初始化与forward(data)输入data对象输出log_softmax后的[num_nodes, num_classes]张量解析参数后调用run(dataset, Net(dataset), runs, epochs, lr, weight_decay, early_stopping, inference, profile, bf16, compile, permute_masks)。共享流水线会自动为你处理设备选择、多 run 统计、早停、时间与精度汇总以及 profile 文件命名从而保证新方法与既有六种模型在完全一致的实验协议下可比。若需定制数据变换可直接向get_planetoid_dataset传入transform参数或参考 datasets.py 中T.Compose的组合方式。十、小结benchmark/citation是 PyG 中一套开箱即用、协议统一的半监督节点分类评测基准六种代表性 GNN 架构GCN / GAT / Cheb / SGC / ARMA / APPNP、三个经典引文数据集、固定与随机两套划分、100 次重复的统计报告外加训练 / 推理 / 剖析三种运行模式。无论是复现文献基线、为论文补充对比实验还是验证自定义模型的竞争力都可以直接复用 run.sh 与 train_eval.py 提供的标准化流水线将精力集中在模型本身的设计与调优上。【免费下载链接】pytorch_geometricGraph Neural Network Library for PyTorch项目地址: https://gitcode.com/GitHub_Trending/py/pytorch_geometric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
