共用方式為

使用 AdventureWorks 資料集的網狀架構資料代理程式範例（預覽）

本文說明如何使用資料湖存放庫作為資料來源，在 Microsoft Fabric 中設定資料代理程式。 為了說明這個過程，我們會先建立 Lakehouse，並將數據添加進去。 然後，我們創建一個Fabric資料代理，並將湖倉配置為其資料來源。 如果您已經有 Power BI 語意模型（具有必要的讀取/寫入許可權）、倉儲或 KQL 資料庫，您可以在建立網狀架構資料代理程式以新增資料來源之後，遵循相同的步驟。 雖然此處顯示的步驟著重於 Lakehouse，但過程與其他資料來源類似，您只需根據您的特定選擇進行調整。

這很重要

這項功能處於 預覽狀態。

先決條件

使用 AdventureWorksLH 建立湖泊屋

首先，建立資料湖倉，並填入所需的資料。

如果您在湖倉或倉儲中已經有 AdventureWorksLH 的實例，您可以略過此步驟。 如果沒有，您可以使用 Fabric 筆記本中的下列指示，將數據填入湖倉中。

  1. 在您要在其中建立網狀架構資料代理程式的工作區中建立新的筆記本。

  2. 在 [檔案總管] 窗格的左側，選取 [+ 資料來源]。 此選項可讓您新增現有的 Lakehouse 或建立新的 Lakehouse。 為了清晰起見，請建立新的「Lakehouse」，並給它命名。

  3. 在頂端儲存格中，新增下列程式碼片段：

    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. 選擇 全部執行。

顯示具有 AdventureWorks 上傳程式代碼的筆記本螢幕快照。

幾分鐘後，資料湖倉會填入必要的數據。

建立網狀架構資料代理程式

若要建立新的網狀架構資料代理程式，請流覽至您的工作區，然後選取 [+ 新增項目] 按鈕，如下列螢幕擷取畫面所示：

顯示建立 Fabric 數據代理程式位置的螢幕快照。

在 [所有項目] 索引標籤中，搜尋 [網狀架構資料代理程式] 以找出適當的選項。 選取之後，提示會要求您提供網狀架構資料代理程式的名稱，如下列螢幕擷取畫面所示：

此螢幕快照顯示提供網狀架構數據代理程式名稱的位置。

輸入名稱之後，請繼續進行下列步驟，讓網狀架構資料代理程式符合您的特定需求。

選取資料

選取您在上一個步驟中建立的 Lakehouse，然後選取 [ 新增]，如下列螢幕快照所示：

顯示新增「lakehouse」步驟的螢幕快照。

將湖倉新增為資料來源之後，Fabric 資料代理程式頁面左側的 Explorer 窗格會顯示湖倉名稱。 選擇 Lakehouse 以檢視所有可用的表格。 使用複選框來選取您想要提供給 AI 使用的數據表。 在此案例中，請選取下列數據表：

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

此螢幕快照顯示您可以選取 AI 資料表的位置。

提供指示

若要新增網狀架構資料代理程式指示，請選取 [資料代理程式指示] 按鈕，以開啟右側的 [網狀架構資料代理程式指示] 窗格。 您可以新增下列指示。

AdventureWorksLH 資料來源包含來自三個資料表的資訊：

  • dimcustomer，以取得詳細的客戶人口統計和連絡資訊
  • dimdate，適用於日期相關資料 - 例如行事曆和會計資訊
  • dimgeography，以取得地理詳細數據，包括城市名稱和國家/地區代碼。

使用此數據源進行涉及客戶詳細數據、以時間為基礎的事件和地理位置的查詢和分析。

顯示您可以在哪裡提供 AI 指示的螢幕快照。

提供範例

若要新增範例查詢，請選取 [ 範例查詢] 按鈕，以開啟右側的範例查詢窗格。 此窗格提供為所有支持的數據源新增或編輯範例查詢的選項。 針對每個數據源，您可以選取 [新增或編輯範例查詢] 輸入相關範例，如下列螢幕快照所示：

此螢幕快照顯示您可以在何處新增您提供給 AI 的範例。

在這裡，您應該為您所建立的 Lakehouse 數據源新增範例查詢。

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

顯示新增 SQL 範例的螢幕快照。

備註

