代理评估输入架构（MLflow 2）

2025-06-26

重要

本页介绍 MLflow 2 的代理评估版本的 0.22 用法。 Databricks 建议使用 MLflow 3，它与代理评估 >1.0 集成。在 MLflow 3 中，代理评估 API 现在是包的 mlflow 一部分。

有关本主题的信息，请参阅生成 MLflow 评估数据集。

本文介绍代理评估评估评估应用程序的质量、成本和延迟所需的输入架构。

在开发期间，评估会脱机进行，评估集是代理评估所需的输入。
当应用程序处于生产环境中时，代理评估的所有输入都来自推理表或生产日志。

对于联机和脱机评估，输入架构是相同的。

有关评估集的一般信息，请参阅评估集（MLflow 2）。

评估输入架构

下表显示了代理评估的输入架构。表的最后两列指示如何向 mlflow.evaluate() 调用提供输入。有关详细信息，请参阅向评估运行提供输入。

列	数据类型	说明	作为输入参数传递的应用程序	提供的先前生成的输出
请求ID	字符串	请求的唯一标识符。	可选	可选
请求	请参阅请求架构。	用于评估的应用程序输入，用户的问题或查询。例如，`{'messages': [{"role": "user", "content": "What is RAG"}]}` 或“什么是 RAG？”。 `request` 作为字符串提供时，它将在传递给代理之前转换为 `messages`。	必需	必需
响应	请参阅 “架构”以获取响应。	正在评估的应用程序生成的响应。	由代理评估生成	可选。如果未提供，则从跟踪派生。 `response` 或 `trace` 是必需的。
expected_facts	字符串数组	模型输出中预期的事实列表。请参阅 `expected_facts` 指南。	可选	可选
预期响应	字符串	输入请求的真实（正确）答案。请参阅 `expected_response` 指南。	可选	可选
指南	`guidelines` 指引	模型输出应遵循的命名字典或准则列表。请参阅 `guidelines` 指南。	可选	可选
expected_retrieved_context	数组	包含请求的预期检索上下文的对象数组（如果应用程序包含检索步骤）。数组架构	可选	可选
retrieved_context	数组	正在评估的应用程序中的检索器生成的检索结果。如果应用程序中有多个检索步骤，则这是最后一步（跟踪中按时间顺序排列）的检索结果。数组架构	由代理评估生成	可选。如果未提供，则从提供的跟踪派生。
trace	MLflow 跟踪的 JSON 字符串	应用程序对相应请求的执行的 MLflow 跟踪。	由代理评估生成	可选。 `response` 或 `trace` 是必需的。

`expected_facts` 指南

expected_facts 字段指定预期出现在特定输入请求的任何正确模型响应中的事实列表。也就是说，如果模型响应包含这些事实，则视为正确，而不考虑其表述方式。

仅包括所需的事实，并排除答案中不严格要求的事实，这使代理评估能够提供更可靠的输出质量信号。

最多可以指定 expected_facts 和 expected_response 其中一个。如果同时指定这两者，将报告错误。 Databricks 建议使用 expected_facts，因为它是更具体的准则，可帮助代理评估更有效地判断生成的响应的质量。

`guidelines` 指南

该 guidelines 字段指定了任何正确模型响应必须遵循的一组准则。 guidelines 可以用两种格式表示：

准则列表（List[str]）提供一组准则。
命名准则 (Dict[str, List[str]]) 提供准则名称与该名称的准则数组的映射。命名准则需要 databricks-agents >= 0.16.0。

准则可以引用响应的各种特征，包括风格或内容相关的元素。对于准则遵循情况最可靠的信号，Databricks 建议使用以下语言：

“响应必须...”
“响应不得...”
“响应可能可选...”

具体而言，应直接引用请求和响应，并在指南中尽可能少地保留歧义。关于适用于整个评估集的指南（例如，确保响应始终具有专业语气或使用英语），请在评估器配置中使用 global_guidelines 参数，如下所示：

eval_set = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
        # Note: You can also just pass an array to `guidelines`.
        "guidelines": {
            "english": ["The response must be in English"],
            "clarity": ["The response must be clear, coherent, and concise"],
        }
    }
]

mlflow.evaluate(
    data=pd.DataFrame(eval_set),
    model_type="databricks-agent",
    evaluator_config={
        "databricks-agent": {
            # Note: You can also just pass an array to `guidelines`.
            "global_guidelines": {
                "english": ["The response must be in English"],
                "clarity": ["The response must be clear, coherent, and concise"],
            }
        }
    }
)

`expected_response` 指南

