MLflow 로컬 폴더 구조 이해: mlruns 디렉토리의 핵심 구성 정리

MLflow를 로컬 환경에서 실행하면 mlruns/ 폴더가 생성됩니다.
이 폴더는 단순한 로그 저장소가 아니라, 실험 단위(run)와 모델 산출물의 구조화된 저장소입니다.

 

많은 분들이 0, 해시값 폴더, datasets, models, .trash 구조에서 혼란을 느끼는데, 핵심만 이해하면 구조는 단순합니다.

 

MLflow의 로컬 저장 구조는 크게 세 계층으로 나뉩니다.

 

1. Experiment 단위 (mlruns/0)

mlruns/
 └── 0/

• 0은 기본 Experiment ID입니다.
• mlflow.set_experiment()를 사용하지 않으면 여기 저장됩니다.

즉, 이 폴더는 실험 그룹 단위입니다.

 

비유하면:

연구 프로젝트 단위

 

2. Run 단위 (해시값 폴더)

mlruns/0/<run_id>/

해시값처럼 보이는 폴더는 run_id입니다.

 

mlflow.start_run()을 실행할 때마다 하나 생성됩니다.

이 안에는:

• params/ → 하이퍼파라미터
• metrics/ → 성능 지표
• artifacts/ → 모델 파일 및 이미지
• tags/ → 사용자, 실행 정보
• meta.yaml → 실행 메타정보

즉,

한 번의 학습 실행 결과 전체

입니다.

 

3. datasets 폴더

mlruns/0/datasets/<dataset_hash>/

이 폴더는 MLflow 2.x에서 추가된 기능입니다.

• 어떤 데이터셋을 사용했는지
• 데이터 해시
• 스키마 정보

를 저장합니다.

 

중요한 점은:

• 실제로 어떤 run이 사용했는지는
  run_id/inputs/ 폴더를 통해 연결됩니다.

즉, datasets는 “데이터 정의”,
run은 “데이터 사용 기록”입니다.

 

4. models 폴더

mlruns/0/models/m-xxxx/

이 폴더는 Model Registry와 연결된 모델 단위입니다.

• run과는 다른 개념
• 버전 관리되는 모델 객체

즉,

제품화된 모델 단위

입니다.

 

5. .trash 폴더

mlruns/.trash/

삭제된 run이 즉시 제거되지 않고 이곳으로 이동합니다.
완전 삭제 전 임시 보관소 역할입니다.

 

6. 구조를 한 문장으로 정리하면

Experiment
  └── Run
        ├── params / metrics
        ├── artifacts
        └── inputs (dataset 연결)
Registry
  └── models

• Experiment = 실험 그룹
• Run = 실행 단위
• Artifacts = 모델 파일
• Datasets = 데이터 정의
• Models = 버전 관리 모델

mlruns/ 폴더 구조 정리입니다.

 

7. 정리

MLflow 로컬 구조의 본질은:

“Experiment → Run → Artifact” 3단 구조

이고,
datasets와 models는 확장 기능입니다.

 

mlruns/는 Experiment 아래 Run 단위로 실험 결과를 저장하는 구조이며, 모델 파일은 artifacts에, 메타데이터는 run 폴더에, Registry 모델은 models 폴더에 분리되어 관리된다