Valutare l'agente dei dati (anteprima)

Utilizzando l'SDK Fabric per la valutazione, puoi testare in modo programmativo quanto bene il tuo data agent risponde alle domande in linguaggio naturale. Utilizzando un'interfaccia Python semplice, puoi definire esempi di verità sul campo, eseguire valutazioni e analizzare i risultati—tutto all'interno del tuo ambiente notebook. Questo processo ti aiuta a validare l'accuratezza, a debug degli errori e a migliorare con sicurezza il tuo agente prima di implementarlo in produzione.

Prerequisiti

• Una capacità di Fabric a pagamento di livello F2 o superiore, o una capacità Power BI Premium per capacità (P1 o superiore) con Microsoft Fabric abilitato.
• Abilitare l'elaborazione tra aree geografiche e l'archiviazione tra aree geografiche per l'intelligenza artificiale in base ai requisiti illustrati nelle impostazioni del tenant dell'agente dati di Fabric.
• Almeno una di queste origini dati, con dati: un warehouse, una lakehouse, un modello semantico di Power BI, un database KQL, un database con mirroring o un'ontologia. È necessario disporre dell'accesso in lettura all'origine dati.

Installare l'SDK dell'agente dati

Per iniziare a valutare programmaticamente il tuo data agent Fabric, installa l'SDK Python del Fabric data agent. 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ù recenti disponibili nell'SDK.

Caricare il set di dati di verità sul terreno

Per valutare il tuo agente dati Fabric, hai bisogno di una serie di domande di esempio insieme alle risposte attese. Usa queste domande per verificare quanto accuratamente l'agente risponde alle domande reali.

Definisci queste domande direttamente nel tuo 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 hai un dataset di valutazione esistente, caricalo da un file CSV con le colonne question 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 passo successivo è 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
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}")

Dopo la fine della corsa, si vede un output simile al seguente testo:

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

Ottenere il riepilogo della valutazione

Dopo aver eseguito la valutazione, puoi recuperare un riassunto di alto livello dei risultati utilizzando la get_evaluation_summary funzione. Questa funzione fornisce informazioni su quanto bene il tuo data agent abbia funzionato complessivamente, inclusi indicatori come quante risposte corrispondevano alle risposte previste.

from fabric.dataagent.evaluation import get_evaluation_summary

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

Di default, questa funzione cerca una tabella chiamata evaluation_output. Se hai specificato un nome di tabella personalizzato durante la valutazione (come demo_evaluation_output), passa quel nome come argomento table_name.

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.

Esaminare i risultati dettagliati della valutazione

Per approfondire come il tuo data agent ha risposto a ogni singola domanda, usa 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
)

Personalizzare la richiesta di valutazione

Di default, l'SDK Fabric utilizza un prompt integrato per valutare se la risposta effettiva dell'agente dati corrisponde a quella attesa. Tuttavia, puoi fornire un tuo prompt per valutazioni più sfumate o specifiche per il dominio usando il critic_prompt parametro.

Il prompt personalizzato deve includere i segnaposto {query}, {expected_answer}e {actual_answer}. Il processo di valutazione sostituisce dinamicamente questi segnaposto per ogni domanda.

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:

• Vuoi applicare criteri più permissivi o più severi per stabilire cosa è considerato una corrispondenza.
• Le risposte previste e quelle effettive potrebbero variare nel formato ma restano comunque semanticamente equivalenti.
• È necessario acquisire sfumature specifiche del dominio nel modo in cui le risposte devono essere giudicate.

Pulsante di diagnostica

Il pulsante Diagnostica ti permette di scaricare una panoramica completa dei passaggi di configurazione ed esecuzione del tuo data agent. Questa esportazione include dettagli come le impostazioni della fonte dati, le istruzioni applicate, le query di esempio utilizzate e i passaggi sottostanti che l'agente dati ha seguito per generare la sua risposta.

Usa questa funzione quando lavori con supporto tecnico Microsoft o quando risolvi comportamenti imprevisti. Esaminando il file scaricato, puoi vedere esattamente come l'agente dati ha elaborato la tua richiesta, quali configurazioni sono state applicate e dove si sono verificati eventuali problemi. Questo livello di trasparenza rende più facile il debug e l'ottimizzazione delle prestazioni del tuo data agent.

Troubleshooting

Passaggi successivi

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