Exemple d'agent de données Fabric avec l'ensemble de données AdventureWorks (aperçu)

Cet article explique comment configurer un agent de données dans Microsoft Fabric à l’aide d’un lakehouse comme exemple de source de données. Nous allons d’abord créer et remplir un lakehouse, puis créer un agent de données Fabric et y ajouter le lakehouse. Si vous disposez déjà d’un modèle sémantique Power BI (avec les autorisations de lecture/écriture nécessaires), un entrepôt, une base de données KQL ou une ontologie, suivez les mêmes étapes et sélectionnez cette source à la place. Bien que cette procédure pas à pas utilise un lakehouse, le modèle est le même pour d’autres sources : seule la sélection de la source de données diffère.

Conditions préalables

• Une capacité de structure F2 ou supérieure payante, ou une capacité Power BI Premium par capacité (P1 ou supérieure) avec Microsoft Fabric activé
• Les paramètres du locataire de l'agent de données Fabric sont activés.
• Le traitement intergéographique pour l’IA est activé.
• Le stockage multi-régional pour l’IA est activé.
• Au moins l’un d’entre eux, avec des données : un entrepôt, un lachouse, un ou plusieurs modèles sémantiques Power BI, une base de données KQL ou une ontologie.
• Les modèles sémantiques Power BI via le commutateur de locataire des points de terminaison XMLA sont activés pour les sources de données de modèle sémantique Power BI.

Créez un lakehouse avec AdventureWorksLH

Tout d’abord, créez un lakehouse et remplissez-le avec les données nécessaires.

Si vous disposez déjà d'une instance d'AdventureWorksLH dans un lakehouse (ou un entrepôt), vous pouvez ignorer cette étape. Sinon, vous pouvez utiliser les instructions suivantes à partir d’un bloc-notes Fabric pour remplir le lakehouse avec les données.

1. Créez un nouveau bloc-notes dans l’espace de travail dans lequel vous souhaitez créer votre agent de données Fabric.

2. Sur le côté gauche du volet Explorateur, sélectionnez + Sources de données. Cette option vous permet d'ajouter un lakehouse existant ou de créer un nouveau lakehouse. Par souci de clarté, créez un nouveau lakehouse et attribuez-lui un nom.

3. Ajoutez l’extrait de code suivant dans la cellule au sommet :

   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. Sélectionnez Exécuter tout.

Après quelques minutes, le lakehouse se remplit avec les données nécessaires.

Créer un agent de données Fabric

Pour créer un nouvel agent de données Fabric, accédez à votre espace de travail et sélectionnez le bouton + Nouvel élément, comme indiqué dans cette capture d'écran :

Dans l’onglet Tous les éléments, recherchez l’agent de données Fabric pour localiser l’option appropriée. Une fois sélectionné, une invite vous requête de fournir un nom pour votre agent de données Fabric, comme indiqué dans cette capture d'écran :

Après avoir saisi le nom, procédez aux étapes suivantes pour aligner l'agent de données Fabric sur vos besoins spécifiques.

Sélectionner les données

Sélectionnez le lakehouse que vous avez créée à l'étape précédente, puis sélectionnez Ajouter, comme indiqué dans la capture d'écran suivante :

Une fois le lakehouse ajouté en tant que source de données, le volet Explorateur sur le côté gauche de la page de l'agent de données Fabric affiche le nom du lakehouse. Sélectionnez le lakehouse pour voir toutes les tables disponibles. Utilisez les cases à cocher pour sélectionner les tables que vous souhaitez mettre à disposition de l'IA. Pour ce scénario, sélectionnez ces tables :

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

Fournir des instructions

Pour ajouter des instructions, sélectionnez le bouton Instructions de l’agent de données pour ouvrir le volet d’instructions à droite. Vous pouvez ajouter les instructions suivantes.

La source de données AdventureWorksLH contient des informations provenant de trois tables :

• dimcustomer, pour des informations démographiques détaillées sur les clients et des informations de contact
• dimdate, pour les données liées aux dates, par exemple les informations calendaires et fiscales
• dimgeography, pour les détails géographiques, y compris les noms de villes et les codes de région des pays.

Utilisez cette source de données pour les requêtes et les analyses impliquant les détails des clients, les événements temporels et les emplacements géographiques.

Fournir des exemples

