ساخت و استقرار در فضای ابری گوگل با Antigravity

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه از Google Antigravity برای طراحی، ساخت و استقرار یک برنامه بدون سرور در Google Cloud استفاده کنید. ما یک خط لوله سند بدون سرور و رویداد محور خواهیم ساخت که فایل‌ها را از Google Cloud Storage (GCS) دریافت می‌کند، آنها را با استفاده از Cloud Run و Gemini پردازش می‌کند و ابرداده‌های آنها را به BigQuery منتقل می‌کند.

آنچه یاد خواهید گرفت

• نحوه استفاده از ضد جاذبه برای برنامه ریزی و طراحی معماری.
• تولید زیرساخت به صورت کد (اسکریپت‌های پوسته) با یک عامل هوش مصنوعی.
• ساخت و استقرار یک سرویس Cloud Run مبتنی بر پایتون.
• ادغام Gemini روی Vertex AI برای تحلیل اسناد چندوجهی.
• با استفاده از ابزار راهنمای Antigravity، ارتباط سرتاسری را تأیید کنید.

آنچه نیاز دارید

• گوگل آنتی گراویتی نصب شده است.
• یک پروژه ابری گوگل با قابلیت پرداخت صورتحساب.
• رابط خط فرمان gcloud نصب و احراز هویت شد.

۲. نمای کلی برنامه

قبل از اینکه به سراغ معماری و پیاده‌سازی برنامه با استفاده از Antigravity برویم، ابتدا برنامه‌ای را که می‌خواهیم برای خودمان بسازیم، شرح می‌دهیم.

ما می‌خواهیم یک خط لوله سند بدون سرور و رویدادمحور بسازیم که فایل‌ها را از Google Cloud Storage (GCS) دریافت کند، آنها را با استفاده از Cloud Run و Gemini پردازش کند و فراداده‌های آنها را به BigQuery منتقل کند.

یک نمودار معماری سطح بالا برای این برنامه می‌تواند به شکل زیر باشد:

لازم نیست این دقیق باشد. 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 خواستم که این را بگوید:

• یک اسکریپت ساده‌ی gcloud CLI برای تأمین منابع
• اعلان‌های Pub/Sub Storage بومی در فضای ابری + اشتراک Pub/Sub Push در Cloud Run
• برای چارچوب از Flask (با Gunicorn) استفاده کنید
• فقط از شبیه‌سازی محلی با یک فایل متنی برای داده‌ها به جای داده‌های OCR زنده استفاده کنید
• برای وارد کردن ردیف‌ها در BigQuery از تابع table.insert_rows() در BigQuery استفاده کنید.
• استقرار Cloud Run بدون احراز هویت

و سایر گزینه‌های پیشنهادی

طرح اجرایی و فهرست وظایف

آنتی‌گراویتی اکنون شروع به کار می‌کند و یک طرح اجرایی ایجاد می‌کند. این طرح با ارائه پیامی مشابه پیام زیر، آن را برای بررسی شما ارائه می‌دهد:

می‌توانید روی گزینه‌ی Auxiliary Pane در پنجره‌ی بالا سمت راست کلیک کنید و Artifactهای تولید شده را مشاهده کنید، که در این مرحله فقط Implementation Plan (طرح پیاده‌سازی) است.

این طرح موارد زیر را تشریح می‌کند:

• زیرساخت : سطل GCS، Pub/Sub Topic، مجموعه داده BigQuery.
• پردازنده : برنامه پایتون/فلسک، داکرفایل، نیازمندی‌ها.
• یکپارچه‌سازی : اعلان‌های GCS → 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 شروع به تولید فایل‌های مورد نیاز برای برنامه می‌کند، از تهیه اسکریپت‌ها گرفته تا کد برنامه.

آنتی‌گراویتی یک پوشه ایجاد می‌کند و شروع به ایجاد فایل‌های لازم برای پروژه می‌کند. اگر Artifacts را بررسی کنید، متوجه خواهید شد که چندین فایل (کد منبع، فایل‌های اسکریپت و غیره) ایجاد می‌شوند.

پس از اتمام کار، به آن اشاره می‌کند و یک سند راهنما ایجاد می‌کند که می‌توانید آن را مشاهده کنید. در این سند، گام بعدی برای کاربر ذکر شده است، نمونه‌ای از آن در زیر آورده شده است:

