Évaluer les applications GenAI pendant le développement

La fonction mlflow.genai.evaluate() fournit un cadre d'évaluation pour les applications GenAI. Au lieu d'exécuter manuellement votre application et de vérifier les sorties une par une, MLflow Evaluation offre un moyen structuré d'intégrer des données de test, d'exécuter votre application et de noter automatiquement les résultats. Cela facilite la comparaison des versions, le suivi des améliorations et le partage des résultats entre les équipes.

L'évaluation MLflow relie les tests hors ligne au monitoring en production. Cela signifie que la même logique d'évaluation que vous utilisez en développement peut également être exécutée en production, vous offrant une vue cohérente de la qualité sur l'ensemble du cycle de vie de l'IA.

La fonction mlflow.genai.evaluate() teste systématiquement la qualité des applications GenAI en l'exécutant sur des données de test (datasets d'évaluation et en appliquant des scorers).

Si vous êtes novice en matière d'évaluation, start avec une démonstration de 10 minutes : Évaluez une application GenAI.

Quand utiliser

Vérifications quotidiennes ou hebdomadaires de votre application par rapport à des jeux de données d’évaluation organisés.
Validation des changements de prompt ou de modèle entre les versions d'application
Avant une publication ou une PR pour éviter les régressions de qualité

Référence rapide

La fonction mlflow.genai.evaluate() exécute votre application GenAI par rapport à un dataset d'évaluation à l'aide d'évaluateurs spécifiés et éventuellement d'une fonction de prédiction ou d'un ID de modèle, renvoyant un EvaluationResult.

Python
def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

Pour plus de détails sur l'API, consultez les paramètres de mlflow.genai.evaluate() ou la documentation MLflow.
Pour plus de détails sur EvaluationDataset, consultez Création de datasets d'évaluation MLflow.
Pour plus de détails sur les exécutions d’évaluation et la journalisation, consultez Exécutions d’évaluation dans MLflow.

Exigences

Installez MLflow et les packages requis.

Bash
pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"

Créez une expérience MLflow en suivant le guide de démarrage rapide de configuration de votre environnement.

(Facultatif) Configurer la parallélisation

MLflow utilise default un pool de threads d'arrière-plan pour accélérer le processus d'évaluation. Pour configurer le nombre de workers, définissez la variable d'environnement MLFLOW_GENAI_EVAL_MAX_WORKERS.

Bash
export MLFLOW_GENAI_EVAL_MAX_WORKERS=10

Modes d'évaluation

Il existe deux modes d'évaluation :

Évaluation directe (recommandée). MLflow appelle votre application directement pour générer des traces pour l'évaluation :
1. Exécute votre application sur des entrées de test, en capturant des traces.
2. Applique des évaluateurs ou des juges LLM pour évaluer la qualité, créant ainsi un retour.
3. Stocke les résultats dans une exécution d'évaluation dans l'expérience MLflow active.
Évaluation de la feuille de réponses. Vous fournissez des sorties précalculées ou des traces existantes pour évaluation :
1. Applique des scorers ou des juges LLM pour évaluer la qualité sur des sorties pré-calculées ou des traces, en créant des feedback.
2. Stocke les résultats dans une exécution d'évaluation dans l'expérience MLflow active.

Évaluation directe (recommandé)

MLflow appelle directement votre application GenAI pour générer et évaluer des traces. Vous pouvez soit passer le point d'entrée de votre application encapsulé dans une fonction Python (predict_fn), soit, si votre application est déployée en tant qu'Endpoint de Model Serving Databricks, passer cet Endpoint encapsulé dans to_predict_fn.

En appelant directement votre application, ce mode vous permet de réutiliser les évaluateurs définis pour l'évaluation hors ligne dans le monitoring de production, étant donné que les traces résultantes seront identiques.

Comme le montre le diagramme, les données, votre application et les évaluateurs sélectionnés sont fournis en entrée à mlflow.genai.evaluate(), qui exécute l'application et les évaluateurs en parallèle et enregistre les sorties sous forme de traces et de feedback.

Fonctionnement de l'évaluation avec le traçage

Formats de données pour l'évaluation directe

