Evaluer din dataagent (prøveversion)

Evaluering med Fabric SDK giver dig mulighed for programmatisk at teste, hvor godt din Data Agent svarer på spørgsmål om naturligt sprog. Ved at bruge en simpel Python-grænseflade kan du definere eksempler på grundsandhed, køre evalueringer og analysere resultater – alt sammen inden for dit notebook-miljø. Dette hjælper dig med at validere nøjagtighed, fejlfindingsfejl og med sikkerhed forbedre din agent, før du udruller den til produktion.

Forudsætninger

• A betalt F2 eller højere Fabric kapacitet, eller en Power BI Premium pr. kapacitet (P1 eller højere) kapacitet med Microsoft Fabric aktiveret.
• Aktiver cross-geo behandling og cross-geo lagring for AI baseret på krav, der er beskrevet i Fabric data agent tenant-indstillingerne.
• Mindst én af disse datakilder, med data: Et lager, et søhus, en Power BI semantisk model, en KQL-database, en spejlet database eller en ontologi. Du skal have læseadgang til datakilden.

Installér dataagent-SDK'et

For at komme i gang med at evaluere din Fabric Data Agent programmatisk, skal du installere the Fabric Data Agent Python SDK. Dette SDK indeholder de værktøjer og metoder, der kræves for at interagere med din dataagent, køre evalueringer og logføre resultater. Installér den nyeste version ved at køre følgende kommando i notesbogen:

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

Dette trin sikrer, at du har de mest up-to-date-funktioner og -rettelser, der er tilgængelige i SDK'et.

Indlæs dit ground truth-datasæt

For at evaluere din Fabric Data Agent har du brug for et sæt eksempelspørgsmål sammen med de forventede svar. Disse spørgsmål bruges til at bekræfte, hvor præcist agenten reagerer på forespørgsler fra den virkelige verden.

Du kan definere disse spørgsmål direkte i din kode ved hjælp af en 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)"]
    ]
)

Hvis du har et eksisterende evalueringsdatasæt, kan du også indlæse det fra en CSV-fil med spørgsmålet om kolonner og 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)

Dette datasæt fungerer som input til kørsel af automatiserede evalueringer i forhold til din dataagent for at vurdere nøjagtighed og dækning.

Evaluer og vurder din dataagent

Det næste trin er at køre evalueringen ved hjælp af evaluate_data_agent funktionen . Denne funktion sammenligner agentens svar med dine forventede resultater og gemmer evalueringsmålingerne.

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

Hent evalueringsoversigt

Når du har kørt evalueringen, kan du hente en oversigt på højt niveau over resultaterne ved hjælp af funktionen get_evaluation_summary . Denne funktion giver indsigt i, hvor godt din dataagent klarede sig samlet – herunder målepunkter, f.eks. hvor mange svar der svarede til de forventede svar.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Denne funktion søger som standard efter en tabel med navnet evaluation_output. Hvis du har angivet et brugerdefineret tabelnavn under evalueringen (f.eks. "demo_evaluation_output"), skal du overføre dette navn som table_name argument.

Den returnerede DataFrame indeholder aggregerede målepunkter, f.eks. antallet af korrekte, forkerte eller uklare svar. Dette resultat hjælper dig med hurtigt at vurdere agentens nøjagtighed og identificere områder, der kan forbedres.

get_evaluation_summary

Returnerer en DataFrame, der indeholder overordnede målepunkter på højt niveau for en fuldført evalueringskørsel, f.eks. antallet af korrekte, forkerte og uklare svar.

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

Inputparametre:

• table_name (str, valgfrit) – navnet på den tabel, der indeholder resultaterne af evalueringsoversigten. Som standard ''evaluation_output.
• verbose (bool, valgfrit) – Hvis den er angivet til True, udskrives en oversigt over evalueringsmålepunkter til konsollen. Er som Falsestandard .

Returnerer:

• DataFrame – En pandas DataFrame, der indeholder oversigtsstatistikker for evalueringen, f.eks.:
  • Samlet antal evaluerede spørgsmål
  • Antal sande, falske og uklare resultater
  • Nøjagtighed

Undersøg detaljerede evalueringsresultater

Hvis du vil dykke dybere ned i, hvordan din dataagent besvarede hvert enkelt spørgsmål, skal du bruge funktionen get_evaluation_details . Denne funktion returnerer en detaljeret opdeling af evalueringskørslen, herunder de faktiske agentsvar, om de svarede til det forventede svar, og et link til evalueringstråden (kun synlig for den bruger, der kørte evalueringen).

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
)

get_evaluation_details

Returnerer en DataFrame, der indeholder detaljerede resultater for en bestemt evalueringskørsel, herunder spørgsmål, forventede svar, agentsvar, evalueringsstatus og diagnosticeringsmetadata.

Inputparametre:

• evaluation_id (str) – påkrævet. Det entydige id for den evalueringskørsel, der skal hentes oplysninger om.
• table_name (str, valgfrit) – navnet på den tabel, der indeholder evalueringsresultaterne. Er som evaluation_outputstandard .
• get_all_rows (bool, valgfri) – om alle rækker skal returneres fra evalueringen (Sand) eller kun rækker, hvor agentens svar var forkert eller uklart (Falsk). Er som Falsestandard .
• verbose (bool, valgfrit) – hvis den er angivet til Sand, udskrives en oversigt over evalueringsdata i konsollen. Er som Falsestandard .

Returnerer:

• DataFrame – En pandas DataFrame, der indeholder evalueringsresultater på rækkeniveau, herunder:

  • question
  • expected_answer
  • actual_answer
  • evaluation_result(true, false, ) unclear
  • thread_url (kun tilgængelig for den bruger, der kørte evalueringen)

Tilpas din anmodning om evaluering

Som standard bruger Fabric SDK en indbygget prompt til at vurdere, om Data Agents faktiske svar matcher det forventede svar. Du kan dog angive din egen anmodning om mere nuancerede eller domænespecifikke evalueringer ved hjælp af critic_prompt parameteren .

Den brugerdefinerede prompt skal indeholde pladsholderne {query}, {expected_answer}og {actual_answer}. Disse pladsholdere erstattes dynamisk af hvert spørgsmål under evalueringen.

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)

Denne funktion er især nyttig, når:

• Du vil søge efter mere lempelige eller strengere kriterier, der tæller som et match.
• Dine forventede og faktiske svar kan variere i format, men de er stadig semantisk ækvivalente.
• Du skal registrere domænespecifikke nuancer i, hvordan svar skal bedømmes.

Knap Diagnosticering

Knappen Diagnosticering giver dig mulighed for at downloade et komplet øjebliksbillede af din Data Agents konfigurations- og udførelsestrin. Denne eksport indeholder oplysninger som f.eks. indstillinger for datakilde, anvendte instruktioner, anvendte eksempelforespørgsler og de underliggende trin, som Data Agent tog for at generere sit svar.

Brug denne funktion, når du arbejder med Microsoft Support eller fejlsøger uventet adfærd. Ved at gennemgå den downloadede fil kan du se præcis, hvordan dataagenten behandlede din anmodning, hvilke konfigurationer der blev anvendt, og hvor der kan være opstået potentielle problemer. Dette niveau af gennemsigtighed gør det nemmere at fejlfinde og optimere din Data Agents ydeevne.

Næste trin

• Brug den Fabric dataagent SDK
• Få adgang til eksempelnotesbøger om, hvordan du bruger Data Agent SDK