Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

إنشاء التطبيقات ونشرها على Google Cloud باستخدام Antigravity

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية استخدام Google Antigravity لتصميم تطبيق بدون خادم وإنشائه ونشره على Google Cloud. سننشئ مسار بيانات مستندًا إلى الأحداث وبدون خادم، وهو مسار يستوعب الملفات من Google Cloud Storage (GCS)، ويعالجها باستخدام Cloud Run وGemini، ويبث بياناتها الوصفية إلى BigQuery.

ما ستتعلمه

كيفية استخدام Antigravity في التخطيط المعماري والتصميم
إنشاء برامج وتطبيقات البنية الأساسية (برامج نصية shell) باستخدام وكيل يعمل بالذكاء الاصطناعي
إنشاء خدمة 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 أفضل من حيث البنية والرمز.

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 أن يختار:

نص برمجي بسيط لواجهة سطر الأوامر gcloud لتوفير الموارد
إشعارات Pub/Sub الأصلية في Cloud Storage + اشتراك Pub/Sub Push في Cloud Run
استخدام Flask (مع Gunicorn) كإطار عمل
ما عليك سوى استخدام المحاكاة المحلية مع ملف نصي للبيانات بدلاً من بيانات التعرّف البصري على الأحرف المباشرة
استخدِم BigQuery table.insert_rows() لإدراج صفوف في BigQuery
نشر Cloud Run بدون مصادقة

وخيارات أخرى مقترَحة.

خطة التنفيذ وقائمة المهام

سيبدأ Antigravity الآن العمل وإنشاء خطة تنفيذ. سيتم عرضها لتراجعها من خلال إرسال رسالة مشابهة للرسالة أدناه:

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

توضّح هذه الخطة ما يلي:

البنية الأساسية: حزمة GCS، وموضوع Pub/Sub، ومجموعة بيانات BigQuery
المعالِج: تطبيق Python/Flask وDockerfile وRequirements
عملية الدمج: إشعارات 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. سينفّذ الوكيل هذه المهام واحدة تلو الأخرى. يتم عرض نموذج لقائمة المهام أدناه:

4. إنشاء التطبيق

بعد الموافقة على الخطة، تبدأ Antigravity في إنشاء الملفات المطلوبة للتطبيق، بدءًا من نصوص توفير المتطلبات إلى الرمز البرمجي للتطبيق.

سيُنشئ Antigravity مجلدًا ويبدأ في إنشاء الملفات اللازمة للمشروع. إذا اطّلعت على "العناصر"، ستلاحظ إنشاء عدة ملفات (رمز المصدر وملفات البرامج النصية وما إلى ذلك).

بعد انتهاء الأداة من عملها، ستشير إلى ذلك وستنشئ مستند شرح يمكنك الاطّلاع عليه. في هذا القسم، يتم ذكر الخطوة التالية التي يجب أن يتّخذها المستخدم، وفي ما يلي مثال على ذلك:

نشر مسار التعلّم: تأكَّد من تسجيل الدخول إلى واجهة سطر الأوامر في Google Cloud Platform وضبط مشروعك المستهدَف، ثم نفِّذ الأمر التالي: ./ deploy.sh
تشغيل اختبار شامل: نفِّذ نص برمجي لاختبار التكامل مع السحابة الإلكترونية للتأكّد من أنّ تحميل ملف يؤدي إلى تشغيل معالجة Cloud Run وبث البيانات الوصفية إلى BigQuery:./test_cloud.sh
التنظيف: بعد الانتهاء من الاختبار، يُرجى الرجوع إلى أوامر التنظيف README.md لإزالة الموارد التي تم إنشاؤها وتجنُّب تحمّل أي رسوم.

سيتم إنشاء ملف نص برمجي shell باسم deploy.sh أو اسم مشابه، ما يؤدي إلى تشغيل عملية إنشاء الموارد تلقائيًا، ويتولّى هذا الملف ما يلي:

تفعيل واجهات برمجة التطبيقات (run وpubsub وbigquery وstorage)
إنشاء حزمة Google Cloud Storage (document-processing-ingest-{project-id})
إنشاء مجموعة بيانات وجدول BigQuery (document_processing.processed_metadata)
ضبط مواضيع Pub/Sub والإشعارات

5- نشر التطبيق

لننفّذ عملية نشر التطبيق كما هو موضّح باستخدام الأمر ./ deploy.sh. يمكننا أن نطلب من Antigravity تنفيذ ذلك نيابةً عنا، ولكن قبل ذلك، تأكَّد من توفّر gcloud CLI وإعداده لمشروع 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.

يمكننا فتح عنصر 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 Console من إنشاء جميع الموارد، إذا أردت ذلك، باتّباع الخطوات التالية.

