Ti diamo il benvenuto nel PetVerse.

1. Introduzione

Ti diamo il benvenuto su PetVerse! Tutti gli animali domestici sono i benvenuti. 🐈🐶🐍🐟🦄

Prerequisiti

• Comprensione di base della console Google Cloud
• Conoscenza di base delle istruzioni SQL

Cosa imparerai a fare

• Creare set di dati e tabelle in BigQuery
• Crea colonne ObjectRef per fare riferimento ai contenuti multimediali in un bucket di archiviazione in BigQuery
• Utilizza le funzioni di AI in BigQuery per migliorare il tuo set di dati dai contenuti dei dati non strutturati
• Creare incorporamenti multimediali per cercare contenuti simili
• Crea embedding di testo per eseguire la ricerca semantica con VECTOR_SEARCH
• Utilizzare Gemini CLI per creare un'applicazione web

Che cosa ti serve

• Un account Google Cloud e un progetto Google Cloud con un account di fatturazione
• Un browser web come Chrome

2. Configurazione e requisiti

Configurazione dell'ambiente autonomo

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione:un ID progetto è univoco a livello globale e non può essere utilizzato da altri dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare la località predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.

3. Apri Cloud Shell

Vai a https://shell.cloud.google.com/?show=ide%2Cterminal . Quando richiesto, fai clic su Autorizza.

Assicurati che siano visibili sia l'editor sia la console:

4. Crea uno script di supporto

Per semplificare questa esperienza, creerai uno script di supporto che imposta le variabili di ambiente pertinenti.

Sostituisci <<Project ID>> con il tuo ID progetto di seguito.

Copia il seguente comando nel terminale Cloud Shell e premi Invio per eseguirlo.

gcloud config set project <<PROJECT_ID>>

Suggerimento 💡 : utilizza Ctrl/Command + Maiusc + V per incollare nella console e Ctrl/Command + Maiusc + C per copiare.

Copia il seguente comando nel terminale Cloud Shell e premi Invio per eseguirlo. In questo modo verranno abilitati i servizi necessari, creato il file e modificato in Cloud Shell.

gcloud services enable compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       aiplatform.googleapis.com \
                       storage-component.googleapis.com  \
                       bigqueryconnection.googleapis.com \
run.googleapis.com \
secretmanager.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com  \
iap.googleapis.com
edit  ~/petverse-setup.sh

Dovresti vedere una nuova scheda con il nome del file. Incolla il seguente script nel nuovo file:

#!/bin/bash

# -----------------------------------------------------------------------------
# 1. Global Variables: Set your desired project ID and region here.
# -----------------------------------------------------------------------------

# 🦄 🦄 Set your project ID here ⬇️.

# Example: PROJECT_ID="your-project-id"
PROJECT_ID=""

# Set your desired region here. Default is 'us-central1'.
# Example: REGION="us-east1"
REGION="us-central1"

# -----------------------------------------------------------------------------
# 2. Check and Authenticate
# -----------------------------------------------------------------------------

echo "  ➡️   Checking for active Google Cloud authentication..."

# Check if the user is authenticated; if not, prompt for authentication.
if ! gcloud auth list --format="value(account)" | grep -q @; then
  echo "⚠️   Not authenticated. Please authenticate now."
  gcloud auth login
fi

echo "  ✅   Authentication check passed."

# -----------------------------------------------------------------------------
# 3. Get Project ID from User if not set
# -----------------------------------------------------------------------------

# If PROJECT_ID is not set in the script or as an environment variable,
# prompt the user to choose one.
if [[ -z "$PROJECT_ID" ]] && [[ -n "$DEVSHELL_PROJECT_ID" ]]; then
  PROJECT_ID=$DEVSHELL_PROJECT_ID
fi

if [[ -z "$PROJECT_ID" ]]; then
  echo "  ⚠️   Project ID is not set. Listing available projects:"
 
  # List projects and store them in an array.
  projects_array=($(gcloud projects list --format="value(projectId)"))
 
  # Check if projects were found.
  if [[ ${#projects_array[@]} -eq 0 ]]; then
    echo "  ❌   No projects found. Please ensure your account has access to projects."
    exit 1
  fi
 
  # Display the projects and prompt for input.
  echo " "
  echo "Available Projects:"
  for project in "${projects_array[@]}"; do
    echo "$project"
  done
 
  echo " "
  read -p "Please enter your desired project ID from the list above: " PROJECT_ID
 
  # Validate the user's input by checking if it's in the array.
  if [[ ! " ${projects_array[@]} " =~ " ${PROJECT_ID} " ]]; then
    echo "  ❌   Invalid project ID. Please run the script again and select a valid ID."
    exit 1
  fi
fi

echo "  ✅   Project ID set to: $PROJECT_ID"

# -----------------------------------------------------------------------------
# 4. Set Environment Variables
# -----------------------------------------------------------------------------

# Set the project and region for the current session.
echo "  🔄   Setting Google Cloud configuration for this session..."
gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"

echo "  ✅   Google Cloud configuration updated."
echo "Project ID: $PROJECT_ID"
echo "Region: $REGION"
echo " "
echo "  🎉 🦄 🦄   Script execution complete. You can now use Google Cloud commands in this shell session."

Sostituisci il segnaposto per PROJECT_ID con il nome del tuo progetto:

Copia il seguente comando ed eseguilo nel terminale:

chmod +x petverse-setup.sh
~/petverse-setup.sh

Output previsto:

5. Crea un bucket di archiviazione

Crea un bucket Cloud Storage e copia i contenuti multimediali disponibili nel tuo bucket. Lo utilizzerai per archiviare i contenuti multimediali disponibili per i nostri meravigliosi animali domestici. Creerai anche una connessione per accedere al bucket tramite BigQuery.

Incolla ed esegui questo comando nel terminale:

~/petverse-setup.sh
cd ~/
gcloud storage buckets create gs://$DEVSHELL_PROJECT_ID-petverse --uniform-bucket-level-access --location=us-central1
gcloud storage cp -r gs://sample-data-and-media/petverse/* gs://$DEVSHELL_PROJECT_ID-petverse/
bq mk --dataset --location=us-central1 --project_id=$DEVSHELL_PROJECT_ID petverse
bq mk --connection --location=us-central1 --project_id=$DEVSHELL_PROJECT_ID \
--connection_type=CLOUD_RESOURCE pet-connection
echo "your bucket is gs://$DEVSHELL_PROJECT_ID-petverse "

Nota 🐱 : se vuoi aggiungere una foto del tuo animale domestico, questa è l'occasione giusta. Se lo fai, dovrai modificare il codice durante questo codelab. Carica un'immagine del profilo nel bucket in formato JPG o PNG. Puoi aggiungere video e altre immagini nella cartella additional_media. Assicurati che il bucket che utilizzi sia sicuro e che vi possano accedere solo le persone che vuoi che vedano le immagini e i video.

Nota 💡 : prendi nota del nome del bucket (ad es. <<YOUR_PROJECT_ID>>-petverse).

6. Creare la tabella degli animali domestici

Ora creerai una tabella in BigQuery per archiviare le informazioni sui tuoi animali domestici.

Apri una nuova scheda nel browser. Vai alla pagina https://console.cloud.google.com/bigquery .

Assicurati che nella console sia selezionato lo stesso progetto che hai utilizzato:

Ora puoi creare una tabella utilizzando i dati del file pets.csv. Questo file contiene i nomi, i cibi preferiti, i giocattoli e altre informazioni interessanti sui nostri animali domestici.

Copia il seguente codice in una nuova query SQL per creare una tabella fisica e caricare i dati.

LOAD DATA INTO petverse.pets
OPTIONS(
    description="Table for furry friend data"
  )
FROM FILES (
  skip_leading_rows=1,
  uris = ['gs://<<your_bucket_name>>/pets.csv'],
  format = 'CSV'
);

Sostituisci il segnaposto del bucket nel codice con il bucket che hai creato nel passaggio precedente.

Puoi controllare tutti i tuoi bucket di archiviazione in una scheda del browser separata che punta a questo URL: https://console.cloud.google.com/storage/browser .

Utilizza il pulsante Esegui per eseguire la query.

Una volta caricati correttamente i dati, fai clic su Vai alla tabella.

Fai clic su Anteprima per visualizzare i contenuti della tabella.

Nota 🐱 : se nel passaggio precedente hai aggiunto un'immagine del profilo del tuo animale domestico, dovrai inserire manualmente un record per lui. Apri un editor SQL e aggiorna l'istruzione di inserimento:

INSERT INTO your_dataset.your_table ( Id, Name, Species, Breed, Nationality, Nicknames, Hobby, AdoptionStory, FavoriteFood, FavoriteToy)

VALUES (

@Id,

@Name,

@Species,

@Breed,

@Nationality,

@Nicknames,

@Hobby,

@AdoptionStory,

@FavoriteFood,

@FavoriteToy

);

7. Connetti BigQuery al bucket di archiviazione

Se esamini il bucket che hai creato in precedenza, troverai un insieme di file multimediali relativi a ogni animale domestico.

BigQuery è in grado di leggere questi bucket e utilizzare i file insieme ai dati nelle tabelle. Questo tipo di valore è chiamato ObjectRef.

Recupera l'ID service account per la connessione che hai creato in precedenza facendo clic su di essa nella sezione Connessioni esterne.

Copia l'ID service account.

Vai alla console di amministrazione IAM in una nuova scheda del browser ( https://console.cloud.google.com/iam-admin/ ).

Concedi al service account le autorizzazioni Visualizzatore oggetti Storage e Utente Vertex AI (le utilizzerai in un secondo momento).

Fai clic su Salva e 🕰️ attendi un paio di minuti.

Nella scheda BigQuery, utilizza la seguente query in BigQuery Studio per testare la connessione tra BigQuery e il bucket di archiviazione.

Sostituisci <<PROJECT_ID>> con il tuo ID progetto.

Suggerimento 💡 : utilizza Ctrl/Comando + H per sostituire tutti i valori

SET @@location='us-central1';
SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/yoda_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))

Fai clic su Visualizza risultati. Dovresti ottenere i metadati nei risultati:

Importante ⚠️ : se visualizzi errori, correggili prima di continuare

8. Aggiungi il supporto di archiviazione ai dati strutturati

Puoi migliorare la tabella Animali domestici aggiungendo una colonna con l'immagine del profilo di ogni animale domestico, se disponibile. Aggiungerai anche un'altra colonna con un array di riferimenti ai contenuti multimediali, per contenere tutti gli altri file correlati a ciascun animale domestico.

L'accesso ai contenuti multimediali richiede una connessione, che hai creato all'inizio di questo codelab dopo aver creato il bucket.

Incolla i seguenti comandi in una console SQL di BigQuery ed eseguili per aggiungere due colonne alla tabella pets.

SET @@location='us-central1';
ALTER TABLE petverse.pets
ADD COLUMN IF NOT EXISTS profile_picture STRUCT<uri STRING, version STRING, authorizer STRING, details JSON>,
ADD COLUMN IF NOT EXISTS additional_media ARRAY<STRUCT<uri STRING, version STRING, authorizer STRING, details JSON>>;

Copia le seguenti istruzioni e sostituisci il segnaposto per PROJECT_ID con il tuo ID progetto.

Suggerimento 💡 : utilizza Ctrl/Comando + H per sostituire tutti i valori

SET @@location='us-central1';

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/yoda_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Yoda_asks_for_cuddles.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 1;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/madonna_profile_picture.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Madonna_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 2;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/pixel_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pixel_thug_life.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pixel_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 3;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/sql_profile_picture.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/SQL_description.wav', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/SQL_favorite_toy.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 4;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/buddy_golden_retriever.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 5;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/daisy_french_bulldog.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 6;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/max_german_shepherd.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/max_description_tells_jokes.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 7;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 8;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/rocky_description.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))] WHERE Id = 9;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/pip_hamster.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/pip_Hamster_Wheel_Video_Generated.mp4', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 10;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 11;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/scales_snake.png', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = NULL
WHERE Id = 12;

UPDATE petverse.pets SET profile_picture = NULL, additional_media = NULL WHERE Id = 13;

UPDATE petverse.pets
SET profile_picture = (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/Joel_Profile_Picture.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
    additional_media = [(SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Catwalk.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Flowers.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection'))),
                       (SELECT OBJ.FETCH_METADATA(OBJ.MAKE_REF('gs://<<PROJECT_ID>>-petverse/additional_media/Joel_Plays.jpg', 'projects/<<PROJECT_ID>>/locations/us-central1/connections/pet-connection')))]
WHERE Id = 14;

Nota 🐱 : se hai aggiunto il tuo animale domestico, aggiungi qui una dichiarazione che rifletta i contenuti multimediali aggiuntivi per la sua identificazione.

Esegui l'istruzione. Dopo qualche minuto dovresti vedere le esecuzioni riuscite:

Controlla i risultati utilizzando l'anteprima della tabella. Dovresti visualizzare i metadati delle immagini del profilo esistenti e di altri contenuti multimediali per il gatto di nome Pixel.

SELECT *
FROM `petverse.pets`
WHERE name = 'Pixel'

9. Generare descrizioni di animali domestici

Se visualizzi l'anteprima della tabella animali domestici, noterai che alcuni animali domestici, come Yoda, Pixel o Rocky, non hanno il loro cibo o giocattolo preferito.

Le risposte a queste domande potrebbero trovarsi nei video e negli audio correlati a questi animali domestici. Utilizzerai le funzioni AI incorporate per eseguire il controllo.

Prova con la seguente affermazione:

SELECT name,
AI.GENERATE(
   prompt=> ('What are this pet\'s favorite toy and favorite foods', additional_media ),
    connection_id => 'us-central1.pet-connection',
    endpoint => 'gemini-2.5-flash',
output_schema => 'food STRING, toy STRING')
FROM petverse.pets
WHERE name = 'Rocky'

Nota 📝: se ricevi un errore relativo al provisioning degli agenti di servizio, attendi alcuni minuti e riprova.

Puoi vedere il video di Rocky nel tuo bucket di archiviazione.

Utilizza la seguente istruzione per aggiornare le descrizioni mancanti:

UPDATE petverse.pets AS p
SET FavoriteFood = aigen.food
FROM
  (
    SELECT Id, name,
          AI.GENERATE(
                prompt=> ('What are this pet\'s favorite toy and favorite foods', additional_media ),
                connection_id => 'us-central1.pet-connection',
                endpoint => 'gemini-2.5-flash',
                output_schema => 'food STRING').food
    FROM petverse.pets ) AS  aigen
WHERE p.Id = aigen.Id
AND p.FavoriteFood IS NULL
AND p.additional_media IS NOT NULL

Utilizza la seguente istruzione per creare una descrizione degli animali domestici in base ai loro contenuti multimediali in una nuova colonna:

ALTER TABLE petverse.pets ADD COLUMN MediaDescription STRING;
UPDATE petverse.pets AS p
SET MediaDescription = aigen.description
FROM
  (
    SELECT Id, name,
          AI.GENERATE(
                prompt=> ('Create a description in an epic tone for this pet based on these media: ', additional_media ),
                connection_id => 'us-central1.pet-connection',
                endpoint => 'gemini-2.5-flash',
                output_schema => 'description STRING').description
    FROM petverse.pets ) AS  aigen
WHERE p.Id = aigen.Id
AND p.MediaDescription IS NULL
AND p.additional_media IS NOT NULL

Dopo qualche minuto dovresti visualizzare alcune descrizioni delle creatività:

Curiosità 📝: il file audio di Madonna è in spagnolo.

10. Crea incorporamenti

Crea una tabella per archiviare gli embedding per le immagini del profilo e per le descrizioni e gli hobby da utilizzare in una ricerca semantica. Troveremo somiglianze tra gli animali domestici utilizzando le ricerche vettoriali.

SET @@location='us-central1';

CREATE OR REPLACE MODEL petverse.multimodalembedding
  REMOTE WITH CONNECTION `us-central1.pet-connection`
  OPTIONS(ENDPOINT = 'multimodalembedding@001');

CREATE TABLE IF NOT EXISTS petverse.profile_embeddings
AS
SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL petverse.multimodalembedding,
    (
      SELECT profile_picture as content,
      Id
      FROM petverse.pets)
 );

CREATE OR REPLACE MODEL petverse.textembedding
  REMOTE WITH CONNECTION `us-central1.pet-connection`
  OPTIONS (ENDPOINT = 'text-embedding-005');

CREATE OR REPLACE TABLE petverse.text_embeddings AS
SELECT * FROM ML.GENERATE_EMBEDDING(
  MODEL petverse.textembedding,
  (
    SELECT CONCAT(AdoptionStory, ' . This pet\'s hobby is: ', Hobby, ' and their nickname(s) is: ', COALESCE(Nicknames, Name)) AS content,
    Id, Name
    FROM petverse.pets
    WHERE LENGTH(AdoptionStory) > 0 AND LENGTH(Hobby) > 0
  )
)
WHERE LENGTH(ml_generate_embedding_status) = 0;

Controlla la nuova tabella nella scheda dei risultati.

Utilizza la seguente istruzione per controllare lo stato di tutti gli incorporamenti:

SELECT DISTINCT(ml_generate_embedding_status),
  COUNT(content.uri) AS num_rows
FROM petverse.profile_embeddings
GROUP BY 1;

Se sono presenti errori, li vedrai in uno stato non vuoto. Questo è l'output corretto: non sono presenti record con errori**:**

Di seguito è riportato un esempio di record con errori. Questi errori non sono previsti, ma devono essere corretti prima di procedere con i passaggi successivi:

Importante ⚠️ : se visualizzi degli errori, correggili prima di continuare. Se vedi solo una riga vuota con 10 o più num_rows, puoi continuare.

Cercare animali domestici simili

Il set di dati predefinito contiene animali domestici simili. Ecco due esempi: Pixel (ID: 3) e SQL (ID: 4):

Puoi utilizzare la distanza tra gli incorporamenti per calcolare animali domestici simili:

SELECT
t2.id AS similar_pet_id,
COSINE_DISTANCE(t1.ml_generate_embedding_result, t2.ml_generate_embedding_result) AS distance
FROM
petverse.profile_embeddings AS t1,
petverse.profile_embeddings AS t2
WHERE
t1.Id = 3 -- The pet you want to find similar ones to
AND t1.Id != t2.Id -- Exclude the pet itself from the results
AND t1.content.uri IS NOT NULL
AND t2.content.uri IS NOT NULL
ORDER BY
distance
LIMIT 5;

Dovresti ottenere risultati con gli ID delle immagini simili tra loro. Verrà incluso tutto ciò che è presente nell'immagine. In questo esempio, Pixel e SQL sono simili e l'animale domestico più simile successivo è Joel (ID: 14).

Ecco una foto di Joel come riferimento:

Prova la ricerca semantica

Puoi utilizzare la funzione VECTOR_SEARCH per eseguire ricerche semantiche negli embedding di testo. Se questa tabella fosse più grande, dovresti creare un indice per gli incorporamenti.

SELECT query.query, base.content, base.Name
FROM VECTOR_SEARCH(
  TABLE `petverse.text_embeddings`, 'ml_generate_embedding_result',
  (
  SELECT ml_generate_embedding_result, content AS query
  FROM ML.GENERATE_EMBEDDING(
  MODEL `petverse.textembedding`,
  (SELECT 'Pets who like to relax' AS content))
  ),
  top_k => 5, options => '{"fraction_lists_to_search": 0.50}')
ORDER BY distance DESC

Prova a modificare il termine di ricerca semantica (Pets who like to relax) e il parametro fraction_lists_to_search e vedi cosa succede. Puoi scoprire di più su queste funzioni qui.

11. Creare un vibe coding per una pagina del profilo

⚠️ Importante ⚠️ : per questa operazione sono necessarie alcune conoscenze di sviluppo di applicazioni web (Python, HTML e deployment in Cloud Run). Se vuoi importare un'app funzionante e saltare questo passaggio, segui le istruzioni nel file README di questo repository Git demo.

La CLI può comportare dei costi a seconda della configurazione. La CLI potrebbe anche apportare modifiche all'infrastruttura del tuo progetto e alla directory Cloud Shell. Ti consigliamo vivamente di esaminare le modifiche prima che vengano applicate e di monitorare le esecuzioni per intervenire quando la CLI potrebbe essere in un loop.

Utilizzerai Gemini CLI in Cloud Shell per avviare rapidamente un'applicazione web demo semplice. Questa applicazione web è stata semplificata nel prompt per dimostrare come potrebbe prendere vita il Petverse.

Torna a Cloud Shell. Avrai un'esperienza migliore con la sola console a schermo intero:

Esegui lo script di inizializzazione per assicurarti che le variabili di ambiente siano impostate, crea una directory per contenere questo progetto ed esegui Gemini CLI:

~/petverse-setup.sh
mkdir petverse-profiles
cd petverse-profiles
gemini

Dovresti vedere la CLI di Gemini:

Sostituisci il nome del bucket nel prompt riportato di seguito.

Incolla il prompt nella riga di comando di Gemini.

You are a fullstack engineer creating an application to display the profiles of cats, dogs and other pets stored in BigQuery. The table where these are stored is called pets, in the dataset petverse.
1.Application Requirements: Display the pets with their profile picture, all the other information in the Pets table, and other media that may be available. The pictures are in a GCS bucket, the field in the table pets profile_picture.uri contains the URI for the storage bucket of that profile picture.  The field additional_media is an array of objectref that contains multiple URI to different media stored in a GCS bucket.
Important: In the code, in the values for the URIs retrieved from BigQuery, replace gs://<<YOUR_PROJECT_ID>>-petverse/ with https://storage.mtls.cloud.google.com/<<YOUR_PROJECT_ID>>-petverse/ as follows: replace('gs://', 'https://storage.mtls.cloud.google.com/'). Use the python library. Media can be pictures, videos and audio. Consider these formats in the code. Some pets may not have profile pictures or additional media.
2.Hosting: Create a web application hosted in a single container and service in Cloud Run, use the following syntax to deploy it using IAP. IMPORTANT: DO NOT ADD IAM AUTHENTICATION AND DO NOT ALLOW UNAUTHENTICATED: gcloud beta run deploy SERVICE_NAME  --region=REGION --image=IMAGE_URL  --no-allow-unauthenticated --iap
3.Database access: Display similar pets based on a similarity between embeddings in table petverse.profile_embeddings. 
Here's the schema for the pets table in CSV format (Field name, type, mode):
Id,INTEGER,NULLABLE
Name,STRING,NULLABLE
Species,STRING,NULLABLE
Breed,STRING,NULLABLE
Nationality,STRING,NULLABLE
Nicknames,STRING,NULLABLE
Hobby,STRING,NULLABLE
AdoptionStory,STRING,NULLABLE
FavoriteFood,STRING,NULLABLE
FavoriteToy,STRING,NULLABLE
profile_picture,RECORD,NULLABLE
additional_media,RECORD,REPEATED
profile_embeddings,FLOAT,REPEATED
Here's a sample query to check for similarity:
SELECT
t2.id AS similar_pet_id,
COSINE_DISTANCE(t1.ml_generate_embedding_result, t2.ml_generate_embedding_result) AS distance
FROM
petverse.profile_embeddings AS t1,
petverse.profile_embeddings AS t2
WHERE
t1.Id = 3 -- The pet you want to find similar ones to
AND t1.Id != t2.Id -- Exclude the pet itself from the results
AND t1.content.uri IS NOT NULL
AND t2.content.uri IS NOT NULL
ORDER BY
distance
LIMIT 5;
Complement the profile of each pet with a description. Here's an example of the access to such table:
SELECT Name, MediaDescription from petverse.pets;
4.For each access to BigQuery, show the SQL statement that is used in the console logs.
5.Search functionality: Add a search bar for a semantic search for pets. There's a text embedding for the Adoption story, the pet's past-time or hobby and their nicknames in the table: petverse.text_embeddings . This is a sample of semantic search:
SELECT query.query, base.content, base.Name FROM VECTOR_SEARCH(TABLE `petverse.text_embeddings`, 'ml_generate_embedding_result', ( SELECT ml_generate_embedding_result, content AS query FROM ML.GENERATE_EMBEDDING(MODEL `petverse.textembedding`,(SELECT 'Pets who like to relax' AS content))), top_k => 5, options => '{"fraction_lists_to_search": 0.50}') ORDER BY distance DESC
6.Use Python for the backend. Generate the deployment scripts for an authenticated service using IAP with the flags --no-allow-unauthenticated --iap
7. Make the UI look like a modern art museum.
8. Use the gunicorn library. Validate version dependencies.

Ora l'avventura è tua. Ti verrà mostrato un piano e ti verrà chiesto di confermare i passaggi.

È molto improbabile che il codice e il deployment prodotti funzionino al primo tentativo. Dovrai iterare con Gemini CLI finché non otterrai il risultato corretto.

Nota 📝: se dovessi creare un'applicazione simile in un ambiente di produzione reale, dovresti prendere in considerazione altri aspetti relativi a sicurezza e scalabilità. Esempi sono tecniche di autenticazione più avanzate nel codice, servizi diversi per funzioni diverse (ad es. un backend, un frontend, un accesso al database) o un bilanciatore del carico come punto di accesso.

Se vedi che il processo è bloccato in un ciclo, interrompilo con Ctrl/Command + C, analizza il problema e riprova.

Ti consigliamo di leggere attentamente ciascuna conferma, una per una, per capire cosa farà la CLI:

Dopo alcuni minuti, l'applicazione dovrebbe essere pronta per l'esecuzione. Può capitare che la console sembri bloccata:

Puoi provare manualmente l'applicazione in una nuova scheda di Cloud Shell con gunicorn. Assicurati che il progetto sia impostato:

Dovresti visualizzare il nuovo sito (il suo aspetto potrebbe essere diverso da questo). Se qualcosa non funziona, dovresti essere in grado di visualizzare i log di errore e di debug nella riga di comando di Cloud Shell in esecuzione in locale.

Se tutto è a posto, puoi facoltativamente eseguire il deployment dell'applicazione in Cloud Run.

Se il tuo progetto appartiene a un'organizzazione, assicurati di configurare IAP seguendo queste istruzioni. Se il tuo progetto non fa parte di un'organizzazione, puoi seguire queste istruzioni per proteggere l'accesso alla tua applicazione. Soprattutto per le impostazioni di produzione, ti consigliamo di NON consentire l'accesso non autenticato.

Se il deployment funziona, dovresti vedere l'applicazione Cloud Run in esecuzione nella console Cloud Run.

Assicurati che l'accesso sia solo IAP. Utilizza Modifica criterio per aggiungere l'utente al binding e fai clic su Salva.

⚠️Importante ⚠️ : l'opzione Acquisti in-app sarà disponibile solo per i progetti all'interno di un'organizzazione. Se il tuo progetto non appartiene a un'organizzazione (ad esempio, è stato creato con un account Gmail con "Nessuna organizzazione"), puoi utilizzare un bilanciatore del carico esterno come descritto qui.

Attendi qualche minuto affinché i binding IAP vengano propagati e fai clic sull'URL in alto. Il sito dovrebbe essere visualizzato.

12. Esegui la pulizia

Questo passaggio ti guiderà nell'eliminazione delle risorse create in questo codelab.

Elimina il servizio Cloud Run (adatta il nome dei servizi e della regione in base alle necessità):

gcloud run services delete petverse-profiles --region us-central1

Elimina tutti gli asset BigQuery:

bq rm -f petverse
gcloud bigquery connections delete pet-connection --location=us-central1