Exemplo do agente de dados do Fabric com o conjunto de dados do AdventureWorks (versão prévia)

Este artigo mostra como configurar um agente de dados no Microsoft Fabric usando um lakehouse como a fonte de dados de exemplo. Primeiro criamos e populamos um lakehouse, depois criamos um agente de dados do Fabric e adicionamos a lakehouse a ele. Se você já tiver um modelo semântico do Power BI (com as permissões de leitura/gravação necessárias), um warehouse, um banco de dados KQL ou uma ontologia, siga as mesmas etapas e selecione essa origem. Embora este passo a passo utilize um lakehouse, o padrão permanece consistente para outras origens de dados—apenas a escolha da fonte de dados é diferente.

Pré-requisitos

• Uma capacidade paga do F2 ou superior do Fabric ou uma capacidade do Power BI Premium por capacidade (P1 ou superior) com o Microsoft Fabric habilitado
• As Configurações de locatário do agente de dados do Fabric estão habilitadas.
• O Processamento entre áreas geográficas de IA está habilitado.
• O Armazenamento entre áreas geográficas de IA está habilitado.
• Pelo menos um destes, com dados: um armazém, um lakehouse, um ou mais modelos semânticos do Power BI, um banco de dados KQL ou uma ontologia.
• Os Modelos semânticos do Power BI pela opção de locatário dos pontos de extremidade XMLA estão habilitados para as fontes de dados do modelo semântico do Power BI.

Crie um lakehouse com o AdventureWorksLH

Primeiro, crie um lakehouse e preencha-o com os dados necessários.

Se você já tiver uma instância do AdventureWorksLH em um depósito ou lakehouse, pode ignorar esta etapa. Caso contrário, você pode usar as instruções a seguir de um bloco de anotações do Fabric para preencher o lakehouse com os dados.

1. Crie um novo notebook no espaço de trabalho em que deseja criar o agente de dados do Fabric.

2. No lado esquerdo do painel Explorer, selecione + Fontes de dados. Essa opção permite que você adicione um lakehouse já existente ou crie um novo lakehouse. Para fins de clareza, crie um novo lakehouse e atribua um nome a ele.

3. Na célula superior, adicione o seguinte snippet de código:

   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. Selecione Executar tudo.

Após alguns minutos, o lakehouse é preenchido com os dados necessários.

Como criar um agente de dados do Fabric

Para criar um novo agente de dados do Fabric, navegue até seu workspace e selecione o botão Novo Item, conforme mostrado nesta captura de tela:

Na guia Todos os itens, pesquise Agente de dados do Fabric para localizar a opção apropriada. Depois de selecionado, um prompt solicita que você forneça um nome para o agente de dados do Fabric, conforme mostrado nesta captura de tela:

Depois de inserir o nome, prossiga com as etapas a seguir para alinhar o agente de dados do Fabric com seus requisitos específicos.

Selecione os dados

Selecione o lakehouse que você criou na etapa anterior e, em seguida, selecione Adicionar, conforme mostrado na seguinte captura de tela:

Assim que o lakehouse é adicionado como uma fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados do Fabric mostra o nome do lakehouse. Selecione o lakehouse para exibir todas as tabelas disponíveis. Use as caixas de seleção para selecionar as tabelas que você deseja disponibilizar para a IA. Para este cenário, selecione estas tabelas:

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

Fornecer instruções

Para adicionar instruções, selecione o botão instruções do agente de dados para abrir o painel de instruções à direita. Você pode adicionar as instruções a seguir.

A fonte de dados AdventureWorksLH contém informações de três tabelas:

• dimcustomer, para informações detalhadas de dados demográficos e de contato do cliente
• dimdate, para dados relacionados à data – por exemplo, informações de calendário e fiscais
• dimgeography, para obter detalhes geográficos, incluindo nomes de cidade e códigos de região do país.

Use essa fonte de dados para consultas e análises que envolvem detalhes do cliente, eventos baseados em tempo e localizações geográficas.

