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 KI-Agenten verwenden, um die Daten zu finden, zu verstehen und abzufragen, die zum Beantworten von Nutzerfragen erforderlich sind.

Knowledge Catalog verwaltet Ressourcen automatisch, verfolgt technische Schemas und generiert Beschreibungen und Datenprofile. Wertvoller Geschäftskontext befindet sich jedoch häufig 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 im großen Maßstab kontinuierlich anzureichern. In dieser Anleitung wird Beispielcode aus dem Repository knowledge-catalog 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 extrahiertem Kontext und anderen Informationsquellen.
  • Suche und Auffindbarkeit verbessern: Die generierte Dokumentation wird im Knowledge Catalog veröffentlicht, sodass Einträge über die Suche leichter zu finden und zu verstehen sind.

Hinweis

Damit Sie den Knowledge Catalog-Anreicherungs-Agent 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 Anreicherungs-Agents 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 für die Verwendung des Anreicherungs-Agents erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um den Anreicherungs-Agent zu verwenden:

  • 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

Wenn Sie den Knowledge Catalog-Anreicherungs-Agent verwenden möchten, aktivieren Sie die folgenden APIs in Ihrem Projekt:

  • BigQuery API
  • Dataplex-API
  • Vertex AI API
  • Service Usage 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

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 Beispiel-MCP-Servers
  • gcloud für die Authentifizierung und Konfiguration. Informationen zum Installieren der Google Cloud CLI finden Sie in der Dokumentation zum Google Cloud SDK.

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 Repository knowledge-catalog und rufen Sie das Beispielquellverzeichnis auf:

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

  3. Verwenden Sie zum Installieren von Abhängigkeiten das bereitgestellte Skript, mit dem eine virtuelle Python-Umgebung und die erforderlichen Umgebungsvariablen eingerichtet werden:

    source env.sh --install

  4. Führen Sie das Skript create_data.py aus, um ein BigQuery-Beispiel-Dataset mit dem Namen kc_sample_analytics in der Region us Ihres Cloud-Projekts 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 Anreicherungs-Agent verwendet diese Wissensdatenbank, um Informationen zu extrahieren und Dokumentation zu erstellen.

Metadaten herunterladen

Führen Sie zuerst das Downloadtool aus, um einen Metadaten-Snapshot 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 Script erstellt eine Markdown-Datei pro Tabelle im Verzeichnis sample/metadata 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 Anreicherungs-Agent aus. Der KI-Agent geht jede Datei durch, sucht nach Informationen, die für die Tabellen relevant sind, und fasst die Ergebnisse zusammen. Außerdem fügt er Zitate hinzu, 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 Dateien mit angereicherten Metadaten enthalten die vom Agent erstellte Dokumentation. Überprüfen und ändern Sie die Dateien nach Bedarf, bevor Sie die Änderungen im 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 auf das Verzeichnis ../sample/config für seine Konfiguration zu verweisen. So weiß der Agent, wo er Informationen findet und wie er mit verschiedenen Quellen interagieren kann.

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: Ergänzt die grundlegenden Anweisungen des KI-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 KI-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.

Beispielcode für Knowledge Catalog ansehen

Die Tools download und publish im Abschnitt „Anreicherungsfluss“ verwenden Knowledge Catalog APIs zum Lesen und Schreiben von Metadaten.

In diesem Abschnitt wird die Funktionsweise dieser APIs beschrieben, damit Sie das Beispiel für Ihre eigenen Integrationen anpassen können.

Metadaten suchen und abrufen

Im Beispiel werden die folgenden APIs verwendet, um nach Metadaten zu suchen und diese abzurufen:

  • SearchEntries, um die Eintrags- und Standortmetadaten für das Dataset abzurufen.
  • ListEntries, um BigQuery-Tabellen in einer Catalog-EntryGroup aufzulisten.
  • GetEntry, um die spezifischen Metadaten für jede BigQuery-Tabelle abzurufen.

Im folgenden Code wird gezeigt, wie Sie nach einem Dataset suchen, um die zugehörige Eintragsgruppe zu finden, alle enthaltenen Tabellen aufzulisten und die zugehörigen 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 im Aspekt „Übersicht“ für eine Tabelle veröffentlichen und die 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