Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mulai menggunakan ML Diagnostics CLI

Gunakan ML Diagnostics Google Cloud CLI untuk membuat operasi machine learning, men-deploy XProf sebagai instance terkelola dengan backend yang skalabel, dan menyediakan 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, menjelaskan, mencantumkan, dan mengupdate operasi machine learning. Gunakan perintah profiler untuk mencantumkan node dan mengambil profil on-demand 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 menetapkan project:

gcloud config set project PROJECT_ID

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

Mengambil profil

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

Untuk mengaktifkan pengambilan profil on-demand, Anda harus memulai server XProf dalam kode dan memanggil metode profiler.start_server. Tindakan ini akan memulai server XProf di workload ML yang memproses pemicu pengambilan on-demand untuk mulai mengambil profil. Gunakan port 9999 untuk perintah ini: profiler.start_server(port=9999)

Untuk pengambilan profil terprogram dan on-demand, tentukan lokasi untuk menyimpan profil yang diambil. Misalnya: gs://my-bucket/my-run. Profil disimpan dalam direktori yang berada di dalam lokasi:gs://my-bucket/my-run/plugins/profile/session1/. Pengambilan profil terprogram dan pengambilan on-demand tidak boleh terjadi selama periode waktu yang sama.

Untuk pengambilan profil on-demand, siapkan cluster GKE yang menginstal connection-operator. Untuk pengambilan profil terprogram, siapkan cluster GKE yang menginstal injection-webhook, menggunakan ML Diagnostics SDK dan memberi label pada workload.

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

Membuat operasi machine learning

Buat resource operasi 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 operasi machine learning pertama dibuat dalam project.

Gunakan perintah machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

Ada dua cara untuk membuat operasi machine learning:

Daftarkan profil yang diambil yang ada ke platform ML Diagnostics.
Gunakan ML Diagnostics untuk melakukan pengambilan profil on-demand dengan mendaftarkan operasi aktif. Tindakan ini memerlukan penyiapan cluster GKE.

Membuat Operasi ML dan mendaftarkan profil yang diambil yang ada

Kode berikut membuat operasi dan mendaftarkan profil yang diambil yang ada 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 operasi 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	Lokasi penyimpanan tempat semua profil disimpan. Google Cloud 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 operasi yang termasuk dalam eksperimen yang sama. Misalnya, semua operasi yang terkait dengan TPU slice size sweep dapat berada dalam grup yang sama.
`display-name`	Opsional	Nama tampilan untuk operasi machine learning. Jika tidak diberikan, nama tampilan akan ditetapkan ke ID operasi machine learning.

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

Membuat operasi machine learning dengan status "Completed".
Menelusuri file xplane.pb secara berulang dalam jalur direktori Cloud Storage.
Memuat semua sesi profil yang ditemukan ke dalam database ML Diagnostics untuk dilihat di Google Cloud, membuat link yang dapat dibagikan untuk sesi profil, dan memungkinkan pengguna mengelola profil ini dengan platform ML Diagnostics.

Jika flag --labels list_existing_sessions_only ditetapkan ke true untuk operasi, Anda tidak dapat melakukan pembuatan profil on-demand atau mengupdate operasi. Anda hanya dapat melihat dan mengelola profil yang ada.

Membuat Operasi ML untuk melakukan pengambilan profil on-demand

Kode berikut membuat mlrun untuk melakukan pengambilan profil on-demand:

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 menggunakan flag tambahan berikut:

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

Menjelaskan operasi machine learning

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

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

Contoh berikut adalah permintaan detail operasi 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 operasi machine learning dalam project dan lokasi yang ditentukan dengan perintah machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

Contoh berikut adalah permintaan daftar hingga dua operasi, 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

Mengupdate operasi machine learning

Update operasi machine learning di project dan lokasi yang ditentukan. Anda dapat mengupdate nama tampilan, fase operasi, orchestrator, dan detail workload GKE. Anda tidak dapat mengubah ID dan lokasi operasi. Update operasi dengan perintah machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

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

Flag etag adalah kolom wajib, dan harus merupakan nilai ETag (tag entity) terbaru untuk resource Operasi ML. Untuk mengetahui informasi selengkapnya, lihat Menggunakan tag entity untuk kontrol konkurensi optimis. Gunakan hal 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

Hapus operasi machine learning di project dan lokasi yang ditentukan dengan perintah machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

Menghapus operasi ML tidak akan menghapus data apa pun di Cloud Storage, Cloud Logging, atau workload GKE. Menghapus mlrun hanya akan menghapus metadata yang terkait dengan operasi dalam sistem ML Diagnostics.

Perintah profiler

Anda dapat menggunakan grup perintah profiler untuk mencantumkan semua profil, menemukan node GKE workload tempat server XProf berjalan, dan mengambil profil on-demand dari CLI.

Mencantumkan target profiler

Cantumkan semua target profiler yang terkait dengan operasi machine learning di project dan lokasi yang ditentukan:

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 ML Diagnostics, dengan webhook dan operator yang di-deploy.
Workload yang di-deploy di GKE.

Berikut adalah contoh permintaan:

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

Berikut adalah contoh output:

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

Cantumkan semua sesi profiler yang terkait dengan operasi machine learning di project dan lokasi yang ditentukan dengan perintah berikut:

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

Perintah profiler ini tidak memerlukan penyiapan GKE atau workload. Perintah 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, pemberian label workload GKE, atau pengaktifan XProf on-demand yang diperlukan.

Berikut adalah contoh permintaan:

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

Mengambil sesi profiler on-demand

Anda dapat mengambil sesi profiler on-demand untuk operasi machine learning pada kumpulan 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 ML Diagnostics, dengan webhook dan operator yang di-deploy
Workload yang di-deploy di GKE.

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 diambil.
`duration`	Wajib	Durasi untuk pengambilan sesi profiler. Jenisnya adalah `Duration`. Misalnya, tentukan durasi `1s` untuk 1 detik, `400ms` untuk 400 milidetik, dan `5m` untuk 5 menit.
`targets`	Wajib	ID target profiler atau ID yang sepenuhnya memenuhi syarat untuk target profiler. Harus cocok dengan daftar target yang terkait dengan operasi.
`device-tracer-level`	Opsional	Tingkat pelacak perangkat untuk sesi. Nilai yang diterima: `device-tracer-level-enabled`, `device-tracer-level-disabled` (default).
`host-tracer-level`	Opsional	Tingkat pelacak 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`.