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

Começar a usar a CLI do ML Diagnostics

Use a CLI do Google Cloud para criar uma execução de machine learning, implantar XProf como uma instância gerenciada com um back-end escalonável e oferecer uma experiência de criação de perfil gerenciada em Google Cloud.

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

Comandos Machine-learning-run: Create, Delete, Describe, List, 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 XProf da 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 a gravação de dados. A captura on demand ocorre em tempo real, em que você aciona o criador de perfil enquanto a carga de trabalho já está em execução.

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 carga de trabalho de ML que detecta o gatilho da captura on demand para começar a capturar perfis. Use a porta 9999 para este comando: profiler.start_server(port=9999)

Para a captura 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 on demand não pode ocorrer durante o mesmo período.

Para a captura de perfil on demand, configure um cluster do GKE que instala o connection-operator. Para a captura de perfil programática, configure um cluster do GKE que instala o injection-webhook, usando o SDK do ML Diagnostics e rotulando a carga de trabalho.

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

Criar execução de machine learning

Crie 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 ML Diagnostics.
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.

Criar execução de ML e registrar perfis capturados

O código a seguir cria uma execução e registra perfis capturados 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 falhará com a mensagem: "A execução de ML já existe".
`location`	Obrigatório	Todos os locais do Cluster Director são aceitos, 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 Google Cloud local de armazenamento 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, ele será definido como o ID da execução de machine learning.

A flag --labels list_existing_sessions_only=true é necessária se você quiser visualizar e gerenciar os perfis coletados no ML Diagnostics. 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 ML Diagnostics.

Se a flag --labels list_existing_sessions_only estiver definida como true para uma execução, não será possível realizar a criação de perfil on demand ou atualizar a execução. Só é possível visualizar e gerenciar perfis.

Criar execução de ML para realizar a captura de perfil on demand

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 para a 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 da 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 de carimbo de data/hora ISO. Por exemplo: `2026-02-20T06:00:00Z`.
`run-phase`	Opcional	Fase e estado de uma execução. Se não for fornecido, será `ACTIVE` por padrão.

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 de execução em JSON:

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

O resultado será assim:

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

Receba uma lista de execuções de machine learning em um projeto e local especificados com 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

Atualize 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 de ETag (tag de entidade) mais recente 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 de ETAG correto:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Confira a seguir 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 nenhum dado no Cloud Storage, no Cloud Logging ou na carga de trabalho do GKE. A exclusão do mlrun exclui apenas os metadados relacionados à execução no sistema do ML Diagnostics.

Comandos do criador de perfil

É possível usar o grupo de comandos do criador de perfil para listar todos os perfis, encontrar nós do GKE da carga de trabalho em que o servidor XProf está em execução 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 exige 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.

Confira a seguir 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 comando a seguir:

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

Esse comando do criador de perfil não exige a configuração do GKE ou da carga de trabalho. Ele vai listar todas as sessões de perfil, programáticas e on demand. Se você tiver apenas capturas de perfil programáticas, use esse comando para listar todas as sessões de perfil. Não há configuração obrigatória do GKE, rotulagem da carga de trabalho do GKE ou ativação do XProf on demand.

Confira a seguir 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á em execução (destinos do criador de perfil).

Esse comando exige 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.

Confira a seguir 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 perfil ou identificadores totalmente qualificados para os destinos do criador de perfil. Precisa corresponder a uma lista de destinos associados à execução.
`device-tracer-level`	Opcional	Nível do rastreador de dispositivos 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`.