Bem-vindo ao PetVerse!

1. Introdução

Este é o Petverse! Todos os animais de estimação são bem-vindos! 🐈🐶🐍🐟🦄

Pré-requisitos

• Conhecimento básico do console do Google Cloud
• Conhecimento básico de instruções SQL

O que você vai aprender

• Criar conjuntos de dados e tabelas no BigQuery
• Criar colunas ObjectRef para referenciar multimídia em um bucket de armazenamento no BigQuery
• Use funções de IA no BigQuery para melhorar seu conjunto de dados com o conteúdo de dados não estruturados
• Criar embeddings multimídia para pesquisar mídias semelhantes
• Criar embeddings de texto para realizar pesquisa semântica com VECTOR_SEARCH
• Usar a CLI do Gemini para criar um web app

O que é necessário

• Uma conta e um projeto do Google Cloud com uma conta de faturamento
• Um navegador da Web, como o Chrome

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

3. Abrir o Cloud Shell

Acesse https://shell.cloud.google.com/?show=ide%2Cterminal . Quando solicitado, clique em Autorizar.

Verifique se o editor e o console estão visíveis:

4. Criar um script auxiliar

Para facilitar essa experiência, você vai criar um script auxiliar que define as variáveis de ambiente relevantes.

Substitua <<Project ID>> pelo ID do seu projeto abaixo.

Copie o comando a seguir no terminal do Cloud Shell e pressione Enter para executar**.**

gcloud config set project <<PROJECT_ID>>

Dica 💡 : use Ctrl/Command + Shift + V para colar no console e Ctrl/Command + Shift + C para copiar.

Copie o comando a seguir no terminal do Cloud Shell e pressione Enter para executar**.** Isso vai ativar os serviços necessários e criar o arquivo para edição no 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

Uma nova guia com o nome do arquivo vai aparecer. Cole o script a seguir no novo arquivo:

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

Substitua o marcador de posição PROJECT_ID pelo nome do seu projeto:

Copie e execute o seguinte comando no terminal:

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

Saída esperada:

5. Criar um bucket de armazenamento

Crie um bucket do Cloud Storage e copie a mídia disponível para ele. Você vai usar isso para armazenar a mídia disponível para nossos pets maravilhosos. Você também vai criar uma conexão para acessar o bucket pelo BigQuery.

Cole e execute o seguinte no 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 "

Observação 🐱 : se você quiser adicionar uma foto do seu próprio animal de estimação, esta é a sua chance. Se fizer isso, você precisará modificar o código ao longo deste codelab. Faça upload de uma foto do perfil para seu bucket em JPG ou PNG. Você pode adicionar vídeos e mais fotos na pasta "additional_media". Verifique se o bucket que você está usando é seguro e só pode ser acessado pelas pessoas que você quer que vejam as fotos e os vídeos.

Observação 💡 : anote o nome do bucket (por exemplo, <<YOUR_PROJECT_ID>>-petverse).

6. Criar a tabela de animais de estimação

Agora você vai criar uma tabela no BigQuery para armazenar informações sobre seus animais de estimação.

Abra uma nova guia no navegador. Acesse https://console.cloud.google.com/bigquery .

Verifique se o mesmo projeto que você estava usando está selecionado no console do Google Cloud:

Agora você pode criar uma tabela usando os dados do arquivo pets.csv. Esse arquivo contém os nomes, comidas favoritas, brinquedos e outras informações interessantes sobre nossos animais de estimação.

Copie o código a seguir em uma nova consulta SQL para criar uma tabela física e carregar os dados.

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

Substitua o marcador de posição do bucket no código pelo bucket que você criou na etapa anterior.

Você pode verificar todos os seus buckets de armazenamento em uma guia separada do navegador apontada para este URL: https://console.cloud.google.com/storage/browser .

Use o botão Executar para executar a consulta.

Depois que os dados forem carregados, clique em Acessar tabela.

Clique em Visualização para conferir o conteúdo da tabela.

Observação 🐱 : se você adicionou uma foto do perfil do seu animal de estimação na etapa anterior, será necessário inserir manualmente um registro para ele. Abra um editor SQL e atualize a instrução de inserção:

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. Conectar o BigQuery ao bucket de armazenamento

Se você procurar no bucket criado anteriormente, vai encontrar um conjunto de arquivos de mídia relacionados a cada animal de estimação.