• استقرار خط لوله: مطمئن شوید که به رابط خط فرمان GCP خود وارد شده‌اید و پروژه هدف خود را تعیین کرده‌اید، سپس deploy.sh زیر را اجرا کنید: ./
• اجرای تست سرتاسری : اسکریپت تست یکپارچه‌سازی ابری را اجرا کنید تا تأیید کنید که آپلود فایل، پردازش Cloud Run را فعال می‌کند و فراداده‌ها را به BigQuery ارسال می‌کند: ./test_cloud.sh
• پاکسازی: پس از اتمام آزمایش، برای حذف منابع ایجاد شده و جلوگیری از هزینه‌های اضافی، به دستورات پاکسازی README.md مراجعه کنید.

خواهید دید که یک فایل deploy.sh یا یک فایل اسکریپت پوسته با نام مشابه ایجاد می‌شود که ایجاد منابع را خودکار می‌کند. این فایل موارد زیر را مدیریت می‌کند:

1. فعال کردن APIها ( run ، pubsub ، bigquery ، storage ).
2. ایجاد سطل ذخیره‌سازی ابری گوگل ( document-processing-ingest-{project-id} ).
3. ایجاد مجموعه داده و جدول BigQuery ( document_processing.processed_metadata ).
4. پیکربندی موضوعات و اعلان‌های Pub/Sub.

۵. برنامه را مستقر کنید

بیایید برنامه را همانطور که گفته deploy.sh از طریق دستور ./ مستقر کنیم. می‌توانیم از Antigravity بخواهیم که این کار را برای ما اجرا کند، اما قبل از انجام این کار، مطمئن شوید که gcloud CLI برای پروژه Google Cloud وجود دارد و پیکربندی شده است.

می‌توانیم به Antigravity بگوییم «فایل deploy.sh را برای من اجرا کن». این کار از شما اجازه می‌خواهد. اجازه دهید.

همانطور که در پیام زیر توضیح داده شده است، این فرآیند به عنوان یک کار پس‌زمینه شروع می‌شود:

من فرآیند استقرار را با اجرای ./deploy.sh در پس‌زمینه آغاز کرده‌ام. گزارش‌های اجرا را رصد خواهم کرد و به محض اتمام استقرار، به شما اطلاع خواهم داد!

۶. برنامه را تأیید کنید

پس از استقرار خط لوله، 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.

می‌توانیم مصنوع Walkthrough را باز کنیم تا نتایج را مشاهده کنیم:

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 ).

میخانه/ساب

هدف : تأیید کنید که موضوع وجود دارد و اشتراک خبرنامه فعال است.

1. به «میخانه/فرعی > موضوعات» بروید.
2. موضوع-بارگذاری-سند را پیدا کنید.
3. روی شناسه موضوع کلیک کنید.
4. به پایین اسکرول کنید تا به برگه اشتراک‌ها برسید.
5. تأیید کنید: مطمئن شوید که doc-uploads-sub با نوع تحویل « Push » فهرست شده است.

اجرای ابری

هدف : بررسی وضعیت سرویس و گزارش‌ها.

1. به Cloud Run بروید.
2. روی پردازشگر سند سرویس کلیک کنید.
3. تأیید کنید:
4. سلامت: علامت تیک سبز نشان دهنده فعال بودن سرویس است.
5. گزارش‌ها: روی برگه گزارش‌ها کلیک کنید. به دنبال ورودی‌هایی مانند « در حال پردازش فایل: gs://... » و « با موفقیت درج شد... » باشید.

بیگ‌کوئری

هدف : اعتبارسنجی داده‌های ذخیره شده.

1. به BigQuery > SQL Workspace بروید.
2. در پنجره اکسپلورر، پروژه خود را باز کنید > document_processing dataset .
3. روی جدول processed_metadata کلیک کنید.
4. روی تب Query کلیک کنید و تمام ردیف‌های جدول را از طریق دستور SELECT * بازیابی کنید.
5. تأیید: باید ردیف‌هایی حاوی filename ، process_timestamp ، tags و word_count را ببینید.

۷. برنامه را بررسی کنید

در این مرحله، برنامه‌ی پایه آماده و در حال اجرا است. قبل از اینکه به سراغ توسعه‌ی بیشتر این برنامه برویم، کمی وقت بگذارید و کد را بررسی کنید. می‌توانید مصنوعات را مشاهده کنید و باید فایل‌های کد تولید شده را به شما نشان دهد.

