Agent zum Anreichern von Metadaten erstellen

Knowledge Catalog (ehemals Dataplex Universal Catalog) verwaltet Metadaten für Daten-Assets in der gesamten Organisation. Diese Metadaten liefern den Kontext, den Agenten verwenden, um die Daten zu finden, zu verstehen und abzufragen, die zum Beantworten von Nutzerfragen erforderlich sind.

Knowledge Catalog verwaltet zwar automatisch Ressourcen, verfolgt technische Schemas und generiert Beschreibungen und Datenprofile, aber wertvoller geschäftlicher Kontext befindet sich oft an anderen Orten, z. B.:

  • Interne Dokumente und Wikis
  • Code-Repositories
  • Kommunikationskanäle wie Google Chat und Slack

Sie können KI-Agenten erstellen, um Kontext aus diesen Quellen zu extrahieren und Ihre Metadaten kontinuierlich in großem Maßstab anzureichern. In dieser Anleitung wird Beispielcode aus dem knowledge-catalog Repository verwendet, um zu zeigen, wie Sie einen Agenten erstellen, der Folgendes tut:

  • Kontext extrahieren:Extrahiert geschäftlichen Kontext aus Wissensdatenbanken, Dokumenten, Code oder Chats, um technische Metadaten anzureichern.
  • Dokumentation generieren:Generiert Dokumentation für BigQuery-Tabellen basierend auf dem extrahierten Kontext und anderen Informationsquellen.
  • Suche und Auffindbarkeit verbessern:Veröffentlicht die generierte Dokumentation in Knowledge Catalog, wodurch Einträge über die Suche leichter zu finden und zu verstehen sind.

Hinweis

Damit Sie den Knowledge Catalog-Anreicherungsagenten ausführen können, müssen die folgenden Anforderungen erfüllt sein:

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 zur Verwendung des Anreicherungsagenten benötigen:

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

Diese vordefinierten Rollen enthalten die Berechtigungen, die zur Verwendung des Anreicherungsagenten erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind für die Verwendung des Anreicherungsagenten erforderlich:

  • bigquery.projects.get/createDatasets
  • dataplex.projects.search
  • dataplex.entryGroups.get/updateEntries
  • aiplatform.endpoints.predict
  • serviceusage.services.use

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

APIs aktivieren

Aktivieren Sie die folgenden APIs in Ihrem Projekt, um den Knowledge Catalog-Anreicherungsagenten zu verwenden:

  • BigQuery API
  • Knowledge Catalog API
  • Vertex AI API
  • Service Usage 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.

APIs aktivieren

Abhängigkeiten installieren

Sie benötigen die folgenden Python-Pakete und -Tools, um das Beispiel auszuführen:

  • google-adk (Agent Development Kit (ADK))
  • google-cloud-dataplex Knowledge Catalog Python Client
  • google-auth verwaltet Standardanmeldedaten für Anwendungen
  • mcp[cli] zum Erstellen eines MCP-Beispielservers
  • gcloud für die Authentifizierung und Konfiguration. Informationen zum Installieren der Google Cloud CLI finden Sie in der Google Cloud SDK-Dokumentation.

Umgebung einrichten

  1. Konfigurieren Sie gcloud und melden Sie sich an:

    gcloud auth application-default login
gcloud config set core/project PROJECT_ID

    Ersetzen Sie Folgendes:

    • PROJECT_ID durch die ID Ihres Projekts

  2. Klonen Sie das knowledge-catalog Repository und wechseln Sie zum Beispielquellverzeichnis:

    git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/src

  3. Verwenden Sie das bereitgestellte Skript, um Abhängigkeiten zu installieren. Es richtet eine virtuelle Python-Umgebung und die erforderlichen Umgebungsvariablen ein:

    source env.sh --install

  4. Führen Sie das Skript create_data.py aus, um in der Region us Ihres Cloud-Projekts ein BigQuery-Beispieldataset mit dem Namen kc_sample_analytics zu erstellen:

    python3 ../sample/data/create_data.py

    Das Beispiel enthält auch eine Reihe von Dokumenten im Verzeichnis sample/docs. Diese Dokumente bilden eine lokale Wissensdatenbank. Der Anreicherungsagent verwendet diese Wissensdatenbank, um Informationen zu extrahieren und Dokumentation zu erstellen.

Metadaten herunterladen

Führen Sie zuerst das Download-Tool aus, um einen Metadatensnapshot aus Knowledge Catalog für das BigQuery-Dataset und seine Tabellen zu extrahieren. Dadurch werden lokale Metadatenartefakte erstellt.

Das Argument --dir gibt das Verzeichnis an, in das die Metadatendateien geschrieben werden.

python3 -m enrichment.download \
  --dir ../sample/metadata.initial \
  --dataset ${KC_ENRICH_SAMPLE_PROJECT}.kc_sample_analytics

Das Skript erstellt im Verzeichnis sample/metadata eine Markdown-Datei pro Tabelle mit der folgenden Namenskonvention: <project_id>.<dataset_id>.<table_id>.md.

Metadaten anreichern

Nachdem Sie die lokalen Markdown-Dateien erstellt haben, führen Sie den Anreicherungsagenten aus. Der Agent durchläuft jede Datei, sucht nach Informationen, die für die Tabellen relevant sind, und fasst die Ergebnisse zusammen. Außerdem werden Zitate hinzugefügt, um aktualisierte Markdown-Dateien zu generieren.

  • --dir: Gibt das Verzeichnis mit den lokalen Metadatendateien an.
  • --output-dir: Gibt das Zielverzeichnis für die aktualisierten Metadatendateien an.
  • --config-dir: Gibt das Verzeichnis an, das Agentenanweisungen, MCP-Tools und Skills enthält.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Metadaten prüfen

