评估工具

2025-10-28

评估工具充当 GenAI 应用程序的测试框架。使用该工具，您无需手动运行应用程序并逐个检查输出，而是可以采用一种结构化的方法，将测试数据输入、运行应用程序并自动对结果评分。这样，可以更轻松地比较版本、跟踪改进并跨团队共享结果。

借助 MLflow，评估工具将脱机测试与生产监视连接起来。这意味着在开发中使用的相同评估逻辑也可以在生产环境中运行，从而在整个 AI 生命周期中提供一致的质量视图。

该 mlflow.genai.evaluate() 函数通过运行评估数据集和应用记分器系统地测试 GenAI 应用的质量。

如果你不熟悉评估，请从教程开始：评估和改进 GenAI 应用程序。

何时使用

对应用进行针对特选评估数据集的每晚或每周检查
验证不同应用版本的提示或模型更改
在发布或 PR 之前防止质量回归

处理工作流

评估工具执行以下任务：

在测试输入上运行应用程序，捕获追踪记录。
应用记分器来评估质量，创建反馈。
将结果存储在评估运行中。

快速参考

有关 API 详细信息，请参阅参数或 mlflow.genai.evaluate()MLflow 文档。

该 mlflow.genai.evaluate() 函数使用指定的记分器以及预测函数或模型 ID（可选）对评估数据集运行 GenAI 应用，并返回一个 EvaluationResult。

def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

Prerequisites

安装 MLflow 和所需的包。

pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"

请按照设置环境快速入门创建 MLflow 试验。

（可选）配置并行化

默认情况下，MLflow 使用后台线程池来加快评估过程。若要配置辅助角色数，请设置环境变量 MLFLOW_GENAI_EVAL_MAX_WORKERS。

export MLFLOW_GENAI_EVAL_MAX_WORKERS=10

评估模式

有两种评估模式：

直接评估（建议）。 MLflow 直接调用应用以生成用于评估的跟踪信息。
答题卡评估。您提供预先计算的输出或现有的跟踪以进行评估。

直接评估（建议）

MLflow 直接调用 GenAI 应用程序，以生成和评估轨迹。可以传递 Python 函数中包装的应用程序的入口点 (predict_fn)，或者，如果将应用部署为 Databricks 模型服务终结点，则传递 to_predict_fn 中包装的终结点。

通过直接调用应用，此模式使你能够重复使用在生产监视中为脱机评估定义的记分器，因为生成的跟踪将相同。

如图所示，数据、应用程序和所选评分器作为输入提供给mlflow.genai.evaluate()，在其中应用程序和评分器并行运行，并将输出记录为跟踪和反馈。

评估如何与跟踪配合使用

用于直接评估的数据格式

有关架构详细信息，请参阅评估数据集参考。

Field	数据类型	Required	Description
`inputs`	`dict[Any, Any]`	是的	传递给 `predict_fn` 的字典
`expectations`	`dict[str, Any]`	否	评分器的可选基本事实

使用直接评估的示例

以下代码演示了如何运行评估的示例：

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app with MLflow tracing
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    if "MLflow" in question:
        response = "MLflow is an open-source platform for managing ML and GenAI workflows."
    else:
        response = "I can help you with MLflow questions."

    return {"response": response}

# Evaluate your app
results = mlflow.genai.evaluate(
    data=[
        {"inputs": {"question": "What is MLflow?"}},
        {"inputs": {"question": "How do I get started?"}}
    ],
    predict_fn=my_chatbot_app,
    scorers=[RelevanceToQuery(), Safety()]
)

然后，可以在 UI 中查看结果：

评估结果

答题纸评估

在评估期间无法或不想直接运行 GenAI 应用时，请使用此模式。例如，你已有输出（例如，来自外部系统、历史跟踪或批处理作业），并且只想对其进行评分。请提供输入和输出，然后 Harness 将运行记分器并记录评估运行。

Important

如果您使用的答案表中的跟踪信息与生产环境不同，则可能需要重新编写记分器函数，以便用于生产监视。

如图所示，您将评估数据和所选评分器作为输入提供给mlflow.genai.evaluate()。评估数据可以由现有的跟踪数据，或输入和预计算的输出组成。如果提供输入和预计算的输出，mlflow.genai.evaluate() 将从这些输入和输出中构造跟踪。对于这两个输入选项， mlflow.genai.evaluate() 在跟踪上运行评分器，并输出来自评分器的反馈。

