Ejemplo del agente de datos de Fabric con el conjunto de datos de AdventureWorks (versión preliminar)

En este artículo se muestra cómo configurar un agente de datos en Microsoft Fabric mediante una instancia de Lakehouse como origen de datos de ejemplo. Primero creamos y rellenamos un lakehouse y, a continuación, creamos un agente de datos de Fabric y agregamos el lakehouse a este. Si ya tiene un modelo semántico de Power BI (con los permisos de lectura y escritura necesarios), un almacenamiento, una base de datos KQL o una ontología, siga los mismos pasos y seleccione ese origen en su lugar. Aunque en este tutorial se utiliza un lakehouse, el patrón es el mismo para otros orígenes; solo varía la selección del origen de datos.

Importante

Esta característica se encuentra en versión preliminar.

Prerrequisitos

• Una capacidad de Tejido F2 o superior de pago, o una capacidad de Power BI Premium por capacidad (P1 o superior) con Microsoft Fabric habilitado
• La configuración del inquilino del agente de datos de Fabric está habilitada.
• El procesamiento entre regiones geográficas para la inteligencia artificial está habilitado.
• El almacenamiento entre regiones geográficas para la inteligencia artificial está habilitado.
• Al menos uno de ellos, con datos: un almacén, un lakehouse, uno o varios modelos semánticos de Power BI, una base de datos KQL o una ontología.
• Modelos semánticos de Power BI a través del conmutador de inquilino de puntos de conexión XMLA está habilitado para orígenes de datos del modelo semántico de Power BI.

Importante

Asegúrese de que la experiencia autónoma de Copilot está habilitada en el portal de administración de Power BI (Configuración del inquilino > Copilot > experiencia autónoma de Copilot). Si no está activado, no podrá usar el agente de datos en los escenarios de Copilot, incluso si otros interruptores de inquilino de Copilot están encendidos. Para obtener más información, consulte Copilot en la configuración del espacio de trabajo de Power BI.

Crear un lakehouse con AdventureWorksLH

En primer lugar, cree un lago de datos y complételo con los datos necesarios.

Si ya tiene una instancia de AdventureWorksLH en un almacén o lago de datos, puede omitir este paso. Si no es así, puede usar las siguientes instrucciones de un cuaderno de Fabric para rellenar el almacén de lago con los datos.

1. Cree un nuevo cuaderno en el área de trabajo donde quiera crear su agente de datos de Fabric.

2. En el lado izquierdo del panel Explorador, seleccione + Orígenes de datos. Esta opción le permite agregar un lakehouse existente o bien crear uno nuevo. Para mayor claridad, cree un nuevo lakehouse y asígnele un nombre.

3. En la celda superior, añada el siguiente fragmento 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. Seleccione Run all (Ejecutar todas).

Después de unos minutos, el almacén de lago se llena con los datos necesarios.

Precaución

Los cuadernos que continúan ejecutándose (por ejemplo, debido a bucles infinitos accidentales o sondeos constantes) pueden consumir capacidad de Fabric indefinidamente. Una vez que los datos terminen de cargarse, detenga las celdas activas y finalice la sesión del cuaderno (barra de herramientas del cuaderno > Detener sesión) si ya no la necesita. Evite agregar bucles que se ejecuten durante un período prolongado sin un límite de tiempo.

Creación de un agente de datos de Fabric

Para crear un nuevo agente de datos de Fabric, navegue hasta su área de trabajo y seleccione el botón + Nuevo elemento, como se muestra en este recorte de pantalla:

En la pestaña Todos los elementos, busque Agente de datos de Fabric para localizar la opción adecuada. Una vez seleccionado, una indicación le pide que proporcione un nombre para su agente de datos de Fabric, como se muestra en este recorte de pantalla:

Después de escribir el nombre, siga los siguientes pasos para alinear el agente de datos de Fabric con sus requisitos específicos.

Selección de los datos:

Seleccione el lakehouse que creó en el paso anterior y después seleccione Agregar, como se muestra en la captura de pantalla a continuación.

Una vez que el "lakehouse" se agrega como origen de datos, el panel Explorador del lado izquierdo de la página del agente de datos de Fabric muestra el nombre del "lakehouse". Seleccione el almacén de lago para ver todas las tablas disponibles. Use las casillas de verificación para seleccionar las tablas que quiere poner a disposición de la IA. Para este escenario, seleccione estas tablas:

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

Proporcionar instrucciones

Para agregar instrucciones, seleccione el botón Instrucciones del agente de datos para abrir el panel de instrucciones de la derecha. Puede agregar las siguientes instrucciones.

El origen de datos de AdventureWorksLH contiene información de tres tablas:

• dimcustomer, para obtener datos demográficos detallados del cliente e información de contacto
• dimdate, para los datos relacionados con la fecha, por ejemplo, el calendario y la información fiscal
• dimgeography, para obtener detalles geográficos, incluidos los nombres de ciudad y los códigos de región de país.

