{"id":13935792,"url":"https://github.com/HKUST-KnowComp/MnemonicReader","last_synced_at":"2025-07-19T21:30:40.365Z","repository":{"id":101129133,"uuid":"129780251","full_name":"HKUST-KnowComp/MnemonicReader","owner":"HKUST-KnowComp","description":"A PyTorch implementation of Mnemonic Reader for the Machine Comprehension task","archived":false,"fork":false,"pushed_at":"2018-11-15T13:24:11.000Z","size":103,"stargazers_count":136,"open_issues_count":4,"forks_count":38,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-27T03:34:43.363Z","etag":null,"topics":["document-reader","machine-comprehension","mnemonic-reader","nlp","pytorch","r-net","squad"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUST-KnowComp.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}},"created_at":"2018-04-16T17:22:48.000Z","updated_at":"2024-06-24T08:40:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"645e292d-f8a6-4964-9eab-6a1cdad3b435","html_url":"https://github.com/HKUST-KnowComp/MnemonicReader","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/HKUST-KnowComp/MnemonicReader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-KnowComp%2FMnemonicReader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-KnowComp%2FMnemonicReader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-KnowComp%2FMnemonicReader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-KnowComp%2FMnemonicReader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUST-KnowComp","download_url":"https://codeload.github.com/HKUST-KnowComp/MnemonicReader/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-KnowComp%2FMnemonicReader/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266019657,"owners_count":23864916,"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":["document-reader","machine-comprehension","mnemonic-reader","nlp","pytorch","r-net","squad"],"created_at":"2024-08-07T23:02:05.861Z","updated_at":"2025-07-19T21:30:40.359Z","avatar_url":"https://github.com/HKUST-KnowComp.png","language":"Python","readme":"# Mnemonic Reader\nThe Mnemonic Reader is a deep learning model for Machine Comprehension task. You can get details from this [paper](https://arxiv.org/pdf/1705.02798.pdf). It combines advantages of [match-LSTM](https://arxiv.org/pdf/1608.07905), [R-Net](https://www.microsoft.com/en-us/research/wp-content/uploads/2017/05/r-net.pdf) and [Document Reader](https://arxiv.org/abs/1704.00051) and utilizes a new unit, the Semantic Fusion Unit (SFU), to achieve state-of-the-art results (at that time).\n\nThis model is a [PyTorch](http://pytorch.org/) implementation of Mnemonic Reader. At the same time, a PyTorch implementation of R-Net and a PyTorch implementation of Document Reader are also included to compare with the Mnemonic Reader. Pretrained models are also available in [release](https://github.com/HKUST-KnowComp/MnemonicReader/releases).\n\nThis repo belongs to [HKUST-KnowComp](https://github.com/HKUST-KnowComp) and is under the [BSD LICENSE](LICENSE).\n\nSome codes are implemented based on [DrQA](https://github.com/facebookresearch/DrQA).\n\nPlease feel free to contact with Xin Liu (xliucr@connect.ust.hk) if you have any question about this repo.\n\n### Evaluation on SQuAD\n\n| Model                                 | DEV_EM | DEV_F1 |\n| ------------------------------------- | ------ | ------ |\n| Document Reader (original paper)      | 69.5   | 78.8   |\n| Document Reader (trained model)       | 69.4   | 78.6   |\n| R-Net (original paper 1)              | 71.1   | 79.5   |\n| R-Net (original paper 2)              | 72.3   | 80.6   |\n| R-Net (trained model)                 | 70.2   | 79.4   |\n| Mnemonic Reader (original paper)      | 71.8   | 81.2   |\n| Mnemonic Reader + RL (original paper) | 72.1   | 81.6   |\n| Mnemonic Reader (trained model)       | 73.2   | 81.5   |\n\n![EM_F1](img/EM_F1.png)\n\n### Requirements\n\n* Python \u003e= 3.4\n* PyTorch \u003e= 0.31\n* spaCy \u003e= 2.0.0\n* tqdm\n* ujson\n* numpy\n* prettytable\n\n### Prepare\n\nFirst of all, you need to download the dataset and pre-trained word vectors.\n\n```bash\nmkdir -p data/datasets\nwget https://rajpurkar.github.io/SQuAD-explorer/dataset/train-v1.1.json -O data/datasets/SQuAD-train-v1.1.json\nwget https://rajpurkar.github.io/SQuAD-explorer/dataset/dev-v1.1.json -O data/datasets/SQuAD-dev-v1.1.json\n```\n\n```bash\nmkdir -p data/embeddings\nwget http://nlp.stanford.edu/data/glove.840B.300d.zip -O data/embeddings/glove.840B.300d.zip\ncd data/embeddings\nunzip glove.840B.300d.zip\n```\n\nThen, you need to preprocess these data.\n\n```bash\npython script/preprocess.py data/datasets data/datasets --split SQuAD-train-v1.1\npython script/preprocess.py data/datasets data/datasets --split SQuAD-dev-v1.1\n```\n\nIf you want to use multicores to speed up, you could add `--num-workers 4` in commands.\n\n### Train\n\nThere are some parameters to set but default values are ready. If you are not interested in tuning parameters, you can use default values. Just run:\n\n```bash\npython script/train.py\n```\n\nAfter several hours, you will get the model in `data/models/`, e.g. `20180416-acc9d06d.mdl` and you can see the log file in `data/models/`, e.g. `20180416-acc9d06d.txt`.\n\n### Predict\n\nTo evaluate the model you get, you should complete this part.\n\n```bash\npython script/predict.py --model data/models/20180416-acc9d06d.mdl\n```\n\nYou need to change the model name in the command above.\n\nYou will not get results directly but to use the official `evaluate-v1.1.py` in `data/script`.\n\n```bash\npython script/evaluate-v1.1.py data/predict/SQuAD-dev-v1.1-20180416-acc9d06d.preds data/datasets/SQuAD-dev-v1.1.json\n```\n\n### Interactivate\n\nIn order to help those who are interested in QA systems, `script/interactivate.py` provides an easy but good demo.\n\n```bash\npython script/interactivate.py --model data/models/20180416-acc9d06d.mdl\n```\n\nThen you will drop into an interactive session. It looks like:\n\n```\n* Interactive Module *\n\n* Repo: Mnemonic Reader (https://github.com/HKUST-KnowComp/MnemonicReader)\n\n* Implement based on Facebook's DrQA\n\n\u003e\u003e\u003e process(document, question, candidates=None, top_n=1)\n\u003e\u003e\u003e usage()\n\n\u003e\u003e\u003e text=\"Architecturally, the school has a Catholic character. Atop the Main Building's gold dome is a golden statue of the Virgin Mary. Immediately in front of the Main Building and facing it, is a copper statue of Christ with arms upraised with the legend \\\"Venite Ad Me Omnes\\\". Next to the Main Building is the Basilica of the Sacred Heart. Immediately behind the basilica is the Grotto, a Marian place of prayer and reflection. It is a replica of the grotto at Lourdes, France where the Virgin Mary reputedly appeared to Saint Bernadette Soubirous in 1858. At the end of the main drive (and in a direct line that connects through 3 statues and the Gold Dome), is a simple, modern stone statue of Mary.\"\n\u003e\u003e\u003e question = \"To whom did the Virgin Mary allegedly appear in 1858 in Lourdes France?\"\n\u003e\u003e\u003e process(text, question)\n\n+------+----------------------------+-----------+\n| Rank |            Span            |   Score   |\n+------+----------------------------+-----------+\n|  1   | Saint Bernadette Soubirous | 0.9875301 |\n+------+----------------------------+-----------+\n```\n\n### More parameters\n\nIf you want to tune parameters to achieve a higher score, you can get instructions about parameters via using\n\n```bash\npython script/preprocess.py --help\n```\n\n```bash\npython script/train.py --help\n```\n\n```bash\npython script/predict.py --help\n```\n\n```bash\npython script/interactivate.py --help\n```\n\n## License\n\nAll codes in **Mnemonic Reader** are under [BSD LICENSE](LICENSE).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHKUST-KnowComp%2FMnemonicReader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHKUST-KnowComp%2FMnemonicReader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHKUST-KnowComp%2FMnemonicReader/lists"}