计图挑战赛赛道一热身赛：基于 Cora 的 GCN 节点分类

1. 项目简介

本项目面向计图挑战赛赛道一热身赛，使用 Jittor 实现两层图卷积网络（Graph Convolutional Network，GCN），在基于 Cora 的引文网络数据集上完成节点分类任务。

数据集中的每个节点表示一篇论文，节点特征为词袋特征，边表示论文之间的引用关系。训练集和验证集节点具有真实标签，测试集节点标签被隐藏，需要通过训练后的模型预测其所属类别。

本项目生成的 result.json 已通过线上评测，达到赛题要求的测试集准确率阈值。

2. 项目结构

.
├── gcn.py          # GCN 模型、训练、验证和预测代码
├── result.json     # 测试集节点预测结果
├── README.md       # 项目说明文档
└── data/
    └── cora.pkl    # 比赛提供的数据集，不上传至开源仓库

说明：data/cora.pkl 由比赛发布包提供。按照开源规范，原始数据文件不应提交到代码仓库。

3. 数据集说明

本项目使用比赛提供的 Cora 引文网络数据集，主要信息如下：

节点数：2708
边数：5429
节点特征维度：1433
类别数：7
任务类型：半监督节点分类

data/cora.pkl 中包含以下字段：

x：节点特征矩阵，形状为 2708 × 1433
y：节点标签，测试集节点标签为 -1
edge_index：图的边列表，形状为 2 × num_edges
train_mask：训练集节点掩码
val_mask：验证集节点掩码
test_mask：测试集节点掩码
num_classes：类别数量
num_features：节点特征维度

4. 环境安装

建议优先使用比赛官方提供的运行环境。

基础环境：

Python 3.8 或更高版本
NumPy
Jittor

安装依赖：

pip install numpy jittor

安装完成后，可以运行以下命令检查 Jittor 是否可用：

python -c "import jittor as jt; print(jt.__version__)"

如果使用 GPU，请确保 CUDA、显卡驱动与 Jittor 环境正确匹配。

5. 数据准备

将比赛提供的 cora.pkl 放入项目根目录下的 data 文件夹：

data/cora.pkl

运行前确认目录结构如下：

.
├── gcn.py
└── data/
    └── cora.pkl

代码默认从以下相对路径读取数据：

with open("data/cora.pkl", "rb") as f:
    data = pickle.load(f)

因此需要在项目根目录执行训练命令。

6. 模型方法

本项目采用两层 GCN。模型结构为：

1433 维输入特征
        ↓
线性变换：1433 → 16
        ↓
归一化邻接矩阵传播
        ↓
ReLU + Dropout
        ↓
线性变换：16 → 7
        ↓
归一化邻接矩阵传播
        ↓
7 类节点预测结果

首先根据 edge_index 构建无向邻接矩阵，并加入自环：

A_hat = A + I

随后进行对称归一化：

A_norm = D^(-1/2) A_hat D^(-1/2)

两层图卷积的主要计算过程为：

H1 = ReLU(A_norm X W1)
Z  = A_norm H1 W2

其中：

X 为节点特征矩阵
A_norm 为归一化后的邻接矩阵
W1、W2 为可训练参数
Z 为每个节点对应 7 个类别的预测分数

7. 训练配置

代码中的主要超参数如下：

参数	数值
随机种子	42
隐藏层维度	16
Dropout	0.5
训练轮数	200
学习率	0.01
权重衰减	0.0005
优化器	Adam
损失函数	CrossEntropyLoss
验证间隔	每 20 轮

为提高实验可复现性，代码同时固定了 NumPy 和 Jittor 的随机种子：

jt.set_seed(42)
np.random.seed(42)

训练过程中，每 20 轮在验证集上计算一次准确率，并保存验证准确率最高的模型参数。训练结束后恢复最佳参数，再对测试集节点进行预测。

8. 训练与预测

在项目根目录运行：

python gcn.py

该命令会依次完成：

加载 data/cora.pkl
构建并归一化邻接矩阵
创建两层 GCN 模型
使用训练集节点训练模型
使用验证集选择最佳模型参数
对测试集节点进行预测
在项目根目录生成 result.json

本项目将训练、验证和测试集推理集成在同一个脚本中，因此不需要单独执行评测脚本或加载外部模型权重。

9. 输出结果

程序运行结束后生成：

result.json

文件格式为 JSON 字典：

{
  "1": 3,
  "2": 6,
  "6": 5
}

其中：

key：测试集节点编号，保存为字符串
value：预测类别编号，取值范围为 0-6

代码只保存 test_mask 对应节点的预测结果。

10. 评测指标

比赛采用分类准确率（Accuracy）作为评测指标：

Accuracy = 预测正确的测试节点数 / 测试节点总数

测试集真实标签由评测平台保存，本地数据中的测试标签为 -1，因此本地无法直接计算最终测试准确率。

当前提交结果已通过线上评测，即测试集准确率已达到赛题规定的通过标准。

由于模型参数初始化、运行设备和底层计算环境可能存在差异，重新训练得到的预测结果可能与已提交的 result.json 略有不同。

11. 复现说明

推荐按照以下步骤复现实验：

# 1. 安装依赖
pip install numpy jittor

# 2. 将数据放入指定目录
mkdir -p data
# 将比赛提供的 cora.pkl 放入 data/cora.pkl

# 3. 运行训练与预测
python gcn.py

# 4. 检查预测文件
python -m json.tool result.json

运行前请确认：

data/cora.pkl 文件存在
当前工作目录为项目根目录
Jittor 可以正常导入
GPU 环境下 CUDA 与驱动配置正确

12. 提交说明

比赛提交压缩包结构应为：

result.zip
├── gcn.py
└── result.json

创建压缩包时不要额外嵌套外层目录，也不要将 data/cora.pkl、缓存文件、日志或其他训练产物加入提交包。

13. 第三方工具与数据声明

深度学习框架：Jittor
数据集：比赛发布包提供的 Cora 引文网络数据集
基础模型：Graph Convolutional Network（GCN）

本项目未使用预训练权重。模型参数均通过比赛提供的数据从头训练得到。

14. 许可证

开源仓库应在根目录补充 LICENSE 文件，并根据比赛要求选择合适的开源许可证。