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

2025-05-06

A avaliação com o SDK de malha permite que você teste programaticamente o quão bem seu 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 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.

Pré-requisitos

Um recurso de capacidade Fabric F2 pago ou superior
As configurações do locatário do agente de dados de infraestrutura estão habilitadas.
A mudança de locatário do Copilot está habilitada.
O processamento geográfico cruzado para IA está habilitado.
O armazenamento geográfico cruzado para IA está habilitado.
Pelo menos uma das seguintes fontes de dados: um armazém, uma casa de lago, um ou mais modelos semânticos do Power BI ou um banco de dados KQL com dados.

Instalar o SDK do agente de dados

Para começar a avaliar seu Fabric Data Agent programaticamente, você precisa instalar o SDK Python do Fabric Data Agent. 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 seu Fabric Data Agent, você 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)

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. Esse resultado ajuda a avaliar rapidamente a precisão do agente e identificar áreas para melhoria.

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
)

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 todas as linhas da avaliação devem ser retornadas (True) ou apenas as linhas em que a resposta do agente foi incorreta ou pouco clara (False). 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 padrão, o SDK da malha 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.

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.