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

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

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

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

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

評価入力スキーマ

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

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

expected_facts ガイドライン

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

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

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

guidelines ガイドライン

guidelines フィールドは、正しいモデル応答が従う必要がある一連のガイドラインを指定します。guidelines は、次の 2 つの形式で表すことができます。

• ガイドラインのリスト (List[str]) は、単一のガイドライン セットを提供します。
• 名前付きガイドライン (Dict[str, List[str]]) は、 guideline の名前を、その名前のガイドラインの配列にマッピングします。 名前付きガイドラインには 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={
        "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 には、正しい応答に必要な最小限のファクトのセットのみを含める必要があります。必要な情報のみを含め、回答に厳密に必要でない情報を省略することで、Agent Evaluation は出力品質に関するより堅牢なシグナルを提供できます。

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

要求のスキーマ

要求スキーマは、次のいずれかになります。

• 任意の直列化可能なディクショナリ ( 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）。	必須	必須

コンピュート メトリクス

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

これらのメトリクスの測定内容の詳細については 、「エージェント評価による品質、コスト、およびレイテンシーの評価方法」を参照してください。

計算されたメトリクス	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			✓		✓