jittor-HUX2026-CoraNodeClassification

基于 JittorGeometric 图神经网络库，在 Cora 引文网络数据集上使用 GCN（Graph Convolutional Network） 模型完成节点分类任务。

战队名称：HUX2026　|　项目名称：CoraNodeClassification　|　比赛：计图（Jittor）热身赛 - 赛道一

本项目依据《开源代码规范（计图比赛）》组织，结构清晰、可复现、易运行。

目录结构

jittor-HUX2026-CoraNodeClassification/
├── README.md                # 本文档
├── LICENSE                  # MIT 许可证
├── .gitignore
├── requirements.txt         # Python 依赖
├── configs/
│   └── default.yaml         # 默认训练/推理配置
├── src/                     # 核心代码
│   ├── __init__.py
│   ├── data.py              # 数据加载与图预处理
│   ├── model.py             # GCN 模型定义
│   ├── train.py             # 训练 / 评估 / 预测函数
│   └── utils.py             # 随机种子、配置加载、日志
├── scripts/                 # 运行入口
│   ├── train.py             # 训练并输出预测结果
│   └── infer.py             # 加载权重进行推理
├── data/                    # 数据目录（仅含说明，不提交数据文件）
│   └── README.md
└── outputs/                 # 日志、权重、结果（默认不提交）

1. 环境安装

Python 版本：3.8 ~ 3.10（推荐 3.9）
操作系统：Windows / Linux / macOS

1.1 安装 Jittor

Jittor 是 JittorGeometric 的底层框架，需先行安装，请参考 Jittor 官方安装指南。

1.2 安装 JittorGeometric 及依赖

参考 JittorGeometric 官方安装指南，然后安装本项目其余依赖：

pip install -r requirements.txt

2. 数据准备

数据集 cora.pkl 由赛题发布包提供，请将其放置于 data/ 目录下：

data/
└── cora.pkl

注意：cora.pkl 为数据原始文件，不纳入版本管理（已在 .gitignore 中忽略）。

数据集为 pickle 格式，包含以下字段：

字段	类型	说明
`x`	numpy array (2708, 1433)	节点特征矩阵
`y`	numpy array (2708,)	节点标签（测试集标签为 -1）
`edge_index`	numpy array (2, num_edges)	边列表
`train_mask`	numpy bool array (2708,)	训练集掩码
`val_mask`	numpy bool array (2708,)	验证集掩码
`test_mask`	numpy bool array (2708,)	测试集掩码
`num_classes`	int	类别数（7）
`num_features`	int	特征维度（1433）

数据根目录配置：默认路径为 data/cora.pkl，可通过命令行参数 --data_path 覆盖。

3. 训练

在项目根目录执行以下命令，即可完成训练并生成测试集预测结果：

python scripts/train.py --config configs/default.yaml

该命令会：

读取 configs/default.yaml 配置（CLI 参数优先级高于配置文件）；
设置随机种子（默认 seed=42）保证可复现；
训练 200 个 epoch，保存验证集最优模型权重；
使用最优模型对测试集节点预测，输出 result.json。

常用参数示例：

python scripts/train.py --config configs/default.yaml --epochs 300 --seed 0 --use_cuda 1

每次运行会在 outputs/run_YYYYMMDD_HHMMSS/ 下保存：

config.json：实际使用的配置
command.txt：运行命令
train.log：训练日志
best_model.pkl：最优模型权重
result.json：测试集预测结果（同时复制一份到项目根目录）

4. 评测 / 推理

使用已训练的权重直接对测试集进行推理（无需重新训练）：

python scripts/infer.py --ckpt outputs/run_YYYYMMDD_HHMMSS/best_model.pkl

可选参数：

python scripts/infer.py \
    --ckpt outputs/run_YYYYMMDD_HHMMSS/best_model.pkl \
    --data_path data/cora.pkl \
    --output result.json

5. 结果说明

评价指标

训练 / 验证准确率（Train / Val Accuracy）：模型在训练集 / 验证集上的分类准确率，计算方式为预测正确的节点数除以对应集合的节点总数。
测试集预测结果：对 test_mask 标记的测试节点预测其所属类别（0~6），输出为 result.json，格式为 { "节点编号": 预测类别, ... }。

复现结果

默认配置（seed=42，CPU，200 epoch）下，验证集准确率约为 0.79~0.81。

线上测试集准确率：0.802（提交赛题官方评测所得）。

差异说明

本地验证集准确率（约 0.79~0.81）与线上测试集准确率（0.802）基本一致，表明模型未出现明显过拟合。
本地验证集与线上测试集的节点分布存在差异，两者间仍可能有轻微波动。
若修改随机种子或硬件环境（CPU/GPU），结果可能略有波动。

6. 可复现性说明

通过 --seed 参数（或配置项 seed）统一设置 random、numpy、jittor 的随机种子。
每次运行自动落盘：实际配置（config.json）、运行命令（command.txt）、训练日志（train.log）。
训练 / 推理脚本在缺少数据或权重文件时会给出明确的错误提示及修复方法。
命令行参数优先级高于配置文件（二者同时存在时以命令行为准）。

7. 第三方引用与声明

Jittor：清华大学计图深度学习框架，Apache-2.0 许可证。
JittorGeometric：基于 Jittor 的图神经网络库。
模型实现参考 Kipf & Welling, Semi-Supervised Classification with Graph Convolutional Networks (ICLR 2017)。
Cora 引文网络数据集由赛题方提供。

8. 许可证

本项目采用 MIT 许可证。