Bienvenue dans le PetVerse !

1. Introduction

Bienvenue dans le Petverse ! Tous les animaux de compagnie sont les bienvenus ! 🐈🐶🐍🐟🦄

Prérequis

• Connaissances de base concernant la console Google Cloud
• Comprendre les bases des instructions SQL

Points abordés

• Créer des ensembles de données et des tables dans BigQuery
• Créer des colonnes ObjectRef pour référencer des contenus multimédias dans un bucket de stockage dans BigQuery
• Utiliser des fonctions d'IA dans BigQuery pour améliorer votre ensemble de données à partir du contenu de données non structurées
• Créer des embeddings multimédias pour rechercher des contenus similaires
• Créer des embeddings de texte pour effectuer une recherche sémantique avec VECTOR_SEARCH
• Utiliser Gemini CLI pour créer une application Web

Prérequis

• Un compte Google Cloud et un projet Google Cloud avec un compte de facturation
• Un navigateur Web tel que Chrome

2. Préparation

Configuration de l'environnement au rythme de chacun

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.

• Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
• Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention : Un ID de projet est unique. Une fois que vous l'avez choisi, personne d'autre ne peut l'employer. Vous en êtes le seul utilisateur. Même si un projet est supprimé, son ID ne peut pas être réutilisé.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

3. Ouvrir Cloud Shell

Accédez à https://shell.cloud.google.com/?show=ide%2Cterminal . Lorsque vous y êtes invité, cliquez sur Autoriser.

Assurez-vous que l'éditeur et la console sont visibles :

4. Créer un script d'assistance

Pour rendre cette expérience plus fluide, vous allez créer un script d'assistance qui définit les variables d'environnement pertinentes.

Remplacez <<ID du projet>> par l'ID de votre projet ci-dessous.

Copiez la commande suivante dans le terminal Cloud Shell et appuyez sur Entrée pour l'exécuter.

gcloud config set project <<PROJECT_ID>>

Conseil 💡 : Utilisez Ctrl/Cmd+Maj+V pour coller dans la console et Ctrl/Cmd+Maj+C pour copier.

Copiez la commande suivante dans le terminal Cloud Shell et appuyez sur Entrée pour l'exécuter. Cela activera les services nécessaires, créera le fichier et le modifiera dans 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

Un nouvel onglet portant le nom du fichier devrait s'afficher. Collez le script suivant dans le nouveau fichier :

#!/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."

Remplacez l'espace réservé PROJECT_ID par le nom de votre projet :

Copiez la commande suivante et exécutez-la dans le terminal :

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

Résultat attendu :

5. Créer un bucket de stockage

Créez un bucket Cloud Storage et copiez-y les contenus multimédias disponibles. Vous l'utiliserez pour stocker les contenus multimédias disponibles pour nos adorables animaux de compagnie. Vous allez également créer une connexion pour accéder au bucket via BigQuery.

Collez et exécutez la commande suivante dans le terminal :

~/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 "

Remarque 🐱 : Si vous souhaitez ajouter une photo de votre propre animal de compagnie, c'est le moment. Si c'est le cas, vous devrez modifier le code tout au long de cet atelier de programmation. Importez une photo de profil au format JPG ou PNG dans votre bucket. Vous pouvez ajouter des vidéos et d'autres images dans le dossier "additional_media". Assurez-vous que le bucket que vous utilisez est sécurisé et qu'il n'est accessible qu'aux personnes que vous souhaitez autoriser à consulter les photos et vidéos.

Remarque 💡 : Notez le nom de votre bucket (par exemple, <<YOUR_PROJECT_ID>>-petverse).

6. Créer la table "pets"

Vous allez maintenant créer une table dans BigQuery pour stocker des informations sur vos animaux de compagnie.

Ouvrez un nouvel onglet dans le navigateur. Accédez à https://console.cloud.google.com/bigquery .

Assurez-vous que le même projet que celui que vous avez utilisé est sélectionné dans la console :

Vous pouvez maintenant créer un tableau à l'aide des données du fichier pets.csv. Ce fichier contient les noms, les aliments préférés, les jouets et d'autres informations intéressantes sur nos animaux de compagnie.

Copiez le code suivant dans une nouvelle requête SQL pour créer une table physique et charger les données.

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'
);

Remplacez l'espace réservé pour le bucket dans le code par le bucket que vous avez créé à l'étape précédente.

Vous pouvez consulter tous vos buckets de stockage dans un onglet de navigateur distinct en accédant à l'URL https://console.cloud.google.com/storage/browser .

Utilisez le bouton Exécuter pour exécuter la requête.

Une fois les données chargées, cliquez sur Accéder à la table.

Cliquez sur Aperçu pour afficher le contenu de la table.

Remarque 🐱 : Si vous avez ajouté une photo de profil de votre animal de compagnie à l'étape précédente, vous devrez insérer manuellement un enregistrement pour lui. Ouvrez un éditeur SQL et mettez à jour l'instruction d'insertion :

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. Connecter BigQuery au bucket de stockage

