Começar a usar a CLI do ML Diagnostics

Use a CLI do Google Cloud ML Diagnostics para criar uma execução de machine learning, implante o XProf como uma instância gerenciada com um backend escalonável e ofereça uma experiência de criação de perfil gerenciada no Google Cloud.

Há duas categorias de comandos da CLI gcloud do ML Diagnostics: comandos machine-learning-run e profiler. Use os comandos machine-learning-run para criar, excluir, descrever, listar e atualizar execuções de aprendizado de máquina. Use os comandos profiler para listar nós e capturar perfis sob demanda da CLI.

Comandos Machine-learning-run: Create, Delete, Describe, List e Update.
Comandos do criador de perfil:
- profiler-target: List
- profiler-session: Capture, List

Todos os comandos da CLI gcloud exigem um projeto definido no ambiente. Para definir o projeto:

gcloud config set project PROJECT_ID

Para mais informações sobre os comandos da CLI gcloud do ML Diagnostics, consulte a referência da API.

Capturar perfis

É possível capturar perfis do XProf da sua carga de trabalho de ML com captura programática ou on demand (manual). A captura programática envolve a incorporação de comandos de criação de perfil diretamente no código de machine learning e a declaração explícita de quando iniciar e parar de gravar dados. A captura on demand ocorre em tempo real, em que você aciona o criador de perfil enquanto a carga de trabalho já está sendo executada ativamente.

Para ativar a captura de perfil on demand, inicie o servidor XProf no código e chame o método profiler.start_server. Isso inicia um servidor XProf na sua carga de trabalho de ML que detecta o gatilho de captura on demand para começar a capturar perfis. Use a porta 9999 para este comando: profiler.start_server(port=9999)

Para as capturas de perfil programática e on demand, especifique o local para armazenar os perfis capturados. Por exemplo, gs://my-bucket/my-run. Os perfis são armazenados em diretórios aninhados no local:gs://my-bucket/my-run/plugins/profile/session1/. A captura de perfil programática e a captura on demand não podem ocorrer durante o mesmo período.

Para captura de perfil sob demanda, configure um cluster do GKE e implante a carga de trabalho com o rótulo: managed-mldiagnostics-gke=true.

Para mais informações sobre a criação de perfil com JAX, consulte Criação de perfil de computação.

Criar execução de machine learning

Cria um recurso de execução de machine learning em um projeto e local especificados. O comando machine-learning-run create implanta o XProf como uma instância gerenciada no seu projeto. A instância gerenciada do XProf é usada para visualizar todos os perfis no projeto e é criada quando a primeira execução de machine learning é criada no projeto.

Use o comando machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

Há duas maneiras de criar uma execução de machine learning:

Registre os perfis capturados na plataforma de diagnóstico de ML.
Use o ML Diagnostics para realizar a captura de perfil on demand registrando uma execução ativa. Isso exige uma configuração de cluster do GKE e uma carga de trabalho implantada no GKE com o rótulo managed-mldiagnostics-gke=true.

Criar uma execução de ML e registrar perfis capturados

O código a seguir cria uma execução e registra os perfis capturados atuais no 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"

O exemplo de código usa as seguintes flags:

Sinalização	Requisito	Descrição
`machine-learning-run`	Obrigatório	Um identificador exclusivo para essa execução específica. Se o nome não for exclusivo, a criação da execução vai falhar com a mensagem "A execução de ML já existe".
`location`	Obrigatório	Todos os locais do Cluster Director são compatíveis, exceto `us-east5`. Essa flag pode ser definida por um argumento para cada comando ou com o comando: `gcloud config set compute/region`.
`gcs-path`	Obrigatório	O local de armazenamento Google Cloud em que todos os perfis são salvos. Por exemplo, `gs://my-bucket` ou `gs://my-bucket/folder1`. Necessário apenas se o SDK for usado para captura de perfil.
`run-group`	Opcional	Um identificador que pode ajudar a agrupar várias execuções pertencentes ao mesmo experimento. Por exemplo, todas as execuções associadas a uma varredura de tamanho de fração de TPU podem pertencer ao mesmo grupo.
`display-name`	Opcional	Nome de exibição da execução de machine learning. Se não for fornecido, será definido como o ID da execução de aprendizado de máquina.

A flag --labels list_existing_sessions_only=true é obrigatória se você quiser ver e gerenciar os perfis coletados no Diagnóstico de ML. A flag faz o seguinte:

Cria uma execução de machine learning com o estado "Concluído".
Pesquisa recursivamente arquivos xplane.pb no caminho do diretório do Cloud Storage.
Carrega todas as sessões de perfil localizadas no banco de dados do ML Diagnostics para visualização em Google Cloud, cria links compartilháveis para as sessões de perfil e permite que os usuários gerenciem esses perfis com a plataforma do ML Diagnostics.

Se a flag --labels list_existing_sessions_only estiver definida como true para uma execução, não será possível fazer criação de perfil sob demanda nem atualizar a execução. Só é possível ver e gerenciar perfis existentes.

Criar uma execução de ML para realizar a captura de perfil sob demanda

O código a seguir cria um mlrun para realizar a captura de perfil 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

Além das flags do exemplo anterior, o exemplo de código usa as seguintes flags adicionais:

Sinalização	Requisito	Descrição
`orchestrator`	Opcional	O orquestrador usado na execução. Se não for especificado, `gke` será usado por padrão. Valores válidos: `gce`, `gke`, `slurm`.
`gke-cluster-name`	Necessário para o GKE	O cluster da carga de trabalho. Por exemplo, `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Necessário para o GKE	O tipo de carga de trabalho. Por exemplo, `JobSet`.
`gke-namespace`	Necessário para o GKE	O namespace da carga de trabalho. Por exemplo, `default`.
`gke-workload-name`	Necessário para o GKE	O identificador da carga de trabalho. Por exemplo, `jobset-abcd`.
`gke-workload-create-time`	Necessário para o GKE	O carimbo de data/hora de criação de um JobSet no formato ISO. Por exemplo, `2026-02-20T06:00:00Z`.
`run-phase`	Opcional	Fase e estado de uma execução. Se não for fornecido, o padrão será `ACTIVE`.

Descrever a execução de machine learning

Confira os detalhes de uma execução de machine learning com o comando machine-learning-run describe:

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

O exemplo a seguir é uma solicitação de detalhes da execução em JSON:

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

O resultado será o seguinte:

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

Listar execuções de machine learning

Para conferir uma lista de execuções de machine learning em um projeto e local especificados, use o comando machine-learning-run list:

gcloud alpha mldiagnostics machine-learning-run list

O exemplo a seguir é uma solicitação de uma lista de até duas execuções, com saídas dos caminhos 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

Atualizar execuções de machine learning

Atualiza uma execução de machine learning em um projeto e local especificados. É possível atualizar o nome de exibição, a fase de execução, o orquestrador e os detalhes da carga de trabalho do GKE. Não é possível mudar o ID e o local da execução. Atualize uma execução com o comando machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

Forneça todos os campos incluídos na solicitação create. Se os campos obrigatórios não forem fornecidos durante a solicitação de atualização, eles serão substituídos pelos valores padrão.

A flag etag é um campo obrigatório e precisa ser o valor mais recente da ETag (tag de entidade) para um recurso de execução de ML. Para mais informações, consulte Usar tags de entidade para controle de simultaneidade otimista. Use o seguinte para encontrar o valor correto da ETAG:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Confira um exemplo de solicitação de atualização 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

Excluir execuções de machine learning

Exclua uma execução de machine learning em um projeto e local especificados com o comando machine-learning-run delete:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

A exclusão de uma execução de ML não exclui dados no Cloud Storage, no Cloud Logging ou na carga de trabalho do GKE. A exclusão do mlrun remove apenas os metadados relacionados à execução no sistema de diagnóstico de ML.

Comandos do Profiler

É possível usar o grupo de comandos do profiler para listar todos os perfis, encontrar nós do GKE da carga de trabalho em que o servidor XProf está sendo executado e capturar perfis on demand na CLI.

Listar destinos do criador de perfil

Liste todos os destinos do criador de perfil associados a uma execução de machine learning em um projeto e local especificados:

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

Esse comando requer o seguinte:

O Xprof on demand está ativado na carga de trabalho, que implanta o servidor XProf em todos os nós da carga de trabalho.
O cluster do GKE está configurado para o ML Diagnostics, com webhook e operador implantados.
Carga de trabalho implantada no GKE com o rótulo: managed-mldiagnostics-gke=true.

Veja um exemplo de solicitação:

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

Veja a seguir um exemplo da saída:

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

Listar sessões do criador de perfil

Liste todas as sessões do criador de perfil associadas a uma execução de machine learning em um projeto e local especificados com o seguinte comando:

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

Esse comando do criador de perfil não exige configuração do GKE ou da carga de trabalho. Ela vai listar todas as sessões de perfil, tanto programáticas quanto on demand. Se você tiver apenas capturas de perfil programáticas, use este comando para listar todas as sessões de perfil. Não é necessário configurar o GKE, rotular a carga de trabalho do GKE nem ativar o XProf sob demanda.

Veja um exemplo de solicitação:

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

Capturar sessões do criador de perfil on demand

É possível capturar uma sessão do criador de perfil on demand para uma execução de machine learning em um conjunto especificado de nós em que a carga de trabalho está sendo executada (destinos do criador de perfil).

Esse comando requer o seguinte:

O XProf on demand está ativado na carga de trabalho, que implanta o servidor XProf em todos os nós da carga de trabalho.
O cluster do GKE está configurado para o ML Diagnostics, com webhook e operador implantados.
Carga de trabalho implantada no GKE com o rótulo: managed-mldiagnostics-gke=true.

Veja um exemplo de solicitação:

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

O exemplo usa as seguintes flags:

Sinalização	Requisito	Descrição
`profiler-session-name`	Obrigatório	Nome da sessão do criador de perfil a ser capturada.
`duration`	Obrigatório	Duração da captura da sessão do criador de perfil. É do tipo `Duration`. Por exemplo, especifique uma duração de `1s` para 1 segundo, `400ms` para 400 milissegundos e `5m` para 5 minutos.
`targets`	Obrigatório	IDs dos destinos do criador de perfis ou identificadores totalmente qualificados para os destinos do criador de perfis. Precisa corresponder a uma lista de destinos associados à execução.
`device-tracer-level`	Opcional	Nível do rastreador de dispositivo para a sessão. Valores aceitos: `device-tracer-level-enabled`, `device-tracer-level-disabled` (padrão).
`host-tracer-level`	Opcional	Nível do rastreador de host para a sessão. Valores aceitos: `host-tracer-level-info` (padrão), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`.
`python-tracer-level`	Opcional	Nível do rastreador do Python para a sessão. Valores aceitos: `python-tracer-level-disabled` (padrão), `python-tracer-level-enabled`.