Evaluación del agente de datos (versión preliminar)

Al usar el SDK Fabric para evaluación, puedes probar programáticamente qué tan bien responde tu agente de datos a preguntas de lenguaje natural. Utilizando una interfaz sencilla de Python, puedes definir ejemplos de verdad concreta, realizar evaluaciones y analizar resultados, todo dentro del entorno de tu cuaderno. Este proceso te ayuda a validar la precisión, depurar errores y mejorar tu agente con confianza antes de desplegarlo en producción.

Importante

Esta característica se encuentra en versión preliminar.

Prerrequisitos

Instalación del SDK del agente de datos

Para empezar a evaluar tu agente de datos Fabric de forma programática, instala el SDK Python del agente de datos Fabric. Este SDK proporciona las herramientas y los métodos necesarios para interactuar con el agente de datos, ejecutar evaluaciones y registrar resultados. Instale la versión más reciente ejecutando el comando siguiente en el cuaderno:

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

Este paso garantiza que tiene las características y correcciones más actualizadas disponibles en el SDK.

Carga del conjunto de verdad fundamental

Para evaluar tu agente de datos Fabric, necesitas un conjunto de preguntas de ejemplo junto con las respuestas esperadas. Utiliza estas preguntas para verificar qué tan precisa responde el agente a las consultas del mundo real.

Define estas preguntas directamente en tu código usando 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)"]
    ]
)

Alternativamente, si tienes un conjunto de datos de evaluación existente, cárgalo desde un archivo CSV con las columnas question y 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)

Este conjunto de datos actúa como entrada para ejecutar evaluaciones automatizadas en el agente de datos para evaluar la precisión y la cobertura.

Evaluación del agente de datos

El siguiente paso es ejecutar la evaluación utilizando la evaluate_data_agent función. Esta función compara las respuestas del agente con los resultados esperados y almacena las métricas de evaluación.

Note

Este paso requiere un agente de datos que ya esté publicado en la fase que evalúas (production o sandbox). Si aún no tienes uno, consulta Crear un agente de datos Fabric.

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

Cuando termina la ejecución, ves una salida similar al siguiente texto:

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

Obtener resumen de evaluación

Tras realizar la evaluación, puedes obtener un resumen general de los resultados utilizando la get_evaluation_summary función. Esta función proporciona información sobre cómo ha funcionado tu agente de datos en general, incluyendo métricas como cuántas respuestas coincidían con las respuestas esperadas.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Captura de pantalla que muestra el resumen de los resultados de evaluación del agente de datos.

Por defecto, esta función busca una tabla llamada evaluation_output. Si especificas un nombre de tabla personalizado durante la evaluación (como demo_evaluation_output), pasa ese nombre como table_name argumento.

La trama de datos devuelta incluye métricas agregadas, como el número de respuestas correctas, incorrectas o poco claras. Este resultado le ayuda a evaluar rápidamente la precisión del agente e identificar las áreas para mejorar.

Inspección de los resultados detallados de la evaluación

Para profundizar en cómo respondió tu agente de datos a cada pregunta individual, utiliza la get_evaluation_details función. Esta función devuelve un desglose detallado de la ejecución de evaluación, incluidas las respuestas reales del agente, si coinciden con la respuesta esperada y un vínculo al subproceso de evaluación (visible solo para el usuario que ejecutó la evaluación).

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
)

Captura de pantalla que muestra los detalles de los resultados de evaluación de un agente de datos específico.

Personaliza tu solicitud para evaluación

Por defecto, el Fabric SDK utiliza un prompt incorporado para evaluar si la respuesta real del agente de datos coincide con la esperada. Sin embargo, puedes proporcionar tu propio prompt para evaluaciones más matizadas o específicas de dominio usando el critic_prompt parámetro.

Tu indicación personalizada debe incluir los marcadores de posición {query}, {expected_answer} y {actual_answer}. El proceso de evaluación sustituye dinámicamente estos marcadores de posición para cada pregunta.

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)

Esta característica es especialmente útil cuando:

  • Quieres aplicar criterios más flexibles o estrictos para determinar qué cuenta como coincidencia.
  • Tus respuestas esperadas y reales pueden variar en formato, pero seguir siendo semánticamente equivalentes.
  • Necesita captar los matices específicos del dominio sobre cómo se deben juzgar las respuestas.

Botón de diagnóstico

El botón de Diagnóstico te permite descargar una instantánea completa de los pasos de configuración y ejecución de tu agente de datos. Esta exportación incluye detalles como la configuración de la fuente de datos, instrucciones aplicadas, consultas de ejemplo utilizadas y los pasos subyacentes que el agente de datos siguió para generar su respuesta.

Utiliza esta función cuando trabajes con Soporte técnico de Microsoft o para solucionar problemas inesperados. Al revisar el archivo descargado, puedes ver exactamente cómo el agente de datos procesó tu solicitud, qué configuraciones se aplicaron y dónde surgieron posibles problemas. Este nivel de transparencia facilita la depuración y optimización del rendimiento de tu agente de datos.

Captura de pantalla del botón de diagnóstico en el agente de datos.

Troubleshooting

Cuestión Causa Resolution
Agente de datos no encontrado El data_agent_name o workspace_name es incorrecto, o el agente no está publicado. Verifica el nombre y el espacio de trabajo del agente, y asegúrate de que el agente esté publicado en el data_agent_stage especificado.
Resultados vacíos o ausentes El nombre de la tabla no coincide con el usado durante evaluate_data_agent. Pasa lo mismo table_name a get_evaluation_summary y get_evaluation_details.
message_url no es accesible Los hilos de evaluación son visibles solo para el usuario que realizó la evaluación. Vuelve a ejecutar la evaluación bajo tu propia identidad para acceder a los enlaces del hilo.
La instrucción personalizada no tiene efecto o produce errores A critic_prompt le faltan marcadores de posición obligatorios. Incluye {query}, {expected_answer}, y {actual_answer} en tu prompt.
Error de permisos o de capacidad Falta capacidad F2 o superior, o falta acceso de lectura al origen de datos. Confirma los requisitos previos, incluyendo capacidad y acceso a la lectura de fuentes de datos.

Pasos siguientes

  • Last updated on