Exemplo de agente de dados em malha com o conjunto de dados AdventureWorks (pré-visualização)

Este artigo mostra como configurar um agente de dados no Microsoft Fabric usando uma lakehouse como fonte de dados de exemplo. Primeiro, criamos e preenchemos uma lakehouse, depois criamos um agente de dados do Fabric e adicionamos a lakehouse a ela. Se já tiver um modelo semântico Power BI (com as permissões necessárias de leitura/escrita), um armazém, uma base de dados KQL ou uma ontologia, siga os mesmos passos e selecione essa fonte em vez disso. Embora este passo a passo use uma casa de lago, o padrão é o mesmo para outras fontes — apenas a seleção da fonte de dados é diferente.

Pré-requisitos

• Uma capacidade de malha paga F2 ou superior ou uma capacidade do Power BI Premium por capacidade (P1 ou superior) com o Microsoft Fabric habilitado
• As configurações do locatário do agente de dados de infraestrutura estão habilitadas.
• O processamento geográfico cruzado para IA está habilitado.
• O armazenamento geográfico cruzado para IA está habilitado.
• Pelo menos um destes, com dados: um armazém, uma casa de lago, um ou mais modelos semânticos Power BI, uma base de dados KQL ou uma ontologia.
• Os modelos semânticos do Power BI por meio da opção de locatário de pontos de extremidade XMLA estão habilitados para fontes de dados de modelo semântico do Power BI.

Crie uma casa no lago com o AdventureWorksLH

Primeiro, crie uma casa de lago e preencha-a com os dados necessários.

Se você já tiver uma instância do AdventureWorksLH em uma casa no lago (ou em um armazém), ignore esta etapa. Caso contrário, podes usar as seguintes instruções de um notebook do Fabric para preencher o lakehouse com dados.

1. Crie um novo bloco de anotações no espaço de trabalho onde você deseja criar seu agente de dados do Fabric.

2. No lado esquerdo do painel Explorer , selecione + Fontes de dados. Esta opção permite ao utilizador adicionar uma lakehouse existente ou criar uma nova lakehouse. Por uma questão de clareza, crie uma nova casa do lago e atribua-lhe um nome.

3. Na célula superior, adicione o seguinte trecho 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.

Criar um agente de dados Fabric

Para criar um novo agente de dados do Fabric, navegue até ao seu ambiente de trabalho e selecione o botão 'Novo Item' (+), conforme mostrado nesta captura de ecrã:

Na guia Todos os itens, procure agente de dados Fabric para localizar a opção apropriada. Uma vez selecionado, um prompt solicita que você forneça um nome para seu 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 de malha com seus requisitos específicos.

Selecione os dados

Selecione a casa do lago que você criou na etapa anterior e, em seguida, selecione Adicionar, conforme mostrado na captura de tela a seguir:

Assim que o lakehouse é adicionado como fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados do Fabric mostra o nome do lakehouse. Selecione a casa do lago para ver todas as mesas disponíveis. Use as caixas de seleção para selecionar as tabelas que deseja disponibilizar para a IA. Para esse 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 seguintes instruções.

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

• dimcustomer, para dados demográficos detalhados dos clientes e informações de contato
• dimdate, para dados relacionados com a data - por exemplo, calendário e informações fiscais
• dimgeography, para obter detalhes geográficos, incluindo nomes de cidades e códigos de região do país.

Use essa fonte de dados para consultas e análises que envolvam detalhes do cliente, eventos baseados no 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 suportadas. Para cada fonte de dados, você pode selecionar Adicionar ou Editar Consultas de Exemplo para inserir os exemplos relevantes, conforme mostrado na captura de tela a seguir:

Aqui, você deve adicionar consultas de exemplo para a fonte de dados 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 continua os testes, 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 feedback e, com base em suas entradas, certifique-se de que as consultas e instruções de exemplo fornecidas estejam alinhadas 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ê pode decidir publicá-lo para poder compartilhá-lo com seus colegas que desejam fazer perguntas&respostas sobre dados. Nesse caso, selecione Publicar, conforme mostrado nesta captura de tela:

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

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

Usar o agente de dados Fabric no Copilot do Power BI

Você pode usar o Copilot no Power BI para interagir com o agente de dados do Fabric após a sua publicação. 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 se abre. 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, pode fazer perguntas relacionadas ao seu 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 Fabric programaticamente em um bloco de anotações Fabric. Para determinar se o agente de dados de malha tem ou não um valor de URL publicado, selecione Configurações, conforme mostrado na captura de tela a seguir:

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

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, pode copiar o URL publicado e usá-lo no caderno Fabric. Dessa forma, você pode consultar o agente de dados do Fabric fazendo chamadas para a API do agente de dados do Fabric em um bloco de anotações do Fabric. Cole o URL copiado neste trecho de código. Em seguida, substitua a pergunta por qualquer consulta relevante para seu agente de dados do Fabric. Este exemplo usa \<generic published URL value\> como 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 de tecido
• Criar um agente de dados Fabric