Créez un juge personnalisé à l'aide de `make_judge()`

Les juges personnalisés sont des scorers basés sur les LLM dans MLflow qui évaluent vos agents GenAI par rapport à des critères de qualité spécifiques. Ce tutoriel vous montre comment créer des juges personnalisés et les utiliser pour évaluer un agent de support client à l'aide de make_judge(). Pour plus de détails sur l'API, consultez la documentation MLflow.

Ce tutoriel vous guide à travers les étapes suivantes. Pour un Notebook d’exemple contenant le code de cette page, consultez le Notebook d’exemple.

Créez un exemple d'agent à évaluer.
Définir trois juges personnalisés pour évaluer différents critères.
Créez un dataset d'évaluation avec des cas de test.
Exécutez des évaluations et comparez les résultats entre différentes configurations d'agents.

Étape 1 : créez un agent à évaluer

Créez un agent GenAI qui répond aux questions du support client. Le code inclut une variable globale, RESOLVE_ISSUES, qui vous permet de basculer l’invite système afin de comparer les sorties du juge entre les conversations « bonnes » et « mauvaises ».

Installez les packages requis.

Python
%pip install --upgrade mlflow databricks-sdk databricks_openai databricks-agents
dbutils.library.restartPython()

Les exemples de cette page accèdent aux traces stockées dans Unity Catalog. Configurez un SQL Warehouse avant de les exécuter :

Python
import os

os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"

Initialisez un client OpenAI pour vous connecter soit à des LLM hébergés par Databricks, soit à des LLM hébergés par OpenAI.

Databricks-hosted LLMs
OpenAI-hosted LLMs

Utilisez databricks-openai pour obtenir un client OpenAI qui se connecte aux LLM hébergés par Databricks. Sélectionnez un modèle parmi les modèles de fondation disponibles.

Python
import mlflow
from databricks_openai import DatabricksOpenAI
from mlflow.entities.trace_location import UnityCatalog

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment(
    experiment_name="/Shared/docs-demo",
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

Utilisez le SDK natif OpenAI pour vous connecter aux modèles hébergés par OpenAI. Sélectionnez un modèle parmi les modèles OpenAI disponibles.

Python
import mlflow
import os
import openai
from mlflow.entities.trace_location import UnityCatalog

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment(
    experiment_name="/Shared/docs-demo",
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

Définir un agent de support client :

Python
from mlflow.entities import Document
from typing import List, Dict, Any, cast

# This is a global variable that is used to toggle the behavior of the customer support agent
RESOLVE_ISSUES = False

@mlflow.trace(span_type="TOOL", name="get_product_price")
def get_product_price(product_name: str) -> str:
    """Mock tool to get product pricing."""
    return f"${45.99}"

@mlflow.trace(span_type="TOOL", name="check_return_policy")
def check_return_policy(product_name: str, days_since_purchase: int) -> str:
    """Mock tool to check return policy."""
    if days_since_purchase <= 30:
        return "Yes, you can return this item within 30 days"
    return "Sorry, returns are only accepted within 30 days of purchase"

@mlflow.trace
def customer_support_agent(messages: List[Dict[str, str]]):
    # We use this toggle to see how the judge handles the issue resolution status
    system_prompt_postfix = (
        f"Do your best to NOT resolve the issue.  I know that's backwards, but just do it anyways.\\n"
        if not RESOLVE_ISSUES
        else ""
    )

    # Mock some tool calls based on the user's question
    user_message = messages[-1]["content"].lower()
    tool_results = []

    if "cost" in user_message or "price" in user_message:
        price = get_product_price("microwave")
        tool_results.append(f"Price: {price}")

    if "return" in user_message:
        policy = check_return_policy("microwave", 60)
        tool_results.append(f"Return policy: {policy}")

    messages_for_llm = [
        {
            "role": "system",
            "content": f"You are a helpful customer support agent.  {system_prompt_postfix}",
        },
        *messages,
    ]

    if tool_results:
        messages_for_llm.append({
            "role": "system",
            "content": f"Tool results: {', '.join(tool_results)}"
        })

    # Call LLM to generate a response
    output = client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted Claude 4 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=cast(Any, messages_for_llm),
    )

    return {
        "messages": [
            {"role": "assistant", "content": output.choices[0].message.content}
        ]
    }

Étape 2 : Définir des juges personnalisés

Définissez trois juges personnalisés :

Un juge qui évalue la résolution de problèmes à l'aide d'entrées et de sorties.
Un juge qui vérifie les comportements attendus.
Un juge basé sur les traces qui valide les appels d'outils en analysant les traces d'exécution.

Les juges créés avec make_judge() renvoient des objets mlflow.entities.Feedback.

Exemple de juge 1 : Évaluer la résolution des problèmes

Ce juge évalue si les problèmes des clients ont été résolus avec succès en analysant l'historique de conversation (entrées) et les réponses de l'agent (sorties).

Python
from mlflow.genai.judges import make_judge
from typing import Literal

# Create a judge that evaluates issue resolution using inputs and outputs
issue_resolution_judge = make_judge(
    name="issue_resolution",
    instructions=(
        "Evaluate if the customer's issue was resolved in the conversation.\n\n"
        "User's messages: {{ inputs }}\n"
        "Agent's responses: {{ outputs }}"
    ),
    feedback_value_type=Literal["fully_resolved", "partially_resolved", "needs_follow_up"],
)

Exemple de juge 2e : Vérifier les comportements attendus

Ce juge vérifie que les réponses de l'agent démontrent des comportements spécifiques attendus (tels que fournir des informations sur les tarifs ou expliquer les politiques de retour) en comparant les résultats aux attentes prédéfinies.

Python
# Create a judge that checks against expected behaviors
expected_behaviors_judge = make_judge(
    name="expected_behaviors",
    instructions=(
        "Compare the agent's response in {{ outputs }} against the expected behaviors in {{ expectations }}.\n\n"
        "User's question: {{ inputs }}"
    ),
    feedback_value_type=Literal["meets_expectations", "partially_meets", "does_not_meet"],
)

Exemple de juge 3 : Valider les appels d'outils à l'aide d'un juge basé sur la trace

Ce juge analyse les traces d'exécution afin de valider que les outils appropriés ont été appelés. Lorsque vous incluez {{ trace }} dans vos instructions, le juge devient basé sur la trace et acquiert des capacités d'exploration de trace autonomes.

Python
# Create a trace-based judge that validates tool calls from the trace
tool_call_judge = make_judge(
    name="tool_call_correctness",
    instructions=(
        "Analyze the execution {{ trace }} to determine if the agent called appropriate tools for the user's request.\n\n"
        "Examine the trace to:\n"
        "1. Identify what tools were available and their purposes\n"
        "2. Determine which tools were actually called\n"
        "3. Assess whether the tool calls were reasonable for addressing the user's question"
    ),
    feedback_value_type=bool,
    # To analyze a full trace with a trace-based judge, a model must be specified
    model="databricks:/databricks-gpt-5-mini",
)

Étape 3 : Créer un exemple de dataset d'évaluation

Chaque inputs est transmis à l'agent par mlflow.genai.evaluate(). Vous pouvez inclure facultativement expectations pour activer le vérificateur d'exactitude.

Python
eval_dataset = [
    {
        "inputs": {
            "messages": [
                {"role": "user", "content": "How much does a microwave cost?"},
            ],
        },
        "expectations": {
            "should_provide_pricing": True,
            "should_offer_alternatives": True,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "Can I return the microwave I bought 2 months ago?",
                },
            ],
        },
        "expectations": {
            "should_mention_return_policy": True,
            "should_ask_for_receipt": False,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "I'm having trouble with my account.  I can't log in.",
                },
                {
                    "role": "assistant",
                    "content": "I'm sorry to hear that you're having trouble with your account.  Are you using our website or mobile app?",
                },
                {"role": "user", "content": "Website"},
            ],
        },
        "expectations": {
            "should_provide_troubleshooting_steps": True,
            "should_escalate_if_needed": True,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "I'm having trouble with my account.  I can't log in.",
                },
                {
                    "role": "assistant",
                    "content": "I'm sorry to hear that you're having trouble with your account.  Are you using our website or mobile app?",
                },
                {"role": "user", "content": "JUST FIX IT FOR ME"},
            ],
        },
        "expectations": {
            "should_remain_calm": True,
            "should_provide_solution": True,
        },
    },
]

