[PYTHON] MLflow 및 WandB 실험 이력 관리와 아티팩트 저장소 구조화 해결 방법 7가지

MLflow vs WandB

 

머신러닝 프로젝트가 실험 단계를 넘어 프로덕션 수준으로 진화할 때, 데이터 사이언티스트들이 직면하는 가장 큰 혼란은 '모델과 관련 부산물(Artifact)의 무질서한 산재'입니다. MLflow나 WandB는 강력한 실험 추적 도구이지만, 초기 설계 단계에서 아티팩트 저장소의 구조를 명확히 정의하지 않으면 수천 개의 실험 결과 속에서 특정 시점의 가중치나 시각화 자료를 찾는 것은 불가능에 가깝습니다. 본 가이드에서는 파이썬 기반의 MLOps 파이프라인을 구축할 때, MLflow와 WandB의 특성에 따른 아티팩트 저장소 최적화 구조화 방안을 제시합니다. 파일 시스템 레이아웃부터 태그 기반의 검색 최적화까지, 실무에서 즉시 도입 가능한 전문적인 해결 전략을 상세히 다룹니다.

---

1. MLflow vs WandB: 아티팩트 관리 철학 및 기술적 차이

두 도구는 실험을 기록한다는 목적은 같으나, 아티팩트를 물리적으로 저장하고 논리적으로 분류하는 방식에서 뚜렷한 차이를 보입니다. 이를 표를 통해 비교해 보았습니다.

비교 항목	MLflow (Open-source 중심)	WandB (SaaS 및 클라우드 중심)	구조화 해결 핵심 포인트
저장소 위치	로컬, S3, Azure Blob, GCS (사용자 설정)	WandB Cloud 또는 온프레미스 서버	경로 규칙 및 아티팩트 버전 관리
데이터 단위	Run (실험 단위) 중심 파일 적재	Artifact (독립 엔티티) 중심 객체 관리	계층적 네이밍 컨벤션 수립
버전 관리	Model Registry를 통한 수동 등록	자동 Aliasing 및 리니지 추적	Semantic Versioning 적용
접근 방식	URI 기반 직접 경로 접근	API 기반 고유 식별자(ID) 접근	중앙 집중식 메타데이터 동기화

---

2. 아티팩트 저장소 구조화를 위한 7가지 실무 Python Examples

실제 대규모 프로젝트에서 모델 가중치, 전처리 객체, 분석 리포트를 효율적으로 관리하기 위한 파이썬 구현 코드입니다.

Example 1: MLflow 계층적 디렉토리 구조 자동 생성

실험 이름과 타임스탬프를 조합하여 물리적 저장소(S3 등) 내에서 가시성을 확보하는 방법입니다.

import mlflow
import datetime

def start_structured_run(experiment_name, run_name):
    mlflow.set_experiment(experiment_name)
    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    # 물리적 아티팩트 경로에 날짜와 실행 명칭을 포함하여 가독성 증대
    with mlflow.start_run(run_name=f"{run_name}_{timestamp}") as run:
        mlflow.log_param("env", "production")
        # 저장 시 하위 디렉토리(models, plots, logs)를 명시적으로 구분
        mlflow.log_artifact("local_model.pth", "models/weights")
        mlflow.log_artifact("confusion_matrix.png", "analysis/plots")
    return run.info.run_id

# 적용 예시
start_structured_run("Demand_Forecasting", "LGBM_Baseline")

Example 2: WandB Artifact 리니지(계층 구조) 정의 및 업로드

데이터셋, 전처리, 학습 모델 간의 연결 고리를 유지하며 저장소를 구조화하는 방식입니다.

import wandb

def save_data_to_wandb(file_path, artifact_name, project_type="dataset"):
    run = wandb.init(project="MLOps_Structure", job_type=project_type)
    # 아티팩트 타입별(raw_data, processed, model)로 저장소 영역 분리
    artifact = wandb.Artifact(name=artifact_name, type=project_type)
    artifact.add_file(file_path)
    run.log_artifact(artifact)
    run.finish()

# 데이터셋 버전과 모델 버전을 논리적으로 연결
save_data_to_wandb("train.csv", "census_income_v1", project_type="raw_data")

Example 3: 모델 가중치와 메타데이터의 원자적 저장 (Atomic Logging)

모델 파일뿐만 아니라 해당 모델의 환경 설정(Config) 파일을 항상 같은 폴더에 묶어 구조화하는 해결 방법입니다.

import json
import os

def log_model_bundle(model, config, save_dir="bundle"):
    os.makedirs(save_dir, exist_ok=True)
    # 모델 저장
    model_path = os.path.join(save_dir, "model.h5")
    model.save(model_path)
    # 환경 설정 저장
    with open(os.path.join(save_dir, "config.json"), "w") as f:
        json.dump(config, f)
    
    # MLflow에 폴더 전체를 하나의 아티팩트 단위로 전송
    mlflow.log_artifacts(save_dir, artifact_path="model_output")

