API: モデル実験

モデル実験の Python API は、メトリクスとハイパーパラメーターを実験に書き込むためのメソッドを提供します。このページでは、palantir_models.experiments パッケージで利用可能な関数とクラスについて説明します。

palantir_models.experiments.Experiment

モデルのトレーニング実験を追跡するためのクラスです。実験は、任意の ModelOutput クラスから作成できます。

Copied!
1
model_output.create_experiment(name="experiment-name")

palantir_models.experiments.ErrorHandlerType

実験コードの実行時にエラーをどのように処理するかを制御する列挙型です。具体的には、メトリクスの書き込み時のネットワークエラーや実験のサイズ超過など、ユーザーコード以外に起因するエラーを制御します。

以下に示すように、実験の作成時に、目的のエラーハンドラーの種類を ModelOutput.create_experiment に渡すことができます。

Copied!
1
2
3
4
5
from palantir_models.experiments import ErrorHandlerType
model_output.create_experiment(
    name="mnist-experiment",
    error_handler_type=ErrorHandlerType.WARN
)

---

Experiment.log_param

palantir_models.experiments.Experiment.log_param(key: str, value: Union[bool, date, datetime, float, int, str])

• 指定されたパラメーターの value を、指定された key に記録します。
• 同じパラメーターキーに記録することで、パラメーターを上書きできます。

Copied!
1
experiment.log_param(key="learning_rate", value=1e-3)

パラメーター

• key: str
  • 書き込むパラメーターの名前です。
• value: Union[bool, date, datetime, float, int, str]
  • パラメーターに書き込む値です。

---

Experiment.log_params

palantir_models.experiments.Experiment.log_params(parameter_map: Dict[str, Union[bool, date, datetime, float, int, str]])

• log_param のバッチ処理バージョンです。

Copied!
1
2
3
4
experiment.log_params(parameter_map={
    "learning_rate": 1e-3,
    "model_type": "CNN"
})

パラメーター

• parameter_map: Dict[str, Union[bool, date, datetime, float, int, str]]
  • パラメーター名からパラメーター値へのマッピングです。

---

Experiment.log_metric

palantir_models.experiments.Experiment.log_metric(metric_name: str, metric_value: float, step: Optional[int] = None)

• 系列にメトリクス値を記録します。
• 系列が存在しない場合（まだ記録されていない場合）は、作成されます。
• step が指定されている場合は、そのステップへの記録が試行されます。そのステップにすでに記録されている場合は、エラーが送出されます。
• step が指定されていない場合は、系列の現在のステップが自動的に1増加します。

Copied!
1
2
experiment.log_metric(metric_name="train/loss", metric_value=1.5)
experiment.log_metric(metric_name="train/loss", metric_value=0.9) # ステップが自動的にインクリメントされます

パラメーター

• metric_name: str
  • 値を書き込むメトリクス系列の名前です。
• metric_value: float
  • 書き込む値です。
• step: Optional[int]
  • 書き込み先のステップ（任意）です。指定されたステップが現在のステップより小さい場合は、エラーが送出されます。ステップが指定されていない場合は、ステップが自動的に増加します。

---

Experiment.log_metrics

palantir_models.experiments.Experiment.log_metrics(values: Dict[str, float], step: Optional[int] = None)

• log_metric のバッチ処理バージョンです。
• 指定されたすべての値を、それぞれの系列の同じステップに記録します。
• 存在しない系列がある場合（まだ記録されていない場合）は、その系列が作成されます。
• step が指定されている場合は、そのステップへの記録が試行されます。いずれかの系列でそのステップにすでに記録されている場合は、エラーが送出されます。
• step が指定されていない場合は、すべての系列の現在のステップが、それぞれ独立して自動的に1増加します。

Copied!
1
2
3
4
experiment.log_metrics(values={
    "train/loss": 1.5,
    "train/acc", 0.7
})

パラメーター

• values: Dict[str, float]
  • メトリクス名からメトリクス値へのマッピングです。
• step: Optional[int]
  • 書き込み先のステップ（任意）です。指定されたステップが、書き込み先のいずれかの系列の現在のステップより小さい場合は、エラーが送出されます。ステップが指定されていない場合は、各系列のステップがそれぞれ独立して自動的に増加します。

---

Experiment.log_image

palantir_models.experiments.Experiment.log_image(series_name: str, image: Union[str, bytes, "PIL.Image.Image"], caption: Optional[str] = None, step: Optional[int] = None)

• 系列に画像を記録します。
• 画像には、PNG 画像へのパス、PNG 画像のバイト列、または Pillow ↗ の画像を指定する必要があります。
• 系列が存在しない場合（まだ記録されていない場合）は、作成されます。
• step が指定されている場合は、そのステップへの記録が試行されます。そのステップにすでに記録されている場合は、エラーが送出されます。
• step が指定されていない場合は、系列の現在のステップが自動的に1増加します。

Copied!
1
experiment.log_image("bounding_boxes", image="/path/to/image.png", caption="My caption", step=1)

パラメーター

• series_name: str
  • 値を書き込む画像系列の名前です。
• image: Union[str, bytes, "PIL.Image.Image"]
  • 書き込む画像です。
• caption: Optional[str]
  • 画像とともに書き込むキャプション（任意）です。
• step: Optional[str]
  • 書き込み先のステップ（任意）です。指定されたステップが現在のステップより小さい場合は、エラーが送出されます。ステップが指定されていない場合は、ステップが自動的に増加します。

---

Experiment.log_plot

palantir_models.experiments.Experiment.log_plot(series_name: str, plot_data: "plotly.graph_objects.Figure", caption: Optional[str] = None, step: Optional[int] = None)

• 系列にプロットを記録します。
• プロットは Plotly ↗ の plotly.graph_objects.Figure である必要があります。
• 系列が存在しない場合（まだ記録されていない場合）は、作成されます。
• step が指定されている場合は、そのステップへの記録が試行されます。そのステップにすでに記録されている場合は、エラーが送出されます。
• step が指定されていない場合は、系列の現在のステップが自動的に1増加します。

Copied!
1
2
3
4
import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 3, 2])
experiment.log_plot("training/accuracy", plot_data=fig, caption="Accuracy over epochs", step=10)

パラメーター

• series_name: str
  • 値を書き込むプロット系列の名前です。
• plot_data: "plotly.graph_objects.Figure"
  • 書き込むプロットです。
• caption: Optional[str]
  • プロットとともに書き込むキャプション（任意）です。
• step: Optional[int]
  • 書き込み先のステップ（任意）です。指定されたステップが現在のステップより小さい場合は、エラーが送出されます。ステップが指定されていない場合は、ステップが自動的に増加します。

---

Experiment.log_table

palantir_models.experiments.Experiment.log_table(table_name: str, table: Union["polars.DataFrame", "pandas.DataFrame"], description: Optional[str] = None)

• テーブルを実験に記録します。
• テーブルは pandas ↗ または Polars ↗ の DataFrame である必要があります。

Copied!
1
2
3
4
5
6
7
8
9
import pandas as pd

leaderboard = pd.DataFrame({
    "model_type": ["xgboost", "decision_tree", "torch_nn"],
    "score": [0.75, 0.6, 0.93],
    "rank": [2, 3, 1]
})

experiment.log_table("model_leaderboard", leaderboard)

パラメーター

• table_name: str
  • テーブルの名前です。
• table: Union["polars.DataFrame", "pandas.DataFrame"]
  • 書き込むテーブルデータです。
• description: Optional[str]
  • テーブルとともに書き込む説明（任意）です。

---

Experiment.as_mlflow_run

palantir_models.experiments.Experiment.as_mlflow_run()

• 実験に書き込むアクティブな MLflow 実行を作成します。
• MLflow >= 2.0.0 が必要です。

Copied!
1
2
with experiment.as_mlflow_run() as run:
    ...

---