Si vous examinez le bucket que vous avez créé précédemment, vous trouverez un ensemble de fichiers multimédias associés à chaque animal.

BigQuery peut lire ces buckets et utiliser les fichiers avec les données des tables. Ce type de valeur est appelé ObjectRef.

Récupérez l'ID du compte de service pour la connexion que vous avez créée précédemment en cliquant dessus sous Connexions externes.

Copiez l'ID du compte de service.

Accédez à la console d'administration IAM dans un nouvel onglet de navigateur ( https://console.cloud.google.com/iam-admin/ ).

Attribuez au compte de service les rôles Lecteur des objets de l'espace de stockage et Utilisateur Vertex AI (vous utiliserez cette autorisation ultérieurement).

Cliquez sur Enregistrer, puis 🕰️ patientez quelques minutes.

De retour dans l'onglet BigQuery, utilisez la requête suivante dans BigQuery Studio pour tester la connexion entre BigQuery et le bucket de stockage.

Remplacez <<PROJECT_ID>> par l'ID de votre projet.

Conseil 💡 : Utilisez Ctrl/Commande+H pour remplacer toutes les valeurs.

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'))

Cliquez sur Afficher les résultats. Vous devriez obtenir les métadonnées dans les résultats :

Important ⚠️ : Si vous constatez des erreurs, veuillez les corriger avant de continuer.

8. Ajouter le support de stockage à vos données structurées

Vous pouvez améliorer la table pets pour ajouter une colonne avec la photo de profil de chaque animal, le cas échéant. Vous ajouterez également une autre colonne avec un tableau de références multimédias, pour contenir tous les autres fichiers liés à chaque animal.

L'accès au contenu multimédia nécessite une connexion, que vous avez créée au début de cet atelier de programmation après avoir créé votre bucket.

Collez les commandes suivantes dans une console SQL BigQuery et exécutez-les pour ajouter deux colonnes à votre table 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>>;

Copiez les instructions suivantes et remplacez l'espace réservé PROJECT_ID par l'ID de votre projet.

Conseil 💡 : Utilisez Ctrl/Commande+H pour remplacer toutes les valeurs.

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;

Remarque 🐱 : Si vous avez ajouté votre propre animal de compagnie, ajoutez une déclaration pour refléter les éléments multimédias supplémentaires pour son ID ici.

Exécutez l'instruction. Au bout de quelques minutes, vous devriez voir des exécutions réussies :

Vérifiez les résultats à l'aide de l'aperçu du tableau. Vous devriez voir les métadonnées des photos de profil existantes et des contenus multimédias supplémentaires pour le chat nommé Pixel.

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

9. Générer des descriptions d'animaux de compagnie

Si vous prévisualisez la table pets, vous remarquerez que certains animaux, comme Yoda, Pixel ou Rocky, n'ont pas leur aliment ou leur jouet préférés.

Vous trouverez peut-être les réponses à ces questions dans les vidéos et les contenus audio associés à ces animaux. Vous utiliserez des fonctions d'IA intégrées pour vérifier.

Testez cela avec l'instruction suivante :

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'

Remarque 📝 : Si vous recevez un message d'erreur indiquant que les agents de service sont en cours de provisionnement, patientez quelques minutes et réessayez.

Vous pouvez voir la vidéo de Rocky dans votre bucket de stockage.

Utilisez l'instruction suivante pour mettre à jour les descriptions manquantes :

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

Utilisez l'instruction suivante pour créer une description des animaux de compagnie en fonction de leur contenu multimédia dans une nouvelle colonne :

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

Au bout de quelques minutes, vous devriez voir des descriptions de créations :

Anecdote 📝 : Le fichier audio de Madonna est en espagnol.

10. Créer des embeddings

Créez une table pour stocker les embeddings des photos de profil, ainsi que des descriptions et des loisirs à utiliser dans une recherche sémantique. Nous allons rechercher des similitudes entre les animaux à l'aide de recherches vectorielles.

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;

Consultez la nouvelle table dans l'onglet "Résultats".

Utilisez l'instruction suivante pour vérifier l'état de tous les embeddings :

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

En cas d'erreur, l'état ne sera pas vide. Le résultat est correct : aucune erreur n'a été détectée.

Voici un exemple d'enregistrements comportant des erreurs. Les erreurs suivantes ne sont pas attendues, mais doivent être corrigées avant de passer aux étapes suivantes :

Important ⚠️ : Si vous constatez des erreurs, veuillez les corriger avant de continuer. Si vous ne voyez qu'une ligne vide avec 10 num_rows ou plus, vous pouvez continuer.

Rechercher des animaux similaires

L'ensemble de données par défaut contient des animaux de compagnie similaires. Voici deux exemples : Pixel (ID 3) et SQL (ID 4) :

Vous pouvez utiliser la distance entre les embeddings pour calculer les animaux de compagnie similaires :

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;

