Comienza a usar la CLI de ML Diagnostics

Usa Google Cloud CLI de ML Diagnostics para crear y administrar ejecuciones 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. También puedes enumerar todos los eventos detectados por la supervisión de cargas de trabajo y obtener detalles del analizador para estos eventos a través de la CLI o la API.

En la siguiente tabla, se resumen las categorías de los comandos de gcloud CLI de ML Diagnostics:

Categoría Comandos Función
Ejecuciones de aprendizaje automático machine-learning-run: create, describe, list, update, delete, start-continuous-profiling, stop-continuous-profiling Crea y administra ejecuciones de aprendizaje automático, y, además, inicia o detén la creación continua de perfiles.
Profiler
  • profiler-target: list
  • profiler-session: list, capture
Enumera los nodos de carga de trabajo y las sesiones del generador de perfiles, y captura perfiles a pedido o instantáneas de creación continua de perfiles.
Eventos supervisados monitored-events: list, describe Enumera los eventos detectados por la supervisión de cargas de trabajo y obtén detalles del analizador para cada evento.

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

Requisitos previos

Antes de ejecutar los comandos de gcloud CLI de ML Diagnostics, completa los siguientes requisitos previos:

  1. Habilita la API de Cluster Director y otorga los permisos de Identity and Access Management (IAM) necesarios. Para obtener más información, consulta Requisitos previos de ML Diagnostics.
  2. Instala gcloud CLI y, luego, instala el componente alpha:

    gcloud components install alpha
    
  3. Establece un proyecto predeterminado en tu entorno, que es obligatorio para todos los comandos de gcloud CLI:

    gcloud config set project PROJECT_ID
    

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

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 de XProf administrada 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 maneras 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 a pedido registrando una ejecución activa. Para ello, se requiere la configuración de un clúster de GKE.

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

Con el siguiente código, se crea una ejecución y se registran 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 falla con 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 de Google Cloud en la que se guardan todos los perfiles. Por ejemplo: gs://my-bucket o gs://my-bucket/folder1. Solo es obligatorio si el SDK se usa para capturar 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 barrido de tamaño de 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 de aprendizaje automático.

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

  1. Crea una ejecución de aprendizaje automático con el estado "Completada".
  2. Busca de forma recurrente archivos xplane.pb en la ruta del directorio de Cloud Storage.
  3. 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 que los usuarios administren estos perfiles con la plataforma de ML Diagnostics.

Si la marca --labels list_existing_sessions_only se establece en true para una ejecución, no puedes realizar un perfilamiento 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 on demand

El siguiente código crea un mlrun para realizar la captura de perfiles 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

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 Obligatorio para GKE El clúster de la carga de trabajo. Por ejemplo: /projects/<project_id>/locations/<location>/clusters/<cluster_name>.
gke-kind Obligatorio para GKE Es el tipo de carga de trabajo. Por ejemplo: JobSet.
gke-namespace Obligatorio para GKE El espacio de nombres de la carga de trabajo. Por ejemplo: default.
gke-workload-name Obligatorio para GKE Es el identificador de la carga de trabajo. Por ejemplo: jobset-abcd.
gke-workload-create-time Obligatorio 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

En el siguiente ejemplo, se muestra 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"
    }
  }
}

Mostrar una lista de 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 de una lista de hasta dos ejecuciones, con resultados de sus rutas de acceso de 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

Actualizar 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 organizador 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 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 el siguiente comando 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.

Iniciar la creación continua de perfiles

Cuando se habilita la creación continua de perfiles, la plataforma de diagnóstico de ML captura de forma continua un perfil en un búfer en memoria en tus hosts de TPU. Puedes iniciar la generación de perfiles continua en uno o más destinos de generación de perfiles de una ejecución de aprendizaje automático activa.

Mientras la generación de perfiles continua está activa, el generador de perfiles de XProf en cada destino conserva los 2 GB de datos de seguimiento más recientes en un búfer circular en la memoria. Solo puede haber una sesión de generación de perfiles continua activa en una ejecución de aprendizaje automático a la vez.

La generación de perfiles continua solo admite el seguimiento en el dispositivo, no recopila los seguimientos del host ni de Python. Los niveles de seguimiento y el puerto del servidor de XProf no se pueden cambiar mientras la creación de perfiles continua esté activa. Para cambiar los niveles de seguimiento, debes detener el perfil continuo y reiniciar el proceso.

Para iniciar la generación de perfiles continua, ejecuta el siguiente comando en uno o más destinos del generador de perfiles de una ejecución de aprendizaje automático activa:

gcloud alpha mldiagnostics machine-learning-run start-continuous-profiling \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION \
  --targets=TARGETS

Reemplaza lo siguiente:

  • RUN_NAME: Es el ID de la ejecución activa de aprendizaje automático.
  • LOCATION: Es la región de la ejecución del aprendizaje automático, por ejemplo, us-central1.
  • TARGETSGlossary: Es una lista separada por comas de IDs de destinos del generador de perfiles o nombres de destinos del generador de perfiles completamente calificados. Por ejemplo: my-node-0,my-node-1 Para ver los destinos disponibles, consulta Enumera los destinos del generador de perfiles.

Para guardar los datos de seguimiento almacenados en el búfer como una sesión del generador de perfiles, usa el comando profiler-session capture con la marca --kind=snapshot:

gcloud alpha mldiagnostics profiler-session capture \
  SESSION_NAME \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION \
  --targets=TARGETS \
  --kind=snapshot

Reemplaza SESSION_NAME por un ID para la sesión de generador de perfiles capturada.

Detener la creación continua de perfiles

Puedes detener la generación de perfiles continua en todos los destinos del generador de perfiles de una ejecución de aprendizaje automático. Cuando detienes la generación de perfiles continua, los destinos del generador de perfiles dejan de registrar datos de seguimiento en sus búferes en memoria y no puedes capturar nuevas instantáneas. Las sesiones existentes del generador de perfiles de instantáneas no se verán afectadas.

Detén la creación continua de perfiles para una ejecución de aprendizaje automático con el siguiente comando:

gcloud alpha mldiagnostics machine-learning-run stop-continuous-profiling \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION

Reemplaza lo siguiente:

  • RUN_NAME: Es el ID de la ejecución de aprendizaje automático.
  • LOCATION: Es la región de la ejecución de aprendizaje automático. Por ejemplo: us-central1.

Comandos del generador de perfiles

Puedes usar el grupo de comandos profiler para enumerar todos los perfiles, encontrar nodos de GKE de una carga de trabajo en la que se ejecuta el servidor de XProf, capturar perfiles a pedido y capturar instantáneas de generación de perfiles continuos desde la CLI.

Enumera los destinos del generador de perfiles

Enumera todos los destinos 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 a pedido 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, o el DaemonSet de ML Diagnostics.
  • Implementaste la carga de trabajo en GKE.

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 generador de perfiles 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 la configuración de GKE ni de la carga de trabajo. En ella, se enumeran todas las sesiones de perfil, incluidas las sesiones de instantáneas de creación de perfiles programáticas, a pedido y continuas. Si solo tienes capturas de perfiles programáticas, usa este comando para enumerar todas las sesiones de perfiles. 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

Cómo capturar sesiones del generador de perfiles

Puedes capturar una sesión del generador de perfiles a pedido o guardar una instantánea de generación de perfiles continua en uno o más objetivos del generador de perfiles de una ejecución de aprendizaje automático activa.

Para capturar un perfil, se requiere lo siguiente:

  • XProf a pedido 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, o el DaemonSet de ML Diagnostics.
  • Implementaste la carga de trabajo en GKE.

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

El comando acepta 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 del tipo Duration. Por ejemplo, especifica una duración de 1s para 1 segundo, 400ms para 400 milisegundos y 5m para 5 minutos.
targets Obligatorio Son los IDs de los destinos del generador de perfiles o los identificadores completamente calificados para los destinos del generador de perfiles. Debe coincidir con una lista de objetivos asociados con la ejecución.
device-tracer-level Opcional Es el nivel de rastreador de dispositivo para la sesión. Valores aceptados: device-tracer-level-enabled, device-tracer-level-disabled (predeterminado).
host-tracer-level Opcional Es el nivel de rastreador de host de 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 de rastreador de Python para la sesión. Valores aceptados: python-tracer-level-disabled (predeterminado), python-tracer-level-enabled.
kind Opcional Es el tipo de sesión del generador de perfiles. Valor predeterminado: on-demand. Valores aceptados:
  • on-demand: Es la sesión de Profiler creada a través de una solicitud on demand en la CLI, Google Cloud la consola o la API.
  • snapshot: Es la sesión de Profiler que se creó a través del flujo de creación continua de perfiles para capturar una instantánea.

Eventos supervisados

Puedes usar los comandos de monitored-events para enumerar todos los eventos detectados por la supervisión de cargas de trabajo y obtener detalles del analizador para cada uno de los eventos.

Generar una lista de eventos supervisados

Enumera todos los eventos detectados por la supervisión de cargas de trabajo asociados con una ejecución de aprendizaje automático.

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

gcloud alpha mldiagnostics monitored-events list \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

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

[
 {
   "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
   "endTime": "2026-05-01T12:10:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
   "startTime": "2026-05-01T12:00:00Z",
   "type": "PERFORMANCE_DEGRADATION"
 },
 {
   "displayName": "Performance degradation - 2026-06-27T07:35:00Z",
   "endTime": "2026-06-27T08:15:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-789-def-123",
   "startTime": "2026-06-27T07:35:00Z",
   "type": "PERFORMANCE_DEGRADATION"
   }
   // ... other events
]

Describe los eventos supervisados

Obtén detalles del analizador para cada uno de los eventos que detecta la supervisión de cargas de trabajo asociada con una ejecución de aprendizaje automático.

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

gcloud alpha mldiagnostics monitored-events describe abc-123-def-456 \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

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

{
 "analyzerReports": [
   {
     "analyzer": "ICI Link Analyzer",
     "detectionState": "DETECTED",
     "details": "ICI Link issues detected in <instance_ids>: This indicates networking issues on ICI links connected between TPU processors.",
     "recommendedActions": [
       {
         "description": "Contact Google team for further diagnosis. Potential action could be to Outkast affected nodes, but there could be other causes that need further investigation.",
         "documentationUrl": "https://docs.cloud.google.com/tpu/docs/ml-diagnostics/workload-monitoring"
       }
     ]
   }
 ],
 "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
 "endTime": "2026-05-01T12:10:00Z",
 "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
 "startTime": "2026-05-01T12:00:00Z",
 "type": "PERFORMANCE_DEGRADATION"
}