1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام Google Antigravity (يُشار إليه باسم Antigravity في بقية المستند) لتصميم تطبيق بدون خادم وإنشائه ونشره على Google Cloud. سننشئ مسار مستندات بلا خادم يستند إلى الأحداث، ويستوعب الملفات من Google Cloud Storage (GCS)، ويعالجها باستخدام Cloud Run وGemini، ويبث البيانات الوصفية الخاصة بها إلى BigQuery.
ما ستتعلمه
- كيفية استخدام Antigravity في التخطيط المعماري والتصميم
- إنشاء برامج وتطبيقات البنية الأساسية (برامج نصية shell) باستخدام وكيل يعمل بالذكاء الاصطناعي
- إنشاء خدمة Cloud Run مستندة إلى Python ونشرها
- دمج Gemini على Vertex AI لتحليل المستندات المتعدّدة الوسائط
- تحقَّق من صحة مسار العرض الكامل باستخدام عنصر Walkthrough من Antigravity.
المتطلبات
- تثبيت Google Antigravity إذا كنت بحاجة إلى مساعدة في تثبيت Antigravity وفهم الأساسيات، ننصحك بإكمال تجربة البرمجة: البدء باستخدام Google Antigravity.
- مشروع Google Cloud تم تفعيل الفوترة فيه
- تم تثبيت gcloud CLI والمصادقة عليه.
2. نظرة عامة على التطبيق
قبل أن نبدأ في تصميم التطبيق وتنفيذه باستخدام Antigravity، دعنا أولاً نحدّد التطبيق الذي نريد إنشاءه لأنفسنا.
نريد إنشاء مسار مستندات بدون خادم يستند إلى الأحداث، ويستوعب الملفات من Google Cloud Storage (GCS)، ويعالجها باستخدام Cloud Run وGemini، ويبث بياناتها الوصفية إلى BigQuery.
يمكن أن يبدو مخطط البنية العالية المستوى لهذا التطبيق على النحو التالي:
ليس من الضروري أن تكون هذه القيمة دقيقة. يمكن أن تساعدنا Antigravity في معرفة تفاصيل التصميم أثناء التنفيذ. ومع ذلك، من المفيد أن تكون لديك فكرة عمّا تريد إنشاءه. كلّما زادت التفاصيل التي يمكنك تقديمها، كانت النتائج التي ستحصل عليها من Antigravity أفضل من حيث التصميم والرمز البرمجي.
3- تخطيط البنية
نحن على استعداد لبدء التخطيط لتفاصيل البنية باستخدام Antigravity.
تتفوق Antigravity في تخطيط الأنظمة المعقدة. بدلاً من كتابة الرمز البرمجي على الفور، يمكننا البدء بتحديد البنية عالية المستوى.
أولاً، تأكَّد من أنّك في "مدير الوكلاء". إذا فتحت Antigravity للتو، يمكنك النقر على الزر Open Agent Manager في الوسط أو على الزر نفسه في أعلى يسار الشاشة.Open Agent Manager
في "أداة إدارة العملاء"، يمكنك فتح مساحة عمل أو استخدام "ساحة التدريب"، وهي مساحة عمل مستقلة لإنشاء نماذج أولية سريعة وتجربتها. لنبدأ بـ 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.
قائمة المهام وخطة التنفيذ
ستحلّل Antigravity طلبك وتنشئ قائمة بالمهام وخطة التنفيذ.
توضّح هذه الخطة ما يلي:
- البنية الأساسية: حزمة GCS، وموضوع Pub/Sub، ومجموعة بيانات BigQuery
- المعالِج: تطبيق Python/Flask، وملف Dockerfile، وملف Requirements
- عملية الدمج: إشعارات GCS → Pub/Sub → Cloud Run
من المفترض أن يظهر لك ما يلي:
انقر على الزر Open بجانب الصف Task. من المفترض أن يعرض لك ذلك مجموعة من المهام التي أنشأتها Antigravity. سيراجع الوكيل هذه الطلبات واحدًا تلو الآخر:
الخطوة التالية هي مراجعة خطة التنفيذ ومنح الوكيل الإذن بالمتابعة.
انقر على خطة التنفيذ للاطّلاع على تفاصيلها. يُرجى قراءته بعناية. هذه هي فرصتك لتقديم ملاحظاتك بشأن عملية التنفيذ. يمكنك النقر على أي جزء من خطة التنفيذ وإضافة تعليقات. بعد إضافة بعض التعليقات، احرص على إرسال أي تغييرات تريد رؤيتها للمراجعة، خاصةً تلك المتعلّقة بالتسمية ومعرّف مشروع Google Cloud والمنطقة وما إلى ذلك.
بعد التأكّد من أنّ كل المعلومات صحيحة، امنح الموظف الإذن بالمتابعة في تنفيذ خطة التنفيذ من خلال النقر على الزر Proceed.
4. إنشاء التطبيق
بعد الموافقة على الخطة، تبدأ Antigravity في إنشاء الملفات المطلوبة للتطبيق، بدءًا من نصوص توفير المتطلبات إلى رمز التطبيق.
سيُنشئ Antigravity مجلدًا ويبدأ في إنشاء الملفات اللازمة للمشروع. في عملية التشغيل النموذجية، لاحظنا ما يلي:
يتم إنشاء ملف نص برمجي shell باسم setup.sh أو اسم مشابه، ما يؤدي إلى إتمام عملية إنشاء المورد تلقائيًا. يتعامل مع:
- تفعيل واجهات برمجة التطبيقات (
runوpubsubوbigqueryوstorage) - إنشاء حزمة Google Cloud Storage (
doc-ingestion-{project-id}) - إنشاء مجموعة بيانات وجدول في BigQuery (
pipeline_data.processed_docs) - ضبط مواضيع Pub/Sub والإشعارات
يجب أن ينشئ الوكيل تطبيق Python (main.py) يستمع إلى رسائل الدفع في Pub/Sub. تستخدم هذه الأداة منطق التعرّف الضوئي على الحروف المحاكى، ما يؤدي إلى إنشاء عدد عشوائي من الكلمات والعلامات وحفظها في BigQuery.
بعد إنشاء نص الإعداد هذا، من المفترض أن يطلب منك Antigravity تنفيذ النص البرمجي نيابةً عنك. يظهر أدناه نموذج للشاشة:
انقر على Accept حسب الحاجة.
سينشئ النص البرمجي للتوفير الموارد ويتأكّد من إنشائها. بعد إجراء عملية التحقّق بنجاح، سيتم الانتقال إلى إنشاء الحاوية ونشرها كخدمة (في main.py) في Cloud Run. يظهر أدناه نموذج للناتج:
وكجزء من نشر الخدمة، سيتم أيضًا إعداد اشتراكات Pub/Sub وغيرها من العناصر الأساسية المطلوبة لتشغيل خط الأنابيب هذا. من المفترَض أن يستغرق كل ذلك بضع دقائق.
في الوقت الحالي، يمكنك التبديل إلى Inbox (من أعلى يمين الصفحة)، والاطّلاع على المهام Pending التي تنتظر إدخالك:
هذه طريقة جيدة لضمان الموافقة على المهام أثناء طلب الوكيل للحصول على ملاحظاتك.
5- التحقّق من التطبيق
بعد نشر خطوة المعالجة، تتحقّق Antigravity من أنّ التطبيق يعمل بالفعل. تنفّذ Antigravity هذه العملية تلقائيًا من خلال خطوات التحقّق في قائمة المهام. يظهر أدناه نموذج للشاشة:
ينشئ هذا الأمر عنصر اختبار (test.txt) ويريد تحميله إلى حزمة Google Cloud Storage. انقر على Accept للمتابعة.
إذا أردت إجراء المزيد من الاختبارات بنفسك، يمكنك الاستفادة من خطوة التحقّق في Antigravity، حيث تستخدم الأداة المساعدة gsutil لتحميل ملف نموذجي إلى حزمة Cloud Storage. يظهر نموذج الأمر أدناه:
gsutil cp <some-test-doc>.txt gs://<bucket-name>/
التحقّق من النتائج في BigQuery
وكجزء من عملية التحقّق، سيتم أيضًا التأكّد من استمرار البيانات في BigQuery.
دوِّن استعلام SQL الذي تم استخدامه للبحث عن المستندات.
بعد اكتمال عملية التحقّق، من المفترض أن تظهر لك قائمة المهام على النحو التالي:
اختياري: إثبات الملكية يدويًا
على الرغم من أنّ Antigravity قد تحقّقت من التطبيق، يمكنك أيضًا التحقّق يدويًا في Google Cloud Console من إنشاء جميع الموارد، إذا أردت ذلك، باتّباع الخطوات التالية.
Cloud Storage
الهدف: التأكّد من توفّر الحزمة والبحث عن الملفات التي تم تحميلها
- انتقِل إلى Cloud Storage > الحِزم.
- ابحث عن الحزمة المسماة
[PROJECT_ID]-doc-uploads. - انقر على اسم الحزمة لتصفّح الملفات.
- تحقَّق من ظهور الملفات التي حمّلتها (مثل
test.txt).
نشر/اشتراك
الهدف: التأكّد من توفُّر الموضوع ومن حصوله على اشتراك في الإشعارات الفورية
- انتقِل إلى النشر/الاشتراك > المواضيع.
- ابحث عن doc-processing-topic.
- انقر على رقم تعريف الموضوع.
- انتقِل للأسفل إلى علامة التبويب الاشتراكات.
- تحقَّق من أنّ doc-processing-sub مدرَج مع نوع التسليم "Push".
Cloud Run
الهدف: التحقّق من حالة الخدمة وسجلّاتها
- انتقِل إلى Cloud Run.
- انقر على الخدمة doc-processor.
- يجب إثبات ما يلي:
- الحالة: علامة اختيار خضراء تشير إلى أنّ الخدمة نشطة.
- السجلات: انقر على علامة التبويب "السجلات". ابحث عن إدخالات مثل "جارٍ معالجة الملف: gs://..." و "تمت المعالجة بنجاح...".
BigQuery
الهدف: التأكّد من تخزين البيانات فعليًا.
- انتقِل إلى BigQuery > SQL Workspace.
- في جزء "المستكشف"، وسِّع المشروع > مجموعة بيانات pipeline_data.
- انقر على جدول processed_docs.
- انقر على علامة التبويب معاينة.
- التحقّق: من المفترض أن تظهر لك صفوف تحتوي على اسم الملف وتاريخ التحميل والعلامات وعدد الكلمات.
جولة تفصيلية
في الخطوة الأخيرة، تنشئ Antigravity عنصرًا اصطناعيًا يقدّم جولة إرشادية. يلخّص هذا العنصر ما يلي:
- تم إجراء تغييرات.
- يتم تنفيذ أوامر التحقّق.
- النتائج الفعلية (ناتج طلب البحث الذي يعرض البيانات الوصفية المستخرَجة من Gemini)
يمكنك النقر على Open للاطّلاع عليه. يظهر أدناه نموذج للناتج:
6. استكشاف التطبيق
في هذه المرحلة، يكون لديك تطبيق أساسي تم توفيره وتشغيله. قبل التوسّع في هذا التطبيق، خذ بعض الوقت لاستكشاف الرمز. يمكنك التبديل إلى المحرّر باستخدام الزر Open Editor في أعلى يسار الصفحة.
في ما يلي ملخّص سريع للملفات التي قد تظهر لك:
setup.sh: النص البرمجي الرئيسي الذي يوفّر جميع موارد Google Cloud ويفعّل واجهات برمجة التطبيقات المطلوبة.-
main.py: نقطة الدخول الرئيسية إلى مسار العرض ينشئ تطبيق Python هذا خادم ويب يتلقّى رسائل دفع Pub/Sub، وينزّل الملف من GCS، و"يعالجه" (يحاكي التعرّف البصري على الأحرف)، ويبث البيانات الوصفية إلى BigQuery. -
Dockerfile: تحدّد كيفية تجميع التطبيق في صورة حاوية. -
requirements.txt: تعرض هذه السمة قائمة بملفات Python المطلوبة.
قد تظهر لك أيضًا نصوص برمجية أخرى وملفات نصية مطلوبة للاختبار والتحقّق.
في هذه المرحلة، قد تحتاج أيضًا إلى الانتقال من Playground إلى مساحة عمل أو مجلد مخصّص. يمكنك إجراء ذلك من خلال النقر على الزر ذي الصلة في أعلى يسار الصفحة:
بعد اختيار مجلد، سيتم نقل كل الرمز إلى هذا المجلد وسيتم إنشاء مساحة عمل جديدة تتضمّن المجلد وسجلّ المحادثات.
7. تمديد فترة التطبيق
بعد أن أصبح لديك تطبيق أساسي يعمل، يمكنك مواصلة تكرار التطبيق وتوسيعه. في ما يلي بعض الأفكار.
إضافة واجهة مستخدم
أنشئ واجهة ويب بسيطة لعرض المستندات المعالَجة.
جرِّب الطلب التالي: 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 لمساعدتك في تنفيذها.
8. الخاتمة
لقد أنشأت بنجاح مسار مستندات قابلاً للتوسّع وبدون خادم ومستندًا إلى الذكاء الاصطناعي في غضون دقائق باستخدام Google Antigravity. لقد تعلّمت كيفية:
- تخطيط البنى باستخدام الذكاء الاصطناعي
- يمكنك توجيه Antigravity وإدارته أثناء عمله على إنشاء التطبيق، بدءًا من إنشاء الرمز البرمجي ووصولاً إلى النشر والتحقّق.
- التحقّق من عمليات النشر والتحقّق من الصحة باستخدام "الجولات الإرشادية"
المستندات المرجعية
- الموقع الإلكتروني الرسمي : https://antigravity.google/
- المستندات: https://antigravity.google/docs
- حالات الاستخدام : https://antigravity.google/use-cases
- تنزيل : https://antigravity.google/download
- درس تطبيقي حول الترميز : بدء استخدام Google Antigravity