히스토리

• GitLab 15.11에서 도입되었습니다.
• GitLab 17.8에서 일반 제공됩니다.

MLflow는 머신 러닝 실험 추적에 널리 쓰이는 오픈 소스 도구입니다. GitLab 모델 실험 추적과 GitLab 모델 레지스트리는 MLflow 클라이언트와 호환됩니다. 설정에 필요한 기존 코드 변경은 최소한입니다.

MLflow 클라이언트 통합 활성화#

사전 요구 사항:

• GitLab과 호환되는 Python 클라이언트:
  • 권장: GitLab MLOps Python 클라이언트.
  • 다른 선택지는 MLflow 클라이언트 버전입니다. MLflow 클라이언트는 GitLab과 호환됩니다.
• Developer, Maintainer 또는 Owner 권한과 api 스코프를 가진 개인, 프로젝트 또는 그룹 액세스 토큰.
• 프로젝트 ID. 프로젝트 ID를 확인하는 방법은 다음과 같습니다.
  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Settings > General을 선택합니다.

로컬 환경에서 MLflow 클라이언트 호환성을 사용하는 방법은 다음과 같습니다.

1. 코드를 실행하는 호스트에 추적 URI와 토큰 환경 변수를 설정합니다. 로컬 환경, CI 파이프라인 또는 원격 호스트가 될 수 있습니다. 예를 들면 다음과 같습니다.

   export MLFLOW_TRACKING_URI="<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow"
   export MLFLOW_TRACKING_TOKEN="<your_access_token>"
   

2. 학습 코드에 mlflow.set_tracking_uri() 호출이 있으면 제거합니다.

모델 레지스트리에서는 오른쪽 위 오버플로 메뉴의 세로 줄임표 (⋮)를 선택해 추적 URI를 복사할 수 있습니다.

모델 실험#

학습 코드를 실행할 때 MLflow 클라이언트로 실험, 실행, 모델, 모델 버전을 생성할 수 있습니다. 파라미터, 메트릭, 메타데이터, 아티팩트를 GitLab에 기록하는 데에도 사용할 수 있습니다.

실험이 기록되면 /<your project>/-/ml/experiments 아래에 나열됩니다.

실행은 등록되며, 실험, 모델 또는 모델 버전을 선택해 살펴볼 수 있습니다.

실험 만들기#

import mlflow

# Create a new experiment
experiment_id = mlflow.create_experiment(name="<your_experiment>")

# Setting the active experiment also creates a new experiment if it doesn't exist.
mlflow.set_experiment(experiment_name="<your_experiment>")

실행 만들기#

import mlflow

# Creating a run requires an experiment ID or an active experiment
mlflow.set_experiment(experiment_name="<your_experiment>")

# Runs can be created with or without a context manager
with mlflow.start_run() as run:
    print(run.info.run_id)
    # Your training code

with mlflow.start_run():
    # Your training code

파라미터 및 메트릭 로깅#

import mlflow

mlflow.set_experiment(experiment_name="<your_experiment>")

with mlflow.start_run():
    # Parameter keys need to be unique in the scope of the run
    mlflow.log_param(key="param_1", value=1)

    # Metrics can be updated throughout the run
    mlflow.log_metric(key="metrics_1", value=1)
    mlflow.log_metric(key="metrics_1", value=2)

아티팩트 로깅#

import mlflow

mlflow.set_experiment(experiment_name="<your_experiment>")

with mlflow.start_run():
    # Plaintext text files can be logged as artifacts using `log_text`
    mlflow.log_text('Hello, World!', artifact_file='hello.txt')

    mlflow.log_artifact(
        local_path='<local/path/to/file.txt>',
        artifact_path='<optional relative path to log the artifact at>'
    )

모델 로깅#

모델은 지원되는 MLflow 모델 플레이버 중 하나로 기록할 수 있습니다. 모델 플레이버로 기록하면 메타데이터가 함께 저장되므로 여러 도구와 환경에서 모델을 관리하고 로드하고 배포하기가 쉬워집니다.

import mlflow
from sklearn.ensemble import RandomForestClassifier

mlflow.set_experiment(experiment_name="<your_experiment>")

with mlflow.start_run():
    # Create and train a simple model
    model = RandomForestClassifier(n_estimators=10, random_state=42)
    model.fit(X_train, y_train)

    # Log the model using MLflow sklearn model flavor
    mlflow.sklearn.log_model(model, artifact_path="")

실행 로드#

히스토리

• GitLab 17.9에서 도입되었습니다.

예측을 수행하는 등의 목적으로 GitLab 모델 레지스트리에서 실행을 로드할 수 있습니다.

import mlflow
import mlflow.pyfunc

run_id = "<your_run_id>"
download_path = "models"  # Local folder to download to

mlflow.pyfunc.load_model(f"runs:/{run_id}/", dst_path=download_path)

sample_input = [[1,0,3,4],[2,0,1,2]]
model.predict(data=sample_input)

실행을 CI/CD job에 연결#

히스토리

• GitLab 16.1에서 도입되었습니다.
• GitLab 17.1에서 베타로 변경되었습니다.

학습 코드가 CI/CD job에서 실행되면 GitLab은 그 정보를 활용해 실행 메타데이터를 보강할 수 있습니다. 실행을 CI/CD job에 연결하는 방법은 다음과 같습니다.

1. 프로젝트 CI 변수에 다음 변수를 포함합니다.

   • MLFLOW_TRACKING_URI: "<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow"
   • MLFLOW_TRACKING_TOKEN: <your_access_token>

