학습 실험에 매개변수와 지표 기록

실험(Experiment)은 모델 학습 작업에서 만든 매개변수와 지표를 모은 산출물입니다. 하이퍼파라미터와 학습 중 지표를 기록하여 모델 버전별 시도를 비교하고 어떤 설정이 결과에 영향을 주는지 확인합니다.

생성과 모델 게시

Jupyter Code Workspace는 palantir_models.code_workspaces.ModelOutput을 사용합니다. my-alias는 현재 작업 공간에서 추가한 실제 모델의 별칭으로 바꿉니다.

from palantir_models.code_workspaces import ModelOutput
# `my-alias` is an alias to a model in the current workspace
model_output = ModelOutput("my-alias")
experiment = model_output.create_experiment(name="my-experiment")

Code Repositories에서는 palantir_models.transforms.ModelOutput을 변환의 모델 출력으로 선언하고 변환 함수에 주입된 model_output에서 create_experiment를 호출합니다. 실제 모델 경로를 ModelOutput의 입력으로 지정하고, 데이터 입력은 transforms.api.Input으로 선언합니다. 입출력 이름은 변환 함수의 인자 이름과 맞춥니다. 두 환경 모두 같은 모델에 같은 실험 이름을 다시 사용하면 이름을 자동으로 구분하므로 실행할 때마다 직접 바꿀 필요는 없습니다.

게시할 어댑터는 palantir_models.ModelAdapter의 실제 하위 클래스 인스턴스여야 합니다. 추상 기본 클래스를 직접 만들 수는 없습니다. 사용자 어댑터는 load로 저장 상태를 읽고, save로 모델을 저장하며, api로 입출력을 정의하고 predict로 추론을 수행합니다. 학습 코드가 만든 모델을 이 구현에 연결한 뒤 게시합니다.

다음 함수는 실제 학습이 만든 어댑터, 하이퍼파라미터 사전 및 단계별 지표를 받습니다. step_metrics는 (증가하는 정수 step, 지표 이름과 수치의 사전)을 순서대로 제공해야 합니다. 기록한 실험을 모델 버전과 함께 게시해야 모델 페이지에 표시됩니다.

def publish_training_experiment(model_output, model_adapter, parameters, step_metrics):
    experiment = model_output.create_experiment(name="my-experiment")
    experiment.log_params(parameters)
    for step, metrics in step_metrics:
        experiment.log_metrics(metrics, step=step)
    model_output.publish(model_adapter, experiment=experiment)

게시한 결과는 실험 시각화에서 확인합니다.

단일 지표 기록

log_metric으로 단계 없는 지표와 단계별 지표를 기록할 수 있습니다. 다음 함수는 계산한 손실과 단계, 구현된 어댑터를 받습니다. 명시한 step은 앞서 자동으로 기록한 단계보다 커야 합니다.

def publish_training_result(model_output, adapter, loss: float, step: int):
    experiment = model_output.create_experiment(name="my-experiment")
    experiment.log_param("learning_rate", 1e-4)
    experiment.log_metric("train/loss", loss)
    experiment.log_metric("train/loss", loss, step=step)
    model_output.publish(adapter, experiment=experiment)

learning_rate=1e-4는 예시 설정이므로 실제 학습에 사용한 값으로 기록합니다.

기록 실패의 처리 방식

네트워크 오류나 실험 시리즈 크기 초과 등 기록 과정의 오류를 처리하는 방식을 생성 시 정할 수 있습니다. 이는 사용자가 작성한 모든 학습 오류를 무시하는 설정이 아닙니다.

from palantir_models.experiments import ErrorHandlerType
experiment = model_output.create_experiment(name="my-experiment", error_handler_type=ErrorHandlerType.FAIL)

하이퍼파라미터

log_param과 log_params는 학습 작업의 정적 설정을 키와 값으로 저장합니다. Boolean, date, datetime, float, int와 str을 지원합니다. 같은 키로 다시 기록하면 값을 덮어씁니다. 다음은 학습 설정 예시입니다.

experiment.log_param("learning_rate", 1e-3)
experiment.log_param("model_type", "CNN")
experiment.log_params({
    "batch_size": 12,
    "parallel": True
})

단계별 지표

log_metric과 log_metrics는 수치를 시리즈로 기록합니다. 없는 시리즈는 처음 기록할 때 만들며 step은 엄격하게 증가해야 합니다. step을 생략하면 각 시리즈의 현재 단계에서 1씩 증가합니다. 여러 시리즈에 같은 단계를 기록하려면 step을 명시합니다.

학습 루프에서 실제 계산한 값을 다음과 같이 기록할 수 있습니다.

def record_training_step(experiment, step, train_accuracy, test_accuracy, train_loss):
    experiment.log_metric("test/acc", test_accuracy, step=step)
    experiment.log_metrics({
        "train/acc": train_accuracy,
        "train/loss": train_loss,
    }, step=step)

이미지와 사용자 정의 차트

log_image는 PNG 파일 경로, PNG 바이트 또는 Pillow 이미지 객체를 시리즈에 기록합니다. 다른 이미지 형식은 거부합니다. caption과 step을 지정할 수 있으며 없는 시리즈는 자동 생성합니다.

다음 함수의 pillow_image, image_bytes_arr와 segmentation_path는 실제 이미지 객체, PNG 바이트 및 PNG 경로입니다.

def record_images(experiment, pillow_image, image_bytes_arr, segmentation_path, step):
    experiment.log_image("train/bounding_boxes", pillow_image, step=step)
    experiment.log_image("test/bounding_boxes", image_bytes_arr, step=step)
    experiment.log_image(
        "test/segmentation", segmentation_path,
        caption="Segmentation Image", step=step,
    )

Matplotlib으로 만든 차트도 PNG로 저장한 뒤 기록할 수 있습니다. 아래 함수는 실제 x_data와 y_data 및 쓸 수 있는 PNG 경로를 받습니다.

import matplotlib.pyplot as plt

def record_scatter(experiment, x_data, y_data, png_path):
    figure, axis = plt.subplots()
    axis.scatter(x_data, y_data)
    figure.savefig(png_path)
    plt.close(figure)
    experiment.log_image("scatter", png_path)

대화형 플롯

log_plot에는 plotly.graph_objects.Figure를 전달합니다. 다른 플롯 타입은 거부합니다. 이름별 시리즈를 자동 생성하며 caption과 step을 지정할 수 있습니다. 다음 함수는 실제 학습 단계와 검증 손실 값으로 플롯을 만듭니다.

import plotly.express as px

def record_loss_plot(experiment, epochs, losses, step):
    figure = px.line(x=epochs, y=losses)
    experiment.log_plot(
        "validation/loss", figure,
        caption="Validation Loss over Epochs", step=step,
    )

표

log_table에는 pandas 또는 Polars DataFrame을 전달합니다. 다른 자료형은 거부합니다. 예를 들어 모델별 model_type, score와 rank 열을 가진 실제 비교 표를 experiment.log_table("model_leaderboard", leaderboard)로 저장합니다. 표에는 단계 인자가 없습니다.

MLflow 자동 기록

MLflow 2.0.0 이상에서 experiment.as_mlflow_run()으로 현재 실험을 활성 실행에 연결할 수 있습니다. 이후 MLflow API와 자동 기록 기능이 해당 실험에 씁니다. 아래 함수는 scikit-learn 추정기, 실제 특성 및 정답, 학습한 추정기를 ModelAdapter로 감싸는 adapter_factory를 받습니다.

import mlflow

def train_sklearn_with_experiment(model_output, estimator, features, targets, adapter_factory):
    experiment = model_output.create_experiment(name="my-experiment")
    with experiment.as_mlflow_run():
        mlflow.sklearn.autolog()
        estimator.fit(features, targets)
    model_output.publish(adapter_factory(estimator), experiment=experiment)

Keras 학습에는 콜백을 사용할 수 있습니다. Keras 3와 mlflow.keras.MlflowCallback을 제공하는 MLflow 및 사용할 백엔드를 설치합니다. KERAS_BACKEND는 keras를 가져오기 전에 tensorflow, torch 또는 jax로 설정할 수 있습니다. 아래 데이터는 (샘플 수, 28, 28, 3) 형태이고 label은 각 샘플의 0 또는 1 정답입니다. adapter_factory는 학습한 Keras 모델을 게시할 수 있는 실제 어댑터를 반환해야 합니다.

import keras
import mlflow

def train_keras_with_experiment(model_output, data, label, adapter_factory):
    experiment = model_output.create_experiment(name="my-experiment")
    model = keras.Sequential([
        keras.Input([28, 28, 3]),
        keras.layers.Flatten(),
        keras.layers.Dense(2),
    ])
    model.compile(
        loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True),
        optimizer=keras.optimizers.Adam(0.001),
        metrics=[keras.metrics.SparseCategoricalAccuracy()],
    )
    with experiment.as_mlflow_run():
        model.fit(
            data, label, batch_size=16, epochs=8,
            callbacks=[mlflow.keras.MlflowCallback()],
        )
    model_output.publish(adapter_factory(model), experiment=experiment)

Foundry 실험과 MLflow의 통합은 학습 및 모델 게시 시점의 기록에 사용합니다. 전체 MLflow 기능을 지원하지는 않습니다. PNG가 아닌 자산은 경고 없이 버리고 태그는 무시하며 중첩 실행은 지원하지 않습니다.

한도

한도를 늘려야 하면 Palantir Support에 문의합니다. Python API 참조에 메서드별 인자와 오류 조건이 있습니다.