Uw gegevensagent evalueren (preview)

Door gebruik te maken van de Fabric SDK voor evaluatie kun je programmatisch testen hoe goed je dataagent reageert op vragen in natuurlijke taal. Met een eenvoudige Python-interface kun je voorbeelden van grondwaarheid definiëren, evaluaties uitvoeren en resultaten analyseren – allemaal binnen je notebookomgeving. Dit proces helpt je om nauwkeurigheid te valideren, fouten te debuggen en je agent met vertrouwen te verbeteren voordat je hem in productie uitrolt.

Belangrijk

Deze functie is beschikbaar als preview-versie.

Vereiste voorwaarden

De SDK voor de gegevensagent installeren

Om te beginnen met het programmatisch evalueren van je Fabric data agent, installeer je de Fabric data agent Python SDK. Deze SDK biedt de hulpprogramma's en methoden die nodig zijn om te communiceren met uw gegevensagent, evaluaties uit te voeren en logboekresultaten te registreren. Installeer de nieuwste versie door de volgende opdracht uit te voeren in uw notebook:

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

Deze stap zorgt ervoor dat u beschikt over de meest up-to-date functies en fixes die beschikbaar zijn in de SDK.

Laad uw grondwaarheidsdataset

Om je Fabric dataagent te evalueren, heb je een set voorbeeldvragen nodig samen met de verwachte antwoorden. Gebruik deze vragen om te controleren hoe nauwkeurig de agent reageert op echte vragen.

Definieer deze vragen direct in je code met behulp van een 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)"]
    ]
)

Als alternatief, als je een bestaande evaluatiedataset hebt, laad deze dan vanuit een CSV-bestand met de kolommen question en 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)

Deze gegevensset fungeert als invoer voor het uitvoeren van geautomatiseerde evaluaties op basis van uw gegevensagent om de nauwkeurigheid en dekking te beoordelen.

Uw gegevensagent evalueren en beoordelen

De volgende stap is het uitvoeren van de evaluatie met behulp van de evaluate_data_agent functie. Met deze functie worden de reacties van de agent vergeleken met de verwachte resultaten en worden de metrische evaluatiegegevens opgeslagen.

Note

Deze stap vereist een dataagent die al gepubliceerd is tot het stadium dat je evalueert (production of sandbox). Als je er nog geen hebt, zie Create a Fabric data agent.

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

Na afloop zie je output die lijkt op de volgende tekst:

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

Evaluatieoverzicht ophalen

Na het uitvoeren van de evaluatie kun je een overzicht van de resultaten ophalen met behulp van de get_evaluation_summary functie. Deze functie geeft inzicht in hoe goed uw dataagent het overall heeft gepresteerd, inclusief statistieken zoals hoeveel antwoorden overeenkwamen met de verwachte antwoorden.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Schermopname van de samenvatting van de resultaten van de evaluatie van de gegevensagent.

Standaard zoekt deze functie naar een tabel met de naam evaluation_output. Als je tijdens de evaluatie een aangepaste tabelnaam hebt opgegeven (zoals demo_evaluation_output), geef die naam als argument table_name door.

Het geretourneerde DataFrame bevat geaggregeerde metrische gegevens, zoals het aantal juiste, onjuiste of onduidelijke antwoorden. Met dit resultaat kunt u snel de nauwkeurigheid van de agent beoordelen en gebieden voor verbetering identificeren.

Gedetailleerde evaluatieresultaten controleren

Om dieper in te gaan op hoe je dataagent op elke individuele vraag heeft gereageerd, gebruik de get_evaluation_details functie. Deze functie retourneert een gedetailleerde uitsplitsing van de evaluatieuitvoering, inclusief de werkelijke agentreacties, of deze overeenkomen met het verwachte antwoord en een koppeling naar de evaluatiethread (alleen zichtbaar voor de gebruiker die de evaluatie heeft uitgevoerd).

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
)

Schermopname met details van de evaluatieresultaten van een specifieke gegevensagent.

Uw prompt voor evaluatie aanpassen

Standaard gebruikt de Fabric SDK een ingebouwde prompt om te evalueren of het daadwerkelijke antwoord van de dataagent overeenkomt met het verwachte antwoord. Je kunt echter je eigen prompt voor meer genuanceerde of domeinspecifieke evaluaties geven door de critic_prompt parameter te gebruiken.

Uw aangepaste prompt moet de tijdelijke aanduidingen {query}bevatten, {expected_answer}en {actual_answer}. Het evaluatieproces vervangt dynamisch deze tijdelijke antwoorden voor elke vraag.

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)

Deze functie is vooral handig wanneer:

  • Je wilt soepelere of strengere criteria hanteren voor wat als match telt.
  • Je verwachte en daadwerkelijke antwoorden kunnen verschillen in format, maar zijn nog steeds semantisch gelijk.
  • U moet domeinspecifieke nuances vastleggen in hoe antwoorden moeten worden beoordeeld.

knop Diagnostiek

Met de Diagnostiek-knop kun je een volledige snapshot downloaden van de configuratie- en uitvoeringsstappen van je dataagent. Deze export bevat details zoals databroninstellingen, toegepaste instructies, gebruikte voorbeeldzoekopdrachten en de onderliggende stappen die de dataagent heeft genomen om zijn antwoord te genereren.

Gebruik deze functie als je samenwerkt met Microsoft Ondersteuning of onverwacht gedrag oplost. Door het gedownloade bestand te bekijken, kun je precies zien hoe de dataagent je verzoek heeft verwerkt, welke configuraties zijn toegepast en waar mogelijke problemen zich voordoen. Dit niveau van transparantie maakt het eenvoudiger om de prestaties van je dataagent te debuggen en te optimaliseren.

Screenshot van de diagnostische knop in de data-agent.

Troubleshooting

Probleem Oorzaak Resolutie / Besluit
Dataagent niet gevonden data_agent_name of workspace_name klopt niet, of de agent is niet gepubliceerd. Controleer de naam van de agent en de werkruimte, en zorg dat de agent is gepubliceerd op het gespecificeerde data_agent_stage.
Lege of ontbrekende resultaten De tabelnaam komt niet overeen met die die tijdens evaluate_data_agentwordt gebruikt. Geef hetzelfde table_name door aan get_evaluation_summary en get_evaluation_details.
message_url is niet toegankelijk Evaluatiethreads zijn alleen zichtbaar voor de gebruiker die de evaluatie heeft uitgevoerd. Voer de evaluatie opnieuw uit onder je eigen identiteit om toegang te krijgen tot de threadlinks.
De aangepaste prompt heeft geen effect of veroorzaakt fouten De critic_prompt mist vereiste plaatsaanduidingen. Voeg {query}, {expected_answer}, en {actual_answer} toe in je prompt.
Toestemmings- of capaciteitsfout Ontbrekende F2 of hogere capaciteit, of gebrek aan leestoegang tot de databron. Bevestig de vereisten, inclusief capaciteit en leestoegang tot de gegevensbron.

Volgende stappen

  • Last updated on