Share via

Voorbeeld van Fabric-gegevensagent met de AdventureWorks-gegevensset (preview)

In dit artikel wordt beschreven hoe u een gegevensagent instelt in Microsoft Fabric met behulp van een lakehouse als voorbeeldgegevensbron. Eerst maken en vullen we een Lakehouse, vervolgens maken we een Fabric-gegevensagent en voegen we het lakehouse eraan toe. Als u al een semantisch Power BI-model (met de benodigde lees-/schrijfmachtigingen), een magazijn, een KQL-database of een ontologie hebt, volgt u dezelfde stappen en selecteert u die bron. Hoewel in dit scenario een lakehouse wordt gebruikt, is het patroon hetzelfde voor andere bronnen. Alleen de selectie van de gegevensbron verschilt.

Belangrijk

Deze functie is beschikbaar als preview-versie.

Vereiste voorwaarden

Belangrijk

Zorg ervoor dat de zelfstandige Copilot-functie is ingeschakeld in het Power BI-beheerportaal (Instellingen voor huurder > Copilot > Zelfstandige Copilot-functie). Als deze niet is ingeschakeld, kunt u de gegevensagent niet gebruiken in Copilot-scenario's, zelfs niet als andere Copilot-tenantswitches zijn ingeschakeld. Zie Copilot in de tenantinstellingen van Power BI voor meer informatie.

Een lakehouse maken met AdventureWorksLH

Maak eerst een lakehouse en vul deze met de benodigde gegevens.

Als u al een exemplaar van AdventureWorksLH in een lakehouse (of een magazijn) hebt, kunt u deze stap overslaan. Zo niet, dan kunt u de volgende instructies uit een Fabric-notebook gebruiken om het lakehouse te vullen met de gegevens.

  1. Maak een nieuw notitieblok in de werkruimte waar u uw Fabric-gegevensagent wilt maken.

  2. Selecteer + gegevensbronnen aan de linkerkant van het deelvenster Explorer. Met deze optie kunt u een bestaand lakehouse toevoegen of een nieuw lakehouse maken. Maak voor de duidelijkheid een nieuw lakehouse en wijs er een naam aan toe.

  3. Voeg in de bovenste cel het volgende codefragment toe:

    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. Selecteer Alles uitvoeren.

Schermopname van een notebook met de AdventureWorks-uploadcode.

Binnen enkele minuten wordt het lakehouse gevuld met de benodigde gegevens.

Waarschuwing

Notebooks die blijven werken (bijvoorbeeld vanwege onbedoelde oneindige lussen of constante polling) kunnen de capaciteit van de Fabric onbeperkt verbruiken. Nadat de gegevens zijn geladen, stopt u alle actieve cellen en beëindigt u de notebooksessie (notebookwerkbalk > sessie stoppen) als u deze niet meer nodig hebt. Vermijd het toevoegen van langlopende lussen zonder een time-out.

Een Fabric-gegevensagent maken

Als u een nieuwe Fabric-gegevensagent wilt maken, gaat u naar uw werkruimte en selecteert u de knop + Nieuw item, zoals wordt weergegeven in deze schermopname:

Schermafbeelding waarin wordt weergegeven waar Fabric-gegevensagenten moeten worden gemaakt.

Zoek op het tabblad Alle items naar Fabric-gegevensagent om de juiste optie te vinden. Zodra deze optie is geselecteerd, wordt u gevraagd een naam op te geven voor uw Fabric-gegevensagent, zoals wordt weergegeven in deze schermopname:

schermopname waarin wordt weergegeven waar u de naam voor de Fabric-gegevensagent opgeeft.

Nadat u de naam hebt ingevoerd, gaat u verder met de volgende stappen om de Fabric-gegevensagent af te stemmen op uw specifieke vereisten.

Selecteer de gegevens

Selecteer het lakehouse dat u in de vorige stap hebt gemaakt en selecteer vervolgens Toevoegen, zoals wordt weergegeven in de volgende schermopname:

Schermopname van de stap waar een lakehouse wordt toegevoegd.

Zodra het Lakehouse is toegevoegd als een gegevensbron, wordt in het deelvenster Explorer aan de linkerkant van de pagina Fabric-gegevensagent de naam van lakehouse weergegeven. Selecteer het lakehouse om alle beschikbare tabellen weer te geven. Gebruik de selectievakjes om de tabellen te selecteren die u beschikbaar wilt maken voor de AI. Selecteer voor dit scenario de volgende tabellen:

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

schermopname die laat zien waar u tabellen voor AI kunt selecteren.

Instructies opgeven

Als u instructies wilt toevoegen, selecteert u de knop Instructies voor gegevensagent om het deelvenster instructies aan de rechterkant te openen. U kunt de volgende instructies toevoegen.

De AdventureWorksLH gegevensbron bevat informatie uit drie tabellen:

  • dimcustomer, voor gedetailleerde demografische gegevens van klanten en contactgegevens
  • dimdate, voor datumgerelateerde gegevens, bijvoorbeeld kalender- en fiscale gegevens
  • dimgeography, voor geografische details, waaronder stadsnamen en landregiocodes.

Gebruik deze gegevensbron voor query's en analyses die betrekking hebben op klantgegevens, tijdgebeurtenissen en geografische locaties.

schermopname die laat zien waar u de instructies voor de AI kunt opgeven.

Voorbeelden opgeven

Als u voorbeeldquery's wilt toevoegen, selecteert u de knop Voorbeeldquery's om het deelvenster voorbeeldquery's aan de rechterkant te openen. Dit deelvenster bevat opties voor het toevoegen of bewerken van voorbeeldquery's voor alle ondersteunde gegevensbronnen. Voor elke gegevensbron kunt u Voorbeeldquery's toevoegen of bewerken selecteren om de relevante voorbeelden in te voeren, zoals wordt weergegeven in de volgende schermopname:

