Παράγοντας δεδομένων Fabric Python SDK (προεπισκόπηση)

Το Python SDK του παράγοντα δεδομένων Fabric παρέχει πρόσβαση μέσω προγραμματισμού σε αντικείμενα σχεδίασης του παράγοντα δεδομένων Fabric. Έχει σχεδιαστεί για χρήστες που δίνουν προτεραιότητα στον κώδικα και θέλουν να δημιουργήσουν, να ρυθμίσουν τις παραμέτρους τους, να ενημερώσουν και να δημοσιεύσουν παράγοντες δεδομένων χωρίς να χρησιμοποιήσουν την πύλη Fabric. Μπορείτε να εκτελέσετε το SDK μέσα σε ένα σημειωματάριο Microsoft Fabric ή από το δικό σας περιβάλλον μετά τον έλεγχο ταυτότητας στο Fabric.

Σημαντικό

Το SDK Fabric Data Agent μεταβαίνει από το OpenAI Assistants API στο OpenAI Responses API για την υποβολή ερωτημάτων σε πράκτορες δεδομένων. Εάν υποβάλετε ερώτημα σε έναν παράγοντα δεδομένων με το πρόγραμμα-πελάτη Fabric OpenAI, μπορείτε να ξεκινήσετε τη μετεγκατάσταση στο πρόγραμμα-πελάτη Fabric OpenAI Responses από τις 11 Αυγούστου 2026 πριν τεθεί σε ισχύ η απόσυρση του API βοηθών στις 26 Αυγούστου 2026. Μόνο οι αλλαγές στον κώδικα ερωτήματος—η δημιουργία, η ρύθμιση παραμέτρων και η δημοσίευση παραγόντων δεδομένων παραμένουν οι ίδιες. Για βήματα μετεγκατάστασης και ένα παράδειγμα με δυνατότητα εκτέλεσης, ανατρέξτε στο δείγμα σημειωματαρίου API αποκρίσεων.

Σημαντικό

Αυτή η δυνατότητα είναι σε προεπισκόπηση.

Επίπεδο διαχείρισης και χρόνος εκτέλεσης

Το SDK είναι ένα εργαλείο επιπέδου διαχείρισης. Χρησιμοποιήστε το για να διαχειριστείτε τον κύκλο ζωής ενός πράκτορα δεδομένων: δημιουργήστε το τεχνούργημα, προσθέστε και ρυθμίστε τις παραμέτρους προελεύσεων δεδομένων, ορίστε οδηγίες και παραδείγματα ερωτημάτων και δημοσιεύστε. Εκτελείται στο Fabric public REST API, το οποίο είναι η ίδια επιφάνεια που χρησιμοποιείτε ήδη για άλλους χώρους εργασίας και στοιχεία, επομένως ο έλεγχος ταυτότητας και τα μοτίβα αίτησης είναι τα ίδια.

Το επίπεδο διαχείρισης είναι ξεχωριστό από τον τρόπο με τον οποίο υποβάλλετε ερώτημα στον παράγοντα δεδομένων κατά τον χρόνο εκτέλεσης. Αφού δημοσιεύσετε έναν παράγοντα δεδομένων, υποβάλετε ερώτημα μέσω του τελικού σημείου Model Context Protocol (MCP) από εργαλεία, εφαρμογές και άλλες εμπειρίες παράγοντα. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Παράγοντας δεδομένων ως διακομιστής πρωτοκόλλου περιβάλλοντος μοντέλου.

Prerequisites

  • Ένας χώρος εργασίας Fabric με εκχωρημένους πόρους που υποστηρίζουν πράκτορες δεδομένων.
  • Μια υποστηριζόμενη προέλευση δεδομένων στον χώρο εργασίας, όπως μια λίμνη, μια αποθήκη, ένα σημασιολογικό μοντέλο Power BI ή μια βάση δεδομένων KQL.
  • Python 3.10 ή νεότερη έκδοση.
  • Για εκτέλεση εκτός σημειωματαρίου Fabric, ένας τρόπος ελέγχου ταυτότητας στο Fabric, όπως το Azure CLI ή μια κύρια υπηρεσία.

Installation

Το SDK δημοσιεύεται στο PyPI ως fabric-data-agent-sdk. Εγκαταστήστε το χρησιμοποιώντας το pip:

%pip install fabric-data-agent-sdk

Έλεγχος ταυτότητας στο Fabric

Όταν εκτελείτε το SDK μέσα σε ένα σημειωματάριο Fabric, το σημειωματάριο χειρίζεται τον έλεγχο ταυτότητας για εσάς.