expected_response 字段包含一个完整的响应，表示正确模型响应的参考。也就是说，如果模型响应与 expected_response 中的信息内容匹配，则被视为正确。相比之下，expected_facts 仅列出在正确响应中需要出现的事实，而不是完整的参考响应。

expected_response 类似于 expected_facts，应仅包含正确响应所需的最小事实集。仅包括所需的信息，并排除不在回答中严格要求的信息，这使代理评估能够提供更可靠的输出质量信号。

请求架构

请求架构可以是下列项之一：

任意可序列化字典（例如 Dict[str, Any]）
如果代理支持 OpenAI 聊天补全架构，则可以传递纯字符串。此格式仅支持单轮对话。在传递给代理之前，纯字符串将通过 "role": "user" 转换为 messages 格式。例如，在传递给代理之前，纯字符串 "What is MLflow?" 将转换为 {"messages": [{"role": "user", "content": "What is MLflow?"}]}。

请注意，内置评审最适合使用 OpenAI 聊天补全架构的任何格式。 OpenAI 聊天补全架构必须具有一个对象数组作为 messages 参数。 messages 字段可以对完整对话进行编码。

以下示例显示了评估数据集的同 request 一列中的几个可能选项：

import pandas as pd

data = {
  "request": [

      # Plain string. Plain strings are transformed to the `messages` format before being passed to your agent.
      "What is the difference between reduceByKey and groupByKey in Spark?",

      # OpenAI chat completion schema. Use the `messages` field for a single- or multi-turn chat.
      {
          "messages": [
              {
                  "role": "user",
                  "content": "How can you minimize data shuffling in Spark?"
              }
          ]
      },

      # SplitChatMessagesRequest. Use the `query` and `history` fields for a single- or multi-turn chat.
      {
          "query": "Explain broadcast variables in Spark. How do they enhance performance?",
          "history": [
              {
                  "role": "user",
                  "content": "What are broadcast variables?"
              },
              {
                  "role": "assistant",
                  "content": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine."
              }
          ]
      },

      # Arbitrary format. These must be JSON-serializable and are passed directly to your agent.
      {
        "message_history": [
            {
                "user_0": "What are broadcast variables?",
                "assistant_0": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine.",
            }
        ],
        "last_user_request": "How can you minimize data shuffling in Spark?"
      },
  ],

  "expected_response": [
    "expected response for first question",
    "expected response for second question",
    "expected response for third question",
    "expected response for fourth question",
  ]
}

eval_dataset = pd.DataFrame(data)

响应架构

响应架构（类似于请求架构）可以是以下项之一：

任意可序列化字典（例如 Dict[str, Any]）。
如果代理支持 OpenAI 聊天补全架构，则可以传递纯字符串。此格式仅支持单轮对话。纯字符串转换为 choices 格式。例如，将纯字符串 "MLFlow is a framework." 转换为 {"choices": [{"message": {"content": "MLFlow is a framework."}}]}。

评估输入中数组的架构

数组 expected_retrieved_context 和 retrieved_context 的架构如下表中所示：

列	数据类型	说明	作为输入参数传递的应用程序	提供的先前生成的输出
内容	字符串	检索到的上下文的内容。任意格式的字符串，例如 HTML、纯文本或 Markdown。	可选	可选
doc_uri	字符串	区块的来源父文档的唯一标识符 (URI)。	必需	必需

计算指标

下表中的列指示输入中包含的数据，✓ 指示提供该数据时支持该指标。

有关这些指标度量值的详细信息，请参阅代理评估（MLflow 2）如何评估质量、成本和延迟。

测算指标	`request`	`request` 和 `expected_response`	`request`、`expected_response`、`expected_retrieved_context`和 `guidelines`	`request` 和 `expected_retrieved_context`	`request` 和 `guidelines`
`response/llm_judged/relevance_to_query/rating`	✓	✓	✓
`response/llm_judged/safety/rating`	✓	✓	✓
`response/llm_judged/groundedness/rating`	✓	✓	✓
`retrieval/llm_judged/chunk_relevance_precision`	✓	✓	✓
`agent/total_token_count`	✓	✓	✓
`agent/input_token_count`	✓	✓	✓
`agent/output_token_count`	✓	✓	✓
`response/llm_judged/correctness/rating`		✓	✓
`retrieval/llm_judged/context_sufficiency/rating`		✓	✓
`retrieval/ground_truth/document_recall`			✓	✓
`response/llm_judged/guideline_adherence/rating`			✓		✓

通过

代理评估输入架构 （MLflow 2）

评估输入架构

expected_facts 指南

guidelines 指南

expected_response 指南