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

備考

ベータ版

この機能はベータ版です。

本番運用モニタリングは、ライブトラフィックに対してスコアラーを自動的に実行することで、生成AIアプリケーションの継続的な品質評価を可能にします。 MLflowを使用すると、任意のスコアラー (カスタムメトリクスと組み込みまたはカスタム LLM ジャッジを含む) を登録し、登録、アクティベーション、更新、削除を通じてライフサイクルを管理できます。

本番運用モニタリングには、次の機能が含まれています。

登録するスコアラーオブジェクト指向の方法を通じてライフサイクルを管理します。
設定可能なサンプリングレートにより、カバレッジと計算コストのトレードオフを制御できます。
開発と本番運用で同じスコアラーを使用して、一貫した評価を確保します。
モニタリングをバックグラウンドで実行した継続的な品質評価。
評価結果は、評価されたトレースにフィードバックとして自動的に添付されます。
状態管理を改善するために新しいスコアラーインスタンスを返す不変の操作。

legacy 製品モニタリングに関する情報については、本番運用モニタリング API reference (legacy) を参照してください。

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

新しいスコアラーのライフサイクルでは、異なる状態を明確に進行できます。

未登録 : スコアラー関数はローカルに存在しますが、サーバーには認識されません
登録済み :スコアラーはMLFlowに名前付きで保存されます( .register()を使用)
アクティブ : スコアラーはサンプルレート > 0 で実行されています ( .start()を使用)
停止: スコアラーは登録されていますが、実行されていません (サンプルレート = 0、 .stop()を使用 )
削除: スコアラーがサーバーから完全に削除されます(.delete()

すべてのライフサイクル操作は不変であり、元のインスタンスを変更するのではなく、新しいスコアラーインスタンスを返します。

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): エクスペリメント内のスコアラーの一意の名前。デフォルトはスコアラーの既存の名前です。

収益： サーバー登録を含む新しい 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): スコアラーの名前。指定しない場合、デフォルトはスコアラーの現在の名前になります。
sampling_config (ScorerSamplingConfig): トレースサンプリング構成
- sample_rate (float): 評価するトレースの割合 (0.0-1.0)。デフォルト: 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): スコアラーの名前。指定しない場合、デフォルトはスコアラーの現在の名前になります。
sampling_config (ScorerSamplingConfig): トレースサンプリング構成
- sample_rate (float): 評価するトレースの割合 (0.0-1.0)。デフォルト: 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): スコアラーの名前。指定しない場合、デフォルトはスコアラーの現在の名前になります。

収益： 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 instance

`mlflow.genai.scorers.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 import ScorerSamplingConfig

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

属性：

sample_rate (float、オプション): サンプリングレート 0.0 から 1.0 まで
filter_string (str、省略可能): MLflow トレースフィルター

使用パターン

基本的なスコアラーのライフサイクル

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

# Built-in scorer lifecycle
safety_scorer = Safety().register(name="safety_check")
safety_scorer = safety_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=1.0),
)
safety_scorer = safety_scorer.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)
safety_scorer = safety_scorer.stop()
safety_scorer.delete()

# Custom scorer lifecycle
@scorer
def response_length(outputs):
    return len(str(outputs.get("response", "")))

length_scorer = response_length.register(name="length_check")
length_scorer = length_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=0.5),
)

複数のスコアラーの管理

Python
from mlflow.genai.scorers import Safety, Guidelines, list_scorers

# Register multiple scorers
safety_scorer = Safety().register(name="safety")
safety_scorer = safety_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=1.0),
)

guidelines_scorer = Guidelines(
    name="english",
    guidelines=["Response must be in English"]
).register(name="english_check")
guidelines_scorer = guidelines_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=0.5),
)

# List and manage all scorers
all_scorers = list_scorers()
for scorer in all_scorers:
    if scorer.sample_rate > 0:
        print(f"{scorer.name} is active")
    else:
        print(f"{scorer.name} is stopped")

不変の更新

Python
# Demonstrate immutability
original_scorer = Safety().register(name="safety")
original_scorer = original_scorer.start(
   sampling_config=ScorerSamplingConfig(sample_rate=0.3),
)

# Update returns new instance
updated_scorer = original_scorer.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)

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

メトリクス backfill

`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、オプション): バックフィルするエクスペリメントの ID。指定しない場合は、現在のエクスペリメントコンテキストを使用します
scorers (Union[List[BackfillScorerConfig], List[str]], required): カスタムサンプルレートを持つBackfillScorerConfigオブジェクトのリスト (BackfillScorerConfig でsample_rateが指定されていない場合、デフォルトは登録されたスコアラーのサンプルレートに)、またはエクスペリメントのスケジュールされたスコアラーからの現在のサンプルレートを使用するスコアラー名 (文字列) のリスト。空にすることはできません。
start_time (datetime、オプション): バックフィル評価の開始時刻。指定しない場合、開始時間の制約は適用されません
end_time (datetime、オプション): バックフィル評価の終了時刻。指定しない場合、終了時間の制約は適用されません

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

ベストプラクティス

スコアラーの状態管理

プロパティを使用して操作する前に スコアラーの状態を確認する sample_rate
不変パターンを使用 - 変数に .start()、 .update()、 .stop() の結果を割り当てます
ライフサイクルの理解 - .stop() は登録を保持 .delete() 完全に削除します

命名と構成

スコアラーの目的を示すわか りやすい名前を使用する
「safety_check」、「relevance_monitor」などの 命名規則に従ってください
エクスペリメント内の名前 は一意である必要があります (エクスペリメントごとに最大20人のスコアラー)

サンプリング戦略

クリティカルスコアラー : 安全性とセキュリティのチェックには sample_rate=1.0 を使用します
高価なスコアラー: 複雑な LLM ジャッジには、より低いサンプルレート (0.05-0.2) を使用します
開発スコアラー : 反復的な改善のために中程度のレート (0.3-0.5) を使用します

メトリクス backfill

小規模から始める : ジョブの期間とリソース使用量を見積もるために、より短い時間範囲から始めます
適切なサンプルレート: 高いサンプルレートがコストと時間に与える影響を考慮する

次のステップ

実行 scorers in 本番運用 - モニタリングを有効にするためのステップバイステップガイド。
ビルド評価データセット - モニタリング結果を使用して品質を向上させます。
カスタムスコアラーの作成 - ニーズに合わせたスコアラーを構築します。

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

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​

backfill_scorers()​

ベストプラクティス​

スコアラーの状態管理​

命名と構成​

サンプリング戦略​

メトリクス backfill​

次のステップ​

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

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

`backfill_scorers()`

ベストプラクティス

スコアラーの状態管理

命名と構成

サンプリング戦略

メトリクス backfill

次のステップ