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

Usando o Fabric SDK para avaliação, você pode testar programaticamente quão bem seu agente de dados responde a perguntas em linguagem natural. Usando uma interface simples em Python, você pode definir exemplos de verdade no terreno, rodar avaliações e analisar resultados — tudo dentro do ambiente do seu caderno. Esse processo ajuda você a validar a 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 seu agente de dados Fabric programaticamente, instale o Fabric data agent SDK Python. 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. Use essas perguntas para verificar quão precisa o agente responde às consultas do mundo real.

Defina essas perguntas diretamente no seu código usando um DataFrame do 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, se você já tiver um conjunto de dados de avaliação, carregue-o a partir de um arquivo CSV com as colunas question 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

O próximo passo é 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.

Note

Essa etapa requer um agente de dados que já esteja publicado no ambiente que você está avaliando (production ou sandbox). Se você ainda não tem um, veja Criar um agente de dados 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}")

Após o término da execução, você vê um resultado semelhante ao texto a seguir:

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

Obter resumo da avaliação

Após executar a avaliação, você pode obter 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 seu agente de dados, incluindo métricas como quantas respostas corresponderam às 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 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 não claras. Esse resultado ajuda você a avaliar rapidamente a precisão do agente e identificar áreas de melhoria.

Inspecionar os resultados detalhados da avaliação

Para aprofundar como seu 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.

Personalize seu prompt para avaliação

Por padrão, o Fabric SDK usa um prompt embutido para avaliar se a resposta real do agente de dados corresponde à esperada. No entanto, você pode fornecer seu próprio prompt para avaliações mais nuançadas ou específicas de domínio usando o critic_prompt parâmetro.

Seu prompt personalizado deve incluir os espaços reservados {query}, {expected_answer}, e {actual_answer}. O processo de avaliação substitui dinamicamente esses espaços reservados para cada pergunta.

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 flexíveis ou mais rigorosos para definir o que é considerado uma correspondência.
  • Suas respostas esperadas e reais podem variar no formato, mas ainda assim serem semanticamente equivalentes.
  • Você precisa capturar nuances específicas do domínio sobre como as respostas devem ser julgadas.

Botão de diagnóstico

O botão Diagnósticos permite baixar um snapshot completo das etapas de configuração e execução do seu agente de dados. Essa exportação inclui detalhes como configurações da fonte de dados, instruções aplicadas, consultas de exemplo usadas e os passos subjacentes que o agente de dados seguiu para gerar sua resposta.

Use esse recurso quando trabalhar com o Suporte da Microsoft ou tentar resolver comportamentos inesperados. Ao revisar 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 ocorreram. Esse nível de transparência facilita a depuração e otimização do desempenho do seu agente de dados.

Captura de tela do botão de diagnóstico no data agent.

Troubleshooting

Issue Cause Resolução
Agente de dados não encontrado O data_agent_name ou workspace_name está incorreto, ou o agente não está publicado. Verifique o nome e o espaço de trabalho do agente e certifique-se de que ele tenha sido publicado no local especificado data_agent_stage.
Resultados vazios ou ausentes O nome da tabela não corresponde ao usado durante evaluate_data_agent. Passe o mesmo table_name para get_evaluation_summary e get_evaluation_details.
message_url não é acessível Threads de avaliação são visíveis apenas para o usuário que executou a avaliação. Execute novamente a avaliação com sua própria identidade para acessar os links do tópico.
O prompt personalizado não surte efeito ou apresenta erros O critic_prompt não contém os placeholders obrigatórios. Inclua {query}, {expected_answer}, e {actual_answer} no seu prompt.
Erro de permissão ou capacidade Falta de capacidade F2 ou superior, ou falta de acesso de leitura à fonte de dados. Confirme os pré-requisitos, incluindo capacidade e acesso à leitura da fonte de dados.

Próximas etapas

  • Última atualização em