Forneça exemplos

Para adicionar consultas de exemplo, selecione o botão Consultas de Exemplo para abrir o painel de consultas de exemplo à direita. Este painel fornece opções para adicionar ou editar consultas de exemplo para todas as fontes de dados com suporte. Para cada fonte de dados, você pode selecionar Adicionar ou Editar Consultas de Exemplo para inserir os exemplos relevantes, conforme mostrado na seguinte captura de tela:

Aqui, você deve adicionar consultas de exemplo para a fonte de dados do lakehouse que você criou.

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

Testar e revisar o agente de dados do Fabric

Agora que você configurou o agente de dados do Fabric, adicionou instruções do agente de dados do Fabric e forneceu consultas de exemplo para o lakehouse, você pode interagir com ele fazendo perguntas e recebendo respostas. À medida que você continua testando, você pode adicionar mais exemplos e refinar as instruções para melhorar ainda mais o desempenho do agente de dados do Fabric. Colabore com seus colegas para coletar comentários e, com base em suas entradas, verifique se as consultas e instruções de exemplo fornecidas se alinham com os tipos de perguntas que eles desejam fazer.

Publicar o agente de dados do Fabric

Depois de validar o desempenho do agente de dados do Fabric, você poderá decidir publicá-lo para que possa compartilhá-lo com seus colegas que desejam fazer P e R por meio de dados. Nesse caso, selecione Publicar conforme mostrado nesta captura de tela:

A caixa Publicar agente de dados é aberta, conforme mostrado nesta captura de tela:

Nesta caixa, selecione Publicar para publicar o agente de dados do Fabric. A URL publicada para o agente de dados do Fabric é exibida, conforme mostrado nesta captura de tela:

Utilize o agente de dados do Fabric no Copilot do Power BI

Você pode usar o Copilot no Power BI para interagir com o agente de dados do Fabric depois de publicá-lo. Com o Copilot no Power BI, você pode consumir diretamente o agente de dados e outros itens (por exemplo, relatórios ou modelos semânticos) sem precisar alternar entre eles.

Selecione o botão Copilot no painel de navegação esquerdo para abrir o Copilot no Power BI. Em seguida, selecione Adicionar itens para obter melhores resultados na caixa de texto na parte inferior, para adicionar o agente de dados. Selecione agentes de dados na janela que é aberta. Você só pode ver os agentes de dados que você tem permissão para acessar. Escolha o agente de dados desejado e selecione Confirmar. Este exemplo mostra como trabalhar com um único agente de dados, mas você pode adicionar mais itens , por exemplo, outros agentes de dados, relatórios ou modelos semânticos. A captura de tela a seguir ilustra as etapas com um único agente de dados:

Agora que você adicionou o agente de dados ao Copilot no Power BI, você pode fazer perguntas relacionadas ao agente de dados do Fabric, conforme mostrado na captura de tela a seguir:

Usar o agente de dados do Fabric programaticamente

Você pode usar o agente de dados do Fabric programaticamente em um bloco de anotações do Fabric. Para determinar se o agente de dados do Fabric tem ou não um valor de URL publicado, selecione Configurações, conforme mostrado na seguinte captura de tela:

Antes de publicar o agente de dados do Fabric, ele não tem um valor de URL publicado, conforme mostrado na seguinte captura de tela:

Se você não tiver publicado o agente de dados do Fabric antes, poderá publicá-lo seguindo as instruções nas etapas anteriores. Em seguida, você pode copiar a URL publicada e usá-la no notebook do Fabric. Dessa forma, você pode consultar o agente de dados do Fabric fazendo chamadas à API do agente de dados do Fabric em um bloco de anotações do Fabric. Cole a URL copiada neste snippet de código. Em seguida, substitua a pergunta por qualquer consulta relevante para seu agente de dados Fabric. Este exemplo usa \<generic published URL value\> como a 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)

Conteúdo relacionado

• Conceito de agente de dados do Fabric
• Como criar um agente de dados do Fabric