Use este origen de datos para consultas y análisis que implican detalles del cliente, eventos basados en tiempo y ubicaciones geográficas.

Provisión de ejemplos

Para agregar consultas de ejemplo, seleccione el botón Consultas de ejemplo para abrir el panel de consultas de ejemplo a la derecha. Este panel ofrece opciones para agregar o editar consultas de ejemplo para todos los orígenes de datos compatibles. Para cada origen de datos, puede seleccionar Agregar o editar consultas de ejemplo para escribir los ejemplos pertinentes, como se muestra en la captura de pantalla siguiente:

Aquí, debe agregar Consultas de ejemplo para el origen de datos del almacén de lago de datos que creó.

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

Nota:

La adición de pares de consultas y preguntas de ejemplo no se admite actualmente para orígenes de datos del modelo semántico de Power BI.

Prueba y revisión del agente de datos de Fabric

Ahora que ha configurado el agente de datos de Fabric, agregado instrucciones para el agente y proporcionado consultas de ejemplo para el lakehouse, puede interactuar con él haciendo preguntas y recibiendo respuestas. A medida que continúe realizando pruebas, podrá agregar más ejemplos y mejorar las instrucciones para mejorar aún más el rendimiento del agente de datos de Fabric. Colabore con sus compañeros para recopilar comentarios y, basándose en sus aportaciones, asegúrese de que los ejemplos de consultas y las instrucciones proporcionadas se ajustan a los tipos de preguntas que quieren hacer.

Publicar el agente de datos de Fabric

Después de validar el funcionamiento del agente de datos de Fabric, es posible que decida publicarlo para poder compartirlo después con sus compañeros que quieran hacer preguntas y respuestas sobre los datos. En este caso, seleccione Publicar, como se muestra en esta captura de pantalla:

Se abre el cuadro Agente de Publicación de Datos, como se muestra en esta captura de pantalla:

En este cuadro, seleccione Publicar para publicar el agente de datos de Fabric. Aparece la dirección URL publicada para el agente de datos de Fabric, como se muestra en este recorte de pantalla:

Uso del agente de datos de Fabric en Copilot en Power BI

Puede usar Copilot en Power BI para interactuar con el agente de datos de Fabric después de publicarlo. Con Copilot en Power BI, puede consumir directamente el agente de datos y otros elementos (por ejemplo, informes o modelos semánticos) sin necesidad de cambiar entre ellos.

Seleccione el botón Copilot en el panel de navegación izquierdo para abrir Copilot en Power BI. A continuación, seleccione Agregar elementos para obtener mejores resultados en el cuadro de texto de la parte inferior para agregar el agente de datos. Seleccione Agentes de datos en la ventana que se abre. Sólo puede ver los agentes de datos a los que tiene permiso para acceder. Elija el agente de datos que desee y seleccione Confirmar. En este ejemplo se muestra cómo trabajar con un único agente de datos, pero puede agregar más elementos, por ejemplo, otros agentes de datos, informes o modelos semánticos. En la captura de pantalla siguiente se muestran los pasos con un único agente de datos:

Ahora que agregó el agente de datos a Copilot en Power BI, puede hacer cualquier pregunta relacionada con el agente de datos de Fabric, como se muestra en la captura de pantalla siguiente:

Uso del agente de datos de Fabric mediante programación

Puede usar el agente de datos de Fabric mediante programación dentro de un cuaderno de Fabric. Para determinar si el agente de datos de Fabric tiene o no un valor de dirección URL publicado, seleccione Configuración, como se muestra en la captura de pantalla siguiente:

Antes de publicar el agente de datos de Fabric, no tiene un valor de dirección URL publicado, como se muestra en la captura de pantalla siguiente:

Si no ha publicado el agente de datos de Fabric antes, puede publicarlo siguiendo las instrucciones de los pasos anteriores. A continuación, puede copiar la dirección URL publicada y utilizarla en el cuaderno de Fabric. De este modo, puede consultar al agente de datos de Fabric realizando llamadas a la API del agente de datos de Fabric en un cuaderno de Fabric. Pegue la dirección URL copiada en este fragmento de código. A continuación, reemplace la pregunta por cualquier consulta relevante para el agente de datos de Fabric. Este ejemplo utiliza \<generic published URL value\> como dirección URL.

Importante

Al llamar a un agente de datos mediante programación, implemente:

1. Un tiempo de espera de sondeo (consulte el ejemplo siguiente) para evitar bucles indefinidos.
2. Frecuencia mínima de sondeo (comienza en 2 a 5 segundos; aumenta solo si es necesario).
3. Limpieza de hilos o recursos creados tras su finalización.
4. Cerrar la sesión del cuaderno al finalizar para liberar la capacidad de Fabric.

Nota:

Ajuste las fijaciones de versión (openai, synapseml, pandas, tqdm) a las versiones validadas más recientes para el entorno de ejecución de Fabric si estas versiones exactas se vuelven obsoletas.

%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)

Contenido relacionado

• Concepto del agente de datos de Fabric
• Creación de un agente de datos de Fabric