Verificare l'accuratezza delle affermazioni con un agente AI dell'ADK e il modello Gemini

Livello di programmazione: avanzato
Durata: 30 minuti
Tipo di progetto: funzione personalizzata

Panoramica

Una funzione personalizzata di verifica dei fatti per Fogli Google da utilizzare come progetto Apps Script associato basato su un agente Vertex AI e sul modello Gemini.

Questo esempio mostra come utilizzare due potenti tipi di risorse AI direttamente nei fogli di lavoro Google Sheets:

1. Agenti AI per funzionalità di ragionamento sofisticate, multi-strumento e multi-passaggio utilizzando gli agenti ADK di cui è stato eseguito il deployment in Vertex AI Agent Engine.
2. Modelli di AI per funzionalità avanzate di comprensione, generazione e riepilogo utilizzando i modelli Gemini di Vertex AI.

Obiettivi

• Comprendi cosa fa la soluzione.
• Scopri come viene implementata la soluzione.
• Esegui il deployment dell'agente Vertex AI.
• Configura lo script.
• Esegui lo script.

Informazioni su questa soluzione

La funzione personalizzata di Fogli si chiama FACT_CHECK e funziona come soluzione end-to-end. Analizza un'affermazione, basa la sua risposta sulle informazioni web più recenti e restituisce il risultato nel formato che ti serve:

• Utilizzo:
  • =FACT_CHECK("Your statement here") per un output conciso e riassuntivo.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") per un formato di output specifico.
• Motivazione: LLM Auditor ADK AI Agent (Python sample).
• Formattazione dell'output: modello Gemini.

Questa soluzione richiede le API REST Vertex AI utilizzando UrlFetchApp.

Architettura

Il seguente diagramma mostra l'architettura delle risorse Google Workspace e Google Cloud utilizzate dalla funzione personalizzata.

Prerequisiti

Per utilizzare questo esempio, devi soddisfare i seguenti prerequisiti:

• Un Account Google (gli account Google Workspace potrebbero richiedere l'approvazione dell'amministratore).

• Un browser web con accesso a internet.

• Prerequisiti dell'agente LLM Auditor ADK

  • Python 3.11+: per l'installazione, segui le istruzioni sul sito web ufficiale di Python.
  • Python Poetry: per l'installazione, segui le istruzioni sul sito web ufficiale di Poetry.
  • Google Cloud CLI: per l'installazione, segui le istruzioni sul sito web di Google Cloud ufficiale.

Prepara l'ambiente

Questa sezione mostra come creare e configurare un progetto Google Cloud.

Crea un progetto Google Cloud

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Crea un progetto.

   Vai a Crea un progetto

2. Nel campo Project Name (Nome progetto), inserisci un nome descrittivo per il progetto.

   (Facoltativo) Per modificare l'ID progetto, fai clic su Modifica. L'ID progetto non può essere modificato dopo la creazione del progetto, quindi scegli un ID che soddisfi le tue esigenze per l'intera durata del progetto.

3. Nel campo Posizione, fai clic su Sfoglia per visualizzare le potenziali posizioni per il tuo progetto. Quindi, fai clic su Seleziona.
   Attenzione: non riesci a trovare la tua organizzazione Google Workspace?
   Ciò significa che non hai eseguito l'accesso a un account Google Workspace. Alcune delle funzionalità descritte nella documentazione per gli sviluppatori di Google Workspace sono disponibili solo per i progetti associati a un'organizzazione.
4. Fai clic su Crea. La console Google Cloud passa alla pagina Dashboard e il progetto viene creato entro pochi minuti.

Interfaccia a riga di comando gcloud

In uno dei seguenti ambienti di sviluppo, accedi a Google Cloud CLI (gcloud):

• Cloud Shell: per utilizzare un terminale online con gcloud CLI già configurato, attiva Cloud Shell.
  Attiva Cloud Shell
• Shell locale: per utilizzare un ambiente di sviluppo locale, installa e inizializza gcloud CLI.
  Per creare un progetto Cloud, utilizza il comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID impostando l'ID del progetto che vuoi creare.

Abilita la fatturazione per il progetto Cloud

Se non riesci a collegare un account di fatturazione, non disponi delle autorizzazioni necessarie per apportare questa modifica. Per ulteriori informazioni, vedi Autorizzazioni richieste per attivare la fatturazione.

Console Google Cloud

1. Nella console Google Cloud, vai a Fatturazione. Fai clic su Menu > Fatturazione > I miei progetti.

   Vai a Fatturazione per i miei progetti

2. In Seleziona un'organizzazione, scegli l'organizzazione associata al tuo progetto Google Cloud.
3. Nella riga del progetto, apri il menu Azioni (), fai clic su Modifica fatturazione e scegli l'account di fatturazione Cloud.
4. Fai clic su Imposta account.

Interfaccia a riga di comando gcloud

1. Per elencare gli account di fatturazione disponibili, esegui:

   gcloud billing accounts list

2. Collega un account di fatturazione a un progetto Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Sostituisci quanto segue:

   • PROJECT_ID è l'ID progetto del progetto Cloud per il quale vuoi attivare la fatturazione.
   • BILLING_ACCOUNT_ID è l'ID account di fatturazione da collegare al progetto Google Cloud.

