MLflow 2026: 10,000+ 실험을 추적하는 오픈소스 ML 라이프사이클 플랫폼 — 설정 가이드

# 하나의 다이어그램으로 보는 완전한 MLflow 아키텍처:
# 1. Tracking Server (REST API + UI)
#    ├── Backend Store: PostgreSQL / MySQL / SQLite
#    └── Artifact Store: S3 / GCS / Azure / Local
#
# 2. Tracking Client (Python/R/Java/REST)
#    ├── log_param(), log_metric(), log_artifact()
#    └── set_tags(), register_model()
#
# 3. Model Registry
#    ├── Model Versions (v1, v2, v3...)
#    └── Stage Transitions (None → Staging → Production)
#
# 4. Model Serving
#    └── REST endpoint: /invocations

# MLflow 설치
pip install mlflow==2.22.0

# 로컬 파일 저장소로 추적 서버 시작
mkdir -p ~/mlflow-tracking
mlflow server \
  --backend-store-uri sqlite:///~/mlflow-tracking/mlflow.db \
  --default-artifact-root ~/mlflow-tracking/artifacts \
  --host 0.0.0.0 \
  --port 5000

# 별도의 터미널에서 첫 번째 추적 실험 실행
python -c "
import mlflow

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('quick-start')

with mlflow.start_run():
    mlflow.log_param('learning_rate', 0.01)
    mlflow.log_param('epochs', 10)
    mlflow.log_metric('accuracy', 0.94)
    mlflow.log_metric('f1_score', 0.93)
    print(f'Run ID: {mlflow.active_run().info.run_id}')
"

# 데이터베이스 및 클라우드 지원 설치
pip install mlflow[extras]==2.22.0 psycopg2-binary boto3

# PostgreSQL 및 S3로 추적 서버 시작
export MLFLOW_S3_ENDPOINT_URL=https://s3.amazonaws.com
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

mlflow server \
  --backend-store-uri postgresql://mlflow:password@postgres:5432/mlflowdb \
  --default-artifact-root s3://your-bucket/mlflow-artifacts \
  --host 0.0.0.0 \
  --port 5000

# docker-compose.yml — 완전한 MLflow 스택
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: mlflow
      POSTGRES_PASSWORD: mlflow_password
      POSTGRES_DB: mlflowdb
    volumes:
      - pgdata:/var/lib/postgresql/data

  mlflow:
    image: python:3.11-slim
    command: >
      bash -c "pip install mlflow==2.22.0 psycopg2-binary boto3 &&
               mlflow server
               --backend-store-uri postgresql://mlflow:mlflow_password@postgres:5432/mlflowdb
               --default-artifact-root s3://my-bucket/mlflow
               --host 0.0.0.0 --port 5000"
    ports:
      - "5000:5000"
    depends_on:
      - postgres

volumes:
  pgdata:

# 전체 스택 시작
docker-compose up -d

# 추적 서버가 실행 중인지 확인
curl http://localhost:5000/api/2.0/mlflow/experiments/list

# Droplet을 생성하고 MLflow 설치
ssh root@your-droplet-ip << 'EOF'
apt update && apt install -y python3-pip
pip install mlflow[extras]==2.22.0 psycopg2-binary

# MLflow용 systemd 서비스 생성
cat > /etc/systemd/system/mlflow.service << 'SERVICEDEF'
[Unit]
Description=MLflow Tracking Server
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/mlflow server --backend-store-uri sqlite:///var/lib/mlflow/mlflow.db --default-artifact-root /var/lib/mlflow/artifacts --host 0.0.0.0 --port 5000
Restart=always

[Install]
WantedBy=multi-user.target
SERVICEDEF

systemctl enable mlflow && systemctl start mlflow
EOF

# tracking_example.py — MLflow로 실험 기록
import mlflow
import mlflow.sklearn
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, f1_score
import warnings
warnings.filterwarnings('ignore')

# 추적 서버 및 실험 설정
mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('wine-classification')

def run_experiment(n_estimators, max_depth, min_samples_split):
    with mlflow.start_run():
        # 파라미터 기록
        mlflow.log_param('n_estimators', n_estimators)
        mlflow.log_param('max_depth', max_depth)
        mlflow.log_param('min_samples_split', min_samples_split)
        mlflow.log_param('model_type', 'RandomForest')

        # 데이터 로드 및 훈련
        X, y = load_wine(return_X_y=True)
        X_train, X_test, y_train, y_test = train_test_split(
            X, y, test_size=0.2, random_state=42
        )

        clf = RandomForestClassifier(
            n_estimators=n_estimators,
            max_depth=max_depth,
            min_samples_split=min_samples_split,
            random_state=42
        )
        clf.fit(X_train, y_train)

        # 평가
        predictions = clf.predict(X_test)
        accuracy = accuracy_score(y_test, predictions)
        f1 = f1_score(y_test, predictions, average='weighted')

        # 메트릭 기록
        mlflow.log_metric('accuracy', accuracy)
        mlflow.log_metric('f1_score', f1)

        # 모델 기록
        mlflow.sklearn.log_model(
            clf,
            artifact_path='model',
            registered_model_name='wine-classifier'
        )

        print(f'Run completed: accuracy={accuracy:.4f}, f1={f1:.4f}')

