Fabric-dataagent-eksempel med AdventureWorks-datasettet (forhåndsvisning)

Denne artikkelen viser hvordan man setter opp en dataagent i Microsoft Fabric ved å bruke et lakehouse som eksempeldatakilde. Først lager og fyller vi et lakehouse, deretter lager vi en Fabric dataagent og legger lakehouse til det. Hvis du allerede har en Power BI-semantisk modell, sørg for at du har lesetillatelse til å samhandle med den gjennom en dataagent (skrivetillatelse kreves kun for å endre den semantiske modellen eller bruke funksjoner som Prep for AI). For et lager, en KQL-database eller en ontologi, følg de samme stegene og velg den kilden i stedet. Selv om denne gjennomgangen bruker et innsjøhus, er mønsteret det samme for andre kilder; kun valget av datakilde skiller seg ut.

Prerequisites

• A betalt F2 eller høyere Fabric kapasitet, eller en Power BI Premium per kapasitet (P1 eller høyere) kapasitet med Microsoft Fabric aktivert.
• Fabric dataagent-leietakerinnstillinger er aktivert, inkludert innstillingen Kapasiteter kan angis som Fabric Copilot kapasiteter.
• kryss-geo-behandling for AI- er aktivert.
• kryss-geo lagring for AI- er aktivert.
• Minst én av disse, med data: Et lager, et innsjøhus, en eller flere Power BI-semantiske modeller, en KQL-database eller en ontologi.
• Power BI semantiske modeller via XMLA endpoints tenant switch er aktivert for Power BI semantiske modelldatakilder.
• For Power BI-semantiske modeller brukt med en dataagent, sørg for at brukere som interagerer via agenten har lesetillatelse på den semantiske modellen. Workspace Member- eller Build-tillatelse kreves ikke for interaksjon.

Opprett et lakehouse med AdventureWorksLH

Først oppretter du et lakehouse og fyller det ut med de nødvendige dataene.

Hvis du allerede har en forekomst av AdventureWorksLH i et lakehouse (eller et lager), kan du hoppe over dette trinnet. Hvis ikke, kan du bruke følgende instruksjoner fra en Fabric-notatbok for å fylle innsjøhuset med dataene.

1. Opprett en ny notatbok i arbeidsområdet der du vil opprette din Fabric-dataagent.

2. På venstre side av Utforsker-ruten velger du + Datakilder. Med dette alternativet kan du legge til et eksisterende lakehouse eller opprette et nytt lakehouse. For klarhet, opprett et nytt innsjøhus og tilordne et navn til det.

3. Legg til følgende kodesnutt i den øverste cellen:

   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. Velg Kjør alle.

Etter noen minutter fylles lakehouse med de nødvendige dataene.

Opprett en Fabric-dataagent

For å opprette en ny Fabric dataagent, naviger til arbeidsområdet ditt og velg knappen + Nytt element, som vist i dette skjermbildet:

I fanen Alle elementer, søk etter Fabric data agent for å finne riktig alternativ. Når du er valgt, ber en prompt deg om å oppgi et navn til din Fabric-dataagent, som vist i dette skjermbildet:

Etter at du har skrevet inn navnet, fortsetter du med følgende steg for å tilpasse Fabric-dataagenten til dine spesifikke krav.

Velg dataene

Velg innsjøhuset du opprettet i forrige trinn, og velg deretter Legg til, som vist i følgende skjermbilde:

Når innsjøhuset legges til som datakilde, viser Explorer-panelet på venstre side av Fabric dataagent-siden navnet på innsjøhuset. Velg lakehouse for å vise alle tilgjengelige tabeller. Bruk avmerkingsboksene til å velge tabellene du vil gjøre tilgjengelig for kunstig intelligens. Velg disse tabellene for dette scenarioet:

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

Tillatelser for semantiske modeller i dataagenter

Brukere trenger kun lesetillatelse på en Power BI-semantisk modell for å legge den til i en dataagent og stille spørsmål gjennom agenten. Arbeidsområdetilgang (Medlemrolle) og byggetillatelse kreves ikke for interaksjon via dataagenter. Skrivetillatelse trengs kun for å endre den semantiske modellen eller bruke funksjoner som Prep for AI.

Denne tillatelsesendringen gjelder kun for interaksjoner gjennom dataagenter. Andre tilgangsmønstre (for eksempel Analyser i Excel eller direkte rapportforfatterskap) følger standard Power BI-tillatelser.

Gi instruksjoner

Hvis du vil legge til instruksjoner, velger du Instruksjoner for dataagent for å åpne instruksjonsruten til høyre. Du kan legge til følgende instruksjoner.

