Utvärdera din dataagent (förhandsversion)

Genom att använda Fabric SDK för utvärdering kan du programmatiskt testa hur väl din dataagent svarar på frågor om naturligt språk. Genom att använda ett enkelt Python-gränssnitt kan du definiera exempel på grundsanning, köra utvärderingar och analysera resultat – allt inom din anteckningsboksmiljö. Denna process hjälper dig att validera noggrannhet, felsöka fel och självsäkert förbättra din agent innan den distribueras till produktion.

Förutsättningar

• En betald F2 eller högre Fabric Kapacitet, eller en Power BI Premium kapacitet per kapacitet (P1 eller högre) med Microsoft Fabric Aktiverat.
• Aktivera kors-geo-bearbetning och kors-geo-lagring för AI baserat på krav som beskrivs i klientinställningarna för Fabricdataagenten.
• Minst en av dessa datakällor, med data: Ett lager, ett sjöhus, en Power BI-semantisk modell, en KQL-databas, en speglad databas eller en ontologi. Du måste ha läsbehörighet till datakällan.

Installera dataagentens SDK

För att börja utvärdera din Fabric-dataagent programmatiskt, installera Fabric data agent Python SDK. Det här SDK:et innehåller de verktyg och metoder som krävs för att interagera med din dataagent, köra utvärderingar och loggresultat. Installera den senaste versionen genom att köra följande kommando i notebook-filen:

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

Det här steget säkerställer att du har de mest up-to-date-funktioner och korrigeringar som är tillgängliga i SDK: et.

Läs in datauppsättningen för grundsanning

För att utvärdera din Fabric-dataagent behöver du en uppsättning exempelfrågor tillsammans med de förväntade svaren. Använd dessa frågor för att verifiera hur korrekt agenten svarar på verkliga frågor.

Definiera dessa frågor direkt i din kod med hjälp 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)"]
    ]
)

Alternativt, om du har en befintlig utvärderingsdatamängd, ladda den från en CSV-fil med kolumnerna question och 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)

Den här datamängden fungerar som indata för att köra automatiserade utvärderingar mot din dataagent för att utvärdera noggrannhet och täckning.

Utvärdera och bedöm din dataagent

Nästa steg är att köra utvärderingen med hjälp av evaluate_data_agent funktionen. Den här funktionen jämför agentens svar med dina förväntade resultat och lagrar utvärderingsmåtten.

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

När körningen har slutförts ser du utdata som liknar följande text:

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

Hämta utvärderingssammanfattning

Efter att ha kört utvärderingen kan du hämta en övergripande sammanfattning av resultaten med hjälp av get_evaluation_summary funktionen. Denna funktion ger insikter om hur väl din dataagent presterade totalt sett, inklusive mätvärden som hur många svar som matchade de förväntade svaren.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Som standard letar denna funktion efter en tabell med namnet evaluation_output. Om du angav ett anpassat tabellnamn under utvärderingen (som demo_evaluation_output), skicka det namnet som table_name argument.

Den returnerade DataFrame innehåller aggregerade mått, till exempel antalet korrekta, felaktiga eller otydliga svar. Det här resultatet hjälper dig att snabbt utvärdera agentens noggrannhet och identifiera förbättringsområden.

Granska detaljerade utvärderingsresultat

För att fördjupa dig i hur din dataagent svarade på varje enskild fråga, använd funktionen get_evaluation_details . Den här funktionen returnerar en detaljerad uppdelning av utvärderingskörningen, inklusive de faktiska agentsvaren, om de matchade det förväntade svaret och en länk till utvärderingstråden (endast synlig för den användare som körde utvärderingen).

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
)

Anpassa din uppmaning för utvärdering

Som standard använder Fabric SDK en inbyggd prompt för att utvärdera om dataagentens faktiska svar matchar det förväntade svaret. Du kan dock tillhandahålla din egen prompt för mer nyanserade eller domänspecifika utvärderingar genom att använda parametern critic_prompt .

Din anpassade fråga bör innehålla platshållarna {query}, {expected_answer}och {actual_answer}. Utvärderingsprocessen ersätter dynamiskt dessa platshållare för varje fråga.

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)

Den här funktionen är särskilt användbar när:

• Du vill tillämpa mer generösa eller striktare kriterier för vad som räknas som en matchning.
• Dina förväntade och faktiska svar kan variera i format men ändå vara semantiskt likvärdiga.
• Du måste samla in domänspecifika nyanser i hur svar ska bedömas.

Diagnostikknapp

Diagnostikknappen låter dig ladda ner en fullständig ögonblicksbild av din dataagents konfiguration och exekveringssteg. Denna export inkluderar detaljer som datakällors inställningar, tillämpade instruktioner, använda exempelfrågor och de underliggande steg som dataagenten tog för att generera sitt svar.

Använd denna funktion när du arbetar med Microsoft Support eller felsöker oväntat beteende. Genom att granska den nedladdade filen kan du se exakt hur dataagenten behandlade din begäran, vilka konfigurationer som tillämpades och var potentiella problem uppstod. Denna nivå av transparens gör det enklare att felsöka och optimera din dataagents prestanda.

Troubleshooting

Nästa steg

• Skapa en Fabric-dataagent
• Använd Fabric data agent-SDK:n
• Få åtkomst till exempelanteckningsböcker om hur du använder dataagentens SDK