MLflow 산출물(Artifacts) 폴더 구조 이해하기

 

1. MLflow의 기본 저장 구조

MLflow는 모델을 학습하거나 평가할 때,
그 결과물(모델, 환경, 예시 데이터 등)을 자동으로 mlruns/ 폴더에 기록합니다.

이 폴더는 실험(Experiment) 과 실행(Run) 단위로 계층적으로 구성되어 있습니다.

mlruns/
└── <experiment_id>/                 # 실험 단위
    └── <run_id>/                   # 실행 단위
        ├── MLmodel
        ├── model.pkl
        ├── conda.yaml
        ├── python_env.yaml
        ├── requirements.txt
        ├── input_example.json
        └── serving_input_example.json

 

 

2. 상위 구조: Experiment와 Run의 관계

구분	설명	예시
Experiment	모델 실험의 그룹 단위	예: experiment_id=1
Run	한 번의 학습 혹은 실행 단위	예: run_id=eefcfa883dca49c3abb882a0cb0aa523

즉,

하나의 Experiment 안에는 여러 개의 Run이 존재하며,
각 Run 폴더는 해당 실행의 모든 산출물(Artifacts)을 포함합니다.

 

 

3. Run 폴더 내부 구성 살펴보기

파일명	설명	주요 역할
MLmodel	모델의 메타정보 파일	모델 환경, flavor, 입출력 구조(signature) 정의
model.pkl	실제 학습된 모델 파일	모델 객체(가중치, 구조 포함)
conda.yaml	Conda 환경 설정 파일	학습 시 사용된 Python 및 패키지 버전
python_env.yaml	pip/virtualenv 환경 설정 파일	Conda 없는 환경에서 사용
requirements.txt	의존성 패키지 목록	환경 복원용
input_example.json	입력 데이터 예시	모델 입력 형식 테스트용
serving_input_example.json	서빙용 입력 예시	API 호출 시 테스트용 샘플

 

4. MLflow가 이 구조를 사용하는 이유

 

MLflow는 단순히 모델만 저장하지 않습니다.
“모델 + 실행환경 + 입력 구조 + 예시 데이터” 를 함께 기록하여
실험의 재현성과 안정성을 보장합니다.

목적	설명
재현성 (Reproducibility)	동일한 환경을 다시 구성할 수 있도록 conda.yaml, python_env.yaml 제공
일관성 (Consistency)	모델 구조, 입력 형식, 환경 버전이 일치
안정성 (Serving Safety)	signature 및 입력 예시 파일로 서빙 시 입력 오류 방지
추적성 (Traceability)	Run ID를 통해 언제, 어떤 설정으로 모델이 생성되었는지 기록 확인 가능

 

 

5. MLflow 데이터 저장 흐름

MLflow는 실험 데이터를 두 부분으로 나누어 저장합니다.

실험 실행 (Run)
   ↓
MLflow Tracking Server
   ├── Backend Store (MySQL 등)  →  메타데이터 저장
   └── Artifact Store (./mlruns) →  산출물 저장

• Backend Store (예: MySQL)
  → 파라미터, 메트릭, 태그 등 운영 관리 정보 저장
• Artifact Store (mlruns)
  → 모델 파일, 환경 파일 등 실제 실행 산출물 저장

 

정리하면

 

구분	저장 위치	내용
운영 메타데이터	MySQL 등 Backend Store	실험 이름, 파라미터, 메트릭, 태그
실행 산출물 (Artifacts)	로컬 폴더(mlruns/)	모델 파일, 환경 설정, 입력 예시 등

MLflow의 mlruns/ 폴더는 실험 실행의 모든 산출물(Artifacts) 을 저장하는 공간으로,

각 Run 폴더에는 모델, 환경, 입력 예시 등 재현 가능한 머신러닝 실험의 핵심 결과가 기록된다.