Kontext für Datenassets abrufen

Der Kontext, der Ihre Daten umgibt, vermittelt Ihren KI-Anwendungen ein tiefes Verständnis Ihrer Datenassets und verbessert so die Genauigkeit und Relevanz von LLM-generierten Antworten.

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 oder andere Einträge.

Kontext für ein Asset mit der Methode lookupContext abrufen

  1. Der Agent ruft Datenassets ab, die für den Kontextabruf potenziell relevant sind, z. B. mit der semantischen Suche von 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.
    Betriebliche Metadaten Verknüpfungen und andere Beziehungen, basierend auf Protokollen mit Abfrageverlauf und Data Insights. Weitere Informationen finden Sie unter Datenbeziehungen ansehen.
    Unternehmensbeschreibungen Verwandte Geschäftsbegriffe, Übersichten, Kataloganmerkungen, Beschreibungen, die im Quellsystem erfasst und in Knowledge Catalog automatisch 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 wie Glossarbegriffen oder anderen verknüpften Assets wie häufig verknüpften Tabellen. Der für verknüpfte Assets zurückgegebene Kontext umfasst dieselben Elemente wie für das Haupt-Asset oder die Haupt-Assets.

  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 die erforderlichen APIs aktiviert sind.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Google Cloud Projekt iam.gserviceaccount.comzuzuweisen, damit Sie die Berechtigungen zum Aufrufen der lookupContext Methode haben:

  • 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 IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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, mit der der Kontext für eine BigQuery-Tabelle abgerufen wird, 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 dem folgenden ähnelt:

{
"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 Kurzanleitung zu Knowledge Catalog mit Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Knowledge Catalog Python API.

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}")

Best Practices für die Methode lookupContext

Beachten 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 Grenzwerte 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