Dati non elaborati per la previsione in pochi secondi con gli agenti AI

1. Introduzione

In questo codelab, assumerai il ruolo di data scientist per una società fittizia di yogurt ghiacciato che lancia un nuovo gusto, "Midnight Swirl". Per garantire un lancio globale di successo, l'azienda deve rispondere a domande fondamentali su ingredienti, domanda di mercato e ritorno sull'investimento (ROI). Questo flusso di lavoro end-to-end mostra come il Knowledge Catalog di Google Cloud (precedentemente noto come Dataplex) e Lakehouse per Apache Iceberg (precedentemente noto come BigLake) colmano il divario tra i dati non strutturati "dark" e forniscono business intelligence azionabile utilizzando Gemini nel tuo IDE (VS Code) tramite un livello di governance unificato.

Flusso di lavoro di previsione dei dati non elaborati

In questo lab proverai a:

  • Individuazione non strutturata: le ricette in formato PDF archiviate in Cloud Storage vengono sottoposte a scansione da Knowledge Catalog DataScan. Crea tabelle di oggetti in BigQuery per i PDF scansionati. Utilizzando Vertex AI Semantic Inference, il sistema "legge" i PDF per estrarre informazioni strutturate su prodotti, allergeni, ingredienti e attributi correlati. Poi genera in modo intelligente uno schema per i dati archiviati nei PDF.
  • Metadati unificati: i dati estratti dai file PDF vengono archiviati direttamente in BigQuery come tabella ampia nativa e vengono create viste per facilitare le query comuni. Un set di dati di input indipendente contenente dati storici sulle vendite è archiviato nelle tabelle Apache Iceberg su Google Cloud Storage. Questa tabella Iceberg verrà unita ai dati estratti in BigQuery in un passaggio successivo.
  • Analisi cross-engine: utilizzando Managed Service for Apache Spark (precedentemente noto come Dataproc) con un catalogo REST di Iceberg, unirai questi metadati PDF aggiornati e i dati semantici strutturati inferiti (da tabelle e viste BigQuery) con i dati di vendita strutturati archiviati nelle tabelle Apache Iceberg su Google Cloud Storage. Questa operazione è regolata da un modello di sessione interattiva Managed Apache Spark utilizzato come kernel Jupyter Notebook che garantisce impostazioni di sicurezza e di calcolo coerenti per il job Spark.
  • Approfondimenti semantici: unendo i dati di prodotto dedotti con i dati di clienti e vendite (in BigQuery), la demo è in grado di estrarre approfondimenti come l'identificazione dei dati sugli allergeni e la previsione delle entrate.
  • Governance autonoma: l'intero ciclo di vita, dalle scansioni di rilevamento all'esecuzione di Spark, è orchestrato tramite modelli, istruzioni, regole e automazione basata su agenti pronti per Gemini, dimostrando che l'AI può gestire l'infrastruttura che alimenta l'analisi.

Che cosa ti serve

Il completamento di questo codelab potrebbe comportare costi stimati inferiori a 5 $per l'utilizzo tipico. Per ottenere stime dettagliate dei costi in base all'utilizzo previsto o ai prezzi attuali, utilizza il Calcolatore prezzi di Google Cloud.

Per completare il codelab, assicurati di disporre dei seguenti prerequisiti.

2. Prima di iniziare

Crea un progetto Google Cloud

  1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari.

  1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
  2. Una volta connesso a Cloud Shell, verifica l'autenticazione:
    gcloud auth list
  3. Verifica che il progetto sia configurato:
    gcloud config get project
  4. Se il progetto non è impostato come previsto, impostalo:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Abilita le API richieste

Esegui questo comando per abilitare tutte le API richieste:

  gcloud services enable \
    dataplex.googleapis.com \
    datacatalog.googleapis.com \
    discoveryengine.googleapis.com \
    bigqueryconnection.googleapis.com \
    bigquery.googleapis.com \
    biglake.googleapis.com \
    dataproc.googleapis.com \
    metastore.googleapis.com \
    dataform.googleapis.com \
    notebooks.googleapis.com \
    aiplatform.googleapis.com \
    cloudresourcemanager.googleapis.com \
    serviceusage.googleapis.com \
    secretmanager.googleapis.com \
    storage.googleapis.com

Scarica gli asset del codelab

Questo repository contiene i file Parquet, ricette, fornitori, copilot-instructions.md, template.yaml e quickstart.py da utilizzare con questo codelab. Assicurati di scaricare questi file.

Per scaricare i file:

  1. In Cloud Shell, esegui questo comando:
    git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
  2. Vai alla cartella appena creata:
    cd next-26-keynotes
  3. Estrai la cartella data-cloud-demo
    git sparse-checkout set genkey/data-cloud-demo
  4. Al termine del pagamento, vai alla cartella data-cloud-demo ed estrai i file ZIP per accedere agli asset del codelab.

3. Configurare Lakehouse per i dati dei clienti Froyo

In questa sezione, creerai un catalogo in Lakehouse per utilizzare il metastore Lakehouse per i tuoi flussi di lavoro. Crea interoperabilità tra i motori di query offrendo un'unica fonte attendibile per tutti i dati Iceberg. Consente ai motori di query, come Apache Spark, di rilevare, leggere i metadati e gestire le tabelle Iceberg in modo coerente.

