Crea conjuntos de contexto con Gemini CLI

En este documento, se describe cómo usar la CLI de Gemini y la caja de herramientas de MCP para compilar archivos de contexto del agente. Estos archivos contienen plantillas, facetas y búsquedas de valores que proporcionan contexto para generar consultas en SQL a partir del lenguaje natural. También usarás la extensión DB Context Enrichment.

Para obtener más información sobre los conjuntos de contexto, consulta Descripción general de los conjuntos de contexto.

Para compilar un archivo de contexto del agente, sigue estos pasos generales:

  • Prepara el entorno
  • Genera plantillas segmentadas
  • Genera facetas segmentadas
  • Genera búsquedas de valores segmentadas
  • Es opcional. Genera plantillas de forma masiva

Antes de comenzar

Completa los siguientes requisitos previos antes de crear un agente.

Habilita los servicios obligatorios

Habilita los siguientes servicios para tu proyecto:

Prepara una instancia de Cloud SQL

Roles y permisos requeridos

Otorga permiso de executesql a la instancia de Cloud SQL

Para otorgar el permiso executesql a la instancia de Cloud SQL y habilitar la API de Cloud SQL Data, ejecuta el siguiente comando: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Reemplaza lo siguiente:
  • PROJECT_ID: Es el ID de tu proyecto de Cloud de Confiance by S3NS .
  • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
Para seguir los pasos de este instructivo, accede a Cloud de Confiance by S3NS y, luego, autentícate en la base de datos con la autenticación de IAM.

Prepara la base de datos para las búsquedas de valores

Para usar las búsquedas de valores semánticos y trigramas, debes configurar tu instancia de Cloud SQL para MySQL de modo que admita embeddings de vectores y la indexación de n-gramas.

  1. Para habilitar la instancia de Cloud SQL para MySQL para que realice búsquedas de valores semánticos, debes habilitar las siguientes marcas.

    1. Habilita la marca cloudsql_vector.

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

    2. Habilita la marca enable-google-ml-integration para permitir que la instancia de Cloud SQL para MySQL se integre en Vertex AI.

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

    3. Crea una columna de vectores para almacenar los embeddings de ciudades

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

    4. Genera y almacena embeddings de vectores para los nombres de las ciudades

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

  2. Para habilitar la instancia de Cloud SQL para MySQL para que realice búsquedas de valores de trigramas, sigue estos pasos.

    1. Habilita la marca ngram_token_size.

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

    2. Crea un índice FULLTEXT para la coincidencia de trigramas en el nombre del aeropuerto

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

Prepara el entorno

Puedes compilar archivos de conjunto de contexto desde cualquier entorno de desarrollo local o IDE. Para preparar el entorno, sigue estos pasos:

  • Instala Gemini CLI
  • Instala la extensión DB Context Enrichment
  • Configura la conexión a la base de datos

Instala Gemini CLI

Para instalar Gemini CLI, consulta Comienza a usar Gemini CLI.

Instala la extensión del MCP de enriquecimiento del contexto de la base de datos

La extensión DB Context Enrichment proporciona un flujo de trabajo guiado e interactivo para generar contexto estructurado de NL2SQL a partir de los esquemas de tu base de datos.

Para obtener más información sobre la instalación de la extensión DB Context Enrichment, consulta Extensión DB Context Enrichment.

Para instalar la extensión DB Context Enrichment, sigue estos pasos:

  1. Instala la extensión DB Context Enrichment de Gemini CLI:

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

  2. (Opcional) Actualiza la extensión DB Context Enrichment.

    Para verificar la versión instalada de la extensión, ejecuta el siguiente comando:

    gemini extensions list

    Asegúrate de que la versión sea 0.4.2 o posterior. Para actualizar la extensión DB Context Enrichment, ejecuta el siguiente comando:

      gemini extensions update mcp-db-context-enrichment

    Para actualizar la extensión DB Context Enrichment o reemplazar el GEMINI_API_KEY, ejecuta el siguiente comando:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Reemplaza GEMINI_API_KEY por tu clave de la API de Gemini.

Configura la conexión de la base de datos

