Kontext für Datenassets abrufen

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

Die Methode lookupContext schließt die Kontextlücke mit einer einzigen API-Anfrage, um ein vorformatiertes Bundle von Asset-Metadaten abzurufen, das für interaktive agentische Workflows optimiert ist. Sie können diesen kompakten, LLM-fähigen Kontext verwenden, um Ihre Agenten bei der Bewertung und Verwendung von Daten-Assets zu fundieren.

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

Wie können KI-Agenten Datenkontext erhalten?

  1. Der Agent ruft Daten-Assets ab, die für den Kontextabruf potenziell relevant sind, z. B. mithilfe der semantischen Suche im Knowledge Catalog.
  2. Der Agent verwendet die Methode lookupContext, um einen einzelnen API-Aufruf oder eine MCP-Toolanfrage 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 dem in der Anfrage angegebenen Parameter format 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, z. B. BigQuery-Partitionierungs- und Clustering-Strategien, sowie BigQuery-Routinedefinitionen, einschließlich Argumenten, Rückgabetypen und Quellcode.
    Betriebsmetadaten Joins und andere Beziehungen, basierend auf historischen Abfrageprotokollen und Dateneinblicken. Weitere Informationen finden Sie unter Datenbeziehungen ansehen.
    Unternehmensbeschreibungen Zugehörige Geschäftsbedingungen, Übersichten, Kataloganmerkungen, Beschreibungen, die im Quellsystem erfasst und automatisch in Knowledge Catalog generiert wurden, sowie Richtlinien.

    Hinweis: Sie können den Richtlinienaspekt für Daten-Assets verwenden, um zusätzlichen Kontext zu erfassen, der für Agenten nützlich ist, wenn sie Daten-Assets entdecken, prüfen oder verwenden.
    Datenprofil Verteilungsstatistiken, Anzahl eindeutiger Werte, Nullverhältnisse und Beispielwerte.
    Datenqualität Automatisierte Datenqualitätsprüfung anhand vordefinierter Regeln.
    Kontext zu ähnlichen Daten-Assets Kontext zu zugehörigen Daten-Assets, z. B. Glossarbegriffe oder andere zugehörige Assets, wie häufig verknüpfte Tabellen. Der für ähnliche 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, 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, um die Berechtigungen zu 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:

  • Dataplex-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 Inhaberrolle (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 Daten-Asset abrufen

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

Mit der Methode lookupContext werden die Ressourcen anhand Ihrer Berechtigungen gefiltert. Die Antwort enthält nur Daten für Assets, auf 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 Daten-Asset 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 Projekts in Google Cloud
  • 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 Schema-Joins, 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 beschränkt ist. Wenn Sie den Parameter all_schema_fields auf true setzen, gibt die API alle Schemafelder unabhängig vom Wert context_budget zurück.

Eine Beispielanfrage zum Abrufen des Kontexts 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 Kurzanleitung zur Verwendung von Clientbibliotheken für Knowledge Catalog. Weitere Informationen finden Sie in der API-Referenzdokumentation für Knowledge Catalog Python.

Richten Sie zur Authentifizierung bei Knowledge Catalog 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)

Im folgenden Beispiel wird gezeigt, wie Sie 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 Abläufe abrufen

Mit der Methode lookupContext können Sie Kontext für BigQuery-Routinen wie benutzerdefinierte Funktionen, Tabellenfunktionen und gespeicherte Prozeduren abrufen. KI-Agenten können diesen Kontext verwenden, um zu verstehen, was eine Routine tut und wie sie aufgerufen wird, z. B. beim Generieren von SQL-Abfragen. Der Kontext für eine Routine umfasst die folgenden Informationen:

  • Der Routinentyp, z. B. Skalarfunktion, Tabellenfunktion oder Prozedur.
  • Die Sprache des Ablaufs.
  • Die Argumente und der Rückgabetyp der Routine.
  • 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 Liste resources 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.

Welche Best Practices gibt es für Kontextabfragen?

Beachten Sie die folgenden Best Practices, um Ihre Ergebnisse bei 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 genau wie möglich innerhalb der durch den Parameter vorgegebenen Grenzen in die Ausgabe einzufügen.
  • 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 bereit, sondern auch für mögliche Join-Pfade zwischen ihnen. So erhalten Sie die erforderlichen Informationen, um diese Tabellen zusammen zu verwenden.
  • Verwenden Sie die Option format, z. B. yaml oder json, die am besten zur Parsing-Logik des LLM oder des KI-Agenten passt, um kostspielige Transformationen zu vermeiden.

Nächste Schritte