Pour plus de détails sur le schéma, consultez la référence du dataset d'évaluation.

Champ	Type de données	Obligatoire	Description
`inputs`	`dict[Any, Any]`	Oui	Dictionnaire transmis à votre `predict_fn`
`expectations`	`dict[str, Any]`	Non	Vérité terrain facultative pour les évaluateurs

Exemple utilisant l'évaluation directe

Le code suivant montre un exemple d'exécution de l'évaluation :

Python
import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app with MLflow tracing
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    if "MLflow" in question:
        response = "MLflow is an open-source platform for managing ML and GenAI workflows."
    else:
        response = "I can help you with MLflow questions."

    return {"response": response}

# Evaluate your app
results = mlflow.genai.evaluate(
    data=[
        {"inputs": {"question": "What is MLflow?"}},
        {"inputs": {"question": "How do I get started?"}}
    ],
    predict_fn=my_chatbot_app,
    scorers=[RelevanceToQuery(), Safety()]
)

Limitation du débit des appels de modèle

Lors de l'évaluation des modèles avec des limites de débit (tels que les APIs tierces ou les Endpoint de modèles de fondation), enveloppez votre fonction de prédiction avec une logique de limitation de débit. Cet exemple utilise la bibliothèque ratelimit:

Python
import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety
from ratelimit import limits, sleep_and_retry

# You can replace this with your own predict_fn
predict_fn = mlflow.genai.to_predict_fn("endpoints:/databricks-gpt-oss-20b")

@sleep_and_retry
@limits(calls=10, period=60)  # 10 calls per minute
def rate_limited_predict_fn(*args, **kwargs):
  return predict_fn(*args, **kwargs)

results = mlflow.genai.evaluate(
    data=[{"inputs": {"messages": [{"role": "user", "content": "How does MLflow work?"}]}}],
    predict_fn=predict_fn,
    scorers=[RelevanceToQuery(), Safety()]
)

La limite de débit ci-dessus contrôle les appels vers votre fonction predict_fn. Vous pouvez également contrôler le nombre de Workers utilisés pour évaluer votre agent en configurant la parallélisation.

Évaluation de la feuille de réponses

Utilisez ce mode lorsque vous ne pouvez pas (ou ne voulez pas) exécuter votre application GenAI directement pendant l'évaluation. Par exemple, vous disposez déjà de sorties (provenant par exemple de systèmes externes, de traces historiques ou de jobs batch) et vous souhaitez simplement les noter. Vous fournissez les entrées et les sorties, et evaluate() exécute les évaluateurs et logs une exécution d'évaluation.

important

Si vous utilisez une feuille de réponses avec des traces différentes de votre environnement de production, vous devrez peut-être réécrire vos fonctions d'évaluateur pour les utiliser pour le monitoring de production.

Comme indiqué dans le diagramme, vous fournissez les données d'évaluation et les évaluateurs sélectionnés en tant qu'entrées de mlflow.genai.evaluate(). Les données d'évaluation peuvent consister en des traces existantes, ou en des entrées et des sorties précalculées. Si des entrées et des sorties pré-calculées sont fournies, mlflow.genai.evaluate() construit des traces à partir des entrées et des sorties. Pour les deux options d'entrée, mlflow.genai.evaluate() exécute les évaluateurs sur les traces et affiche le feedback des évaluateurs.

Comment l'évaluation fonctionne avec une feuille de réponses

Formats de données pour l'évaluation des feuilles de réponses

Pour plus de détails sur le schéma, consultez la référence du dataset d'évaluation.

Si des entrées et des sorties sont fournies

Champ	Type de données	Obligatoire	Description
`inputs`	`dict[Any, Any]`	Oui	Entrées originales de votre application GenAI
`outputs`	`dict[Any, Any]`	Oui	Résultats précalculés de votre application
`expectations`	`dict[str, Any]`	Non	Vérité terrain facultative pour les évaluateurs

Champ	Type de données	Obligatoire	Description
`inputs`	`dict[Any, Any]`	Oui	Entrées originales de votre application GenAI
`outputs`	`dict[Any, Any]`	Oui	Résultats précalculés de votre application
`expectations`	`dict[str, Any]`	Non	Vérité terrain facultative pour les évaluateurs

