Fabric data agent eksempel med AdventureWorks-datasættet (forhåndsvisning)

Denne artikel viser, hvordan man opsætter en dataagent i Microsoft Fabric ved at bruge et lakehouse som eksempeldatakilde. Vi opretter og fylder først et lakehouse, derefter opretter vi en Fabric dataagent og tilføjer lakehouse til det. Hvis du allerede har en Power BI semantisk model, skal du sikre dig, at du har læsetilladelse til at interagere med den via en dataagent (skrivetilladelse kræves kun for at ændre den semantiske model eller bruge funktioner som Prep for AI). For et lager, en KQL-database eller en ontologi, følg de samme trin og vælg i stedet den kilde. Selvom denne gennemgang bruger et søhus, er mønsteret det samme for andre kilder; kun valget af datakilder adskiller sig.

Prerequisites

• A betalt F2 eller højere Fabric kapacitet, eller en Power BI Premium pr. kapacitet (P1 eller højere) kapacitet med Microsoft Fabric aktiveret.
• Fabric dataagent-lejerindstillinger er aktiveret, inklusive indstillingen Kapaciteter kan angives som Fabric Copilot kapaciteter.
• Tværgående geobehandling af AI- er aktiveret.
• Cross-geo-lagring til AI- er aktiveret.
• Mindst én af disse, med data: Et lager, et søhus, en eller flere Power BI semantiske modeller, en KQL-database eller en ontologi.
• Power BI semantiske modeller via XMLA endpoints tenant switch er aktiveret for Power BI semantiske modeldatakilder.
• For Power BI semantiske modeller, der bruges med en dataagent, skal du sikre, at brugere, der interagerer via agenten, har læsetilladelse på den semantiske model. Workspace Member eller Build tilladelse er ikke nødvendig for interaktion.

Opret et lakehouse med AdventureWorksLH

Først skal du oprette et lakehouse og udfylde det med de nødvendige data.

Hvis du allerede har en forekomst af AdventureWorksLH i et lakehouse (eller et lager), kan du springe dette trin over. Hvis ikke, kan du bruge følgende instruktioner fra en Fabric-notesbog til at fylde søhuset med dataene.

1. Opret en ny notesbog i arbejdsområdet, hvor du vil oprette din Fabric-dataagent.

2. I venstre side af ruden Stifinder skal du vælge + Datakilder. Denne indstilling giver dig mulighed for at tilføje et eksisterende lakehouse eller oprette et nyt lakehouse. Af hensyn til klarheden skal du oprette et nyt lakehouse og tildele et navn til det.

3. Tilføj følgende kodestykke i den øverste celle:

   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. Vælg Kør alle.

Efter et par minutter udfylder lakehouse med de nødvendige data.

Opret en Fabric-dataagent

For at oprette en ny Fabric dataagent, navigér til dit arbejdsområde og vælg knappen + Nyt element, som vist på dette skærmbillede:

I fanen Alle genstande søger du efter Fabric data agent for at finde den passende mulighed. Når du er valgt, beder en prompt dig om at angive et navn til din Fabric-dataagent, som vist på dette screenshot:

Efter du har indtastet navnet, fortsætter du med følgende trin for at tilpasse Fabric-dataagenten til dine specifikke krav.

Vælg dataene

Vælg det søhus, du oprettede i det forrige trin, og vælg derefter Tilføj, som vist på følgende skærmbillede:

Når søhuset er tilføjet som datakilde, viser Explorer-panelet i venstre side af Fabric dataagent-siden søhusets navn. Vælg lakehouse for at få vist alle tilgængelige tabeller. Brug afkrydsningsfelterne til at vælge de tabeller, du vil gøre tilgængelige for AI. I dette scenarie skal du vælge disse tabeller:

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

Tilladelser for semantiske modeller i dataagenter

Brugere behøver kun læsetilladelse på en Power BI semantisk model for at tilføje den til en dataagent og stille spørgsmål gennem agenten. Workspace-adgang (medlemrolle) og byggetilladelse er ikke nødvendige for interaktion via dataagenter. Skrivetilladelse er kun nødvendig for at ændre den semantiske model eller bruge kapabiliteter som Prep for AI.

Denne ændring af tilladelser gælder kun for interaktioner gennem dataagenter. Andre adgangsmønstre (for eksempel Analyser i Excel eller direkte rapportforfatterskab) følger standard Power BI-tilladelser.

Giv instruktioner

Hvis du vil tilføje instruktioner, skal du vælge knappen Instruktioner til dataagent for at åbne ruden til højre. Du kan tilføje følgende instruktioner.

Den AdventureWorksLH datakilde indeholder oplysninger fra tre tabeller:

