Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 AlloyDB 进行氛围编程：借助 Antigravity 从 0 到生产

1. 简介

氛围编程彻底改变了前端的开发速度和方式，但它在到达数据库时往往会遇到瓶颈。过去，开发者必须切换上下文、编写复杂的 SQL 架构、管理连接池，并手动配置数据库扩展程序。

在此 Codelab 中，您将体验顺畅的对话式数据库开发工作流程。借助 Model Context Protocol (MCP) 和智能体 IDE，您将能够像经验丰富的数据工程师一样使用编辑器，在几分钟内将一个简单的想法转化为一个完全连接、优化且支持 AI 的数据库应用，而无需离开工作区。

构建内容

在此 Codelab 中，您将构建并部署 AI 美食指南，这是一个由 AlloyDB 提供支持的现代 Next.js 应用。该应用将支持：

动态目录注入：自动从原始 CSV 文件导入和构建餐厅数据。
基于关键字的搜索：使用全文搜索动态查询数据库。
AI 赋能的语义搜索：使用 Agent Platform 嵌入模型，通过描述“氛围”（例如“适合约会的舒适场所”或“夜间快餐”）来查找餐厅。

学习内容

预配具有公共 IP 和 VPC 网络配置的 Google Cloud AlloyDB 实例。
使用 Model Context Protocol (MCP) Toolbox 将 Antigravity IDE 直接连接到 AlloyDB。
使用环境变量和安全的 SSL 连接将 Next.js 前端连接到实时数据库。
启用数据库内 Agent Platform 集成，以使用 text-embedding-004 生成向量嵌入。
使用余弦距离运算符 (<=>) 执行向量相似度搜索。
使用 HNSW 索引和表分区来优化生产规模的数据库性能，充当虚拟 DBA。

所需条件

要完成本 Codelab，您需要：

在本地机器上安装了 Antigravity。
Google Cloud CLI (gcloud) 和 Git 已在本地机器上安装并经过身份验证。
启用了结算功能的 Google Cloud 项目。
网络浏览器（建议使用 Chrome）。

本 Codelab 适合各种水平的开发者，包括新手。

2. 准备工作

本部分将引导您完成 Google Cloud 项目中所需的初始设置，然后您才能开始构建 AI 柏林美食指南。

创建项目

在 Google Cloud Console 的项目选择器页面上，选择或创建一个 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

打开项目文件夹：
依次前往“文件”>“打开文件夹”（或“打开…”）。
找到并选择新克隆的 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

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”的 VPC 网络（如果您的项目中不存在此类网络）。
为 AlloyDB 设置专用服务访问通道。
部署同时启用了专用 IP 和公共 IP 的 AlloyDB 集群和主实例。
向 AlloyDB 服务代理授予必要的 Agent Platform 权限。

输出的内容应类似于以下文本：

----------------------------------------
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 应用用于在 VPC 内安全连接。
AlloyDB 公共 IP：由本地 Antigravity IDE 用于直接连接。
数据库密码：为 postgres 用户自动生成的密码。

4. 部署前端

在本部分中，您将使用 Antigravity IDE 集成终端将基准 Next.js 前端（状态 0）部署到 Google Cloud Run。此初始版本使用模拟数据，但尚未连接到数据库。

首先，在 Antigravity 终端中直接运行以下命令，向 Compute Engine 默认服务账号授予必要的 IAM 角色：

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，然后打开您刚刚克隆的项目文件夹。
依次点击“新建对话”>“新建项目”>“添加文件夹”。
找到并选择新克隆的 vibe-coding-postgres-mcp 文件夹。
现在，您将在 Antigravity 2.0 中看到指向克隆工作区的智能体界面，随时可以开始编码！

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 工具来创建表 restaurants。
它会将 CSV 文件中的 100 条餐厅记录批量插入到数据库中。

验证

当代理告知您已完成时，您可以验证数据是否已加载：

在代理聊天中，向代理提问：

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 赋能的语义向量搜索。用户无需再只通过完全匹配的关键字进行搜索，而是可以通过描述自己想要的“氛围”或体验进行搜索（例如“浪漫的晚餐地点”或“夜店后的快餐”）。

