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

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

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

אם נתקלתם בבעיות בתבנית 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.

סיבה אפשרית:

הסיבה לכך היא כנראה שחסרים כללי כניסה נדרשים במתחם ההיקפי של VPC-SC.

פתרון מומלץ:

אם אתם משתמשים ב-Agent Platform בסביבת VPC-SC, אתם צריכים ליצור כלל תעבורת נתונים נכנסת (ingress) בגבול הגזרה כדי לאפשר תעבורת נתונים נכנסת מסוכן השירות של Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) לשירות 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
  • צריך להפחית את התדירות של פריסות בו-זמניות.

משאבי תמיכה

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