Créer des ensembles de contextes à l'aide de Gemini CLI

Ce document explique comment utiliser Gemini CLI et la boîte à outils MCP pour créer des fichiers de contexte d'agent. Ces fichiers contiennent des modèles, des facettes et des recherches de valeurs qui fournissent un contexte pour générer des requêtes SQL à partir du langage naturel. Vous utiliserez également l'extension d'enrichissement du contexte de la base de données.

Pour en savoir plus sur les ensembles de contexte, consultez la présentation des ensembles de contexte.

Pour créer un fichier de contexte d'agent, procédez comme suit :

  • Préparer votre environnement
  • Générer des modèles ciblés
  • Générer des facettes ciblées
  • Générer des recherches de valeurs ciblées
  • Facultatif. Générer des modèles groupés

Avant de commencer

Avant de créer un agent, respectez les conditions préalables suivantes.

Activer les services requis

Activez les services suivants pour votre projet :

Préparer une instance Cloud SQL

Rôles et autorisations requis

Accorder l'autorisation executesql à l'instance Cloud SQL

Pour accorder l'autorisation executesql à l'instance Cloud SQL et activer l'API Cloud SQL Data, exécutez la commande suivante : 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Remplacez les éléments suivants :
  • PROJECT_ID : ID de votre Google Cloud projet.
  • INSTANCE_ID : ID de votre instance Cloud SQL.
Pour suivre les étapes de ce tutoriel, connectez-vous à Google Cloud, puis authentifiez-vous auprès de la base de données à l'aide de l'authentification IAM.

Préparer la base de données pour les recherches de valeurs

Pour utiliser les recherches de valeurs sémantiques et trigrammes, vous devez configurer votre instance Cloud SQL pour MySQL afin qu'elle prenne en charge les embeddings vectoriels et l'indexation n-gram.

  1. Pour que l'instance Cloud SQL pour MySQL puisse effectuer des recherches de valeurs sémantiques, vous devez activer les options suivantes.

    1. Activez l'option cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Activez l'option enable-google-ml-integration pour permettre à l'instance Cloud SQL pour MySQL de s'intégrer à Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Créez une colonne vectorielle pour stocker les embeddings de ville.

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Générez et stockez des embeddings vectoriels pour les noms de villes.

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Pour que l'instance Cloud SQL pour MySQL puisse effectuer des recherches de valeurs trigrammes, procédez comme suit.

    1. Activez l'option ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Créez un index FULLTEXT pour la correspondance trigramme sur le nom de l'aéroport.

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Préparer votre environnement

Vous pouvez créer des fichiers d'ensemble de contexte à partir de n'importe quel environnement de développement local ou IDE. Pour préparer l'environnement, procédez comme suit :

  • Installer Gemini CLI
  • Installer l'extension d'enrichissement du contexte de la base de données
  • Configurer la connexion à la base de données

Installer Gemini CLI

Pour installer Gemini CLI, consultez Premiers pas avec Gemini CLI.

Installer l'extension MCP d'enrichissement du contexte de la base de données

L'extension d'enrichissement du contexte de la base de données fournit un workflow interactif guidé pour générer un contexte NL2SQL structuré à partir de vos schémas de base de données.

Pour en savoir plus sur l'installation de l'extension d'enrichissement du contexte de la base de données, consultez la section Extension d'enrichissement du contexte de la base de données.

Pour installer l'extension d'enrichissement du contexte de la base de données, procédez comme suit :

  1. Installez l'extension Gemini CLI d'enrichissement du contexte de la base de données :

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

  2. (Facultatif) Mettez à jour l'extension d'enrichissement du contexte de la base de données.

    Pour vérifier la version installée de l'extension, exécutez la commande suivante :

    gemini extensions list

    Assurez-vous que la version est 0.4.2 ou supérieure. Pour mettre à jour l'extension d'enrichissement du contexte de la base de données, exécutez la commande suivante :

      gemini extensions update mcp-db-context-enrichment

    Pour mettre à jour l'extension d'enrichissement du contexte de la base de données ou remplacer la GEMINI_API_KEY, exécutez la commande suivante :

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Remplacez GEMINI_API_KEY par votre clé API Gemini.

Configurer la connexion à la base de données

