Contoh agen pengelola data Fabric dengan kumpulan data AdventureWorks (pratinjau)

Artikel ini memperlihatkan cara menyiapkan agen data di Microsoft Fabric menggunakan lakehouse sebagai sumber data contoh. Kami pertama-tama membuat dan mengisi lakehouse, lalu membuat agen data Fabric dan menambahkan lakehouse ke dalamnya. Jika Anda sudah memiliki model semantik Power BI (dengan izin baca/tulis yang diperlukan), gudang, database KQL, atau ontologi, ikuti langkah yang sama dan pilih sumber tersebut sebagai gantinya. Meskipun panduan ini menggunakan lakehouse, polanya sama untuk sumber lain—pemilihan sumber data saja yang berbeda.

Penting

Fitur ini sedang dalam tahap pratinjau.

Prasyarat

Kapasitas F2 berbayar atau Fabric yang lebih tinggi, atau kapasitas Power BI Premium per kapasitas (P1 atau lebih tinggi) dengan Microsoft Fabric diaktifkan
Pengaturan tenant agen data Fabric aktif.
Pemrosesan lintas geografis untuk kecerdasan buatan diaktifkan.
Penyimpanan lintas geo untuk AI diaktifkan.
Setidaknya salah satu dari ini, dengan data: Gudang, lakehouse, satu atau beberapa model semantik Power BI, database KQL, atau ontologi.
Model semantik Power BI melalui pengalihan penyewa pada titik akhir XMLA diaktifkan untuk sumber data model semantik Power BI.

Penting

Pastikan pengalaman Copilot mandiri diaktifkan di portal admin Power BI (Pengaturan Tenant > Pengalaman Copilot Mandiri >). Jika belum diaktifkan, Anda tidak akan dapat menggunakan agen data dalam skenario Copilot, walaupun pengaturan tenant Copilot lainnya aktif. Untuk informasi lebih lanjut, lihat Copilot di pengaturan penyewa Power BI.

Membangun lakehouse dengan AdventureWorksLH

Pertama, buat lakehouse dan isi dengan data yang diperlukan.

Jika Anda sudah memiliki salinan AdventureWorksLH di lakehouse atau di gudang, Anda dapat melewati tahap ini. Jika tidak, Anda dapat menggunakan instruksi berikut dari notebook Fabric untuk mengisi lakehouse dengan data tersebut.

Buat buku catatan baru di ruang kerja tempat Anda ingin membuat agen data Fabric Anda.
Di sisi kiri panel Explorer, pilih + Sumber data. Opsi ini memungkinkan Anda menambahkan lakehouse yang ada atau membuat lakehouse baru. Demi kejelasan, buat lakehouse baru dan tetapkan nama untuk itu.

Di sel atas, tambahkan cuplikan kode berikut:

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)

Pilih Jalankan Semua.

Setelah beberapa menit, lakehouse terisi dengan data yang diperlukan.

Perhatian

Notebook yang terus berjalan (misalnya, karena perulangan tak terbatas yang tidak disengaja atau polling konstan) dapat mengonsumsi kapasitas Fabric tanpa batas waktu. Setelah data selesai dimuat, hentikan sel aktif apa pun dan akhiri sesi buku catatan (Toolbar Buku Catatan > Hentikan sesi) jika Anda tidak lagi membutuhkannya. Hindari menambahkan perulangan jangka panjang tanpa batas waktu.

Membuat agen data Fabric

Untuk membuat agen data Fabric baru, buka ruang kerja Anda dan pilih tombol + Item Baru, seperti yang ditunjukkan pada cuplikan layar ini.

Cuplikan layar menunjukkan di mana membuat agen data Fabric.

Di tab Semua item, cari agen data Fabric untuk menemukan opsi yang sesuai. Setelah dipilih, permintaan meminta Anda untuk memberikan nama untuk agen data Fabric Anda, seperti yang ditunjukkan dalam cuplikan layar ini:

Setelah Anda memasukkan nama, lanjutkan dengan langkah-langkah berikut untuk menyelaraskan agen data Fabric dengan persyaratan spesifik Anda.

Pilih data

Pilih lakehouse yang Anda buat di langkah sebelumnya, lalu pilih Tambahkan, seperti yang ditunjukkan pada cuplikan layar berikut:

Setelah lakehouse ditambahkan sebagai sumber data, panel Explorer di sisi kiri halaman agen data Fabric menampilkan nama lakehouse. Pilih Lakehouse untuk melihat semua tabel yang tersedia. Gunakan kotak centang untuk memilih tabel yang ingin Anda sediakan untuk AI. Untuk skenario ini, pilih tabel ini:

dimcustomer
dimdate
dimgeography
dimproduct
dimproductcategory
dimpromotion
dimreseller
dimsalesterritory
factinternetsales
factresellersales

Berikan instruksi

Untuk menambahkan instruksi, pilih tombol Instruksi agen data untuk membuka panel instruksi di sebelah kanan. Anda dapat menambahkan instruksi berikut.

Sumber data AdventureWorksLH berisi informasi dari tiga tabel:

dimcustomer, untuk demografi pelanggan terperinci dan informasi kontak
dimdate, untuk data terkait tanggal - misalnya, informasi kalender dan fiskal
dimgeography, untuk detail geografis termasuk nama kota dan kode wilayah negara.

Gunakan sumber data ini untuk kueri dan analisis yang melibatkan detail pelanggan, peristiwa berbasis waktu, dan lokasi geografis.

Berikan contoh