• dimcustomerfor at få detaljerede kundedemografi- og kontaktoplysninger
• dimdatefor datorelaterede data , f.eks. kalender- og regnskabsoplysninger
• dimgeographyfor geografiske oplysninger, herunder bynavne og landeområdekoder.

Brug denne datakilde til forespørgsler og analyser, der omfatter kundeoplysninger, tidsbaserede hændelser og geografiske placeringer.

Giv eksempler

Hvis du vil tilføje eksempelforespørgsler, skal du vælge knappen Eksempelforespørgsler for at åbne ruden med eksempelforespørgsler til højre. Denne rude indeholder indstillinger til at tilføje eller redigere eksempelforespørgsler for alle understøttede datakilder. For hver datakilde kan du vælge Tilføj eller rediger eksempelforespørgsler for at angive de relevante eksempler, som vist på følgende skærmbillede:

Her skal du tilføje eksempelforespørgsler for den datakilde i lakehouse,du har oprettet.

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

Nu hvor du har konfigureret Fabric-dataagenten, tilføjet Fabric-dataagentinstruktioner og leveret eksempelforespørgsler til lakehouset, kan du interagere med den ved at stille spørgsmål og modtage svar. Efterhånden som du fortsætter testen, kan du tilføje flere eksempler og forfine instruktionerne for yderligere at forbedre ydeevnen af Fabric-dataagenten. Samarbejd med dine kolleger om at indsamle feedback, og sørg for, at de angivne eksempelforespørgsler og instruktioner er i overensstemmelse med de typer spørgsmål, de vil stille.

Publicér Fabric-dataagenten

Efter du har valideret ydeevnen af Fabric-dataagenten, kan du beslutte at publicere den, så du derefter kan dele den med dine kolleger, der vil lave Q& A over data. I dette tilfælde skal du vælge Udgiv som vist på dette skærmbillede:

Feltet Publicer dataagent åbnes som vist på dette skærmbillede:

I denne boks vælger du Publicish for at publicere den Fabric dataagent. Den offentliggjorte URL til Fabric-dataagenten vises, som vist på dette screenshot:

Brug Fabric-dataagenten i Copilot i Power BI

Du kan bruge Copilot i Power BI til at interagere med Fabric-dataagenten efter du har udgivet den. Med Copilot i Power BI kan du direkte forbruge dataagenten og andre elementer (for eksempel rapporter eller semantiske modeller) uden at skulle skifte mellem dem.

Vælg knappen Copilot i venstre navigationspanel for at åbne Copilot i Power BI. Vælg derefter Tilføj elementer for at få bedre resultater i tekstfeltet nederst for at tilføje dataagenten. Vælg Dataagenter i det vindue, der åbnes. Du kan kun se de dataagenter, du har adgangstilladelse til. Vælg den ønskede dataagent, og vælg Bekræft. Dette eksempel viser, hvordan du arbejder med en enkelt dataagent, men du kan tilføje flere elementer, f.eks. andre dataagenter, rapporter eller semantiske modeller. På følgende skærmbillede illustreres trinnene med en enkelt dataagent:

Når en dataagent inkluderer en Power BI-semantisk model, behøver brugerne kun læsetilladelse på den semantiske model for at interagere med den via Copilot; adgang til arbejdsområdet er ikke påkrævet. Skrivetilladelse er stadig nødvendig for ændringer af semantiske modeller og forberedelse til AI.

Nu hvor du har tilføjet dataagenten til Copilot i Power BI, kan du stille spørgsmål vedrørende din Fabric-dataagent, som vist i følgende skærmbillede:

Brug Fabric-dataagenten programmatisk

Du kan bruge Fabric-dataagenten programmatisk inden for en Fabric-notesbog. For at afgøre, om Fabric dataagent har en offentliggjort URL-værdi, vælg Settings, som vist i følgende skærmbillede:

Før du offentliggør Fabric-dataagenten, har den ikke en publiceret URL-værdi, som vist på følgende skærmbillede:

Hvis du ikke har offentliggjort Fabric-dataagenten før, kan du udgive den ved at følge instruktionerne i de foregående trin. Du kan derefter kopiere den publicerede URL og bruge den i Fabric-notesbogen. På denne måde kan du forespørge Fabric-dataagenten ved at foretage kald til Fabric data agent-API'en i en Fabric-notebook. Indsæt den kopierede URL-adresse i dette kodestykke. Erstat derefter spørgsmålet med enhver forespørgsel, der er relevant for din Fabric-dataagent. Dette eksempel bruger \<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)

Relateret indhold

• Fabric dataagent-koncept
• Opret en Fabric dataagent