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

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

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

• Machine-learning-run פקודות: Create, Delete, Describe, List, Update.
• פקודות של כלי הפרופיל:
  • 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. הדגל מבצע את הפעולות הבאות:

1. יוצר הפעלה של למידת מכונה עם הסטטוס 'הושלם'.
2. חיפוש רקורסיבי של קובצי xplane.pb בנתיב של ספריית Cloud Storage.
3. טוען את כל הפרופילים שנמצאו למסד הנתונים של 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 ואופרטור.
• עומס עבודה (workload) שנפרס ב-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 שנפרסו
• עומס עבודה (workload) שנפרס ב-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 בסשן. ערכים קבילים: python-tracer-level-disabled (ברירת מחדל), python-tracer-level-enabled.