# 여러 실험 실행
if __name__ == '__main__':
    configs = [
        (50, 5, 0.01),
        (100, 10, 0.02),
        (200, 15, 0.05),
        (300, 20, 0.10),
        (500, None, 0.02),
    ]
    for n_est, depth, min_split in configs:
        run_experiment(n_est, depth, min_split)

# 실험 스위프 실행
python tracking_example.py

# autolog_example.py — scikit-learn 자동 로깅
import mlflow
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('autolog-demo')

# autologging 활성화 — 파라미터, 메트릭, 모델, 아티팩트 캡처
mlflow.sklearn.autolog()

X, y = load_wine(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

with mlflow.start_run():
    clf = RandomForestClassifier(n_estimators=100, random_state=42)
    clf.fit(X_train, y_train)
    # 수동 로깅 불필요 — autolog가 모든 것을 캡처

# pytorch_tracking.py — MLflow로 PyTorch 훈련 추적
import mlflow
import torch
import torch.nn as nn
from torch.utils.data import DataLoader
from torchvision import datasets, transforms

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('pytorch-cifar10')

# PyTorch autologging 활성화
mlflow.pytorch.autolog()

def train_model(epochs, lr, batch_size):
    with mlflow.start_run():
        mlflow.log_param('epochs', epochs)
        mlflow.log_param('learning_rate', lr)
        mlflow.log_param('batch_size', batch_size)

        device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
        mlflow.log_param('device', str(device))

        # 데이터 로딩
        transform = transforms.Compose([
            transforms.ToTensor(),
            transforms.Normalize((0.5,), (0.5,))
        ])
        train_ds = datasets.CIFAR10('./data', train=True, download=True, transform=transform)
        train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True)

        # 간단한 CNN 모델
        model = nn.Sequential(
            nn.Conv2d(3, 32, 3, padding=1), nn.ReLU(), nn.MaxPool2d(2),
            nn.Conv2d(32, 64, 3, padding=1), nn.ReLU(), nn.MaxPool2d(2),
            nn.Flatten(), nn.Linear(64 * 8 * 8, 128), nn.ReLU(),
            nn.Linear(128, 10)
        ).to(device)

        optimizer = torch.optim.Adam(model.parameters(), lr=lr)
        criterion = nn.CrossEntropyLoss()

        # 훈련 루프
        model.train()
        for epoch in range(epochs):
            total_loss = 0
            for batch_idx, (data, target) in enumerate(train_loader):
                data, target = data.to(device), target.to(device)
                optimizer.zero_grad()
                output = model(data)
                loss = criterion(output, target)
                loss.backward()
                optimizer.step()
                total_loss += loss.item()

            avg_loss = total_loss / len(train_loader)
            mlflow.log_metric('train_loss', avg_loss, step=epoch)
            print(f'Epoch {epoch}: loss={avg_loss:.4f}')

        # 최종 모델 기록
        mlflow.pytorch.log_model(model, 'model')

if __name__ == '__main__':
    train_model(epochs=5, lr=0.001, batch_size=64)

# registry_example.py — 모델 버전 및 단계 관리
import mlflow
from mlflow.tracking import MlflowClient

client = MlflowClient(tracking_uri='http://localhost:5000')
model_name = 'wine-classifier'

# 새 모델 버전 등록
result = mlflow.register_model(
    model_uri='runs:/<RUN_ID>/model',
    name=model_name
)
print(f'Registered version: {result.version}')

# 버전을 Staging으로 전환
client.transition_model_version_stage(
    name=model_name,
    version=result.version,
    stage='Staging'
)

# 버전 설명 추가
client.update_model_version(
    name=model_name,
    version=result.version,
    description='Wine classifier with 94.4% accuracy, RandomForest 200 estimators'
)

# 버전 태그 설정
client.set_model_version_tag(
    name=model_name,
    version=result.version,
    key='reviewed_by',
    value='ml-lead@company.com'
)

# 모델의 모든 버전 나열
mlflow models list-versions -m wine-classifier

# 예상 출력:
#   Version  Stage       Description
#   1        Production  Initial production model
#   2        Staging     Wine classifier with 94.4% accuracy...
#   3        None        Experimental architecture

