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

プレビュー

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

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

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

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

評価入力スキーマ

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

列	データ型	説明	入力引数として渡されるアプリケーション	提供された以前の生成出力
request_id	string	リクエストの一意の識別子。	オプション	オプション
request	要求のスキーマを参照してください。	評価するために、ユーザーの質問またはクエリをアプリケーションに入力します。たとえば、 `{'messages': [{"role": "user", "content": "What is RAG"}]}` や "RAG とは" などです。 `request` が文字列として指定されている場合、エージェントに渡される前に `messages` に変換されます。	必須	必須
response	string	評価対象のアプリケーションによって生成された応答。	エージェント評価によって生成	オプション。指定されていない場合は、トレースから派生します。`response`または`trace`のいずれかが必要です。
expected_facts	文字列の配列	モデル出力で想定されるファクトの一覧。 expected_factsガイドラインを参照してください。	オプション	オプション
expected_response	string	入力要求に対するグラウンドトゥルース (正しい) 回答。 expected_responseガイドラインを参照してください。	オプション	オプション
expected_retrieved_context	配列	要求に対して取得される予期されるコンテキストを含むオブジェクトの配列 (アプリケーションに取得ステップが含まれている場合)。配列スキーマ	オプション	オプション
retrieved_context	配列	評価対象のアプリケーションで取得者によって生成された取得結果。アプリケーション内に複数の取得ステップがある場合、これは最後のステップ (トレース内の時系列) からの取得結果です。配列スキーマ	エージェント評価によって生成	オプション。提供されていない場合は、提供されたトレースから派生します。
trace	MLフロートレースの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チャット完了スキーマをサポートしている場合は、プレーンな文字列を渡すことができます。この形式では、1 ターンの会話のみがサポートされています。プレーンな文字列は、エージェントに渡される前に、"role": "user" を含む messages 形式に変換されます。たとえば、プレーンな文字列 "What is MLflow?" は、エージェントに渡される前に {"messages": [{"role": "user", "content": "What is MLflow?"}]} に変換されます。
SplitChatMessagesRequest.最新の要求の query 文字列フィールドと、会話の前のターンをエンコードするオプションの history フィールド。

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

次の例は、評価データセットの同じ request 列にある 3 つのオプションすべてを示しています。

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のスキーマは以下の表の通りです：

列	データ型	説明	入力引数として渡されるアプリケーション	提供された以前の生成出力
コンテンツ	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`			✓	✓