Inizia a utilizzare ML Diagnostics CLI

Utilizza Google Cloud CLI di ML Diagnostics per creare un'esecuzione di machine learning, eseguire il deployment di XProf come istanza gestita con un backend scalabile e fornire un'esperienza di profilazione gestita su Google Cloud.

Esistono due categorie di comandi gcloud CLI di ML Diagnostics: comandi machine-learning-run e comandi profiler. Utilizza i comandi machine-learning-run per creare, eliminare, descrivere, elencare e aggiornare le esecuzioni di machine learning. Utilizza i comandi profiler per elencare i nodi e acquisire profili on demand dalla CLI.

Comandi Machine-learning-run: Create, Delete, Describe, List, Update.
Comandi del Profiler:
- profiler-target: List
- profiler-session: Capture, List

Tutti i comandi gcloud CLI richiedono un progetto definito nell'ambiente. Per impostare il progetto:

gcloud config set project PROJECT_ID

Per saperne di più sui comandi gcloud CLI di ML Diagnostics, consulta il riferimento API.

Acquisire profili

Puoi acquisire profili XProf del tuo workload ML con l'acquisizione programmatica o l'acquisizione on demand (acquisizione manuale). L'acquisizione programmatica prevede l'incorporamento di comandi di profilazione direttamente nel codice di machine learning e la dichiarazione esplicita di quando iniziare e interrompere la registrazione dei dati. L'acquisizione on demand avviene in tempo reale, in cui attivi il profiler mentre il carico di lavoro è già in esecuzione.

Per abilitare l'acquisizione di profili on demand, devi avviare il server XProf all'interno del tuo codice e chiamare il metodo profiler.start_server. Viene avviato un server XProf sul tuo workload ML che ascolta il trigger di acquisizione on demand per avviare l'acquisizione dei profili. Utilizza la porta 9999 per questo comando: profiler.start_server(port=9999)

Per l'acquisizione di profili sia programmatica sia on demand, specifica la posizione in cui memorizzare i profili acquisiti. Ad esempio: gs://my-bucket/my-run. I profili vengono memorizzati in directory nidificate all'interno della posizione:gs://my-bucket/my-run/plugins/profile/session1/. L'acquisizione programmatica dei profili e l'acquisizione on demand non devono avvenire nello stesso periodo di tempo.

Per l'acquisizione di profili on demand, configura un cluster GKE ed esegui il deployment del workload con l'etichetta: managed-mldiagnostics-gke=true.

Per ulteriori informazioni sulla profilazione con JAX, consulta Profilazione del calcolo.

Crea esecuzione di machine learning

Crea una risorsa di esecuzione di machine learning in un progetto e una località specifici. Il comando machine-learning-run create esegue il deployment di XProf come istanza gestita nel tuo progetto. L'istanza XProf gestita viene utilizzata per visualizzare tutti i profili nel progetto e viene creata quando viene creata la prima esecuzione di machine learning nel progetto.

Utilizza il comando machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

Esistono due modi per creare un'esecuzione di machine learning:

Registra i profili acquisiti esistenti nella piattaforma ML Diagnostics.
Utilizza ML Diagnostics per eseguire l'acquisizione del profilo on demand registrando un'esecuzione attiva. Ciò richiede la configurazione di un cluster GKE e un workload di cui è stato eseguito il deployment su GKE con l'etichetta managed-mldiagnostics-gke=true.

Crea un'esecuzione ML e registra i profili acquisiti esistenti

Il seguente codice crea un'esecuzione e registra i profili acquisiti esistenti in 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"

L'esempio di codice utilizza i seguenti flag:

Flag	Requisito	Descrizione
`machine-learning-run`	Obbligatorio	Un identificatore univoco per questa esecuzione specifica. Se il nome non è univoco, la creazione dell'esecuzione non riesce e viene visualizzato il messaggio: "L'esecuzione ML esiste già".
`location`	Obbligatorio	Sono supportate tutte le posizioni di Cluster Director, ad eccezione di `us-east5`. Questo flag può essere impostato da un argomento per ogni comando o con il comando: `gcloud config set compute/region`.
`gcs-path`	Obbligatorio	La Google Cloud posizione di archiviazione in cui vengono salvati tutti i profili. Ad esempio: `gs://my-bucket` o `gs://my-bucket/folder1`. Obbligatorio solo se l'SDK viene utilizzato per l'acquisizione del profilo.
`run-group`	Facoltativo	Un identificatore che può aiutare a raggruppare più esecuzioni appartenenti allo stesso esperimento. Ad esempio, tutte le esecuzioni associate a una variazione delle dimensioni della sezione TPU potrebbero appartenere allo stesso gruppo.
`display-name`	Facoltativo	Nome visualizzato per l'esecuzione di machine learning. Se non viene fornito, viene impostato sull'ID esecuzione del machine learning.

Il flag --labels list_existing_sessions_only=true è obbligatorio se vuoi visualizzare e gestire i profili raccolti esistenti in Diagnostica ML. Il flag esegue le seguenti operazioni:

Crea un'esecuzione di machine learning con lo stato "Completato".
Esegue la ricerca ricorsiva dei file xplane.pb all'interno del percorso della directory Cloud Storage.
Carica tutte le sessioni dei profili trovati nel database ML Diagnostics per la visualizzazione in Google Cloud, crea link condivisibili per le sessioni dei profili e consente agli utenti di gestire questi profili con la piattaforma ML Diagnostics.

Se il flag --labels list_existing_sessions_only è impostato su true per un'esecuzione, non puoi eseguire la profilazione on demand o aggiornare l'esecuzione. Puoi solo visualizzare e gestire i profili esistenti.

Crea un'esecuzione ML per eseguire l'acquisizione del profilo on demand

Il seguente codice crea un mlrun per eseguire l'acquisizione on demand del profilo:

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

Oltre ai flag dell'esempio precedente, l'esempio di codice utilizza i seguenti flag aggiuntivi:

Flag	Requisito	Descrizione
`orchestrator`	Facoltativo	L'orchestratore utilizzato per l'esecuzione. Se non specificato, `gke` viene utilizzato per impostazione predefinita. Valori validi: `gce`, `gke`, `slurm`.
`gke-cluster-name`	Obbligatorio per GKE	Il cluster del carico di lavoro. Ad esempio: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Obbligatorio per GKE	Il tipo di workload. Ad esempio: `JobSet`.
`gke-namespace`	Obbligatorio per GKE	Lo spazio dei nomi del workload. Ad esempio: `default`.
`gke-workload-name`	Obbligatorio per GKE	L'identificatore del carico di lavoro. Ad esempio: `jobset-abcd`.
`gke-workload-create-time`	Obbligatorio per GKE	Il timestamp di creazione di un JobSet nel formato timestamp ISO. Ad esempio: `2026-02-20T06:00:00Z`.
`run-phase`	Facoltativo	Fase e stato di un'esecuzione. Se non viene fornito, il valore predefinito è `ACTIVE`.

Descrivere l'esecuzione di machine learning

Visualizza i dettagli di un'esecuzione di machine learning con il comando machine-learning-run describe:

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

Il seguente esempio è una richiesta di dettagli dell'esecuzione in formato JSON:

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

L'output è simile al seguente:

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

Elenca le esecuzioni di machine learning

Visualizza un elenco di esecuzioni di machine learning all'interno di un progetto e di una località specifici con il comando machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

L'esempio seguente è una richiesta di un elenco di massimo due esecuzioni, con gli output dei percorsi 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

Aggiorna le esecuzioni di machine learning

Aggiorna un'esecuzione di machine learning in un progetto e una località specifici. Puoi aggiornare il nome visualizzato, la fase di esecuzione, l'orchestratore e i dettagli del workload GKE. Non puoi modificare l'ID corsa e la posizione. Aggiorna un'esecuzione con il comando machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

Fornisci tutti i campi inclusi nella richiesta create. Se i campi obbligatori non vengono forniti durante la richiesta di aggiornamento, vengono sostituiti dai valori predefiniti.

