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

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

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

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

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

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

הבעיה:

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

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

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

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

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

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

שגיאות בסידור הפרקים

באופן כללי, חשוב לוודא שהסביבות "המקומית" ו "המרוחקת" מסונכרנות כשפורסים את הנציג. כדי לוודא שזה קורה, אתם יכולים לציין את הערך 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

אם אתם משתמשים במכונה של Notebook (לדוגמה, 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

אם נתקלתם בבעיות בקטגוריית ה-Staging ב-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

אם אתם משתמשים במכונה של Notebook (לדוגמה, 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, אתם צריכים ליצור כלל תעבורת נתונים נכנסת בגבולות הגזרה כדי לאפשר תעבורת נתונים נכנסת מסוכן השירות של מנוע חשיבה רציונלית (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.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 מנוע חשיבה רציונלית אין את ההרשאה iam.serviceAccounts.getAccessToken בחשבון השירות בהתאמה אישית.

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

פתרון מומלץ:

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

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

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

הבעיה:

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

סיבה אפשרית:

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

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

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

יש כרגע עומס גדול מהרגיל באזור

הבעיה:

הפריסה נכשלת עם הסטטוס 429, RESOURCE_EXHAUSTED והודעה שאומרת שהאזור הגיע באופן זמני לקיבולת המקסימלית של הזיכרון או המעבד (CPU).

סיבה אפשרית:

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

המגבלה הזו היא לא אחת מהמכסות של הפרויקט. היא לא מופיעה בדףCloud de Confiance Quotas ואי אפשר להגדיל אותה באמצעות בקשה להגדלת מכסה.

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

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

פתרונות שלא רלוונטיים:

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

מספר המכונות המקסימלי חורג מהמגבלה האזורית

הבעיה:

הפריסה נכשלת עם הסטטוס 429, RESOURCE_EXHAUSTED והודעה שאומרת ש-spec.deployment_spec.max_instances חורג מהמספר המקסימלי של מכונות שנתמכות עבור המעבד (CPU) או הזיכרון המבוקשים ב-resource_limits של האזור.

סיבה אפשרית:

כשפורסים סוכן, Agent Runtime מכפיל את spec.deployment_spec.max_instances ב-cpu וב-memory לכל מכונה ב-spec.deployment_spec.resource_limits, ובודק אם ההקצאה המקסימלית של הסוכן היחיד הזה מתאימה למגבלה האזורית של הפרויקט הבסיסי להצגת מודעות. אם לא מציינים את max_instances, Agent Runtime מחיל ערך ברירת מחדל (כמו 200), שבאזורים עם מגבלות נמוכות יותר יכול לחרוג ממספר המכונות המקסימלי הנתמך כשמכפילים אותו ב-cpu או ב-memory שהוגדרו לכל מכונה.

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

  • מגדירים את spec.deployment_spec.max_instances לערך המקסימלי שמוצג בהודעת השגיאה (או פחות).
  • מפחיתים את הערך של cpu או memory לכל מכונה ב-spec.deployment_spec.resource_limits.
  • פורסים את הנציג באזור נתמך אחר עם מגבלה גבוהה יותר.

פתרונות שלא רלוונטיים:

  • בקשה להגדלת המכסה בדף Cloud de Confiance Quotas של הפרויקט לא תשפיע, כי המגבלה הזו נאכפת בפרויקט להצגת מודעות שמנוהל על ידי Google, ולא בפרויקט שלכם.
  • מחיקת סוכנים אחרים בפרויקט או ניסיון חוזר בלי לשנות את max_instances או את resource_limits לא פותרים את השגיאה, כי הבדיקה מעריכה את ההקצאה המקסימלית של הפריסה היחידה ביחס למגבלה סטטית.

שגיאות גישה ל-Secret Manager

הבעיה:

הפריסה נכשלת עם הסטטוס 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) והודעה דומה לזו:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

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

  • ‫NOT_FOUND: מזהה הסוד או מזהה הגרסה שצוינו ב-secret_env לא קיימים ב-Secret Manager באותו פרויקט שבו פרוס הנציג, או שהם מכילים שגיאת הקלדה.
  • ‫DESTROYED או DISABLED: גרסת הסוד שאליה מפנים ב-Secret Manager מושמדת או מושבתת.
  • ‫PERMISSION_DENIED: לחשבון השירות שמשמש את הנציג אין את התפקיד "גישה לסודות של Secret Manager" (roles/secretmanager.secretAccessor) בסוד שאליו מפנים.

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

  • ב-NOT_FOUND, ב-DESTROYED או ב-DISABLED:
    1. בדף Secret Manager של הפרויקט שבו אתם פורסים את הנציג, ודאו שכל SECRET_ID ו-VERSION_ID שמוזכרים ב-secret_env קיימים ונמצאים במצב Enabled.
    2. אם גרסה שצוינה הושבתה או הושמדה, צריך להפעיל גרסה תקינה או לעדכן את secret_env כך שתציין גרסה פעילה.
  • ב-PERMISSION_DENIED: מקצים את התפקיד מבקש גישה לסודות ב-Secret Manager (roles/secretmanager.secretAccessor) בסוד (או בפרויקט שמכיל את הסוד) לחשבון השירות שמאחזר את הסוד:
    • חשבון שירות שמוגדר כברירת מחדל: מקצים את התפקיד לסוכן השירות של מנוע החשיבה הרציונלית של פלטפורמת AI‏ (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com).
    • חשבון שירות בהתאמה אישית: מקצים את התפקיד לחשבון השירות בהתאמה אישית שמוגדר בסוכן.

הסתיים הזמן הקצוב לבניית קובץ אימג' של קונטיינר

הבעיה:

הפריסה נכשלת עם הסטטוס 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) והודעה שאומרת שקובץ האימג' של הקונטיינר של הנציג לא סיים את הבנייה בזמן.

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

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

  • רשימה ארוכה של חבילות ב-requirements, כולל חבילות שהסוכן לא משתמש בהן.
  • חבילות בלי קובצי wheel שנבנו מראש לסביבת ה-build, שמקומפלות מהמקור במהלך ה-build.
  • גרסאות לא מוצמדות או מוצמדות באופן רופף, שמאטות את פתרון התלות.

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

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

הקונטיינר לא הופעל בזמן

הבעיה:

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

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

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

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

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

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

משאבי תמיכה

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