פיתוח ופריסה ב-Google Cloud באמצעות Antigravity

1. מבוא

בשיעור Codelab הזה נלמד איך להשתמש ב-Google Antigravity כדי לתכנן, ליצור ולפרוס אפליקציה ללא שרת ב-Google Cloud. ניצור פייפליין של מסמכים ללא שרת שמבוסס על אירועים, שקולט קבצים מ-Google Cloud Storage ‏ (GCS), מעבד אותם באמצעות Cloud Run ו-Gemini, ומזרים את המטא-נתונים שלהם ל-BigQuery.

מה תלמדו

• איך משתמשים ב-Antigravity לתכנון ולעיצוב של ארכיטקטורה.
• יצירת תשתית כקוד (סקריפטים של מעטפת) באמצעות סוכן AI.
• פיתוח ופריסה של שירות Cloud Run מבוסס Python.
• שילוב של Gemini ב-Vertex AI לניתוח מולטי-מודאלי של מסמכים.
• מאמתים את צינור הנתונים מקצה לקצה באמצעות ארטיפקט ההדרכה של Antigravity.

מה תצטרכו

• Google Antigravity מותקן.
• פרויקט ב-Google Cloud שהחיוב בו מופעל.
• ה-CLI של gcloud מותקן ומאומת.

2. סקירה כללית של האפליקציה

לפני שנתחיל לתכנן וליישם את האפליקציה באמצעות Antigravity, נגדיר קודם את האפליקציה שאנחנו רוצים ליצור.

אנחנו רוצים ליצור פייפליין לעיבוד מסמכים בלי שרתים שמבוסס על אירועים. הצינור הזה יקבל קבצים מ-Google Cloud Storage ‏ (GCS), יעבד אותם באמצעות Cloud Run ו-Gemini ויזרים את המטא-נתונים שלהם ל-BigQuery.

דיאגרמת ארכיטקטורה כללית של האפליקציה יכולה להיראות כך:

לא צריך להיות מדויקים. Antigravity יכול לעזור לנו להבין את פרטי הארכיטקטורה תוך כדי התהליך. עם זאת, כדאי שתהיה לכם תמונה כללית של מה שאתם רוצים לבנות. ככל שתספקו יותר פרטים, כך התוצאות שתקבלו מ-Antigravity יהיו טובות יותר מבחינת הארכיטקטורה והקוד.

3. תכנון הארכיטקטורה

אנחנו מוכנים להתחיל לתכנן את פרטי הארכיטקטורה באמצעות Antigravity!

‫Antigravity מצטיין בתכנון מערכות מורכבות. במקום לכתוב קוד באופן מיידי, אנחנו יכולים להתחיל בהגדרת הארכיטקטורה ברמה גבוהה ולהשתמש באחת מהתכונות כדי לעזור ל-Antigravity להעריך את הבקשה שלנו, לשאול אותנו שאלות המשך ואז להמשיך בתכנון וביישום.

נניח שהפעלתם את Antigravity, עכשיו ניצור פרויקט חדש בשביל ה-codelab הזה.

לוחצים על סמל הפרויקט החדש לצד תכונת ה-Labs‏ 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 להשתמש ב:

• סקריפט פשוט ב-CLI של gcloud להקצאת משאבים
• התראות Pub/Sub מקוריות של Cloud Storage + מינוי דחיפה של Pub/Sub ל-Cloud Run
• שימוש ב-Flask (עם Gunicorn) למסגרת
• פשוט משתמשים בסימולציה מקומית עם קובץ טקסט לנתונים במקום בנתוני OCR בזמן אמת
• שימוש ב-BigQuery table.insert_rows() כדי להוסיף שורות ל-BigQuery
• פריסת Cloud Run לא מאומתת

ואפשרויות מומלצות אחרות.

תוכנית הטמעה ורשימת משימות

‫Antigravity יתחיל לפעול וייצור תוכנית הטמעה. הוא יציג אותה לבדיקה שלכם באמצעות הודעה דומה להודעה הבאה:

אפשר ללחוץ על המתג של החלונית העזר בפינה השמאלית העליונה של החלון כדי לראות את הארטיפקטים שנוצרו. בשלב הזה, זה רק תוכנית ההטמעה.

בתוכנית הזו מפורטים:

• תשתית: מאגר GCS, נושא Pub/Sub, מערך נתונים ב-BigQuery.
• מעבד: אפליקציית Python/Flask, קובץ Docker, דרישות.
• שילוב: התראות 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 כדי לתת לנציג הרשאה להמשיך עם תוכנית ההטמעה.