در اینجا خلاصه‌ای سریع از فایل‌هایی که ممکن است ببینید، آورده شده است:

1. deploy.sh : اسکریپت اصلی که تمام منابع Google Cloud را فراهم می‌کند و APIهای مورد نیاز را فعال می‌کند.
2. appy.py : نقطه ورودی اصلی خط لوله. این برنامه پایتون یک وب سرور ایجاد می‌کند که پیام‌های Pub/Sub push را دریافت می‌کند، فایل را از GCS دانلود می‌کند، آن را "پردازش" (شبیه‌سازی OCR) می‌کند و فراداده را به BigQuery ارسال می‌کند.
3. Dockerfile : نحوه بسته‌بندی برنامه در یک تصویر کانتینر را تعریف می‌کند.
4. requirements.txt : وابستگی‌های پایتون را فهرست می‌کند.

همچنین ممکن است اسکریپت‌ها و فایل‌های متنی دیگری را که برای آزمایش و تأیید لازم هستند، مشاهده کنید.

۸. درخواست را تمدید کنید

حالا که یک برنامه‌ی کاربردی پایه و کاربردی دارید، می‌توانید به تکرار و توسعه‌ی برنامه ادامه دهید. در اینجا چند ایده ارائه شده است.

یک رابط کاربری اضافه کنید

یک رابط وب ساده برای مشاهده اسناد پردازش شده بسازید.

دستور زیر را امتحان کنید: 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. منطق OCR ساختگی را جایگزین کنید. تصویر/PDF را برای استخراج متن و داده‌های واقعی به Gemini ارسال کنید. متن استخراج شده را تجزیه و تحلیل کنید تا نوع سند (فاکتور، قرارداد، رزومه) را طبقه‌بندی کنید یا موجودیت‌ها (تاریخ‌ها، نام‌ها، مکان‌ها) را استخراج کنید.
2. به طور خودکار زبان سند را تشخیص داده و قبل از ذخیره سازی آن را به انگلیسی ترجمه کنید. می‌توانید از هر زبان دیگری نیز استفاده کنید.

افزایش فضای ذخیره‌سازی و تجزیه و تحلیل

شما می‌توانید قوانین چرخه عمر را روی باکت پیکربندی کنید تا فایل‌های قدیمی را به فضای ذخیره‌سازی «Coldline» یا «Archive» منتقل کنید تا در هزینه‌ها صرفه‌جویی شود.

استحکام و امنیت

شما می‌توانید برنامه را قوی‌تر و امن‌تر کنید، مانند:

1. صف‌های نامه‌های معوق (DLQ): اشتراک Pub/Sub را برای مدیریت خطاها به‌روزرسانی کنید. اگر سرویس Cloud Run 5 بار در پردازش یک فایل ناموفق بود، پیام را برای بررسی انسانی به یک موضوع/سطل جداگانه "نامه معوق" ارسال کنید.
2. مدیر مخفی: اگر برنامه شما به کلیدهای API یا پیکربندی حساس نیاز دارد، آنها را در مدیر مخفی ذخیره کنید و به جای رشته‌های کدگذاری شده، از طریق Cloud Run به طور ایمن به آنها دسترسی داشته باشید.
3. Eventarc: برای مسیریابی انعطاف‌پذیرتر رویدادها، از Pub/Sub مستقیم به Eventarc ارتقا دهید و به شما امکان می‌دهد بر اساس گزارش‌های حسابرسی پیچیده یا سایر رویدادهای سرویس GCP، تریگر (فعال‌سازی) انجام دهید.

البته، شما می‌توانید ایده‌های خودتان را مطرح کنید و از Antigravity برای اجرای آنها کمک بگیرید!

۹. نتیجه‌گیری

شما با موفقیت یک خط لوله سند مقیاس‌پذیر، بدون سرور و مبتنی بر هوش مصنوعی را در عرض چند دقیقه با استفاده از Google Antigravity ساختید. شما یاد گرفتید که چگونه:

• معماری‌ها را با هوش مصنوعی برنامه‌ریزی کنید.
• آموزش و مدیریت Antigravity در حین تولید برنامه از تولید کد تا استقرار و اعتبارسنجی.
• استقرارها و اعتبارسنجی را با Walkthroughs تأیید کنید.

اسناد مرجع

• سایت رسمی: https://antigravity.google/
• مستندات: https://antigravity.google/docs
• موارد استفاده: https://antigravity.google/use-cases
• دانلود: https://antigravity.google/download