Eingabeschema für die Agentauswertung (MLflow 2)

2025-06-27

Von Bedeutung

Auf dieser Seite wird die Verwendung der Agentauswertungsversion 0.22 mit MLflow 2 beschrieben. Databricks empfiehlt die Verwendung von MLflow 3, die in die Agent-Auswertung >1.0integriert ist. In MLflow 3 sind Die Agentauswertungs-APIs jetzt Teil des mlflow Pakets.

Informationen zu diesem Thema finden Sie unter Building MLflow Evaluation Datasets.

In diesem Artikel wird das eingabeschema erläutert, das von der Agentauswertung benötigt wird, um die Qualität, Kosten und Latenz Ihrer Anwendung zu bewerten.

Während der Entwicklung erfolgt die Auswertung offline, und ein Evaluierungssatz ist eine erforderliche Eingabe für die Agentenauswertung.
Wenn sich eine Anwendung in der Produktion befindet, stammen alle Eingaben zur Agent-Auswertung aus Ihren Rückschlusstabellen oder Produktionsprotokollen.

Das Eingabeschema ist sowohl für Online- als auch offline-Auswertungen identisch.

Allgemeine Informationen zu Auswertungssätzen finden Sie unter Evaluierungssätze (MLflow 2).For general information about evaluation sets, see Evaluation sets (MLflow 2).

Auswertungseingabeschema

Die folgende Tabelle zeigt das Eingabeschema der Agentenbewertung. Die letzten beiden Spalten der Tabelle beziehen sich auf die Bereitstellung von Eingaben für den mlflow.evaluate() Aufruf. Weitere Informationen finden Sie unter Bereitstellen von Eingaben für eine Auswertungsausführung.

Spalte	Datentyp	Beschreibung	Als Eingabeargument übergebene Anwendung	Zuvor generierte Ausgaben
Anfrage_ID	string	Eindeutiger Bezeichner der Anforderung.	Wahlfrei	Wahlfrei
Anfrage	Weitere Informationen finden Sie unter Schema für Anforderungen.	Eingabe in die Anwendung zur Auswertung, Frage oder Abfrage des Benutzers. Zum Beispiel: `{'messages': [{"role": "user", "content": "What is RAG"}]}` "Was ist RAG?". Wenn `request` sie als Zeichenfolge angegeben wird, wird sie transformiert `messages`, bevor sie an Ihren Agent übergeben wird.	Erforderlich	Erforderlich
Antwort	Siehe Schema für Antwort.	Antwort, die von der zu bewertenden Anwendung generiert wurde.	Generiert durch Agent-Auswertung	Wahlfrei. Wenn dies nicht angegeben wird, wird sie von der Ablaufverfolgung abgeleitet. Entweder `response` oder `trace` ist erforderlich.
erwartete_Fakten	Array von Zeichenfolgen	Eine Liste der Fakten, die in der Modellausgabe erwartet werden. Siehe `expected_facts` Richtlinien.	Wahlfrei	Wahlfrei
erwartete_Antwort	string	Grundwahrheitsantwort (richtig) auf die Eingabeanforerung. Siehe `expected_response` Richtlinien.	Wahlfrei	Wahlfrei
Leitlinien	`guidelines` Leitlinien	Ein benannter Dict oder eine Liste von Richtlinien, an die sich die Ausgabe des Modells halten soll. Siehe `guidelines` Richtlinien.	Wahlfrei	Wahlfrei
erwarteter_abgerufener_Kontext	Array	Array von Objekten, die den erwarteten abgerufenen Kontext für die Anforderung enthalten (falls die Anwendung einen Abrufschritt enthält). Array-Schema	Wahlfrei	Wahlfrei
abgerufener Kontext	Array	Abrufergebnisse, die vom Retriever in der zu bewertenden Anwendung generiert werden. Wenn sich mehrere Abrufschritte in der Anwendung befinden, ist dies das Abrufergebnis aus dem letzten Schritt (chronologisch in der Ablaufverfolgung). Array-Schema	Generiert durch Agent-Auswertung	Wahlfrei. Wenn dies nicht angegeben wird, wird sie von der bereitgestellten Ablaufverfolgung abgeleitet.
Ablaufverfolgung	JSON-Zeichenfolge der MLflow-Ablaufverfolgung	MLflow-Trace der Ausführung der Anwendung auf die entsprechende Anfrage.	Generiert durch Agent-Auswertung	Wahlfrei. Entweder `response` oder `trace` ist erforderlich.

`expected_facts` Richtlinien

Das expected_facts Feld gibt die Liste der Fakten an, die in jeder korrekten Modellantwort für die spezifische Eingabeanforderung angezeigt werden sollen. Das heißt, eine Modellantwort gilt als richtig, wenn sie diese Fakten enthält, unabhängig davon, wie die Antwort formuliert wird.

Wenn Sie nur die erforderlichen Fakten einschließen und Fakten, die in der Antwort nicht unbedingt erforderlich sind, können Agentenauswertung ein robusteres Signal für die Ausgabequalität bereitstellen.

Sie können höchstens eine von expected_facts und expected_response angeben. Wenn Sie beide angeben, wird ein Fehler gemeldet. Databricks empfiehlt die Verwendung expected_facts, da es sich um eine spezifischere Richtlinie handelt, die Agent Evaluation hilft, die Qualität der generierten Antworten effektiver zu beurteilen.

`guidelines` Richtlinien

