企业官网建设流程全解析

JittorGeometric是一个基于 Jittor 深度学习框架构建的图机器学习（GNN）库，内置 GCN、GAT、GraphSAGE 等 40+ 图神经网络模型、高性能稀疏算子和丰富数据集加载器。本教程带你从零开始：安装环境 → 理解图卷积核心概念 → 在 Cora 数据集上完整训练GCN、GAT、GraphSAGE三大经典 GNN 模型，跑通第一个图卷积分类任务。

一、为什么选择 JittorGeometric？

JittorGeometric 面向 GNN 研究与教学场景，对新手非常友好：

库的核心模块组织如下，后续章节会逐一对应：

• 卷积层（GCN/GAT/GraphSAGE 等）：jittor_geometric/nn/conv/
• 稀疏矩阵与消息传递算子：jittor_geometric/ops/
• 数据集加载器：jittor_geometric/datasets/
• 全部官方示例代码：examples/

二、三步完成 JittorGeometric 安装

环境要求：Python 3.10+，GPU 训练需 CUDA 11.0+（没有 GPU 也能在 CPU 上跑通小数据集）。

第 1 步：创建 conda 环境

conda create -n jittorgeometric python=3.10 conda activate jittorgeometric

第 2 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/ji/JittorGeometric cd JittorGeometric

第 3 步：一键安装（自动安装 Jittor 及依赖）

pip install .

依赖清单见 requirements.txt（含jittor、numpy、scipy、networkx等）。

验证安装：直接运行 GCN 示例即可，成功的话你会看到逐 epoch 的准确率日志：

python examples/gcn_example.py --dataset cora

💡 提示：仓库已附带 Cora 数据集（data/cora/目录），本地运行无需联网下载。

三、图卷积三大核心概念（新手必读）

在动手前，先搞懂 GNN 训练的三个关键概念，读示例代码时就不会迷路。

1. Data 对象：图的"数据容器"

一个Data对象封装了整张图的全部信息：

• data.x：节点特征矩阵（如论文的词袋特征）
• data.edge_index：边的索引（源节点、目标节点两条数组）
• data.y：节点标签
• data.train_mask / val_mask / test_mask：训练/验证/测试掩码

Cora 是经典的半监督节点分类数据集：节点是机器学习论文，边是引用关系，任务是 7 分类。它由 jittor_geometric/datasets/planetoid.py 中的Planetoid类加载。

2. 边归一化 + 稀疏矩阵格式：图卷积的"预处理"

所有卷积层都不直接吃原始边表，而是先用gcn_norm/sage_norm完成邻接矩阵归一化（加自环、按度归一），再转成 CSR/CSC 稀疏格式：

edge_index, edge_weight = gcn_norm( edge_index, edge_weight, v_num, improved=False, add_self_loops=True) with jt.no_grad(): data.csc = cootocsc(edge_index, edge_weight, v_num) data.csr = cootocsr(edge_index, edge_weight, v_num)

对应的底层 C++ 算子（如 cootocsc.py、spmmcoo.py）就是 JittorGeometric 性能快的关键。

3. 三种卷积层：GCN vs GAT vs SAGE

三者源码分别在：

• jittor_geometric/nn/conv/gcn_conv.py
• jittor_geometric/nn/conv/gat_conv.py
• jittor_geometric/nn/conv/sage_conv.py

四、实战一：训练你的第一个 GCN 图卷积模型

完整代码见 examples/gcn_example.py，整体流程只有四步。

第 1 步：加载 Cora 数据集

from jittor_geometric.datasets import Planetoid import jittor_geometric.transforms as T dataset = Planetoid(path, 'cora', transform=T.NormalizeFeatures()) data = dataset[0]

T.NormalizeFeatures()会对特征做行归一化，是图节点分类的标准预处理。

第 2 步：定义两层 GCN 网络

from jittor_geometric.nn import GCNConv class Net(nn.Module): def __init__(self, dataset, dropout=0.8): super(Net, self).__init__() self.conv1 = GCNConv(in_channels=dataset.num_features, out_channels=256) self.conv2 = GCNConv(in_channels=256, out_channels=dataset.num_classes) self.dropout = dropout def execute(self): x, csc, csr = data.x, data.csc, data.csr x = nn.relu(self.conv1(x, csc, csr)) x = nn.dropout(x, self.dropout, is_train=self.training) x = self.conv2(x, csc, csr) return nn.log_softmax(x, dim=1)