La extensión requiere la conexión a la base de datos para la generación de contexto para recuperar esquemas y ejecutar instrucciones de SQL. Para permitir que la extensión interactúe con tu base de datos, debes configurar las credenciales de autenticación y definir las fuentes y herramientas de tu base de datos.

Configura las credenciales predeterminadas de la aplicación

Debes configurar las credenciales predeterminadas de la aplicación (ADC) para proporcionar credenciales de usuario para dos componentes principales:

  • Servidor de MCP de Toolbox: Usa credenciales para conectarse a tu base de datos, recuperar esquemas y ejecutar SQL para la validación.
  • Extensión de enriquecimiento del contexto de la base de datos: Usa credenciales para autenticarse y llamar a la API de Gemini.

Ejecuta los siguientes comandos en tu terminal para autenticarte:

gcloud auth application-default login

Configura el archivo tools.yaml

La extensión requiere una conexión a la base de datos para la generación de contexto, que es compatible con MCP Toolbox y se define en el archivo de configuración tools.yaml.

El archivo tools.yaml especifica la fuente de tu base de datos y las herramientas necesarias para recuperar esquemas o ejecutar SQL. La extensión incluye habilidades de agente preinstaladas para ayudarte a generar la configuración.

  1. Inicia Gemini CLI:

    gemini

  2. Para verificar que las habilidades estén activas, escribe lo siguiente en Gemini CLI: 

    /skills

  3. Escribe una instrucción como help me setup the database connection. La skill te guía para crear el archivo tools.yaml en tu directorio de trabajo actual.

  4. Ejecuta el siguiente comando en Gemini CLI para aplicar la configuración de tools.yaml al servidor de MCP de Toolbox.

    /mcp reload

Para obtener más información sobre cómo configurar manualmente el archivo tools.yaml, consulta Configuración de MCP Toolbox.

Generar contexto

Las extensiones que instalaste anteriormente permiten que Gemini CLI te ayude a crear contexto en forma de un archivo JSON.

Genera plantillas segmentadas

Si deseas agregar un par de búsquedas específico como plantilla de búsqueda al conjunto de contexto, puedes usar el comando /generate_targeted_templates. Para obtener más información sobre las plantillas, consulta Descripción general de los conjuntos de contexto.

Para agregar una plantilla de consulta al conjunto de contexto, sigue estos pasos:

  1. En el mismo directorio, inicia Gemini CLI:

    gemini

  2. Completa la Configuración de autenticación de Gemini CLI.

  3. Verifica que la caja de herramientas de MCP y la extensión de enriquecimiento de la base de datos estén listas para usarse:

    /mcp reload

  4. Ejecuta el comando /generate_targeted_templates:

    /generate_targeted_templates

  5. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

  6. Ingresa la consulta en SQL correspondiente en la plantilla de consulta.

  7. Revisa la plantilla de búsqueda generada. Puedes guardar la plantilla de consulta como un archivo de conjunto de contexto o agregarla a un archivo de conjunto de contexto existente.

El archivo de conjunto de contexto similar a my-cluster-psc-primary_postgres_templates_20251104111122.json se guarda en el directorio en el que ejecutaste los comandos.

Para obtener más información sobre el archivo de conjunto de contexto y la plantilla de consulta, consulta Descripción general de los conjuntos de contexto.

Genera facetas segmentadas

Si deseas agregar un par de búsquedas específico como faceta al archivo de conjunto de contexto, puedes usar el comando /generate_targeted_facets.

Para agregar una faceta al archivo de conjunto de contexto, sigue estos pasos:

  1. Ejecuta el comando /generate_targeted_facets:

    /generate_targeted_facets

  2. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

  3. Ingresa la consulta en SQL correspondiente en la plantilla de consulta.

  4. Revisa la faceta generada. Puedes guardar la faceta en un archivo de conjunto de contexto o agregarla a un archivo de conjunto de contexto existente.

El archivo de conjunto de contexto similar a my-cluster-psc-primary_postgres_templates_20251104111122.json se guarda en el directorio en el que ejecutaste los comandos.

Para obtener más información sobre el archivo de conjunto de contexto y las facetas, consulta Descripción general de los conjuntos de contexto.

Genera búsquedas de valor

