Jittor ZenFlow CiteGraph

1. 项目简介

本项目面向计图挑战赛赛道一热身赛，在 Cora 引文网络数据集上完成节点分类任务。核心思路是将两种互补的图神经网络架构——侧重局部特征变换的 APPNP 与侧重深层图结构学习的 GCNII——进行集成，并在模型输出之上施加基于图拓扑的标签传播后处理，以充分利用训练集与验证集的全部标签信息。

1.1 技术架构

输入特征 (2708 x 1433)
        │
   ┌────┴────┐
   │         │
 APPNP     GCNII          ← 双架构并行
 3层MLP    32层GCN2Conv
 +PPR传播   +初始残差
   │         │
   ▼         ▼
 softmax   softmax        ← 各架构独立输出概率
   │         │
   └────┬────┘
        │
  Label Propagation       ← PPR 标签传播后处理
  (clamp train+val)       (scipy 稀疏矩阵加速)
        │
  Multi-Seed Ensemble     ← 10 seeds × 2 models × 3 variants
        │                  = 60 个预测取均值
        ▼
  Final Prediction        ← argmax 输出

1.2 核心组件

组件	模型/方法	关键参数
APPNP	3 层 MLP + PPR 传播	hidden=256, K=10, alpha=0.1
GCNII	32 层深度 GCN + 初始残差	hidden=64, layers=32, alpha=0.1
标签传播	PPR 迭代 + 标签 clamp	alpha in {0.2, 0.5}, iters=50
集成策略	多种子概率均值	10 seeds, 60 predictions
训练策略	train+val 合并训练	640 labeled nodes

1.3 数据集

Cora 引文网络数据集：

属性	值
节点数	2,708（每节点为一篇论文）
边数	5,429（无向引用关系）
特征维度	1,433（词袋特征）
类别数	7
训练/验证/测试	140 / 500 / 1,000

2. 环境安装

2.1 系统要求

Python >= 3.10
CUDA >= 11.0（GPU 加速，可选但推荐）

2.2 安装步骤

# 1. 创建并激活 conda 环境
conda create -n jittor python=3.10 -y
conda activate jittor

# 2. 安装全部依赖（含 Jittor、JittorGeometric 及本项目依赖）
pip install -r requirements.txt

2.3 验证安装

python -c "import jittor; import jittor_geometric; print('Done!')"

3. 数据准备

将 cora.pkl 放置于 ./data/ 目录下：

data/
└── cora.pkl

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

字段	类型	形状	说明
`x`	float32	(2708, 1433)	节点特征矩阵
`y`	int64	(2708,)	节点标签（测试集为 -1）
`edge_index`	int64	(2, 10858)	无向边列表
`train_mask`	bool	(2708,)	训练集掩码
`val_mask`	bool	(2708,)	验证集掩码
`test_mask`	bool	(2708,)	测试集掩码

4. 训练与推理

4.1 快速开始

# 完整训练（默认设置中的10个seeds全部运行）
python scripts/train.py --config configs/default.yaml --data-root ./data

# 单种子调试
python scripts/train.py --config configs/default.yaml --data-root ./data --seed 42

# 自定义输出路径
python scripts/train.py --config configs/default.yaml --data-root ./data \
    --output ./outputs/result.json

4.2 命令行参数

参数	类型	默认值	说明
`--config`	str	`configs/default.yaml`	配置文件路径
`--data-root`	str	配置文件中的值	数据目录（覆盖配置）
`--seed`	int	None	指定单一种子（调试用）
`--output`	str	配置文件中的值	输出路径（覆盖配置）
`--no-cuda`	flag	False	禁用 GPU

命令行参数优先级高于配置文件。

4.3 配置说明

所有超参数集中于 configs/default.yaml，可按需调整：

model:
  appnp:
    hidden: 256      # MLP 隐藏层宽度
    K: 10            # PPR 传播步数
    alpha: 0.1       # PPR teleport 概率
  gcnii:
    num_layers: 32   # GCN2Conv 层数
    hidden: 64       # 隐藏层宽度

train:
  lr: 0.01           # 学习率
  max_epochs: 600    # 最大训练轮次

ensemble:
  seeds: [42, 123, 456, 789, 2024, 314, 271, 888, 999, 2048]       # 随机种子列表
  lp_alphas: [0.2, 0.5]  # 标签传播 alpha 候选

4.4 输出

训练完成后自动生成：

outputs/result.json — 测试集预测结果
outputs/config_used.yaml — 本次运行使用的完整配置

预测结果格式：

{
    "1708": 0,
    "1709": 1,
    "1710": 3
}

key: 测试集节点编号（字符串）
value: 预测类别（整数，0-6）

5. 项目结构

Jittor-ZenFlow-CiteGraph/
├── configs/
│   └── default.yaml              # 训练超参数配置
├── src/
│   ├── __init__.py               # 包初始化
│   ├── data.py                   # 数据加载与图预处理
│   ├── models.py                 # APPNPNet 与 GCNIINet 模型定义
│   └── label_propagation.py      # 标签传播后处理
├── scripts/
│   └── train.py                  # 训练与推理入口
├── data/                         # 数据目录（这里按开源规范要求，没有上传 cora.pkl ）
├── outputs/                      # 运行结果
├── README.md
├── LICENSE
├── requirements.txt
└── .gitignore

6. 第三方依赖与致谢

项目	用途	许可证
Jittor	深度学习框架	Apache 2.0
JittorGeometric	图神经网络库	Apache 2.0
Cora 数据集	引文网络基准数据	LINQS

7. License

本项目基于 Apache License 2.0 开源。