异构图Transformer (HGT)

替代参考：深度图库 (DGL) 实现

异构图Transformer是一种图神经网络架构，能够处理大规模的异构动态图。

更多详细信息请参阅我们在 WWW 2020 上发表的论文 “异构图Transformer”。

本实现基于 PyTorch Geometric API。

概述

该项目中最重要的文件如下：

• conv.py：我们模型的核心部分，实现了类似Transformer的异构图卷积层。
• model.py：不同模型组件的封装。
• data.py：数据接口及使用方法。
  • class Graph：异构图的数据结构。节点特征存储在 Graph.node_feature 中，格式为 pandas.DataFrame；邻接矩阵存储在 Graph.edge_list 中，格式为字典。
  • def sample_subgraph：异构图的采样算法。每次迭代会按类型采样固定数量的节点，所有采样的节点都位于已采样节点的邻域内，采样概率与相对度数的平方成正比。
• train_*.py：针对特定下游任务的训练和验证脚本。
  • def *_sample：给定任务的采样函数。请注意屏蔽图中已存在的边，以避免信息泄露。
  • def prepare_data：使用多进程并行进行采样，可与模型训练无缝衔接。

环境配置

本实现基于 PyTorch Geometric。要运行代码，您需要以下依赖项：

• PyTorch 1.3.0
• PyTorch Geometric 1.3.2
  • torch-cluster==1.4.5
  • torch-scatter==1.3.2
  • torch-sparse==0.4.3
• gensim
• scikit-learn
• tqdm
• dill
• pandas

您可以直接运行 pip install -r requirements.txt 来安装所有必要的包。

OAG 数据集

我们目前的实验是在开放学术图（OAG）上进行的。为了便于使用，我们将整个数据集按不同粒度进行了拆分和预处理：包括1900年至2020年间的所有 CS 论文（8.1G）、ML 论文（1.9G） 和 NN 论文（0.6G）。您可以通过此 链接 下载预处理后的图。

如果您希望直接从原始数据开始处理，可以从此 链接 下载数据。下载后，请运行 preprocess_OAG.py 来提取特征，并将其存储到我们的数据结构中。

您也可以使用我们的代码处理其他异构图，只需将它们加载到 data.py 中的 class Graph 数据结构中即可。具体操作可参考 preprocess_OAG.py 的示例。

使用方法

要使用 HGT 在论文领域（L2）分类任务上进行训练，请执行以下脚本：

python3 train_paper_field.py --data_dir DATASET_PATH --model_dir SAVED_MODEL_PATH --conv_name hgt

其他两个任务的训练方式与此类似。该脚本的一些关键选项如下：

• conv_name：选择用于训练的相应模型。默认使用 HGT。
• --sample_depth 和 --sample_width：采样子图的深度和宽度。如果模型占用显存过多，可以考虑减少这两个参数；若希望训练更深的 GNN 模型，则可适当增加这些参数。
• --n_pool：用于并行采样的进程数。如果您的机器内存较大，可以增加该参数以缩短批次准备时间。
• --repeat：重复使用采样子图进行训练的次数。如果训练时间远小于采样时间，可以考虑增加该参数。

其他可选超参数的详细信息请参阅 train_*.py 文件。

引用

在您的应用中使用我们的代码时，请考虑引用以下论文：

@inproceedings{hgt,
  author    = {Ziniu Hu and
               Yuxiao Dong and
               Kuansan Wang and
               Yizhou Sun},
  title     = {Heterogeneous Graph Transformer},
  booktitle = {{WWW} '20: The Web Conference 2020, Taipei, Taiwan, April 20-24, 2020},
  pages     = {2704--2710},
  publisher = {{ACM} / {IW3C2}},
  year      = {2020},
  url       = {https://doi.org/10.1145/3366423.3380027},
  doi       = {10.1145/3366423.3380027},
  timestamp = {Wed, 06 May 2020 12:56:16 +0200},
  biburl    = {https://dblp.org/rec/conf/www/HuDWS20.bib},
  bibsource = {dblp computer science bibliography, https://dblp.org}
}

pyHGT 快速上手指南

pyHGT 是一个基于 PyTorch Geometric 实现的异构图变压器（Heterogeneous Graph Transformer）模型，专为处理大规模异构及动态图数据设计。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux / macOS (Windows 需额外配置编译环境)
• Python: 推荐 Python 3.6+
• 核心依赖:
  • PyTorch 1.3.0+
  • pytorch_geometric 1.3.2+ (及其底层库：torch-cluster, torch-scatter, torch-sparse)
  • 其他辅助库：gensim, sklearn, tqdm, dill, pandas

国内加速建议：安装 PyTorch 及相关扩展库时，建议使用清华或阿里镜像源以提升下载速度。

安装步骤

1. 安装 PyTorch (推荐使用清华镜像)

根据您的 CUDA 版本选择合适的命令。若无 GPU 环境，可使用 CPU 版本：

pip install torch==1.3.0 torchvision==0.4.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 pytorch_geometric 及其依赖

由于 pytorch_geometric 需要编译特定的 C++/CUDA 扩展，建议先安装其底层依赖（版本号需与 PyTorch 匹配），再安装主库。

# 安装底层扩展库 (版本参考原文要求，可根据实际 PyTorch 版本调整)
pip install torch-scatter==1.3.2 torch-sparse==0.4.3 torch-cluster==1.4.5 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 pytorch_geometric
pip install torch-geometric==1.3.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装项目其余依赖

克隆项目代码后，在项目根目录下运行：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

(注：若项目中无 requirements.txt，请手动安装：pip install gensim scikit-learn tqdm dill pandas)

基本使用

本项目以开放学术图谱（OAG）为例，演示如何训练论文领域分类任务。

1. 数据准备

您可以下载预处理好的数据集（包含 CS、ML、NN 论文子集），或者使用原始数据自行预处理。

• 下载预处理数据：访问 Google Drive 链接 下载并解压。
• 自行预处理：下载 原始数据，然后运行：

  python preprocess_OAG.py
  

2. 运行训练脚本

以下命令演示如何使用 HGT 模型在“论文 - 领域 (L2)"分类任务上进行训练：

python3 train_paper_field.py --data_dir PATH_OF_DATASET --model_dir PATH_OF_SAVED_MODEL --conv_name hgt

关键参数说明：

• --data_dir: 预处理后的数据集路径。
• --model_dir: 模型保存路径。
• --conv_name: 指定模型类型，默认为 hgt。
• --sample_depth / --sample_width: 采样图的深度和宽度。若显存不足可适当减小；若需训练更深模型则增大。
• --n_pool: 并行采样的进程数。内存充足的机器可增加此数值以缩短数据准备时间。
• --repeat: 每个采样批次重复使用的次数。若采样耗时远大于训练耗时，可增加此值以提高效率。

其他下游任务的训练方式类似，只需替换对应的 train_*.py 脚本即可。