הסוכן ימשיך ליצור עוד ארטיפקט Task Plan (תוכנית משימות), שמכיל קבוצה של משימות שנוצרו על ידי Antigravity. הסוכן יבצע את המשימות אחת אחרי השנייה. דוגמה לרשימת משימות מוצגת בהמשך:

4. יצירת הבקשה

אחרי שהתוכנית מאושרת, Antigravity מתחיל ליצור את הקבצים שנדרשים לאפליקציה, מסקריפטים להקצאת משאבים ועד קוד האפליקציה.

‫Antigravity ייצור תיקייה ויתחיל ליצור את הקבצים שנדרשים לפרויקט. אם תבדקו את הארטיפקטים, תראו שנוצרו כמה קבצים (קוד מקור, קובצי סקריפט וכו').

אחרי שהיא תסיים את העבודה, היא תציין זאת ותיצור מסמך הדרכה שתוכלו לעיין בו. ההודעה צריכה לכלול את השלב הבא שהמשתמש צריך לבצע. הנה דוגמה:

• פריסת צינור עיבוד הנתונים: מוודאים שנכנסתם ל-GCP CLI והגדרתם את פרויקט היעד, ואז מריצים את הפקודה: ./ deploy.sh
• הפעלת בדיקת מקצה לקצה: מריצים את סקריפט הבדיקה של השילוב עם הענן כדי לוודא שהעלאת קובץ מפעילה את העיבוד ב-Cloud Run ומעבירה מטא-נתונים ל-BigQuery:./test_cloud.sh
• ניקוי: אחרי שמסיימים את הבדיקה, אפשר להשתמש בפקודות הניקוי README.md כדי להסיר את המשאבים שנוצרו ולמנוע חיובים.

נוצר קובץ סקריפט מעטפת בשם deploy.sh או בשם דומה, שמבצע אוטומציה של יצירת המשאבים. הוא מטפל ב:

1. הפעלת ממשקי API ‏ (run, pubsub, bigquery, storage).
2. יצירת הקטגוריה ב-Google Cloud Storage‏ (document-processing-ingest-{project-id}).
3. יצירת מערך נתונים וטבלה ב-BigQuery‏ (document_processing.processed_metadata).
4. הגדרת נושאים והתראות ב-Pub/Sub.

5. פריסת האפליקציה

נפרוס את האפליקציה כמו שצוין באמצעות הפקודה ./ deploy.sh. אנחנו יכולים לבקש מ-Antigravity להריץ את הפקודה הזו בשבילנו, אבל לפני כן, צריך לוודא שה-CLI של gcloud קיים ומוגדר לפרויקט Google Cloud.

אנחנו יכולים לתת ל-Antigravity את ההנחיה 'Run the deploy.sh for me'. תופיע בקשה להרשאה, ואתם צריכים לאשר אותה.

התהליך מתחיל כמשימה ברקע, כפי שמוסבר בהודעה הבאה:

התחלתי את תהליך הפריסה על ידי הפעלת ./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.

אפשר לפתוח את ארטיפקט ההסבר המפורט כדי לראות את התוצאות:

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 שכל המשאבים נוצרו. כדי לעשות זאת, פועלים לפי השלבים הבאים.

Cloud Storage

המטרה: לוודא שהמאגר קיים ולבדוק אם יש בו קבצים שהועלו.

1. עוברים אל Cloud Storage > Buckets.
2. מאתרים את הקטגוריה בשם document-processing-ingest-{project-id}.
3. לוחצים על שם הקטגוריה כדי לעיין בקבצים.
4. מאמתים: הקבצים שהועלו אמורים להופיע (למשל,cloud_test_sample.txt).

Pub/Sub

המטרה: לוודא שהנושא קיים ושיש לו מינוי לשליחת הודעות פוש.

1. עוברים אל Pub/Sub > Topics.
2. מחפשים את document-uploads-topic.
3. לוחצים על מזהה הנושא.
4. גוללים למטה לכרטיסייה מינויים.
5. אימות: מוודאים ש-doc-uploads-sub מופיע עם סוג המסירה Push.

Cloud Run

המטרה: בדיקת הסטטוס והיומנים של השירות.

1. עוברים אל Cloud Run.
2. לוחצים על השירות document-processor.
3. אימות:
4. תקינות: סימן וי ירוק מציין שהשירות פעיל.
5. יומנים: לוחצים על הכרטיסייה Logs (יומנים). מחפשים רשומות כמו Processing file: gs://...‎ ו-Successfully inserted...‎.

BigQuery

המטרה: לוודא שהנתונים מאוחסנים בפועל.

1. עוברים אל BigQuery >‏ SQL Workspace (סביבת עבודה של SQL).
2. בחלונית Explorer, מרחיבים את הפרויקט > מערך הנתונים document_processing.
3. לוחצים על הטבלה processed_metadata.
4. לוחצים על הכרטיסייה Query (שאילתה) ומאחזרים את כל השורות מהטבלה באמצעות ההצהרה SELECT * ‎.
5. בודקים: אמורות להופיע שורות עם filename,‏ process_timestamp,‏ tags ו-word_count.

7. סקירת האפליקציה

בשלב הזה, האפליקציה הבסיסית מוכנה ופועלת. לפני שמרחיבים את האפליקציה הזו, כדאי להקדיש רגע לבדיקת הקוד. אפשר לראות את הארטיפקטים, ויוצגו קובצי הקוד שנוצרו.

הנה סיכום קצר של הקבצים שיופיעו:

1. ‫deploy.sh: סקריפט האב שמקצה את כל המשאבים ב-Google Cloud ומפעיל את ממשקי ה-API הנדרשים.
2. ‫appy.py: נקודת הכניסה הראשית של צינור עיבוד הנתונים. אפליקציית Python הזו יוצרת שרת אינטרנט שמקבל הודעות push של Pub/Sub, מוריד את הקובץ מ-GCS, מבצע בו 'עיבוד' (סימולציה של OCR) ומזרים את המטא-נתונים ל-BigQuery.
3. ‫Dockerfile: מגדיר איך לארוז את האפליקציה בקובץ אימג' של קונטיינר.
4. ‫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

שילוב עם AI/ML אמיתי

במקום להשתמש בעיבוד OCR מדומה, אפשר להשתמש במודלים של Gemini כדי לחלץ, לסווג ולתרגם.

1. מחליפים את לוגיקת ה-OCR הפיקטיבית. שולחים את התמונה או את קובץ ה-PDF אל Gemini כדי לחלץ טקסט ונתונים בפועל. לנתח את הטקסט שחולץ כדי לסווג את סוג המסמך (חשבונית, חוזה, קורות חיים) או לחלץ ישויות (תאריכים, שמות, מיקומים).
2. המערכת תזהה אוטומטית את השפה של המסמך ותתרגם אותו לאנגלית לפני האחסון. אפשר להשתמש גם בכל שפה אחרת.

שיפור האחסון והניתוח

אפשר להגדיר כללים לניהול מחזור החיים בקטגוריה כדי להעביר קבצים ישנים לאחסון מסוג Coldline או Archive כדי לחסוך בעלויות.

חוסן ואבטחה

אתם יכולים לשפר את האמינות והאבטחה של האפליקציה, למשל:

1. תורים של הודעות שלא ניתן להעביר (DLQ): צריך לעדכן את המינוי ל-Pub/Sub כדי לטפל בכשלים. אם שירות Cloud Run נכשל בעיבוד קובץ 5 פעמים, המערכת שולחת את ההודעה לנושא או למאגר נפרדים של 'הודעות שלא נמסרו' לבדיקה על ידי אדם.
2. ‫Secret Manager: אם האפליקציה צריכה מפתחות API או הגדרות רגישות, כדאי לאחסן אותם ב-Secret Manager ולגשת אליהם בצורה מאובטחת מ-Cloud Run במקום להקשיח מחרוזות.
3. ‫Eventarc: שדרוג מ-Pub/Sub ישיר ל-Eventarc כדי ליהנות מניתוב אירועים גמיש יותר, שמאפשר הפעלה על סמך יומני ביקורת מורכבים או אירועים אחרים של שירותי GCP.

כמובן, אתם יכולים להעלות רעיונות משלכם ולהשתמש ב-Antigravity כדי ליישם אותם.

9. סיכום

הצלחתם ליצור תוך דקות צינור עיבוד נתונים של מסמכים מבוסס-AI, ניתן להרחבה וללא שרת באמצעות Google Antigravity. למדתם איך:

• תכנון ארכיטקטורות באמצעות AI.
• נותנים הוראות ל-Antigravity ומנהלים אותו בזמן שהוא יוצר את האפליקציה, החל מיצירת הקוד ועד לפריסה ולאימות.
• אימות הפריסות והוולידציה באמצעות מדריכים.

מסמכי עזר

• האתר הרשמי : https://antigravity.google/
• תיעוד: https://antigravity.google/docs
• תרחישים לדוגמה : https://antigravity.google/use-cases
• הורדה : https://antigravity.google/download