Utilizzare l'agente Gemini CLI per testare il contesto dei dati

Gli agenti AI possono ragionare, ma iniziano con zero conoscenze sulla tua azienda specifica. Immagina di chiedere a un agente: "Qual è il nostro fatturato del primo trimestre?" Senza indicazioni, l'agente potrebbe scegliere tra decine di tabelle denominate "fatturato" nei tuoi database, che vanno dai report ufficiali ai dati di test disordinati. Se l'agente sceglie la tabella con il nome più simile, potrebbe restituire risposte convincenti ma errate basate su fonti non verificate.

L'arricchimento dei metadati è la soluzione a questo problema di contesto. In questo tutorial, configurerai gli aspetti che forniscono questo contesto e utilizzerai Gemini CLI per testare il contesto dei dati e verificare che un agente possa basare con precisione le sue risposte su dati attendibili e certificati.

Obiettivi

• Crea un data lake realistico per i test.
• Utilizza gli aspetti di Knowledge Catalog per etichettare i dati "gold" e distinguerli dai dati di test.
• Testa il contesto dei dati localmente con Gemini CLI.

Prima di iniziare

Prima di iniziare, assicurati di:

• Scegli un Google Cloud progetto per questo tutorial.
• Verifica che la fatturazione sia attivata per il tuo progetto.

Per completare questo tutorial, dovresti anche avere una conoscenza di base di BigQuery, Knowledge Catalog e Terraform.

Prepara l'ambiente

Questo tutorial utilizza Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

1. Dallaconsole, fai clic su Attiva Cloud Shell in nella barra degli strumenti in alto a destra. Google Cloud Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente.

2. In Cloud Shell, imposta le variabili PROJECT_ID e REGION in modo che tutti i comandi futuri siano destinati al tuo specifico Google Cloud progetto.

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

3. Abilita i servizi necessari 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 il Google Cloud repository DevRel Demos.

   Scarica il codice e gli script dell'infrastruttura da GitHub. Utilizza un checkout sparse per estrarre solo la cartella specifica di cui hai bisogno per questo tutorial.

   # 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 il data lake

Per rendere le cose realistiche, hai bisogno di un mix di dati ufficiali e dati disordinati e non attendibili. Utilizza Terraform e i file di configurazione Terraform preconfigurati dal repository del tutorial per configurare rapidamente questa opzione.

La configurazione di Terraform gestisce due attività:

• Configura i tipi di aspetti di Knowledge Catalog (modelli di metadati), i set di dati e le tabelle BigQuery, inclusi finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real.
• Carica i dati di esempio nelle tabelle.

1. Apri la directory terraform e inizializzala.

   cd terraform
   terraform init
   

2. Applica la configurazione. Questa operazione potrebbe richiedere fino a un minuto.

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

Ora hai un data lake non gestito. Per un agente AI, le tabelle nel data lake hanno esattamente lo stesso aspetto, poiché sono solo oggetti con colonne. Per risolvere il problema, devi applicare la governance nel passaggio successivo.

Applica la governance

Questa è la parte più importante della configurazione. Al momento, le due tabelle hanno lo stesso aspetto per un agente AI. Per distinguerle, devi applicare gli aspetti, che sono come etichette di metadati certificati che forniscono all'agente il contesto di cui ha bisogno. In questa sezione, utilizzerai due script: uno per generare i metadati e un altro per applicarli alle tabelle.

Genera payload di governance

Terraform ha già configurato i tipi di aspetti, quindi ora devi generare i dati per riempirli.

Esegui lo script ./generate_payloads.sh per creare una directory aspect_payloads/. La directory contiene quattro file YAML che definiscono diversi scenari di governance, che applicherai nel passaggio successivo.

Torna alla radice della directory del tutorial ed esegui lo script ./generate_payloads.sh:

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

Applica gli aspetti

1. Prima di eseguire lo script apply_governance.sh, dai un'occhiata ai dati che verranno allegati alle tabelle. Esegui il comando seguente per visualizzare i metadati definiti per i dati finanziari interni:

   cat aspect_payloads/fin_internal.yaml
   

   Il file YAML definisce il contesto aziendale per la tabella:

   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
   

   Nota come i dati siano contrassegnati esplicitamente come is_certified: true e a cui sia assegnato il livello GOLD_CRITICAL. In questo modo, l'agente AI dispone di regole chiare e strutturate da seguire.

2. Esegui lo script apply_governance.sh. Questo script scorre le tabelle BigQuery e utilizza l'interfaccia a riga di comando gcloud per "stampare" i metadati dai payload YAML su ogni tabella.

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

Verifica i metadati

Prima di procedere, verifica che lo script abbia applicato correttamente gli aspetti.

1. Apri la pagina Knowledge Catalog nella Google Cloud console. Puoi utilizzare la barra di ricerca in alto per trovarla.
2. Cerca fin_monthly_closing_internal. Seleziona il nome della tabella nei risultati per aprire la pagina dei dettagli.
3. Nella sezione Tag e aspetti facoltativi, trova l'aspetto official-data-product-spec. Verifica che i valori corrispondano allo scenario "Gold Internal" che hai applicato.

