记分器生命周期管理 API 参考

2025-08-29

重要

此功能在 Beta 版中。

通过生产监控，可以通过在实时流量上自动运行评分器来持续评价您的 GenAI 应用程序的质量。使用 MLflow，可以注册任何记分器（包括自定义指标和内置或自定义 LLM 法官），并通过注册、激活、更新和删除来管理其生命周期。

生产监视包括以下功能：

通过面向对象的方法注册记分器并管理其生命周期。
可配置的采样率，以便控制覆盖率与计算成本之间的权衡。
在开发和生产中使用相同的评分器来确保一致的评估。
持续质量评估，后台运行监控。
评估结果会自动作为反馈附加到被评估的记录中。
返回新记分器实例的不可变操作，以便更好地管理状态。

有关旧产品监视的信息，请参阅生产监视 API 参考（旧版）。

记分器生命周期概述

新的记分器生命周期通过不同的状态提供明确的进展：

未注册：记分器函数在本地存在，但服务器不知道
已注册：记分器以名称保存在 MLFlow 中（使用 .register()）
激活：评分器在采样率大于 > 0 时运行（使用 .start()）
已停止：记分器已注册但未运行（采样率 = 0，使用 .stop()）
已删除：记分器已完全从服务器中删除（使用 .delete()）

所有生命周期作都是 不可变 的 - 它们返回新的记分器实例，而不是修改原始实例。

API 参考文档

记分器实例方法

`Scorer.register()`

API 参考：Scorer.register

向服务器注册自定义记分器函数。用于使用 @scorer 修饰器创建的记分器。

@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

使用指定的采样配置开始联机评估。

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

修改活动评分器的采样配置。这是一个不可变的操作。

# 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 来停止联机评估。使记分器保持注册状态。

# 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

按名称检索已注册的记分器。

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()`

列出当前试验的所有已注册评分器。

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

按名称删除已注册的记分器。

from mlflow.genai.scorers import delete_scorer

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

参数：

name （str）：已注册的记分器的名称

返回： 没有

记分器属性

`Scorer.sample_rate`

当前采样率（0.0-1.0）。返回已停止的记分器的 0。

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

`Scorer.filter_string`

MLflow 跟踪选择的当前跟踪筛选器字符串。

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

Configuration 类

`ScorerSamplingConfig`

API 参考：ScorerSamplingConfig

保存评分器的采样配置的数据类。

from mlflow.genai import ScorerSamplingConfig

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

属性：

sample_rate （浮点数，可选）：采样率介于 0.0 和 1.0 之间
filter_string （str，可选）：MLflow 跟踪筛选器

使用模式

基本记分器生命周期

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),
)

管理多个评分器

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")

不可变更新

# 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_scorers()`

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，则默认为已注册的记分器的采样率）、或记分器名称列表（字符串）以使用试验计划评分器中的当前采样率。不能为空。
start_time （日期时间，可选）：回填评估的开始时间。如果未提供，则不应用开始时间约束
end_time （日期时间，可选）：回填评估的结束时间。如果未提供，则不应用结束时间约束

返回： 为状态跟踪创建的回填作业的作业 ID （str）

最佳做法

记分器状态管理

使用属性进行操作之前检查记分器状态
使用不可变模式 - 将.start()、.update()、.stop()的结果分配给变量
了解生命周期 - .stop()可保留注册，.delete()则完全删除

命名和组织

使用指示记分器用途的描述性名称
遵循命名约定 ，例如“safety_check”、“relevance_monitor”
名称在实验中必须唯一（每个实验最多 20 个评分者）

采样策略

关键评估工具：使用 sample_rate=1.0 进行安全性和保安性检查
昂贵的评分员：对复杂的 LLM 法官使用较低的采样率（0.05-0.2）
开发评分器：使用中等速率（0.3-0.5）进行迭代改进

指标回填

从小开始：从较小的时间范围开始，以估计作业持续时间和资源使用情况
适当的采样率：考虑高采样率的成本和时间影响

后续步骤

在生产环境中运行记分器 - 启用监视的分步指南。
生成评估数据集 - 使用监视结果提高质量。
创建自定义记分器 - 生成根据需求定制的评分器。

다음을 통해 공유

记分器生命周期管理 API 参考

记分器生命周期概述

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

Configuration 类

ScorerSamplingConfig

使用模式

基本记分器生命周期

管理多个评分器

不可变更新

指标回填

backfill_scorers()

最佳做法

记分器状态管理

命名和组织

采样策略

指标回填

后续步骤

추가 리소스

`Scorer.register()`

`Scorer.start()`

`Scorer.update()`

`Scorer.stop()`

`mlflow.genai.scorers.get_scorer()`

`mlflow.genai.scorers.list_scorers()`

`Scorer.sample_rate`

`Scorer.filter_string`

`ScorerSamplingConfig`

`backfill_scorers()`