Antigravity로 Google Cloud에 빌드 및 배포

1. 소개

fca14bb9f4bb74f4.png

이 Codelab에서는 Google Antigravity (이 문서의 나머지 부분에서는 Antigravity라고 함)를 사용하여 Google Cloud에 서버리스 애플리케이션을 설계, 빌드, 배포하는 방법을 알아봅니다. Google Cloud Storage (GCS)에서 파일을 수집하고, Cloud Run 및 Gemini를 사용하여 파일을 처리하고, 메타데이터를 BigQuery로 스트리밍하는 서버리스 이벤트 기반 문서 파이프라인을 빌드합니다.

학습할 내용

  • 건축 계획 및 설계에 Antigravity를 사용하는 방법
  • AI 에이전트로 코드형 인프라 (셸 스크립트)를 생성합니다.
  • Python 기반 Cloud Run 서비스를 빌드하고 배포합니다.
  • Vertex AI의 Gemini를 통합하여 멀티모달 문서 분석을 수행합니다.
  • Antigravity의 둘러보기 아티팩트를 사용하여 엔드 투 엔드 파이프라인을 확인합니다.

필요한 항목

  • Google Antigravity가 설치되어 있어야 합니다. Antigravity를 설치하고 기본사항을 이해하는 데 도움이 필요한 경우 Google Antigravity 시작하기 Codelab을 완료하는 것이 좋습니다.
  • 결제가 사용 설정된 Google Cloud 프로젝트
  • gcloud CLI가 설치되고 인증되어 있어야 합니다.

2. 앱 개요

Antigravity를 사용하여 애플리케이션을 설계하고 구현하기 전에 먼저 빌드하려는 애플리케이션을 간략하게 설명해 보겠습니다.

Google Cloud Storage (GCS)에서 파일을 수집하고, Cloud Run 및 Gemini를 사용하여 파일을 처리하고, 메타데이터를 BigQuery로 스트리밍하는 서버리스 이벤트 기반 문서 파이프라인을 빌드하려고 합니다.

이 애플리케이션의 개략적인 아키텍처 다이어그램은 다음과 같습니다.

3bd519cfab38258d.png

정확하지 않아도 됩니다. Antigravity는 진행하면서 아키텍처 세부정보를 파악하는 데 도움이 됩니다. 하지만 빌드하려는 항목에 대한 아이디어가 있으면 도움이 됩니다. 세부정보를 많이 제공할수록 아키텍처와 코드 측면에서 Antigravity의 더 나은 결과를 얻을 수 있습니다.

3. 아키텍처 계획

이제 Antigravity로 아키텍처 세부정보를 계획할 준비가 되었습니다.

Antigravity는 복잡한 시스템을 계획하는 데 탁월합니다. 코드를 즉시 작성하는 대신 먼저 개략적인 아키텍처를 정의할 수 있습니다.

먼저 에이전트 관리자에 있는지 확인합니다. Antigravity를 방금 열었다면 가운데에 있는 Open Agent Manager 버튼을 클릭하거나 오른쪽 상단에 동일한 Open Agent Manager가 표시됩니다.

에이전트 관리자에서 작업공간을 열거나 빠른 프로토타입 제작 및 실험을 위한 독립적인 작업공간인 Playground를 사용할 수 있습니다. 먼저 Playground부터 살펴보겠습니다.

+ 버튼을 클릭하여 Playground에서 새 대화를 시작합니다.

4e33c028a604a375.png

그러면 아래와 같이 프롬프트를 제공할 수 있는 인터페이스가 표시됩니다.

fbf023e84f0eb3b2.png

오른쪽 상단에서 설정 아이콘 ⚙️을 클릭하고 Artifact 아래의 Review Policy과 Terminal 아래의 Terminal Command Auto Execution을 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 버킷, 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 버킷 (doc-ingestion-{project-id})을 만듭니다.
  3. BigQuery 데이터 세트 및 테이블 만들기 (pipeline_data.processed_docs)
  4. Pub/Sub 주제 및 알림 구성

