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

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 ML Diagnostics : les commandes machine-learning-run et les commandes profiler. Utilisez les commandes machine-learning-run pour créer, supprimer, décrire, répertorier et mettre à jour les exécutions de machine learning. Utilisez les commandes profiler pour répertorier les nœuds et capturer les profils à la demande à partir de la CLI.

Commandes Machine-learning-run : Create, Delete, Describe, List, Update
Commandes de Profiler :
- 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 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, lorsque 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 sur votre charge de travail de ML un serveur XProf 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 avoir lieu au cours de la même période.

Pour la capture de profil à la demande, configurez un cluster GKE qui installe connection-operator. Pour la capture de profil programmatique, configurez un cluster GKE qui installe injection-webhook, à l'aide du SDK ML Diagnostics et en étiquetant la charge de travail.

Pour en savoir plus sur le profilage avec JAX, consultez Profiler des calculs.

Créer une exécution de machine learning

Créez 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 et est créée lors de la première exécution de machine learning dans le projet.

Utilisez 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. Cela nécessite la configuration d'un cluster GKE.

Créer une exécution de ML et enregistrer les 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 options suivantes :

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 « ML Run already exists » (L'exécution de ML existe déjà) s'affiche.
`location`	Obligatoire	Tous les emplacements de Cluster Director sont compatibles, à l'exception de `us-east5`. Cette option peut être définie par un argument pour chaque commande ou avec la commande : `gcloud config set compute/region`.
`gcs-path`	Obligatoire	Emplacement de stockage où tous les profils sont enregistrés. Google Cloud Par exemple : `gs://my-bucket` ou `gs://my-bucket/folder1`. Obligatoire uniquement si le SDK est utilisé pour la capture de profil.
`run-group`	Facultatif	Identifiant qui peut aider à regrouper plusieurs exécutions appartenant à la même expérience. Par exemple, toutes les exécutions associées à une analyse de la taille des tranches de TPU peuvent appartenir au même groupe.
`display-name`	Facultatif	Nom à afficher pour l'exécution de machine learning. Si aucune valeur n'est fournie, elle est définie sur l'ID d'exécution de machine learning.

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

Crée une exécution de machine learning avec l'état "Terminé".
Recherche de manière récursive 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 in 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'option --labels list_existing_sessions_only est définie sur true pour une exécution, vous ne pouvez pas effectuer de profilage à la demande ni mettre à jour l'exécution. Vous ne pouvez qu'afficher et gérer les profils existants.

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

Le code suivant crée un mlrun afin d'effectuer une 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 options de l'exemple précédent, l'exemple de code utilise les options supplémentaires suivantes :

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`, `slurm`.
`gke-cluster-name`	Obligatoire pour GKE	Cluster de la charge de travail. Par exemple : `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Obligatoire pour GKE	Type de la charge de travail. Par exemple : `JobSet`.
`gke-namespace`	Obligatoire pour GKE	Espace de noms de la charge de travail. Par exemple : `default`.
`gke-workload-name`	Obligatoire pour GKE	Identifiant de la charge de travail. Par exemple : `jobset-abcd`.
`gke-workload-create-time`	Obligatoire pour GKE	Horodatage de création d'un JobSet au format ISO. Par exemple : `2026-02-20T06:00:00Z`.
`run-phase`	Facultatif	Phase et état d'une exécution. Si aucune valeur n'est fournie, 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 requête de détails d'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"
    }
  }
}

Répertorier les exécutions de machine learning

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

gcloud alpha mldiagnostics machine-learning-run list

L'exemple suivant est une requête pour une liste d'au maximum deux exécutions, avec les chemins d'accès à leurs 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

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 mettre à jour 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 et 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

Fournissez tous les champs inclus dans la create requête. Si des 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'option etag est un champ obligatoire et doit correspondre à la dernière valeur ETag (balise d'entité) pour une ressource d'exécution de ML. Pour en savoir plus, consultez Utiliser des balises 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 avec la commande machine-learning-run delete :

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

La suppression d'une exécution de ML ne supprime aucune donnée dans Cloud Storage, Cloud Logging ni la charge de travail GKE. La suppression de mlrun ne supprime que les métadonnées associées à l'exécution dans le système ML Diagnostics.

Commandes de Profiler

Vous pouvez utiliser le groupe de commandes du profileur pour répertorier 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 les profils à la demande à partir de la CLI.

Répertorier 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 ML Diagnostics, avec le webhook et l'opérateur déployés.
La charge de travail est déployée sur GKE.

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

Répertorier les sessions du profileur

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

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

Cette commande du profileur ne nécessite pas de configuration GKE ni de charge de travail. Elle répertorie toutes les sessions de profil, à la fois programmatiques et à la demande. Si vous n'avez que des captures de profil programmatiques, utilisez cette commande pour répertorier toutes les sessions de profil. Aucune configuration GKE, étiquetage de la charge de travail GKE ni activation de 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 est en cours d'exécution (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 ML Diagnostics, avec le webhook et l'opérateur déployés.
La charge de travail est déployée sur GKE.

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 pour les 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 du traceur d'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`.