Ora hai utilizzato correttamente i metadati per distinguere queste tabelle e hai fornito al tuo agente AI un modo per fare lo stesso.

Testa il contesto dei dati con Gemini CLI

Prima di creare un'applicazione web completa, puoi testare la logica di governance localmente utilizzando un ambiente Model Context Protocol (MCP). In questa configurazione, Gemini CLI funge da client (l'interfaccia con cui interagisci) e l'estensione Knowledge Catalog funge da server locale.

Installa l'estensione Knowledge Catalog

In Cloud Shell, installa l'estensione Knowledge Catalog.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Definisci le regole

Il file di configurazione GEMINI.md contiene una logica che trasforma le regole dichiarative come "Ho bisogno di dati sicuri" in ricerche precise che restituiscono solo tabelle con le etichette di governance corrette.

Al momento, il file di configurazione è solo un modello. Devi aggiungere l'ID progetto specifico Google Cloud alle regole in modo che, quando esegui l'interfaccia a riga di comando, questa sia destinata correttamente ai dati gestiti.

1. Aggiungi il tuo PROJECT_ID al file di configurazione.

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

2. Per controllare le modifiche e capire come funziona il contesto dei dati, dai un'occhiata al file GEMINI.md:

   cat GEMINI.md
   

   Tieni presente che il file suddivide le regole in Fase 1 e Fase 2. In questo modo viene applicato un ordine rigoroso delle operazioni. L'agente deve prima cercare le etichette di governance corrette (Fase 1) prima di poter toccare i dati stessi (Fase 2). Questa logica "prima ricerca" impedisce all'agente di indovinare i nomi delle tabelle o di inventare risposte da fonti non verificate.

   Assicurati che la Fase 2 contenga l'ID progetto effettivo Google Cloud . Se non è corretto, l'agente non saprà dove cercare i dati.

Avvia Gemini CLI e testa gli scenari

Avvia una nuova sessione di Gemini. Poiché ti trovi nella cartella del progetto, l'interfaccia a riga di comando rileva e carica automaticamente il file GEMINI.md locale come contesto di sistema.

gemini

Nota: potresti visualizzare il caricamento di più file di contesto (ad esempio, GEMINI.md e altri). È normale. L'interfaccia a riga di comando carica il file GEMINI.md locale per le regole specifiche di questo progetto, oltre alle istruzioni predefinite per l'estensione Knowledge Catalog stessa.

Verifica l'installazione

Verifica che l'estensione Knowledge Catalog sia attiva. dataplex dovrebbe essere visualizzato nell'elenco degli strumenti del server MCP configurati.

/mcp desc

Fai una prova

Ora è il momento di vedere il contesto dei dati in azione. Incolla questi prompt nell'interfaccia a riga di comando uno alla volta.

Suggerimento: l'interfaccia a riga di comando chiede l'autorizzazione a utilizzare i suoi strumenti. Seleziona "2. Consenti strumento per questa sessione" per non dover approvare ogni singolo passaggio.

Scenario 1: trova i dati standard "gold"

Verifica se Gemini CLI riesce a trovare i dati più attendibili per una riunione del consiglio di amministrazione ad alto rischio.

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?

L'interfaccia a riga di comando deve ignorare i dati non elaborati e trovare fin_monthly_closing_internal. Per farlo, confronta la tua richiesta di dati "finalizzati" e "riservati" con i tag GOLD_CRITICAL e INTERNAL_ONLY che hai applicato in precedenza.

Scenario 2: divulgazione pubblica

Supponiamo che tu voglia condividere i dati esternamente. Devi assicurarti che l'interfaccia a riga di comando non riveli segreti interni.

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?

Anche se la tabella interna contiene i dettagli più completi, l'interfaccia a riga di comando deve ignorarla. Dovrebbe indirizzarti a fin_quarterly_public_report perché è l'unica tabella con il tag EXTERNAL_READY.

Scenario 3: esigenze operative in tempo reale

I data scientist hanno spesso bisogno delle informazioni più recenti. Verifica se Gemini CLI comprende la differenza tra un batch giornaliero e uno streaming live.

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?

L'interfaccia a riga di comando deve trovare mkt_realtime_campaign_performance. Identifica la frequenza di aggiornamento REALTIME_STREAMING nei metadati.

Scenario 4: esplorazione della sandbox

A volte "abbastanza buono" è meglio di "perfetto". Verifica se Gemini CLI riesce a trovare i dati non elaborati della sandbox per alcuni lavori di ML sperimentali.

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.

L'interfaccia a riga di comando deve trovare tmp_data_dump_v2_final_real. Sa che questa è la scelta giusta perché corrisponde al livello BRONZE_ADHOC ed è contrassegnata esplicitamente con is_certified: false.

Al termine del test, puoi uscire dalla sessione dell'interfaccia a riga di comando:

/quit

Libera spazio

Per evitare addebiti ricorrenti:

1. Elimina le risorse Terraform.

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

2. Disinstalla l'estensione Knowledge Catalog e rimuovi i file demo locali.

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

Conclusione

Hai creato una base di dati solida, applicato un contesto rigoroso utilizzando i metadati e verificato che tutto funzioni localmente utilizzando Gemini CLI.