Mulai menggunakan ML Diagnostics CLI

Gunakan ML Diagnostics Google Cloud CLI untuk membuat proses machine learning, men-deploy XProf sebagai instance terkelola dengan backend yang skalabel, dan memberikan pengalaman pembuatan profil terkelola di Google Cloud.

Ada dua kategori perintah gcloud CLI ML Diagnostics: perintah machine-learning-run dan perintah profiler. Gunakan perintah machine-learning-run untuk membuat, menghapus, mendeskripsikan, mencantumkan, dan memperbarui proses machine learning. Gunakan perintah profiler untuk mencantumkan node dan merekam profil sesuai permintaan dari CLI.

  • Perintah Machine-learning-run: Create, Delete, Describe, List, Update.
  • Perintah profiler:
    • profiler-target: List
    • profiler-session: Capture, List

Semua perintah gcloud CLI memerlukan project yang ditentukan di lingkungan. Untuk menyetel project:

gcloud config set project PROJECT_ID

Untuk mengetahui informasi selengkapnya tentang perintah gcloud CLI ML Diagnostics, lihat referensi API.

Merekam profil

Anda dapat merekam profil XProf dari workload ML dengan perekaman terprogram atau perekaman sesuai permintaan (perekaman manual). Pengambilan data terprogram melibatkan penyematan perintah pembuatan profil langsung ke dalam kode machine learning Anda, dan menyatakan secara eksplisit kapan harus mulai dan berhenti merekam data. Pengambilan data sesuai permintaan terjadi secara real-time, saat Anda memicu profiler ketika workload sudah berjalan aktif.

Untuk mengaktifkan pengambilan profil sesuai permintaan, Anda perlu memulai server XProf dalam kode dan memanggil metode profiler.start_server. Tindakan ini akan memulai server XProf pada workload ML Anda yang memproses pemicu pengambilan sesuai permintaan untuk mulai merekam profil. Gunakan port 9999 untuk perintah ini: profiler.start_server(port=9999)

Untuk pengambilan profil terprogram dan sesuai permintaan, tentukan lokasi untuk menyimpan profil yang diambil. Misalnya: gs://my-bucket/my-run. Profil disimpan di direktori bertingkat dalam lokasi:gs://my-bucket/my-run/plugins/profile/session1/. Pengambilan profil terprogram dan pengambilan sesuai permintaan tidak boleh terjadi dalam jangka waktu yang sama.

Untuk pengambilan profil sesuai permintaan, siapkan cluster GKE dan deploy workload dengan label: managed-mldiagnostics-gke=true.

Untuk mengetahui informasi selengkapnya tentang pembuatan profil dengan JAX, lihat Membuat profil komputasi.

Membuat proses machine learning

Membuat resource run machine learning di project dan lokasi yang ditentukan. Perintah machine-learning-run create men-deploy XProf sebagai instance terkelola di project Anda. Instance XProf terkelola digunakan untuk melihat semua profil dalam project, dan dibuat saat proses machine learning pertama dibuat dalam project.

Gunakan perintah machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

Ada dua cara untuk membuat proses machine learning:

  • Mendaftarkan profil yang sudah direkam ke platform Diagnostik ML.
  • Gunakan Diagnostik ML untuk melakukan pengambilan profil sesuai permintaan dengan mendaftarkan run aktif. Hal ini memerlukan penyiapan cluster GKE dan workload yang di-deploy di GKE dengan label managed-mldiagnostics-gke=true.

Membuat ML Run dan mendaftarkan profil yang ada yang telah diambil

Kode berikut membuat proses dan mendaftarkan profil yang sudah direkam ke 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"

Contoh kode menggunakan flag berikut:

Flag Persyaratan Deskripsi
machine-learning-run Wajib ID unik untuk proses tertentu ini. Jika nama tidak unik, pembuatan operasi akan gagal dengan pesan: "ML Run already exists".
location Wajib Semua lokasi Cluster Director didukung kecuali us-east5. Flag ini dapat ditetapkan oleh argumen untuk setiap perintah, atau dengan perintah: gcloud config set compute/region.
gcs-path Wajib Google Cloud Lokasi penyimpanan tempat semua profil disimpan. Misalnya gs://my-bucket atau gs://my-bucket/folder1. Hanya diperlukan jika SDK digunakan untuk pengambilan profil.
run-group Opsional ID yang dapat membantu mengelompokkan beberapa proses yang termasuk dalam eksperimen yang sama. Misalnya, semua proses yang terkait dengan sapuan ukuran slice TPU dapat termasuk dalam grup yang sama.
display-name Opsional Nama tampilan untuk proses machine learning. Jika tidak diberikan, ID ini akan disetel ke ID operasi machine learning.

Flag --labels list_existing_sessions_only=true diperlukan jika Anda ingin melihat dan mengelola profil yang ada yang dikumpulkan di Diagnostik ML. Flag ini melakukan hal berikut:

  1. Membuat proses machine learning dengan status "Selesai".
  2. Menelusuri file xplane.pb secara rekursif dalam jalur direktori Cloud Storage.
  3. Memuat semua sesi profil yang berlokasi ke dalam database Diagnostik ML untuk dilihat di Google Cloud, membuat link yang dapat dibagikan untuk sesi profil, dan memungkinkan pengguna mengelola profil ini dengan platform Diagnostik ML.

Jika tanda --labels list_existing_sessions_only disetel ke true untuk suatu proses, Anda tidak dapat melakukan pembuatan profil sesuai permintaan atau memperbarui proses. Anda hanya dapat melihat dan mengelola profil yang ada.

Membuat ML Run untuk melakukan pengambilan profil sesuai permintaan

Kode berikut membuat mlrun untuk melakukan pengambilan profil sesuai permintaan:

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

Selain flag dari contoh sebelumnya, contoh kode ini menggunakan flag tambahan berikut:

Flag Persyaratan Deskripsi
orchestrator Opsional Orchestrator yang digunakan untuk menjalankan. Jika tidak ditentukan, gke akan digunakan secara default. Nilai yang valid: gce, gke, slurm.
gke-cluster-name Diperlukan untuk GKE Cluster workload. Contoh: /projects/<project_id>/locations/<location>/clusters/<cluster_name>.
gke-kind Diperlukan untuk GKE Jenis workload. Misalnya: JobSet.
gke-namespace Diperlukan untuk GKE Namespace workload. Misalnya: default.
gke-workload-name Diperlukan untuk GKE ID beban kerja. Misalnya: jobset-abcd.
gke-workload-create-time Diperlukan untuk GKE Stempel waktu pembuatan JobSet dalam format stempel waktu ISO. Misalnya: 2026-02-20T06:00:00Z.
run-phase Opsional Fase dan status proses. Jika tidak diberikan, nilai defaultnya adalah ACTIVE.

Menjelaskan eksekusi machine learning

Lihat detail eksekusi machine learning dengan perintah machine-learning-run describe:

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

Contoh berikut adalah permintaan detail proses dalam JSON:

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

Outputnya mirip dengan hal berikut ini:

{
  "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"
    }
  }
}

Mencantumkan operasi machine learning

Dapatkan daftar proses machine learning dalam project dan lokasi tertentu dengan perintah machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

Contoh berikut adalah permintaan untuk daftar hingga dua proses, dengan output jalur URI-nya:

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

Memperbarui proses machine learning

Memperbarui proses machine learning di project dan lokasi tertentu. Anda dapat memperbarui nama tampilan, fase berjalan, orkestrator, dan detail workload GKE. Anda tidak dapat mengubah ID dan lokasi proses. Perbarui proses dengan perintah machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

Berikan semua kolom yang disertakan dalam permintaan create. Jika kolom wajib diisi tidak diberikan selama permintaan update, kolom tersebut akan diganti dengan nilai default.

