Créer un agent pour enrichir vos métadonnées

Knowledge Catalog (anciennement Dataplex Universal Catalog) gère les métadonnées des actifs de données dans toute l'organisation. Ces métadonnées fournissent le contexte que les agents utilisent pour découvrir, comprendre et interroger les données nécessaires pour répondre aux questions des utilisateurs.

Bien que Knowledge Catalog gère automatiquement les ressources, effectue le suivi des schémas techniques et génère des descriptions et des profils de données, un contexte métier précieux réside souvent dans d'autres emplacements, tels que :

  • Les documents et wikis internes
  • Les dépôts de code
  • Les canaux de communication tels que Google Chat et Slack

Vous pouvez créer des agents d'IA pour extraire le contexte de ces sources et enrichir en continu vos métadonnées à grande échelle. Ce tutoriel utilise un exemple de code du dépôt dataplex-labs pour vous montrer comment créer un agent qui effectue les opérations suivantes :

  • Extraire le contexte : extrait le contexte métier des bases de connaissances, des documents, du code ou des discussions pour enrichir les métadonnées techniques.
  • Générer de la documentation : génère de la documentation pour les tables BigQuery en fonction du contexte extrait et d'autres sources d'informations.
  • Améliorer la recherche et la découverte : publie la documentation générée dans Knowledge Catalog, ce qui permet de trouver et de comprendre plus facilement les entrées grâce à la recherche.

Avant de commencer

Pour exécuter l'agent d'enrichissement Knowledge Catalog, vous devez remplir les conditions suivantes :

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'agent d'enrichissement, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre Google Cloud projet iam.gserviceaccount.com:

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour utiliser l'agent d'enrichissement. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour utiliser l'agent d'enrichissement :

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Pour utiliser l'agent d'enrichissement Knowledge Catalog, activez les API suivantes dans votre projet :

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

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

Activer les API

Installer des dépendances

Vous avez besoin des packages et outils Python suivants pour exécuter l'exemple :

  • google-adk (Agent Development Kit (ADK))
  • google-cloud-dataplex Client Python Knowledge Catalog
  • google-auth gère les identifiants par défaut de l'application
  • mcp[cli] pour créer un exemple de serveur MCP
  • gcloud pour l'authentification et la configuration. Pour installer Google Cloud CLI, consultez la documentation sur Google Cloud SDK.

Configurer l'environnement

  1. Configurez gcloud et connectez-vous :

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

    Remplacez les éléments suivants :

    • PROJECT_ID par l'ID de votre projet

  2. Clonez le dépôt dataplex-labs et accédez au répertoire source de l'exemple :

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

  3. Pour installer les dépendances, utilisez le script fourni qui configure un environnement virtuel Python et les variables d'environnement nécessaires :

    source env.sh --install

  4. Pour créer un exemple d'ensemble de données BigQuery nommé kc_sample_analytics dans la région us de votre projet cloud, exécutez le script create_data.py :

    python3 ../sample/data/create_data.py

    L'exemple inclut également un certain nombre de documents dans le répertoire sample/docs. Ces documents forment une base de connaissances locale. L'agent d'enrichissement utilise cette base de connaissances pour extraire des informations et générer de la documentation.

Télécharger les métadonnées

Commencez par exécuter l'outil de téléchargement pour extraire un instantané des métadonnées de Knowledge Catalog pour l'ensemble de données BigQuery et ses tables. Cette opération crée des artefacts de métadonnées locaux.

L'argument --dir spécifie le répertoire dans lequel les fichiers de métadonnées sont écrits.

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

Le script crée un fichier Markdown par table dans le répertoire sample/metadata en utilisant la convention d'attribution de noms suivante : <project_id>.<dataset_id>.<table_id>.md.

Enrichir les métadonnées

Une fois les fichiers Markdown locaux créés, exécutez l'agent d'enrichissement. L'agent itère sur chaque fichier, recherche les informations pertinentes pour les tables et résume les résultats avec des citations pour générer des fichiers Markdown mis à jour.

  • --dir : spécifie le répertoire contenant les fichiers de métadonnées locaux.
  • --output-dir : spécifie le répertoire cible pour les fichiers de métadonnées mis à jour.
  • --config-dir : spécifie le répertoire contenant les instructions de l'agent, les outils MCP et les compétences.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Examiner les métadonnées

Les fichiers de métadonnées enrichis contiennent la documentation produite par l'agent. Examinez et modifiez les fichiers si nécessaire avant de publier les modifications dans Knowledge Catalog.

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

Publier les métadonnées

Exécutez l'outil de publication pour déployer les métadonnées enrichies dans Knowledge Catalog.

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

Personnaliser pour vos données

À l'étape précédente, vous avez utilisé l'argument --config-dir pour indiquer à l'agent le répertoire ../sample/config pour sa configuration. C'est ainsi que l'agent sait où trouver des informations et comment interagir avec différentes sources.

L'exemple est fourni avec une configuration par défaut qui indique à l'agent d'utiliser un serveur MCP local pour accéder aux fichiers de la base de connaissances locale (sample/docs). Pour appliquer ce workflow dans votre environnement, vous pouvez personnaliser ces fichiers de configuration afin de connecter l'agent à vos wikis internes, dépôts de code, Google Drive ou autres systèmes.

Le répertoire sample/config/ contient les fichiers suivants :

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md : augmente les instructions de base de l'agent avec des informations pertinentes pour votre organisation, par exemple en lui indiquant de rechercher une base de connaissances spécifique.
  • mcp.json : configure les serveurs MCP que l'agent peut utiliser pour accéder aux outils de vos sources d'informations, par exemple un outil permettant de lire des fichiers à partir d'un répertoire local.
  • SKILL.md : décrit comment l'agent doit utiliser des outils spécifiques pour interagir avec une source d'informations, par exemple en utilisant list_contents, read_file et search_content pour trouver des informations dans des documents locaux.

Explorer l'exemple de code Knowledge Catalog

Les outils download et publish de la section sur le flux d'enrichissement utilisent les API Knowledge Catalog pour lire et écrire des métadonnées.

Cette section explique le fonctionnement de ces API afin que vous puissiez adapter l'exemple à vos propres intégrations.

Rechercher et récupérer des métadonnées

L'exemple utilise les API suivantes pour rechercher et récupérer des métadonnées :

  • SearchEntries pour récupérer les métadonnées d'entrée et d'emplacement de l'ensemble de données.
  • ListEntries pour énumérer les tables BigQuery dans un EntryGroup de catalogue.
  • GetEntry pour récupérer les métadonnées spécifiques de chaque table BigQuery.

Le code suivant montre comment rechercher un ensemble de données pour localiser son groupe d'entrées, lister toutes les tables qu'il contient et récupérer leurs métadonnées spécifiques :

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

Mettre à jour les métadonnées d'une table

Le code suivant montre comment publier la documentation générée dans l'aspect « Présentation » d'une table et mettre à jour ses métadonnées :

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

Étape suivante