MLflow 모델 기록

2025-05-03

이 문서에서는 학습된 기계 학습 모델 또는 아티팩트(MLflow 모델)를 기록하는 방법을 설명합니다. MLflow는 기계 학습 워크플로를 관리하기 위한 오픈 소스 프레임워크입니다. 이 문서에서는 MLflow가 모델을 패키지하고 실행하는 방식을 사용자 지정하기 위한 다양한 옵션을 살펴봅니다.

필수 조건

MLflow SDK mlflow 패키지

아티팩트 대신 모델을 기록하는 이유는 무엇인가요?

MLflow 모델은 아티팩트 유형입니다. 그러나 모델에는 모델을 만드는 사람과 모델을 사용하려는 사용자 간에 계약 역할을 하는 특정 구조가 있습니다. 이 계약은 아티팩트 자체와 해당 의미 사이를 연결하는 데 도움이 됩니다.

아티팩트 또는 파일 로깅과 MLflow 모델 로깅 간의 차이는 MLflow의 아티팩트 및 모델을 참조하세요.

모델의 파일을 아티팩트로 기록할 수 있지만 모델 로깅은 다음과 같은 이점을 제공합니다.

유추를 위해 모델을 직접 로드하는 데 사용할 mlflow.<flavor>.load_model 수 있으며 함수를 predict 사용할 수 있습니다.
파이프라인 입력은 모델을 직접 사용할 수 있습니다.
점수 매기기 스크립트 또는 환경을 지정하지 않고 모델을 배포할 수 있습니다.
Swagger는 배포된 엔드포인트에서 자동으로 켜집니다. 따라서 Azure Machine Learning 스튜디오의 테스트 기능을 사용하여 모델을 테스트할 수 있습니다.
책임 있는 AI 대시보드를 사용할 수 있습니다. 자세한 내용은 Azure Machine Learning Studio에서 책임 있는 AI 대시보드 사용을 참조하세요.

자동 로깅을 사용하여 모델 기록

MLflow autolog 기능을 사용하여 모델을 자동으로 기록할 수 있습니다. 자동 로깅을 사용하는 경우 MLflow는 프레임워크의 모든 관련 메트릭, 매개 변수, 아티팩트 및 모델을 캡처합니다. 기록되는 데이터는 프레임워크에 따라 달라집니다. 기본적으로 자동 로깅이 켜져 있으면 대부분의 모델이 기록됩니다. 일부 버전에서는 모델을 기록하지 않는 경우도 있습니다. 예를 들어 PySpark 버전은 특정 크기를 초과하는 모델을 로그하지 않습니다.

자동 로깅을 mlflow.autolog 사용하거나 mlflow.<flavor>.autolog 활성화합니다. 다음 코드는 XGBoost를 사용하여 학습된 분류자 모델을 기록하는 데 사용합니다 autolog .

import mlflow
from xgboost import XGBClassifier
from sklearn.metrics import accuracy_score

mlflow.autolog()

model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
model.fit(X_train, y_train, eval_set=[(X_test, y_test)], verbose=False)

y_pred = model.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)

팁

기계 학습 파이프라인(예: scikit-learn 파이프라인)을 사용하는 경우 해당 파이프라인 버전의 기능을 사용하여 autolog 모델을 기록합니다. 모델 로깅은 파이프라인 개체에서 메서드가 fit 호출되면 자동으로 실행됩니다. 모델을 기록하고, 전처리를 포함하고, 파이프라인을 사용하는 Notebook의 경우 MLflow를 사용하여 XGBoost 분류자 학습 및 추적을 참조하세요.

사용자 지정 서명, 환경 또는 샘플을 사용하는 로그 모델

MLflow mlflow.<flavor>.log_model 메서드를 사용하여 모델을 수동으로 기록할 수 있습니다. 이 워크플로는 모델 로깅의 다양한 측면을 제어합니다.

이 방법을 사용하는 경우는 다음과 같습니다.

