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 |
|
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:
- 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.
Instala gcloud CLI y, luego, instala el componente
alpha:gcloud components install alphaEstablece un proyecto predeterminado en tu entorno, que es obligatorio para todos los comandos de gcloud CLI:
gcloud config set project PROJECT_IDReemplaza
PROJECT_IDpor 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:
- Crea una ejecución de aprendizaje automático con el estado "Completada".
- Busca de forma recurrente archivos xplane.pb en la ruta del 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 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-1Para 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:
|
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"
}