Flag etag adalah kolom wajib diisi, dan harus berupa nilai ETag (tag entitas) terbaru untuk resource ML Run. Untuk mengetahui informasi selengkapnya, lihat Menggunakan tag entitas untuk kontrol konkurensi optimis. Gunakan perintah berikut untuk menemukan nilai ETAG yang benar:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Berikut adalah contoh permintaan update lengkap:

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

Menghapus operasi machine learning

Menghapus proses machine learning dalam project dan lokasi tertentu dengan perintah machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

Menghapus proses ML tidak akan menghapus data apa pun di Cloud Storage, Cloud Logging, atau beban kerja GKE. Menghapus mlrun hanya akan menghapus metadata yang terkait dengan proses dalam sistem Diagnostik ML.

Perintah profiler

Anda dapat menggunakan grup perintah profiler untuk mencantumkan semua profil, menemukan node GKE beban kerja tempat server XProf berjalan, dan merekam profil sesuai permintaan dari CLI.

Mencantumkan target profiler

Mencantumkan semua target profiler yang terkait dengan proses machine learning dalam project dan lokasi tertentu:

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

Perintah ini memerlukan hal berikut:

  • Xprof on-demand diaktifkan dalam workload, yang men-deploy server XProf ke semua node workload.
  • Cluster GKE disiapkan untuk Diagnostik ML, dengan webhook dan operator yang di-deploy.
  • Workload yang di-deploy di GKE dengan label: managed-mldiagnostics-gke=true.

Berikut adalah contoh permintaan:

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

Berikut adalah contoh output-nya:

---
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

Mencantumkan sesi profiler

Mencantumkan semua sesi profiler yang terkait dengan proses machine learning di project dan lokasi tertentu dengan perintah berikut:

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

Perintah profiler ini tidak memerlukan penyiapan GKE atau workload. Bagian ini akan mencantumkan semua sesi profil, baik terprogram maupun on-demand. Jika Anda hanya memiliki pengambilan profil terprogram, gunakan perintah ini untuk mencantumkan semua sesi profil. Tidak ada penyiapan GKE yang diperlukan, pemberian label workload GKE, atau pengaktifan XProf sesuai permintaan.

Berikut adalah contoh permintaan:

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

Merekam sesi profiler on-demand

Anda dapat merekam sesi profiler sesuai permintaan untuk menjalankan machine learning di serangkaian node tertentu tempat workload berjalan (target profiler).

Perintah ini memerlukan hal berikut:

  • XProf on-demand diaktifkan dalam workload, yang men-deploy server XProf ke semua node workload
  • Cluster GKE disiapkan untuk Diagnostik ML, dengan webhook dan operator yang di-deploy
  • Workload yang di-deploy di GKE dengan label: managed-mldiagnostics-gke=true.

Berikut adalah contoh permintaan:

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

Contoh ini menggunakan flag berikut:

Flag Persyaratan Deskripsi
profiler-session-name Wajib Nama sesi profiler yang akan direkam.
duration Wajib Durasi untuk perekaman sesi profiler. Ini adalah jenis Duration. Misalnya, tentukan durasi 1s selama 1 detik, 400ms selama 400 milidetik, dan 5m selama 5 menit.
targets Wajib ID target profiler atau ID yang sepenuhnya memenuhi syarat untuk profiler-targets. Harus cocok dengan daftar target yang terkait dengan proses.
device-tracer-level Opsional Tingkat perekaman aktivitas perangkat untuk sesi. Nilai yang diterima: device-tracer-level-enabled, device-tracer-level-disabled (default).
host-tracer-level Opsional Tingkat pelacakan host untuk sesi. Nilai yang diterima: host-tracer-level-info (default), host-tracer-level-critical, host-tracer-level-disabled, host-tracer-level-verbose.
python-tracer-level Opsional Tingkat pelacak Python untuk sesi. Nilai yang diterima: python-tracer-level-disabled (default), python-tracer-level-enabled.