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

Ce document explique comment créer et optimiser le contexte qui vous permet d'améliorer la précision de QueryData pour créer vos applications d'agent de données. L'extension d'enrichissement du contexte de base de données dans Gemini CLI donne accès à une suite d'outils pour les développeurs qui automatisent la création et l'optimisation des ensembles de contextes.

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

L'extension automatise la création et l'optimisation des ensembles de contexte dans l'ordre suivant :

  1. Comprendre les applications : ingérez des artefacts tels que des schémas de base de données, du code d'application et des exigences métier pour établir la logique métier de base de votre agent de données.
  2. Créez des ensembles de données : créez un ensemble de données d'évaluation contenant des questions représentatives en langage naturel et les réponses SQL attendues. Il est essentiel d'établir cet ensemble de données de référence pour mesurer les performances et suivre les améliorations au fil du temps.
  3. Générez un contexte initial : générez automatiquement un ensemble de contexte de base directement à partir du schéma de votre base de données et des artefacts d'application facultatifs pour démarrer rapidement.
  4. Optimisez le contexte de manière itérative : évaluez votre ensemble de données pour identifier la raison de l'échec de certaines requêtes. Gemini utilise le raisonnement automatique pour suggérer des mises à jour ciblées du contexte, ce qui permet d'améliorer progressivement la précision.

Bien que l'extension offre un workflow automatisé robuste, elle s'adapte à vos besoins. Vous pouvez contourner l'automatisation pour créer et insérer du contexte de manière plus précise. Grâce à des commandes de génération spécialisées, vous contrôlez la création de modèles, de facettes et de requêtes de recherche de valeurs de haute qualité.

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 d'ensemble de contexte à partir de n'importe quel environnement de développement local ou IDE. Pour préparer votre 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 d'enrichissement du contexte de la base de données

L'extension d'enrichissement du contexte de base de données fournit un workflow interactif et guidé pour générer des ensembles de contexte structurés et les itérer.

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 pour l'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.5.0 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 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 une connexion à une base de données pour extraire les schémas et valider la syntaxe du contexte SQL généré. Pour permettre à l'extension d'interagir avec votre base de données, configurez les identifiants d'authentification et définissez la configuration de la connexion à votre base de données.

Configurer les identifiants par défaut de l'application

Configurez les identifiants par défaut de l'application (ADC) pour fournir les identifiants utilisateur pour 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 de connexion à la base de données

L'extension nécessite une connexion à une base de données pour générer le contexte. La boîte à outils MCP est compatible avec cette connexion et la définit dans un fichier de configuration.

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

  1. Lancez la CLI Gemini :

    gemini

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

    /skills

  3. Saisissez une requête, par exemple help me set up the database connection. La skill vous guide pour créer le fichier de configuration autoctx/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 de configuration de la base de données, consultez Configuration de MCP Toolbox.

Générer le contexte avec un workflow automatisé

L'amélioration de la précision grâce à l'ingénierie du contexte est généralement un processus manuel d'essais et d'erreurs. Les développeurs devinent souvent pourquoi une requête a échoué, écrivent une correction et la testent manuellement. L'extension d'enrichissement du contexte de la base de données dans la CLI Gemini automatise ce processus d'amélioration. Il utilise des ensembles de données d'évaluation (ensembles de questions avec leurs réponses SQL correctes) pour mesurer les performances et identifier les raisons pour lesquelles certaines requêtes échouent. Gemini suggère ensuite automatiquement des mises à jour spécifiques du contexte pour améliorer la précision. Suivez ces étapes pour améliorer systématiquement la précision de votre agent de données.

Initialiser un espace de travail

La commande d'initialisation configure votre espace de travail local, y compris la configuration de la connexion à la base de données et le répertoire de test. Cet espace de travail dédié permet de regrouper toutes les configurations, les expériences et les fichiers générés, ce qui facilite la gestion et le suivi de vos efforts d'optimisation du contexte.

  1. Créez un répertoire qui servira d'espace de travail pour le flux d'optimisation itérative, puis accédez-y.

  2. Démarrez la CLI Gemini dans le nouveau répertoire :

    gemini

  3. Exécutez la commande d'initialisation :

    /autoctx:init

    L'agent vous guide dans la création du fichier tools.yaml si aucune connexion à une base de données n'a été configurée. Il initialise également le fichier state.md local et un répertoire experiments.

    Après l'initialisation, votre espace de travail devrait se présenter comme suit :

    my-workspace/
└── autoctx/
    ├── tools.yaml          # Database connection and tools configuration
    ├── state.md            # Local file to track the experiment progress
    └── experiments/        # Dedicated directory for future experiment-specific files

Préparer et étendre les ensembles de données

Pour permettre à Gemini d'optimiser systématiquement votre ensemble de contexte, préparez un ensemble de données d'évaluation composé de questions représentatives en langage naturel et de leurs réponses SQL attendues ("références") pour évaluer votre ensemble de contexte. Un ensemble de données d'évaluation de haute qualité est essentiel pour mesurer les performances, identifier les échecs de requêtes et suivre les améliorations au fil du temps. L'ensemble de données doit être un fichier JSON contenant la question en langage naturel (QLN) et le code SQL de référence qui couvre les cas d'utilisation ciblés dans votre application de données.

Voici un exemple du format attendu :

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

L'extension Gemini CLI inclut une commande fournie qui crée et met à l'échelle une petite base de référence de questions à des fins d'évaluation.

  1. Accédez au dossier de votre espace de travail.

  2. Démarrez la CLI Gemini dans le nouveau répertoire :

    gemini

  3. Exécutez la commande /autoctx:generate-dataset dans Gemini CLI :

    /autoctx:generate-dataset

  4. Lorsque l'agent vous y invite, fournissez une graine, c'est-à-dire un exemple initial ou un petit ensemble d'exemples qui guident la génération d'un ensemble de données plus volumineux. Une source peut être l'un des éléments suivants :

    • Petit fichier d'ensemble de données de référence
    • Paires d'or spécifiques pour la conversion du langage naturel en SQL (NL2SQL)

    Par exemple, vous pouvez fournir la paire d'or NL2SQL suivante comme point de départ :

    Question: "What are the names of all airports in California?"
SQL: "SELECT name FROM airports WHERE state = 'CA';"

  5. L'agent demande l'autorisation de vérifier la syntaxe et la validité de l'exécution à l'aide de l'outil execute_sql. Cette étape est facultative.

  6. L'agent demande s'il faut étendre l'ensemble de données avec des variantes issues des données de départ (en appliquant différents filtres, synonymes, etc.). Cette étape est facultative.

    L'agent utilise l'outil execute_sql pour exécuter les requêtes SQL nouvellement générées sur la base de données afin de vérifier la syntaxe et la validité de l'exécution avant de vous les présenter.

  7. Acceptez, modifiez ou refusez les suggestions de manière sélective. Les paires approuvées sont automatiquement enregistrées en local et prêtes à être évaluées.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json  # Generated dataset
    └── experiments/

Créer un ensemble de contexte initial

La génération d'un ensemble de contexte initial fournit une base pour l'évaluation et l'amélioration itérative. Cette étape utilise le schéma de votre base de données et les artefacts de votre application pour créer un contexte de base qui reflète votre logique métier.

L'extension Gemini CLI inclut une commande prédéfinie permettant de générer un ensemble initial de modèles et de facettes en fonction du schéma de base de données et des informations sur votre application d'agent de données, par exemple votre code d'application ou les fichiers contenant des informations sur vos exigences métier. Pour générer un ensemble de contexte de référence à partir de zéro :

  1. Accédez au dossier de votre espace de travail.

  2. Démarrez la CLI Gemini dans le nouveau répertoire :

    gemini

  3. Exécutez la commande /autoctx:bootstrap dans Gemini CLI :

    /autoctx:bootstrap

    Voici ce à quoi vous pouvez généralement vous attendre de l'agent.

    • L'agent vous invite à spécifier un nom de test. Un test est un dossier d'espace de travail dédié qui englobe l'ensemble du cycle de vie d'une configuration de contexte de base de données, en suivant son état de référence, les résultats des tests d'évaluation et les améliorations itératives ultérieures. Ce nom est utilisé pour organiser tous les fichiers générés dans le dossier de l'expérience de votre espace de travail. Choisissez un nom descriptif et facile à retenir.

    • L'agent récupère et liste les schémas de votre base de données cible, et vous invite à fournir éventuellement des ressources ou des fichiers supplémentaires. Si le schéma est complexe, l'agent vous invite également à sélectionner des schémas ou des tables spécifiques pour l'ensemble de contexte initial. Si vous n'en spécifiez aucune, il suppose que toutes les tables disponibles dans les schémas de base de données actuels sont concernées.

  4. Examinez et affinez éventuellement l'ensemble de contextes généré. Une fois affiné, l'agent produit un fichier de contexte JSON directement sur votre disque local, dans le dossier de votre espace de travail :

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json  # The generated initial context set file

  5. Suivez les instructions pour importer le contexte depuis Cloud SQL Studio.

Évaluer l'efficacité du contexte

L'extension Gemini CLI inclut une commande intégrée permettant d'évaluer votre agent de données à l'aide d'un ensemble de données de référence. L'extension s'intègre à Evalbench pour effectuer des évaluations en interrogeant l'API QueryData de l'agent avec les questions spécifiées dans l'ensemble de référence, puis en comparant le code SQL généré et ses résultats d'exécution avec le code SQL de référence. L'évaluation est essentielle pour comprendre l'efficacité de votre ensemble de contexte actuel. En comparant le code SQL généré à l'ensemble de données de référence, vous pouvez identifier les requêtes spécifiques qui échouent et les domaines dans lesquels le contexte doit être amélioré.

