本番運用スコアラーの管理

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

本番運用モニタリングを設定した後は、ライフサイクル全体にわたってスコアラーを管理できるようになります。このページでは、スコアラーの一覧表示、更新、停止、再起動、および削除の方法について説明します。

API パラメーターのリファレンス全文については、本番運用スコアラーの管理を参照してください。

スコアラーのライフサイクル

スコアラーのライフサイクルは、MLflow エクスペリメントを中心にしています。スコアラーは*不変*です。各ライフサイクル操作は、元のスコアラーを変更するのではなく、新しいスコアラーインスタンスを返します。

状態	説明	API
未登録	スコアラー関数は定義されていますが、サーバーには認識されていません。
登録済み	スコアラーはアクティブなMLflowエクスペリメントに登録されます。	`.register()`
アクティブ	スコアラーは0より大きいサンプリングレートで実行されています。	`.start()`
停止	スコアラーは登録されていますが、実行されていません（サンプルレート = 0）。	`.stop()`
削除済み	スコアラーはサーバーから削除され、エクスプロメントとは関連付けられなくなりました。	`delete_scorer()`

状態	説明	API
未登録	スコアラー関数は定義されていますが、サーバーには認識されていません。
登録済み	スコアラーはアクティブなMLflowエクスペリメントに登録されます。	`.register()`
アクティブ	スコアラーは0より大きいサンプリングレートで実行されています。	`.start()`
停止	スコアラーは登録されていますが、実行されていません（サンプルレート = 0）。	`.stop()`
削除済み	スコアラーはサーバーから削除され、エクスプロメントとは関連付けられなくなりました。	`delete_scorer()`

ライフサイクルの例

以下の例は、スコアラーがライフサイクルのすべての状態を経ていく様子を示しています。

Python
from mlflow.genai.scorers import Safety, scorer, ScorerSamplingConfig, delete_scorer

# Register → Start → Update → Stop → Delete
safety_judge = Safety().register(name="safety_check")
safety_judge = safety_judge.start(
    sampling_config=ScorerSamplingConfig(sample_rate=1.0),
)
safety_judge = safety_judge.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)
safety_judge = safety_judge.stop()
delete_scorer(name="safety_check")

スコアラーを管理する

スコアラーを管理するために、以下のAPIs利用可能です。

API	説明	例
`list_scorers()`	現在のエクスペリメントに登録されているすべてのスコアラーをリストします。	リストスコアラー
`get_scorer()`	登録済みのスコアラーを名前で検索します。	`Scorer.update()`
`Scorer.update()`	アクティブなスコアラーのサンプリング設定を変更します。これは変更不可能な操作です。	`Scorer.update()`
`backfill_scorer()`	過去のトレースに対して、新規または更新されたメトリクスを遡及的に適用する。	スコアラーで歴史的な痕跡を埋める
`delete_scorer()`	登録済みのスコアラーを名前で削除します。	スコアラーを停止して削除します

API	説明	例
`list_scorers()`	現在のエクスペリメントに登録されているすべてのスコアラーをリストします。	リストスコアラー
`get_scorer()`	登録済みのスコアラーを名前で検索します。	`Scorer.update()`
`Scorer.update()`	アクティブなスコアラーのサンプリング設定を変更します。これは変更不可能な操作です。	`Scorer.update()`
`backfill_scorer()`	過去のトレースに対して、新規または更新されたメトリクスを遡及的に適用する。	スコアラーで歴史的な痕跡を埋める
`delete_scorer()`	登録済みのスコアラーを名前で削除します。	スコアラーを停止して削除します

リストスコアラー

エクスペリメントの登録済みスコアラーをすべて表示するには:

Python
from mlflow.genai.scorers import list_scorers

# List all registered scorers
scorers = list_scorers()
for scorer in scorers:
    print(f"Name: {scorer.name}")
    print(f"Sample rate: {scorer.sample_rate}")
    print(f"Filter: {scorer.filter_string}")
    print("---")

スコアラーを取得して更新する

get_scorer()を使用してスコアラーを名前で取得し、 update()を使用してその設定を変更します。スコアラーは不変であるため、 update()新しいインスタンスを返します。

Python
from mlflow.genai.scorers import get_scorer, ScorerSamplingConfig

# Get existing scorer and update its configuration (immutable operation)
safety_judge = get_scorer(name="safety_monitor")
updated_judge = safety_judge.update(sampling_config=ScorerSamplingConfig(sample_rate=0.8))

# The original scorer remains unchanged; update() returns a new scorer instance
print(f"Original sample rate: {safety_judge.sample_rate}")  # Original rate
print(f"Updated sample rate: {updated_judge.sample_rate}")   # New rate

スコアラーを停止して削除します

スコアラーを停止すると、サンプリングレートは0に設定されますが、記録は維持されます。スコアラーを削除すると、サーバーから完全に削除されます。

Python
from mlflow.genai.scorers import get_scorer, delete_scorer, ScorerSamplingConfig

# Get existing scorer
databricks_scorer = get_scorer(name="databricks_mentions")

