1. 소개
이 Codelab에서는 Google Antigravity를 사용하여 서버리스 애플리케이션을 설계, 빌드, Google Cloud에 배포하는 방법을 알아봅니다. Google Cloud Storage (GCS)에서 파일을 수집하고 Cloud Run 및 Gemini를 사용하여 파일을 처리하며 메타데이터를 BigQuery로 스트리밍하는 서버리스 이벤트 기반 문서 파이프라인을 빌드합니다.
학습할 내용
- Antigravity를 사용하여 아키텍처 계획 및 설계
- AI 에이전트로 코드형 인프라 (셸 스크립트) 생성
- Python 기반 Cloud Run 서비스 빌드 및 배포
- Vertex AI에서 Gemini를 통합하여 멀티모달 문서 분석
- Antigravity의 Walkthrough 아티팩트를 사용하여 엔드 투 엔드 파이프라인 확인
필요한 항목
- Google Antigravity가 설치되어 있어야 합니다.
- 결제가 사용 설정된 Google Cloud 프로젝트
- gcloud CLI 설치 및 인증
2. 앱 개요
Antigravity를 사용하여 애플리케이션을 설계하고 구현하기 전에 먼저 빌드하려는 애플리케이션을 간략하게 설명해 보겠습니다.
Google Cloud Storage (GCS)에서 파일을 수집하고 Cloud Run 및 Gemini를 사용하여 파일을 처리하며 메타데이터를 BigQuery로 스트리밍하는 서버리스 이벤트 기반 문서 파이프라인을 빌드합니다.
이 애플리케이션의 대략적인 아키텍처 다이어그램은 다음과 같습니다.
정확하지 않아도 됩니다. Antigravity는 진행하면서 아키텍처 세부정보를 파악하는 데 도움이 될 수 있습니다. 하지만 빌드하려는 항목에 대한 아이디어가 있으면 도움이 됩니다. 세부정보를 더 많이 제공할수록 아키텍처 및 코드 측면에서 Antigravity에서 더 나은 결과를 얻을 수 있습니다.
3. 아키텍처 계획
이제 Antigravity를 사용하여 아키텍처 세부정보를 계획할 준비가 되었습니다.
Antigravity는 복잡한 시스템을 계획하는 데 탁월합니다. 코드를 즉시 작성하는 대신 대략적인 아키텍처를 정의하는 것으로 시작하고 기능 중 하나를 사용하여 Antigravity가 요청을 평가하고 후속 질문을 한 다음 계획 및 구현을 진행하도록 할 수 있습니다.
Antigravity를 실행했다고 가정하고 이 Codelab을 위한 새 프로젝트를 만듭니다.
아래와 같이 Projects 실습 옆에 있는 새 프로젝트 아이콘을 클릭한 다음 New Project 를 클릭합니다.
그러면 아래와 같이 Add Folder 옵션이 표시됩니다.
Add Folder 버튼을 클릭하여 프로젝트에 폴더를 추가합니다. 내 머신에서 google-cloud-serverless-app 폴더를 만들고 이 프로젝트에 추가했습니다.
그러면 google-cloud-serverless-app 프로젝트에서 대화가 열립니다.
화면 왼쪽 하단에 있는 기본 설정 아이콘 ⚙️을 클릭하고 프로젝트별 설정으로 이동합니다. google-cloud-serverless-app 프로젝트가 나열되지 않으면 대화를 한 번만 진행한 후 프로젝트 설정으로 돌아갑니다.
아래와 같이 Agent Settings / Security Preset 을 Default 로, Agent Behaviour / Artifact Review Policy 를 Always Ask 로 설정합니다.
이렇게 하면 모든 단계에서 에이전트가 실행되기 전에 계획을 검토하고 승인할 수 있습니다.
프롬프트
이제 Antigravity에 첫 번째 프롬프트를 제공할 준비가 되었습니다. 슬래시 명령어 /grill-me를 사용하여 요청을 평가합니다.
/grill-me를 입력한 다음 다음 프롬프트를 입력하고 제출 버튼을 클릭합니다.
/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.
/grill-me 명령어는 최대한 많은 후속 질문을 합니다. 추천 답변 도 제안하며 원하는 경우 이 답변을 사용할 수 있습니다.
내 /grill-me 명령어의 샘플 실행은 다음과 같습니다.
How would you like the Cloud Run service to receive events from Cloud Storage and Pub/Sub?
(Recommended) Cloud Storage Pub/Sub Notification with a Pub/Sub Push Subscription (HTTP POST to Cloud Run)
How should access to the Cloud Run service endpoint be secured for Pub/Sub push requests?
Publicly accessible Cloud Run service without authentication (for prototyping/quick testing only)
How should the Python processor handle file inspection and the simulated OCR logic?
(Recommended) Download file from GCS: if plain text/utf-8, extract actual words and tags; if binary/image/PDF, simulate OCR processing (mock latency, generate synthetic text & tags, count words)
How should the processor write metadata to BigQuery and handle table/schema provisioning?
(Recommended) Use BigQuery Streaming Inserts (`insert_rows_json`) with auto-creation of the dataset and table if they do not exist
How should the Cloud Run service handle processing failures and retries from Pub/Sub?
(Recommended) Return HTTP 500 on transient errors for Pub/Sub automatic retry; return HTTP 200/204 on non-retryable errors (e.g., file not found, bad event format) to avoid poison pill loops
Which web framework would you prefer for the Python Cloud Run service?
Flask with Gunicorn: minimal, classic lightweight standard for GCP microservices
How would you like the cloud infrastructure (Bucket, Pub/Sub, Cloud Run, BigQuery) to be provisioned and deployed?
(Recommended) Provide both: automated `gcloud` CLI setup/deploy scripts for quick manual rollout AND Terraform manifests for reproducible IaC
How would you like to handle local testing and development before deploying to Google Cloud?
(Recommended) Include a local mock test suite and script (`test_local.py`) that can simulate Pub/Sub push envelopes and test processing with both mocked GCP clients and actual files
Antigravity에 다음을 요청했습니다.
- 리소스 프로비저닝을 위한 간단한 gcloud CLI 스크립트
- 기본 Cloud Storage Pub/Sub 알림 + Cloud Run에 대한 Pub/Sub 푸시 구독
- 프레임워크에 Flask (Gunicorn 포함) 사용
- 실시간 OCR 데이터 대신 데이터에 텍스트 파일로 로컬 시뮬레이션 사용
- BigQuery 테이블.insert_rows()를 사용하여 BigQuery에 행 삽입
- 인증되지 않은 Cloud Run 배포
및 기타 권장 옵션
구현 계획 및 할 일 목록
이제 Antigravity가 작동하여 구현 계획 을 생성합니다. 아래와 비슷한 메시지를 표시하여 검토를 요청합니다.
오른쪽 상단 창에서 보조 창 전환 버튼을 클릭하고 생성된 아티팩트(이 시점에서는 구현 계획 만 해당)를 볼 수 있습니다.
이 계획은 다음을 간략하게 설명합니다.
- 인프라: GCS 버킷, Pub/Sub 주제, BigQuery 데이터 세트
- 프로세서: Python/Flask 앱, Dockerfile, 요구사항
- 통합: GCS 알림 → Pub/Sub → Cloud Run
다음과 비슷한 내용이 표시됩니다. 머신에서 구현 계획의 일부 목록은 다음과 같습니다.
주의 깊게 읽어 보세요. 구현에 대한 의견을 제공할 수 있는 기회입니다. 구현 계획의 아무 부분이나 클릭하고 의견을 추가할 수 있습니다. 의견을 추가한 후에는 특히 이름 지정, Google Cloud 프로젝트 ID, 리전 등에 관한 변경사항을 검토를 위해 제출해야 합니다.
모든 항목이 올바르게 표시되면 Proceed 버튼을 클릭하여 에이전트가 구현 계획을 진행할 수 있는 권한을 부여합니다.
4. 애플리케이션 생성
계획이 승인되면 Antigravity는 프로비저닝 스크립트에서 애플리케이션 코드에 이르기까지 애플리케이션에 필요한 파일 생성을 시작합니다.
Antigravity는 폴더를 만들고 프로젝트에 필요한 파일 생성을 시작합니다. 아티팩트를 확인하면 여러 파일 (소스 코드, 스크립트 파일 등)이 생성되는 것을 확인할 수 있습니다.
작업이 완료되면 이를 언급하고 살펴볼 수 있는 Walkthrough 문서를 만듭니다. 샘플 출력은 다음과 같습니다.
Walkthrough 문서에는 구현된 내용, 생성된 스크립트, 가장 중요한 검증 및 유효성 검사가 언급되어 있습니다. 검증 및 유효성 검사를 포함하는 Walkthrough 문서의 일부 출력은 다음과 같습니다.
3. Verification & Validation
Test Suite Execution
We ran the automated test suite using pytest:
bash
.venv/bin/pytest tests/ -v
tests/test_local.py::test_health_check PASSED [ 9%]
tests/test_local.py::test_invalid_pubsub_envelope PASSED [ 18%]
tests/test_local.py::test_ignore_delete_events PASSED [ 27%]
tests/test_local.py::test_gcs_file_not_found PASSED [ 36%]
tests/test_local.py::test_successful_contract_processing PASSED [ 45%]
tests/test_local.py::test_successful_pdf_ocr_processing PASSED [ 54%]
tests/test_local.py::test_transient_bq_error_triggers_500_retry PASSED [ 63%]
tests/test_processor.py::test_tag_extraction_filters_stopwords PASSED [ 72%]
tests/test_processor.py::test_process_plain_text_document PASSED [ 81%]
tests/test_processor.py::test_process_binary_pdf_simulated_ocr PASSED [ 90%]
tests/test_processor.py::test_process_empty_text_document PASSED [100%]
============================== 11 passed in 2.37s ==============================
Standalone End-to-End Simulation
We executed the standalone simulation script:
bash
.venv/bin/python tests/test_local.py
Sample Output:
=================================================================
Running Serverless Document Processing Local Simulation
=================================================================
[1] Health Check: Status=200, Payload={'service': 'document-processor', 'status': 'healthy'}
[2] Simulating GCS Event: Object Finalized 'sample_contract.txt' in 'finance-bucket'
Response: Status=200, Body={'file_name': 'sample_contract.txt', 'ocr_status': 'EXTRACTED_TEXT', 'status': 'success', 'tags': ['provider', 'cloud', 'client', 'agreement', 'shall'], 'word_count': 181}
[3] Simulating GCS Event: Object Finalized 'sample_invoice.pdf' in 'invoices-bucket'
Response: Status=200, Body={'file_name': 'sample_invoice.pdf', 'ocr_status': 'SIMULATED_OCR', 'status': 'success', 'tags': ['invoice', 'finance', 'billing', 'acme', 'pdf'], 'word_count': 62}
=================================================================
BigQuery Streamed Table Inspection (Mock Table)
=================================================================
Row #1:
File: sample_contract.txt (gs://finance-bucket)
Status: EXTRACTED_TEXT
Words: 181
Tags: ['provider', 'cloud', 'client', 'agreement', 'shall']
Processed: 2026-09-08T02:50:37.436225+00:00
Row #2:
File: sample_invoice.pdf (gs://invoices-bucket)
Status: SIMULATED_OCR
Words: 62
Tags: ['invoice', 'finance', 'billing', 'acme', 'pdf']
Processed: 2026-09-08T02:50:37.641931+00:00
Antigravity에 이 애플리케이션을 Google Cloud에 배포하는 방법을 물어볼 수 있습니다. 아래에 나열된 것과 동일한 세부정보가 포함된 답변이 반환됩니다. 요약하자면 Google Cloud 프로젝트 설정과 함께 Google Cloud SDK가 설치되어 있는지 확인하라는 메시지가 표시됩니다. 완료되면
1단계: 필수 GCP API 사용 설정
setup_gcp.sh를 실행하여 Cloud Run, Pub/Sub, Cloud Storage, BigQuery, Cloud Build API를 사용 설정합니다. ./scripts/setup_gcp.sh
2단계: 전체 파이프라인 배포
deploy.sh를 실행합니다.
export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1" # or your region
./scripts/deploy.sh
이 스크립트가 백그라운드에서 실행하는 작업은 다음과 같습니다.
- Google Cloud Build를 사용하여 컨테이너 이미지를 빌드하고 Container/Artifact Registry에 푸시합니다.
- 적절한 환경 변수 (
GCP_PROJECT,BQ_DATASET_ID,BQ_TABLE_ID)를 사용하여 서비스를 Cloud Run에 배포합니다. - Cloud Storage 수집 버킷 (
gs://<PROJECT_ID>-document-ingest)을 만듭니다. - Pub/Sub 주제 (
document-upload-events)를 만들고 GCS 권한을 부여하여 게시합니다. - 버킷에서 GCS 알림 (
OBJECT_FINALIZE)을 구성합니다. - 자동 재시도 백오프를 사용하여 Cloud Run 서비스 URL을 타겟팅하는 Pub/Sub 푸시 구독을 만듭니다.
파이프라인을 테스트하는 방법도 제안합니다.
test_pipeline.sh 실행: ./scripts/test_pipeline.sh
이렇게 하면 samples/sample_contract.txt 및 samples/sample_invoice.pdf 가 버킷에 업로드되고, 처리를 기다린 후 추출된 메타데이터, 단어 수, 태그를 보여주는 BigQuery SQL 쿼리가 실행됩니다.
5. 애플리케이션 배포
언급된 대로 애플리케이션을 배포해 보겠습니다. Antigravity에 이 작업을 실행하도록 요청할 수 있지만, 그 전에 gcloud CLI가 있고 Google Cloud 프로젝트에 구성되어 있는지 확인합니다.
Antigravity에 "Deploy the application for me"라는 프롬프트를 제공할 수 있습니다. 그러면 다양한 권한을 묻는 메시지가 표시되고 스크립트 파일 실행이 진행됩니다.
아래 메시지에 설명된 대로 백그라운드 작업으로 프로세스를 시작합니다.
I have initiated the deployment of the document processing pipeline to Google Cloud project PROJECT_ID in REGION.The deployment process is currently executing in the background:
Building and publishing the container image via Cloud Build.
Configuring service account IAM permissions and deploying the Cloud Run service.
Provisioning the Cloud Storage bucket (gs://PROJECT_ID-document-ingest).
Setting up the Pub/Sub topic, GCS notification, and push subscription.
I will notify you as soon as the deployment finishes!
6. 애플리케이션 확인
파이프라인이 배포되면 Antigravity는 애플리케이션이 실제로 작동하는지 확인합니다. test_pipeline.sh 파일을 실행할 수 있는지 묻습니다. 권한을 부여할 수 있습니다.
마지막으로 다음과 같이 알려줍니다.
🚀 Deployment Successful & Verified on Google Cloud!
The application has been deployed to Google Cloud project PROJECT_ID in REGION and end-to-end event-driven processing has been verified.
또한 결과를 볼 수 있도록 Walkthrough 아티팩트를 업데이트했습니다 (일부 목록은 아래에 제공됨).
배포 요약
- GCP 프로젝트: PROJECT_ID
- 리전: REGION
- Cloud Run 서비스: document-processor
- Cloud Run 엔드포인트: SERVICE_URL
- Cloud Storage 버킷: gs://PROJECT_ID-document-ingest
- Pub/Sub 주제: document-upload-events
- Pub/Sub 푸시 구독: document-upload-events-push-sub
- BigQuery 대상: PROJECT_ID.document_processing.document_metadata
실시간 파이프라인 확인
실시간 Google Cloud 환경에 대해 scripts/test_pipeline.sh를 실행했습니다.
- sample_contract.txt 및 sample_invoice.pdf를 Cloud Storage 버킷에 업로드했습니다.
- GCS가 Pub/Sub에 OBJECT_FINALIZE 이벤트를 생성했습니다.
- Pub/Sub가 봉투를 Cloud Run 마이크로서비스에 푸시했습니다.
- Cloud Run이 메타데이터를 추출하고 시뮬레이션된 OCR을 처리하고 레코드를 BigQuery로 스트리밍했습니다.
실시간 BigQuery 쿼리 출력
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| file_name | word_count | ocr_status | tags | processed_at |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| test_invoice_1788840194.pdf | 62 | SIMULATED_OCR | ["invoice","finance","billing","acme","pdf"] | 2026-09-08 04:03:27 |
| test_contract_1788840194.txt | 181 | EXTRACTED_TEXT | ["provider","cloud","client","agreement","shall"] | 2026-09-08 04:03:22 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
모든 파이프라인 구성요소가 프로덕션에서 활성 상태이고 정상이며 확인되었습니다.
선택사항: 수동 확인
Antigravity에서 이미 애플리케이션을 확인했지만 원하는 경우 다음 단계에 따라 Google Cloud 콘솔에서 모든 리소스가 생성되었는지 수동으로 확인할 수도 있습니다.
Cloud Storage
목표: 버킷이 있는지 확인하고 업로드된 파일을 확인합니다.
- Cloud Storage > 버킷 으로 이동합니다.
PROJECT_ID-document-processing이라는 버킷을 찾습니다.- 버킷 이름을 클릭하여 파일을 탐색합니다.
- 확인: 업로드된 파일 (예:
sample_contract.txt)이 표시됩니다.
Pub/Sub
목표: 주제가 있고 푸시 구독이 있는지 확인합니다.
- Pub/Sub > 주제 로 이동합니다.
- document-uploads-events 를 찾습니다.
- 주제 ID 를 클릭합니다.
- 구독 탭으로 아래로 스크롤합니다.
- 확인: doc-uploads-events-push-sub 가 나열되어 있는지 확인합니다.
Cloud Run
목표: 서비스 상태 및 로그를 확인합니다.
- Cloud Run 으로 이동합니다.
- 서비스 document-processor 를 클릭합니다.
- 확인:
- 상태: 서비스가 활성 상태임을 나타내는 녹색 체크표시입니다.
- 로그: 로그 탭을 클릭합니다. "Processing document: gs://..." 및 "Successfully streamed metadata..."와 같은 항목을 찾습니다.
BigQuery
목표: 데이터가 실제로 저장되었는지 확인합니다.
- BigQuery > SQL 작업공간 으로 이동합니다.
- 탐색기 창에서 프로젝트 > document_processing 데이터 세트를 펼칩니다.
- document_metadata 테이블을 클릭합니다.
- 쿼리 탭을 클릭하고 SELECT * 문을 통해 테이블에서 모든 행을 가져옵니다.
- 확인: file_name, process_at, tags, word_count 가 포함된 행이 표시됩니다.
7. 애플리케이션 살펴보기
이제 기본 앱이 프로비저닝되고 실행됩니다. 이 애플리케이션을 더 확장하기 전에 코드를 살펴보세요. 아티팩트를 보면 생성된 코드 파일이 표시됩니다.
다음은 표시될 수 있는 몇 가지 파일의 간단한 요약입니다.
deploy.sh: 모든 Google Cloud 리소스를 프로비저닝하고 필요한 API를 사용 설정하는 기본 스크립트입니다.main.py: 파이프라인의 기본 진입점입니다. 이 Python 앱은 Pub/Sub 푸시 메시지를 수신하고 GCS에서 파일을 다운로드하고 '처리'(OCR 시뮬레이션)하고 메타데이터를 BigQuery로 스트리밍하는 웹 서버를 만듭니다.Dockerfile: 앱을 컨테이너 이미지로 패키징하는 방법을 정의합니다.requirements.txt: Python 종속 항목을 나열합니다.
테스트 및 확인에 필요한 다른 스크립트 및 텍스트 파일도 표시될 수 있습니다.
8. 애플리케이션 확장
이제 기본 애플리케이션이 작동하므로 애플리케이션을 계속 반복하고 확장할 수 있습니다. 다음은 참고할 수 있는 팁입니다.
프런트엔드 추가
처리된 문서를 볼 수 있는 간단한 웹 인터페이스를 빌드합니다.
다음 프롬프트를 사용해 봅니다. 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과 통합
시뮬레이션된 OCR 처리 대신 Gemini 모델을 사용하여 추출, 분류, 번역합니다.
- 더미 OCR 로직을 바꿉니다. Gemini에 이미지/PDF를 전송하여 실제 텍스트와 데이터를 추출합니다. 추출된 텍스트를 분석하여 문서 유형 (인보이스, 계약서, 이력서)을 분류하거나 항목 (날짜, 이름, 위치)을 추출합니다.
- 문서의 언어를 자동으로 감지하고 저장하기 전에 영어로 번역합니다. 다른 언어를 사용할 수도 있습니다.
저장 및 분석 개선
버킷에서 수명 주기 규칙을 구성하여 이전 파일을 'Coldline' 또는 'Archive' 스토리지로 이동하여 비용을 절감할 수 있습니다.
강력함 및 보안
다음과 같이 앱을 더 강력하고 안전하게 만들 수 있습니다.
- 데드 레터 큐 (DLQ): 실패를 처리하도록 Pub/Sub 구독을 업데이트합니다. Cloud Run 서비스에서 파일을 5번 처리하지 못하면 사람의 검사를 위해 메시지를 별도의 '데드 레터' 주제/버킷으로 보냅니다.
- Secret Manager: 앱에 API 키 또는 민감한 구성이 필요한 경우 문자열을 하드 코딩하는 대신 Secret Manager에 저장하고 Cloud Run에서 안전하게 액세스합니다.
- Eventarc: 더 유연한 이벤트 라우팅을 위해 직접 Pub/Sub에서 Eventarc로 업그레이드하여 복잡한 감사 로그 또는 기타 GCP 서비스 이벤트를 기반으로 트리거할 수 있습니다.
물론 자체 아이디어를 내고 Antigravity를 사용하여 구현할 수도 있습니다.
9. 결론
Google Antigravity를 사용하여 확장 가능한 서버리스 AI 기반 문서 파이프라인을 몇 분 만에 빌드했습니다. 지금까지 배운 내용은 다음과 같습니다.
- AI로 아키텍처 계획
- 코드 생성에서 배포 및 유효성 검사에 이르기까지 애플리케이션을 생성하는 동안 Antigravity를 안내하고 관리
- Walkthrough를 사용하여 배포 및 유효성 검사 확인