Migrer vers MLflow 3 depuis Agent Evaluation

Agent Evaluation est maintenant intégré à MLflow 3 sur Databricks. Les méthodes du SDK Agent Evaluation sont désormais exposées via le SDK mlflow[databricks]>=3.1, sous l'espace de noms mlflow.genai. MLflow 3 présente :

Interface utilisateur actualisée qui reflète toutes les fonctionnalités du SDK
Nouveau SDK mlflow.genai avec des APIs simplifiées pour l'évaluation, l'annotation humaine et la gestion des datasets d'évaluation
**Traçage amélioré** avec un backend d’ingestion de traces à l’échelle de la production qui offre une observabilité en temps réel
**Collecte optimisée des feedbacks humains**
Juges LLM améliorés en tant qu'évaluateurs intégrés

Ce guide vous aide à migrer d'Agent Evaluation (MLflow 2.x avec databricks-agents<1.0) vers MLflow 3. Ce guide détaillé est également disponible au format référence rapide.

important

MLflow 3 avec Agent Evaluation fonctionne uniquement sur Managed MLflow, et non sur MLflow open source. Consultez la page MLflow géré vs open source pour mieux comprendre les différences entre MLflow géré et open source.

Liste de contrôle de la migration

start by using this checklist. Chaque élément contient des liens vers des détails dans les sections ci-dessous.

Pièges courants à éviter

N'oubliez pas de mettre à jour les noms de champs de données dans vos DataFrames.
N'oubliez pas que model_type="databricks-agent" n'est plus nécessaire
Assurez-vous que les scoreurs personnalisés renvoient des valeurs valides (“yes”/“no” pour réussi/échec)
Utilisez search_traces() au lieu d'accéder directement aux tables de résultats
Mettez à jour toutes les références d'espace de noms codées en dur dans votre code
N'oubliez pas de spécifier explicitement tous les évaluateurs : MLflow 3 n'exécute pas automatiquement les juges
Convertir global_guidelines de la configuration en évaluateurs Guidelines() explicites

Migration de l'API d'évaluation

Mises à jour des importations

La liste ci-dessous récapitule les imports à mettre à jour, avec des détails et des exemples dans chaque sous-section ci-dessous.

Python
# Old imports
from mlflow import evaluate
from databricks.agents.evals import metric
from databricks.agents.evals import judges

# New imports
from mlflow.genai import evaluate
from mlflow.genai.scorers import scorer
from mlflow.genai import judges
# For predefined scorers:
from mlflow.genai.scorers import (
    Correctness, Guidelines, ExpectationsGuidelines,
    RelevanceToQuery, Safety, RetrievalGroundedness,
    RetrievalRelevance, RetrievalSufficiency
)

De `mlflow.evaluate()` à `mlflow.genai.evaluate()`

L'API d'évaluation principale a été déplacée vers un espace de noms GenAI dédié avec des noms de parameter plus clairs.

Modifications clés de l'API :

MLflow 2.x	MLflow 3.x	Notes
`mlflow.evaluate()`	`mlflow.genai.evaluate()`	Nouvel espace de noms
`model` parameter	`predict_fn` parameter	Nom plus descriptif
`model_type="databricks-agent"`	Non nécessaire	Détecté automatiquement
`extra_metrics=[...]`	`scorers=[...]`	Terminologie plus claire
`evaluator_config={...}`	Non nécessaire	Partie des évaluateurs

MLflow 2.x	MLflow 3.x	Notes
`mlflow.evaluate()`	`mlflow.genai.evaluate()`	Nouvel espace de noms
`model` parameter	`predict_fn` parameter	Nom plus descriptif
`model_type="databricks-agent"`	Non nécessaire	Détecté automatiquement
`extra_metrics=[...]`	`scorers=[...]`	Terminologie plus claire
`evaluator_config={...}`	Non nécessaire	Partie des évaluateurs

Mappage de champs de données :

Champ MLflow 2.x	Champ MLflow 3.x	Description
`request`	`inputs`	Entrée de l'agent
`response`	`outputs`	Sortie de l'agent
`expected_response`	`expectations`	Vérité terrain
`retrieved_context`	Accessible via des traces	Contexte de la trace
`guidelines`	Partie de la configuration de l'évaluateur	Déplacé au niveau de l'évaluateur