L'extension nécessite la connexion à la base de données pour la génération de contexte afin d'extraire les schémas et d'exécuter des instructions SQL. Pour permettre à l'extension d'interagir avec votre base de données, vous devez configurer les identifiants d'authentification et définir vos sources et outils de base de données.

Configurer les identifiants par défaut de l'application

Vous devez configurer les identifiants par défaut de l'application (ADC, Application Default Credentials) pour fournir des identifiants utilisateur à deux composants principaux :

  • Serveur MCP de la boîte à outils : utilise des identifiants pour se connecter à votre base de données, extraire des schémas et exécuter des requêtes SQL à des fins de validation.
  • Extension d'enrichissement du contexte de la base de données : utilise des identifiants pour s'authentifier et appeler l'API Gemini.

Exécutez les commandes suivantes dans votre terminal pour vous authentifier :

gcloud auth application-default login

Configurer le fichier tools.yaml

L'extension nécessite une connexion à la base de données pour la génération de contexte, qui est prise en charge par la boîte à outils MCP et définie dans le fichier de configuration tools.yaml.

Le fichier tools.yaml spécifie votre source de base de données et les outils nécessaires pour extraire des schémas ou exécuter des requêtes SQL. L'extension est fournie avec des compétences d'agent préinstallées pour vous aider à générer la configuration.

  1. Démarrez Gemini CLI :

    gemini

  2. Vérifiez que les compétences sont actives en saisissant dans Gemini CLI : 

    /skills

  3. Saisissez un prompt tel que help me setup the database connection (Aidez-moi à configurer la connexion à la base de données). La compétence vous guide dans la création du fichier tools.yaml dans votre répertoire de travail actuel.

  4. Exécutez la commande suivante dans Gemini CLI pour appliquer la configuration tools.yaml au serveur MCP de la boîte à outils.

    /mcp reload

Pour en savoir plus sur la configuration manuelle du fichier tools.yaml, consultez la section Configuration de la boîte à outils MCP.

Générer un contexte

Les extensions installées précédemment permettent à Gemini CLI de vous aider à créer un contexte sous la forme d'un fichier JSON.

Générer des modèles ciblés

Si vous souhaitez ajouter une paire de requêtes spécifique en tant que modèle de requête à l'ensemble de contexte, vous pouvez utiliser la commande /generate_targeted_templates. Pour en savoir plus sur les modèles, consultez la présentation des ensembles de contexte.

Pour ajouter un modèle de requête à l'ensemble de contexte, procédez comme suit :

  1. Dans le même répertoire, démarrez Gemini CLI :

    gemini

  2. Effectuez la configuration de l'authentification Gemini CLI.

  3. Vérifiez que la boîte à outils MCP et l'extension d'enrichissement de la base de données sont prêtes à être utilisées :

    /mcp reload

  4. Exécutez la commande /generate_targeted_templates :

    /generate_targeted_templates

  5. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

  6. Saisissez la requête SQL correspondante dans le modèle de requête.

  7. Examinez le modèle de requête généré. Vous pouvez enregistrer le modèle de requête en tant que fichier d'ensemble de contexte ou l'ajouter à un fichier d'ensemble de contexte existant.

Le fichier d'ensemble de contexte semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier d'ensemble de contexte et le modèle de requête, consultez la présentation des ensembles de contexte.

Générer des facettes ciblées

Si vous souhaitez ajouter une paire de requêtes spécifique en tant que facette au fichier d'ensemble de contexte, vous pouvez utiliser la commande /generate_targeted_facets.

Pour ajouter une facette au fichier d'ensemble de contexte, procédez comme suit :

  1. Exécutez la commande /generate_targeted_facets :

    /generate_targeted_facets

  2. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

  3. Saisissez la requête SQL correspondante dans le modèle de requête.

  4. Examinez la facette générée. Vous pouvez enregistrer la facette dans un fichier d'ensemble de contexte ou l'ajouter à un fichier d'ensemble de contexte existant.

Le fichier d'ensemble de contexte semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier d'ensemble de contexte et les facettes, consultez la présentation des ensembles de contexte.

Générer des requêtes de recherche de valeurs

