基于 GCN 的 Cora 节点分类

本项目使用 Jittor 和 Jittor Geometric 实现两层图卷积神经网络（Graph Convolutional Network，GCN），完成计图比赛热身赛中的 Cora 节点分类任务。

项目包含数据加载、特征归一化、图结构归一化、GCN 模型训练、验证集评测以及测试集预测结果生成等完整流程。

1. 项目结构

.
├── data/
│   └── cora.pkl
├── gcn.py
├── README.md
├── requirements.txt
├── LICENSE
├── .gitignore
└── result.json

各文件说明如下：

• gcn.py：数据处理、GCN 模型定义、训练、验证和预测代码；
• data/cora.pkl：比赛提供的预处理 Cora 数据文件，不提交到代码仓库；
• requirements.txt：Python 依赖及版本；
• LICENSE：项目开源许可证；
• .gitignore：Git 忽略规则；
• result.json：程序生成的测试节点预测结果。

2. 运行环境

本项目已在以下环境中运行验证：

• 操作系统：Linux（AutoDL）
• Python：3.10
• GPU：NVIDIA GeForce RTX 4090 24 GB
• NVIDIA Driver：580.105.08
• Jittor CUDA：12.2
• cuDNN：8
• Jittor：1.3.9.14
• Jittor Geometric：2.0.0
• NumPy：1.24.0
• 随机种子：42

Jittor 使用即时编译机制，首次运行时需要编译 C++ 和 CUDA 算子，因此第一次运行时间通常较长。

3. 环境安装

3.1 创建 Conda 环境

source "$(conda info --base)/etc/profile.d/conda.sh"
conda create -n jittor_gcn python=3.10 -y
conda activate jittor_gcn

检查 Python 版本：

python --version

应显示 Python 3.10。

3.2 安装 Python 依赖

进入项目根目录：

cd ~/autodl-tmp

安装依赖：

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

如果访问 GitHub 时出现临时 TLS 连接错误，可以重新执行安装命令。Jittor Geometric 使用 GitHub 官方源码压缩包安装。

3.3 配置 Jittor CUDA

本项目使用 Jittor 提供的 CUDA 12.2 和 cuDNN 8 环境。

设置环境变量：

export JTCUDA_VERSION=12.2
export OMP_NUM_THREADS=16
export use_cutlass=0
unset nvcc_path

安装 Jittor CUDA：

python -m jittor_utils.install_cuda

安装完成后，Jittor CUDA 通常位于：

~/.cache/jittor/jtcuda/cuda12.2_cudnn8_linux/

为了在每次激活 Conda 环境时自动设置变量，可以执行：

mkdir -p "$CONDA_PREFIX/etc/conda/activate.d"

tee "$CONDA_PREFIX/etc/conda/activate.d/jittor_env.sh" > /dev/null <<'ENV'
export JTCUDA_VERSION=12.2
export OMP_NUM_THREADS=16
export use_cutlass=0
unset nvcc_path
ENV

重新激活环境：

conda deactivate
conda activate jittor_gcn

3.4 验证 Jittor GPU

创建一个简单的 GPU 张量并执行计算：

python -c "import jittor as jt; jt.flags.use_cuda=1; x=jt.array([1.0,2.0,3.0]); print((x*2).numpy())"

正常情况下应输出：

[2. 4. 6.]

4. Jittor Geometric 兼容处理

当前 Jittor Geometric 2.0 的 SpmmCsr Python 接口向底层算子传入了 trans_A 和 trans_B，而 Jittor 1.3.9.14 中的 cusparse_spmmcsr 只接受七个参数。

对于本项目使用的无向 Cora 图，经过 gcn_norm 后的邻接传播矩阵是对称的，因此可以删除这两个额外的转置参数。

安装依赖后，执行：

SPMM_FILE="$CONDA_PREFIX/lib/python3.10/site-packages/jittor_geometric/ops/spmmcsr.py"

cp "$SPMM_FILE" "${SPMM_FILE}.bak"

sed -i \
's/,v_num,v_num,trans_A,trans_B)/,v_num,v_num)/' \
"$SPMM_FILE"

sed -i \
's/,self\.v_num,self\.v_num,self\.trans_A,self\.trans_B)/,self.v_num,self.v_num)/' \
"$SPMM_FILE"

检查修改结果：

grep -n "cusparse_spmmcsr" "$SPMM_FILE"

有效调用的结尾应分别为：

..., v_num, v_num).fetch_sync()

和：

..., self.v_num, self.v_num).fetch_sync()

该处理仅适用于当前无向 Cora 图任务。如果用于非对称有向图，需要使用真正支持转置参数的稀疏矩阵乘法实现。

5. 数据准备

本项目使用比赛提供的预处理 Cora 数据：

