API：モデル評価

モデル評価の Python API は、評価を作成し、メトリクス、画像、プロット、テーブルを評価に記録するためのメソッドを提供します。

palantir_models.transforms.evaluation

palantir_models.transforms.evaluation デコレーターは評価を作成します。このデコレーターでトランスフォームをラップし、モデル入力上の書き込み先の評価セットを指定します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
from transforms.api import configure, transform, Input
import palantir_models as pm
from palantir_models.transforms import ModelInput

# 評価を作成するには、このデコレーターを適用する必要があります。
# このデコレーターは、モデル入力に書き込む評価セットを指定します。
@pm.transforms.evaluation("error_analysis")
@transform.using(
    input_data=Input("..."),
    model_input=ModelInput("..."),
)
def compute(input_data, model_input):
    evaluation = model_input.create_evaluation(name="my-evaluation")

上記の例では、評価は model_input モデル上の error_analysis 評価セットに書き込まれます。評価セットがまだ存在しない場合は、トランスフォームの初回実行時に自動的に作成されます。

パラメーター

• evaluation_set_name: str
  • 評価を書き込む評価セットの名前です。空でない文字列である必要があります。

---

ModelInput.create_evaluation

palantir_models.transforms.ModelInput.create_evaluation(name: Optional[str] = None) -> Evaluation

• この ModelInput によって読み込まれたモデルの Evaluation を作成して返します。
• @pm.transforms.evaluation でデコレートされたトランスフォーム内から呼び出す必要があります。
• 返される評価は、トランスフォームが生成または使用したモデルバージョンに関連付けられます。ビルドが正常に終了すると、評価は自動的に評価セットにコミットされます。ビルドに失敗した場合は、評価は中止されます。
• 同じトランスフォーム内で create_evaluation を複数回呼び出すと、同じ評価インスタンスが返されます。

Copied!
1
evaluation = model_input.create_evaluation(name="my-evaluation")

パラメーター

• name: Optional[str]
  • 評価の名前です。値を指定しない場合は、評価セットの名前が使用されます。名前は一意である必要はありません。再利用された名前は、自動的に一意になるように変更されます。

---

palantir_models.evaluations.Evaluation

モデル評価の結果を記録するためのクラスです。Evaluation は、create_evaluation を使用して ModelInput から作成され、単一のモデルバージョンがテストデータに対して示す性能を記録します。

実験とは異なり、評価はステップごとの時系列ではなく、結果の単一のスナップショットを記録するため、記録メソッドは step 引数を受け付けません。

evaluation_rid プロパティは、評価のリソース識別子（RID）を返します。

---

Evaluation.log_metric

palantir_models.evaluations.Evaluation.log_metric(key: str, value: Union[int, float])

• 指定された key に、単一のメトリクスの value を記録します。
• メトリクスの値は数値（int または float）である必要があります。
• 既存のキーに記録すると、以前の値が上書きされます。

Copied!
1
evaluation.log_metric("mae", 14250.0)

パラメーター

• key: str
  • 書き込むメトリクスの名前です。
• value: Union[int, float]
  • 書き込む数値です。

---

Evaluation.log_metrics

palantir_models.evaluations.Evaluation.log_metrics(metrics: Dict[str, Union[int, float]])

• log_metric のバッチ版です。
• すべての値は数値（int または float）である必要があります。

Copied!
1
2
3
4
evaluation.log_metrics({
    "mae": 14250.0,
    "r2": 0.91,
})

パラメーター

• metrics: Dict[str, Union[int, float]]
  • メトリクス名を数値のメトリクス値に対応付けるマッピングです。

---

Evaluation.log_image

palantir_models.evaluations.Evaluation.log_image(name: str, image: Union[str, bytes, "PIL.Image.Image"], caption: Optional[str] = None)

• 画像を評価に記録します。
• 画像は、PNG 画像へのパス、PNG 画像のバイト列、または Pillow ↗ 画像である必要があります。その他の画像形式は拒否されます。

Copied!
1
2
3
4
5
6
evaluation.log_image("residual_distribution", pillow_image)
evaluation.log_image(
    "error_heatmap",
    "path/to/image.png",
    caption="Geographic error heatmap",
)

パラメーター

• name: str
  • 書き込む画像の名前です。
• image: Union[str, bytes, "PIL.Image.Image"]
  • 書き込む画像です。
• caption: Optional[str]
  • 画像とともに書き込む任意のキャプションです。

---

Evaluation.log_plot

palantir_models.evaluations.Evaluation.log_plot(name: str, plot_data: "plotly.graph_objects.Figure", description: Optional[str] = None)

• プロットを評価に記録します。
• プロットは Plotly ↗ の plotly.graph_objects.Figure である必要があります。その他の種類のプロットは拒否されます。

Copied!
1
2
3
4
5
6
7
8
import plotly.express as px

fig = px.box(df, x="price_tier", y="residual", title="Residuals by price tier")
evaluation.log_plot(
    "residuals_by_tier",
    fig,
    description="Residual distribution across all price tiers",
)

パラメーター

• name: str
  • 書き込むプロットの名前です。
• plot_data: "plotly.graph_objects.Figure"
  • 書き込むプロットです。
• description: Optional[str]
  • プロットとともに書き込む任意の説明です。

---

Evaluation.log_table

palantir_models.evaluations.Evaluation.log_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

error_by_tier = pd.DataFrame({
    "price_tier": ["affordable", "mid_range", "luxury"],
    "mae": [8200.0, 15400.0, 42300.0],
    "r2": [0.94, 0.91, 0.87],
})

evaluation.log_table("error_by_price_tier", error_by_tier)

パラメーター

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

---