schermopname die laat zien waar u de voorbeelden kunt toevoegen die u aan de AI verstrekt.

Hier moet u voorbeeldquery's toevoegen voor de lakehouse-gegevensbron die u hebt gemaakt.

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

Schermopname van het toevoegen van SQL-voorbeelden.

Opmerking

Het toevoegen van voorbeeldquery-/vraagparen wordt momenteel niet ondersteund voor gegevensbronnen van het semantische Power BI-model.

De Fabric-gegevensagent testen en herzien

Nu u de Fabric-gegevensagent hebt geconfigureerd, instructies voor de Fabric-gegevensagent hebt toegevoegd en voorbeeldquery's voor lakehouse hebt opgegeven, kunt u ermee werken door vragen te stellen en antwoorden te ontvangen. Wanneer u doorgaat met testen, kunt u meer voorbeelden toevoegen en de instructies verfijnen om de prestaties van de Fabric-gegevensagent verder te verbeteren. Werk samen met uw collega's om feedback te verzamelen en zorg ervoor dat de opgegeven voorbeeldquery's en instructies overeenkomen met de typen vragen die ze willen stellen.

De Fabric-gegevensagent publiceren

Nadat u de prestaties van de Fabric-gegevensagent hebt gevalideerd, kunt u besluiten deze te publiceren, zodat u deze vervolgens kunt delen met uw collega's die Q&A over gegevens willen uitvoeren. In dit geval selecteert u Publiceren, zoals wordt weergegeven in deze schermopname:

Schermopname van de selectie van de optie Publiceren.

Het vak Gegevensagent publiceren wordt geopend, zoals wordt weergegeven in deze schermopname:

Schermopname van de functie publiceren van de gegevensagent.

Selecteer In dit vak Publiceren om de Fabric-gegevensagent te publiceren. De gepubliceerde URL voor de Fabric-gegevensagent wordt weergegeven, zoals wordt weergegeven in deze schermopname:

Schermopname van de gepubliceerde URL.

De Fabric-gegevensagent gebruiken in Copilot in Power BI

U kunt copilot in Power BI gebruiken om te communiceren met de Fabric-gegevensagent nadat u deze hebt gepubliceerd. Met Copilot in Power BI kunt u de gegevensagent en andere items (bijvoorbeeld rapporten of semantische modellen) rechtstreeks gebruiken zonder dat u tussen deze items hoeft te schakelen.

Selecteer de knop Copilot in het linkernavigatiedeelvenster om de Copilot in Power BI te openen. Selecteer vervolgens Items toevoegen voor betere resultaten in het tekstvak onderaan om de gegevensagent toe te voegen. Selecteer Gegevensagents in het venster dat wordt geopend. U kunt alleen de gegevensagenten zien waartoe u toegang hebt. Kies de gewenste gegevensagent en selecteer Bevestigen. In dit voorbeeld ziet u hoe u met één gegevensagent werkt, maar u kunt meer items toevoegen, bijvoorbeeld andere gegevensagenten, rapporten of semantische modellen. In de volgende schermopname ziet u de stappen met één gegevensagent:

Schermopname van de copilot-knop en -knop om items zoals Gegevensagenten toe te voegen.

Nu u de gegevensagent hebt toegevoegd aan Copilot in Power BI, kunt u vragen stellen met betrekking tot uw Fabric-gegevensagent, zoals wordt weergegeven in de volgende schermopname:

Schermopname van copilot die een vraag beantwoordt.

De Fabric-gegevensagent programmatisch gebruiken

U kunt de Fabric-gegevensagent programmatisch in een Fabric-notebook gebruiken. Als u wilt bepalen of de Fabric-gegevensagent een gepubliceerde URL-waarde heeft, selecteert u Instellingen, zoals wordt weergegeven in de volgende schermopname:

Schermopname van de selectie van de instellingen van de Fabric-gegevensagent.

Voordat u de Fabric-gegevensagent publiceert, heeft deze geen gepubliceerde URL-waarde, zoals wordt weergegeven in de volgende schermopname:

Schermopname die laat zien dat een Fabric-gegevensagent vóór publicatie geen gepubliceerde URL-waarde heeft.

Als u de Fabric-gegevensagent nog niet eerder hebt gepubliceerd, kunt u deze publiceren volgens de instructies in de vorige stappen. Vervolgens kunt u de gepubliceerde URL kopiëren en gebruiken in het Fabric-notebook. Op deze manier kunt u een query uitvoeren op de Fabric-gegevensagent door aanroepen uit te voeren naar de Fabric-gegevensagent-API in een Fabric-notebook. Plak de gekopieerde URL in dit codefragment. Vervang vervolgens de vraag door een query die relevant is voor uw Fabric-gegevensagent. In dit voorbeeld wordt de URL gebruikt \<generic published URL value\> .

Belangrijk

Implementeer het volgende wanneer u programmatisch een gegevensagent aanroept:

  1. Een time-out voor polling (zie het onderstaande voorbeeld) om onbepaalde lussen te voorkomen.
  2. Minimale pollingfrequentie (begin bij 2-5 seconden; verhoog alleen indien nodig).
  3. Opschonen van gemaakte threads of resources na voltooiing.
  4. Sluit de notebooksessie af wanneer deze klaar is om de Fabric-capaciteit vrij te geven.

Opmerking

Pas versiepinnen (openai, synapseml, pandas, tqdm) aan op de meest recente gevalideerde versies voor uw Fabric-runtime als deze exacte versies verouderd raken.

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

Verwante inhoud

  • Last updated on