Si vous souhaitez générer des recherches de valeurs qui spécifient comment le système doit rechercher et faire correspondre des valeurs spécifiques dans un type de concept, vous pouvez utiliser la commande /generate_targeted_value_searches.

Assurez-vous de suivre les étapes décrites dans Préparer la base de données pour les recherches de valeurs.

Pour générer un index de valeurs, procédez comme suit :

  1. Exécutez la commande /generate_targeted_value_searches :

    /generate_targeted_value_searches
  1. Saisissez mysql pour sélectionner MySQL comme moteur de base de données. Sélectionnez "default" (par défaut) pour sélectionner MySQL 8.0.

  1. Saisissez la configuration de la recherche de valeurs comme suit :

    Table name: TABLE_NAME
Column name: COLUMN_NAME
Concept type: CONCEPT_TYPE
Match function: MATCH_FUNCTION
Description: DESCRIPTION

    Remplacez les éléments suivants :

    • TABLE_NAME : table dans laquelle existe la colonne associée au type de concept.
    • COLUMN_NAME : nom de la colonne associée au type de concept.
    • CONCEPT_TYPE : type de concept que vous souhaitez définir, par exemple City name (Nom de la ville).

    • MATCH_FUNCTION : fonction de correspondance à utiliser pour la recherche de valeurs. Vous pouvez utiliser l'une des fonctions suivantes :

      • EXACT_STRING_MATCH : pour une correspondance exacte de deux valeurs de chaîne. Idéal pour les ID, les codes et les clés primaires uniques.
      • TRIGRAM_STRING_MATCH : pour une correspondance approximative qui calcule la distance trigramme normalisée. Idéal pour les recherches utilisateur et la correction de noms. Pour utiliser TRIGRAM_STRING_MATCH, vous devez préparer votre base de données pour qu'elle prenne en charge l'indexation n-gram.
      • SEMANTIC_SIMILARITY_MATCH : pour la recherche sémantique sur les valeurs de chaîne. Idéal pour les recherches multilingues et de synonymes. Pour obtenir la liste des modèles compatibles, consultez la section Modèles Google compatibles. Pour utiliser SEMANTIC_SIMILARITY_MATCH, vous devez préparer votre base de données pour qu'elle prenne en charge les embeddings vectoriels.

    • DESCRIPTION : (facultatif) description de la requête de recherche de valeurs.

  2. Ajoutez d'autres recherches de valeurs si nécessaire. Si vous ignorez l'ajout d'index de valeurs supplémentaires, la génération SQL basée sur un modèle passe à l'étape suivante.

  3. Examinez les recherches de valeurs générées. Vous pouvez enregistrer l'ensemble de contexte en tant que fichier d'ensemble de contexte ou l'ajouter à un fichier d'ensemble de contexte existant.

Le fichier d'ensemble de contexte semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur l'index de valeurs, consultez la présentation des ensembles de contexte.

Facultatif : Générer des modèles groupés

Si vous souhaitez générer automatiquement le fichier d'ensemble de contexte en fonction de votre schéma et de vos données de base de données, vous pouvez utiliser la commande /generate_bulk_templates.

Pour générer automatiquement des modèles groupés, procédez comme suit :

  1. Exécutez la commande /generate_bulk_templates :

    /generate_bulk_templates

  2. En fonction de votre schéma de base de données, la génération SQL basée sur un modèle vous pose une série de questions liées à la vérification des informations de la base de données et à l'octroi d'autorisations d'accès au schéma de la base de données.

  3. Examinez le modèle de requête généré. Vous pouvez approuver le modèle ou mettre à jour une paire de requêtes que vous souhaitez modifier.

  4. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

  5. Saisissez la requête SQL correspondante dans le modèle de requête.

  6. Examinez le modèle de requête généré. Vous pouvez enregistrer le modèle de requête en tant que fichier d'ensemble de contexte ou l'ajouter à un fichier de contexte existant.

  7. Une fois que vous avez approuvé le modèle de requête, vous pouvez créer un fichier de modèle ou ajouter les paires de requêtes à un fichier de modèle existant. Le modèle de requête est enregistré en tant que fichier JSON dans votre répertoire local.

Le fichier d'ensemble de contexte semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier d'ensemble de contexte, consultez la présentation des ensembles de contexte.

Étape suivante