Cloud Storage

الهدف: التأكّد من توفّر الحزمة والبحث عن الملفات التي تم تحميلها.

انتقِل إلى Cloud Storage > الحِزم.
ابحث عن الحزمة المسماة document-processing-ingest-{project-id}.
انقر على اسم الحزمة لتصفُّح الملفات.
تحقَّق: من المفترض أن تظهر لك الملفات التي حمّلتها (مثلcloud_test_sample.txt).

Pub/Sub

الهدف: التأكّد من توفُّر الموضوع ومن حصوله على اشتراك في الإشعارات الفورية

انتقِل إلى Pub/Sub > المواضيع.
ابحث عن document-uploads-topic.
انقر على رقم تعريف الموضوع.
انتقِل للأسفل إلى علامة التبويب الاشتراكات.
تحقَّق من أنّ doc-uploads-sub مُدرَج مع نوع التسليم "إرسال".

Cloud Run

الهدف: التحقّق من حالة الخدمة وسجلّاتها

انتقِل إلى Cloud Run.
انقر على خدمة document-processor.
يجب التأكّد مما يلي:
الحالة: علامة اختيار خضراء تشير إلى أنّ الخدمة نشطة.
السجلّات: انقر على علامة التبويب "السجلّات". ابحث عن إدخالات مثل "جارٍ معالجة الملف: gs://‎..." و"تم الإدراج بنجاح...".

BigQuery

الهدف: التأكّد من تخزين البيانات فعليًا.

انتقِل إلى BigQuery > SQL Workspace.
في جزء "المستكشف"، وسِّع المشروع > مجموعة بيانات document_processing.
انقر على جدول processed_metadata.
انقر على علامة التبويب الاستعلام واستردِد جميع الصفوف من الجدول من خلال عبارة SELECT *.
تحقَّق من ذلك: من المفترض أن ترى صفوفًا تحتوي على اسم الملف والطابع الزمني للمعالجة والعلامات وعدد الكلمات.

7. استكشاف التطبيق

في هذه المرحلة، يكون لديك تطبيق أساسي تم توفيره وتشغيله. قبل التوسّع في هذا التطبيق، خذ بعض الوقت لاستكشاف الرمز. يمكنك الاطّلاع على "النتائج"، ومن المفترض أن تظهر لك ملفات الرمز البرمجي التي تم إنشاؤها.

في ما يلي ملخّص سريع للملفات التي قد تظهر لك:

deploy.sh: النص البرمجي الرئيسي الذي يوفّر جميع موارد Google Cloud ويفعّل واجهات برمجة التطبيقات المطلوبة.
‫appy.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" أو "الأرشيف" لتوفير التكاليف.

المتانة والأمان

يمكنك جعل التطبيق أكثر فعالية وأمانًا، مثل:

قوائم انتظار الرسائل غير الصالحة (DLQ): عدِّل اشتراك Pub/Sub للتعامل مع حالات الفشل. إذا تعذّر على خدمة Cloud Run معالجة ملف 5 مرات، أرسِل الرسالة إلى موضوع/حزمة "رسائل غير صالحة" منفصلة لكي يفحصها أحد الموظفين.
‫Secret Manager: إذا كان تطبيقك يحتاج إلى مفاتيح واجهة برمجة تطبيقات أو إعدادات حساسة، خزِّنها في Secret Manager واطّلِع عليها بأمان من Cloud Run بدلاً من ترميز السلاسل.
‫Eventarc: يمكنك الترقية من Pub/Sub المباشر إلى Eventarc للحصول على توجيه أكثر مرونة للأحداث، ما يتيح لك تشغيل الأحداث استنادًا إلى سجلّات تدقيق معقّدة أو أحداث أخرى من خدمات Google Cloud Platform.

بالطبع، يمكنك ابتكار أفكارك الخاصة واستخدام Antigravity لمساعدتك في تنفيذها.

9- الخاتمة

لقد أنشأت بنجاح مسار مستندات قابلاً للتوسّع وبلا خادم ومستندًا إلى الذكاء الاصطناعي في غضون دقائق باستخدام Google Antigravity. لقد تعلّمت كيفية:

تخطيط البنى باستخدام الذكاء الاصطناعي
إصدار التعليمات إلى Antigravity وإدارته أثناء عمله على إنشاء التطبيق، بدءًا من إنشاء الرموز البرمجية إلى النشر والتحقّق
التحقّق من عمليات النشر والتحقّق من الصحة باستخدام "الجولات الإرشادية"

المستندات المرجعية

الموقع الإلكتروني الرسمي : https://antigravity.google/
المستندات: https://antigravity.google/docs
حالات الاستخدام : https://antigravity.google/use-cases
تنزيل : https://antigravity.google/download