Condividi tramite

Esempio dell'agente dati di Fabric con il set di dati AdventureWorks (anteprima)

Questo articolo illustra come configurare un agente dati in Microsoft Fabric usando un lakehouse come origine dati di esempio. Prima di tutto creiamo e popoliamo un lakehouse, quindi configuriamo un Fabric Data Agent e aggiungiamo il lakehouse. Se si ha già un modello semantico di Power BI (con le autorizzazioni di lettura/scrittura necessarie), un warehouse o un database KQL, seguire la stessa procedura e selezionare l'origine. Anche se questa procedura dettagliata utilizza un lakehouse, lo schema è lo stesso per altre origini: cambia solo la selezione dell'origine dati.

Importante

Questa funzionalità si trova in Anteprima.

Prerequisiti

Importante

Verificare che l'esperienza di Copilot autonoma sia abilitata nel portale di amministrazione di Power BI (Impostazioni del tenant > Copilot > Esperienza di Copilot autonoma). Se non è abilitato, non sarà possibile usare l'agente di dati nei scenari Copilot anche se sono attivati altri switch del tenant Copilot. Per informazioni dettagliate, vedere Copilot nelle impostazioni del tenant di Power BI.

Creare una Lakehouse con AdventureWorksLH

Prima di tutto, creare una lakehouse e popolarla con i dati necessari.

Se hai già un'istanza di AdventureWorksLH in una lakehouse (o in un magazzino), puoi saltare questo passaggio. In caso contrario, è possibile utilizzare le istruzioni seguenti da un notebook di Fabric per popolare il lakehouse con i dati.

  1. Crea un nuovo notebook nell'area di lavoro in cui vuoi creare l'agente dei dati Fabric.

  2. Sul lato sinistro del riquadro Esplora selezionare + Origini dati. Questa opzione consente di aggiungere una lakehouse esistente o di creare un nuovo lakehouse. Per maggiore chiarezza, creare una nuova lakehouse e assegnarvi un nome.

  3. Nella cella superiore, aggiungere il seguente frammento di codice:

    import pandas as pd
from tqdm.auto import tqdm
base = "https://synapseaisolutionsa.z13.web.core.windows.net/data/AdventureWorks"

# load list of tables
df_tables = pd.read_csv(f"{base}/adventureworks.csv", names=["table"])

for table in (pbar := tqdm(df_tables['table'].values)):
    pbar.set_description(f"Uploading {table} to lakehouse")

    # download
    df = pd.read_parquet(f"{base}/{table}.parquet")

    # save as lakehouse table
    spark.createDataFrame(df).write.mode('overwrite').saveAsTable(table)

  4. Selezionare Esegui tutto.

Screenshot che mostra un notebook con il codice di caricamento AdventureWorks.

Dopo alcuni minuti, il lakehouse si popola con i dati necessari.

Attenzione

I notebook che continuano a funzionare (ad esempio, a causa di cicli infiniti accidentali o di polling costante) possono utilizzare la capacità di Fabric indefinitamente. Al termine del caricamento dei dati, arrestare le celle attive e terminare la sessione del notebook (sessione di arresto della barra degli strumenti > del notebook) se non è più necessaria. Evitare di aggiungere cicli a esecuzione continua senza un limite di tempo predefinito.

Creare un agente dei dati di Fabric

Per creare un nuovo agente dati di Fabric, passa all'area di lavoro e seleziona il pulsante + Nuovo elemento, come illustrato in questo screenshot:

Screenshot che mostra dove si possono creare agenti dati di Fabric.

Nella scheda Tutti gli elementi cercare Fabric data agent per individuare l'opzione appropriata. Dopo aver selezionato un'opzione, ti viene richiesto di specificare un nome per l'agente dei dati di Fabric, come illustrato in questo screenshot:

Screenshot che mostra dove inserire il nome dell'agente dati di Fabric.

Dopo aver immesso il nome, procedi con i passaggi seguenti per allineare l'agente dati di Fabric ai requisiti specifici.

