ProG-V2：一个可复现的图提示学习工具包

ProG-V2 是原始 ProG 图提示学习基准的工程化扩展。它保留了标准的 pre-train → prompt-tune → evaluate 工作流，同时增加了模块化的提示策略架构、更广泛的提示覆盖范围、集中化的路径/设备/日志工具、基准测试脚本、测试以及公开的合并结果报告。

ProG-V2 的新特性

通过 PromptStrategy 注册表注册的 17 种提示策略。
通过 prompt_graph.model.build_gnn 注册的 6 种 GNN 骨干网络。
用于节点级和图级任务的可复现少样本基准测试工具。
集中化的文件系统路径、设备解析、日志记录以及 CLI/YAML 配置。
针对数据加载、GNN 工厂构建、策略注册以及提示-任务冒烟运行的测试。
修复了 WebKB、MultiGprompt、RELIEF 和 GraphMAE 中若干阻碍基准测试的边缘情况。

架构

ProG pipeline

基准测试结果

我们发布了两份互补的公开 GCN 基准报告：一份是节点和图分类报告，另一份是**边任务（链接预测）**报告。两者均采用相同的 {pretrain}+{prompt} 矩阵格式，因此可以使用相同的工具进行读取和合并。

节点与图分类

分类报告位于 results/benchmark-gcn/ 下，包含 714 个独立的 (dataset, shot, pretrain+prompt) 组合 以及 2142 个指标值，涵盖 Accuracy、Macro-F1 和 AUROC。

实验参数：

设置	值
骨干网络	GCN
GNN 层数	2
隐藏维度	128
随机种子	42
样本数	1-shot, 3-shot, 5-shot
少样本划分	每个样本数设置 5 个划分（`mean±std`）
下游预算	50 个 epoch，带早停
预训练预算	生成的检查点为 200 个 epoch
指标	Accuracy, Macro-F1, AUROC
结果格式	`{pretrain}+{prompt}` 列

覆盖范围：

数据集	任务	1-shot	3-shot	5-shot
Cora	节点	72	72	72
Wisconsin	节点	59	59	59
MUTAG	图	56	56	56
PROTEINS	图	51	51	51

结果文件：

summary.csv: 扁平表格，每个实验组合一行。
final_matrices.xlsx: 12 个工作表，每个 (dataset, shot) 任务视图一个。
README.md: 详细的结果文档和指标定义。

边任务（链接预测）

链接预测报告位于 results/link-prediction-gcn/ 下，包含 2912 个 (dataset, shot, pretrain+prompt) 组合，涵盖 Accuracy、F1、 AUROC 和 AUPRC。

设置	值
骨干网络	GCN
数据集	CiteSeer, Cora, IMDB-BINARY, MUTAG, PROTEINS, PTC_MR, PubMed, Wisconsin (8)
样本数	0-shot, 1-shot, 3-shot, 5-shot
预训练	None, DGI, GraphMAE, Edgepred_GPPT, Edgepred_Gprompt, GraphCL, SimGRACE (7)
提示	13 种支持 LinkTask 的策略
每个数据集的组合数	91 (13 提示 × 7 预训练) × 4 样本数 = 364 个单元格
主要指标	AUROC, AUPRC (保留 Accuracy/F1 以兼容矩阵)

结果文件：

summary.csv: 扁平表格，每个实验组合一行。
final_matrices.xlsx: 32 个工作表，每个 (dataset, shot) 视图一个 (4 样本数 × 8 数据集)。
README.md: 详细结果文档和指标定义。

两份报告目前均使用 GCN。其他骨干网络在模型注册表中可用，但不包含在这些公开基准表中。

安装

使用 Python 3.9 或 3.11。建议本地开发使用 Python 3.11。

conda create -n prog-v2 python=3.11 -y
conda activate prog-v2
pip install -e ".[dev]"
pre-commit install

如果 PyTorch Geometric 扩展 wheel 未自动解析，请从官方 PyG wheel 索引中安装与您的 PyTorch/CUDA 版本匹配的 wheel：

python -m pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/

快速开始

运行一个最小的下游任务：