Ruoli obbligatori

Assicurati di disporre dei seguenti ruoli Identity and Access Management (IAM):

  • roles/biglake.viewer
  • roles/bigquery.user
  • roles/bigquery.dataEditor
  • roles/biglake.editor
  • roles/biglake.metadataViewer
  • roles/bigquery.connectionUser
  • roles/storage.objectUser
  • roles/storage.objectViewer
  • roles/storage.objectCreator
  • roles/storage.admin

Per saperne di più sulla concessione dei ruoli IAM, consulta Concedere un ruolo IAM.

Crea un catalogo Lakehouse con un bucket

Crea un catalogo Lakehouse per gestire i metadati delle tabelle Iceberg. Ti connetti a questo catalogo nel tuo job Spark per creare ed eseguire query sulle tabelle Iceberg.

  1. Nella console Google Cloud, vai a Lakehouse.
  2. Fai clic su Crea catalogo. Viene visualizzata la pagina Crea catalogo.
  3. Per Tipo di catalogo, seleziona Catalogo REST Iceberg.
  4. In Seleziona le opzioni del bucket del catalogo Lakehouse, seleziona Catalogo con un solo bucket.
  5. Per Bucket Cloud Storage del catalogo predefinito, fai clic su Sfoglia e poi su Crea nuovo bucket.
  6. Nella pagina Crea un bucket, segui questi passaggi:
  7. Nella sezione Inizia, inserisci un nome univoco globale che soddisfi i requisiti per il nome del bucket.
  8. Nella sezione Scegli dove archiviare i tuoi dati, seleziona Regione per Tipo di località e inserisci la tua regione. Ad esempio: us-west1.
  9. Nella sezione Scegli come controllare l'accesso agli oggetti, deseleziona la casella di controllo Applica la prevenzione dell'accesso pubblico in questo bucket.
    In questo modo puoi simulare scenari reali come l'hosting di contenuti web pubblici o repository di dati condivisi. Senza questa modifica, il bucket applicherebbe un criterio "solo privato" rigoroso; qualsiasi tentativo di accedere ai tuoi asset genererebbe un errore 403 vietato, anche se hai concesso correttamente le autorizzazioni pubbliche ai file.
  10. Fai clic su Continua > Crea > Seleziona > Continua.
  11. In Authentication method (Metodo di autenticazione), seleziona Credential vending mode (Modalità di distribuzione delle credenziali).
  12. Fai clic su Crea.Il catalogo viene creato e si apre la pagina Dettagli catalogo.
  13. Nella sezione Metodo di autenticazione, fai clic su Imposta autorizzazioni bucket.
  14. Nella finestra di dialogo, fai clic su Conferma.In questo modo, viene verificato che l'account di servizio del catalogo disponga del ruolo Storage Object User nel bucket di archiviazione.
  15. Nella pagina Dettagli catalogo, copia il percorso dell'URI del catalogo REST. Utilizza questo percorso durante l'attività Esegui job Spark.

Carica i file Parquet nel bucket

Per caricare i file Parquet nella radice del bucket:

  1. Nella console Google Cloud, vai alla pagina Bucket Cloud Storage.
  2. Nell'elenco dei bucket, fai clic sul nome del bucket. Ad esempio, acai_demo.
  3. Nella scheda Oggetti del bucket, fai clic su Carica > Carica file.
  4. Seleziona i file dalla cartella Parquet che hai clonato nella sezione Prima di iniziare di questo codelab.
  5. Fai clic su Apri.

4. Configura la rete VPC

Crea una rete Virtual Private Cloud (VPC) e una subnet che consenta alle risorse di comunicare con le API di Google senza uscire su internet pubblico e un firewall che consenta al traffico interno di fluire liberamente tra i nodi di elaborazione dei dati.

  1. Nella console Google Cloud, vai alla pagina Reti VPC.
  2. Fai clic su Crea rete VPC.
  3. Inserisci un Nome per la rete. Ad esempio, acai-network.
  4. Per configurare l'unità massima di trasmissione (MTU) della rete, seleziona la casella di controllo Imposta MTU automaticamente.
  5. Scegli Automatica per la Modalità di creazione subnet.
  6. Nella sezione Regole firewall, seleziona tutte le caselle di controllo per Regole firewall IPv4.
  7. Fai clic su Crea.

Abilita l'accesso privato Google

I nodi Dataproc Serverless non hanno indirizzi IP pubblici. Per comunicare con Lakehouse Catalog e Cloud Storage, la subnet deve avere l'accesso privato Google abilitato.

  1. Nella console Google Cloud, vai alla pagina Reti VPC.
  2. Fai clic sul nome della rete che contiene la subnet per la quale devi attivare l'accesso privato Google. Ad esempio, us-west1.
  3. Fai clic sul nome della subnet. Viene visualizzata la pagina dei dettagli Subnet.
  4. Fai clic su Modifica.
  5. Nella sezione Accesso privato Google, seleziona On.
  6. Fai clic su Salva.

5. Crea ed esegui un job Spark

