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

La evaluación con el SDK de Fabric permite probar mediante programación cómo responde el agente de datos a preguntas de lenguaje natural. Con una interfaz de Python sencilla, puede definir ejemplos de verdad básica, ejecutar evaluaciones y analizar resultados, todo ello en el entorno del cuaderno. Esto le ayuda a validar la precisión, depurar errores y mejorar con confianza el agente antes de implementarlo 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 el Agente de Datos de Fabric mediante programación, debe instalar el SDK de Python del Agente de Datos de 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 el agente de datos de Fabric, necesita un conjunto de preguntas de ejemplo junto con las respuestas esperadas. Estas preguntas se usan para comprobar con qué precisión responde el agente a las consultas del mundo real.

Puede definir estas preguntas directamente en el código mediante un dataframe de 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)"]
    ]
)

Como alternativa, si tiene un conjunto de datos de evaluación existente, puede cargarlo desde un archivo CSV con la pregunta de columnas 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 consiste en ejecutar la evaluación mediante 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.

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

Obtener resumen de evaluación

Después de ejecutar la evaluación, puede recuperar un resumen de alto nivel de los resultados mediante la get_evaluation_summary función . Esta función proporciona información sobre el rendimiento general del agente de datos, incluidas las métricas, como el número de respuestas que coinciden con las respuestas esperadas.

from fabric.dataagent.evaluation import get_evaluation_summary

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

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

De forma predeterminada, esta función busca una tabla denominada evaluation_output. Si especificó un nombre de tabla personalizado durante la evaluación (como "demo_evaluation_output"), pase 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.

obtener_resumen_evaluación

Devuelve un DataFrame que contiene métricas de resumen generales para una ejecución de evaluación completada, como el número de respuestas correctas, incorrectas y poco claras.

get_evaluation_summary(table_name='evaluation_output', verbose=False)

Parámetros de entrada:

  • table_name (str, opcional): el nombre de la tabla que contiene los resultados del resumen de evaluación. El valor predeterminado es "evaluation_output".
  • verbose (bool, opcional): si se establece en True, imprime un resumen de las métricas de evaluación en la consola. Tiene como valor predeterminado False.

Devuelve:

  • DataFrame – DataFrame de Pandas que contiene estadísticas de resumen para la evaluación, como:
    • Número total de preguntas evaluadas
    • Recuentos de resultados verdaderos, falsos y poco claros
    • Precisión

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

Para profundizar en cómo respondió el Agente de datos a cada pregunta individual, use 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.

obtener_detalles_evaluación

Devuelve un DataFrame que contiene resultados detallados para una ejecución de evaluación específica, incluidas preguntas, respuestas esperadas, respuestas del agente, estado de evaluación y metadatos de diagnóstico.

Parámetros de entrada:

  • evaluation_id (str) – Obligatorio. Id. único para la ejecución de evaluación de la que se obtienen detalles.
  • table_name (str, opcional): el nombre de la tabla que contiene los resultados de la evaluación. Tiene como valor predeterminado evaluation_output.
  • get_all_rows (bool, opcional): indica si se devuelven todas las filas de la evaluación (True) o solo las filas en las que la respuesta del agente era incorrecta o poco clara (False). Tiene como valor predeterminado False.
  • verbose (bool, opcional): si se establece en True, imprime un resumen de las métricas de evaluación en la consola. Tiene como valor predeterminado False.

Devuelve:

  • DataFrame: DataFrame de Pandas que contiene resultados de evaluación de nivel de fila, entre los que se incluyen los siguientes:

    • question
    • expected_answer
    • actual_answer
    • evaluation_result (true, false, unclear)
    • thread_url (solo accesible por el usuario que ejecutó la evaluación)

Personaliza tu solicitud para evaluación

De forma predeterminada, el SDK de Fabric usa una solicitud integrada para evaluar si la respuesta real del Agente de datos coincide con la respuesta esperada. Sin embargo, puede proporcionar su propia solicitud para evaluaciones más matizadas o específicas del dominio mediante el critic_prompt parámetro .

Tu indicación personalizada debe incluir los marcadores de posición {query}, {expected_answer} y {actual_answer}. Estos marcadores de posición se sustituyen dinámicamente para cada pregunta durante la evaluación.

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:

  • Quiere aplicar criterios más laxos o más estrictos para lo que se considera una coincidencia.
  • Las respuestas esperadas y reales pueden variar en formato, pero siguen siendo semánticamente equivalentes.
  • Necesita captar los matices específicos del dominio sobre cómo se deben juzgar las respuestas.

Botón Diagnósticos

El botón Diagnósticos permite descargar una instantánea completa de los pasos de configuración y ejecución del Agente de datos. Esta exportación incluye detalles como la configuración del origen de datos, las instrucciones aplicadas, las consultas de ejemplo usadas y los pasos subyacentes que tomó el Agente de datos para generar su respuesta.

Use esta característica al trabajar con Microsoft Support o solucionar problemas de comportamiento inesperado. Al revisar el archivo descargado, puede ver exactamente cómo procesó el Agente de datos la solicitud, qué configuraciones se aplicaron y dónde se pueden haber producido posibles problemas. Este nivel de transparencia facilita la depuración y optimización del rendimiento del agente de datos.

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

Pasos siguientes

  • Last updated on