使用 Antigravity 构建和部署到 Google Cloud

1. 简介

fca14bb9f4bb74f4.png

在此 Codelab 中，您将学习如何使用 Google Antigravity（在本文档的其余部分中简称为 Antigravity）设计、构建和部署无服务器应用到 Google Cloud。我们将构建一个无服务器且由事件驱动的文档流水线，该流水线可从 Google Cloud Storage (GCS) 提取文件，使用 Cloud Run 和 Gemini 处理这些文件，并将它们的元数据流式传输到 BigQuery。

学习内容

  • 如何使用 Antigravity 进行建筑规划和设计。
  • 使用 AI 代理生成基础架构即代码（shell 脚本）。
  • 构建并部署基于 Python 的 Cloud Run 服务。
  • 集成 Vertex AI 上的 Gemini，以进行多模态文档分析。
  • 使用 Antigravity 的 Walkthrough 制品验证端到端流水线。

所需条件

2. 应用概览

在开始使用 Antigravity 设计和实现应用之前，我们先来概述一下要构建的应用。

我们希望构建一个无服务器且由事件驱动的文档流水线，该流水线可从 Google Cloud Storage (GCS) 提取文件，使用 Cloud Run 和 Gemini 处理这些文件，并将它们的元数据流式传输到 BigQuery。

此应用的概要架构图可能如下所示：

3bd519cfab38258d.png

不必精确。Antigravity 可以帮助我们逐步了解架构细节。不过，最好先确定要构建什么内容。您提供的信息越详细，Antigravity 在架构和代码方面给出的结果就越好。

3. 规划架构

我们已准备好开始使用 Antigravity 规划架构细节！

Antigravity 擅长规划复杂系统。我们可以先定义高级别架构，而不是立即编写代码。

首先，确保您位于代理管理器中。如果您刚刚打开 Antigravity，可以点击中间的 Open Agent Manager 按钮，也可以在右上角看到相同的 Open Agent Manager。

在代理管理器中，您可以选择打开工作区，也可以直接使用 Playground，这是一个独立的用于快速原型设计和实验的工作区。我们先从 Playground 开始。

点击 + 按钮，在 Playground 中开始新的对话：

4e33c028a604a375.png

系统会显示一个界面，您可以在其中提供提示，如下所示：

fbf023e84f0eb3b2.png

点击右上角的“设置”图标 ⚙️，然后将 Artifact 下的 Review Policy 和 Terminal 下的 Terminal Command Auto Execution 设置为 Request Review。这样可确保在每个步骤中，您都能在代理执行之前查看并批准方案。

提示

现在，我们已准备好向 Antigravity 提供第一个提示。

首先，请确保 Antigravity 处于 Planning 模式，对于模型，我们选择 Gemini Pro (High) 模型（但您可以随意尝试其他模型）。

输入以下提示，然后点击提交按钮：

I want to build a serverless event-driven document processing pipeline on Google Cloud.
Architecture:
- Ingestion: Users upload files to a Cloud Storage bucket.
- Trigger: File uploads trigger a Pub/Sub message.
- Processor: A Python-based Cloud Run service receives the message, processes the file (simulated OCR), and extracts metadata.
- Storage: Stream the metadata (filename, date, tags, word_count) into a BigQuery dataset.

任务列表和实施计划

Antigravity 会分析您的请求，并生成任务列表和实施方案。

此计划概述了：

  • 基础设施：GCS 存储分区、Pub/Sub 主题、BigQuery 数据集。
  • 处理器：Python/Flask 应用、Dockerfile、要求。
  • 集成：GCS 通知 → Pub/Sub → Cloud Run。

您应该会看到类似以下所示的内容：

ada19341c490a570.png

点击 Task 行旁边的 Open 按钮。这应该会显示 Antigravity 创建的一组任务。代理会逐一检查这些文件：

19675c55a71b373.png

下一步是查看实施方案，并向代理授予继续操作的权限。