如何使用答案表进行评估

答题卡评估的数据格式

有关架构详细信息，请参阅评估数据集参考。

如果提供了输入和输出

Field	数据类型	Required	Description
`inputs`	`dict[Any, Any]`	是的	GenAI 应用的原始输入
`outputs`	`dict[Any, Any]`	是的	应用的预计算输出
`expectations`	`dict[str, Any]`	否	评分器的可选基本事实

如果提供了现有跟踪

Field	数据类型	Required	Description
`trace`	`mlflow.entities.Trace`	是的	具有输入/输出的 MLflow 跟踪对象
`expectations`	`dict[str, Any]`	否	评分器的可选基本事实

使用输入和输出的示例

以下代码演示了如何运行评估的示例：

import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery

# Pre-computed results from your GenAI app
results_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "outputs": {"response": "MLflow is an open-source platform for managing machine learning workflows, including tracking experiments, packaging code, and deploying models."},
    },
    {
        "inputs": {"question": "How do I get started?"},
        "outputs": {"response": "To get started with MLflow, install it using 'pip install mlflow' and then run 'mlflow ui' to launch the web interface."},
    }
]

# Evaluate pre-computed outputs
evaluation = mlflow.genai.evaluate(
    data=results_data,
    scorers=[Safety(), RelevanceToQuery()]
)

然后，可以在 UI 中查看结果：

评估结果

使用现有跟踪的示例

以下代码演示如何使用现有跟踪运行评估：

import mlflow

# Retrieve traces from production
traces = mlflow.search_traces(
    filter_string="trace.status = 'OK'",
)

# Evaluate problematic traces
evaluation = mlflow.genai.evaluate(
    data=traces,
    scorers=[Safety(), RelevanceToQuery()]
)

参数 `mlflow.genai.evaluate()`

本部分介绍所使用的 mlflow.genai.evaluate()每个参数。

def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

`data`

评估数据集必须具有以下格式之一：

EvaluationDataset（推荐）。
字典、Pandas DataFrame 或 Spark DataFrame 的列表。

如果数据参数作为数据帧或字典列表提供，则它必须遵循以下架构。这与 EvaluationDataset 使用的架构一致。除了跟踪每个记录的世系之外，Databricks 还建议使用 EvaluationDataset 强制实施架构验证。

Field	数据类型	Description	与直接评估配合使用	与答案表一起使用
`inputs`	`dict[Any, Any]`	一个使用 `dict` 传递给 `predict_fn` 的 `**kwargs`。必须是 JSON 可序列化的。每个键必须对应于`predict_fn`中的命名参数。	Required	要么`inputs` + `outputs`，要么`trace`是必需的。不能同时传递这两者。未提供时派生自 `trace`。
`outputs`	`dict[Any, Any]`	含对应 `dict` 的 GenAI 应用输出的 `input`。必须是 JSON 可序列化的。	不得提供，由 MLflow 根据 Trace 生成。	要么`inputs` + `outputs`，要么`trace`是必需的。不能同时传递这两者。未提供时派生自 `trace`。
`expectations`	`dict[str, Any]`	含与 `dict` 对应的基本事实标签的 `input`。 `scorers` 用于质量检查。必须是 JSON 可序列化的，并且每个密钥必须是一个 `str`。	Optional	Optional
`trace`	`mlflow.entities.Trace`	请求的跟踪对象。如果提供了`trace`，那么`expectations`可以在`Assessments`上以`trace`的形式提供，而不是作为一个单独的列。	不得提供，由 MLflow 根据 Trace 生成。	要么`inputs` + `outputs`，要么`trace`是必需的。不能同时传递这两者。

`scorers`

要应用的质量指标列表。可以提供：

有关更多详细信息，请参阅记分器。

`predict_fn`

GenAI 应用的入口点。此参数仅用于直接计算。 predict_fn 必须满足以下要求：

接受字典inputs中的data键作为关键字参数。
返回 JSON 可序列化字典。
使用 MLflow 跟踪进行检测。
每次调用都仅发出一个跟踪。

`model_id`

可选模型标识符，用于将结果链接到应用版本（例如 "models:/my-app/1"）。有关更多详细信息，请参阅版本跟踪。

后续步骤

评估你的应用 - 运行第一次评估的分步指南。
生成评估数据集 - 从生产日志或暂存创建结构化测试数据。
定义自定义记分器 - 生成针对特定用例定制的指标。

反馈

此页面是否有帮助？