ב-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 (
roles/aiplatform.user) -
מפעילים את ממשקי ה-API הנדרשים:
אדמין של שימוש בשירות (
roles/serviceusage.serviceUsageAdmin) -
מקצים את התפקידים הנדרשים לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine: אדמין IAM של פרויקט (
roles/resourcemanager.projectIamAdmin) -
פריסת אפליקציה של Cloud Run:
- אדמין ב-Cloud Run (
roles/run.admin) - Cloud Run Source Developer (
roles/run.sourceDeveloper)
- אדמין ב-Cloud Run (
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
התפקידים הנדרשים לחשבון השירות של הפריסה
כדי לוודא שלחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine יש את ההרשאות שנדרשות להפעלת בנייה בשמכם, צריך לבקש מהאדמין להקצות לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בפרויקט את תפקידי ה-IAM הבאים:
- סוכן שירות של פלטפורמת סוכנים (
roles/aiplatform.serviceAgent) - חשבון שירות של Cloud Build (
roles/cloudbuild.builds.builder)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שהאדמין גם יוכל לתת לחשבון השירות המשמש כברירת מחדל של Compute Engine את ההרשאות שנדרשות באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
אם יש לכם הרשאה להקצות תפקידים, אתם יכולים להקצות את התפקידים האלה כשאתם פורסים את האפליקציה.
יצירת הנחיה עם משתני הנחיה
עוברים אל דף יצירת ההנחיות של Agent Studio, ואז לוחצים על הוספת משתנה בתיבת הקלט של ההנחיה.
בתיבת הדו-שיח Manage prompt variables, מזינים שם למשתנה ונותנים לו ערך. לוחצים על אישור.
בתיבת הקלט של ההנחיה, כותבים את ההנחיה באמצעות המשתנה ואז משנים פרמטרים אחרים. לדוגמה, אתם יכולים להפעיל את העיגון באמצעות חיפוש Google ולהגדיר את ההוראה "תמיד לקבל את מזג האוויר הנוכחי מהאינטרנט" כהוראת המערכת.
פריסת הפרומפט כאפליקציית אינטרנט
כדי לפרוס את ההנחיה כאפליקציית אינטרנט, לוחצים על ואז על פריסה כאפליקציה.
שמירת הפרומפט
תיבת הדו-שיח לשמירת ההנחיה תופיע, כי צריך לשמור את ההנחיה לפני שאפשר לפרוס אותה. תיבת הדו-שיח של הפריסה תיפתח אוטומטית אחרי שמירת ההנחיה.
הפעלת ממשקי API לפריסה הראשונה והענקת הרשאות
- אחרי ששומרים את ההנחיה, תהליך הפריסה ממשיך. אם זו הפריסה הראשונה שלכם, תוצג לכם תיבת דו-שיח להפעלת ממשקי ה-API הנדרשים. לוחצים על Enable required APIs (הפעלת ממשקי ה-API הנדרשים).
-
אחרי שמפעילים את ממשקי ה-API, מופיעה תיבת הדו-שיח Create a web app. אפשר לבחור באפשרות Require authentication (via Identity-Aware Proxy) או באפשרות Allow public access.
- אם בחרתם באפשרות 'נדרש אימות', צריך לפעול לפי ההוראות למתן גישה (כולל לעצמכם).
- כשבוחרים באפשרות גישה ציבורית, כל אחד יכול לגשת לאפליקציה. לכן, חשוב לא לכלול בהנחיה מידע רגיש או פרטים אישיים מזהים (PII). כדי לאשר, מסמנים את התיבה I understand this app will be deployed publicly.
- כדי להתחיל את הפריסה, לוחצים על יצירת אפליקציה.
- אם זו הפריסה הראשונה שלכם, יופיע עוד דו-שיח שבו תתבקשו להעניק את התפקידים הנדרשים לחשבון השירות. כדי להמשיך, לוחצים על הענקת גישה לכולם.
תחילת הפריסה
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 באופן אוטומטי.
פותחים את אפליקציית האינטרנט ושולחים את ההנחיה.
בתיבת הדו-שיח Manage web app, לוחצים על Open כדי לגשת לאפליקציית האינטרנט שנפרסה. האפליקציה צריכה להיפתח עם המפתח הסודי שנוסף לכתובת ה-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 תופיע שוב. התהליך דומה לפריסה הראשונית. אפשר לעקוב אחרי ההתקדמות באותו אופן כמו בפריסה הראשונה.
אחרי שהעדכון יסתיים, תוכלו לפתוח שוב את אפליקציית האינטרנט. ממשק המשתמש של השיחה יופיע עם משתנה ההנחיה. כדי להמשיך את השיחה, צריך למלא את הערך ולהקליד תוכן כלשהו שאינו ריק.
הוספת תוכן מולטימודאלי
אתם יכולים להוסיף קלט כמו תמונות, סרטונים, אודיו ומסמכים לממשק המשתמש של הצ'אט. סוגי הקלט הנתמכים תלויים במודל שנבחר להנחיה. מידע נוסף זמין במסמכי התיעוד בנושא תמיכה ב-multimodal לכל מודל.
כדי להוסיף קובץ, לוחצים על סמל האטב בתיבת הקלט של השיחה.
תוכלו ליצור אינטראקציה עם המודל באמצעות הקלט שתספקו.
נושאים מתקדמים
אחרי שתכירו את תהליך הפריסה, תוכלו לבצע את הפעולות הבאות.
עריכת קוד המקור ב-Cloud Run
אם רוצים להתאים אישית את אפליקציית האינטרנט, אפשר לבצע שינויים בקוד המקור ב-Cloud Run. פותחים את הדף של קוד המקור של Cloud Run מתיבת הדו-שיח Manage web app. לשם כך, לוחצים על לחצן סמל האפשרויות הנוספות בסוף השורה.
אפשר גם לעבור לדף האבטחה מאפליקציית האינטרנט בלחיצה על הקישור עורך קוד המקור.
בדף קוד המקור של Cloud Run, לוחצים על Edit source כדי להתחיל את מצב העריכה. בסיום, לוחצים על שמירה ופריסה מחדש.
אחרי שהפריסה מחדש מסתיימת, צריך לפתוח את האפליקציה מ-Agent Studio. אפשר לעבור לדף Agent Studio מהקישור שבתג Deployed from Agent Platform.
הענקת גישה
כדי לתת למשתמשים או לקבוצות גישה לאפליקציה:
- פותחים את תיבת הדו-שיח ניהול אפליקציית אינטרנט.
- לוחצים על סמל העיפרון בעמודה בקרת גישה. דף האבטחה של Cloud Run ייפתח בכרטיסייה חדשה.
- בדף האבטחה של Cloud Run, מוצאים את תיבת הסימון של שרת proxy לאימות זהויות (IAP). מוודאים שהתיבה מסומנת ולוחצים על עריכת המדיניות.
-
תופיע תת-משימה שמאפשרת לערוך את הגישה. מזינים את כתובות האימייל של המשתמשים או הקבוצות בשדה Principal.
אם אתם משתמשים בארגון, אתם יכולים להוסיף רק משתמשים מאותו ארגון.
- משאירים את השדה של רמות הגישה ריק.
- לוחצים על שמירה.
-
אחרי שסוגרים את משימת המשנה, לוחצים שוב על שמירה בדף Cloud Run.
השבתת הגישה לכולם
אם אתם לא רוצים שאפליקציית האינטרנט תהיה נגישה לכולם, אתם יכולים להשבית אותה ב-Cloud Run. פותחים את תיבת הדו-שיח Manage Web App ולוחצים על סמל העיפרון בעמודה בקרת גישה. הדף בנושא אבטחה ב-Cloud Run ייפתח בכרטיסייה חדשה.
אפשר גם לעבור לדף האבטחה מאפליקציית האינטרנט בלחיצה על הקישור הגדרות אבטחה.
בדף Security (אבטחה) של שירות Cloud Run שמתאים לאפליקציית האינטרנט, מסמנים את התיבה Use Cloud IAM to authenticate incoming requests (שימוש ב-Cloud IAM לאימות בקשות נכנסות) ובוחרים באפשרות Require authentication (נדרש אימות). לוחצים על שמירה.
כתוצאה מכך, לא תהיה יותר גישה לאפליקציית האינטרנט דרך כתובת ה-URL. אם תנסו לגשת אליו, תופיע הודעת השגיאה Error: Forbidden.
הפעלה מחדש של הגישה לכולם
כדי להחזיר את הגישה הציבורית, מבטלים את הסימון של התיבה Use Cloud IAM to authenticate incoming requests (שימוש ב-Cloud IAM לאימות בקשות נכנסות) ושומרים. אם בוחרים באפשרות Allow unauthenticated invocations, היא לא תפעל אם הפרויקט נמצא בארגון. לפרטים נוספים, ראו אימות ב-Cloud Run.
הגדרת גישה מקומית לפיתוח
בגרסת ה-Public Preview, עדיין אין תמיכה בבקרת גישה. לכן, אחרי שמכבים את הגישה הציבורית, הדרך היחידה לגשת לאפליקציית האינטרנט היא להגדיר פרוקסי מקומי. אפשר לעשות את זה באמצעות פקודות gcloud. קודם פותחים את Cloud Shell באמצעות הלחצן סמל הטרמינל בפינה השמאלית העליונה של Google Cloud המסוף. תתבקשו לאשר את Cloud Shell. כדי להמשיך, לוחצים על Authorize.
אחרי שהפעולה מסתיימת, פותחים את תיבת הדו-שיח Manage web app ולוחצים על סמל האפשרויות הנוספות בסוף השורה כדי לראות פעולות נוספות. לוחצים על הגדרת גישה מקומית באמצעות 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.