官网 | 文档 | 教程 | 中文文档 | 官方示例 | 讨论区

新闻

• 2025-09-01 -> v0.9.5 现已发布！修复了一些bug，并迁移到UV包管理器，采用PEP 621格式！
• 2024-01-31 -> v0.9.4 现已发布！修复了若干bug，增加了更多数据集！
• 2022-12-28 -> v0.9.3 现已发布！包含更多数据集和超图操作！
• 2022-09-25 -> v0.9.2 现已发布！包含了更多数据集、最新模型和可视化功能！
• 2022-08-25 -> DHG的第一个版本 v0.9.1 正式发布！

DHG (DeepHypergraph) 是一个基于 PyTorch 的深度学习库，用于同时进行图神经网络和超图神经网络的学习。它是一个通用框架，支持低阶和高阶的消息传递，例如 从顶点到顶点、从一个域的顶点到另一个域的顶点、从顶点到超边、从超边到顶点、从顶点集合到顶点集合。

该库支持多种结构，包括低阶结构（如普通图、有向图、二分图等）和高阶结构（如超图等）。在不同结构中集成了多种基于谱的运算（如基于拉普拉斯矩阵的平滑）和基于空间的运算（如域与域之间的消息传递）。此外，它还提供了多种常用指标来评估不同任务的性能。许多最先进的模型已被实现，便于研究人员使用。我们还提供了针对低阶和高阶结构的多种可视化工具。

另外，DHG 的 dhg.experiments 模块（基于 Optuna 实现的 Auto-ML）可以帮助您自动调整模型训练中的超参数，轻松超越现有最先进模型的性能。

• 亮点
• 安装
• 依赖项
• 快速入门
• 示例
• 数据集
• 指标
• 已实现的模型

---

亮点

• 支持结构上的高阶消息传递： DHG 支持在图结构上进行两两消息传递，而在超图结构上则支持多于两两的消息传递。

• 与 PyTorch 生态系统共享： DHG 基于 PyTorch 构建，任何基于 PyTorch 的模型都可以集成到 DHG 中。如果您熟悉 PyTorch，那么使用 DHG 就会非常容易。

• 强大的 API 用于设计 GNN 和 HGNN： DHG 提供了多种拉普拉斯矩阵和消息传递函数，分别帮助构建基于谱和基于空间的模型。

• 图和超图的可视化 DHG 提供了一个功能强大的可视化工具，可以轻松地展示您的图和超图结构。

• 连接图与超图的桥梁： DHG 提供了从图构建超图以及从超图构建图的功能。将图升级为超图或许能够挖掘出潜在的高阶连接，从而提升模型性能。

• 将基于谱/空间的运算附加到结构上： 在 DHG 中，这些拉普拉斯矩阵和消息传递函数都被附加到了图/超图结构上。一旦您使用 DHG 构建了某种结构，这些功能就可以直接用于模型的构建过程中。

• 全面、灵活且便捷： DHG 提供随机图/超图生成器、各种最先进的图/超图卷积层和模型、多种公开的图/超图数据集以及多种评估指标。

• 支持通过 Auto-ML 调优结构和模型： 借助 Optuna 库，DHG 具备了自动机器学习的能力。它可以自动搜索构建图/超图结构的最佳配置，以及您模型和训练过程中的最优超参数。

安装

目前，DHG 的稳定版本是 0.9.5。您可以使用 pip 进行安装：

pip install dhg

您也可以尝试使用 pip 安装 DHG 库的夜间版本（0.9.6）：

pip install git+https://github.com/iMoonLab/DeepHypergraph.git

夜间版本是 DHG 的开发版本，可能包含最新的最先进方法和数据集，但也可能不够稳定，尚未经过充分测试。如果您发现任何问题，请在 GitHub Issues 中向我们报告。

依赖项

DHG 需要以下依赖项：

• Python >= 3.8
• PyTorch >= 1.12.1, < 2.0
• scipy >= 1.8
• matplotlib >= 3.7.0
• numpy
• scikit-learn
• optuna
• requests

对于可视化功能，需要 matplotlib 3.7.0 或更高版本才能正确渲染 3D 图形。

快速入门

