Crea conjuntos de contexto con Gemini CLI

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio y las Condiciones Adicionales para Productos de IA Generativa en Versión Preliminar. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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:

• API de Data Analytics with Gemini
• API de Gemini for Google Cloud
• API de Knowledge Catalog

Prepara un clúster, una instancia y una base de datos de AlloyDB para PostgreSQL

Asegúrate de tener acceso a un clúster y una instancia existentes de AlloyDB, o crea uno nuevo.
En este instructivo, se requiere que tengas una base de datos en tu instancia de AlloyDB. Para obtener más información, consulta Crea una base de datos.

Roles y permisos requeridos

• Agrega un usuario o una cuenta de servicio de Identity and Access Management (IAM) al clúster a nivel de la base de datos. Para obtener más información, consulta Administra usuarios de bases de datos.
• Otorga los roles alloydb.databaseUser, serviceusage.serviceUsageConsumer y geminidataanalytics.queryDataUser al usuario de IAM a nivel del proyecto. Para obtener más información, consulta Cómo agregar una vinculación de política de IAM para un proyecto.

Otorga permiso de executesql a la instancia de AlloyDB para PostgreSQL

Para otorgar el permiso executesql a la instancia de AlloyDB para PostgreSQL y establecer el parámetro de configuración de la instancia data_api_access en el valor ALLOW_DATA_API, usa el siguiente comando curl :

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
• LOCATION: Es la región en la que se encuentra tu clúster de AlloyDB.
• CLUSTER_ID: Es el ID de tu clúster de AlloyDB.
• INSTANCE_ID: Es el ID de tu instancia de AlloyDB.

Para seguir los pasos de este instructivo, accede a Google Cloud y, luego, autentícate en la base de datos con la autenticación de IAM.

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

   Nota: La extensión requiere una clave de API de Gemini durante la instalación para autenticarse con la API de Gemini y habilitar la generación de contexto. Para obtener más información sobre cómo encontrar tu clave de API, consulta Cómo usar las claves de la API de Gemini.

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.

Nota: Si no se establece esta conexión, la extensión mostrará mensajes de error, como "Error Discovering tools from mcp_toolbox", y no funcionará la generación de contexto.

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.

Nota: Gemini CLI puede acceder a tus archivos locales para reducir la sobrecarga, como especificar las ubicaciones exactas de los archivos en tus directorios locales. Por ejemplo, si un paso del flujo de trabajo de Gemini CLI te pide información que puedes encontrar en tu archivo tools.yaml, puedes pedirle a Gemini CLI que use tools.yaml o responder con una instrucción como look it up.

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.

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

1. Ejecuta el comando /generate_targeted_value_searches:

   /generate_targeted_value_searches

1. Ingresa postgresql para seleccionar AlloyDB como el motor de base de datos.

2. Ingresa la versión de PostgreSQL que deseas usar. Selecciona default para elegir PostgreSQL 16.

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 habilitar la extensión pg_trgm.
     • 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 habilitar la extensión vector y google_ml_integration.

   • 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?

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