Si deseas generar búsquedas de valores que especifiquen cómo el sistema debe buscar y hacer coincidir valores específicos dentro de un tipo de concepto, puedes usar el comando /generate_targeted_value_searches.

Asegúrate de completar los pasos en Prepara la base de datos para las búsquedas de valores.

Para generar un índice de valores, realiza los siguientes pasos:

  1. Ejecuta el comando /generate_targeted_value_searches:

    /generate_targeted_value_searches
  1. Ingresa mysql para seleccionar MySQL como el motor de base de datos. Selecciona predeterminado para seleccionar MySQL 8.0.

  1. Ingresa la configuración de búsqueda de valores de la siguiente manera:

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

    Reemplaza lo siguiente:

    • TABLE_NAME: Es la tabla en la que existe la columna asociada al tipo de concepto.
    • COLUMN_NAME: Es el nombre de la columna asociada al tipo de concepto.
    • CONCEPT_TYPE: Es el tipo de concepto que deseas definir, por ejemplo, City name.

    • MATCH_FUNCTION: Es la función de coincidencia que se usará para la búsqueda de valores. Puedes usar una de las siguientes funciones:

      • EXACT_STRING_MATCH: Para la coincidencia exacta de dos valores de cadena. Es mejor para IDs, códigos y claves primarias únicos.
      • TRIGRAM_STRING_MATCH: Para la correlación aproximada que calcula la distancia de trigramas normalizada. Es la mejor opción para las búsquedas de usuarios y la corrección de nombres. Para usar TRIGRAM_STRING_MATCH, debes preparar tu base de datos para que admita la indexación de n-gramas.
      • SEMANTIC_SIMILARITY_MATCH: Para la búsqueda semántica en valores de cadena. Es la mejor opción para las búsquedas de sinónimos y en varios idiomas. Para obtener una lista de los modelos compatibles, consulta Modelos de Google compatibles. Para usar SEMANTIC_SIMILARITY_MATCH, debes preparar tu base de datos para que admita embeddings de vectores.

    • DESCRIPTION: (Opcional) Es la descripción de la búsqueda de valores.

  2. Agrega búsquedas de valores adicionales según sea necesario. Si no agregas índices de valores adicionales, la generación de SQL basada en plantillas pasará al siguiente paso.

  3. Revisa las búsquedas de valores generadas. Puedes guardar el conjunto de contexto como un archivo de conjunto de contexto o agregarlo a un archivo de conjunto de contexto existente.

El archivo de conjunto de contexto similar a my-cluster-psc-primary_postgres_templates_20251104111122.json se guarda en el directorio en el que ejecutaste los comandos.

Para obtener más información sobre el índice de valores, consulta Descripción general de los conjuntos de contexto.

Opcional: Genera plantillas de forma masiva

Si deseas generar automáticamente el archivo de conjunto de contexto en función del esquema y los datos de tu base de datos, puedes usar el comando /generate_bulk_templates.

Para generar automáticamente plantillas masivas, sigue estos pasos:

  1. Ejecuta el comando /generate_bulk_templates:

    /generate_bulk_templates

  2. Según el esquema de tu base de datos, la generación de SQL basada en plantillas te guía a través de una serie de preguntas relacionadas con la verificación de la información de la base de datos y el otorgamiento de permisos para acceder al esquema de la base de datos.

  3. Revisa la plantilla de búsqueda generada. Puedes aprobar la plantilla o actualizar un par de búsquedas que quieras revisar.

  4. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

  5. Ingresa la consulta en SQL correspondiente en la plantilla de consulta.

  6. Revisa la plantilla de búsqueda generada. Puedes guardar la plantilla de consulta como un archivo de conjunto de contexto o agregarla a un archivo de contexto existente.

  7. Después de aprobar la plantilla de consulta, puedes crear un archivo de plantilla nuevo o agregar los pares de consultas a un archivo de plantilla existente. La plantilla de consulta se guarda como un archivo JSON en tu directorio local.

El archivo de conjunto de contexto similar a my-cluster-psc-primary_postgres_templates_20251104111122.json se guarda en el directorio en el que ejecutaste los comandos.

Para obtener más información sobre el archivo de conjunto de contexto, consulta Descripción general de los conjuntos de contexto.

¿Qué sigue?