Xây dựng và triển khai lên Google Cloud bằng Antigravity

1. Giới thiệu

fca14bb9f4bb74f4.png

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách sử dụng Google Antigravity để thiết kế, xây dựng và triển khai một ứng dụng không máy chủ lên Google Cloud. Chúng ta sẽ xây dựng một quy trình xử lý tài liệu dựa trên sự kiện và không máy chủ, quy trình này sẽ nhập tệp từ Google Cloud Storage (GCS), xử lý tệp bằng Cloud Run và Gemini, đồng thời truyền siêu dữ liệu của tệp vào BigQuery.

Kiến thức bạn sẽ học được

  • Cách sử dụng Antigravity để lập kế hoạch và thiết kế kiến trúc.
  • Tạo cơ sở hạ tầng dưới dạng mã (tập lệnh shell) bằng một tác nhân AI.
  • Tạo và triển khai một dịch vụ Cloud Run dựa trên Python.
  • Tích hợp Gemini trên Vertex AI để phân tích tài liệu đa phương thức.
  • Xác minh quy trình từ đầu đến cuối bằng cách sử dụng cấu phần phần mềm Hướng dẫn của Antigravity.

Bạn cần có

  • Đã cài đặt Google Antigravity.
  • Một Dự án trên Google Cloud đã bật tính năng thanh toán.
  • Đã cài đặt và xác thực gcloud CLI.

2. Tổng quan về ứng dụng

Trước khi bắt tay vào thiết kế và triển khai ứng dụng bằng Antigravity, trước tiên, hãy phác thảo ứng dụng mà chúng ta muốn tự xây dựng.

Chúng tôi muốn xây dựng một quy trình xử lý tài liệu dựa trên sự kiện và không cần máy chủ, quy trình này sẽ nhập tệp từ Google Cloud Storage (GCS), xử lý tệp bằng Cloud Run và Gemini, đồng thời truyền siêu dữ liệu của tệp vào BigQuery.

Sơ đồ kiến trúc cấp cao cho ứng dụng này có thể trông như sau:

3bd519cfab38258d.png

Bạn không cần phải cung cấp thông tin chính xác. Antigravity có thể giúp chúng ta tìm ra thông tin chi tiết về cấu trúc trong quá trình thực hiện. Tuy nhiên, bạn nên có ý tưởng về những gì mình muốn xây dựng. Bạn càng cung cấp nhiều thông tin chi tiết, thì bạn sẽ nhận được kết quả càng tốt từ Antigravity về mặt cấu trúc và mã.

3. Lập kế hoạch cho cấu trúc

Chúng ta đã sẵn sàng bắt đầu lên kế hoạch chi tiết về kiến trúc bằng Antigravity!

Antigravity có khả năng lập kế hoạch cho các hệ thống phức tạp. Thay vì viết mã ngay lập tức, chúng ta có thể bắt đầu bằng cách xác định cấu trúc cấp cao và sử dụng một trong các tính năng để giúp Antigravity đánh giá yêu cầu của chúng ta, đặt câu hỏi nối tiếp cho chúng ta rồi tiến hành lập kế hoạch và triển khai.

Giả sử bạn đã chạy Antigravity, chúng ta sẽ tạo một Dự án mới cho lớp học lập trình này.

Nhấp vào biểu tượng dự án mới bên cạnh phòng thí nghiệm Projects rồi nhấp vào New Project như minh hoạ dưới đây:

949cd615a1ce8dc3.png

Thao tác này sẽ mở ra lựa chọn Add Folder như minh hoạ dưới đây:

ee8ff88b71c10e9f.png

Nhấp vào nút Add Folder (Thêm thư mục) để thêm một thư mục vào dự án. Trên máy của mình, tôi đã tạo một thư mục google-cloud-serverless-app và thêm thư mục đó vào dự án này.

Thao tác này sẽ mở một cuộc trò chuyện trong không gian làm việc google-cloud-serverless-app.

