Crea un agente per arricchire i metadati

Knowledge Catalog (in precedenza 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, tenga traccia degli schemi tecnici e generi descrizioni e profili di dati, il contesto aziendale di valore spesso risiede 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 origini e arricchire continuamente i metadati su larga scala. Questo tutorial utilizza il codice campione del knowledge-catalog repository 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 origini di informazioni.
  • Migliora la ricerca e il rilevamento: 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 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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin). 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 la creazione di 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 knowledge-catalog e vai alla directory di origine dell'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 Python virtuale 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 i metadati

Inizia eseguendo lo strumento di download per estrarre un'istantanea dei metadati da Knowledge Catalog per il set di dati 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 scorre ogni file, trova le informazioni pertinenti alle tabelle e riepiloga 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 contenente le istruzioni dell'agente, gli strumenti MCP e le competenze.
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 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 origini.

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 flusso di lavoro nel tuo ambiente, puoi personalizzare questi file di configurazione per connettere l'agente ai 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 indicandogli di cercare 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 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 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 del 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]
        )
    )

Aggiorna i metadati della 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