Crea conjuntos de contexto con Gemini CLI

En este documento, se describe cómo crear y optimizar el contexto que te permite mejorar la precisión de QueryData para compilar tus aplicaciones de agentes de datos. Con la extensión de enriquecimiento del contexto de la base de datos en Gemini CLI, se proporciona acceso a un conjunto de herramientas para desarrolladores que automatizan la creación y la optimización de conjuntos de contexto.

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

La extensión automatiza la creación y la optimización de los conjuntos de contexto en la siguiente secuencia:

  1. Comprende las aplicaciones: Ingiere artefactos, como esquemas de bases de datos, código de la aplicación y requisitos comerciales, para establecer la lógica empresarial fundamental de tu agente de datos.
  2. Crea conjuntos de datos: Selecciona un conjunto de datos de evaluación que contenga preguntas representativas en lenguaje natural y sus respuestas esperadas en SQL. Establecer este conjunto de datos de referencia es fundamental para medir el rendimiento y hacer un seguimiento de las mejoras a lo largo del tiempo.
  3. Genera contexto inicial: Genera automáticamente un conjunto de contexto de referencia derivado directamente del esquema de tu base de datos y de los artefactos de la aplicación opcionales como inicio rápido.
  4. Optimiza el contexto de forma iterativa: Evalúa tu conjunto de datos para identificar por qué fallan las búsquedas específicas. Gemini usa el razonamiento automatizado para sugerir actualizaciones de contexto segmentadas, lo que permite lograr una mayor precisión de forma iterativa.

Si bien la extensión ofrece un flujo de trabajo automatizado sólido, se adapta a tus necesidades. Puedes omitir la automatización para crear e insertar contexto a un nivel más detallado. Con comandos de generación especializados, controlas la creación de plantillas, facetas y consultas de búsqueda de valores de alta calidad.

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 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 Google Cloud .
  • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
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 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, habilita 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, completa los siguientes 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 tu entorno, completa los siguientes pasos:

  • Instala Gemini CLI
  • Instala la extensión DB Context Enrichment
  • 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 DB Context Enrichment

La extensión de enriquecimiento del contexto de la base de datos proporciona un flujo de trabajo interactivo y guiado para generar conjuntos de contexto estructurados y realizar iteraciones sobre ellos.

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, completa 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.5.0 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 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 una conexión a la base de datos para recuperar esquemas y la capacidad de validar la sintaxis del contexto de SQL generado. Para permitir que la extensión interactúe con tu base de datos, configura las credenciales de autenticación y define la configuración de conexión de la base de datos.

Configura las credenciales predeterminadas de la aplicación

Configura 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 de conexión de la base de datos

La extensión requiere una conexión a la base de datos para la generación de contexto, que la caja de herramientas de MCP admite y define dentro de un archivo de configuración.

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

  1. Inicia la Gemini CLI:

    gemini

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

    /skills

  3. Escribe una instrucción, por ejemplo, help me set up the database connection. La skill te guía para crear el archivo de configuración en tu directorio de trabajo actual como autoctx/tools.yaml.

  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 de configuración de la base de datos, consulta Configuración de MCP Toolbox.

Genera el contexto con un flujo de trabajo automatizado

Mejorar la precisión a través de la ingeniería de contexto suele ser un proceso manual de prueba y error. Los desarrolladores suelen adivinar por qué falló una búsqueda, escribir una corrección y probarla de forma manual. La extensión DB Context Enrichment en la CLI de Gemini automatiza este proceso de mejora. Utiliza conjuntos de datos de evaluación (conjuntos de preguntas con sus respuestas correctas en SQL) para medir el rendimiento y determinar por qué fallan ciertas consultas. Luego, Gemini sugiere automáticamente actualizaciones de contexto específicas para lograr una mayor precisión. Completa estos pasos para mejorar sistemáticamente la precisión de tu agente de datos.