Example 4: 다중 가용 영역을 고려한 MLflow Artifact URI 동적 할당

클라우드 환경에서 리전별 혹은 프로젝트별로 저장 위치(S3 bucket)를 다르게 구성할 때 유용합니다.

def get_artifact_location(project_code):
    # 프로젝트 코드에 따라 저장소 버킷 주소를 분기 처리
    storage_map = {
        "FIN": "s3://finance-ml-artifacts/models",
        "MKT": "s3://marketing-ml-artifacts/models"
    }
    return storage_map.get(project_code, "s3://default-ml-artifacts/general")

# 실험 생성 시 전용 저장소 설정
# mlflow.create_experiment("Project_A", artifact_location=get_artifact_location("FIN"))

Example 5: WandB를 활용한 대용량 체크포인트 파일 필터링 저장

모든 에포크의 파일을 저장하면 저장소 비용이 폭증하므로, 최고 성능의 아티팩트만 선별하여 구조화합니다.

import wandb

def log_best_checkpoint(val_acc, best_acc, model_path):
    if val_acc > best_acc:
        # 가치가 있는 아티팩트만 'best_model' 태그를 붙여 저장소에 관리
        run = wandb.init(project="Model_Optimization")
        artifact = wandb.Artifact("classifier", type="model", 
                                 description="Highest accuracy weight")
        artifact.add_file(model_path)
        run.log_artifact(artifact, aliases=["best", "latest"])
        return val_acc
    return best_acc

Example 6: 아티팩트 검색 효율을 위한 태그 기반 메타데이터 관리

물리적 경로 구조 외에 논리적 인덱싱을 추가하여 검색 속도를 높이는 해결 방법입니다.

from mlflow.tracking import MlflowClient

def add_search_tags(run_id, model_type, dataset_version):
    client = MlflowClient()
    # 저장소 구조와 별개로 메타데이터 태그를 심어 나중에 쿼리 가능하게 함
    client.set_tag(run_id, "model_architecture", model_type)
    client.set_tag(run_id, "data_ref", dataset_version)
    client.set_tag(run_id, "stage", "staging")

# 이후 검색 시: mlflow.search_runs(filter_string="tags.stage = 'staging'")

Example 7: 로컬 캐시와 리모트 아티팩트 저장소 동기화 (Hybrid)

네트워크 불안정 시에도 실험이 중단되지 않도록 로컬에 먼저 구조화하여 저장한 후 배치로 전송하는 로직입니다.

import shutil

def sync_artifacts_to_cloud(local_folder, remote_artifact_path):
    try:
        # 로컬의 구조화된 폴더를 통째로 업로드
        mlflow.log_artifacts(local_folder, artifact_path=remote_artifact_path)
        print("Cloud Sync Complete.")
        # 전송 성공 후 로컬 정리 (Disk 용량 관리)
        shutil.rmtree(local_folder)
    except Exception as e:
        print(f"Sync failed, data remains in {local_folder}: {e}")

---

3. 아티팩트 저장소의 모범 사례(Best Practices) 전략

단순히 툴을 사용하는 것을 넘어, 팀 단위의 협업을 위해 반드시 지켜야 할 구조화 규칙입니다.

• 네이밍 컨벤션의 통일: `project/sub_module/YYYYMMDD/version` 형태의 규칙을 수립하십시오.
• 중복 저장 방지: 동일한 데이터셋은 매번 저장하지 않고, WandB의 Artifact Reference 기능을 활용해 포인터만 저장하십시오.
• 자동 삭제 정책(TTL): 개발용 실험 아티팩트는 30일 후 자동 삭제되도록 S3 수명 주기 정책과 연동하십시오.
• 보안 및 권한 제어: 민감 데이터가 포함된 아티팩트는 IAM 역할을 통해 접근을 제한하고, 기록(Log)에 포함되지 않도록 마스킹 처리하십시오.

---

4. 결론 및 MLOps 확장을 위한 제언

MLflow와 WandB는 데이터 과학자의 실험 일기장과 같습니다. 하지만 일기장이 가득 찼을 때 원하는 내용을 찾지 못한다면 그 기록은 가치를 잃습니다. 오늘 소개한 7가지 구조화 전략을 통해 물리적 저장소의 계층을 설계하고, 논리적 메타데이터를 결합한다면 프로젝트 규모가 커지더라도 흔들림 없는 관리 체계를 유지할 수 있습니다.

나아가 아티팩트 저장소의 구조화를 CI/CD 파이프라인과 결합하면, 성능이 검증된 아티팩트가 자동으로 배포 단계로 넘어가는 자동화된 MLOps 환경을 구축할 수 있습니다.

---

내용 출처:

• MLflow Documentation: Artifact Stores Strategy Guide
• WandB Official Docs: Organizing Artifacts and Lineage
• Engineering MLOps: Managing Machine Learning Lifecycles at Scale
• NVIDIA Blog: Best Practices for Tracking Deep Learning Experiments