共用方式為

代理評估輸入架構

  • 發行項

重要

這項功能處於公開預覽狀態。

本文說明代理程式評估所需的輸入架構，以評估應用程式的品質、成本和延遲。

  • 在開發期間，評估會離線進行，且評估集是代理程式評估的必要輸入。
  • 當應用程式在生產環境中時，代理程式評估的所有輸入都來自推斷數據表或生產記錄。

在線和離線評估的輸入架構都相同。

如需評估集的一般資訊，請參閱 評估集。

評估輸入架構

下表顯示代理程式評估的輸入架構。 數據表的最後兩欄指的是如何將輸入提供給 mlflow.evaluate() 呼叫。 如需詳細資訊，請參閱 提供評估回合 的輸入。

列 資料類型 描述 傳遞為輸入自變數的應用程式 先前提供的輸出
request_id 字串 要求的唯一標識碼。 選擇性 選擇性
要求 如需要求，請參閱 架構。 要評估的應用程式輸入、使用者的問題或查詢。 例如， {'messages': [{"role": "user", "content": "What is RAG"}]} 或「什麼是RAG？」。 當 以字串的形式提供時 request ，它會在傳遞至代理程式之前將其轉換成 messages 。 必要 必要
回覆 如需回應 ，請參閱架構。 評估應用程式所產生的回覆。 由代理程式評估產生 選擇性。 如果未提供，則衍生自追蹤。 (response 或 trace為必要項目。)
expected_facts 字串陣列 模型輸出中預期的事實清單。 請參閱 expected_facts 指導方針。 選擇性 選擇性
expected_response 字串 輸入要求的基準真相 (正確) 答案。 請參閱 expected_response 指導方針。 選擇性 選擇性
準則 guidelines 指導方針 模型輸出預期遵循的具名字典或指導方針清單。 請參閱 guidelines 指導方針。 選擇性 選擇性
expected_retrieved_context 陣列 物件的陣列，其中包含要求的預期擷取內容 (如果應用程式包含擷取步驟)。 陣列架構 選擇性 選擇性
retrieved_context 陣列 正在評估之應用程式中擷取器所產生的擷取結果。 如果應用程式中有多個擷取步驟，這是最後一個步驟的擷取結果 (依時間順序在追蹤中)。 陣列架構 由代理程式評估產生 選擇性。 如果未提供，則衍生自提供的追蹤。
追蹤 MLflow 追蹤的 JSON 字串 對應要求上應用程式執行的 MLflow 追蹤。 由代理程式評估產生 選擇性。 (response 或 trace為必要項目。)

expected_facts 方針

[expected_facts] 字段會指定預期出現在特定輸入要求的任何正確模型回應中的事實清單。 也就是說，如果模型回應包含這些事實，則不論回應的片語方式為何，都會被視為正確。

只包含必要事實，並排除答案中並非嚴格要求的事實，可讓代理程式評估在輸出品質上提供更強固的訊號。

您最多可以指定和 的expected_factsexpected_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 應該只包含正確回應所需的最少事實集。 只包含必要資訊，並排除答案中並非嚴格要求的資訊，可讓代理程式評估在輸出品質上提供更強固的訊號。

您最多可以指定和 的expected_factsexpected_response其中一個 。 如果您同時指定兩者，則會報告錯誤。 Databricks 建議使用 expected_facts，因為它是更具體的指導方針，可協助代理程式評估更有效率地判斷產生的響應品質。

架構要求

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

  • 任意可串行化字典（例如，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 的架構：

列 資料類型 描述 傳遞為輸入引數的應用程式 先前提供的生成輸出
content 字串 擷取內容的內容。 任何格式的字串，例如 HTML、純文字或 Markdown。 選擇性 選擇性
doc_uri 字串 區塊的來源父檔的唯一標識碼 （URI）。 必要 必要

計算計量

下表中的欄位顯示輸入中包含的數據，而 ✓ 表示當提供該數據時，支援此指標。

如需這些計量量值的詳細資訊，請參閱 代理程式評估如何評估品質、成本和延遲。

計算計量 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 ✓ ✓