# NeuralKG

**Repository Path**: Modberge/NeuralKG

## Basic Information

- **Project Name**: NeuralKG
- **Description**: An Open Source Library for Diverse Representation Learning of Knowledge Graphs
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2022-03-30
- **Last Updated**: 2023-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


<p align="center">
    <a href=""> <img src="pics/logo.png" width="400"/></a>
<p>
<p align="center">  
    <a href="http://neuralkg.zjukg.cn/">
        <img alt="Website" src="https://img.shields.io/badge/website-online-orange">
    </a>
    <a href="https://pypi.org/project/neuralkg/">
        <img alt="Pypi" src="https://img.shields.io/pypi/v/neuralkg">
    </a>
    <a href="https://github.com/zjukg/NeuralKG/blob/main/LICENSE">
        <img alt="Pypi" src="https://img.shields.io/badge/license-Apache--2.0-yellowgreen">
    </a>
    <!-- <a href="">
        <img alt="LICENSE" src="https://img.shields.io/badge/license-MIT-brightgreen">
    </a> -->
    <a href="https://zjukg.github.io/NeuralKG/index.html">
        <img alt="Documentation" src="https://img.shields.io/badge/Doc-online-blue">
    </a>
</p>
<h1 align="center">
    <p>支持多种知识图谱表示学习的开源工具包</p>
</h1>