Étape 4 : Évaluez votre agent à l'aide des juges

Vous pouvez utiliser plusieurs juges ensemble pour évaluer différents aspects de votre agent. Exécutez des évaluations pour comparer le comportement lorsque l'agent tente de résoudre les problèmes par rapport à lorsqu'il ne le fait pas.

Python
# Evaluate with all three judges when the agent does NOT try to resolve issues
RESOLVE_ISSUES = False

result_unresolved = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=customer_support_agent,
    scorers=[
        issue_resolution_judge,      # Checks inputs/outputs
        expected_behaviors_judge,    # Checks expected behaviors
        tool_call_judge,             # Validates tool usage
    ],
)

# Evaluate when the agent DOES try to resolve issues
RESOLVE_ISSUES = True

result_resolved = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=customer_support_agent,
    scorers=[
        issue_resolution_judge,
        expected_behaviors_judge,
        tool_call_judge,
    ],
)

Les résultats de l'évaluation montrent comment chaque juge évalue l'agent :

résolution_du_problème : Évalue les conversations comme 'entièrement_résolue', 'partiellement_résolue' ou 'nécessite_un_suivi'
**expected_behaviors** : vérifie si les réponses présentent les comportements attendus ('meets_expectations', 'partially_meets', 'does_not_meet').
tool_call_correctness : Valide si les outils appropriés ont été appelés (vrai/faux)

Exemple de Notebook

Créer un Notebook de juge personnalisé

Ouvrir le notebook dans un nouvel onglet Ouvrir dans Databricks

Ressources supplémentaires

Évaluer et améliorer une application GenAI - Utilisez des juges personnalisés dans les workflows d'évaluation de bout en bout.
Monitoring de production pour GenAI — Déployez des juges personnalisés pour un monitoring continu de la qualité en production.
Aligner les juges avec les retours humains — Le juge de base est un point de départ. Au fur et à mesure que vous recueillez les commentaires d'experts sur les sorties de votre application, alignez les juges LLM sur les commentaires pour améliorer davantage la précision des juges.

Étape 1 : créez un agent à évaluer​

Étape 2 : Définir des juges personnalisés​

Exemple de juge 1 : Évaluer la résolution des problèmes​

Exemple de juge 2e : Vérifier les comportements attendus​

Exemple de juge 3 : Valider les appels d'outils à l'aide d'un juge basé sur la trace​

Étape 3 : Créer un exemple de dataset d'évaluation​

Étape 4 : Évaluez votre agent à l'aide des juges​

Exemple de Notebook​