Ocena agenta danych (wersja zapoznawcza)

Ocena przy użyciu zestawu SDK Fabric umożliwia programowe testowanie, jak dobrze agent danych odpowiada na pytania dotyczące języka naturalnego. Korzystając z prostego interfejsu Python, można zdefiniować przykłady podstawowych faktów, uruchomić oceny i analizować wyniki — wszystko w środowisku notesu. Pomaga to zweryfikować dokładność, błędy debugowania i pewnie poprawić agenta przed wdrożeniem go w środowisku produkcyjnym.

Ważne

Ta funkcja jest dostępna w wersji zapoznawczej.

Wymagania wstępne

• Płatna pojemność Fabric F2 lub wyższa, lub Power BI Premium per capacity (P1 lub wyższa) z włączonym Microsoft Fabric.
• Włącz przetwarzanie i przechowywanie między lokalizacjami geograficznymi dla sztucznej inteligencji na podstawie wymagań opisanych w ustawieniach dzierżawy agenta danych Fabric.
• Co najmniej jedno z tych źródeł danych z danymi: magazynem, usługą lakehouse, modelem semantycznym usługi Power BI, bazą danych KQL, dublowaną bazą danych lub ontologią. Musisz mieć uprawnienia do odczytu źródła danych.

Instalowanie zestawu SDK agenta danych

Aby rozpocząć programową ocenę agenta Danych Fabric, należy zainstalować Python SDK agenta Danych Fabric. Ten SDK udostępnia narzędzia i metody wymagane do interakcji z agentem danych, przeprowadzania ocen i logowania wyników. Zainstaluj najnowszą wersję, uruchamiając następujące polecenie w notesie:

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

Ten krok zapewnia, że masz najbardziej aktualne funkcje i poprawki dostępne w zestawie SDK.

Załaduj zestaw danych odniesienia

Aby ocenić agenta danych Fabric, potrzebujesz zestawu przykładowych pytań wraz z oczekiwanymi odpowiedziami. Te pytania służą do sprawdzania, jak dokładnie agent odpowiada na zapytania w świecie rzeczywistym.

Te pytania można zdefiniować bezpośrednio w kodzie przy użyciu ramki danych biblioteki pandas:

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

Ewentualnie, jeśli masz już istniejący zestaw danych ewaluacyjnych, możesz załadować go z pliku CSV z kolumnami "question" i "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)

Ten zestaw danych służy jako dane wejściowe do uruchamiania automatycznych ocen względem agenta danych w celu oceny dokładności i pokrycia.

Oceń i zbadaj swojego agenta danych

Następnym krokiem jest uruchomienie oceny przy użyciu evaluate_data_agent funkcji . Ta funkcja porównuje odpowiedzi agenta z oczekiwanymi wynikami i przechowuje metryki oceny.

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

Pobieranie podsumowania oceny

Po uruchomieniu oceny możesz pobrać ogólne podsumowanie wyników przy użyciu get_evaluation_summary funkcji . Ta funkcja zapewnia szczegółowe informacje na temat ogólnej wydajności agenta danych — w tym metryk, takich jak liczba odpowiedzi dopasowanych do oczekiwanych odpowiedzi.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Domyślnie ta funkcja wyszukuje tabelę o nazwie evaluation_output. Jeśli podczas oceny określono niestandardową nazwę tabeli (na przykład "demo_evaluation_output"), przekaż tę nazwę jako table_name argument.

Zwrócona ramka danych zawiera zagregowane metryki, takie jak liczba poprawnych, niepoprawnych lub niejasnych odpowiedzi. Ten wynik pomaga szybko ocenić dokładność agenta i zidentyfikować obszary pod kątem poprawy.

uzyskaj_podsumowanie_oceny

Zwraca ramkę danych zawierającą metryki podsumowania wysokiego poziomu dla ukończonego przebiegu oceny, takie jak liczba poprawnych, niepoprawnych i niejasnych odpowiedzi.

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

Parametry wejściowe:

• table_name (str, optional) — nazwa tabeli zawierającej wyniki podsumowania oceny. Wartość domyślna to "evaluation_output".
• verbose (wartość logiczna, opcjonalnie) — jeśli ustawiona na True, wyświetla w konsoli podsumowanie metryk oceny. Wartość domyślna to False.