Si des traces existantes sont fournies

Champ	Type de données	Obligatoire	Description
`trace`	`mlflow.entities.Trace`	Oui	Objets Trace MLflow avec entrées/sorties
`expectations`	`dict[str, Any]`	Non	Vérité terrain facultative pour les évaluateurs

Exemple utilisant des entrées et des sorties

Le code suivant montre un exemple d'exécution de l'évaluation :

Python
import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery

# Pre-computed results from your GenAI app
results_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "outputs": {"response": "MLflow is an open-source platform for managing machine learning workflows, including tracking experiments, packaging code, and deploying models."},
    },
    {
        "inputs": {"question": "How do I get started?"},
        "outputs": {"response": "To get started with MLflow, install it using 'pip install mlflow' and then run 'mlflow ui' to launch the web interface."},
    }
]

# Evaluate pre-computed outputs
evaluation = mlflow.genai.evaluate(
    data=results_data,
    scorers=[Safety(), RelevanceToQuery()]
)

Exemple d'utilisation de traces existantes

Le code suivant montre comment lancer l'évaluation en utilisant des traces existantes :

Python
import mlflow

# Retrieve traces from production
traces = mlflow.search_traces(
    filter_string="trace.status = 'OK'",
)

# Evaluate problematic traces
evaluation = mlflow.genai.evaluate(
    data=traces,
    scorers=[Safety(), RelevanceToQuery()]
)

Afficher les résultats dans l'UI

Une exécution d'évaluation est comme un rapport de test qui capture tout sur la façon dont votre application a fonctionné sur un dataset spécifique. L'exécution de l'évaluation contient une trace pour chaque ligne de votre dataset d'évaluation, annotée avec les commentaires de chaque juge.

En utilisant l'exécution d'évaluation, vous pouvez afficher les métriques agrégées et étudier les cas de test où votre application a mal fonctionné.

Résumé de l'évaluation

Cliquez sur **Expériences** dans la barre latérale pour afficher la page Expériences.
Cliquez sur le nom de votre experimentation pour l'ouvrir.
Dans la barre latérale gauche, cliquez sur Exécutions d'évaluation . Le volet de droite affiche un tableau de traces.

Si vous ne voyez pas les Évaluations avec leurs étiquettes Réussite et Échec , faites défiler vers la droite ou survolez le séparateur de volet et cliquez sur la flèche pointant vers la gauche.
Pour voir la justification de l'étiquette Réussite ou Échec , passez la souris sur l'étiquette.

Détails et ajout de commentaires.

Pour voir plus de détails pour chaque trace :

Cliquez sur l'identifiant de la demande dans la colonne **Demande**. Une fenêtre apparaît, affichant la trace complète, y compris les entrées et les sorties pour chaque étape.
À droite, vous pouvez ajouter des commentaires ou des attentes à appliquer à la réponse pour cette demande. Si le volet Évaluations n’apparaît pas, cliquez sur . Pour ajouter une nouvelle Évaluation, faites défiler l’écran vers le bas et cliquez sur .
Vous pouvez utiliser les flèches de chaque côté de cette fenêtre pour parcourir les requêtes.

Paramètres pour `mlflow.genai.evaluate()`

Cette section décrit chacun des paramètres utilisés par mlflow.genai.evaluate().

Python
def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

`data`

Le dataset d'évaluation doit être dans l'un des formats suivants :

EvaluationDataset (recommandations).
Liste de dictionnaires, DataFrame Pandas ou DataFrame Spark.

Si l’argument de données est fourni en tant que DataFrame ou liste de dictionnaires, il doit suivre le schéma suivant. Ceci est cohérent avec le schéma utilisé par EvaluationDataset. Databricks recommande d'utiliser un EvaluationDataset car il applique la validation du schéma, en plus de suivre la traçabilité de chaque enregistrement.

