1- مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّفون على كيفية استخدام Google Antigravity لتصميم تطبيق بدون خادم وإنشائه ونشره على Google Cloud. سننشئ مسار بيانات بدون خادم ومستند إلى الأحداث للمستندات، حيث يتم استيعاب الملفات من Google Cloud Storage (GCS)، ومعالجتها باستخدام Cloud Run وGemini، وبث بياناتها الوصفية إلى BigQuery.
المواضيع التي ستتعرّفون عليها
- كيفية استخدام Antigravity لتخطيط البنية وتصميمها
- إنشاء البنية الأساسية كرمز (برامج نصية للواجهة) باستخدام وكيل الذكاء الاصطناعي
- إنشاء ونشر خدمة Cloud Run مستندة إلى Python
- دمج Gemini على Vertex AI لتحليل المستندات المتعددة الوسائط
- التحقّق من مسار البيانات الكامل باستخدام عنصر Walkthrough في Antigravity
المتطلبات
- تثبيت Google Antigravity
- مشروع على Google Cloud مفعّلة فيه الفوترة
- gcloud CLI مثبت ومصادق عليه.
2. نظرة عامة على التطبيق
قبل الانتقال إلى تصميم التطبيق وتنفيذه باستخدام Antigravity، لنحدّد أولاً التطبيق الذي نريد إنشاءه.
نريد إنشاء مسار بيانات بدون خادم ومستند إلى الأحداث للمستندات، حيث يتم استيعاب الملفات من Google Cloud Storage (GCS)، ومعالجتها باستخدام Cloud Run وGemini، وبث بياناتها الوصفية إلى BigQuery.
قد يبدو مخطط البنية الأساسية لهذا التطبيق على النحو التالي:

ليس من الضروري أن يكون هذا المخطط دقيقًا. يمكن أن يساعدنا Antigravity في تحديد تفاصيل البنية أثناء تقدمنا. ومع ذلك، من المفيد أن يكون لديك فكرة عن ما تريد إنشاءه. كلما زادت التفاصيل التي يمكنك تقديمها، كانت النتائج التي ستحصل عليها من Antigravity أفضل من حيث البنية والرمز.
3. تخطيط البنية
نحن على استعداد لبدء تخطيط تفاصيل البنية باستخدام Antigravity.
يتفوّق Antigravity في تخطيط الأنظمة المعقدة. بدلاً من كتابة الرمز البرمجي على الفور، يمكننا البدء بتحديد البنية الأساسية واستخدام إحدى الميزات لمساعدة Antigravity في تقييم طلبنا، وطرح أسئلة متابعة علينا، ثم المتابعة في التخطيط والتنفيذ.
بافتراض أنّك شغّلت Antigravity، سننشئ مشروعًا جديدًا لهذا الدرس التطبيقي حول الترميز.
انقر على رمز المشروع الجديد بجانب مختبر Projects ، ثم على New Project كما هو موضّح أدناه:

سيظهر خيار Add Folder كما هو موضّح أدناه:

انقر على الزر Add Folder لإضافة مجلد إلى مشروعك. على جهازي، أنشأت مجلد google-cloud-serverless-app وأضفته إلى هذا المشروع.
يؤدي ذلك إلى فتح محادثة في مشروع google-cloud-serverless-app.
انقر على رمز الإعدادات الرئيسي ⚙️ في أسفل يمين الشاشة وانتقِل إلى إعدادات المشروع المحدّدة. إذا لم يظهر مشروع google-cloud-serverless-app في القائمة، ما عليك سوى إجراء محادثة واحدة ثم العودة إلى إعدادات المشروع.
اضبط إعدادات الوكيل / إعدادات الأمان المُسبَقة على Default وسلوك الوكيل / سياسة مراجعة العناصر على 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 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
لاحظ أنّني طلبت من Antigravity استخدام ما يلي:
- برنامج نصي بسيط لـ gcloud CLI لتوفير الموارد
- إشعارات Pub/Sub الأصلية في Cloud Storage + اشتراك Pub/Sub الفوري في Cloud Run
- استخدام Flask (مع Gunicorn) للإطار
- استخدام المحاكاة المحلية فقط مع ملف نصي للبيانات بدلاً من بيانات التعرّف البصري على الأحرف المباشرة
- استخدام BigQuery table.insert_rows() لإدراج الصفوف في BigQuery
- نشر Cloud Run بدون مصادقة
وخيارات أخرى مقترَحة
خطة التنفيذ وقائمة المهام
سيبدأ Antigravity الآن العمل وإنشاء خطة تنفيذ. سيطلب منك مراجعتها من خلال عرض رسالة مشابهة للرسالة أدناه:

