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

Les agents d'IA peuvent raisonner, mais ils ne disposent d'aucune connaissance sur votre entreprise. Imaginez que vous demandiez à un agent : "Quel est notre chiffre d'affaires au premier trimestre ?" Sans indication, l'agent peut choisir parmi des dizaines de tables nommées "chiffre d'affaires" 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 fausses convaincantes 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 et utiliser Gemini CLI pour tester le contexte des données et vérifier qu'un agent peut baser ses réponses sur des données fiables et certifiées.

Objectifs

• Créer un lac de données réaliste pour les tests
• Utiliser les aspects Knowledge Catalog aspects pour étiqueter vos données "or" et les distinguer des données de test
• Tester le contexte de vos données localement avec Gemini CLI

Avant de commencer

Avant de commencer, assurez-vous d'effectuer les opérations 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 une connaissance de base de BigQuery, de Knowledge Catalog et de 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 Google Cloud console, cliquez sur Activer Cloud Shell en haut à droite de la barre d'outils. 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 spécifique Google Cloud .

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

3. Activez les services nécessaires Google Cloud .

   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 Google Cloud dépôt DevRel Demos.

   Téléchargez le code d'infrastructure et les scripts depuis GitHub. Utilisez une extraction partielle 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 désordonnées non fiables. Utilisez Terraform et les fichiers de configuration Terraform préconfigurés du dépôt du tutoriel pour configurer rapidement cet environnement.

La configuration Terraform gère deux tâches :

• Configure les types d'aspects Knowledge Catalog (modèles de métadonnées), les ensembles de données et les tables BigQuery, 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. Cette opération peut prendre jusqu'à une minute.

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

Vous disposez maintenant d'un lac de données non géré. Pour un agent d'IA, les tables de votre lac de données se ressemblent exactement, 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 la partie la plus importante de la configuration. Pour le moment, vos deux tables sont identiques pour un agent d'IA. Pour les distinguer, vous appliquez des aspects, qui sont comme des étiquettes de métadonnées certifiées 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 jointes à 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. Cela fournit à l'agent d'IA des règles claires et structurées à suivre.

2. Exécutez le script apply_governance.sh. Ce script parcourt vos tables BigQuery et utilise la CLI gcloud pour "marquer" 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 Google Cloud console. 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 de la table 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 maintenant 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 le contexte de vos données avec Gemini CLI

Avant de créer une application Web complète, vous pouvez tester votre logique de gouvernance localement à l'aide d'un environnement MCP (Model Context Protocol). Dans cette configuration, Gemini CLI agit en tant que client (l'interface à laquelle vous vous adressez) et l'extension Knowledge Catalog agit en tant que 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 avec les étiquettes de gouvernance appropriées.

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

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 comment fonctionne le contexte des données, examinez rapidement le 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 étiquettes de gouvernance appropriées (phase 1) avant d'être autorisé à toucher les données elles-mêmes (phase 2). Cette logique "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 ce n'est pas le cas, l'agent ne saura pas où rechercher vos données.

Démarrer Gemini CLI et tester des scénarios

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

gemini

Remarque : Vous verrez peut-être plusieurs fichiers de contexte se charger (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 doit apparaître dans la liste des outils de serveur MCP configurés.

/mcp desc

Essayer

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

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

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

Vérifiez si Gemini CLI peut trouver les données les plus fiables pour une réunion du conseil d'administration à enjeux élevés.

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, elle fait correspondre 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 voulez vous assurer que la CLI ne laisse pas échapper de secrets internes.

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 contient le plus de détails, la CLI doit la contourner. Elle doit 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 dernières informations. Vérifiez si Gemini CLI 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 doit trouver mkt_realtime_campaign_performance. Elle identifie la fréquence de mise à jour REALTIME_STREAMING dans les métadonnées.

Scénario 4 : Exploration du bac à sable

Parfois, "suffisamment bien" vaut mieux que "parfait". Vérifiez si Gemini CLI peut trouver les données brutes du bac à sable pour certains travaux d'IA 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 doit trouver tmp_data_dump_v2_final_real. Elle 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, procédez comme suit :

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 fonctionne localement à l'aide de Gemini CLI.