エージェント評価の入力スキーマ

重要

この機能はパブリック プレビュー段階にあります。

この記事では、アプリケーションの品質、コスト、待機時間を評価するためにエージェント評価で必要な入力スキーマについて説明します。

• 開発中は、評価はオフラインで行われ、評価セットはエージェント評価に必要な入力です。
• アプリケーションが運用環境にある場合、Agent Evaluation へのすべての入力は、推論テーブルまたは運用ログから取得されます。

入力スキーマは、オンライン評価とオフライン評価の両方で同じです。

評価セットの一般的な情報については、「 評価セットを参照してください。

評価入力スキーマ

次の表に、エージェント評価の入力スキーマを示します。 テーブルの最後の 2 つの列は、 mlflow.evaluate() 呼び出しに対する入力の提供方法を示します。 詳細については、「 評価実行への入力方法 を参照してください。

列	データ型	説明	入力引数として渡されるアプリケーション	以前に生成された出力が提供されました
request_id	string	要求の一意識別子。	省略可能	省略可能
request	「要求のスキーマ」をご覧ください。	評価するアプリケーションへの入力、ユーザーの質問またはクエリ。 たとえば、 {'messages': [{"role": "user", "content": "What is RAG"}]} や "RAG とは何か?" などです。 requestが文字列として指定されると、エージェントに渡される前にmessagesに変換されます。	必須	必須
応答	string	評価対象のアプリケーションによって生成される応答。	エージェント評価によって生成される	省略可能。 未指定の場合は、トレースから生成。 response または trace が必須。
expected_facts	文字列の配列	モデル出力で予想されるファクトの一覧。 expected_factsガイドラインを参照してください。	省略可能	省略可能
expected_response	string	入力要求に対する正確な (正しい) 回答。 「expected_response ガイドライン」を参照してください。	省略可能	省略可能
expected_retrieved_context	配列	要求に対して想定される取得コンテキストを含むオブジェクトの配列 (アプリケーションに取得ステップが含まれる場合)。 配列スキーマ	省略可能	省略可能
retrieved_context	配列	評価対象のアプリケーション内の取得コンポーネントによって生成された取得結果。 アプリケーション内に複数の取得ステップがある場合、これが (トレース内で時系列的に) 最後のステップからの取得結果です。 配列スキーマ	エージェント評価によって生成される	省略可能。 未指定の場合は、指定されたトレースから生成。
trace	MLflow トレースの JSON 文字列	対応する要求に対するアプリケーションの実行の MLflow トレース。	エージェント評価によって生成される	省略可能。 response または trace が必須。

expected_facts ガイドライン

expected_facts フィールドは、特定の入力要求に対する適切なモデル応答に表示されることが予想されるファクトの一覧を指定します。 つまり、応答の表現方法に関係なく、モデルの応答にこれらの事実が含まれている場合は正しいと見なされます。

必要な事実のみを含め、答えに厳密に要求されない事実を除外することで、Agent Evaluation は出力品質に関するより堅牢な信号を提供できます。

expected_factsとexpected_responseのいずれかを指定できます。 両方を指定すると、エラーが報告されます。 Databricks では、生成された応答の品質をより効果的に判断するのに役立つより具体的なガイドラインであるため、 expected_factsを使用することをお勧めします。

expected_response ガイドライン

expected_response フィールドには、正しいモデル応答の参照を表す完全形式の応答が含まれています。 つまり、モデルの応答は、 expected_responseの情報コンテンツと一致すると正しいと見なされます。 これに対し、 expected_facts は、正しい応答で表示する必要があり、完全な形式の参照応答ではないファクトのみを一覧表示します。

expected_factsと同様に、expected_responseには、正しい応答に必要な最小限のファクト セットのみを含める必要があります。 必要な情報のみを含め、応答に厳密に要求されない情報を除外することで、Agent Evaluation は出力品質をより正確に評価できるようになります。

expected_factsとexpected_responseのいずれかを指定できます。 両方を指定すると、エラーが報告されます。 Databricks では、生成された応答の品質をより効果的に判断するのに役立つより具体的なガイドラインであるため、 expected_factsを使用することをお勧めします。

要求のスキーマ

要求スキーマには、次のいずれかを指定できます。

• OpenAI チャット完了スキーマ。 OpenAI チャット完了スキーマには、 messages パラメーターとしてオブジェクトの配列が必要です。 messages フィールドは、会話全体をエンコードできます。
• エージェントが OpenAI チャット完了スキーマをサポートしている場合は、プレーン文字列を渡すことができます。 この形式では、単一ターンの会話のみがサポートされます。 プレーン文字列は、エージェントに渡される前に、"role": "user"を使用してmessages形式に変換されます。 たとえば、プレーン文字列 "What is MLflow?" は、エージェントに渡される前に {"messages": [{"role": "user", "content": "What is MLflow?"}]} に変換されます。
• SplitChatMessagesRequest. 最新の要求の query 文字列フィールドと、会話の以前のターンをエンコードする省略可能な history フィールド。

マルチターン チャット アプリケーションの場合は、上記の 2 番目または 3 番目のオプションを使用します。

次の例は、3 つのオプションすべてを評価データセットの同じ 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."
              }
          ]
      }
  ],

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

eval_dataset = pd.DataFrame(data)

評価入力の配列のスキーマ

配列 expected_retrieved_context と retrieved_context のスキーマを次の表に示します。

列	データ型	説明	入力引数として渡されるアプリケーション	以前に生成された出力の指定
content	string	取得したコンテキストの内容。 HTML、プレーン テキスト、Markdown などの任意の形式の文字列。	省略可能	省略可能
doc_uri	string	チャンクが由来する親ドキュメントの一意識別子 (URI)。	必須	必須

計算されたメトリック

次の表の列は入力に含まれるデータを示し、 ✓ は、そのデータが提供されたときにメトリックがサポートされていることを示しています。

これらのメトリックが測定する内容の詳細については、「 エージェント評価で品質、コスト、待機時間を評価する方法を参照してください。

計算されるメトリック	request	request および expected_response	request、expected_response、expected_retrieved_context	request および expected_retrieved_context
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			✓	✓