דרישות לגבי מאגרים מותאמים אישית להסקת מסקנות

כדי להשתמש בקונטיינר מותאם אישית להצגת מסקנות ממודל שאומן בהתאמה אישית, צריך לספק לפלטפורמת הסוכן של Gemini Enterprise תמונת קונטיינר של Docker שמריצה שרת HTTP. במאמר הזה מפורטות הדרישות שקובץ אימג' של קונטיינר צריכה לעמוד בהן כדי להיות תואמת ל-Gemini Enterprise Agent Platform. בנוסף, במאמר מוסבר איך Agent Platform פועלת עם קונטיינר מותאם אישית שלכם אחרי שהוא מתחיל לפעול. במילים אחרות, במסמך הזה מתואר מה צריך לקחת בחשבון כשמתכננים קובץ אימג' של קונטיינר לשימוש עם Agent Platform.

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

הדרישות לגבי קובץ אימג' של קונטיינר

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

אפשר להטמיע את שרת ה-HTTP בכל דרך, באמצעות כל שפת תכנות, כל עוד הוא עומד בדרישות שבקטע הזה. לדוגמה, אפשר לכתוב שרת HTTP מותאם אישית באמצעות מסגרת אינטרנט כמו Flask, או להשתמש בתוכנת שרת ללמידת מכונה (ML) שמריצה שרת HTTP, כמו TensorFlow Serving, ‏ TorchServe או KServe Python Server.

הפעלת שרת ה-HTTP

אפשר להריץ שרת HTTP באמצעות הוראה של ENTRYPOINT, הוראה של CMD או שילוב של שתיהן בקובץ Dockerfile שמשמש ליצירת קובץ אימג' של קונטיינר. מידע נוסף על האינטראקציה בין CMD לבין ENTRYPOINT

לחלופין, אפשר לציין את השדות containerSpec.command ו-containerSpec.args כשיוצרים את משאב Model כדי לשנות את הערכים של ENTRYPOINT ו-CMD בתמונת הקונטיינר. אם מציינים אחד מהשדות האלה, אפשר להשתמש בקובץ אימג' של קונטיינר שלא עומד בדרישות בגלל ENTRYPOINT או CMD לא תואמים (או לא קיימים).

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

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

בדיקות מצב הפעילות (liveness)

Agent Platform מבצעת בדיקת פעילות כשהקונטיינר מתחיל לפעול כדי לוודא שהשרת פועל. כשפורסים מודל שאומן בהתאמה אישית למשאב Endpoint, Agent Platform משתמשת בבדיקת פעילות של TCP כדי לנסות ליצור חיבור TCP לקונטיינר ביציאה שהוגדרה. הבדיקה מנסה ליצור חיבור עד 4 פעמים, וממתינה 10 שניות אחרי כל ניסיון כושל. אם הבדיקה עדיין לא הצליחה ליצור חיבור בשלב הזה, Agent Platform מפעיל מחדש את הקונטיינר.

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

בדיקות תקינות

אפשר לציין startup_probe או health_probe.

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

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

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

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

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

בדיקות תקינות שמוגדרות כברירת מחדל

כברירת מחדל, Agent Platform מבצעת מדי פעם בדיקות תקינות בשרת ה-HTTP בזמן שהוא פועל, כדי לוודא שהוא מוכן לטפל בבקשות הסקה. השירות משתמש בבקשה לבדיקת תקינות (probe) כדי לשלוח בקשות HTTP GET לנתיב בדיקת תקינות שניתן להגדרה בשרת. מציינים את הנתיב הזה בשדה containerSpec.healthRoute כשיוצרים Model. כדי להבין איך הקונטיינר יכול לגשת לערך הזה, אפשר לקרוא את הקטע במסמך הזה על משתנה הסביבה AIP_HEALTH_ROUTE.

מגדירים את שרת ה-HTTP כך שיגיב לכל בקשה לבדיקת תקינות באופן הבא:

• אם השרת מוכן לטפל בבקשות הסקה, צריך להשיב לבקשת בדיקת תקינות תוך 10 שניות עם קוד סטטוס 200 OK. אין חשיבות לתוכן של גוף התגובה, כי Agent Platform מתעלמת ממנו.

  התגובה הזו מציינת שהשרת תקין.

• אם השרת לא מוכן לטפל בבקשות הסקה, לא מגיבים לבקשת בדיקת התקינות תוך 10 שניות, או מגיבים עם קוד סטטוס כלשהו מלבד 200 OK. לדוגמה, תגובה עם קוד הסטטוס 503 Service Unavailable.

  התגובה הזו (או היעדר תגובה) מציינת שהשרת לא תקין.

אם בקשת בדיקת התקינות מקבלת מהשרת תגובה שמצביעה על בעיה (כולל מצב שבו לא מתקבלת תגובה תוך 10 שניות), היא שולחת עד 3 בדיקות תקינות נוספות במרווחי זמן של 10 שניות. במהלך התקופה הזו, Agent Platform עדיין מחשיב את השרת שלכם כשרת תקין. אם הבדיקה מקבלת תשובה תקינה לאחת מהבדיקות האלה, היא חוזרת מיד ללוח הזמנים שלה לביצוע בדיקות תקינות לסירוגין. עם זאת, אם הבקשה לבדיקת תקינות (probe) מקבלת 4 תגובות לא תקינות ברצף, Agent Platform מפסיקה להפנות תעבורת נתונים של היקש אל הקונטיינר. (אם משאב DeployedModel מותאם לשימוש בכמה צמתים של הסקת מסקנות, Agent Platform מעביר בקשות להסקת מסקנות למאגרי מידע אחרים תקינים).

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

הנחיות מעשיות

במקרים מסוימים, מספיק ששרת ה-HTTP במאגר תמיד יגיב לבדיקות תקינות עם קוד סטטוס 200 OK. אם מאגר התגים טוען משאבים לפני הפעלת השרת, המאגר לא תקין במהלך תקופת ההפעלה ובמהלך תקופות שבהן שרת ה-HTTP נכשל. בכל שאר המקרים, התגובה היא תקינה.

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

בקשות להסקת מסקנות

יש שני דפוסים להגדרת מסלולים לשרת המודל. אחת מוגדרת על ידי Gemini Enterprise Agent Platform‏ (/predict), והשנייה מאפשרת התאמה אישית מלאה כדי שתוכלו פשוט להוסיף את שרת המודלים שבחרתם (/invoke).

נתיב Vertex מוגדר /predict

כשלקוח שולח בקשת projects.locations.endpoints.predict אל Agent Platform API, ‏ Agent Platform מעביר את הבקשה הזו כבקשת HTTP POST אל נתיב הסקה שניתן להגדרה בשרת שלכם. מציינים את הנתיב הזה containerSpec.predictRouteבשדה כשיוצרים Model. כדי להבין איך הקונטיינר יכול לגשת לערך הזה, אפשר לקרוא את הקטע במסמך הזה על משתנה הסביבה AIP_PREDICT_ROUTE.

דרישות לבקשה

אם המודל נפרס לנקודת קצה ציבורית משותפת, כל בקשת הסקה צריכה להיות בגודל של עד 1.5MB. שרת ה-HTTP צריך לקבל בקשות להסקת מסקנות עם כותרת ה-HTTP‏ Content-Type: application/json וגופי JSON בפורמט הבא:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

בדוגמאות האלה:

• ‫INSTANCES הוא מערך של ערכי JSON אחד או יותר מכל סוג. כל ערך מייצג מופע שאתם מספקים לו מסקנה.

• ‫PARAMETERS הוא אובייקט JSON שמכיל את כל הפרמטרים שהמאגר צריך כדי לעזור להציג מסקנות לגבי המקרים. השדה parameters הוא אופציונלי ב-Agent Platform, כך שאפשר לעצב את הקונטיינר כך שהוא יחייב את השדה, ישתמש בו רק אם הוא יסופק או יתעלם ממנו.

