MLflow Projects — 폴더 구조부터 실행까지 한 번에 이해하기

1. 기본 폴더 구조

MLflow Projects를 제대로 쓰기 위해서는,
코드 / 환경 / 실행 설정 / 결과 로그가 분리되어야 합니다.
아래는 가장 실용적인 구조 👇

project_root/                     ← 루트 디렉토리
│
├── mlruns/                       ← MLflow Tracking 로그 저장소
│   └── 0/
│
├── ml-project/                   ← 실제 프로젝트 실행 폴더
│   ├── MLproject                 ← 실행 정의 파일 (프로젝트 매니페스트)
│   ├── train.py                  ← 실행될 Python 스크립트
│   ├── requirements.txt          ← 의존성 패키지 목록
│   └── data.csv                  ← (예시) 입력 데이터
│
└── run_project.py                ← MLflow 프로젝트를 실행시키는 메인 스크립트

 

 

2. 각 구성 요소의 역할

파일 / 폴더	역할
mlruns/	모든 실험 결과(log, metrics, artifacts)가 저장되는 Tracking 디렉토리
ml-project/	하나의 MLflow Project 단위 (코드, 환경, 실행 정보 포함)
MLproject	“이 프로젝트를 어떻게 실행할지”를 정의한 설정 파일
train.py	실제 학습 코드 (MLflow Tracking API 포함 가능)
requirements.txt	실행 시 필요한 Python 패키지 명시
run_project.py	Python 코드 내에서 프로젝트 실행 (mlflow.projects.run)

 

 

3. MLproject 파일 예시

ml-project/MLproject

name: iris_classification_project

python_env: requirements.txt

entry_points:
  main:
    parameters:
      test_size: {type: float, default: 0.2}
      random_state: {type: int, default: 42}
    command: "python train.py --test_size {test_size} --random_state {random_state}"

해석

• python_env: 이 프로젝트가 의존하는 패키지를 requirements.txt로부터 설치
• entry_points: 실행할 명령 정의 (python train.py ...)
• parameters: 실행 시 외부에서 넘길 수 있는 변수 설정

 

4. train.py (모델 학습 코드)

ml-project/train.py

import mlflow
import mlflow.sklearn
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
import argparse

# 파라미터 받기
parser = argparse.ArgumentParser()
parser.add_argument("--test_size", type=float, default=0.2)
parser.add_argument("--random_state", type=int, default=42)
args = parser.parse_args()

# 데이터 로드
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=args.test_size, random_state=args.random_state
)

# MLflow Tracking 시작
with mlflow.start_run():
    model = LogisticRegression(max_iter=200)
    model.fit(X_train, y_train)

    # 로그 기록
    acc = model.score(X_test, y_test)
    mlflow.log_metric("accuracy", acc)
    mlflow.sklearn.log_model(model, "model")

    print(f"✅ 모델 정확도: {acc:.4f}")

 

 

5. requirements.txt

 

ml-project/requirements.txt

mlflow==2.20.2
scikit-learn==1.6.1
pandas==2.2.3

 

6. 프로젝트 실행 (Python 방식)

이제 터미널에서 직접 mlflow run .을 칠 필요 없이,
Python 코드 내부에서 프로젝트를 실행할 수 있습니다 👇

 

run_project.py

import mlflow.projects

# 루트 기준 경로 지정
mlflow.projects.run(
    uri="ml-project",                  # MLproject가 위치한 폴더
    parameters={
        "test_size": 0.3,
        "random_state": 123
    },
    env_manager="local"                # 로컬 환경에서 실행
)

이 스크립트를 실행하면 👇

1️⃣ ml-project/MLproject 파일이 읽히고
2️⃣ requirements.txt 환경 세팅이 자동으로 이루어지며
3️⃣ train.py가 실행되고
4️⃣ 결과가 mlruns/ 폴더에 저장됩니다 ✅

 

 

7. 실행 결과 확인

mlruns/ 폴더 안에는 다음과 같은 구조가 생깁니다 👇

mlruns/
└── 0/
    └── <run_id>/
        ├── metrics/
        ├── params/
        ├── artifacts/
        │   └── model/
        └── MLmodel

이 폴더는 Tracking 서버가 없어도 자동 생성되며,
MLflow UI를 띄우면 쉽게 시각화할 수 있습니다 👇

mlflow ui

→ 브라우저에서 http://localhost:5000 접속

 

 

정리하면

 

MLflow Projects는 루트 폴더 하위에 독립된 실행 폴더(ml-project/)를 두고,
mlflow.projects.run()으로 환경 통일 + 실행 + Tracking을 한 번에 수행할 수 있는
완전한 실험 자동화 구조다.