Vyhodnoťte svého datového agenta (náhled)

Použitím Fabric SDK pro hodnocení můžete programově otestovat, jak dobře váš datový agent reaguje na otázky v přirozeném jazyce. Použitím jednoduchého Python rozhraní můžete definovat příklady pravdivosti, provádět vyhodnocení a analyzovat výsledky – to vše přímo ve vašem notebookovém prostředí. Tento proces vám pomůže ověřit přesnost, odstraňovat chyby a sebevědomě vylepšovat agenta před nasazením do produkce.

Důležité

Tato funkce je ve verzi Preview.

Požadavky

• Placená kapacita Fabric F2 nebo vyšší, nebo kapacita Power BI Premium na uživatele (P1 nebo vyšší) s povolenou funkcí Microsoft Fabric.
• Povolit zpracování a ukládání napříč geografiemi pro AI na základě požadavků uvedených v nastavení tenanta datového agenta Fabric.
• Nejméně jeden z těchto zdrojů dat s daty: sklad, jezero, sémantický model Power BI, databáze KQL, zrcadlená databáze nebo ontologie. Ke zdroji dat musíte mít přístup pro čtení.

Instalace sady SDK datového agenta

Pro zahájení programového vyhodnocení vašeho Fabric datového agenta nainstalujte Fabric datový agent Python SDK. Tento SDK poskytuje nástroje a metody potřebné k interakci s vaším datovým agentem, spouštění vyhodnocení a zaznamenávání výsledků. Nainstalujte nejnovější verzi spuštěním následujícího příkazu v poznámkovém bloku:

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

Tento krok zajistí, že budete mít k dispozici nejnovější up-tofunkce a opravy v sadě SDK.

Načtení základní datové sady pravdy

Pro vyhodnocení vašeho Fabric datového agenta potřebujete sadu vzorových otázek spolu s očekávanými odpověďmi. Použijte tyto otázky k ověření, jak přesně agent odpovídá na dotazy z reálného světa.

Tyto otázky definujte přímo ve svém kódu pomocí 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)"]
    ]
)

Případně, pokud máte stávající datovou sadu pro vyhodnocení, načtěte ji ze souboru CSV se sloupci question a 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)

Tato datová sada slouží jako vstup pro spouštění automatizovaných vyhodnocení pro vašeho datového agenta za účelem vyhodnocení přesnosti a pokrytí.

Vyhodnoťte a posuďte svého datového agenta

Dalším krokem je spustit vyhodnocení pomocí evaluate_data_agent funkce. Tato funkce porovnává odpovědi agenta s očekávanými výsledky a ukládá metriky vyhodnocení.

Note

Tento krok vyžaduje agenta dat, který už je publikovaný do fáze, kterou vyhodnocujete (production nebo sandbox). Pokud ho ještě nemáte, podívejte se na Vytvořte datového agenta v Fabric.

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

Po skončení běhu vidíte výstup podobný následujícímu textu:

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

Získání souhrnu vyhodnocení

Po provedení hodnocení můžete pomocí funkce získat souhrn výsledků get_evaluation_summary na vyšší úrovni. Tato funkce poskytuje vhled do toho, jak dobře váš datový agent celkově fungoval, včetně metrik jako kolik odpovědí odpovídalo očekávaným odpovědím.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Ve výchozím nastavení tato funkce hledá tabulku s názvem evaluation_output. Pokud jste při vyhodnocení zadali vlastní název tabulky (například demo_evaluation_output), pošlete tento název jako table_name argument.

Vrácený datový rámec zahrnuje agregované metriky, jako je počet správných, nesprávných nebo nejasných odpovědí. Tento výsledek vám pomůže rychle vyhodnotit přesnost agenta a identifikovat oblasti pro zlepšení.

Kontrola podrobných výsledků vyhodnocení

Chcete-li se ponořit hlouběji do toho, jak váš datový agent reagoval na jednotlivé otázky, použijte get_evaluation_details tuto funkci. Tato funkce vrátí podrobný rozpis spuštění vyhodnocení, včetně skutečných odpovědí agenta, toho, jestli odpovídaly očekávané odpovědi, a odkaz na vlákno vyhodnocení (viditelné pouze uživateli, který spustil vyhodnocení).

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
)

Přizpůsobte svou výzvu k vyhodnocení

Ve výchozím nastavení používá Fabric SDK vestavěný prompt k vyhodnocení, zda skutečná odpověď datového agenta odpovídá očekávané odpovědi. Nicméně můžete pomocí parametru critic_prompt zadat vlastní prompt pro nuancovanější nebo daně specifické hodnocení.

Vlastní výzva by měla obsahovat zástupné symboly {query}, {expected_answer} a {actual_answer}. Hodnotící proces dynamicky nahrazuje tyto zástupce pro každou otázku.

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)

Tato funkce je užitečná zejména v těchto případech:

• Chcete uplatnit mírnější nebo přísnější kritéria pro to, co se počítá jako shoda.
• Vaše očekávané i skutečné odpovědi se mohou lišit ve formátu, ale stále být sémanticky ekvivalentní.
• Potřebujete zachytit drobné odlišnosti specifické pro doménu v tom, jak by měly být odpovědi posouzeny.

Tlačítko Diagnostika

Tlačítko Diagnostika vám umožní stáhnout kompletní snímek konfiguračních a výkonných kroků vašeho datového agenta. Tento export zahrnuje detaily jako nastavení datového zdroje, aplikované instrukce, příklady použitých dotazů a základní kroky, které datový agent provedl k generování své odpovědi.

Tuto funkci využijte, když spolupracujete s podpora Microsoftu nebo řešíte neočekávané chování. Při prohlédnutí staženého souboru můžete přesně vidět, jak datový agent zpracoval váš požadavek, které konfigurace byly aplikovány a kde se objevily možné problémy. Tato úroveň transparentnosti usnadňuje ladění a optimalizaci výkonu vašeho datového agenta.

Řešení problémů

Problém	Příčina	Resolution
Datový agent nenalezen	data_agent_name nebo workspace_name není správné nebo agent není publikovaný.	Ověřte název agenta a pracovní prostor a ujistěte se, že je agent publikován do zadaného data_agent_stage.
Prázdné nebo chybějící výsledky	Název tabulky neodpovídá tomu, který byl použit během evaluate_data_agent.	Předáme stejné table_name na get_evaluation_summary a get_evaluation_details.
message_url není přístupný	Vlákna hodnocení jsou viditelná pouze uživateli, který hodnocení provedl.	Spusť vyhodnocení znovu pod svou identitou, abys měl přístup k vláknovým odkazům.
Vlastní prompt nemá žádný účinek nebo způsobuje chyby	V položce critic_prompt chybí požadované zástupné symboly.	Do výzvy zahrňte {query}, {expected_answer} a {actual_answer}.
Chyba oprávnění nebo kapacity	Chybí kapacita F2 nebo vyšší nebo oprávnění pro čtení zdroje dat.	Potvrďte předpoklady, včetně kapacity a přístupu ke čtení zdrojů dat.

Další kroky

• Vytvoření datového agenta Fabric
• Použití sady SDK datového agenta Fabric
• Získejte přístup k ukázkovým poznámkovým blokům s využitím sady SDK datového agenta