Premiers pas avec la CLI ML Diagnostics

Utilisez la Google Cloud CLI ML Diagnostics pour créer une exécution de machine learning, déployer XProf en tant qu'instance gérée avec un backend évolutif et fournir une expérience de profilage gérée sur Google Cloud.

Il existe deux catégories de commandes gcloud CLI pour les diagnostics ML : les commandes machine-learning-run et les commandes profiler. Utilisez les commandes machine-learning-run pour créer, supprimer, décrire, lister et mettre à jour les exécutions de machine learning. Utilisez les commandes profiler pour lister les nœuds et capturer des profils à la demande depuis la CLI.

Commandes Machine-learning-run : Create, Delete, Describe, List, Update.
Commandes du profileur :
- profiler-target : List
- profiler-session : Capture, List

Toutes les commandes gcloud CLI nécessitent un projet défini dans l'environnement. Pour définir le projet :

gcloud config set project PROJECT_ID

Pour en savoir plus sur les commandes gcloud CLI de ML Diagnostics, consultez la documentation de référence de l'API.

Capturer des profils

Vous pouvez capturer des profils XProf de votre charge de travail de ML avec la capture programmatique ou la capture à la demande (capture manuelle). La capture programmatique consiste à intégrer des commandes de profilage directement dans votre code de machine learning et à indiquer explicitement quand commencer et arrêter l'enregistrement des données. La capture à la demande se produit en temps réel. Vous déclenchez le profileur alors que la charge de travail est déjà en cours d'exécution.

Pour activer la capture de profil à la demande, vous devez démarrer le serveur XProf dans votre code et appeler la méthode profiler.start_server. Cela démarre un serveur XProf sur votre charge de travail de ML qui attend le déclencheur de capture à la demande pour commencer à capturer les profils. Utilisez le port 9999 pour cette commande : profiler.start_server(port=9999)

Pour la capture de profil programmatique comme pour la capture de profil à la demande, spécifiez l'emplacement où stocker les profils capturés. Exemple : gs://my-bucket/my-run. Les profils sont stockés dans des répertoires imbriqués dans l'emplacement gs://my-bucket/my-run/plugins/profile/session1/. La capture de profil programmatique et la capture à la demande ne doivent pas se produire au cours de la même période.

Pour la capture de profil à la demande, configurez un cluster GKE et déployez une charge de travail avec le libellé managed-mldiagnostics-gke=true.

Pour en savoir plus sur le profilage avec JAX, consultez Profilage du calcul.

Créer une exécution de machine learning

Crée une ressource d'exécution de machine learning dans un projet et un emplacement spécifiés. La commande machine-learning-run create déploie XProf en tant qu'instance gérée dans votre projet. L'instance XProf gérée est utilisée pour afficher tous les profils du projet. Elle est créée lors de la première exécution de machine learning dans le projet.

Exécutez la commande machine-learning-run create :

gcloud alpha mldiagnostics machine-learning-run create

Il existe deux façons de créer une exécution de machine learning :

Enregistrez les profils capturés existants sur la plate-forme ML Diagnostics.
Utilisez ML Diagnostics pour effectuer une capture de profil à la demande en enregistrant une exécution active. Pour cela, vous devez configurer un cluster GKE et déployer une charge de travail sur GKE avec le libellé managed-mldiagnostics-gke=true.

Créer une exécution de ML et enregistrer des profils capturés existants

Le code suivant crée une exécution et enregistre les profils capturés existants dans 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'exemple de code utilise les indicateurs suivants :