Όταν εκτελείτε το SDK εκτός του Fabric, συνδεθείτε πρώτα στο Fabric. Το παρακάτω παράδειγμα συνδέεται με τα διαπιστευτήρια Azure CLI και τα ορίζει ως προεπιλογή για την περίοδο λειτουργίας. Μπορείτε να χρησιμοποιήσετε είτε έναν λογαριασμό χρήστη είτε μια κύρια υπηρεσία.

from azure.identity import AzureCliCredential
from fabric.analytics.environment.credentials import (
    SetFabricAnalyticsDefaultTokenCredentialsGlobally,
)

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Σημείωση

Ο λογαριασμός ή η κύρια υπηρεσία με την οποία πραγματοποιείτε έλεγχο ταυτότητας πρέπει να έχει δικαίωμα δημιουργίας και διαχείρισης στοιχείων στον χώρο εργασίας προορισμού.

Δημιουργία παράγοντα δεδομένων

Δημιουργήστε έναν παράγοντα δεδομένων σε έναν χώρο εργασίας. Αντικαταστήστε το αναγνωριστικό χώρου εργασίας με το αναγνωριστικό του χώρου εργασίας όπου υπάρχει ο παράγοντας δεδομένων.

from fabric.dataagent.client import create_data_agent

workspace_id = "<your-workspace-id>"

agent = create_data_agent(
    data_agent_name="Quickstart data agent",
    workspace_id=workspace_id,
)

Ρύθμιση παραμέτρων του παράγοντα δεδομένων και προσθήκη προελεύσεων δεδομένων

Ορίστε τις οδηγίες του παράγοντα και, στη συνέχεια, προσθέστε μια προέλευση δεδομένων. Χρησιμοποιήστε το αναγνωριστικό τεχνουργήματος μιας υπάρχουσας βάσης δεδομένων lakehouse, αποθήκης, σημασιολογικού μοντέλου ή KQL.

agent_instructions = "<your agent instructions>"
datasource_id = "<your-datasource-id>"

agent.update_settings(ai_instructions=agent_instructions)

agent.add_staging_datasource(
    artifact_name_or_id=datasource_id,
    workspace_id_or_name=workspace_id,
)

Μπορείτε επίσης να προσθέσετε οδηγίες προέλευσης δεδομένων και παραδείγματα ερωτημάτων για να βελτιώσετε την ποιότητα των απαντήσεων του εκπροσώπου δεδομένων. Για να μάθετε περισσότερα, ανατρέξτε στα δείγματα SDK παράγοντα δεδομένων Fabric στο GitHub.

Δημοσίευση του παράγοντα δεδομένων

Δημοσιεύστε την προετοιμασμένη ρύθμιση παραμέτρων για να κάνετε τον παράγοντα δεδομένων διαθέσιμο για υποβολή ερωτημάτων.

agent.publish_staging(description="Initial publish")

Σημείωση

Η δημοσίευση μέσω του SDK λειτουργεί εντός και εκτός του Fabric. Η δημοσίευση ενός παράγοντα δεδομένων στο Microsoft 365 Copilot δεν χρησιμοποιεί ακόμα το δημόσιο API, επομένως εξακολουθείτε να το κάνετε μέσα από το Fabric, είτε στην πύλη είτε εκτελώντας το SDK σε ένα σημειωματάριο Fabric.

Υποβολή ερωτήματος σε δημοσιευμένο παράγοντα δεδομένων

Αφού δημοσιεύσετε τον παράγοντα δεδομένων, υποβάλετε ερώτημα μέσω του τελικού σημείου MCP. Το τελικό σημείο MCP είναι η επιφάνεια χρόνου εκτέλεσης και κατανάλωσης για τον πράκτορα δεδομένων. Μπορείτε να συνδεθείτε σε αυτό από εργαλεία, εφαρμογές και άλλους πράκτορες για να υποβάλετε ερωτήματα στον πράκτορα δεδομένων, να κάνετε ερωτήσεις και να λάβετε απαντήσεις. Για τα βήματα εγκατάστασης και τους υποστηριζόμενους υπολογιστές-πελάτες, ανατρέξτε στην ενότητα Παράγοντας δεδομένων ως διακομιστής πρωτοκόλλου περιβάλλοντος μοντέλου.

Σημαντικό

Ο παράγοντας δεδομένων λειτουργεί ως διακομιστής MCP μόνο αφού τον δημοσιεύσετε. Εάν δεν δημοσιεύσετε τον παράγοντα δεδομένων, το τελικό σημείο MCP δεν λειτουργεί.