NeuralKG是一个支持多种知识图谱表示学习/知识图谱嵌入（Knowledge Graph Embedding， KGE）模型的Python工具包，其中实现了多种传统知识图谱嵌入、基于图神经网络的知识图谱嵌入以及基于规则的知识图谱嵌入方法。同时为初学者提供了详细的[文档](https://zjukg.github.io/NeuralKG/index.html)以及一个开放共享的知识图谱表示学习社区[网站](http://neuralkg.zjukg.cn/)。

<br>

# 目录

- [目录](#目录)
- [😃最新消息](#最新消息)
  - [2022年3月](#2022年3月)
  - [2022年2月](#2022年2月)
- [工具概览](#工具概览)
- [运行示例](#运行示例)
- [实现模型](#实现模型)
- [快速上手](#快速上手)
  - [下载](#下载)
  - [模型训练](#模型训练)
  - [模型测试](#模型测试)
  - [超参调节](#超参调节)
- [复现结果](#复现结果)
- [Notebook教程](#notebook教程)
- [详细文档](#详细文档)
- [引用](#引用)
<!-- * [To do](#to-do) -->

<br>

# 😃最新消息

## 2022年3月
* 我们提供了一个[Google Colab教程](https://drive.google.com/drive/folders/1OyuxvdjRNFzRuheNZaGGCsPe75T1pW1P?usp=sharing)帮助用户使用我们的工具包
* 我们提供了一篇[博客](http://neuralkg.zjukg.cn/CN/index.php/2022/03/17/neuralkg-for-recommendation/)来介绍我们的工具包在自定义数据集上的使用方式

## 2022年2月
* 我们发布了关于该工具包的论文[NeuralKG: An Open Source Library for Diverse Representation Learning of Knowledge Graphs](https://arxiv.org/abs/2202.12571)

<br>

# 工具概览

<h3 align="center">
    <img src="pics/overview.png", width="600">
</h3>
<!-- <p align="center">
    <a href=""> <img src="pics/overview.png" width="400"/></a>
<p> -->


NeuralKG工具包整体基于[PyTorch Lightning](https://www.pytorchlightning.ai/)框架，并提供了一个用于多种知识图谱表示学习模型的通用工作流程且高度模块化。NeuralKG具有如下特性：

+  **支持多种方法。** NeuralKG提供了对三类知识图谱嵌入方法的代码实现，包括**传统知识图谱嵌入**, **基于图神经网络的知识图谱嵌入**, 以及**基于规则的知识图谱嵌入**。


+ **方便快速的客制化。** NeuralKG对知识图谱表示模型进行细化的模块解耦以方便使用者快速定制自己的模型，其中包括知识图谱数据处理模块，负采样模块，超参数监控模块，训练模块以及模型验证模块。这些模块被广泛应用于不同的知识图谱嵌入模型中
+ **长期技术支持。** NeuralKG的核心开发团队将提供长期的技术支持，同时我们也欢迎开发者们对本项目进行pull requests。

<br>

# 运行示例
NeuralKG在自定义知识图谱demo_kg上运行的示例。
<!-- ![框架](./pics/demo.gif) -->
<img src="pics/demo.gif">
<!-- <img src="pics/demo.gif" width="900" height="476" align=center> -->

<br>

# 实现模型

|类别| 模型 |
|:--:|:--------------:|
|传统知识图谱嵌入（KGEModel）|[TransE](https://papers.nips.cc/paper/2013/hash/1cecc7a77928ca8133fa24680a88d2f9-Abstract.html), [TransH](https://ojs.aaai.org/index.php/AAAI/article/view/8870), [TransR](https://www.aaai.org/ocs/index.php/AAAI/AAAI15/paper/viewFile/9571/9523/), [ComplEx](http://proceedings.mlr.press/v48/trouillon16.pdf), [DistMult](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/ICLR2015_updated.pdf), [RotatE](https://arxiv.org/abs/1902.10197), [ConvE](https://arxiv.org/abs/1707.01476), [BoxE](https://arxiv.org/pdf/2007.06267.pdf), [CrossE](https://arxiv.org/abs/1903.04750), [SimplE](https://arxiv.org/abs/1802.04868)|
|基于图神经网络的知识图谱嵌入（GNNModel）|[RGCN](https://arxiv.org/abs/1703.06103), [KBAT](https://arxiv.org/abs/1906.01195), [CompGCN](https://arxiv.org/abs/1906.01195), [XTransE](https://link.springer.com/chapter/10.1007/978-981-15-3412-6_8)|
|基于规则的知识图谱嵌入（RuleModel）|[ComplEx-NNE+AER](https://aclanthology.org/P18-1011/), [RUGE](https://arxiv.org/abs/1711.11231), [IterE](https://arxiv.org/abs/1903.08948)|

<br>

# 快速上手

## 下载

**Step1** 使用 ```Anaconda``` 创建虚拟环境，并进入虚拟环境

```bash
conda create -n neuralkg python=3.8
conda activate neuralkg
```
**Step2** 下载适用您CUDA版本的的PyTorch的DGL，下面我们提供一个基于CUDA 11.1的下载样例 

+  下载PyTorch
```
pip install torch==1.9.1+cu111 -f https://download.pytorch.org/whl/torch_stable.html
```
+ 下载DGL
```
pip install dgl-cu111 dglgo -f https://data.dgl.ai/wheels/repo.html
```

**Step3** 安装NeuralKG

+ 基于Pypi
```bash
pip install neuralkg
```

+ 或基于源码

```bash
git clone https://github.com/zjukg/NeuralKG.git
cd NeuralKG
python setup.py install
```
## 模型训练
```
# Use bash script
sh ./scripts/your-sh

# Use config
python main.py --load_config --config_path <your-config>

```

## 模型测试
```
python main.py --test_only --checkpoint_dir <your-model-path>
```
## 超参调节
NeuralKG使用[Weights&Biases](https://wandb.ai/site)进行超参数调节，支持多种超参优化例如网格搜索、随机搜索和贝叶斯优化。搜索类型和搜索空间可以通过配置（*.yaml）文件进行设置。

下面展示了在FB15k-237上训练TransE，并使用网格搜索（grid search）进行超参数调节的配置文件：

```
command:
  - ${env}
  - ${interpreter}
  - ${program}
  - ${args}
program: main.py
method: grid
metric:
  goal: maximize
  name: Eval|hits@10
parameters:
  dataset_name:
    value: FB15K237
  model_name:
    value: TransE
  loss_name:
    values: [Adv_Loss, Margin_Loss]
  train_sampler_class:
    values: [Unisampler, BernSampler]
  emb_dim:
    values: [400, 600]
  lr:
    values: [1e-4, 5e-5, 1e-6]
  train_bs:
    values: [1024, 512]
  num_neg:
    values: [128, 256]
```
<br>

# 复现结果
下面展示了使用NeuralKG的不同模型在FB15k-237上的结果，更多结果请访问[此处](https://zjukg.github.io/NeuralKG/result.html)。


|Method | MRR | Hit@1 | Hit@3 | Hit@10 |
|:------:|:---:|:-----:|:-----:|:------:|
|TransE|0.32|0.23|0.36|0.51|
|TransR|0.23|0.16|0.26|0.38|
|TransH|0.31|0.2|0.34|0.50|
|DistMult|0.30|0.22|0.33|0.48|
|ComplEx|0.25|0.17|0.27|0.40|
|SimplE|0.16|0.09|0.17|0.29|
|ConvE|0.32|0.23|0.35|0.50|
|RotatE|0.33|0.23|0.37|0.53|
|BoxE|0.32|0.22|0.36|0.52|
|XTransE|0.29|0.19|0.31|0.45|
|RGCN|0.25|0.16|0.27|0.43|
|KBAT*|0.19|0.11|0.22|0.38|
|CompGCN|0.34|0.25|0.38|0.52|
|IterE|0.26|0.19|0.29|0.41|

*:在KBAT的原论文作者实现中存在标签泄漏的问题，所以正确的结果相对较低，具体可以查看https://github.com/deepakn97/relationPrediction/issues/28

<br>

# Notebook教程


😃我们使用colab提供部分notebook供用户使用我们的工具包

[![Colab Notebook](https://colab.research.google.com/assets/colab-badge.svg)](https://drive.google.com/drive/folders/1OyuxvdjRNFzRuheNZaGGCsPe75T1pW1P?usp=sharing)

<br>

# 详细文档
https://zjukg.github.io/NeuralKG/neuralkg.html


<!-- <br> -->

<!-- # To do -->

<br>

# 引用

如果您使用了NeuralKG，请引用我们的论文

```bibtex
@article{zhang2022neuralkg,
      title={NeuralKG: An Open Source Library for Diverse Representation Learning of Knowledge Graphs}, 
      author={Zhang, Wen and Chen, Xiangnan and Yao, Zhen and Chen, Mingyang and Zhu, Yushan and Yu, Hongtao and Huang, Yufeng and others},
      journal={arXiv preprint arXiv:2202.12571},
      year={2022},
}

```
<br>

# NeuralKG核心团队

**浙江大学**: 张文，陈湘楠，姚祯，陈名杨，朱渝珊，俞洪涛，黄雨峰，许泽众，徐雅静，叶鹏，张溢弛，张宁豫，郑国轴，陈华钧