Crea conjuntos de contexto con Gemini CLI

En este documento, se describe cómo usar Gemini CLI y MCP Toolbox 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 de lenguaje natural. También usarás la extensión de enriquecimiento de contexto de la base de datos.

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 masivas

Antes de comenzar

Completa los siguientes requisitos previos antes de crear un agente.

Habilita los servicios obligatorios

• API de Data Analytics with Gemini
• API de Gemini for Google Cloud
• API de Dataplex Universal Catalog

Prepara una instancia de Cloud SQL

• Asegúrate de tener acceso a una instancia de Cloud SQL existente o crea una nueva. Para obtener más información, consulta Crea instancias para Cloud SQL.
• Asegúrate de crear una base de datos en tu instancia en la que crearás las tablas. Para obtener más información, consulta Crea una base de datos en la instancia de Cloud SQL.

Roles y permisos requeridos

• Agrega un usuario o una cuenta de servicio de IAM a nivel de la instancia. Para obtener más información, consulta Agrega una vinculación de política de IAM a un usuario, una cuenta de servicio o un grupo.
• Otorga las funciones cloudsql.studioUser, cloudsql.instanceUser y geminidataanalytics.queryDataUser al usuario o la cuenta de servicio de IAM a nivel del proyecto. Para obtener más información, consulta Agrega una vinculación de política de IAM para un proyecto.
• Debes tener un usuario con privilegios que otorgue privilegios de base de datos a el usuario o la cuenta de servicio de IAM.
  
  GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Para obtener más información, consulta Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individual.

Otorga permiso executesql a la instancia de Cloud SQL

gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

• PROJECT_ID: Es el ID de tu Cloud de Confiance by S3NS proyecto.
• INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.

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

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

1. Para habilitar la instancia de Cloud SQL para MySQL para realizar búsquedas de valores semánticas, 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 con Vertex AI.

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

   3. Crea una columna de vector para almacenar embeddings de ciudades.

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

   4. Genera y almacena embeddings de vector para nombres de 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 realizar 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 contexto del agente desde cualquier entorno de desarrollo local o IDE. Para preparar el entorno, sigue estos pasos:

• Instala Gemini CLI
• Instala la extensión de enriquecimiento de contexto de la base de datos
• Configura la conexión de la base de datos

Instala Gemini CLI

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

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

La extensión de enriquecimiento de contexto de la base de datos proporciona un flujo de trabajo interactivo y guiado 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 de enriquecimiento de contexto de la base de datos, consulta Extensión de enriquecimiento de contexto de la base de datos.

Para instalar la extensión de enriquecimiento de contexto de la base de datos, sigue estos pasos:

1. Instala la extensión de Gemini CLI de MCP Toolbox:

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

2. (Opcional) Actualiza la extensión de enriquecimiento de contexto de la base de datos.

   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 de enriquecimiento de contexto de la base de datos, ejecuta el siguiente comando:

     gemini extensions update mcp-db-context-enrichment

   Para actualizar la extensión de enriquecimiento de contexto de la base de datos o reemplazar 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 API de Gemini.

Configura la conexión de la base de datos

La extensión requiere la conexión de 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 tus fuentes y herramientas de 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 de contexto de la base de datos: Usa credenciales para autenticar 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 de base de datos para la generación de contexto, que es compatible con el MCP Toolbox y se define en el archivo de configuración tools.yaml.

El archivo tools.yaml especifica la fuente de la base de datos y las herramientas necesarias para recuperar esquemas o ejecutar SQL. La extensión incluye habilidades del 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 habilidad 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 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.

Genera contexto

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

Genera plantillas segmentadas

Si deseas agregar un par de consultas específico como plantilla de consulta 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 MCP Toolbox y la extensión de enriquecimiento de la base de datos estén listos para usar:

   /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 a la plantilla de consulta.

7. Revisa la plantilla de consulta 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 consultas 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 a 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 consultas de búsqueda de valores

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, sigue estos 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 default 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 con el tipo de concepto.
   • COLUMN_NAME: Es el nombre de la columna asociada con el 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. Ideal para IDs, códigos y claves primarias únicos.
     • TRIGRAM_STRING_MATCH: Para la coincidencia aproximada que calcula la distancia de trigramas normalizada. Ideal para búsquedas de usuarios y 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. Ideal para búsquedas multilingües y de sinónimos. 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 vector.

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

2. Agrega búsquedas de valores adicionales según sea necesario. Si omites agregar índices de valores adicionales, la generación de SQL basada en plantillas pasa 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 masivas

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 consulta generada. Puedes aprobar la plantilla o actualizar un par de consultas que deseas revisar.

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

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

6. Revisa la plantilla de consulta 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?

• Obtén más información sobre los conjuntos de contexto.
• Obtén información para crear o borrar un conjunto de contexto en Cloud SQL Studio.
• Obtén información para probar un conjunto de contexto.