Das guidelines Feld gibt eine Reihe von Richtlinien an, die von allen korrekten Modellantworten eingehalten werden müssen. guidelines kann in zwei Formaten ausgedrückt werden:

Liste der Richtlinien (List[str]) stellt eine einzige Reihe von Richtlinien bereit.
Benannte Richtlinien (Dict[str, List[str]]) bieten die Zuordnung eines Richtliniennamens zu einem Array von Richtlinien für diesen Namen. Benannte Richtlinien erfordern databricks-agents >= 0.16.0.

Richtlinien können sich auf verschiedene Merkmale der Antwort beziehen, einschließlich stilistischer oder inhaltsbezogener Elemente. Für das robusteste Signal zur Richtlinientreue empfiehlt Databricks die Verwendung der folgenden Sprache:

„Die Antwort muss …“
"Die Antwort darf nicht ..."
„Optional kann die Antwort …“

Insbesondere sollten Sie direkt auf die Anfrage und Antwort verweisen und in den Richtlinien so wenig Mehrdeutigkeit wie möglich hinterlassen. Verwenden Sie für Richtlinien, die für Ihren gesamten Auswertungssatz gelten, z. B. dass die Antworten einen professionellen Ton haben oder immer in Englisch sind, den global_guidelines Parameter in der Evaluator-Konfiguration wie folgt:

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` Richtlinien

Das expected_response Feld enthält eine vollständig gebildete Antwort, die einen Verweis für die richtigen Modellantworten darstellt. Das heißt, eine Modellantwort gilt als richtig, wenn sie mit dem Informationsinhalt expected_responseübereinstimmt. Im Gegensatz dazu werden nur die Fakten aufgelistet, expected_facts die in einer korrekten Antwort angezeigt werden müssen und keine vollständig gebildete Referenzantwort ist.

Ähnlich wie expected_facts, expected_response sollte nur die minimale Menge von Fakten enthalten, die für eine korrekte Antwort erforderlich sind. Wenn Sie nur die erforderlichen Informationen einschließen und Informationen auslassen, die in der Antwort nicht unbedingt erforderlich sind, ermöglicht die Agent-Auswertung ein robusteres Signal für die Ausgabequalität.

Schema für Anforderung

Das Anforderungsschema kann Folgendes sein:

Ein beliebiges serialisierbares Wörterbuch (z. B Dict[str, Any]. )
Wenn der Agent das OpenAI-Chatabschlussschema unterstützt, können Sie eine einfache Zeichenfolge übergeben. Dieses Format unterstützt nur Unterhaltungen mit nur einer Wendung. Einfache Zeichenfolgen werden in das messages Format konvertiert, bevor "role": "user" sie an Ihren Agent übergeben werden. Beispielsweise wird eine einfache Zeichenfolge vor der Übergabe an Ihren Agent in "What is MLflow?" eine einfache Zeichenfolge {"messages": [{"role": "user", "content": "What is MLflow?"}]} konvertiert.

Beachten Sie, dass die integrierten Richter am besten mit jedem Format mit einem OpenAI-Chatabschlussschema arbeiten. Das OpenAI-Chatabschlussschema muss ein Array von Objekten als messages Parameter aufweisen. Das messages Feld kann die vollständige Unterhaltung codieren.

Das folgende Beispiel zeigt einige mögliche Optionen in derselben request Spalte des Auswertungsdatensets:

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)

Schema für Antwort

Das Antwortschema, ähnlich dem Anforderungsschema, kann eine der folgenden Sein:

Ein beliebiges serialisierbares Wörterbuch (z. B Dict[str, Any]. ).
Wenn der Agent das OpenAI-Chatabschlussschema unterstützt, können Sie eine einfache Zeichenfolge übergeben. Dieses Format unterstützt nur Unterhaltungen mit nur einer Wendung. Einfache Zeichenfolgen werden in das choices Format konvertiert. Beispielsweise wird eine einfache Zeichenfolge "MLFlow is a framework." in {"choices": [{"message": {"content": "MLFlow is a framework."}}]} umgewandelt.

Schema für Arrays in der Bewertungseingabe

Das Schema der Arrays expected_retrieved_context und retrieved_context wird in der folgenden Tabelle angezeigt:

Spalte	Datentyp	Beschreibung	Als Eingabeargument übergebene Anwendung	Zuvor generierte Ausgaben
Inhalt	string	Inhalt des abgerufenen Kontexts. Zeichenfolge in beliebigem Format, z. B. HTML, Nur-Text oder Markdown.	Wahlfrei	Wahlfrei
doc_uri	string	Eindeutiger Bezeichner (URI) des übergeordneten Dokuments, aus dem der Block stammt.	Erforderlich	Erforderlich

Berechnete Metriken

Die Spalten in der folgenden Tabelle geben die in der Eingabe enthaltenen Daten an und ✓ geben an, dass die Metrik unterstützt wird, wenn diese Daten bereitgestellt werden.

Ausführliche Informationen dazu, was diese Metriken messen, finden Sie unter "Bewertung von Qualität, Kosten und Latenz durch Agent Evaluation (MLflow 2)".

Berechnete Metriken	`request`	`request` und `expected_response`	`request`, `expected_response`, `expected_retrieved_context`und `guidelines`	`request` und `expected_retrieved_context`	`request` und `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`			✓		✓

Freigeben über

Eingabeschema für die Agentauswertung (MLflow 2)

Auswertungseingabeschema

expected_facts Richtlinien

guidelines Richtlinien

expected_response Richtlinien