Selezionare i dati

Seleziona il lakehouse creato nel passaggio precedente e quindi seleziona Aggiungi, come illustrato nello screenshot seguente:

Screenshot che mostra il passaggio per aggiungere un lakehouse.

Dopo aver aggiunto il lakehouse come origine dati, nel riquadro Esplora sul lato sinistro della pagina dell'agente dati di Fabric viene visualizzato il nome del lakehouse. Seleziona il lakehouse per visualizzare tutte le tabelle disponibili. Usare le caselle di controllo per selezionare le tabelle da rendere disponibili per l'intelligenza artificiale. Per questo scenario, selezionare queste tabelle:

  • dimcustomer
  • dimdate
  • dimgeography
  • dimproduct
  • dimproductcategory
  • dimpromotion
  • dimreseller
  • dimsalesterritory
  • factinternetsales
  • factresellersales

Screenshot che mostra dove è possibile selezionare le tabelle per intelligenza artificiale.

Fornire istruzioni

Per aggiungere istruzioni, selezionare il pulsante Istruzioni agente dati per aprire il riquadro istruzioni a destra. È possibile aggiungere le istruzioni seguenti.

L'origine dati AdventureWorksLH contiene informazioni di tre tabelle:

  • dimcustomer, per informazioni dettagliate sui dati demografici e sui contatti dei clienti
  • dimdate, per i dati relativi alla data, ad esempio calendario e informazioni fiscali
  • dimgeography, per i dettagli geografici, inclusi i nomi delle città e i codici dell'area geografica.

Usare questa origine dati per query e analisi che coinvolgono i dettagli dei clienti, gli eventi basati sul tempo e le posizioni geografiche.

Screenshot che mostra dove è possibile fornire le istruzioni per l'intelligenza artificiale.

Fornire esempi

Per aggiungere query di esempio, selezionare il pulsante Query di esempio per aprire il riquadro query di esempio a destra. Questo riquadro offre opzioni per aggiungere o modificare query di esempio per tutte le origini dati supportate. Per ogni origine dati, è possibile selezionare Aggiungi o Modifica query di esempio per immettere gli esempi pertinenti, come illustrato nello screenshot seguente:

Screenshot che mostra dove è possibile aggiungere gli esempi forniti all'intelligenza artificiale.

In questo contesto, dovresti aggiungere delle query di esempio per l'origine dati lakehouse che hai creato.

Question: Calculate the average percentage increase in sales amount for repeat purchases for every zipcode. Repeat purchase is a purchase subsequent to the first purchase (the average should always be computed relative to the first purchase)

SELECT AVG((s.SalesAmount - first_purchase.SalesAmount) / first_purchase.SalesAmount * 100) AS AvgPercentageIncrease
FROM factinternetsales s
INNER JOIN dimcustomer c ON s.CustomerKey = c.CustomerKey
INNER JOIN dimgeography g ON c.GeographyKey = g.GeographyKey
INNER JOIN (
    SELECT *
    FROM (
        SELECT
            CustomerKey,
            SalesAmount,
            OrderDate,
            ROW_NUMBER() OVER (PARTITION BY CustomerKey ORDER BY OrderDate) AS RowNumber
        FROM factinternetsales
    ) AS t
    WHERE RowNumber = 1
) first_purchase ON s.CustomerKey = first_purchase.CustomerKey
WHERE s.OrderDate > first_purchase.OrderDate
GROUP BY g.PostalCode;

Question: Show the monthly total and year-to-date total sales. Order by year and month.

