OpenHGNN：实践指南
如果把OpenHGNN放进候选清单，不能只看热度；它的定位是这是一个基于DGL的异构图神经网络（OpenHGNN）的开源工具包。实际做日常自动化时，经常会碰到输入边界、依赖和失败处理如果不清楚就很难稳定复用，所以功能列表并不能代替验证。我建议用一项范围明确的真实任务完成最小试跑，重点记录配置时间、输出质量、异常信息和维护痕迹，再与现有方案比较。我会把它列入愿意先做小范围验证并复查原始文档的团队的候选清单，而不是仅凭项目介绍直接纳入生产。
异质图神经网络开源工具包
启智社区（中文版）｜ Github Community (English) ｜Space4HGNN [SIGIR2022] ｜Benchmark&Leaderboard | Slack Channel
OpenHGNN是一个基于 DGL [Deep Graph Library] 和 PyTorch 的开源异质图神经网络工具包，集成了异质图神经网络的前沿模型。
当前最新版本：OpenHGNN v0.9.0。 v0.9 新增10个模型贡献、node_regression 任务、模型复现文档和更统一的DGL模型接入说明。
新闻
2024-07-23 开源0.7版本
我们开源了0.7版本
- 新增模型和数据集
- 新增图提示学习框架
- 新增DGL的数据处理框架Graphbolt
- 新增GNN消息聚合方式：dgl.sparse
- 新增分布式训练流程
2023-07-17 开源0.5版本
我们开源了0.5版本。
- 新增模型和数据集
- 四个新的前沿图学习任务：预训练、推荐、图攻防、异常事件检测
- TensorBoard可视化功能
- 维护和测试模块
2023-02-24 优秀孵化奖
OpenHGNN荣获启智社区优秀孵化项⽬奖！详细链接：https://mp.weixin.qq.com/s/PpbwEdP0-8wG9dsvRvRDaA
2023-02-21 中国电子学会科技进步一等奖
算法库支撑了北邮牵头，蚂蚁集团、中国移动、海致科技等参与的“大规模复杂异质图数据智能分析技术与规模化应用”项目。该项目获得了2022年电子学会科技进步一等奖。
2023-01-13 开源0.4版本
我们开源了0.4版本。
- 新增模型
- 提供构建应用的流程
- 更多支持采样训练的模型
- 更新千万节点规模图的评测
2022-08-02 论文接收
我们的论文 OpenHGNN: An Open Source Toolkit for Heterogeneous Graph Neural Network 在CIKM2022 short paper track接收。
2022-06-27 开源0.3版本
我们开源了0.3版本。
- 新增模型
- 支持API调用
- 简化定制数据集和模型流程
- 异质图信息可视化工具
2022-02-28 开源0.2版本
我们开源了0.2版本。
- 新增模型
- 异质图神经网络的设计空间：Space4HGNN [SIGIR2022]
- 基准数据集以及排行榜：Benchmark&Leaderboard
2022-01-07 加入启智社区
启智社区用户可以享受到如下功能：
- 全新的中文文档
- 免费的计算资源—— 云脑使用教程
- OpenHGNN最新功能
- 新增模型：【KDD2017】Metapath2vec、【TKDE2018】HERec、【KDD2021】HeCo、【KDD2021】SimpleHGN、【TKDE2021】HPN、【ICDM2021】HDE、fastGTN
- 新增日志功能
- 新增美团外卖数据集
关键特性
- 易用：OpenHGNN提供了了易用的接口在给定的模型和数据集上运行实验，且集成了 optuna 进行超参数优化。
- 可扩展：用户可以定义定制化的任务/模型/数据集来对新的场景应用新的模型。
- 高效：底层的DGL框架提供了提供了高效的API。
- 可发现：可以通过 CLI 查看当前环境、注册模型、注册任务和数据集。
当前版本统计：
- 注册模型名：83个。
- 注册任务/流程入口：17个。
- v0.9新增模型贡献：10个，其中
HERO和HERO_homo是同一模型贡献下的两个注册名。 - v0.9新增任务：
node_regression。
常用文档入口：
- 0.9版本更新说明
- 快速开始
- 模型导览
- 模型复现指南
- 任务导览与node_regression说明
- 模型PR审查规范
开始使用
环境要求
-
Python 3.10-3.12
-
PyTorch 2.3.x-2.4.x
-
DGL 2.2.x-2.4.x
-
CPU 或者 NVIDIA GPU, Linux, Python3
1. Python 环境 (可选): 推荐使用 Conda 包管理
官方推荐环境：
- 首选：
Python 3.11 + PyTorch 2.4.0 + DGL 2.4.0+cu121 - 兼容：
Python 3.10 + PyTorch 2.3.1 + DGL 2.2.1
仓库中的 environment.yml 已经按首选环境固定。
conda create -n openhgnn python=3.11
conda activate openhgnn
2. 安装Pytorch: 参考 PyTorch安装文档 根据你的操作系统和CUDA版本选择合适的安装命令。例如：
pip install torch==2.4.0 torchvision torchaudio
3. 安装DGL: 参考 DGL安装文档 根据你的操作系统和CUDA版本选择合适的安装命令。例如：
pip install dgl==2.4.0+cu121 -f https://data.dgl.ai/wheels/torch-2.4/cu121/repo.html
4. 安装 openhgnn:
- 从pypi安装
pip install openhgnn
- 从源码安装
git clone https://github.com/BUPT-GAMMA/OpenHGNN
# If you encounter a network error, try git clone from openi as following.
# git clone https://git.openi.org.cn/GAMMALab/OpenHGNN.git
cd OpenHGNN
# 如果希望直接创建完整的固定环境，也可以使用：
# conda env create -f environment.yml && conda activate openhgnn
pip install -r requirements.txt
pip install -e .
也可以直接使用 CLI 查看当前支持能力和环境状态：
openhgnn list models
openhgnn list tasks
openhgnn env --format json
5. 安装 gdbi(可选):
- 安装gdbi
pip install git+https://github.com/xy-Ji/gdbi.git
- 安装图数据库
pip install neo4j==5.16.0
pip install nebula3-python==3.4.0
在已有的评测上运行已有的基线模型 数据集
python main.py -m model_name -d dataset_name -t task_name -g 0 --use_best_config --load_from_pretrained
使用方法: main.py [-h] [--model MODEL] [--task TASK] [--dataset DATASET] [--gpu GPU] [--use_best_config][--use_database]
可选参数:
-h, --help 展示帮助信息并退出
--model -m 模型名
--task -t 任务名
--dataset -d 数据集名
--gpu -g 控制你使用哪一个GPU，如果没有GPU，设定 -g -1。
--use_best_config use_best_config 意味着你使用该模型在该数据集下最优的配置，如果你想要设定不同的超参数,请手动修改 配置文件。使用最佳配置会覆盖配置文件中的参数。
--load_from_pretrained 从默认检查点加载模型。
--use_database 从数据库加载数据集
---mini_batch_flag 使用mini_batch方式训练HGNN
---graphbolt 使用graphbolt框架的mini_batch训练流程
---use_distributed 使用分布式方式训练HGNN
示例:
python main.py -m GTN -d imdb4GTN -t node_classification -g 0 --use_best_config
python main.py -m RGCN -d imdb4GTN -t node_classification -g 0 --mini_batch_flag --graphbolt
提示: 如果你对某个模型感兴趣,你可以参考下列的模型列表。
请参考 文档 了解更多的基础和进阶的使用方法。
使用TensorBoard可视化训练结果
tensorboard --logdir=./openhgnn/output/{model_name}/
示例：
tensorboard --logdir=./openhgnn/output/RGCN/
提示:需要先运行一次你想要可视化的模型，才能用以上命令可视化结果。
使用gdbi访问数据库中的标准图数据
以neo4j数据库和imdb数据集为例
- 构造图数据集的csv文件(节点级:A.csv，连接级:A_P.csv)
- 导入csv文件到图数据库中
LOAD CSV WITH HEADERS FROM "file:///data.csv" AS row
CREATE (:graphname_labelname {ID: row.ID, ... });
- 在config.py文件中添加访问图数据库所需的用户信息
self.graph_address = [graph_address]
self.user_name = [user_name]
self.password = [password]
- 示例:
python main.py -m MAGNN -d imdb4MAGNN -t node_classification -g 0 --use_best_config --use_database
模型
Supported Models with specific task / 特定任务下支持的模型
当前版本共注册83个模型名。下表列出README中维护的主要模型与任务覆盖情况；完整注册列表可以通过 openhgnn list models 查看。表格中的链接给出了模型的基本使用方法。
| 模型 | 节点分类 | 链路预测 | 推荐 | 节点回归 | 其他/说明 |
|---|---|---|---|---|---|
| TransE[NIPS 2013] | :heavy_check_mark: | 知识图谱表示 | |||
| TransH[AAAI 2014] | :heavy_check_mark: | 知识图谱表示 | |||
| TransR[AAAI 2015] | :heavy_check_mark: | 知识图谱表示 | |||
| TransD[ACL 2015] | :heavy_check_mark: | 知识图谱表示 | |||
| Metapath2vec[KDD 2017] | :heavy_check_mark: | 表示学习 | |||
| RGCN[ESWC 2018] | :heavy_check_mark: | :heavy_check_mark: | |||
| HERec[TKDE 2018] | :heavy_check_mark: | 表示学习 | |||
| HAN[WWW 2019] | :heavy_check_mark: | :heavy_check_mark: | |||
| KGCN[WWW 2019] | :heavy_check_mark: | ||||
| HetGNN[KDD 2019] | :heavy_check_mark: | :heavy_check_mark: | |||
| HeGAN[KDD 2019] | :heavy_check_mark: | ||||
| HGAT[EMNLP 2019] | short text classification | ||||
| GTN[NeurIPS 2019] & fastGTN | :heavy_check_mark: | ||||
| RSHN[ICDM 2019] | :heavy_check_mark: | :heavy_check_mark: | |||
| GATNE-T[KDD 2019] | :heavy_check_mark: | ||||
| DMGI[AAAI 2020] | :heavy_check_mark: | ||||
| MAGNN[WWW 2020] | :heavy_check_mark: | ||||
| HGT[WWW 2020] | heterogeneous transformer | ||||
| CompGCN[ICLR 2020] | :heavy_check_mark: | :heavy_check_mark: | |||
| NSHE[IJCAI 2020] | :heavy_check_mark: | ||||
| NARS[arxiv] | :heavy_check_mark: | ||||
| MHNF[arxiv] | :heavy_check_mark: | ||||
| HGSL[AAAI 2021] | :heavy_check_mark: | ||||
| HGNN-AC[WWW 2021] | :heavy_check_mark: | ||||
| HeCo[KDD 2021] | :heavy_check_mark: | ||||
| SimpleHGN[KDD 2021] | :heavy_check_mark: | ||||
| HPN[TKDE 2021] | :heavy_check_mark: | :heavy_check_mark: | |||
| RHGNN[arxiv] | :heavy_check_mark: | ||||
| HDE[ICDM 2021] | :heavy_check_mark: | ||||
| HetSANN[AAAI 2020] | :heavy_check_mark: | ||||
| ieHGCN[TKDE 2021] | :heavy_check_mark: | ||||
| KTN[NeurIPS 2022] | :heavy_check_mark: | ||||
| HGDL[NeurIPS 2024] | :heavy_check_mark: | v0.9新增 | |||
| HGEN[IJCAI 2025] | :heavy_check_mark: | v0.9新增 | |||
| HGSketch[SIGIR 2025] | v0.9新增，图级表示/graph classification pipeline | ||||
| HGOT[ICML 2025] | :heavy_check_mark: | v0.9新增 | |||
| RMR[KDD 2024] | :heavy_check_mark: | v0.9新增 | |||
| HERO[ICLR 2024] | :heavy_check_mark: | v0.9新增，异质图版本 | |||
| HERO_homo[ICLR 2024] | :heavy_check_mark: | v0.9新增，同构图版本 | |||
| SEHTGNN[NeurIPS 2025] | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | v0.9新增 | |
| HTGformer[SIGIR 2025] | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | v0.9新增 | |
| HCMGNN[IJCAI 2024] | :heavy_check_mark: | v0.9新增 | |||
| RelGT[arXiv 2025] | :heavy_check_mark: | v0.9新增，RelBench任务 |
v0.9新增模型统计
| 统计项 | 数量 | 说明 |
|---|---|---|
| 新增模型贡献 | 10 | 按论文/模型贡献计数 |
| 新增注册模型名 | 11 | HERO 和 HERO_homo 分别注册 |
| 当前注册模型名 | 83 | 以 openhgnn.models.SUPPORTED_MODELS 为准 |
| 当前注册任务/流程入口 | 17 | 以 openhgnn.tasks.SUPPORTED_TASKS 为准 |
v0.9新增模型贡献包括：HGDL、HGEN、HGSketch、HGOT、RMR、HERO/HERO_homo、SEHTGNN、HTGformer、HCMGNN、RelGT。
详细的v0.9模型复现入口、任务、数据集和后续文档整理说明见 0.9版本更新说明 和 模型复现指南。
候选模型
- Heterogeneous Graph Attention Networks for Semi-supervised Short Text Classification[EMNLP 2019]
- Heterogeneous Information Network Embedding with Adversarial Disentangler[TKDE 2021]
引用OpenHGNN
欢迎在您的工作中用如下的方式引用OpenHGNN:
@inproceedings{han2022openhgnn,
title={OpenHGNN: An Open Source Toolkit for Heterogeneous Graph Neural Network},
author={Hui Han, Tianyu Zhao, Cheng Yang, Hongyi Zhang, Yaoqi Liu, Xiao Wang, Chuan Shi},
booktitle={CIKM},
year={2022}
}
