Partilhar via

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.

Importante

Este recurso está em pré-visualização.

Pré-requisitos

Importante

Verifique se a experiência do Copilot independente está habilitada no portal de administração do Power BI (Definições do Inquilino > Copilot > Experiência do Copilot Independente). Se não estiver ativado, não será possível usar o agente de dados nos cenários do Copilot, mesmo que outros interruptores de inquilino do Copilot estejam ativados. Para ver detalhes, consulte Copilot nas configurações de inquilino 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.

Captura de tela mostrando um bloco de anotações com o código de carregamento do AdventureWorks.

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

Atenção

Os notebooks que continuam a executar (por exemplo, devido a loops infinitos acidentais ou sondagem constante) podem consumir a capacidade da Fabric indefinidamente. Após o término do carregamento dos dados, pare todas as células ativas e encerre a sessão do notebook (barra de ferramentas > do notebook Encerrar sessão) caso já não precise. Evite adicionar loops de longa duração sem um tempo limite.

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ã:

Screenshot mostrando onde criar agentes de dados do Fabric.

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:

Captura de tela mostrando onde fornecer o nome para o agente de dados do Fabric.

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:

Captura de tela mostrando a etapa de adicionar um lakehouse.

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

Captura de tela mostrando onde você pode selecionar tabelas para IA.

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.

Captura de tela mostrando onde você pode fornecer as instruções para a IA.

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:

Captura de tela mostrando onde você pode adicionar os exemplos fornecidos à IA.

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

Captura de tela mostrando a adição de exemplos SQL.

Observação

Atualmente, não há suporte para a adição de pares de consulta/pergunta de exemplo para fontes de dados de modelo semântico do Power BI.

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:

Captura de ecrã a mostrar a seleção da opção Publicar.

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

Captura de tela mostrando o recurso de agente de dados de publicação.

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:

Captura de ecrã a mostrar o URL publicado.

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:

Captura de tela mostrando o botão Copilot e o botão para adicionar itens como Agentes 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:

Captura de ecrã a mostrar o Copilot a responder a uma pergunta.

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:

Captura de tela mostrando a seleção de configurações do agente de dados do Fabric.

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:

Captura de tela mostrando que um agente de dados do Fabric não tem um valor de URL publicado antes da publicação.

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.

Importante

Ao chamar um agente de dados programaticamente, implemente:

  1. Um tempo limite de sondagem (veja o exemplo abaixo) para evitar loops indefinidos.
  2. Frequência mínima de sondagem (comece em 2–5 segundos; aumente apenas se necessário).
  3. Limpeza de threads ou recursos criados após a conclusão.
  4. Encerramento da sessão do caderno de notas quando concluída a fim de libertar a capacidade do Fabric.

Observação

Ajuste os pinos de versão (openai, synapseml, pandas, tqdm) para as versões validadas mais recentes para o runtime do Fabric se essas versões exatas ficarem desatualizadas.

%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

  • Last updated on