1. 概览
在此 Codelab 中，您将构建 Neighbor Loop，这是一款可持续的盈余共享应用，可将智能视为数据层的一等公民。
通过集成 Gemini 3.0 Flash 和 Cloud SQL 的机器学习集成功能，您将超越基本存储，进入数据库内智能领域。您将学习如何在 SQL 中直接执行多模态项目分析和语义发现。
构建内容
一款高性能的“滑动配对”Web 应用，用于社区剩余物品分享。
学习内容
- 一键式配置：如何设置专为 AI 工作负载设计的 Cloud SQL 实例。
- 数据库内嵌：直接在 INSERT 语句中生成 text-embedding-005 向量。
- 多模态推理：使用 Gemini 3.0 Flash“查看”商品，并自动生成诙谐幽默的约会风格个人简介。
- 语义发现：使用 ai.if() 函数在 SQL 查询中执行基于逻辑的“氛围检查”，以根据上下文（而不仅仅是数学）过滤结果。
架构
Neighbor Loop 可绕过传统的应用层瓶颈。我们不再提取数据进行处理，而是使用：
- Cloud SQL + 机器学习集成：用于实时生成和存储向量。
- Google Cloud Storage：用于存储图片
- Gemini 3.0 Flash：直接通过 SQL 对图片和文本数据执行亚秒级推理。
- Cloud Run：用于托管轻量级单文件 Flask 后端。
要求
2. 准备工作
创建项目
- 在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。
- 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
- 您将使用 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。
- 连接到 Cloud Shell 后，您可以使用以下命令检查自己是否已通过身份验证，以及项目是否已设置为您的项目 ID：
gcloud auth list
- 在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目。
gcloud config list project
- 如果项目未设置，请使用以下命令进行设置：
gcloud config set project <YOUR_PROJECT_ID>
- 启用必需的 API：点击此链接并启用相应的 API。
或者，您也可以使用 gcloud 命令来完成此操作。如需了解 gcloud 命令和用法，请参阅文档。
注意事项和问题排查
“幽灵项目” 综合征 | 您运行了 |
结算 路障 | 您已启用项目，但忘记了结算账号。如果结算信息为空，Cloud SQL 将不会启动。 |
API 传播 延迟 | 您点击了“启用 API”，但命令行仍显示 |
3. 数据库设置
在本实验中，我们将使用 Cloud SQL for PostgreSQL 作为测试数据的数据库。
我们来创建一个 Cloud SQL 实例，用于加载测试数据集。
- 点击相应按钮，或将下方的链接复制到已登录 Google Cloud 控制台用户的浏览器中。
- 完成此步骤后，代码库将克隆到本地 Cloud Shell 编辑器，您将能够从项目文件夹中运行以下命令（请务必确保您位于项目目录中）：
sh run.sh
- 现在，使用界面（点击终端中的链接或点击终端中的“在网页上预览”链接）。
- 输入项目 ID 和实例名称等详细信息，即可开始使用。
- 在日志滚动时，您可以去喝杯咖啡，然后点击此处了解其幕后运作方式。
注意事项和问题排查
地区不匹配 | 如果您在 |
Cloud Shell 超时 | 如果您的咖啡休息时间为 30 分钟，Cloud Shell 可能会进入休眠状态并断开 |
4. 架构配置
Cloud SQL 实例运行后，前往 Cloud SQL Studio SQL 编辑器，启用 AI 扩展程序并预配架构。
您可能需要等待实例完成创建。完成后，使用您在创建 Cloud SQL 实例时创建的凭据登录该实例。使用以下数据向 PostgreSQL 进行身份验证：
- 用户名：“
postgres” - 数据库：“
postgres” - 密码：“
cloudsql”（或您在创建时设置的任何密码）
成功通过 Cloud SQL Studio 的身份验证后，您可以在编辑器中输入 SQL 命令。您可以使用最后一个窗口右侧的加号添加多个编辑器窗口。
您将在编辑器窗口中输入 Cloud SQL 命令，并根据需要使用“运行”“格式化”和“清除”选项。
启用扩展程序
在构建此应用时，我们将使用扩展程序 pgvector 和 google_ml_integration。借助 pgvector 扩展程序，您可以存储和搜索向量嵌入。google_ml_integration 扩展程序提供用于访问 Vertex AI 预测端点以在 SQL 中获取预测结果的函数。运行以下 DDL 以启用这些扩展程序：
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
创建表
您可以在 Cloud SQL Studio 中使用以下 DDL 语句创建表：
-- 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()
);
item_vector 列将允许存储文本的矢量值。
授予权限
运行以下语句，以授予对“embedding”函数的执行权限：
GRANT EXECUTE ON FUNCTION embedding TO postgres;
启用机器学习集成
如需直接在数据库中利用机器学习功能，您需要启用 ML 集成标志。
您可以在 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
为 Cloud SQL 服务账号授予 Vertex AI User 角色
在 Google Cloud IAM 控制台中，向 Cloud SQL 服务账号（格式如下：service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com）授予“Vertex AI 用户”角色。PROJECT_NUMBER 将包含您的项目编号。
或者，您也可以从 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"
在 Cloud SQL 中注册 Gemini 3 Flash 模型
在 Cloud SQL 查询编辑器中运行以下 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.
注意事项和问题排查
“密码遗忘”循环 | 如果您使用了“一键”设置，但不记得密码，请前往控制台中的实例基本信息页面，然后点击“修改”以重置 |
“找不到扩展程序”错误 | 如果 |
IAM 传播差距 | 您运行了 |
向量维度不匹配 | 将 |
项目 ID 拼写错误 | 在 |
Vertex AI 集成已停用 | 运行 |
5. 图片存储 (Google Cloud Storage)
为了存储剩余物品的照片，我们使用了一个 GCS 存储分区。在此演示应用中，我们希望图片可公开访问，以便它们在滑动卡片中立即呈现。
- 创建存储分区：在您的 GCP 项目中创建一个新存储分区（例如 neighborloop-images），最好与您的数据库和应用位于同一区域。
- 配置公开访问权限： * 前往存储分区的权限标签页。
- 添加 allUsers 主账号。
- 分配 Storage Object Viewer 角色（以便所有人都能查看照片）和 Storage Object Creator 角色（用于演示上传）。
替代方案（服务账号）：如果您不想使用公开访问权限，请确保为应用的服务账号授予对 Cloud SQL 的完全访问权限，以及管理对象所需的存储角色。
如果您希望运行该命令并授予公开访问权限。在 Cloud Shell 终端中运行以下命令：
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
注意事项和问题排查
区域拖动 | 如果您的数据库位于 |
存储分区名称的唯一性 | 存储分区名称是全局命名空间。如果您尝试将存储分区命名为 |
“创作者”与“观看者”的混淆 | “创建者”与“查看者”混淆：如果您仅添加“查看者”，那么当用户尝试列出新商品时，应用会因没有写入文件的权限而崩溃。在此特定演示设置中，您需要同时使用这两个参数。 |
6. 我们来创建应用
将此代码库克隆到您的项目中，然后我们来逐步了解一下。
- 如需克隆此项目，请在 Cloud Shell 终端中（在根目录中或在您要创建此项目的任何位置）逐个运行以下命令：
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
这应该会创建项目，您可以在 Cloud Shell 编辑器中验证这一点。
- 如何获取 Gemini API 密钥
- 访问 Google AI Studio：前往 aistudio.google.com。
- 登录：使用您用于 Google Cloud 项目的同一 Google 账号。
- 创建 API 密钥：
- 在左侧边栏中，点击“获取 API 密钥”。
- 点击“在新项目中创建 API 密钥”按钮。
- 复制密钥：生成密钥后，点击复制图标。
- 现在，在 .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>>
替换占位符 <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>. 的值
注意事项和问题排查
多账号混淆 | 如果您登录了多个 Google 账号（个人账号与工作账号），AI Studio 可能会默认使用错误的账号。检查右上角的头像，确保其与您的 GCP 项目账号一致。 |
达到“免费层级”配额 | 如果您使用的是“免费”层级，则会受到速率限制（RPM - 每分钟请求数）。如果您在邻居圈中“滑动”得太快，可能会收到 |
公开密钥安全性 | 如果您不小心 |
7. 我们来检查一下代码
您物品的“约会资料”
用户上传商品照片时，无需撰写长篇说明。我使用 Gemini 3 Flash 来“查看”商品并撰写商品详情。
在后端，用户只需提供标题和照片。Gemini 会处理其余事宜：
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")
)
实时数据库内嵌
Cloud SQL 最酷的功能之一是能够在不离开 SQL 上下文的情况下生成嵌入。我没有在 Python 中调用嵌入模型并将向量发送回数据库，而是使用 embedding() 函数在一个 INSERT 语句中完成了所有操作：
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
)
这样可确保每件商品在发布后立即就能通过其含义进行搜索。请注意，此部分涵盖了 Neighbor Loop 应用的“列出商品”功能。
使用 Gemini 3.0 实现高级向量搜索和智能过滤
标准关键字搜索存在限制。如果您搜索“something to fix my chair”，如果某个商品的标题中没有“chair”一词，传统数据库可能不会返回任何结果。Neighbor Loop 通过 Cloud SQL AI 的高级向量搜索功能解决了这一问题。
通过使用 pgvector 扩展程序和 Cloud SQL 的优化存储，我们可以执行极快的相似性搜索。不过，当我们将向量邻近度与基于 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
此查询代表着重大的架构转变：我们将逻辑移至数据。Gemini 3 Flash 不会将数千个结果提取到应用代码中进行过滤，而是在数据库引擎内部执行“氛围检查”。这不仅可以缩短延迟时间、降低出站流量费用，还可以确保结果不仅在数学上相似，而且在上下文上相关。
“滑动配对”循环
界面是一副经典的卡牌。
向左滑动：舍弃。
向右滑动：配对成功！
当您向右滑动时，后端会在滑动次数表中记录相应互动，并将相应商品标记为已配对。前端会立即触发一个模态框，其中显示提供商的联系信息，以便您安排取货。
8. 我们将其部署到 Cloud Run
- 通过在克隆项目的 Cloud Shell 终端中运行以下命令，将其部署到 Cloud Run 上，确保您位于项目的根文件夹中。
在 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>>
替换占位符 <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>> 的值
命令运行完毕后，系统会输出服务网址。复制。
现在，使用服务网址（您之前复制的 Cloud Run 端点）测试应用。上传旧电动工具的照片，然后让 Gemini 完成剩下的工作！
注意事项和问题排查
“修订失败”循环 | 如果部署完成，但网址显示 |
9. 高级问题排查
10. 演示
您应该能够将端点用于测试。
不过，为了演示目的，您可以在几天内尝试以下操作：
11. 清理
完成本实验后，请务必删除 Cloud SQL 实例。
12. 恭喜
您已成功使用 Google Cloud 构建了 Neighbor Loop 应用，以打造可持续发展的社区。通过将嵌入和 Gemini 3 Flash AI 逻辑移入 Cloud SQL，应用的速度非常快（取决于部署设置），代码也非常简洁。我们不仅能存储数据，还能存储意图。
Gemini 3 Flash 的速度与 Cloud SQL 的优化矢量处理相结合，真正为社区驱动型平台开创了新局面。