Valutare l'agente dei dati (anteprima)

La valutazione con Fabric SDK consente di testare a livello di codice il grado di risposta dell'agente dati alle domande in linguaggio naturale. Usando una semplice interfaccia Python, è possibile definire esempi di verità di base, eseguire valutazioni e analizzare i risultati, tutti all'interno dell'ambiente notebook. In questo modo è possibile convalidare l'accuratezza, eseguire il debug degli errori e migliorare in modo sicuro l'agente prima di distribuirlo nell'ambiente di produzione.

Importante

Questa funzionalità si trova in Anteprima.

Prerequisiti

• Una capacità di Infrastruttura F2 o superiore a pagamento o una capacità Power BI Premium per capacità (P1 o superiore) con Microsoft Fabric abilitato
• Le impostazioni tenant dell'agente dati di Fabric sono abilitate.
• L'elaborazione multigeografica per l'intelligenza artificiale è abilitata.
• L'archiviazione tra aree geografiche per intelligenza artificiale è abilitata.
• Almeno uno di questi, con dati: un warehouse, una lakehouse, uno o più modelli semantici di Power BI, un database KQL o un'ontologia.
• I modelli semantici di Power BI tramite il cambio di tenant degli endpoint XMLA sono abilitati per le origini dati semantiche di Power BI.

Installare l'SDK dell'agente dati

Per iniziare a valutare l'agente dati di Fabric a livello di codice, è necessario installare l'SDK Python dell'agente dati di Fabric. Questo SDK fornisce gli strumenti e i metodi necessari per interagire con l'agente dati, eseguire valutazioni e registrare i risultati. Installare la versione più recente eseguendo il comando seguente nel notebook:

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

Questo passaggio assicura di avere le funzionalità e le correzioni più up-todisponibili nell'SDK.

Caricare il set di dati di verità sul terreno

Per valutare l'agente dati di Fabric, è necessario un set di domande di esempio insieme alle risposte previste. Queste domande vengono usate per verificare in modo accurato la risposta dell'agente alle query reali.

È possibile definire queste domande direttamente nel codice usando un dataframe 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)"]
    ]
)

In alternativa, se si dispone di un set di dati di valutazione esistente, è possibile caricarlo da un file CSV con le colonne domande e 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)

Questo set di dati funge da input per l'esecuzione di valutazioni automatizzate sull'agente dati per valutare l'accuratezza e la copertura.

Esamina e valuta il responsabile dei dati

Il passaggio successivo consiste nell'eseguire la valutazione usando la evaluate_data_agent funzione . Questa funzione confronta le risposte dell'agente con i risultati previsti e archivia le metriche di valutazione.

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

Ottenere il riepilogo della valutazione

Dopo aver eseguito la valutazione, è possibile recuperare un riepilogo generale dei risultati usando la get_evaluation_summary funzione . Questa funzione fornisce informazioni dettagliate sull'esecuzione complessiva dell'agente dati, incluse metriche come il numero di risposte corrispondenti alle risposte previste.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Per impostazione predefinita, questa funzione cerca una tabella denominata evaluation_output. Se è stato specificato un nome di tabella personalizzato durante la valutazione (ad esempio "demo_evaluation_output"), passare tale table_name nome come argomento.

Il dataframe restituito include metriche aggregate, ad esempio il numero di risposte corrette, errate o poco chiare. Questo risultato consente di valutare rapidamente l'accuratezza dell'agente e identificare le aree per il miglioramento.

ottieni_riassunto_valutazione

Restituisce un dataframe contenente metriche di riepilogo generali per un'esecuzione di valutazione completata, ad esempio il numero di risposte corrette, errate e poco chiare.

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

Parametri di input:

• table_name (str, facoltativo): nome della tabella contenente i risultati di riepilogo della valutazione. Il valore predefinito è 'evaluation_output'.
• verbose (bool, facoltativo): se impostato su True, stampa un riepilogo delle metriche di valutazione nella console. Il valore predefinito è False.

restituisce:

• DataFrame – DataFrame pandas contenente statistiche di riepilogo per la valutazione, ad esempio:
  • Numero totale di domande valutate
  • Conteggi dei risultati veri, falsi e non chiari
  • Accuratezza

Esaminare i risultati dettagliati della valutazione

Per approfondire il modo in cui l'agente dati ha risposto a ogni singola domanda, usare la get_evaluation_details funzione . Questa funzione restituisce una suddivisione dettagliata dell'esecuzione della valutazione, incluse le risposte effettive dell'agente, se corrispondono alla risposta prevista e un collegamento al thread di valutazione (visibile solo all'utente che ha eseguito la valutazione).

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
)

ottieni_dettagli_valutazione

Restituisce un dataframe contenente risultati dettagliati per un'esecuzione di valutazione specifica, incluse domande, risposte previste, risposte dell'agente, stato di valutazione e metadati di diagnostica.

Parametri di input:

• evaluation_id (str): obbligatorio. Identificatore univoco per l'esecuzione della valutazione per cui recuperare i dettagli.
• table_name (str, facoltativo): nome della tabella contenente i risultati della valutazione. Il valore predefinito è evaluation_output.
• get_all_rows (bool, facoltativo): indica se restituire tutte le righe dalla valutazione (True) o solo le righe in cui la risposta dell'agente non è corretta o poco chiara (False). Il valore predefinito è False.
• verbose (bool, facoltativo): se impostato su True, stampa un riepilogo delle metriche di valutazione nella console. Il valore predefinito è False.

restituisce:

• DataFrame – DataFrame pandas contenente risultati di valutazione a livello di riga, tra cui:

  • question
  • expected_answer
  • actual_answer
  • evaluation_result (true, false, unclear)
  • thread_url (accessibile solo dall'utente che ha eseguito la valutazione)

Personalizzare la richiesta di valutazione

Per impostazione predefinita, Fabric SDK usa un prompt predefinito per valutare se la risposta effettiva dell'agente dati corrisponde alla risposta prevista. Tuttavia, è possibile fornire una richiesta personalizzata per valutazioni più sfumate o specifiche del dominio usando il critic_prompt parametro .

Il prompt personalizzato deve includere i segnaposto {query}, {expected_answer}e {actual_answer}. Questi segnaposto vengono sostituiti dinamicamente per ogni domanda durante la valutazione.

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)

Questa funzionalità è particolarmente utile quando:

• Si vogliono applicare criteri più flessibili o più rigorosi per definire cosa conta come corrispondenza.
• Le risposte previste e effettive possono variare nel formato, ma comunque essere semanticamente equivalenti.
• È necessario acquisire sfumature specifiche del dominio nel modo in cui le risposte devono essere giudicate.

Pulsante Diagnostica

Il pulsante Diagnostica consente di scaricare uno snapshot completo dei passaggi di configurazione ed esecuzione dell'agente dati. Questa esportazione include dettagli quali le impostazioni dell'origine dati, le istruzioni applicate, le query di esempio usate e i passaggi sottostanti impiegato dall'agente dati per generare la risposta.

Usare questa funzionalità quando si usa il supporto tecnico Microsoft o si risolve un comportamento imprevisto. Esaminando il file scaricato, è possibile vedere esattamente come l'agente dati ha elaborato la richiesta, quali configurazioni sono state applicate e dove potrebbero verificarsi potenziali problemi. Questo livello di trasparenza semplifica il debug e l'ottimizzazione delle prestazioni dell'agente dati.

Passaggi successivi

• Usare l'SDK dell'agente dati di Fabric
• Accedi ai notebook di esempio su come utilizzare l'SDK dell'agente dati