פתרון בעיות בהטמעה של סוכן

במסמך הזה מוסבר איך לפתור שגיאות שעלולות להתרחש כשפורסים סוכן ב-Agent Runtime. הוא כולל מגוון בעיות נפוצות, כולל כשלים בסריאליזציה, שגיאות הרשאה והפרות של גבולות VPC-SC.

הערה: כדי לחפש ולסנן יומני שגיאות של סוכנים, משתמשים בכלי Logs Explorer, בוחרים באפשרות RESOURCE TYPE 'Vertex AI Reasoning Engine' ובוחרים את הערך המתאים RESOURCE CONTAINER (כלומר, מספר הפרויקט) ואת הערך REASONING ENGINE ID.

שגיאות בתבניות מוכנות מראש

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

שגיאות שרת פנימיות

בעיה:

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

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

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

סיבות אפשריות:

• מצב לא נקי ב-LangchainAgent. זה יכול לקרות אם הפונקציה .set_up() הופעלה ב-LangchainAgent לפני פריסת הסוכן.
• גרסאות חבילה לא עקביות. זה יכול לקרות אם החבילות שהותקנו בסביבת הפיתוח שונות מהחבילות שהותקנו בסביבה המרוחקת בזמן הריצה של הסוכן.

פתרונות מומלצים:

• מצב לא נקי ב-LangchainAgent. צריך ליצור מופע חדש של LangchainAgent או להסיר את agent.set_up() מהקוד לפני פריסת הסוכן.
• מפרטי חבילה לא עקביים. אפשר לעיין בקטע בנושא פתרון בעיות של שגיאות סריאליזציה.

שגיאות סריאליזציה

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

אם נתקלתם בבעיות בסריאליזציה (שגיאות שקשורות ל-pickle או ל-pickling הן שגיאות שקשורות לסריאליזציה), יכול להיות שהן נובעות מאחת הבעיות שמתוארות בקטע הזה.

גרסת Pydantic

בעיה:

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

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

סיבה אפשרית:

זה יכול לקרות אם חבילת pydantic שלכם היא מגרסה מוקדמת יותר מגרסה 2.6.4. כדי לבדוק באיזו גרסה אתם משתמשים, מריצים את הפקודה הבאה במסוף:

pip show pydantic

פתרון מומלץ:

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

pip install pydantic --upgrade

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

pip show pydantic

אם אתם נמצאים במכונת מחברת (לדוגמה, Jupyter,‏ Colab או Workbench), יכול להיות שתצטרכו להפעיל מחדש את זמן הריצה כדי להשתמש בחבילות המעודכנות.

גרסת Cloudpickle

בעיה:

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

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

סיבה אפשרית:

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

pip show cloudpickle

פתרון מומלץ:

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

שגיאות שרת פנימיות

בעיה:

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

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

סיבה אפשרית:

זה יכול לקרות אם sys_version= שונה מסביבת הפיתוח כשפורסים את הסוכן.

פתרון מומלץ:

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

שגיאות בקטגוריה של Cloud Storage

אם נתקלתם בבעיות בקטגוריית הביניים של Cloud Storage שמשמשת בזמן הפריסה לאיסוף ולהעלאה של הסוכן, יכול להיות שהבעיה נובעת מאחת מהבעיות הבאות:

שגיאות הרשאה

פתרון מומלץ:

אם רוצים להשתמש בדלי קיים: מוודאים שלישות המורשית שאומתה לשימוש ב-Agent Platform (אתם או חשבון שירות) יש גישת Storage Admin לדלי, ומעניקים הרשאות לחשבון השירות.

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

אם עדיין נתקלים בבעיות, אפשר לדווח על באג.

לא נוצרת ספריית משנה בקטגוריית Cloud Storage

בעיה:

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

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

(השגיאה 404 מתרחשת כשהמערכת מנסה להעתיק לתיקייה שלא קיימת).

סיבה אפשרית:

הסיבה לכך היא כנראה בעיה באינטרפולציה של מחרוזות בגרסאות של google-cloud-aiplatform שקודמות לגרסה 1.49.0. הבעיה הזו תוקנה בגרסאות מאוחרות יותר. כדי לבדוק באיזו גרסה של google-cloud-aiplatform אתם משתמשים, מריצים את הפקודה הבאה במסוף:

pip show google-cloud-aiplatform

פתרון מומלץ:

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