SELECT
    Year,
    Month,
    MonthlySales,
    SUM(MonthlySales) OVER (PARTITION BY Year ORDER BY Year, Month ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS CumulativeTotal
FROM (
    SELECT
       YEAR(OrderDate) AS Year,
       MONTH(OrderDate) AS Month,
       SUM(SalesAmount) AS MonthlySales
    FROM factinternetsales
    GROUP BY YEAR(OrderDate), MONTH(OrderDate)
) AS t

Screenshot che mostra l'aggiunta di esempi SQL.

Annotazioni

L'aggiunta di coppie di query/domande di esempio non è attualmente supportata per le origini dati del modello semantico di Power BI.

Testare e modificare l'agente dati di Fabric

Ora che è stato configurato l'agente dati di Fabric, sono state aggiunte le istruzioni dell'agente dati di Fabric e sono state fornite query di esempio per il lakehouse, è possibile interagire con esso ponendo domande e ricevendo risposte. Man mano che si continua a eseguire il test, puoi aggiungere altri esempi e perfezionare le istruzioni per migliorare ulteriormente le prestazioni dell'agente dati di Fabric. Collaborare con i colleghi per raccogliere commenti e suggerimenti e, in base all'input, assicurarsi che le query di esempio e le istruzioni fornite siano allineate ai tipi di domande che vogliono porre.

Pubblica l'agente dati di Fabric

Dopo aver convalidato le prestazioni dell'agente dati di Fabric, puoi decidere di pubblicarlo in modo da poterlo condividere con i colleghi che vogliono eseguire domande e risposte sui dati. In tal caso, selezionare Pubblica, come illustrato in questo screenshot:

Screenshot che mostra la selezione dell’opzione Pubblica.

Viene visualizzata la casella Pubblica agente dati , come illustrato in questo screenshot:

Screenshot che mostra la funzionalità dell'agente di pubblicazione dei dati.

In questa casella, seleziona Pubblica per pubblicare l'agente dei dati Fabric. Viene visualizzato l'URL pubblicato per l'agente dei dati Fabric, come illustrato in questo screenshot:

Screenshot che mostra l’URL pubblicato.

Usare l'agente dati Fabric in Copilot in Power BI

È possibile usare Copilot in Power BI per interagire con l'agente dati di Fabric dopo la pubblicazione. Con Copilot in Power BI, è possibile usare direttamente l'agente dati e altri elementi (ad esempio, report o modelli semantici) senza dover passare da una all'altra.

Selezionare il pulsante Copilot nel riquadro di spostamento sinistro per aprire Copilot in Power BI. Selezionare quindi Aggiungi elementi per ottenere risultati migliori nella casella di testo nella parte inferiore per aggiungere l'agente dati. Selezionare Agenti dati nella finestra visualizzata. Puoi visualizzare solo gli agenti dati ai quali hai accesso. Scegliere l'agente dati desiderato e selezionare Conferma. Questo esempio illustra come usare un singolo agente dati, ma è possibile aggiungere altri elementi, ad esempio altri agenti dati, report o modelli semantici. Lo screenshot seguente illustra i passaggi con un singolo agente dati:

Screenshot che mostra il pulsante Copilot e il pulsante per aggiungere elementi come Agenti dati.

Dopo aver aggiunto l'agente dati a Copilot in Power BI, è possibile porre domande correlate all'agente dati di Fabric, come illustrato nello screenshot seguente:

Screenshot che mostra la risposta di Copilot a una domanda.

Utilizzare il programma agente dati di Fabric a livello di codice

È possibile usare l'agente dati di Fabric a livello di codice all'interno di un notebook di Fabric. Per determinare se l'agente dati di Fabric ha un valore URL pubblicato, selezionare Impostazioni, come illustrato nello screenshot seguente:

Screenshot che mostra la selezione delle impostazioni dell'agente dati di Fabric.

Prima di pubblicare l'agente dati di Fabric, non ha un valore URL pubblicato, come illustrato nello screenshot seguente:

Screenshot che mostra che un agente dati di Fabric non ha un valore URL pubblicato prima della pubblicazione.

Se in precedenza non è stato pubblicato l'agente dati di Fabric, è possibile pubblicarlo seguendo le istruzioni nei passaggi precedenti. Successivamente, è possibile copiare l'URL pubblicato e usarlo nel notebook di Fabric. In questo modo, è possibile eseguire query sull'agente dati di Fabric effettuando chiamate all'API dell'agente dati di Fabric in un notebook di Fabric. Incollare l'URL copiato in questo frammento di codice. Poi, sostituisci la domanda con qualsiasi query pertinente all'agente di dati Fabric. Questo esempio usa \<generic published URL value\> come URL.

Importante

Quando si chiama un agente dati a livello di codice, implementare:

  1. Timeout di polling (vedere l'esempio seguente) per evitare cicli indefiniti.
  2. Frequenza minima di polling (inizia da 2 a 5 secondi; aumenta solo se necessario).
  3. Pulizia dei thread o delle risorse creati dopo il completamento.
  4. Arresto della sessione del notebook al termine del rilascio della capacità di Fabric.

Annotazioni

Modificare i pin di versione (openai, synapseml, pandas, tqdm) alle versioni convalidate più recenti per il runtime di Fabric se queste versioni esatte diventano obsolete.

%pip install "openai==1.70.0"
%pip install "synapseml==1.0.5"  # Required for synapse.ml.mlflow (update version as needed)
%pip install pandas tqdm  # Skip if already available in the Fabric runtime

import typing as t
import time
import uuid

# OpenAI SDK internals
from openai import OpenAI
from openai._models import FinalRequestOptions
from openai._types import Omit
from openai._utils import is_given

# SynapseML helper for env config
from synapse.ml.mlflow import get_mlflow_env_config

# Removed unused imports: requests, json, pprint, APIStatusError, SynapseTokenProvider
 
base_url = "https://<generic published base URL value>"
question = "What data sources do you have access to?"

configs = get_mlflow_env_config()

# Create OpenAI Client
class FabricOpenAI(OpenAI):
    def __init__(
        self,
        api_version: str ="2024-05-01-preview",
        **kwargs: t.Any,
    ) -> None:
        self.api_version = api_version
        default_query = kwargs.pop("default_query", {})
        default_query["api-version"] = self.api_version
        super().__init__(
            api_key="",
            base_url=base_url,
            default_query=default_query,
            **kwargs,
        )
    
    def _prepare_options(self, options: FinalRequestOptions) -> None:
        headers: dict[str, str | Omit] = (
            {**options.headers} if is_given(options.headers) else {}
        )
        options.headers = headers
        headers["Authorization"] = f"Bearer {configs.driver_aad_token}"
        if "Accept" not in headers:
            headers["Accept"] = "application/json"
        if "ActivityId" not in headers:
            correlation_id = str(uuid.uuid4())
            headers["ActivityId"] = correlation_id

        return super()._prepare_options(options)

# Pretty printing helper
def pretty_print(messages):
    print("---Conversation---")
    for m in messages:
        print(f"{m.role}: {m.content[0].text.value}")
    print()

fabric_client = FabricOpenAI()
# Create assistant
assistant = fabric_client.beta.assistants.create(model="not used")
# Create thread
thread = fabric_client.beta.threads.create()
# Create message on thread
message = fabric_client.beta.threads.messages.create(thread_id=thread.id, role="user", content=question)
# Create run
run = fabric_client.beta.threads.runs.create(thread_id=thread.id, assistant_id=assistant.id)

# Wait for run to complete (avoid indefinite loop)
terminal_states = {"completed", "failed", "cancelled", "requires_action"}
poll_interval = 2
timeout_seconds = 300  # Adjust based on expected workload
start_time = time.time()

while run.status not in terminal_states:
    if time.time() - start_time > timeout_seconds:
        raise TimeoutError(f"Run polling exceeded {timeout_seconds} seconds (last status={run.status})")
    run = fabric_client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id,
    )
    print(run.status)
    time.sleep(poll_interval)

if run.status != "completed":
    print(f"Run finished with status: {run.status}")

# Print messages
response = fabric_client.beta.threads.messages.list(thread_id=thread.id, order="asc")
pretty_print(response)

# Delete thread
fabric_client.beta.threads.delete(thread_id=thread.id)

Contenuti correlati

  • Last updated on