点击相应实施计划即可查看其详细信息。请仔细阅读。您可以借此机会针对实施情况提供反馈。您可以点击实施计划的任何部分并添加评论。添加一些注释后，请务必提交您希望看到的任何更改以供审核，尤其是在命名、Google Cloud 项目 ID、区域等方面。

一切正常后，点击 Proceed 按钮，授予代理商权限以继续执行实施方案。

4. 生成应用

方案获得批准后，Antigravity 会开始生成应用所需的文件，从配置脚本到应用代码。

Antigravity 将创建一个文件夹，并开始创建项目所需的文件。在我们的示例运行中，我们看到了以下内容：

4d98413e3bd17148.png

系统会生成一个 setup.sh 或类似名称的 shell 脚本文件，用于自动创建资源。它处理：

  1. 启用 API（run、pubsub、bigquery、storage）。
  2. 创建 Google Cloud Storage 存储分区 (doc-ingestion-{project-id})。
  3. 创建 BigQuery 数据集和表 (pipeline_data.processed_docs)。
  4. 配置 Pub/Sub 主题和通知。

代理应生成一个 Python 应用 (main.py)，用于监听 Pub/Sub 推送消息。它使用模拟的 OCR 逻辑，生成随机字数和标记，并将其持久保存到 BigQuery。

生成此设置脚本后，Antigravity 应该会提示您代表您执行该脚本。示例界面如下所示：

44395ab66413a64f.png

您可以根据需要点击 Accept。

配置脚本将创建资源并验证这些资源是否已创建。如果检查成功，系统将继续构建容器，并将其作为服务（在 main.py 中）部署到 Cloud Run。输出示例如下所示：

e0e625e218e7fe46.png

在部署服务时，它还会设置 Pub/Sub 订阅和使此流水线正常运行所需的其他粘合代码。整个过程应该只需要几分钟的时间。

在此期间，您可以切换到 Inbox（从左上角），查看等待您输入的 Pending 任务：

ddd2f49d02fad987.png

这样可以确保您在代理寻求反馈时批准任务。

5. 验证申请

流水线部署完毕后，Antigravity 会继续验证应用是否正常运行。Antigravity 会通过任务列表中的验证步骤自动执行此操作。示例界面如下所示：

b8758b77880cc4d9.png

它会创建一个测试制品 (test.txt)，并希望将其上传到 Google Cloud Storage 存储分区。点击 Accept 继续。

如果您想自行运行更多测试，可以参考 Antigravity 的验证步骤，其中使用了 gsutil 实用程序将示例文件上传到 Cloud Storage 存储分区。示例命令如下所示：

gsutil cp <some-test-doc>.txt gs://<bucket-name>/

在 BigQuery 中查看结果

在验证过程中，系统还会检查数据是否已持久保留在 BigQuery 中。

c0f08fedf671e9bd.png

请注意它用于检查文档的 SQL 查询。

验证完成后，您应该会看到任务列表已完成：

b55ad48a87f95eca.png

可选：手动验证

即使 Antigravity 已经验证了应用，您也可以按照以下步骤在 Google Cloud 控制台中手动检查是否已创建所有资源。

Cloud Storage

目标：验证存储分区是否存在并检查上传的文件。

  1. 前往 Cloud Storage > 存储分区。
  2. 找到名为 [PROJECT_ID]-doc-uploads 的存储分区。
  3. 点击相应存储分区名称即可浏览文件。
  4. 验证：您应该会看到已上传的文件（例如，test.txt）。

Pub/Sub

目标：确认主题存在且具有推送订阅。

  1. 前往 Pub/Sub > 主题。
  2. 找到 doc-processing-topic。
  3. 点击主题 ID。
  4. 向下滚动到订阅标签页。
  5. 验证：确保 doc-processing-sub 列出的传送类型为“推送”。

Cloud Run

目标：检查服务状态和日志。

  1. 前往 Cloud Run。
  2. 点击服务 doc-processor。
  3. 验证：
  4. 健康状况：绿色对勾标记表示服务处于活跃状态。
  5. 日志：点击“日志”标签页。查找“正在处理文件：gs://...”和“已成功处理...”之类的条目。