Pour mesurer l'efficacité de votre contexte actuel par rapport à votre ensemble de données de référence :

  1. Importez le contexte depuis Cloud SQL Studio vers les ensembles de contexte cibles pour l'évaluation. Cette étape est facultative si le contexte à évaluer n'est pas importé.
  2. Accédez au dossier de votre espace de travail.

  3. Lancez la CLI Gemini dans le dossier :

    gemini

  4. Exécutez la commande /autoctx:evaluate dans Gemini CLI :

    /autoctx:evaluate

  5. Indiquez les chemins d'accès à votre ensemble de données de référence, à l'ID de votre ensemble de contexte pour la génération et l'exécution de la configuration d'évaluation, ainsi qu'à un répertoire de sortie désigné.

    Une fois l'évaluation terminée, l'agent génère les résultats sous forme de fichiers dans le dossier de votre test et les résume.

    Vous pouvez également inspecter manuellement l'évaluation à partir du rapport d'évaluation détaillé, qui est stocké sous forme de fichiers CSV dans le dossier de votre expérience.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
                └── <configs_for_eval_run>/
            └── eval_reports/
                └── <eval_id>/
                    └── eval_report/
                        ├── configs.csv
                        ├── evals.csv
                        ├── scores.csv
                        └── summary.csv

Effectuer une analyse des écarts et optimiser le contexte

Étape essentielle de l'optimisation de l'ensemble de contexte, l'extension Gemini CLI inclut une commande intégrée permettant d'effectuer une analyse des écarts sur votre ensemble de contexte existant et de proposer des modifications pour améliorer sa qualité. L'analyse des écarts est essentielle pour comprendre pourquoi certaines requêtes échouent et où le contexte peut être amélioré. Sur la base de cette analyse, Gemini utilise le raisonnement automatisé pour suggérer des mises à jour ciblées du contexte (comme de nouveaux modèles ou facettes) afin de résoudre ces échecs et d'améliorer de manière itérative la précision des requêtes.

  1. Accédez au dossier de votre espace de travail.

  2. Lancez la CLI Gemini dans le dossier :

    gemini

  3. Exécutez la commande /autoctx:hillclimb dans Gemini CLI :

    /autoctx:hillclimb

    L'agent identifie automatiquement les résultats d'évaluation et le contexte de base les plus appropriés pour l'escalade de colline, et demande une confirmation s'il existe plusieurs options.

    Si aucun résultat d'évaluation n'est disponible, l'agent vous invite à exécuter une évaluation avec l'ensemble de données et le contexte définis.

    Une fois prêt, l'agent lit les résultats de l'évaluation et le contexte défini existant, puis génère un rapport d'analyse des écarts.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                └── gap_analysis_v1.md

    L'agent formule des corrections en proposant de nouveaux modèles et facettes prescriptifs, en testant éventuellement le code SQL par rapport à la base de données via execute_sql.

    Une fois prêt, un nouveau fichier JSON de contexte amélioré est généré localement, laissant intact le fichier JSON de contexte de référence.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                ├── gap_analysis_v1.md
                └── improved_context_v1.md

  4. Suivez les instructions pour importer le contexte dans l'ensemble de contextes cibles à partir de Cloud SQL Studio. Vous serez alors prêt pour la prochaine série d'itérations, en commençant par l'évaluation.

Limites

Le workflow automatisé permet uniquement de générer et d'optimiser des modèles et des facettes. Si vous souhaitez configurer la recherche de valeurs pour votre agent de données, consultez Générer des requêtes de recherche de valeurs.

Générer un contexte ciblé

Si vous préférez une approche plus personnalisée pour la création de contexte, vous pouvez utiliser l'extension DB Context Enrichment pour générer manuellement des éléments de contexte spécifiques. Les commandes suivantes vous guident dans la création d'un contexte en tant que fichier JSON, ce qui vous permet de contrôler précisément la génération des requêtes de recherche de modèles, de facettes et de valeurs.

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

Pour ajouter une paire requête-SQL spécifique en tant que modèle de requête à l'ensemble de contexte, utilisez la commande /generate_targeted_templates.

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.

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

  1. Exécutez la commande /generate_targeted_templates dans Gemini CLI :

    /generate_targeted_templates

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

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

  4. 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, par exemple my-cluster-psc-primary_postgres_context_set_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

Générer des facettes ciblées

Pour ajouter une requête spécifique à une condition SQL en tant que facette au fichier de l'ensemble de contexte, utilisez la commande /generate_targeted_facets.

Pour en savoir plus sur le fichier de définition du contexte et les facettes, consultez Présentation des ensembles de contexte.

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

  1. Exécutez la commande /generate_targeted_facets dans Gemini CLI :

    /generate_targeted_facets

  2. Saisissez l'intention en langage naturel à ajouter au facette.

  3. Saisissez l'extrait SQL correspondant à la facette.

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

Le fichier de définition du contexte, par exemple my-cluster-psc-primary_postgres_context_set_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

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

Pour générer des recherches de valeurs qui spécifient comment le système recherche et fait correspondre des valeurs spécifiques dans un type de concept, utilisez la commande /generate_targeted_value_searches.

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

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

  2. Saisissez postgresql pour sélectionner AlloyDB comme moteur de base de données.

  3. Saisissez la version de PostgreSQL à utiliser. Sélectionnez default pour sélectionner PostgreSQL 16.

  4. 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 à 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, activez les extensions vector et google_ml_integration.

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

  5. 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.

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

Le fichier de définition du contexte, par exemple my-cluster-psc-primary_postgres_context_set_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

Étapes suivantes