Usa el agente de Gemini CLI para probar el contexto de datos

Los agentes de IA pueden razonar, pero comienzan sin ningún conocimiento sobre tu empresa específica. Imagina que le preguntas a un agente: "¿Cuáles son nuestros ingresos del primer trimestre?". Sin orientación, el agente podría elegir entre docenas de tablas llamadas "ingresos" en tus bases de datos, que van desde informes oficiales hasta datos de prueba desordenados. Si el agente elige la tabla con el nombre que suena más parecido, podría devolver respuestas convincentemente incorrectas basadas en fuentes no verificadas.

El enriquecimiento de metadatos es la solución a este problema de contexto. En este instructivo, configurarás aspectos que proporcionan este contexto y usarás la CLI de Gemini para probar el contexto de los datos y verificar que un agente pueda fundamentar con precisión sus respuestas en datos certificados y confiables.

Objetivos

• Crea un data lake realista para realizar pruebas.
• Usa los aspectos de Knowledge Catalog para etiquetar tus datos "de oro" y distinguirlos de los datos de prueba.
• Prueba tu contexto de datos de forma local con Gemini CLI.

Antes de comenzar

Antes de comenzar, asegúrate de hacer lo siguiente:

• Elige un Google Cloud proyecto para este instructivo.
• Confirma que la facturación esté habilitada para tu proyecto.

Para completar este instructivo, también debes tener conocimientos básicos de BigQuery, Knowledge Catalog y Terraform.

Prepara el entorno

En este instructivo, se usa Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

1. En la Google Cloud consola, haz clic en Activar Cloud Shell en la barra de herramientas de la esquina superior derecha. El aprovisionamiento y la conexión al entorno demorarán unos minutos.

2. En Cloud Shell, configura tus variables PROJECT_ID y REGION para que todos los comandos futuros se dirijan a tu proyecto Google Cloud específico.

   export PROJECT_ID=$(gcloud config get-value project)
   gcloud config set project $PROJECT_ID
   export REGION="us-central1"
   

3. Habilita los Google Cloud servicios necesarios.

   gcloud services enable \
     artifactregistry.googleapis.com \
     bigqueryunified.googleapis.com \
     cloudaicompanion.googleapis.com \
     cloudbuild.googleapis.com \
     cloudresourcemanager.googleapis.com \
     datacatalog.googleapis.com \
     run.googleapis.com
   

4. Clona el repositorio de demostraciones deGoogle Cloud DevRel.

   Descarga el código y las secuencias de comandos de la infraestructura desde GitHub. Usa una extracción dispersa para extraer solo la carpeta específica que necesitas para este instructivo.

   # Perform a shallow clone to get only the latest repository structure without the full history
   git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
   cd devrel-demos
   
   # Specify and download only the folder you need for this tutorial
   git sparse-checkout set data-analytics/governance-context
   cd data-analytics/governance-context
   

Crea el data lake

Para que las cosas sean realistas, necesitas una combinación de datos oficiales y datos desordenados y no confiables. Usa Terraform y los archivos de configuración de Terraform preconfigurados del repositorio del instructivo para realizar esta configuración rápidamente.

La configuración de Terraform controla dos tareas:

• Configura los tipos de aspectos (plantillas de metadatos) de Knowledge Catalog, los conjuntos de datos de BigQuery y las tablas, incluidos finance_mart.fin_monthly_closing_internal y analyst_sandbox.tmp_data_dump_v2_final_real.
• Carga datos de muestra en las tablas.

1. Abre el directorio terraform y, luego, inicialízalo.

   cd terraform
   terraform init
   

2. Aplica la configuración. Esto podría tardar hasta un minuto.

   terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

Ahora tienes un data lake no administrado. Para un agente de IA, las tablas de tu data lake se ven exactamente iguales, ya que son solo objetos con columnas. Para solucionar este problema, debes aplicar la gobernanza en el siguiente paso.

Aplicar la administración

Esta es la parte más importante de la configuración. En este momento, tus dos tablas se ven idénticas para un agente de IA. Para distinguirlos, se aplican aspectos, que son como etiquetas de metadatos certificadas que le brindan al agente el contexto que necesita. En esta sección, usarás dos secuencias de comandos: una para generar los metadatos y otra para aplicarlos a tus tablas.

Genera cargas útiles de administración

Terraform ya configuró los tipos de aspectos, por lo que ahora debes generar los datos para completarlos.

Ejecuta la secuencia de comandos ./generate_payloads.sh para crear un directorio aspect_payloads/. El directorio contiene cuatro archivos YAML que definen diferentes situaciones de gobernanza, que aplicarás en el siguiente paso.

Regresa a la raíz del directorio del instructivo y ejecuta la secuencia de comandos ./generate_payloads.sh:

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

Cómo aplicar aspectos

1. Antes de ejecutar la secuencia de comandos apply_governance.sh, consulta los datos que se adjuntarán a tus tablas. Ejecuta el siguiente comando para ver los metadatos definidos para tus datos financieros internos:

   cat aspect_payloads/fin_internal.yaml
   

   El archivo YAML define el contexto comercial de la tabla:

   your-project-id.us-central1.official-data-product-spec:
     data:
       product_tier: GOLD_CRITICAL
       data_domain: FINANCE
       usage_scope: INTERNAL_ONLY
       update_frequency: DAILY_BATCH
       is_certified: true
   

   Observa cómo se marcan explícitamente los datos como is_certified: true y se les asigna el nivel GOLD_CRITICAL. Esto le proporciona al agente de IA reglas claras y estructuradas para seguir.

2. Ejecuta la secuencia de comandos apply_governance.sh. Esta secuencia de comandos itera a través de tus tablas de BigQuery y usa la CLI de gcloud para "marcar" los metadatos de tus cargas útiles de YAML en cada tabla.

   chmod +x ./apply_governance.sh
   ./apply_governance.sh
   

Verifica los metadatos

Antes de continuar, verifica que la secuencia de comandos haya aplicado los aspectos correctamente.

1. Abre la página Knowledge Catalog en la consola de Google Cloud . Puedes usar la barra de búsqueda superior para encontrarlo.
2. Busca fin_monthly_closing_internal. Selecciona el nombre de la tabla en los resultados para abrir su página de detalles.
3. En la sección Aspectos y etiquetas opcionales, busca el aspecto official-data-product-spec. Confirma que los valores coincidan con el escenario "Interno de oro" que aplicaste.

Ahora usaste correctamente los metadatos para distinguir estas tablas y le proporcionaste a tu agente de IA una forma de hacer lo mismo.

Prueba tu contexto de datos con la CLI de Gemini

Antes de compilar una aplicación web completa, puedes probar tu lógica de gobernanza de forma local con un entorno del Protocolo de contexto del modelo (MCP). En esta configuración, la CLI de Gemini actúa como el cliente (la interfaz con la que hablas) y la extensión de Knowledge Catalog actúa como el servidor local.

Instala la extensión de Knowledge Catalog

En Cloud Shell, instala la extensión de Knowledge Catalog.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

Define las reglas

El archivo de configuración GEMINI.md tiene una lógica que convierte reglas declarativas, como "Necesito datos seguros", en búsquedas precisas que solo muestran tablas con las etiquetas de administración correctas.

Por el momento, el archivo de configuración es solo una plantilla. Debes agregar el ID de tu proyecto Google Cloud específico a las reglas para que, cuando ejecutes la CLI, se segmenten correctamente tus datos gobernados.

1. Agrega tu PROJECT_ID al archivo de configuración.

   envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md
   

2. Para verificar tus cambios y comprender cómo funciona el contexto de datos, echa un vistazo rápido al archivo GEMINI.md:

   cat GEMINI.md
   

   Ten en cuenta que el archivo divide las reglas en la fase 1 y la fase 2. Esto exige un orden estricto de las operaciones. Primero, el agente debe buscar las etiquetas de administración correctas (fase 1) antes de poder acceder a los datos (fase 2). Esta lógica de "primero la búsqueda" evita que el agente adivine nombres de tablas o alucine respuestas de fuentes no verificadas.

   Asegúrate de que la fase 2 contenga tu ID del proyecto Google Cloud real. Si no es correcta, el agente no sabrá dónde buscar tus datos.

Inicia la Gemini CLI y prueba situaciones

Inicia una nueva sesión de Gemini. Como estás en la carpeta del proyecto, la CLI detecta y carga automáticamente el GEMINI.md local como contexto del sistema.

gemini

Nota: Es posible que veas que se cargan varios archivos de contexto (por ejemplo, GEMINI.md y otros). Esto es normal. La CLI carga el GEMINI.md local para las reglas específicas de este proyecto, además de las instrucciones predeterminadas para la extensión de Knowledge Catalog.

Verifica la instalación

Confirma que la extensión de Knowledge Catalog esté activa. dataplex debería aparecer en la lista de herramientas del servidor de MCP configurado.

/mcp desc

Probarlo

Ahora es el momento de ver tu contexto de datos en acción. Pega estos mensajes en la CLI uno por uno.

Nota: La CLI solicita permiso para usar sus herramientas. Selecciona “2. Permitir la herramienta para esta sesión" para que no tengas que aprobar cada paso.

Caso 1: Cómo encontrar datos de referencia

Comprueba si la CLI de Gemini puede encontrar los datos más confiables para una reunión de la junta de alto riesgo.

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

La CLI debe omitir los datos sin procesar y encontrar fin_monthly_closing_internal. Para ello, compara tu solicitud de datos "finalizados" y "confidenciales" con las etiquetas GOLD_CRITICAL y INTERNAL_ONLY que aplicaste anteriormente.

Situación 2: Divulgación pública

Supongamos que quieres compartir datos de forma externa. Quieres asegurarte de que la CLI no deje escapar ningún secreto interno.

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

Aunque la tabla interna tiene la mayor cantidad de detalles, la CLI debe omitirla. Debería dirigirte a fin_quarterly_public_report porque es la única tabla etiquetada como EXTERNAL_READY.

Situación 3: Necesidades operativas en tiempo real

Los científicos de datos suelen necesitar la información más reciente. Comprueba si Gemini CLI comprende la diferencia entre un lote diario y una transmisión en vivo.

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

La CLI debería encontrar mkt_realtime_campaign_performance. Identifica la frecuencia de actualización de REALTIME_STREAMING en los metadatos.

Situación 4: Exploración de la zona de pruebas

A veces, "suficiente" es mejor que "perfecto". Comprobar si la CLI de Gemini puede encontrar los datos sin procesar de la zona de pruebas para algún trabajo experimental de AA

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

La CLI debería encontrar tmp_data_dump_v2_final_real. Sabe que esta es la opción correcta porque coincide con el nivel de BRONZE_ADHOC y está marcada explícitamente con is_certified: false.

Cuando termines de hacer pruebas, puedes salir de la sesión de la CLI:

/quit

Realiza una limpieza

Sigue estos pasos para evitar cargos recurrentes:

1. Destruye los recursos de Terraform.

   cd ~/devrel-demos/data-analytics/governance-context/terraform
   terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

2. Desinstala la extensión de Knowledge Catalog y quita los archivos de demostración locales.

   gemini extensions uninstall dataplex
   cd ~
   rm -rf ~/devrel-demos
   

Conclusión

Creaste una base de datos sólida, aplicaste un contexto estricto con metadatos y verificaste que todo funcione de forma local con la CLI de Gemini.