실험 추적 MLflow 완벽 가이드

머신러닝 실험을 체계적으로 관리하고 추적하는 MLflow의 핵심 개념을 다룹니다. 실험 로깅부터 모델 레지스트리까지, 초급 개발자도 쉽게 따라할 수 있도록 설명합니다.

---

목차

1. MLflow_설치_및_구조
2. 실험과_Run_개념
3. 파라미터_메트릭_아티팩트_로깅
4. 모델_레지스트리
5. 모델_버전_관리
6. UI와_API_활용

---

1. MLflow 설치 및 구조

김개발 씨는 머신러닝 모델을 개발하면서 매번 고민에 빠집니다. "어제 학습시킨 모델이 오늘 것보다 성능이 좋았던 것 같은데, 그때 어떤 파라미터를 썼더라?" 엑셀에 기록해두려고 했지만, 어느새 수십 개의 실험이 쌓이면서 관리가 불가능해졌습니다.

MLflow는 머신러닝 실험의 전 과정을 추적하고 관리하는 오픈소스 플랫폼입니다. 마치 연구 노트를 체계적으로 정리해주는 비서와 같습니다.

파라미터, 메트릭, 모델 파일까지 모든 것을 자동으로 기록하고, 나중에 쉽게 비교할 수 있게 해줍니다.

다음 코드를 살펴봅시다.

# MLflow 설치
# pip install mlflow

import mlflow

# MLflow 버전 확인
print(f"MLflow 버전: {mlflow.__version__}")

# 트래킹 서버 URI 설정 (로컬 또는 원격)
mlflow.set_tracking_uri("http://localhost:5000")

# 현재 트래킹 URI 확인
print(f"트래킹 URI: {mlflow.get_tracking_uri()}")

# MLflow UI 실행 (터미널에서)
# mlflow ui --port 5000

김개발 씨는 입사 6개월 차 머신러닝 엔지니어입니다. 요즘 그는 추천 시스템을 개발하면서 수많은 실험을 진행하고 있습니다.

학습률을 바꿔보기도 하고, 레이어 개수를 조정해보기도 합니다. 문제는 실험이 쌓일수록 어떤 설정이 가장 좋았는지 기억하기 어려워진다는 것입니다.

노트에 적어두려고 했지만 금세 지저분해졌고, 엑셀은 모델 파일까지 관리할 수 없었습니다. 그때 선배 박시니어 씨가 다가왔습니다.

"MLflow 써봤어요? 실험 관리가 훨씬 편해질 거예요." MLflow란 무엇일까요?

쉽게 비유하자면, MLflow는 마치 과학자의 실험 노트를 자동으로 작성해주는 똑똑한 조수와 같습니다. 어떤 재료를 얼마나 사용했는지, 결과가 어땠는지, 그리고 그 결과물까지 모두 체계적으로 정리해줍니다.

MLflow가 없던 시절에는 개발자들이 직접 모든 것을 관리해야 했습니다. 하이퍼파라미터는 텍스트 파일에, 결과는 스프레드시트에, 모델 파일은 날짜별 폴더에 저장하는 식이었습니다.

프로젝트가 커질수록 이런 관리 방식은 한계에 부딪혔습니다. MLflow는 크게 네 가지 핵심 컴포넌트로 구성됩니다.

첫째, Tracking은 실험의 파라미터와 결과를 기록합니다. 둘째, Projects는 코드를 재현 가능한 형태로 패키징합니다.

셋째, Models는 다양한 환경에서 모델을 배포할 수 있게 합니다. 넷째, Model Registry는 모델의 버전을 관리합니다.

위의 코드를 살펴보면, 설치는 pip install mlflow 한 줄이면 충분합니다. 설치 후 mlflow.set_tracking_uri를 통해 실험 결과를 저장할 위치를 지정합니다.

로컬에서 작업할 때는 localhost를 사용하고, 팀과 협업할 때는 원격 서버 주소를 입력하면 됩니다. 터미널에서 mlflow ui 명령어를 실행하면 웹 브라우저에서 대시보드를 확인할 수 있습니다.