Il flag etag è un campo obbligatorio e deve essere l'ultimo valore ETag (entity tag) per una risorsa ML Run. Per saperne di più, vedi Utilizzare i tag di entità per il controllo della concorrenza ottimistico. Utilizza quanto segue per trovare il valore ETAG corretto:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Di seguito è riportato un esempio di richiesta di aggiornamento completa:

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

Elimina esecuzioni di machine learning

Elimina un'esecuzione di machine learning in un progetto e in una località specificati con il comando machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

L'eliminazione di un'esecuzione ML non elimina i dati in Cloud Storage, Cloud Logging o nel workload GKE. L'eliminazione di mlrun comporta l'eliminazione solo dei metadati relativi alla corsa all'interno del sistema ML Diagnostics.

Comandi di Profiler

Puoi utilizzare il gruppo di comandi del profiler per elencare tutti i profili, trovare i nodi GKE del workload in cui è in esecuzione il server XProf e acquisire profili on demand dalla CLI.

Elenco dei target del profiler

Elenca tutti i target del profiler associati a un'esecuzione di machine learning in un progetto e una località specificati:

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

Questo comando richiede quanto segue:

Xprof on demand è abilitato nel workload, che esegue il deployment del server XProf in tutti i nodi del workload.
Il cluster GKE è configurato per ML Diagnostics, con webhook e operatore di cui è stato eseguito il deployment.
Workload di cui è stato eseguito il deployment su GKE con l'etichetta: managed-mldiagnostics-gke=true.

Di seguito è riportato un esempio di richiesta:

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

Di seguito è riportato un esempio di 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

Elenco delle sessioni di Profiler

Elenca tutte le sessioni del profiler associate a un'esecuzione di machine learning in un progetto e una località specifici con il seguente comando:

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

Questo comando del profiler non richiede la configurazione di GKE o del workload. Verranno elencate tutte le sessioni del profilo, sia programmatiche che on demand. Se hai solo acquisizioni di profili programmatiche, utilizza questo comando per elencare tutte le sessioni dei profili. Non è richiesta alcuna configurazione GKE, etichettatura dei workload GKE o attivazione di XProf on demand.

Di seguito è riportato un esempio di richiesta:

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

Acquisire sessioni del profiler on demand

Puoi acquisire una sessione del profiler on demand per un'esecuzione di machine learning su un insieme specificato di nodi su cui viene eseguito il carico di lavoro (target del profiler).

Questo comando richiede quanto segue:

XProf on demand è abilitato nel workload, che esegue il deployment del server XProf in tutti i nodi del workload
Il cluster GKE è configurato per ML Diagnostics, con webhook e operatore di cui è stato eseguito il deployment
Workload di cui è stato eseguito il deployment su GKE con l'etichetta: managed-mldiagnostics-gke=true.

Di seguito è riportato un esempio di richiesta:

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

L'esempio utilizza i seguenti flag:

Flag	Requisito	Descrizione
`profiler-session-name`	Obbligatorio	Nome della sessione del profiler da acquisire.
`duration`	Obbligatorio	Durata dell'acquisizione della sessione del profiler. È di tipo `Duration`. Ad esempio, specifica una durata di `1s` per 1 secondo, `400ms` per 400 millisecondi e `5m` per 5 minuti.
`targets`	Obbligatorio	ID dei target del profiler o identificatori completi dei profiler-targets. Deve corrispondere a un elenco di target associati all'esecuzione.
`device-tracer-level`	Facoltativo	Livello tracer dispositivo per la sessione. Valori accettati: `device-tracer-level-enabled`, `device-tracer-level-disabled` (predefinito).
`host-tracer-level`	Facoltativo	Livello tracer host per la sessione. Valori accettati: `host-tracer-level-info` (valore predefinito), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`.
`python-tracer-level`	Facoltativo	Livello tracer Python per la sessione. Valori accettati: `python-tracer-level-disabled` (predefinito), `python-tracer-level-enabled`.