PyGCL 是一个基于 PyTorch 的开源图对比学习（GCL）库，它提供了来自已发表论文的模块化 GCL 组件、标准化的评估以及实验管理功能。

---

什么是图对比学习？

图对比学习（GCL）为无监督图表示学习建立了一种新的范式。典型的 GCL 算法首先通过对输入图进行随机增强来构建多个视图，然后通过对比正样本和负样本来进行表示学习。

👉 如需了解 GCL 的一般介绍，请参阅我们的 论文 和 博客。此外，这个 仓库 会跟踪新发表的 GCL 论文。

安装

前置条件

PyGCL 需要预先安装以下软件包：

• Python 3.8+
• PyTorch 1.9+
• PyTorch-Geometric 1.7
• DGL 0.7+
• Scikit-learn 0.24+
• Numpy
• tqdm
• NetworkX

通过 PyPI 安装

要使用 pip 安装 PyGCL，只需运行：

pip install PyGCL

之后，您就可以从当前环境中导入 GCL。

关于 DGL 的说明

目前 DGL 团队维护两个版本：dgl 用于 CPU 支持，而 dgl-cu*** 用于 CUDA 支持。由于 pip 将它们视为不同的包，PyGCL 很难检查 dgl 的版本要求。因此，我们在设置配置中移除了对 dgl 的依赖检查，并要求用户自行 安装合适的版本。

包概述

我们的 PyGCL 实现了图对比学习算法中的四个主要组件：

• 图增强：将输入图转换为一致的图视图。
• 对比架构与模式：根据节点和图嵌入生成正样本对和负样本对。
• 对比目标：计算正样本对和负样本对的似然得分。
• 负采样策略：通过考虑负样本的相对相似性（即难度），优化负样本集。

我们还实现了用于训练模型、评估模型性能以及管理实验的实用工具。

实现与示例

如需快速入门，请查看 examples 文件夹。目前我们已实现以下方法：

• DGI（P. Veličković 等人，Deep Graph Infomax，ICLR，2019）[示例1, 示例2]
• InfoGraph（F.-Y. Sun 等人，InfoGraph：基于互信息最大化的无监督与半监督图级表示学习，ICLR，2020）[示例]
• MVGRL（K. Hassani 等人，图上的对比多视图表示学习，ICML，2020）[示例1, 示例2]
• GRACE（Y. Zhu 等人，深度图对比表示学习，GRL+@ICML，2020）[示例]
• GraphCL（Y. You 等人，基于增强的图对比学习，NeurIPS，2020）[示例]
• SupCon（P. Khosla 等人，有监督对比学习，NeurIPS，2020）[示例]
• HardMixing（Y. Kalantidis 等人，对比学习中的硬负样本混合，NeurIPS，2020）
• DCL（C.-Y. Chuang 等人，去偏对比学习，NeurIPS，2020）
• HCL（J. Robinson 等人，使用硬负样本的对比学习，ICLR，2021）
• Ring（M. Wu 等人，用于视觉表示对比学习的条件负样本采样，ICLR，2021）
• Exemplar（N. Zhao 等人，什么使实例判别对迁移学习有益？，ICLR，2021）
• BGRL（S. Thakoor 等人，图上的自举表示学习，arXiv，2021）[示例1, 示例2]
• G-BT（P. Bielak 等人，图 Barlow Twins：一种用于图的自监督表示学习框架，arXiv，2021）[示例]
• VICReg（A. Bardes 等人，VICReg：用于自监督学习的方差-不变性-协方差正则化，arXiv，2021）

构建您自己的 GCL 算法

除了尝试上述用于节点和图分类任务的示例外，您还可以直接构建自己的图对比学习算法。

图增强

在 GCL.augmentors 中，PyGCL 提供了 Augmentor 基类，该类为图增强函数提供了一个通用接口。具体来说，PyGCL 实现了以下增强函数：

增强类型	类名
边添加（EA）	EdgeAdding
边删除（ER）	EdgeRemoving
特征掩码（FM）	FeatureMasking
特征丢弃（FD）	FeatureDropout
边属性掩码（EAR）	EdgeAttrMasking
个性化 PageRank（PPR）	PPRDiffusion
马尔可夫扩散核（MDK）	MarkovDiffusion
节点丢弃（ND）	NodeDropping
节点洗牌（NS）	NodeShuffling
随机游走诱导的子图（RWS）	RWSampling
自我网络采样（ES）	Identity

调用这些增强函数时，只需以节点特征、边索引和边特征的元组形式 (x, edge_index, edge_attrs) 输入一个 Graph，即可生成相应的增强图。

复合增强

PyGCL 支持将任意数量的增强操作组合在一起。要组合一个增强实例列表 augmentors，你需要使用 Compose 类：

import GCL.augmentors as A

aug = A.Compose([A.EdgeRemoving(pe=0.3), A.FeatureMasking(pf=0.3)])