# 추론을 위해 특정 모델 버전 로드
import mlflow.pyfunc

model = mlflow.pyfunc.load_model(
    model_uri='models:/wine-classifier/Production'
)

# 또는 버전 번호로 로드
model_v2 = mlflow.pyfunc.load_model(
    model_uri='models:/wine-classifier/2'
)

# MLflow 내장 서버로 로컬 모델 서빙
mlflow models serve \
  -m models:/wine-classifier/Production \
  -p 5001 \
  --env-manager local

# 엔드포인트 테스트
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      [14.23, 1.71, 2.43, 15.6, 127.0, 2.80, 3.06, 0.28, 2.29, 5.64, 1.04, 3.92, 1065.0],
      [12.37, 1.07, 2.10, 18.5, 88.0, 3.52, 3.75, 0.24, 1.95, 4.50, 1.04, 2.77, 660.0]
    ]
  }'

# 응답: {"predictions": [0, 1]}

# 모델용 Docker 이미지 빌드
mlflow models build-docker \
  -m models:/wine-classifier/Production \
  -n wine-classifier-serving:v1.0 \
  --enable-mlserver

# 서빙 컨테이너 실행
docker run -p 5001:8080 wine-classifier-serving:v1.0

# 테스트
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"inputs": [[14.23, 1.71, 2.43, 15.6, 127.0, 2.80, 3.06, 0.28, 2.29, 5.64, 1.04, 3.92, 1065.0]]}'

# deploy_sagemaker.py — AWS SageMaker에 배포
import mlflow.sagemaker

mlflow.sagemaker.deploy(
    app_name='wine-classifier-prod',
    model_uri='models:/wine-classifier/Production',
    execution_role_arn='arn:aws:iam::123456789:role/SageMakerRole',
    instance_type='ml.m5.large',
    region_name='us-east-1'
)

# deploy_azure.py — Azure ML에 배포
from azureml.core import Workspace
import mlflow.azureml

ws = Workspace.from_config()
mlflow.azureml.deploy(
    model_uri='models:/wine-classifier/Production',
    workspace=ws,
    deployment_config={
        'computeType': 'aci',
        'containerResourceRequirements': {'cpu': 1, 'memoryInGB': 2}
    },
    service_name='wine-classifier-aci'
)

# auth_server.py — 기본 인증이 있는 MLflow 서버
from flask import Flask, request, Response
import mlflow.server
import os

app = Flask(__name__)

VALID_CREDENTIALS = {
    'data-scientist': 'secure_password_123',
    'ml-engineer': 'engineer_pass_456'
}

def check_auth():
    auth = request.authorization
    if not auth or not auth.password:
        return False
    return VALID_CREDENTIALS.get(auth.username) == auth.password

@app.before_request
def require_auth():
    if not check_auth():
        return Response('Authentication required', 401,
                       {'WWW-Authenticate': 'Basic realm="MLflow"'})

# 인증 프록시 뒤에 MLflow 마운트
# 또는 nginx 리버스 프록시와 기본 인증 사용

# nginx.conf — 기본 인증이 있는 리버스 프록시
server {
    listen 80;
    server_name mlflow.yourcompany.com;

    location / {
        auth_basic "MLflow Tracking Server";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# cleanup.py — 저장소 관리를 위해 오래된 실행 삭제
from mlflow.tracking import MlflowClient
from datetime import datetime, timedelta

client = MlflowClient('http://localhost:5000')

# 90일 이상된 실행 찾아서 삭제
cutoff = datetime.now() - timedelta(days=90)
experiments = client.search_experiments()

for exp in experiments:
    runs = client.search_runs(
        experiment_ids=[exp.experiment_id],
        filter_string=f"attributes.start_time < {int(cutoff.timestamp() * 1000)}"
    )
    for run in runs:
        if run.info.status == 'FINISHED':
            client.delete_run(run.info.run_id)
            print(f'Deleted run {run.info.run_id} from {exp.name}')

print(f'Cleanup completed. Deleted {len(runs)} old runs.')

# cron을 통해 주간 정리 실행
crontab -e
# 추가: 0 2 * * 0 /usr/bin/python3 /opt/mlflow/cleanup.py >> /var/log/mlflow-cleanup.log 2>&1

# .github/workflows/ml-pipeline.yml
name: ML Training Pipeline
on:
  push:
    branches: [main]

jobs:
  train:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install mlflow==2.22.0 scikit-learn pandas

      - name: Train and register model
        env:
          MLFLOW_TRACKING_URI: ${{ secrets.MLFLOW_TRACKING_URI }}
        run: |
          python train.py --register-model --stage Staging

      - name: Notify team
        run: |
          echo "Model trained and registered. Review at $MLFLOW_TRACKING_URI"