Nhấp vào biểu tượng cài đặt chính ⚙️ ở dưới cùng bên trái màn hình rồi chuyển đến phần Cài đặt dành riêng cho dự án. Đặt Agent Settings / Security Present thành Default và Agent Behaviour / Artifact Review Policy thành Always Ask, như minh hoạ dưới đây:

b28e175be64f4390.png

Điều này sẽ đảm bảo rằng ở mỗi bước, bạn sẽ xem xét và phê duyệt kế hoạch trước khi nhân viên hỗ trợ thực hiện.

Câu lệnh

Giờ đây, chúng ta đã sẵn sàng đưa ra câu lệnh đầu tiên cho Antigravity. Chúng ta sẽ sử dụng lệnh dấu gạch chéo /grill-me để đánh giá yêu cầu của mình.

Nhập /grill-me rồi nhập câu lệnh sau và nhấp vào nút gửi:

/grill-me 

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.

Lệnh /grill-me sẽ đặt một số câu hỏi nối tiếp mà bạn có thể cố gắng trả lời theo những gì bạn biết. Tính năng này cũng đề xuất Câu trả lời được đề xuất và bạn có thể chọn câu trả lời đó nếu muốn.

Dưới đây là một ví dụ về lệnh /grill-me mà tôi đã chạy:

How would you provision and manage the Google Cloud infrastructure resources (Cloud Storage buckets, Pub/Sub topics, BigQuery datasets, Cloud Run service)?
gcloud CLI Setup Script - Shell scripts running gcloud CLI commands to create resources step-by-step

How should the Cloud Storage upload events trigger and reach your Python Cloud Run service?
(Recommended) Native Cloud Storage Pub/Sub Notifications + Pub/Sub Push subscription to Cloud Run (direct, lightweight, standard event-driven approach)

Which Python web framework would you prefer for the Cloud Run processing service?
Flask (with Gunicorn) - Standard, lightweight, and very common for simple Cloud Run services

How should the OCR and metadata extraction logic be implemented in the Cloud Run service?
(Recommended) Full local simulation - If it's a .txt file, read the contents, count words, and extract tags. For other files, generate mock OCR metadata and simulated word count. No external API calls.

Which BigQuery insertion method should the Cloud Run service use to store metadata?
(Recommended) BigQuery table.insert_rows() (Legacy Streaming API) - Extremely simple to code, clean error handling, perfect for simulation and low-to-medium volumes.

How should security/authentication be configured for the Cloud Run service?
Unauthenticated Cloud Run - Allow public requests to the Cloud Run service URL (simpler setup, but insecure for production).


What schema would you like to define for the BigQuery metadata table?
(Recommended) Extended Schema - Include filename, bucket, size, content_type, word_count, tags (as a REPEATED STRING array), ocr_text_preview, and process_timestamp.

How should the Cloud Run service handle processing failures (e.g., file not found, BigQuery write error)?
(Recommended) Fail-Fast with Retry - Log error to standard output (Cloud Logging) and return HTTP 500 to Pub/Sub, so that Pub/Sub automatically retries the message delivery.

What testing tools should we generate to verify the pipeline's functionality?
(Recommended) Both - Include a local test script (sending mock Pub/Sub POST requests to the local Flask server) and a Cloud-integrated test script (uploading a real file to GCS and verifying BigQuery).

Xin lưu ý rằng tôi đã yêu cầu Antigravity thực hiện:

  • Một tập lệnh gcloud CLI đơn giản để cung cấp tài nguyên
  • Thông báo Pub/Sub của Cloud Storage gốc + gói thuê bao đẩy Pub/Sub đến Cloud Run
  • Sử dụng Flask (với Gunicorn) cho khung
  • Chỉ cần sử dụng mô phỏng cục bộ với một tệp văn bản cho dữ liệu thay vì dữ liệu OCR trực tiếp
  • Sử dụng BigQuery table.insert_rows() để chèn các hàng vào BigQuery
  • Triển khai Cloud Run chưa được xác thực