يمكنك النقر على مفتاح "اللوحة الإضافية" في أعلى يسار النافذة وعرض العناصر التي تم إنشاؤها، والتي لا تتضمّن في هذه المرحلة سوى خطة التنفيذ.

توضّح هذه الخطة ما يلي:
- البنية الأساسية: حزمة GCS وموضوع Pub/Sub ومجموعة بيانات BigQuery
- المعالِج: تطبيق Python/Flask وDockerfile والمتطلبات
- التكامل: إشعارات GCS ← Pub/Sub ← Cloud Run.
من المفترض أن يظهر لك شيء مشابه لما يلي. في ما يلي قائمة جزئية بخطة التنفيذ على جهازنا:

يُرجى قراءتها بعناية. هذه فرصتك لتقديم ملاحظاتك حول التنفيذ. يمكنك النقر على أي جزء من خطة التنفيذ وإضافة تعليقات. بعد إضافة بعض التعليقات، احرص على إرسال أي تغييرات تريد رؤيتها للمراجعة، خاصةً ما يتعلق بالتسمية ورقم تعريف مشروع Google Cloud والمنطقة وما إلى ذلك.
بعد التأكّد من أنّ كل شيء يبدو جيدًا، امنح الوكيل الإذن بالمتابعة في خطة التنفيذ من خلال النقر على الزر Proceed.
4. إنشاء التطبيق
بعد الموافقة على الخطة، يبدأ Antigravity في إنشاء الملفات المطلوبة للتطبيق، بدءًا من النصوص البرمجية لتوفير الموارد وصولاً إلى الرمز البرمجي للتطبيق.
سينشئ Antigravity مجلدًا ويبدأ في إنشاء الملفات اللازمة للمشروع. إذا اطّلعت على العناصر، ستلاحظ إنشاء عدة ملفات (رمز المصدر وملفات النصوص البرمجية وما إلى ذلك).

بعد اكتمال عمله، سيشير إلى ذلك وينشئ مستند Walkthrough يمكنك الاطّلاع عليه. في ما يلي نموذج للناتج:

