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 IA do AlloyDB, você vai além do armazenamento básico e entra no campo da inteligência no banco de dados. Você vai aprender a realizar análises multimodais de itens e descoberta semântica diretamente no SQL, eliminando o "tributo de IA" de latência e o inchaço arquitetônico.
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 um cluster e uma instância do AlloyDB 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 divertidas e no estilo de aplicativos de relacionamento automaticamente.
- Descoberta semântica: realização de "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 os gargalos tradicionais da camada de aplicativo. Em vez de extrair dados para processamento, usamos:
- AlloyDB AI:para gerar e armazenar vetores em tempo real.
- Google Cloud Storage:para armazenar imagens
- Gemini 3.0 Flash:para fazer inferências em menos de um segundo sobre 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 seu ID do 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 AlloyDB é um mecanismo de alto desempenho. Ele não vai iniciar se o "tanque de combustível" (faturamento) estiver vazio. |
Atraso na propagação da API | Você clicou em "Ativar APIs", mas a linha de comando ainda mostra |
Quags de cota | Se você estiver usando uma conta de teste nova, poderá atingir uma cota regional para instâncias do AlloyDB. Se |
Agente de serviço"oculto" | Às vezes, o agente de serviço do AlloyDB não recebe automaticamente o papel |
3. Configuração do banco de dados
Neste laboratório, vamos usar o AlloyDB como banco de dados para os dados de teste. Ele usa clusters para armazenar todos os recursos, como bancos de dados e registros. Cada cluster tem uma instância principal que fornece um ponto de acesso aos dados. As tabelas vão conter os dados reais.
Vamos criar um cluster, uma instância e uma tabela do AlloyDB 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, do cluster e dos nomes das instâncias para começar.
- Tome um café enquanto os registros rolam e leia aqui como isso é feito nos bastidores.
Problemas e solução de problemas
O problema da "paciência" | Os clusters de banco de dados são uma infraestrutura pesada. Se você atualizar a página ou encerrar a sessão do Cloud Shell porque ela "parece travada", poderá acabar com uma instância "fantasma" parcialmente provisionada e impossível de excluir sem intervenção manual. |
Incompatibilidade de região | Se você ativou as APIs em |
Clusters zumbis | Se você usou o mesmo nome para um cluster e não o excluiu, o script pode informar que o nome do cluster já existe. Os nomes de cluster precisam ser exclusivos em um projeto. |
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 o cluster e a instância do AlloyDB estiverem em execução, acesse o editor de SQL do AlloyDB 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 no AlloyDB usando as credenciais criadas ao criar o cluster. Use os seguintes dados para autenticar no PostgreSQL:
- Nome de usuário : "
postgres" - Banco de dados : "
postgres" - Senha : "
alloydb" (ou o que você definiu no momento da criação)
Depois de se autenticar no AlloyDB 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 AlloyDB 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 AlloyDB 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;
Conceder o papel de usuário da Vertex AI à conta de serviço do AlloyDB
No console do Google Cloud IAM, conceda à conta de serviço do AlloyDB (que tem esta aparência: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.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:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
Registrar o modelo Gemini 3 Flash no AlloyDB
Execute a instrução SQL abaixo no editor de consultas do AlloyDB
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 => 'llm',
model_auth_type => 'alloydb_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 do |
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 |
5. Armazenamento de imagens (Google Cloud Storage)
Para armazenar as fotos dos 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 AlloyDB e os papéis necessários do Storage para gerenciar objetos com segurança.
Problemas e solução de problemas
The Region Drag | 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 o seguinte comando:
git clone https://github.com/AbiramiSukumaran/neighbor-loop
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ê |
O vazio "Tempo limite da conexão" | Você usou o endereço IP particular no arquivo .env, mas está tentando se conectar de fora da VPC (como sua máquina local). Os IPs particulares só podem ser acessados na mesma rede do Google Cloud. Mude para o IP público. |
A proposição da porta 5432 | Embora 5432 seja a porta padrão do PostgreSQL, o AlloyDB às vezes exige configurações de porta específicas se você estiver usando um proxy de autenticação. Neste laboratório, use :5432 no final da string de host. |
O Gatekeeper "Redes autorizadas" | Mesmo que você tenha o IP público, o AlloyDB vai "Recusar conexão" a menos que você tenha adicionado o endereço IP da máquina que executa o código à lista de permissões.Correção: nas configurações da instância do AlloyDB, adicione 0.0.0.0/0 (somente para testes temporários) ou seu IP específico às redes autorizadas. |
Falha no handshake de SSL/TLS | O AlloyDB prefere conexões seguras. Se a DATABASE_URL não especificar o driver corretamente (como usar pg8000), o handshake poderá falhar sem aviso, deixando você com um erro genérico "Banco de dados não acessível". |
A troca "Principal x pool de leitura" | Se você copiar acidentalmente o endereço IP do pool de leitura em vez da instância principal, o app vai funcionar para pesquisar itens, mas vai falhar com um erro "Somente leitura" quando você tentar listar um novo item. Sempre use o IP da instância principal para gravações. |
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 de detalhes.
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 AlloyDB é 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 AlloyDB.
Ao usar a extensão pgvector e o armazenamento otimizado do AlloyDB, 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.
A IA do AlloyDB permite chamar modelos como o Gemini diretamente nas nossas consultas SQL. Isso significa que podemos realizar uma descoberta semântica que inclui uma "verificação de integridade" baseada em lógica usando a função ai.if():
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
AND ai.if(
prompt => 'Does this text: "' || bio ||'" match the user request: "' || :query || '", at least 60%? "',
model_id => 'gemini-3-flash-preview'
)
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 do 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 este comando no terminal do Cloud Shell:
gcloud beta run deploy neighbor-loop \
--source . \
--region=us-central1 \
--network=<<YOUR_NETWORK_NAME>> \
--subnet=<<YOUR_SUBNET_NAME>> \
--allow-unauthenticated \
--vpc-egress=all-traffic \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:<<PORT>>/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.
- Conceda o papel Cliente do AlloyDB à conta de serviço do Cloud Run.Isso permite que seu aplicativo sem servidor faça um túnel seguro no banco de dados.
Execute o seguinte no terminal do Cloud Shell:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
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 for concluída, mas o URL retornar um |
O papel "sombra" do IAM | Mesmo que você tenha permissão para implantar, a conta de serviço do Cloud Run (geralmente |
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 o cluster e a instância do AlloyDB.
Ele vai limpar o cluster e as instâncias dele.
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 AlloyDB, o app fica incrivelmente rápido (sujeito às configurações de implantação) e o código fica muito limpo. Não armazenamos apenas dados, mas também intenção.
A combinação da velocidade do Gemini 3 Flash e do processamento de vetores otimizado do AlloyDB é realmente a próxima fronteira para plataformas orientadas pela comunidade.