Champ MLflow 2.x	Champ MLflow 3.x	Description
`request`	`inputs`	Entrée de l'agent
`response`	`outputs`	Sortie de l'agent
`expected_response`	`expectations`	Vérité terrain
`retrieved_context`	Accessible via des traces	Contexte de la trace
`guidelines`	Partie de la configuration de l'évaluateur	Déplacé au niveau de l'évaluateur

Exemple : évaluation de base

MLflow 2.x :

Python
import mlflow
import pandas as pd

eval_data = [
        {
            "request":  "What is MLflow?",
            "response": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
            "expected_response": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
        },
        {
            "request":  "What is Databricks?",
            "response": "Databricks is a unified analytics platform.",
            "expected_response": "Databricks is a unified analytics platform for big data and AI.",
        },
    ]

# Note: By default, MLflow 2.x runs all applicable judges automatically
results = mlflow.evaluate(
    data=eval_data,
    model=my_agent,
    model_type="databricks-agent",
    evaluator_config={
        &quot;databricks-agent&quot;: {
            # Optional: limit to specific judges
            # &quot;metrics&quot;: [&quot;correctness&quot;, &quot;safety&quot;],
            # Optional: add global guidelines
            &quot;global_guidelines&quot;: {
                &quot;clarity&quot;: [&quot;Response must be clear and concise&quot;]
            }
        }
    }
)

# Access results
eval_df = results.tables['eval_results']

MLflow 3.x :

Python
import mlflow
import pandas as pd
from mlflow.genai.scorers import Guidelines

eval_data = [
        {
            "inputs": {"request": "What is MLflow?"},
            "outputs": {
                "response": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models."
            },
            "expectations": {
                "expected_response":
                    "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",

            },
        },
        {
            "inputs": {"request": "What is Databricks?"},
            "outputs": {"response": "Databricks is a unified analytics platform."},
            "expectations": {
                "expected_response":
                    "Databricks is a unified analytics platform for big data and AI.",

            },
        },
    ]

# Define guidelines for scorer
guidelines = {
    "clarity": ["Response must be clear and concise"],
    # supports str or list[str]
    "accuracy": "Response must be factually accurate",
}

print("Running evaluation with mlflow.genai.evaluate()...")

with mlflow.start_run(run_name="basic_evaluation_test") as run:
    # Run evaluation with new API
    # Note: Must explicitly specify which scorers to run (no automatic selection)
    results = mlflow.genai.evaluate(
        data=eval_data,
        scorers=[
            Correctness(),  # Requires expectations.expected_response
            RelevanceToQuery(),  # No ground truth needed
            Guidelines(name="clarity", guidelines=guidelines["clarity"]),
            Guidelines(name="accuracy", guidelines=guidelines["accuracy"]),
            # ExpectationsGuidelines(),
            # Add more scorers as needed: Safety(), RetrievalGroundedness(), etc.
        ],
    )

# Access results using search_traces
traces = mlflow.search_traces(
        run_id=results.run_id,
)

Accéder aux résultats d'évaluation

Dans MLflow 3, les résultats d'évaluation sont stockés sous forme de traces avec des évaluations. Utilisez mlflow.search_traces() pour accéder aux résultats détaillés :

Python
# Access results using search_traces
traces = mlflow.search_traces(
    run_id=results.run_id,
)

# Access assessments for each trace
for trace in traces:
    assessments = trace.info.assessments
    for assessment in assessments:
        print(f"Scorer: {assessment.name}")
        print(f"Value: {assessment.value}")
        print(f"Rationale: {assessment.rationale}")

Évaluation d'un MLflow LoggedModel

Dans MLflow 2.x, vous pouviez transmettre un modèle MLflow enregistré (tel qu'un modèle PyFunc ou un modèle enregistré par des agents personnalisés) directement à mlflow.evaluate(). Dans MLflow 3.x, vous devez encapsuler le modèle dans une fonction de prédiction pour gérer le mappage des paramètres.

Ce wrapper est nécessaire car mlflow.genai.evaluate() attend une fonction de prédiction qui accepte les clés du dictionnaire inputs de votre dataset comme arguments nommés, tandis que la plupart des modèles journalisés acceptent un seul parameter d'entrée (par exemple, model_inputs pour les modèles PyFunc ou des interfaces similaires pour les modèles LangChain).

La fonction de prédiction sert de couche de traduction entre les paramètres nommés du framework d'évaluation et le format d'entrée attendu du modèle.

Python
import mlflow
from mlflow.genai.scorers import Safety

# Make sure to load your logged model outside of the predict_fn so MLflow only loads it once!
model = mlflow.pyfunc.load_model("models:/chatbot/staging")

def evaluate_model(question: str) -> dict:
    return model.predict({"question": question})

results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "Tell me about MLflow"}}],
    predict_fn=evaluate_model,
    scorers=[Safety()]
)

