Evaluer dataagenten (forhåndsvisning)

Evaluering med Fabric SDK lar deg 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å grunnsannhet, kjøre evalueringer og analysere resultater—alt innenfor notatboken din. Dette hjelper deg med å validere nøyaktighet, feilsøke feil og forbedre agenten trygt før du distribuerer den til produksjon.

Viktig!

Denne funksjonen er i forhåndsvisning.

Forutsetninger

Installer dataagenten SDK

For å komme i gang med å evaluere din Fabric Data Agent programmatisk, må du installere the Fabric Data Agent 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 Data Agent trenger du et sett med eksempelspørsmål sammen med forventede svar. Disse spørsmålene brukes til å bekrefte hvor nøyaktig agenten reagerer på virkelige spørringer.

Du kan definere disse spørsmålene direkte i koden ved hjelp av 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 evalueringsdatasett, kan du eventuelt laste det inn fra en CSV-fil med kolonnespørsmålet 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 trinn er å kjøre evalueringen ved hjelp av evaluate_data_agent funksjonen. 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
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}")

Få evalueringssammendrag

Når du har kjørt evalueringen, kan du hente et sammendrag på høyt nivå av resultatene ved hjelp av get_evaluation_summary funksjonen. Denne funksjonen gir innsikt i hvor godt dataagenten utførte samlet sett , inkludert måledata som hvor mange svar som samsvarte med de forventede svarene.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Skjermbilde som viser sammendrag av evalueringsresultatene for dataagenten.

Som standard ser denne funksjonen etter en tabell med navnet evaluation_output. Hvis du har angitt et egendefinert tabellnavn under evalueringen (for eksempel «demo_evaluation_output» sender du dette navnet som table_name argumentet.

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.

get_evaluation_summary

Returnerer en dataramme som inneholder sammendragsmål på høyt nivå for en fullført evalueringskjøring, for eksempel antall riktige, feil og uklare svar.

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

Inndataparametere:

  • table_name (str, valgfritt) – navnet på tabellen som inneholder evalueringssammendragsresultatene. Standarder til 'evaluation_output'.
  • verbose (boolsk, valgfritt) – Hvis angitt til True, skriver du ut et sammendrag av evalueringsmåledata til konsollen. Standarder til False.

Returnerer:

  • DataFrame – En pandas DataFrame som inneholder sammendragsstatistikk for evalueringen, for eksempel:
    • Totalt antall evaluerte spørsmål
    • Antall sanne, falske og uklare resultater
    • Nøyaktighet

Undersøke detaljerte evalueringsresultater

Hvis du vil gå dypere ned i hvordan dataagenten svarte på hvert enkelt spørsmål, bruker get_evaluation_details du funksjonen. 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
)

Skjermbilde som viser detaljer om bestemte evalueringsresultater for dataagenter.

get_evaluation_details

Returnerer en DataFrame som inneholder detaljerte resultater for en bestemt evalueringskjøring, inkludert spørsmål, forventede svar, agentsvar, evalueringsstatus og diagnosedata.

Inndataparametere:

  • evaluation_id (str) – obligatorisk. Den unike identifikatoren for evalueringskjøringen for å hente detaljer for.
  • table_name (str, valgfritt) – navnet på tabellen som inneholder evalueringsresultatene. Standarder til evaluation_output.
  • get_all_rows (bool, valgfritt) – Om alle rader fra evalueringen skal returneres (Sant) eller kun rader der agentens svar var feil eller uklart (Falskt). Standarder til False.
  • verbose (boolsk, valgfritt) – Hvis satt til Sann, skriver du ut et sammendrag av evalueringsmåledata til konsollen. Standarder til False.

Returnerer:

  • DataFrame – En pandas DataFrame som inneholder evalueringsresultater på radnivå, inkludert:

    • question
    • expected_answer
    • actual_answer
    • evaluation_result(true, false, ) unclear
    • thread_url (bare tilgjengelig for brukeren som kjørte evalueringen)

Tilpasse ledeteksten for evaluering

Som standard bruker Fabric SDK en innebygd prompt for å vurdere om Data Agents faktiske svar stemmer overens med det forventede svaret. Du kan imidlertid angi din egen ledetekst for mer nyanserte eller domenespesifikke evalueringer ved hjelp av parameteren critic_prompt .

Den egendefinerte ledeteksten bør inneholde plassholderne {query}, {expected_answer}og {actual_answer}. Disse plassholderne erstattes dynamisk for hvert spørsmå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 funksjonen er spesielt nyttig når:

  • Du vil søke om mildere eller strengere vilkår som teller som et treff.
  • Forventede og faktiske svar kan variere i format, men likevel være semantisk like.
  • Du må fange opp domenespesifikke nyanser i hvordan svar skal dømmes.

Diagnostikk-knapp

Diagnostikk-knappen lar deg laste ned et fullstendig øyeblikksbilde av Dataagentens konfigurasjon og utførelsestrinn. Denne eksporten inneholder detaljer som datakildeinnstillinger, brukte instruksjoner, eksempelspørringer som brukes, og de underliggende trinnene dataagenten tok for å generere svaret.

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

Skjermbilde av diagnoseknappen i dataagenten

Neste trinn

  • Last updated on