Option	Exigence	Description
`machine-learning-run`	Obligatoire	Identifiant unique de cette exécution spécifique. Si le nom n'est pas unique, la création de l'exécution échoue et le message "L'exécution ML existe déjà" s'affiche.
`location`	Obligatoire	Toutes les zones Cluster Director sont acceptées, à l'exception de `us-east5`. Ce flag peut être défini par un argument pour chaque commande ou avec la commande : `gcloud config set compute/region`.
`gcs-path`	Obligatoire	Emplacement de stockage Google Cloud où tous les profils sont enregistrés. Par exemple, `gs://my-bucket` ou `gs://my-bucket/folder1`. Obligatoire uniquement si le SDK est utilisé pour la capture de profils.
`run-group`	Facultatif	Identifiant permettant de regrouper plusieurs exécutions appartenant au même test. Par exemple, toutes les exécutions associées à un balayage de la taille de tranche TPU peuvent appartenir au même groupe.
`display-name`	Facultatif	Nom à afficher pour l'exécution du machine learning. Si aucune valeur n'est fournie, elle est définie sur l'ID d'exécution du machine learning.

L'option --labels list_existing_sessions_only=true est requise si vous souhaitez afficher et gérer les profils collectés existants dans ML Diagnostics. L'indicateur effectue les opérations suivantes :

Crée une exécution de machine learning avec l'état "Terminé".
Recherche récursivement les fichiers xplane.pb dans le chemin d'accès au répertoire Cloud Storage.
Charge toutes les sessions de profil trouvées dans la base de données ML Diagnostics pour les afficher dans Google Cloud, crée des liens partageables pour les sessions de profil et permet aux utilisateurs de gérer ces profils avec la plate-forme ML Diagnostics.

Si l'indicateur --labels list_existing_sessions_only est défini sur true pour une exécution, vous ne pouvez pas effectuer de profilage à la demande ni mettre à jour l'exécution. Vous ne pouvez que consulter et gérer les profils existants.

Créer une exécution ML pour effectuer la capture de profil à la demande

Le code suivant crée un mlrun pour effectuer la capture de profil à la demande :

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

En plus des indicateurs de l'exemple précédent, l'exemple de code utilise les indicateurs supplémentaires suivants :

