评估快速入门

MLflow 助手

需要设置评估方面的帮助？请尝试 MLflow Assistant - 一个强大的 AI 助手，可以帮助你为项目设置评估。

本快速入门指南将引导你使用 MLflow 全面的评估框架来评估 LLM（大语言模型）应用程序和 AI 智能体。在不到 5 分钟的时间内，你将学习如何评估 LLM 输出、使用内置及自定义评估标准，并在 MLflow UI 中分析结果。

前提条件

根据你的 Python 环境，你可能需要通过运行以下命令来安装所需的包

bash
pip install openai

信息

本指南中的代码示例使用了 OpenAI SDK；不过，MLflow 的评估框架适用于任何 LLM 提供商，包括 Anthropic、Google、Bedrock 等。

第 1 步：设置环境

MLflow 将评估结果存储在 MLflow 跟踪服务器 (Tracking Server) 中。

通过执行以下任一方法启动本地 MLflow 跟踪服务器。

本地 (uv)
本地 (pip)
本地 (docker)

安装 Python 包管理器 uv（该管理器还将安装 uvx 命令，以便在不安装的情况下调用 Python 工具）。

在本地启动 MLflow 服务器。

shell
uvx mlflow server

信息

请参阅安全安装 (Secure Installs)，了解如何使用哈希检查和上传时过滤功能将依赖项固定到已知良好版本。

Python 环境：Python 3.10+

通过 pip 安装 mlflow Python 包并在本地启动 MLflow 服务器。

shell
pip install --upgrade mlflow
mlflow server

信息

请参阅安全安装 (Secure Installs)，了解如何使用哈希检查和上传时过滤功能将依赖项固定到已知良好版本。

MLflow 提供了一个 Docker Compose 文件，用于启动一个带有 PostgreSQL 数据库和 MinIO 服务器的本地 MLflow 服务器。

shell
git clone --depth 1 --filter=blob:none --sparse https://github.com/mlflow/mlflow.git
cd mlflow
git sparse-checkout set docker-compose
cd docker-compose
cp .env.dev.example .env
docker compose up -d

有关更多详细信息（例如，覆盖默认环境变量），请参考说明。

第 2 步：创建评估脚本

创建一个名为 quickstart_eval.py 的文件。此脚本将包含你的模拟智能体、评估数据集、评分器 (Scorers) 以及评估执行代码。或者，你也可以在 notebook 中运行它。

从环境设置开始

python
# quickstart_eval.py
import os
import mlflow

# Configure environment
os.environ["OPENAI_API_KEY"] = "your-api-key-here"  # Replace with your API key
mlflow.set_experiment("Evaluation Quickstart")

第 3 步：定义模拟智能体的预测函数

首先，我们需要创建一个预测函数，该函数接收一个问题并返回一个答案。这里我们使用 OpenAI 的 gpt-4o-mini 模型来生成答案，但如果你愿意，也可以使用任何其他 LLM 提供商。

将你的模拟智能体实现添加到 quickstart_eval.py 中

python
from openai import OpenAI

client = OpenAI()


def my_agent(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant. Answer questions concisely.",
            },
            {"role": "user", "content": question},
        ],
    )
    return response.choices[0].message.content


def qa_predict_fn(question: str) -> str:
    """Wrapper function for evaluation using ``my_agent``."""
    return my_agent(question)

第 4 步：准备评估数据集

评估数据集是一系列样本的集合，每个样本都包含 inputs（输入）和 expectations（期望）字段。

inputs：上述 predict_fn 函数的输入。键名必须与 predict_fn 函数的参数名称匹配。
expectations：predict_fn 函数的预期输出，即答案的地面真值 (ground truth)。

数据集可以是字典列表、pandas DataFrame 或 spark DataFrame。为简单起见，这里我们使用字典列表。

python
# Define a simple Q&A dataset with questions and expected answers
eval_dataset = [
    {
        "inputs": {"question": "What is the capital of France?"},
        "expectations": {"expected_response": "Paris"},
    },
    {
        "inputs": {"question": "Who was the first person to build an airplane?"},
        "expectations": {"expected_response": "Wright Brothers"},
    },
    {
        "inputs": {"question": "Who wrote Romeo and Juliet?"},
        "expectations": {"expected_response": "William Shakespeare"},
    },
]

第 5 步：使用评分器 (Scorers) 定义评估标准

评分器 (Scorer) 是一个函数，用于根据各种评估标准计算给定输入-输出对的得分。你可以使用 MLflow 为常见评估标准提供的内置评分器，也可以创建自己的自定义评分器。

python
from mlflow.genai import scorer
from mlflow.genai.scorers import Correctness, Guidelines


@scorer
def is_concise(outputs: str) -> bool:
    """Evaluate if the answer is concise (less than 5 words)"""
    return len(outputs.split()) <= 5


scorers = [
    Correctness(),
    Guidelines(name="is_english", guidelines="The answer must be in English"),
    is_concise,
]