Per creare ed eseguire query su una tabella Iceberg, carica il job PySpark con le istruzioni Spark SQL necessarie. Poi esegui il job con Managed Service for Spark.

Carica quickstart.py nel bucket Cloud Storage

Dopo aver clonato gli asset del codelab, aggiorna lo script quickstart.py con i dettagli del progetto e caricalo nel bucket Cloud Storage.

  1. Apri lo script quickstart.py in un editor di testo.
  2. Sostituisci il segnaposto BUCKET_NAME nello script con il nome del tuo bucket Cloud Storage e salvalo.
  3. Nella console Google Cloud, vai a Bucket Cloud Storage.
  4. Fai clic sul nome del bucket. Ad esempio, acai_demo.
  5. Nella scheda Oggetti, fai clic su Carica > Carica file.
  6. Nel browser di file, seleziona il file quickstart.py aggiornato e poi fai clic su Apri.

Esegui il job Spark

Dopo aver caricato lo script quickstart.py, eseguilo come job batch Managed Service for Spark.

  1. Per configurare le variabili, esegui questo comando in Cloud Shell.
    # Configuration Variables
export PROJECT_ID="<PROJECT_ID>"
export REGION="<REGION>"
export BUCKET_NAME="<BUCKET_NAME>"
export SUBNET="<SUBNET>"
export LAKEHOUSE_CATALOG_ID="<LAKEHOUSE_CATALOG_ID>"
export CATALOG_URI_ID="<CATALOG_URI_ID>"
    Sostituisci quanto segue:
    • LAKEHOUSE_CATALOG_ID: il nome della risorsa del catalogo Lakehouse che contiene il file dell'applicazione PySpark. Ad esempio, acai_demo
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • REGION: la regione in cui eseguire il workload batch Managed Service for Spark. Ad esempio, us-west1.
    • BUCKET_NAME: il nome del tuo bucket Cloud Storage. Ad esempio, acai_demo.
    • SUBNET: il nome della tua subnet VPC. Ad esempio, acai-network.
    • CATALOG_URI_ID: l'ID URI del catalogo Lakehouse che hai copiato durante la creazione di un catalogo Lakehouse con un bucket. Ad esempio, https://biglake.googleapis.com/iceberg/v1/restcatalog.
  2. In Cloud Shell, esegui il seguente job batch Managed Service for Spark utilizzando lo script quickstart.py.
      gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \
     --project=${PROJECT_ID} \
     --region=${REGION} \
     --subnet=${SUBNET} \
     --version=2.2 \
     --properties="\
  spark.sql.defaultCatalog=${LAKEHOUSE_CATALOG_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}=org.apache.iceberg.spark.SparkCatalog,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.type=rest,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.uri=${CATALOG_URI_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.warehouse=gs://${BUCKET_NAME},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.header.x-goog-user-project=${PROJECT_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
  spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.rest-metrics-reporting-enabled=false,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.header.X-Iceberg-Access-Delegation=vended-credentials,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"
    Puoi osservare lo stato dei job Spark in esecuzione in Batch Dataproc.Al termine del job, viene visualizzato un output simile al seguente:
     All tables registered successfully!
 Batch [126fa2226a904d2e944c8eecbe0b1840] finished.
 metadata:
   '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
   batch: projects/PROJECT_ID/locations/REGION/batches/126fa2226a904d2e944c8eecbe0b1840
   batchUuid: 3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
   createTime: '2026-04-09T13:17:26.222727Z'
   description: Batch
   labels:
     goog-dataproc-batch-id: 126fa2226a904d2e944c8eecbe0b1840
     goog-dataproc-batch-uuid: 3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
     goog-dataproc-drz-resource-uuid: batch-3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
     goog-dataproc-location: REGION
   operationType: BATCH
 name: projects/PROJECT_ID/regions/REGION/operations/47bc59e8-5082-3af9-89a0-22289aa5f4b9

6. Esegui query sulla tabella da BigQuery

Eseguendo correttamente il job batch Spark, hai utilizzato Managed Service for Spark Serverless come motore di calcolo distribuito per registrare più tabelle, una per ogni file Parquet all'interno di Lakehouse Metastore. Questa registrazione consente a Google Cloud di trattare i tuoi file non elaborati in Cloud Storage come tabelle strutturate ad alte prestazioni.

I seguenti passaggi ti guidano nella verifica della corretta sincronizzazione dei metadati, assicurando che i tuoi dati non solo siano archiviati in modo sicuro, ma siano anche completamente rilevabili e interrogabili tramite l'interfaccia BigQuery.

  1. Nella console Google Cloud, vai a BigQuery.
  2. Nell'editor di query, inserisci la seguente istruzione. La query utilizza la sintassi project.namespace.dataset.table.
    SELECT * FROM `<PROJECT_ID>.<NAMESPACE>.<ICEBERG_DATASET>.<ICEBERG_TABLE>`
    Ad esempio, SELECT * FROM PROJECT_ID.acai_demo.acai_dataset.order_items.
    Sostituisci quanto segue:
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • NAMESPACE: lo spazio dei nomi creato nel passaggio precedente come risultato del job Spark, che puoi trovare nella pagina dell'Explorer oggetti BigQuery. Ad esempio, acai_demo.
    • ICEBERG_DATASET: il nome del set di dati all'interno del catalogo Iceberg, ad esempio acai_dataset.
    • ICEBERG_TABLE: il nome della tabella all'interno del set di dati Iceberg, ad esempio order_items.
  3. Fai clic su Esegui. I risultati della query mostrano i dati che hai inserito con il job Spark.Il risultato dei dati per la tabella di BigQuery

7. Configurare i file di dati di prodotto non strutturati

In questa sezione, crei una struttura organizzativa in BigQuery per archiviare i dati di fornitori e ricette di Froyo, in particolare per i dettagli del prodotto Froyo. Stabilisce anche una connessione alle risorse cloud, che funge da "ponte" sicuro che consente a BigQuery di leggere i file da origini esterne come Cloud Storage.

Crea il bucket e carica i file di dettagli di Froyo

Crea e carica i file del fornitore e della ricetta nel bucket Cloud Storage.

  1. Nella console Google Cloud, vai alla pagina Bucket Cloud Storage.
  2. Fai clic su Crea.
  3. Nella pagina Crea un bucket, inserisci le informazioni del bucket. Dopo ogni passaggio riportato di seguito, fai clic su Continua per passare al passaggio successivo:
  4. Nella sezione Inizia, inserisci il nome del bucket. Ad esempio, acai_pdfs.
  5. Nella sezione Scegli dove archiviare i tuoi dati, seleziona Regione e poi inserisci la tua regione. Ad esempio: us-west1.
  6. Nella sezione Scegli come controllare l'accesso agli oggetti, deseleziona la casella di controllo Applica la prevenzione dell'accesso pubblico in questo bucket.
  7. Fai clic su Crea.
  8. Nell'elenco dei bucket, fai clic su quello che hai creato. Ad esempio, acai_pdfs.
  9. Nella scheda Oggetti del bucket, fai clic su Carica > Carica cartelle.
  10. Seleziona la cartella recipes che hai estratto nella sezione Prima di iniziare di questo codelab.
  11. Fai clic su Carica.
  12. Ripeti la procedura di caricamento per la cartella suppliers.

Crea una connessione

Crea una connessione alle risorse Cloud. In questo modo viene generato un service account univoco che funge da "documento di identità" di BigQuery per accedere ai file esterni.

  1. Vai alla pagina BigQuery.
  2. Nel riquadro a sinistra, fai clic su Explorer. Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro a sinistra per aprirlo.
  3. Nel riquadro Explorer, espandi il nome del progetto e fai clic su Connessioni.
  4. Nella pagina Connessioni, fai clic su Crea connessione.
  5. Per il tipo Connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).
  6. Nel campo ID connessione, inserisci il nome dell'ID connessione. Ad esempio, acai_pdf_connection. Assicurati di annotare questo ID, perché ti servirà quando configurerai la scansione dei dati più avanti in questo codelab.
  7. Imposta Tipo di località su Regione, quindi seleziona una regione. Ad esempio: us-west1. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.
  8. Fai clic su Crea connessione.
  9. Fai clic su Vai alla connessione.
  10. Nel riquadro Informazioni sulla connessione, copia l'ID dell'account di servizio da utilizzare in un passaggio successivo. Il service account è simile a bqcx-175930350285-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com.

Gestire l'accesso agli account di servizio

Fornisci l'accesso al service account in modo che Lakehouse possa leggere i tuoi PDF.

  1. Vai alla pagina IAM e amministrazione.
  2. Fai clic su Concedi l'accesso. Si apre la finestra di dialogo Aggiungi entità.
  3. Nel campo Nuove entità, inserisci l'ID account del service account che hai copiato in precedenza.
  4. Nel campo Seleziona un ruolo, aggiungi i seguenti ruoli:
    • roles/storage.objectUser
    • roles/storage.objectViewer
    • roles/bigquery.user
    • roles/bigquery.dataEditor
    • roles/aiplatform.user
    • roles/storage.admin
    • roles/dataproc.serviceAgent
  5. Fai clic su Salva.

Per saperne di più sui ruoli IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

8. Gestisci le autorizzazioni per il job DataScan

Crea account di servizio (identità) specifici per Spark e Dataform, quindi concedi a questi, insieme agli agenti di servizio automatizzati di Google, le autorizzazioni precise necessarie per leggere l'archiviazione, eseguire job BigQuery e utilizzare Vertex AI per l'individuazione.

Accesso IAM per Spark e Dataform

  1. Nella console Google Cloud, vai alla pagina Crea service account.
  2. Se non è selezionato, seleziona il tuo progetto Google Cloud.
  3. Fai clic su Crea account di servizio.
  4. Inserisci un nome per il service account. Ad esempio, sa-spark-stg1. La console Google Cloud genera un ID service account in base a questo nome. Modifica l'ID, se necessario. Non potrai modificare l'ID in un secondo momento.
  5. Per impostare i controlli dell'accesso, fai clic su Crea e continua e vai al passaggio successivo.
  6. Scegli i seguenti ruoli IAM da concedere al service account nel progetto.
    • roles/dataproc.worker
    • roles/storage.objectUser
    • roles/bigquery.dataEditor
    • roles/bigquery.jobUser
    • roles/aiplatform.user
    • roles/dataplex.discoveryPublishingServiceAgent
  7. Quando hai finito di aggiungere i ruoli, fai clic su Continua.
  8. Fai clic su Fine per completare la creazione del service account.

Autorizzazioni di connessione BigQuery per l'accesso a Knowledge Catalog

  1. Nella console Google Cloud, vai alla pagina Bucket Cloud Storage.
  2. Nell'elenco dei bucket, fai clic sul nome del bucket che hai creato per Froyo. Ad esempio, acai_pdfs.
  3. Nella scheda Autorizzazioni, fai clic su Concedi l'accesso. Viene visualizzata la finestra di dialogo Aggiungi entità.
  4. Nel campo Nuove entità, inserisci l'ID del service account BigQuery. Il service account è simile a bqcx-175930350285-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com.
  5. Seleziona il seguente ruolo (o ruoli) dal menu a discesa Seleziona un ruolo.
    • roles/storage.objectUser
    • roles/dataplex.serviceAgent
    • roles/dataplex.securityAdmin
    • roles/aiplatform.serviceAgent
    • roles/dataplex.discoveryPublishingServiceAgent
  6. Fai clic su Salva.

9. Configurare Knowledge Catalog

Crea un Knowledge Catalog per unificare i dati correlati a Froyo e automatizzare l'individuazione di file non strutturati (come ricette in PDF e fornitori in PDF).

Crea DataScan tramite curl

In questa sezione, crei scansioni per il tuo bucket Cloud Storage (ad esempio acai_pdfs) aggiungendo datascan_ID e indirizzandolo ai tuoi set di dati BigQuery. Dopodiché, Knowledge Catalog creerà automaticamente le voci per i tuoi PDF in BigQuery.

  1. Per eseguire la scansione dei PDF (fornitori e ricette), esegui il comando seguente:
    # 1. Set your variables
PROJECT_ID="<PROJECT_ID>"
REGION="<REGION>"
ENV_SUFFIX="stg1"
DATASCAN_ID="froyo-profile-${ENV_SUFFIX}"
BUCKET_NAME="<BUCKET_NAME>"

# 2. Set this to the Name of the connection you created in Step 7
CONNECTION_ID="<CONNECTION_ID_NAME>"

# 3. Define the API Endpoint
DATAPLEX_API="dataplex.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}"

# 4. Create the DataScan via CURL
echo "Creating Dataplex DataScan: ${DATASCAN_ID}..."

curl -X POST "https://$DATAPLEX_API/dataScans?dataScanId=${DATASCAN_ID}" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"data": {
   "resource": "//storage.googleapis.com/projects/'"${PROJECT_ID}"'/buckets/'"${BUCKET_NAME}"'"
   },
"executionSpec": {
   "trigger": {
      "on_demand": {}
   }
},
"dataDiscoverySpec": {
   "bigqueryPublishingConfig": {
      "tableType": "BIGLAKE",
      "connection": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/connections/'"${CONNECTION_ID}"'"
   },
   "storageConfig": {
      "unstructuredDataOptions": {
      "entity_inference_enabled": true
      }
   }
   }
}'
  2. Il comando curl mostra i risultati di Knowledge Catalog DataScan, in modo simile all'immagine seguente. Il risultato della scansione dei dati

Esegui il job

Esegui questo comando:

  gcloud dataplex datascans run $DATASCAN_ID --location=$REGION

Descrivere un lavoro

Per descrivere il job, esegui questo comando:

  gcloud dataplex datascans describe $DATASCAN_ID --location=$REGION

Eliminare un job di scansione dei dati

Se la scansione viene eseguita per più di 10 minuti o se lo stato del job rimane In attesa per un periodo di tempo prolungato senza passare a In esecuzione, il problema potrebbe essere dovuto alla mancata disponibilità temporanea delle risorse nella regione. In questo caso, puoi eseguire il comando seguente per eliminare il job, quindi provare a crearlo ed eseguirlo di nuovo. A volte, un'esecuzione iniziale potrebbe non riuscire rapidamente con un errore come unable to acquire necessary resources.

   gcloud dataplex datascans delete $DATASCAN_ID --location=$REGION

Visualizzare lo stato del job

Per controllare lo stato del job:

  1. Nella console Google Cloud, vai alla pagina Curation dei metadati.
  2. Nella scheda Rilevamento Cloud Storage, fai clic sul nome delle scansioni di rilevamento.Lo stato del job
  3. Nella pagina Dettagli scansione, puoi visualizzare lo stato del job.
  4. Al termine del job, controlla se è presente il set di dati pubblicato (ad esempio, acai_pdfs_discovered_003) che hai creato utilizzando il comando curl.Set di dati pubblicato dopo la scansione

Visualizzare la tabella degli oggetti

Per visualizzare la tabella degli oggetti creata dopo il job di rilevamento:

  1. Nella console Google Cloud, vai a BigQuery.
  2. Fai clic su Set di dati e seleziona il set di dati pubblicato creato nel passaggio precedente. Ad esempio, acai_pdfs_discovered_003.
  3. Per visualizzare la tabella degli oggetti, fai clic sull'ID tabella. Ad esempio, acai_pdfs.
  4. La tabella degli oggetti risultante è simile all'immagine seguente:Tabella degli oggetti del set di dati pubblicato

