1. Visão geral
Neste codelab, você vai criar o Neighbor Loop, um app sustentável de compartilhamento de excedentes que trata a inteligência como um cidadão de primeira classe da camada de dados.
Ao integrar o Gemini 3.0 Flash e a integração de ML do Cloud SQL, você vai além do armazenamento básico e entra no campo da inteligência no banco de dados. Você vai aprender a fazer análises multimodais de itens e descoberta semântica diretamente no SQL.
O que você vai criar
Um aplicativo da Web de alto desempenho "deslizar para corresponder" para compartilhamento de excedentes da comunidade.
O que você vai aprender
- Provisionamento com um clique: como configurar uma instância e um Cloud SQL projetados para cargas de trabalho de IA.
- Embeddings no banco de dados: geração de vetores text-embedding-005 diretamente em instruções INSERT.
- Raciocínio multimodal: usar o Gemini 3.0 Flash para "ver" itens e gerar biografias automáticas e divertidas no estilo de apps de encontros.
- Descoberta semântica: realiza "testes de vibe" com base em lógica em consultas SQL usando a função ai.if() para filtrar resultados com base no contexto, não apenas em cálculos.
A arquitetura
O Neighbor Loop evita gargalos tradicionais da camada de aplicativo. Em vez de extrair dados para processamento, usamos:
- Integração do Cloud SQL e ML:para gerar e armazenar vetores em tempo real.
- Google Cloud Storage:para armazenar imagens
- Gemini 3.0 Flash:para realizar raciocínio em menos de um segundo em dados de imagem e texto diretamente via SQL.
- Cloud Run:para hospedar um back-end Flask leve de arquivo único.
Requisitos
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
- Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com o ID do seu projeto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>
- Ative as APIs necessárias: siga o link e ative as APIs.
Como alternativa, use o comando gcloud. Consulte a documentação para ver o uso e os comandos gcloud.
Problemas e solução de problemas
A síndrome do projeto fantasma | Você executou |
A barricada de faturamento | Você ativou o projeto, mas esqueceu a conta de faturamento. O Cloud SQL não será iniciado se o faturamento estiver vazio. |
Atraso na propagação da API | Você clicou em "Ativar APIs", mas a linha de comando ainda mostra |
3. Configuração do banco de dados
Neste laboratório, vamos usar o Cloud SQL para PostgreSQL como banco de dados para os dados de teste.
Vamos criar uma instância do Cloud SQL em que o conjunto de dados de teste será carregado.
- Clique no botão ou copie o link abaixo para o navegador em que o usuário do console do Google Cloud está conectado.
- Depois que essa etapa for concluída, o repositório será clonado no editor local do Cloud Shell, e você poderá executar o comando abaixo na pasta do projeto. É importante verificar se você está no diretório do projeto:
sh run.sh
- Agora use a interface (clique no link no terminal ou no link "visualizar na Web" no terminal).
- Insira os detalhes do ID do projeto e do nome da instância para começar.
- Tome um café enquanto os registros rolam e leia aqui como isso é feito nos bastidores.
Problemas e solução de problemas
Incompatibilidade de região | Se você ativou as APIs em |
Tempo limite do Cloud Shell | Se o intervalo para o café durar 30 minutos, o Cloud Shell poderá entrar em modo de espera e desconectar o processo |
4. Provisionamento de esquema
Depois que a instância do Cloud SQL estiver em execução, acesse o editor de SQL do Cloud SQL Studio para ativar as extensões de IA e provisionar o esquema.
Talvez seja necessário aguardar a conclusão da criação da instância. Depois disso, faça login na instância do Cloud SQL usando as credenciais criadas. Use os seguintes dados para autenticar no PostgreSQL:
- Nome de usuário : "
postgres" - Banco de dados : "
postgres" - Senha : "
cloudsql" (ou o que você definiu no momento da criação)
Depois de se autenticar no Cloud SQL Studio, os comandos SQL são inseridos no editor. É possível adicionar várias janelas do Editor usando o sinal de mais à direita da última janela.
Você vai inserir comandos para o Cloud SQL nas janelas do editor, usando as opções "Executar", "Formatar" e "Limpar" conforme necessário.
Ativar extensões
Para criar esse app, vamos usar as extensões pgvector e google_ml_integration. A extensão pgvector permite armazenar e pesquisar embeddings de vetores. A extensão google_ml_integration oferece funções que você usa para acessar endpoints de previsão da Vertex AI e receber previsões em SQL. Ative essas extensões executando os seguintes DDLs:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Criar uma tabela
É possível criar uma tabela usando a instrução DDL abaixo no Cloud SQL Studio:
-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id UUID,
provider_name TEXT,
provider_phone TEXT,
title TEXT,
bio TEXT,
category TEXT,
image_url TEXT,
item_vector VECTOR(768),
status TEXT DEFAULT 'available',
created_at TIMESTAMP DEFAULT NOW()
);
-- Swipes Table (The Interaction)
CREATE TABLE swipes (
swipe_id SERIAL PRIMARY KEY,
swiper_id UUID,
item_id UUID REFERENCES items(item_id),
direction TEXT CHECK (direction IN ('left', 'right')),
is_match BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
A coluna item_vector vai permitir o armazenamento dos valores vetoriais do texto.
Conceder permissão
Execute a instrução abaixo para conceder a execução na função "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Ativar a integração de ML
Para aproveitar os recursos de machine learning diretamente no seu banco de dados, ative a flag de integração de ML.
Execute o comando abaixo no terminal do Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840
gcloud sql instances patch $INSTANCE_NAME \
--database-flags=cloudsql.enable_google_ml_integration=on
gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration
Conceder o papel de usuário da Vertex AI à conta de serviço do Cloud SQL
No console do Google Cloud IAM, conceda à conta de serviço do Cloud SQL (que tem esta aparência: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) acesso à função "Usuário da Vertex AI". PROJECT_NUMBER vai ter o número do seu projeto.
Como alternativa, execute o comando abaixo no terminal do Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_EMAIL" \
--role="roles/aiplatform.user"
Registrar o modelo Gemini 3 Flash no Cloud SQL
Execute a instrução SQL abaixo no editor de consultas do Cloud SQL
CALL google_ml.create_model(
model_id => 'gemini-3-flash-preview',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
model_qualified_name => 'gemini-3-flash-preview',
model_provider => 'google',
model_type => 'generic',
model_auth_type => 'cloudsql_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Problemas e solução de problemas
O loop de "amnésia de senha" | Se você usou a configuração "Um clique" e não se lembra da senha, acesse a página de informações básicas da instância no console e clique em "Editar" para redefinir a senha |
O erro "Extensão não encontrada" | Se |
A lacuna de propagação do IAM | Você executou o comando do IAM |
Incompatibilidade de dimensão do vetor | A tabela |
Erro de digitação no ID do projeto | Na chamada |
A integração com a Vertex AI está desativada | Execute |
5. Armazenamento de imagens (Google Cloud Storage)
Para armazenar as fotos dos nossos itens excedentes, usamos um bucket do GCS. Para fins deste app de demonstração, queremos que as imagens sejam acessíveis ao público para que sejam renderizadas instantaneamente nos nossos cards de deslizar.
- Crie um bucket: Crie um novo bucket no seu projeto do GCP (por exemplo, neighborloop-images), de preferência na mesma região do banco de dados e do aplicativo.
- Configurar o acesso público: * Acesse a guia Permissões do bucket.
- Adicione o principal allUsers.
- Atribua o papel Leitor de objetos do Storage (para que todos possam ver as fotos) e o papel Criador de objetos do Storage (para fins de upload de demonstração).
Alternativa (conta de serviço): se você preferir não usar o acesso público, verifique se a conta de serviço do aplicativo tem acesso total ao Cloud SQL e as funções necessárias do Storage para gerenciar objetos com segurança.
Se você quiser executar o comando e conceder acesso público. Execute os comandos abaixo no terminal do Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Problemas e solução de problemas
The Region Drag (em inglês) | Se o banco de dados estiver em |
Exclusividade do nome do bucket | Os nomes de bucket são um namespace global. Se você tentar nomear seu bucket como |
A confusão entre "Criador" e "Leitor" | Confusão entre "Criador" e "Leitor":se você adicionar apenas "Leitor", o app vai falhar quando um usuário tentar listar um novo item porque não tem permissão para gravar o arquivo. Você precisa dos dois para esta configuração de demonstração específica. |
6. Vamos criar o aplicativo
Clone este repositório no seu projeto e vamos analisar.
- Para clonar, no terminal do Cloud Shell (no diretório raiz ou em qualquer lugar em que você queira criar o projeto), execute os comandos a seguir um por um:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Isso vai criar o projeto, e você pode verificar isso no editor do Cloud Shell.
- Como conseguir sua chave da API Gemini
- Acesse o Google AI Studio: acesse aistudio.google.com.
- Fazer login: use a mesma Conta do Google que você está usando no projeto do Google Cloud.
- Criar chave de API:
- Na barra lateral à esquerda, clique em "Receber chave de API".
- Clique no botão "Criar chave de API em um novo projeto".
- Copie a chave: depois que a chave for gerada, clique no ícone de cópia.
- Agora defina as variáveis de ambiente no arquivo .env
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Substitua os valores dos marcadores <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Problemas e solução de problemas
Confusão de várias contas | Se você tiver feito login em várias Contas do Google (pessoal x trabalho), o AI Studio poderá usar a conta errada por padrão. Verifique o avatar no canto superior direito para garantir que ele corresponda à sua conta do projeto do GCP. |
Violação de cota do nível sem custo financeiro | Se você estiver usando o nível sem custos financeiros, haverá limites de taxa (RPM - solicitações por minuto). Se você deslizar muito rápido no Neighbor Loop, poderá receber um erro |
Segurança de chaves expostas | Se você |
7. Vamos verificar o código
O "Perfil de encontros" das suas coisas
Quando um usuário faz upload de uma foto de um item, ele não precisa escrever uma descrição longa. Uso o Gemini 3 Flash para "ver" o item e escrever a página dele.
No back-end, o usuário só precisa fornecer um título e uma foto. O Gemini cuida do resto:
prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
"bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
"category": "One-word category",
"tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
model="gemini-3-flash-preview",
contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
config=types.GenerateContentConfig(response_mime_type="application/json")
)
Embeddings no banco de dados em tempo real
Um dos recursos mais legais do Cloud SQL é a capacidade de gerar embeddings sem sair do contexto SQL. Em vez de chamar um modelo de embedding em Python e enviar o vetor de volta ao banco de dados, faço tudo em uma instrução INSERT usando a função embedding():
INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
:owner, :name, :phone, :title, :bio, :cat, :url, 'available',
embedding('text-embedding-005', :title || ' ' || :bio)::vector
)
Isso garante que cada item seja "pesquisável" pelo significado no momento em que é postado. Essa é a parte que aborda o recurso "listar o produto" do app Neighbor Loop.
Pesquisa vetorial avançada e filtragem inteligente com o Gemini 3.0
A pesquisa padrão de palavras-chave é limitada. Se você pesquisar "algo para consertar minha cadeira", um banco de dados tradicional poderá não retornar nada se a palavra "cadeira" não estiver em um título. O Neighbor Loop resolve isso com a pesquisa vetorial avançada da IA do Cloud SQL.
Ao usar a extensão pgvector e o armazenamento otimizado do Cloud SQL, podemos realizar pesquisas de similaridade extremamente rápidas. Mas a verdadeira "mágica" acontece quando combinamos a proximidade vetorial com a lógica baseada em LLM.
SELECT item_id, title, bio, category, image_url,
1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
AND item_vector IS NOT NULL
ORDER BY score DESC
LIMIT 5
Essa consulta representa uma grande mudança arquitetônica: estamos movendo a lógica para os dados. Em vez de extrair milhares de resultados para o código do aplicativo e filtrá-los, o Gemini 3 Flash faz uma "verificação de vibe" no mecanismo de banco de dados. Isso reduz a latência e os custos de saída e garante que os resultados não sejam apenas matematicamente semelhantes, mas contextualmente relevantes.
O loop "Deslize para combinar"
A interface é um baralho clássico.
Deslizar para a esquerda: descartar.
Deslize para a direita: é um match!
Quando você desliza para a direita, o back-end registra a interação na nossa tabela de deslizes e marca o item como correspondente. O front-end aciona instantaneamente um modal mostrando os dados de contato do provedor para que você possa combinar a retirada.
8. Vamos implantar no Cloud Run
- Implante no Cloud Run executando o seguinte comando no terminal do Cloud Shell, em que o projeto é clonado. Verifique se você está na pasta raiz do projeto.
Execute o seguinte no terminal do Cloud Shell:
gcloud run deploy neighbor-loop-cloud-sql \
--source . \
--region=us-central1 \
--allow-unauthenticated \
--network=easy-cloudsql-vpc \
--subnet=easy-cloudsql-subnet \
--vpc-egress=private-ranges-only \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Substitua os valores dos marcadores <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Quando o comando terminar, ele vai gerar um URL de serviço. Copie.
Agora use o URL do serviço (endpoint do Cloud Run que você copiou antes) e teste o app. Envie uma foto daquela ferramenta elétrica antiga e deixe o Gemini fazer o resto.
Problemas e solução de problemas
O loop "Falha na revisão" | Se a implantação terminar, mas o URL retornar um |
9. Solução de problemas de alto nível
10. Demonstração
Você poderá usar seu endpoint para testes.
Mas, para fins de demonstração por alguns dias, você pode usar isto:
11. Limpar
Depois de concluir este laboratório, não se esqueça de excluir a instância do Cloud SQL.
12. Parabéns
Você criou o app Neighbor Loop para comunidades sustentáveis com o Google Cloud. Ao mover a incorporação e a lógica de IA do Gemini 3 Flash para o Cloud SQL, o app fica incrivelmente rápido (sujeito às configurações de implantação) e o código fica muito limpo. Não estamos apenas armazenando dados, mas também intenção.
A combinação da velocidade do Gemini 3 Flash e do processamento de vetores otimizado do Cloud SQL é realmente a próxima fronteira para plataformas orientadas pela comunidade.