Agent zum Anreichern von Metadaten erstellen

Im Knowledge Catalog (ehemals Dataplex Universal Catalog) werden Metadaten für Daten-Assets in der gesamten Organisation verwaltet. Diese Metadaten liefern den Kontext, den Agents benötigen, um die Daten zu ermitteln, zu verstehen und abzufragen, die zur Beantwortung von Nutzerfragen erforderlich sind.

Knowledge Catalog verwaltet Ressourcen automatisch, verfolgt technische Schemas und generiert Beschreibungen und Datenprofile. Wertvoller Geschäftskontext ist jedoch oft an anderen Orten zu finden, z. B.:

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

Sie können KI-Agents erstellen, um Kontext aus diesen Quellen zu extrahieren und Ihre Metadaten kontinuierlich zu erweitern. In dieser Anleitung wird Beispielcode aus dem Repository dataplex-labs verwendet, um zu zeigen, wie Sie einen Agenten erstellen, der Folgendes ausführt:

  • Kontext extrahieren:Geschäftsbezogener Kontext wird aus Wissensdatenbanken, Dokumenten, Code oder Chats extrahiert, 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 leichter über die Suche gefunden und verstanden werden können.

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 Enrichment-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 zum Verwenden des Enrichment-Agents erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind für die Verwendung des Anreicherungs-Agents 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

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

  • 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 IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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 Google Cloud SDK-Dokumentation.

Umgebung einrichten

  1. gcloud konfigurieren und anmelden:

    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 dataplex-labs und wechseln Sie in das Beispielquellverzeichnis:

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/knowledge_catalog_enrichment_agent/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 create_data.py-Skript 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 Enrichment-Agent verwendet diese Wissensdatenbank, um Informationen zu extrahieren und Dokumentation zu erstellen.

Metadaten herunterladen

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

Mit dem Argument --dir wird das Verzeichnis angegeben, 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 eine Markdown-Datei pro Tabelle im Verzeichnis sample/metadata. Dabei wird die folgende Namenskonvention verwendet: <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 durchläuft jede Datei, sucht nach Informationen, die für die Tabellen relevant sind, und fasst die Ergebnisse zusammen. Außerdem fügt er Zitationen hinzu, um aktualisierte Markdown-Dateien zu generieren.

  • --dir: Gibt das Verzeichnis an, das die lokalen Metadatendateien enthält.
  • --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. Ü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 soll.

Das Beispiel enthält eine Standardkonfiguration, die den Agent 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 Agent 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 Bereich „Anreicherungsablauf“ verwenden Knowledge Catalog APIs zum Lesen und Schreiben von Metadaten.

In diesem Abschnitt wird beschrieben, wie diese APIs funktionieren, 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 sie abzurufen:

  • SearchEntries zum Abrufen der Metadaten für Einträge und Standortmetadaten für das Dataset.
  • ListEntries zum Auflisten von BigQuery-Tabellen in einer Catalog EntryGroup.
  • GetEntry, um die spezifischen Metadaten für jede BigQuery-Tabelle abzurufen.

Im folgenden Code wird gezeigt, 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 die generierte Dokumentation für eine Tabelle im Aspekt „Übersicht“ veröffentlicht und die zugehörigen Metadaten aktualisiert werden:

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