Migration des métriques personnalisées vers les scorers

Les fonctions d'évaluation personnalisées (@metric) utilisent maintenant le décorateur @scorer avec une signature simplifiée.

**Changements clés :**

MLflow 2.x	MLflow 3.x	Notes
`@metric` décorateur	`@scorer` décorateur	Nouveau nom
`def my_metric(request, response, ...)`	`def my_scorer(inputs, outputs, expectations, traces)`	Plus simple
Plusieurs paramètres attendus : *	Param `expectations` unique de type dict	Consolidé
`custom_expected`	Fait partie de `expectations` dictionnaire	Plus simple
`request` parameter	`inputs` parameter	Nomenclature cohérente
`response` parameter	`outputs` parameter	Nomenclature cohérente

MLflow 2.x	MLflow 3.x	Notes
`@metric` décorateur	`@scorer` décorateur	Nouveau nom
`def my_metric(request, response, ...)`	`def my_scorer(inputs, outputs, expectations, traces)`	Plus simple
Plusieurs paramètres attendus : *	Param `expectations` unique de type dict	Consolidé
`custom_expected`	Fait partie de `expectations` dictionnaire	Plus simple
`request` parameter	`inputs` parameter	Nomenclature cohérente
`response` parameter	`outputs` parameter	Nomenclature cohérente

Exemple : Évaluateur de réussite/échec

MLflow 2.x :

Python
from databricks.agents.evals import metric

@metric
def response_length_check(request, response, expected_response=None):
    """Check if response is within acceptable length."""
    length = len(response)
    return "yes" if 50 <= length <= 500 else "no"

# Use in evaluation
results = mlflow.evaluate(
    data=eval_data,
    model=my_agent,
    model_type="databricks-agent",
    extra_metrics=[response_length_check]
)

MLflow 3.x :

Python
import mlflow
from mlflow.genai.scorers import scorer


# Sample agent function
@mlflow.trace
def my_agent(request: str):
    """Simple mock agent for testing - MLflow 3 expects dict input"""
    responses = {
        "What is MLflow?": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
        "What is Databricks?": "Databricks is a unified analytics platform.",
    }
    return {"response": responses.get(request, "I don't have information about that.")}


@scorer
def response_length_check(inputs, outputs, expectations=None, traces=None):
    """Check if response is within acceptable length."""
    length = len(outputs)
    return "yes" if 50 <= length <= 500 else "no"

# Use in evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[response_length_check]
)

Exemple : Évaluateur numérique avec évaluation

MLflow 2.x :

Python
from databricks.agents.evals import metric, Assessment

def calculate_similarity(response, expected_response):
    return 1

@metric
def semantic_similarity(response, expected_response):
    """Calculate semantic similarity score."""
    # Your similarity logic here
    score = calculate_similarity(response, expected_response)

    return Assessment(
        name="semantic_similarity",
        value=score,
        rationale=f"Similarity score based on embedding distance: {score:.2f}"
    )

MLflow 3.x :

Python
from mlflow.genai.scorers import scorer
from mlflow.entities import Feedback

@scorer
def semantic_similarity(outputs, expectations):
    """Calculate semantic similarity score."""
    # Your similarity logic here
    expected = expectations.get("expected_response", "")
    score = calculate_similarity(outputs, expected)

    return Feedback(
        name="semantic_similarity",
        value=score,
        rationale=f"Similarity score based on embedding distance: {score:.2f}"
    )

Migration des juges LLM

Différences clés dans le comportement du juge.

Sélection automatique du juge :

MLflow 2.x	MLflow 3.x
Exécute automatiquement tous les juges applicables en fonction des données	Doit explicitement spécifier quels évaluateurs utiliser
Utilisez `evaluator_config` pour limiter les juges	Passez les scorers souhaités dans le parameter `scorers`
`global_guidelines` dans la configuration	Utiliser l’évaluateur `Guidelines()`
Juges sélectionnés en fonction des champs de données disponibles	Vous contrôlez exactement quels évaluateurs s'exécutent.

