使用 Antigravity 构建和部署到 Google Cloud

1. 简介

fca14bb9f4bb74f4.png

在此 Codelab 中，您将学习如何使用 Google 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。

首先，为应用创建一个文件夹，例如 document-pipeline，然后在智能体管理器中将其添加为工作区：

6df2bebcee5608b7.png

在智能体管理器中，在 document-pipeline 工作区中开始对话。确保还启用了“规划”模式：

b7d18b5ec36004cf.png

点击右上角的设置图标 ⚙️，然后在 Artifact 下将 Review Policy 设置为 Asks for Review，在 Terminal 下将 Terminal Command Auto Execution 设置为 Request Review。这样可确保您在每个步骤中都能审核并批准计划，然后智能体才会执行。

提示

现在，我们可以向 Antigravity 提供第一个提示了。

首先，仔细检查 Antigravity 是否处于 Plan 模式，对于模型，我们选择 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。

预配脚本将创建资源并验证是否已创建这些资源。检查成功后，它将继续构建容器，并将其作为 Cloud Run 中的服务（在 main.py 中）进行部署。以下是示例输出：

e0e625e218e7fe46.png

在部署服务时，它还会设置 Pub/Sub 订阅和其他使此流水线正常运行所需的粘合代码。所有这些操作都应需要几分钟时间。

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

ddd2f49d02fad987.png

当智能体寻求您的反馈时，这是一种确保您批准任务的好方法。

5. 验证应用

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

b8758b77880cc4d9.png

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

如果您想自行运行更多测试，可以尝试将示例文件上传到 Cloud Storage 存储分区：

gcloud storage cp <some-test-doc>.txt gs://doc-ingestion-{project-id}/

在 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. 日志：点击“日志”标签页。查找类似“Processing file: gs://...”和“Successfully processed...”的条目。

BigQuery

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

  1. 前往 BigQuery > SQL 工作区 。
  2. 在探索器窗格中，展开您的项目 > pipeline_data 数据集 。
  3. 点击 processed_docs 表。
  4. 点击预览 标签页。
  5. 验证：您应该会看到包含文件名、上传日期、标记和字数的行。

演示

最后一步，Antigravity 会生成一个 Walkthrough 制品。此制品总结了：

  • 所做的更改。
  • 运行的验证命令。
  • 实际结果（显示 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 依赖项。

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

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 从代码生成到部署和验证生成应用的过程中，对其进行指导和管理。
  • 使用 Walkthrough 验证部署和验证。

参考文档