主页 | 论文 | 文档 | 讨论论坛 | 数据集 | 中文
CogDL 是一个图深度学习工具包,允许研究人员和开发人员轻松训练和比较节点分类、图分类及其他重要任务的基线或自定义模型。
我们总结了 CogDL 的贡献如下:
- 效率: CogDL 使用优化良好的操作器来加速训练并节省 GNN 模型的 GPU 内存。
- 易用性: CogDL 提供了易于使用的 API,通过使用超参数搜索来运行给定模型和数据集的实验。
- 扩展性: CogDL 的设计使得在我们的框架基础上,将 GNN 模型应用于新场景变得容易。
❗ 新闻
-
CogDL 论文 被 WWW 2023 接收。欢迎在 WWW 2023 见到我们!我们还发布了新的 v0.6 版本,其中增加了更多图自监督学习的示例,包括 GraphMAE、GraphMAE2 和 BGRL。
-
新的 v0.5.3 版本通过设置 \textit{fp16=True} 支持混合精度训练,并提供了由 Jittor 编写的一个基本示例。它还更新了文档中的教程,修复了一些数据集的下载链接和操作器的潜在错误。
历史新闻
-
新的 v0.5.2 版本增加了一个 ogbn-products 的 GNN 示例,并更新了 geom 数据集。它还修复了一些潜在错误,包括设置设备、使用 cpu 进行推理等。
-
新的 v0.5.1 版本增加了快速操作器,包括 SpMM(cpu 版)和 scatter_max(cuda 版)。它还增加了许多节点分类的数据集,可以在此链接中找到。🎉
-
新的 v0.5.0 版本设计并实现了 GNN 的统一训练循环。它引入了
DataWrapper
来帮助准备训练/验证/测试数据,以及ModelWrapper
来定义训练/验证/测试步骤。🎉 -
新的 v0.4.1 版本添加了 Deep GNNs 的实现和推荐任务。它还支持生成嵌入和推荐的新管道。欢迎参加我们在 2021 年 8 月 14 日上午 10:30 - 中午 12:00(新加坡时间)的 KDD 2021 讲座。更多详情请见 https://kdd2021graph.github.io/。🎉
-
新的 v0.4.0 版本重构了数据存储(从
Data
到Graph
),并提供了更多快速操作器以加快 GNN 训练的速度。它还包括了许多在图上的自监督学习方法。顺便说一句,我们高兴地宣布,我们将在 8 月份的 KDD 2021 上进行教程。请参见此链接了解更多详情。🎉 -
CogDL 支持具有专家混合(MoE)的 GNN 模型。您现在可以安装 FastMoE 并在 CogDL 中尝试 MoE GCN!
-
新的 v0.3.0 版本提供了一个快速 spmm 操作器,以加快 GNN 训练的速度。我们还在 arXiv 上发布了第一版 CogDL 论文。您可以加入我们的 slack进行讨论。🎉🎉🎉
-
新的 v0.2.0 版本包括了所有实验和应用的易于使用的
experiment
和pipeline
API。experiment
API 支持自动化搜索超参数的功能。此版本还提供了OAGBert
API 进行模型推理(OAGBert
是由我们的实验室在大规模学术语料库上训练的)。开源社区也添加了一些功能和模型(感谢所有贡献者 🎉)。 -
新的 v0.1.2 版本包括预训练任务、许多示例、OGB 数据集、一些知识图谱嵌入方法和一些图神经网络模型。CogDL 的覆盖率增加到 80%。开发并测试了一些新的 API,如
Trainer
和Sampler
。 -
新的 v0.1.1 版本包括知识链接预测任务、许多最先进的模型和
optuna
支持。我们也有一个中文微信帖子 介绍了 CogDL 的发布。
快速开始
需求与安装
- Python 版本 >= 3.7
- PyTorch 版本 >= 1.7.1
请按照此处的说明安装 PyTorch (https://github.com/pytorch/pytorch#installation)。
安装 PyTorch 后,可以按如下方式使用 pip 安装 cogdl:
pip install cogdl
从源码安装:
pip install git+https://github.com/thudm/cogdl.git
或者克隆仓库并使用以下命令安装:
git clone git@github.com:THUDM/cogdl.git
cd cogdl
pip install -e .
用法
API 使用
您可以通过 CogDL API 尤其是 experiment
运行各种实验。您也可以使用自己的数据集和模型进行实验。可以在 quick_start.py 找到一个快速入门示例。更多示例提供在 examples/。
from cogdl import experiment
# 基本用法
experiment(dataset="cora", model="gcn")
# 设置其他超参数
experiment(dataset="cora", model="gcn", hidden_size=32, epochs=200)
# 在不同种子上运行多个模型
experiment(dataset="cora", model=["gcn", "gat"], seed=[1, 2])
# automl 用法
def search_space(trial):
return {
"lr": trial.suggest_categorical("lr", [1e-3, 5e-3, 1e-2]),
"hidden_size": trial.suggest_categorical("hidden_size", [32, 64, 128]),
"dropout": trial.suggest_uniform("dropout", 0.5, 0.8),
}
experiment(dataset="cora", model="gcn", seed=[1, 2], search_space=search_space)
命令行使用
你也可以使用 python scripts/train.py --dataset example_dataset --model example_model
在 example_data 上运行 example_model。
- --dataset,运行的数据集名称,可以是一个用空格分隔的数据集列表,例如
cora citeseer
。支持的数据集包括 'cora'、'citeseer'、'pumbed'、'ppi'、'wikipedia'、'blogcatalog'、'flickr'。更多数据集可以在 cogdl/datasets 中找到。 - --model,运行的模型名称,可以是一个模型列表,例如
gcn gat
。支持的模型包括 'gcn'、'gat'、'graphsage'、'deepwalk'、'node2vec'、'hope'、'grarep'、'netmf'、'netsmf'、'prone'。更多模型可以在 cogdl/models 中找到。
例如,如果你想在 Cora 数据集上使用 GCN 和 GAT 运行,使用 5 个不同的种子:
python scripts/train.py --dataset cora --model gcn gat --seed 0 1 2 3 4
预期输出:
Variant | test_acc | val_acc |
---|---|---|
('cora', 'gcn') | 0.8050±0.0047 | 0.7940±0.0063 |
('cora', 'gat') | 0.8234±0.0042 | 0.8088±0.0016 |
如果在上述步骤中遇到任何困难,请随时提交问题。您可以在 24 小时内获得回复。
❗ 常见问题解答
如何为 CogDL 做出贡献?
如果您有一个表现良好的算法,并愿意将其实现到我们的工具包中以帮助更多人,您可以首先提交一个 issue,然后创建一个 pull request,详细信息可以在这里找到。
在提交修改之前,请先运行 pre-commit install
来设置 git hook,以使用 black
和 flake8
检查代码格式和样式。然后,pre-commit
将在 git commit
时自动运行!有关 pre-commit
的详细信息可以在这里找到。
如何启用快速 GNN 训练?
CogDL 提供了一个快速稀疏矩阵-矩阵乘法操作符 [GE-SpMM](https://arxiv.org/abs/2007.03179),以加速在 GPU 上的 GNN 模型训练。该功能将在可用时自动使用。 注意,此功能仍在测试中,可能在某些版本的 CUDA 下无法正常工作。
如何在多个模型上使用 GPUs 进行并行实验?
如果您想在服务器上使用多个 GPUs 对多个模型(如 GCN 和 GAT)在 Cora 数据集上进行并行实验:
$ python scripts/train.py --dataset cora --model gcn gat --hidden-size 64 --devices 0 1 --seed 0 1 2 3 4
预期输出:
Variant | Acc |
---|---|
('cora', 'gcn') | 0.8236±0.0033 |
('cora', 'gat') | 0.8262±0.0032 |
如何使用其他库中的模型?
如果您熟悉其他流行的图学习库,可以使用 PyTorch Geometric (PyG) 中的模块在 CogDL 中实现自己的模型。 有关 PyG 的安装,可以按照 PyG 的说明进行操作 (https://github.com/rusty1s/pytorch_geometric/#installation)。 关于如何使用 PyG 层的快速入门示例,可以在 [examples/pyg](https://github.com/THUDM/cogdl/tree/master/examples/pyg/) 中找到一些示例。
如何通过单元测试成功进行 pull request?
要成功进行 pull request,您需要至少包括 (1) 您的模型实现和 (2) 一个单元测试。
您可能会感到困惑,为什么即使您的模型在本地运行良好,pull request 仍然因 'Coverage decreased ...' 问题而被拒绝。这是因为您没有包含单元测试,单元测试会运行您添加的额外代码行。Github 使用的 Travis CI 服务会对您提交的代码进行所有单元测试,并检查有多少代码行已被测试,如果您的代码没有被充分测试(覆盖率不足),pull request 就会被拒绝。
那么如何进行单元测试呢?
- 假设您在脚本
models/nn/abcgnn.py
中实现了一个执行节点分类任务的 GNN 模型。然后,您需要在脚本tests/tasks/test_node_classification.py
中添加一个单元测试(或任何与您的模型任务相关的测试)。 - 要添加单元测试,只需添加一个函数 test_abcgnn_cora()(只需遵循脚本中已有单元测试的格式),填充所需的参数,函数的最后一行 'assert 0 <= ret["Acc"] <= 1' 是单元测试进行的最基本的健全性检查。
- 修改
tests/tasks/test_node_classification.py
后,将其与您的models/nn/abcgnn.py
一起提交,您的 pull request 应该会通过。
CogDL 团队
CogDL 由清华大学、浙江大学、达摩院和智谱.AI开发和维护。
核心开发团队可以通过 cogdlteam@gmail.com 联系。
引用 CogDL
如果您发现我们的代码或结果对您的研究有帮助,请引用我们的论文:
@inproceedings{cen2023cogdl,
title={CogDL: A Comprehensive Library for Graph Deep Learning},
author={Yukuo Cen and Zhenyu Hou and Yan Wang and Qibin Chen and Yizhen Luo and Zhongming Yu and Hengrui Zhang and Xingcheng Yao and Aohan Zeng and Shiguang Guo and Yuxiao Dong and Yang Yang and Peng Zhang and Guohao Dai and Yu Wang and Chang Zhou and Hongxia Yang and Jie Tang},
booktitle={Proceedings of the ACM Web Conference 2023 (WWW'23)},
year={2023}
}