Agent Evaluation 入力スキーマ (MLflow 2)

重要

Databricks では、GenAI アプリの評価とモニタリングに MLflow 3 の使用を推奨しています。このページでは、MLflow 2 の Agent Evaluation について説明します。

MLflow 3での評価とモニタリングの概要については、AIエージェントの評価とモニタリングを参照してください。
MLflow 3への移行に関する情報については、Agent EvaluationからMLflow 3への移行を参照してください。
このトピックに関するMLflow 3の情報については、「MLflow評価データセットの構築」を参照してください。

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

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

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

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

評価入力スキーマ

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

列	データ型	説明	入力引数として渡されたアプリケーション	提供された以前の生成出力
request_id	string	リクエストの一意の識別子。	オプション	オプション
request	リクエストのスキーマを参照してください。	評価するアプリケーションへの入力、ユーザーの質問またはクエリ。例えば、`{'messages': [{"role": "user", "content": "What is RAG"}]}` または「What is RAG？」。`request` が文字列として提供される場合、エージェントに渡される前に `messages` に変換されます。	必須	必須
応答	応答のスキーマを参照してください。	評価中のアプリケーションによって生成された応答。	エージェント評価によって生成	オプション。指定されていない場合は、トレースから派生します。`response`または`trace`のいずれかが必要です。
予想される事実。	文字列の配列	モデル出力で期待される事実のリストです。`expected_facts`ガイドラインを参照してください。	オプション	オプション
expected_response	string	入力リクエストに対するグラウンドトゥルース (正解) の回答。`expected_response`ガイドラインを参照してください。	オプション	オプション
ガイドライン	`guidelines` ガイドライン	モデルの出力が準拠することが期待される、名前付きのディクショナリまたはガイドラインのリスト。`guidelines`ガイドラインを参照してください。	オプション	オプション
expected_retrieved_context	array	リクエストに対して期待される取得されたコンテキストを含むオブジェクトの配列（アプリケーションに検索ステップが含まれる場合）。配列スキーマ	オプション	オプション
retrieved_context	array	評価対象のアプリケーションのリトリーバーによって生成された検索結果。アプリケーションに複数の取得ステップがある場合、これは最後のステップからの取得結果です（トレース内で時系列的に）。配列スキーマ	エージェント評価によって生成	オプション。提供されていない場合は、提供されたトレースから派生します。
trace	MLフロートレースのJSON文字列	対応するリクエストに対するアプリケーションの実行のMLflowトレース。	エージェント評価によって生成	オプション。`response`または`trace`のいずれかが必要です。

`expected_facts` ガイドライン

expected_facts フィールドは、特定の入力リクエストに対する正しいモデル応答に表示されると予想される事実のリストを指定します。つまり、モデルの応答がこれらの事実を含んでいる場合、その応答の表現方法にかかわらず、正しいと見なされます。

必要な事実のみを含め、回答に厳密には必要ない事実を除外することで、Agent Evaluation は出力品質についてより堅牢なシグナルを提供できます。

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

`guidelines` ガイドライン

guidelinesフィールドは、正しいモデル応答が順守しなければならない一連のガイドラインを指定します。guidelinesは、2つの形式で表現できます。

ガイドラインのリスト (List[str]) は、単一のガイドラインセットを提供します。
名前付きガイドライン（Dict[str, List[str]]）は、ガイドラインの名前からその名前のガイドラインの配列へのマッピングを提供します。名前付きガイドラインにはdatabricks-agents >= 0.16.0が必要です。

ガイドラインは、応答のスタイルやコンテンツに関連する要素など、様々な特性を参照できます。ガイドラインへの準拠に関する最も堅牢なシグナルを得るために、Databricksは以下の表現を使用することを推奨しています。

「応答は…」
「応答は...であってはなりません。」
「応答は任意で…」

具体的には、リクエストとレスポンスを直接参照し、ガイドラインの曖昧さを可能な限り少なくしてください。応答のトーンがプロフェッショナルであることや、常に英語であることなどを保証するなど、評価セット全体に適用されるガイドラインについては、評価ツールの設定で global_guidelines パラメーターを次のように使用します。

Python
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={
        &quot;databricks-agent&quot;: {
            # Note: You can also just pass an array to `guidelines`.
            &quot;global_guidelines&quot;: {
                &quot;english&quot;: [&quot;The response must be in English&quot;],
                &quot;clarity&quot;: [&quot;The response must be clear, coherent, and concise&quot;],
            }
        }
    }
)

`expected_response` ガイドライン

expected_responseフィールドには、正しいモデル応答の参照となる完全に形成された応答が含まれています。つまり、モデルの応答がexpected_responseの情報コンテンツと一致する場合、その応答は正しいと見なされます。対照的に、expected_factsは正しい応答に表示される必要のある事実のみをリストしており、完全に形成された参照応答ではありません。

expected_factsと同様に、expected_responseには正しい応答に必要な最小限の事実のみを含めるべきです。必要な情報のみを含め、回答に厳密には必要ない情報を除外すると、Agent Evaluationが出力品質に関するより堅牢なシグナルを提供できるようになります。

要求のスキーマ

リクエストスキーマは次のいずれかです：

任意のシリアル化可能な辞書（例：Dict[str, Any]）
エージェントがOpenAIチャット補完スキーマをサポートしている場合は、プレーン文字列を渡すことができます。この形式は、1ターンの会話のみをサポートします。プレーン文字列は、エージェントに渡される前に"role": "user"でmessages形式に変換されます。たとえば、プレーン文字列"What is MLflow?"は、エージェントに渡される前に{"messages": [{"role": "user", "content": "What is MLflow?"}]}に変換されます。

組み込みのジャッジは、OpenAIチャット補完スキーマを使用する任意の形式で最適に機能することに注意してください。OpenAIチャット補完スキーマには、messagesパラメーターとしてオブジェクトの配列が必要です。messagesフィールドは会話全体をエンコードできます。

次の例は、評価データセットの同じrequest列のいくつかの利用可能なオプションを示しています。

Python
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チャット補完スキーマをサポートしている場合は、プレーン文字列を渡すことができます。この形式は、1ターンの会話のみをサポートします。プレーンな文字列はchoices形式に変換されます。例えば、プレーンな文字列"MLFlow is a framework."は{"choices": [{"message": {"content": "MLFlow is a framework."}}]}に変換されます。

評価入力における配列のスキーマ

配列expected_retrieved_contextとretrieved_contextのスキーマは以下の表の通りです：

列	データ型	説明	入力引数として渡されたアプリケーション	提供された以前の生成出力
コンテンツ	string	取得したコンテキストの内容。HTML、プレーンテキスト、Markdownなどの任意の形式の文字列。	オプション	オプション
doc_uri	string	チャンクの元となった親ドキュメントの一意の識別子（URI）。	必須	必須

コンピュートされたメトリクス

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

これらのメトリクスが何を測定するかの詳細については、「Agent Evaluationによる品質、コスト、およびレイテンシの評価方法 (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`			✓		✓

評価入力スキーマ​

expected_facts ガイドライン​

guidelines ガイドライン​

expected_response ガイドライン​

要求のスキーマ​

応答のスキーマ​

評価入力における配列のスキーマ​

コンピュートされたメトリクス​