Awesome

Dist-KGE: A knowledge graph embedding library for multi-GPU and multi-machine training

This is the code and configuration accompanying the paper "Parallel Training of Knowledge Graph Embedding Models: A Comparison of Techniques". The code extends the knowledge graph embedding library LibKGE. For documentation on LibKGE refer to LibKGE repository. We provide the hyper-parameter settings for the experiments in their corresponding configuration files.

Table of contents

1. News
2. Quick start
3. Dataset preparation for parallel training
4. Single Machine Multi-GPU Training
5. Multi-GPU Multi-Machine Training
6. Folder structure of experiment results
7. Results and Configurations
8. How to cite

News

In our follow up work "Start small, think big: On hyperparameter optimization for large-scale knowledge graph embeddings", (code), we show (i) the importance of hyperparameter optimiziation (HPO) for large-scale KGEs, and (ii) how to efficently perform HPO on large graphs.

Reported results show strong improvements in terms of MRR.

Quick start

# retrieve and install project in development mode
git clone https://github.com/uma-pi1/dist-kge.git
cd dist-kge
pip install -e .

# download and preprocess datasets
cd data
sh download_all.sh
cd ..

# train an example model on toy dataset (you can omit '--job.device cpu' when you have a gpu)
kge start examples/toy-complex-train.yaml --job.device cpu

This example will train on a toy dataset in a sequential setup on CPU.

For further documentation on possible configuration can be found in the file config-default.yaml.

Supported Models

For a list of models for sequential training using a single GPU we refer to LibKGE.

Models supporte for Multi-GPU and Multi-Machine are:

• ComplEx
• RotatE
• TransE

Dataset preparation for parallel training

NOTE: Freebase already comes with multiple partition settings to save preprocessing time

To partition the data run the following commands (you only need to do this once)

Random Partitioning

For random partitioning no further preparation is needed.

Relation Partitioning

cd data
python partition_relation.py <dataset-name> -n <num-partitions>
cd ..

Stratification

cd data 
python partition_stratification.py <dataset-name> -n <num-partitions>
cd ..

Graph-Cut

cd data
python partition_graph_cut.py <dataset-name> -n <num-partitions>
cd ..

Single Machine Multi-GPU Training

Run following example to train on two GPUs with random partitioning (two worker per GPU):

python -m kge start examples/fb15k-complex-parallel.yaml

The most important configuration options for multi-gpu training are:

import:
  - complex
  - distributed_model
model: distributed_model
distributed_model:
  base_model: complex
job:
  distributed:
    num_partitions: 4
    num_workers: 4
    partition_type: random
    master_port: 8888  # change in case this port is used on your machine
  device_pool:
    - cuda:0
    - cuda:1
train:
  type: distributed_negative_sampling
  optimizer:
    default:
      type: dist_adagrad

Multi-GPU Multi-Machine Training

Parameter Server

For multi-machine training we use the parameter server Lapse. To install Lapse and the corresponding python bindings run the following commands:

git clone https://github.com/alexrenz/lapse-ps.git lapse-ps
cd lapse-ps
git checkout 72c7197c6d1795a8de184de84ffbe1b08151756d
make ps KEY_TYPE=int64_t CXX11_ABI=$(python bindings/lookup_torch_abi.py) DEPS_PATH=$(pwd)/deps_bindings
cd bindings 
python setup.py install --user

For further documentation on the python bindings refer to Lapse-Binding documentation.

In case you can not use Lapse, we provide a very inefficient parameter server (for debugging). To use this debugging PS use the option --job.distributed.parameter_server torch

Interface

As we use the gloo backend to communicate between master and worker nodes you need to specify the interface connecting your machines and specify it as --job.distributed.gloo_socket_ifname. You can find out the names of your interfaces with the command

ip address

Example

Run the following example to train on two machines with one GPU each (1@2) with random partitioning:

Command for machine 1

python -m kge start examples/fb15k-complex-distributed.yaml --job.distributed.machine_id 0 --job.distributed.master_ip <ip_of_machine_0>

Command for machine 2

python -m kge start examples/fb15k-complex-distributed.yaml --job.distributed.machine_id 1 --job.distributed.master_ip <ip_of_machine_0>

Important options for distributed training in addition to the options specified in the single-machine setting are:

job:
  distributed:
    master_ip: '<ip_of_machine_0>'  # ip address of the machine with machine_id 0
    num_machines: 2
    num_workers: 4  # total number of workers over all machines
    gloo_socket_ifname: bond0  # name of the interface to use. Use command 'ip address' to find names
    parameter_server: lapse

Different number of workers per machine

If you have two machines with a varying number of GPUs you might want to set a varying number of workers per machine. You can do so with the following commands

Command for machine 1

python -m kge start examples/fb15k-complex-distributed.yaml --job.distributed.machine_id 0 --job.distributed.master_ip <ip_of_machine_0> --job.distributed_num_workers_machine 3

Command for machine 2

python -m kge start examples/fb15k-complex-distributed.yaml --job.distributed.machine_id 1 --job.distributed.master_ip <ip_of_machine_0> --job.distributed.num_workers_machine 1 --job.distributed.already_init_workers 3

Note that you need to specify for each machine how many workers are initialized on the previous machines with job.distributed.already_init_workers if the number of workers varies per machine. You can also create one configuration file per machine, with corresponding settings for num_workers_machine and already_init_workers.

Folder structure of experiment results

• by default, each experiment will create a new folder in local/experiments/<timestamp>-<config-name>
• this folder can be changed with command line argument --folder path/to/folder
• for multi-machine training a folder is created for each machine. Therefore, specify a separate folder name for each machine if you work on a shared filesystem.
• each worker will have its own subfolder logging partition-processing times
• the complete epoch time over all partitions is logged in the main kge.log file
• hardware information is logged into hardware_monitor.log and gpu_monitor.log
• evaluation is performed on machine-0 by worker-0. Therefore, evaluation results are logged into folder <experiment-folder-machine-0>/worker-0/ in the files kge.log and trace.yaml

Results and Configurations

• all ranking metrics are filtered with train, valid and test if not mentioned otherwise
• configuration files for the experiments can be found here

Partitioning techniques (best-performing variant)

• best performing variant in terms of time to 0.95 MRR reached in the sequential setting

FB15k

ComplEx

RotatE

Yago3-10

ComplEx

RotatE

Wikidata5m

ComplEx

RotatE

Freebase

ComplEx

RotatE

Row-Adagrad

Row-wise optimizers treat each embedding as a single parameter instead of each dimension of an embedding and therefore reduce storage and communication overhead by about 50%. We observed no negative influence on the resulting embedding quality for all partitioning methods but graph-cut partitioning, where the drop was small but noticeable. Overall, we found Row-Adagrad to be a suitable approach to reduce storage and communication costs. We report on ComplEx, 1@2.

Yago3-10

Wikidata5m

How to cite

@article{kochsiek2021parallel,
  title={Parallel training of knowledge graph embedding models: a comparison of techniques},
  author={Kochsiek, Adrian and Gemulla, Rainer},
  journal={Proceedings of the VLDB Endowment},
  volume={15},
  number={3},
  pages={633--645},
  year={2021},
  publisher={VLDB Endowment}
}