Создание и развертывание приложений в облаке Google с помощью Antigravity.

1. Введение

В этом практическом занятии вы узнаете, как использовать Google Antigravity для проектирования, создания и развертывания бессерверного приложения в Google Cloud. Мы создадим бессерверный и событийно-ориентированный конвейер обработки документов, который будет получать файлы из Google Cloud Storage (GCS), обрабатывать их с помощью Cloud Run и Gemini и передавать их метаданные в BigQuery.

Что вы узнаете

• Как использовать антигравитацию в архитектурном планировании и проектировании.
• Создание инфраструктуры в виде кода (сценариев командной оболочки) с помощью агента искусственного интеллекта.
• Создайте и разверните облачный сервис Cloud Run на основе Python.
• Интегрируйте Gemini с Vertex AI для мультимодального анализа документов.
• Проверьте весь конвейер обработки данных, используя артефакт Walkthrough от Antigravity.

Что вам понадобится

• Установлена ​​функция Google Antigravity .
• Проект в Google Cloud с включенной функцией выставления счетов.
• Интерфейс командной строки gcloud установлен и авторизован.

2. Обзор приложения

Прежде чем приступить к проектированию и реализации приложения с использованием Antigravity, давайте сначала определим, какое приложение мы хотим для себя создать.

Мы хотим создать бессерверный и событийно-ориентированный конвейер обработки документов, который будет получать файлы из Google Cloud Storage (GCS), обрабатывать их с помощью Cloud Run и Gemini и передавать их метаданные в BigQuery.

Архитектурная схема высокого уровня для этого приложения может выглядеть следующим образом:

Точность не обязательна. Antigravity может помочь нам проработать детали архитектуры по ходу работы. Однако полезно иметь представление о том, что вы хотите построить. Чем больше деталей вы предоставите, тем лучше будут результаты, которые вы получите от Antigravity с точки зрения архитектуры и кода.

3. Спланируйте архитектуру.

Мы готовы приступить к планированию архитектурных деталей с помощью Antigravity!

Antigravity превосходно справляется с планированием сложных систем. Вместо того чтобы сразу писать код, мы можем начать с определения высокоуровневой архитектуры и использовать одну из функций, чтобы помочь Antigravity оценить наш запрос, задать нам уточняющие вопросы, а затем перейти к его планированию и реализации.

Предполагая, что вы запустили Antigravity, мы создадим новый проект для этого практического занятия.

Нажмите на значок нового проекта рядом с разделом Projects , а затем выберите New Project , как показано ниже:

После этого появится опция Add Folder , как показано ниже:

Нажмите кнопку «Добавить папку» , чтобы добавить папку в ваш проект. На моем компьютере я создал папку 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 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).

Обратите внимание, что я попросил компанию Antigravity использовать следующее:

• Простой CLI-скрипт gcloud для выделения ресурсов.
• Встроенные уведомления Pub/Sub облачного хранилища + подписка Pub/Sub на Cloud Run
• Используйте Flask (с Gunicorn) в качестве фреймворка.
• Вместо данных оптического распознавания текста в реальном времени используйте локальное моделирование с текстовым файлом в качестве источника данных.
• Используйте метод `table.insert_rows()` в BigQuery для вставки строк в BigQuery.
• Неаутентифицированное развертывание Cloud Run

а также другие рекомендуемые варианты.

План реализации и перечень задач

Теперь Antigravity приступит к работе и сгенерирует план реализации . Он будет представлен на ваше рассмотрение, выведя сообщение, подобное приведенному ниже:

Вы можете щелкнуть переключатель «Вспомогательная панель» в правом верхнем углу окна и просмотреть сгенерированные артефакты, которыми на данный момент является только план реализации.

В этом плане изложены следующие положения:

• Инфраструктура : хранилище GCS, тема Pub/Sub, набор данных BigQuery.
• Процессор : приложение на Python/Flask, Dockerfile, необходимые зависимости.
• Интеграция : GCS Notifications → Pub/Sub → Cloud Run.

Вы должны увидеть что-то похожее на следующее. Ниже представлен частичный список плана внедрения на нашем компьютере:

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

Внимательно прочтите план. Это ваш шанс оставить отзыв о его реализации. Вы можете щелкнуть по любой части плана и добавить комментарии. После добавления комментариев обязательно отправьте на рассмотрение любые изменения, которые вы хотели бы внести, особенно касающиеся именования, идентификатора проекта Google Cloud, региона и т. д.

