代理程式評估輸入架構（MLflow 2）

2025-06-11

這很重要

此頁面說明使用 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_response` 指導方針。	選擇性	選擇性
準則	`guidelines` 指引	模型輸出應遵守的具名字典或指南清單。請參閱 `guidelines` 指導方針。	選擇性	選擇性
預期檢索內容上下文	陣列	物件的陣列，其中包含要求的預期擷取內容 (如果應用程式包含擷取步驟)。陣列結構	選擇性	選擇性
檢索到的內容	陣列	正在評估之應用程式中擷取器所產生的擷取結果。如果應用程式中有多個擷取步驟，這是最後一個步驟的擷取結果 (依時間順序在追蹤中)。陣列結構	由代理程式評估產生	選擇性。如果未提供，則從提供的追蹤資料中衍生。
追蹤	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_facts類似，expected_response 應該只包含正確回應所需的最少事實集。只包含必要資訊，並排除答案中並非嚴格要求的資訊，可讓代理程式評估在輸出品質上提供更強固的訊號。

架構要求

要求架構可以是下列其中一項：

任意可串行化字典（例如，Dict[str, Any]）
如果代理程式支援 OpenAI 聊天完成架構，您可以傳遞純字串。此格式僅支援單一回合交談。在傳遞至您的代理程式之前，一般字串會使用 messages 轉換為 "role": "user" 格式。例如，在傳遞至代理程式之前，會先將純字串 "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 方針