Utiliser l'agent Gemini CLI pour tester le contexte des données

Les agents IA peuvent raisonner, mais ils ne disposent d'aucune connaissance sur votre entreprise. Imaginez que vous demandiez à un agent : "Quels sont nos revenus pour le premier trimestre ?" Sans conseils, l'agent peut choisir parmi des dizaines de tables nommées "revenus" dans vos bases de données, allant des rapports officiels aux données de test désordonnées. Si l'agent choisit la table dont le nom est le plus proche, il peut renvoyer des réponses convaincantes, mais incorrectes, basées sur des sources non vérifiées.

L'enrichissement des métadonnées est la solution à ce problème de contexte. Dans ce tutoriel, vous allez configurer des aspects qui fournissent ce contexte, puis utiliser Gemini CLI pour tester le contexte des données et vérifier qu'un agent peut ancrer précisément ses réponses dans des données fiables et certifiées.

Objectifs

• Créez un lac de données réaliste pour les tests.
• Utilisez les aspects Knowledge Catalog pour étiqueter vos données "or" et les distinguer des données de test.
• Testez votre contexte de données en local avec Gemini CLI.

Avant de commencer

Avant de commencer, assurez-vous d'avoir effectué les actions suivantes :

• Choisissez un Google Cloud projet pour ce tutoriel.
• Vérifiez que la facturation est activée pour votre projet.

Pour suivre ce tutoriel, vous devez également avoir des connaissances de base sur BigQuery, le catalogue de connaissances et Terraform.

Préparer votre environnement

Ce tutoriel utilise Google Cloud Shell, un environnement de ligne de commande qui s'exécute dans le cloud.

1. Dans la console Google Cloud , cliquez sur Activer Cloud Shell dans la barre d'outils en haut à droite. Le provisionnement et la connexion à l'environnement prennent quelques instants.

2. Dans Cloud Shell, définissez vos variables PROJECT_ID et REGION afin que toutes les commandes futures ciblent votre projet Google Cloud spécifique.

   export PROJECT_ID=$(gcloud config get-value project)
   gcloud config set project $PROJECT_ID
   export REGION="us-central1"
   

3. Activez les services Google Cloud nécessaires.

   gcloud services enable \
     artifactregistry.googleapis.com \
     bigqueryunified.googleapis.com \
     cloudaicompanion.googleapis.com \
     cloudbuild.googleapis.com \
     cloudresourcemanager.googleapis.com \
     datacatalog.googleapis.com \
     run.googleapis.com
   

4. Clonez le dépôt de démonstrations DevRelGoogle Cloud .

   Téléchargez le code d'infrastructure et les scripts depuis GitHub. Utilisez un checkout sparse pour n'extraire que le dossier spécifique dont vous avez besoin pour ce tutoriel.

   # 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 you need for this tutorial
   git sparse-checkout set data-analytics/governance-context
   cd data-analytics/governance-context
   

Créer le lac de données

Pour que les choses soient réalistes, vous avez besoin d'un mélange de données officielles et de données non fiables et désordonnées. Pour configurer rapidement cette intégration, utilisez Terraform et les fichiers de configuration Terraform préconfigurés du dépôt du tutoriel.

La configuration Terraform gère deux tâches :

• Configure les types d'aspect (modèles de métadonnées) du catalogue de connaissances, les ensembles de données BigQuery et les tables, y compris finance_mart.fin_monthly_closing_internal et analyst_sandbox.tmp_data_dump_v2_final_real.
• Charge des exemples de données dans les tables.

1. Ouvrez le répertoire terraform et initialisez-le.

   cd terraform
   terraform init
   

2. Appliquez la configuration. Cela peut prendre jusqu'à une minute.

   terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

Vous disposez désormais d'un lac de données non gouvernées. Pour un agent d'IA, les tables de votre lac de données se présentent exactement de la même manière, car il s'agit simplement d'objets avec des colonnes. Pour résoudre ce problème, vous devez appliquer la gouvernance à l'étape suivante.

