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 allez également utiliser l'extension d'enrichissement du contexte de base de données.

Pour en savoir plus sur les ensembles de contexte, consultez 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, remplissez les conditions préalables suivantes.

Activer les services requis

Activez les services suivants pour votre projet :

Préparer une instance Cloud SQL

Assurez-vous d'avoir accès à une instance Cloud SQL existante ou créez-en une. Pour en savoir plus, consultez Créer des instances pour Cloud SQL.

Ce tutoriel nécessite que vous disposiez d'une base de données dans votre instance Cloud SQL. Pour en savoir plus, consultez Créer une base de données sur l'instance Cloud SQL.

Rôles et autorisations nécessaires

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 projet Google Cloud .
  • INSTANCE_ID : ID de votre instance Cloud SQL.
Pour effectuer 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 votre environnement

Vous pouvez créer des fichiers de contexte d'agent à 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 la CLI Gemini, consultez Premiers pas avec la CLI Gemini.

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 et 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 base de données, consultez Extension d'enrichissement du contexte de base de données.

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

  1. Installez l'extension Gemini CLI de MCP Toolbox :

    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 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, l'extraction de schémas et l'exécution d'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) pour fournir les identifiants utilisateur à deux composants principaux :

  • Serveur MCP Toolbox : utilise les identifiants pour se connecter à votre base de données, récupérer les schémas et exécuter le code SQL pour la validation.
  • Extension d'enrichissement du contexte de 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 à une base de données pour générer du contexte. Cette connexion est prise en charge par MCP Toolbox et définie dans le fichier de configuration tools.yaml.

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

  1. Lancez Gemini CLI :

    gemini

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

    /skills

  3. Saisissez une requête, telle que help me setup the database connection. 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 Toolbox.

    /mcp reload

Pour en savoir plus sur la configuration manuelle du fichier tools.yaml, consultez Configuration de MCP Toolbox.

Générer le contexte

Les extensions installées précédemment permettent à Gemini CLI de vous aider à créer du 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 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. Suivez la procédure de 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 à l'emploi :

    /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 de définition du 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 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 de l'ensemble de contexte, vous pouvez utiliser la commande /generate_targeted_facets.

Pour ajouter un aspect au fichier de l'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 le facette générée. Vous pouvez enregistrer le facette dans un fichier d'ensemble de contextes ou l'ajouter à un fichier d'ensemble de contextes existant.

Le fichier de définition du 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 de définition du contexte et les facettes, consultez 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 postgresql pour sélectionner AlloyDB comme moteur de base de données.

  2. Saisissez la version de PostgreSQL que vous souhaitez utiliser. Sélectionnez default pour sélectionner PostgreSQL 16.

  1. Saisissez la configuration de 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 se trouve 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).

    • 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 entre deux valeurs de chaîne. Idéal pour les ID uniques, les codes et les clés primaires.
      • TRIGRAM_STRING_MATCH : pour la correspondance approximative qui calcule la distance trigramme normalisée. Idéal pour les recherches d'utilisateurs et la correction de noms.
      • 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 Google compatibles, consultez Modèles Google compatibles. Pour utiliser SEMANTIC_SIMILARITY_MATCH, vous devez activer les extensions vector et google_ml_integration.

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

  2. Ajoutez d'autres recherches de valeurs si nécessaire. Si vous ne souhaitez pas ajouter d'autres index de valeurs, la génération de code SQL basée sur le modèle passe à l'étape suivante.

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

Le fichier de définition du 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 des valeurs, consultez Présentation des ensembles de contexte.

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

Si vous souhaitez générer automatiquement le fichier de contexte en fonction du schéma et des données de votre 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 du schéma de votre base de données, la génération de code SQL basée sur des modèles vous guide à travers 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 modifier une paire de requêtes que vous souhaitez réviser.

  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é sous forme de fichier JSON dans votre répertoire local.

Le fichier de définition du 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 de définition du contexte, consultez Présentation des ensembles de contexte.

Étapes suivantes