Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Utiliser l'interface de ligne de commande Antigravity 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 configurez des aspects qui fournissent ce contexte et utilisez la CLI Antigravity 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

Déployer un lac de données réaliste à plusieurs niveaux dans BigQuery à des fins de test.
Concevoir et enregistrer des modèles de métadonnées personnalisés (types d'aspects) dans Knowledge Catalog pour distinguer les produits de données officiels des tables de bac à sable brutes.
Vérifier les règles de gouvernance des données et la base de l'agent d'IA à l'aide de la CLI Antigravity (agy).

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 sur votre projet.

Pour suivre ce tutoriel, vous devez également avoir une compréhension de base de BigQuery et de Knowledge Catalog.

Préparer votre environnement

Ce tutoriel utilise Google Cloud Shell, un environnement de ligne de commande qui s'exécute dans le cloud. La CLI Antigravity (agy) est préinstallée dans Google Cloud Shell.

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.
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"
```

Activez les services nécessaires Google Cloud .

gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

Clonez le Google Cloud dépôt DevRel Demos.

Téléchargez le code d'infrastructure et les scripts depuis GitHub. Utilisez un extrait clairsemé 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

Déployer un exemple de lac de données dans BigQuery

Les environnements de données réels sont rarement propres. Pour simuler la réalité, vous avez besoin d'un mélange de magasins de données "officiels" et de tables de bac à sable non fiables.

Vous utilisez 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ée trois ensembles de données BigQuery (finance_mart, marketing_prod, analyst_sandbox) et remplit leurs tables avec des exemples de données :

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Vous disposez maintenant d'un lac de données entièrement rempli, mais non géré. Pour un agent d'IA, toutes les tables se ressemblent.

Définir un type d'aspect personnalisé dans Knowledge Catalog

Vous allez maintenant définir les règles de gouvernance de vos données. Pour ce faire dans Knowledge Catalog, vous créez un type d'aspect, qui est un modèle de métadonnées fortement typé et réutilisable.

Dans cette section, vous enregistrez ce modèle à l'aide de la CLI gcloud afin de voir comment il est défini.

Inspecter le schéma du modèle 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 comment 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 un bool pour is_certified. Cela garantit que les métadonnées restent structurées et lisibles par machine.

Enregistrer le type d'aspect dans Knowledge Catalog

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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

Associer des aspects de gouvernance aux tables du lac de données

Il s'agit de l'étape d'ingénierie essentielle. Pour le moment, les tables finance_mart.fin_monthly_closing_internal et analyst_sandbox.tmp_data_dump_v2_final_real sont identiques pour un agent d'IA. Il s'agit simplement d'objets avec des colonnes.

Pour les distinguer, vous appliquez des aspects, qui associent des libellés de métadonnées certifiés à ces tables afin de les différencier. Dans une entreprise réelle, vous automatisez ce processus avec des pipelines CI/CD. Dans ce tutoriel, vous simulez cette automatisation avec des scripts.

Générer les charges utiles des métadonnées d'aspect

Les clés d'aspect Knowledge Catalog doivent être uniques au niveau mondial (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

Cela crée un répertoire aspect_payloads/ contenant quatre fichiers YAML définissant différents scénarios de gouvernance des données (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Associer des aspects aux tables BigQuery

Avant d'exécuter le script, examinez les données que vous associez aux tables. Exécutez la commande suivante pour afficher les métadonnées de 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 comment cela définit explicitement le contexte métier, par exemple en définissant is_certified: true et en attribuant le niveau GOLD_CRITICAL. Cela fournit à l'agent d'IA des règles claires et structurées à évaluer au lieu de deviner en fonction des noms de tables.
Exécutez le script d'application. Ce script parcourt vos tables BigQuery et utilise la commande gcloud dataplex entries update pour associer vos charges utiles de métadonnées à chaque table :
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

Vérifier les aspects appliqués dans la Google Cloud console

Avant de continuer, vérifiez que le script a correctement appliqué les aspects dans la Google Cloud console :

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.
Recherchez fin_monthly_closing_internal. Sélectionnez le nom de la table BigQuery dans les résultats pour ouvrir la page d'informations.
Dans la section Tags et aspects facultatifs en bas de la page, 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 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.

Tester le contexte de vos données avec la CLI Antigravity

Avant de créer une application, vous pouvez vérifier localement la logique de gouvernance de vos données avec la CLI Antigravity. Pour ce faire, installez le plug-in Knowledge Catalog et configurez la compétence de l'agent.

Installer le plug-in Knowledge Catalog

Dans Cloud Shell, installez le plug-in de service :

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Inspecter la définition de 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 des règles humaines abstraites telles que "J'ai besoin de données sécurisées" en recherches techniques structurées.

Pour vérifier la configuration de la compétence et comprendre le fonctionnement du contexte des données, inspectez le fichier SKILL.md :

cat .agents/skills/knowledge-catalog-governance/SKILL.md

Notez qu'il demande au modèle de suivre des boucles strictes de phase 1 (vérification des métadonnées) et de phase 2 (exécution des requêtes). Le modèle doit découvrir et vérifier les métadonnées avant de construire des instructions SQL. Cette logique de 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.

Démarrer la session de la CLI Antigravity

Démarrez la session de la CLI Antigravity. Comme vous vous trouvez dans le dossier du projet, la CLI découvre et charge automatiquement la compétence à partir du répertoire .agents/skills :

agy

Vérifier l'installation du plug-in dans la CLI

Dans l'invite de la CLI Antigravity, vérifiez que le plug-in est actif. Saisissez /mcp pour afficher la liste des outils et plug-ins configurés :

/mcp

knowledge-catalog doit s'afficher comme un plug-in actif avec ses outils disponibles :

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Exécuter des scénarios de vérification du contexte des données

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

Scénario 1 : Récupérer des données certifiées de niveau Gold

Vérifiez si la CLI Antigravity 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 : Limiter la récupération aux données approuvées en externe

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 : Récupérer des données de streaming en temps réel

Les data scientists ont souvent besoin des dernières informations. Vérifiez si la CLI Antigravity 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 : Explorer les données de bac à sable non certifiées

Parfois, "suffisamment bien" vaut mieux que "parfait". Vérifiez si la CLI Antigravity 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 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 de la CLI :

/quit

Libérer de l'espace

Pour éviter les frais récurrents, procédez comme suit :

Si vous êtes dans la session de la CLI Antigravity, quittez-la en appuyant deux fois sur Ctrl+C ou en saisissant /quit.
Exécutez le script de nettoyage pour détruire les tables, les ensembles de données et les types d'aspects Knowledge Catalog créés dans ce tutoriel :
```
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
```
Désinstallez le plug-in de service et supprimez vos fichiers de démonstration locaux :
```
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

Étape suivante

Découvrez d'autres cas d'utilisation de Knowledge Catalog.