‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

תחילת העבודה עם ML Diagnostics CLI

אפשר להשתמש ב-ML Diagnostics Google Cloud CLI כדי ליצור ולנהל הרצות של למידת מכונה, לפרוס את XProf כמופע מנוהל עם קצה עורפי (backend) ניתן להרחבה, ולספק חוויית פרופיל מנוהלת ב- Google Cloud. אפשר גם להשתמש ב-CLI או ב-API כדי לראות רשימה של כל האירועים שזוהו על ידי ניטור עומסי העבודה, ולקבל פרטים על הניתוח של האירועים האלה.

יש שלוש קטגוריות של פקודות ה-CLI של gcloud ל-ML Diagnostics:‏ machine-learning-run, profiler ו-monitored-events. משתמשים בפקודות machine-learning-run כדי ליצור, למחוק, לתאר, להציג ברשימה ולעדכן הרצות של למידת מכונה. אפשר להשתמש בפקודות profiler כדי להציג רשימה של צמתים ולתעד פרופילים לפי דרישה מ-CLI. אפשר להשתמש בפקודות monitored-events כדי להציג רשימה של כל האירועים שזוהו על ידי ניטור עומסי העבודה, ולקבל פרטים על כל אירוע מהכלי לניתוח.

Machine-learning-run פקודות: Create, Delete, Describe, List, Update.
Monitored-events פקודות: Describe, List
פקודות של כלי הפרופילים:
- profiler-target: List
- profiler-session: Capture, List

כל הפקודות ב-CLI של gcloud דורשות פרויקט שמוגדר בסביבה. כדי להגדיר את הפרויקט:

gcloud config set project PROJECT_ID

מידע נוסף על הפקודות של ML Diagnostics ב-CLI של gcloud זמין בהפניית ה-API.

תיעוד פרופילים

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

כדי להפעיל צילום פרופיל לפי דרישה, צריך להפעיל את שרת XProf בקוד ולקרוא לשיטת profiler.start_server. הפעולה הזו מפעילה שרת XProf בעומס העבודה של למידת המכונה, שממתין להפעלת הלכידה לפי דרישה כדי להתחיל ללכוד פרופילים. משתמשים ביציאה 9999 עבור הפקודה הזו: profiler.start_server(port=9999)

גם בלכידת פרופילים אוטומטית וגם בלכידת פרופילים לפי דרישה, צריך לציין את המיקום שבו יישמרו הפרופילים שנלכדו. לדוגמה: gs://my-bucket/my-run. הפרופילים מאוחסנים בספריות שמוטמעות במיקום:gs://my-bucket/my-run/plugins/profile/session1/. אי אפשר להשתמש בו-זמנית בתיעוד פרופילים באופן פרוגרמטי ובתיעוד על פי דרישה.

כדי לצלם פרופיל לפי דרישה, צריך להגדיר אשכול GKE שבו מותקן connection-operator. כדי להגדיר לכידה פרוגרמטית של פרופילים, צריך להגדיר אשכול GKE שמתקין את injection-webhook באמצעות ML Diagnostics SDK ולתייג את עומס העבודה.

מידע נוסף על יצירת פרופילים באמצעות JAX זמין במאמר יצירת פרופילים של חישובים.

יצירת הפעלה של למידת מכונה

יוצרים משאב של הפעלת למידת מכונה בפרויקט ובמיקום שצוינו. הפקודה machine-learning-run create פורסת את XProf כמכונה מנוהלת בפרויקט שלכם. מופע מנוהל של XProf משמש לצפייה בכל הפרופילים בפרויקט, והוא נוצר כשיוצרים את ההרצה הראשונה של למידת מכונה בפרויקט.

משתמשים בפקודה machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

יש שתי דרכים ליצור הרצה של למידת מכונה:

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

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

הקוד הבא יוצר הפעלה ורושם פרופילים קיימים שצולמו ב-ML Diagnostics:

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --run-group GROUP_NAME \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --labels "list_existing_sessions_only"="true"

בדוגמת הקוד נעשה שימוש בדגלים הבאים:

דגל	דרישה	תיאור
`machine-learning-run`	חובה	מזהה ייחודי של הריצה הספציפית הזו. אם השם לא ייחודי, יצירת ההרצה תיכשל ותוצג ההודעה: 'ההרצה של ה-ML כבר קיימת'.
`location`	חובה	כל המיקומים של Cluster Director נתמכים, מלבד `us-east5`. אפשר להגדיר את הדגל הזה באמצעות ארגומנט לכל פקודה, או באמצעות הפקודה: `gcloud config set compute/region`.
`gcs-path`	חובה	Google Cloud מיקום האחסון שבו נשמרים כל הפרופילים. לדוגמה: `gs://my-bucket` או `gs://my-bucket/folder1`. חובה רק אם משתמשים ב-SDK לצורך איסוף נתונים של פרופילים.
`run-group`	אופציונלי	מזהה שיכול לעזור לקבץ כמה הרצות ששייכות לאותו ניסוי. לדוגמה, כל ההרצות שמשויכות לסריקה של גודל פרוסת TPU יכולות להיות שייכות לאותה קבוצה.
`display-name`	אופציונלי	השם המוצג של ההרצה של למידת המכונה. אם לא מציינים את המזהה, הוא מוגדר כמזהה ההרצה של הלמידה החישובית.

הדגל --labels list_existing_sessions_only=true נדרש אם רוצים לראות ולנהל פרופילים קיימים שנאספו בכלי האבחון של ML. הדגל מבצע את הפעולות הבאות:

יוצר הפעלה של למידת מכונה עם הסטטוס 'הושלם'.
חיפוש רקורסיבי של קובצי xplane.pb בנתיב של ספריית Cloud Storage.
טוען את כל הסשנים של הפרופילים שאותרו למסד הנתונים של ML Diagnostics כדי להציג אותם ב- Google Cloud, יוצר קישורים שאפשר לשתף לסשנים של הפרופילים ומאפשר למשתמשים לנהל את הפרופילים האלה באמצעות פלטפורמת ML Diagnostics.

אם הדגל --labels list_existing_sessions_only מוגדר לערך true להרצה, אי אפשר לבצע פרופיל לפי דרישה או לעדכן את ההרצה. אתם יכולים רק לצפות בפרופילים קיימים ולנהל אותם.

יצירת הפעלה של למידת מכונה כדי לבצע לכידה של פרופיל לפי דרישה

הקוד הבא יוצר mlrun כדי לבצע לכידת פרופיל לפי דרישה:

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --orchestrator gke \
  --run-group RUN_GROUP \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --gke-cluster-name projects/user/locations/LOCATION/clusters/CLUSTER_NAME \
  --gke-namespace NAMESPACE \
  --gke-workload-name WORKLOAD_NAME \
  --gke-kind GKE_KIND \
  --gke-workload-create-time CREATE_TIME \
  --run-phase RUN_PHASE

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

דגל	דרישה	תיאור
`orchestrator`	אופציונלי	כלי התזמור שבו נעשה שימוש להרצה. אם לא מציינים ערך, המערכת משתמשת בערך ברירת המחדל `gke`. ערכים תקינים: `gce`, ‏ `gke`, ‏ `slurm`.
`gke-cluster-name`	נדרש ל-GKE	האשכול של עומס העבודה. לדוגמה: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	נדרש ל-GKE	סוג עומס העבודה. לדוגמה: `JobSet`.
`gke-namespace`	נדרש ל-GKE	מרחב השמות של עומס העבודה. לדוגמה: `default`.
`gke-workload-name`	נדרש ל-GKE	המזהה של עומס העבודה. לדוגמה: `jobset-abcd`.
`gke-workload-create-time`	נדרש ל-GKE	חותמת הזמן של יצירת JobSet בפורמט חותמת זמן ISO. לדוגמה: `2026-02-20T06:00:00Z`.
`run-phase`	אופציונלי	השלב והסטטוס של הריצה. אם לא מציינים ערך, ברירת המחדל היא `ACTIVE`.

תיאור של הרצת למידת מכונה

כדי לראות את הפרטים של הרצת למידת מכונה, מריצים את הפקודה machine-learning-run describe:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME --FORMAT=FORMAT

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

gcloud alpha mldiagnostics machine-learning-run describe my-run-on-demand \
  --format json

הפלט אמור להיראות כך:

{
  "artifacts": {
    "gcsPath": "gs://my-bucket"
  },
  "createTime": "2026-02-05T16:25:28.367865234Z",
  "displayName": "mldiagnostics-my-run-on-demand",
  "endTime": "0001-01-01T00:00:00Z",
  "etag": "1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6",
   "name": "projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand",
  "orchestrator": "GKE",
  "runPhase": "ACTIVE",
  "runSet": "my-run-on-demand-group",
  "tools": [
    {
      "XProf": {}
    }
  ],
  "updateTime": "2026-02-05T16:25:28.367865344Z",
  "workloadDetails": {
    "gke": {
      "cluster": "projects/163028815180/locations/us-central1/clusters/my-cluster",
      "id": "jobset-abcd",
      "kind": "JobSet",
      "namespace": "default"
    }
  }
}

הצגת רשימה של הפעלות של למידת מכונה

כדי לקבל רשימה של הרצות של למידת מכונה בפרויקט ובמיקום ספציפיים, משתמשים בפקודה machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

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

gcloud alpha mldiagnostics machine-learning-run list --limit 2 --uri

https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand
https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand-2

עדכון של הרצות של למידת מכונה

עדכון של הרצת למידת מכונה בפרויקט ובמיקום שצוינו. אתם יכולים לעדכן את השם המוצג, את שלב ההרצה, את כלי התזמור ואת פרטי עומס העבודה של GKE. אי אפשר לשנות את מזהה ההפעלה והמיקום. עדכון של ריצה באמצעות הפקודה machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

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

הדגל etag הוא שדה חובה, והוא צריך להיות הערך האחרון של ETag (תג ישות) עבור משאב של הפעלת ML. למידע נוסף, ראו שימוש בתגי ישות לצורך בקרת מקבילות אופטימית. כדי למצוא את ערך ה-ETAG הנכון, אפשר להשתמש בערכים הבאים:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

דוגמה לבקשת עדכון מלאה:

gcloud alpha mldiagnostics machine-learning-run update my-run-on-demand \
  --orchestrator gke \
  --run-group my-run-on-demand-group \
  --gcs-path gs://my-bucket \
  --display-name mldiagnostics-my-run-on-demand-completed \
  --gke-cluster-name projects/user/locations/us-central1/clusters/my-cluster \
  --gke-namespace default \
  --gke-workload-name jobset-abcd \
  --gke-kind JobSet \
  --gke-workload-create-time 2026-02-20T06:06:06Z \
  --run-phase COMPLETED \
  --etag 1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6

מחיקת הרצות של למידת מכונה

כדי למחוק הרצה של למידת מכונה בפרויקט ובמיקום ספציפיים, משתמשים בפקודה machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

מחיקה של הפעלה של ML לא מוחקת נתונים ב-Cloud Storage, ב-Cloud Logging או בעומס העבודה של GKE. מחיקה של mlrun מוחקת רק את המטא-נתונים שקשורים להרצה במערכת ML Diagnostics.

פקודות של כלי לניתוח ביצועים (profiler)

אפשר להשתמש בקבוצת הפקודות של כלי הפרופילים כדי להציג רשימה של כל הפרופילים, למצוא צמתי GKE של עומס עבודה שבהם שרת XProf פועל ולתעד פרופילים לפי דרישה מ-CLI.

הצגת רשימה של יעדי ניתוח הביצועים

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

gcloud alpha mldiagnostics profiler-target list --machine-learning-run RUN_NAME

כדי להשתמש בפקודה הזו, צריך:

התכונה Xprof לפי דרישה מופעלת בעומס העבודה, והיא פורסת את שרת XProf בכל הצמתים של עומס העבודה.
אשכול GKE מוגדר ל-ML Diagnostics, עם פריסה של webhook ואופרטור.
עומס עבודה שנפרס ב-GKE.

דוגמה לבקשה:

gcloud alpha mldiagnostics profiler-target list \
  --machine-learning-run my-run-on-demand

דוגמה לפלט:

---
hostname: gke-tpu-1f0789b5-jqx9
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-0-tcw2k
---
hostname: gke-tpu-1f0789b5-rxvf
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-1-dct59

הצגת סשנים של כלי ליצירת תמונת מצב (profiler)

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