你也可以使用 RandomChoice 类来每次随机选择几个增强操作：

import GCL.augmentors as A

aug = A.RandomChoice([A.RWSampling(num_seeds=1000, walk_length=10),
                      A.NodeDropping(pn=0.1),
                      A.FeatureMasking(pf=0.1),
                      A.EdgeRemoving(pe=0.1)],
                     num_choices=1)

自定义增强方法

你可以通过继承基类 Augmentor 并定义 augment 方法来编写自己的增强函数。

对比学习架构与模式

现有的图对比学习架构可以分为两类：基于负样本的方法和无需负样本的方法。

• 基于负样本的方法可以是单分支或双分支。在单分支对比学习中，我们只需要构建一个图视图，并在这个视图内进行对比学习。而在双分支模型中，则会生成两个图视图，并在视图内部及视图之间进行对比学习。
• 无需负样本的方法则避免了显式负样本的需求。目前，PyGCL 支持自举风格的对比学习以及嵌入空间内的对比学习（如 Barlow Twins 和 VICReg）。

对比学习架构	支持的对比学习模式	是否需要负样本	类名	示例
单分支对比学习	仅 G2L	✅	SingleBranchContrast	DGI, InfoGraph
双分支对比学习	L2L、G2G 和 G2L	✅	DualBranchContrast	GRACE
自举对比学习	L2L、G2G 和 G2L	❎	BootstrapContrast	BGRL
嵌入空间内对比学习	L2L 和 G2G	❎	WithinEmbedContrast	GBT

此外，如果你希望添加正样本或移除负样本，可以使用 add_extra_mask 函数。该函数会对 extra_pos_mask 指定的额外正样本掩码执行按位加运算，对 extra_neg_mask 指定的额外负样本掩码执行按位或运算。这在你拥有来自标签的监督信号并希望以半监督方式训练模型时非常有用。

在内部实现中，PyGCL 会调用 GCL.models 中的 Sampler 类，这些类接收嵌入并向模型输出正/负样本掩码。PyGCL 实现了三种对比模式：(a) 局部-局部 (L2L)，(b) 全局-全局 (G2G)，以及 (c) 全局-局部 (G2L)。L2L 和 G2G 模式是在相同尺度上对比嵌入，而 G2L 模式则是跨尺度对比。如果你想实现自己的图对比学习模型，也可以使用这些提供的采样器模型：

对比模式	类名
同尺度对比（L2L 和 G2G）	SameScaleSampler
跨尺度对比（G2L）	CrossScaleSampler

• 对于 L2L 和 G2G 模式，在不同视图中属于同一节点或图的嵌入对构成正样本对。可参考 GRACE 和 GraphCL 获取示例。
• 对于 G2L 模式，节点-图嵌入对构成正样本。需要注意的是，对于单图数据集，G2L 模式需要显式的负样本采样（否则将没有用于对比的负样本）。可参考 DGI 获取示例。
• 一些模型（例如 GRACE）会添加额外的视图内负样本。你可以手动调用 sampler.add_intraview_negs 来扩大负样本集合。
• 需要注意的是，自举潜伏模型涉及一些特殊的模型设计（非对称的在线/离线编码器以及动量权重更新）。可参考 BGRL 了解详细信息。

对比学习目标函数

在 GCL.losses 中，PyGCL 实现了以下几种对比学习目标函数：

对比学习目标函数	类名
InfoNCE 损失	InfoNCE
焦点-香农散度 (JSD) 损失	JSD
三元组间隔 (TM) 损失	Triplet
自举潜伏 (BL) 损失	BootstrapLatent
Barlow Twins (BT) 损失	BarlowTwins
VICReg 损失	VICReg

所有这些目标函数都可以对比任意的正负样本对，除了 Barlow Twins 和 VICReg 损失，它们是在嵌入空间内进行对比学习。此外，对于 InfoNCE 和 Triplet 损失，我们还提供了 SP 变体，它只需每个样本提供一对正样本即可计算对比目标函数，从而加快计算速度并避免过多的内存消耗。

负样本采样策略

PyGCL 进一步实现了多种负样本采样策略：

负样本采样策略	类名
子采样	GCL.models.SubSampler
硬负样本混合	GCL.models.HardMixing
条件负样本采样	GCL.models.Ring
去偏对比目标函数	GCL.losses.DebiasedInfoNCE , GCL.losses.DebiasedJSD
硬度加权负样本采样	GCL.losses.HardnessInfoNCE, GCL.losses.HardnessJSD

前三种模型作为附加的采样步骤，类似于现有的 Sampler 模型，可以与任何目标函数结合使用。后两种目标函数则仅适用于 InfoNCE 和 JSD 损失。

工具函数

PyGCL 提供了多种评估函数来评估嵌入质量：