MLflow 2.x	MLflow 3.x
Exécute automatiquement tous les juges applicables en fonction des données	Doit explicitement spécifier quels évaluateurs utiliser
Utilisez `evaluator_config` pour limiter les juges	Passez les scorers souhaités dans le parameter `scorers`
`global_guidelines` dans la configuration	Utiliser l’évaluateur `Guidelines()`
Juges sélectionnés en fonction des champs de données disponibles	Vous contrôlez exactement quels évaluateurs s'exécutent.

MLflow 2.x : sélection automatique du juge :

Sans vérité terrain : exécute chunk_relevance, groundedness, relevance_to_query, safety, guideline_adherence
Avec vérité terrain : exécute également context_sufficiency, correctness

MLflow 3.x : sélection explicite de l'évaluateur :

Vous devez explicitement lister les évaluateurs que vous souhaitez exécuter.
Plus de contrôle, mais nécessite d'être explicite quant aux besoins d'évaluation

Chemins de migration

Cas d'usage	MLflow 2.x	MLflow 3.x recommandé.
Vérification de la correction de base	`judges.correctness()` dans `@metric`	`Correctness()` évaluateur ou `judges.is_correct()` juge
Évaluation de la sécurité	`judges.safety()` dans `@metric`	`Safety()` évaluateur ou `judges.is_safe()` juge
Directives globales	`judges.guideline_adherence()`	`Guidelines()` évaluateur ou `judges.meets_guidelines()` juge
Directives par ligne d'ensemble d'évaluation	`judges.guideline_adherence()` avec expected_*	`ExpectationsGuidelines()` évaluateur ou `judges.meets_guidelines()` juge
Vérifiez le soutien factuel.	`judges.groundedness()`	`judges.is_grounded()` ou évaluateur `RetrievalGroundedness()`
Vérifiez la pertinence du contexte	`judges.relevance_to_query()`	`judges.is_context_relevant()` ou évaluateur `RelevanceToQuery()`
Vérifier la pertinence des segments de contexte	`judges.chunk_relevance()`	`judges.is_context_relevant()` ou évaluateur `RetrievalRelevance()`
Vérifier que le contexte est complet	`judges.context_sufficiency()`	`judges.is_context_sufficient()` ou évaluateur `RetrievalSufficiency()`
Logique personnalisée complexe	Appels directs de juges dans `@metric`	Évaluateurs prédéfinis ou `@scorer` avec des appels de juge

Cas d'usage	MLflow 2.x	MLflow 3.x recommandé.
Vérification de la correction de base	`judges.correctness()` dans `@metric`	`Correctness()` évaluateur ou `judges.is_correct()` juge
Évaluation de la sécurité	`judges.safety()` dans `@metric`	`Safety()` évaluateur ou `judges.is_safe()` juge
Directives globales	`judges.guideline_adherence()`	`Guidelines()` évaluateur ou `judges.meets_guidelines()` juge
Directives par ligne d'ensemble d'évaluation	`judges.guideline_adherence()` avec expected_*	`ExpectationsGuidelines()` évaluateur ou `judges.meets_guidelines()` juge
Vérifiez le soutien factuel.	`judges.groundedness()`	`judges.is_grounded()` ou évaluateur `RetrievalGroundedness()`
Vérifiez la pertinence du contexte	`judges.relevance_to_query()`	`judges.is_context_relevant()` ou évaluateur `RelevanceToQuery()`
Vérifier la pertinence des segments de contexte	`judges.chunk_relevance()`	`judges.is_context_relevant()` ou évaluateur `RetrievalRelevance()`
Vérifier que le contexte est complet	`judges.context_sufficiency()`	`judges.is_context_sufficient()` ou évaluateur `RetrievalSufficiency()`
Logique personnalisée complexe	Appels directs de juges dans `@metric`	Évaluateurs prédéfinis ou `@scorer` avec des appels de juge

MLflow 3 propose deux manières d'utiliser les juges LLM :

**Évaluateurs prédéfinis** – Évaluateurs prêts à l'emploi qui encapsulent les juges avec une analyse automatique des traces
**Appels directs du juge** – Appelez les juges directement au sein des évaluateurs personnalisés pour un contrôle accru

Contrôle des juges exécutés

Exemple : spécifier les juges à exécuter

MLflow 2.x (juges default limitants) :

Python
import mlflow

