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

1. Giới thiệu

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 phi 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 phi máy chủ và dựa trên sự kiện, quy trình này sẽ tiếp nhận tệp từ Google Cloud Storage (GCS), xử lý các tệp đó bằng Cloud Run và Gemini, đồng thời truyền siêu dữ liệu của các 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.
• Xây dựng 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 xử lý hai đầu bằ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 đầu 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 ta muốn xây dựng một quy trình xử lý tài liệu phi máy chủ và dựa trên sự kiện, quy trình này sẽ tiếp nhận tệp từ Google Cloud Storage (GCS), xử lý các tệp đó bằng Cloud Run và Gemini, đồng thời truyền siêu dữ liệu của các 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:

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

3. Lập kế hoạch kiến trúc

Chúng ta đã sẵn sàng bắt đầu lập 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 kiến 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, hỏi chúng ta các câu hỏi nối tiếp rồi tiến hành lập kế hoạch và triển khai.

Giả sử bạn đã khởi 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 (Dự án), rồi nhấp vào New Project (Dự án mới) như minh hoạ bên dưới:

Thao tác này sẽ hiển thị tuỳ chọn Add Folder (Thêm thư mục) như minh hoạ bên dưới:

Nhấp vào nút Add Folder (Thêm thư mục) để thêm một thư mục vào dự án của bạn. Trên máy của tôi, 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 Preset (Cài đặt tác nhân/Cài đặt sẵn về bảo mật) thành Default (Mặc định) và Agent Behaviour / Artifact Review Policy (Hành vi của tác nhân/Chính sách xem xét cấu phần phần mềm) thành Always Ask (Luôn hỏi) như minh hoạ bên dưới:

Thao tác 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 tác nhân thực thi.

Câu lệnh

Giờ đây, chúng ta đã sẵn sàng cung cấp 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ẽ hỏi một số câu hỏi nối tiếp mà bạn có thể cố gắng trả lời theo hiểu biết của mình. Lệnh này cũng đề xuất Recommended Answers (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 mẫu chạy lệnh /grill-me của tôi:

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).

Lưu ý rằng tôi đã yêu cầu Antigravity chọ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 Pub/Sub Push đến Cloud Run
• Sử dụng Flask (với Gunicorn) cho khung
• Chỉ 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 bảng BigQuery.insert_rows() để chèn các hàng vào BigQuery
• Triển khai Cloud Run chưa 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 Implementation Plan (Kế hoạch triển khai). Công cụ này sẽ đưa kế hoạch đó 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:

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

Kế hoạch này phác thảo:

• Infrastructure (Cơ sở hạ tầng): Bộ chứa GCS, Chủ đề Pub/Sub, Tập dữ liệu BigQuery.
• Processor (Bộ xử lý): Ứng dụng Python/Flask, Dockerfile, Yêu cầu.
• Integration (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 của 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ề tên, mã dự án trên Google Cloud, khu vực, v.v.

Sau khi mọi thứ đều ổn, hãy cấp cho tác nhân quyền tiếp tục kế hoạch triển khai bằng cách nhấp vào nút Proceed (Tiến hành).

Công cụ này sẽ tiếp tục tạo một cấu phần phần mềm khác là Task Plan (Kế hoạch công việc), chứa một tập hợp các công việc do Antigravity tạo. Tác nhân sẽ lần lượt thực hiện từng công việc. Dưới đây là danh sách việc cần làm mẫu:

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 bạn kiểm tra Cấu phần phần mềm, bạn sẽ thấy một số tệp (mã nguồn, tệp tập lệnh, v.v.) đang được tạo.

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

• Deploy the Pipeline (Triển khai quy trình xử lý): Đả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ử hai đầu: Thực thi kịch bản kiểm tra tích hợp trên đám mây để xác minh rằng việc tải tệp lên sẽ kích hoạt quá trình xử lý Cloud Run và truyền siêu dữ liệu đến BigQuery:./test_cloud.sh
• Clean Up (Dọn dẹp): Sau khi kiểm thử xong, 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 phát sinh phí.

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

1. Bật 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ó mặt 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 for me" (Chạy 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à cấp quyền đó.

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

Tôi đã bắt đầu quá trình triển khai bằng cách chạy ./deploy.sh trong 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 xử lý, Antigravity sẽ tiến hành xác minh rằng ứng dụng thực sự hoạt động. Công cụ này 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 đó.

Cuối cùng, công cụ này sẽ 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ở cấu phần phần mềm 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 đã đượ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 bộ chứa tồn tại và kiểm tra các tệp đã tải lên.

1. Chuyển đến Cloud Storage > Buckets (Cloud Storage > Bộ chứa).
2. Tìm bộ chứa có tên document-processing-ingest-{project-id}.
3. Nhấp vào tên bộ chứa để duyệt 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ó gói thuê bao đẩy.

1. Chuyển đến Pub/Sub > Topics (Pub/Sub > Chủ đề).
2. Tìm document-uploads-topic.
3. Nhấp vào topic ID (mã chủ đề).
4. Di chuyển xuống thẻ Subscriptions (Gói thuê bao).
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 và nhật ký dịch vụ.

1. Chuyển đến Cloud Run.
2. Nhấp vào dịch vụ document-processor.
3. Xác minh:
4. Health (Tình trạng): Dấu kiểm màu xanh lục cho biết dịch vụ đang hoạt động.
5. Logs (Nhật ký): Nhấp vào thẻ Logs (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 > SQL Workspace (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 document_processing).
3. Nhấp vào bảng processed_metadata.
4. Nhấp vào thẻ Query (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 (tên tệp), process_timestamp (dấu thời gian xử lý), tags (thẻ) và word_count (số từ).

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

Lúc 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 thêm ứng dụng này, hãy dành chút thời gian để khám phá mã. Bạn có thể xem Cấu phần phần mềm và công cụ này sẽ hiển thị các tệp mã đã tạo.

Dưới đây là phần tóm tắt nhanh về các 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 trên Google Cloud và bật các API cần thiết.
2. appy.py: Điểm truy cập chính của quy trình xử lý. Ứ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 OCR) tệp đó và truyền siêu dữ liệu đến BigQuery.
3. Dockerfile: Xác định cách đóng gói ứng dụng thành 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, bạn đã 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. Dưới đây là một số ý tưởng.

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

Xây dựng 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ạo một ứng dụng web Streamlit hoặc Flask đơn giản kết nối với BigQuery. Ứng dụng này sẽ hiển thị một bảng các tài liệu đã xử lý (tên tệp, ngày tải lên, thẻ, số từ) và cho phép tôi lọc kết quả theo thẻ)

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

Thay vì xử lý OCR mô phỏng, hãy sử 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 đến Gemini để trích xuất văn bản và dữ liệu thực. 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 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.

Nâng cao khả năng lưu trữ và phân tích

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

Độ ổn định và bảo mật

Bạn có thể làm cho ứng dụng ổn định và bảo mật hơn, 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ý lỗi. Nếu dịch vụ Cloud Run không xử lý được tệp 5 lần, hãy gửi thông báo đến một chủ đề/bộ chứa "Thư không gửi được" riêng để con người kiểm tra.
2. Secret Manager (Trình quản lý bí mật): 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á này trong Secret Manager (Trình quản lý bí mật) 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 để có khả năng đị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ụ GCP khác.

Tất nhiên, bạn có thể đưa ra ý tưởng của riêng mình và sử dụng Antigravity để giúp bạn triển khai các ý tưởng đó!

9. Kết luận

Bạn đã xây dựng thành công một quy trình xử lý tài liệu có thể mở rộng, không 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 tạo ứng dụng từ quá trình tạo mã đế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ài liệu tham khảo

• Trang web chính thức : https://antigravity.google/
• Tài liệu: https://antigravity.google/docs
• Trường hợp sử dụng : https://antigravity.google/use-cases
• Tải xuống : https://antigravity.google/download