Fabric dataagentexempel med AdventureWorks-datauppsättningen (förhandsversion)

Den här artikeln visar hur du konfigurerar en dataagent i Microsoft Fabric med hjälp av ett lakehouse som exempeldatakälla. Först skapar och fyller vi i ett sjöhus, sedan skapar vi en Fabric dataagent och lägger till lakehouse i det. Om du redan har en Power BI semantisk modell kontrollerar du att du har läsbehörighet för att interagera med den via en dataagent (skrivbehörighet krävs endast för att ändra den semantiska modellen eller använda funktioner som Förberedelse för AI). För ett lager, en KQL-databas eller en ontologi följer du samma steg och väljer källan i stället. Även om den här genomgången använder ett sjöhus är mönstret detsamma för andra källor. endast valet av datakälla skiljer sig åt.

Förutsättningar

• En betald F2 eller högre Fabric Kapacitet, eller en Power BI Premium kapacitet per kapacitet (P1 eller högre) med Microsoft Fabric Aktiverat.
• Aktivera kors-geo-bearbetning och kors-geo-lagring för AI baserat på krav som beskrivs i Fabric data agent tenant inställningar.
• Minst en av dessa datakällor, med data: Ett lager, ett sjöhus, en Power BI-semantisk modell, en KQL-databas, en speglad databas eller en ontologi. Du måste ha läsbehörighet till datakällan.

Skapa ett sjöhus med AdventureWorksLH

Först skapar du ett sjöhus och fyller det med nödvändiga data.

Om du redan har en instans av AdventureWorksLH i ett datahus (eller ett lager) kan du hoppa över det här steget. Annars kan du använda följande instruktioner från en Fabric notebook-fil för att fylla lakehouse med data.

1. Skapa en ny notebook-fil på arbetsytan där du vill skapa din Fabric dataagent.

2. Till vänster i fönstret Utforskaren väljer du + Datakällor. Med det här alternativet kan du lägga till ett befintligt sjöhus eller skapa ett nytt sjöhus. Skapa ett nytt sjöhus för tydlighetens skull och tilldela det ett namn.

3. Lägg till följande kodfragment i den översta 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. Välj Kör alla.

Efter några minuter fylls sjöstugan med den nödvändiga datan.

Skapa en Fabric dataagent

Om du vill skapa en ny Fabric dataagent går du till din arbetsyta och väljer knappen + Nytt objekt som du ser i den här skärmbilden:

På fliken Alla objekt söker du efter Fabric dataagent för att hitta lämpligt alternativ. När du har valt det uppmanas du att ange ett namn på din Fabric dataagent, som du ser i den här skärmbilden:

När du har angett namnet fortsätter du med följande steg för att justera Fabric dataagenten efter dina specifika krav.

Välj datamängd

Välj det lakehouse som du skapade i föregående steg och välj sedan Lägg till, som visas i följande skärmbild:

När ett lakehouse har lagts till som en datakälla, visar fönstret Explorer till vänster på sidan för dataagenten namnet på lakehouse. Välj lakehouse för att visa alla tillgängliga tabeller. Använd kryssrutorna för att markera de tabeller som du vill göra tillgängliga för AI:n. I det här scenariot väljer du följande tabeller:

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

Behörigheter för semantiska modeller i dataagenter

Användarna behöver bara läsbehörighet för en Power BI semantisk modell för att lägga till den i en dataagent och ställa frågor via agenten. Åtkomst till arbetsyta (medlemsroll) och skapa-behörighet krävs inte för interaktion via dataagenter. Skrivbehörighet krävs endast för att ändra semantikmodellen eller använda funktioner som Förberedelse för AI.

Den här behörighetsändringen gäller endast interaktioner via dataagenter. Andra åtkomstmönster (till exempel Analysera i Excel eller direkt rapportredigering) följer standardbehörigheter för Power BI.

Ge instruktioner

Om du vill lägga till instruktioner väljer du knappen Dataagentinstruktioner för att öppna anvisningarna till höger. Du kan lägga till följande instruktioner.

Den AdventureWorksLH datakällan innehåller information från tre tabeller:

• dimcustomer, för detaljerad kunddemografi och kontaktinformation
• dimdate, för datumrelaterade data – till exempel kalender- och räkenskapsinformation
• dimgeographyför geografisk information, inklusive ortnamn och landsregionkoder.

Använd den här datakällan för frågor och analyser som omfattar kundinformation, tidsbaserade händelser och geografiska platser.

Ange exempel

Om du vill lägga till exempelfrågor väljer du knappen Exempelfrågor för att öppna fönstret exempelfrågor till höger. Det här fönstret innehåller alternativ för att lägga till eller redigera exempelfrågor för alla datakällor som stöds. För varje datakälla kan du välja Lägg till eller redigera exempelfrågor för att ange relevanta exempel, enligt följande skärmbild:

Här bör du lägga till Exempelfrågor för den lakehouse-datakälla som du skapade.

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

Testa och revidera Fabric-dataagenten

Nu när du har konfigurerat Fabric dataagenten, lagt till Fabric dataagentinstruktioner och tillhandahållit exempelfrågor för lakehouse kan du interagera med den genom att ställa frågor och få svar. När du fortsätter att testa kan du lägga till fler exempel och förfina instruktionerna för att ytterligare förbättra prestandan för Fabric dataagenten. Samarbeta med dina kollegor för att samla in feedback och se till att de exempelfrågor och instruktioner som tillhandahålls överensstämmer med de typer av frågor som de vill ställa.

Publicera Fabric-dataagenten

När du har verifierat prestandan för Fabric dataagenten kan du välja att publicera den så att du sedan kan dela den med dina kollegor som vill genomföra Q&A över data. I det här fallet väljer du Publicera, som du ser i den här skärmbilden:

Rutan Publicera dataagent öppnas, vilket visas i skärmbilden:

I den här rutan väljer du Publicera för att publicera Fabric dataagenten. När dataagenten väl är publicerad kan den konsumeras som en modell kontextprotokoll (MCP)-server.

Använda Fabric-dataagenten programmatiskt

Du kan använda Fabric-dataagenten programmatiskt i en Fabric notebook-fil. Om du vill avgöra om Fabric-dataagenten har ett publicerat URL-värde väljer du Settings enligt följande skärmbild:

Innan du publicerar Fabric dataagenten har den inget publicerat URL-värde, som du ser i följande skärmbild:

Om du inte har publicerat Fabric dataagenten tidigare kan du publicera den enligt anvisningarna i föregående steg. Du kan sedan kopiera den publicerade URL:en och använda den i den Fabric notebook-filen. På så sätt kan du fråga Fabric dataagenten genom att anropa api:et för Fabric-dataagenten i en Fabric notebook-fil. Klistra in den kopierade URL:en i det här kodfragmentet. Ersätt sedan frågan med frågor som är relevanta för din Fabric dataagent. Det här exemplet används \<generic published URL value\> som URL.

%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

Fråga dataagenten med Python

Följande exempel ansluter till MCP-slutpunkten, identifierar verktyget, skickar en fråga och skriver ut svaret. Den återanvänder credential från autentisera till Fabric steg och använder MCP-Python SDK. Installera SDK:et först:

%pip install mcp

import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

workspace_id = "<your-workspace-id>"
data_agent_id = "<your-data-agent-id>"
question = "<your question>"

mcp_url = (
    f"https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspace_id}"
    f"/dataagents/{data_agent_id}/agent"
)


def get_auth_headers():
    token = credential.get_token("https://api.fabric.microsoft.com/.default")
    return {"Authorization": f"Bearer {token.token}"}


async def query_data_agent(question):
    headers = get_auth_headers()

    async with streamablehttp_client(mcp_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # The data agent exposes a single tool. Discover it, then call it.
            tools = await session.list_tools()
            tool = tools.tools[0]
            question_arg = next(iter(tool.inputSchema["properties"]))

            result = await session.call_tool(tool.name, {question_arg: question})

            answers = [block.text for block in result.content if block.type == "text"]
            return "\n".join(answers)


answer = asyncio.run(query_data_agent(question))
print(answer)

Relaterat innehåll

• Fabric data-agent-koncept
• Skapa en Fabric dataagent