{"id":16739386,"url":"https://github.com/zafarali/embedkb","last_synced_at":"2025-10-25T10:10:15.322Z","repository":{"id":69020290,"uuid":"110031752","full_name":"zafarali/embedKB","owner":"zafarali","description":"Repository to benchmark vector representations of knowledge bases (Knowledge Base Embeddings)","archived":false,"fork":false,"pushed_at":"2018-02-17T23:13:22.000Z","size":252,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-29T13:27:21.204Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/zafarali.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-08T21:20:20.000Z","updated_at":"2025-02-05T18:49:03.000Z","dependencies_parsed_at":"2023-02-21T19:30:29.107Z","dependency_job_id":null,"html_url":"https://github.com/zafarali/embedKB","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zafarali/embedKB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zafarali%2FembedKB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zafarali%2FembedKB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zafarali%2FembedKB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zafarali%2FembedKB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zafarali","download_url":"https://codeload.github.com/zafarali/embedKB/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zafarali%2FembedKB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280937288,"owners_count":26416732,"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","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-10-13T00:50:44.711Z","updated_at":"2025-10-25T10:10:15.306Z","avatar_url":"https://github.com/zafarali.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EmbedKB\n\nThe goal of this repository is to allow rapid immplementation of knowledge base embedding models and evaluation on tasks. \n\nSome key features:\n\n- Implementations of common knowledge base embedding models\n- Implementation of the General Framework as described in [1]\n- Full integration with Tensorboard including Embeddings visualizer\n- Benchmarking tasks\n- Knowledge base data manipulation functions.\n- Unit testing\n\nTo install see [Installation](#installation). To get a brief overview of the features see [the introduction section](#easy-to-use) To use the command line interface to train and benchmark models see [training](#Training) and [Benchmarking](#benchmarking).\n\n## Installation\n\nfrom this directory run\n\n```\npip3 install -e . --user\n```\n\nthis way you install a development version of the module.\nThis code has been tested with Tensorflow 1.2.0\n\n\n## Easy to use!\n\nIf you have data in the form of a knowledge base (for example [FBK15](https://www.microsoft.com/en-us/download/details.aspx?id=52312)) you can get started and train knolwedge base embeddings in a few lines of code!\n\n```\n# we want to use the StructuredEmbedding model:\nfrom embedKB.models.se import StructuredEmbedding\n\n# data handling techniques:\nfrom embedKB.datatools import KnowledgeBase\nfrom embedKB.datatools import Dataset\n\n# load the training data\nkb_train = KnowledgeBase.load_from_raw_data('./data/train.txt')\nkb_train.convert_triples() # convert the triples into a numpy format\ntrain_dset = Dataset(kb_train, batch_size=32) # a wrapper that implements negative sampling\n\nframework.create_objective() # create the max-margin loss objective\nframework.create_optimizer() # create the optimizer\nframework.create_summaries() # create the summaries (optional)\n\n# train!\nframework.train(train_dset,\n                 epochs=15)\n```\n\nTo ask for the \"score\" for any given triple you can do `framework.score_triple(1, 4, 5)` or there is a batch mode that is available.\n\n\n## Data\n\n### Knowledge Base Preparation\n\nMake sure that the triples are in a tab separated file of the form:\n```\nhead_entity  relationship  tail_entity\nhead_entity  relationship  tail_entity\nhead_entity  relationship  tail_entity\n```\n\nYou can then use `embedKB.datatools.KnowledgeBase` to manipulate and save the knowledge base into an appropriate format for downstream training:\n\n```\nfrom embedKB.datatools import KnowledgeBase\n\n# load the raw txt files:\n# this will also create a dict with the entity mappings.\nkb = KnowledgeBase.load_from_raw_data('../data/train.txt')\n\n# convert the triples from the file ../data/train.txt\n# into a numpy array using the dicts we created above.\nkb.convert_triples()\nprint(kb.n_triples) # this will print the number of triples available\n\n# save the numpy converted triples\n# save the mappings\nkb.save_converted_triples('./processed/train.npy')\nkb.save_mappings_to_json('./processed/')\n```\n\n### Negative Sampling and data consumption\n\nEmbeddings are usually trained with negative sampling. The object `embedKB.datatools.Dataset` implements this and will allow us to consume for learning. First we load our training and validation data:\n\n```\n# this reloads our training knowledge base\nkb_train = KnowledgeBase()\n# mappings get saved into standard names:\nkb_train.load_mappings_from_json('./processed/entity2id.json', './processed/relationship2id.json')\nkb_train.load_converted_triples('./train.npy')\n\n# we now create a validation knowledge base:\n# this just reuses the entities and relationss from `kb_train`\nkb_val = KnowledgeBase.derive_from(kb_train)\n# since we have not yet converted our validation data\n# we load the raw triples.\nkb_val.load_raw_triples('./data/valid.txt')\n# as before, use this function to convert triples into numpy format.\nkb_val.convert_triples()\n```\n\nThe `Dataset` object takes in a `KnowledgeBase` and makes it ready for use in training. You must specify a `batch_size` during creation:\n\n```\ntrain_dset = Dataset(kb_train, batch_size=64)\nval_dset = Dataset(kb_val, batch_size=64)\n```\n\nThis is what you will feed into the Embedding models. The `Dataset` object has a generator which does negative sampling on the fly. To inspect a single batch:\n\n```\nprint(next(train_dset.get_generator()))\n```\n\nYou will see that it contains a tuple each with a tuple of three numpy arrays representing head_entity_ids, relationship_ids and tail_entity_ids.\n\n## Tasks\n\nThere are currently two tasks implemented for benchmarking:\n\n1. Triple Classification\n2. Entity Prediction\n\nIt's as easy as a few lines:\n\n```\n# using the filtered version of the task:\ntask = EntityPredictionTask(kb, workers=5, filtered=True)\ntask.benchmark(val_dset, framework)\n```\n\n# Training\n\nModel under from [1] are implemented for you. You can use `./scripts/training.py` to run them. \n\n```\nusage: training.py [-h] -m MODEL_NAME [-e ENTITY_DIM] [-r RELATION_DIM]\n                   [-data DATA] [-reg REG_WEIGHT] [-lr INIT_LEARNING_RATE]\n                   [-gpu GPU] [-n_epochs N_EPOCHS]\n                   [-batch_log_freq BATCH_LOG_FREQ] [-batch_size BATCH_SIZE]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -m MODEL_NAME, --model_name MODEL_NAME\n                        model to run\n  -e ENTITY_DIM, --entity_dim ENTITY_DIM\n                        model to run\n  -r RELATION_DIM, --relation_dim RELATION_DIM\n                        model to run\n  -data DATA, --data DATA\n                        location of the data\n  -reg REG_WEIGHT, --reg_weight REG_WEIGHT\n                        regularization weight\n  -lr INIT_LEARNING_RATE, --init_learning_rate INIT_LEARNING_RATE\n                        initial learning rate\n  -gpu GPU              ID of GPU to execute on\n  -n_epochs N_EPOCHS, --n_epochs N_EPOCHS\n                        number of epochs\n  -batch_log_freq BATCH_LOG_FREQ, --batch_log_freq BATCH_LOG_FREQ\n                        logging frequency\n  -batch_size BATCH_SIZE, --batch_size BATCH_SIZE\n```\n\nFor example:\n\n```\ncd scripts\npython3 training.py -m TransE -e 50 -r 50 -data '../data/Release' -n_epochs 100\n```\n\nWill run TransE. The data and models are check pointed and saved into `./TransE`.\n\n# Benchmarking\n\nYou can find the script for bencmarking in `./scripts` as well.\n\n```\npython3 scripts/benchmark.py -h\nusage: benchmark.py [-h] -m MODEL_NAME [-e ENTITY_DIM] [-r RELATION_DIM] -f\n                    FOLDER [-gpu GPU] -t TASK\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -m MODEL_NAME, --model_name MODEL_NAME\n                        model to run\n  -e ENTITY_DIM, --entity_dim ENTITY_DIM\n                        model to run\n  -r RELATION_DIM, --relation_dim RELATION_DIM\n                        model to run\n  -f FOLDER, --folder FOLDER\n                        location of the model and kb\n  -gpu GPU              ID of GPU to execute on\n  -t TASK, --task TASK  the task to benchmark upon\n```\n\nTwo tasks are already implemented:\n\n- `ept`: Entity Prediction as described in [2]\n- `tct`: Triple Classification as described in [3]\n\n## Testing\n\nThere are a few unit tests. To run:\n\n\n```\npython3 -m pytest\n```\n\n# Reference\n\n[1] [Yang, Bishan, et al. \"Learning multi-relational semantics using neural-embedding models.\" arXiv preprint arXiv:1411.4072 (2014).](https://arxiv.org/pdf/1412.6575.pdf)\n\n[2] [Bordes, Antoine, et al. \"Translating embeddings for modeling multi-relational data.\" Advances in neural information processing systems. 2013.](https://papers.nips.cc/paper/5071-translating-embeddings-for-modeling-multi-relational-data.pdf)\n\n[3] [Socher, Richard, et al. \"Reasoning with neural tensor networks for knowledge base completion.\" Advances in neural information processing systems. 2013.](https://nlp.stanford.edu/pubs/SocherChenManningNg_NIPS2013.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzafarali%2Fembedkb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzafarali%2Fembedkb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzafarali%2Fembedkb/lists"}