Crea un agente per arricchire i metadati

Knowledge Catalog (precedentemente Dataplex Universal Catalog) gestisce i metadati per gli asset di dati in tutta l'organizzazione. Questi metadati forniscono il contesto che gli agenti utilizzano per scoprire, comprendere ed eseguire query sui dati necessari per rispondere alle domande degli utenti.

Sebbene Knowledge Catalog gestisca automaticamente le risorse, monitori gli schemi tecnici e generi descrizioni e profili dei dati, il contesto aziendale prezioso si trova spesso in altre posizioni, ad esempio:

  • Documenti e wiki interni
  • repository di codice
  • Canali di comunicazione come Google Chat e Slack

Puoi creare agenti AI per estrarre il contesto da queste fonti e arricchire continuamente i metadati su larga scala. Questo tutorial utilizza il codice campione del repository dataplex-labs per mostrare come creare un agente che esegue le seguenti operazioni:

  • Estrai contesto:estrae il contesto aziendale da knowledge base, documenti, codice o chat per arricchire i metadati tecnici.
  • Genera documentazione:genera la documentazione per le tabelle BigQuery in base al contesto estratto e ad altre origini di informazioni.
  • Migliora la ricerca e la scoperta:pubblica la documentazione generata in Knowledge Catalog, rendendo le voci più facili da trovare e comprendere tramite la ricerca.

Prima di iniziare

Per eseguire l'agente di arricchimento di Knowledge Catalog, devi soddisfare i seguenti requisiti:

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare l'agente di arricchimento, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo Google Cloud progetto iam.gserviceaccount.com:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per utilizzare l'agente di arricchimento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per utilizzare l'agente di arricchimento sono necessarie le seguenti autorizzazioni:

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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Per utilizzare l'agente di arricchimento di Knowledge Catalog, abilita le seguenti API nel tuo progetto:

  • API BigQuery
  • API Knowledge Catalog
  • API Vertex AI
  • API Service Usage

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilita le API

Installa le dipendenze

Per eseguire l'esempio, devi disporre dei seguenti pacchetti e strumenti Python:

  • google-adk (Agent Development Kit (ADK))
  • google-cloud-dataplex Client Python di Knowledge Catalog
  • google-auth gestisce le Credenziali predefinite dell'applicazione
  • mcp[cli] per creare un server MCP di esempio
  • gcloud per l'autenticazione e la configurazione. Per installare Google Cloud CLI, consulta la documentazione di Google Cloud SDK.

Configura l'ambiente

  1. Configura gcloud e accedi:

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

    Sostituisci quanto segue:

    • PROJECT_ID con l'ID del tuo progetto

  2. Clona il repository dataplex-labs e vai alla directory di origine di esempio:

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/knowledge_catalog_enrichment_agent/src

  3. Per installare le dipendenze, utilizza lo script fornito che configura un ambiente virtuale Python e le variabili di ambiente necessarie:

    source env.sh --install

  4. Per creare un set di dati BigQuery di esempio denominato kc_sample_analytics nella regione us del tuo progetto cloud, esegui lo script create_data.py:

    python3 ../sample/data/create_data.py

    Il campione include anche una serie di documenti nella directory sample/docs. Questi documenti formano una knowledge base locale. L'agente di arricchimento utilizza questa knowledge base per estrarre informazioni e produrre documentazione.

Scarica metadati

Inizia eseguendo lo strumento di download per estrarre uno snapshot dei metadati da Knowledge Catalog per il dataset BigQuery e le relative tabelle. Vengono creati artefatti di metadati locali.

L'argomento --dir specifica la directory in cui vengono scritti i file di metadati.

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

Lo script crea un file Markdown per ogni tabella nella directory sample/metadata utilizzando la seguente convenzione di denominazione: <project_id>.<dataset_id>.<table_id>.md.

Arricchisci i metadati

Dopo aver creato i file Markdown locali, esegui l'agente di arricchimento. L'agente esamina ogni file, trova le informazioni pertinenti alle tabelle e riassume i risultati insieme alle citazioni per generare file Markdown aggiornati.

  • --dir: specifica la directory contenente i file di metadati locali.
  • --output-dir: specifica la directory di destinazione per i file di metadati aggiornati.
  • --config-dir: specifica la directory che contiene le istruzioni dell'agente, gli strumenti MCP e le skill.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Esamina i metadati

I file di metadati arricchiti contengono la documentazione prodotta dall'agente. Esamina e modifica i file in base alle esigenze prima di pubblicare le modifiche nel Knowledge Catalog.

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

Pubblicare i metadati

Esegui lo strumento di pubblicazione per implementare i metadati arricchiti in Knowledge Catalog.

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

Personalizzare in base ai tuoi dati

Nel passaggio precedente, hai utilizzato l'argomento --config-dir per indirizzare l'agente alla directory ../sample/config per la sua configurazione. In questo modo l'agente sa dove trovare le informazioni e come interagire con le diverse fonti.

L'esempio viene fornito con una configurazione predefinita che indica all'agente di utilizzare un server MCP locale per accedere ai file nella knowledge base locale (sample/docs). Per applicare questo flusso di lavoro nel tuo ambiente, puoi personalizzare questi file di configurazione per connettere l'agente ai tuoi wiki interni, ai repository di codice, a Google Drive o ad altri sistemi.

La directory sample/config/ contiene i seguenti file:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md: aumenta le istruzioni di base dell'agente con dettagli pertinenti alla tua organizzazione, ad esempio indicando di cercare in una knowledge base specifica.
  • mcp.json: configura i server MCP che l'agente può utilizzare per accedere agli strumenti per le tue fonti di informazioni, ad esempio uno strumento per leggere i file da una directory locale.
  • SKILL.md: descrive come l'agente deve utilizzare strumenti specifici per interagire con un'origine di informazioni, ad esempio utilizzando list_contents, read_file e search_content per trovare informazioni nei documenti locali.

Esplora il codice di esempio di Knowledge Catalog

Gli strumenti download e publish nella sezione del flusso di arricchimento utilizzano le API Knowledge Catalog per leggere e scrivere i metadati.

Questa sezione descrive il funzionamento di queste API in modo che tu possa adattare l'esempio alle tue integrazioni.

Cercare e recuperare i metadati

L'esempio utilizza le seguenti API per cercare e recuperare i metadati:

  • SearchEntries per recuperare i metadati della voce e della posizione per il set di dati.
  • ListEntries per enumerare le tabelle BigQuery all'interno di un gruppo di voci di catalogo.
  • GetEntry per recuperare i metadati specifici per ogni tabella BigQuery.

Il seguente codice mostra come cercare un set di dati per individuare il relativo gruppo di voci, elencare tutte le tabelle contenute e recuperare i relativi metadati specifici:

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

Aggiornamento metadati tabella

Il seguente codice mostra come pubblicare la documentazione generata nell'aspetto Panoramica di una tabella e aggiornarne i metadati:

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],
    )
)

Passaggi successivi