Skip to content

Latest commit

 

History

History
429 lines (370 loc) · 15.2 KB

README_CN.md

File metadata and controls

429 lines (370 loc) · 15.2 KB

unKR：面向不确定性知识图谱表示学习的开源工具包

Pypi Pypi Documentation

English | 中文

unKR是一个面向不确定性知识图谱表示学习（UKRL）的开源工具包。 其基于PyTorch Lightning框架解耦UKRL模型的工作流程，以实现多种不确定性知识图谱嵌入（Uncertain Knowledge Graph Embedding, UKGE）方法，进而辅助知识图谱补全、推理等工作。 该工具提供了多种已有UKGE模型的代码实现和结果，并为使用者提供了详细的技术文档。


🔖 概览

unKR工具包是基于PyTorch Lightning框架，用于不确定性知识图谱表示学习的一种高效实现。 它提供了一个可实现多种不确定性知识图谱嵌入模型的模块化流程，包括不确定性知识图谱数据处理模块（负采样模块），模型实现基础模块以及模型训练、验证、测试模块。这些模块被广泛应用于多种UKGE模型中，便于使用者快速构建自己的模型。

已有模型根据是否为小样本场景进行划分，共包含九种不同模型。unKR分别在三种数据集及七种不同的评估指标上完成了工具包有效性验证，模型具体内容在后续部分展开。

unKR的核心开发团队将对该工具包提供长期的技术支持，同时也欢迎开发者们进行探讨研究，可使用 issue 发起问题。

关于unKR技术及结果的详细文档请查阅📋。


💻 运行示例

下面展示了unKR的安装过程，并以PASSLEAF模型为例，给出如何进行模型训练以及测试的示例。


📝 模型

unKR实现了九种不确定性知识图谱嵌入方法，根据模型是否为小样本场景进行划分。已有模型如下所示。

类型 模型
一般场景 BEURrE，FocusE，GTransE，PASSLEAF，UKGE，UKGsE，UPGAT
小样本场景 GMUC，GMUC+

数据集

unKR提供了三种不同来源的不确定性知识图谱数据集，包括CN15K、NL27K以及PPI5K。下表展示了三种数据集的来源及其包含的实体数、关系数和四元组数量。

数据集 来源 实体数 关系数 四元组数
CN15K ConceptNet 15000 36 241158
NL27K NELL 27221 404 175412
PPI5K STRING 4999 7 271666

对每个数据集进行整理，分别包含以下三个通用于所有模型的数据文件。

train.tsv：所有用于训练的三元组及其对应的置信度分数，格式为(ent1, rel, ent2, score)，每行表示一个四元组。

val.tsv：所有用于验证的三元组及其对应的置信度分数，格式为(ent1, rel, ent2, score)，每行表示一个四元组。

test.tsv：所有用于测试的三元组及其对应的置信度分数，格式为(ent1, rel, ent2, score)，每行表示一个四元组。

在UKGE中，还需使用softlogic.tsv文件。

softloic.tsv： 所有经由PSL规则推理得到的三元组及其被推理出的置信度分数，格式为(ent1, rel, ent2, score)，每行表示一个四元组。

在GMUC，GMUC+中，还需使用以下五个数据文件。

train/dev/test_tasks.json：小样本数据集，每一个关系为一个任务，格式为{rel:[[ent1, rel, ent2, score], ...]}。字典的键为任务名称，值为该任务下的所有四元组。

path_graph：除训练、验证和测试任务外所有数据，即背景知识，格式为(ent1, rel, ent2, score)。每行表示一个四元组。

ontology.csv：GMUC+模型所需本体知识数据，格式为(number, h, rel, t)，每行表示一个本体知识。其中rel共有四种，分别为is_A，domain，range，type。

  • c1 is_A c2：c1是c2的子类；
  • c1 domain c2：c1的定义域是c2；
  • c1 range c2：c1的值域是c2；
  • c1 type c2：c1的类型是c2。

结果

unKR使用了置信度预测和链接预测任务，在MSE、MAE（置信度预测）、Hits@k（k=1,3,10）、MRR、MR、WMRR以及WMR（链接预测）七种不同的指标进行模型评估，并且进行了raw和filter的设置。此外，unKR还采取了高置信度过滤（设置过滤值为0.7）的评估方法。

下面展示了使用unKR的不同模型在NL27K上的结果，更多结果请访问此处。

置信度预测结果

