Kontext für Datenassets abrufen

Der Kontext Ihrer Daten versetzt Ihre KI-Anwendungen in die Lage, Ihre Datenassets umfassend zu verstehen. Dadurch werden die Genauigkeit und Relevanz von LLM-generierten Antworten verbessert.

Die Methode lookupContext schließt die Kontextlücke mit einer einzigen API-Anfrage, um ein vorformatiertes Paket mit Asset-Metadaten abzurufen, das für interaktive Agenten-Workflows optimiert ist. Mit diesem kompakten, LLM-fähigen Kontext können Sie Ihre Agenten bei der Bewertung und Verwendung von Datenassets unterstützen.

Sie können die Methode lookupContext für alle Datenassets verwenden, die in Knowledge Catalog gespeichert sind, z. B. BigQuery-Tabellen, Datasets und Routinen sowie Datendomains und alle anderen Einträge.

Wie erhalten Agenten Datenkontext?

  1. Der Agent ruft Datenassets ab, die für den Kontextabruf potenziell relevant sind, z. B. mithilfe der semantischen Suche in Knowledge Catalog.
  2. Der Agent verwendet die Methode lookupContext, um einen einzelnen API-Aufruf oder eine MCP-Tool-Anfrage zu senden, mit der der Kontext für ein bestimmtes Asset abgerufen wird.

  3. Die Methode gibt eine Antwort mit einem vorformatierten Textblock zurück. Je nach Parameter format, den Sie in der Anfrage angeben, kann das Dokument im YAML-, XML- oder JSON-Format vorliegen.

    Die Antwort enthält die folgenden Kontextelemente:

    Kontextelement Beschreibung
    Technische Metadaten Ressourcenschemas und physische Konfigurationen wie BigQuery-Partitionierungs- und Clustering-Strategien sowie BigQuery-Routinendefinitionen, einschließlich Argumenten, Rückgabetypen und Quellcode.
    Betriebliche Metadaten Verknüpfungen und andere Beziehungen, basierend auf Protokollen mit Abfrageverlauf und Dateneinblicken. Weitere Informationen finden Sie unter Datenbeziehungen ansehen.
    Unternehmensbeschreibungen Verwandte Geschäftsbegriffe, Übersichten, Kataloganmerkungen, Beschreibungen, die im Quellsystem erfasst und automatisch in Knowledge Catalog generiert wurden, sowie Richtlinien.

    Hinweis: Sie können den Aspekt „Richtlinien“ für Datenassets verwenden, um zusätzlichen Kontext zu erfassen, der für Agenten nützlich ist, wenn sie Datenassets suchen, prüfen oder verwenden.
    Datenprofil Verteilungsstatistiken, Anzahl eindeutiger Werte, Nullverhältnisse und Beispielwerte.
    Datenqualität Ausgaben der automatischen Datenqualitätsprüfung anhand vordefinierter Regeln.
    Kontext zu verknüpften Datenassets Kontext zu verknüpften Datenassets, z. B. Glossarbegriffe oder andere verknüpfte Assets wie häufig verknüpfte Tabellen. Der für verknüpfte Assets zurückgegebene Kontext umfasst dieselbe Bandbreite an Elementen wie für das Hauptasset oder die Hauptassets.

  4. Der Agent verwendet diese Antwort, um die Auswahl relevanter Assets oder deren Verwendung zu steuern.

Hinweis

Bevor Sie die Methode lookupContext verwenden, prüfen Sie, ob Sie die erforderlichen Rollen haben, und aktivieren Sie die erforderlichen APIs.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Google Cloud Projekt iam.gserviceaccount.comzuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen der lookupContext Methode benötigen:

  • Lesezugriff auf Katalogressourcen, einschließlich Einträge, Eintragsgruppen und Glossare: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

APIs aktivieren

Aktivieren Sie die folgenden APIs in Ihrem Projekt, um die Methode lookupContext zu verwenden:

  • Knowledge Catalog API

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.

API aktivieren

Kontext für ein Datenasset abrufen

Wenn Sie den Kontext für ein Datenasset abrufen möchten, greifen Sie direkt mit der Dataplex API auf die Methode lookupContext zu oder verwenden Sie den Remote-MCP-Server (Model Context Protocol) von Knowledge Catalog oder die MCP Toolbox For Databases.