Pour ajouter des exemples de requêtes, sélectionnez le bouton Exemples de requêtes pour ouvrir le volet Exemples de requêtes sur la droite. Ce volet fournit des options permettant d'ajouter ou de modifier des exemples de requêtes pour toutes les sources de données prises en charge. Pour chaque source de données, vous pouvez sélectionner Ajouter ou modifier des exemples de requêtes pour entrer les exemples pertinents, comme illustré dans la capture d’écran suivante :

Ici, vous devez ajouter des exemples de requêtes pour la source de données Lakehouse que vous avez créée.

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

Tester et réviser l'agent de données Fabric

Maintenant que vous avez configuré l'agent de données Fabric, ajouté des instructions à l'agent de données Fabric et fourni des exemples de requêtes pour le lakehouse, vous pouvez interagir avec lui en posant des questions et en recevant des réponses. Au fur et à mesure que vous continuez les tests, vous pouvez ajouter d’autres exemples et affiner les instructions pour améliorer encore les performances de l’agent de données Fabric. Collaborez avec vos collègues pour recueillir des commentaires et, en fonction de leurs contributions, assurez-vous que les exemples de requêtes et d’instructions fournis correspondent aux types de questions qu’ils souhaitent poser.

Publier l’agent de données Fabric

Après avoir validé les performances de l'agent de données Fabric, vous pouvez décider de le publier afin de pouvoir ensuite le partager avec vos collègues qui souhaitent effectuer des questions-réponses sur les données. Dans ce cas, sélectionnez Publier, comme indiqué dans cette capture d’écran :

La zone Publier l’agent de données s’ouvre, comme illustré dans cette capture d’écran :

Dans cette zone, sélectionnez Publier pour publier l’agent de données Fabric. L'URL publiée pour l'agent de données Fabric apparaît, comme indiqué dans cette capture d'écran :

Utiliser l’agent de données Fabric dans Copilot dans Power BI

Vous pouvez utiliser Copilot dans Power BI pour interagir avec l’agent de données Fabric après sa publication. Avec Copilot dans Power BI, vous pouvez utiliser directement l’agent de données et d’autres éléments (par exemple, des rapports ou des modèles sémantiques) sans avoir à basculer entre eux.

Sélectionnez le bouton Copilot dans le volet de navigation gauche pour ouvrir Copilot dans Power BI. Ensuite, sélectionnez Ajouter des éléments pour obtenir de meilleurs résultats dans la zone de texte en bas, pour ajouter l’agent de données. Sélectionnez Agents de données dans la fenêtre qui s’ouvre. Vous ne pouvez voir que les agents de données auxquels vous êtes autorisé à accéder. Choisissez l’agent de données souhaité, puis sélectionnez Confirmer. Cet exemple montre comment utiliser un seul agent de données, mais vous pouvez ajouter d’autres éléments, par exemple d’autres agents de données, rapports ou modèles sémantiques. La capture d’écran suivante illustre les étapes avec un seul agent de données :

Maintenant que vous avez ajouté l’agent de données au Copilot dans Power BI, vous pouvez poser toutes les questions relatives à votre agent de données Fabric, comme illustré dans la capture d’écran suivante :

Utiliser l'agent de données Fabric par programmation

Vous pouvez utiliser l'agent de données Fabric par programmation dans un bloc-notes Fabric. Pour déterminer si l’agent de données Fabric a ou non une valeur d’URL publiée, sélectionnez Paramètres, comme illustré dans la capture d’écran suivante :

Avant de publier l’agent de données Fabric, il n’a pas de valeur d’URL publiée, comme illustré dans la capture d’écran suivante :

Si vous n’avez pas publié l’agent de données Fabric avant, vous pouvez le publier en suivant les instructions des étapes précédentes. Vous pouvez ensuite copier l’URL publiée et l’utiliser dans le notebook Fabric. De cette façon, vous pouvez interroger l’agent de données Fabric en effectuant des appels à l’API de l’agent de données Fabric dans un bloc-notes Fabric. Collez l’URL copiée dans cet extrait de code. Ensuite, remplacez la question par toute requête pertinente pour votre agent de données Fabric. L’exemple suivant utilise \<generic published URL value\> en tant que 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

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)

Contenu connexe

• Concept d'agent de données Fabric
• Créer un agent de données Fabric