Évaluer votre agent de données (aperçu)

En utilisant le SDK Fabric pour l’évaluation, vous pouvez tester de manière programmatique la capacité de votre agent de données à répondre aux questions en langage naturel. En utilisant une interface Python simple, vous pouvez définir des exemples de vérité sur le terrain, effectuer des évaluations et analyser les résultats — le tout dans votre environnement de carnet. Ce processus vous aide à valider l’exactitude, à déboguer les erreurs et à améliorer votre agent en toute confiance avant de le déployer en production.

Conditions préalables

• Une capacité payante F2 ou une capacité de Fabric supérieure, ou un Power BI Premium selon la capacité (P1 ou supérieur) et avec Microsoft Fabric activé.
• Activez le traitement intergéographique et le stockage intergéographique pour l’IA en fonction des exigences expliquées dans les paramètres du locataire de l’agent de données Fabric.
• Au moins une de ces sources de données, avec des données : un entrepôt, un lac de données, un modèle sémantique Power BI, une base de données KQL, une base de données mise en miroir ou une ontologie. Vous devez disposer d’un accès en lecture à la source de données.

Installer le Kit de développement logiciel (SDK) de l’agent de données

Pour commencer à évaluer votre agent de données Fabric de manière programmatique, installez le SDK Python de l’agent de données Fabric. Ce Kit de développement logiciel (SDK) fournit les outils et méthodes nécessaires pour interagir avec votre agent de données, exécuter des évaluations et consigner les résultats. Installez la dernière version en exécutant la commande suivante dans votre notebook :

%pip install -U fabric-data-agent-sdk

Cette étape veille à ce que vous disposiez des fonctionnalités et correctifs les plus à jour disponibles dans le Kit de développement logiciel (SDK).

Charger votre jeu de données de vérité terrain

Pour évaluer votre agent de données Fabric, vous avez besoin d’un ensemble de questions types ainsi que des réponses attendues. Utilisez ces questions pour vérifier la précision avec laquelle l’agent répond aux requêtes réelles.

Définissez ces questions directement dans votre code en utilisant un DataFrame pandas :

import pandas as pd

# Define a sample evaluation set with user questions and their expected answers.
# You can modify the question/answer pairs to match your scenario.
df = pd.DataFrame(
    columns=["question", "expected_answer"],
    data=[
        ["Show total sales for Canadian Dollar for January 2013", "46,117.30"],
        ["What is the product with the highest total sales for Canadian Dollar in 2013", "Mountain-200 Black, 42"],
        ["Total sales outside of the US", "19,968,887.95"],
        ["Which product category had the highest total sales for Canadian Dollar in 2013", "Bikes (Total Sales: 938,654.76)"]
    ]
)

Sinon, si vous avez un jeu de données d’évaluation existant, chargez-le depuis un fichier CSV avec les colonnes question et expected_answer:

# Load questions and expected answers from a CSV file
input_file_path = "/lakehouse/default/Files/Data/Input/curated_2.csv"
df = pd.read_csv(input_file_path)

Ce jeu de données sert d’entrée pour exécuter des évaluations automatisées sur votre agent de données afin d’évaluer la précision et la couverture.

Évaluer et analyser votre agent de données

L’étape suivante consiste à exécuter l’évaluation en utilisant la evaluate_data_agent fonction. Cette fonction compare les réponses de l’agent à vos résultats attendus et stocke les métriques d’évaluation.

from fabric.dataagent.evaluation import evaluate_data_agent

# Name of your data agent
data_agent_name = "AgentEvaluation"

# (Optional) Name of the workspace if the data agent is in a different workspace
workspace_name = None

# (Optional) Name of the output table to store evaluation results (default: "evaluation_output")
# Two tables will be created:
# - "<table_name>": contains summary results (e.g., accuracy)
# - "<table_name>_steps": contains detailed reasoning and step-by-step execution
table_name = "demo_evaluation_output"

# Specify the data agent stage: "production" (default) or "sandbox"
data_agent_stage = "production"

# Run the evaluation and get the evaluation ID
try:
    evaluation_id = evaluate_data_agent(
        df,
        data_agent_name,
        workspace_name=workspace_name,
        table_name=table_name,
        data_agent_stage=data_agent_stage
    )
    print(f"Unique ID for the current evaluation run: {evaluation_id}")
except Exception as e:
    print(f"Evaluation failed: {e}")

Une fois l’exécution terminée, une sortie similaire au texte suivant s’affiche :

