1. Introdução
Neste codelab, você vai aprender a usar o Google Antigravity para criar, desenvolver e implantar um aplicativo sem servidor no Google Cloud. Vamos criar um pipeline de documentos sem servidor e orientado a eventos que ingere arquivos do Google Cloud Storage (GCS), os processa usando o Cloud Run e o Gemini e transmite os metadados para o BigQuery.
O que você vai aprender
- Como usar o Antigravity para planejamento e design arquitetônico.
- Gerar infraestrutura como código (scripts shell) com um agente de IA.
- Criar e implantar um serviço do Cloud Run baseado em Python.
- Integrar o Gemini na Vertex AI para análise multimodal de documentos.
- Verificar o pipeline de ponta a ponta usando o artefato de instruções do Antigravity.
O que é necessário
- O Google Antigravity instalado.
- Um projeto do Google Cloud com faturamento ativado.
- A CLI gcloud instalada e autenticada.
2. Visão geral do app
Antes de começar a arquitetar e implementar o aplicativo usando o Antigravity, vamos descrever o aplicativo que queremos criar.
Queremos criar um pipeline de documentos sem servidor e orientado a eventos que ingere arquivos do Google Cloud Storage (GCS), os processa usando o Cloud Run e o Gemini e transmite os metadados para o BigQuery.
Um diagrama de arquitetura de alto nível para esse aplicativo pode ser assim:
Isso não precisa ser preciso. O Antigravity pode nos ajudar a descobrir os detalhes da arquitetura à medida que avançamos. No entanto, é útil ter uma ideia do que você quer criar. Quanto mais detalhes você fornecer, melhores serão os resultados do Antigravity em termos de arquitetura e código.
3. Planejar a arquitetura
Estamos prontos para começar a planejar os detalhes da arquitetura com o Antigravity.
O Antigravity é excelente no planejamento de sistemas complexos. Em vez de escrever o código imediatamente, podemos começar definindo a arquitetura de alto nível e usar um dos recursos para ajudar o Antigravity a avaliar nossa solicitação, fazer perguntas complementares e, em seguida, prosseguir com o planejamento e a implementação.
Supondo que você tenha iniciado o Antigravity, vamos criar um novo projeto para este codelab.
Clique no ícone de novo projeto ao lado do laboratório Projects e, em seguida, em New Project , conforme mostrado abaixo:
Isso vai mostrar a opção Add Folder , conforme mostrado abaixo:
Clique no botão Add Folder para adicionar uma pasta ao projeto. Na minha máquina, criei uma pasta google-cloud-serverless-app e a adicionei a esse projeto.
Isso abre uma conversa no espaço de trabalho google-cloud-serverless-app.
Clique no ícone de configurações principal ⚙️ na parte de baixo à esquerda da tela e acesse as configurações específicas do projeto. Defina Agent Settings / Security Preset como Default e Agent Behaviour / Artifact Review Policy como Always Ask, conforme mostrado abaixo:
Isso garante que, em cada etapa, você possa revisar e aprovar o plano antes que o agente seja executado.
Comando
Agora estamos prontos para fornecer nosso primeiro comando ao Antigravity. Vamos usar um comando de barra /grill-me para avaliar nossa solicitação.
Digite /grill-me, insira o comando a seguir e clique no botão "Enviar":
/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.
O comando /grill-me faz várias perguntas complementares que você pode tentar responder da melhor forma possível. Ele também sugere Respostas recomendadas , que você pode usar se quiser.
Um exemplo de execução do meu comando /grill-me é mostrado abaixo:
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).
Perceba que pedi ao Antigravity para usar:
- Um script simples da CLI gcloud para provisionar recursos
- Notificações nativas do Cloud Storage Pub/Sub + assinatura por push do Pub/Sub para o Cloud Run
- Usar o Flask (com Gunicorn) para o framework
- Basta usar a simulação local com um arquivo de texto para os dados em vez de dados OCR em tempo real
- Usar table.insert_rows() do BigQuery para inserir linhas no BigQuery
- Implantação não autenticada do Cloud Run
e outras opções recomendadas.
Plano de implementação e lista de tarefas
O Antigravity vai começar a trabalhar e gerar um plano de implementação. Ele o coloca para sua revisão, enviando uma mensagem semelhante à mostrada abaixo:
Você pode clicar na alternância do painel auxiliar na janela no canto superior direito e conferir os artefatos gerados, que neste momento são apenas o plano de implementação.
Esse plano descreve:
- Infraestrutura: bucket do GCS, tópico do Pub/Sub, conjunto de dados do BigQuery.
- Processador: app Python/Flask, Dockerfile, requisitos.
- Integração: notificações do GCS → Pub/Sub → Cloud Run.
Você verá algo semelhante ao seguinte. Uma lista parcial do plano de implementação na nossa máquina é mostrada abaixo:
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
Leia com atenção. Esta é sua chance de enviar feedback para a implementação. Você pode clicar em qualquer parte do plano de implementação e adicionar comentários. Depois de adicionar alguns comentários, envie para revisão as mudanças que você gostaria de ver, especialmente em relação a nomes, ID do projeto do Google Cloud, região etc.
Quando tudo estiver bem, clique no botão Proceed para dar permissão ao agente de continuar com o plano de implementação.
Agora, ele vai criar outro artefato Task Plan, que contém um conjunto de tarefas criadas pelo Antigravity. O agente vai passar por elas uma a uma e executá-las. Um exemplo de lista de tarefas é mostrado abaixo:
4. Gerar o aplicativo
Depois que o plano é aprovado, o Antigravity começa a gerar os arquivos necessários para o aplicativo, desde scripts de provisionamento até código do aplicativo.
O Antigravity vai criar uma pasta e começar a criar os arquivos necessários para o projeto. Se você verificar os artefatos, vai notar vários arquivos (código-fonte, arquivos de script etc.) sendo gerados.
Quando o trabalho for concluído, ele vai mencionar isso e criar um documento de instruções que você pode consultar. Nele, a próxima etapa para o usuário é mencionada. Um exemplo é mostrado abaixo:
- Implantar o pipeline:verifique se você fez login na CLI do GCP e definiu o projeto de destino. Em seguida, execute:
./deploy.sh - Executar o teste de ponta a ponta: execute o script de teste de integração na nuvem para verificar se um upload de arquivo aciona o processamento do Cloud Run e transmite metadados para o BigQuery:
./test_cloud.sh - Limpar:quando terminar o teste, consulte os comandos de limpeza
README.mdpara remover os recursos criados e evitar cobranças.
Um arquivo de script de shell deploy.sh ou um arquivo com nome semelhante é gerado, o que automatiza a criação de recursos. Ela trabalha com:
- Ativação de APIs (
run,pubsub,bigquery,storage). - Criação do bucket do Google Cloud Storage (
document-processing-ingest-{project-id}). - Criação do conjunto de dados e da tabela do BigQuery (
document_processing.processed_metadata). - Configuração de tópicos e notificações do Pub/Sub.
5. Implantar o aplicativo
Vamos implantar o aplicativo conforme mencionado pelo ./ deploy.sh comando. Podemos pedir ao Antigravity para executar isso para nós, mas antes de fazer isso, verifique se a CLI gcloud está presente e configurada para o projeto do Google Cloud.
Podemos dar um comando ao Antigravity "Run the deploy.sh for me". Isso vai pedir sua permissão. Continue e conceda.
Ele inicia o processo como uma tarefa em segundo plano, conforme explicado pela mensagem abaixo:
Iniciei o processo de implantação executando ./deploy.sh em segundo plano. Vou monitorar os registros de execução e avisar assim que a implantação terminar.
6. Verificar o aplicativo
Depois que o pipeline é implantado, o Antigravity continua a verificar se o aplicativo realmente funciona. Ele nos pergunta se pode executar o arquivo test_cloud.sh. Podemos continuar e dar a permissão.
Por fim, ele nos diz o seguinte:
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.
Podemos abrir o artefato de instruções para conferir os resultados:
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.
Opcional: verificação manual
Embora o Antigravity já tenha verificado o aplicativo, você também pode verificar manualmente no console do Google Cloud se todos os recursos foram criados, seguindo estas etapas.
Cloud Storage
Objetivo: verificar se o bucket existe e conferir os arquivos enviados.
- Acesse Cloud Storage > Buckets.
- Localize o bucket chamado
document-processing-ingest-{project-id}. - Clique no nome do bucket para navegar pelos arquivos.
- Verificar: os arquivos enviados (por exemplo,
cloud_test_sample.txt) vão aparecer.
Pub/Sub
Objetivo: confirmar se o tópico existe e tem uma assinatura por push.
- Acesse Pub/Sub > Tópicos.
- Encontre document-uploads-topic.
- Clique no ID do tópico.
- Role a tela para baixo até a guia Assinaturas.
- Verificar: confira se doc-uploads-sub está listado com o tipo de entrega "Push".
Cloud Run
Objetivo: verificar o status e os registros do serviço.
- Acesse Cloud Run.
- Clique no serviço document-processor.
- Verificar:
- Saúde: marca de seleção verde indicando que o serviço está ativo.
- Registros: clique na guia "Registros". Procure entradas como "Processing file: gs://..." e "Successfully inserted...".
BigQuery
Objetivo: validar se os dados estão realmente armazenados.
- Acesse BigQuery > Espaço de trabalho SQL.
- No painel "Explorador", expanda o projeto > conjunto de dados document_processing.
- Clique na tabela processed_metadata.
- Clique na guia Consulta e recupere todas as linhas da tabela usando a instrução SELECT *.
- Verificar: você verá linhas contendo filename, process_timestamp, tags e word_count.
7. Conheça o aplicativo
Neste ponto, você tem o app básico provisionado e em execução. Antes de se aprofundar na extensão desse aplicativo, reserve um momento para explorar o código. Você pode conferir os artefatos, e eles vão mostrar os arquivos de código gerados.
Confira um breve resumo dos arquivos que podem aparecer:
deploy.sh: o script principal que provisiona todos os recursos do Google Cloud e ativa as APIs necessárias.appy.py: o ponto de entrada principal do pipeline. Esse app Python cria um servidor da Web que recebe mensagens de envio do Pub/Sub, faz o download do arquivo do GCS, o "processa" (simula OCR) e transmite os metadados para o BigQuery.Dockerfile: define como empacotar o app em uma imagem do contêiner.requirements.txt: lista as dependências do Python.
Você também pode encontrar outros scripts e arquivos de texto necessários para testes e verificação.
8. Estender o aplicativo
Agora que você tem um aplicativo básico funcional, pode continuar iterando e estendendo o aplicativo. Confira algumas ideias.
Adicionar um front-end
Crie uma interface da Web simples para visualizar os documentos processados.
Tente o seguinte comando: 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
Integrar com IA/ML real
Em vez de processamento OCR simulado, use modelos do Gemini para extrair, classificar e traduzir.
- Substitua a lógica OCR fictícia. Envie a imagem/PDF para o Gemini para extrair texto e dados reais. Analise o texto extraído para classificar o tipo de documento (fatura, contrato, currículo) ou extrair entidades (datas, nomes, locais).
- Detecte automaticamente o idioma do documento e traduza-o para o inglês antes de armazená-lo. Você também pode usar qualquer outro idioma.
Melhorar o armazenamento e a análise
Você pode configurar regras de ciclo de vida no bucket para mover arquivos antigos para o armazenamento "Coldline" ou "Archive" para economizar custos.
Robustez e segurança
Você pode tornar o app mais robusto e seguro, como:
- Filas de mensagens mortas (DLQ): atualize a assinatura do Pub/Sub para processar falhas. Se o serviço do Cloud Run não conseguir processar um arquivo cinco vezes, envie a mensagem para um tópico/bucket de "mensagens mortas" separado para inspeção humana.
- Secret Manager: se o app precisar de chaves de API ou configurações confidenciais, armazene-as no Secret Manager e acesse-as com segurança no Cloud Run em vez de codificar strings.
- Eventarc: faça upgrade do Pub/Sub direto para o Eventarc para um roteamento de eventos mais flexível, permitindo que você acione com base em registros de auditoria complexos ou outros eventos de serviço do GCP.
É claro que você pode criar suas próprias ideias e usar o Antigravity para ajudar a implementá-las.
9. Conclusão
Você criou um pipeline de documentos escalonável, sem servidor e com tecnologia de IA em minutos usando o Google Antigravity. Você aprendeu a:
- Planejar arquiteturas com IA.
- Instruir e gerenciar o Antigravity enquanto ele trabalha na geração do aplicativo, desde a geração de código até a implantação e validação.
- Verificar implantações e validação com instruções.
Documentos de referência
- Site oficial : https://antigravity.google/
- Documentação: https://antigravity.google/docs
- Casos de uso : https://antigravity.google/use-cases
- Download : https://antigravity.google/download