python downstream_task.py \
  --downstream_task NodeTask \
  --dataset_name Cora \
  --gnn_type GCN \
  --prompt_type GPF \
  --shot_num 1 \
  --epochs 1 \
  --device cpu

运行一个小型基准测试单元格并编写一个 Excel 矩阵：

python scripts/bootstrap_excel_full.py --gnn_type GCN
python bench.py \
  --pretrain_task NodeTask \
  --dataset_name Cora \
  --prompt_type None \
  --gnn_type GCN \
  --shot_num 1 \
  --epochs 1 \
  --device cpu \
  --pre_train_model_path None \
  --num_iter 1

运行 LinkTask 单元格（链接预测，点积解码器）：

python bench.py \
  --pretrain_task LinkTask \
  --dataset_name Cora \
  --prompt_type GPF \
  --gnn_type GCN \
  --shot_num 0 \
  --epochs 10 \
  --device cpu \
  --pre_train_model_path None \
  --num_iter 1

对于单次运行的 LinkTask 入口点，downstream_task.py 也接受 --downstream_task LinkTask：

python downstream_task.py \
  --downstream_task LinkTask \
  --dataset_name Cora \
  --prompt_type None \
  --gnn_type GCN \
  --shot_num 0 \
  --epochs 2 \
  --device cpu \
  --pre_train_model_path None

支持的组件

骨干网络

GCN
GAT
GIN
GraphSAGE
GCov
GraphTransformer

预训练方法

DGI
GraphMAE
GraphCL
SimGRACE
Edgepred_GPPT
Edgepred_Gprompt
MultiGprompt

提示策略

None、GPF、GPF-plus、Gprompt、All-in-one、GPPT、Prodigy、 GraphPrompter、EdgePrompt、EdgePromptplus、RELIEF、MultiGprompt、 UniPrompt、SelfPro、ProNoG、PSP 和 DAGPrompT。

下游任务

任务	类别	数据集	备注
`NodeTask`	`prompt_graph.tasker.NodeTask`	`NODE_TASKS` (12)	节点分类，支持全部 17 个提示。
`GraphTask`	`prompt_graph.tasker.GraphTask`	`GRAPH_TASKS` (11)	图分类，支持全部 17 个提示。
`LinkTask`	`prompt_graph.tasker.LinkTask`	`LINK_TASKS` (16 个精选)	对于大多数提示，使用二元 BCE + 点积解码器进行链接预测。

脚本

公开的扫描脚本由 --gnn_type 参数化：

bash scripts/pretrain_full_grid.sh --gnn_type GCN --fast
bash scripts/bench_full_grid.sh --gnn_type GCN --fast --datasets "Cora MUTAG"

实用脚本：

脚本	用途
`scripts/bootstrap_excel_full.py`	为选定的骨干网络创建空的 Excel 矩阵。
`scripts/pretrain_full_grid.sh`	预训练选定的方法/数据集/骨干网络。
`scripts/bench_full_grid.sh`	使用过滤器运行完整的项目基准测试网格。
`scripts/merge_result_excels.py`	将每次运行的 Excel 输出合并为一份报告。
`scripts/export_final_matrices.py`	将已填充的按数据集划分的矩阵导出到 `summary.csv` 和 `final_matrices.xlsx`。

开发检查

ruff check .
ruff format --check .
pytest tests/ -v

有关贡献指南，请参阅 CONTRIBUTING.md。

引用

如果您觉得本项目有用，请引用原始的 ProG/graph prompt 工作：

@article{zi2024prog,
  title={ProG: A Graph Prompt Learning Benchmark},
  author={Chenyi Zi and Haihong Zhao and Xiangguo Sun and Yiqing Lin and Hong Cheng and Jia Li},
  year={2024},
  journal={Advances in Neural Information Processing Systems}
}

@inproceedings{sun2023all,
  title={All in One: Multi-Task Prompting for Graph Neural Networks},
  author={Sun, Xiangguo and Cheng, Hong and Li, Jia and Liu, Bo and Guan, Jihong},
  booktitle={Proceedings of the 29th ACM SIGKDD Conference on Knowledge Discovery and Data Mining},
  year={2023}
}