10. Estrazione semantica

Inferirai ed estrarrai tabelle strutturate, altri oggetti di database e relazioni per questa tabella di oggetti non strutturati che hai creato nel passaggio precedente. Per farlo, utilizzerai la funzionalità Knowledge Catalog Insights per generare istruzioni SQL per estrarre dati strutturati dalla tabella non strutturata.

  1. Nella console Google Cloud, vai alla pagina Ricerca nel catalogo delle conoscenze.
  2. Cerca la tabella del set di dati per cui vuoi visualizzare gli approfondimenti. Ad esempio, acai_pdfs_discovered_003. Visualizza la tabella in Knowledge Catalog
  3. Nei risultati di ricerca, fai clic sulla tabella per aprire la relativa pagina di inserimento.
  4. Fai clic sulla scheda Approfondimenti. Se la scheda è vuota, significa che gli approfondimenti per questa tabella non sono ancora stati generati. La generazione di insight potrebbe richiedere dai 15 ai 25 minuti.
  5. Una volta visualizzati gli approfondimenti, fai clic su Estrai > Estrai con SQL.Estrai insight con SQL
  6. Nella pagina Estrai con SQL, inserisci il set di dati in Destinazione. Ad esempio: acai_pdfs_discovered_003.
  7. Fai clic su Estrai. Si apre l'editor BigQuery con la query caricata.
  8. Fai clic su Esegui. Questo passaggio genera un insieme di istruzioni e potrebbe richiedere alcuni minuti per il completamento dell'esecuzione.
  9. Al termine della query, vengono visualizzati i seguenti risultati:Il risultato della query sugli approfondimenti estratti
  10. Vai a BigQuery e fai clic su Set di dati (ad esempio acai_pdfs_discovered_003). Nel set di dati selezionato al passaggio 6 viene creato un nuovo insieme di oggetti di database strutturati.Il risultato del database strutturato

Genera insight per l'oggetto in BigQuery

Per generare approfondimenti per un set di dati BigQuery, devi accedere al set di dati in BigQuery utilizzando BigQuery Studio.

  1. Nella console Google Cloud, vai a BigQuery Studio.
  2. Nel riquadro Spazio di esplorazione, seleziona il progetto e vai al set di dati per cui vuoi generare approfondimenti.
  3. Fai clic sulla scheda Approfondimenti.
  4. Se vedi il pulsante Abilita API, fai clic per abilitare Gemini in Google Cloud. Si aprirà la finestra Abilita funzionalità principali.
    1. Nella sezione API delle funzionalità principali, fai clic su Attiva per API Gemini for Google Cloud e API BigQuery Unified, quindi fai clic su Avanti.
    2. Nella sezione Autorizzazioni (facoltativo), concedi i ruoli IAM alle entità se necessario, quindi fai clic su Avanti.
  5. Per generare insight e pubblicarli in Knowledge Catalog, fai clic su Genera e pubblica.
  6. Una volta pubblicate, potrai visualizzare le statistiche nella scheda.Gli approfondimenti per l&#39;oggetto in BigQuery

11. Configurare l'IDE per l'analisi dei dati con agenti

L'estensione Google Cloud Data Agent Kit per Visual Studio Code è un'estensione IDE per data scientist e data engineer. Consente di connettersi e lavorare con le risorse e i dati di Google Data Cloud direttamente dall'IDE. Per ulteriori informazioni, consulta la panoramica dell'estensione Data Agent Kit per VS Code.

L'estensione Data Agent Kit per VS Code è utile quando vuoi:

  • Crea, testa, rivedi e implementa una pipeline di dati pronta per la produzione, come Spark ETL o BigQuery ETL, direttamente da VS Code.
  • Esplora i dati, crea una pipeline di addestramento, identifica i modelli ML ottimali ed esegui il deployment in un endpoint di produzione utilizzando l'assistenza AI.
  • Connettiti a origini dati attendibili, crea un modello di dati ad alte prestazioni e pubblica una dashboard interattiva per gli stakeholder aziendali.

Installa l'estensione Data Agent Kit per VS Code

  1. Apri VS Code.
  2. Installa Google Cloud CLI. Per saperne di più, consulta Installa Google Cloud CLI.
  3. Installa l'estensione Data Agent Kit per VS Code.
  4. Completa la procedura di onboarding dell'estensione, che richiede di:
    • Accedere all'estensione
    • Installare le skill, server MCP
  5. Ricarica o riavvia la finestra al termine dell'onboarding. Per saperne di più, vedi Configurare l'estensione Data Agent Kit per VS Code.
  6. Dopo il ricaricamento dell'IDE, fai clic sull'icona Google Data Cloud nel riquadro di navigazione, vai alle impostazioni e assicurati di aver impostato correttamente l'ID progetto e la regione (us-west1) nelle impostazioni comuni.

Configurare lo spazio di lavoro in VS Code

  1. Apri VS Code e seleziona File > Apri cartella > Nuova cartella.
  2. Crea una nuova cartella denominata acai_test e poi fai clic su Apri. VS Code ora considera la cartella che hai aperto come uno spazio di lavoro.
  3. Nella finestra di dialogo Affidabilità dello spazio di lavoro, seleziona Sì, mi fido degli autori per attivare tutte le funzionalità dello spazio di lavoro.
  4. Crea una cartella .github nello spazio di lavoro acai_test.
  5. Crea un nuovo file copilot-instructions.md nella cartella .github e inserisci le seguenti regole.
    ## 1. Project Context
- **Project ID**: <PROJECT_ID>
- **Domain**: This project is centralized around "Froyo", a brand of frozen yogurt offering multiple flavors.
- **Documentation**: Raw PDF documents detailing flavors and ingredients are stored in Google Cloud Storage at `gs://<BUCKET_NAME>`.

## 2. Execution & Data Processing Rules
- **CRITICAL RULE - Structured Specs**: The semantic and structured information extracted from the PDFs is available in a BigQuery dataset named `<BQ_DATASET_NAME>` (referred to as the Knowledge Catalog).
- **CRITICAL RULE - Customer Data**: Existing Froyo customer data resides in BigQuery in the dataset `<DATASET_ID>`. When you are referencing a dataset, ensure you are using it with the project ID (`<PROJECT_ID>`) and namespace prefix `<NAMESPACE_NAME>`. For example, to query order table in this dataset you should use `<PROJECT_ID>.<NAMESPACE>.<DATASET_ID>.orders`.
- **CRITICAL RULE - Data Joins between BigQuery dataset and Iceberg dataset**: ANY task requiring a join or integration between the BigQuery datasets `<DATASET_ID>` of the PDF data and the `<DATASET_ID>` of the customer data MUST be executed using **Spark Notebooks**.
- **CRITICAL RULE - Notebook Kernel**: Every Spark notebook utilized MUST exclusively be configured to run on the Serverless Session template `iceberg-federation-template` as its kernel.
- **CRITICAL RULE - Data Science**: ANY data science, machine learning, or advanced analytical task MUST be performed strictly within **Spark Notebooks** using the aforementioned setup.
  6. Crea un altro nuovo file template.yaml nello spazio di lavoro acai_test e inserisci le seguenti informazioni nel file.
    labels:
 client: "vscode"
jupyterSession:
 displayName: "iceberg-federation-template"
 kernel: "PYTHON"
environmentConfig:
 executionConfig:
   serviceAccount: "sa-spark-dev1@<PROJECT_ID>.iam.gserviceaccount.com"
   subnetworkUri: "projects/<PROJECT_ID>/regions/<REGION>/subnetworks/<SUBNET_NAME>"
runtimeConfig:
 version: "2.3"
 properties:
 # This enables the secure proxy URL you were looking for
   dataproc.tier: "premium"
   spark.dataproc.engine: "lightningEngine"
   spark.dataproc.lightningEngine.runtime: "native"
   spark.memory.offHeap.enabled: "true"
   spark.memory.offHeap.size: "1g"
   spark.executor.memory: "4g"
   "dataproc.component.gateway.enabled": "true"
   "dataproc.jupyter.listen.all.interfaces": "true"
   "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
   "spark.sql.defaultCatalog": "<CATALOG_NAME>"
   "spark.sql.catalog.<CATALOG_NAME>": "org.apache.iceberg.spark.SparkCatalog"
   "spark.sql.catalog.<CATALOG_NAME>.type": "rest"
   "spark.sql.catalog.<CATALOG_NAME>.uri": "<CATALOG_URI_ID>"
   "spark.sql.catalog.<CATALOG_NAME>.warehouse": "bl://projects/<PROJECT_ID>/catalogs/<CATALOG_NAME>"
   "spark.sql.catalog.<CATALOG_NAME>.rest.auth.type": "org.apache.iceberg.gcp.auth.GoogleAuthManager"
  7. In VS Code, fai clic su Terminale ed esegui questo comando per importare il file template.yaml come modello di sessione. Questo modello viene utilizzato in un secondo momento dall'agente per creare una sessione Spark.
    gcloud beta dataproc session-templates import iceberg-federation-template \
    --source=template.yaml \
    --location=<REGION>
    Sostituisci REGION con la tua regione.

