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

Este artigo mostra como configurar um agente de dados no Microsoft Fabric usando uma casa de lago como fonte de dados de exemplo. Primeiro criamos e povoamos uma casa do lago, depois criamos um agente de dados Fabric e adicionamos a casa do lago. Se já tiver um modelo semântico do Power BI, certifique-se de que tem permissão de leitura para interagir com ele através de um agente de dados (a permissão de escrita só é necessária para modificar o modelo semântico ou usar capacidades como Prep for AI). Para um armazém, uma base de dados KQL ou uma ontologia, siga os mesmos passos e selecione essa fonte em vez disso. Embora este tutorial utilize um lakehouse, o padrão é o mesmo para outras fontes de dados; apenas a seleção da fonte de dados difere.

Pré-requisitos

• Uma capacidade paga F2 ou superior do Fabric, ou uma capacidade do Power BI Premium (P1 ou superior) com Microsoft Fabric ativado.
• As definições do tenant do agente de dados Fabric estão ativadas, incluindo a definição Capacidades podem ser designadas como capacidades do Fabric Copilot.
• 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.
• Modelos semânticos Power BI via troca de inquilino dos endpoints XMLA estão ativados para fontes de dados de modelos semânticos Power BI.
• Para modelos semânticos do Power BI usados com um agente de dados, certifique-se de que os utilizadores que interagem através do agente têm permissão de leitura sobre o modelo semântico. Não é necessária permissão de Membro do Espaço de Trabalho ou de Construção para interagir.

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, pode usar as seguintes instruções de um notebook Fabric para preencher o lakehouse com os dados.

1. Crie um novo caderno no espaço de trabalho onde quer criar o seu agente de dados 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 Fabric, navegue até ao seu espaço de trabalho e selecione o botão + Novo Item, como mostrado nesta captura de ecrã:

No separador Todos os itens, pesquise por Fabric data agent para localizar a opção apropriada. Uma vez selecionado, um prompt pede-lhe que forneça um nome para o seu agente de dados Fabric, como mostrado nesta captura de ecrã:

Depois de inserir o nome, siga os seguintes passos para alinhar o agente de dados Fabric com os 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:

Uma vez que a casa do lago é adicionada como fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados Fabric mostra o nome da casa do lago. 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

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

Os utilizadores só precisam de permissão de leitura num modelo semântico Power BI para o adicionar a um agente de dados e colocar questões através do agente. O acesso ao espaço de trabalho (função de membro) e a permissão de compilação não são necessários para interagir através de agentes de dados. A permissão de escrita é necessária apenas para modificar o modelo semântico ou utilizar capacidades como Prep for AI.

Esta alteração de permissões aplica-se apenas a interações através de agentes de dados. Outros padrões de acesso (por exemplo, Analisar em Excel ou autoria de relatórios diretos) seguem permissões padrão do Power BI.

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 rever o agente de dados Fabric

Agora que configurou o agente de dados Fabric, adicionou instruções do agente de dados Fabric e forneceu consultas de exemplo para a casa do lago, pode interagir com ela fazendo perguntas e recebendo respostas. À medida que continua a testar, 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 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 Fabric

Depois de validar o desempenho do agente de dados Fabric, pode decidir publicá-lo para depois partilhá-lo com os seus colegas que queiram realizar sessões de perguntas e 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 Fabric aparece, como mostrado nesta captura de ecrã:

Use o agente de dados Fabric no Copilot no Power BI

Podes usar o Copilot no Power BI para interagir com o agente de dados Fabric depois de o publicares. Com o Copilot no Power BI, pode consumir diretamente o agente de dados e outros itens (por exemplo, relatórios ou modelos semânticos) sem precisar de alternar entre eles.

Selecione o botão Copilot no painel de navegação esquerdo para abrir a 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:

Quando um agente de dados inclui um modelo semântico Power BI, os utilizadores só precisam de permissão de leitura nesse modelo semântico para interagir com ele via Copilot; não é necessário acesso ao espaço de trabalho. Ainda é necessária permissão de escrita para alterações semânticas de modelos e Preparação para IA.

Agora que adicionou o agente de dados ao Copilot no Power BI, pode colocar quaisquer perguntas relacionadas com o seu agente de dados Fabric, como mostrado na seguinte captura de ecrã:

Use o agente de dados Fabric programaticamente

Podes usar o agente de dados Fabric programaticamente dentro de um notebook Fabric. Para determinar se o agente de dados Fabric tem ou não um valor de URL publicado, selecione Settings, como mostrado na seguinte captura de ecrã:

Antes de publicar o agente de dados Fabric, não tem um valor de URL publicado, como mostrado na seguinte captura de ecrã:

Se nunca publicou o agente de dados Fabric antes, pode publicá-lo seguindo as instruções dos passos anteriores. Depois podes copiar o URL publicado e usá-lo no caderno Fabric. Desta forma, pode consultar o agente de dados Fabric fazendo chamadas para a API do agente de dados Fabric num caderno Fabric. Cole o URL copiado neste trecho de código. Depois, substitua a pergunta por qualquer consulta relevante para o seu agente de dados 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 rede
• Criar um agente de dados Fabric