注意GCNConv的输入是(x, csc, csr)——节点特征 + 预处理好的稀疏矩阵，这正是第三节讲的核心概念。

第 3 步：训练循环

model = Net(dataset) optimizer = nn.Adam(model.parameters(), lr=0.001, weight_decay=5e-4) for epoch in range(200): train() # 前向传播 → cross_entropy_loss → optimizer.step(loss) train_acc, val_acc, test_acc = test() # 三个掩码上的准确率 if val_acc > best_val_acc: best_val_acc, final_test_acc = val_acc, test_acc

Jittor 风格的优化器更新只需一行optimizer.step(loss)，梯度计算由框架自动完成。

第 4 步：运行并查看结果

python examples/gcn_example.py --dataset cora

训练 200 个 epoch 后，示例会输出最终指标（示例中记录了训练耗时）：

Final Results across 1 splits: Average Val Acc: 0.xxxx Average Test Acc: 0.xxxx Training time: x.xx s

在 Cora 上，两层 GCN 的典型测试准确率约为81%，GPU 下几十秒即可跑完。

五、实战二：GAT 图注意力网络训练

GAT 的完整示例见 examples/gat_example.py，整体流程与 GCN 完全一致，只有模型定义不同：

from jittor_geometric.nn import GATConv self.conv1 = GATConv(dataset.num_features, 128, e_num, cached=True) self.conv2 = GATConv(128, dataset.num_classes, e_num, cached=True)

两个关键差异：

1. 注意力加权：GATConv 通过ScatterToEdge → 注意力计算 → EdgeSoftmax → 聚合的流水线（见 gat_conv.py），让模型自适应地学习"哪个邻居更重要"，而不是像 GCN 一样对所有邻居一视同仁。
2. cached=True：边级注意力分数只计算一次并缓存，后续 epoch 直接复用，显著提速。

运行方式：

python examples/gat_example.py --dataset cora

GAT 在 Cora 上的典型测试准确率约为83%，略高于 GCN，这也是注意力机制的价值所在。

六、实战三：GraphSAGE 归纳式学习

GraphSAGE 示例见 examples/sage_example.py。它的"杀手锏"是归纳式学习：采样邻居、聚合信息，因此能泛化到训练时没见过的图和新节点。

from jittor_geometric.nn import SAGEConv self.conv1 = SAGEConv(in_channels=dataset.num_features, out_channels=256, cached=True, root_weight=False) self.conv2 = SAGEConv(in_channels=256, out_channels=dataset.num_classes, cached=True, root_weight=False)

与 GCN 的两处不同：

• 归一化使用sage_norm（按邻居数做度归一，见 sage_conv.py），而非 GCN 的对称归一化；
• 前向传播直接传入edge_index：self.conv1(x, edge_index)，内部走消息传递路径。

python examples/sage_example.py --dataset cora

此外，所有示例都支持切换数据集，例如--dataset citeseer、--dataset pubmed乃至 OGB 的ogbn-arxiv，一行命令即可换库训练。

七、常见问题与调参技巧

🔧调参小贴士：示例统一采用 Adam 优化器，GCN/SAGE 用lr=0.001 + weight_decay=5e-4，GAT 用lr=5e-3 + weight_decay=1e-4——不同模型的最优超参差异不小，迁移经验时注意参考对应示例文件。

八、从示例出发：探索 40+ 模型库

跑通三大经典模型后，你可以沿着 examples/ 目录继续探索：

• 谱方法：ChebNet（cheb_example.py）、BernNet（bernnet_example.py）、GPRGNN（gprgnn_example.py）
• 更深的 GCN：GCNII（gcn2_example.py）、SGC（sgc_example.py）
• 图 Transformer：Graphormer（graphormer_example.py）、PolyFormer（polyformer_example.py）
• 动态图：TGN（tgn_example.py）、DyRep（dyrep_example.py）
• 大规模分布式 GCN 训练：examples/dist_gcn/dist_gcn.py

每个模型文件都是"开箱即跑"的独立脚本，改一个参数就能实验，是学习 GNN 架构差异的最佳教材。

写在最后

至此，你已经完成了 JittorGeometric 的安装，并掌握了GCN 图卷积、GAT 注意力、GraphSAGE 归纳式学习三种经典 GNN 的完整训练流程。建议的下一步：先复现 Cora 上三个模型的准确率差异，再换--dataset pubmed观察规模变化下的表现，最后挑战 OGB 数据集——GNN 之路，就从这条"图卷积实战"开始吧！🎯