任务

您将指示代理在“restaurants”表上启用语义搜索。智能体将利用代码库中的 add-vector-search-alloydb 自定义技能自动处理数据库扩展程序、智能体平台模型注册、嵌入生成和查询更新。

在 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”
“夜店狂欢后的快餐”

请注意，即使名称或说明中没有“浪漫”或“夜店”等确切字词，它也会返回高度相关的餐厅（例如 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 索引。
它将按社区对餐厅表进行分区，为每个社区创建子分区表，并迁移现有数据。

验证

请代理验证优化是否已成功应用。在智能体对话中，提出以下问题：

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 数据库集成（模型上下文协议）

传统上，编写数据库代码是一个手动过程，需要在 IDE、文档和数据库客户端之间切换。

在本实验中，您使用了 Model Context Protocol (MCP) 工具箱来弥合这一差距。通过将数据库架构检查和 SQL 执行直接作为工具向 AI 代理公开，该代理能够：

检查原始 CSV 数据并设计数据库架构。
生成并执行 DDL 以创建表。
在 Next.js 应用中连接连接池。

此视频展示了 MCP 如何在 IDE 中让开发者完全掌控数据库开发，同时提供对话式高速体验。

数据库内 AI（代理平台和语义搜索）

您的应用利用 AlloyDB 与 Google Cloud 的 Agent Platform 的原生集成，使用 SQL 直接在数据库内生成向量嵌入：

在线生成嵌入：AlloyDB 不会将数据提取到外部 Python 服务，而是通过 SQL 函数在数据库内调用 text-embedding-004 模型。
语义向量搜索：通过使用 pgvector 扩展程序和余弦距离运算符 (<=>)，代理可以根据用户的自然语言“氛围”（例如“浪漫晚餐”）在餐厅目录中找到最接近的向量表示形式，并在几毫秒内返回语义相关的结果。

生产级数据库优化（HNSW 和分区）

为了确保应用可以扩缩到 10 万行以上，并处理高流量，您充当虚拟 DBA 来应用两项高级数据库优化：

HNSW（分层可导航小世界）索引：您在向量列上创建了 HNSW 索引。与扁平索引不同，HNSW 构建了一个多层图，可实现极快的近似最近邻 (ANN) 搜索，并具有较高的召回率。
声明式表分区：您按社区对餐厅表进行了分区。这样可确保以特定区域为目标的查询仅扫描相关分区，而不是整个表，从而大幅减少磁盘 I/O 和查询延迟时间。

作为应用开发者，我们往往会避开复杂的数据库配置、向量数学和深度索引策略，因为这些都需要专业的 DBA 知识。通过将氛围编程与智能体 IDE 相结合，我们可以弥合这一差距。现在，我们可以放心地使用自然语言设计、构建和优化生产级数据库应用，从而显著缩短开发周期，并专注于最重要的事情：打造出色的用户体验。

12. 清理

为避免系统因本实验中使用的资源向您的 Google Cloud 账号收取费用，请按照以下步骤操作：

在 Google Cloud 控制台中，前往管理资源页面。
在项目列表中，选择要删除的项目，然后点击“删除”。
在对话框中输入项目 ID，然后点击“关停”以删除项目。

13. 恭喜

您已成功使用氛围编程构建并部署了一个数据驱动型 AI 赋能的应用！

您此实验中，您将执行以下操作：

预配了同时支持专用 IP 和公共 IP 访问的 AlloyDB 数据库。
使用 Model Context Protocol (MCP) Toolbox 将 Antigravity IDE 直接连接到数据库。
使用自然语言提取 CSV 目录，将 Next.js 前端连接到数据库，并将其部署到 Cloud Run。
在数据库中启用代理平台集成，以生成向量嵌入并执行语义搜索。
充当虚拟 DBA，使用 HNSW 索引和表分区来优化数据库，以实现生产规模。

所有这些操作都是通过与 AI 智能体进行自然对话来完成的，无需手动编写任何 SQL 代码或打开外部数据库客户端！

如需了解详情，请参阅产品文档：