Inicializa un lugar de trabajo

El comando de inicialización configura tu espacio de trabajo local, incluida la configuración de conexión de la base de datos y el directorio del experimento. Este espacio de trabajo exclusivo garantiza que todas las configuraciones, los experimentos y los archivos generados estén organizados en un solo lugar, lo que facilita la administración y el seguimiento de tus esfuerzos de optimización del contexto.

  1. Crea un directorio nuevo que sirva como espacio de trabajo para el flujo de optimización iterativo y navega hasta él.

  2. Inicia Gemini CLI en el directorio nuevo:

    gemini

  3. Ejecuta el comando de inicialización:

    /autoctx:init

    El agente te guía para crear el archivo tools.yaml si no se configuró ninguna conexión de base de datos y también inicializa el archivo state.md local y un directorio experiments.

    Después de la inicialización, tu espacio de trabajo debería verse de la siguiente manera:

    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

Prepara y expande conjuntos de datos

Para permitir que Gemini realice optimizaciones de forma sistemática en tu conjunto de contexto, prepara un conjunto de datos de evaluación de preguntas representativas en lenguaje natural y sus respuestas esperadas en SQL ("estándar de oro") para evaluar tu conjunto de contexto. Un conjunto de datos de evaluación de alta calidad es fundamental para medir el rendimiento, identificar fallas en las búsquedas y hacer un seguimiento de las mejoras a lo largo del tiempo. El conjunto de datos debe ser un archivo JSON que contenga la pregunta en lenguaje natural (NLQ) y el SQL de referencia que abarca los casos de uso objetivo en tu aplicación de datos.

Este es un ejemplo del formato esperado:

[
  {
    "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;"
  }
]

La extensión de Gemini CLI incluye un comando proporcionado que crea y ajusta una pequeña línea de base de preguntas para fines de evaluación.

  1. Navega a la carpeta de tu espacio de trabajo.

  2. Inicia Gemini CLI en el directorio nuevo:

    gemini

  3. Ejecuta el comando /autoctx:generate-dataset en Gemini CLI:

    /autoctx:generate-dataset

  4. Cuando el agente te lo solicite, proporciona una semilla, que es un ejemplo inicial o un pequeño conjunto de ejemplos que guía la generación de un conjunto de datos más grande. Una semilla puede ser una de las siguientes:

    • Un pequeño archivo de conjunto de datos de referencia
    • Pares de referencia específicos de lenguaje natural a SQL (NL2SQL)

    Por ejemplo, podrías proporcionar el siguiente par de referencia de NL2SQL como semilla:

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

  5. El agente solicita permiso para verificar la sintaxis y la validez de la ejecución con la herramienta execute_sql. Este paso es opcional.

  6. El agente pregunta si se debe expandir el conjunto de datos con variaciones de los datos iniciales (aplicando diferentes filtros, sinónimos, etcétera). Este paso es opcional.

    El agente usa la herramienta execute_sql para ejecutar las consultas en SQL recién generadas en la base de datos y verificar la sintaxis y la validez de la ejecución antes de presentártelas.

  7. Acepta, edita o rechaza las sugerencias de forma selectiva. Los pares aprobados se guardan automáticamente de forma local y están listos para la evaluación.

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

Crea un conjunto de contextos inicial

Generar un conjunto de contexto inicial proporciona un modelo de referencia para la evaluación y la mejora iterativa. En este paso, se usan el esquema de la base de datos y los artefactos de la aplicación para crear un contexto fundamental que refleje tu lógica empresarial.

