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

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

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

שגיאות בבנייה ובהפעלה של קונטיינרים

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

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

הבעיה:

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

The Reasoning Engine could not be deployed because its container image failed to build.

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

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

  • התקנת דרישות החבילה: חבילה ב-requirements או בקובץ הדרישות של קובצי המקור לא קיימת, מצמידה גרסה שלא קיימת, מתנגשת עם חבילה אחרת או לא תומכת בגרסת Python של הסוכן.
  • התקנת קובץ wheel מקומי: קובץ wheel שמופיע ב-requirements לא נכלל גם ב-extra_packages, ולכן אי אפשר להתקין אותו.
  • הרצת סקריפטים של התקנה: סקריפט בספרייה installation_scripts נסגר עם שגיאה.
  • פיתוח קובץ Docker: כשפורסים מקובץ Docker ‏(image_spec), הוראה בקובץ Docker נכשלת.

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

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

    python -m venv agent-env
    agent-env/bin/pip install -r requirements.txt
  • כדי שהגרסאות שבדקתם באופן מקומי יותקנו ב-build, צריך להצמיד את גרסאות החבילות. הגדרת הדרישות של החבילה

  • אם מתקינים קובץ wheel מקומי, צריך לכלול אותו גם ב-requirements וגם ב-extra_packages. הגדרת חבילות נוספות

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

  • אם אתם פורסים מקובץ Docker, אתם צריכים ליצור את קובץ האימג' של הקונטיינר באופן מקומי מאותם קובצי מקור (לדוגמה, באמצעות docker build) ולתקן את ההוראות שנכשלו.

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

  • אם תנסו לפרוס מחדש בלי לשנות את הדרישות, את הסקריפטים להתקנה או את קובץ ה-Dockerfile, הפריסה תיכשל באותו אופן כי ה-build יריץ את אותם השלבים.

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

הבעיה:

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

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

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

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

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

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

הפעלת הקונטיינר נכשלה

הבעיה:

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

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

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

  • תלות חסרה: הנציג מייבא חבילה שלא מופיעה ב-requirements או ב-extra_packages, ולכן טעינת הנציג נכשלת עם שגיאה כמו ModuleNotFoundError.
  • חוסר התאמה בין גרסאות החבילות: החבילות שמותקנות בסביבה שנפרסה שונות מאלה שבסביבת הפיתוח, ולכן טעינת הנציג נכשלת ומופיעה שגיאה כמו AttributeError: Can't get attribute. שגיאות בסדרתיות
  • שגיאה במהלך האיניציאליזציה: השיטה set_up() של הסוכן, או קוד אחר שפועל כשהסוכן נטען, גורמים לחריגה או ממתינים למשאב שאי אפשר להגיע אליו.
  • אתחול איטי: טעינת הסוכן נמשכת יותר זמן מהזמן הקצוב לתפוגה של ההפעלה.
  • קונטיינר בהתאמה אישית לא מאזין: קונטיינר בהתאמה אישית צריך להאזין לבקשות HTTP ב-0.0.0.0 ביציאה 8080. לעיון בחוזה של סביבת זמן הריצה
  • הפעלה חסומה של Agent Gateway: כשמנתבים תנועה דרך Agent Gateway, ההפעלה נכשלת אם Identity-Aware Proxy ‏(IAP) חוסם קריאות לאתחול, אם לזהות של הסוכן אין את התפקידים הנדרשים או אם קונטיינר בהתאמה אישית לא נותן אמון באישור הבסיס של השער. אפשר לעיין במאמרים שגיאות במהלך ההפעלה של Agent Runtime וסוכן שנפרס עם קונטיינר בהתאמה אישית (BYOC) לא מצליח להתחבר ל-Agent Gateway.

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

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

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

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

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

הבעיה:

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

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

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

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

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

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

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

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

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

הבעיה:

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

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

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

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

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

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

  • מצב מלוכלך ב-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

אם אתם משתמשים במכונה של 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.

פתרון מומלץ:

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

הקצאת הסביבה נכשלה

הבעיה:

יצירת הנציג נכשלת עם הסטטוס 500, INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED) והודעה שאומרת שלא ניתן היה להקצות את הסביבה של הנציג שמנוהלת על ידי Google.

סיבה אפשרית:

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

פתרון מומלץ:

פנו לתמיכה וציינו את שם הפעולה שנכשלה בפורמט projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

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

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

שגיאות של עומס על משאבים

אם הפריסה נכשלת עם הסטטוס 429, RESOURCE_EXHAUSTED, יכול להיות שהסיבה היא אחת מהבעיות הבאות:

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

הבעיה:

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

סיבה אפשרית:

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

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

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

אי אפשר ליצור תמונות כרגע בגלל עומס חריג באזור

הבעיה:

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

סיבה אפשרית:

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

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

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

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

החיפוש ב-Agent Gateway הוגבל

הבעיה:

הפריסה או העדכון של סוכן שמשתמש ב-Agent Gateway נכשלים עם סטטוס 429,‏ RESOURCE_EXHAUSTED (REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) והודעה דומה לזו:

The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.

סיבה אפשרית:

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

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

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

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

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

שגיאות גישה ל-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.).
    • חשבון שירות בהתאמה אישית: מקצים את התפקיד לחשבון השירות בהתאמה אישית שמוגדר ב-Agent.

שגיאות בקישור של Agent Gateway

אם אתם מנתבים תנועה דרך Agent Gateway, והפריסה או העדכון של הנציג נכשלים לפני שהנציג מתחיל לפעול, יכול להיות שהסיבה היא אחת מהבעיות הבאות:

נגמר הזמן הקצוב לקישור של Agent Gateway

הבעיה:

פריסה או עדכון של סוכן נכשלים עם הסטטוס 504, DEADLINE_EXCEEDED (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) והודעה דומה לזו:

The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.

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

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

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

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

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

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

  • בדיקה של יומני הקונטיינר או של יומני התנועה של Agent Gateway לא מציגה שגיאה לגבי הכשל הזה, כי הזמן הקצוב לתפוגה מתרחש לפני ש-Agent Runtime מפעיל את הקונטיינר של הסוכן.
  • שינוי הקוד, requirements או resource_limits של הנציג לא מקצר את זמן ההגדרה של הקישור המשותף.

אם הקישור לשער מצליח אבל המאגר לא מופעל, קראו את המאמר שגיאות במהלך ההפעלה של Agent Runtime.

הקישור של Agent Gateway בוטל

הבעיה:

פריסה או עדכון של סוכן נכשלים עם הסטטוס 409,‏ ABORTED (REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED) והודעה שדומה לזו:

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.

סיבה אפשרית:

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

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

  • צריך להמתין לפחות 10 דקות עד ש-Agent Runtime יסיים את החזרה למצב הקודם של ההגדרה שנכשלה, ואז לנסות שוב לפרוס או לעדכן. אם מנסים שוב לפני שהחזרה למצב הקודם מסתיימת, הניסיון עלול להיכשל עם הסטטוס 504, DEADLINE_EXCEEDED. הזמן הקצוב לתפוגה של הקישור ל-Agent Gateway
  • כדי לנסות שוב כמה פריסות או עדכונים, נסו קודם אחד, המתינו עד שהפעולה תצליח ואז נסו שוב את השאר בו-זמנית. אם הפעולה הראשונה נכשלת, היא מחזירה את השגיאה הבסיסית במקום 409, ABORTED (לדוגמה, Agent Gateway binding temporarily unavailable או Container image build failed), שאפשר לחפש בקטלוג השגיאות.

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

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

הקישור ל-Agent Gateway לא זמין באופן זמני

הבעיה:

פריסה או עדכון של סוכן נכשלים עם סטטוס 503, UNAVAILABLE (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE) והודעה שדומה לזו:

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.

סיבה אפשרית:

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

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

  • צריך להמתין לפחות 10 דקות עד ש-Agent Runtime יסיים את החזרה למצב הקודם של ההגדרה שנכשלה, ואז לנסות שוב לפרוס או לעדכן. אם מנסים שוב לפני שהחזרה למצב הקודם מסתיימת, הניסיון עלול להיכשל עם הסטטוס 504, DEADLINE_EXCEEDED. הזמן הקצוב לתפוגה של הקישור ל-Agent Gateway
  • אם השגיאה נמשכת אחרי כמה ניסיונות, פנו לתמיכה וציינו את שם הפעולה שנכשלה בפורמט projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

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

  • שינוי הקוד של הסוכן, requirements או resource_limits לא יעזור, כי הכשל מתרחש לפני ש-Agent Runtime פורס את הסוכן.
  • בקשה להגדלת המכסה של הפרויקט לא תשפיע, כי Google מנהלת את משאבי הרשת האלה.

משאבי תמיכה

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