Crea un agente para enriquecer tus metadatos

Knowledge Catalog (anteriormente, Dataplex Universal Catalog) administra los metadatos de los recursos de datos en toda la organización. Estos metadatos proporcionan el contexto que usan los agentes para descubrir, comprender y consultar los datos necesarios para responder las preguntas de los usuarios.

Si bien Knowledge Catalog administra automáticamente los recursos, hace un seguimiento de los esquemas técnicos y genera descripciones y perfiles de datos, el contexto empresarial valioso suele residir en otras ubicaciones, como las siguientes:

  • Documentos y wikis internos
  • Repositorios de código
  • Canales de comunicación, como Google Chat y Slack

Puedes crear agentes de IA para extraer contexto de estas fuentes y enriquecer continuamente tus metadatos a gran escala. En este instructivo, se usa código de muestra del repositorio knowledge-catalog para mostrarte cómo crear un agente que haga lo siguiente:

  • Extraer contexto: Extrae el contexto empresarial de las bases de conocimiento, los documentos, el código o el chat para enriquecer los metadatos técnicos.
  • Generar documentación: Genera documentación para las tablas de BigQuery en función del contexto extraído y otras fuentes de información.
  • Mejorar la búsqueda y el descubrimiento: Publica la documentación generada en Knowledge Catalog, lo que facilita la búsqueda y la comprensión de las entradas.

Antes de comenzar

Para ejecutar el agente de enriquecimiento de Knowledge Catalog, debes cumplir con los siguientes requisitos:

Roles obligatorios

Para obtener los permisos que necesitas para usar el agente de enriquecimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu Google Cloud proyecto iam.gserviceaccount.com:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para usar el agente de enriquecimiento. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar el agente de enriquecimiento:

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

También puedes obtener estos permisos con roles personalizados o otros roles predefinidos.

Habilita las APIs

Para usar el agente de enriquecimiento de Knowledge Catalog, habilita las siguientes APIs en tu proyecto:

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

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar las API

Instala dependencias

Necesitas los siguientes paquetes y herramientas de Python para ejecutar la muestra:

  • google-adk (Kit de desarrollo de agentes [ADK])
  • google-cloud-dataplex Cliente de Python de Knowledge Catalog
  • google-auth administra las credenciales predeterminadas de la aplicación
  • mcp[cli] para crear un servidor de MCP de muestra
  • gcloud para la autenticación y la configuración. Para instalar Google Cloud CLI, consulta la documentación de SDK de Google Cloud.

Configura el entorno

  1. Configura gcloud y accede:

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

    Reemplaza lo siguiente:

    • PROJECT_ID con el ID de tu proyecto.

  2. Clona el repositorio knowledge-catalog y navega al directorio del código fuente de muestra:

    git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/src

  3. Para instalar dependencias, usa la secuencia de comandos proporcionada que configura un entorno virtual de Python y las variables de entorno necesarias:

    source env.sh --install

  4. Para crear un conjunto de datos de BigQuery de muestra llamado kc_sample_analytics en la región us de tu proyecto de Cloud, ejecuta la secuencia de comandos create_data.py:

    python3 ../sample/data/create_data.py

    La muestra también incluye varios documentos en el directorio sample/docs. Estos documentos forman una base de conocimiento local. El agente de enriquecimiento usa esta base de conocimiento para extraer información y producir documentación.

Descargar metadatos

Comienza por ejecutar la herramienta de descarga para extraer una instantánea de metadatos de Knowledge Catalog para el conjunto de datos de BigQuery y sus tablas. Esto crea artefactos de metadatos locales.

El argumento --dir especifica el directorio en el que se escriben los archivos de metadatos.

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

La secuencia de comandos crea un archivo Markdown por tabla en el directorio sample/metadata con la siguiente convención de nombres: <project_id>.<dataset_id>.<table_id>.md.

Enriquece los metadatos

Después de crear los archivos Markdown locales, ejecuta el agente de enriquecimiento. El agente itera sobre cada archivo, busca información relevante para las tablas y resume los resultados junto con las citas para generar archivos Markdown actualizados.

  • --dir: Especifica el directorio que contiene los archivos de metadatos locales.
  • --output-dir: Especifica el directorio de destino para los archivos de metadatos actualizados.
  • --config-dir: Especifica el directorio que contiene las instrucciones del agente, las herramientas de MCP y las habilidades.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Revisa los metadatos

Los archivos de metadatos enriquecidos contienen la documentación producida por el agente. Revisa y modifica los archivos según sea necesario antes de publicar los cambios en Knowledge Catalog.

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

Publica los metadatos

Ejecuta la herramienta de publicación para implementar los metadatos enriquecidos en Knowledge Catalog.

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

Personaliza tus datos

En el paso anterior, usaste el argumento --config-dir para dirigir el agente al directorio ../sample/config para su configuración. Así es como el agente sabe dónde encontrar información y cómo interactuar con diferentes fuentes.

La muestra incluye una configuración predeterminada que le indica al agente que use un servidor de MCP local para acceder a los archivos de la base de conocimiento local (sample/docs). Para aplicar este flujo de trabajo en tu entorno, puedes personalizar estos archivos de configuración para conectar el agente a tus wikis internos, repositorios de código, Google Drive o cualquier otro sistema.

El directorio sample/config/ contiene los siguientes archivos:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md: Aumenta las instrucciones de referencia del agente con detalles relevantes para tu organización, como indicarle que busque una base de conocimiento específica.
  • mcp.json: Configura los servidores de MCP que el agente puede usar para acceder a las herramientas de tus fuentes de información, como una herramienta para leer archivos de un directorio local.
  • SKILL.md: Describe cómo el agente debe usar herramientas específicas para interactuar con una fuente de información, como usar list_contents, read_file y search_content para encontrar información en documentos locales.

Explora el código de Knowledge Catalog de muestra

Las herramientas download y publish de la sección de flujo de enriquecimiento usan las APIs de Knowledge Catalog para leer y escribir metadatos.

En esta sección, se explica cómo funcionan estas APIs para que puedas adaptar la muestra a tus propias integraciones.

Busca y recupera metadatos

La muestra usa las siguientes APIs para buscar y recuperar metadatos:

  • SearchEntries para recuperar los metadatos de entrada y ubicación del conjunto de datos.
  • ListEntries para enumerar las tablas de BigQuery dentro de un EntryGroup del catálogo.
  • GetEntry para recuperar los metadatos específicos de cada tabla de BigQuery.

En el siguiente código, se muestra cómo buscar un conjunto de datos para ubicar su grupo de entradas, enumerar todas las tablas contenidas y recuperar sus metadatos específicos:

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

Actualizar metadatos de tablas

En el siguiente código, se muestra cómo publicar la documentación generada en el aspecto Descripción general de una tabla y actualizar sus metadatos:

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

¿Qué sigue?