và các lựa chọn được đề xuất khác.

Kế hoạch triển khai và danh sách việc cần làm

Antigravity sẽ bắt đầu hoạt động và tạo ra một Kế hoạch triển khai. Thao tác này sẽ đưa yêu cầu lên để bạn xem xét bằng cách gửi cho bạn một thông báo tương tự như thông báo bên dưới:

2bf129fc14fa019e.png

Bạn có thể nhấp vào nút bật/tắt Auxiliary Pane (Ngăn phụ) ở cửa sổ trên cùng bên phải và xem các Artifact (Hiện vật) đã tạo. Tại thời điểm này, hiện vật chỉ là Implementation Plan (Kế hoạch triển khai).

fc8d1f0f54d3e723.png

Kế hoạch này nêu rõ:

  • Cơ sở hạ tầng: Nhóm GCS, Chủ đề Pub/Sub, Tập dữ liệu BigQuery.
  • Bộ xử lý: Ứng dụng Python/Flask, Dockerfile, Yêu cầu.
  • Tích hợp: Thông báo GCS → Pub/Sub → Cloud Run.

Bạn sẽ thấy nội dung tương tự như sau. Dưới đây là danh sách một phần của kế hoạch triển khai trên máy của chúng tôi:

Event-Driven Document Processing Pipeline Implementation Plan
This implementation plan describes the components and setup scripts required to build a serverless event-driven document processing pipeline on Google Cloud.

User Review Required

Please review the proposed architecture, components, and default configuration. If you agree, please approve the plan so we can proceed with creating the files and implementation.

IMPORTANT

Security Notice: As requested, the Cloud Run service is configured to allow unauthenticated invocations (--allow-unauthenticated) for simpler testing and development.

Error Handling: The service returns an HTTP 500 error code for failures to trigger Pub/Sub retries.

GCP Configuration: The provisioning scripts will use standard environment variables (e.g., GCP_PROJECT, GCP_REGION) that default to the active configuration of your local gcloud CLI.

Proposed Components and Files

The project will be organized as follows:
google-cloud-serverless-app/
├── src/
│   ├── __init__.py
│   ├── app.py              # Flask app entrypoint and routes
│   ├── processor.py        # Simulated OCR and metadata extraction engine
│   ├── gcs_helper.py       # Helper functions to read files from Cloud Storage
│   └── bq_helper.py        # Helper functions to write metadata to BigQuery
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker configuration for Cloud Run
├── deploy.sh               # gcloud CLI provisioning and deployment script
├── test_local.sh           # Script to test the Flask app locally with mock Pub/Sub events
├── test_cloud.sh           # Script to upload a real file to GCS and query BigQuery
└── README.md               # Setup and execution guide

Hãy đọc kỹ. Đây là cơ hội để bạn đưa ra ý kiến phản hồi về việc triển khai. Bạn có thể nhấp vào bất kỳ phần nào trong kế hoạch triển khai và thêm nhận xét. Sau khi thêm một số nhận xét, hãy nhớ gửi mọi thay đổi mà bạn muốn xem xét, đặc biệt là về việc đặt tên, mã dự án Google Cloud, khu vực, v.v.

Sau khi kiểm tra và thấy mọi thứ đều ổn, hãy nhấp vào nút Proceed để cấp cho nhân viên hỗ trợ quyền tiếp tục thực hiện kế hoạch triển khai.

Bây giờ, ứng dụng sẽ tiếp tục tạo một cấu phần phần mềm khác là Kế hoạch công việc. Cấu phần phần mềm này chứa một nhóm các công việc do Antigravity tạo. Trợ lý sẽ xem xét từng bước một và thực hiện các bước đó. Dưới đây là danh sách việc cần làm mẫu:

7d17f032d4b6bd04.png

4. Tạo ứng dụng