Abilita l'API Vertex AI

Console Google Cloud

1. Nella console Google Cloud, abilita l'API Vertex AI.

   Abilita le API

2. Verifica di abilitare l'API Vertex AI nel progetto Cloud corretto, poi fai clic su Avanti.

3. Verifica di abilitare l'API corretta, poi fai clic su Abilita.

Interfaccia a riga di comando gcloud

1. Se necessario, imposta il progetto Cloud corrente su quello che hai creato con il comando gcloud config set project:

   gcloud config set project PROJECT_ID

   Sostituisci PROJECT_ID con l'ID progetto del progetto Cloud che hai creato.

2. Abilita l'API Vertex AI con il comando gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

Crea un service account nella console Google Cloud

Crea un nuovo service account con il ruolo Vertex AI User seguendo questi passaggi:

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Inserisci i dettagli del service account, quindi fai clic su Crea e continua.
   Nota: per impostazione predefinita, Google crea un ID service account univoco. Se vuoi modificare l'ID, modificalo nel campo ID account di servizio.
4. (Facoltativo) Assegna ruoli al tuo service account per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci gli utenti o i gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Gestione dell'impersonificazione degli account di servizio.
7. Fai clic su Fine. Prendi nota dell'indirizzo email del service account.

Interfaccia a riga di comando gcloud

1. Crea l'account di servizio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. (Facoltativo) Assegna ruoli al tuo service account per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

L'account di servizio viene visualizzato nella pagina degli account di servizio. Poi, crea una chiave privata per il service account.

Crea una chiave privata

Avviso: questo esempio utilizza una chiave del service account esportata per semplicità. L'esportazione di una chiave privata non è consigliata in produzione perché non deve essere archiviata in una posizione non sicura, ad esempio il controllo del codice sorgente.

Per scoprire di più sulle implementazioni sicure dei service account e sulle best practice, consulta Scegliere quando utilizzare i service account.

Per creare e scaricare una chiave privata per il service account, segui questi passaggi:

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Seleziona il tuo service account.
3. Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
4. Seleziona JSON, quindi fai clic su Crea.

   Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato come credentials.json nella directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestione delle chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per saperne di più sui service account, consulta la sezione Service account nella documentazione di Google Cloud IAM.

Esegui il deployment dell'agente AI LLM Auditor ADK

1. Se non l'hai ancora fatto, esegui l'autenticazione con il tuo account Google Cloud e configura Google Cloud CLI in modo da utilizzare il tuo progetto Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Sostituisci PROJECT_ID con l'ID del progetto Cloud che hai creato.

2. Scarica questo repository GitHub

   Scarica

3. Nell'ambiente di sviluppo locale che preferisci, estrai il file archivio scaricato e apri la directory adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Crea un nuovo bucket Cloud Storage dedicato all'agente ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con un nome di bucket univoco che vuoi utilizzare.
   2. PROJECT_ID con l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.

5. Imposta le seguenti variabili di ambiente:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con il nome del bucket che hai creato.
   2. PROJECT_ID con l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.

6. Installa e implementa l'agente ADK dall'ambiente virtuale.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Recupera l'ID agente, ti servirà in un secondo momento per configurare la funzione personalizzata.

   python3 deployment/deploy.py --list

Rivedi il codice campione

Se vuoi, prima di creare il nuovo foglio di lavoro, prenditi un momento per esaminare e familiarizzare con il codice di esempio ospitato su GitHub.

Visualizza su GitHub

Creare e configurare in un nuovo foglio di lavoro

1. Fai clic sul pulsante seguente e crea una copia completa del foglio di lavoro Google Sheets di esempio, incluso il progetto Apps Script associato al contenitore.

   Copiare un foglio di lavoro Fogli Google

2. Nel foglio di lavoro appena creato, vai a Estensioni > Apps Script.

3. Nel progetto Apps Script, vai a Impostazioni progetto, fai clic su Modifica proprietà script, poi su Aggiungi proprietà script per aggiungere le seguenti proprietà script:

   1. LOCATION con la posizione del progetto Google Cloud creato nei passaggi precedenti, ad esempio us-central1.
   2. GEMINI_MODEL_ID con il modello Gemini che vuoi utilizzare, ad esempio gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID con l'ID dell'agente LLM Auditor ADK di cui è stato eseguito il deployment nei passaggi precedenti, ad esempio 1234567890.
   4. SERVICE_ACCOUNT_KEY con la chiave JSON dell'account di servizio scaricata nei passaggi precedenti, ad esempio { ... }.

4. Fai clic su Salva proprietà script.

Testare la funzione personalizzata

1. Vai al foglio di lavoro appena creato.
2. Modifica le istruzioni nella colonna A.
3. Le formule nella colonna B vengono eseguite e poi vengono visualizzati i risultati del fact checking.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per questo tutorial, quando lo elimini, elimini anche tutto il lavoro effettuato nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID del progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più tutorial e guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona quello che vuoi eliminare, quindi fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Funzioni personalizzate in Fogli Google
• Estensione di Fogli Google