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 en bloc

Avant de commencer

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

Activer les services requis

Activez les services suivants pour votre projet :

Préparer une instance Spanner


Ce tutoriel nécessite que vous disposiez d'une base de données dans votre instance Spanner. Pour en savoir plus, consultez la page Créer une base de données.

Rôles et autorisations requis

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 la page 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 page 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 de la boîte à outils MCP :

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

  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 ulté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 requis 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 page 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.

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 spanner pour sélectionner Spanner comme moteur de base de données.

  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.

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

  2. Ajoutez d'autres recherches de valeurs si nécessaire. Si vous n'ajoutez pas 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 en bloc

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 en bloc, 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 le modèle de requête approuvé, 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