이 대시보드에서 모든 실험을 한눈에 비교하고 분석할 수 있습니다. 실제 현업에서는 MLflow 서버를 별도로 운영하는 경우가 많습니다.

여러 팀원이 각자의 실험을 중앙 서버에 기록하면, 누가 어떤 실험을 했는지 쉽게 파악할 수 있기 때문입니다. 김개발 씨는 박시니어 씨의 조언대로 MLflow를 설치해봤습니다.

생각보다 간단해서 놀랐습니다. 이제 본격적으로 실험을 기록하는 방법을 배워볼 차례입니다.

실전 팁

💡 - 로컬에서 테스트할 때는 별도 서버 없이 mlflow ui만 실행해도 충분합니다

• 팀 협업 시에는 PostgreSQL이나 MySQL을 백엔드로 사용하는 것을 권장합니다

---

2. 실험과 Run 개념

MLflow를 설치한 김개발 씨는 이제 본격적으로 실험을 기록해보려 합니다. 그런데 문서를 읽다 보니 Experiment와 Run이라는 용어가 계속 등장합니다.

이 둘의 차이가 무엇일까요?

Experiment는 관련된 실험들을 묶는 큰 폴더와 같습니다. 그리고 Run은 그 폴더 안에 들어가는 개별 실험 기록입니다.

추천 시스템이라는 Experiment 안에 학습률 0.01로 실험, 학습률 0.001로 실험 등 여러 Run이 포함되는 구조입니다.

다음 코드를 살펴봅시다.

import mlflow

# 실험(Experiment) 생성 또는 선택
mlflow.set_experiment("추천시스템-개발")

# Run 시작 - 개별 실험 기록
with mlflow.start_run(run_name="첫번째_실험"):
    # 이 안에서 파라미터, 메트릭 등을 기록
    print("실험이 시작되었습니다!")

    # 현재 Run 정보 확인
    run = mlflow.active_run()
    print(f"Run ID: {run.info.run_id}")
    print(f"Experiment ID: {run.info.experiment_id}")

# with 블록을 나오면 자동으로 Run 종료

김개발 씨는 MLflow 문서를 읽으면서 Experiment와 Run의 관계가 헷갈렸습니다. 박시니어 씨에게 물어보니 아주 쉬운 비유로 설명해주었습니다.

"회사의 프로젝트 관리를 생각해봐요. Experiment는 하나의 프로젝트 폴더예요.

예를 들어 추천시스템-개발이라는 폴더가 있다고 치죠. 그리고 Run은 그 폴더 안에 있는 각각의 시도들이에요." 이 비유를 들으니 이해가 되기 시작했습니다.

추천시스템-개발이라는 Experiment 안에는 학습률 0.01로 시도, 배치사이즈 64로 시도 같은 여러 Run이 들어가는 것입니다. Experiment를 생성하는 방법은 간단합니다.

mlflow.set_experiment() 함수에 이름을 전달하면 됩니다. 이미 존재하는 이름이면 해당 Experiment를 선택하고, 없으면 새로 만듭니다.

Run을 시작할 때는 with mlflow.start_run()을 사용합니다. 파이썬의 컨텍스트 매니저를 활용하기 때문에, with 블록이 끝나면 자동으로 Run이 종료됩니다.

실수로 Run을 닫지 않아서 생기는 문제를 방지할 수 있습니다. run_name 파라미터를 사용하면 각 Run에 의미 있는 이름을 붙일 수 있습니다.

나중에 UI에서 찾아볼 때 첫번째_실험보다는 lr_0.01_batch_64 같은 이름이 훨씬 유용합니다. active_run() 함수를 호출하면 현재 진행 중인 Run의 정보를 얻을 수 있습니다.

Run ID는 각 실험을 고유하게 식별하는 값으로, 나중에 특정 실험 결과를 불러올 때 사용합니다. 주의할 점이 있습니다.

하나의 Run이 진행 중일 때 또 다른 Run을 시작하면 중첩 Run이 됩니다. 이는 의도한 게 아니라면 혼란을 줄 수 있으므로, 항상 이전 Run이 종료되었는지 확인하는 것이 좋습니다.

실무에서는 보통 모델 종류나 데이터셋에 따라 Experiment를 나눕니다. 추천시스템-협업필터링, 추천시스템-콘텐츠기반처럼 세분화하면 나중에 결과를 비교하기 쉽습니다.

김개발 씨는 이제 Experiment와 Run의 개념을 확실히 이해했습니다. 다음으로 배울 것은 Run 안에서 실제로 무엇을 기록할 수 있는지입니다.

실전 팁

💡 - Experiment 이름은 프로젝트명-목적 형태로 짓는 것이 좋습니다

• Run 이름에는 핵심 하이퍼파라미터 값을 포함시키면 나중에 찾기 쉽습니다

---

3. 파라미터 메트릭 아티팩트 로깅

김개발 씨가 드디어 첫 모델 학습을 시작했습니다. 학습률은 0.001, 에폭은 100, 결과 정확도는 0.85가 나왔습니다.

이 정보들을 MLflow에 어떻게 기록할까요? 그리고 학습된 모델 파일은요?

MLflow에서 기록할 수 있는 세 가지 핵심 요소가 있습니다. **파라미터(params)**는 실험의 입력값이고, **메트릭(metrics)**은 결과 수치입니다.

**아티팩트(artifacts)**는 모델 파일이나 그래프 같은 결과물입니다. 이 세 가지만 잘 기록하면 어떤 실험이든 완벽하게 재현할 수 있습니다.

다음 코드를 살펴봅시다.

import mlflow

mlflow.set_experiment("추천시스템-개발")

with mlflow.start_run(run_name="baseline_model"):
    # 파라미터 로깅 - 실험의 입력값
    mlflow.log_param("learning_rate", 0.001)
    mlflow.log_param("epochs", 100)
    mlflow.log_param("batch_size", 32)

    # 메트릭 로깅 - 실험의 결과값
    mlflow.log_metric("accuracy", 0.85)
    mlflow.log_metric("loss", 0.32)

    # 에폭별 메트릭 로깅 (step 활용)
    for epoch in range(5):
        mlflow.log_metric("train_loss", 1.0 - epoch*0.1, step=epoch)

    # 아티팩트 로깅 - 파일 저장
    mlflow.log_artifact("model.pkl")

모델 학습이 끝난 김개발 씨 앞에는 기록해야 할 것들이 잔뜩 쌓여 있습니다. 학습률, 배치 사이즈 같은 설정값부터 정확도, 손실값 같은 결과까지.

예전에는 이걸 어디에 적어둬야 하나 고민했지만, 이제 MLflow가 있습니다. MLflow에서 기록할 수 있는 정보는 크게 세 가지로 나뉩니다.

첫째는 파라미터입니다. 학습률, 에폭 수, 배치 사이즈처럼 실험을 시작하기 전에 정하는 값들입니다.

요리로 치면 레시피에 적힌 재료의 양과 같습니다. 둘째는 메트릭입니다.

정확도, 손실값, F1 점수처럼 실험의 결과로 나오는 수치들입니다. 요리의 맛 평가 점수라고 생각하면 됩니다.

메트릭은 파라미터와 달리 실험 도중에 여러 번 기록할 수 있습니다. 셋째는 아티팩트입니다.

학습된 모델 파일, 혼동 행렬 이미지, 예측 결과 CSV 등 파일 형태로 저장되는 모든 것이 여기에 해당합니다. 요리로 치면 완성된 음식 사진을 찍어두는 것과 같습니다.

코드를 살펴보면, log_param 함수는 키-값 쌍으로 파라미터를 기록합니다. 한 번 기록하면 수정할 수 없으므로, 실험 시작 시점에 모든 설정값을 기록하는 것이 좋습니다.

log_metric 함수도 비슷하게 동작하지만, step 파라미터를 추가로 받을 수 있습니다. 이를 활용하면 에폭별 손실값의 변화를 추적할 수 있습니다.

UI에서는 이 값들이 그래프로 시각화됩니다. log_artifact 함수는 파일 경로를 받아서 해당 파일을 MLflow 저장소에 복사합니다.

로컬 파일뿐만 아니라 폴더 전체를 log_artifacts로 업로드할 수도 있습니다. 실무에서 흔히 하는 실수가 있습니다.

