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

Este artigo mostra como configurar um agente de dados em Microsoft Fabric usando um lakehouse como a fonte de dados de exemplo. Primeiro criamos e populamos uma lakehouse, depois criamos um agente de dados Fabric e adicionamos o lakehouse a ele. Se você já tiver um modelo semântico Power BI, verifique se tem permissão de leitura para interagir com ele por meio de um agente de dados (a permissão de gravação só é necessária para modificar o modelo semântico ou usar recursos como o Prep for AI). Para um armazém, um banco de dados KQL ou uma ontologia, siga as mesmas etapas e selecione essa fonte. Embora este passo a passo use uma lakehouse, o padrão é o mesmo para outras fontes; apenas a seleção da fonte de dados é diferente.

Pré-requisitos

• Uma capacidade paga de Fabric F2 ou superior ou uma capacidade Power BI Premium por capacidade (P1 ou superior) com Microsoft Fabric habilitado.
• Configurações do locatário do agente de dados de Fabricação estão habilitadas, incluindo a configuração as capacidades podem ser designadas como capacidades Copilot de Fabricação.
• O Processamento entre áreas geográficas de IA está habilitado.
• O Armazenamento entre áreas geográficas de IA está habilitado.
• Pelo menos um deles, com dados: um armazém, um lakehouse, um ou mais modelos semânticos Power BI, um banco de dados KQL ou uma ontologia.
• Modelos semânticos do Power BI por meio do comutador de locatário de pontos de extremidade XMLA estão habilitados para fontes de dados de modelos semânticos do Power BI.
• Para modelos semânticos do Power BI usados com um agente de dados, assegure-se de que os usuários que interajam via o agente tenham permissão de leitura no modelo semântico. A permissão de membro do workspace ou de Build não é necessária para interação.

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 notebook Fabric para preencher o lakehouse com os dados.

1. Crie um novo bloco de anotações no workspace em que você deseja criar seu agente de dados 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.

Criar um agente de dados Fabric

Para criar um novo agente de dados Fabric, navegue até o 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 Fabric, conforme mostrado nesta captura de tela:

Depois de inserir o nome, prossiga com as etapas a seguir para alinhar o agente de dados 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:

Depois que o lakehouse é adicionado como uma fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados 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

Permissões para modelos semânticos em agentes de dados

Os usuários só precisam de permissão de leitura em um modelo semântico Power BI para adicioná-lo a um agente de dados e fazer perguntas por meio do agente. O acesso ao workspace (função membro) e a permissão Build não são necessários para interação por meio de agentes de dados. A permissão de gravação é necessária apenas para modificar o modelo semântico ou usar recursos como Preparação para IA.

Essa alteração de permissões se aplica somente a interações por meio de agentes de dados. Outros padrões de acesso (por exemplo, Analisar em Excel ou criação direta de relatório) seguem permissões de Power BI padrão.

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 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 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 Fabric

Depois de validar o desempenho do agente de dados Fabric, você poderá decidir publicá-lo para que possa compartilhá-lo com seus colegas que desejam fazer Q& Um sobre 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 Publish para publicar o agente de dados Fabric. A URL publicada para o agente de dados Fabric é exibida, conforme mostrado nesta captura de tela:

Usar o agente de dados Fabric em Copilot em Power BI

Você pode usar o Copilot em Power BI para interagir com o agente de dados Fabric depois de publicá-lo. Com Copilot em 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 em 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:

Quando um agente de dados inclui um modelo semântico Power BI, os usuários precisam apenas da permissão de leitura nesse modelo semântico para interagir com ele por meio de Copilot; o acesso ao workspace não é necessário. A permissão de gravação ainda é necessária para alterações no modelo semântico e preparação para Inteligência Artificial.

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

Usar o agente de dados 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 Fabric tem ou não um valor de URL publicado, selecione Settings, conforme mostrado na captura de tela a seguir:

Antes de publicar o agente de dados 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, você pode copiar a URL publicada e usá-la no bloco de anotações Fabric. Dessa forma, você pode consultar o agente de dados Fabric fazendo chamadas para a API do agente de dados Fabric em um bloco de anotações Fabric. Cole a URL copiada neste snippet de código. Em seguida, substitua a pergunta por qualquer consulta relevante para o 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 Fabric
• Criar um agente de dados Fabric