MLflow Models

MLflow Models

MLflow Model은 머신러닝 모델을 패키징하는 표준 포맷이에요. REST API를 통한 실시간 서빙, Apache Spark에서의 배치 추론처럼 다양한 다운스트림 도구에서 쓸 수 있죠. 이 포맷은 모델을 서로 다른 도구가 이해할 수 있는 여러 "플레이버(flavor)"로 저장하는 규약을 정의해요.

출처: MLflow Models

구조와 MLmodel 파일

각 MLflow Model은 임의의 파일이 담긴 디렉토리에, 디렉토리 루트에 MLmodel 파일이 함께 있는 구조예요. MLmodel 파일은 모델을 볼 수 있는 여러 플레이버를 정의할 수 있어요.

모델의 model 측면은 직렬화된 객체(예: pickled scikit-learn 모델)이거나, mlflow.models.set_model() API로 정의된 모델 인스턴스를 담은 파이썬 스크립트(또는 Databricks라면 노트북)일 수 있어요.

플레이버 (Flavors)

플레이버는 MLflow Model을 강력하게 만드는 핵심 개념이에요. 배포 도구가 모델을 이해하는 데 쓰는 규약이라, 각 도구를 각 라이브러리와 통합할 필요 없이 어떤 ML 라이브러리의 모델이든 동작하는 도구를 만들 수 있게 해 줘요. MLflow는 모든 내장 배포 도구가 지원하는 몇 가지 "표준" 플레이버를 정의해요. 예를 들어 모델을 파이썬 함수로 실행하는 방법을 설명하는 "Python function" 플레이버가 있어요. 라이브러리는 다른 플레이버도 정의·사용할 수 있어요. 예를 들어 mlflow.sklearn은 모델을 scikit-learn Pipeline 객체로 다시 로드할 수도, 일반 파이썬 함수로 로드할 수도 있게 해 줘요.

모델이 지원하는 모든 플레이버는 MLmodel 파일에 YAML 형식으로 정의돼요. 예를 들어 mlflow.sklearn.save_model(model, "model", input_example=...)을 실행하면 model 디렉토리 아래 이런 파일들이 생겨요:

model/
├── MLmodel
├── model.pkl
├── conda.yaml
├── python_env.yaml
├── requirements.txt
├── input_example.json (optional, only logged when input example is provided and valid during model logging)
├── serving_input_example.json (optional, only logged when input example is provided and valid during model logging)
└── environment_variables.txt (optional, only logged when environment variables are used during model inference)

그리고 그 MLmodel 파일은 두 플레이버를 이렇게 설명해요:

time_created: 2018-05-25T17:28:53.35
flavors:
  sklearn:
    sklearn_version: 0.19.1
    pickled_model: model.pkl
  python_function:
    loader_module: mlflow.sklearn

flavors 필드 외에 MLmodel YAML 형식이 가질 수 있는 필드는 이래요.

  • time_created: 모델이 만들어진 시각(UTC ISO 8601)
  • run_id: tracking으로 저장됐다면 모델을 만든 run의 ID
  • signature: JSON 형식의 model signature
  • input_example: input example 아티팩트 참조
  • databricks_runtime: Databricks 노트북·잡에서 학습됐다면 런타임 버전·타입
  • mlflow_version: 모델을 로깅하는 데 쓰인 MLflow 버전

환경 기록

환경 재현을 위해 모델이 로깅될 때마다 conda.yaml, python_env.yaml, requirements.txt 파일이 자동으로 기록돼요. 이 파일들로 conda나 virtualenv+pip를 사용해 의존성을 재설치할 수 있어요.

모델 입력 예시(input example)를 로깅할 때 제공하면 input_example.json과 serving_input_example.json 두 파일이 추가로 기록돼요.

모델 로깅 시 모델 추론에 사용된 환경 변수 이름을 environment_variables.txt 파일에 기록해요. 이 파일에는 환경 변수의 이름만 담기고 값은 저장되지 않아요. 이 기능을 끄려면 환경 변수 MLFLOW_RECORD_ENV_VARS_IN_MODEL_LOGGING을 false로 설정해요.

모델 시그니처와 입력 예시

모델을 효과적으로 관리·배포하려면 model signature와 input example을 이해하는 게 중요해요.

  • Model Signature: 모델 입력·출력·추가 추론 파라미터의 스키마를 정의해 모델 상호작용을 위한 표준 인터페이스를 제공해요.
  • Model Input Example: 유효한 모델 입력의 구체적 인스턴스를 제공해 모델 요구사항을 이해·테스트하게 해 줘요. 입력 예시를 제공하면 명시적으로 주지 않아도 모델 시그니처가 자동으로 추론·저장돼요.
  • Model Serving Payload Example: 배포된 모델 엔드포인트를 쿼리하기 위한 JSON 페이로드 예시예요. 입력 예시가 있으면 서빙 페이로드 예시가 자동으로 생성되어 serving_input_example.json으로 저장돼요.

저장·로딩

MLflow Model은 여러 방식으로 저장·로딩할 수 있어요. 첫째, 여러 일반 라이브러리와 통합이 있어요. mlflow.sklearn은 scikit-learn 모델용 save_model, log_model, load_model 함수를 제공해요. 둘째, mlflow.models.Model 클래스로 모델을 만들·쓸 수 있어요. 이 클래스는 네 가지 핵심 함수가 있어요.

  • add_flavor: 모델에 플레이버 추가. 각 플레이버는 문자열 이름과 YAML로 직렬화 가능한 키-값 속성 딕셔너리를 가져요.
  • save: 모델을 로컬 디렉토리에 저장
  • log: MLflow Tracking을 이용해 모델을 현재 run의 아티팩트로 로깅
  • load: 로컬 디렉토리나 이전 run의 아티팩트에서 모델 로딩

정리

MLflow Model은 "플레이버"라는 추상화로 어떤 ML 라이브러리의 모델이든 배포 도구가 이해할 수 있게 만들어요. MLmodel 파일이 그 규약의 핵심이고, 환경·시그니처·입력 예시까지 함께 기록해 재현성과 배포 신뢰성을 높여 줘요.

더 알아보기