파라미터와 메트릭의 이름을 일관성 없이 짓는 것입니다. 어떤 실험에서는 lr이라고 적고, 다른 실험에서는 learning_rate라고 적으면 나중에 비교가 어려워집니다.

박시니어 씨는 팀 내에서 명명 규칙을 정해두라고 조언했습니다. model.accuracy, train.loss처럼 네임스페이스를 붙이면 메트릭이 많아져도 정리하기 쉽습니다.

김개발 씨는 첫 실험 결과를 성공적으로 기록했습니다. MLflow UI에 접속하니 방금 기록한 모든 정보가 깔끔하게 정리되어 있었습니다.

실전 팁

💡 - 파라미터 이름은 팀 내 규칙을 정해서 일관되게 사용하세요

• 중요한 메트릭은 step과 함께 기록해서 학습 곡선을 시각화하세요

---

4. 모델 레지스트리

수많은 실험 끝에 김개발 씨는 드디어 만족스러운 모델을 만들었습니다. 그런데 박시니어 씨가 물었습니다.

"이 모델을 운영 환경에 배포하려면 어떻게 관리할 거예요?" 실험용 모델과 배포용 모델을 체계적으로 관리할 방법이 필요했습니다.

모델 레지스트리는 모델의 생명주기를 관리하는 중앙 저장소입니다. 마치 소프트웨어의 릴리스 관리처럼, 모델도 버전을 붙이고 스테이지를 지정할 수 있습니다.

Staging에서 테스트하고, Production으로 승격하는 워크플로우를 구축할 수 있습니다.

다음 코드를 살펴봅시다.

import mlflow
from mlflow.tracking import MlflowClient

mlflow.set_experiment("추천시스템-개발")

with mlflow.start_run():
    mlflow.log_param("model_type", "collaborative_filtering")
    mlflow.log_metric("rmse", 0.89)

    # 모델을 레지스트리에 등록
    model_uri = "runs:/{}/model".format(mlflow.active_run().info.run_id)
    mlflow.register_model(model_uri, "추천시스템-모델")

# 클라이언트로 모델 관리
client = MlflowClient()

# 모델 스테이지 변경
client.transition_model_version_stage(
    name="추천시스템-모델",
    version="1",
    stage="Production"
)

김개발 씨의 모델이 좋은 성능을 보이자, 팀에서는 이 모델을 실제 서비스에 적용하기로 결정했습니다. 하지만 문제가 생겼습니다.

실험할 때 만든 모델 파일이 여기저기 흩어져 있었던 것입니다. "어떤 모델이 현재 운영 중인 건지 어떻게 알 수 있죠?" 김개발 씨의 질문에 박시니어 씨가 모델 레지스트리를 소개해주었습니다.

모델 레지스트리는 마치 도서관의 서가 시스템과 같습니다. 책에 고유 번호를 붙이고, 대출 가능 여부를 표시하듯이, 모델에도 버전을 붙이고 현재 상태를 표시하는 것입니다.

MLflow의 모델 레지스트리는 네 가지 스테이지를 제공합니다. None은 등록만 된 상태입니다.

Staging은 테스트 중인 모델입니다. Production은 현재 운영 중인 모델입니다.

Archived는 더 이상 사용하지 않는 모델입니다. 모델을 레지스트리에 등록하려면 mlflow.register_model 함수를 사용합니다.

첫 번째 인자는 모델의 위치를 나타내는 URI이고, 두 번째 인자는 레지스트리에서 사용할 이름입니다. 등록된 모델의 스테이지를 변경하려면 MlflowClient를 사용합니다.

transition_model_version_stage 메서드로 특정 버전의 모델을 원하는 스테이지로 이동시킬 수 있습니다. 실무에서는 이 과정을 자동화하는 경우가 많습니다.

예를 들어, 테스트를 통과한 모델만 자동으로 Staging으로 올리고, 사람이 직접 확인한 후 Production으로 승격하는 파이프라인을 구축합니다. 주의할 점은 Production 스테이지에는 동시에 여러 버전이 있을 수 있다는 것입니다.

이전 버전을 Archived로 옮기지 않으면 혼란이 생길 수 있으므로, 버전 관리 정책을 미리 정해두는 것이 좋습니다. 김개발 씨는 이제 어떤 모델이 운영 중인지 한눈에 파악할 수 있게 되었습니다.

모델 레지스트리 덕분에 배포 과정이 훨씬 체계적으로 바뀌었습니다.

실전 팁

💡 - 모델 이름은 프로젝트-용도 형태로 지정하면 관리하기 좋습니다

• Production 배포 전 반드시 Staging에서 충분히 테스트하세요

---

5. 모델 버전 관리

운영 중인 모델을 개선한 새 버전을 만들었습니다. 그런데 새 버전에서 예상치 못한 문제가 발생하면 어떻게 할까요?

김개발 씨는 이전 버전으로 빠르게 돌아갈 수 있는 방법이 필요했습니다.

MLflow 모델 레지스트리는 같은 이름의 모델에 여러 버전을 등록할 수 있습니다. 각 버전은 고유한 번호를 가지며, 언제든 특정 버전을 불러와 사용할 수 있습니다.

이를 통해 문제 발생 시 빠른 롤백이 가능합니다.

다음 코드를 살펴봅시다.

import mlflow
from mlflow.tracking import MlflowClient

client = MlflowClient()

# 모델의 모든 버전 조회
model_name = "추천시스템-모델"
versions = client.search_model_versions(f"name='{model_name}'")

for v in versions:
    print(f"버전: {v.version}, 스테이지: {v.current_stage}")

# 특정 버전 모델 불러오기
model_version = 2
model = mlflow.pyfunc.load_model(f"models:/{model_name}/{model_version}")

# Production 스테이지 모델 직접 불러오기
prod_model = mlflow.pyfunc.load_model(f"models:/{model_name}/Production")

# 이전 버전으로 롤백
client.transition_model_version_stage(
    name=model_name,
    version="1",  # 이전 버전
    stage="Production"
)

새로 개선한 모델 버전 2를 배포한 지 하루 만에 문제가 발생했습니다. 특정 상황에서 추천 결과가 이상하게 나오는 것이었습니다.

김개발 씨는 당황했지만, 다행히 MLflow의 버전 관리 덕분에 빠르게 대응할 수 있었습니다. 모델 버전 관리는 마치 문서의 버전 관리와 같습니다.

워드 프로세서에서 이전 버전으로 돌아갈 수 있듯이, 모델도 이전 버전으로 되돌릴 수 있습니다. search_model_versions 함수를 사용하면 특정 모델의 모든 버전을 조회할 수 있습니다.

각 버전의 생성 시간, 현재 스테이지, 관련 Run ID 등 다양한 정보를 확인할 수 있습니다. 모델을 불러오는 방법은 여러 가지입니다.

버전 번호로 직접 지정할 수도 있고, 스테이지 이름으로 불러올 수도 있습니다. models:/모델명/Production처럼 스테이지를 지정하면 해당 스테이지의 최신 모델을 가져옵니다.

롤백은 생각보다 간단합니다. 이전 버전의 스테이지를 Production으로 변경하기만 하면 됩니다.

서비스에서 models:/모델명/Production으로 모델을 불러오고 있다면, 코드 변경 없이 자동으로 이전 버전이 사용됩니다. 하지만 주의할 점이 있습니다.

버전 번호는 한 번 붙으면 바꿀 수 없습니다. 또한 삭제한 버전은 복구할 수 없으므로, 중요한 버전은 함부로 삭제하지 않는 것이 좋습니다.

실무에서는 버전에 설명을 붙여두는 것이 좋습니다. client.update_model_version을 사용해서 새 추천 알고리즘 적용 같은 메모를 남겨두면 나중에 어떤 변경이 있었는지 파악하기 쉽습니다.

김개발 씨는 버전 1을 다시 Production으로 올려서 문제를 해결했습니다. 그리고 차분하게 버전 2의 문제점을 분석해서 버전 3을 준비하기로 했습니다.

실전 팁

💡 - 각 버전에는 반드시 변경 내용을 설명하는 메모를 남기세요

• 주요 버전은 별도로 백업해두면 더욱 안전합니다