# By default, runs all applicable judges
# Use evaluator_config to limit which judges run
results = mlflow.evaluate(
    data=eval_data,
    model=my_agent,
    model_type="databricks-agent",
    evaluator_config={
        &quot;databricks-agent&quot;: {
            # Only run these specific judges
            &quot;metrics&quot;: [&quot;groundedness&quot;, &quot;relevance_to_query&quot;, &quot;safety&quot;]
        }
    }
)

MLflow 3.x (sélection explicite du scorer) :

Python
from mlflow.genai.scorers import (
    RetrievalGroundedness,
    RelevanceToQuery,
    Safety
)

# Must explicitly specify which scorers to run
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[
        RetrievalGroundedness(),
        RelevanceToQuery(),
        Safety()
    ]
)

Exemple de migration complet

Cet exemple montre la migration d'une évaluation qui utilise plusieurs juges avec une configuration personnalisée :

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric
import mlflow

# Custom metric using judge
@metric
def check_no_pii(request, response, retrieved_context):
    """Check if retrieved context contains PII."""
    context_text = '\n'.join([c['content'] for c in retrieved_context])

    return judges.guideline_adherence(
        request=request,
        guidelines=["The context must not contain personally identifiable information."],
        guidelines_context={&quot;retrieved_context&quot;: context_text}
    )

# Define global guidelines
global_guidelines = {
    "tone": ["Response must be professional and courteous"],
    "format": ["Response must use bullet points for lists"]
}

# Run evaluation with multiple judges
results = mlflow.evaluate(
    data=eval_data,
    model=my_agent,
    model_type="databricks-agent",
    evaluator_config={
        &quot;databricks-agent&quot;: {
            # Specify subset of built-in judges
            &quot;metrics&quot;: [&quot;correctness&quot;, &quot;groundedness&quot;, &quot;safety&quot;],
            # Add global guidelines
            &quot;global_guidelines&quot;: global_guidelines
        }
    },
    # Add custom judge
    extra_metrics=[check_no_pii]
)

MLflow 3.x :

Python
from mlflow.genai.scorers import (
    Correctness,
    RetrievalGroundedness,
    Safety,
    Guidelines,
    scorer
)
from mlflow.genai import judges
import mlflow

# Custom scorer using judge
@scorer
def check_no_pii(inputs, outputs, traces):
    """Check if retrieved context contains PII."""
    # Extract retrieved context from trace
    retrieved_context = traces.data.spans[0].attributes.get("retrieved_context", [])
    context_text = '\n'.join([c['content'] for c in retrieved_context])

    return judges.meets_guidelines(
        name="no_pii",
        context={
            &quot;request&quot;: inputs,
            &quot;retrieved_context&quot;: context_text
        },
        guidelines=["The context must not contain personally identifiable information."]
    )

# Run evaluation with explicit scorers
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[
        # Built-in scorers (explicitly specified)
        Correctness(),
        RetrievalGroundedness(),
        Safety(),
        # Global guidelines as scorers
        Guidelines(name="tone", guidelines="Response must be professional and courteous"),
        Guidelines(name="format", guidelines="Response must use bullet points for lists"),
        # Custom scorer
        check_no_pii
    ]
)

Migration vers des évaluateurs de juges prédéfinis

MLflow 3 fournit des évaluateurs prédéfinis qui englobent les juges LLM, ce qui les rend plus faciles à utiliser avec mlflow.genai.evaluate().

Exemple : juge d'exactitude

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric

@metric
def check_correctness(request, response, expected_response):
    """Check if response is correct."""
    return judges.correctness(
        request=request,
        response=response,
        expected_response=expected_response
    )

# Use in evaluation
results = mlflow.evaluate(
    data=eval_data,
    model=my_agent,
    model_type="databricks-agent",
    extra_metrics=[check_correctness]
)

MLflow 3.x (Option 1 : Utilisation d'un évaluateur prédéfini) :

Python
from mlflow.genai.scorers import Correctness

# Use predefined scorer directly
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[Correctness()]
)

MLflow 3.x (Option 2 : évaluateur personnalisé avec juge) :

Python
from mlflow.genai.scorers import scorer
from mlflow.genai import judges

@scorer
def check_correctness(inputs, outputs, expectations):
    """Check if response is correct."""
    return judges.correctness(
        request=inputs,
        response=outputs,
        expected_response=expectations.get("expected_response", "")
    )

# Use in evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[check_correctness]
)

Exemple : Juge de sécurité

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric

@metric
def check_safety(request, response):
    """Check if response is safe."""
    return judges.safety(
        request=request,
        response=response
    )