评估工具	类名
逻辑回归	LREvaluator
支持向量机	SVMEvaluator
随机森林	RFEvaluator

要使用这些评估工具，首先需要通过 get_split（随机划分）或 from_predefined_split（根据预设划分）生成数据集划分。

贡献

如果您发现任何意外情况，欢迎随时提交问题；或者您可以创建拉取请求来添加您自己的工作！我们致力于不断改进 PyGCL。

引用

如果您在自己的工作中使用了本代码，请引用我们的论文：

@article{Zhu:2021tu,
author = {朱彦桥、徐一晨、刘强、吴舒},
title = {{图对比学习的实证研究}},
journal = {arXiv.org},
year = {2021},
eprint = {2109.01116v1},
eprinttype = {arxiv},
eprintclass = {cs.LG},
month = sep,
}

PyGCL 快速上手指南

PyGCL 是一个基于 PyTorch 的开源图对比学习（Graph Contrastive Learning, GCL）库，提供了模块化的 GCL 组件、标准化的评估流程以及实验管理工具。

环境准备

在安装 PyGCL 之前，请确保您的系统满足以下要求：

• 操作系统：Linux / macOS / Windows
• Python：3.8 或更高版本
• 核心依赖：
  • PyTorch 1.9+
  • PyTorch-Geometric 1.7+
  • DGL 0.7+ (注意：需手动安装对应 CUDA 版本的 dgl-cu*** 或 CPU 版本)
  • Scikit-learn 0.24+
  • Numpy, tqdm, NetworkX

注意：由于 pip 将 CPU 版 (dgl) 和 GPU 版 (dgl-cu***) 视为不同包，PyGCL 未强制检查 DGL 版本。请务必根据官方文档 DGL 安装指南 自行安装合适的版本。

安装步骤

1. 安装基础依赖

建议先安装 PyTorch 及相关几何深度学习库。国内用户可使用清华源加速：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install torch-geometric -i https://pypi.tuna.tsinghua.edu.cn/simple
# 请根据您的 CUDA 版本安装对应的 DGL，例如：
# pip install dgl-cu118 -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 PyGCL

通过 PyPI 直接安装：

pip install PyGCL

安装完成后，您可以在 Python 环境中导入使用：

import GCL

基本使用

PyGCL 的核心流程包含三个步骤：图增强 (Augmentation) -> 构建对比对 (Contrasting) -> 计算损失 (Objectives)。

以下是一个最简单的双分支对比学习示例（类似 GRACE 算法逻辑）：

import torch
import GCL.augmentors as A
import GCL.losses as L
import GCL.models as M

# 1. 定义图增强策略
# 组合两种增强方法：随机删边 (30%) 和 特征掩码 (30%)
aug = A.Compose([
    A.EdgeRemoving(pe=0.3), 
    A.FeatureMasking(pf=0.3)
])

# 假设已有输入数据: x (节点特征), edge_index (边索引)
# x: [num_nodes, num_features], edge_index: [2, num_edges]
# 生成两个不同的视图
view1 = aug(x, edge_index)
view2 = aug(x, edge_index)

# 2. 定义编码器 (此处以简单的 MLP 为例，实际使用中通常替换为 GCN/GAT 等)
encoder = torch.nn.Sequential(
    torch.nn.Linear(x.shape[1], 64),
    torch.nn.PReLU(),
    torch.nn.Linear(64, 32)
)

# 获取两个视图的嵌入表示
z1 = encoder(view1[0], view1[1])
z2 = encoder(view2[0], view2[1])

# 3. 定义对比模式和损失函数
# 实例化双分支对比器，模式为 Local-to-Local (节点对节点)
contrast = M.DualBranchContrast(mode='L2L')

# 实例化损失函数 (InfoNCE)
loss_fn = L.InfoNCE(tau=0.5)

# 4. 计算损失
# sampler 会自动生成正负样本掩码
loss = loss_fn(
    z1, z2, 
    contrast.get_targets(z1, z2) # 内部处理正负样本对构建
)

print(f"Contrastive Loss: {loss.item()}")

关键组件说明

• 图增强 (GCL.augmentors)：支持边删除、特征掩码、子图采样等多种策略，可通过 Compose 组合或 RandomChoice 随机选择。
• 对比架构 (GCL.models)：
  • SingleBranchContrast: 单分支对比（如 DGI）。
  • DualBranchContrast: 双分支对比（如 GRACE, GraphCL）。
  • BootstrapContrast: 无负样本的自举式对比（如 BGRL）。
  • WithinEmbedContrast: 嵌入内对比（如 Barlow Twins, VICReg）。
• 损失函数 (GCL.losses)：内置 InfoNCE, JSD, Triplet, BarlowTwins, VICReg 等主流目标函数。

更多完整示例（如 DGI, InfoGraph, MVGRL 等复现代码）请参考项目根目录下的 examples 文件夹。