{"id":13644211,"url":"https://github.com/deepgraphlearning/astarnet","last_synced_at":"2025-06-14T11:08:20.060Z","repository":{"id":161110538,"uuid":"635873961","full_name":"DeepGraphLearning/AStarNet","owner":"DeepGraphLearning","description":"Official implementation of A* Networks","archived":false,"fork":false,"pushed_at":"2023-08-12T19:41:59.000Z","size":32068,"stargazers_count":143,"open_issues_count":5,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-21T07:41:33.029Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepGraphLearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-05-03T16:30:17.000Z","updated_at":"2025-04-21T06:09:16.000Z","dependencies_parsed_at":"2024-01-14T10:11:25.006Z","dependency_job_id":null,"html_url":"https://github.com/DeepGraphLearning/AStarNet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DeepGraphLearning/AStarNet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FAStarNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FAStarNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FAStarNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FAStarNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepGraphLearning","download_url":"https://codeload.github.com/DeepGraphLearning/AStarNet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FAStarNet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259804865,"owners_count":22913903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:01:59.165Z","updated_at":"2025-06-14T11:08:20.055Z","avatar_url":"https://github.com/DeepGraphLearning.png","language":"Python","readme":"# A\\*Net: A\\* Networks #\n\nThis is the official codebase of the paper\n\n[A*Net: A Scalable Path-based Reasoning Approach for Knowledge Graphs][paper]\n\n[Zhaocheng Zhu](https://kiddozhu.github.io)\\*,\n[Xinyu Yuan](https://github.com/KatarinaYuan)\\*,\n[Mikhail Galkin](https://migalkin.github.io),\n[Sophie Xhonneux](https://github.com/lpxhonneux),\n[Ming Zhang](http://net.pku.edu.cn/dlib/mzhang/),\n[Maxime Gazeau](https://scholar.google.com/citations?user=LfmqBJsAAAAJ),\n[Jian Tang](https://jian-tang.com)\n\n[paper]: https://arxiv.org/pdf/2206.04798.pdf\n\n## Overview ##\n\nA\\*Net is a scalable path-based method for knowledge graph reasoning. Inspired by\nthe classical A\\* algorithm, A\\*Net learns a neural priority function to select\nimportant nodes and edges at each iteration, which significantly reduces time and\nmemory footprint for both training and inference.\n\nA\\*Net is the first path-based method that scales to ogbl-wikikg2 (2.5M entities,\n16M triplets). It also enjoys the advantages of path-based methods such as\ninductive capacity and interpretability.\n\nHere is a demo of A\\*Net with a ChatGPT interface. By reasoning on the Wikidata\nknowledge graph, ChatGPT produces more grounded predictions and less hallucination.\n\n![A*Net with ChatGPT interface](asset/chat.png)\n\nhttps://github.com/DeepGraphLearning/AStarNet/assets/17213634/b521113e-1360-4082-af65-e2579bf01b29\n\nThis codebase contains implementation for A\\*Net and its predecessor [NBFNet].\n\n[NBFNet]: https://github.com/DeepGraphLearning/NBFNet\n\n## Installation ##\n\nThe dependencies can be installed via either conda or pip. A\\*Net is compatible\nwith 3.7 \u003c= Python \u003c= 3.10 and PyTorch \u003e= 1.13.0.\n\n### From Conda ###\n\n```bash\nconda install pytorch cudatoolkit torchdrug pytorch-sparse -c pytorch -c pyg -c milagraph\nconda install ogb easydict pyyaml openai -c conda-forge\n```\n\n### From Pip ###\n\n```bash\npip install torch torchdrug torch-sparse\npip install ogb easydict pyyaml openai\n```\n\n## Usage ##\n\nTo run A\\*Net, use the following command. The argument `-c` specifies the experiment\nconfiguration file, which includes the dataset, model architecture, and\nhyperparameters. You can find all configuration files in `config/.../*.yaml`.\nAll the datasets will be automatically downloaded in the code.\n\n```bash\npython script/run.py -c config/transductive/fb15k237_astarnet.yaml --gpus [0]\n```\n\nFor each experiment, you can specify the number of GPU via the argument `--gpus`.\nYou may use `--gpus null` to run A\\*Net on a CPU, though it would be very slow.\nTo run A\\*Net with multiple GPUs, launch the experiment with `torchrun`\n\n```bash\ntorchrun --nproc_per_node=4 script/run.py -c config/transductive/fb15k237_astarnet.yaml --gpus [0,1,2,3]\n```\n\nFor the inductive setting, there are 4 different splits for each dataset. You need\nto additionally specify the split version with `--version v1`.\n\n## ChatGPT Interface ##\n\nWe provide a ChatGPT interface of A\\*Net, where users can interact with A\\*Net\nthrough natural language. To play with the ChatGPT interface, download the\ncheckpoint [here] and run the following command. Note you need an OpenAI API key\nto run the demo.\n\n```bash\nexport OPENAI_API_KEY=your-openai-api-key\npython script/chat.py -c config/transductive/wikikg2_astarnet_visualize.yaml --checkpoint wikikg2_astarnet.pth --gpus [0]\n```\n\n[here]: https://drive.google.com/drive/folders/15NtyKEXnP4NkHIZEArfTE04Tn5PjpbpJ?usp=sharing\n\n## Visualization ##\n\nA\\*Net supports visualization of important paths for its predictions. With a trained\nmodel, you can visualize the important paths with the following line. Please replace\nthe checkpoint with your own path.\n\n```bash\npython script/visualize.py -c config/transductive/fb15k237_astarnet_visualize.yaml --checkpoint /path/to/astarnet/experiment/model_epoch_20.pth --gpus [0]\n```\n\n## Parameterize with your favourite GNNs ##\n\nA\\*Net is designed to be general frameworks for knowledge graph reasoning. This\nmeans you can parameterize it with a broad range of message-passing GNNs. To do so,\njust implement a convolution layer in `reasoning/layer.py` and register it with\n`@R.register`. The GNN layer is expected to have the following member functions\n\n```python\ndef message(self, graph, input):\n    ...\n    return message\n\ndef aggregate(self, graph, message):\n    ...\n    return update\n\ndef combine(self, input, update):\n    ...\n    return output\n```\n\nwhere the arguments and the return values are\n- `graph` ([data.PackedGraph]): a batch of subgraphs selected by A*Net, with\n  `graph.query` being the query embeddings of shape `(batch_size, input_dim)`.\n- `input` (Tensor): node representations of shape `(graph.num_node, input_dim)`.\n- `message` (Tensor): messages of shape `(graph.num_edge, input_dim)`.\n- `update` (Tensor): aggregated messages of shape `(graph.num_node, *)`.\n- `output` (Tensor): output representations of shape `(graph.num_node, output_dim)`.\n\nTo support the neural priority function in A\\*Net, we need to additionally provide\nan interface for computing messages\n\n```python\ndef compute_message(self, node_input, edge_input):\n   ...\n   return msg_output\n```\n\nYou may refer to the following tutorials of TorchDrug\n- [Graph Data Structures](https://torchdrug.ai/docs/notes/graph.html)\n- [Graph Neural Network Layers](https://torchdrug.ai/docs/notes/layer.html)\n\n[data.PackedGraph]: https://torchdrug.ai/docs/api/data.html#packedgraph\n\n## Frequently Asked Questions ##\n\n1. **The code is stuck at the beginning of epoch 0.**\n\n   This is probably because the JIT cache is broken.\n   Try `rm -r ~/.cache/torch_extensions/*` and run the code again.\n\n## Citation ##\n\nIf you find this project useful, please consider citing the following paper\n\n```bibtex\n@article{zhu2022scalable,\n  title={A*Net: A Scalable Path-based Reasoning Approach for Knowledge Graphs},\n  author={Zhu, Zhaocheng and Yuan, Xinyu and Galkin, Mikhail and Xhonneux, Sophie and Zhang, Ming and Gazeau, Maxime and Tang, Jian},\n  journal={arXiv preprint arXiv:2206.04798},\n  year={2022}\n}\n```","funding_links":[],"categories":["Reimplementations"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgraphlearning%2Fastarnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepgraphlearning%2Fastarnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgraphlearning%2Fastarnet/lists"}