מידע נוסף על הדרישות לגבי גוף הבקשה

דרישות לגבי תגובה

אם המודל נפרס לנקודת קצה ציבורית משותפת, כל תגובה של הסקה צריכה להיות בגודל של עד 1.5MB. שרת ה-HTTP צריך לשלוח תגובות עם גופי JSON בפורמט הבא:

{
  "predictions": INFERENCES
}

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

אחרי ששרת ה-HTTP שולח את התגובה הזו, Agent Platform מוסיף שדה deployedModelId לתגובה לפני שהוא מחזיר אותה ללקוח. בשדה הזה מצוין איזה DeployedModel ב-Endpoint שולח את התגובה. מידע נוסף על פורמט גוף התגובה

נתיבי הסקה בהתאמה אישית

אם שרת המודל מטמיע כמה מסלולי הסקה, מומלץ להשתמש ב-invoke API כדי לגשת לכמה מסלולי הסקה. אפשר להפעיל את Invoke API במהלך העלאת המודל על ידי הגדרת השדה Model.containerSpec.invokeRoutePrefix לערך ‎"/*". אחרי הפריסה, בקשת HTTP לנתיב /invoke/foo/bar תועבר לנתיב /foo/bar של שרת המודל. פרטים נוספים מופיעים במאמר בנושא שימוש במסלולים מותאמים אישית שרירותיים.

הדרישות לפרסום קובצי אימג' של קונטיינרים

כדי להשתמש בקובץ אימג' של קונטיינר עם Agent Platform, צריך להעביר אותו בדחיפה אל Artifact Registry. איך מעבירים קובץ אימג' של קונטיינר ל-Artifact Registry

בפרט, צריך לדחוף את קובץ אימג' של קונטיינר למאגר שעומד בדרישות הבאות לגבי מיקום והרשאות.

מיקום

כשמשתמשים ב-Artifact Registry, המאגר צריך להשתמש באזור שתואם לנקודת הקצה מבוססת-המיקום שבה מתכננים ליצור Model. לדוגמה, אם אתם מתכננים ליצור Model בנקודת הקצה us-central1-aiplatform.googleapis.com, השם המלא של קובץ אימג' של קונטיינר צריך להתחיל ב-us-central1-docker.pkg.dev/. אל תשתמשו במאגר רב-אזורי לקובץ האימג' של הקונטיינר.

הרשאות

ל-Agent Platform צריכה להיות הרשאה לשליפת קובץ אימג' של קונטיינר כשיוצרים Model. באופן ספציפי, לסוכן השירות של Agent Platform בפרויקט צריכות להיות ההרשאות של התפקיד Artifact Registry Reader‏ (roles/artifactregistry.reader) במאגר של קובץ האימג' בקונטיינר.

Agent Platform משתמשת בנציג השירות של Agent Platform בפרויקט שלכם כדי ליצור אינטראקציה עם שירותים אחרים של Google Cloud . כתובת האימייל של חשבון השירות הזה היא service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, כאשר PROJECT_NUMBER מוחלף במספר הפרויקט של פרויקט Agent Platform.

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

לעומת זאת, אם העליתם את קובץ אימג' של קונטיינר לGoogle Cloud פרויקט אחר מזה שבו אתם משתמשים ב-Agent Platform, אתם צריכים להעניק לסוכן השירות של Agent Platform את התפקיד Artifact Registry Reader (קורא Artifact Registry) עבור מאגר Artifact Registry.

גישה לפריטי מידע שנוצרים בתהליך פיתוח (Artifact) של מודלים

כשיוצרים Model שעבר אימון מותאם אישית בלי קונטיינר מותאם אישית, צריך לציין את ה-URI של ספריית Cloud Storage עם ארטיפקטים של מודל בתור השדה artifactUri. כשיוצרים Model עם מאגר בהתאמה אישית, אפשר לספק ארטיפקטים של מודלים ב-Cloud Storage.

