Kontext für Datenassets abrufen

Der Kontext Ihrer Daten liefert Ihren KI-Anwendungen ein umfassendes Verständnis Ihrer Datenassets und verbessert so die Genauigkeit und Relevanz von Antworten, die von LLMs generiert werden.

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.

Wie erhalten Agenten Datenkontext?

1. Der Agent ruft Datenassets ab, die für den Kontextabruf potenziell relevant sind, z. B. mithilfe 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 Datenanalysen. 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, z. B. häufig verknüpften Tabellen. Der für verknüpfte Assets zurückgegebene Kontext umfasst dieselbe Auswahl 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, 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

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

• Knowledge Catalog API

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.

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

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

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

# 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)

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

Welche Best Practices gibt es für Kontextabfragen?

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 weit wie möglich in die Ausgabe einzufügen, wobei die durch den Parameter vorgegebenen Grenzwerte eingehalten werden.
• Sie können bis zu zehn Datenassets in der Liste resources auflisten. Wenn Sie beispielsweise mehrere Tabellen in die Liste resources aufnehmen, liefert die API nicht nur den Kontext für diese Tabellen, sondern auch für mögliche Verknüpfungspfade zwischen ihnen. 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

• Erfahren Sie, wie Sie einen Agenten zum Auffinden Ihrer Daten erstellen.
• Agent zum Anreichern Ihrer Metadaten erstellen .
• Suchsyntax für Knowledge Catalog verstehen.
• Mehr über das Ansehen von Datenbeziehungen erfahren.