Criar um agente para enriquecer seus metadados

O Knowledge Catalog (antigo Dataplex Universal Catalog) gerencia metadados de recursos de dados em toda a organização. Esses metadados fornecem o contexto que os agentes usam para descobrir, entender e consultar os dados necessários para responder às perguntas dos usuários.

Embora o Knowledge Catalog gerencie recursos, rastreie esquemas técnicos e gere descrições e perfis de dados automaticamente, o contexto comercial valioso geralmente reside em outros locais, como:

  • Documentos e wikis internos
  • Repositórios de código
  • Canais de comunicação, como o Google Chat e o Slack

É possível criar agentes de IA para extrair contexto dessas fontes e enriquecer continuamente seus metadados em escala. Este tutorial usa um exemplo de código do dataplex-labs repositório para mostrar como criar um agente que faz o seguinte:

  • Extrair contexto:extrai o contexto comercial de bases de conhecimento, documentos, códigos ou chats para enriquecer metadados técnicos.
  • Gerar documentação:gera documentação para tabelas do BigQuery com base no contexto extraído e em outras fontes de informação.
  • Melhorar a pesquisa e a descoberta:publica a documentação gerada no Knowledge Catalog, facilitando a localização e a compreensão das entradas por meio da pesquisa.

Antes de começar

Para executar o agente de enriquecimento do Knowledge Catalog, é necessário atender aos seguintes requisitos:

Funções exigidas

Para receber as permissões necessárias a fim de usar o agente de enriquecimento, peça que o administrador conceda a você os seguintes papéis do IAM no Google Cloud projeto iam.gserviceaccount.com:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar o agente de enriquecimento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para usar o agente de enriquecimento:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Ativar APIs

Para usar o agente de enriquecimento do Knowledge Catalog, ative as seguintes APIs no seu projeto:

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

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

Ativar as APIs

Instalar dependências

Você precisa dos seguintes pacotes e ferramentas do Python para executar o exemplo:

  • google-adk (Kit de Desenvolvimento de Agente, ADK)
  • google-cloud-dataplex Biblioteca de cliente Python do Knowledge Catalog
  • google-auth gerencia o Application Default Credentials
  • mcp[cli] para criar um exemplo de servidor MCP
  • gcloud para autenticação e configuração. Para instalar a Google Cloud CLI, consulte a documentação do SDK Google Cloud.

Configurar o ambiente

  1. Configure gcloud e faça login:

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

    Substitua:

    • PROJECT_ID pelo ID do projeto

  2. Clone o repositório dataplex-labs e navegue até o diretório de origem de amostra:

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

  3. Para instalar dependências, use o script fornecido que configura um ambiente virtual Python e as variáveis de ambiente necessárias:

    source env.sh --install

  4. Para criar um exemplo de conjunto de dados do BigQuery chamado kc_sample_analytics na região us do projeto na nuvem, execute o script create_data.py:

    python3 ../sample/data/create_data.py

    O exemplo também inclui vários documentos no diretório sample/docs. Esses documentos formam uma base de conhecimento local. O agente de enriquecimento usa essa base de conhecimento para extrair informações e produzir documentação.

Fazer download dos metadados

Comece executando a ferramenta de download para extrair um snapshot de metadados do Knowledge Catalog para o conjunto de dados do BigQuery e as tabelas dele. Isso cria artefatos de metadados locais.

O argumento --dir especifica o diretório em que os arquivos de metadados são gravados.

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

O script cria um arquivo Markdown por tabela no diretório sample/metadata usando a seguinte convenção de nomenclatura: <project_id>.<dataset_id>.<table_id>.md.

Enriquecer os metadados

Depois de criar os arquivos Markdown locais, execute o agente de enriquecimento. O agente itera em cada arquivo, encontra informações relevantes para as tabelas e resume as descobertas com citações para gerar arquivos Markdown atualizados.

  • --dir: especifica o diretório que contém os arquivos de metadados locais.
  • --output-dir: especifica o diretório de destino para os arquivos de metadados atualizados.
  • --config-dir: especifica o diretório que contém instruções do agente, ferramentas e habilidades do MCP.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Analisar os metadados

Os arquivos de metadados enriquecidos contêm a documentação produzida pelo agente. Analise e modifique os arquivos conforme necessário antes de publicar as mudanças no Knowledge Catalog.

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

Publicar os metadados

Execute a ferramenta de publicação para implantar os metadados enriquecidos no Knowledge Catalog.

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

Personalizar para seus dados

Na etapa anterior, você usou o argumento --config-dir para direcionar o agente ao diretório ../sample/config para a configuração. É assim que o agente sabe onde encontrar informações e como interagir com diferentes fontes.

O exemplo vem com uma configuração padrão que instrui o agente a usar um servidor MCP local para acessar arquivos na base de conhecimento local (sample/docs). Para aplicar esse fluxo de trabalho no seu ambiente, personalize esses arquivos de configuração para conectar o agente aos wikis internos, repositórios de código, Google Drive ou outros sistemas.

O diretório sample/config/ contém os seguintes arquivos:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md: aumenta as instruções de linha de base do agente com detalhes relevantes para sua organização, como instruir a pesquisa em uma base de conhecimento específica.
  • mcp.json: configura servidores MCP que o agente pode usar para acessar ferramentas para suas fontes de informação, como uma ferramenta para ler arquivos de um diretório local.
  • SKILL.md: descreve como o agente deve usar ferramentas específicas para interagir com uma fonte de informação, como usar list_contents, read_file e search_content para encontrar informações em documentos locais.

Conferir o exemplo de código do Knowledge Catalog

As ferramentas download e publish na seção de fluxo de enriquecimento usam APIs do Knowledge Catalog para ler e gravar metadados.

Esta seção aborda como essas APIs funcionam para que você possa adaptar o exemplo às suas próprias integrações.

Pesquisar e recuperar metadados

O exemplo usa as seguintes APIs para pesquisar e recuperar metadados:

  • SearchEntries para recuperar os metadados de entrada e metadados de local do conjunto de dados.
  • ListEntries para enumerar tabelas do BigQuery em um EntryGroup do catálogo.
  • GetEntry para buscar os metadados específicos de cada tabela do BigQuery.

O código a seguir mostra como pesquisar um conjunto de dados para localizar o grupo de entradas, listar todas as tabelas contidas e recuperar os metadados específicos delas:

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

Atualizar metadados de tabela

O código a seguir mostra como publicar a documentação gerada no aspecto de visão geral de uma tabela e atualizar os metadados dela:

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

A seguir