使用 Antigravity 建構及部署至 Google Cloud

1. 簡介

fca14bb9f4bb74f4.png

在本程式碼研究室中，您將瞭解如何使用 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 擅長規劃複雜系統，我們可以先定義高階架構，而不是立即編寫程式碼。

首先，請確認您位於代理程式管理員中。如果剛開啟「反重力」模式，可以點選中間的 Open Agent Manager 按鈕，或右上角也會顯示相同的 Open Agent Manager。

在 Agent Manager 中，您可以選擇開啟工作區，或直接使用 Playground，這是獨立的工作區，可快速製作原型和進行實驗。我們先從 Playground 開始。

按一下 + 按鈕，即可在 Playground 中發起新對話：

4e33c028a604a375.png

系統會顯示介面，讓您提供提示，如下所示：

fbf023e84f0eb3b2.png

按一下右上角的設定圖示 ⚙️，然後將 Review Policy 下方的 Artifact 設為 Asks for Review，並將 Terminal Command Auto Execution 下方的 Terminal 設為 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 Bucket、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 或類似名稱的殼層指令碼檔案，自動建立資源。可處理：

  1. 啟用 API (run、pubsub、bigquery、storage)。
  2. 建立 Google Cloud Storage bucket (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 bucket。按一下 Accept 繼續操作。

如要自行執行進一步測試，可以試著將範例檔案上傳至 Cloud Storage bucket：

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」>「Buckets」。
  2. 找出名為 [PROJECT_ID]-doc-uploads 的 bucket。
  3. 按一下 bucket 名稱即可瀏覽檔案。
  4. 確認：您應該會看到上傳的檔案 (例如 test.txt)。

Pub/Sub

目標：確認主題存在，且已訂閱推送通知。

  1. 依序前往「Pub/Sub」>「主題」。
  2. 找到 doc-processing-topic。
  3. 按一下主題 ID。
  4. 向下捲動至「訂閱項目」分頁標籤。
  5. 驗證：確認「doc-processing-sub」列於清單中，且傳送類型為「Push」。

Cloud Run

目標：檢查服務狀態和記錄。

  1. 前往 Cloud Run。
  2. 按一下「doc-processor」服務。
  3. 驗證：
  4. 健康狀態：綠色勾號表示服務已啟用。
  5. 記錄：按一下「記錄」分頁標籤。尋找「Processing file: gs://...」和「Successfully processed...」等項目。

BigQuery

目標：驗證資料是否確實已儲存。

  1. 前往「BigQuery」>「SQL 工作區」。
  2. 在「Explorer」窗格中，依序展開「專案」>「pipeline_data 資料集」。
  3. 點選「processed_docs」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 應用程式會建立網路伺服器，接收 Pub/Sub 推送訊息、從 GCS 下載檔案、「處理」檔案 (模擬 OCR)，並將中繼資料串流至 BigQuery。
  3. Dockerfile：定義如何將應用程式封裝至容器映像檔。
  4. requirements.txt：列出 Python 依附元件。

您也可能會看到測試和驗證所需的其他指令碼和文字檔。

此時，您可能也想從 Playground 移至專屬工作區/資料夾。如要這麼做，請按一下右上角的相關按鈕：

278de21c89e5c726.png

選擇資料夾後，所有程式碼都會移至該資料夾，並以該資料夾和對話記錄建立新的工作區。

7. 擴充應用程式

現在您已擁有可運作的基本應用程式，可以繼續疊代及擴充應用程式。以下提供幾個點子。

新增前端

建構簡單的網頁介面，以便查看處理過的文件。

請嘗試使用下列提示：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/ML 整合

請改用 Gemini 模型擷取、分類及翻譯，而非模擬 OCR 處理程序。

  1. 取代虛擬 OCR 邏輯。將圖片/PDF 傳送給 Gemini，即可擷取實際文字和資料。分析擷取的文字，將文件分類 (例如應付憑據、合約、履歷表)，或擷取實體 (例如日期、姓名、地點)。
  2. 系統會自動偵測文件語言，並先翻譯成英文再儲存。你也可以使用其他語言。

提升儲存空間和數據分析功能

您可以在 bucket 中設定生命週期規則，將舊檔案移至「Coldline」或「Archive」儲存空間，以節省費用。

穩定性與安全性

您可以採取下列措施，讓應用程式更穩定可靠且安全：

  1. 無效信件佇列 (DLQ)：更新 Pub/Sub 訂閱項目，處理失敗情況。如果 Cloud Run 服務無法處理檔案 5 次，請將訊息傳送至另一個「Dead Letter」主題/bucket，供人工檢查。
  2. Secret Manager：如果應用程式需要 API 金鑰或機密設定，請將這些資訊儲存在 Secret Manager 中，並從 Cloud Run 安全地存取，而非將字串硬式編碼。
  3. Eventarc：從直接使用 Pub/Sub 升級至 Eventarc，即可享有更彈性的事件轉送功能，根據複雜的稽核記錄或其他 GCP 服務事件觸發動作。

當然，你可以提出自己的想法，並使用 Antigravity 協助實作！

8. 結語

您已使用 Google Antigravity，在幾分鐘內成功建構可擴充的無伺服器 AI 輔助文件管道。您已學會如何：

  • 使用 AI 規劃架構。
  • 指示及管理 Antigravity，讓它從程式碼生成到部署及驗證，逐步生成應用程式。
  • 透過逐步解說驗證部署作業和驗證。

參考文件