Comienza a usar la CLI de ML Diagnostics

Usa la CLI de ML Diagnostics de Google Cloud para crear una ejecución de aprendizaje automático, implementar XProf como una instancia administrada con un backend escalable y proporcionar una experiencia de generación de perfiles administrada en Google Cloud.

Existen dos categorías de comandos de la gcloud CLI de ML Diagnostics: comandos machine-learning-run y comandos profiler. Usa los comandos de machine-learning-run para crear, borrar, describir, enumerar y actualizar ejecuciones de aprendizaje automático. Usa los comandos de profiler para enumerar nodos y capturar perfiles a pedido desde la CLI.

Comandos de Machine-learning-run: Create, Delete, Describe, List y Update
Comandos del generador de perfiles:
- profiler-target: List
- profiler-session: Capture, List

Todos los comandos de gcloud CLI requieren un proyecto definido en el entorno. Para configurar el proyecto, haz lo siguiente:

gcloud config set project PROJECT_ID

Para obtener más información sobre los comandos de gcloud CLI de ML Diagnostics, consulta la referencia de la API.

Captura de perfiles

Puedes capturar perfiles de XProf de tu carga de trabajo de AA con la captura programática o la captura bajo demanda (captura manual). La captura programática implica incorporar comandos de generación de perfiles directamente en tu código de aprendizaje automático y establecer de forma explícita cuándo comenzar y detener el registro de datos. La captura bajo demanda se produce en tiempo real, ya que activas el generador de perfiles mientras la carga de trabajo ya se está ejecutando de forma activa.

Para habilitar la captura de perfiles bajo demanda, debes iniciar el servidor de XProf en tu código y llamar al método profiler.start_server. Esto inicia un servidor de XProf en tu carga de trabajo de AA que escucha el activador de captura bajo demanda para comenzar a capturar perfiles. Usa el puerto 9999 para este comando: profiler.start_server(port=9999)

Para ambos tipos de capturas, especifica la ubicación en la que quieres almacenar los perfiles capturados. Por ejemplo: gs://my-bucket/my-run. Los perfiles se almacenan en directorios anidados dentro de la ubicación:gs://my-bucket/my-run/plugins/profile/session1/. La captura de perfiles programática y la captura bajo demanda no deben ocurrir durante el mismo período.

Para la captura de perfiles a pedido, configura un clúster de GKE y, luego, implementa la carga de trabajo con la etiqueta managed-mldiagnostics-gke=true.

Para obtener más información sobre la generación de perfiles con JAX, consulta Generación de perfiles de la computación.

Crear ejecución de aprendizaje automático

Crea un recurso de ejecución de aprendizaje automático en un proyecto y una ubicación especificados. El comando machine-learning-run create implementa XProf como una instancia administrada en tu proyecto. La instancia administrada de XProf se usa para ver todos los perfiles del proyecto y se crea cuando se crea la primera ejecución de aprendizaje automático en el proyecto.

Usa el comando machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

Existen dos formas de crear una ejecución de aprendizaje automático:

Registra los perfiles capturados existentes en la plataforma de ML Diagnostics.
Usa ML Diagnostics para realizar la captura de perfiles bajo demanda registrando una ejecución activa. Esto requiere la configuración de un clúster de GKE y una carga de trabajo implementada en GKE con la etiqueta managed-mldiagnostics-gke=true.

Crea una ejecución de ML y registra los perfiles capturados existentes

El siguiente código crea una ejecución y registra los perfiles capturados existentes en 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"

En el ejemplo de código, se usan las siguientes marcas:

Marca	Requisito	Descripción
`machine-learning-run`	Obligatorio	Es un identificador único para esta ejecución específica. Si el nombre no es único, la creación de la ejecución fallará y se mostrará el mensaje "ML Run already exists".
`location`	Obligatorio	Se admiten todas las ubicaciones de Cluster Director, excepto `us-east5`. Esta marca se puede establecer con un argumento para cada comando o con el comando `gcloud config set compute/region`.
`gcs-path`	Obligatorio	Es la ubicación de almacenamiento Google Cloud en la que se guardan todos los perfiles. Por ejemplo: `gs://my-bucket` o `gs://my-bucket/folder1`. Solo se requiere si el SDK se usa para la captura de perfiles.
`run-group`	Opcional	Es un identificador que puede ayudar a agrupar varias ejecuciones que pertenecen al mismo experimento. Por ejemplo, todas las ejecuciones asociadas con un análisis de variación del tamaño de la porción de TPU podrían pertenecer al mismo grupo.
`display-name`	Opcional	Es el nombre visible de la ejecución de aprendizaje automático. Si no se proporciona, se establece en el ID de ejecución del aprendizaje automático.

La marca --labels list_existing_sessions_only=true es obligatoria si deseas ver y administrar los perfiles recopilados existentes en Diagnóstico de AA. La marca hace lo siguiente:

Crea una ejecución de aprendizaje automático con el estado "Completado".
Busca de forma recursiva archivos xplane.pb en la ruta de directorio de Cloud Storage.
Carga todas las sesiones de perfil ubicadas en la base de datos de ML Diagnostics para verlas en Google Cloud, crea vínculos para compartir las sesiones de perfil y permite a los usuarios administrar estos perfiles con la plataforma de ML Diagnostics.

Si la marca --labels list_existing_sessions_only está configurada como true para una ejecución, no puedes realizar la generación de perfiles a pedido ni actualizar la ejecución. Solo puedes ver y administrar los perfiles existentes.

Crea una ejecución de ML para realizar la captura de perfiles a pedido

El siguiente código crea un mlrun para realizar la captura de perfil a pedido:

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

Junto con las marcas del ejemplo anterior, el ejemplo de código usa las siguientes marcas adicionales:

Marca	Requisito	Descripción
`orchestrator`	Opcional	Es el organizador que se usó para la ejecución. Si no se especifica, se usa `gke` de forma predeterminada. Valores válidos: `gce`, `gke` y `slurm`.
`gke-cluster-name`	Se requiere para GKE	Es el clúster de la carga de trabajo. Por ejemplo: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Se requiere para GKE	Es el tipo de carga de trabajo. Por ejemplo: `JobSet`.
`gke-namespace`	Se requiere para GKE	El espacio de nombres de la carga de trabajo. Por ejemplo: `default`.
`gke-workload-name`	Se requiere para GKE	Es el identificador de la carga de trabajo. Por ejemplo: `jobset-abcd`.
`gke-workload-create-time`	Se requiere para GKE	Es la marca de tiempo de creación de un JobSet en formato de marca de tiempo ISO. Por ejemplo: `2026-02-20T06:00:00Z`.
`run-phase`	Opcional	Fase y estado de una ejecución. Si no se proporciona, el valor predeterminado es `ACTIVE`.

Describe la ejecución de aprendizaje automático

Consulta los detalles de una ejecución de aprendizaje automático con el comando machine-learning-run describe:

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

El siguiente ejemplo es una solicitud de detalles de ejecución en JSON:

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

El resultado es similar a lo siguiente:

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

Enumera las ejecuciones de aprendizaje automático

Obtén una lista de las ejecuciones de aprendizaje automático dentro de un proyecto y una ubicación especificados con el comando machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

En el siguiente ejemplo, se muestra una solicitud para obtener una lista de hasta dos ejecuciones, con las rutas de URI de sus resultados:

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

Actualiza las ejecuciones de aprendizaje automático

Actualiza una ejecución de aprendizaje automático en un proyecto y una ubicación especificados. Puedes actualizar el nombre visible, la fase de ejecución, el orquestador y los detalles de la carga de trabajo de GKE. No puedes cambiar el ID ni la ubicación de la ejecución. Actualiza una ejecución con el comando machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

Proporciona todos los campos que se incluyeron en la solicitud create. Si no se proporcionan los campos obligatorios durante la solicitud de actualización, se anulan con los valores predeterminados.

La marca etag es un campo obligatorio y debe ser el valor de ETag (etiqueta de entidad) más reciente para un recurso de ejecución de ML. Para obtener más información, consulta Usa etiquetas de entidad para el control de simultaneidad optimista. Usa lo siguiente para encontrar el valor de ETAG correcto:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

