딥러닝 프로젝트를 진행할 때 가장 번거로운 작업 중 하나는 수많은 하이퍼파라미터와 설정값을 효과적으로 관리하는 것입니다. 학습 모듈에서는 배치 크기, 에폭 수, 학습률 스케줄러 관련 값들이 필요하고, 데이터 전처리 단계에서는 훈련-검증 분할 비율, 이미지 증강 파라미터 등이 필요합니다.
이러한 설정들을 명령줄 인자로 전달하는 방식은 입력이 복잡해지고 관리가 어렵습니다. TOML 형식의 설정 파일을 활용하면 이러한 문제를 해결할 수 있습니다. TOML은 Python 딕셔너리로 쉽게 변환될 수 있어 코드에서 직접 접근하기 편리합니다.
TOML 형식의 특징
TOML(Tom's Obvious Minimal Language)은 설정 파일 전용으로 설계된 형식입니다. YAML과 유사하게 계층적 구조로 키-값 쌍을 저장할 수 있지만, 깊은 중첩 구조에서도 가독성을 유지하는 장점이 있습니다.
TOML 설정의 실용적 이점
ML 프로젝트에서 TOML을 활용하면 두 가지 핵심 이점을 얻을 수 있습니다:
- 중앙 집중식 설정 관리: 학습 관련 설정은
[train]섹션에, 서비스 배포 정보는[serve]섹션에 모아두고, 단일 파일에서 전체 프로젝트의 설정을 제어할 수 있습니다.train.py와inference.py를 따로 수정할 필요가 없습니다. - 서버 환경 친화적: SSH로 접속한 원격 서버에서 vim이나 nano로 간단히 수정할 수 있어, GUI 없는 환경에서도 설정 변경이 용이합니다.
Python에서 TOML 활용하기
TOML 파일을 Python 코드에서 활용하려면 toml과 munch 패키지를 함께 사용하는 것을 권장합니다. toml은 파일을 파싱하여 딕셔너리로 변환하고, munch는 점 표기법(dot notation)으로 속성에 접근할 수 있게 해줍니다. 즉, cfg["optimization"]["lr"] 대신 cfg.optimization.lr처럼 더 직관적으로 작성할 수 있습니다.
다음은 프로젝트 구조 예시입니다:
project/
├── settings.toml
├── configuration.py
└── experiment.py
settings.toml의 내용 예시:
[preprocessing]
token_count = 5589
max_seq_len = 10
eval_ratio = 0.3
raw_data_dir = "dataset/"
tensor_cache_dir = "cached_tensors/"
[architecture]
vector_dim = 256
transformer_layers = 5
attention_heads = 3
[optimization]
max_iterations = 10
samples_per_batch = 32
step_size = 0.001
model_artifact_dir = "auto"
설정을 불러오는 유틸리티 모듈 configuration.py:
import toml
import munch
def fetch_settings(path="settings.toml"):
raw_data = toml.load(path)
return munch.munchify(raw_data)
def persist_settings(updated, path="settings.toml"):
with open(path, "w", encoding="utf-8") as f:
toml.dump(updated, f)
실제 학습 스크립트 experiment.py에서의 사용:
from configuration import fetch_settings
cfg = fetch_settings()
samples_per_batch = cfg.optimization.samples_per_batch
current_lr = cfg.optimization.step_size
if cfg.optimization.model_artifact_dir == "auto":
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
artifact_path = f"checkpoints/run_{timestamp}"
toml.load()의 반환 결과는 다음과 같은 중첩 딕셔너리 구조입니다:
{
'preprocessing': {
'token_count': 5589,
'max_seq_len': 10,
'eval_ratio': 0.3,
'raw_data_dir': 'dataset/',
'tensor_cache_dir': 'cached_tensors/'
},
'architecture': {
'vector_dim': 256,
'transformer_layers': 5,
'attention_heads': 3
},
'optimization': {
'max_iterations': 10,
'samples_per_batch': 32,
'step_size': 0.001,
'model_artifact_dir': 'auto'
}
}
이러한 딕셔너리 구조는 W&B나 MLflow 같은 MLOps 도구에 설정값을 그대로 전달하기에도 적합합니다.
활용 전략
TOML 기반 설정 관리는 특히 실험을 반복적으로 수행하는 상황에서 강점을 발휘합니다. 동일한 모델을 다른 하이퍼파라미터로 여러 번 학습할 때, 명령줄 인자를 수정하는 대신 설정 파일만 교체하면 됩니다. 기존 코드베이스에도 최소한의 변경으로 도입할 수 있어, 별도의 복잡한 인프라 없이 실험 관리 효율을 높일 수 있습니다.