Если все будет выглядеть нормально, дайте агенту разрешение продолжить выполнение плана внедрения, нажав кнопку Proceed .

Примечание: Иногда кнопка «Продолжить» может отсутствовать, и Antigravity может продолжить работу, не дожидаясь вашего ввода.

Теперь агент приступает к созданию еще одного артефакта — Плана задач , содержащего набор задач, созданных Antigravity. Агент будет проходить по ним одну за другой и выполнять их. Пример списка задач показан ниже:

4. Создайте приложение.

После утверждения плана компания Antigravity начинает генерировать файлы, необходимые для работы приложения, от скриптов инициализации до кода приложения.

Примечание : Вам будет предложено несколько команд терминала (gcloud, скрипты оболочки и т. д.), которые агенту потребуется использовать, чтобы понять среду и сгенерировать соответствующие скрипты. Нажмите кнопку Submit , чтобы агент продолжил работу. Хотя в этой лабораторной работе рассматриваются конкретные имена файлов, которые были сгенерированы, вы можете обнаружить, что Antigravity генерирует другие имена файлов, хотя назначение и содержимое файлов должны быть схожими.

Antigravity создаст папку и начнёт создавать файлы, необходимые для проекта. Если вы посмотрите на раздел «Артефакты», то увидите, что генерируется несколько файлов (исходный код, скриптовые файлы и т. д.).

После завершения работы программа сообщит об этом и создаст документ с пошаговым руководством , с которым вы сможете ознакомиться. В этом документе будут указаны следующие шаги для пользователя; пример приведен ниже:

• Развертывание конвейера: Убедитесь, deploy.sh вы вошли в CLI GCP и указали целевой проект, затем выполните команду: ./
• Выполните сквозное тестирование : запустите скрипт интеграционного тестирования в облаке, чтобы убедиться, что загрузка файла запускает обработку Cloud Run и передает метаданные в BigQuery: ./test_cloud.sh
• Очистка: После завершения тестирования обратитесь к командам очистки в файле README.md , чтобы удалить созданные ресурсы и избежать дополнительных расходов.

Вы обнаружите, что генерируется файл deploy.sh или аналогичный по названию скрипт оболочки, который автоматизирует создание ресурсов. Он обрабатывает:

1. Включение API ( run , pubsub , bigquery , storage ).
2. Создание хранилища Google Cloud Storage ( document-processing-ingest-{project-id} ).
3. Создание набора данных и таблицы BigQuery ( document_processing.processed_metadata ).
4. Настройка тем и уведомлений Pub/Sub.

5. Разверните приложение.

Давайте развернем приложение deploy.sh как указано, с помощью команды ./ . Мы можем попросить Antigravity выполнить это за нас, но прежде чем это сделать, убедитесь, что CLI gcloud установлен и настроен для проекта Google Cloud.

Мы можем отправить Antigravity запрос на выполнение команды "Запустите для меня deploy.sh ". Вам будет предложено предоставить необходимые разрешения. Пожалуйста, сделайте это.

Этот процесс запускается в фоновом режиме, как поясняется в сообщении ниже:

Я запустил процесс развертывания, выполнив в фоновом режиме команду ./deploy.sh . Буду следить за логами выполнения и сообщу вам, как только развертывание завершится!

6. Проверьте заявку.

После развертывания конвейера Antigravity приступает к проверке работоспособности приложения. Он спрашивает, может ли он запустить файл test_cloud.sh. Мы можем предоставить ему разрешение.

В итоге это позволяет нам узнать следующее:

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.

Мы можем открыть артефакт «Пошаговое руководство», чтобы просмотреть результаты:

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.

Дополнительно: Ручная проверка

Несмотря на то, что Antigravity уже проверила приложение, при желании вы также можете вручную проверить в консоли Google Cloud, созданы ли все ресурсы, выполнив следующие шаги.

Облачное хранилище

Цель : Проверить существование хранилища и наличие загруженных файлов.

1. Перейдите в раздел «Облачное хранилище» > «Корзины» .
2. Найдите раздел с именем document-processing-ingest-{project-id} .
3. Щелкните по названию корзины, чтобы просмотреть файлы.
4. Проверка: Вы должны увидеть загруженные файлы (например, cloud_test_sample.txt ).

Паб/Саб

Цель : Подтвердить существование темы и наличие подписки на push-уведомления.

