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

ML Workload Debugging Wiki הוא מאגר ב-GitHub שסוכני AI לכתיבת קוד משתמשים בו כדי לפתור בעיות בעומסי עבודה של TPU שפועלים ב-Google Kubernetes Engine ‏ (GKE) עם JAX,‏ XLA או Pathways. הוויקי מאפשר לסוכני ה-AI לאסוף יומני עומסי עבודה, להתאים חתימות שגיאה למצבי כשל ידועים, להריץ תהליכי עבודה של אבחון ולדווח על שורש הבעיה על סמך היומנים. כך הסוכנים מקבלים את המידע שנדרש כדי לאבחן קריסות, תקיעות, הפעלות מחדש או הפסקות של עומסי עבודה.

הוויקי מכיל שני סוגים של חומרי עזר:

  • דפי ידע: דפי Markdown שמתארים מושגים, תסמינים של כשלים וחתימות היומן שלהם, פלייבוקים לפתרון בעיות וכלי אבחון.
  • הליכים שניתנים להפעלה: פעולות ותהליכי עבודה ב-JSON. פעולה היא שלב אבחון יחיד, כמו שאילתת יומן או פקודת kubectl. תהליך עבודה מריץ רצף של פעולות כדי לאבחן מצב כשל ספציפי.

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

קובצי מפתחות

בטבלה הבאה מפורטים הקבצים והספריות העיקריים ב-Debug ML Workloads Wiki:

נתיב תיאור
_wiki/TUTORIAL.md הסבר על מה שקורה במהלך האבחון ואיך להעריך את התוצאות, כולל דוגמה מעשית.
_wiki/INDEX.md קטלוג של כל דף, פעולה ותהליך עבודה בוויקי, עם סיכום של שורה אחת לכל אחד.
_wiki/concepts/ מושגים שקשורים לארכיטקטורת המערכת ולמחזור החיים של הרכיבים, כמו מחזור החיים של תוכנית libtpu, קצב העברת הנתונים (goodput) ומעקב אחרי התקדמות עומס העבודה.
_wiki/entities/ ישויות של חומרה, תוכנה ופלטפורמה, כמו TPU,‏ GPU,‏ JAX,‏ XLA ו-Pathways.
_wiki/symptoms/ מצבי כשל, חתימות היומן שלהם ואיך לאמת כל אחד מהם.
_wiki/playbooks/ אסטרטגיות לפתרון בעיות, תרשימי זרימה של עצי החלטות ומלכודות נפוצות.
_wiki/tools/ כלי אבחון, סקריפטים ומדריכי עזר לשורת הפקודה.
_wiki/workflows/ הליכי אבחון ב-JSON. כל תהליך עבודה מריץ רצף של פעולות כדי לאבחן מצב כשל ספציפי.
_wiki/actions/ שלבי אבחון ספציפיים ב-JSON, כמו שאילתות ביומן ופקודות kubectl.
_wiki/SCHEMA.md סוגי הדפים, הדרישות של ה-frontmatter ותגי הטקסונומיה שדפי הוויקי צריכים לעמוד בהם.
_agents/QUICKSTART.md פרטי ההגדרה והשליחה למשתמשי Antigravity.
CLAUDE.md פריסת סביבת העבודה, כלי שורת הפקודה ותפקידי סוכני המשנה, למשתמשי Claude Code.

פקודות מקשים

בטבלה הבאה מפורטות הפקודות שאפשר להריץ באמצעות הוויקי:

פקודה Usage תיאור
/troubleshoot ‫/troubleshoot WORKLOAD_ID, כאשר WORKLOAD_ID הוא השם של עומס העבודה או של JobSet. אבחון עומס עבודה באמצעות Cloud Logging, אירועים באשכול GKE, יומני kubelet ויומני צמתים. סוכני המשנה לניתוב, לביצוע, לבדיקה ולייעוץ מריצים את האבחון ומדווחים על שורש הבעיה, על המארחים שגרמו לבעיה כפי שצוין ביומנים ועל טבלת כשלים.
/dashboard ‫/dashboard [TARGET], כאשר TARGET הוא מזהה פרויקט, שם אשכול או מזהה עומס עבודה אופציונלי. אם לא מציינים את TARGET, במרכז הבקרה מוצגים כל אשכולות ה-GKE בפרויקט שמוגדר ב-Google Cloud CLI. הפעלת GKE Capacity & Triage Dashboard, אפליקציית אינטרנט מקומית בכתובת http://localhost:8080. הפקודה סורקת את האשכולות כדי למצוא את היעד, ואז מחזירה קישור לתצוגה של מרכז הבקרה שמסוננת לפי היעד.
/handoff

/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]

כל הארגומנטים, חוץ מ-WORKLOAD_ID, הם אופציונליים:

  • ‫CASE_ID: מספר בקשת התמיכה.
  • ‫--bucket=BUCKET: שם הקטגוריה. אם לא תציינו את הדגל הזה, הנציג יבקש קטגוריה.
  • ‫--findings=PATH: הנתיב לקובץ ממצאים קיים. אם מגדירים את הדגל הזה, הפקודה לא מריצה את /troubleshoot.
  • ‫--no-watch: השבתת המעקב אחר קטגוריות.
 אוסף את הממצאים של /troubleshoot בקטגוריה של Cloud Storage כדי לשתף אותם עם Cloud Customer Care, ואז עוקב אחרי הקטגוריה כדי לראות אם יש עדכונים. כדי לבדוק אם יש עדכונים בהמשך, מריצים את הפקודה /handoff --watch STORAGE_KEY, כאשר STORAGE_KEY הוא השם של תיקיית ההעברה בקטגוריה.