---

6. UI와 API 활용

파라미터와 메트릭을 로깅하고, 모델을 레지스트리에 등록하는 법까지 배웠습니다. 이제 김개발 씨는 이 모든 정보를 효율적으로 조회하고 비교하는 방법이 궁금해졌습니다.

MLflow는 웹 UI와 Python API 두 가지 방법을 제공합니다.

MLflow UI는 브라우저에서 모든 실험을 시각적으로 탐색할 수 있는 대시보드입니다. 실험 비교, 메트릭 시각화, 아티팩트 다운로드가 가능합니다.

Python API를 활용하면 프로그래밍 방식으로 실험 데이터에 접근하여 자동화된 분석이 가능합니다.

다음 코드를 살펴봅시다.

import mlflow
from mlflow.tracking import MlflowClient

# UI 실행 (터미널에서)
# mlflow ui --host 0.0.0.0 --port 5000

# Python API로 실험 조회
client = MlflowClient()

# 모든 실험 목록 가져오기
experiments = client.search_experiments()
for exp in experiments:
    print(f"실험: {exp.name}")

# 특정 실험의 Run 검색
runs = client.search_runs(
    experiment_ids=["1"],
    filter_string="metrics.accuracy > 0.8",
    order_by=["metrics.accuracy DESC"],
    max_results=5
)

# 결과 출력
for run in runs:
    print(f"Run ID: {run.info.run_id}")
    print(f"정확도: {run.data.metrics['accuracy']}")
    print(f"파라미터: {run.data.params}")

어느덧 김개발 씨의 실험 기록이 100개를 넘어섰습니다. 이제 가장 좋은 성능의 모델을 찾으려면 체계적인 검색이 필요합니다.

MLflow는 이를 위해 두 가지 도구를 제공합니다. 첫째는 웹 UI입니다.

터미널에서 mlflow ui 명령어를 실행하면 브라우저에서 접속할 수 있는 대시보드가 열립니다. 이 대시보드에서는 모든 실험을 테이블 형태로 볼 수 있습니다.

UI의 가장 강력한 기능은 실험 비교입니다. 여러 Run을 선택하고 Compare 버튼을 누르면, 파라미터와 메트릭을 나란히 비교할 수 있습니다.

어떤 설정이 성능 향상에 기여했는지 한눈에 파악할 수 있습니다. 메트릭 시각화도 유용합니다.

에폭별로 기록한 손실값이 어떻게 변화하는지 그래프로 확인할 수 있습니다. 여러 Run의 학습 곡선을 겹쳐서 보면 수렴 속도도 비교할 수 있습니다.

둘째는 Python API입니다. MlflowClient 클래스를 사용하면 코드에서 직접 실험 데이터에 접근할 수 있습니다.

이는 자동화된 분석이나 리포트 생성에 특히 유용합니다. search_runs 함수는 SQL과 비슷한 필터링을 지원합니다.

metrics.accuracy > 0.8처럼 조건을 지정하면 해당하는 Run만 검색됩니다. order_by로 정렬도 가능해서 상위 N개의 모델을 쉽게 찾을 수 있습니다.

실무에서는 UI와 API를 함께 활용하는 경우가 많습니다. 일상적인 확인은 UI로 하고, 정기 리포트 생성이나 최적 모델 자동 선택 같은 작업은 API로 자동화합니다.

박시니어 씨는 매주 금요일에 자동으로 실행되는 스크립트를 보여주었습니다. 이 스크립트는 한 주간의 실험 중 가장 성능이 좋은 모델을 찾아서 팀 슬랙 채널에 알려줍니다.

김개발 씨는 이제 MLflow의 핵심 기능을 모두 익혔습니다. 실험 추적부터 모델 관리까지, 머신러닝 워크플로우가 한층 체계적으로 바뀌었습니다.

처음에는 복잡해 보였지만, 막상 사용해보니 그렇게 어렵지 않았습니다.

실전 팁

💡 - UI는 팀 공유용, API는 자동화용으로 적절히 활용하세요

• search_runs의 filter_string 문법을 익혀두면 복잡한 검색도 쉽게 할 수 있습니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!