pip install google-cloud-aiplatform --upgrade

כדי לוודא שאתם משתמשים בגרסה 1.49.0 ואילך של google-cloud-aiplatform, מריצים את הפקודה הבאה במסוף:

pip show google-cloud-aiplatform

אם אתם משתמשים במכונת מחברת (לדוגמה, Jupyter,‏ Colab או Workbench), יכול להיות שתצטרכו להפעיל מחדש את זמן הריצה כדי שתוכלו להשתמש בחבילות המעודכנות.

שגיאות של הפרת VPC-SC

אם נתקלתם בבעיות ב-VPC-SC, יכול להיות שהן נובעות מאחת מהבעיות הבאות:

שגיאות הרשאה

בעיה:

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

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

או:

Request is prohibited by organization's policy.

סיבה אפשרית:

הסיבה לכך היא כנראה שחסרים כללי תעבורת נתונים נכנסת (ingress) נדרשים בגבולות הגזרה של VPC-SC.

פתרון מומלץ:

אם אתם משתמשים ב-Agent Platform בסביבת VPC-SC, אתם צריכים ליצור כלל תעבורת נתונים נכנסת (ingress) בגבול הגזרה כדי לאפשר תעבורת נתונים נכנסת מסוכן השירות של Reasoning Engine ([e-mail]) לשירות storage.googleapis.com ולשירות artifactregistry.googleapis.com.

שגיאות בחשבונות שירות מותאמים אישית

אם נתקלתם בבעיות בחשבונות שירות, יכול להיות שהן נובעות מאחת מהבעיות הבאות:

פעולה בתור חשבון שירות

בעיה:

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

You do not have permission to act as service_account.

סיבה אפשרית:

יכול להיות שאין לכם הרשאת iam.serviceAccounts.actAs בחשבון השירות המותאם אישית שמשמש לפריסה. שימו לב: במערכת מרובת סוכנים שבה יש כמה חשבונות שירות מותאמים אישית, מחבר או פורס של סוכן יכול לפעול בתור חלק מחשבונות השירות. אם משתמשים בחשבון שירות לא נכון, השגיאה הזו היא ההתנהגות הצפויה

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

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

פתרון מומלץ:

מוודאים שאתם משתמשים בחשבון השירות הרצוי. בודקים אם יש לכם את התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות הזה. אם לא, צריך לבקש מהאדמין להקצות לכם את התפקיד בחשבון השירות הזה.

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

שרת המטא-נתונים לא זמין

בעיה:

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

ServiceUnavailable: 503 Getting metadata from plugin failed with error

או

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

סיבה אפשרית:

זה יכול לקרות אם חשבון השירות המותאם אישית והסוכן נמצאים בפרויקטים שונים, ולסוכן השירות של AI Platform Reasoning Engine אין הרשאת iam.serviceAccounts.getAccessToken בחשבון השירות המותאם אישית.

במאמר הזה מפורטת הרשימה המלאה של ההגדרות הנדרשות לתרחיש הזה.

פתרון מומלץ:

מבקשים מהאדמין להקצות לסוכן השירות של פרויקט הסוכן את התפקיד יצירת אסימונים בחשבון שירות (roles/iam.serviceAccountTokenCreator) בחשבון השירות המותאם אישית.

סוכן השירות של AI Platform Reasoning Engine צריך להיות באותו פרויקט שבו אתם משתמשים כדי לפרוס את הסוכן. הקישור של הקצאת התפקיד ב-IAM צריך להיות בפרויקט שבו נמצא חשבון השירות המותאם אישית.

שגיאות של עומס על משאבים או הגבלת קצב (שגיאה 429)

בעיה:

הפריסה נכשלת עם הסטטוס Error 429 או RESOURCE_EXHAUSTED.

סיבה אפשרית:

הפרויקט חרג ממגבלות קצב הבקשות ל-API או ממכסות הבקשות המקבילות.

פתרונות מומלצים:

• הטמעה של אסטרטגיה של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) וניסיון חוזר בסקריפטים של פריסה.
• בדף Quotas (מכסות) של Agent Platform API (ממשק API של פלטפורמת סוכנים) אפשר לבדוק את השימוש הנוכחי לעומת המגבלות. Google Cloud
• צריך להפחית את התדירות של פריסות בו-זמניות.

משאבי תמיכה

אם הבעיה עדיין לא נפתרה, אפשר להיעזר במדריך התמיכה.