Evaluer dataagenten (forhåndsvisning)

Ved å bruke Fabric SDK for evaluering kan du programmatisk teste hvor godt dataagenten din svarer på spørsmål om naturlig språk. Ved å bruke et enkelt Python-grensesnitt kan du definere eksempler på grunnfakta, kjøre evalueringer og analysere resultater – alt innenfor notatboken din. Denne prosessen hjelper deg med å validere nøyaktighet, feilsøke feil og trygt forbedre agenten din før du distribuerer den til produksjon.

Forutsetninger

• A betalt F2 eller høyere Fabric kapasitet, eller en Power BI Premium per kapasitet (P1 eller høyere) kapasitet med Microsoft Fabric aktivert.
• Aktiver cross-geo prosessering og cross-geo lagring for AI basert på kravene som er beskrevet i Fabric data agent tenant-innstillingene.
• Minst én av disse datakildene, med data: Et lager, et innsjøhus, en Power BI-semantisk modell, en KQL-database, en speilet database eller en ontologi. Du må ha lesetilgang til datakilden.

Installer dataagenten SDK

For å komme i gang med å evaluere Fabric-dataagenten din programmatisk, installer Fabric-dataagenten Python SDK. Denne SDK-en inneholder verktøyene og metodene som kreves for å samhandle med dataagenten, kjøre evalueringer og logge resultater. Installer den nyeste versjonen ved å kjøre følgende kommando i notatblokken:

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

Dette trinnet sikrer at du har de mest up-to-dato-funksjonene og løsningene som er tilgjengelige i SDK-en.

Last inn datasettet for grunnsannhet

For å evaluere din Fabric-dataagent trenger du et sett med eksempelspørsmål sammen med forventede svar. Bruk disse spørsmålene for å verifisere hvor nøyaktig agenten svarer på virkelige spørsmål.

Definer disse spørsmålene direkte i koden din ved å bruke 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)"]
    ]
)

Alternativt, hvis du har et eksisterende evalueringsdatasett, last det inn fra en CSV-fil med kolonnene question 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 datasettet fungerer som inndata for å kjøre automatiserte evalueringer mot dataagenten for å vurdere nøyaktighet og dekning.

Evaluer og vurder dataagenten

Neste steg er å kjøre evalueringen ved å bruke funksjonen evaluate_data_agent . Denne funksjonen sammenligner agentens svar med dine forventede resultater og lagrer evalueringsmetrikkene.

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

Etter at gjennomspillingen er ferdig, ser du et resultat som ligner på følgende tekst:

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

Få evalueringssammendrag

Etter å ha kjørt evalueringen, kan du hente en overordnet oppsummering av resultatene ved å bruke funksjonen get_evaluation_summary . Denne funksjonen gir innsikt i hvor godt dataagenten din presterte totalt sett, inkludert måleparametere som hvor mange svar som matchet de forventede svarene.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Som standard ser denne funksjonen etter en tabell kalt evaluation_output. Hvis du spesifiserte et egendefinert tabellnavn under evalueringen (for eksempel demo_evaluation_output), gi det navnet som argument.table_name

Den returnerte DataFrame inkluderer aggregerte måledata, for eksempel antall riktige, uriktige eller uklare svar. Dette resultatet hjelper deg raskt å vurdere agentens nøyaktighet og identifisere forbedringsområder.

Undersøke detaljerte evalueringsresultater

For å gå dypere inn i hvordan dataagenten din svarte på hvert enkelt spørsmål, bruk funksjonen get_evaluation_details . Denne funksjonen returnerer en detaljert oversikt over evalueringskjøringen, inkludert de faktiske agentsvarene, om de samsvarte med det forventede svaret og en kobling til evalueringstråden (bare synlig for brukeren som kjø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
)

Tilpasse ledeteksten for evaluering

Som standard bruker Fabric SDK en innebygd prompt for å vurdere om dataagentens faktiske svar samsvarer med det forventede svaret. Du kan imidlertid gi din egen prompt for mer nyanserte eller domenespesifikke evalueringer ved å bruke parameteren critic_prompt .

Den egendefinerte ledeteksten bør inneholde plassholderne {query}, {expected_answer}og {actual_answer}. Evalueringsprosessen erstatter dynamisk disse plassholderne for hvert spørsmål.

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 funksjonen er spesielt nyttig når:

• Du bør bruke mer lempelige eller strengere kriterier for hva som teller som match.
• Dine forventede og faktiske svar kan variere i format, men er fortsatt semantisk likeverdige.
• Du må fange opp domenespesifikke nyanser i hvordan svar skal dømmes.

Diagnostikkknapp

Diagnostikk-knappen lar deg laste ned et fullstendig øyeblikksbilde av dataagentens konfigurasjon og utførelsestrinn. Denne eksporten inkluderer detaljer som datakildeinnstillinger, anvendte instruksjoner, eksempelspørringer som ble brukt, og de underliggende stegene dataagenten tok for å generere sitt svar.

Bruk denne funksjonen når du samarbeider med Microsoft Kundestøtte eller feilsøker uventet oppførsel. Ved å gjennomgå den nedlastede filen kan du se nøyaktig hvordan dataagenten behandlet forespørselen din, hvilke konfigurasjoner som ble brukt, og hvor potensielle problemer oppsto. Dette nivået av åpenhet gjør det enklere å feilsøke og optimalisere ytelsen til dataagenten din.

Feilsøking

Neste trinn

• Opprett en Fabric dataagent
• Bruk Fabric data agent SDK
• Få tilgang til eksempelnotatblokker om hvordan du bruker dataagenten SDK