MLflow 3.x :

Python
from mlflow.genai.scorers import Safety

# Use predefined scorer
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[Safety()]
)

Exemple : Juge de pertinence

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric

@metric
def check_relevance(request, response):
    """Check if response is relevant to query."""
    return judges.relevance_to_query(
        request=request,
        response=response
    )

MLflow 3.x :

Python
from mlflow.genai.scorers import RelevanceToQuery

# Use predefined scorer
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[RelevanceToQuery()]
)

Exemple : Juge de l'ancrage

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric

@metric
def check_groundedness(response, retrieved_context):
    """Check if response is grounded in context."""
    context_text = '\n'.join([c['content'] for c in retrieved_context])
    return judges.groundedness(
        response=response,
        context=context_text
    )

MLflow 3.x :

Python
from mlflow.genai.scorers import RetrievalGroundedness

# Use predefined scorer (automatically extracts context from trace)
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[RetrievalGroundedness()]
)

Migration de la conformité aux directives vers meets_guidelines

Le juge guideline_adherence a été renommé en meets_guidelines avec une API plus propre.

MLflow 2.x :

Python
from databricks.agents.evals import judges, metric

@metric
def check_tone(request, response):
    """Check if response follows tone guidelines."""
    return judges.guideline_adherence(
        request=request,
        response=response,
        guidelines=["The response must be professional and courteous."]
    )

@metric
def check_policies(request, response, retrieved_context):
    """Check if response follows company policies."""
    context_text = '\n'.join([c['content'] for c in retrieved_context])

    return judges.guideline_adherence(
        request=request,
        guidelines=["Response must comply with return policy in context."],
        guidelines_context={
            &quot;response&quot;: response,
            &quot;retrieved_context&quot;: context_text
        }
    )

MLflow 3.x (Option 1 : Utilisation d'un évaluateur de lignes directrices prédéfini) :

Python
from mlflow.genai.scorers import Guidelines

# For simple guidelines that only need request/response
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[
        Guidelines(
            name="tone",
            guidelines="The response must be professional and courteous."
        )
    ]
)

MLflow 3.x (Option 2 : Scorer personnalisé avec meets_guidelines) :

Python
from mlflow.genai.scorers import scorer
from mlflow.genai import judges

@scorer
def check_policies(inputs, outputs, traces):
    """Check if response follows company policies."""
    # Extract retrieved context from trace
    retrieved_context = traces.data.spans[0].attributes.get("retrieved_context", [])
    context_text = '\n'.join([c['content'] for c in retrieved_context])

    return judges.meets_guidelines(
        name="policy_compliance",
        guidelines="Response must comply with return policy in context.",
        context={
            &quot;request&quot;: inputs,
            &quot;response&quot;: outputs,
            &quot;retrieved_context&quot;: context_text
        }
    )

Exemple : Migration des ExpectationsGuidelines

Lorsque vous souhaitez définir des directives pour chaque exemple de votre ensemble d'évaluation, comme exiger que certains sujets soient traités, ou que la réponse suive un style spécifique, utilisez le scoreur ExpectationsGuidelines dans MLflow 3.x.

MLflow 2.x :

Dans MLflow 2.x, vous implémenteriez des directives comme suit :

Python
import pandas as pd

eval_data = {
    "request": "What is MLflow?",
    "response": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
    "guidelines": [
        ["The response must mention these topics: platform, observability, testing"]
    ],
}

eval_df = pd.DataFrame(eval_data)

mlflow.evaluate(
    data=eval_df,
    model_type="databricks-agent",
    evaluator_config={
        &quot;databricks-agent&quot;: {&quot;metrics&quot;: [&quot;guideline_adherence&quot;]}
    }
)

MLflow 3.x :

Dans MLflow 3.x, vous organisez les données d'évaluation différemment. Chaque entrée dans vos données d'évaluation doit avoir une clé expectations, et à l'intérieur, vous pouvez inclure des champs comme guidelines.

Voici à quoi pourraient ressembler vos données d'évaluation :

