1. 簡介
直覺式程式開發徹底改變了前端的開發速度和方式，但通常會在資料庫方面遇到瓶頸。傳統上，開發人員必須切換環境、撰寫複雜的 SQL 結構定義、管理連線集區，以及手動設定資料庫擴充功能。
在本程式碼研究室中，您將體驗流暢的對話式資料庫開發工作流程。您將使用 Model Context Protocol (MCP) 和代理 IDE，將編輯器視為經驗豐富的資料工程師，在幾分鐘內從簡單的概念，建構出完全連線、經過最佳化且支援 AI 的資料庫應用程式，完全不必離開工作區。
建構項目
在本程式碼研究室中，您將建構及部署 AI 美食指南，這是一個以 AlloyDB 為後端的現代化 Next.js 應用程式。應用程式將支援：
- 動態目錄擷取：自動從原始 CSV 檔案匯入及建構餐廳資料。
- 以關鍵字為準的搜尋：使用全文搜尋功能動態查詢資料庫。
- AI 輔助語意搜尋：使用 Agent Platform 嵌入內容，依「氛圍」描述尋找餐廳 (例如「適合約會的舒適場所」或「深夜快速用餐」)。
課程內容
- 佈建具有公開 IP 和虛擬私有雲網路設定的 Google Cloud AlloyDB 執行個體。
- 使用 Model Context Protocol (MCP) Toolbox，將 Antigravity IDE 直接連線至 AlloyDB。
- 使用環境變數和安全 SSL 連線，將 Next.js 前端連線至即時資料庫。
- 啟用資料庫內建的 Agent Platform 整合功能，使用 text-embedding-004 生成向量嵌入。
- 使用餘弦距離運算子 (<=>) 執行向量相似度搜尋。
- 使用 HNSW 索引和資料表分區，盡可能提高生產規模的資料庫效能，扮演虛擬資料庫管理員的角色。
軟硬體需求
如要完成本程式碼研究室，您需要：
- 在本機電腦上安裝 Antigravity。
- 在本機電腦上安裝並驗證 Google Cloud CLI (gcloud) 和 Git。
- 已啟用計費功能的 Google Cloud 專案。
- 網路瀏覽器 (建議使用 Chrome)。
本程式碼研究室適合各種程度的開發人員 (包括初學者)。
2. 事前準備
本節將逐步說明在 Google Cloud 專案中進行初始設定的必要步驟，完成後即可開始建構 AI 柏林美食指南。
建立專案
- 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
- 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
安裝本機必要條件
確認本機電腦已安裝下列工具：
- Antigravity 2.0：安裝 Antigravity
- Git：下載並安裝 Git。
- Google Cloud CLI：下載並安裝 gcloud
設定 Antigravity 2.0
首次啟動 Antigravity 2.0 時，系統會提示您輸入上一個步驟中的 Google Cloud 專案 ID。
輸入專案 ID，初始化工作區：
設定並開啟 Antigravity IDE
我們會在電腦上安裝並開啟 Antigravity IDE，以便執行終端機指令
- 在 Antigravity 2.0 介面中，找到並點選「Install Antigravity IDE」(安裝 Antigravity IDE) 選項 (位於右上角)。
- 下載及安裝提示出現後，請按照安裝精靈的預設設定操作。
- 安裝完成後，啟動 Antigravity IDE
複製存放區並使用 Google Cloud 進行驗證
您將直接在 IDE 中執行所有指令列指令。
- 在本機電腦上開啟 Antigravity IDE
- 開啟 Antigravity 的終端機，然後複製專案存放區：
git clone https://github.com/mtoscano84/vibe-coding-postgres-mcp.git
- 開啟專案資料夾：
- 依序前往「File」>「Open Folder」(或「Open...」)。
- 找出並選取新複製的 vibe-coding-postgres-mcp 資料夾。
- 專案資料夾開啟後，請在 Antigravity IDE 中啟動新的整合式終端機。設定 PROJECT_ID 環境變數，並設定 gcloud CLI 使用該變數 (將 [YOUR_PROJECT_ID] 替換為實際的 GCP 專案 ID)：
export PROJECT_ID=[YOUR_PROJECT_ID]
gcloud config set project $PROJECT_ID
- 登入 Google Cloud CLI：
gcloud auth login
- 登入應用程式預設憑證 (ADC)：(這會建立本機憑證檔案，供實驗室後續的 AI 和 MCP 資料庫連線器使用)
gcloud auth application-default login
- 驗證有效帳戶：
gcloud auth list
啟用必要的 API
在 Antigravity 終端機中執行下列指令，啟用必要的 Google Cloud 服務：
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
3. 建立 AlloyDB 執行個體
在本節中，您將在 Antigravity 終端機中執行自動化指令碼，在 Google Cloud 中佈建 AlloyDB 叢集和執行個體。
在作用中的 Antigravity IDE 整合式終端機 (已位於 vibe-coding-postgres-mcp 專案目錄中)，執行 AlloyDB 佈建指令碼：
source database/deploy_alloydb.sh --region us-central1 --public-ip
注意：佈建程序約需 10 到 15 分鐘
佈建指令碼會執行下列動作：
- 建立名為「default」的虛擬私有雲網路 (如果專案中沒有)。
- 為 AlloyDB 設定私人服務存取權。
- 部署已啟用私人 IP 和公開 IP 的 AlloyDB 叢集和主要執行個體。
- 將必要的 Agent Platform 權限授予 AlloyDB 服務代理。
畫面上應該會顯示類似以下的輸出內容：
----------------------------------------
Deployment Process Completed
Cluster: alloydb-aip-01 (STANDARD)
Instance: alloydb-aip-01-pr
Region: us-central1
Private IP: XX.XX.XX.XX
Public IP: XX.XX.XX.XX
Initial Password: XXXXXXXXXX (if new cluster)
----------------------------------------
請務必複製並儲存下列詳細資料：
- AlloyDB 私人 IP：Cloud Run 應用程式會使用這個 IP 位址，在 VPC 內安全連線。
- AlloyDB 公開 IP：用於本機 Antigravity IDE 直接連線。
- 資料庫密碼：系統為 postgres 使用者自動產生的密碼。
4. 部署前端
在本節中，您將使用 Antigravity IDE 整合式終端機，將基準 Next.js 前端 (狀態 0) 部署至 Google Cloud Run。這個初始版本使用模擬資料，尚未連線至資料庫。
首先，請直接在 Antigravity 終端機中執行下列指令，將必要的 IAM 角色授予 Compute Engine 預設服務帳戶：
PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")
# Grant Storage Object Viewer (to read source code)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/storage.objectViewer"
# Grant Log Writer (to write build logs)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/logging.logWriter"
# Grant Artifact Registry Writer (to push container images)
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"
在 Antigravity 終端機中，從 vibe-coding-postgres-mcp 目錄的根目錄執行下列指令，將 Next.js 應用程式編譯及部署至 VPC 網路：
gcloud run deploy berlin-gastronomy-guide \
--source frontend/ \
--network=default \
--subnet=default \
--allow-unauthenticated \
--region=us-central1
部署完成後，系統會顯示服務網址。
Building using Dockerfile and deploying container to Cloud Run service [berlin-gastronomy-guide] in project [vibe-coding-postgres-mcp] region [us-central1]
Building and deploying...
Validating configuration...done
Uploading sources...done
Building Container... Logs are available at [ https://console.cloud.google.com/cloud-build/builds;region=us-central1/46a6e834-d5e9-4dfd-885e-d39e2790f72d?project=734791203988 ]....done
Setting IAM Policy...done
Creating Revision...done
Routing traffic...done
Done.
Service [berlin-gastronomy-guide] revision [berlin-gastronomy-guide-00002-n6k] has been deployed and is serving 100 percent of traffic.
Service URL: https://berlin-gastronomy-guide-[YOUR_PROJECT_NUMBER].us-central1.run.app
複製網址並在瀏覽器中開啟。
確認您看到柏林 AI 美食指南網頁，其中顯示模擬餐廳資訊卡。
5. 將 Antigravity 連線至 Google Cloud
如要讓在本機執行的 IDE (Antigravity) 中的 AI 代理與資料庫互動，我們會使用官方的 Google Cloud AlloyDB MCP 伺服器。
由於我們在佈建期間已啟用 AlloyDB 執行個體的公開 IP，因此本機 IDE 可以直接透過網際網路連線至該執行個體。連線會使用 SSL 和密碼驗證機制確保安全，且 MCP 伺服器會使用您的本機 Google Cloud 憑證授權連線。
在 Antigravity 中設定 MCP 伺服器
- 在 Antigravity IDE 中，按一下即時通訊視窗右上角的三點選單 (...)。
- 選取 MCP 伺服器，然後按一下「受管理 MCP 伺服器」(或「查看原始設定」/「編輯設定檔」)。
- 在 mcpServers 物件中新增下列 JSON 區塊。請務必將 [YOUR_PROJECT_ID] 和 [YOUR_ALLOYDB_PASSWORD] 替換為實際專案 ID，以及您在 AlloyDB 佈建步驟中儲存的資料庫密碼：
"alloydb-postgres": {
"command": "npx",
"args": [
"-y",
"@toolbox-sdk/server@latest",
"--prebuilt",
"alloydb-postgres",
"--stdio"
],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "[YOUR_PROJECT_ID]",
"ALLOYDB_POSTGRES_REGION": "us-central1",
"ALLOYDB_POSTGRES_CLUSTER": "alloydb-aip-01",
"ALLOYDB_POSTGRES_INSTANCE": "alloydb-aip-01-pr",
"ALLOYDB_POSTGRES_DATABASE": "postgres",
"ALLOYDB_POSTGRES_USER": "postgres",
"ALLOYDB_POSTGRES_PASSWORD": "[YOUR_ALLOYDB_PASSWORD]"
}
}
- 儲存設定檔
- IDE 會自動啟動 MCP 伺服器。MCP 面板中的 alloydb-postgres 旁應會顯示綠點，表示已成功連線。
在 Antigravity 2.0 中開啟存放區
在本實驗室的後續部分，我們將使用 Antigravity 2.0 編寫及建構應用程式。
- 返回 Antigravity 2.0，開啟剛才複製的專案資料夾。
- 依序點選「New Conversation」>「New Project」>「Add Folder」。
- 找出並選取新複製的 vibe-coding-postgres-mcp 資料夾。
- 現在您會在 Antigravity 2.0 中看到 Agent 介面，直接指向複製的工作區，準備好開始編碼！
6. 直覺式程式開發：資料庫擷取
現在 Antigravity 已透過 MCP 伺服器連線至 AlloyDB 執行個體，您可以開始體驗 vibe-coding。
在這個步驟中，您會指示 AI 代理程式讀取含有柏林美食目錄的本機 CSV 檔案，並載入 AlloyDB 資料庫。
工作
您將在 Antigravity 中使用 Agent Chat。代理程式會自主讀取檔案、分析資料類型、連線至資料庫、建立資料表，以及插入記錄。
接著複製下列提示詞，貼到對話中並按下 Enter 鍵：
Read the headers of database/seed_data_berlin.csv. Connect to the database via the MCP tool, create a table named restaurants with the correct data types, and load all the records from the CSV file into it.
觀察代理程式執行工作：
- 系統會先讀取 CSV 檔案標頭和一些範例資料列，判斷適當的結構定義。
- 這項工具會呼叫 AlloyDB MCP 工具，建立餐廳資料表。
- 這會將 CSV 檔案中的 100 筆餐廳記錄批次插入資料庫。
驗證
代理程式告知完成後，您可以驗證資料是否已載入：
在 Agent Chat 中詢問代理：
Show me the first 5 records from the restaurants table.
代理程式會查詢資料庫並顯示前 5 間餐廳 (例如 Pub Lia's Kitchen 和 Cafe Clärchens)，確認資料庫擷取作業成功。
7. 直覺式程式開發：將前端連結至資料庫
在本節中，您會將 Next.js 前端連結至即時 AlloyDB 資料庫。您將指示代理程式以即時資料庫查詢取代模擬資料，並實作關鍵字搜尋。
工作
您會提示代理程式編寫連線程式碼，並更新首頁。由於我們在 .agents/AGENTS.md 中提交了資料庫 SSL 規則，因此代理程式會自動設定連線集區，以使用 SSL 進行雲端連線，您不需要在提示中指定這項設定！
在 Antigravity Agent 對話中，複製並貼上下列提示，然後按下 Enter 鍵 (將 [YOUR_PASSWORD] 換成實際的資料庫密碼)：
Connect our Next.js frontend to the restaurants table in the database using the pg library. Use a connection pool configured with environment variables: DB_HOST, DB_USER (postgres), DB_PASS (password is '[YOUR_PASSWORD]'), and DB_NAME (postgres). Replace the mock data in page.tsx with a live query, and implement keyword search on the name, category, and description
觀察代理程式執行工作：
- 這會安裝 pg 套件和 TypeScript 型別 (@types/pg)。
- 這會建立資料庫連線檔案 (或 Next.js 伺服器動作)，並設定連線集區。
- 這項工具會讀取 AGENTS.md 規則，並自動為非本機主機新增 SSL 設定。
- 這會重新編寫 page.tsx，查詢資料庫並根據搜尋查詢篩選結果。
驗證
如要測試變更，您必須將前端重新部署至 Cloud Run。由於我們採用「僅限雲端」流程，因此新代碼會以這種方式出貨。
在 Antigravity IDE 中開啟整合式終端機 (請確認您位於根目錄)。
執行部署指令，並將 AlloyDB 私人 IP 和密碼做為環境變數傳遞 (將預留位置替換為實際值)：
gcloud run deploy berlin-gastronomy-guide \
--source frontend/ \
--network=default \
--subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
--allow-unauthenticated \
--region=us-central1
部署完成後，請在瀏覽器中開啟服務網址。
嘗試搜尋「Burgermeister」或「Kebab」。您應該會看到從資料庫載入的真實餐廳！
請注意，餐廳資訊卡現在會顯示實際的 GCS 圖片 (因為資料庫記錄包含我們稍早上傳的公開 GCS 網址！)。
8. 直覺式程式開發：啟用語意搜尋
在本節中，您將升級應用程式，支援 AI 輔助的語意向量搜尋。使用者不必輸入完全相符的關鍵字，只要描述想找的「氛圍」或體驗 (例如「浪漫的晚餐地點」或「夜店後快速用餐」)，就能找到所需資訊。
工作
您將指示代理在餐廳資料表上啟用語意搜尋。代理程式會運用存放區中的 add-vector-search-alloydb 自訂技能，自動處理資料庫擴充功能、Agent Platform 模型註冊、嵌入生成和查詢更新。
在 Antigravity Agent 對話中，複製並貼上下列提示，然後按下 Enter 鍵：
Upgrade our database to support Semantic Vector Search on the restaurants table based on the description column. Then, update our frontend search query to use vector similarity search.
觀察代理程式執行工作：
- 這項指令會連線至 AlloyDB，並啟用 vector (pgvector) 和 google_ml_integration 擴充功能。
- 這會在資料庫中註冊 Agent Platform 嵌入模型 (text-embedding-004)。
- 系統會在餐廳資料表中新增嵌入欄。
- 系統會執行資料庫內查詢，為所有 100 筆餐廳說明生成嵌入內容。
- 這會更新前端程式碼，為使用者的搜尋查詢產生嵌入，並使用餘弦距離運算子 (<=>) 執行向量相似度搜尋。
驗證
將更新後的程式碼重新部署至 Cloud Run。
在 Antigravity IDE 整合式終端機中，執行部署指令 (將預留位置替換成實際值)：
gcloud run deploy berlin-gastronomy-guide \
--source frontend/ \
--network=default \
--subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
--allow-unauthenticated \
--region=us-central1
部署完成後，請在瀏覽器中開啟服務網址。
輸入自然語言描述 (例如)：
- 「a romantic dinner spot」
- 「clubbing 後的點心」
請注意，即使名稱或說明中沒有「浪漫」或「夜店」等確切字詞，系統仍會傳回高度相關的餐廳 (例如 Cafe Clärchens 或 Burgermeister)！
9. 直覺式程式開發：資料庫最佳化
隨著應用程式成長，資料庫必須經過最佳化調整，才能處理大量資料 (超過 10 萬列) 和高並行搜尋流量。在最後一個步驟中，您會將虛擬服務專員視為虛擬資料庫管理員 (DBA)，分析及最佳化資料庫結構定義。
工作
您會要求代理扮演首席資料庫架構師，分析目前的結構定義，並建議最佳化做法。審查並核准最佳化建議後，代理程式就會使用 optimize-database-alloydb 自訂技能，自動套用這些建議。
Act as a Principal Database Architect. Our semantic search is working, but we need to optimize the database for production scale. Analyze our current schema. What are the top 2 database-schema optimizations you recommend we implement right now? Explain them to me and wait for my approval before modifying the database.
代理程式會分析資料庫，並回覆兩項建議：
- HNSW 索引：嵌入欄的近似最鄰近 (ANN) 索引，可大幅加快向量相似度查詢速度。
- 資料表分區：將餐廳資料表分區 (例如依據鄰近地區進行清單分區)，以提升查詢效能及可管理性。
查看說明。準備就緒後，請在即時通訊中回覆服務專員：
Approved, please apply these optimizations.
觀察代理程式執行工作：
- 這會在嵌入資料欄上建立 HNSW 索引。
- 系統會依據鄰里劃分餐廳資料表，為每個鄰里建立子分區資料表，並遷移現有資料。
驗證
請服務專員確認最佳化設定是否已成功套用。在 Agent Chat 中詢問：
Show me the list of partitions for the restaurants table and the indexes on it.
代理程式會查詢資料庫目錄，並顯示新的分割區結構 (例如 restaurants_mitte、restaurants_kreuzberg) 和 HNSW 索引，確認資料庫現在已完全針對正式環境進行最佳化！
10. 挑戰：新增評論和評分
現在輪到你大顯身手，測試 Vibe 程式碼技能了！在這項挑戰中，您將擴充柏林美食指南，支援顧客評論和星級評等。
工作
請在 Antigravity Agent Chat 中自行編寫提示，而非複製並貼上提示，以實作下列功能：
- 資料庫結構定義：建立連結至
restaurants資料表的新reviews資料表。應儲存評分 (1 到 5 的整數) 和簡短的文字評論。 - 生成資料：為資料庫中的 100 間餐廳各生成 3 到 4 則真實的顧客評論。
- 前端整合：更新 Next.js 前端，計算並顯示每個餐廳資訊卡上的平均星等 (例如
⭐⭐⭐⭐☆)。 - 篩選：在頁面頂端新增下拉式篩選器，依評分篩選餐廳 (例如「顯示全部」、「4 星以上」、「3 星以上」)。
驗證
代理程式完成工作後，請從 Antigravity IDE 整合式終端機，將應用程式重新部署至 Cloud Run (將預留位置替換為實際值)：
gcloud run deploy berlin-gastronomy-guide \
--source frontend/ \
--network=default \
--subnet=default \
--set-env-vars="DB_HOST=[YOUR_ALLOYDB_PRIVATE_IP],DB_USER=postgres,DB_PASS=[YOUR_PASSWORD],DB_NAME=postgres" \
--allow-unauthenticated \
--region=us-central1
部署完成後，請重新整理瀏覽器，並確認卡片上的星等
。
11. 結果
完成上述步驟後，您已成功使用直覺式程式開發，建構及最佳化新一代以資料庫為基礎的 AI 應用程式。本節重點說明您實作的核心架構功能：
Agentic Database Integration (Model Context Protocol)
傳統上，編寫資料庫程式碼時，您必須手動在 IDE、說明文件和資料庫用戶端之間切換。
在本實驗室中，您使用了 Model Context Protocol (MCP) Toolbox 來彌補這項差距。將資料庫結構定義檢查和 SQL 執行作業直接做為工具提供給 AI 代理程式，代理程式就能：
- 檢查原始 CSV 資料，並設計資料庫結構定義。
- 產生並執行 DDL 來建立資料表。
- 在 Next.js 應用程式中連結連線集區。
這項功能可讓開發人員在 IDE 中完全掌控資料庫，同時享受對話式的高速開發體驗。
資料庫內建 AI (Agent Platform 和語意搜尋)
您的應用程式運用 AlloyDB 與 Google Cloud Agent Platform 的原生整合功能，直接在資料庫內使用 SQL 生成向量嵌入：
- 線上生成嵌入項目：AlloyDB 會透過 SQL 函式在資料庫中呼叫 text-embedding-004 模型，不必將資料擷取至外部 Python 服務。
- 語意向量搜尋：透過 pgvector 擴充功能和餘弦距離運算子 (<=>)，代理程式可將使用者的自然語言「氛圍」(例如「浪漫晚餐」) 與餐廳目錄中最接近的向量表示法相符，並在毫秒內傳回語意相關的結果。
生產環境等級的資料庫最佳化 (HNSW 和分割)
為確保應用程式可擴充至 10 萬列以上，並處理高流量，您以虛擬 DBA 的身分套用兩項進階資料庫最佳化措施：
- HNSW (階層式可導覽小世界) 索引：您在向量欄上建立了 HNSW 索引。與平面索引不同，HNSW 會建構多層圖表，可進行極快的近似最鄰近 (ANN) 搜尋，且召回率高。
- 宣告式資料表分區：您已依據鄰近地區將餐廳資料表分區。這可確保查詢特定區域時，系統只會掃描相關分區，而非整個資料表，大幅減少磁碟 I/O 和查詢延遲。
應用程式開發人員通常會避開複雜的資料庫設定、向量數學和深入的索引策略，因為這些都需要專業的 DBA 知識。透過代理式 IDE 搭配直覺式程式開發，我們就能彌合這項差距。現在，我們可以使用自然語言，放心地設計、建構及最佳化生產級資料庫應用程式，大幅加快開發週期，並專注於最重要的事：打造優質的使用者體驗。
12. 清除
如要避免系統向您的 Google Cloud 帳戶收取本實驗室所用資源的費用，請按照下列步驟操作：
13. 恭喜
您已成功使用 Vibe Coding，建構及部署以資料為基礎的 AI 輔助應用程式！
本實驗室的學習內容如下：
- 佈建 AlloyDB 資料庫，並同時提供私人和公開 IP 存取權。
- 使用 Model Context Protocol (MCP) Toolbox，直接將 Antigravity IDE 連線至資料庫。
- 使用自然語言擷取 CSV 目錄、將 Next.js 前端連線至資料庫，並部署至 Cloud Run。
- 啟用資料庫內建的 Agent Platform 整合功能，生成向量嵌入並執行語意搜尋。
- 擔任虛擬 DBA，使用 HNSW 索引和資料表分割功能，將資料庫最佳化，以因應生產規模。
您只需與 AI 代理程式進行自然對話，不必手動編寫任何 SQL 程式碼，也不必開啟外部資料庫用戶端，就能完成上述所有作業！
詳情請參閱產品說明文件：