דרישות מוקדמות

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

  • השם של עומס העבודה או של ה-JobSet.
  • מזהה הפרויקט ב- Google Cloud שבו פועל עומס העבודה.
  • טווח הזמן המשוער של ההפעלה שרוצים לאבחן.

התקנות

כדי להשתמש בוויקי, צריך להתקין את הדברים הבאים:

  1. מתקינים את Python 3, כולל המודול venv. כדי להשתמש בוויקי, צריך להתקין את Python מגרסה 3.9 ואילך. ב-Debian וב-Ubuntu, המודול venv נמצא בחבילה python3-venv.
  2. מתקינים ומפעילים את Google Cloud CLI.
  3. מתקינים את kubectl ואת gke-gcloud-auth-plugin.
  4. מתקינים את אחד מסוכני ה-AI לתכנות הבאים. הוויקי כולל קובצי תצורה לשני המקרים:

התפקידים הנדרשים

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

  • צפייה ביומנים (roles/logging.viewer): מאפשר לסוכנים לקרוא את יומני הביקורת, הקונטיינרים והצמתים של עומס העבודה.
  • צפייה ב-Kubernetes Engine‏ (roles/container.viewer): מאפשרת לנציגים לבדוק את האשכול, הצמתים וה-pods שהריצו את עומס העבודה.
  • צפייה ב-Compute‏ (roles/compute.viewer): מאפשרת לסוכנים לבדוק את המכונות הווירטואליות של Compute Engine שתומכות בצומתי האשכול, כולל אירועי תחזוקה וסיום של מכונות וירטואליות.
  • צפייה במעקב (roles/monitoring.viewer): מאפשרת לסוכנים לקרוא מדדי Cloud Monitoring של תהליכי עבודה שבודקים מדדים של עומסי עבודה וצמתים.

כדי להריץ את הפקודה /handoff, צריך גם את התפקיד "אדמין של אובייקטים ב-Storage" (roles/storage.objectAdmin) בקטגוריה של Cloud Storage שמשתפים עם Cloud Customer Care. התפקיד הזה מאפשר לסוכנים להעלות ממצאים לקטגוריה ולעקוב אחרי עדכונים.

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

הגדרת ה-wiki

  1. משכפלים את המאגר ועוברים לתיקיית השורש שלו:

    git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki

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

  2. יוצרים ומפעילים סביבה וירטואלית של Python ומתקינים את יחסי התלות של הוויקי:

    python3 -m venv _wiki/.venv
source _wiki/.venv/bin/activate
pip install -r _wiki/requirements.txt

  3. יוצרים Application Default Credentials‏ (ADC) מקומיים לחשבון המשתמש. כלי ה-Python של הוויקי משתמשים ב-ADC כדי לשלוח שאילתות ל-Cloud Logging:

    gcloud auth application-default login

  4. כדי לוודא שההגדרה תקינה, מריצים את ה-wiki linter:

    python3 _wiki/wiki_linter.py

    ה-linter בודק את המבנה, הסכימות והקישורים של הוויקי, ואז מדפיס דוח JSON. אם הדוח מכיל את הערך "status": "PASS", הבדיקה הצליחה. אזהרות בדוח לא משפיעות על הסטטוס.

פתרון בעיות בעומס עבודה

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

  1. מפעילים את הנציג מהשורש של מאגר ML Workload Debugging Wiki:

    • ‫Claude Code: במעטפת שבה הפעלתם את הסביבה הווירטואלית, מריצים את claude. ‫Claude Code טוען את ההוראות של הוויקי מ-CLAUDE.md ואת הגדרות הפקודות והסוכנים המשניים מהספרייה .claude/.
    • ‫Antigravity: פותחים את התיקייה הראשית של המאגר כסביבת העבודה. ההגדרות של המיומנות ושל סוכן המשנה של Antigravity בוויקי נמצאות בספרייה _agents/. פרטים על ההגדרה מופיעים במאמר _agents/QUICKSTART.md.

  2. מריצים את הפקודה /troubleshoot ומציינים את שם עומס העבודה או ה-JobSet שרוצים לאבחן:

    /troubleshoot WORKLOAD_ID

  3. ציינו לנציג את מזהה הפרויקט ואת טווח התאריכים של ההרצה. אפשר לציין טווח זמן מדויק בפורמט של חותמת זמן ב-UTC (YYYY-MM-DDTHH:MM:SSZ), או טווחי זמן יחסיים בשפה טבעית, כמו "לפני שעה" או "ב-24 השעות האחרונות". הסוכנים משתמשים בטווח תאריכים כדי להגדיר את היקף השאילתות ביומן, לכן חשוב לוודא שהוא מכסה את כל ההרצה.

כברירת מחדל, תהליכי העבודה של האבחון מריצים בדיקות לקריאה בלבד. לפני שהסוכן מריץ פעולה שמשנה את מצב האשכול, כמו הפעלה מחדש או סימון של צומת כפגום, הוא מבקש אישור מפורש. צריך לבדוק ולאשר כל פקודה. הפעולות האלה מסומנות ב-requires_approval: true בהגדרות שלהן ב-_wiki/actions/. הנציג מדווח על הממצאים שלו אחרי שהאבחון מסתיים.

במאמר _wiki/TUTORIAL.md מוסבר איך להעריך את הממצאים, כולל איך לזהות תוצאה לא חד-משמעית.