A continuación, se muestra un ejemplo de una solicitud de actualización 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

Borrar ejecuciones de aprendizaje automático

Borra una ejecución de aprendizaje automático en un proyecto y una ubicación especificados con el comando machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

Borrar una ejecución de ML no borra ningún dato en Cloud Storage, Cloud Logging ni la carga de trabajo de GKE. Si borras el mlrun, solo se borrarán los metadatos relacionados con la ejecución dentro del sistema de ML Diagnostics.

Comandos del generador de perfiles

Puedes usar el grupo de comandos del generador de perfiles para enumerar todos los perfiles, encontrar los nodos de GKE de la carga de trabajo en la que se ejecuta el servidor de XProf y capturar perfiles bajo demanda desde la CLI.

Enumera los destinos del generador de perfiles

Enumera todos los objetivos del generador de perfiles asociados con una ejecución de aprendizaje automático en un proyecto y una ubicación especificados:

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

Este comando requiere lo siguiente:

XProf bajo demanda está habilitado en la carga de trabajo, lo que implementa el servidor de XProf en todos los nodos de la carga de trabajo.
El clúster de GKE está configurado para ML Diagnostics, con el webhook y el operador implementados.
Carga de trabajo implementada en GKE con la etiqueta: managed-mldiagnostics-gke=true.

A continuación, se muestra un ejemplo de una solicitud:

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

A continuación, se muestra un ejemplo del resultado:

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

Enumera las sesiones del generador de perfiles

Enumera todas las sesiones del Profiler asociadas con una ejecución de aprendizaje automático en un proyecto y una ubicación especificados con el siguiente comando:

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

Este comando del generador de perfiles no requiere configuración de GKE ni de la carga de trabajo. Se enumerarán todas las sesiones de perfil, tanto programáticas como on demand. Si solo tienes capturas de perfiles programáticas, usa este comando para enumerar todas las sesiones de perfil. No se requiere configuración de GKE, etiquetado de cargas de trabajo de GKE ni habilitación de XProf a pedido.

A continuación, se muestra un ejemplo de una solicitud:

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

Captura sesiones del generador de perfiles on demand

Puedes capturar una sesión del generador de perfiles on demand para una ejecución de aprendizaje automático en un conjunto especificado de nodos en los que se ejecuta la carga de trabajo (objetivos del generador de perfiles).

Este comando requiere lo siguiente:

XProf bajo demanda está habilitado en la carga de trabajo, lo que implementa el servidor de XProf en todos los nodos de la carga de trabajo.
El clúster de GKE está configurado para ML Diagnostics, con el webhook y el operador implementados.
Carga de trabajo implementada en GKE con la etiqueta: managed-mldiagnostics-gke=true.

A continuación, se muestra un ejemplo de una solicitud:

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

En el ejemplo, se usan las siguientes marcas:

Marca	Requisito	Descripción
`profiler-session-name`	Obligatorio	Es el nombre de la sesión del generador de perfiles que se capturará.
`duration`	Obligatorio	Es la duración de la captura de la sesión del generador de perfiles. Es de tipo `Duration`. Por ejemplo, especifica una duración de `1s` para 1 segundo, `400ms` para 400 milisegundos y `5m` para 5 minutos.
`targets`	Obligatorio	IDs de los destinos del generador de perfiles o identificadores completamente calificados para los destinos del generador de perfiles. Debe coincidir con una lista de destinos asociados con la ejecución.
`device-tracer-level`	Opcional	Es el nivel de registro del dispositivo para la sesión. Valores aceptados: `device-tracer-level-enabled` y `device-tracer-level-disabled` (predeterminado).
`host-tracer-level`	Opcional	Es el nivel de registro del host para la sesión. Valores aceptados: `host-tracer-level-info` (predeterminado), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`.
`python-tracer-level`	Opcional	Es el nivel del registrador de Python para la sesión. Valores aceptados: `python-tracer-level-disabled` (predeterminado), `python-tracer-level-enabled`.