jittor-locksmith-gcn-cora

计图比赛（Jittor）热身赛 / 赛道一：基于 GCN 的 Cora 节点分类。

本项目是计图比赛热身赛的示例/基线代码，按照《开源代码规范（计图比赛）》整理，结构清晰、可复现、易运行、易审阅。

仓库命名遵循规范 jittor-开锁师傅-[项目名字]。其中团队名 开锁师傅 在 GitHub 仓库 slug 中需使用 ASCII，故渲染为 locksmith；项目名取 gcn-cora。如需使用其他团队标识，可在 GitHub 创建仓库时自行命名（本地文件夹名不影响远程仓库名）。

目录结构

.
├── README.md                # 本文件
├── LICENSE                  # MIT 许可证
├── NOTICE                   # 第三方代码/数据声明
├── .gitignore
├── requirements.txt         # 依赖清单
├── configs/
│   └── default.yaml         # 训练/评测配置
├── src/                     # 核心代码
│   ├── data.py              # 数据加载与预处理
│   ├── model.py             # GCN 模型定义
│   ├── train.py             # 训练/评测/预测逻辑
│   └── utils.py             # 种子、配置、日志工具
├── scripts/                 # 运行脚本
│   ├── train.py             # 训练入口
│   └── infer.py             # 推理入口
├── tools/
│   └── inspect_data.py      # 数据统计工具
├── data/
│   └── README.md            # 数据说明（不提交原始数据）
└── outputs/                 # 日志/权重/结果（默认不提交）

1. 环境安装

Python 3.8 及以上
安装依赖：
```
pip install -r requirements.txt
```
requirements.txt 包含 jittor、jittor_geometric、numpy、PyYAML。 Jittor 的安装与 CUDA 配置请参考 Jittor 官方文档。

2. 数据准备

从赛题页面下载 cora.pkl，放置到 data/ 目录：
```
data/cora.pkl
```
数据集字段与说明见 data/README.md。
数据根目录可通过 --data-root 或 configs/default.yaml 的 data.data_root 配置。

3. 训练

在仓库根目录执行（一条命令即可跑通默认配置）：

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

常用可覆盖参数（命令行优先级高于配置文件）：

python scripts/train.py --epochs 50 --seed 0 --lr 0.005 --hidden-dim 128

运行后会在 outputs/ 下生成：config.yaml（实际配置）、command.txt（运行命令）、 train.log（日志）、best_model.pkl（最优权重）、result.json（测试集预测）。

4. 评测 / 推理

加载已训练权重，生成测试集预测结果：

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

若权重不在默认位置，可显式指定：

python scripts/infer.py --ckpt outputs/best_model.pkl --output-dir outputs

5. 结果说明

指标：节点分类准确率（Accuracy），即预测类别与真实标签一致的比例，在训练集与验证集上计算（src/train.py 的 evaluate）。
输出：outputs/result.json 为字典 {节点编号: 预测类别}，仅包含测试集节点，可直接作为赛题提交文件。
与线上成绩的差异说明：测试集标签在 cora.pkl 中为 -1，本地无法计算测试集准确率；最终线上成绩以赛方评测为准。本基线默认配置（hidden_dim=256, lr=1e-2, epochs=200, seed=42）在验证集上即可获得可用的 GCN 基线效果，与最终提交成绩可能存在合理波动。

6. 可复现说明

随机种子由 --seed（或 training.seed）统一设置（见 src/utils.py 的 set_seed）。
每次运行都会把实际配置、运行命令、日志落盘到 outputs/，便于复现与审阅。
训练/推理脚本在缺少数据或权重时会给出明确报错与修复提示。

7. 第三方声明

本项目使用 Jittor、JittorGeometric 与 Cora 数据集，来源与许可证见 NOTICE。

8. 提交规范

提交信息建议使用前缀：feat: / fix: / docs: / refactor: / chore:。提交前请确保：代码可运行、README 命令真实可用、未提交大文件与中间产物。