אם תמונת המאגר כוללת את ארטיפקטי המודל שדרושים להצגת מסקנות, אין צורך לטעון קבצים מ-Cloud Storage. עם זאת, אם מספקים ארטיפקטים של מודל על ידי ציון השדה artifactUri הקונטיינר חייב לטעון את הארטיפקטים האלה כשהוא מתחיל לפעול. כש-Agent Platform מפעיל את הקונטיינר, הוא מגדיר את משתנה הסביבה AIP_STORAGE_URI ל-URI של Cloud Storage שמתחיל ב-gs://. ההוראה ENTRYPOINT של הקונטיינר יכולה להוריד את הספרייה שצוינה ב-URI הזה כדי לגשת לארטיפקטים של המודל.

שימו לב שהערך של משתנה הסביבה AIP_STORAGE_URI לא זהה ל-URI של Cloud Storage שאתם מציינים בשדה artifactUri כשאתם יוצרים את Model. במקום זאת, AIP_STORAGE_URI מצביע על עותק של ספריית ארטיפקטים של המודל בקטגוריה אחרת של Cloud Storage, שמנוהלת על ידי Agent Platform. Agent Platform מאכלסת את הספרייה הזו כשיוצרים Model. אי אפשר לעדכן את התוכן של הספרייה. כדי להשתמש בארטיפקטים של מודל חדש, צריך ליצור Model חדש.

לחשבון השירות שבו המאגר משתמש כברירת מחדל יש הרשאה לקרוא מה-URI הזה.

לעומת זאת, אם מציינים חשבון שירות בהתאמה אישית כשפורסים את Model ב-Endpoint, Agent Platform מעניק אוטומטית לחשבון השירות שצוין את התפקיד 'צפייה באובייקט אחסון' (roles/storage.objectViewer) עבור קטגוריית Cloud Storage של ה-URI.

כדי לטעון את ארטיפקטים של המודל, אפשר להשתמש בכל ספרייה שתומכת ב-Application Default Credentials ‏ (ADC). לא צריך להגדיר אימות באופן מפורש.

משתני סביבה שזמינים במאגר התגים

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

משתנים שמוגדרים בקובץ אימג' של קונטיינר

כדי להגדיר משתני סביבה בקובץ האימג' של הקונטיינר כשיוצרים אותו, משתמשים בהוראה ENV של Docker. אל תגדירו משתני סביבה שמתחילים בקידומת AIP_.

אפשר להשתמש במשתני הסביבה האלה בהוראה ENTRYPOINT של הקונטיינר, אבל אי אפשר להפנות אליהם בשדות של Model API.

משתנים שמוגדרים על ידי Agent Platform

כש-Agent Platform מתחילה להריץ את הקונטיינר, היא מגדירה את משתני הסביבה הבאים בסביבת הקונטיינר. כל משתנה מתחיל בתחילית AIP_. אל תגדירו ידנית משתני סביבה שמשתמשים בקידומת הזו.

ההוראה ENTRYPOINT של מאגר התגים יכולה לגשת למשתנים האלה. כדי לדעת אילו שדות ב-Agent Platform API יכולים להפנות גם למשתנים האלה, אפשר לקרוא את הפניית ה-API ל-ModelContainerSpec.

משתנים שהוגדרו במשאב Model

כשיוצרים Model, אפשר להגדיר משתני סביבה נוספים בשדה containerSpec.env.

ההוראה ENTRYPOINT של מאגר התגים יכולה לגשת למשתנים האלה. כדי לדעת אילו שדות ב-Agent Platform API יכולים להפנות גם למשתנים האלה, אפשר לקרוא את הפניית ה-API ל-ModelContainerSpec.

המאמרים הבאים

• מידע נוסף על הצגת מסקנות באמצעות קונטיינר בהתאמה אישית, כולל איך מציינים שדות API שקשורים לקונטיינר כשמייבאים מודל