Power BI 語意模型數據源目前不支援新增範例查詢/問題組。

測試及修改網狀架構資料代理程式

既然您已設定網狀架構資料代理程式、新增網狀架構資料代理程式指示，並提供資料湖存放庫的範例查詢，您可以藉由詢問問題和接收答案來與其互動。 當您繼續測試時，您可以新增更多範例，並精簡指示，以進一步改善網狀資料代理程式的效能。 與您的同事共同作業以收集意見反應，並根據其輸入，確保提供的範例查詢和指示符合他們想要詢問的問題類型。

發佈網狀架構數據代理程式

驗證網狀架構資料代理程式的效能之後，您可能會決定發佈它，以便與想要對資料進行問答的同事共用。 在此情況下，請選取 [發佈]，如本螢幕擷取畫面所示：

顯示選取 [發佈] 選項的螢幕快照。

發佈資料代理程式視窗隨即開啟，如下列螢幕擷取畫面所示：

顯示發佈數據代理程式功能的螢幕快照。

在此方塊中，選取 [發佈] 以發佈網狀架構資料代理程式。 隨即出現網狀架構資料代理程式的已發佈 URL，如下列螢幕擷取畫面所示：

顯示已發佈URL的螢幕快照。

在 Power BI 中使用 Copilot 中的 Fabric 數據代理程式

您可以在發佈 Fabric 數據代理程序之後，使用 Power BI 中的 Copilot 與 Fabric 數據代理程式互動。 在 Power BI 中使用 Copilot 時，您可以直接取用數據代理程式和其他專案（例如報表或語意模型），而不需要在它們之間切換。

選取左側瀏覽窗格中的 [Copilot ] 按鈕，以在Power BI 中開啟 Copilot。 接下來，在底部的文本框中選取 新增項目以取得更好的結果，以新增數據代理程式。 在開啟的視窗中選取 [數據代理程式 ]。 您只能看到您有權存取的數據代理程式。 選擇您想要的數據代理程式，然後選取 [ 確認]。 此範例示範如何使用單一數據代理程式，但您可以新增更多專案，例如其他數據代理程式、報表或語意模型。 下列螢幕快照說明單一數據代理程式的步驟：

顯示 [Copilot] 按鈕及新增如數據代理程式等項目按鈕的螢幕快照。

既然您已將數據代理程式新增至 Power BI 中的 Copilot，您可以詢問與 Fabric 數據代理程式相關的任何問題，如下列螢幕快照所示：

顯示 Copilot 回答問題的螢幕快照。

以程式設計方式使用網狀架構資料代理程式

您可以在網狀架構筆記本內以程式設計方式使用網狀架構資料代理程式。 若要判斷 Fabric 數據代理程式是否有已發佈的 URL 值，請選取 [ 設定]，如下列螢幕快照所示：

顯示選取 [Fabric 數據代理設定] 的螢幕快照。

發佈 Fabric 數據代理程式之前，它沒有已發佈的 URL 值，如下列螢幕快照所示：

顯示 Fabric 數據代理程式在發行前沒有已發佈 URL 值的螢幕快照。

如果您之前尚未發佈 Fabric 數據代理程式，您可以依照先前步驟中的指示加以發佈。 然後，您可以複製已發佈的網址，並在 Fabric 筆記本中使用該網址。 如此一來，您可以在網狀架構筆記本中呼叫網狀架構資料代理程式 API，以查詢網狀架構資料代理程式。 將此程式碼片段中複製的網址貼上。 然後將問題替換成與您的 Fabric 資料代理程式相關的任意查詢。 此範例使用 \<generic published URL value\> 作為網址。

%pip install "openai==1.70.0"

%pip install httpx==0.27.2

import requests
import json
import pprint
import typing as t
import time
import uuid

from openai import OpenAI
from openai._exceptions import APIStatusError
from openai._models import FinalRequestOptions
from openai._types import Omit
from openai._utils import is_given
from synapse.ml.mlflow import get_mlflow_env_config
from sempy.fabric._token_provider import SynapseTokenProvider
 
base_url = "https://<generic published base URL value>"
question = "What datasources 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
while run.status == "queued" or run.status == "in_progress":
    run = fabric_client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id,
    )
    print(run.status)
    time.sleep(2)

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

相關內容