Jittor Warm-up Competition - sdxpq

本仓库整理了队伍 sdxpq 在 Jittor 图学习热身赛中的代码、实验记录和最终提交文件。任务是在 Cora 图数据上做半监督节点分类，并为 test_mask 节点生成预测结果。

项目结构

.
├── configs/                 # 训练/推理配置
├── data/                    # 数据说明；本地运行时放 cora.pkl，不提交原始数据
├── docs/                    # 方法说明
├── release/                 # 历史实验脚本
├── scripts/                 # 可复现训练/推理入口
├── src/                     # 核心训练与推理代码
├── submission/final/        # 最终提交文件
├── tools/                   # 数据检查工具
├── README.md
├── LICENSE
├── NOTICE
├── requirements.txt
└── .gitignore

环境安装

推荐环境：

• Python 3.9 或 3.10
• Jittor
• JittorGeometric
• NumPy

安装命令：

pip install -r requirements.txt

Jittor/JittorGeometric 的 CUDA、编译器和平台适配要求以比赛官方环境为准。如果只查看 --help 或数据说明，不需要先安装 Jittor；实际训练和推理需要完整运行环境。

数据准备

本仓库不提交原始数据文件。请下载比赛官方 cora.pkl，并放到以下结构：

data/
└── cora.pkl

也可以放在其他目录，运行时通过 --data-root 指定。数据文件应包含：

字段	形状/类型	说明
x	(2708, 1433)	节点特征
y	(2708,)	节点标签，测试集标签为 -1
edge_index	(2, E)	COO 格式边列表
train_mask	(2708,)	训练节点掩码
val_mask	(2708,)	验证节点掩码
test_mask	(2708,)	测试节点掩码
num_classes	int	类别数
num_features	int	特征维度

检查数据：

python tools/inspect_data.py --config configs/appnp_ensemble.json --data-root data

训练

可复现训练入口：

python scripts/train.py --config configs/appnp_ensemble.json --data-root data --seed 42

关键参数来自 configs/appnp_ensemble.json，命令行参数优先级更高。训练会保存：

• outputs/appnp_ensemble/config.json：实际使用的配置
• outputs/appnp_ensemble/command.txt：运行命令
• outputs/appnp_ensemble/train.log：训练日志
• outputs/appnp_ensemble/checkpoints/*.pkl：各 seed 的模型参数
• outputs/appnp_ensemble/predictions/result.json：ensemble 预测结果

可用的小规模 smoke run：

python scripts/train.py --config configs/appnp_ensemble.json --data-root data --seed 42 --phase1-epochs 2 --phase1-seeds 42 --phase2-seeds 42 --tta-runs 1

评测/推理

使用训练保存的 checkpoint 目录重新生成测试集预测：

python scripts/infer.py --config configs/appnp_ensemble.json --data-root data --ckpt outputs/appnp_ensemble/checkpoints --output outputs/appnp_ensemble/predictions/infer_result.json

--ckpt 可以传单个 .pkl 文件，也可以传 checkpoint 目录。缺少数据、配置或 checkpoint 时，脚本会报出具体路径和修复方式。

比赛最终提交副本位于：

submission/final/gcn.py
submission/final/result.json

该提交脚本保持自包含风格，适合按比赛提交包要求单独运行；规范化复现请优先使用 scripts/ 入口。

开源自查

本地没有 Jittor 环境时，也可以先检查仓库结构和禁提交文件：

python tools/check_open_source.py

该脚本会检查必备文件、README 最小小节，以及 .pkl、.pt、.ckpt、.npz、.npy、.zip、.log、outputs/、artifacts/、__pycache__/ 等不应随开源仓库提交的内容。

结果说明

主要指标为节点分类准确率：

Accuracy = 预测正确节点数 / 参与评估节点数

本地脚本使用 val_mask 计算可见验证准确率，用 test_mask 生成线上提交 JSON。最终记录的线上提交分数为 0.844，对应 submission/final/result.json。重新训练可能因 Jittor/CUDA/编译器版本、随机性和硬件环境出现小幅差异。

方法概述

最终方法对应历史版本 release/gcn_v5.py：

• 对输入特征做行归一化。
• 使用归一化邻接矩阵预聚合一跳邻居特征，构造 [X, A_norm X]。
• 用两层 MLP 得到初始 logits，再做 APPNP 风格传播。
• Phase-1 使用 train_mask 训练并用 val_mask 选择训练轮数。
• Phase-2 使用 train_mask | val_mask 训练多个随机种子。
• 推理时保留 dropout 做 TTA，并对多个 seed 的 softmax 概率取平均。

更详细的方案说明见 docs/solution.md。