chore: modify readme

README.md

@@ -1,12 +1,30 @@
-# Readme
+# ODQA(Open Domain Question Answering)
 
 ## 소개
 
-P stage 3 대회를 위한 베이스라인 코드 
+지문이 주어진 상태에서 질의에 해당하는 답을 찾는 Task를 MRC(Machine Reading Comprehension)라고 한다.  
+ODQA는 지문이 주어진 상태가 아니라 wiki나 웹 전체 등과 같은 다양한 documents들 중 적절한 지문을 찾는 retrieval 단계와 추출된 지문들 사이에서 적절한 답을 찾는 reader 단계, 2-stage로 이루어진 Task를 의미한다.  
 
-## 설치 방법
+### Retrieval
 
-### 요구 사항
+문서들을 추출하기 위해 일련의 벡터 형태로 표현해야 하는데 대표적으로 Sparse Embedding 방식과 Dense Embedding 방식으로 나누어 진다.  
+
+### Reader
+
+질의에 맞는 적절한 답을 추출된 문서들 사이에서 찾는 단계로, 정답의 span을 예측하는 방식으로 학습된다.
+
+<br>
+
+# 팀 구성
+
+
+|[김현수](https://github.com/khs0415p)|[이성구](https://github.com/papari1123)|[이현준](https://github.com/coderJoon)|[조문기](https://github.com/siryuon)|[조익노](https://github.com/iknocho)|
+|:-:|:-:|:-:|:-:|:-:|
+|<a href="https://github.com/khs0415p"><img src="assets/profile/hs.png" width=300></a>|<a href="https://github.com/papari1123"><img src="assets/profile/sg.png" width=280></a>|<a href="https://github.com/coderJoon"><img src="assets/profile/hj.png" width=310></a>|<a href="https://github.com/siryuon"><img src="assets/profile/mg.png" width=290></a>|<a href="https://github.com/iknocho"><img src="assets/profile/ik.png" width=280></a>|
+
+<br>
+
+# Requirements
 
 ```
 # data (51.2 MB)
@@ -16,25 +34,49 @@ tar -xzf data.tar.gz
 bash ./install/install_requirements.sh
 ```
 
-## 파일 구성
+<br>
 
+# 파일 구성
 
-### 저장소 구조
+## 저장소 구조
 
 ```bash
-./assets/                # readme 에 필요한 이미지 저장
-./install/               # 요구사항 설치 파일 
-./data/                  # 전체 데이터. 아래 상세 설명
-retrieval.py             # sparse retreiver 모듈 제공 
-arguments.py             # 실행되는 모든 argument가 dataclass 의 형태로 저장되어있음
-trainer_qa.py            # MRC 모델 학습에 필요한 trainer 제공.
-utils_qa.py              # 기타 유틸 함수 제공 
-
-train.py                 # MRC, Retrieval 모델 학습 및 평가 
-inference.py		     # ODQA 모델 평가 또는 제출 파일 (predictions.json) 생성
+.
+|-- README.md
+|
+|-- arguments.py # data, model, training arguments 관리
+|
+|-- colbert # dense retrieval(ColBERT) 학습 및 추론
+|   |-- evaluate.py
+|   |-- inference.py
+|   |-- model.py
+|   |-- tokenizer.py
+|   `-- train.py
+|
+|-- es_retrieval.py # sparse retrieval(Elasticsearch) connetion
+|-- retrieval.py # tfidf, bm25, elasticsearch retrieval class
+|-- settings.json # elasticsearch settings
+|
+|-- kfold_ensemble_hard.py # k-fold hard voting
+|-- kfold_ensemble_soft.py # k-fold soft voting
+|-- make_folds.py
+|
+|-- models # model 저장소
+|   `-- model_folder
+|
+|-- outputs # matrix 저장소
+|   `-- output_folder
+|
+|-- train.py # reader 학습
+|-- train_kfold.py # reader 학습(with. k-fold)
+|-- inference.py # retrieval + reader (end-to-end) 평가 및 추론
+|-- trainer_qa.py # Trainer class
+`-- utils_qa.py # utility function
 ```
 
-## 데이터 소개
+<br>
+
+# 데이터 소개
 
 아래는 제공하는 데이터셋의 분포를 보여줍니다.
 
@@ -49,17 +91,15 @@ inference.py		     # ODQA 모델 평가 또는 제출 파일 (predictions.json)
     ./wikipedia_documents.json # 위키피디아 문서 집합. retrieval을 위해 쓰이는 corpus.
 ```
 
-data에 대한 argument 는 `arguments.py` 의 `DataTrainingArguments` 에서 확인 가능합니다. 
-
-# 훈련, 평가, 추론
+data에 대한 argument 는 `arguments.py` 의 `DataTrainingArguments` 에서 확인 가능합니다.  
+만약 arguments 에 대한 세팅을 직접하고 싶다면 `arguments.py` 를 참고해주세요. 
 
-### train
+<br>
 
-만약 arguments 에 대한 세팅을 직접하고 싶다면 `arguments.py` 를 참고해주세요. 
+# Usage
 
-roberta 모델을 사용할 경우 tokenizer 사용시 아래 함수의 옵션을 수정해야합니다.
-베이스라인은 klue/bert-base로 진행되니 이 부분의 주석을 해제하여 사용해주세요 ! 
-tokenizer는 train, validation (train.py), test(inference.py) 전처리를 위해 호출되어 사용됩니다.
+roberta 모델을 사용할 경우 tokenizer 사용시 아래 함수의 옵션을 수정해야합니다.  
+tokenizer는 train, validation (train.py), test(inference.py) 전처리를 위해 호출되어 사용됩니다.  
 (tokenizer의 return_token_type_ids=False로 설정해주어야 함)
 
 ```python
@@ -79,13 +119,24 @@ def prepare_train_features(examples):
             padding="max_length" if data_args.pad_to_max_length else False,
         )
 ```
+<br>
+
+## train
 
 ```bash
 # 학습 예시 (train_dataset 사용)
 python train.py --output_dir ./models/train_dataset --do_train
 ```
 
-### eval
+- `train.py` 에서 sparse embedding 을 훈련하고 저장하는 과정은 시간이 오래 걸리지 않아 따로 argument 의 default 가 True로 설정되어 있습니다. 실행 후 sparse_embedding.bin 과 tfidfv.bin 이 저장이 됩니다. **만약 sparse retrieval 관련 코드를 수정한다면, 꼭 두 파일을 지우고 다시 실행해주세요!** 안그러면 기존 파일이 load 됩니다.
+
+- 모델의 경우 `--overwrite_cache` 를 추가하지 않으면 같은 폴더에 저장되지 않습니다. 
+
+- `./outputs/` 폴더 또한 `--overwrite_output_dir` 을 추가하지 않으면 같은 폴더에 저장되지 않습니다.
+
+<br>
+
+## eval
 
 MRC 모델의 평가는(`--do_eval`) 따로 설정해야 합니다.  위 학습 예시에 단순히 `--do_eval` 을 추가로 입력해서 훈련 및 평가를 동시에 진행할 수도 있습니다.
 
@@ -94,7 +145,9 @@ MRC 모델의 평가는(`--do_eval`) 따로 설정해야 합니다.  위 학습
 python train.py --output_dir ./outputs/train_dataset --model_name_or_path ./models/train_dataset/ --do_eval 
 ```
 
-### inference
+<br>
+
+## inference
 
 retrieval 과 mrc 모델의 학습이 완료되면 `inference.py` 를 이용해 odqa 를 진행할 수 있습니다.
 
@@ -108,14 +161,62 @@ retrieval 과 mrc 모델의 학습이 완료되면 `inference.py` 를 이용해
 python inference.py --output_dir ./outputs/test_dataset/ --dataset_name ../data/test_dataset/ --model_name_or_path ./models/train_dataset/ --do_predict
 ```
 
-### How to submit
 
-`inference.py` 파일을 위 예시처럼 `--do_predict` 으로 실행하면 `--output_dir` 위치에 `predictions.json` 이라는 파일이 생성됩니다. 해당 파일을 제출해주시면 됩니다.
+<br>
+
+# Models
+
+## Retrieval
+
+### Sparse Embedding
+
+- TF-IDF
+
+<img src="./assets/tf.png" height=45 width=340>  
+<img src="./assets/idf.png" height=45 width=150>
+<img src="./assets/tfidf.png" width=500>
+
+단어의 등장빈도(TF)와 단어가 제공하는 정보의 양(IDF)를 이용한 function
+
+- BM25
+
+<img src="./assets/bm25.png" width=500>
+
+기존 TF-IDF보다 TF의 영향력을 줄인 알고리즘으로 TF의 한계를 지정하여 일정 범위를 유지하도록 한다.  
+BM25는 문서의 길이가 더 작을수록 큰 가중치를 부여하는 function
+
+- Elasticsearch
+
+Elasticsearch는 기본적으로 scoring function으로 bm25 알고리즘을 사용한다.  
+위의 bm25와 차이점은 `k=1.2`, `b=0.75`를 사용했다.
+검색엔진의 Elasticsearch는 다양한 플러그인을 사용할 수 있는데 우리는 형태소 분석기인 *nori-analyzer*를 사용했다. 자세한 setting은 `settings.json`파일을 참고할 수 있다.
+
+### Dense Embedding
+
+- ColBERT
+
+<img src="./assets/colbert.png" width=500>
+
+ColBERT는 BERT 기반의 Encoder를 사용하는 모델로 Query 인코더의 $f_Q$ Document 인코더의 $f_D$로 구성된다.  
+하나의 BERT모델을 공유하여 이를 구분하기 위해 *[Q], [D]*의 스페셜 토큰을 사용하며 Query와 Document의 relevance score를 구하는 함수는 Cosine similarity를 사용했다.  
+ColBERT는 각 문서에 대한 점수를 생성하고 Cross-entropy loss를 이용하여 최적화를 진행한다.  
+다양한 실험을 통해 ColBERT와 BM25간의 가중치를 부여한 Ensemble모델을 채택하여 사용했으며 자세한 실험 내용은 [이곳](https://github.com/boostcampaitech4lv23nlp2/level2_mrc_nlp-level3-nlp-08/discussions/23)에서 확인할 수 있다.
+
+<br>
+
+## Reader
+
+- BERT
+
+- BERT multilingual
+
+- klue/RoBERTa
+
+- xlm/RoBERTa
 
-## Things to know
+- ELECTRA
 
-1. `train.py` 에서 sparse embedding 을 훈련하고 저장하는 과정은 시간이 오래 걸리지 않아 따로 argument 의 default 가 True로 설정되어 있습니다. 실행 후 sparse_embedding.bin 과 tfidfv.bin 이 저장이 됩니다. **만약 sparse retrieval 관련 코드를 수정한다면, 꼭 두 파일을 지우고 다시 실행해주세요!** 안그러면 기존 파일이 load 됩니다.
 
-2. 모델의 경우 `--overwrite_cache` 를 추가하지 않으면 같은 폴더에 저장되지 않습니다. 
+<br>
 
-3. `./outputs/` 폴더 또한 `--overwrite_output_dir` 을 추가하지 않으면 같은 폴더에 저장되지 않습니다.
+# Results