data/cora.pkl

请将 cora.pkl 放在项目根目录下的 data/ 文件夹中：

项目根目录/
├── data/
│   └── cora.pkl
└── gcn.py

运行前检查数据文件：

ls -lh data/cora.pkl

cora.pkl 应包含以下字段：

x
y
edge_index
train_mask
val_mask
test_mask
num_features
num_classes

其中：

• x：节点特征矩阵；
• y：节点类别标签；
• edge_index：图的边连接关系；
• train_mask：训练节点掩码；
• val_mask：验证节点掩码；
• test_mask：测试节点掩码；
• num_features：节点特征维数；
• num_classes：节点类别数量。

根据比赛开源规范，数据文件不直接提交到 Git 仓库。

6. 模型说明

本项目使用两层 GCN：

1. 第一层将输入节点特征映射到 256 维隐藏空间；
2. 使用 ReLU 激活函数；
3. 使用 Dropout 抑制过拟合；
4. 第二层输出各节点所属类别的 logits。

GCN 的传播形式为：

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

主要模型参数如下：

参数	数值
隐藏层维数	256
Dropout	0.8
学习率	0.01
Weight decay	0.0005
训练轮数	200
随机种子	42

优化器使用 Adam，损失函数使用交叉熵损失。

7. 训练与评测

确认已经激活环境：

conda activate jittor_gcn

进入项目根目录：

cd ~/autodl-tmp

检查代码语法：

python -m py_compile gcn.py

开始训练：

python gcn.py

如需同时保存日志：

mkdir -p outputs
python gcn.py 2>&1 | tee outputs/train.log

本项目的训练、验证和测试预测集成在同一个入口脚本中，不需要额外的命令行参数。

8. 评价指标

本项目使用节点分类准确率（Accuracy）作为验证指标：

Accuracy = 正确分类的节点数 / 参与评测的节点总数

训练过程中每隔 20 个 epoch 输出训练集准确率和当前最佳验证集准确率。

9. 实验结果

在上述环境下运行 200 个 epoch，得到以下结果：

模型	数据集	随机种子	最佳验证准确率
GCN	Cora	42	0.8080

由于测试节点标签未公开，本项目不计算测试集准确率，而是生成测试节点的预测类别。

本次运行共生成：

1000

个测试节点的预测结果。

受 GPU、CUDA、Jittor 版本以及算子编译环境影响，不同环境中的结果可能存在小幅差异。

10. 预测结果

训练结束后，程序自动对测试集节点进行预测，并生成：

result.json

结果格式如下：

{
  "节点编号": 预测类别
}

可以执行以下命令检查结果：

ls -lh result.json
head -n 20 result.json

本次运行共预测 1000 个测试节点。

11. 可复现性说明

为提高实验的可复现性，本项目采用以下设置：

• 固定随机种子为 42；
• 使用固定的数据路径 data/cora.pkl；
• 使用固定的 Python 和核心依赖版本；
• 使用固定的模型结构和训练超参数；
• 训练和预测使用统一入口 gcn.py；
• 使用 .gitignore 排除数据、缓存和训练日志；
• 在 README 中记录 Jittor Geometric 稀疏算子兼容处理。

Jittor 使用异步执行和即时编译机制，不同 GPU、CUDA 或编译器环境下可能出现合理的数值差异。

12. 常见问题

12.1 找不到数据文件

如果出现：

FileNotFoundError: data/cora.pkl

请执行：

cd ~/autodl-tmp
ls -lh data/cora.pkl

确认当前目录是项目根目录。

12.2 CUTLASS 下载校验失败

如果出现 CUTLASS 的 MD5 校验错误，执行：

rm -f ~/.cache/jittor/cutlass/cutlass.zip
export use_cutlass=0

本项目不依赖 CUTLASS。

12.3 找不到 cuDNN

如果出现：

libcudnn_ops_infer.so not found

执行：

export JTCUDA_VERSION=12.2
unset nvcc_path
python -m jittor_utils.install_cuda

12.4 cusparse_spmmcsr 参数数量错误

如果出现：

Wrong inputs arguments
cusparse_spmmcsr

请按照“Jittor Geometric 兼容处理”一节修改 spmmcsr.py。

13. 第三方依赖与声明

本项目使用以下开源软件：

• Jittor
• Jittor Geometric
• NumPy
• SciPy
• NetworkX

Jittor Geometric 采用 Apache License 2.0。Cora 数据集的版权和使用许可归原数据集发布者所有，本仓库不直接分发 cora.pkl。

如果代码参考或修改自比赛模板或其他第三方代码，应在项目中保留相应声明，并注明代码来源和许可证。

14. License

本项目采用 MIT License，具体内容见 LICENSE。