可视化

您可以使用 DHG 的可视化工具绘制图、超图、有向图和二分图。更多详细信息请参阅 教程。

import matplotlib.pyplot as plt
import dhg
# 绘制一个图
g = dhg.random.graph_Gnm(10, 12)
g.draw()
# 绘制一个超图
hg = dhg.random.hypergraph_Gnm(10, 8)
hg.draw()
# 显示图形
plt.show()

import matplotlib.pyplot as plt
import dhg
# 绘制一个有向图
g = dhg.random.digraph_Gnm(12, 18)
g.draw()
# 绘制一个二分图
g = dhg.random.bigraph_Gnm(30, 40, 20)
g.draw()
# 显示图形
plt.show()

低阶结构上的学习

在图结构上，您可以通过 GCN 的拉普拉斯矩阵对给定的节点特征进行平滑处理：

import torch
import dhg
g = dhg.random.graph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.smoothing_with_GCN(X)

在图结构上，您还可以通过 mean 聚合方式实现节点之间的消息传递：

import torch
import dhg
g = dhg.random.graph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.v2v(X, aggr="mean")

在有向图结构上，同样可以使用 mean 聚合方式进行节点间的消息传递：

import torch
import dhg
g = dhg.random.digraph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.v2v(X, aggr="mean")

在二分图结构上，您也可以利用 GCN 的拉普拉斯矩阵对节点特征进行平滑处理：

import torch
import dhg
g = dhg.random.bigraph_Gnm(3, 5, 8)
X_u, X_v = torch.rand(3, 2), torch.rand(5, 2)
X = torch.cat([X_u, X_v], dim=0)
X_ = g.smoothing_with_GCN(X, aggr="mean")

此外，在二分图结构上，您还可以通过 mean 聚合方式实现从 U 集合到 V 集合的节点间消息传递：

import torch
import dhg
g = dhg.random.bigraph_Gnm(3, 5, 8)
X_u, X_v = torch.rand(3, 2), torch.rand(5, 2)
X_u_ = g.v2u(X_v, aggr="mean")
X_v_ = g.u2v(X_u, aggr="mean")

高阶结构上的学习

在超图结构上，您可以通过 HGNN 的拉普拉斯矩阵对给定的节点特征进行平滑处理：

import torch
import dhg
hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)
X_ = hg.smoothing_with_HGNN(X)

在超图结构上，您还可以通过 mean 聚合方式实现从节点到超边的消息传递：

import torch
import dhg
hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)
Y_ = hg.v2e(X, aggr="mean")

随后，您可以通过 mean 聚合方式将超边中的信息传递回节点：

X_ = hg.e2v(Y_, aggr="mean")

或者，您也可以通过 mean 聚合方式实现节点集之间的消息传递：

X_ = hg.v2v(X, aggr="mean")

示例

构建 GCN 的卷积层

class GCNConv(nn.Module):
    def __init__(self,):
        super().__init__()
        ...
        self.reset_parameters()

    def forward(self, X: torch.Tensor, g: dhg.Graph) -> torch.Tensor:
        # 将可训练参数 ``theta`` 应用于输入 ``X``
        X = self.theta(X)
        # 使用 GCN 的拉普拉斯矩阵对输入 ``X`` 进行平滑处理
        X = g.smoothing_with_GCN(X)
        X = F.relu(X)
        return X

构建 GAT 的卷积层

class GATConv(nn.Module):
    def __init__(self,):
        super().__init__()
        ...
        self.reset_parameters()

    def forward(self, X: torch.Tensor, g: dhg.Graph) -> torch.Tensor:
        # 将可训练参数 ``theta`` 应用于输入 ``X``
        X = self.theta(X)
        # 计算每条边的注意力权重
        x_for_src = self.atten_src(X)
        x_for_dst = self.atten_dst(X)
        e_atten_score = x_for_src[g.e_src] + x_for_dst[g.e_dst]
        e_atten_score = F.leaky_relu(e_atten_score).squeeze()
        # 将 ``e_atten_score`` 应用于图中每一条边，以 ``softmax_then_sum`` 方式聚合邻居消息，
        # 并通过 ``v2v()`` 消息传递函数在图中完成节点间的消息传递
        X = g.v2v(X, aggr="softmax_then_sum", e_weight=e_atten_score)
        X = F.elu(X)
        return X

构建 HGNN 的卷积层

class HGNNConv(nn.Module):
    def __init__(self,):
        super().__init__()
        ...
        self.reset_parameters()

    def forward(self, X: torch.Tensor, hg: dhg.Hypergraph) -> torch.Tensor:
        # 将可训练参数 ``theta`` 应用于输入 ``X``
        X = self.theta(X)
        # 使用 HGNN 的拉普拉斯矩阵对输入 ``X`` 进行平滑处理
        X = hg.smoothing_with_HGNN(X)
        X = F.relu(X)
        return X

构建 HGNN $^+$ 的卷积层

class HGNNPConv(nn.Module):
    def __init__(self,):
        super().__init__()
        ...
        self.reset_parameters()

    def forward(self, X: torch.Tensor, hg: dhg.Hypergraph) -> torch.Tensor:
        # 将可训练参数 ``theta`` 应用于输入 ``X``
        X = self.theta(X)
        # 在超图中通过 ``v2v()`` 消息传递函数实现节点→超边→节点的消息传递，
        # 该函数结合了 ``v2e()`` 和 ``e2v()`` 两个步骤
        X = hg.v2v(X, aggr="mean")
        X = F.relu(X)
        return X

数据集

目前，我们已添加以下数据集：

• Cora：用于节点分类任务的引用网络数据集。

• PubMed：用于节点分类任务的引用网络数据集。

• Citeseer：用于节点分类任务的引用网络数据集。

• BlogCatalog：用于节点分类任务的社交网络数据集。

• Flickr：用于节点分类任务的社交网络数据集。

• Github：用于节点分类任务的合作网络数据集。

• Facebook：用于节点分类任务的社交网络数据集。

• MovieLens1M：用于用户-物品推荐任务的电影数据集。

• AmazonBook：用于用户-物品推荐任务的亚马逊数据集。

• Yelp2018：用于用户-物品推荐任务的餐厅评论数据集。

• Gowalla：用于用户-物品推荐任务的位置反馈数据集。

• TecentBiGraph：用于节点分类任务的社交网络数据集。

• CoraBiGraph：用于节点分类任务的引用网络数据集。

• PubmedBiGraph：用于节点分类任务的引用网络数据集。

• CiteseerBiGraph：用于节点分类任务的引用网络数据集。

• Cooking200：用于节点分类任务的烹饪食谱数据集。

• CoauthorshipCora：用于节点分类任务的引用网络数据集。

• CoauthorshipDBLP：用于节点分类任务的引用网络数据集。

• CocitationCora：用于节点分类任务的引用网络数据集。

• CocitationPubmed：用于节点分类任务的引用网络数据集。

• CocitationCiteseer：用于节点分类任务的引用网络数据集。

• YelpRestaurant：用于节点分类任务的餐厅评论网络数据集。

• WalmartTrips：用于节点分类任务的用户-商品网络数据集。

• HouseCommittees：用于节点分类任务的委员会网络数据集。

• News20：用于节点分类任务的报纸网络数据集。

• DBLP8k：DBLP-8k数据集是一个用于链接预测任务的引用网络数据集。

• DBLP4k：DBLP-4k数据集是一个用于节点分类任务的引用网络数据集。

• IMDB4k：IMDB-4k数据集是一个用于节点分类任务的电影数据集。

• Recipe100k：Recipe100k数据集是一个用于节点分类任务的食谱-食材网络数据集。

• Recipe200k：Recipe200k数据集是一个用于节点分类任务的食谱-食材网络数据集。

• Yelp3k：Yelp3k数据集是Yelp-Restaurant数据集的一个子集，用于节点分类任务。

• Tencent2k：Tencent2k数据集是一个用于节点分类任务的社交网络数据集。

评估指标

分类任务指标

• 准确率：计算预测的准确率。

• F1分数：计算预测的F1分数。

• 混淆矩阵：计算预测的混淆矩阵。

推荐系统指标

• Precision@k：计算预测的 Precision@k。