Zwraca:

• DataFrame — Ramka danych biblioteki pandas zawierająca podsumowanie statystyk oceny, takich jak:
  • Łączna liczba ocenianych pytań
  • Liczby wyników prawdziwych, fałszywych i niejasnych
  • Dokładność

Sprawdzanie szczegółowych wyników oceny

Aby dowiedzieć się więcej na temat odpowiedzi agenta danych na poszczególne pytania, użyj get_evaluation_details funkcji . Ta funkcja zwraca szczegółowy podział przebiegu oceny, w tym rzeczywiste odpowiedzi agenta, czy pasują one do oczekiwanej odpowiedzi, oraz link do wątku oceny (widoczne tylko dla użytkownika, który uruchomił ocenę).

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
)

pobierz_szczegóły_oceny

Zwraca ramkę danych zawierającą szczegółowe wyniki dla określonego przebiegu oceny, w tym pytania, oczekiwane odpowiedzi, odpowiedzi agenta, stan oceny i metadane diagnostyczne.

Parametry wejściowe:

• evaluation_id (str) — wymagane. Unikatowy identyfikator przebiegu oceny służący do uzyskania szczegółowych informacji.
• table_name (str, optional) — nazwa tabeli zawierającej wyniki oceny. Wartość domyślna to evaluation_output.
• get_all_rows (wartość logiczna, opcjonalnie) — czy zwracać wszystkie wiersze z oceny (Prawda) lub tylko wiersze, w których odpowiedź agenta była niepoprawna lub niejasna (Fałsz). Wartość domyślna to False.
• verbose (wartość logiczna, opcjonalnie) — jeśli ustawiono wartość "True", wyświetla podsumowanie metryk oceny w konsoli. Wartość domyślna to False.

Zwraca:

• DataFrame — Ramka danych biblioteki pandas zawierająca wyniki oceny na poziomie poszczególnych wierszy, w tym:

  • question
  • expected_answer
  • actual_answer
  • evaluation_result (true, false, unclear)
  • thread_url (dostępne tylko dla użytkownika, który przeprowadził ocenę)

Dostosowywanie monitu o ocenę

Domyślnie zestaw SDK Fabric używa wbudowanego monitu, aby ocenić, czy rzeczywista odpowiedź agenta danych jest zgodna z oczekiwaną odpowiedzią. Można jednak podać własny tekst zachęty do bardziej zniuansowanych lub specyficznych dla domeny ocen przy użyciu parametru critic_prompt.

Twój niestandardowy komunikat powinien zawierać symbole zastępcze {query}, {expected_answer} i {actual_answer}. Te elementy zastępcze są dynamicznie zastępowane dla każdego pytania w trakcie oceny.

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)

Ta funkcja jest szczególnie przydatna, gdy:

• Chcesz wybrać bardziej łagodne lub bardziej rygorystyczne kryteria określające, co jest uznawane za zgodne.
• Oczekiwane i rzeczywiste odpowiedzi mogą się różnić w formacie, ale nadal są równoważne.
• Należy przechwycić niuanse specyficzne dla domeny w sposobie oceniania odpowiedzi.

Przycisk Diagnostyki

Przycisk Diagnostyka umożliwia pobranie pełnej migawki kroków konfiguracji i wykonywania agenta danych. Ten eksport zawiera szczegółowe informacje, takie jak ustawienia źródła danych, zastosowane instrukcje, użyte przykładowe zapytania, a także podstawowe kroki wykonywane przez agenta danych w celu wygenerowania odpowiedzi.

Użyj tej funkcji podczas pracy z pomoc techniczna firmy Microsoft lub rozwiązywania problemów z nieoczekiwanym zachowaniem. Przeglądając pobrany plik, możesz zobaczyć dokładnie, jak agent danych przetworzył żądanie, które konfiguracje zostały zastosowane i gdzie mogły wystąpić potencjalne problemy. Ten poziom przejrzystości ułatwia debugowanie i optymalizowanie wydajności agenta danych.

Dalsze kroki

• Użyj zestawu SDK agenta danych Fabric
• Uzyskiwanie dostępu do przykładowych notesów dotyczących korzystania z zestawu SDK agenta danych