Datakilden AdventureWorksLH inneholder informasjon fra tre tabeller:

• dimcustomer, for detaljert kundedemografi og kontaktinformasjon
• dimdate, for datorelaterte data – for eksempel kalender- og regnskapsinformasjon
• dimgeographyfor geografiske detaljer, inkludert bynavn og landsområdekoder.

Bruk denne datakilden for spørringer og analyser som involverer kundedetaljer, tidsbaserte hendelser og geografiske plasseringer.

Gi eksempler

Hvis du vil legge til eksempelspørringer, velger du Eksempelspørringer-knappen for å åpne eksempelspørringsruten til høyre. Denne ruten inneholder alternativer for å legge til eller redigere eksempelspørringer for alle støttede datakilder. For hver datakilde kan du velge Legg til eller rediger eksempelspørringer for å legge inn de relevante eksemplene, som vist i følgende skjermbilde:

Her bør du legge til eksempelspørringer for datakilden for lakehouse som du opprettet.

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

Test og revider Fabric-dataagenten

Nå som du har konfigurert Fabric-dataagenten, lagt til instruksjoner for Fabric-dataagenten, og gitt eksempelforespørsler for lakehouse, kan du samhandle med den ved å stille spørsmål og motta svar. Etter hvert som du fortsetter testingen, kan du legge til flere eksempler og forbedre instruksjonene for å ytterligere forbedre ytelsen til Fabric-dataagenten. Samarbeid med kollegene dine for å samle inn tilbakemeldinger, og kontroller at de angitte eksempelspørringene og instruksjonene samsvarer med spørsmålstypene de vil stille.

Publiser Fabric-dataagenten

Etter at du har validert ytelsen til Fabric-dataagenten, kan du bestemme deg for å publisere den slik at du kan dele den med kollegene dine som vil gjøre Q& En overdata. I dette tilfellet velger du Publiser, som vist i dette skjermbildet:

Boksen Publiser dataagent åpnes, som vist i dette skjermbildet:

I denne boksen velger du Publish for å publisere den Fabric dataagenten. Den publiserte URL-en for Fabric-dataagenten vises, som vist i dette skjermbildet:

Bruk Fabric-dataagenten i Copilot i Power BI

Du kan bruke Copilot i Power BI for å samhandle med Fabric-dataagenten etter at du har publisert den. Med Copilot i Power BI kan du direkte konsumere dataagenten og andre elementer (for eksempel rapporter eller semantiske modeller) uten å måtte bytte mellom dem.

Velg knappen Copilot i venstre navigasjonspanel for å åpne Copilot i Power BI. Deretter velger du Legg til elementer for bedre resultater i tekstboksen nederst for å legge til dataagenten. Velg Dataagenter i vinduet som åpnes. Du kan bare se dataagentene du har tilgang til. Velg dataagenten du vil bruke, og velg Bekreft. Dette eksemplet viser hvordan du arbeider med én enkelt dataagent, men du kan legge til flere elementer – for eksempel andre dataagenter, rapporter eller semantiske modeller. Følgende skjermbilde illustrerer trinnene med én enkelt dataagent:

Når en dataagent inkluderer en Power BI-semantisk modell, trenger brukere kun lesetillatelse på den semantiske modellen for å kunne interagere med den via Copilot; arbeidsplasstilgang er ikke nødvendig. Skrivetillatelse er fortsatt nødvendig for endringer i semantiske modeller og forberedelser for AI.

Nå som du har lagt til dataagenten i Copilot i Power BI, kan du stille spørsmål knyttet til din Fabric-dataagent, som vist i følgende skjermbilde:

Bruk Fabric-dataagenten programmatisk

Du kan bruke Fabric-dataagenten programmatisk innenfor en Fabric-notatbok. For å avgjøre om den Fabric dataagenten har en publisert URL-verdi, velg Settings, som vist i følgende skjermbilde:

Før du publiserer Fabric-dataagenten, har den ikke en publisert URL-verdi, som vist i følgende skjermbilde:

Hvis du ikke har publisert Fabric-dataagenten før, kan du publisere den ved å følge instruksjonene i de forrige stegene. Du kan deretter kopiere den publiserte URL-en og bruke den i Fabric-notatboken. På denne måten kan du spørre Fabric-dataagenten ved å gjøre kall til Fabric-dataagent-API-et i en Fabric-notatbok. Lim inn den kopierte URL-adressen i kodesnutten. Deretter erstatter du spørsmålet med en hvilken som helst spørring som er relevant for din Fabric-dataagent. Dette eksemplet brukes \<generic published URL value\> som URL-adresse.

%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)

Relatert innhold

• Fabric dataagentkonsept
• Opprett en Fabric dataagent