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

1. מבוא

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

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

מה תלמדו

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

מה תצטרכו

• Google Antigravity מותקן. אם אתם צריכים עזרה בהתקנת Antigravity ובהבנת היסודות, מומלץ להשלים את ה-codelab: Getting Started with Google Antigravity (תחילת העבודה עם Google Antigravity).
• פרויקט ב-Google Cloud עם חיוב מופעל.
• ה-CLI של gcloud מותקן ומאומת.

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

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

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

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

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

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

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

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

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

ב-Agent Manager, יש לכם אפשרות לפתוח סביבת עבודה או פשוט להשתמש ב-Playground, סביבת עבודה עצמאית ליצירת אבות טיפוס מהירים ולניסויים. נתחיל עם Playground.

לוחצים על הלחצן + כדי להתחיל שיחה חדשה במגרש המשחקים:

יוצג ממשק שבו תוכלו להזין את ההנחיה כמו שמוצג בהמשך:

בפינה השמאלית העליונה, לוחצים על סמל ההגדרות ⚙️ ומגדירים את Review Policy בקטע Artifact לערך Asks for Review ואת 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, קובץ Docker, דרישות.
• שילוב: התראות GCS ‏→ Pub/Sub ‏→ Cloud Run.

אמורה להופיע כותרת שדומה לכותרת הבאה:

לוחצים על הלחצן Open לצד השורה Task. יוצגו לכם קבוצת משימות שנוצרו על ידי Antigravity. הסוכן יעבור עליהם אחד אחד:

השלב הבא הוא לבדוק את תוכנית ההטמעה ולתת לסוכן הרשאה להמשיך.

לוחצים על תוכנית ההטמעה כדי לראות את הפרטים שלה. חשוב לקרוא אותו בעיון. זו ההזדמנות שלכם לספק משוב על ההטמעה. אפשר ללחוץ על כל חלק בתוכנית ההטמעה ולהוסיף הערות. אחרי שמוסיפים הערות, חשוב לשלוח לבדיקה את כל השינויים שרוצים לבצע, במיוחד שינויים שקשורים לשמות, למזהה הפרויקט ב-Google Cloud, לאזור וכו'.

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

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

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

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

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

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

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

הנציג צריך ליצור אפליקציית Python ‏ (main.py) שמקשיבה להודעות מסוג push ב-Pub/Sub. הוא משתמש בלוגיקה מדומה של OCR, יוצר ספירות מילים ותגים אקראיים ושומר אותם ב-BigQuery.

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

לוחצים על Accept לפי הצורך.

סקריפט ההקצאה ייצור את המשאבים ויאמת שהם נוצרו. אם הבדיקה תצליח, המערכת תמשיך ליצירת הקונטיינר ולפריסתו כשירות (ב-main.py) ב-Cloud Run. דוגמה לפלט:

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

בינתיים, אפשר לעבור אל Inbox (מהפינה הימנית העליונה) ולבדוק את המשימות Pending שממתינות להזנת נתונים:

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

5. אימות האפליקציה

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

הוא יוצר ארטיפקט לבדיקה (test.txt) ורוצה להעלות אותו לקטגוריה של Google Cloud Storage. כדי להמשיך, לוחצים על Accept.

אם רוצים להריץ בדיקות נוספות בעצמכם, אפשר לנסות להעלות קובץ לדוגמה לקטגוריה של Cloud Storage:

gcloud storage cp <some-test-doc>.txt gs://doc-ingestion-{project-id}/

בדיקת התוצאות ב-BigQuery

כחלק מתהליך האימות, המערכת תבדוק גם שהנתונים נשמרו ב-BigQuery.

שימו לב לשאילתת ה-SQL שבה נעשה שימוש כדי לבדוק את המסמכים.

אחרי שהאימות יסתיים, תראו שרשימת המשימות הושלמה:

אופציונלי: אימות ידני

למרות ש-Antigravity כבר אימתה את האפליקציה, אתם יכולים גם לבדוק באופן ידני במסוף Google Cloud שכל המשאבים נוצרו. כדי לעשות זאת, פועלים לפי השלבים הבאים.

Cloud Storage

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

1. עוברים אל Cloud Storage > Buckets.
2. מאתרים את הקטגוריה בשם [PROJECT_ID]-doc-uploads.
3. לוחצים על שם הקטגוריה כדי לעיין בקבצים.
4. בודקים: הקבצים שהועלו אמורים להופיע (למשל, test.txt).

Pub/Sub

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

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

Cloud Run

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

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

BigQuery

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

1. עוברים אל BigQuery >‏ SQL Workspace (סביבת עבודה של SQL).
2. בחלונית Explorer, מרחיבים את הפרויקט > מערך הנתונים pipeline_data.
3. לוחצים על הטבלה processed_docs.
4. לוחצים על הכרטיסייה תצוגה מקדימה.
5. בודקים: אמורות להופיע שורות עם filename,‏ upload_date,‏ tags ו-word_count.

הדרכה מפורטת

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

• השינויים בוצעו.
• פקודות האימות מופעלות.
• התוצאות בפועל (פלט השאילתה שמציג את המטא-נתונים שחולצו על ידי Gemini).

אפשר ללחוץ על Open כדי לראות אותו. דוגמה לפלט:

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

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

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

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

הטמעה של AI/ML אמיתי

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

1. מחליפים את לוגיקת ה-OCR של ה-dummy. שולחים את התמונה או קובץ ה-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 כדי ליישם אותם.

8. סיכום

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

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

מאמרי עזרה

• האתר הרשמי : https://antigravity.google/
• תיעוד: https://antigravity.google/docs
• תרחישים לדוגמה : https://antigravity.google/use-cases
• הורדה : https://antigravity.google/download
• ‫Codelab : Getting Started with Google Antigravity