ב-Agent Studio אתם יכולים לעצב ולשפר את ההנחיות, ולהשוות בין התוצאות של הגדרות ומודלים שונים. אחרי שמסיימים לפתח את ההנחיה, אפשר לפרוס אותה כאפליקציית אינטרנט כדי לשתף אותה עם שותפי העריכה או עם משתמשי היעד, כדי שהם יוכלו לבדוק את אפליקציית האינטרנט. אפליקציית האינטרנט מתארחת ב-Cloud Run וזמינה מחוץ למסוף Google Cloud .
במדריך למתחילים הזה תבצעו את הפעולות הבאות:
- יצירת הנחיה עם משתני הנחיה
- פריסת ההנחיה כאפליקציית אינטרנט
- מעקב אחרי התקדמות הפריסה ובדיקת האפליקציה שנפרסה
- עדכון ופריסה מחדש של ההנחיה
- בדיקת שליחת הנחיות עם תמיכה במולטימודאליות
לפני שמתחילים
אם אף פעם לא השתמשתם ב-Agent Studio, אתם יכולים להיעזר במדריך אחר להתחלה מהירה או להשתתף בקורס של Google Cloud Skills Boost כדי ללמוד את העקרונות הבסיסיים של Agent Studio. במדריך הזה, אתם צריכים את הדברים הבאים:
- פרויקט ב-Google Cloud עם חיוב ו-Agent Platform API מופעל.
- התפקידים שנדרשים כדי לפרוס הנחיה של Agent Studio כאפליקציית אינטרנט. אם משתמשים בפרויקט חדש, לא צריך לוודא כי כבר יש את ההרשאות הנדרשות.
אפשר גם לוודא שלחשבון השירות שמשמש כברירת מחדל ב-Compute Engine יש את התפקידים שנדרשים לחשבון השירות לפריסה. אם יש לכם הרשאה להקצות תפקידים, אתם יכולים להקצות את התפקידים האלה כשאתם פורסים את האפליקציה.
התפקידים הנדרשים
כדי לקבל את ההרשאות שדרושות לפריסת הנחיה של Agent Studio כאפליקציית אינטרנט, בקשו מהאדמין לתת לכם את התפקידים הבאים ב-IAM בפרויקט:
- Agent Platform User (
roles/aiplatform.user) -
הפעלת ממשקי ה-API הנדרשים:
אדמין של שימוש בשירות (
roles/serviceusage.serviceUsageAdmin) -
מקצים את התפקידים הנדרשים לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine:
אדמין IAM של פרויקט (
roles/resourcemanager.projectIamAdmin) -
פריסת אפליקציה של Cloud Run:
- אדמין ב-Cloud Run (
roles/run.admin) - מפתח מקורות ב-Cloud Run (
roles/run.sourceDeveloper)
- אדמין ב-Cloud Run (
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
התפקידים הנדרשים לחשבון השירות לפריסה
כדי לוודא שלחשבון השירות שמשמש כברירת מחדל ב-Compute Engine יש את ההרשאות הנדרשות להרצת גרסאות build בשמכם, צריך לבקש מהאדמין לתת לחשבון השירות שמשמש כברירת מחדל ב-Compute Engine את תפקידי ה-IAM הבאים בפרויקט:
- סוכן שירות של Vertex AI (
roles/aiplatform.serviceAgent) - חשבון שירות של Cloud Build (
roles/cloudbuild.builds.builder)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שהאדמין גם יוכל לתת לחשבון השירות שמשמש כברירת מחדל ב-Compute Engine את ההרשאות שנדרשות באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
אם יש לכם הרשאה להקצות תפקידים, אתם יכולים להקצות את התפקידים האלה כשאתם פורסים את האפליקציה.
יצירת הנחיה עם משתני הנחיה
עוברים לדף יצירת ההנחיות ב-Agent Studio ולוחצים על Add variable בתיבת הקלט של ההנחיה.
בתיבת הדו-שיח Manage prompt variables, מזינים שם למשתנה ונותנים לו ערך. לאחר מכן לוחצים על אישור.
בתיבת הטקסט של ההנחיה, כותבים את ההנחיה באמצעות המשתנה ומשנים את הפרמטרים האחרים. לדוגמה, אתם יכולים להפעיל את העיגון באמצעות חיפוש Google ולהגדיר את ההוראה "תמיד לקבל את מזג האוויר הנוכחי מהאינטרנט" כהוראת המערכת.
פריסת ההנחיה כאפליקציית אינטרנט
כדי לפרוס את ההנחיה כאפליקציית אינטרנט, לוחצים על ואז על Deploy as app.
שמירת ההנחיה
תיבת הדו-שיח לשמירת ההנחיה תופיע, כי צריך לשמור את ההנחיה לפני שאפשר לפרוס אותה. תיבת הדו-שיח לפריסה תיפתח באופן אוטומטי אחרי שההנחיה תישמר.
הפעלת ממשקי API לפריסה הראשונה והענקת הרשאות
- אחרי ששומרים את ההנחיה, תהליך הפריסה ממשיך. אם זו הפריסה הראשונה שלכם, תופיע תיבת דו-שיח להפעלת ממשקי ה-API הנדרשים. לוחצים על Enable required APIs.
-
אחרי שמפעילים את ממשקי ה-API, מופיעה תיבת הדו-שיח Create a web app. אפשר לבחור באפשרות Require authentication (via Identity-Aware Proxy) או באפשרות Allow public access.
- אם בחרתם באפשרות של אימות נדרש, פעלו לפי המדריך למתן גישה (כולל את עצמכם).
- כשבוחרים באפשרות לאפשר גישה ציבורית, כל אחד יכול לגשת לאפליקציה. לכן, אל תכללו בהנחיה מידע רגיש או פרטים אישיים מזהים (PII). כדי לאשר, מסמנים את התיבה I understand this app will be deployed publicly.
- לוחצים על Create app כדי להתחיל את הפריסה.
- אם זה הפריסה הראשונה שלכם, תופיע תיבת דו-שיח נוספת שבה תתבקשו להקצות את התפקידים הנדרשים לחשבון השירות. כדי להמשיך, לוחצים על הענקת גישה לכולם.
תחילת הפריסה
Agent Studio ייצור קובץ ZIP שמכיל את קוד המקור של אפליקציית האינטרנט, ויעלה את קובץ ה-ZIP לקטגוריה של Cloud Storage. אחרי שהפריסה תתחיל, תיפתח תיבת הדו-שיח Manage web app עם מידע על הפריסה, כמו שם האפליקציה, מתי היא נפרסה לאחרונה, סטטוס הפריסה ועוד.
מעקב אחרי סטטוס הפריסה
הפריסה נמשכת 2-3 דקות, והסטטוס שלה מופיע בעמודה Status בתיבת הדו-שיח Manage web app. אם סוגרים את תיבת הדו-שיח Manage web app, אפשר לפתוח אותה מחדש מהתפריט שמתחת ללחצן Build with code.
בסיום הפריסה, הסטטוס בעמודה ישתנה ל-Ready והלחצן Open יופיע ליד שם האפליקציה.
בקרת גישה ומפתח סודי
אפליקציית האינטרנט נפרסת כשבקרת הגישה Allow unauthenticated מופעלת כברירת מחדל. כדי להשבית את התכונה, לוחצים על כפתור סמל העיפרון . מידע נוסף זמין בקטע השבתת הגישה הציבורית.
כדי לספק הגנה בסיסית, אפליקציית האינטרנט דורשת להוסיף מפתח סודי לכתובת ה-URL לשליחת ההנחיה. המפתח הסודי מופיע בעמודה Secret Key. אם פותחים את אפליקציית האינטרנט מ-Agent Studio, המפתח יתווסף לכתובת ה-URL באופן אוטומטי.
פותחים את אפליקציית האינטרנט ושולחים את ההנחיה
כדי לגשת לאפליקציה שנפרסה, לוחצים על Open בתיבת הדו-שיח Manage web app. האפליקציה אמורה להיפתח עם המפתח הסודי שמצורף לכתובת ה-URL בפורמט ?key=SECRET_KEY.
מזינים ערך למשתנה ולוחצים על שליחה. התוצאות אמורות להופיע בצד שמאל.
פותחים את אפליקציית האינטרנט מתפריט הכפתור "פיתוח באמצעות קוד"
אם אפליקציית האינטרנט מוכנה, אתם יכולים לפתוח אותה גם מתפריט הכפתור Build with code.
Cloud Run הוא שירות ללא שרת (serverless), כלומר הקונטיינר של האפליקציה ייסגר אם לא משתמשים בו באופן פעיל. לכן, לפעמים לוקח לאפליקציית האינטרנט כמה שניות להיטען, או שהשליחה לא עובדת אם אפליקציית האינטרנט לא הייתה פעילה במשך זמן רב מדי. רענון הדף אמור לפתור את הבעיה.
מעקב אחרי הסטטוס באמצעות פעמון ההתראות
אפשר גם לעקוב אחרי הסטטוס בתפריט Notifications בלחיצה על סמל הפעמון. אם הפריסה הושלמה בהצלחה, אנימציית הטעינה של סמל הפעמון תיפסק ויופיע עיגול ירוק.
אם תלחצו על ההתראה, תועברו לדף של Cloud Run. כתובת ה-URL בדף Cloud Run לא כוללת את המפתח הסודי. צריך להוסיף אותו באופן ידני בפורמט ?key=SECRET_KEY.
עדכון ופריסה מחדש של ההנחיה
אתם יכולים להמשיך לערוך את ההנחיה ב-Agent Studio ולהפוך אותה לשיחה. אחר כך לוחצים על Build with code ואז על Manage app כדי לפתוח את תיבת הדו-שיח Manage web app. לוחצים על Update app כדי לפרוס מחדש את אפליקציית האינטרנט עם ההנחיה המעודכנת.
תופיע תיבת דו-שיח לאישור. היא מציינת שאם תפרסו מחדש, תאבדו את כל השינויים שביצעתם באפליקציית האינטרנט שנפרסה מחוץ ל-Agent Studio (למשל בעורך קוד המקור של Cloud Run). לוחצים על אישור כדי להמשיך.
תיבת הדו-שיח Manage web app תופיע שוב. התהליך דומה לפריסה הראשונית. אפשר לעקוב אחרי ההתקדמות באותו אופן כמו בפריסה הראשונה.
אחרי שהעדכון יסתיים, תוכלו לפתוח שוב את אפליקציית האינטרנט. ממשק המשתמש של השיחה יופיע עם משתנה ההנחיה. כדי להמשיך את השיחה, צריך למלא את הערך ולהקליד תוכן כלשהו.
הוספת תוכן מולטימודלי
אתם יכולים להוסיף לממשק השיחה קלט כמו תמונות, סרטונים, אודיו ומסמכים. סוגי הקלט הנתמכים תלויים במודל שנבחר להנחיה. למידע נוסף על התמיכה במולטימודליות בכל מודל
כדי להוסיף קובץ, לוחצים על כפתור הסמל של מהדק הנייר בתיבת הקלט של השיחה.
תוכלו לקיים אינטראקציה עם המודל באמצעות הקלט שתספקו.
נושאים מתקדמים
אחרי שתכירו את תהליך הפריסה, תוכלו לבצע את הפעולות הבאות.
עריכת קוד המקור ב-Cloud Run
אם רוצים להתאים אישית את אפליקציית האינטרנט, אפשר לשנות את קוד המקור ב-Cloud Run. בתיבת הדו-שיח Manage web app, לוחצים על סמל האפשרויות הנוספות בסוף השורה כדי לפתוח את דף קוד המקור של Cloud Run.
אפשר גם לעבור לדף האבטחה מאפליקציית האינטרנט בלחיצה על הקישור עורך קוד המקור.
בדף קוד המקור של Cloud Run, לוחצים על Edit source כדי להתחיל את מצב העריכה. בסיום, לוחצים על שמירה ופריסה מחדש.
אחרי שהפריסה מחדש מסתיימת, צריך לפתוח את האפליקציה מ-Agent Studio. אפשר לעבור לדף Agent Studio מהקישור שבתג Deployed from Agent Platform.
הענקת גישה
כדי לתת למשתמשים או לקבוצות גישה לאפליקציה:
- פותחים את תיבת הדו-שיח ניהול אפליקציית אינטרנט.
- לוחצים על סמל העיפרון בעמודה בקרת גישה. דף האבטחה של Cloud Run נפתח בכרטיסייה חדשה.
- בדף האבטחה של Cloud Run, מאתרים את תיבת הסימון של שרת proxy לאימות זהויות (IAP). מוודאים שהיא מסומנת ולוחצים על עריכת המדיניות.
-
תופיע תת-משימה שמאפשרת לערוך את הגישה. מזינים את כתובות האימייל של המשתמשים או הקבוצות בשדה Principal.
אם אתם משתמשים בארגון, אתם יכולים להוסיף רק משתמשים מאותו ארגון.
- משאירים את השדה של רמות הגישה ריק.
- לוחצים על שמירה.
-
אחרי שסוגרים את תת-משימה, לוחצים שוב על Save בדף Cloud Run.
השבתת הגישה הציבורית
אם אתם לא צריכים שאפליקציית האינטרנט תהיה נגישה לכולם, אתם יכולים להשבית אותה ב-Cloud Run. פותחים את תיבת הדו-שיח Manage Web App ולוחצים על סמל העיפרון בעמודה בקרת גישה. דף האבטחה של Cloud Run ייפתח בכרטיסייה חדשה.
אפשר גם לעבור לדף האבטחה מאפליקציית האינטרנט בלחיצה על הקישור הגדרות אבטחה.
בדף Security של שירות Cloud Run שתואם לאפליקציית האינטרנט, מסמנים את האפשרות Use Cloud IAM to authenticate incoming requests ובוחרים באפשרות Require authentication. לוחצים על שמירה.
כתוצאה מכך, לא תהיה יותר גישה לאפליקציית האינטרנט דרך כתובת ה-URL. אם תנסו לגשת אליו, תופיע הדף שגיאה: אסור.
הפעלה מחדש של הגישה הציבורית
אם רוצים להחזיר את הגישה הציבורית, מבטלים את הסימון של התיבה Use Cloud IAM to authenticate incoming requests ושומרים. אם בוחרים באפשרות Allow unauthenticated invocations, היא לא תפעל אם הפרויקט נמצא בארגון. למידע נוסף, ראו אימות ב-Cloud Run.
הגדרת גישה מקומית לפיתוח
בגרסת Public Preview עדיין אין תמיכה בבקרת גישה. לכן, אחרי שמשביתים את הגישה הציבורית, הדרך היחידה לגשת לאפליקציית האינטרנט היא להגדיר שרת proxy מקומי. אפשר לעשות את זה באמצעות פקודות gcloud. קודם כל, פותחים את Cloud Shell באמצעות לחצן הטרמינל בפינה הימנית העליונה של מסוף Google Cloud . תתבקשו לאשר את Cloud Shell. כדי להמשיך, לוחצים על Authorize.
בסיום, פותחים את תיבת הדו-שיח Manage web app ולוחצים על סמל האפשרויות הנוספות בסוף השורה כדי לראות עוד פעולות. לוחצים על Set up local access via Cloud Shell.
פקודה תתווסף ל-Cloud Shell. לוחצים על Enter ומחכים שההדפסה תסתיים. לוחצים על הקישור בשורה שמתחילה ב-Click on the
link to preview. תוכלו לראות את הבקשה שלכם. הקישור הזה פועל רק כשפקודת gcloud פועלת.
בעיות נפוצות
שגיאת אימות: אין מפתח סודי
אם מופיעה השגיאה הבאה, זה אומר שלא צורף מפתח סודי לכתובת ה-URL. פועלים לפי ההוראות לפתיחת אפליקציית האינטרנט מ-Agent Studio, או מעתיקים את המפתח הסודי מתיבת הדו-שיח Manage app ומוסיפים אותו לכתובת ה-URL בפורמט ?key=SECRET_KEY.
שגיאת אימות: מפתח סודי לא תקין
השגיאה הבאה מציינת שהמפתח שנוסף לכתובת ה-URL לא תקין. המפתח הסודי הוא ייחודי לכל הנחיה. אם יש לכם מפתח סודי מהנחיה אחרת, הוא לא יעבוד. כאן מוסבר איך לפתוח את אפליקציית האינטרנט כמו שצריך.
400 ארגומנט לא תקין: קלט ריק
השגיאה הבאה מתרחשת כשיש קלט במשתנה ההנחיה, אבל הצ'אט ריק. תופיע הודעת שגיאה 400. כדי לתקן את הבעיה, צריך להקליד משהו בשדה ולשלוח אותו מחדש.
400 ארגומנט לא תקין: אין תמיכה ב-mimeType
אם תבחרו סוג קובץ שהמודל לא תומך בו, תוחזר שגיאה 400. זה צפוי, ותצטרכו להשתמש בסוגים אחרים של קבצים שהמודל תומך בהם. במסמכי התיעוד של כל מודל מוסבר איך הוא תומך במולטימודליות.
המאמרים הבאים
מדריך למתחילים ב-Agent Studio: שליחת פרומפטים טקסטואליים ל-Gemini
איך שולחים פרומפטים טקסטואליים ל-Gemini באמצעות Agent Studio.