Die angereicherten Metadatendateien enthalten die vom Agenten erstellte Dokumentation. Prüfen und ändern Sie die Dateien nach Bedarf, bevor Sie die Änderungen in Knowledge Catalog veröffentlichen.

git diff --no-index ../sample/metadata.initial ../sample/metadata.new

Metadaten veröffentlichen

Führen Sie das Veröffentlichungstool aus, um die angereicherten Metadaten in Knowledge Catalog bereitzustellen.

python3 -m src.enrichment.publish --dir ../sample/metadata.new

An Ihre Daten anpassen

Im vorherigen Schritt haben Sie das Argument --config-dir verwendet, um den Agenten für die Konfiguration auf das Verzeichnis ../sample/config zu verweisen. So weiß der Agent, wo er Informationen findet und wie er mit verschiedenen Quellen interagiert.

Das Beispiel enthält eine Standardkonfiguration, die den Agenten anweist, einen lokalen MCP-Server zu verwenden, um auf Dateien in der lokalen Wissensdatenbank (sample/docs) zuzugreifen. Wenn Sie diesen Workflow in Ihrer Umgebung anwenden möchten, können Sie diese Konfigurationsdateien anpassen, um den Agenten mit Ihren internen Wikis, Code-Repositories, Google Drive oder anderen Systemen zu verbinden.

Das Verzeichnis sample/config/ enthält die folgenden Dateien:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md: Erweitert die grundlegenden Anweisungen des Agenten um Details, die für Ihre Organisation relevant sind, z. B. die Anweisung, eine bestimmte Wissensdatenbank zu durchsuchen.
  • mcp.json: Konfiguriert MCP-Server, die der Agent verwenden kann, um auf Tools für Ihre Informationsquellen zuzugreifen, z. B. ein Tool zum Lesen von Dateien aus einem lokalen Verzeichnis.
  • SKILL.md: Beschreibt, wie der Agent bestimmte Tools verwenden soll, um mit einer Informationsquelle zu interagieren, z. B. list_contents, read_file und search_content, um Informationen in lokalen Dokumenten zu finden.

Knowledge Catalog-Beispielcode ansehen

Die Tools download und publish im Abschnitt zum Anreicherungsablauf verwenden Knowledge Catalog APIs, um Metadaten zu lesen und zu schreiben.

In diesem Abschnitt wird beschrieben, wie diese APIs funktionieren, damit Sie das Beispiel an Ihre eigenen Integrationen anpassen können.

Nach Metadaten suchen und sie abrufen

Das Beispiel verwendet die folgenden APIs, um nach Metadaten zu suchen und sie abzurufen:

  • SearchEntries, um die Metadaten für den Eintrag und die Standortmetadaten des Datasets abzurufen.
  • ListEntries, um BigQuery-Tabellen in einer Catalog EntryGroup aufzulisten.
  • GetEntry, um die spezifischen Metadaten für jede BigQuery-Tabelle abzurufen.

Der folgende Code zeigt, wie Sie nach einem Dataset suchen, um seine Eintragsgruppe zu finden, alle enthaltenen Tabellen aufzulisten und ihre spezifischen Metadaten abzurufen:

import google.cloud.dataplex_v1 as dataplex

BIGQUERY_TABLE_TYPE = "projects/dataplex-types/locations/global/entryTypes/bigquery-table"
OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"

catalog = dataplex.CatalogServiceClient()

dataset_reference = '...'   # project_id.dataset_id
project_id, dataset_id = dataset_reference.split('.')

# 1. Search for dataset to determine its location
search_response = catalog.search_entries(
    request=dataplex.SearchEntriesRequest(
        name=f"projects/{project_id}/locations/global",
        query=f"type=dataset name={dataset_id}",
        page_size=1
    )
)
dataset_entry = search_response.results[0].dataplex_entry
location_id = dataset_entry.entry_source.location

# 2. List resources in the underlying group
entry_group_name = f"projects/{project_id}/locations/{location_id}/entryGroups/@bigquery"
entry_filter = f'parent_entry="{dataset_entry.name}"'
list_response = catalog.list_entries(
    request=dataplex.ListEntriesRequest(
        parent=entry_group_name,
        entry_filter=entry_filter,
    )
)

# 3. Retrieve metadata for each table in the list
for table_entry in list_response.entries:
    entry = catalog.get_entry(
        request=dataplex.GetEntryRequest(
            name=table_entry.name,
            view="CUSTOM",
            aspect_types=[OVERVIEW_ASPECT_TYPE]
        )
    )

Tabellenmetadaten aktualisieren

Der folgende Code zeigt, wie Sie die generierte Dokumentation für den Aspekt „Übersicht“ einer Tabelle veröffentlichen und ihre Metadaten aktualisieren:

import google.cloud.dataplex_v1 as dataplex
import google.protobuf.field_mask_pb2 as field_mask_pb2
import google.protobuf.json_format as jsonpb

OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"
OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview"

catalog = dataplex.CatalogServiceClient()

table_reference = "..."    # project_id.dataset_id.table_id
project_id, dataset_id, table_id = table_reference.split('.')

entry_data = {
    "name": f"bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}",
    "aspects": {
        OVERVIEW_ASPECT_KEY: {
            "aspectType": OVERVIEW_ASPECT_TYPE,
            "data": {
                "content": "...", # content parsed from local markdown file
                "contentType": "MARKDOWN"
            }
        }
    }
}

entry = dataplex.Entry()
jsonpb.ParseDict(entry_data, entry._pb)

catalog.update_entry(
    request=dataplex.UpdateEntryRequest(
        entry=entry,
        update_mask=field_mask_pb2.FieldMask(paths=["aspects"]),
        aspect_keys=[OVERVIEW_ASPECT_KEY],
    )
)

Nächste Schritte