Avalie o seu/vosso agente de dados (em visualização)

A avaliação com o Fabric SDK permite-lhe testar programaticamente quão bem o seu Data Agent responde a perguntas em linguagem natural. Usando uma interface simples em Python, pode definir exemplos de verdade básica, executar avaliações e analisar resultados — tudo no ambiente do seu notebook. Isso ajuda você a validar a precisão, depurar erros e melhorar com confiança seu agente antes de implantá-lo na produção.

Importante

Este recurso está em pré-visualização.

Pré-requisitos

Instalar o SDK do agente de dados

Para começar a avaliar programaticamente o seu Fabric Data Agent, precisa de instalar the Fabric Data Agent Python SDK. Este SDK fornece as ferramentas e os métodos necessários para interagir com seu agente de dados, executar avaliações e registrar resultados. Instale a versão mais recente executando o seguinte comando no seu bloco de notas:

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

Esta etapa garante que tenha os recursos e correções mais atualizados up-todisponíveis no SDK.

Carregue seu conjunto de dados de verdade terrestre

Para avaliar o seu Fabric Data Agent, precisa de um conjunto de perguntas de exemplo juntamente com as respostas esperadas. Essas perguntas são usadas para verificar com que precisão o agente responde a consultas do mundo real.

Você pode definir essas perguntas diretamente em seu código usando um Pandas DataFrame:

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, se você tiver um conjunto de dados de avaliação existente, poderá carregá-lo de um arquivo CSV com as colunas pergunta e 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)

Esse conjunto de dados serve como entrada para a execução de avaliações automatizadas em relação ao seu agente de dados para avaliar a precisão e a cobertura.

Avalie e analise o seu agente de dados

O próximo passo é executar a avaliação usando a evaluate_data_agent função. Esta função compara as respostas do agente com os resultados esperados e armazena as métricas de avaliação.

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

Obter resumo da avaliação

Depois de executar a avaliação, você pode recuperar um resumo de alto nível dos resultados usando a get_evaluation_summary função. Essa função fornece informações sobre o desempenho geral do seu Data Agent, incluindo métricas como quantas respostas corresponderam às respostas esperadas.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Captura de tela mostrando o resumo dos resultados da avaliação do agente de dados.

Por padrão, essa função procura uma tabela chamada evaluation_output. Se você especificou um nome de tabela personalizado durante a avaliação (como "demo_evaluation_output"), passe esse nome como argumento table_name .

O DataFrame retornado inclui métricas agregadas, como o número de respostas corretas, incorretas ou pouco claras. Este resultado ajuda-o a avaliar rapidamente a precisão do agente e a identificar áreas a melhorar.

get_evaluation_summary

Retorna um DataFrame contendo métricas de resumo de elevado nível para uma avaliação concluída, como o número de respostas corretas, incorretas e pouco claras.

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

Parâmetros de entrada:

  • table_name (str, opcional) – O nome da tabela que contém os resultados do resumo da avaliação. O padrão é 'evaluation_output'.
  • verbose (bool, opcional) – Se definido como True, imprime um resumo das métricas de avaliação no console. O padrão é False.

Devoluções:

  • DataFrame – Um Pandas DataFrame contendo estatísticas resumidas para a avaliação, tais como:
    • Número total de perguntas avaliadas
    • Contagens de resultados verdadeiros, falsos e incertos
    • Exatidão

Inspecionar resultados detalhados da avaliação

Para se aprofundar em como seu Agente de Dados respondeu a cada pergunta individual, use a get_evaluation_details função. Esta função retorna um detalhamento detalhado da execução da avaliação, incluindo as respostas reais do agente, se elas corresponderam à resposta esperada e um link para o thread de avaliação (visível apenas para o usuário que executou a avaliação).

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 tela mostrando detalhes dos resultados de uma avaliação específica do agente de dados.

obter_detalhes_avaliação

Retorna um DataFrame contendo resultados detalhados para uma execução de avaliação específica, incluindo perguntas, respostas esperadas, respostas do agente, status da avaliação e metadados de diagnóstico.

Parâmetros de entrada:

  • evaluation_id (str) – Obrigatório. O identificador exclusivo para a execução da avaliação para recuperar detalhes.
  • table_name (str, opcional) – O nome da tabela que contém os resultados da avaliação. O padrão é evaluation_output.
  • get_all_rows (bool, opcional) – Se deve devolver todas as linhas da avaliação (Verdadeiro) ou apenas linhas em que a resposta do agente foi incorreta ou pouco clara (Falso). O padrão é False.
  • verbose (bool, opcional) – Se definido como True, imprime um resumo das métricas de avaliação no console. O padrão é False.

Devoluções:

  • DataFrame – Um DataFrame pandas contendo resultados de avaliação em nível de linha, incluindo:

    • question
    • expected_answer
    • actual_answer
    • evaluation_result (true, false, unclear)
    • thread_url (acessível apenas pelo utilizador que executou a avaliação)

Personalize seu prompt para avaliação

Por defeito, o Fabric SDK utiliza um prompt incorporado para avaliar se a resposta real do Data Agent corresponde à esperada. No entanto, você pode fornecer seu próprio prompt para avaliações mais matizadas ou específicas do domínio usando o critic_prompt parâmetro.

O seu prompt personalizado deve incluir os marcadores {query}, {expected_answer} e {actual_answer}. Estes espaços reservados são dinamicamente substituídos para cada pergunta durante a avaliação.

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)

Este recurso é especialmente útil quando:

  • Você quer aplicar critérios mais brandos ou mais rigorosos para o que é considerado uma correspondência.
  • Suas respostas esperadas e reais podem variar em formato, mas ainda assim ser semanticamente equivalentes.
  • Você precisa capturar nuances específicas de um domínio na forma como as respostas devem ser avaliadas.

Botão de diagnóstico

O botão de Diagnóstico permite-lhe descarregar um snapshot completo dos passos de configuração e execução do seu Data Agent. Essa exportação inclui detalhes como configurações da fonte de dados, instruções aplicadas, consultas de exemplo usadas e as etapas subjacentes que o Agente de Dados tomou para gerar sua resposta.

Use esta funcionalidade ao trabalhar com o Suporte da Microsoft ou ao resolver comportamentos inesperados. Ao analisar o arquivo baixado, você pode ver exatamente como o Agente de Dados processou sua solicitação, quais configurações foram aplicadas e onde possíveis problemas podem ter ocorrido. Este nível de transparência facilita a depuração e otimização do desempenho do seu Data Agent.

Captura de ecrã do botão de diagnóstico no Agente de Dados

Próximos passos

  • Last updated on