2. 실행 실행 컨텍스트 안의 학습 코드에 다음 코드 스니펫을 추가합니다.

   import os
   import mlflow
   
   with mlflow.start_run(run_name=f"Run {index}"):
     # Your training code
   
     # Start of snippet to be included
     if os.getenv('GITLAB_CI'):
       mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID'))
     # End of snippet to be included
   

모델 레지스트리#

MLflow 클라이언트로 모델과 모델 버전을 관리할 수도 있습니다. 모델은 /<your project>/-/ml/models 아래에 등록됩니다.

모델#

모델 만들기#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
description = 'Model description'
model = client.create_registered_model(model_name, description=description)

참고 사항

• create_registered_model의 tags 인수는 무시됩니다.
• name은 프로젝트 안에서 고유해야 합니다.
• name은 기존 실험의 이름일 수 없습니다.

모델 가져오기#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
model = client.get_registered_model(model_name)

모델 업데이트#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
description = 'New description'
client.update_registered_model(model_name, description=description)

모델 삭제#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
client.delete_registered_model(model_name)

모델에 실행 로깅#

모든 모델에는 이름 앞에 [model]이 붙은 같은 이름의 실험이 연결됩니다. 모델에 실행을 기록하려면 올바른 이름을 전달해 그 실험을 사용합니다.

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
exp = client.get_experiment_by_name(f"[model]{model_name}")
run = client.create_run(exp.experiment_id)

모델 버전#

모델 버전 만들기#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
description = 'Model version description'
model_version = client.create_model_version(model_name, source="", description=description)

version 파라미터를 전달하지 않으면 마지막으로 업로드된 버전에서 자동으로 증가합니다. 모델 버전을 만들 때 태그를 전달해 버전을 지정할 수 있습니다. 버전은 SemVer 형식을 따라야 합니다.

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
tags = { "gitlab.version": version }
client.create_model_version(model_name, version, description=description, tags=tags)

참고 사항

• run_id 인수는 무시됩니다. 모든 모델 버전은 실행처럼 동작합니다. 실행에서 모델 버전을 만드는 기능은 아직 지원되지 않습니다.
• source 인수는 무시됩니다. GitLab은 모델 버전 파일을 위한 패키지 위치를 생성합니다.
• run_link 인수는 무시됩니다.
• await_creation_for 인수는 무시됩니다.

모델 업데이트#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
description = 'New description'
client.update_model_version(model_name, version, description=description)

모델 버전 가져오기#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
client.get_model_version(model_name, version)

모델의 최신 버전 가져오기#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
client.get_latest_versions(model_name)

참고 사항

• stages 인수는 무시됩니다.
• 버전은 시맨틱 버전이 높은 순으로 정렬됩니다.

모델 버전 로드#

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version'  # for example: '1.0.0'

# Alternatively search the version
version = mlflow.search_registered_models(filter_string="name='{model_name}'")[0].latest_versions[0].version

model = mlflow.pyfunc.load_model(f"models:/{model_name}/{latest_version}")

# Or load the latest version
model = mlflow.pyfunc.load_model(f"models:/{model_name}/latest")

모델 버전에 메트릭 및 파라미터 로깅#

모든 모델 버전은 실행이기도 하므로 사용자가 파라미터와 메트릭을 기록할 수 있습니다. 실행 ID는 GitLab의 Model version 페이지에서 확인하거나 MLflow 클라이언트로 확인할 수 있습니다.

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
model_version = client.get_model_version(model_name, version)
run_id = model_version.run_id

# Your training code

client.log_metric(run_id, '<metric_name>', '<metric_value>')
client.log_param(run_id, '<param_name>', '<param_value>')
client.log_batch(run_id, metric_list, param_list, tag_list)

파일 하나의 크기 제한이 5 GB이므로 그보다 큰 모델은 분할해야 합니다.

모델 버전에 아티팩트 로깅#

GitLab은 MLflow 클라이언트가 파일을 업로드할 때 사용할 수 있는 패키지를 생성합니다.

from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
model_version = client.get_model_version(model_name, version)
run_id = model_version.run_id

# Your training code

client.log_artifact(run_id, '<local/path/to/file.txt>', artifact_path="")
client.log_figure(run_id, figure, artifact_file="my_plot.png")
client.log_dict(run_id, my_dict, artifact_file="my_dict.json")
client.log_image(run_id, image, artifact_file="image.png")

그러면 아티팩트는 https://<your project>/-/ml/models/<model_id>/versions/<version_id> 아래에서 확인할 수 있습니다.

모델 버전을 CI/CD job에 연결#

실행과 마찬가지로 모델 버전도 CI/CD job에 연결할 수 있습니다.

import os
from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
version = '<your_version>'
model_version = client.get_model_version(model_name, version)
run_id = model_version.run_id

# Your training code

if os.getenv('GITLAB_CI'):
    client.set_tag(model_version.run_id, 'gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID'))

지원되는 MLflow 클라이언트 메서드 및 주의 사항#

GitLab은 MLflow 클라이언트의 다음 메서드를 지원합니다. 자세한 내용은 MLflow 문서를 참고합니다. 아래 메서드에 대응하는 MlflowClient 메서드도 같은 주의 사항으로 지원됩니다.

기타 MLflowClient 메서드:

알려진 문제#

• 지원되는 메서드에 나열되지 않은 MLflow 클라이언트 메서드도 동작할 수 있으나 테스트되지 않았습니다.
• 실험과 실행을 생성하는 동안 ExperimentTags는 화면에 표시되지 않더라도 저장됩니다.