Champ	Type de données	Description	Utiliser avec l'évaluation directe	À utiliser avec feuille de réponses
`inputs`	`dict[Any, Any]`	Un `dict` qui est transmis à votre `predict_fn` à l’aide de `**kwargs`. Doit être sérialisable JSON. Chaque clé doit correspondre à un argument nommé dans `predict_fn`.	Obligatoire	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux. Dérivé de `trace` si non fourni.
`outputs`	`dict[Any, Any]`	Un `dict` avec les sorties de votre application GenAI pour le `input` correspondant. Doit être sérialisable en JSON.	Ne doit pas être fourni, généré par MLflow à partir de la trace.	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux. Dérivé de `trace` si non fourni.
`expectations`	`dict[str, Any]`	Un `dict` avec des étiquettes de vérité terrain correspondant à `input`. Utilisé par `scorers` pour vérifier la qualité. Doit être sérialisable en JSON et chaque clé doit être un `str`.	Facultatif	Facultatif
`trace`	`mlflow.entities.Trace`	L'objet de trace de la requête. Si le `trace` est fourni, le `expectations` peut être fourni sous forme de `Assessment`s sur le `trace` plutôt que comme une colonne séparée.	Ne doit pas être fourni, généré par MLflow à partir de la trace.	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux.

Champ	Type de données	Description	Utiliser avec l'évaluation directe	À utiliser avec feuille de réponses
`inputs`	`dict[Any, Any]`	Un `dict` qui est transmis à votre `predict_fn` à l’aide de `**kwargs`. Doit être sérialisable JSON. Chaque clé doit correspondre à un argument nommé dans `predict_fn`.	Obligatoire	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux. Dérivé de `trace` si non fourni.
`outputs`	`dict[Any, Any]`	Un `dict` avec les sorties de votre application GenAI pour le `input` correspondant. Doit être sérialisable en JSON.	Ne doit pas être fourni, généré par MLflow à partir de la trace.	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux. Dérivé de `trace` si non fourni.
`expectations`	`dict[str, Any]`	Un `dict` avec des étiquettes de vérité terrain correspondant à `input`. Utilisé par `scorers` pour vérifier la qualité. Doit être sérialisable en JSON et chaque clé doit être un `str`.	Facultatif	Facultatif
`trace`	`mlflow.entities.Trace`	L'objet de trace de la requête. Si le `trace` est fourni, le `expectations` peut être fourni sous forme de `Assessment`s sur le `trace` plutôt que comme une colonne séparée.	Ne doit pas être fourni, généré par MLflow à partir de la trace.	Soit `inputs` + `outputs`, soit `trace` est requis. Impossible de transmettre les deux.

`scorers`

Liste des indicateurs de qualité à appliquer. Vous pouvez fournir :

Consultez Évaluateurs pour plus de détails.

`predict_fn`

Le point d'entrée de l'application GenAI. Ce parameter n'est utilisé qu'avec l'évaluation directe. predict_fn doit satisfaire aux exigences suivantes :

Acceptez les clés du dictionnaire inputs dans data comme arguments de mot-clé.
Renvoyer un dictionnaire sérialisable en JSON.
Instrumentez-vous avec MLflow Tracing.
Émettre exactement une trace par appel.

`model_id`

Identifiant de modèle facultatif pour Link les résultats à votre version d'application (par exemple, "models:/my-app/1").

Ressources supplémentaires

Évaluez votre application – Guide étape par étape pour exécuter votre première évaluation.
Construire des datasets d'évaluation – Créez des données de test structurées à partir des logs de production ou de zéro.
Définir des évaluateurs personnalisés — Créez des indicateurs adaptés à votre cas d'utilisation spécifique.

Quand utiliser​

Référence rapide​

Exigences​

(Facultatif) Configurer la parallélisation​

Modes d'évaluation​

Évaluation directe (recommandé)​

Formats de données pour l'évaluation directe​

Exemple utilisant l'évaluation directe​

Limitation du débit des appels de modèle​

Évaluation de la feuille de réponses​

Formats de données pour l'évaluation des feuilles de réponses​

Exemple utilisant des entrées et des sorties​

Exemple d'utilisation de traces existantes​

Afficher les résultats dans l'UI​

Résumé de l'évaluation​

Détails et ajout de commentaires.​

Paramètres pour mlflow.genai.evaluate()​

data​

scorers​

predict_fn​

model_id​

Ressources supplémentaires​