Die Methode lookupContext filtert die Ressourcen anhand Ihrer Berechtigungen. Die Antwort enthält nur Daten für Assets, für die Ihre Identität die erforderlichen IAM-Berechtigungen (Identity and Access Management) hat. Wenn Sie keine Berechtigungen für die angeforderten Ressourcen haben, gibt die Methode eine leere Antwort zurück.

REST

Senden Sie die folgende Anfrage, um den Kontext für ein Datenasset abzurufen:

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID Ihres Google Cloud Projekts
  • LOCATION: die Region, in der sich das Asset befindet, z. B. us-central1
  • RESOURCES: bis zu zehn Eintragsnamen, für die der Kontext abgerufen werden soll, formatiert als projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Bei mehreren Ressourcen stellt die API Beziehungen zwischen den angeforderten Ressourcen her, z. B. häufige Schemaverknüpfungen, und gibt die Beziehungsinformationen im Kontext zurück.
  • OPTIONS: die Optionen, mit denen Sie den Kontext definieren können:
    • format ist das Format der Kontextdatei. Beispiel: yaml.
    • context_budget ist die Anzahl der Zeichen, auf die die Antwort begrenzt ist. Wenn Sie den Parameter all_schema_fields auf true setzen, gibt die API alle Schemafelder unabhängig vom Wert von context_budget zurück.

Eine Beispielanfrage, die den Kontext für eine BigQuery-Tabelle abruft, sieht so aus:

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

Die Antwort ist ein vorformatierter Textblock, der etwa so aussieht:

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

Folgen Sie der Python Einrichtungsanleitung in der Knowledge Catalog-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der API-ReferenzdokumentationPython für Knowledge Catalog.

Richten Sie zur Authentifizierung bei Knowledge Catalog die Standardanmeldedaten für Anwendungen (ADC) ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

Das folgende Beispiel zeigt, wie Sie den Kontext für eine BigQuery-Tabelle abrufen:

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

Kontext für Routinen abrufen

Sie können die Methode lookupContext verwenden, um den Kontext für BigQuery-Routinen abzurufen, z. B. benutzerdefinierte Funktionen, Tabellenfunktionen und gespeicherte Prozeduren. Agenten können diesen Kontext verwenden, um zu verstehen, was eine Routine tut und wie sie aufgerufen wird, z. B. wenn sie SQL-Abfragen generieren. Der Kontext für eine Routine enthält die folgenden Informationen:

  • Der Routinetyp, z. B. Skalarfunktion, Tabellenfunktion oder Prozedur.
  • Die Routinesprache.
  • Die Routineargumente und der Rückgabetyp.
  • Der Quellcode der Routine (Definitionstext).
  • Beschreibungen und andere Metadaten aus Knowledge Catalog.

Wenn Sie den Kontext für eine Routine abrufen möchten, fügen Sie den Eintragsnamen der Routine in die resources Liste der Anfrage ein. Der Eintragsname hat folgendes Format:

projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des Projekts, das die Routine enthält.
  • LOCATION: der Standort des Datasets, das die Routine enthält, z. B. us.
  • DATASET_ID: die ID des Datasets, das die Routine enthält.
  • ROUTINE_ID: die ID der Routine.

Was sind einige Best Practices für Kontextabfragen?

Berücksichtigen Sie die folgenden Best Practices, um Ihre Ergebnisse bei der Verwendung der Methode lookupContext zu optimieren:

  • Fordern Sie die ausgewählte Länge des Ausgabekontexts mit dem Parameter context_budget an. Die Methode lookupContext versucht, den relevantesten Kontext so nah wie möglich an die durch den Parameter vorgegebenen Grenzen in die Ausgabe einzufügen.
  • Sie können bis zu zehn Datenassets in der Liste resources auflisten. Wenn Sie beispielsweise mehrere Tabellen in die Liste resources aufnehmen, stellt die API den Kontext nicht nur für diese Tabellen, sondern auch für mögliche Verknüpfungspfade zwischen ihnen bereit. So erhalten Sie die notwendigen Informationen zur gemeinsamen Verwendung dieser Tabellen.
  • Verwenden Sie die Option format, z. B. yaml oder json, die am besten zur Parsing-Logik des LLM oder Agenten passt, um kostspielige Transformationen zu vermeiden.

Nächste Schritte