1. Introduction
Les modèles d'IA générative sont de puissants raisonneurs, mais ils manquent de contexte institutionnel. Si un dirigeant demande à un agent d'IA "Quels sont nos revenus au premier trimestre ?", l'agent peut trouver des dizaines de tables nommées "revenus" dans votre lac de données. Certaines sont des rapports financiers rigoureux, d'autres des estimations marketing en temps réel, et beaucoup sont probablement des bacs à sable obsolètes.
Sans ancrage explicite, un agent d'IA sélectionne une table en fonction d'une simple similitude de nom, ce qui conduit à des réponses "convaincantes, mais erronées" , dérivées de données non vérifiées.
Cet atelier de programmation fait partie d'une série en deux parties qui explique comment créer un agent d'IA compatible avec la gouvernance.
Dans cette première partie, vous allez créer une base de données. Vous allez configurer un lac de données "désordonné" réaliste dans BigQuery, appliquer des tags de métadonnées rigides (aspects Knowledge Catalog) pour différencier les données valides du bruit, et utiliser l'interface de ligne de commande Antigravity (AGY) pour tester localement si l'agent suit strictement vos règles de gouvernance des données.
Vous pouvez lire la deuxième partie de cette série, qui explique comment déployer le prototype d'agent local dans une application Web sécurisée de niveau entreprise à l'aide du protocole MCP (Model Context Protocol) et de Cloud Run. 👉 Lire la partie 2
Points abordés
- Déployer un lac de données réaliste à plusieurs niveaux à l'aide d'un script de configuration.
- Concevoir et enregistrer des modèles de métadonnées personnalisés (types d'aspect) dans Knowledge Catalog pour distinguer les produits de données officiels des tables brutes du bac à sable.
- Vérifier localement les règles de gouvernance des données à l'aide de la CLI AGY avant d'écrire du code d'application.
Ce dont vous avez besoin
- Un projet Google Cloud avec facturation activée.
- Accès à Google Cloud Shell (la CLI AGY est préinstallée dans Cloud Shell).
- Connaissances de base sur BigQuery et Knowledge Catalog.
Concepts clés
- Knowledge Catalog : service unifié de gestion des métadonnées. Nous l'utilisons pour enrichir les métadonnées techniques (schémas) avec un contexte métier (gouvernance).
- Type d'aspect: modèle de métadonnées structuré. Contrairement aux tags en texte libre, les aspects appliquent un typage fort (énumérations, valeurs booléennes), ce qui les rend fiables pour l'évaluation par les machines.
2. Préparation
Démarrer Cloud Shell
Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.
Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :
Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :
Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.
Initialiser l'environnement
Ouvrez Cloud Shell et définissez les variables de votre projet pour vous assurer que toutes les commandes ciblent l'infrastructure appropriée.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
Activer les API
Activez les services Google Cloud nécessaires pour exécuter l'instruction suivante.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
Cloner le dépôt
Récupérez le code d'infrastructure et les scripts d'automatisation à partir du dépôt GitHub. Pour économiser de l'espace disque dans Cloud Shell, nous ne téléchargerons que le dossier spécifique nécessaire pour cet atelier.
# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
Créer le lac de données "désordonné"
Les environnements de données réels sont rarement propres. Pour simuler la réalité, nous avons besoin d'un mélange de data marts "officiels" et de tables "bac à sable" non fiables.
Nous allons utiliser un script de configuration pour déployer les ensembles de données et les tables BigQuery.
- Rendez le script de configuration exécutable et exécutez-le. Cela créera trois ensembles de données BigQuery (
finance_mart,marketing_prod,analyst_sandbox) et remplira leurs tables avec des exemples de données.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Point de contrôle : Vous disposez maintenant d'un lac de données entièrement rempli, mais complètement non géré. Pour une IA, chaque table est exactement la même.
3. Créer le modèle de gouvernance des données (type d'aspect)
Nous allons maintenant définir des règles de gouvernance des données. Dans Knowledge Catalog, cela se fait en créant un type d'aspect, qui est un modèle de métadonnées réutilisable et fortement typé.
Nous allons enregistrer ce modèle à l'aide de la CLI gcloud pour que vous puissiez voir comment il est défini.
Inspecter le schéma d'aspect
Affichez le contenu de aspect_template.json pour voir la définition du schéma.
cat aspect_template.json
La structure JSON suivante s'affiche :
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
...
}
]
}
Notez que ce schéma applique des types de données stricts, tels que enum pour le niveau de criticité (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) et bool pour is_certified. Cela garantit que les métadonnées restent structurées et lisibles par machine.
Enregistrer le type d'aspect
Exécutez la commande gcloud suivante pour enregistrer ce modèle dans votre registre Knowledge Catalog.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. Appliquer la gouvernance
Il s'agit de l'étape d'ingénierie critique. Actuellement, les tables finance_mart.fin_monthly_closing_internal et analyst_sandbox.tmp_data_dump_v2_final_real sont identiques pour un LLM. Il s'agit simplement d'objets avec des colonnes.
En tant qu'ingénieur en gouvernance, vous devez associer un aspect (un libellé de métadonnées certifié) à ces tables pour les différencier. Dans une entreprise réelle, vous automatisez ce processus via des pipelines CI/CD. Nous allons simuler cette automatisation avec des scripts.
Générer des charges utiles de gouvernance
Les clés d'aspect Knowledge Catalog doivent être globalement uniques (avec le préfixe de votre ID de projet). Le script ./generate_payloads.sh génère dynamiquement les fichiers de métadonnées YAML.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
Résultat :
Cela crée un dossier "./aspect_payloads" contenant quatre fichiers YAML, qui définissent les scénarios de gouvernance (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Appliquer des aspects avec la CLI
Avant d'exécuter le script, voyons ce que nous appliquons réellement pour démystifier le processus. Exécutez la commande suivante pour afficher la structure de la charge utile financière interne :
cat aspect_payloads/fin_internal.yaml
Le contenu suivant s'affiche.
your-project-id.us-central1.official-data-product-spec:
data:
product_tier: GOLD_CRITICAL
data_domain: FINANCE
usage_scope: INTERNAL_ONLY
update_frequency: DAILY_BATCH
is_certified: true
Notez que ce fichier YAML définit explicitement le contexte métier, par exemple en définissant l'indicateur is_certified sur "true" et en attribuant le niveau GOLD_CRITICAL. Cela permet de fournir au LLM des règles claires et structurées à évaluer au lieu de simplement deviner en fonction des noms de tables.
Exécutez maintenant le script d'application. Il parcourt les tables BigQuery et exécute la commande gcloud dataplex entries update pour associer ces métadonnées rigides.
chmod +x ./apply_governance.sh
./apply_governance.sh
Validation (facultative)
Avant de continuer, vérifiez que les métadonnées ont été correctement appliquées dans la console.
- Ouvrez la page Knowledge Catalog dans la console Google Cloud. Si vous ne voyez pas "Knowledge Catalog" dans le menu de navigation de gauche, utilisez la barre de recherche en haut de la fenêtre de la console Google Cloud, saisissez "Knowledge Catalog", puis sélectionnez le résultat sous "Meilleurs résultats" ou "Produits et pages".
- Recherchez
fin_monthly_closing_internal. La table BigQuery doit s'afficher dans les résultats. Cliquez sur le nom de la table pour accéder à sa page d'informations.
- Sur la page d'informations de la table, recherchez la section « Tags et aspects facultatifs » en bas de la page.
- Vous trouverez l'aspect
official-data-product-spec. Vérifiez que les valeurs correspondent au scénario Gold Internal que nous avons appliqué.
Vous avez maintenant confirmé que les tables BigQuery techniquement identiques (fin_monthly_closing_internal et tmp_data_dump_v2_final_real) sont logiquement différenciées par des métadonnées lisibles par machine.
5. Configurer et prototyper l'agent
Avant de créer une application (ce que nous ferons dans la partie 2), nous allons vérifier localement notre logique de gouvernance des données. Nous devons installer le plug-in Knowledge Catalog et configurer la compétence de l'agent.
Installer l'extension
Dans Cloud Shell, installez le plug-in Knowledge Catalog. Vous devrez confirmer et fournir les détails de votre configuration.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
Inspecter la compétence de l'agent
La compétence de l'agent est un fichier de définition statique et réutilisable situé dans .agents/skills/knowledge_catalog_governance/SKILL.md. Il contient la logique qui traduit les règles humaines abstraites (par exemple, "J'ai besoin de données sécurisées") en recherches techniques strictes.
Inspectez le fichier pour comprendre l'algorithme que nous enseignons à l'IA :
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Notez qu'il indique explicitement au modèle de suivre une boucle stricte en phase 1 (vérification des métadonnées) et en phase 2 (exécution de la requête). Le modèle doit découvrir et vérifier les métadonnées avant de construire du code SQL.
Démarrer l'agent et tester des scénarios
Démarrez la session CLI AGY. Elle découvre et charge automatiquement la compétence à partir du répertoire .agents/skills.
agy
Remarque : Il est possible que plusieurs fichiers de contexte soient chargés. Ceci est normal. La CLI charge la compétence locale pour les règles spécifiques de ce projet, ainsi que les instructions par défaut pour le plug-in Knowledge Catalog lui-même.
Vérifier l'installation
Saisissez /mcp pour vérifier que le plug-in Knowledge Catalog est actif. knowledge-catalog doit s'afficher comme plug-in actif avec ses outils disponibles.
/mcp
Résultat attendu :
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Scénarios de test (prototypage)
Collez les invites suivantes dans la session d'agent en cours d'exécution, une par une, pour vérifier qu'elle respecte vos règles.
- Scénario A (certifier les données du directeur financier) :
"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"
Résultat attendu : L'agent découvre automatiquement votre projet et votre région actifs à partir de ses outils, interroge fin_monthly_closing_internal car il correspond sémantiquement à GOLD_CRITICAL (précis) et INTERNAL_ONLY (réunion du conseil d'administration) dans son aspect, et le recommande.
- Scénario B (divulgation publique) :
"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"
Résultat attendu : L'agent doit contourner la table interne mensuelle et sélectionner strictement fin_quarterly_public_report, car il s'agit du seul élément tagué EXTERNAL_READY.
- Scénario C (besoins opérationnels) :
"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"
Résultat attendu : L'agent sélectionne mkt_realtime_campaign_performance, car il identifie la fréquence de mise à jour REALTIME_STREAMING, en la privilégiant par rapport au niveau GOLD_CRITICAL des données financières.
- Scénario D (expérimentation dans le bac à sable) :
"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."
Résultat attendu : L'agent sélectionne tmp_data_dump_v2_final_real, car il correspond sémantiquement à BRONZE_ADHOC (données brutes) et is_certified: false (environnement de bac à sable) dans son aspect.
(Pour quitter la session AGY, saisissez /exit ou /quit)
6. Félicitations ! Étape suivante
Vous avez créé une base de données gérée et prouvé qu'une IA peut suivre strictement vos règles de métadonnées à l'aide d'un prototype de CLI local.
Vous avez maintenant atteint un point de contrôle. Veuillez choisir l'étape suivante :
Option A : Je veux passer à la partie 2 tout de suite.
Si vous êtes prêt à transformer ce prototype local en une application Web sécurisée de qualité production à l'aide du protocole MCP (Model Context Protocol) et de Cloud Run :
👉 Lien vers l'atelier de programmation de la partie 2
Option B : Je ferai la partie 2 plus tard ou je voulais seulement terminer la partie 1.
Si vous souhaitez vous arrêter pour aujourd'hui et éviter les coûts cloud, vous devez nettoyer vos ressources.
Pas de panique ! Dans la partie 2, nous fournirons un "script accéléré" qui recréera complètement cet environnement de la partie 1 en seulement deux minutes afin que vous puissiez reprendre exactement là où vous vous étiez arrêté.
👉 Passez à la section de nettoyage.
7. Libérer de l'espace (pour l'option B uniquement)
Si vous vous arrêtez ici, détruisez les ressources pour éviter que des frais ne vous soient facturés.
Détruire le lac de données
Si vous êtes actuellement dans la session CLI AGY, quittez-la en appuyant deux fois sur Ctrl+C ou en saisissant /quit. Exécutez ensuite les commandes suivantes :
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
Désinstaller le plug-in CLI AGY et supprimer les fichiers locaux
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos