GNN-QE: Graph Neural Network Query Executor

This is the official code base of the paper

Neural-Symbolic Models for Logical Queries on Knowledge Graphs

Zhaocheng Zhu, Mikhail Galkin, Zuobai Zhang, Jian Tang

Overview

GNN-QE is a neural-symbolic model for answering multi-hop logical queries on knowledge graphs. Given a multi-hop logical query, GNN-QE first decomposes it into 4 basic operations over fuzzy sets, and then executes the operations with graph neural networks and fuzzy logic operations.

Additionally, the intermediate variables in GNN-QE are interpretable, and one can visualize them to better understand the multi-hop reasoning process.

Installation

The dependencies can be installed via either conda or pip. GNN-QE is compatible with Python 3.7/3.8/3.9 and PyTorch >= 1.8.0.

From Conda

conda install torchdrug pytorch cudatoolkit -c milagraph -c pytorch -c pyg
conda install easydict pyyaml -c conda-forge

From Pip

pip install torchdrug torch
pip install easydict pyyaml

Usage

To run GNN-QE, use the following command. Alternatively, you may specify --gpus null to run GNN-QE on a CPU. All the datasets will be automatically downloaded in the code.

python script/run.py -c config/fb15k237.yaml --gpus [0]

We provide the hyperparameters for each experiment in a separate configuration file. The hyperparameters are designed for 32GB GPUs, but you may adjust the batch size to fit a smaller GPU memory. All the configuration files can be found in config/*.yaml.

To run GNN-QE with multiple GPUs or multiple machines, use the following commands

python -m torch.distributed.launch --nproc_per_node=4 script/run.py -c config/fb15k237.yaml --gpus [0,1,2,3]

python -m torch.distributed.launch --nnodes=4 --nproc_per_node=4 script/run.py -c config/fb15k237.yaml --gpus [0,1,2,3,0,1,2,3,0,1,2,3,0,1,2,3]

Once you have models trained on FB15k-237, you can visualize the intermediate variables with the following line. The visualizations will be output in a new experiment directory as png files. Please replace the checkpoint with your own path.

python script/visualize.py -c config/fb15k237_visualize.yaml --checkpoint /path/to/gnn-qe/experiment/model_epoch_10.pth

Bring your own GNNs

Generally, GNN-QE is a GNN-agnostic framework for answering logical queries. You may plug any GNN model into GNN-QE. To do so, just implement the convolution layer in gnnqe/layer.py and the GNN model in gnnqe/gnn.py. The GNN model is expected to have the following signature

def forward(self, graph, input, all_loss=None, metric=None):
    ...
    return {
        "node_feature": node_feature,
    }

where the arguments and the return value are

graph (data.Graph): the knowledge graph with graph.query being the query embeddings of shape (batch_size, input_dim).
input (Tensor): input tensor of shape (|V|, batch_size, input_dim)
all_loss (Tensor): a scalar tensor that accumulates losses during training
metric (Tensor): a dict that stores any scalar information for logging during training
node_feature (Tensor): node feature of shape (|V|, batch_size, output_dim)

For how to implement GNN models in TorchDrug, please refer to these tutorials

Frequently Asked Questions

The code is stuck at the beginning of epoch 0.

This is probably because the JIT cache is broken. Try rm -r ~/.cache/torch_extensions/* and run the code again.

Citation

If you find this project useful in your research, please cite the following paper

@inproceedings{zhu2022neural,
  title={Neural-Symbolic Models for Logical Queries on Knowledge Graphs},
  author={Zhu, Zhaocheng and Galkin, Mikhail and Zhang, Zuobai and Tang, Jian},
  booktitle={Proceedings of the 39th International Conference on Machine Learning},
  pages={27454--27478},
  volume={162},
  year={2022},
}

DeepGraphLearning/GNN-QE