자동으로 검색된 패키지 또는 환경과 다른 Conda 환경 또는 pip 패키지를 나타내려고 합니다.
입력 예제를 포함하려고 합니다.
필요한 패키지에 특정 아티팩트가 포함되어야 합니다.
메서드가 autolog 서명을 올바르게 유추하지 않습니다. 이 사례는 서명에 특정 셰이프가 있어야 하는 텐서 입력을 사용할 때 발생합니다.
이 메서드가 autolog 모든 요구 사항을 충족하지는 않습니다.

다음 코드는 XGBoost 분류자 모델을 기록합니다.

import mlflow
from xgboost import XGBClassifier
from sklearn.metrics import accuracy_score
from mlflow.models import infer_signature
from mlflow.utils.environment import _mlflow_conda_env

mlflow.autolog(log_models=False)

model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
model.fit(X_train, y_train, eval_set=[(X_test, y_test)], verbose=False)
y_pred = model.predict(X_test)

accuracy = accuracy_score(y_test, y_pred)

# Infer the signature.
signature = infer_signature(X_test, y_test)

# Set up a Conda environment.
custom_env =_mlflow_conda_env(
    additional_conda_deps=None,
    additional_pip_deps=["xgboost==1.5.2"],
    additional_conda_channels=None,
)

# Sample the data.
input_example = X_train.sample(n=1)

# Log the model manually.
mlflow.xgboost.log_model(model, 
                         artifact_path="classifier", 
                         conda_env=custom_env,
                         signature=signature,
                         input_example=input_example)

참고 항목

의 구성을 autolog 사용하는 호출입니다 log_models=False. 이 설정은 자동 MLflow 모델 로깅을 해제합니다. 이 log_model 메서드는 나중에 모델을 수동으로 기록하는 데 사용됩니다.
이 infer_signature 메서드는 입력 및 출력에서 직접 서명을 유추하는 데 사용됩니다.
mlflow.utils.environment._mlflow_conda_env 메서드는 MLflow SDK의 프라이빗 메서드입니다. 이 예제에서는 코드를 간소화합니다. 그러나 이 메서드는 나중에 변경될 수 있으므로 주의해서 사용합니다. 또는 YAML 정의를 Python 사전으로 수동으로 생성할 수 있습니다.

수정된 예측 동작을 사용하는 로그 모델

모델을 사용 mlflow.autolog 하거나 mlflow.<flavor>.log_model 로그하는 경우 모델 버전에 따라 유추가 수행되는 방법이 결정됩니다. 또한 이 맛은 모델이 반환하는 것을 결정합니다. MLflow는 결과 생성 predict 에 대한 특정 동작을 적용하지 않습니다. 일부 시나리오에서는 데이터를 전처리하거나 사후 처리하려고 할 수 있습니다.

이 경우 입력에서 출력으로 직접 이동하는 기계 학습 파이프라인을 구현할 수 있습니다. 이러한 유형의 구현은 때때로 성능을 향상시킬 수 있지만 달성하기 어려울 수 있습니다. 이러한 경우 모델에서 유추를 처리하는 방법을 사용자 지정하는 것이 유용할 수 있습니다. 자세한 내용은 다음 섹션인 사용자 지정 모델 로그를 참조하세요.

사용자 지정 모델 기록

MLflow는 다음 버전을 포함하여 많은 기계 학습 프레임워크를 지원합니다.

CatBoost
FastAI
물 (H₂O)
Keras
LightGBM
MLeap
ONNX
예언자
PyTorch
scikit-learn (파이썬 머신러닝 라이브러리)
spaCy
Spark MLlib
statsmodels (파이썬 통계 모형 라이브러리)
Tensorflow
XGBoost

전체 목록은 Built-In 모델 버전을 참조하세요.

그러나 버전 작동 방식을 변경하거나 MLflow에서 기본적으로 지원하지 않는 모델을 기록해야 할 수 있습니다. 또는 다양한 프레임워크의 여러 요소를 사용하는 모델을 기록해야 할 수도 있습니다. 이러한 경우 사용자 지정 모델 버전을 만들 수 있습니다.

이 문제를 해결하기 위해 MLflow는 Python 모델의 기본 모델 인터페이스인 PyFunc 버전을 제공합니다. 이 맛은 해당 개체가 다음 두 가지 조건을 충족하는 한 모든 개체를 모델로 기록할 수 있습니다.

최소한 predict 메서드를 구현합니다.
Python 객체는 mlflow.pyfunc.PythonModel 클래스를 상속합니다.

팁

scikit-learn API를 구현하는 직렬화 가능한 모델은 scikit-learn으로 모델을 빌드했는지 여부에 관계없이 scikit-learn 버전을 사용하여 모델을 기록할 수 있습니다. 모델을 Pickle 형식으로 유지할 수 있고 개체에 최소한 predict 메서드와 predict_proba 메서드가 있는 경우 MLflow 실행 내에서 모델을 기록하는 데 사용할 mlflow.sklearn.log_model 수 있습니다.

사용자 지정 모델에 대한 변형을 만드는 가장 쉬운 방법은 기존 모델 객체 주위에 래퍼를 만드는 것입니다. MLflow는 모델을 직렬화하고 패키지합니다. Python 개체를 파일(일반적으로 Pickle 형식)로 파일 시스템에 저장할 수 있는 경우 이러한 개체를 직렬화할 수 있습니다. 런타임에 해당 파일에서 개체를 로드할 수 있습니다. 로드하면 저장 시 사용할 수 있는 모든 값, 속성 및 메서드가 복원됩니다.

이 방법을 사용하는 경우는 다음과 같습니다.

모델을 Pickle 형식으로 직렬화할 수 있습니다.
학습 직후 모델의 상태를 유지하려고 합니다.
predict 함수의 작동 방식을 사용자 지정하려고 합니다.

다음 코드는 XGBoost 버전 기본 구현과 다르게 동작하도록 XGBoost로 만든 모델을 래핑합니다. 클래스 대신 확률을 반환합니다.

from mlflow.pyfunc import PythonModel, PythonModelContext

class ModelWrapper(PythonModel):
    def __init__(self, model):
        self._model = model

    def predict(self, context: PythonModelContext, data):
        # The next line uses a prediction function. However, you could also use model.recommend(), model.forecast(), or a similar function instead.
        return self._model.predict_proba(data)

    # You can add extra functions if you need to. Because the model is serialized,
    # all of them are available when you load your model.
    def predict_batch(self, data):
        pass

다음 코드를 사용하여 실행하는 동안 사용자 지정 모델을 기록합니다.

import mlflow
from xgboost import XGBClassifier
from sklearn.metrics import accuracy_score
from mlflow.models import infer_signature

mlflow.xgboost.autolog(log_models=False)

model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
model.fit(X_train, y_train, eval_set=[(X_test, y_test)], verbose=False)
y_probs = model.predict_proba(X_test)

accuracy = accuracy_score(y_test, y_probs.argmax(axis=1))
mlflow.log_metric("accuracy", accuracy)

signature = infer_signature(X_test, y_probs)
mlflow.pyfunc.log_model("classifier", 
                        python_model=ModelWrapper(model),
                        signature=signature)

팁

앞의 코드에서 메서드는 infer_signature 서명을 유추하는 데 사용합니다 y_probs . 대상 열에는 대상 클래스가 포함되지만 모델은 각 클래스에 대해 두 개의 확률을 반환합니다.

경우에 따라 모델을 로드해야 하는 여러 조각으로 구성됩니다. 또한 경우에 따라 모델을 Pickle 파일로 직렬화할 방법이 없습니다. 이러한 경우 클래스를 PythonModel 사용할 수 있습니다. 임의 아티팩트 목록에 대한 지원을 제공합니다. 각 아티팩트는 모델과 함께 패키징됩니다.

다음 경우에 이 기술을 사용합니다.