gcloud alpha mldiagnostics profiler-session list --machine-learning-run RUN_NAME

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

דוגמה לבקשה:

gcloud alpha mldiagnostics profiler-session list \
  --machine-learning-run my-run-on-demand

תיעוד של סשנים של פרופילר על פי דרישה

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

כדי להשתמש בפקודה הזו, צריך:

הפרופילר XProf מופעל בעומס העבודה לפי דרישה, והוא פורס את שרת XProf בכל הצמתים של עומס העבודה
אשכול GKE מוגדר ל-ML Diagnostics, עם webhook ו-operator שנפרסו
עומס עבודה שנפרס ב-GKE.

דוגמה לבקשה:

gcloud alpha mldiagnostics profiler-session capture \
  profiler-session-on-demand \
  --machine-learning-run RUN_NAME \
  --targets TARGET \
  --duration DURATION

בדוגמה הזו נעשה שימוש בדגלים הבאים:

דגל	דרישה	תיאור
`profiler-session-name`	חובה	השם של סשן הפרופילר שרוצים ללכוד.
`duration`	חובה	משך הזמן של ההקלטה בסשן של כלי הפרופיל. הוא מסוג `Duration`. לדוגמה, מציינים משך זמן של `1s` לשנייה אחת, `400ms` ל-400 אלפיות השנייה ו-`5m` ל-5 דקות.
`targets`	חובה	מזהים של יעדי הפרופיל או מזהים מוגדרים במלואם של יעדי הפרופיל. הערך חייב להיות זהה לרשימת היעדים שמשויכים להרצה.
`device-tracer-level`	אופציונלי	רמת הכלי למעקב אחר מכשירים בסשן. ערכים קבילים: `device-tracer-level-enabled`, ‏ `device-tracer-level-disabled` (ברירת מחדל).
`host-tracer-level`	אופציונלי	רמת מעקב המארח בסשן. ערכים קבילים: `host-tracer-level-info` (ברירת מחדל), `host-tracer-level-critical`, ‏ `host-tracer-level-disabled`, ‏ `host-tracer-level-verbose`.
`python-tracer-level`	אופציונלי	רמת Python tracer לסשן. ערכים קבילים: `python-tracer-level-disabled` (ברירת מחדל), `python-tracer-level-enabled`.

פקודות של אירועים במעקב

אתם יכולים להשתמש בפקודות monitored-events כדי לראות רשימה של כל האירועים שזוהו על ידי ניטור עומסי העבודה, ולקבל פרטים על כל אחד מהאירועים.

רשימת האירועים שבמעקב

רשימה של כל האירועים שזוהו על ידי ניטור עומסי עבודה שמשויכים להרצת למידת מכונה.

דוגמה לבקשה:

gcloud alpha mldiagnostics monitored-events list \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

דוגמה לפלט:

[
 {
   "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
   "endTime": "2026-05-01T12:10:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
   "startTime": "2026-05-01T12:00:00Z",
   "type": "PERFORMANCE_DEGRADATION"
 },
 {
   "displayName": "Performance degradation - 2026-06-27T07:35:00Z",
   "endTime": "2026-06-27T08:15:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-789-def-123",
   "startTime": "2026-06-27T07:35:00Z",
   "type": "PERFORMANCE_DEGRADATION"
   }
   // ... other events
]

Describe monitored-events

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

דוגמה לבקשה:

gcloud alpha mldiagnostics monitored-events describe abc-123-def-456 \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

דוגמה לפלט:

{
 "analyzerReports": [
   {
     "analyzer": "ICI Link Analyzer",
     "detectionState": "DETECTED",
     "details": "ICI Link issues detected in <instance_ids>: This indicates networking issues on ICI links connected between TPU processors.",
     "recommendedActions": [
       {
         "description": "Contact Google team for further diagnosis. Potential action could be to Outkast affected nodes, but there could be other causes that need further investigation.",
         "documentationUrl": "https://docs.cloud.google.com/tpu/docs/ml-diagnostics/workload-monitoring"
       }
     ]
   }
 ],
 "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
 "endTime": "2026-05-01T12:10:00Z",
 "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
 "startTime": "2026-05-01T12:00:00Z",
 "type": "PERFORMANCE_DEGRADATION"
}