• Recall@k：计算预测的 Recall@k。

• NDCG@k：计算预测的归一化折损累计增益@k。

检索系统指标

• Precision@k：计算预测的 Precision@k。

• Recall@k：计算预测的 Recall@k。

• mAP@k：计算预测的 mAP@k。

• NDCG@k：计算预测的归一化折损累计增益@k。

• mRR@k：计算预测的平均倒数排名@k。

• PR-Curve：计算预测的精确率-召回率曲线。

已实现模型

基于低阶结构

• GCN 模型，出自论文《基于图卷积网络的半监督分类》（ICLR 2017）。

• GraphSAGE 模型，出自论文《大规模图上的归纳式表示学习》（NeurIPS 2017）。

• GAT 模型，出自论文《图注意力网络》（ICLR 2018）。

• GIN 模型，出自论文《图神经网络有多强大？》（ICLR 2019）。

• NGCF 模型，出自论文《神经图协同过滤》（SIGIR 2019）。

• LightGCN 模型，出自论文《LightGCN：轻量级图卷积网络》（SIGIR 2020）。

• BGNN-Adv 模型，出自论文《Cascade-BGNN：面向大规模二分图的高效自监督表示学习》（TNNLS 2020）。

• BGNN-MLP 模型，出自论文《Cascade-BGNN：面向大规模二分图的高效自监督表示学习》（TNNLS 2020）。

基于高阶结构

• HGNN 模型，出自论文《超图神经网络》（AAAI 2019）。

• HGNN+ 模型，出自论文《HGNN+：通用超图神经网络》（IEEE T-PAMI 2022）。

• HyperGCN 模型，出自论文《HyperGCN：一种在超图上训练图卷积网络的新方法》（NeurIPS 2019）。

• DHCF 模型，出自论文《双通道超图协同过滤》（KDD 2020）。

• HNHN 模型，出自论文《HNHN：带有超边神经元的超图网络》（ICML 2020）。

• UniGCN 模型，出自论文《UniGNN：图与超图神经网络的统一框架》（IJCAI 2021）。

• UniGAT 模型，出自论文《UniGNN：图与超图神经网络的统一框架》（IJCAI 2021）。

• UniSAGE 模型，出自论文《UniGNN：图与超图神经网络的统一框架》（IJCAI 2021）。

• UniGIN 模型，出自论文《UniGNN：图与超图神经网络的统一框架》（IJCAI 2021）。

引用

如果您在研究中发现 DHG 非常有用，请考虑引用以下文献：

@article{gao2022hgnn,
  title={HGNN $\^{}+ $: General Hypergraph Neural Networks},
  author={Gao, Yue and Feng, Yifan and Ji, Shuyi and Ji, Rongrong},
  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
  year={2022},
  publisher={IEEE}
}

@inproceedings{feng2019hypergraph,
  title={Hypergraph neural networks},
  author={Feng, Yifan and You, Haoxuan and Zhang, Zizhao and Ji, Rongrong and Gao, Yue},
  booktitle={Proceedings of the AAAI conference on artificial intelligence},
  volume={33},
  number={01},
  pages={3558--3565},
  year={2019}
}

DHG 团队

DHG 由 DHG 核心团队开发，成员包括 冯一凡、张新伟、严杰龙、韩相敏、高岳 和 戴琼海。该项目由清华大学的 iMoon 实验室 维护。如需联系，请发送邮件至 evanfeng97@gmail.com。

许可证

DHG 采用 Apache License 2.0 许可证。

DeepHypergraph (DHG) 快速上手指南

DeepHypergraph (DHG) 是一个基于 PyTorch 的深度学习库，专为图神经网络 (GNN) 和超图神经网络 (HGNN) 设计。它支持低阶结构（如图、有向图、二分图）和高阶结构（如超图）上的消息传递，并内置了多种 SOTA 模型、数据集及自动超参数优化功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: >= 3.8
• 核心依赖:
  • PyTorch: >= 1.12.1, < 2.0
  • scipy: >= 1.8
  • matplotlib: >= 3.7.0 (用于渲染 3D 可视化图表)
  • numpy, scikit-learn, optuna, requests

注意: 建议先安装好对应 CUDA 版本的 PyTorch，再安装 DHG。

安装步骤

方式一：安装稳定版（推荐）

使用 pip 直接安装最新稳定版本 (v0.9.5)：

pip install dhg

国内加速方案： 如果您在中国大陆地区，建议使用清华源或阿里源以加快下载速度：

pip install dhg -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：安装开发版（夜间版）

如果您需要体验最新的 SOTA 方法或数据集（可能包含未完全测试的功能），可以安装 GitHub 上的开发版本 (v0.9.6)：

pip install git+https://github.com/iMoonLab/DeepHypergraph.git

基本使用

DHG 的使用风格与 PyTorch 高度一致。以下是几个最核心的快速示例。

1. 结构可视化

DHG 内置了强大的可视化工具，可一键绘制图、超图、有向图和二分图。

import matplotlib.pyplot as plt
import dhg

# 绘制随机图 (Graph)
g = dhg.random.graph_Gnm(10, 12)
g.draw()

# 绘制随机超图 (Hypergraph)
hg = dhg.random.hypergraph_Gnm(10, 8)
hg.draw()

# 显示图像
plt.show()

2. 低阶结构学习 (图神经网络)

在普通图上，您可以直接使用内置方法进行特征平滑或顶点到顶点的消息传递。

特征平滑 (基于 GCN Laplacian):

import torch
import dhg

# 创建一个随机图
g = dhg.random.graph_Gnm(5, 8)
# 随机生成顶点特征
X = torch.rand(5, 2)

# 使用 GCN 拉普拉斯矩阵进行平滑
X_ = g.smoothing_with_GCN(X)

顶点到顶点消息传递 (Vertex-to-Vertex):

import torch
import dhg

g = dhg.random.graph_Gnm(5, 8)
X = torch.rand(5, 2)

# 使用 "mean" 聚合策略进行消息传递
X_ = g.v2v(X, aggr="mean")

3. 高阶结构学习 (超图神经网络)

DHG 的核心优势在于处理超图结构，支持顶点与超边之间的双向消息传递。

特征平滑 (基于 HGNN Laplacian):

import torch
import dhg

# 创建一个随机超图
hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)

# 使用 HGNN 拉普拉斯矩阵进行平滑
X_ = hg.smoothing_with_HGNN(X)

两阶段消息传递 (Vertex -> Hyperedge -> Vertex):

import torch
import dhg

hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)

# 第一步：从顶点传递消息到超边 (Vertex to Hyperedge)
Y_ = hg.v2e(X, aggr="mean")

# 第二步：从超边传递消息回顶点 (Hyperedge to Vertex)
X_ = hg.e2v(Y_, aggr="mean")

# 或者直接进行顶点到顶点的传递 (内部自动处理超边连接)
X_direct = hg.v2v(X, aggr="mean")

4. 构建自定义卷积层

您可以像编写普通 PyTorch 模块一样，结合 DHG 的结构对象构建 GCN 或 HGNN 层。

构建一个简单的 GCN 卷积层:

import torch
import torch.nn as nn
import torch.nn.functional as F
import dhg

class GCNConv(nn.Module):
    def __init__(self, in_channels, out_channels):
        super().__init__()
        self.theta = nn.Linear(in_channels, out_channels)

    def forward(self, X: torch.Tensor, g: dhg.Graph) -> torch.Tensor:
        # 应用可学习参数
        X = self.theta(X)
        # 使用图的拉普拉斯矩阵进行平滑
        X = g.smoothing_with_GCN(X)
        return F.relu(X)

构建一个简单的 HGNN 卷积层:

class HGNNConv(nn.Module):
    def __init__(self, in_channels, out_channels):
        super().__init__()
        self.theta = nn.Linear(in_channels, out_channels)

    def forward(self, X: torch.Tensor, hg: dhg.Hypergraph) -> torch.Tensor:
        # 应用可学习参数
        X = self.theta(X)
        # 使用超图的拉普拉斯矩阵进行平滑
        X = hg.smoothing_with_HGNN(X)
        return F.relu(X)

更多高级用法、完整模型示例及自动超参数调优 (dhg.experiments) 请参考 官方文档。