BigQuery

目标：验证数据是否已实际存储。

  1. 前往 BigQuery > SQL 工作区。
  2. 在“探索器”窗格中，展开您的项目 > pipeline_data 数据集。
  3. 点击 processed_docs 表。
  4. 点击预览标签页。
  5. 验证：您应该会看到包含 filename、upload_date、tags 和 word_count 的行。

演示

最后一步，Antigravity 会生成一个演练制品。此制品总结了以下内容：

  • 已进行更改。
  • 运行验证命令。
  • 实际结果（显示 Gemini 提取的元数据的查询输出）。

您可以点击 Open 查看。输出示例如下所示：

47ecf561d0252924.png

6. 探索应用

至此，您已完成基本应用的配置并使其正常运行。在深入了解如何进一步扩展此应用之前，请先花点时间探索一下代码。您可以使用右上角的 Open Editor 按钮切换到编辑器。

下面简要介绍了您可能会看到的文件：

  1. setup.sh：用于预配所有 Google Cloud 资源并启用所需 API 的主脚本。
  2. main.py：流水线的主要入口点。此 Python 应用会创建一个 Web 服务器，该服务器接收 Pub/Sub 推送消息，从 GCS 下载文件，对其进行“处理”（模拟 OCR），并将元数据流式传输到 BigQuery。
  3. Dockerfile：定义如何将应用打包到容器映像中。
  4. requirements.txt：列出 Python 依赖项。

您可能还会看到测试和验证所需的其他脚本和文本文件。

此时，您可能还需要从 Playground 迁移到专用工作区/文件夹。为此，您可以点击右上角的相关按钮：

278de21c89e5c726.png

选择文件夹后，所有代码都将移至该文件夹，并创建一个包含该文件夹和对话历史记录的新工作区。

7. 扩展应用

现在，您已经有了一个正常运行的基本应用，可以继续迭代和扩展该应用。以下是一些建议。

添加前端

构建一个简单的 Web 界面来查看处理后的文档。

不妨试试以下提示：Create a simple Streamlit or Flask web application that connects to BigQuery. It should display a table of the processed documents (filename, upload_date, tags, word_count) and allow me to filter the results by tag

与真实的 AI/机器学习集成

使用 Gemini 模型进行提取、分类和翻译，而不是模拟 OCR 处理。

  1. 替换了虚拟 OCR 逻辑。将图片/PDF 发送给 Gemini 以提取实际文本和数据。分析提取的文本，以对文档类型（账单、合同、简历）进行分类或提取实体（日期、名称、地点）。
  2. 自动检测文档的语言并将其翻译为英语，然后再存储。您也可以使用任何其他语言。

增强存储和分析功能

您可以在存储分区中配置生命周期规则，将旧文件移至“Coldline”或“Archive”存储空间，以节省费用。

稳健性和安全性

您可以提高应用的稳健性和安全性，例如：

  1. 死信队列 (DLQ)：更新 Pub/Sub 订阅以处理失败情况。如果 Cloud Run 服务处理文件失败 5 次，则将消息发送到单独的“死信”主题/存储分区以供人工检查。
  2. Secret Manager：如果您的应用需要 API 密钥或敏感配置，请将其存储在 Secret Manager 中，并从 Cloud Run 安全地访问它们，而不是对字符串进行硬编码。
  3. Eventarc：从直接 Pub/Sub 升级到 Eventarc，以实现更灵活的事件路由，从而根据复杂的审核日志或其他 GCP 服务事件触发函数。

当然，您也可以提出自己的想法，并使用 Antigravity 帮助您实现这些想法！

8. 总结

您已成功使用 Google Antigravity 在几分钟内构建了一个可扩缩的无服务器 AI 赋能型文档流水线。您已学习了：

  • 利用 AI 规划架构。
  • 指导并管理 Antigravity，使其完成从代码生成到部署和验证的应用生成工作。
  • 通过演练验证部署和验证。

参考文档