La extensión de Gemini CLI incluye un comando prediseñado para generar un conjunto inicial de plantillas y facetas según el esquema de la base de datos y la información sobre tu aplicación de agente de datos, por ejemplo, el código de la aplicación o los archivos con información sobre tus requisitos comerciales. Para generar un conjunto de contexto de referencia desde cero, haz lo siguiente:

  1. Navega a la carpeta de tu espacio de trabajo.

  2. Inicia Gemini CLI en el directorio nuevo:

    gemini

  3. Ejecuta el comando /autoctx:bootstrap en Gemini CLI:

    /autoctx:bootstrap

    Por lo general, puedes esperar lo siguiente del agente.

    • El agente te pedirá que especifiques un nombre para el experimento. Un experimento es una carpeta de espacio de trabajo dedicada que encapsula el ciclo de vida completo de una configuración de contexto de la base de datos, ya que realiza un seguimiento de su estado de referencia, los resultados de las pruebas de evaluación y las posteriores mejoras iterativas de ascenso de colinas. Este nombre se usa para organizar todos los archivos generados en la carpeta del experimento en tu espacio de trabajo. Elige un nombre descriptivo y fácil de recordar.

    • El agente recupera y enumera los esquemas de tu base de datos de destino, y te solicita que proporciones recursos o archivos adicionales de forma opcional. Si el esquema es complejo, el agente también te pedirá que selecciones esquemas o tablas específicos para el conjunto de contexto inicial. Si no especificas ninguna, se supone que se incluyen todas las tablas disponibles en los esquemas de la base de datos actual.

  4. Revisa y, de manera opcional, define mejor el conjunto de información contextual generado. Una vez que se perfecciona, el agente produce un archivo de contexto JSON directamente en tu disco local, en la carpeta de tu espacio de trabajo:

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

  5. Sigue las instrucciones para subir el contexto desde Cloud SQL Studio.

Evalúa la efectividad del contexto

La extensión de Gemini CLI incluye un comando integrado para evaluar tu agente de datos con un conjunto de datos de referencia. La extensión se integra con Evalbench para realizar evaluaciones. Para ello, consulta la API de QueryData del agente con las preguntas especificadas en el conjunto de referencia y, luego, compara el código SQL generado y sus resultados de ejecución con el código SQL de referencia. La evaluación es clave para comprender la eficacia de tu conjunto de contexto actual. Si comparas el código SQL generado con el conjunto de datos de referencia, puedes identificar las consultas específicas que fallan y las áreas en las que se necesita mejorar el contexto.

Para medir la eficacia de tu contexto actual en comparación con tu conjunto de datos de referencia, haz lo siguiente:

  1. Sube el contexto de Cloud SQL Studio a los conjuntos de contexto de destino para la evaluación. Este paso es opcional si no se sube el contexto que se evaluará.
  2. Navega a la carpeta de tu espacio de trabajo.

  3. Inicia Gemini CLI en la carpeta:

    gemini

  4. Ejecuta el comando /autoctx:evaluate en Gemini CLI:

    /autoctx:evaluate

  5. Proporciona las rutas de acceso a tu conjunto de datos de referencia, el ID de tu conjunto de contexto para la generación de la configuración de evaluación y la ejecución de la evaluación, y un directorio de salida designado.

    Una vez que se complete, el agente generará los resultados de la evaluación como archivos en la carpeta del experimento y resumirá el resultado de la evaluación.

    De manera opcional, puedes inspeccionar manualmente la evaluación en el informe de evaluación detallado, que se almacena como archivos CSV en la carpeta del experimento.

    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

Realiza análisis de brechas y optimización del contexto

Como paso fundamental para optimizar el conjunto de contexto, la extensión de Gemini CLI incluye un comando integrado para realizar un análisis de brechas en tu conjunto de contexto existente y proponer cambios para mejorar su calidad. El análisis de brechas es fundamental para comprender por qué fallan las búsquedas específicas y dónde se puede mejorar el contexto. Según este análisis, Gemini usa el razonamiento automatizado para sugerir actualizaciones de contexto segmentadas, como plantillas o facetas nuevas, para abordar estos errores y mejorar de forma iterativa la precisión de las búsquedas.

  1. Navega a la carpeta de tu espacio de trabajo.

  2. Inicia Gemini CLI en la carpeta:

    gemini

  3. Ejecuta el comando /autoctx:hillclimb en Gemini CLI:

    /autoctx:hillclimb

    El agente identifica automáticamente los resultados de evaluación y el contexto base más adecuados para el ascenso de colina, y solicita confirmación si hay varias opciones.

    Si no hay resultados de evaluación disponibles, el agente te pedirá que ejecutes una evaluación con el conjunto de datos y el contexto establecidos.

    Cuando está listo, el agente lee los resultados de la evaluación y el conjunto de contexto existente, y luego genera un informe de análisis de brechas.

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

    El agente formula correcciones proponiendo nuevas plantillas y facetas prescriptivas, y, de manera opcional, prueba el SQL en la BD a través de execute_sql.

    Cuando esté listo, se generará de forma local un nuevo archivo JSON de contexto mejorado, y el archivo JSON de contexto de referencia permanecerá intacto.

    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. Sigue las instrucciones para subir el contexto al conjunto de contexto de destino desde Cloud SQL Studio, listo para la próxima ronda de iteración que comienza con la evaluación.

Limitaciones

El flujo de trabajo automatizado solo admite la generación y la optimización de plantillas y facetas. Si deseas configurar la búsqueda de valores para tu agente de datos, consulta Cómo generar búsquedas de valores.

Genera contexto segmentado

Si prefieres un enfoque más personalizado para la creación de contexto, puedes usar la extensión DB Context Enrichment para generar manualmente elementos de contexto específicos. Los siguientes comandos te guiarán para crear el contexto de creación como un archivo JSON, lo que te brindará un control detallado sobre la generación de consultas de búsqueda de plantillas, facetas y valores.

Genera plantillas segmentadas

Para agregar un par específico de consulta y SQL como plantilla de consulta al conjunto de contexto, usa el comando /generate_targeted_templates.

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.

Para agregar una plantilla de consulta al conjunto de contexto, completa los siguientes pasos:

  1. Ejecuta el comando /generate_targeted_templates en Gemini CLI:

    /generate_targeted_templates

  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 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, por ejemplo, my-cluster-psc-primary_postgres_context_set_20251104111122.json, se guarda en el directorio en el que ejecutaste los comandos.

Genera facetas segmentadas

Para agregar una búsqueda específica a la condición SQL como una faceta al archivo de conjunto de contexto, usa el comando /generate_targeted_facets.

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.

Para agregar una faceta al archivo de conjunto de contexto, completa los siguientes pasos:

  1. Ejecuta el comando /generate_targeted_facets en Gemini CLI:

    /generate_targeted_facets

  2. Ingresa la intención en lenguaje natural que deseas agregar a la faceta.

  3. Ingresa el fragmento de SQL correspondiente a la faceta.

  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, por ejemplo, my-cluster-psc-primary_postgres_context_set_20251104111122.json, se guarda en el directorio en el que ejecutaste los comandos.

Genera búsquedas de valor

Para generar búsquedas de valores que especifiquen cómo el sistema busca y coincide con valores específicos dentro de un tipo de concepto, usa el comando /generate_targeted_value_searches.

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

Completa los pasos que se indican en Prepara la base de datos para las búsquedas de valores.

Para generar un índice de valor, completa los siguientes pasos:

  1. Ejecuta el comando /generate_targeted_value_searches:

    /generate_targeted_value_searches

  2. Ingresa mysql para seleccionar MySQL como el motor de base de datos. Selecciona predeterminado para seleccionar MySQL 8.0.

  3. 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 se 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, prepara tu base de datos para admitir 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, prepara tu base de datos para admitir incorporaciones de vectores.

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

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

  5. 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, por ejemplo, my-cluster-psc-primary_postgres_context_set_20251104111122.json, se guarda en el directorio en el que ejecutaste los comandos.

¿Qué sigue?