1. Перейдите в раздел «Публикация/Подписка» > «Темы» .
2. Найдите тему «Загрузки документов» .
3. Нажмите на идентификатор темы .
4. Прокрутите страницу вниз до вкладки «Подписки» .
5. Проверка: Убедитесь, что в каталоге doc-uploads-sub указан тип доставки " Push ".

Cloud Run

Цель : Проверить состояние сервиса и журналы событий.

1. Перейдите в Cloud Run .
2. Нажмите на кнопку « Обработчик сервисных документов» .
3. Проверять:
4. Состояние: Зеленая галочка указывает на то, что услуга активна.
5. Журналы: Перейдите на вкладку «Журналы». Найдите записи типа « Обработка файла: gs://... » и « Успешно вставлен... ».

BigQuery

Цель : Проверить, действительно ли данные сохранены.

1. Перейдите в раздел BigQuery > SQL Workspace .
2. В панели Проводника разверните свой проект > набор данных document_processing .
3. Щёлкните по таблице processed_metadata .
4. Перейдите на вкладку «Запрос» и получите все строки из таблицы с помощью оператора SELECT *.
5. Проверка: Вы должны увидеть строки, содержащие имя файла , временную метку процесса , теги и количество слов .

7. Изучите приложение.

На данном этапе базовое приложение уже настроено и работает. Прежде чем приступать к дальнейшему расширению приложения, уделите немного времени изучению кода. Вы можете просмотреть артефакты, и там должны отобразиться сгенерированные файлы кода.

Вот краткое описание файлов, которые вы можете увидеть:

1. deploy.sh : Главный скрипт, который подготавливает все ресурсы Google Cloud и включает необходимые API.
2. appy.py : Основная точка входа в конвейер обработки данных. Это приложение на Python создает веб-сервер, который принимает push-уведомления Pub/Sub, загружает файл из GCS, «обрабатывает» его (имитирует OCR) и передает метаданные в BigQuery.
3. Dockerfile : Определяет способ упаковки приложения в образ контейнера.
4. 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

Интеграция с реальным ИИ/машинным обучением

Вместо имитации обработки OCR используйте модели Gemini для извлечения, классификации и перевода данных.

1. Замените фиктивную логику распознавания текста. Отправьте изображение/PDF-файл в Gemini для извлечения фактического текста и данных. Проанализируйте извлеченный текст, чтобы классифицировать тип документа (счет-фактура, договор, резюме) или извлечь сущности (даты, имена, местоположения).
2. Функция автоматического определения языка документа и его перевода на английский язык перед сохранением. Вы также можете использовать любой другой язык.

Улучшение хранения данных и аналитики.

Вы можете настроить правила жизненного цикла для хранилища, чтобы перемещать старые файлы в хранилище "Coldline" или "Archive" для экономии средств.

Надежность и безопасность

Вы можете сделать приложение более надежным и безопасным, например:

1. Очереди недоставленных сообщений (DLQ): Обновите подписку Pub/Sub для обработки сбоев. Если служба Cloud Run не обрабатывает файл 5 раз, отправьте сообщение в отдельную тему/корзину «Недоставленные сообщения» для проверки человеком.
2. Менеджер секретов: Если вашему приложению требуются ключи API или конфиденциальные параметры конфигурации, храните их в Менеджере секретов и получайте к ним безопасный доступ из Cloud Run, вместо того чтобы жестко прописывать строки.
3. Eventarc: Переход с прямого подключения Pub/Sub на Eventarc обеспечивает более гибкую маршрутизацию событий, позволяя запускать события на основе сложных журналов аудита или других событий сервисов GCP.

Конечно, вы можете придумывать собственные идеи и использовать антигравитацию для их реализации!

9. Заключение

Вы успешно создали масштабируемый, бессерверный, работающий на основе ИИ конвейер обработки документов за считанные минуты, используя Google Antigravity. Вы научились:

• Планируйте архитектуру с помощью ИИ.
• Обеспечивать руководство и управление процессом разработки приложения Antigravity на всех этапах — от генерации кода до развертывания и проверки.
• Проверьте развертывание и валидацию с помощью пошаговых инструкций.

Справочная документация

• Официальный сайт: https://antigravity.google/
• Документация: https://antigravity.google/docs
• Примеры использования: https://antigravity.google/use-cases
• Скачать: https://antigravity.google/download