使用 Gemini 3 Flash 和 Cloud SQL 构建实时盈余引擎

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 后端。

要求

浏览器，例如 Chrome 或 Firefox。
启用了结算功能的 Google Cloud 项目。
对 SQL 和 Python 有基本的了解。

2. 准备工作

创建项目

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

您将使用 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

“激活 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 命令和用法，请参阅文档。

注意事项和问题排查

“幽灵项目” 综合征	您运行了 `gcloud config set project`，但实际上您在控制台界面中查看的是另一个项目。检查左上角下拉列表中的项目 ID！
结算障碍	您启用了项目，但忘记了结算账号。如果结算账号为空，Cloud SQL 将无法启动。
API 传播延迟	您点击了“启用 API”，但命令行仍然显示 `Service Not Enabled`。请等待 60 秒。云需要一点时间来唤醒其神经元。

3. 数据库设置

在本实验中，我们将使用 Cloud SQL for PostgreSQL 作为测试数据的数据库。

让我们创建一个 Cloud SQL 实例，用于加载测试数据集。

点击该按钮，或将以下链接复制到您已登录 Google Cloud 控制台用户的浏览器中。

完成此步骤后，代码库将克隆到本地 Cloud Shell 编辑器，您将能够从项目文件夹中运行以下命令（请务必确保您位于项目目录中）：

sh run.sh

现在，使用界面（点击终端中的链接或点击终端中的“在网络上预览”链接）。
输入项目 ID 和实例名称的详细信息，即可开始使用。
在日志滚动时，您可以去喝杯咖啡，并在此处了解其在后台的运行方式。

注意事项和问题排查

区域不匹配	如果您在 `us-central1` 中启用了 API，但尝试在 `asia-south1` 中预配集群，则可能会遇到配额问题或服务账号权限延迟。请在整个实验中坚持使用一个区域！
Cloud Shell 超时	如果您的咖啡休息时间为 30 分钟，Cloud Shell 可能会进入休眠状态并断开 `sh run.sh` 进程。请保持标签页处于活动状态！

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;

启用机器学习集成

如需直接在数据库中使用机器学习功能，您需要启用机器学习集成标志。

您可以从 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 User”角色的访问权限。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.

注意事项和问题排查

“密码失忆”循环	如果您使用了“一键式”设置，但忘记了密码，请前往控制台中的实例基本信息页面，然后点击“修改”以重置 `postgres` 密码。
“找不到扩展程序”错误	如果 `CREATE EXTENSION` 失败，通常是因为实例仍处于初始预配的“维护”或“更新”状态。请检查实例创建步骤是否已完成，并根据需要等待几秒钟。
IAM 传播差距	您运行了 `gcloud` IAM 命令，但 SQL `CALL` 仍然失败，并显示权限错误。IAM 更改可能需要一些时间才能通过 Google 主干网传播。请深呼吸。
向量维度不匹配	`items` 表设置为 `VECTOR(768)`。如果您稍后尝试使用其他模型（例如 1536 维模型），则插入操作将会失败。请坚持使用 `text-embedding-005`。
项目 ID 拼写错误	在 `create_model` 调用中，如果您遗漏了方括号 `« »` 或错误输入了项目 ID，则模型注册看起来会成功，但在第一次实际查询期间会失败。请仔细检查您的字符串！
Vertex AI 集成已停用	运行 `–enable-google-ml-integration`（与数据库标志分开）

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"

注意事项和问题排查

区域拖动	如果您的数据库位于 `us-central1` 中，而存储分区位于 `europe-west1` 中，则实际上是在降低 AI 的速度。“氛围检查”会快速进行，但提取界面图片会感觉很慢。请将它们放在同一区域！
存储分区名称的唯一性	存储分区名称是全局命名空间。如果您尝试将存储分区命名为 `neighborloop-images`，则其他人可能已经使用了该名称。如果创建失败，请添加随机后缀。
“创建者”与“查看者”混淆	“创建者”与“查看者”混淆：如果您仅添加“查看者”，则当用户尝试列出新商品时，应用会崩溃，因为它没有写入文件的权限。对于此特定演示设置，您需要同时添加这两个角色。

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 - 每分钟请求数）。如果您在 Neighbor Loop 中“滑动”过快，则可能会收到 `429 Too Many Requests` 错误。请减慢速度！
公开密钥安全	如果您不小心 `git commit` 了包含密钥的 `.env` 文件。请始终将 `.env` 添加到 `.gitignore`。

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 完成其余工作！

注意事项和问题排查

“修订失败”循环

如果部署完成，但网址返回 500 Internal Server Error，请检查日志！这通常是由于缺少环境变量 （例如 DATABASE_URL 中的拼写错误）或 Cloud Run 服务账号缺少从 GCS 存储分区读取的权限所致。

9. 高级问题排查

10. 演示

您应该能够使用端点进行测试。

但为了演示目的，您可以在几天内使用以下内容：

11. 清理

完成此实验后，请不要忘记删除 Cloud SQL 实例。

12. 恭喜

您已使用 Google Cloud 成功构建了 Neighbor Loop 应用，以打造可持续的社区。通过将嵌入和 Gemini 3 Flash AI 逻辑移到 Cloud SQL 中，应用速度非常快（取决于部署设置），并且代码非常简洁。我们不仅存储数据，还存储意图。

Gemini 3 Flash 的速度与 Cloud SQL 的优化向量处理相结合，真正代表了社区驱动型平台的下一个前沿。

使用 Gemini 3 Flash 和 Cloud SQL 构建实时盈余引擎 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

1. 概览

构建内容

学习内容

架构

要求

2. 准备工作

创建项目

注意事项和问题排查

3. 数据库设置

注意事项和问题排查

4. 架构预配

启用扩展程序

创建表

授予权限

启用机器学习集成

为 Cloud SQL 服务账号授予 Vertex AI User 角色

在 Cloud SQL 中注册 Gemini 3 Flash 模型

注意事项和问题排查

5. 图片存储 (Google Cloud Storage)

注意事项和问题排查

6. 开始创建应用

注意事项和问题排查

7. 检查代码

商品的“约会资料”

实时数据库内嵌入

使用 Gemini 3.0 进行高级向量搜索和智能过滤

“滑动匹配”循环

8. 将其部署到 Cloud Run

注意事项和问题排查

9. 高级问题排查

10. 演示

11. 清理

12. 恭喜

使用 Gemini 3 Flash 和 Cloud SQL 构建实时盈余引擎