MLflow Projects

MLflow Projects

MLflow Projects는 재현 가능한 데이터 사이언스 코드를 패키징·공유하기 위한 표준 포맷을 제공해요. 간단한 규약에 기반해, 서로 다른 환경·플랫폼에서의 원활한 협업과 자동화된 실행을 가능하게 해요.

출처: MLflow Projects

프로젝트 실행

어느 Git 저장소나 로컬 디렉토리든 MLflow Project로 실행할 수 있어요.

# Run a project from GitHub
mlflow run https://github.com/mlflow/mlflow-example.git -P alpha=0.5
# Run a local project
mlflow run . -P data_file=data.csv -P regularization=0.1
# Run with specific entry point
mlflow run . -e validate -P data_file=data.csv

프로그래밍 방식으로도 실행할 수 있어요.

import mlflow
# Execute remote project
result = mlflow.run(
    "https://github.com/mlflow/mlflow-example.git",
    parameters={"alpha": 0.5, "l1_ratio": 0.01},
    experiment_name="elasticnet_experiment",
)
# Execute local project
result = mlflow.run(".", entry_point="train", parameters={"epochs": 100}, synchronous=True)

:::tip 프로젝트 구조 MLproject 파일이 있거나 .py/.sh 파일을 담고 있는 어떠한 디렉토리든 MLflow Project로 실행할 수 있어요. 복잡한 설정이 필요 없어요! :::

프로젝트의 세 가지 요소

모든 MLflow Project는 세 가지 핵심 요소로 구성돼요.

1. 이름(Project Name): 보통 MLproject 파일에 정의하는, 사람이 읽을 수 있는 프로젝트 식별자.
2. 엔트리 포인트(Entry Points): 프로젝트 안에서 실행할 수 있는 명령. 엔트리 포인트는 파라미터(타입·기본값 있는 입력), 명령(엔트리 포인트가 실행될 때 수행되는 것), 환경(실행 컨텍스트·의존성)을 정의해요.
3. 환경(Environment): 프로젝트 실행에 필요한 모든 의존성을 담은 소프트웨어 환경. MLflow는 여러 환경 타입을 지원해요.

기본 규약 (MLproject 파일 없음)

MLproject 파일이 없는 프로젝트는 이런 규약을 사용해요:

my-project/
├── train.py          # Executable entry point
├── validate.sh       # Shell script entry point
├── conda.yaml        # Optional: Conda environment
├── python_env.yaml   # Optional: Python environment
└── data/             # Project data and assets

기본 동작:

• 이름: 디렉토리 이름
• 엔트리 포인트: 모든 .py 또는 .sh 파일
• 환경: conda.yaml의 Conda 환경, 또는 파이썬 전용 환경
• 파라미터: --key value 형태로 커맨드라인으로 전달

MLproject 파일

더 세밀한 제어를 위해 MLproject 파일을 만들 수 있어요.

name: My ML Project
# Environment specification (choose one)
python_env: python_env.yaml
# conda_env: conda.yaml
# docker_env:
#   image: python:3.9
entry_points:
  main:
    parameters:
      data_file: path
      regularization: {type: float, default: 0.1}
      max_epochs: {type: int, default: 100}
    command: "python train.py --reg {regularization} --epochs {max_epochs} {data_file}"
  validate:
    parameters:
      model_path: path
      test_data: path
    command: "python validate.py {model_path} {test_data}"
  hyperparameter_search:
    parameters:
      search_space: uri
      n_trials: {type: int, default: 50}
    command: "python hyperparam_search.py --trials {n_trials} --config {search_space}"

파라미터 타입

MLflow는 자동 검증·변환과 함께 네 가지 파라미터 타입을 지원해요.

:::note 파라미터 해석 path 파라미터는 실행 전에 원격 파일(S3, GCS 등)을 로컬 스토리지로 자동 다운로드해요. 원격 스토리지에서 직접 읽을 수 있는 애플리케이션에는 uri를 사용해요. :::

