1. 總覽
在本程式碼研究室中，您將建構 Neighbor Loop，這是一款永續的剩餘物分享應用程式，可將智慧視為資料層的一等公民。
整合 Gemini 3.0 Flash 和 Cloud SQL 的 ML 整合功能後，您就能超越基本儲存功能，進入資料庫內建智慧功能領域。您將瞭解如何直接在 SQL 中執行多模態項目分析和語意探索。
建構項目
高效能的「向左滑動配對」網頁應用程式，可供社群分享剩餘物資。
課程內容
- 一鍵佈建：瞭解如何設定專為 AI 工作負載設計的 Cloud SQL 和執行個體。
- 資料庫內嵌：直接在 INSERT 陳述式中生成 text-embedding-005 向量。
- 多模態推理：使用 Gemini 3.0 Flash「查看」項目，並自動生成幽默的約會風格簡介。
- 語意探索：在 SQL 查詢中使用 ai.if() 函式，根據邏輯執行「氛圍檢查」，根據情境 (而非僅根據數學) 篩選結果。
架構
Neighbor Loop 可避開傳統應用程式層的瓶頸，我們不會提取資料進行處理，而是使用：
- Cloud SQL + ML 整合：即時生成及儲存向量。
- Google Cloud Storage：儲存圖片
- Gemini 3.0 Flash：直接透過 SQL 對圖片和文字資料執行次秒級的推論作業。
- Cloud Run：用於託管輕量型單一檔案 Flask 後端。
需求條件
2. 事前準備
建立專案
- 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 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. 資料庫設定
在本實驗室中，我們將使用 PostgreSQL 適用的 Cloud SQL 做為測試資料的資料庫。
接下來，我們要建立 Cloud SQL 執行個體，並載入測試資料集。
- 按一下按鈕，或將下方連結複製到已登入 Google Cloud 控制台使用者的瀏覽器。
- 完成這個步驟後，存放區會複製到本機 Cloud Shell 編輯器，您就能從專案資料夾執行下列指令 (請務必確認您位於專案目錄中)：
sh run.sh
- 現在請使用 UI (按一下終端機中的連結，或按一下終端機中的「preview on web」連結)。
- 輸入專案 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;
啟用機器學習整合功能
如要直接在資料庫中使用機器學習功能，請啟用機器學習整合旗標。
您可以在 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 使用者角色
在 Google Cloud IAM 控制台中，將「Vertex AI 使用者」角色授予 Cloud SQL 服務帳戶 (格式如下：service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com)。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 bucket 儲存多餘物品的相片。為了這個示範應用程式，我們希望圖片可公開存取，以便在滑動資訊卡中立即顯示。
- 建立值區：在 GCP 專案中建立新值區 (例如 neighborloop-images)，最好與資料庫和應用程式位於相同區域。
- 設定公開存取權： * 前往 bucket 的「Permissions」分頁。
- 新增 allUsers 主體。
- 指派「Storage 物件檢視者」角色 (讓所有人都能查看相片)，以及「Storage 物件建立者」角色 (用於上傳示範)。
替代方案 (服務帳戶)：如果您不想使用公開存取權，請確保應用程式的服務帳戶已獲得 Cloud SQL 的完整存取權，以及管理物件所需的 Storage 角色，以確保安全。
如要執行指令並授予公開存取權，在 Cloud Shell 終端機執行下列指令：
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
常見錯誤與疑難排解
區域拖曳 | 如果資料庫位於 |
值區名稱的專屬性 | 值區名稱屬於全域命名空間，如果您嘗試將 bucket 命名為 |
「建立者」與「檢視者」混淆 | 「建立者」與「檢視者」混淆：如果您只新增「檢視者」，使用者嘗試列出新項目時，應用程式會當機，因為應用程式沒有寫入檔案的權限。您需要這兩項設定才能進行這項特定示範設定。 |
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 金鑰」。
- 按一下「Create API key in new project」(在新專案中建立 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 的最佳化向量處理功能相輔相成，為社群主導的平台開創全新局面。