يذكر مستند Walkthrough ما تم تنفيذه، والنصوص البرمجية التي تم إنشاؤها، والأهم من ذلك، عمليات التحقّق من الصحة والتحقّق التي تم إجراؤها. في ما يلي ناتج جزئي لمستند Walkthrough يتضمّن عمليات التحقّق من الصحة والتحقّق:
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
يمكننا أن نسأل Antigravity عن كيفية نشر هذا التطبيق على Google Cloud. سيعرض تفاصيل كاملة عن ذلك كما هو موضّح أدناه. باختصار، يطلب منا التأكّد من تثبيت Google Cloud SDK وإعداد مشروع على السحابة الإلكترونية. بعد الانتهاء من ذلك،
الخطوة 1: تفعيل واجهات برمجة التطبيقات المطلوبة على Google Cloud
نفِّذ setup_gcp.sh لتفعيل واجهات برمجة التطبيقات Cloud Run وPub/Sub وCloud Storage وBigQuery وCloud Build: ./scripts/setup_gcp.sh
الخطوة 2: تفعيل مسار التعلّم بالكامل
نفِّذ deploy.sh:
export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1" # or your region
./scripts/deploy.sh
في ما يلي ما يفعله هذا النص البرمجي وراء الكواليس:
- ينشئ صورة الحاوية باستخدام Google Cloud Build ويدفعها إلى Container/Artifact Registry.
- ينشر الخدمة على Cloud Run باستخدام متغيرات البيئة المناسبة (
GCP_PROJECTوBQ_DATASET_IDوBQ_TABLE_ID). - ينشئ حزمة استيعاب Cloud Storage (
gs://<PROJECT_ID>-document-ingest). - ينشئ موضوع Pub/Sub (
document-upload-events) ويمنح GCS إذن النشر فيه. - يضبط إشعار GCS (
OBJECT_FINALIZE) على الحزمة. - ينشئ اشتراكًا فوريًا في Pub/Sub يستهدف عنوان URL لخدمة Cloud Run مع إعادة المحاولة تلقائيًا.
يقترح أيضًا كيفية اختبار مسار التعلّم.
نفِّذ test_pipeline.sh: ./scripts/test_pipeline.sh
يؤدي ذلك إلى تحميل samples/sample_contract.txt وsamples/sample_invoice.pdf إلى حزمتك، وينتظر المعالجة، وينفّذ طلب بحث SQL في BigQuery يعرض البيانات الوصفية المستخرَجة وعدد الكلمات والعلامات.
5. نشر التطبيق
لننشر التطبيق كما هو موضّح. يمكننا أن نطلب من Antigravity تنفيذ ذلك نيابةً عنا، ولكن قبل ذلك، تأكّد من توفُّر gcloud CLI وإعداده لمشروع Google Cloud.
يمكننا تقديم طلب إلى Antigravity "Deploy the application for me". سيطلب منك ذلك أذونات مختلفة ثم سيتابع تنفيذ ملفات النصوص البرمجية.
يبدأ العملية كمهمة في الخلفية، كما هو موضّح في الرسالة أدناه:
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. التحقّق من التطبيق
بعد نشر مسار البيانات، يبدأ Antigravity في التحقّق من أنّ التطبيق يعمل فعلاً. يسألنا ما إذا كان بإمكانه تشغيل الملف test_pipeline.sh. يمكننا المتابعة ومنحه الإذن.
يخبرنا أخيرًا بما يلي:
🚀 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.
عدّل أيضًا عنصر Walkthrough لعرض النتائج (القائمة الجزئية موضّحة أدناه):
ملخّص النشر
- مشروع Google Cloud: PROJECT_ID
- المنطقة: REGION
- خدمة Cloud Run: document-processor
- نقطة نهاية Cloud Run: SERVICE_URL
- حزمة Cloud Storage: gs://PROJECT_ID-document-ingest
- موضوع Pub/Sub: document-upload-events
- اشتراك Pub/Sub الفوري: document-upload-events-push-sub
- هدف BigQuery: PROJECT_ID.document_processing.document_metadata
التحقّق من مسار البيانات المباشر
نفّذنا scripts/test_pipeline.sh على بيئة Google Cloud المباشرة:
- تم تحميل sample_contract.txt وsample_invoice.pdf إلى حزمة Cloud Storage.
- أنشأ GCS أحداث OBJECT_FINALIZE في Pub/Sub.
- دفعت خدمة Pub/Sub الرسائل إلى خدمة Cloud Run المصغّرة.
- استخرجت Cloud Run البيانات الوصفية، وعالجت التعرّف البصري على الأحرف المحاكى، وبثت السجلات إلى BigQuery.
ناتج طلب بحث BigQuery المباشر
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| 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 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
كل مكوّنات مسار البيانات نشطة وسليمة وتم التحقّق منها في مرحلة الإنتاج.
اختياري: التحقّق يدويًا
على الرغم من أنّ Antigravity قد تحقّق من التطبيق، يمكنك أيضًا التحقّق يدويًا في Google Cloud Console من أنّ جميع الموارد قد تم إنشاؤها، إذا أردت، باتّباع الخطوات التالية.
Cloud Storage
الهدف: التأكّد من توفُّر الحزمة والبحث عن الملفات المحمّلة
- انتقِل إلى Cloud Storage > الحِزم.
- حدِّد موقع الحزمة المسماة
PROJECT_ID-document-processing. - انقر على اسم الحزمة لتصفّح الملفات.
- تأكّد من ظهور الملفات التي حمّلتها (مثل
sample_contract.txt).
Pub/Sub
الهدف: التأكّد من توفُّر الموضوع وأنّه يتضمّن اشتراكًا فوريًا
- انتقِل إلى Pub/Sub > المواضيع.
- ابحث عن document-uploads-events.
- انقر على رقم تعريف الموضوع.
- انتقِل للأسفل إلى علامة التبويب الاشتراكات.
- تأكّد من إدراج doc-uploads-events-push-sub.
Cloud Run
الهدف: التحقّق من حالة الخدمة وسجلّاتها
- انتقِل إلى Cloud Run.
- انقر على الخدمة document-processor.
- تأكّد مما يلي:
- الحالة: علامة صح خضراء تشير إلى أنّ الخدمة نشطة.
- السجلّات: انقر على علامة التبويب "السجلّات". ابحث عن إدخالات مثل "Processing document: gs://..." و "Successfully streamed metadata...".
BigQuery
الهدف: التأكّد من أنّ البيانات مخزّنة فعلاً
- انتقِل إلى BigQuery > SQL Workspace.
- في لوحة "المستكشف"، وسِّع مشروعك > مجموعة بيانات document_processing.
- انقر على جدول document_metadata.
- انقر على علامة التبويب طلب البحث واسترجِع جميع الصفوف من الجدول باستخدام عبارة SELECT *.
- تأكّد من ظهور صفوف تحتوي على file_name وprocess_at وtags وword_count.
7. استكشاف التطبيق
في هذه المرحلة، يكون لديك التطبيق الأساسي الذي تم توفيره وتشغيله. قبل الانتقال إلى توسيع هذا التطبيق أكثر، خذ بعض الوقت لاستكشاف الرمز. يمكنك عرض العناصر وسيظهر لك ملفات الرمز التي تم إنشاؤها.
في ما يلي ملخص سريع لبعض الملفات التي قد تظهر لك:
deploy.sh: النص البرمجي الرئيسي الذي يوفّر جميع موارد Google Cloud ويُفعِّل واجهات برمجة التطبيقات المطلوبةmain.py: نقطة الدخول الرئيسية لمسار البيانات ينشئ تطبيق Python هذا خادم ويب يتلقّى رسائل Pub/Sub الفورية، وينزِّل الملف من GCS، و"يعالجه" (يحاكي التعرّف البصري على الأحرف)، ويبث البيانات الوصفية إلى BigQuery.Dockerfile: يحدّد كيفية تجميع التطبيق في صورة حاوية.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
التكامل مع الذكاء الاصطناعي/التعلم الآلي الحقيقيَين
بدلاً من معالجة التعرّف البصري على الأحرف المحاكى، استخدِم نماذج Gemini لاستخراج البيانات وتصنيفها وترجمتها.
- استبدِل منطق التعرّف البصري على الأحرف الوهمي. أرسِل الصورة أو ملف PDF إلى Gemini لاستخراج النص والبيانات الفعلية. حلِّل النص المستخرَج لتصنيف نوع المستند (فاتورة أو عقد أو سيرة ذاتية) أو استخراج الكيانات (التواريخ والأسماء والمواقع الجغرافية).
- تعرَّف تلقائيًا على لغة المستند وترجمها إلى الإنجليزية قبل تخزينها. يمكنك أيضًا استخدام أي لغة أخرى.
تحسين التخزين والإحصاءات
يمكنك ضبط قواعد دورة الحياة على الحزمة لنقل الملفات القديمة إلى مساحة التخزين "Coldline" أو "Archive" لتوفير التكاليف.
المتانة والأمان
يمكنك جعل التطبيق أكثر متانة وأمانًا، على سبيل المثال:
- قوائم انتظار الرسائل غير القابلة للتسليم (DLQ): عدِّل اشتراك Pub/Sub للتعامل مع حالات الفشل. إذا تعذّر على خدمة Cloud Run معالجة ملف 5 مرات، أرسِل الرسالة إلى موضوع أو حزمة منفصلَين باسم "الرسائل غير القابلة للتسليم" ليتم فحصها يدويًا.
- Secret Manager: إذا كان تطبيقك يحتاج إلى مفاتيح واجهة برمجة التطبيقات أو إعدادات حساسة، خزِّنها في Secret Manager واطّلِع عليها بأمان من Cloud Run بدلاً من ترميز السلاسل بشكل ثابت.
- Eventarc: يمكنك الترقية من Pub/Sub المباشر إلى Eventarc للحصول على توجيه أكثر مرونة للأحداث، ما يتيح لك تشغيل الأحداث استنادًا إلى سجلّات التدقيق المعقدة أو أحداث خدمات Google Cloud الأخرى.
بالطبع، يمكنك ابتكار أفكارك الخاصة واستخدام Antigravity لمساعدتك في تنفيذها.
9. الخاتمة
لقد أنشأت بنجاح مسار بيانات قابل للتطوير وبدون خادم ومستند إلى الذكاء الاصطناعي للمستندات في دقائق باستخدام Google Antigravity. لقد تعلّمت كيفية:
- تخطيط البنى باستخدام الذكاء الاصطناعي
- إعطاء التعليمات إلى Antigravity وإدارته أثناء عمله على إنشاء التطبيق، بدءًا من إنشاء الرمز وصولاً إلى النشر والتحقّق من الصحة
- التحقّق من عمليات النشر والتحقّق من الصحة باستخدام Walkthroughs
المستندات المرجعية
- الموقع الإلكتروني الرسمي : https://antigravity.google/
- الوثائق: https://antigravity.google/docs
- حالات الاستخدام : https://antigravity.google/use-cases
- التنزيل : https://antigravity.google/download