Appliquer la gouvernance

Il s'agit de l'étape la plus importante de la configuration. Pour le moment, vos deux tableaux sont identiques pour un agent IA. Pour les distinguer, vous appliquez des aspects, qui sont comme des libellés de métadonnées certifiés qui fournissent à l'agent le contexte dont il a besoin. Dans cette section, vous allez utiliser deux scripts : l'un pour générer les métadonnées et l'autre pour les appliquer à vos tables.

Générer des charges utiles de gouvernance

Terraform a déjà configuré les types d'aspects. Vous devez maintenant générer les données pour les remplir.

Exécutez le script ./generate_payloads.sh pour créer un répertoire aspect_payloads/. Le répertoire contient quatre fichiers YAML qui définissent différents scénarios de gouvernance, que vous appliquerez à l'étape suivante.

Revenez à la racine du répertoire du tutoriel et exécutez le script ./generate_payloads.sh :

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

Appliquer des aspects

1. Avant d'exécuter le script apply_governance.sh, examinez les données qui seront associées à vos tables. Exécutez la commande suivante pour afficher les métadonnées définies pour vos données financières internes :

   cat aspect_payloads/fin_internal.yaml
   

   Le fichier YAML définit le contexte métier de la table :

   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 cela marque explicitement les données comme is_certified: true et leur attribue le niveau GOLD_CRITICAL. L'agent d'IA dispose ainsi de règles claires et structurées à suivre.

2. Exécutez le script apply_governance.sh. Ce script parcourt vos tables BigQuery et utilise l'CLI gcloud pour "estampiller" les métadonnées de vos charges utiles YAML sur chaque table.

   chmod +x ./apply_governance.sh
   ./apply_governance.sh
   

Vérifier les métadonnées

Avant de continuer, vérifiez que le script a correctement appliqué les aspects.

1. Ouvrez la page Knowledge Catalog dans la console Google Cloud . Vous pouvez utiliser la barre de recherche en haut de la page pour trouver l'outil.
2. Recherchez fin_monthly_closing_internal. Sélectionnez le nom du tableau dans les résultats pour ouvrir sa page d'informations.
3. Dans la section Tags et aspects facultatifs, recherchez l'aspect official-data-product-spec. Vérifiez que les valeurs correspondent au scénario "Gold Internal" que vous avez appliqué.

Vous avez utilisé des métadonnées pour distinguer ces tables et vous avez donné à votre agent d'IA un moyen de faire de même.

Tester votre contexte de données avec la Gemini CLI

Avant de créer une application Web complète, vous pouvez tester votre logique de gouvernance en local à l'aide d'un environnement MCP (Model Context Protocol). Dans cette configuration, Gemini CLI fait office de client (l'interface avec laquelle vous interagissez) et l'extension Knowledge Catalog fait office de serveur local.

Installer l'extension Knowledge Catalog

Dans Cloud Shell, installez l'extension Knowledge Catalog.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

Définir des règles

Le fichier de configuration GEMINI.md contient une logique qui transforme des règles déclaratives telles que "J'ai besoin de données sécurisées" en recherches précises qui ne renvoient que des tables comportant les libellés de gouvernance appropriés.

Pour l'instant, le fichier de configuration n'est qu'un modèle. Vous devez ajouter l'ID de votre projet Google Cloud spécifique aux règles afin que, lorsque vous exécutez la CLI, elle cible correctement vos données régies.

1. Ajoutez votre PROJECT_ID au fichier de configuration.

   envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md
   

2. Pour vérifier vos modifications et comprendre le fonctionnement du contexte de données, jetez un coup d'œil au fichier GEMINI.md :

   cat GEMINI.md
   

   Notez que le fichier divise les règles en phase 1 et phase 2. Cela impose un ordre strict des opérations. L'agent doit d'abord rechercher les libellés de gouvernance appropriés (phase 1) avant d'être autorisé à toucher les données elles-mêmes (phase 2). Cette logique "search-first" (recherche d'abord) empêche l'agent de deviner les noms de tables ou de générer des réponses à partir de sources non vérifiées.

   Assurez-vous que la phase 2 contient l'ID de votre projet Google Cloud . Si cette information est incorrecte, l'agent ne saura pas où chercher vos données.

