1. Introduction
Dans cet atelier de programmation, vous allez apprendre à utiliser Google Antigravity pour concevoir, créer et déployer une application sans serveur sur Google Cloud. Nous allons créer un pipeline de documents sans serveur et basé sur les événements qui ingère des fichiers à partir de Google Cloud Storage (GCS), les traite à l'aide de Cloud Run et de Gemini, et diffuse leurs métadonnées dans BigQuery.
Points abordés
- Comment utiliser Antigravity pour la planification et la conception architecturales
- Générer une infrastructure en tant que code (scripts shell) avec un agent d'IA
- Créer et déployer un service Cloud Run basé sur Python
- Intégrer Gemini sur Vertex AI pour l'analyse multimodale de documents
- Vérifier le pipeline de bout en bout à l'aide de l'artefact de présentation d'Antigravity
Prérequis
- Google Antigravity installé
- Projet Google Cloud avec facturation activée
- gcloud CLI installée et authentification effectuée
2. Présentation de l'application
Avant de nous lancer dans l'architecture et l'implémentation de l'application à l'aide d'Antigravity, décrivons d'abord l'application que nous voulons créer.
Nous voulons créer un pipeline de documents sans serveur et basé sur les événements qui ingère des fichiers à partir de Google Cloud Storage (GCS), les traite à l'aide de Cloud Run et de Gemini, et diffuse leurs métadonnées dans BigQuery.
Un diagramme de l'architecture de haut niveau pour cette application pourrait se présenter comme suit :
Il n'est pas nécessaire d'être précis. Antigravity peut nous aider à déterminer les détails de l'architecture au fur et à mesure. Toutefois, il est utile d'avoir une idée de ce que vous voulez créer. Plus vous fournissez de détails, meilleurs seront les résultats obtenus avec Antigravity en termes d'architecture et de code.
3. Planifier l'architecture
Nous sommes prêts à commencer à planifier les détails de l'architecture avec Antigravity.
Antigravity excelle dans la planification de systèmes complexes. Au lieu d'écrire du code immédiatement, nous pouvons commencer par définir l'architecture de haut niveau et utiliser l'une des fonctionnalités pour aider Antigravity à évaluer notre requête, à nous poser des questions complémentaires, puis à poursuivre sa planification et son implémentation.
En supposant que vous avez lancé Antigravity, nous allons créer un projet pour cet atelier de programmation.
Cliquez sur l'icône de nouveau projet à côté de l'atelier Projects , puis sur New Project (Nouveau projet), comme illustré ci-dessous :
L'option Add Folder (Ajouter un dossier) s'affiche comme suit :
Cliquez sur le bouton Add Folder (Ajouter un dossier) pour ajouter un dossier à votre projet. Sur ma machine, j'ai créé un dossier google-cloud-serverless-app et je l'ai ajouté à ce projet.
Une conversation s'ouvre dans le projet google-cloud-serverless-app.
Cliquez sur l'icône des paramètres principaux ⚙️en bas à gauche de l'écran, puis accédez aux paramètres spécifiques au projet. Si le projet google-cloud-serverless-app ne s'affiche pas, lancez une conversation, puis revenez aux paramètres du projet.
Définissez Agent Settings/Security Preset (Paramètres de l'agent/Prédéfinis de sécurité) sur Default (Par défaut) et Agent Behavior/Artifact Review Policy (Comportement de l'agent/Règles de révision des artefacts) sur Always Ask (Toujours demander), comme illustré ci-dessous :
Vous pourrez ainsi examiner et approuver le plan à chaque étape avant que l'agent ne l'exécute.
Prompt
Nous sommes maintenant prêts à fournir notre premier prompt à Antigravity. Nous allons utiliser une commande à barre oblique /grill-me pour évaluer notre requête.
Saisissez /grill-me, puis le prompt suivant, et cliquez sur le bouton "Envoyer" :
/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.
La commande /grill-me pose un certain nombre de questions complémentaires auxquelles vous pouvez essayer de répondre au mieux de vos connaissances. Elle suggère également des réponses recommandées que vous pouvez utiliser si vous le souhaitez.
Voici un exemple d'exécution de ma commande /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
Notez que j'ai demandé à Antigravity de procéder comme suit :
- Un script gcloud CLI simple pour provisionner des ressources
- Notifications Pub/Sub natives de Cloud Storage + abonnement push Pub/Sub à Cloud Run
- Utiliser Flask (avec Gunicorn) pour le framework
- Utiliser une simulation locale avec un fichier texte pour les données au lieu de données OCR en direct
- Utiliser table.insert_rows() BigQuery pour insérer des lignes dans BigQuery
- Déploiement Cloud Run non authentifié
et d'autres options recommandées.
Plan d'implémentation et liste des tâches
Antigravity va maintenant se mettre au travail et générer un plan d'implémentation. Il vous le soumet pour examen en vous envoyant un message semblable à celui-ci :
Vous pouvez cliquer sur le bouton bascule du volet auxiliaire en haut à droite de la fenêtre et afficher les artefacts générés, qui ne sont pour l'instant que le plan d'implémentation.
Ce plan décrit les éléments suivants :
- Infrastructure : bucket GCS, sujet Pub/Sub, ensemble de données BigQuery.
- Processeur : application Python/Flask, Dockerfile, exigences
- Intégration : notifications GCS → Pub/Sub → Cloud Run
Le résultat qui s'affiche doit ressembler à ceci : Voici une liste partielle du plan d'implémentation sur notre machine :
Lisez-le attentivement. C'est l'occasion de nous faire part de vos commentaires sur l'implémentation. Vous pouvez cliquer sur n'importe quelle partie du plan d'implémentation et ajouter des commentaires. Une fois que vous avez ajouté des commentaires, veillez à soumettre pour examen toutes les modifications que vous souhaitez voir, en particulier concernant la dénomination, l'ID de projet Google Cloud, la région, etc.
Une fois que tout semble correct, autorisez l'agent à poursuivre le plan d'implémentation en cliquant sur le bouton Proceed (Continuer).
4. Générer l'application
Une fois le plan approuvé, Antigravity commence à générer les fichiers requis pour l'application, des scripts de provisionnement au code de l'application.
Antigravity crée un dossier et commence à créer les fichiers nécessaires au projet. Si vous vérifiez les artefacts, vous remarquerez que plusieurs fichiers (code source, fichiers de script, etc.) sont générés.
Une fois son travail terminé, il le mentionne et crée un document Walkthrough (Présentation) que vous pouvez consulter. Voici un exemple de sortie :
Le document de présentation indique ce qui a été implémenté, les scripts générés et, surtout, la vérification et la validation qui ont été effectuées. Voici une sortie partielle du document de présentation qui inclut la vérification et la validation :
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
Pouvons-nous demander à Antigravity comment déployer cette application sur Google Cloud ? Il fournit des informations complètes à ce sujet, comme indiqué ci-dessous. En résumé, il nous demande de nous assurer que le SDK Google Cloud est installé et qu'un projet Google Cloud est configuré. Une fois cette opération effectuée,
Étape 1 : Activer les API GCP requises
Exécutez setup_gcp.sh pour activer les API Cloud Run, Pub/Sub, Cloud Storage, BigQuery et Cloud Build : ./scripts/setup_gcp.sh
Étape 2 : Déployer l'ensemble du pipeline
Exécutez deploy.sh :
export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1" # or your region
./scripts/deploy.sh
Voici ce que fait ce script en arrière-plan :
- Crée l'image de conteneur à l'aide de Google Cloud Build et la transmet à Container Registry/Artifact Registry.
- Déploie le service sur Cloud Run avec les variables d'environnement appropriées (
GCP_PROJECT,BQ_DATASET_ID,BQ_TABLE_ID). - Crée le bucket d'ingestion Cloud Storage (
gs://<PROJECT_ID>-document-ingest). - Crée le sujet Pub/Sub (
document-upload-events) et accorde à GCS l'autorisation de publier sur ce sujet. - Configure une notification GCS (
OBJECT_FINALIZE) sur le bucket. - Crée un abonnement push Pub/Sub ciblant l'URL du service Cloud Run avec un délai de nouvelle tentative automatique.
Il suggère également comment tester le pipeline.
Exécutez test_pipeline.sh : ./scripts/test_pipeline.sh
Cette commande importe samples/sample_contract.txt et samples/sample_invoice.pdf dans votre bucket, attend le traitement et exécute une requête SQL BigQuery affichant les métadonnées extraites, le nombre de mots et les tags.
5. Déployer l'application
Déployons l'application comme indiqué. Nous pouvons demander à Antigravity d'exécuter cette opération pour nous, mais avant cela, assurez-vous que gcloud CLI est présent et configuré pour le projet Google Cloud.
Nous pouvons envoyer un prompt à Antigravity : "Deploy the application for me" (Déployer l'application pour moi). Vous serez invité à accorder diverses autorisations, puis les fichiers de script seront exécutés.
Le processus démarre en tant que tâche en arrière-plan, comme l'explique le message ci-dessous :
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. Vérifier l'application
Une fois le pipeline déployé, Antigravity vérifie que l'application fonctionne correctement. Il nous demande s'il peut exécuter le fichier test_pipeline.sh. Nous pouvons lui accorder l'autorisation.
Il nous indique finalement ce qui suit :
🚀 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.
Il a également mis à jour l'artefact de présentation pour afficher les résultats (liste partielle ci-dessous) :
Résumé du déploiement
- Projet GCP : PROJECT_ID
- Région : REGION
- Service Cloud Run : document-processor
- Point de terminaison Cloud Run : SERVICE_URL
- Bucket Cloud Storage : gs://PROJECT_ID-document-ingest
- Sujet Pub/Sub : document-upload-events
- Abonnement push Pub/Sub : document-upload-events-push-sub
- Cible BigQuery : PROJECT_ID.document_processing.document_metadata
Vérification du pipeline en direct
Nous avons exécuté scripts/test_pipeline.sh dans l'environnement Google Cloud en direct :
- Nous avons importé sample_contract.txt et sample_invoice.pdf dans le bucket Cloud Storage.
- GCS a généré des événements OBJECT_FINALIZE dans Pub/Sub.
- Pub/Sub a envoyé les enveloppes au microservice Cloud Run.
- Cloud Run a extrait les métadonnées, traité l'OCR simulé et diffusé les enregistrements dans BigQuery.
Sortie de la requête BigQuery en direct
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| 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 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
Tous les composants du pipeline sont actifs, en bon état et vérifiés en production.
Facultatif : Vérification manuelle
Même si Antigravity a déjà vérifié l'application, vous pouvez également vérifier manuellement dans la console Google Cloud que toutes les ressources sont créées, si vous le souhaitez, en procédant comme suit.
Cloud Storage
Objectif : Vérifier que le bucket existe et rechercher les fichiers importés.
- Accédez à Cloud Storage > Buckets.
- Recherchez le bucket nommé
PROJECT_ID-document-processing. - Cliquez sur le nom du bucket pour parcourir les fichiers.
- Vérifiez que les fichiers importés s'affichent (par exemple,
sample_contract.txt).
Pub/Sub
Objectif : Vérifier que le sujet existe et qu'il dispose d'un abonnement push.
- Accédez à Pub/Sub > Sujets.
- Recherchez document-uploads-events.
- Cliquez sur l'ID du sujet.
- Faites défiler la page jusqu'à l'onglet Abonnements.
- Vérifiez que doc-uploads-events-push-sub est répertorié.
Cloud Run
Objectif : Vérifier l'état et les journaux du service.
- Accédez à Cloud Run.
- Cliquez sur le service document-processor.
- Vérifiez :
- État : une coche verte indique que le service est actif.
- Journaux : cliquez sur l'onglet "Journaux". Recherchez des entrées telles que "Processing document: gs://..." (Traitement du document : gs://...) et "Successfully streamed metadata..." (Métadonnées diffusées avec succès...).
BigQuery
Objectif : Vérifier que les données sont réellement stockées.
- Accédez à BigQuery > Espace de travail SQL.
- Dans le volet "Explorateur", développez l'ensemble de données project > document_processing.
- Cliquez sur la table document_metadata.
- Cliquez sur l'onglet Requête et récupérez toutes les lignes de la table à l'aide de l'instruction SELECT *.
- Vérifiez que les lignes contiennent file_name, process_at, tags, et word_count.
7. Explorer l'application
À ce stade, l'application de base est provisionnée et en cours d'exécution. Avant d'étendre davantage cette application, prenez le temps d'explorer le code. Vous pouvez afficher les artefacts, qui devraient afficher les fichiers de code générés.
Voici un bref résumé de quelques fichiers que vous pouvez voir :
deploy.sh: script principal qui provisionne toutes les ressources Google Cloud et active les API requises.main.py: point d'entrée principal du pipeline. Cette application Python crée un serveur Web qui reçoit des messages push Pub/Sub, télécharge le fichier à partir de GCS, le "traite" (simule l'OCR) et diffuse les métadonnées dans BigQuery.Dockerfile: définit comment empaqueter l'application dans une image de conteneur.requirements.txt: liste les dépendances Python.
Vous pouvez également voir d'autres scripts et fichiers texte nécessaires aux tests et à la vérification.
8. Étendre l'application
Maintenant que vous disposez d'une application de base fonctionnelle, vous pouvez continuer à itérer et à étendre l'application. Voici quelques idées :
Ajouter une interface
Créez une interface Web simple pour afficher les documents traités.
Essayez le prompt suivant : 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 (Créer une application Web Streamlit ou Flask simple qui se connecte à BigQuery. Elle doit afficher un tableau des documents traités (nom de fichier, date d'importation, tags, nombre de mots) et me permettre de filtrer les résultats par tag).
Intégrer une IA/ML réelle
Au lieu du traitement OCR simulé, utilisez les modèles Gemini pour extraire, classer et traduire.
- Remplacez la logique OCR factice. Envoyez l'image/le PDF à Gemini pour extraire le texte et les données réels. Analysez le texte extrait pour classer le type de document (facture, contrat, CV) ou extraire des entités (dates, noms, lieux).
- Détectez automatiquement la langue du document et traduisez-le en anglais avant de le stocker. Vous pouvez également utiliser n'importe quelle autre langue.
Améliorer le stockage et les analyses
Vous pouvez configurer des règles de cycle de vie sur le bucket pour déplacer les anciens fichiers vers le stockage "Coldline" ou "Archive" afin de réduire les coûts.
Robustesse et sécurité
Vous pouvez rendre l'application plus robuste et sécurisée, par exemple :
- Files d'attente de lettres mortes (DLQ) : mettez à jour l'abonnement Pub/Sub pour gérer les échecs. Si le service Cloud Run ne parvient pas à traiter un fichier cinq fois, envoyez le message à un sujet/bucket "Lettre morte" distinct pour une inspection humaine.
- Secret Manager : si votre application a besoin de clés API ou d'une configuration sensible, stockez-les dans Secret Manager et accédez-y de manière sécurisée à partir de Cloud Run au lieu de coder en dur des chaînes.
- Eventarc : passez de Pub/Sub direct à Eventarc pour un routage d'événements plus flexible, ce qui vous permet de déclencher des événements en fonction de journaux d'audit complexes ou d'autres événements de service GCP.
Bien sûr, vous pouvez trouver vos propres idées et utiliser Antigravity pour vous aider à les implémenter.
9. Conclusion
Vous avez créé un pipeline de documents évolutif, sans serveur et basé sur l'IA en quelques minutes à l'aide de Google Antigravity. Vous avez appris à effectuer les opérations suivantes :
- Planifier des architectures avec l'IA
- Donner des instructions à Antigravity et le gérer lorsqu'il génère l'application, de la génération de code au déploiement et à la validation
- Vérifier les déploiements et la validation à l'aide de présentations
Documents de référence
- Site officiel : https://antigravity.google/
- Documentation: https://antigravity.google/docs
- Cas d'utilisation : https://antigravity.google/use-cases
- Téléchargement : https://antigravity.google/download