Option	Exigence	Description
`orchestrator`	Facultatif	Orchestrateur utilisé pour l'exécution. Si aucune valeur n'est spécifiée, `gke` est utilisé par défaut. Valeurs valides : `gce`, `gke` et `slurm`.
`gke-cluster-name`	Requis pour GKE	Cluster de la charge de travail. Par exemple, `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Requis pour GKE	Type de charge de travail. Exemple : `JobSet`.
`gke-namespace`	Requis pour GKE	Espace de noms de la charge de travail. Exemple : `default`.
`gke-workload-name`	Requis pour GKE	Identifiant de la charge de travail. Exemple : `jobset-abcd`.
`gke-workload-create-time`	Requis pour GKE	Horodatage de création d'un JobSet au format ISO. Exemple : `2026-02-20T06:00:00Z`.
`run-phase`	Facultatif	Phase et état d'une exécution. Si aucune valeur n'est spécifiée, la valeur par défaut est `ACTIVE`.

Décrire une exécution de machine learning

Affichez les détails d'une exécution de machine learning avec la commande machine-learning-run describe :

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

L'exemple suivant est une demande d'informations sur l'exécution au format JSON :

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

Le résultat ressemble à ce qui suit :

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

Lister les exécutions de machine learning

Obtenez la liste des exécutions de machine learning dans un projet et un emplacement spécifiés à l'aide de la commande machine-learning-run list :

gcloud alpha mldiagnostics machine-learning-run list

L'exemple suivant est une demande de liste de deux exécutions maximum, avec les chemins d'URI de leurs sorties :

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

Mettre à jour les exécutions de machine learning

Mettez à jour une exécution de machine learning dans un projet et un emplacement spécifiés. Vous pouvez modifier le nom à afficher, la phase d'exécution, l'orchestrateur et les détails de la charge de travail GKE. Vous ne pouvez pas modifier l'ID ni l'emplacement de l'exécution. Mettez à jour une exécution avec la commande machine-learning-run update :

gcloud alpha mldiagnostics machine-learning-run update

Renseignez tous les champs inclus dans la requête create. Si les champs obligatoires ne sont pas fournis lors de la requête de mise à jour, ils sont remplacés par les valeurs par défaut.

L'indicateur etag est un champ obligatoire. Il doit correspondre à la dernière valeur ETag (entity tag) pour une ressource ML Run. Pour en savoir plus, consultez Utiliser des tags d'entité pour le contrôle de simultanéité optimiste. Utilisez la commande suivante pour trouver la valeur ETAG correcte :

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Voici un exemple de requête de mise à jour complète :

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

Supprimer les exécutions de machine learning

Supprimez une exécution de machine learning dans un projet et un emplacement spécifiés à l'aide de la commande machine-learning-run delete :

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

La suppression d'une exécution ML n'entraîne pas la suppression des données dans Cloud Storage, Cloud Logging ni la charge de travail GKE. La suppression de mlrun n'entraîne que la suppression des métadonnées liées à l'exécution dans le système ML Diagnostics.

Commandes du profileur

Vous pouvez utiliser le groupe de commandes du profileur pour lister tous les profils, trouver les nœuds GKE de la charge de travail où le serveur XProf est en cours d'exécution et capturer des profils à la demande à partir de la CLI.

Lister les cibles du profileur

Répertoriez toutes les cibles du profileur associées à une exécution de machine learning dans un projet et un emplacement spécifiés :

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

Cette commande nécessite les éléments suivants :

Xprof à la demande est activé dans la charge de travail, ce qui déploie le serveur XProf dans tous les nœuds de la charge de travail.
Le cluster GKE est configuré pour les diagnostics ML, avec le webhook et l'opérateur déployés.
Charge de travail déployée sur GKE avec le libellé : managed-mldiagnostics-gke=true.

Voici un exemple de requête :

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

Voici un exemple de résultat :

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

Lister les sessions du profileur

Répertoriez toutes les sessions de profileur associées à une exécution de machine learning dans un projet et un emplacement spécifiés à l'aide de la commande suivante :

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

Cette commande de profileur ne nécessite aucune configuration de GKE ni de charge de travail. Elle liste toutes les sessions de profil, qu'elles soient programmatiques ou à la demande. Si vous n'avez que des captures de profil programmatiques, utilisez cette commande pour lister toutes les sessions de profil. Aucune configuration GKE, aucun libellé de charge de travail GKE ni aucune activation XProf à la demande ne sont requis.

Voici un exemple de requête :

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

Capturer des sessions de profileur à la demande

Vous pouvez capturer une session de profileur à la demande pour une exécution de machine learning sur un ensemble spécifié de nœuds sur lesquels la charge de travail s'exécute (cibles du profileur).

Cette commande nécessite les éléments suivants :

XProf à la demande est activé dans la charge de travail, ce qui déploie le serveur XProf dans tous les nœuds de la charge de travail.
Le cluster GKE est configuré pour les diagnostics ML, avec un webhook et un opérateur déployés.
Charge de travail déployée sur GKE avec le libellé : managed-mldiagnostics-gke=true.

Voici un exemple de requête :

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

L'exemple utilise les options suivantes :

Option	Exigence	Description
`profiler-session-name`	Obligatoire	Nom de la session de profileur à capturer.
`duration`	Obligatoire	Durée de la capture de la session du profileur. Il est de type `Duration`. Par exemple, spécifiez une durée de `1s` pour 1 seconde, `400ms` pour 400 millisecondes et `5m` pour 5 minutes.
`targets`	Obligatoire	ID des cibles du profileur ou identifiants complets des cibles du profileur. Doit correspondre à une liste de cibles associées à l'exécution.
`device-tracer-level`	Facultatif	Niveau du traceur d'appareil pour la session. Valeurs acceptées : `device-tracer-level-enabled`, `device-tracer-level-disabled` (par défaut).
`host-tracer-level`	Facultatif	Niveau de traceur de l'hôte pour la session. Valeurs acceptées : `host-tracer-level-info` (par défaut), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`.
`python-tracer-level`	Facultatif	Niveau du traceur Python pour la session. Valeurs acceptées : `python-tracer-level-disabled` (par défaut), `python-tracer-level-enabled`.