# Stop monitoring (sets sample_rate to 0, keeps scorer registered)
stopped_scorer = databricks_scorer.stop()
print(f"Sample rate after stop: {stopped_scorer.sample_rate}")  # 0

# Restart monitoring from a stopped scorer
restarted_scorer = stopped_scorer.start(sampling_config=ScorerSamplingConfig(sample_rate=0.5))

# Or remove scorer entirely from the server
delete_scorer(name=databricks_scorer.name)

不変の更新

採点者（LLM審査員を含む）は、不変の存在である。スコアラーを更新すると、元のスコアラーを修正するのではなく、更新されたコピーが作成されます。この不変性は、本番運用用のスコアラーが誤って変更されないようにするのに役立ちます。

Python
from mlflow.genai.scorers import Safety, ScorerSamplingConfig

original_judge = Safety().register(name="safety")
original_judge = original_judge.start(
   sampling_config=ScorerSamplingConfig(sample_rate=0.3),
)

# Update returns new instance
updated_judge = original_judge.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)

# Original remains unchanged
print(f"Original: {original_judge.sample_rate}")  # 0.3
print(f"Updated: {updated_judge.sample_rate}")    # 0.8

ベストプラクティス

sample_rateを使用して操作を行う前にスコアラーの状態を確認します。
不変パターンを使用してください。.start() 、 .update() 、 .stop()の結果を変数に代入します。
.stop() （登録を保持する）とdelete_scorer() （完全に削除する）の違いを理解してください。

スコアラーライフサイクル API リファレンス

スコアラーインスタンスメソッド

`Scorer.register()`

API リファレンス: Scorer.register

カスタムスコアラー関数をサーバーに登録します。 @scorerデコレータで作成されたスコアラーに使用されます。

Python
@scorer
def custom_scorer(outputs):
    return len(str(outputs.get("response", "")))

# Register the custom scorer
my_scorer = custom_scorer.register(name="response_length")

パラメーター:

name (str): エクスペリメント内でのスコアラーの一意の名前。スコアラーの既存の名前にdefaultされます。

戻り値： サーバー登録を含む新しい Scorer インスタンス

`Scorer.start()`

API リファレンス: Scorer.start

指定したサンプリング構成を使用してオンライン評価を開始します。

Python
from mlflow.genai.scorers import ScorerSamplingConfig

# Start monitoring with sampling
active_scorer = registered_scorer.start(
    sampling_config=ScorerSamplingConfig(
        sample_rate=0.5,
        filter_string="trace.status = 'OK'"
    ),
)

パラメーター:

name (str): スコアラーの名前。指定されていない場合は、defaultでスコアラーの現在の名前が使用されます。
sampling_config (ScorerSamplingConfig): トレースサンプリング構成
- sample_rate （float）：評価するトレースの割合（0.0～1.0）。default: 1.0
- filter_string （str、オプション）：トレース選択用の MLflow 互換フィルター

戻り値： アクティブな状態の新しい Scorer インスタンス

`Scorer.update()`

API リファレンス: Scorer.update

アクティブなスコアラーのサンプリング設定を変更します。これは変更不可能な操作です。

Python
# Update sampling rate (returns new scorer instance)
updated_scorer = active_scorer.update(
    sampling_config=ScorerSamplingConfig(
        sample_rate=0.8,
    ),
)

# Original scorer remains unchanged
print(f"Original: {active_scorer.sample_rate}")  # 0.5
print(f"Updated: {updated_scorer.sample_rate}")   # 0.8

パラメーター:

name (str): スコアラーの名前。指定されていない場合は、defaultでスコアラーの現在の名前が使用されます。
sampling_config (ScorerSamplingConfig): トレースサンプリング構成
- sample_rate （float）：評価するトレースの割合（0.0～1.0）。default: 1.0
- filter_string （str、オプション）：トレース選択用の MLflow 互換フィルター

戻り値： 設定が更新された新しい Scorer インスタンス

`Scorer.stop()`

API リファレンス: Scorer.stop

サンプリングレートを 0 に設定して、オンライン評価を停止します。スコアラーの登録は維持されます。

Python
# Stop monitoring but keep scorer registered
stopped_scorer = active_scorer.stop()
print(f"Sample rate: {stopped_scorer.sample_rate}")  # 0

パラメーター:

name (str): スコアラーの名前。指定されていない場合は、defaultでスコアラーの現在の名前が使用されます。

戻り値： sample_rate=0 の新しい Scorer インスタンス

スコアラーレジストリ関数

`mlflow.genai.scorers.get_scorer()`

API リファレンス: get_scorer

登録済みのスコアラーを名前で検索します。

Python
from mlflow.genai.scorers import get_scorer

# Get existing scorer by name
existing_scorer = get_scorer(name="safety_monitor")
print(f"Current sample rate: {existing_scorer.sample_rate}")

パラメーター:

name (str): 登録されたスコアラーの名前

戻り値: Scorer インスタンス

`mlflow.genai.scorers.list_scorers()`

API リファレンス: list_scorers

現在のエクスペリメントに登録されているすべてのスコアラーをリストします。