Untuk menambahkan kueri contoh, pilih tombol Kueri Contoh untuk membuka panel kueri contoh di sebelah kanan. Panel ini menyediakan opsi untuk menambahkan atau mengedit contoh kueri untuk semua sumber data yang didukung. Untuk setiap sumber data, Anda dapat memilih Menambahkan atau Mengedit Contoh Kueri untuk memasukkan contoh yang relevan, seperti yang ditunjukkan pada cuplikan layar berikut:

Di sini, Anda harus menambahkan contoh kueri untuk sumber data lakehouse yang Anda buat.

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

Menambahkan contoh pasangan kueri/pertanyaan saat ini tidak didukung untuk sumber data model semantik Power BI.

Menguji dan merevisi agen data Fabric

Sekarang setelah Anda mengonfigurasi agen data Fabric, menambahkan instruksi agen data Fabric, dan memberikan contoh kueri untuk lakehouse, Anda dapat berinteraksi dengannya dengan mengajukan pertanyaan dan menerima jawaban. Saat melanjutkan pengujian, Anda dapat menambahkan lebih banyak contoh, dan menyempurnakan instruksi, untuk lebih meningkatkan performa agen data Fabric. Berkolaborasi dengan kolega Anda untuk mengumpulkan umpan balik, dan berdasarkan input mereka, pastikan contoh kueri dan instruksi yang disediakan selaras dengan jenis pertanyaan yang ingin mereka tanyakan.

Menerbitkan agen data dari Fabric

Setelah memvalidasi kinerja agen data Fabric, Anda dapat memutuskan untuk menerbitkannya agar dapat dibagikan dengan kolega Anda yang ingin melakukan tanya jawab berbasis data. Dalam hal ini, pilih Terbitkan, seperti yang ditunjukkan dalam cuplikan layar ini:

Kotak Terbitkan agen data terbuka, seperti yang ditunjukkan pada cuplikan layar ini:

Dalam kotak ini, pilih Terbitkan untuk menerbitkan agen data Fabric. URL yang diterbitkan untuk agen data Fabric muncul, seperti yang ditunjukkan pada cuplikan layar ini:

Menggunakan agen data Fabric di Copilot di Power BI

Anda bisa menggunakan Copilot di Power BI untuk berinteraksi dengan agen data Fabric setelah Anda menerbitkannya. Dengan Copilot di Power BI, Anda dapat langsung menggunakan agen data dan item lain (misalnya, laporan, atau model semantik) tanpa perlu beralih di antara mereka.

Pilih tombol Copilot di panel navigasi kiri, untuk membuka Copilot di Power BI. Selanjutnya, pilih Tambahkan item untuk hasil yang lebih baik di kotak teks di bagian bawah, untuk menambahkan agen data. Pilih Agen data di jendela yang terbuka. Anda hanya dapat melihat agen data yang Anda memiliki izin untuk mengaksesnya. Pilih agen data yang Anda inginkan dan pilih Konfirmasi. Contoh ini menunjukkan cara bekerja dengan satu agen data, tetapi Anda dapat menambahkan lebih banyak item - misalnya, agen data, laporan, atau model semantik lainnya. Cuplikan layar berikut mengilustrasikan langkah-langkah dengan satu agen data:

Sekarang setelah Anda menambahkan agen data ke Copilot di Power BI, Anda bisa mengajukan pertanyaan apa pun yang terkait dengan agen data Fabric Anda, seperti yang diperlihatkan dalam cuplikan layar berikut:

Menggunakan agen data Fabric secara terprogram

Anda dapat menggunakan agen data Fabric secara terprogram dalam notebook Fabric. Untuk menentukan apakah agen data Fabric memiliki nilai URL yang diterbitkan atau tidak, pilih Pengaturan, seperti yang ditunjukkan pada cuplikan layar berikut:

Cuplikan layar memperlihatkan pemilihan pengaturan agen data Fabric.

Sebelum Anda menerbitkan agen data Fabric, agen data tersebut tidak memiliki nilai URL yang diterbitkan, seperti yang ditunjukkan pada cuplikan layar berikut:

Jika Anda belum menerbitkan agen data Fabric sebelumnya, Anda dapat menerbitkannya mengikuti instruksi di langkah-langkah sebelumnya. Anda kemudian dapat menyalin URL yang diterbitkan dan menggunakannya di notebook Fabric. Dengan cara ini, Anda dapat mengkueri agen data Fabric dengan melakukan panggilan ke API agen data Fabric di notebook Fabric. Tempelkan URL yang disalin dalam cuplikan kode ini. Kemudian, ganti pertanyaan dengan kueri apa pun yang relevan dengan agen data Fabric Anda. Contoh ini menggunakan \<generic published URL value\> sebagai URL.

Penting

Saat memanggil agen data secara terprogram, terapkan:

Batas waktu polling (lihat contoh di bawah) untuk menghindari perulangan yang tidak terbatas.
Frekuensi polling minimal (mulai dari 2–5 detik; tingkatkan hanya jika diperlukan).
Proses pembersihan benang atau sumber daya yang dibuat setelah selesai.
Penutupan sesi notebook setelah selesai untuk membebaskan kapasitas Fabric.

Nota

Sesuaikan pin versi (openai, synapseml, pandas, tqdm) ke versi tervalidasi terbaru untuk runtime Fabric Anda jika versi yang tepat ini menjadi kedaluarsa.

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

Konsep agen data Fabric
Membuat agen data Fabric

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-06

Bagikan melalui

Contoh agen pengelola data Fabric dengan kumpulan data AdventureWorks (pratinjau)

Prasyarat

Membangun lakehouse dengan AdventureWorksLH

Membuat agen data Fabric

Pilih data

Berikan instruksi

Berikan contoh

Menguji dan merevisi agen data Fabric

Menerbitkan agen data dari Fabric

Menggunakan agen data Fabric di Copilot di Power BI

Menggunakan agen data Fabric secara terprogram

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: