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

Los agentes de IA pueden razonar, pero comienzan con cero conocimiento sobre tu empresa específica. Imagina preguntarle 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 más parecido, podría mostrar 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 proporcionen este contexto y usarás la Gemini CLI para probar el contexto de los datos y verificar que un agente pueda fundamentar con precisión sus respuestas en datos confiables y certificados.

Objetivos

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

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 de, 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 las variables PROJECT_ID y REGION para que todos los comandos futuros apunten a tu Google Cloud proyecto específico.

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

3. Habilita los servicios necesarios Google Cloud .

   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 Google Cloud repositorio de DevRel Demos.

   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
   

Compila 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 configurarlo rápidamente.

La configuración de Terraform controla dos tareas:

• Configura los tipos de aspectos de Knowledge Catalog (plantillas de metadatos), los conjuntos de datos y las tablas de BigQuery, 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 puede 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 solo son objetos con columnas. Para solucionar este problema, debes aplicar la administración en el siguiente paso.

Aplica 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 distinguirlas, debes aplicar 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 administración, que aplicarás en el siguiente paso.

Vuelve 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

Agrega aspectos

1. Antes de ejecutar la secuencia de comandos apply_governance.sh, observa 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 empresarial 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 esto marca explícitamente los datos como is_certified: true y les asigna el nivel GOLD_CRITICAL. Esto 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 Google Cloud consola. 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 Etiquetas y aspectos opcionales, busca el aspecto official-data-product-spec. Confirma que los valores coincidan con la situación "Gold Internal" que aplicaste.

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

Prueba el contexto de tus datos con la CLI de Gemini

Antes de compilar una aplicación web completa, puedes probar tu lógica de administración 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.

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

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 los datos, echa un vistazo rápido al archivo GEMINI.md:

   cat GEMINI.md
   

   Observa que el archivo divide las reglas en Fase 1 y Fase 2. Esto aplica un orden estricto de las operaciones. El agente primero debe buscar las etiquetas de administración correctas (Fase 1) antes de que se le permita tocar los datos en sí (Fase 2). Esta lógica de "buscar primero" evita que el agente adivine los nombres de las tablas o alucine respuestas de fuentes no verificadas.

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

Inicia la CLI de Gemini 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 archivo GEMINI.md local como el 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 archivo 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 de servidor de MCP configuradas.

/mcp desc

Probarlo

Ahora es el momento de ver el contexto de tus 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 herramienta para esta sesión" para no tener que aprobar cada paso.

Situación 1: Busca datos de referencia "Gold"

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

Situación 2: Divulgación pública

Imagina 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 más 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 la 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 debe encontrar mkt_realtime_campaign_performance. Identifica la frecuencia de actualización REALTIME_STREAMING en los metadatos.

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

A veces, "suficientemente bueno" es mejor que "perfecto". Comprueba 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 debe encontrar tmp_data_dump_v2_final_real. Sabe que esta es la opción correcta porque coincide con el nivel BRONZE_ADHOC y está marcada explícitamente con is_certified: false.

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

/quit

Limpia

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 tus archivos de demostración locales.

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

Conclusión

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

¿Qué sigue?

• Prueba otros casos de uso de Knowledge Catalog.