12. Eseguire l'analisi dei dati agentica

  1. Nell'editor di codice di VS Code, fai clic su Attiva/disattiva chat.
  2. In Configura agenti personalizzati, seleziona Agente. Seleziona l&#39;agente in VS Code
  3. Nel riquadro Modelli di ricerca, fai clic su Gestisci modelli linguistici. L&#39;icona di gestione del modello in VS Code
  4. Nella pagina Modelli linguistici, fai clic su Aggiungi modelli.
  5. Seleziona Google dall'elenco e premi Invio per confermare l'input.Aggiungere il modello Google Gemini in VS Code
  6. Per inserire la chiave API per Google Gemini, procedi nel seguente modo:
    1. Vai al sito web di Google AI Studio.
    2. Accedi con il tuo Account Google.
    3. Nella barra laterale, fai clic su Ottieni chiave API.
    4. Fai clic su Crea chiave API. Si apre la pagina Crea una nuova chiave.
    5. Dall'elenco Seleziona un progetto cloud, seleziona Importa progetto.
    6. Inserisci il nome di un progetto esistente.
    7. Fai clic su Crea chiave e copia la chiave API. La chiave fornisce l'accesso alle risorse dell'API Gemini del tuo account.Per saperne di più, consulta Utilizzo delle chiavi API Gemini.
  7. Incolla la chiave API che hai generato nella barra di ricerca e fai clic su Invio. Chiave API Gemini
  8. Se i modelli Gemini non vengono visualizzati, mostrali come illustrato nell'immagine seguente: Mostrare i modelli Google Gemini
  9. Seleziona Anteprima di Gemini 3.1 Pro dall'elenco dei modelli Google Gemini e chiudi la finestra Modelli linguistici.
  10. Nella finestra della chat, inserisci la seguente domanda:
       Search ingredients for Midnight papaya
  11. Dopo alcune interazioni, dovresti vedere il seguente risultato:Risultati della richiesta di informazioni sugli ingredienti di Midnight Papaya
  12. Nella finestra della chat, inserisci un'altra domanda:
       Search allergen information for Midnight papaya
  13. Dopo alcune interazioni e passaggi, l'agente risponderà con il nome dell'allergene Soy, come puoi vedere nell'immagine seguente:Risultati del test dell&#39;allergene papaya di mezzanotte
  14. Nella finestra della chat, inserisci un'altra domanda:
       Build a pipeline to join products with our 'Global Loyalty' Iceberg tables in acai customer, sales data to identify popular products
  15. Per selezionare il kernel, apri il file .ipynb e fai clic su Seleziona kernel > Kernel Spark remoti > Iceberg-federation-template su Spark serverlessSelezionare il kernel in VS Code
  16. Dopo alcune interazioni e passaggi, vedrai l'agente rispondere con tutti i passaggi del notebook eseguiti correttamente, insieme al risultato finale generato alla fine del notebook, come puoi vedere nell'immagine seguente:Risultati della query sulle tabelle Iceberg

13. Esegui la pulizia

Per evitare che ti vengano addebitati dei costi, elimina le risorse che hai creato in questo lab.

  1. Per eliminare Knowledge Catalog DataScan, esegui questo comando:
      DATASCAN_ID="<DATASCAN_ID>"
  echo "Deleting Dataplex DataScan: ${DATASCAN_ID}"
  gcloud dataplex datascans delete "${DATASCAN_ID}" --location="${REGION}" --quiet
  2. Per eliminare i bucket Cloud Storage e tutti i relativi contenuti, esegui questo comando:
      echo "Deleting Cloud Storage buckets: <BUCKET_NAME1> and <BUCKET_NAME2>"
  gsutil -m rm -r gs://<BUCKET_NAME1>
  gsutil -m rm -r gs://<BUCKET_NAME2>
  3. Per eliminare la connessione BigQuery, esegui questo comando:
      CONNECTION_ID="<CONNECTION_NAME>"
  echo "Deleting BigQuery Connection: ${CONNECTION_ID}"
  bq rm --connection "${PROJECT_ID}.${REGION}.${CONNECTION_ID}"
  4. Per eliminare Lakehouse Catalog, esegui questo comando:
      CATALOG_ID="<CATALOG_NAME>"
  echo "Deleting Lakehouse Catalog: ${CATALOG_ID}"
  gcloud biglake catalogs delete "${CATALOG_ID}" --project="${PROJECT_ID}" --location="${REGION}" --quiet
  5. Per eliminare il set di dati contenente le tabelle PDF rilevate, esegui questo comando:
      DATASET_NAME="<DATASET_NAME>"
  echo "Deleting BigQuery Dataset: ${DATASET_NAME}"
  bq rm -r -f "${PROJECT_ID}:${DATASET_NAME}"
  6. Per eliminare il service account personalizzato, esegui questo comando:
      SERVICE_ACCOUNT="<SERVICE_ACCOUNT>"
  echo "Deleting Service Account: ${SERVICE_ACCOUNT}"
  gcloud iam service-accounts delete "${SERVICE_ACCOUNT}"@"${PROJECT_ID}".iam.gserviceaccount.com --quiet
  7. Per eliminare la rete VPC, esegui questo comando:
      VPC_NETWORK="<VPC_NETWORK>"
  echo "Deleting VPC Network: ${VPC_NETWORK}"
  gcloud compute networks delete "${VPC_NETWORK}" --quiet
  8. Per eliminare l'intero progetto Google Cloud, esegui questo comando:
      gcloud projects delete "${PROJECT_ID}"

14. Complimenti

Complimenti! Hai organizzato correttamente il panorama dei dati di PDF e file Parquet isolati in tabelle BigQuery e li hai raggruppati in un unico ecosistema ricercabile e unibile. In sostanza, hai creato un moderno data lakehouse che tratta i PDF e i formati di big data in modo intelligente come tratta una riga di un database. E hai fatto tutto questo direttamente dal tuo agente in un'esperienza conversazionale con Gemini.

Documenti di riferimento

Per approfondire le tecnologie di base utilizzate in questo codelab, consulta la documentazione ufficiale di Google Cloud: