개요
과학기술 분야에서 연구결과물 (데이터 및 모델)에 대한 재현성 보장은 연구에 사용된 데이터와 코드, 모델의 공개/제공 뿐만 아니라 모델의 학습과 실험에 사용된 환경과 절차를 포함하여 공개/제공함으로써 연구결과물을 제공 받은 다른 독립적인 연구자가 동일 혹은 유사한 결과를 얻을 수 있도록 보장하는 것을 의미하며, 과학기술 연구에 대한 신뢰성 향상과 나아가 지속 가능한 연구 생태계 형성에 있어서 매우 중요한 요소입니다. 이에, 인공지능 분야 연구결과물인 데이터와 모델의 공유와 확산을 목표로 하고 있는 AIDA에서는 데이터 및 모델을 등록할 때 본 가이드라인을 따르도록 함으로써, AIDA를 통해 공유되는 연구 결과물에 대한 재현성을 높이고자 합니다. 데이터 및 모델을 등록할 때, 본 가이드라인(REAME.md)의 양식에 따라, 폴더 구조 및 파일, 데이터, 모델, 실험 등의 섹션을 작성하여 함께 제출하시기 바랍니다.
용어 정의
재현성(Reproducibility)과 관련된 다른 용어들로 복제 가능성(Replicability)와 반복성(Repeatability) 등이 있는데, 각각의 정의와 차이점은 3가지 차원, 즉 구성요소(데이터, 코드, 분석)의 제공 여부, 실험 수행의 주체 구분, 실험을 재수행하려는 이유를 기준으로 다음과 같이 구분할 수 있습니다. (참고문헌: “Reproducibility of Machine Learning: Terminolgy, Recommendations and Open Issues”, 2023-02, arXiv:2302.12691v1)
- 재현성(Reproducibility): 본래의 데이터, 코드, 분석을 사용하여 본래의 실험 결과를 가능한 많이 복제하려고 시도할 때, 독립된 연구 주체가 본래의 연구자가 제공한 데이터와 실험 설정을 사용하여 동일하거나 합리적으로 유사한 결과를 재현할 수 있음을 의미합니다. 비슷한 표현으로는 계산 재현성(computational reproducibility), 방법 재현성 (method reproducibility), 직접 복제(direct replication), 재계산(recomputation) 등이 있습니다.
- 복제 가능성(Replicability): 독립된 연구 주체가 변경된 혹은 새로운 데이터와 방법, 실험 설정을 사용하여, 본래 연구의 결론과 일치하는 결과를 생산할 수 있음을 의미합니다. 비슷한 표현으로는 독립적 재현성 (independently reproducible), 강건성(robust) 등이 있습니다.
- 반복성(Repeatability): 본래의 연구와 동일한 연구주체가 동일한 데이터와 실험 환경을 사용하여 같은 연구 절차를 반복했을 때, 원래의 결론과 합리적으로 일치하는 결과를 생산할 수 있음을 의미합니다. 비슷한 표현으로는 약한 수준의 재현성(weak reproducibility)가 있습니다.
재현성 수준
생명과학 분야 기계학습 연구의 재현성 수준을 제안한 Heil et al. (2021)의 연구에 따르면, 재현성(Reproducibility)을 3가지 수준, 즉 Bronze, Silver, Gold로 구분하고 있으며, 이들 각각의 구분은 다음과 같습니다.
- Bronze Standard: 연구에 사용된 데이터, 모델, 소스코드가 공개되어 있고 다운로드 가능함
- Silver Standard: Bronze 수준에 추가하여, 하나의 명령어 실행으로 실험에 필요한 모든 라이브러리 의존성이 설치되고 설정될 수 있고, 주요 분석의 상세항목들이 기록되어 있고, 모든 분석의 구성요소들이 명시되어 있음
- Gold Standard: Silver 수준에 추가하여, 모든 분석(실험)이 하나의 명령어 실행으로 수행될 수 있음
AIDA에서는 Bronze 수준 이상의 재현성 보장을 지향하고 있습니다.
폴더 구조 및 파일
연구결과물 (데이터 및 모델)은 다음과 같은 폴더 구조 및 파일들로 구성됩니다. 연구결과물의 특성에 따라 해당하지 않는 폴더 혹은 파일의 경우에는 생략할 수 있습니다.
- README.md : 연구결과물 (데이터 및 모델)을 설명하는 Markdown 형식의 파일
- data : 모델의 학습 및 평가에 사용된 데이터 (원본 및 전처리/분할된 데이터) 파일을 담고 있는 폴더
- model : 학습된 모델 파일들을 담고 있는 폴더
- src : 데이터 정제/전처리, 모델 구조, 모델의 학습과 평가를 수행하는 소스코드 파일들(.py)을 담고 있는 폴더
- notebooks : 데이터 정제/전처리, 모델 구조, 모델의 학습과 평가를 수행하는 notebook 파일들(.ipynb)을 담고 있는 폴더
- scripts : 환결 설정, 데이터 정제/전처리, 모델의 학습 및 평가 등을 수행하기 위한 스크립트 파일들을 담고 있는 폴더
- figures : 모델의 설명, 실험 결과 설명에 사용된 그림 파일을 담고 있는 폴더
데이터
데이터 목록
모델의 학습 및 평가에 사용된 데이터 (원본 데이터 및 정제/전처리/분할된 데이터) 파일들을 data 폴더에 제공하고 (혹은 다운로드 가능한 링크를 제공하고), 각 데이터 파일들에 대한 설명을 기술합니다. 아래는 데이터 파일을 설명하는 예시입니다.
- data/data-raw.txt : 원본 데이터입니다. 원본 데이터에 대해 간단히 설명합니다.
- data/data-cleaned.txt : 원본 데이터를 정제한 결과입니다.
- data/data-preprocessed.jsonl : 정제한 데이터에 추가적인 전처리를 적용한 결과 데이터입니다.
- data/data-train.jsonl : 전처리 데이터 중 학습용으로 분할한 데이터입니다.
- data/data-valid.jsonl : 전처리 데이터 중 검증용으로 분할한 데이터입니다.
- data/data-test.jsonl : 전처리 데이터 중 평가용으로 분할한 데이터입니다.
데이터 수집 및 레이블링
자체적으로 수집하고 레이블링한 데이터를 사용하였다면, 데이터 수집 절차에 대한 설명과 수집 소스코드 및 스크립트, 레이블링 부착 기준과 품질 제어 방법을 설명하고 제공합니다. 아래는 데이터 수집 소스코드와 스크립트 설명 예시입니다.
- src/data-collect.py : 데이터를 자체 수집하는 소스코드입니다.
- scripts/data-collect.sh : 데이터 자체 수집을 하나의 명령어로 실행하는 스크립트입니다.
- scripts/data-collect.sh 예시:
$ python ../src/data-collect.py -o ../data/data-collected.txt
데이터 정제 및 전처리
원본 데이터에 대한 정제 및 전처리 방법과 절차를 설명합니다. 정제 및 전처리를 위한 소스코드는 src 폴더에 두도록 하며, 정제 및 전처리를 수행하는 스크립트는 scripts 폴더에 두며, 각각의 파일에 대해 간략히 설명합니다. 아래는 데이터 정제 및 전처리에 관한 소스코드 파일 및 스크립트 설명 예시입니다.
- src/data-clean.py : 원본 데이터를 정제하는 소스코드입니다.
- src/data-preprocessing.py : 정제된 데이터를 전처리하는 소스코드입니다.
- scripts/data-clean-and-preprocess.sh : 데이터 정제 및 전처리를 한번에 수행하는 스크립트입니다.
- scripts/data-clean-and-preprocess.sh 예시:
$ python ../src/data-clean.py -i ../data/data-raw.txt -o ../data/data-cleaned.txt
$ python ../src/data-preprocessing.py -i ../data/data-cleaned.txt -o ../data/data-preprocessed.jsonl
데이터 분할
데이터를 모델의 학습용(train), 검증용(valid), 평가용(test)으로 분할(split)한 방법/기준과 절차를 설명합니다. 분할된 데이터 파일들은 data 폴더에 두도록 하며, 데이터 분할을 수행하는 소스코드는 src 폴더에, 스크립트는 scripts 폴더에 두며, 각각의 파일에 대해 간략히 설명합니다. 아래는 데이터 분할에 관한 소스코드 및 스크립트 설명 예시입니다.
- src/data-split.py : 전처리된 데이터를 학습용, 검증용, 평가용으로 분할하는 소스코드입니다.
- scripts/data-split.sh : 전처리된 데이터를 학습용, 검증용, 평가용으로 분할하는 스크립트입니다.
- scripts/data-split.sh 예시:
$ python ../src/data-split.py -i ../data/data-preprocessed.jsonl --train=../data/data-train.jsonl --valid=../data/data-valid.jsonl --test=../data/data-test.jsonl
데이터 특성
모델의 학습 및 평가에 사용된 데이터의 특성에 대해 설명합니다. 데이터의 특성으로는 데이터의 출처, 데이터가 속하는 분야, 데이터 값의 유형과 범위, 학습용/검증용/평가용 데이터의 샘플 수, 카테고리별 레이블 개수, 컬럼 이름들, 샘플의 길이 등 데이터를 이해하는 데 유용한 여러 가지 정보들이 포함될 수 있습니다.
모델
모델 코드
모델의 토크나이저, 구조와 생성, 학습, 추론, 평가에 관련된 소스코드 파일들을 src 폴더에, notebook 파일들은 notebooks 폴더에 제공하고, 각 소스코드 파일들에 대한 설명을 기술합니다. 모델 구조, 학습, 추론, 평가에서 사용되는 하이퍼 파라미터들(hyper-parameters)은 소스코드 내에 hard-coding하지 않도록 하며, 명령행 실행 시에 인자로 지정할 수 있도록 해야 합니다. 아래는 모델 코드 파일을 설명하는 예시입니다.
- src/tokenize.py : 입력 데이터(텍스트)를 토크으로 분리하는 소스코드입니다.
- src/model.py : 모델의 구조를 생성하는 소스코드입니다.
- src/train.py : 모델의 학습에 관한 소스코드입니다.
- src/infer.py : 모델의 추론에 관한 소스코드입니다.
- src/test.py : 모델의 성능을 평가하는 소스코드입니다.
학습된 모델
학습된 모델 가중치 파일 및 하이퍼-파라미터들이 저장된 환경 파일(config.json)을 model 폴더에 제공합니다. 아래는 모델 가중치 파일 및 환결 파일을 설명하는 예시입니다.
- model/pytorch-model.bin : 학습된 모델의 PyTorch 버전 가중치입니다.
- model/tf-model.h5 : 학습된 모델의 TF 버전 가중치입니다.
- model/spm.model : 학습된 토크나이저 모델입니다.
- model/config.json : 모델의 학습에 사용된 hyper-parameter 환경 파일입니다.
- model/tokenizer-config.json : 모델의 학습에 사용된 토크나이저 환경 파일입니다.
모델 구조 및 알고리즘
참조하는 모델이 무엇인지, 추가된 모델 구조 (계층, 뉴런 수, 활성화 함수, 연결 구조 등)와 알고리즘이 무엇인지 등에 대해 설명합니다.
모델 (및 데이터)에 대한 메타데이터를 모델카드에도 작성하여 주시기 바랍니다.
실험
HW 환경
실험 (모델의 학습, 추론, 평가)에 사용된 HW 환경에 대해 설명합니다. 실험(모델의 학습 및 평가 등)을 수행하는 데 필요한 HW 요구사항을 판단하는데 기준이 될 수 있는 사항들을 기재합니다. 특히, 사용된 GPU 모델이 무엇이고 몇 개인지, GPU의 메모리 크기는 얼마인지, CPU RAM의 크기는 얼마인지 등에 대해 기술합니다. 그 외에, 실험을 위해 요구되는 HW 최소 요구사항이 있다면 함께 기술합니다. 아래는 HW 환경의 예시입니다.
- RAM : 128GB
- GPU : Nvidia Quadro RTX 8000 48GB * 2EA
SW 환경
실험 (데이터 정제/전처리, 모델의 학습, 추론, 평가)을 수행하기 위한 주요 SW 라이브러리 환경에 대해 설명합니다. 필요한 각 라이브러리의 이름과 버전 및 설치 방법을 설명합니다. conda, pyenv-virtualenv, venv 또는 virtualenv를 사용한 가상환경 하에서 conda 혹은 pip를 이용한 필요 라이브러리를 설치하는데 필요한 라이브러리-환경 파일 (environment.yaml 또는 requirements.txt)을 제공합니다.
먼저, 분리된 가상환경을 생성하기 위한 도구로, conda, pyenv-virtualenv, venv 또는 virtualenv를 사용할 수 있습니다.
- conda는 패키지/의존성/가상환경 관리를 지원하는 도구, OS별 보다 자세한 설치 및 사용은 Minoconda3를 참고하세요.
- vevn는 파이썬에 내장되어 있는 가상환경 모듈이며, Python 3.5 이후부터 표준 라이브러리에 포함되어 별도의 설치가 필요하지 않습니다.
- pyenv는 파이썬 관리 도구인데, 이와 함께 설치되는 virtualenv 플러그인을 이용해 가상환경을 관리할 수 있습니다. pyenv 사이트와 pyenv-virtualenv사이트를 참고하세요.
- virtualenv는 독립된 파이썬 환경 생성 도구로, 보다 자세한 설치 방법은 Virtualenv Installation을 참고하세요.
conda를 이용한 SW 환경 공유
conda 환경에서 모델을 개발하였다면, 모델 개발에 사용된 conda 환경을 yaml 파일로 반출하여 공유할 수 있습니다.
모델 개발 환경 이름이 myenv일 경우, 다음과 같은 명령을 실행하여 해당 환경(myenv)에 진입한 후, 해당 환경을 environment.yaml 파일에 반출(저장)할 수 있습니다. --from-history
옵션을 사용하면, conda install ...
을 통해 직접 설치한 라이브러리들 목록만 반출됩니다. 만약 pip install ...
을 통해서 직접 설치한 라이브러리들이 있다면, 이 옵션 없이 실행해야 합니다. 다만, 이 경우, 운영체제에 따라 기본적으로 설치되는 라이브러리들과 의존성에 따라 설치되는 라이브러리들 목록까지 모두 반출되는데, 직접 설치하지 않은 라이브러리들 목록은 편집기를 통해 수작업으로 삭제하는 것이 OS 플랫폼 호환성을 높이기 위해 필요합니다. 예를 들어, 아래의 예시에서, _libgcc_mutex=0.1=main
와 _openmp_mutex=5.1=1_gnu
, absl-py==2.1.0
등은 OS에 따라 혹은 의존성에 의해 설치된 것들이므로 삭제하는 것이 좋습니다.
반출(저장)된 environment.yaml 파일로부터 간단히 conda 환경을 생성할 수 있습니다. conda를 이용한 가상환경 관리에 대한 보다 자세한 설명은 Managing environments를 참고하세요.
- conda 환경을 environment.yaml 파일로 반출(저장)하기:
$ conda activate myenv
$ conda env export > environment.yaml
## 또는
$ conda env export --from-history > environment.yaml
- 저장된 environment.yaml (예시):
name: myenv
channels:
- conda-forge
- defaults
dependencies:
- _libgcc_mutex=0.1=main
- _openmp_mutex=5.1=1_gnu
- pip=24.0=py310h06a4308_0
- python=3.10.14=h955ad1f_1
- pip:
- absl-py==2.1.0
- accelerate==0.33.0
- huggingface-hub==0.24.5
- tensorflow==2.15.1
- torch==2.4.0
- transformers==4.45.0.dev0
prefix: /Users/username/miniconda3/envs/myenv
반출(저장)한 환경 파일(environment.yaml)은 root 폴더에 두며, 이를 이용하여 conda 환경을 간단히 생성할 수 있습니다.
- envrionment.yaml : conda 가상 환경을 반출하여 저장한 파일입니다.
- environment.yaml로 부터 conda 가상환경 생성 예시 :
$ conda env create -f environment.yml
pyenv-virtualenv, venv 또는 virtualenv를 이용한 SW 환경 공유
pyenv-virtualenv, venv 또는 virtualenv 등을 이용하여 생성한 가상환경에서는 필요한 라이브러리들을 pip 명령으로 설치하기 때문에, 설치된 라이브러리 목록은 해당 가상 환경에 진입한 상태에서 아래와 같이 pip freeze 명령으로 반출(저장)할 수 있습니다.
- 가상환경의 라이브러리 설치 목록을 requirements.txt 파일로 반출하기:
## 해당 가상환경에 진입한 상태에서 다음 명령을 실행합니다.
$ pip freeze > requirements.txt
- 저장된 requirements.txt (예시):
huggingface-hub==0.24.5
regex==2024.7.24
requests==2.32.3
safetensors==0.4.4
tokenizers==0.19.1
tensorflow==2.15.1
torch==2.4.0
tqdm==4.66.5
transformers==4.44.0
typing_extensions==4.12.2
반출(저장)한 환경 파일(requirements.txt)은 root 폴더에 두며, 이로부터 pip 명령으로 간단히 동일한 환경을 생성할 수 있습니다.
- requirements.txt : pip로 가상 환경을 반출하여 저장한 파일입니다.
- requirements.txt 파일로부터 환경(라이브러리) 설치 예시:
## 해당 가상환경을 먼저 생성하고 진입한 상태에서 다음 명령을 실행합니다.
$ pip install -r requirements.txt
하이퍼-파라미터 (Hyper-parameters)
모델의 학습에 사용된 하이퍼-파라미터(hyper-parameters) 목록을 제시하고 각 하이퍼-파라미터의 의미와 사용된 값을 기술합니다. 모델의 학습 시에 사용한 하이퍼-파라미터는 모델 가중치와 함께 model 폴더에 config.json 파일로 저장합니다.
- 하이퍼-파라미터 (예시) :
bs : batch size = 32
eps : number of epochs = 10
optimizer : Optimizer = AdamW
scheduler : Learning rate scheduler = LinearDecay
lr : Learning rate = 1e-3
wd : Weight decay = 3e-3
하이퍼-파라미터 튜닝을 수행한 경우, 어떤 튜닝 라이브러리를 사용하였는지, 튜닝에 사용된 하이퍼-파라미터 값의 범위는 무엇인지를 기술합니다.
- 하이퍼-파라미터 튜닝 범위 (예시) :
## [start-value, end-value, step-value]
lr : [1e-4, 1e-3, 1e-4]
wd : [1e-3, 1e-2, 1e-3]
실험 수행
실험을 수행하는 목적과 수행 방법 및 절차를 자세히 기술합니다. 일반적으로 어떤 태스크를 위한 모델을 학습 (하이퍼-파라미터 튜닝 포함)한 후, 학습한 모델을 이용하여 추론하고 평가를 수행하는 절차를 거칩니다.
비결정성(non-determinism) 피하기
동일한 환경, 동일한 하이퍼-파라미터를 사용하더라도 random number와 같은 비결정성(non-determinism)으로 인해, 실험 결과가 다르게 나올 수 있는데, 이는 연구결과물의 재현성 (reproducibility)을 어렵게 하는 요인입니다. 따라서, 가능한 random number에 의한 비결정성을 줄이기 위해, 실험의 매 run을 시작할 때, 특정 seed 값으로 random number 생성기를 초기화하는 것이 필요합니다. 아래는 python, numpy, tensorflow, torch 수준에서의 random number 생성기를 특정 seed 값으로 초기화하는 코드 예시를 보여줍니다.
- random number 생성기를 seed_value로 초기화 하기:
def reset_seeds(seed_value=None):
if seed_value is not None:
random.seed(seed_value)
np.random.seed(seed_value)
# in case that tensorflow is used
tf.random.set_seed(seed_value)
# in case that torch is used
torch.manual_seed(seed_value)
Tensorflow의 경우, tf.data.Dataset 객체를 통해 데이터를 shuffle할 경우 GPU 연산 시에 데이터를 무작위 순서로 연산하기 때문에 비결정성이 발생합니다. 이 경우에는 다음의 코드를 추가하여 tf.data.Dataset 객체에 대한 GPU의 비결정성을 피할 수 있습니다. 그러나, 이는 모델의 학습 결과의 성능에 영향을 미칠 수 있습니다. 보다 자세한 내용은 Reproducibility in Keras Models를 참고하세요.
- tf.data.Dataset 객체에 대한 GPU 연산의 무작위성 피하기:
# If using TensorFlow, this will make GPU ops as deterministic as possible,
# but it will affect the overall performance, so be mindful of that.
tf.config.experimental.enable_op_determinism()
모델의 학습
모델을 학습하는 방법을 하나의 스크립트(train.sh)로 scripts 폴더에 제공하고 설명합니다.
- scripts/train.sh (예시) :
python train.py \
--data=data-train.jsonl \
--lr=1e-3 \
--wd=1e-2 \
--bs=32 \
--eps=10 \
--optimizer=AdamW \
...
모델의 평가
모델을 평가하는 (모델의 성능을 측정하는) 방법을 하나의 스크립트(test.sh)로 scripts 폴더에 제공하고 설명합니다.
- scripts/test.sh (예시) :
python test.py \
--model=../model \
--data=data-test.jsonl \
--bs=32 \
...
모델의 추론
모델을 사용하여 추론하는 방법을 하나의 스크립트(infer.sh)로 scripts 폴더에 제공하고 설명합니다.
- scripts/infer.sh (예시) :
python infer.py \
--model=../model \
--data=data-test.jsonl \
--bs=32 \
...
실험 결과 분석
실험을 수행한 결과를 표나 차트로 제시하고 다른 모델의 결과와 비교합니다. 모델의 성능을 측정하는 데 사용된 메트릭(metrics) (eg., 정확도, 정밀도, 재현율, F1 등)을 설명하고, 모델의 학습 과정에서의 손실 및 성능 (train 손실/성능, valid 손실/성능) 변화, 최종 선정된 모델의 성능(평균과 분산)을 표/차트와 함께 설명합니다. 아울러, 모델의 비결정성(non-determinism)을 고려한 성능 평균치를 제시할 때 몇 회 run의 평균치인지를 밝히고 학습 소요시간(평균과 분산) 및 평가(추론) 소요 시간(평균과 분산) 등도 함께 제시합니다.
부록
- 재현성 보장을 위한 데이터 및 모델 등록 체크리스트
- 모델카드: AI 모델에 대한 메타데이터를 기재하는 템플릿