类型 模型 MSE MAE
一般场景 BEUrRE 0.08920 0.22194
PASSLEAF_ComplEx 0.02434 0.05176
PASSLEAF_DistMult 0.02309 0.05107
PASSLEAF_RotatE 0.01949 0.06253
UKGElogi 0.02861 0.05967
UKGElogiPSL 0.02868 0.05966
UKGErect 0.03344 0.07052
UKGErectPSL 0.03326 0.07015
UKGsE 0.12202 0.27065
UPGAT 0.02922 0.10107
小样本场景 GMUC 0.01300 0.08200
GMUC+ 0.01300 0.08600

链接预测结果（在高置信度测试数据上过滤）

类型 模型 Hits@1 Hits@3 Hits@10 MRR MR
一般场景 BEUrRE 0.156 0.385 0.543 0.299 488.051
FocusE 0.814 0.918 0.957 0.870 384.471
GTransE 0.222 0.366 0.493 0.316 1377.564
PASSLEAF_ComplEx 0.669 0.786 0.876 0.741 138.808
PASSLEAF_DistMult 0.627 0.754 0.856 0.707 138.781
PASSLEAF_RotatE 0.687 0.816 0.884 0.762 50.776
UKGElogi 0.526 0.670 0.805 0.622 153.632
UKGElogiPSL 0.525 0.673 0.812 0.623 168.029
UKGErect 0.509 0.662 0.807 0.609 126.011
UKGErectPSL 0.500 0.647 0.800 0.599 125.233
UKGsE 0.038 0.073 0.130 0.069 2329.501
UPGAT 0.618 0.751 0.862 0.701 69.120
小样本场景 GMUC 0.335 0.465 0.592 0.425 58.312
GMUC+ 0.338 0.486 0.636 0.438 45.774

🛠️ 部署

安装

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

conda create -n unKR python=3.8
conda activate unKR
pip install -r requirements.txt

Step2 安装unKR。

  • 基于源码
git clone https://github.com/CodeSlogan/unKR.git
cd unKR
python setup.py install
  • 基于pypi
pip install unKR

数据格式

All models:
    train/val/test.tsv: (ent1, rel, ent2, score)
UKGE model:
    softloic.tsv: (ent1, rel, ent2, score)
GMUC, GMUC+ models:
    train/dev/test_tasks.json: {rel:[[ent1, rel, ent2, score], ...]}
    path_graph: (ent1, rel, ent2, score)
    ontology.csv: (number, h, rel, t)

参数调整

在config文件中，unKR提供了复现结果的参数配置文件，具体使用时可以对以下的参数进行调整。

parameters:
  confidence_filter:  #whether to perform high-confidence filtering
    values: [0, 0.7]
  emb_dim:
    values: [128, 256, 512...]
  lr:
    values: [1.0e-03, 3.0e-04, 5.0e-06...]
  num_neg:
    values: [1, 10, 20...]
  train_bs:
    values: [64, 128, 256...]

模型训练

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

模型测试

python main.py --test_only --checkpoint_dir <your-model-path>

模型定制

如果您想使用unKR个性化实现自己的模型，需要定义以下的函数/类。

data：实现数据处理函数，包括DataPreprocess、Sampler和KGDataModule。

DataPreprocess.py: 
    class unKR.data.DataPreprocess.<your-model-name>BaseSampler
    class unKR.data.DataPreprocess.<your-model-name>Data
Sampler:
    class unKR.data.Sampler.<your-model-name>Sampler
    class unKR.data.Sampler.<your-model-name>TestSampler
KGDataModule.py: 
    class unKR.data.KGDataModule.<your-model-name>DataModule

lit_model：实现模型训练、验证以及测试函数。

<your-model-name>LitModel.py:
    class unKR.lit_model.<your-model-name>LitModel.<your-model-name>LitModel

loss：实现损失函数。

<your-model-name>_Loss.py:
    class unKR.loss.<your-model-name>_Loss.<your-model-name>_Loss

model：实现模型框架函数，根据模型是否为小样本场景分为UKGModel和FSUKGModel。

<your-model-name>.py:
    class unKR.model.UKGModel/FSUKGModel.<your-model-name>.<your-model-name>

config：实现参数设置。

<your-model-name>_<dataset-name>.yaml:
    data_class, litmodel_name, loss_name, model_name, test_sampler_class, train_sampler_class

demo：实现模型运行文件。

<your-model-name>demo.py

😊 unKR核心团队

东南大学: 王靖婷，吴天星，陈仕林，刘云畅，朱曙曈，李伟，许婧怡，漆桂林。