O BigQuery tem a capacidade de ler esses buckets e usar os arquivos com os dados nas tabelas. Esse tipo de valor é chamado de ObjectRef.

Clique na conexão criada em Conexões externas para acessar o ID da conta de serviço.

Copie o ID da conta de serviço.

Acesse o Admin Console do IAM em uma nova guia do navegador ( https://console.cloud.google.com/iam-admin/ ).

Conceda à conta de serviço os papéis Leitor de objetos do Storage e Usuário da Vertex AI. Você vai usar essa permissão mais tarde.

Clique em Salvar e 🕰️ aguarde alguns minutos.

Na guia do BigQuery, use a seguinte consulta no BigQuery Studio para testar a conexão entre o BigQuery e o bucket de armazenamento.

Substitua <<PROJECT_ID>> pelo ID do projeto.

Dica 💡 : use Ctrl/Command + H para substituir todos os valores.

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

Clique em Ver resultados. Os metadados vão aparecer nos resultados:

Importante ⚠️ : se você encontrar erros, corrija-os antes de continuar.

8. Adicione a mídia de armazenamento aos seus dados estruturados

Você pode melhorar a tabela pets para adicionar uma coluna com a foto do perfil de cada animal de estimação, quando disponível. Você também vai adicionar outra coluna com uma matriz de referências de mídia para armazenar todos os outros arquivos relacionados a cada pet.

O acesso à multimídia exige uma conexão, que você criou no início deste codelab depois de criar seu bucket.

Cole os comandos a seguir em um console SQL do BigQuery e execute-os para adicionar duas colunas à tabela 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>>;

Copie as instruções a seguir e substitua o marcador de posição PROJECT_ID pelo ID do seu projeto.

Dica 💡 : use Ctrl/Command + H para substituir todos os valores.

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;

Observação 🐱 : se você adicionou seu próprio animal de estimação, inclua uma declaração para refletir a mídia adicional do ID dele aqui.

Execute a instrução. Você vai ver execuções bem-sucedidas depois de alguns minutos:

Confira os resultados usando a visualização da tabela. Você vai encontrar os metadados das fotos de perfil atuais e outras mídias do gato chamado Pixel.

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

9. Gerar descrições de animais de estimação

Se você visualizar a tabela pets, vai notar que alguns animais de estimação, como Yoda, Pixel ou Rocky, não têm a comida ou o brinquedo favorito.

As respostas para essas perguntas podem estar nos vídeos e áudios relacionados a esses animais de estimação. Você vai usar funções de IA incorporadas para verificar.

Teste com a seguinte declaração:

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'

Observação 📝: se aparecer um erro informando que "Os agentes de serviço estão sendo provisionados", aguarde alguns minutos e tente de novo.

Você pode conferir o vídeo do Rocky no seu bucket de armazenamento.

Use a instrução a seguir para atualizar as descrições ausentes:

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

Use a instrução a seguir para criar uma descrição dos animais de estimação com base no conteúdo multimídia deles em uma nova coluna:

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

Depois de alguns minutos, você vai ver algumas descrições criativas:

Curiosidade 📝: o arquivo de áudio da Madonna está em espanhol.

10. Criar embeddings

Crie uma tabela para armazenar os embeddings das fotos de perfil e das descrições e hobbies para usar em uma pesquisa semântica. Vamos encontrar semelhanças entre os pets usando pesquisas vetoriais.

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;

Confira a nova tabela na guia "Resultados".

Use a instrução a seguir para verificar o status de todos os embeddings:

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

Se houver erros, eles vão aparecer em um status não em branco. Esta é a saída correta: não há registros com erros**:**

Confira a seguir um exemplo de registros com erros. Esses problemas não são esperados, mas precisam ser corrigidos antes de continuar com as próximas etapas:

Importante ⚠️ : se você encontrar erros, corrija-os antes de continuar. Se você só vir uma linha em branco com 10 ou mais num_rows, continue.

Procure pets semelhantes

O conjunto de dados padrão tem animais de estimação semelhantes. Confira dois exemplos: Pixel (ID: 3) e SQL (ID: 4):

Use a distância entre os embeddings para calcular animais de estimação semelhantes:

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;

Você vai receber resultados com os IDs de imagens semelhantes entre si. Isso vai incluir tudo na imagem. Neste exemplo, Pixel e SQL são semelhantes, e o próximo animal de estimação mais parecido é Joel (ID: 14).

Esta é uma foto do Joel para referência:

Teste a pesquisa semântica

Você pode usar a função VECTOR_SEARCH para fazer pesquisas semânticas em embeddings de texto. Se essa tabela fosse maior, seria necessário criar e indexar os 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

Tente mudar o termo de pesquisa semântica (Pets who like to relax) e o parâmetro fraction_lists_to_search para ver o que acontece. Saiba mais sobre essas funções aqui.

11. Criar uma página de perfil no estilo vibe coding

⚠️Importante⚠️ : isso exige algum conhecimento de desenvolvimento de aplicativos da Web (Python, HTML e implantação no Cloud Run). Se você quiser importar um app funcional e pular esta etapa, siga as instruções no README deste repositório git de demonstração.

A CLI pode gerar custos dependendo da configuração. A CLI também pode fazer modificações na infraestrutura do seu projeto e no diretório do Cloud Shell. Recomendamos revisar as mudanças antes de aplicá-las e monitorar as execuções para intervir quando a CLI estiver em uma repetição.

Você vai usar a CLI do Gemini no Cloud Shell para iniciar um web app de demonstração simples. O comando desse aplicativo da Web foi simplificado para demonstrar como o Petverse pode ser criado.

Volte para o Cloud Shell. Você terá uma experiência melhor com apenas o console em tela cheia:

Execute o script de inicialização para garantir que as variáveis de ambiente estejam definidas, crie um diretório para conter este projeto e execute a CLI do Gemini:

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

A CLI do Gemini vai aparecer:

Substitua o nome do bucket no comando abaixo.

Cole o comando na linha de comando do 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.

Agora é sua aventura. Um plano vai aparecer, e você vai precisar confirmar ao longo do processo.

É muito improvável que o código e a implantação produzidos funcionem na primeira tentativa. Você vai precisar iterar com a CLI do Gemini até que ela acerte.

Observação 📝: se você criasse um aplicativo semelhante em um ambiente de produção real, consideraria outros aspectos de segurança e escalonabilidade. Exemplos incluem técnicas de autenticação mais avançadas no código, serviços diferentes para funções diferentes (por exemplo, um back-end, um front-end, um acesso ao banco de dados) ou um balanceador de carga como ponto de acesso.

Se o processo ficar preso em um loop, interrompa-o com CTRL/Command + C, investigue o problema e faça o comando novamente.

Recomendamos ler cada uma das confirmações com atenção, uma por uma, para entender o que a CLI vai fazer:

Depois de alguns minutos, o aplicativo estará pronto para ser executado. Pode parecer que o console está travado:

É possível testar manualmente o aplicativo em uma nova guia do Cloud Shell com o gunicorn. Verifique se o projeto está definido:

Seu novo site vai aparecer. Ele pode ter uma aparência diferente desta. Se algo não estiver funcionando, você poderá ver os logs de erro e depuração na linha de comando do Cloud Shell executada localmente.

Se tudo estiver certo, você poderá implantar o aplicativo no Cloud Run.

Se o projeto pertencer a uma organização, configure o IAP seguindo estas instruções. Se o projeto não fizer parte de uma organização, siga estas instruções para proteger o acesso ao aplicativo. Principalmente para configurações de produção, recomendamos NÃO permitir acesso não autenticado.

Supondo que a implantação funcione, o aplicativo do Cloud Run vai aparecer em execução no console do Cloud Run.

Verifique se o acesso é somente pelo IAP. Use Editar política para adicionar seu usuário à vinculação e clique em Salvar.

⚠️Importante⚠️ : a opção IAP só estará disponível para projetos em uma organização. Se o projeto não pertencer a uma organização (por exemplo, se ele foi criado com uma conta do Gmail com "Sem organização"), use um balanceador de carga externo, conforme descrito aqui.

Aguarde alguns minutos para que as vinculações da IAP sejam propagadas e clique no URL na parte de cima. O site vai aparecer.

12. Limpar

Esta etapa vai orientar você na exclusão dos recursos criados neste codelab.

Exclua o serviço do Cloud Run (adapte o nome dos serviços e a região conforme necessário):

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

Exclua todos os recursos do BigQuery:

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