Démarrer la Gemini CLI et tester des scénarios

Démarrez une nouvelle session Gemini. Étant donné que vous vous trouvez dans le dossier du projet, la CLI détecte et charge automatiquement le GEMINI.md local en tant que contexte système.

gemini

Remarque : Il est possible que plusieurs fichiers de contexte se chargent (par exemple, GEMINI.md et d'autres). Ceci est normal. La CLI charge le fichier GEMINI.md local pour les règles spécifiques de ce projet, ainsi que les instructions par défaut pour l'extension Knowledge Catalog elle-même.

Vérifier l'installation

Vérifiez que l'extension Knowledge Catalog est active. dataplex devrait apparaître dans la liste des outils de serveur MCP configurés.

/mcp desc

Essayer

Il est maintenant temps de voir votre contexte de données en action. Collez ces invites dans la CLI une par une.

Remarque : La CLI demande l'autorisation d'utiliser ses outils. Sélectionnez 2. Autoriser l'outil pour cette session" pour ne pas avoir à approuver chaque étape.

Scénario 1 : Rechercher des données de référence

Découvrez si Gemini CLI peut trouver les données les plus fiables pour une réunion du conseil d'administration à fort enjeu.

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?

La CLI doit ignorer les données brutes et trouver fin_monthly_closing_internal. Pour ce faire, il compare votre demande de données "finalisées" et "confidentielles" aux tags GOLD_CRITICAL et INTERNAL_ONLY que vous avez appliqués précédemment.

Scénario 2 : Divulgation publique

Imaginez que vous souhaitez partager des données en externe. Vous devez vous assurer que l'CLI ne divulgue aucun secret interne.

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?

Même si la table interne est la plus détaillée, la CLI doit la contourner. Il devrait vous rediriger vers fin_quarterly_public_report, car il s'agit de la seule table taguée comme EXTERNAL_READY.

Scénario 3 : Besoins opérationnels en temps réel

Les data scientists ont souvent besoin des informations les plus récentes. Voyez si la CLI Gemini comprend la différence entre un lot quotidien et un flux en direct.

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?

La CLI devrait trouver mkt_realtime_campaign_performance. Elle identifie la fréquence de mise à jour de REALTIME_STREAMING dans les métadonnées.

Scénario 4 : Exploration du bac à sable

Parfois, "suffisant" est préférable à "parfait". Vérifiez si la CLI Gemini peut trouver les données brutes du bac à sable pour certains travaux de ML expérimentaux.

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.

La CLI devrait trouver tmp_data_dump_v2_final_real. Il sait qu'il s'agit du bon choix, car il correspond au niveau BRONZE_ADHOC et est explicitement marqué avec is_certified: false.

Une fois les tests terminés, vous pouvez quitter la session CLI :

/quit

Effectuer un nettoyage

Pour éviter les frais récurrents :

1. Détruisez les ressources Terraform.

   cd ~/devrel-demos/data-analytics/governance-context/terraform
   terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

2. Désinstallez l'extension Knowledge Catalog et supprimez vos fichiers de démonstration locaux.

   gemini extensions uninstall dataplex
   cd ~
   rm -rf ~/devrel-demos
   

Conclusion

Vous avez créé une base de données solide, appliqué un contexte strict à l'aide de métadonnées et vérifié que tout fonctionnait en local à l'aide de Gemini CLI.

Étapes suivantes

• Essayez d'autres cas d'utilisation de Knowledge Catalog.