How zjukg/ankge works
Project type and purpose
• This is a research‐oriented machine‐learning pipeline for Knowledge Graph Embedding (KGE), enhanced by an analogical inference framework (AnKGE).
• Its goal is to load benchmark KG datasets (FB15K‐237, WN18RR), train base embedding models (TransE, RotatE, HAKE, PairRE), augment them with analogical inference at entity, relation, and triple levels, and evaluate on link prediction.
File structure
• Top level
• dataset/ : raw KG data (entities.dict, relations.dict, train/valid/test splits)
• scripts/ : shell scripts to run experiments (base model and AnKGE on FB and WN)
• src/ankge/ : core code organized into subpackages
• main.py : global entrypoint
• src/ankge subpackages
• data/ : data preprocessing, sampling, PyTorch‐Lightning DataModule
• model/KGEModel/ : implementations of base KG models
• loss/ : definitions of loss functions for base and analogical training
• lit_model/ : PyTorch‐Lightning “LightningModule” wrappers for training logic
• eval_task/ : evaluation code (link_prediction)
• utils/ : argument parsing, helper tools
• Config and orchestration
• requirements.txt for dependencies
• .sh scripts set hyperparameters, BASE_MODEL_PATH, and invoke main.py
README for additional insights
• Describes the 3‐stage AnKGE process: retrieve analogical objects → train analogy functions → interpolate analogy score with base model score
• Notes use of PyTorch Lightning, wandb for logging, GPU requirements
• Illustrates the model architecture (AnKGE_structure.png)
a. Main components
1. Dataset Storage
• FB15K‐237 folder, WN18RR folder
2. Data Preprocessing & Loader
• DataPreprocess.py, Sampler.py, RuleDataLoader.py → KGDataModule (PyTorch Lightning)
3. Base KGE Models
• TransE, RotatE, HAKE, PairRE implementations under model/KGEModel/
4. Analogical Inference Module (AnKGE)
• GetNearNeighbor, GetLevelScore, Grounding → analogy functions per level
5. Loss Functions
• AnKnn_Loss, Adv_Loss
6. Training Orchestrator
• AnKnnLitModel, KGELitModel, KGERevLitModel (LightningModule)
• Trainer abstraction provided by PyTorch Lightning and main.py
7. Evaluation
• link_prediction code under eval_task
8. Experiment Controller
• Shell scripts in scripts/ to launch base and AnKGE experiments
9. Logging & Output
• wandb API, output/link_prediction/, logging/
b. Relationships & interactions
• Base model component feeds embeddings into Analogy module
• Analogy module outputs analogical scores merged with base scores
• Loss functions take combined scores + ground truth for backprop
• Evaluation pulls trained model checkpoints to compute metrics
• Shell scripts orchestrate sequential runs: base model first → AnKGE training
c. Architectural patterns & principles
• Modular pipeline: clear separation between data, model, analogy, loss, training, evaluation
• Extensibility: supports plugging in new base models or analogy functions
• Use of PyTorch Lightning enforces uniform Trainer/DataModule/LightningModule pattern
d. Key technologies & frameworks
• Python 3, PyTorch, PyTorch Lightning
• numpy, tqdm, wandb for logging/monitoring
• shell scripts for reproducible experiments
Detailed pointers
• Start at “scripts” level: show how a shell script invokes main.py with parameters pointing to dataset and BASE_MODEL_PATH
• Drill down: main.py parses arguments via setup_parser → instantiates KGDataModule → selects KGEModel class → wraps it in the chosen LightningModule → configures Trainer (GPU, wandb) → Trainer.fit → saves checkpoints
• On AnKGE runs, reflect an extra block: “Analogy Retrieval & Scoring” that taps into embedding space and outputs analogical embeddings/scores, then merges them
• Finally, after training, Trainer.test triggers link_prediction evaluation module, writing to output/link_prediction/*