README_CN.md

用于归纳式知识图谱表示学习的Python工具包

❗️❗️❗️我们已经将NeuralKG-ind并入NeuralKG项目，并将于5月底删除此此仓库，请关注者移步NeuralKG❗️❗️❗️

NeuralKG-ind是一个基于python的归纳知识图表示学习工具包，它包括标准化过程、丰富的现有模型、解耦模块和综合评估指标。我们为初学者提供了详细的文档。

目录

• 目录
• 😃最新消息
  • 2022年2月
• 工具概览
• 运行示例
• 实现模型
• 快速上手
  • 下载
  • 模型训练
  • 模型测试
  • 超参调节
• 复现结果
• Notebook教程
• 详细文档
• NeuralKG-ind核心团队

😃最新消息

2022年2月

• 我们发布了关于该工具包的论文 NeuralKG-ind: A Python Library for Inductive Knowledge Graph Representation Learning

工具概览

NeuralKG-ind工具包整体基于PyTorch Lightning框架，同时在NeuralKG的基础上进行开发，它提供了一个用于处理知识图谱上归纳任务的模型的通用工作流程。Neuralkg-ind具有以下特性：

• 标准化过程。 根据现有方法，我们对构建归纳知识图谱表示学习模型的整个过程进行了标准化，包括数据处理、采样和训练以及链接预测和三元组分类任务的评估。我们还提供辅助功能，包括日志管理和超参数调整，用于模型训练和分析。

• 丰富的现有方法。 我们重新实现了最近3年提出的5种归纳知识图谱表示学习的方法，包括GraIL，CoMPILE，SNRI，RMPI和MorsE，用户可以快速应用这些模型。

• 解耦模块。 我们提供了许多解耦模块，如子图提取、节点标记、邻居聚合、图神经网络层和KGE评分方法，使用户能够快速地构建新的归纳知识图谱表示学习模型。

• 长期支持。 我们为NeuralKG-ind提供长期的技术支持，包括维护使用文档、创建更好的使用体验、添加新的模型、解决存在的问题以及处理pull request。

运行示例

NeuralKG-ind在自定义知识图谱demo_kg上运行的示例。

实现模型

方法	类别	模型
传统知识图谱表示学习方法	传统知识图谱嵌入	TransE, TransH, TransR, ComplEx, DistMult, RotatE, ConvE, BoxE, CrossE, SimplE, HAKE, PairRE, DualE
	基于图神经网络的知识图谱嵌入	RGCN, KBAT, CompGCN, XTransE
	基于规则的知识图谱嵌入	ComplEx-NNE+AER, RUGE, IterE
归纳式知识图谱表示学习方法	基于图神经网络的归纳式知识图谱嵌入	GraIL, CoMPILE, SNRI, RMPI, MorsE

快速上手

下载

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

conda create -n neuralkg-ind python=3.8
conda activate neuralkg-ind

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

• 下载lmdb

pip install lmdb==1.4.0

• 下载sklearn

pip install scikit-learn==1.2.1

Step3 安装NeuralKG-ind

• From Pypi

pip install neuralkg_ind

• From Source

git clone https://github.com/zjukg/NeuralKG-ind.git
cd NeuralKG-ind
python setup.py install

模型训练

# Use bash script
sh ./scripts/your-sh

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

模型测试

# Testing AUC and AUC-PR 
python main.py --test_only --checkpoint_dir <your-model-path> --eval_task triple_classification 

# Testing MRR and hit@1,5,10
python main.py --test_only --checkpoint_dir <your-model-path> --eval_task link_prediction --test_db_path <your-db-path> 

超参调节

NeuralKG-ind使用Weights&Biases进行超参数调节，支持多种超参优化例如网格搜索、随机搜索和贝叶斯优化。搜索类型和搜索空间可以通过配置（*.yaml）文件进行设置。

下面展示了在FB15k-237上训练Grail，并使用贝叶斯搜索（bayes search）进行超参数调节的配置文件：

command:
  - ${env}
  - ${interpreter}
  - ${program}
  - ${args}
program: main.py
method: bayes
metric:
  goal: maximize
  name: Eval|auc
parameters:
  dataset_name:
    value: FB15K237
  model_name:
    value: Grail
  loss_name:
    values: [Margin_Loss]
  train_sampler_class:
    values: [SubSampler]
  emb_dim:
    values: [32, 64]
  lr:
    values: [1e-2, 5e-3, 1e-3]
  train_bs:
    values: [64, 128]
  num_neg:
    values: [16, 32]

复现结果

下面展示了使用NeuralKG-ind的不同模型在FB15k-237上的结果和在NELL-995上的部分结果，更多结果请访问此处。

Method	FB15K-237_v1						FB15K-237_v2
	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10
GraIL	0.802	0.821	0.452	0.359	0.561	0.624	0.873	0.900	0.642	0.539	0.767	0.831
CoMPILE	0.800	0.835	0.516	0.437	0.600	0.668	0.876	0.905	0.617	0.509	0.741	0.813
SNRI	0.792	0.883	0.495	0.390	0.600	0.720	0.884	0.906	0.646	0.536	0.781	0.857
RMPI	0.803	0.823	0.532	0.451	0.620	0.689	0.851	0.882	0.632	0.523	0.763	0.830
MorsE	0.844	0.847	0.591	0.470	0.723	0.833	0.963	0.960	0.754	0.643	0.897	0.950

Method	FB15K-237_v3						FB15K-237_v4
	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10
GraIL	0.871	0.899	0.637	0.530	0.765	0.828	0.911	0.921	0.639	0.521	0.797	0.880
CoMPILE	0.906	0.925	0.670	0.568	0.796	0.859	0.927	0.932	0.704	0.604	0.831	0.894
SNRI	0.870	0.884	0.642	0.525	0.775	0.871	0.899	0.916	0.681	0.573	0.821	0.894
RMPI	0.876	0.866	0.662	0.569	0.767	0.827	0.905	0.916	0.647	0.535	0.787	0.866
MorsE	0.959	0.952	0.745	0.637	0.878	0.954	0.963	0.952	0.742	0.662	0.888	0.958

Method	NELL-995_v1						NELL-995_v2
	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10	AUC	AUC-PR	MRR	Hits@1	Hit@5	Hit@10
GraIL	0.814	0.750	0.467	0.395	0.515	0.575	0.929	0.947	0.735	0.624	0.884	0.933
SNRI	0.737	0.720	0.523	0.475	0.545	0.595	0.864	0.884	0.630	0.507	0.774	0.863

Notebook教程

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

详细文档

https://zjukg.github.io/NeuralKG-ind/neuralkg_ind.model.html

NeuralKG-ind核心团队

浙江大学: 张文，姚祯，陈名杨，黄志伟，陈华钧