Λήψη της διεύθυνσης URL τελικού σημείου

Μπορείτε να λάβετε τη διεύθυνση URL τελικού σημείου MCP με δύο τρόπους:

  • Αντιγράψτε το από τις ρυθμίσεις του παράγοντα δεδομένων. Αφού δημοσιεύσετε τον παράγοντα δεδομένων, ανοίξτε την καρτέλα Model Context Protocol στις ρυθμίσεις του παράγοντα και αντιγράψτε τη διεύθυνση URL του διακομιστή MCP. Για λεπτομέρειες, ανατρέξτε στην ενότητα Παράγοντας δεδομένων ως διακομιστής πρωτοκόλλου περιβάλλοντος μοντέλου.

  • Κατασκευάστε το χειροκίνητα. Δημιουργήστε τη διεύθυνση URL από το αναγνωριστικό χώρου εργασίας και το αναγνωριστικό παράγοντα δεδομένων (τεχνούργημα) χρησιμοποιώντας την ακόλουθη μορφή:

    https://api.fabric.microsoft.com/v1/mcp/workspaces/{WorkspaceId}/dataagents/{DataAgentId}/agent

    Αντικαταστήστε τα σύμβολα κράτησης θέσης με τιμές από τον δημοσιευμένο παράγοντα δεδομένων:

    Σύμβολο κράτησης θέσης Περιγραφή
    {WorkspaceId} Το αναγνωριστικό του χώρου εργασίας Fabric που περιέχει τον παράγοντα δεδομένων.
    {DataAgentId} Το αναγνωριστικό του δημοσιευμένου παράγοντα δεδομένων.

    Μια μη αυτόματα δημιουργημένη διεύθυνση URL λειτουργεί μόνο μετά τη δημοσίευση του παράγοντα δεδομένων. Εάν ο παράγοντας δεδομένων δεν έχει δημοσιευτεί, το τελικό σημείο επιστρέφει ένα σφάλμα ακόμα και όταν η διεύθυνση URL είναι σωστή.

Έλεγχος ταυτότητας

Οι αιτήσεις για το τελικό σημείο MCP πρέπει να ελέγχονται σε σχέση με το Fabric. Βεβαιωθείτε ότι ο πελάτης σας περιλαμβάνει ένα έγκυρο διακριτικό κομιστή με δικαιώματα πρόσβασης στον χώρο εργασίας προορισμού και τον παράγοντα δεδομένων. Το διακριτικό μπορεί να αντιπροσωπεύει είτε μια ταυτότητα χρήστη είτε μια κύρια υπηρεσία (SPN).

Διαθέσιμα εργαλεία

Ο παράγοντας δεδομένων Fabric εκθέτει έναν διακομιστή MCP που παρέχει ένα μόνο εργαλείο. Οι πελάτες καλούν αυτό το εργαλείο για να στείλουν μια ερώτηση στον πράκτορα δεδομένων και να λάβουν την απάντηση που δημιουργήθηκε.

Υποβολή ερωτήματος στον πράκτορα δεδομένων από την Python

Το παρακάτω παράδειγμα συνδέεται με το τελικό σημείο MCP, ανακαλύπτει το εργαλείο, στέλνει μια ερώτηση και εκτυπώνει την απάντηση. Επαναχρησιμοποιεί το credential βήμα από τον έλεγχο ταυτότητας στο Fabric και χρησιμοποιεί το MCP Python SDK. Εγκαταστήστε πρώτα το SDK:

%pip install mcp

import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

workspace_id = "<your-workspace-id>"
data_agent_id = "<your-data-agent-id>"
question = "<your question>"

mcp_url = (
    f"https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspace_id}"
    f"/dataagents/{data_agent_id}/agent"
)


def get_auth_headers():
    token = credential.get_token("https://api.fabric.microsoft.com/.default")
    return {"Authorization": f"Bearer {token.token}"}


async def query_data_agent(question):
    headers = get_auth_headers()

    async with streamablehttp_client(mcp_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # The data agent exposes a single tool. Discover it, then call it.
            tools = await session.list_tools()
            tool = tools.tools[0]
            question_arg = next(iter(tool.inputSchema["properties"]))

            result = await session.call_tool(tool.name, {question_arg: question})

            answers = [block.text for block in result.content if block.type == "text"]
            return "\n".join(answers)


answer = asyncio.run(query_data_agent(question))
print(answer)

Σχετικό περιεχόμενο

  • Last updated on