这里我们使用三个评分器

Correctness（正确性）：使用数据集中的 "expected_response" 字段评估答案在事实上是否正确。
Guidelines（准则）：评估答案是否符合给定的准则。
is_concise：使用 scorer 装饰器定义的自定义评分器，用于判断答案是否简洁（少于 5 个单词）。

前两个评分器使用 LLM 来评估响应，即所谓的 LLM-as-a-Judge（以 LLM 作为裁判）。这是一种评估响应质量的强大技术，因为它能为复杂的语言任务提供类似人类的评估，同时比人工评估更具可扩展性和成本效益。

评分器接口允许你以简单的方式为你的应用程序定义各种类型的质量指标。从简单的自然语言准则到能够完全控制评估逻辑的代码函数均可实现。

提示

用于 Correctness 和 Guidelines 等“LLM-as-a-Judge”评分器的默认模型是 OpenAI 的 gpt-4o-mini。MLflow 通过内置适配器支持所有主流 LLM 提供商，如 Anthropic、Bedrock、Google、xAI 等。

为裁判模型使用不同模型提供商的示例

python
# Anthropic
Correctness(model="anthropic:/claude-sonnet-4-20250514")

# Bedrock (Anthropic on Bedrock)
Correctness(model="bedrock:/anthropic.claude-sonnet-4-20250514")

# Bedrock (Amazon Nova)
Correctness(model="bedrock:/amazon.nova-pro-v1:0")
Correctness(model="bedrock:/amazon.nova-lite-v1:0")
Correctness(model="bedrock:/amazon.nova-micro-v1:0")

# Google
Correctness(model="gemini:/gemini-2.5-flash")

# xAI
Correctness(model="xai:/grok-2-latest")

第 6 步：运行评估

现在我们拥有了评估的所有三个组件：数据集、预测函数和评分器。让我们运行评估吧！

python
# Run evaluation
if __name__ == "__main__":
    results = mlflow.genai.evaluate(
        data=eval_dataset,
        predict_fn=qa_predict_fn,
        scorers=scorers,
    )

现在运行你的评估脚本

uv
Python

shell
uv run --with openai,mlflow quickstart_eval.py

shell
python quickstart_eval.py

完整脚本

以下是完整的 quickstart_eval.py 以供参考

查看完整脚本

python
# quickstart_eval.py
import os
import mlflow
from openai import OpenAI
from mlflow.genai import scorer
from mlflow.genai.scorers import Correctness, Guidelines

# Use different env variable when using a different LLM provider
os.environ["OPENAI_API_KEY"] = "your-api-key-here"
mlflow.set_experiment("Evaluation Quickstart")

# Your agent implementation
client = OpenAI()


def my_agent(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant. Answer questions concisely.",
            },
            {"role": "user", "content": question},
        ],
    )
    return response.choices[0].message.content


# Wrapper function for evaluation
def qa_predict_fn(question: str) -> str:
    return my_agent(question)


# Evaluation dataset
eval_dataset = [
    {
        "inputs": {"question": "What is the capital of France?"},
        "expectations": {"expected_response": "Paris"},
    },
    {
        "inputs": {"question": "Who was the first person to build an airplane?"},
        "expectations": {"expected_response": "Wright Brothers"},
    },
    {
        "inputs": {"question": "Who wrote Romeo and Juliet?"},
        "expectations": {"expected_response": "William Shakespeare"},
    },
]


# Scorers
@scorer
def is_concise(outputs: str) -> bool:
    return len(outputs.split()) <= 5


scorers = [
    Correctness(),
    Guidelines(name="is_english", guidelines="The answer must be in English"),
    is_concise,
]

# Run evaluation
if __name__ == "__main__":
    results = mlflow.genai.evaluate(
        data=eval_dataset,
        predict_fn=qa_predict_fn,
        scorers=scorers,
    )

运行上述代码后，转到 MLflow UI 并导航到“Evaluation Quickstart”实验。你将看到评估结果以及每个评分器的详细指标。

通过点击表中的每一行，你可以查看得分背后的详细基本原理以及预测的跟踪记录。

你也可以比较评估运行情况。点击（左侧的）“Evaluation runs”菜单，选择你想要与基准运行进行比较的运行。

总结

恭喜！您已成功

✅ 为你的应用程序设置 MLflow 评估
✅ 使用内置评分器评估了问答应用程序
✅ 创建了自定义评估准则
✅ 学会了在 MLflow UI 中分析结果

MLflow 的评估框架提供了用于评估 LLM 应用程序和 AI 智能体质量的综合工具，帮助你构建更可靠、更有效的 AI 系统。

前提条件​

第 1 步：设置环境​

第 2 步：创建评估脚本​

第 3 步：定义模拟智能体的预测函数​

第 4 步：准备评估数据集​

第 5 步：使用评分器 (Scorers) 定义评估标准​

第 6 步：运行评估​

完整脚本​

总结​