Python
eval_data = [
    {
        "inputs": {"input": "What is MLflow?"},
        "outputs": {"response": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models."},
        "expectations": {
            "guidelines": [
                "The response should mention the topics: platform, observability, and testing."
            ]
        }
    }
]

Ensuite, utilisez l'évaluateur ExpectationsGuidelines :

Python
import mlflow
from mlflow.genai.scorers import ExpectationsGuidelines

expectations_guideline = ExpectationsGuidelines()

# Use predefined scorer
results = mlflow.genai.evaluate(
    data=eval_data,  # Make sure each row has expectations.guidelines
    predict_fn=my_app,
    scorers=[
        expectations_guideline
    ]
)

astuce

Si vous devez vérifier un contenu factuel spécifique (par ex. : « MLflow est open source »), utilisez le correcteur d'exactitude avec un champ expected_facts au lieu des directives. Voir le correcteur.

Réplication du comportement automatique du juge MLflow 2.x

Pour reproduire le comportement de MLflow 2.x qui consiste à exécuter tous les juges applicables, incluez explicitement tous les scorers :

MLflow 2.x (automatique) :

Python
# Automatically runs all applicable judges based on data
results = mlflow.evaluate(
    data=eval_data,  # Contains expected_response and retrieved_context
    model=my_agent,
    model_type="databricks-agent"
)

MLflow 3.x (explicite) :

Python
from mlflow.genai.scorers import (
    Correctness, RetrievalSufficiency,  # Require ground truth
    RelevanceToQuery, Safety, RetrievalGroundedness, RetrievalRelevance  # No ground truth
)

# Manually specify all judges you want to run
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_agent,
    scorers=[
        # With ground truth judges
        Correctness(),
        RetrievalSufficiency(),
        # Without ground truth judges
        RelevanceToQuery(),
        Safety(),
        RetrievalGroundedness(),
        RetrievalRelevance(),
    ]
)

Utilisation directe du juge

Vous pouvez toujours appeler les juges directement pour les tests :

Python
from mlflow.genai import judges

# Test a judge directly (same in both versions)
result = judges.correctness(
    request="What is MLflow?",
    response="MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
    expected_response="MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models."
)
print(f"Judge result: {result.value}")
print(f"Rationale: {result.rationale}")

Migration du feedback humain

Sessions et schémas d'étiquetage

La fonctionnalité de l'application de révision a été déplacée de databricks.agents vers mlflow.genai.labeling.

Modifications de l'espace de noms :

MLflow 2.x	MLflow 3.x
`databricks.agents.review_app`	`mlflow.genai.labeling`
`databricks.agents.datasets`	`mlflow.genai.datasets`
`review_app.label_schemas.*`	`mlflow.genai.label_schemas.*`
`app.create_labeling_session()`	`labeling.create_labeling_session()`

MLflow 2.x	MLflow 3.x
`databricks.agents.review_app`	`mlflow.genai.labeling`
`databricks.agents.datasets`	`mlflow.genai.datasets`
`review_app.label_schemas.*`	`mlflow.genai.label_schemas.*`
`app.create_labeling_session()`	`labeling.create_labeling_session()`

Exemple : Création d'une session d'étiquetage

MLflow 2.x :

Python
from databricks.agents import review_app
import mlflow

# Get review app

my_app = review_app.get_review_app()

# Create custom label schema
quality_schema = my_app.create_label_schema(
    name="response_quality",
    type="feedback",
    title="Rate the response quality",
    input=review_app.label_schemas.InputCategorical(
        options=["Poor", "Fair", "Good", "Excellent"]
    )
)

# Create labeling session
session = my_app.create_labeling_session(
    name="quality_review_jan_2024",
    agent="my_agent",
    assigned_users=["user1@company.com", "user2@company.com"],
    label_schemas=[
        review_app.label_schemas.EXPECTED_FACTS,
        "response_quality"
    ]
)

# Add traces for labeling
traces = mlflow.search_traces(run_id=run_id)
session.add_traces(traces)

MLflow 3.x :

Python
import mlflow
import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create custom label schema
quality_schema = schemas.create_label_schema(
    name="response_quality",
    type=schemas.LabelSchemaType.FEEDBACK,
    title="Rate the response quality",
    input=schemas.InputCategorical(
        options=["Poor", "Fair", "Good", "Excellent"]
    ),
    overwrite=True
)

# Previously built in schemas must be created before use
# However, constant for their names are provided to ensure your schemas work with built-in scorers
expected_facts_schema = schemas.create_label_schema(
    name=schemas.EXPECTED_FACTS,
    type=schemas.LabelSchemaType.EXPECTATION,
    title="Expected facts",
    input=schemas.InputTextList(max_length_each=1000),
    instruction="Please provide a list of facts that you expect to see in a correct response.",
    overwrite=True
)

# Create labeling session
session = labeling.create_labeling_session(
    name="quality_review_jan_2024",
    assigned_users=["user1@company.com", "user2@company.com"],
    label_schemas=[
        schemas.EXPECTED_FACTS,
        "response_quality"
    ]
)

# Add traces for labeling
traces = mlflow.search_traces(
    run_id=session.mlflow_run_id
)
session.add_traces(traces)

# Get review app URL
app = labeling.get_review_app()
print(f"Review app URL: {app.url}")

Synchronisation du feedback vers les datasets

MLflow 2.x :

Python
# Sync expectations back to dataset
session.sync(to_dataset="catalog.schema.eval_dataset")

# Use dataset for evaluation
dataset = spark.read.table("catalog.schema.eval_dataset")
results = mlflow.evaluate(
    data=dataset,
    model=my_agent,
    model_type="databricks-agent"
)

MLflow 3.x :

Python
from mlflow.genai import datasets
import mlflow

# Sample agent function
@mlflow.trace
def my_agent(request: str):
    """Simple mock agent for testing - MLflow 3 expects dict input"""
    responses = {
        "What is MLflow?": "MLflow is the largest open source AI engineering platform for agents, LLMs, and ML models.",
        "What is Databricks?": "Databricks is a unified analytics platform.",
    }
    return {"response": responses.get(request, "I don't have information about that.")}


# Sync expectations back to dataset
session.sync(to_dataset="catalog.schema.eval_dataset")

# Use dataset for evaluation
dataset = datasets.get_dataset("catalog.schema.eval_dataset")
results = mlflow.genai.evaluate(
    data=dataset,
    predict_fn=my_agent
)

Ressources supplémentaires

Pour une assistance supplémentaire lors de la migration, consultez la documentation MLflow ou contactez votre équipe de support Databricks.

Liste de contrôle de la migration​

API d'évaluation​

juges LLM​

Feedback humain​

Pièges courants à éviter​

Migration de l'API d'évaluation​

Mises à jour des importations​

De mlflow.evaluate() à mlflow.genai.evaluate()​

Exemple : évaluation de base​

Accéder aux résultats d'évaluation​

Évaluation d'un MLflow LoggedModel​

Migration des métriques personnalisées vers les scorers​

Exemple : Évaluateur de réussite/échec​

Exemple : Évaluateur numérique avec évaluation​

Migration des juges LLM​

Différences clés dans le comportement du juge.​

Chemins de migration​

Contrôle des juges exécutés​

Exemple : spécifier les juges à exécuter​

Exemple de migration complet​

Migration vers des évaluateurs de juges prédéfinis​

Exemple : juge d'exactitude​

Exemple : Juge de sécurité​

Exemple : Juge de pertinence​

Exemple : Juge de l'ancrage​

Migration de la conformité aux directives vers meets_guidelines​

Exemple : Migration des ExpectationsGuidelines​

Réplication du comportement automatique du juge MLflow 2.x​

Utilisation directe du juge​

Migration du feedback humain​

Sessions et schémas d'étiquetage​

Exemple : Création d'une session d'étiquetage​

Synchronisation du feedback vers les datasets​

Ressources supplémentaires​

Liste de contrôle de la migration

API d'évaluation

juges LLM

Feedback humain

Pièges courants à éviter

Migration de l'API d'évaluation

Mises à jour des importations

De `mlflow.evaluate()` à `mlflow.genai.evaluate()`

Exemple : évaluation de base

Accéder aux résultats d'évaluation

Évaluation d'un MLflow LoggedModel

Migration des métriques personnalisées vers les scorers

Exemple : Évaluateur de réussite/échec

Exemple : Évaluateur numérique avec évaluation

Migration des juges LLM

Différences clés dans le comportement du juge.

Chemins de migration

Contrôle des juges exécutés

Exemple : spécifier les juges à exécuter

Exemple de migration complet

Migration vers des évaluateurs de juges prédéfinis

Exemple : juge d'exactitude

Exemple : Juge de sécurité

Exemple : Juge de pertinence

Exemple : Juge de l'ancrage

Migration de la conformité aux directives vers meets_guidelines

Exemple : Migration des ExpectationsGuidelines

Réplication du comportement automatique du juge MLflow 2.x

Utilisation directe du juge

Migration du feedback humain

Sessions et schémas d'étiquetage

Exemple : Création d'une session d'étiquetage

Synchronisation du feedback vers les datasets

Ressources supplémentaires