Python
from mlflow.genai.scorers import list_scorers

# List all registered scorers
all_scorers = list_scorers()
for scorer in all_scorers:
    print(f"Name: {scorer._server_name}")
    print(f"Sample rate: {scorer.sample_rate}")
    print(f"Filter: {scorer.filter_string}")

戻り値： Scorerインスタンスのリスト

`mlflow.genai.scorers.delete_scorer()`

API リファレンス: delete_scorer

登録済みのスコアラーを名前で削除します。

Python
from mlflow.genai.scorers import delete_scorer

# Delete existing scorer by name
delete_scorer(name="safety_monitor")

パラメーター:

name (str): 登録されたスコアラーの名前

戻り値： None

スコアラープロパティ

`Scorer.sample_rate`

現在のサンプリング率（0.0～1.0）。停止したスコアラーに対して 0 を返します。

Python
print(f"Sampling {scorer.sample_rate * 100}% of traces")

`Scorer.filter_string`

MLflow トレース選択用の現在のトレースフィルター文字列。

Python
print(f"Filter: {scorer.filter_string}")

構成クラス

`ScorerSamplingConfig`

API リファレンス: ScorerSamplingConfig

スコアラーのサンプリング構成を保持するデータクラス。

Python
from mlflow.genai.scorers import ScorerSamplingConfig

config = ScorerSamplingConfig(
    sample_rate=0.5,
    filter_string="trace.status = 'OK'"
)

属性：

sample_rate （float、オプション）：0.0～1.0のサンプリング率
filter_string (str、省略可能): MLflow トレースフィルター

メトリクスのバックフィル

`backfill_scorers()`

Python
from databricks.agents.scorers import backfill_scorers, BackfillScorerConfig

job_id = backfill_scorers(
    experiment_id="your-experiment-id",
    scorers=[
        BackfillScorerConfig(scorer=safety_scorer, sample_rate=0.8),
        BackfillScorerConfig(scorer=response_length, sample_rate=0.9)
    ],
    start_time=datetime(2024, 1, 1),
    end_time=datetime(2024, 1, 31)
)

パラメーター:

すべてのパラメーターはキーワード専用です。

experiment_id (str, optional) ：バックフィルするエクスペリメントの ID。指定しない場合、現在のエクスペリメントコンテキストが使用されます
scorers (Union[List[BackfillScorerConfig], List[str]], required) : カスタムサンプルレートを持つ BackfillScorerConfig オブジェクトのリスト（BackfillScorerConfig で sample_rate が指定されていない場合は、登録されたスコアラーのサンプルレートにdefault設定されます）、またはエクスペリメントのスケジュールされたスコアラーの現在のサンプルレートを使用するスコアラー名（文字列）のリスト。空にすることはできません。
start_time (datetime、オプション) : バックフィル評価の開始時刻。これを省略して end_time を渡した場合、バックフィルは 1 日前に開始されます end_time
end_time (datetime、オプション) : バックフィル評価の終了時刻。これを省略して start_time を渡した場合、バックフィルは現在時刻まで実行されます。

重要

start_time と end_time の両方を省略した場合、バックフィルは完全なトレース履歴ではなく、過去 7 日間のみをカバーします。上記のように、一方の境界のみを省略すると、異なるdefaultが適用されます。以前のトレースを評価するには、明示的な start_time を指定します。

戻り値: ステータス追跡のために作成されたバックフィルジョブのジョブ ID (str)

次のステップ: エージェントの可観測性のレシピ

スコアラーのライフサイクル​

ライフサイクルの例​

スコアラーを管理する​

リストスコアラー​

スコアラーを取得して更新する​

スコアラーを停止して削除します​

不変の更新​

ベストプラクティス​

スコアラー ライフサイクル API リファレンス​

スコアラーインスタンスメソッド​

Scorer.register()​

Scorer.start()​

Scorer.update()​

Scorer.stop()​

スコアラーレジストリ関数​

mlflow.genai.scorers.get_scorer()​

mlflow.genai.scorers.list_scorers()​

mlflow.genai.scorers.delete_scorer()​

スコアラープロパティ​

Scorer.sample_rate​

Scorer.filter_string​

構成クラス​

ScorerSamplingConfig​

メトリクスのバックフィル​

backfill_scorers()​

スコアラーのライフサイクル

ライフサイクルの例

スコアラーを管理する

リストスコアラー

スコアラーを取得して更新する

スコアラーを停止して削除します

不変の更新

ベストプラクティス

スコアラーライフサイクル API リファレンス

スコアラーインスタンスメソッド

`Scorer.register()`

`Scorer.start()`

`Scorer.update()`

`Scorer.stop()`

スコアラーレジストリ関数

`mlflow.genai.scorers.get_scorer()`

`mlflow.genai.scorers.list_scorers()`

`mlflow.genai.scorers.delete_scorer()`

スコアラープロパティ

`Scorer.sample_rate`

`Scorer.filter_string`

構成クラス

`ScorerSamplingConfig`

メトリクスのバックフィル

`backfill_scorers()`