۱. مقدمه
در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه از Google Antigravity (که در ادامه سند به آن Antigravity گفته میشود) برای طراحی، ساخت و استقرار یک برنامه بدون سرور در Google Cloud استفاده کنید. ما یک خط لوله سند بدون سرور و رویداد محور خواهیم ساخت که فایلها را از Google Cloud Storage (GCS) دریافت میکند، آنها را با استفاده از Cloud Run و Gemini پردازش میکند و ابردادههای آنها را به BigQuery منتقل میکند.
آنچه یاد خواهید گرفت
- نحوه استفاده از ضد جاذبه برای برنامه ریزی و طراحی معماری.
- تولید زیرساخت به صورت کد (اسکریپتهای پوسته) با یک عامل هوش مصنوعی.
- ساخت و استقرار یک سرویس Cloud Run مبتنی بر پایتون.
- ادغام Gemini روی Vertex AI برای تحلیل اسناد چندوجهی.
- با استفاده از ابزار راهنمای Antigravity، ارتباط سرتاسری را تأیید کنید.
آنچه نیاز دارید
- گوگل آنتیگراویتی نصب شده است. اگر برای نصب آنتیگراویتی و درک اصول اولیه به کمک نیاز دارید، توصیه میشود codelab: شروع به کار با گوگل آنتیگراویتی را تکمیل کنید.
- یک پروژه ابری گوگل با قابلیت پرداخت صورتحساب.
- رابط خط فرمان gcloud نصب و احراز هویت شد.
۲. نمای کلی برنامه
قبل از اینکه به سراغ معماری و پیادهسازی برنامه با استفاده از Antigravity برویم، ابتدا برنامهای را که میخواهیم برای خودمان بسازیم، شرح میدهیم.
ما میخواهیم یک خط لوله سند بدون سرور و رویدادمحور بسازیم که فایلها را از Google Cloud Storage (GCS) دریافت کند، آنها را با استفاده از Cloud Run و Gemini پردازش کند و فرادادههای آنها را به BigQuery منتقل کند.
یک نمودار معماری سطح بالا برای این برنامه میتواند به شکل زیر باشد:
لازم نیست این دقیق باشد. Antigravity میتواند به ما کمک کند تا جزئیات معماری را در حین کار مشخص کنیم. با این حال، داشتن ایدهای در مورد آنچه میخواهید بسازید، مفید است. هرچه جزئیات بیشتری ارائه دهید، از نظر معماری و کد، نتایج بهتری از Antigravity خواهید گرفت.
۳. معماری را برنامهریزی کنید
ما آمادهایم تا برنامهریزی جزئیات معماری را با Antigravity شروع کنیم!
آنتیگراویتی در برنامهریزی سیستمهای پیچیده عالی عمل میکند. به جای نوشتن فوری کد، میتوانیم با تعریف معماری سطح بالا شروع کنیم.
ابتدا، مطمئن شوید که در قسمت مدیریت عامل (Agent Manager) هستید. اگر به تازگی Antigravity را باز کردهاید، میتوانید روی دکمهی Open Agent Manager در وسط صفحه کلیک کنید یا باید همان Open Agent Manager را در گوشهی بالا سمت راست نیز مشاهده کنید.
در Agent Manager، شما میتوانید یک فضای کاری باز کنید یا به سادگی از Playground، یک فضای کاری مستقل برای نمونههای اولیه سریع و آزمایش، استفاده کنید. بیایید با Playground شروع کنیم.
برای شروع مکالمه جدید در Playground روی دکمه + کلیک کنید:
این یک رابط کاربری ایجاد میکند که در آن میتوانید اعلان را مطابق شکل زیر ارائه دهید:
در گوشه بالا سمت راست، روی آیکون تنظیمات ⚙️ کلیک کنید و گزینه Review Policy در زیر Artifact و Terminal Command Auto Execution را در زیر Terminal روی 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.
فهرست وظایف و طرح اجرایی
آنتیگراویتی درخواست شما را تجزیه و تحلیل کرده و یک لیست وظایف و برنامه اجرایی ایجاد میکند.
این طرح موارد زیر را تشریح میکند:
- زیرساخت : سطل GCS، Pub/Sub Topic، مجموعه داده BigQuery.
- پردازنده : برنامه پایتون/فلسک، داکرفایل، نیازمندیها.
- یکپارچهسازی : اعلانهای GCS → Pub/Sub → Cloud Run.
شما باید چیزی شبیه به موارد زیر را ببینید:
روی دکمهی Open کنار ردیف Task کلیک کنید. این باید مجموعهای از وظایف ایجاد شده توسط Antigravity را به شما نشان دهد. عامل یکی یکی آنها را بررسی خواهد کرد:
مرحله بعدی بررسی طرح اجرایی و دادن مجوز به نماینده برای ادامه کار است.
برای مشاهده جزئیات طرح پیادهسازی، روی آن کلیک کنید. آن را با دقت مطالعه کنید. این فرصتی است تا بازخورد خود را برای پیادهسازی ارائه دهید. میتوانید روی هر بخش از طرح پیادهسازی کلیک کنید و نظرات خود را اضافه کنید. پس از افزودن نظرات، حتماً هرگونه تغییری را که میخواهید مشاهده کنید، به خصوص در مورد نامگذاری، شناسه پروژه Google Cloud، منطقه و غیره، برای بررسی ارسال کنید.
وقتی همه چیز خوب به نظر رسید، با کلیک بر روی دکمهی Proceed ، به عامل اجازه دهید تا طرح پیادهسازی را ادامه دهد.
۴. برنامه را تولید کنید
پس از تأیید طرح، Antigravity شروع به تولید فایلهای مورد نیاز برای برنامه میکند، از تهیه اسکریپتها گرفته تا کد برنامه.
آنتیگراویتی یک پوشه ایجاد میکند و شروع به ایجاد فایلهای لازم برای پروژه میکند. در نمونهی اجرا شده، موارد زیر را مشاهده کردیم:
یک فایل setup.sh یا یک فایل اسکریپت پوسته با نام مشابه ایجاد میشود که ایجاد منابع را خودکار میکند. این فایل موارد زیر را مدیریت میکند:
- فعال کردن APIها (
run،pubsub،bigquery،storage). - ایجاد سطل ذخیرهسازی ابری گوگل (
doc-ingestion-{project-id}). - ایجاد مجموعه داده و جدول BigQuery (
pipeline_data.processed_docs). - پیکربندی موضوعات و اعلانهای Pub/Sub.
عامل باید یک برنامه پایتون ( main.py ) ایجاد کند که به پیامهای Pub/Sub push گوش میدهد. این برنامه از یک منطق OCR شبیهسازی شده استفاده میکند، تعداد کلمات و برچسبهای تصادفی تولید میکند و آن را در BigQuery ذخیره میکند.
پس از ایجاد این اسکریپت راهاندازی، Antigravity باید از شما بخواهد که اسکریپت را از طرف شما اجرا کند. یک صفحه نمونه در زیر نشان داده شده است:
ادامه دهید و در صورت نیاز روی Accept کلیک کنید.
اسکریپت تأمین، منابع را ایجاد کرده و ایجاد آنها را تأیید میکند. در صورت موفقیتآمیز بودن بررسی، به ساخت کانتینر و استقرار آن به عنوان یک سرویس (در main.py ) در Cloud Run ادامه میدهد. نمونه خروجی در زیر نشان داده شده است:
به عنوان بخشی از استقرار سرویس، اشتراکهای Pub/Sub و سایر موارد لازم برای عملکرد این خط لوله نیز راهاندازی خواهد شد. همه این کارها باید چند دقیقه طول بکشد.
در عین حال، میتوانید به Inbox (از گوشه بالا سمت چپ) بروید، وظایف در انتظار Pending خود را بررسی کنید:
این روش خوبی است تا مطمئن شوید که شما وظایف را تأیید میکنید، زیرا نماینده به دنبال بازخورد شماست.
۵. برنامه را تأیید کنید
پس از استقرار خط لوله، Antigravity برای تأیید صحت عملکرد برنامه اقدام میکند. Antigravity این کار را با مراحل تأیید در لیست وظایف، خودکار میکند. یک صفحه نمونه در زیر نشان داده شده است:
یک فایل آزمایشی ( test.txt ) ایجاد میکند و میخواهد آن را در مخزن ذخیرهسازی ابری گوگل آپلود کند. برای ادامه روی Accept کلیک کنید.
اگر میخواهید آزمایشهای بیشتری را خودتان انجام دهید، میتوانید از مرحله اعتبارسنجی Antigravity الگو بگیرید، جایی که از ابزار gsutil برای آپلود یک فایل نمونه به فضای ذخیرهسازی ابری استفاده میکند. دستور نمونه در زیر نشان داده شده است:
gsutil cp <some-test-doc>.txt gs://<bucket-name>/
نتایج را در BigQuery بررسی کنید
به عنوان بخشی از فرآیند تأیید، بررسی خواهد شد که دادهها در BigQuery نیز ذخیره شدهاند.
به کوئری SQL که برای بررسی اسناد استفاده شده است، توجه کنید.
پس از انجام تأیید، باید ببینید که لیست وظایف تکمیل شده است:
اختیاری: تأیید دستی
اگرچه Antigravity قبلاً برنامه را تأیید کرده است، اما در صورت تمایل میتوانید با دنبال کردن این مراحل، به صورت دستی در کنسول Google Cloud بررسی کنید که آیا همه منابع ایجاد شدهاند یا خیر.
فضای ذخیرهسازی ابری
هدف : تأیید وجود سطل و بررسی فایلهای آپلود شده.
- به فضای ذخیرهسازی ابری > سطلها بروید.
- سطلی با نام
[PROJECT_ID]-doc-uploadsپیدا کنید. - برای مرور فایلها، روی نام باکت کلیک کنید.
- تأیید: شما باید فایلهای آپلود شده خود (مثلاً
test.txt) را ببینید.
میخانه/ساب
هدف : تأیید کنید که موضوع وجود دارد و اشتراک خبرنامه فعال است.
- به «میخانه/فرعی > موضوعات» بروید.
- موضوع پردازش سند را پیدا کنید.
- روی شناسه موضوع کلیک کنید.
- به پایین اسکرول کنید تا به برگه اشتراکها برسید.
- تأیید کنید: مطمئن شوید که doc-processing-sub با نوع تحویل « Push » فهرست شده است.
اجرای ابری
هدف : بررسی وضعیت سرویس و گزارشها.
- به Cloud Run بروید.
- روی پردازشگر سند سرویس کلیک کنید.
- تأیید کنید:
- سلامت: علامت تیک سبز نشان دهنده فعال بودن سرویس است.
- گزارشها: روی برگه گزارشها کلیک کنید. به دنبال ورودیهایی مانند « در حال پردازش فایل: gs://... » و « با موفقیت پردازش شد... » باشید.
بیگکوئری
هدف : اعتبارسنجی دادههای ذخیره شده.
- به BigQuery > SQL Workspace بروید.
- در پنجره اکسپلورر، پروژه خود را باز کنید > pipeline_data dataset .
- روی جدول processed_docs کلیک کنید.
- روی برگه پیشنمایش کلیک کنید.
- تأیید: باید ردیفهایی حاوی filename ، upload_date ، tags و word_count را ببینید.
پیاده روی
به عنوان آخرین مرحله، Antigravity یک مصنوع برای عبور از مراحل ایجاد میکند. این مصنوع به طور خلاصه شامل موارد زیر است:
- تغییرات ایجاد شده.
- دستورات تأیید اجرا میشوند.
- نتایج واقعی (خروجی پرس و جو که فراداده استخراج شده Gemini را نشان میدهد).
برای دیدن آن میتوانید روی Open کلیک کنید. نمونهای از خروجی در زیر نشان داده شده است:
۶. برنامه را بررسی کنید
در این مرحله، برنامهی پایه آماده و در حال اجرا است. قبل از اینکه به سراغ توسعهی بیشتر این برنامه برویم، کمی وقت بگذارید و کد را بررسی کنید. میتوانید با دکمهی Open Editor در گوشهی بالا سمت راست، به ویرایشگر بروید.
در اینجا خلاصهای سریع از فایلهایی که ممکن است ببینید، آورده شده است:
-
setup.sh: اسکریپت اصلی که تمام منابع Google Cloud را فراهم میکند و APIهای مورد نیاز را فعال میکند. -
main.py: نقطه ورودی اصلی خط لوله. این برنامه پایتون یک وب سرور ایجاد میکند که پیامهای Pub/Sub push را دریافت میکند، فایل را از GCS دانلود میکند، آن را "پردازش" (شبیهسازی OCR) میکند و فراداده را به BigQuery ارسال میکند. -
Dockerfile: نحوه بستهبندی برنامه در یک تصویر کانتینر را تعریف میکند. -
requirements.txt: وابستگیهای پایتون را فهرست میکند.
همچنین ممکن است اسکریپتها و فایلهای متنی دیگری را که برای آزمایش و تأیید لازم هستند، مشاهده کنید.
در این مرحله، ممکن است بخواهید از Playground به یک فضای کاری/پوشه اختصاصی منتقل شوید. میتوانید این کار را با کلیک روی دکمه مربوطه در گوشه بالا سمت راست انجام دهید:
پس از انتخاب یک پوشه، تمام کدها به آن پوشه منتقل میشوند و یک فضای کاری جدید با پوشه و تاریخچه مکالمات ایجاد میشود.
۷. درخواست را تمدید کنید
حالا که یک برنامهی کاربردی پایه و کاربردی دارید، میتوانید به تکرار و توسعهی برنامه ادامه دهید. در اینجا چند ایده ارائه شده است.
یک رابط کاربری اضافه کنید
یک رابط وب ساده برای مشاهده اسناد پردازش شده بسازید.
دستور زیر را امتحان کنید: 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 برای استخراج، طبقهبندی و ترجمه استفاده کنید.
- منطق OCR ساختگی را جایگزین کنید. تصویر/PDF را برای استخراج متن و دادههای واقعی به Gemini ارسال کنید. متن استخراج شده را تجزیه و تحلیل کنید تا نوع سند (فاکتور، قرارداد، رزومه) را طبقهبندی کنید یا موجودیتها (تاریخها، نامها، مکانها) را استخراج کنید.
- به طور خودکار زبان سند را تشخیص داده و قبل از ذخیره سازی آن را به انگلیسی ترجمه کنید. میتوانید از هر زبان دیگری نیز استفاده کنید.
افزایش فضای ذخیرهسازی و تجزیه و تحلیل
شما میتوانید قوانین چرخه عمر را روی باکت پیکربندی کنید تا فایلهای قدیمی را به فضای ذخیرهسازی «Coldline» یا «Archive» منتقل کنید تا در هزینهها صرفهجویی شود.
استحکام و امنیت
شما میتوانید برنامه را قویتر و امنتر کنید، مانند:
- صفهای نامههای معوق (DLQ): اشتراک Pub/Sub را برای مدیریت خطاها بهروزرسانی کنید. اگر سرویس Cloud Run 5 بار در پردازش یک فایل ناموفق بود، پیام را برای بررسی انسانی به یک موضوع/سطل جداگانه "نامه معوق" ارسال کنید.
- مدیر مخفی: اگر برنامه شما به کلیدهای API یا پیکربندی حساس نیاز دارد، آنها را در مدیر مخفی ذخیره کنید و به جای رشتههای کدگذاری شده، از طریق Cloud Run به طور ایمن به آنها دسترسی داشته باشید.
- 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
- Codelab: شروع کار با Google Antigravity