모델을 Pickle 형식으로 직렬화할 수 없거나 더 나은 직렬화 형식이 있습니다.
모델을 로드하려면 참조해야 할 아티팩트가 하나 이상 포함되어 있습니다.
몇 가지 유추 구성 속성(예: 추천할 항목 수)을 유지하려고 합니다.
모델이 로드되는 방식과 함수의 작동 방식을 predict 사용자 지정하려고 합니다.

다음 코드는 아티팩트를 사용하는 사용자 지정 모델을 기록하는 방법을 보여 줍니다.

encoder_path = 'encoder.pkl'
joblib.dump(encoder, encoder_path)

model_path = 'xgb.model'
model.save_model(model_path)

mlflow.pyfunc.log_model("classifier", 
                        python_model=ModelWrapper(),
                        artifacts={ 
                            'encoder': encoder_path,
                            'model': model_path 
                        },
                        signature=signature)

참고 항목

모델은 Pickle 형식으로 저장되지 않습니다. 대신 코드는 사용하는 프레임워크의 저장 메서드를 사용하여 모델을 저장합니다.
클래스 ModelWrapper 는 모델을 래핑하는 데 사용되지만 모델은 생성자에 인수 ModelWrapper 로 전달되지 않습니다.
메서드에 log_model 사전 매개 변수 artifacts가 있습니다. 해당 키는 아티팩트 이름을 보유합니다. 각 값에는 로컬 파일 시스템의 아티팩트 경로가 포함됩니다.

해당 모델 래퍼는 다음과 같은 코드와 유사합니다.

from mlflow.pyfunc import PythonModel, PythonModelContext

class ModelWrapper(PythonModel):
    def load_context(self, context: PythonModelContext):
        import pickle
        from xgboost import XGBClassifier
        from sklearn.preprocessing import OrdinalEncoder
        
        self._encoder = pickle.loads(context.artifacts["encoder"])
        self._model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
        self._model.load_model(context.artifacts["model"])

    def predict(self, context: PythonModelContext, data):
        return self._model.predict_proba(data)

전체 학습 루틴은 다음 코드와 유사합니다.

import mlflow
from xgboost import XGBClassifier
from sklearn.preprocessing import OrdinalEncoder
from sklearn.metrics import accuracy_score
from mlflow.models import infer_signature

mlflow.xgboost.autolog(log_models=False)

encoder = OrdinalEncoder(handle_unknown='use_encoded_value', unknown_value=np.nan)
X_train['thal'] = encoder.fit_transform(X_train['thal'].to_frame())
X_test['thal'] = encoder.transform(X_test['thal'].to_frame())

model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
model.fit(X_train, y_train, eval_set=[(X_test, y_test)], verbose=False)
y_probs = model.predict_proba(X_test)

accuracy = accuracy_score(y_test, y_probs.argmax(axis=1))
mlflow.log_metric("accuracy", accuracy)

encoder_path = 'encoder.pkl'
joblib.dump(encoder, encoder_path)
model_path = "xgb.model"
model.save_model(model_path)

signature = infer_signature(X, y_probs)
mlflow.pyfunc.log_model("classifier", 
                        python_model=ModelWrapper(),
                        artifacts={ 
                            'encoder': encoder_path,
                            'model': model_path 
                        },
                        signature=signature)

모델에 복잡한 논리가 있거나 유추 시간에 여러 원본 파일을 로드하는 경우가 있습니다. 예를 들어 모델에 대한 Python 라이브러리가 있는 경우 이 상황이 발생합니다. 이 시나리오에서는 라이브러리가 단일 조각으로 작동할 수 있도록 모델과 함께 라이브러리를 패키지해야 합니다.

다음 경우에 이 기술을 사용합니다.

모델을 Pickle 형식으로 직렬화할 수 없거나, 혹은 더 나은 직렬화 형식을 사용할 수 있습니다.
필요한 모든 아티팩트를 저장하는 폴더에 모델 아티팩트를 저장할 수 있습니다.
모델 소스 코드는 복잡하며 여러 Python 파일이 필요합니다. 잠재적으로 라이브러리는 모델을 지원합니다.
모델이 로드되는 방식과 함수 작동 방식을 predict 사용자 지정하려고 합니다.