Sau khi kế hoạch được phê duyệt, Antigravity sẽ bắt đầu tạo các tệp cần thiết cho ứng dụng, từ tập lệnh cung cấp đến mã xử lý ứng dụng.

Antigravity sẽ tạo một thư mục và bắt đầu tạo các tệp cần thiết cho dự án. Nếu kiểm tra các cấu phần phần mềm, bạn sẽ thấy một số tệp (mã nguồn, tệp kịch bản, v.v.) được tạo.

d142b671ba315ba5.png

Sau khi hoàn tất công việc, nó sẽ đề cập đến việc này và tạo một tài liệu Hướng dẫn mà bạn có thể xem. Trong đó, bước tiếp theo cho người dùng được đề cập, một mẫu được đưa ra dưới đây:

  • Triển khai quy trình: Đảm bảo bạn đã đăng nhập vào GCP CLI và đặt dự án mục tiêu, sau đó chạy: ./ deploy.sh
  • Chạy kiểm thử toàn diện: Thực thi kịch bản kiểm tra tích hợp đám mây để xác minh rằng một tệp được tải lên sẽ kích hoạt quy trình xử lý Cloud Run và truyền siêu dữ liệu đến BigQuery:./test_cloud.sh
  • Dọn dẹp: Sau khi hoàn tất kiểm thử, hãy tham khảo các lệnh dọn dẹp README.md để xoá các tài nguyên đã tạo và tránh bị tính phí.

Bạn sẽ thấy một tệp tập lệnh shell deploy.sh hoặc một tệp có tên tương tự được tạo, giúp tự động hoá quá trình tạo tài nguyên. Thư viện này xử lý:

  1. Bật các API (run, pubsub, bigquery, storage).
  2. Tạo bộ chứa Google Cloud Storage (document-processing-ingest-{project-id}).
  3. Tạo tập dữ liệu và bảng BigQuery (document_processing.processed_metadata).
  4. Định cấu hình chủ đề và thông báo Pub/Sub.

5. Triển khai ứng dụng

Hãy triển khai ứng dụng như đã đề cập thông qua lệnh ./ deploy.sh. Chúng ta có thể yêu cầu Antigravity chạy lệnh này cho chúng ta, nhưng trước khi làm như vậy, hãy đảm bảo rằng gcloud CLI đã có và được định cấu hình cho Dự án trên Google Cloud.

Chúng ta có thể đưa ra câu lệnh cho Antigravity "Run the deploy.sh cho tôi). Thao tác này sẽ nhắc bạn cấp quyền. Hãy tiếp tục và đưa ra yêu cầu đó.

9e5c1c7141b3fc06.png

Thao tác này sẽ bắt đầu quy trình dưới dạng một tác vụ trong nền, như được giải thích trong thông báo bên dưới:

Tôi đã bắt đầu quy trình triển khai bằng cách chạy ./deploy.sh ở chế độ nền. Tôi sẽ theo dõi nhật ký thực thi và thông báo cho bạn ngay khi quá trình triển khai hoàn tất!

6. Xác minh ứng dụng

Sau khi triển khai quy trình, Antigravity sẽ tiến hành xác minh rằng ứng dụng thực sự hoạt động. Hệ thống sẽ hỏi chúng ta xem có thể chạy tệp test_cloud.sh hay không. Chúng ta có thể tiếp tục và cấp quyền cho ứng dụng.

2bc8c959c9f80d30.png

Cuối cùng, thông tin này cho chúng ta biết những điều sau:

I have successfully run both ./deploy.sh and ./test_cloud.sh.
The pipeline is fully deployed to your GCP project PROJECT_ID and working end-to-end. 

Please refer to the walkthrough.md for full verification details and the query output from BigQuery showing the successfully processed document metadata.

Chúng ta có thể mở thành phần Walkthrough (Hướng dẫn) để xem kết quả:

Cloud Verification Results

The deployment and end-to-end cloud integration test (./test_cloud.sh) succeeded perfectly!

Resources Created:

GCS Bucket: gs://document-processing-ingest-gcp-experiments-349209

Pub/Sub Topic: document-uploads-topic

Pub/Sub Subscription: document-uploads-sub (pushing to Cloud Run)

Cloud Run Service: document-processor (URL: https://document-processor-ido3ocn3pq-uc.a.run.app)

BigQuery Dataset: document_processing

BigQuery Table: processed_metadata

Integration Test Run: A test file cloud_test_sample.txt was uploaded to the bucket. The pipeline processed the file and streamed the metadata record into BigQuery:

🔍 Querying BigQuery to verify metadata insertion...
<BIQUERY DATA HERE>

The pipeline successfully detected the hashtags #gcp and #serverless as tags, correctly counted the 47 words, generated the OCR preview, and wrote the entry to BigQuery under the schema.

Không bắt buộc: Xác minh thủ công

Mặc dù Antigravity đã xác minh ứng dụng, nhưng bạn cũng có thể kiểm tra theo cách thủ công trong bảng điều khiển Google Cloud để đảm bảo rằng tất cả tài nguyên đều được tạo (nếu muốn) bằng cách làm theo các bước sau.

Cloud Storage

Mục tiêu: Xác minh rằng vùng chứa tồn tại và kiểm tra các tệp đã tải lên.

  1. Chuyển đến phần Cloud Storage > Bộ chứa.
  2. Tìm vùng chứa có tên document-processing-ingest-{project-id}.
  3. Nhấp vào tên nhóm để duyệt xem các tệp.
  4. Xác minh: Bạn sẽ thấy các tệp đã tải lên (ví dụ: cloud_test_sample.txt).

Pub/Sub

Mục tiêu: Xác nhận rằng chủ đề tồn tại và có một gói thuê bao thông báo đẩy.

  1. Chuyển đến Pub/Sub > Topics (Pub/Sub > Chủ đề).
  2. Tìm document-uploads-topic.
  3. Nhấp vào mã nhận dạng chủ đề.
  4. Di chuyển xuống thẻ Kênh đăng ký.
  5. Xác minh: Đảm bảo doc-uploads-sub được liệt kê với loại phân phối "Push".

Cloud Run

Mục tiêu: Kiểm tra trạng thái dịch vụ và nhật ký.

  1. Chuyển đến Cloud Run.
  2. Nhấp vào dịch vụ document-processor.
  3. Xác minh:
  4. Trạng thái: Dấu kiểm màu xanh lục cho biết dịch vụ đang hoạt động.
  5. Nhật ký: Nhấp vào thẻ Nhật ký. Tìm các mục như "Processing file: gs://..." (Đang xử lý tệp: gs://...) và "Successfully inserted..." (Đã chèn thành công...).

BigQuery

Mục tiêu: Xác thực rằng dữ liệu thực sự được lưu trữ.

  1. Chuyển đến BigQuery > Không gian làm việc SQL.
  2. Trong ngăn Explorer (Trình khám phá), hãy mở rộng project > document_processing dataset (dự án > tập dữ liệu xử lý tài liệu).
  3. Nhấp vào bảng processed_metadata.
  4. Nhấp vào thẻ Truy vấn và truy xuất tất cả các hàng trong bảng thông qua câu lệnh SELECT *.
  5. Xác minh: Bạn sẽ thấy các hàng chứa filename, process_timestamp, tags và word_count.

7. Khám phá ứng dụng

Đến đây, bạn đã cung cấp và chạy ứng dụng cơ bản. Trước khi đi sâu vào việc mở rộng ứng dụng này, hãy dành chút thời gian để khám phá mã. Bạn có thể xem Artifacts (Hiện vật) và Artifacts sẽ cho bạn thấy các tệp mã được tạo.

Sau đây là nội dung tóm tắt nhanh về những tệp bạn có thể thấy:

  1. deploy.sh: Tập lệnh chính cung cấp tất cả tài nguyên Google Cloud và bật các API bắt buộc.
  2. appy.py: Điểm truy cập chính của quy trình. Ứng dụng Python này tạo một máy chủ web nhận thông báo đẩy Pub/Sub, tải tệp xuống từ GCS, "xử lý" (mô phỏng Nhận dạng ký tự quang học (OCR)) tệp đó và truyền trực tuyến siêu dữ liệu đến BigQuery.
  3. Dockerfile: Xác định cách đóng gói ứng dụng vào một hình ảnh vùng chứa.
  4. requirements.txt: Liệt kê các phần phụ thuộc của Python.

Bạn cũng có thể thấy các tập lệnh và tệp văn bản khác cần thiết cho việc kiểm thử và xác minh.

8. Mở rộng ứng dụng

Giờ đây, khi đã có một ứng dụng cơ bản hoạt động, bạn có thể tiếp tục lặp lại và mở rộng ứng dụng. Sau đây là một số ý tưởng.

Thêm giao diện người dùng

Tạo một giao diện web đơn giản để xem các tài liệu đã xử lý.

Hãy thử câu lệnh sau: 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

Tích hợp với AI/ML thực

Thay vì xử lý OCR mô phỏng, hãy dùng các mô hình Gemini để trích xuất, phân loại và dịch.

  1. Thay thế logic OCR giả. Gửi hình ảnh/tệp PDF cho Gemini để trích xuất văn bản và dữ liệu thực tế. Phân tích văn bản đã trích xuất để phân loại loại tài liệu (hoá đơn, hợp đồng, sơ yếu lý lịch) hoặc trích xuất các thực thể (ngày, tên, vị trí).
  2. Tự động phát hiện ngôn ngữ của tài liệu và dịch sang tiếng Anh trước khi lưu trữ. Bạn cũng có thể sử dụng bất kỳ ngôn ngữ nào khác.

Tăng cường bộ nhớ và hoạt động phân tích

Bạn có thể định cấu hình các quy tắc vòng đời trên vùng lưu trữ để di chuyển các tệp cũ sang bộ nhớ "Coldline" hoặc "Archive" để tiết kiệm chi phí.

Độ tin cậy và bảo mật

Bạn có thể tăng cường độ ổn định và tính bảo mật cho ứng dụng, chẳng hạn như:

  1. Hàng đợi thư không gửi được (DLQ): Cập nhật gói thuê bao Pub/Sub để xử lý các lỗi. Nếu dịch vụ Cloud Run không xử lý được một tệp 5 lần, hãy gửi thông báo đến một chủ đề/thùng chứa "Thư không gửi được" riêng để con người kiểm tra.
  2. Secret Manager: Nếu ứng dụng của bạn cần khoá API hoặc cấu hình nhạy cảm, hãy lưu trữ các khoá API đó trong Secret Manager và truy cập một cách an toàn từ Cloud Run thay vì mã hoá cứng các chuỗi.
  3. Eventarc: Nâng cấp từ Pub/Sub trực tiếp lên Eventarc để định tuyến sự kiện linh hoạt hơn, cho phép bạn kích hoạt dựa trên nhật ký kiểm tra phức tạp hoặc các sự kiện dịch vụ khác của GCP.

Tất nhiên, bạn có thể tự nghĩ ra ý tưởng và dùng Antigravity để giúp bạn triển khai ý tưởng đó!

9. Kết luận

Bạn đã tạo thành công một quy trình xử lý tài liệu có thể mở rộng, không cần máy chủ và dựa trên AI trong vài phút bằng Google Antigravity. Bạn đã tìm hiểu cách:

  • Lập kế hoạch kiến trúc bằng AI.
  • Hướng dẫn và quản lý Antigravity khi công cụ này hoạt động thông qua việc tạo ứng dụng từ quá trình tạo mã cho đến triển khai và xác thực.
  • Xác minh quá trình triển khai và xác thực bằng Hướng dẫn từng bước.

Tài liệu tham khảo