Vous devriez obtenir des résultats avec les ID des images qui se ressemblent. Tout ce qui se trouve sur l'image sera inclus. Dans cet exemple, Pixel et SQL sont similaires, et l'animal le plus proche est Joel (ID : 14).

Voici une photo de Joel pour référence :

Essayer la recherche sémantique

Vous pouvez utiliser la fonction VECTOR_SEARCH pour effectuer des recherches sémantiques dans les embeddings de texte. Si cette table était plus grande, vous devriez créer un index pour les embeddings.

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

Essayez de modifier le terme de recherche sémantique (Pets who like to relax) ainsi que le paramètre fraction_lists_to_search et voyez ce qui se passe. Pour en savoir plus sur ces fonctions, cliquez ici.

11. Vibe-codez une page de profil

⚠️ Important ⚠️ : Vous devez avoir des connaissances en développement d'applications Web (Python, HTML et déploiement dans Cloud Run). Si vous souhaitez importer une application fonctionnelle et ignorer cette étape, suivez les instructions du fichier README de ce dépôt Git de démonstration.

L'interface de ligne de commande peut entraîner des coûts en fonction de la configuration. L'interface CLI peut également modifier l'infrastructure de votre projet et de votre répertoire Cloud Shell. Nous vous recommandons vivement d'examiner les modifications avant de les appliquer et de surveiller les exécutions pour intervenir lorsque l'interface de ligne de commande peut être en boucle.

Vous utiliserez la CLI Gemini dans Cloud Shell pour démarrer une application Web de démonstration simple. Cette application Web a été simplifiée dans son invite pour montrer comment le Petverse pourrait prendre vie.

Retournez dans Cloud Shell. Vous profiterez d'une meilleure expérience si vous utilisez uniquement la console en plein écran :

Exécutez le script d'initialisation pour vous assurer que les variables d'environnement sont définies, créez un répertoire pour contenir ce projet et exécutez Gemini CLI :

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

La CLI Gemini devrait s'afficher :

Remplacez le nom du bucket dans le prompt ci-dessous.

Collez le prompt dans la ligne de commande 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.

C'est votre aventure maintenant. Un plan s'affichera et vous serez invité à le confirmer.

Il est très peu probable que le code et le déploiement produits fonctionnent du premier coup. Vous devrez itérer avec Gemini CLI jusqu'à ce qu'elle obtienne le résultat souhaité.

Remarque 📝 : Si vous deviez créer une application similaire dans un environnement de production réel, vous devriez tenir compte d'autres aspects liés à la sécurité et à la scalabilité. Par exemple, vous pouvez utiliser des techniques d'authentification plus avancées dans le code, différents services pour différentes fonctions (par exemple, un backend, un frontend, un accès à une base de données) ou envisager un équilibreur de charge comme point d'accès.

Si vous constatez que le processus est bloqué dans une boucle, arrêtez-le avec CTRL/Commande+C, examinez le problème, puis relancez-le.

Nous vous recommandons de lire attentivement chacune des confirmations, une par une, pour comprendre ce que la CLI va faire :

Après quelques minutes, l'application devrait être prête à s'exécuter. Il peut arriver que la console semble bloquée :

Vous pouvez essayer manuellement l'application dans un nouvel onglet Cloud Shell avec gunicorn. Assurez-vous que le projet est défini :

Votre nouveau site devrait s'afficher (il peut être différent de celui-ci). Si quelque chose ne fonctionne pas, vous devriez pouvoir voir les journaux d'erreur et de débogage dans la ligne de commande Cloud Shell exécutée en local.

Si tout vous semble correct, vous pouvez éventuellement déployer l'application dans Cloud Run.

Si votre projet appartient à une organisation, assurez-vous de configurer IAP en suivant ces instructions. Si votre projet ne fait pas partie d'une organisation, vous pouvez suivre ces instructions pour sécuriser l'accès à votre application. En particulier pour les paramètres de production, nous vous recommandons de NE PAS autoriser l'accès non authentifié.

Si le déploiement fonctionne, l'application Cloud Run devrait s'exécuter dans la console Cloud Run.

Assurez-vous que l'accès est réservé aux achats via l'application. Utilisez Modifier la stratégie pour ajouter votre utilisateur à la liaison, puis cliquez sur Enregistrer.

⚠️ Important ⚠️ : L'option IAP ne sera disponible que pour les projets au sein d'une organisation. Si votre projet n'appartient pas à une organisation (par exemple, s'il a été créé avec un compte Gmail et l'option "Aucune organisation"), vous pouvez utiliser un équilibreur de charge externe, comme décrit ici.

Attendez quelques minutes que les liaisons IAP se propagent, puis cliquez sur l'URL en haut de la page. Le site devrait s'afficher.

12. Effectuer un nettoyage

Cette étape vous guidera dans la suppression des ressources créées dans cet atelier de programmation.

Supprimez le service Cloud Run (adaptez le nom des services et la région si nécessaire) :

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

Supprimez tous les composants BigQuery :

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