Avalie seu agente de dados (versão prévia)

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

Importante

Esse recurso está na versão prévia.

Pré-requisitos

Instalar o SDK do agente de dados

Para começar a avaliar o agente de dados Fabric programaticamente, você precisa instalar o SDK do Python Fabric Data Agent. Esse SDK fornece as ferramentas e os métodos necessários para interagir com seu agente de dados, executar avaliações e resultados de log. Instale a versão mais recente executando o seguinte comando em seu notebook:

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

Essa etapa garante que você tenha os recursos e correções mais atualizados disponíveis no SDK.

Carregue seu conjunto de dados de verdade básica

Para avaliar seu agente de dados Fabric, você precisa de um conjunto de perguntas de exemplo junto 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 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)"]
    ]
)

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 executar avaliações automatizadas em seu agente de dados para avaliar a precisão e a cobertura.

Avalie e analise seu agente de dados

A próxima etapa é executar a avaliação usando a evaluate_data_agent função. Essa 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 insights sobre o desempenho geral do Agente de Dados, 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 o table_name argumento.

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

obter_resumo_avaliacao

Retorna um DataFrame contendo métricas de resumo de alto nível para uma execução de 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. Usa False como padrão.

Retornos:

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

Inspecionar os resultados detalhados da avaliação

Para se aprofundar em como o Agente de Dados respondeu a cada pergunta individual, use a get_evaluation_details função. Essa função retorna um detalhamento da execução de avaliação, incluindo as respostas reais do agente, se 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 de resultados específicos da avaliação do agente de dados.

obter_detalhes_da_avaliacao

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

Parâmetros de entrada:

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

Retornos:

  • 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 somente pelo usuário que executou a avaliação)

Personalize seu prompt para avaliação

Por padrão, o SDK do Fabric usa um prompt interno para avaliar se a resposta real do Agente de Dados corresponde à resposta 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.

Seu prompt personalizado deve incluir os espaços reservados {query}, {expected_answer}, e {actual_answer}. Esses marcadores de posição são substituídos dinamicamente para cada questão 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)

Esse recurso é especialmente útil quando:

  • Você quer aplicar critérios mais brandos ou mais rigorosos sobre o que conta como uma correspondência.
  • Suas respostas esperadas e reais podem variar no formato, mas ainda ser semanticamente equivalentes.
  • Você precisa capturar nuances específicas do domínio sobre como as respostas devem ser julgadas.

Botão Diagnóstico

O botão Diagnóstico permite que você baixe um instantâneo completo das etapas de configuração e execução do Agente de Dados. Essa exportação inclui detalhes como configurações de 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 esse recurso ao trabalhar com Suporte da Microsoft ou solucionar problemas de comportamento inesperado. Ao examinar 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. Esse nível de transparência facilita a depuração e otimização do desempenho do Agente de Dados.

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

Próximas etapas

  • Last updated on