{"id":21441754,"url":"https://github.com/dmis-lab/excord","last_synced_at":"2025-07-23T09:36:44.466Z","repository":{"id":97388607,"uuid":"379171622","full_name":"dmis-lab/excord","owner":"dmis-lab","description":"Learn to Resolve Conversational Dependency: A Consistency Training Framework for Conversational Question Answering (Kim et al., ACL 2021)","archived":false,"fork":false,"pushed_at":"2023-01-02T03:07:35.000Z","size":72,"stargazers_count":32,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-14T20:10:04.076Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2106.11575","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/dmis-lab.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,"zenodo":null}},"created_at":"2021-06-22T06:54:09.000Z","updated_at":"2024-11-26T17:45:55.000Z","dependencies_parsed_at":"2024-03-14T05:15:51.660Z","dependency_job_id":null,"html_url":"https://github.com/dmis-lab/excord","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dmis-lab/excord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmis-lab%2Fexcord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmis-lab%2Fexcord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmis-lab%2Fexcord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmis-lab%2Fexcord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmis-lab","download_url":"https://codeload.github.com/dmis-lab/excord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmis-lab%2Fexcord/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266655743,"owners_count":23963554,"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-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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-11-23T01:41:57.530Z","updated_at":"2025-07-23T09:36:44.450Z","avatar_url":"https://github.com/dmis-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003e\n\u003cp\u003eExCorD\n\u003ca href=\"https://github.com/dmis-lab/excord/blob/master/LICENSE\"\u003e\n   \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"\u003e\n\u003c/a\u003e\n\u003c/h3\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003cp\u003e\u003cb\u003eEx\u003c/b\u003eplicit Guidance on How to Resolve \u003cb\u003eCo\u003c/b\u003enve\u003cb\u003er\u003c/b\u003esational \u003cb\u003eD\u003c/b\u003eependency\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"ExCorD Overview\" src=\"https://github.com/dmis-lab/excord/blob/main/images/ExCorD_overview.png\" width=\"400px\"\u003e\n\u003c/div\u003e\n\nWe present ExCorD for conversational question answering (CQA). You can train RoBERTa by using our framework, ExCorD, described in our [paper](https://aclanthology.org/2021.acl-long.478/). Once you train the model with ExCorD, you can easily evaluate it in the same way with that of common CQA models.\n\n\n## Requirements\n```bash\n$ conda create -n excord python=3.8\n$ conda activate excord\n$ conda install tqdm\n$ conda install pytorch==1.5.0 torchvision==0.6.0 cudatoolkit=10.1 -c pytorch\n$ pip install transformers==3.3.1\n```\nNote that Pytorch has to be installed depending on the version of CUDA.\n\n### Datasets\n\n[Download link](https://drive.google.com/drive/folders/1TJ-cWllUs8SFJlwJdUjUmJJW_kkr-l_u?usp=share_link)\n\nWe use the [QuAC (Choi et al., 2018)](https://quac.ai/) dataset for training and evaluating our models. Datasets you can download from the above link consist of `train.json`, `valid.json` and `dev.json`. Note that `dev.jon` is the official development set of QuAC. On the other hand, `train.json` includes the self-contained questions generated by human annotators in [CANARD (Elgohary et al., 2019)](https://sites.google.com/view/qanta/projects/canard) or our question rewriting (QR) model. You can search optimal hyperparameters by evaluating your model with `valid.json`.\n\n## Train\n\nThe following example fine-tunes RoBERTa on the QuAC dataset by using ExCorD. \nA single 24GB GPU (RTX TITAN) is used for the example so we recommend you to use similar or better equipments.\n\n```bash\nINPUT_DIR=./datasets/\nOUTPUT_DIR=./tmp/\n\npython run_quac.py \\\n\t--model_type roberta \\\n\t--model_name_or_path roberta-base \\\n\t--do_train \\\n\t--data_dir ${INPUT_DIR} \\\n\t--train_file train.json \\\n\t--output_dir ${OUTPUT_DIR} \\\n\t--per_gpu_train_batch_size 12 \\\n\t--num_train_epochs 2 \\\n\t--learning_rate 3e-5 \\\n\t--weight_decay 0.01 \\\n\t--threads 20 \\\n\t--excord_cons_coeff 0.5 \\\n\t--excord_softmax_temp 1 \\\n```\n\nFor efficiency, you can also add `--fp16` arguement after setting up `apex` from [here](https://github.com/NVIDIA/apex). Additionally, preprocessing step can be done faster by setting a larger number for `--threads`, which indicates the number of CPU cores assigned to the process.\n\n## Evaluation\n\nThe following example evaluates our trained model with the development set of QuAC.\n\n```bash\nINPUT_DIR=./datasets/\nMODEL_DIR=./model/\nOUTPUT_DIR=./tmp/\n\npython run_quac.py \\\n\t--model_type roberta \\\n\t--model_name_or_path ${MODEL_DIR} \\\n\t--cache_prefix roberta-base \\\n\t--data_dir ${INPUT_DIR} \\\n\t--predict_file dev.json \\\n\t--output_dir ${OUTPUT_DIR} \\\n\t--do_eval \\\n\t--per_gpu_eval_batch_size 100 \\\n\t--threads 20 \\\n```\n\n### Result\nEvaluating models trained with predefined hyperparameters yields the following results:\n\n```bash\nResults: {'F1': 67.23447159600119}\n```\n\n### Best Model\n[Download link](https://drive.google.com/drive/folders/1TJ-cWllUs8SFJlwJdUjUmJJW_kkr-l_u?usp=share_link)\n\nYou can also download our best model and its predictions on `dev.json` from the above link.\n\n## Citation\n\n```bibtex\n@inproceedings{kim2021conversation,\n    title={Learn to Resolve Conversational Dependency: A Consistency Training Framework for Conversational Question Answering},\n    author={Kim, Gangwoo and Kim, Hyunjae and Park, Jungsoo and Kang, Jaewoo},\n    booktitle={Association for Computational Linguistics (ACL)},\n    year={2021},\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmis-lab%2Fexcord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmis-lab%2Fexcord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmis-lab%2Fexcord/lists"}