에이전트는 Pub/Sub 푸시 메시지를 수신하는 Python 애플리케이션 (main.py)을 생성해야 합니다. 시뮬레이션된 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 아이콘을 클릭하여 계속 진행합니다.

직접 추가 테스트를 실행하려면 Antigravity의 검증 단계를 참고하세요. 여기서는 gsutil 유틸리티를 사용하여 샘플 파일을 Cloud Storage 버킷에 업로드합니다. 샘플 명령어는 다음과 같습니다.

gsutil cp <some-test-doc>.txt gs://<bucket-name>/

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. 로그: 로그 탭을 클릭합니다. '파일 처리: gs://...' 및 '성공적으로 처리됨...'과 같은 항목을 찾습니다.

BigQuery

목표: 데이터가 실제로 저장되었는지 확인합니다.

  1. BigQuery > SQL 작업공간으로 이동합니다.
  2. 탐색기 창에서 프로젝트 > pipeline_data 데이터 세트를 펼칩니다.
  3. 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 종속 항목을 나열합니다.

테스트 및 확인에 필요한 다른 스크립트와 텍스트 파일도 표시될 수 있습니다.

이때 모의 환경에서 전용 워크스페이스/폴더로 이동하는 것이 좋습니다. 오른쪽 상단의 관련 버튼을 클릭하여 이 작업을 수행할 수 있습니다.

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과 통합

시뮬레이션된 OCR 처리 대신 Gemini 모델을 사용하여 추출, 분류, 번역합니다.

  1. 더미 OCR 로직을 대체합니다. 이미지/PDF를 Gemini에 전송하여 실제 텍스트와 데이터를 추출합니다. 추출된 텍스트를 분석하여 문서 유형 (인보이스, 계약서, 이력서)을 분류하거나 항목 (날짜, 이름, 위치)을 추출합니다.
  2. 문서의 언어를 자동으로 감지하고 저장하기 전에 영어로 번역합니다. 다른 언어를 사용해도 됩니다.

스토리지 및 분석 개선

버킷에서 수명 주기 규칙을 구성하여 오래된 파일을 'Coldline' 또는 'Archive' 스토리지로 이동하여 비용을 절감할 수 있습니다.

견고성 및 보안

다음과 같이 앱을 더 강력하고 안전하게 만들 수 있습니다.

  1. 데드 레터 큐 (DLQ): 실패를 처리하도록 Pub/Sub 구독을 업데이트합니다. Cloud Run 서비스가 파일을 5번 처리하지 못하면 사람이 검사할 수 있도록 별도의 '데드 레터' 주제/버킷으로 메시지를 전송합니다.
  2. Secret Manager: 앱에 API 키나 민감한 구성이 필요한 경우 문자열을 하드코딩하는 대신 Secret Manager에 저장하고 Cloud Run에서 안전하게 액세스합니다.
  3. Eventarc: 복잡한 감사 로그 또는 기타 GCP 서비스 이벤트를 기반으로 트리거할 수 있도록 직접 Pub/Sub에서 Eventarc로 업그레이드하여 더 유연한 이벤트 라우팅을 지원합니다.

물론 나만의 아이디어를 떠올려 무중력을 사용해 구현할 수도 있습니다.

8. 결론

Google Antigravity를 사용하여 확장 가능하고 서버리스이며 AI 기반 문서 파이프라인을 몇 분 만에 빌드했습니다. 지금까지 배운 내용은 다음과 같습니다.

  • AI로 아키텍처를 계획하세요.
  • 코드 생성부터 배포 및 검증까지 애플리케이션을 생성하는 동안 Antigravity를 안내하고 관리합니다.
  • 둘러보기를 통해 배포 및 유효성 검사를 확인합니다.

참조 문서