MLflow는 이러한 유형의 모델을 지원합니다. MLflow를 사용하는 경우 소스 코드에 로더 모듈이 있는 한 모델과 함께 패키지할 임의의 소스 코드를 지정할 수 있습니다. 로더를 구현하는 log_model Python 네임스페이스를 나타내는 매개 변수를 사용하여 loader_module 호출에서 로더 모듈을 지정할 수 있습니다. code_path 매개 변수도 필요합니다. 로더 모듈을 정의하는 원본 파일을 제공합니다. 이 네임스페이스에서, 아티팩트의 경로를 입력받아 적어도 predict 메서드를 가진 객체를 반환하는 _load_pyfunc(data_path: str) 함수를 구현해야 합니다.

model_path = 'xgb.model'
model.save_model(model_path)

mlflow.pyfunc.log_model("classifier", 
                        data_path=model_path,
                        code_path=['src'],
                        loader_module='loader_module'
                        signature=signature)

참고 항목

모델은 Pickle 형식으로 저장되지 않습니다. 대신 코드는 사용하는 프레임워크의 저장 메서드를 사용하여 모델을 저장합니다.
메서드에는 log_model 모델 아티팩트를 data_path 보유하는 폴더를 가리키는 매개 변수가 있습니다. 아티팩트가 폴더 또는 파일에 있을 수 있습니다. 아티팩트가 모델과 함께 패키지됩니다.
메서드에는 log_modelcode_path 소스 코드의 위치를 가리키는 매개 변수가 있습니다. 값은 code_path 경로 또는 단일 파일일 수 있습니다. 소스 코드는 모델과 함께 패키지됩니다.
_load_pyfunc 함수는 loader_module Python 모듈에 저장됩니다.

src 폴더에는 loader_module.py 파일이 포함되어 있습니다. 이 파일은 로더 모듈로 사용되며 다음 줄을 포함합니다.

class MyModel():
    def __init__(self, model):
        self._model = model

    def predict(self, data):
        return self._model.predict_proba(data)

def _load_pyfunc(data_path: str):
    import os

    model = XGBClassifier(use_label_encoder=False, eval_metric='logloss')
    model.load_model(os.path.abspath(data_path))

    return MyModel(model)

참고 항목

MyModel 클래스는 앞에서 설명한 대로 PythonModel에서 상속되지 않습니다. 그러나 함수가 있습니다 predict .
모델 소스 코드는 파일에 있습니다. 모든 소스 코드가 적합합니다. 이 경우 src라는 폴더가 이상적입니다.
함수는 _load_pyfunc 모델 클래스의 인스턴스를 반환합니다.

전체 학습 루틴은 다음 코드와 유사합니다.

import mlflow
from xgboost import XGBClassifier
from sklearn.metrics import accuracy_score
from mlflow.models import infer_signature

mlflow.xgboost.autolog(log_models=False)

model = XGBClassifier(use_label_encoder=False, eval_metric="logloss")
model.fit(X_train, y_train, eval_set=[(X_test, y_test)], verbose=False)
y_probs = model.predict_proba(X_test)

accuracy = accuracy_score(y_test, y_probs.argmax(axis=1))
mlflow.log_metric("accuracy", accuracy)

model_path = "xgb.model"
model.save_model(model_path)

signature = infer_signature(X_test, y_probs)
mlflow.pyfunc.log_model("classifier",
                        data_path=model_path,
                        code_path=["loader_module.py"],
                        loader_module="loader_module",
                        signature=signature)

다음 단계

MLflow 모델 배포 지침

다음을 통해 공유

MLflow 모델 기록

필수 조건

아티팩트 대신 모델을 기록하는 이유는 무엇인가요?

자동 로깅을 사용하여 모델 기록

사용자 지정 서명, 환경 또는 샘플을 사용하는 로그 모델

수정된 예측 동작을 사용하는 로그 모델

사용자 지정 모델 기록

다음 단계

피드백

추가 리소스