Schéma d’entrée d’évaluation de l’agent (MLflow 2)

Cet article explique le schéma d’entrée requis par l’évaluation de l’agent pour évaluer la qualité, le coût et la latence de votre application.

• Pendant le développement, l’évaluation se fait hors ligne et Agent Evaluation requiert un jeu d’évaluation comme entrée.
• Lorsqu’une application est en production, toutes les entrées vers Agent Evaluation proviennent de vos tables d’inférence ou journaux de production.

Le schéma d’entrée est identique pour les évaluations en ligne et hors ligne.

Pour obtenir des informations générales sur les jeux d’évaluation, consultez Jeux d’évaluation (MLflow 2).

Schéma d’entrée d’évaluation

Le tableau suivant montre le schéma d’entrée de l’évaluation de l’agent. Les deux dernières colonnes du tableau font référence à la manière dont l’entrée est fournie à l’appel mlflow.evaluate(). Consultez Fournir des entrées à une exécution d’évaluation pour en savoir plus.

Instructions expected_facts

Le champ expected_facts spécifie la liste des faits attendus dans une réponse de modèle correcte pour la requête d’entrée spécifique. Autrement dit, la réponse du modèle est jugée correcte si elle contient ces faits, quelle que soit la manière dont la réponse est formulée.

Le fait d'inclure uniquement les faits requis et de laisser de côté les faits qui ne sont pas strictement requis dans la réponse permet à Agent Evaluation de fournir un signal plus robuste sur la qualité de la sortie.

Vous pouvez spécifier au maximum un expected_facts ou une expected_response. Si vous spécifiez les deux, une erreur est signalée. Databricks recommande d’utiliser expected_facts, car il s’agit d’une directive plus spécifique qui aide Agent Evaluation à juger plus efficacement de la qualité des réponses générées.

Instructions guidelines

Le guidelines champ spécifie des instructions définies auxquelles toute réponse de modèle correcte doit respecter. guidelines peut être exprimé dans deux formats :

• La liste des directives (List[str]) fournit un ensemble unique de directives.
• Les directives nommées (Dict[str, List[str]]) établissent une correspondance entre un nom de directive et un ensemble de directives pour ce nom. Les instructions nommées nécessitent databricks-agents >= 0.16.0.

Les instructions peuvent faire référence à différentes caractéristiques de la réponse, y compris les éléments stylistiques ou liés au contenu. Pour le signal le plus robuste sur l’adhésion aux recommandations, Databricks recommande d’utiliser le langage suivant :

• « La réponse doit ... »
• « La réponse ne doit pas ... »
• « La réponse peut éventuellement ... »

Plus précisément, vous devez faire référence à la demande et à la réponse directement et laisser le moins d'ambiguïté possible dans les instructions. Pour obtenir des instructions qui s’appliquent à l’ensemble de votre jeu d’évaluation, telles que la garantie que les réponses ont un ton professionnel ou sont toujours en anglais, utilisez le paramètre global_guidelines dans la configuration de l’évaluateur comme suit :

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"],
            }
        }
    }
)

Instructions expected_response

Le champ expected_response contient une réponse entièrement formée qui constitue une référence pour les réponses correctes du modèle. Autrement dit, une réponse de modèle est jugée correcte si elle correspond au contenu des informations dans expected_response. En revanche, expected_facts répertorie uniquement les faits requis pour apparaître dans une réponse correcte et n’est pas une réponse de référence entièrement formée.

Comme pour expected_facts, expected_response ne doit contenir qu'un jeu minimal de faits requis pour une réponse correcte. Le fait d'inclure uniquement les informations nécessaires et de laisser de côté celles qui ne sont pas strictement requises dans la réponse permet à Agent Evaluation de fournir un signal plus solide sur la qualité de la sortie.

Vous pouvez spécifier au maximum un expected_facts ou une expected_response. Si vous spécifiez les deux, une erreur est signalée. Databricks recommande d’utiliser expected_facts, car il s’agit d’une directive plus spécifique qui aide Agent Evaluation à juger plus efficacement de la qualité des réponses générées.

Schéma pour la requête

Le schéma de la requête peut être l’un des suivants :

• Dictionnaire sérialisable arbitraire (par exemple, Dict[str, Any])
• Si l’agent prend en charge le schéma de complétion de conversation OpenAI, vous pouvez passer une chaîne standard. Ce format ne prend en charge que les conversations à un seul tour. Les chaînes standard sont converties au format messages avec "role": "user" avant d’être transmises à votre agent. Par exemple, une chaîne standard "What is MLflow?" est convertie en {"messages": [{"role": "user", "content": "What is MLflow?"}]} avant d’être transmise à votre agent.

Notez que les juges intégrés fonctionnent mieux avec tout format utilisant un schéma d’achèvement de conversation OpenAI. Le schéma de complétion de conversation OpenAI doit avoir un tableau d’objets en tant que paramètre messages. Le champ messages peut encoder toute la conversation.

L’exemple suivant montre quelques options possibles dans la même request colonne du jeu de données d’évaluation :

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)

Schéma pour la réponse

Le schéma de réponse, similaire au schéma de requête, peut être l’un des éléments suivants :

• Dictionnaire sérialisable arbitraire (par exemple, Dict[str, Any]).
• Si l’agent prend en charge le schéma de complétion de conversation OpenAI, vous pouvez passer une chaîne standard. Ce format ne prend en charge que les conversations à un seul tour. Les chaînes simples sont converties au choices format. Par exemple, une chaîne "MLFlow is a framework." simple est convertie en {"choices": [{"message": {"content": "MLFlow is a framework."}}]}.

Schéma pour les tableaux dans l’entrée d’évaluation

Le schéma des tableaux expected_retrieved_context et retrieved_context est présenté dans le tableau suivant :

Mesures calculées

Les colonnes du tableau suivant indiquent les données incluses dans l’entrée et ✓ indique que la mesure est prise en charge lorsque ces données sont fournies.

Pour plus d’informations sur la mesure de ces métriques, consultez Comment la qualité, le coût et la latence sont évalués par l’évaluation de l’agent (MLflow 2).