환경 지정

순수 파이썬 의존성에는 python_env.yaml 파일을 만들어요.

# python_env.yaml
python: "3.9.16"
# Optional: build dependencies
build_dependencies:
  - pip
  - setuptools
  - wheel==0.37.1
# Runtime dependencies
dependencies:
  - mlflow>=2.0.0
  - scikit-learn==1.2.0
  - pandas>=1.5.0
  - numpy>=1.21.0

# MLproject
name: Python Project
python_env: python_env.yaml
entry_points:
  main:
    command: "python train.py"

네이티브 라이브러리나 복잡한 의존성이 필요하면 conda.yaml을 사용해요.

# conda.yaml
name: ml-project
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.9
  - cudnn=8.2.1  # CUDA libraries
  - scikit-learn
  - pip
  - pip:
      - mlflow>=2.0.0
      - tensorflow==2.10.0

최대 재현성과 복잡한 시스템 의존성을 위해 Docker를 사용할 수 있어요.

# Dockerfile
FROM python:3.9-slim
RUN apt-get update && apt-get install -y \
    build-essential \
    git \
    && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install -r requirements.txt
WORKDIR /mlflow/projects/code

# MLproject
name: Containerized Project
docker_env:
  image: my-ml-image:latest
  volumes: ["/host/data:/container/data"]
  environment:
    - ["CUDA_VISIBLE_DEVICES", "0,1"]
    - "AWS_PROFILE"  # Copy from host
entry_points:
  train:
    command: "python distributed_training.py"

환경 매니저 선택

어떤 환경 매니저를 쓸지 제어할 수 있어요.

# Force virtualenv (ignores conda.yaml)
mlflow run . --env-manager virtualenv
# Use local environment (no isolation)
mlflow run . --env-manager local
# Use conda (default if conda.yaml present)
mlflow run . --env-manager conda

원격 백엔드 실행

Databricks 클러스터나 Kubernetes에서 실행할 수도 있어요.

# Run on Databricks cluster
mlflow run . --backend databricks --backend-config cluster-config.json

// cluster-config.json
{
  "cluster_spec": {
    "new_cluster": {
      "node_type_id": "i3.xlarge",
      "num_workers": 2,
      "spark_version": "11.3.x-scala2.12"
    }
  },
  "run_name": "distributed-training"
}

# Run on Kubernetes
mlflow run . --backend kubernetes --backend-config k8s-config.json

// k8s-config.json
{
  "kube-context": "my-cluster",
  "repository-uri": "gcr.io/my-project/ml-training",
  "kube-job-template-path": "k8s-job-template.yaml"
}

멀티 스텝 ML 파이프라인

여러 프로젝트를 조합해 정교한 ML 워크플로를 만들 수 있어요. 전처리 → 피처 엔지니어링 → 병렬 모델 학습 → 최고 모델 배포 단계로 이어지는 파이프라인을 mlflow.run()으로 연결할 수 있어요. 각 단계의 출력(run_id)을 다음 단계의 입력으로 넘기고, synchronous=False로 병렬 실행한 뒤 wait()로 완료를 기다렸다 최고 성능 모델을 선택해 배포하는 식이에요.

정리

MLflow Projects는 코드·환경·파라미터를 표준 포맷으로 패키징해 재현성 있는 ML 워크플로를 만들어요. mlflow run 하나로 로컬부터 Databricks·Kubernetes까지 다양한 백엔드에서 실행할 수 있죠. 개발 팁으로는 순수 파이썬엔 virtualenv, 시스템 라이브러리가 필요하면 conda, 복잡한 의존성·프로덕션 배포엔 Docker를 쓰고, 프로덕션 환경에선 정확한 버전을 고정하는 걸 권장해요.

더 알아보기

• MLflow Models — 모델 패키징 포맷
• MLflow Model Registry — 모델 수명주기 관리
• MLflow Tracking — run·실험 추적