Kontext für Datenassets abrufen

Der Kontext, der Ihre Daten umgibt, ermöglicht es Ihren KI-Anwendungen, Ihre Datenbestände genau zu verstehen. So werden die Genauigkeit und Relevanz von LLM-generierten Antworten verbessert.

Die Methode lookupContext schließt die Kontextlücke mit einer einzelnen API-Anfrage, um ein vorformatiertes Paket mit Asset-Metadaten abzurufen, das für interaktive Agenten-Workflows optimiert ist. Sie können diesen kompakten, LLM-kompatiblen Kontext verwenden, um Ihren Agenten eine Grundlage für die Bewertung und Nutzung von Daten-Assets zu geben.

Sie können die lookupContext-Methode für alle in Knowledge Catalog gespeicherten Daten-Assets verwenden, z. B. BigQuery-Tabellen, Datasets oder andere Einträge.

Wie können Agenten Datenkontext erhalten?

  1. Der Agent ruft Datenassets ab, die möglicherweise für den Kontextabruf relevant sind, z. B. mithilfe der semantischen Suche im Knowledge Catalog.
  2. Der Agent verwendet die lookupContext-Methode, um einen einzelnen API-Aufruf oder eine MCP-Tool-Anfrage zu stellen, 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 dem format-Parameter, 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.
    Betriebsmetadaten Joins und andere Beziehungen basierend auf Verlaufs-Query-Logs und Datenstatistiken. Weitere Informationen finden Sie unter Datenbeziehungen ansehen.
    Unternehmensbeschreibungen Zugehörige geschäftliche Begriffe, Übersichten, Kataloganmerkungen, Beschreibungen, die im Quellsystem erfasst und automatisch im Knowledge Catalog generiert werden, und Richtlinien.

    Hinweis: Mit dem Richtlinienaspekt für Daten-Assets können Sie zusätzlichen Kontext erfassen, der für Kundenservicemitarbeiter nützlich ist, wenn sie Daten-Assets ermitteln, prüfen oder verwenden.
    Datenprofil Verteilungsstatistiken, Anzahl eindeutiger Werte, Nullverhältnisse und Stichprobenwerte.
    Datenqualität Automatisierte Datenqualitätsprüfung anhand vordefinierter Regeln.
    Kontext zu verknüpften Datenassets Kontext zu verknüpften Daten-Assets, z. B. Glossarbegriffe oder andere verknüpfte Assets wie häufig zusammengeführte 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 lookupContext-Methode verwenden, müssen Sie die erforderlichen Rollen haben und die erforderlichen APIs aktivieren.

Erforderliche Rollen

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

  • Lesezugriff auf Katalogressourcen, einschließlich Einträgen, Eintragsgruppen und Glossaren: 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

Wenn Sie die Methode lookupContext verwenden möchten, aktivieren Sie die folgenden APIs in Ihrem Projekt:

  • Knowledge Catalog API

Rollen, die zum Aktivieren von APIs erforderlich sind

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

Um den Kontext für ein Daten-Asset abzurufen, greifen Sie direkt mit der Dataplex API auf die Methode lookupContext zu oder verwenden Sie den Remote-MCP-Server (Model Context Protocol) für den Knowledge Catalog oder die MCP Toolbox For Databases.

Die Methode lookupContext filtert die Ressourcen basierend auf Ihren 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

Wenn Sie den Kontext für ein Daten-Asset abrufen möchten, senden Sie die folgende Anfrage:

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 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 festlegen, gibt die API alle Schemafelder unabhängig vom Wert von context_budget zurück.

Eine Beispielanfrage zum Abrufen von Kontext für eine BigQuery-Tabelle 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 in 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

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python in der Knowledge Catalog-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Knowledge Catalog Python API.

Richten Sie zur Authentifizierung bei Knowledge Catalog die Standardanmeldedaten für Anwendungen 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}")

Was sind einige Best Practices für Kontext-Lookups?

Beachten Sie die folgenden Best Practices, um Ihre Ergebnisse bei Verwendung der lookupContext-Methode 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 Ausgabe anzupassen, wobei die durch den Parameter vorgegebenen Grenzen eingehalten werden.
  • Sie können bis zu zehn Daten-Assets in der Liste resources auflisten. Wenn Sie beispielsweise mehrere Tabellen in die Liste resources aufnehmen, stellt die API nicht nur den Kontext für diese Tabellen, sondern auch für mögliche Join-Pfade zwischen ihnen bereit. So erhalten Sie die erforderlichen Informationen dazu, wie Sie diese Tabellen zusammen verwenden können.
  • Verwenden Sie die Option format, z. B. yaml oder json, die am besten zur Parsing-Logik des LLM oder des Agents passt, um kostspielige Transformationen zu vermeiden.

Nächste Schritte