Unique ID for the current evaluation run: <evaluation-id>

Obtenir le résumé de l’évaluation

Après avoir effectué l’évaluation, vous pouvez obtenir un résumé général des résultats en utilisant la get_evaluation_summary fonction. Cette fonction fournit des informations sur la performance globale de votre agent de données, y compris des indicateurs comme le nombre de réponses correspondant aux réponses attendues.

from fabric.dataagent.evaluation import get_evaluation_summary

# Retrieve a summary of the evaluation results
summary_df = get_evaluation_summary(table_name)

Par défaut, cette fonction recherche une table nommée evaluation_output. Si vous spécifiez un nom de table personnalisé lors de l’évaluation (comme demo_evaluation_output), passez ce nom comme table_name argument.

Le DataFrame retourné inclut des métriques agrégées telles que le nombre de réponses correctes, incorrectes ou non claires. Ce résultat vous permet d’évaluer rapidement la précision de l’agent et d’identifier les domaines d’amélioration.

Inspecter les résultats détaillés de l’évaluation

Pour approfondir la réponse de votre agent de données à chaque question individuelle, utilisez la get_evaluation_details fonction. Cette fonction retourne une répartition détaillée de l’exécution de l’évaluation, y compris les réponses réelles de l’agent, s’ils correspondent à la réponse attendue et un lien vers le thread d’évaluation (visible uniquement à l’utilisateur qui a exécuté l’évaluation).

from fabric.dataagent.evaluation import get_evaluation_details

# Table name used during evaluation
table_name = "demo_evaluation_output"

# Whether to return all evaluation rows (True) or only failures (False)
get_all_rows = False

# Whether to print a summary of the results
verbose = True

# Retrieve evaluation details for a specific run
eval_details = get_evaluation_details(
    evaluation_id,
    table_name,
    get_all_rows=get_all_rows,
    verbose=verbose
)

Personnaliser votre invite d’évaluation

Par défaut, le SDK Fabric utilise une invite intégrée pour évaluer si la réponse réelle de l'agent de données correspond à la réponse attendue. Cependant, vous pouvez fournir votre propre prompt pour des évaluations plus nuancées ou spécifiques au domaine en utilisant ce critic_prompt paramètre.

Votre requête personnalisée doit inclure les espaces réservés {query}, {expected_answer} et {actual_answer}. Le processus d’évaluation remplace dynamiquement ces substituts pour chaque question.

from fabric.dataagent.evaluation import evaluate_data_agent

# Define a custom prompt for evaluating agent responses
critic_prompt = """
    Given the following query, expected answer, and actual answer, please determine if the actual answer is equivalent to expected answer. If they are equivalent, respond with 'yes'.

    Query: {query}

    Expected Answer:
    {expected_answer}

    Actual Answer:
    {actual_answer}

    Is the actual answer equivalent to the expected answer?
"""

# Name of the data agent
data_agent_name = "AgentEvaluation"

# Run evaluation using the custom critic prompt
evaluation_id = evaluate_data_agent(df, data_agent_name, critic_prompt=critic_prompt)

Cette fonctionnalité est particulièrement utile quand :

• Vous voulez appliquer des critères plus souples ou plus stricts pour déterminer ce qui compte comme une correspondance.
• Vos réponses attendues et réelles peuvent varier dans leur format mais restent sémantiquement équivalentes.
• Vous devez capturer des nuances spécifiques au domaine dans la façon dont les réponses doivent être jugées.

Bouton de diagnostic

Le bouton Diagnostic vous permet de télécharger un instantané complet des étapes de configuration et d’exécution de votre agent de données. Cette exportation inclut des détails tels que les paramètres de la source de données, les instructions appliquées, les requêtes d’exemple utilisées et les étapes sous-jacentes suivies par l’agent de données pour générer sa réponse.

Utilisez cette fonctionnalité lorsque vous travaillez avec le Support Microsoft ou que vous dépannez des comportements inattendus. En examinant le fichier téléchargé, vous pouvez voir exactement comment l’agent de données a traité votre demande, quelles configurations ont été appliquées et où des problèmes potentiels sont survenus. Ce niveau de transparence facilite le débogage et l’optimisation des performances de votre agent de données.

Troubleshooting

Étapes suivantes

• Créer un agent de données Fabric
• Utilisez le Kit de développement logiciel (SDK) de l’agent de données Fabric
• Accéder à des exemples de notebooks sur l’utilisation du Kit de développement logiciel (SDK) de l’assistant de données