Crea un agente per arricchire i metadati

Knowledge Catalog (in precedenza Dataplex Universal Catalog) gestisce i metadati degli 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 di valore spesso risiede in altre posizioni, ad esempio:

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

Puoi creare agenti AI per estrarre il contesto da queste origini e arricchire continuamente i tuoi metadati su larga scala. Questo tutorial utilizza il codice campione del repository knowledge-catalog per mostrarti 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 fonti di informazioni.
  • Migliora la ricerca e la scoperta:pubblica la documentazione generata in Knowledge Catalog, semplificando la ricerca e la comprensione delle voci.

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 progetto Google Cloud 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 Dataplex
  • API Vertex AI
  • API Service Usage

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Installa le dipendenze

Per eseguire l'esempio, sono necessari i seguenti pacchetti e strumenti Python:

  • google-adk (Agent Development Kit (ADK))
  • Client Python di google-cloud-dataplex 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: l'ID del tuo progetto.

  2. Clona il repository knowledge-catalog e vai alla directory di origine di esempio:

    git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/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

    L'esempio 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 set di dati BigQuery e le relative tabelle. In questo modo vengono creati artefatti di metadati locali.

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

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

Lo script crea un file Markdown per 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 esegue l'iterazione di 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 dei metadati locali.
  • --output-dir: specifica la directory di destinazione per i file dei 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 tue esigenze prima di pubblicare le modifiche in Knowledge Catalog.

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

Pubblica i metadati

Esegui lo strumento di pubblicazione per eseguire il deployment dei metadati arricchiti in Knowledge Catalog.

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

Personalizza per i 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 include 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 workflow 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: integra le istruzioni di base dell'agente con dettagli pertinenti per la tua organizzazione, ad esempio indicandogli di eseguire ricerche in una knowledge base specifica.
  • mcp.json: configura i server MCP che l'agente può utilizzare per accedere agli strumenti per le tue origini di informazioni, ad esempio uno strumento per leggere i file da una directory locale.
  • SKILL.md: descrive in che modo l'agente deve utilizzare strumenti specifici per interagire con una fonte 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 illustra il funzionamento di queste API in modo che tu possa adattare l'esempio alle tue integrazioni.

Cerca e recupera i metadati

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

  • SearchEntries per recuperare i metadati della voce e della località per il set di dati.
  • ListEntries per enumerare le tabelle BigQuery all'interno di un EntryGroup di Catalog.
  • GetEntry per recuperare i metadati specifici per ogni tabella BigQuery.

Il codice seguente 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