Criar cluster

Se você tiver interesse nos clusters de treinamento da Vertex AI, entre em contato com seu representante de vendas para ter acesso.

Esta página mostra o método direto, orientado por API, para criar e gerenciar um cluster de treinamento. Você vai aprender a definir a configuração completa do cluster, incluindo nós de login, partições de GPU de alta performance, como a A4, e configurações do orquestrador Slurm, em um arquivo JSON. Também está incluído como usar o curl e as chamadas da API REST para implantar essa configuração, criar o cluster e gerenciar o ciclo de vida dele com as operações GET, LIST, UPDATE e DELETE.

Definir a configuração do cluster

Crie um arquivo JSON para definir a configuração completa do cluster de treinamento.

Se a política organizacional proibir endereços IP públicos em instâncias de computação, implante o cluster de treinamento com o parâmetro enable_public_ips: false e use o Cloud NAT para saída da Internet.

A primeira etapa no provisionamento de um cluster de treinamento é definir a configuração completa em um arquivo JSON. Esse arquivo atua como o modelo do cluster, especificando tudo, desde o nome e as configurações de rede até o hardware para os nós de login e de trabalho.

A seção a seguir fornece vários arquivos de configuração JSON completos que servem como modelos práticos para uma variedade de casos de uso comuns. Consulte esta lista para encontrar o exemplo que mais se adequa às suas necessidades e use-o como ponto de partida.

GPU somente com o Filestore: uma configuração padrão para treinamento de GPU de uso geral.
GPU com Filestore e Lustre gerenciado: uma configuração avançada para jobs com uso intenso de E/S.
GPU com script de inicialização: mostra como executar comandos personalizados em nós na inicialização.
Cluster somente de CPU: uma configuração básica que usa apenas recursos de CPU.
CPU com configuração avançada do Slurm: um exemplo mostrando configurações personalizadas do programador Slurm.

Cada exemplo é seguido por uma descrição detalhada dos principais parâmetros usados nessa configuração específica.

Somente GPU com Filestore

Essa é a configuração padrão. Ele fornece uma instância do Filestore que serve como o diretório /home para o cluster, adequado para uso geral e armazenamento de dados do usuário.

O exemplo a seguir mostra o conteúdo de gpu-filestore.json. Essa especificação cria um cluster com uma partição de GPU. Você pode usar isso como um modelo e modificar valores como machineType ou nodeCount para atender às suas necessidades.

Para uma lista de parâmetros, consulte Referência de parâmetro.

 {
  "display_name": "DISPLAY_NAME",
  "network": {
    "network": "projects/PROJECT_ID/global/networks/NETWORK",
    "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK"
  },
  "node_pools": [
    {
      "id": "login",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 200
      }
    },
    {
      "id": "a4",
      "machine_spec": {
        "machine_type": "a4-highgpu-8g",
        "accelerator_type": "NVIDIA_B200",
        "accelerator_count": 8,
        "reservation_affinity": {
          "reservationAffinityType": "RESERVATION_AFFINITY_TYPE",
          "key": "compute.googleapis.com/reservation-name",
          "values": [
            "projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION"
          ]
        }
      },
      "provisioning_model": "RESERVATION",
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "hyperdisk-balanced",
        "boot_disk_size_gb": 200
      }
    }
  ],
  "orchestrator_spec": {
    "slurm_spec": {
      "home_directory_storage": "projects/PROJECT_ID/locations/ZONE/instances/FILESTORE",
      "partitions": [
        {
          "id": "a4",
          "node_pool_ids": [
            "a4"
          ]
        }
      ],
      "login_node_pool_id": "login"
    }
  }
}

GPU com Filestore e Managed Lustre

Essa configuração avançada inclui a instância padrão do Filestore, além de um sistema de arquivos Lustre de alto desempenho. Escolha essa opção se os jobs de treinamento exigirem acesso de alta capacidade de processamento a grandes conjuntos de dados.

Para uma lista de parâmetros, consulte Referência de parâmetro.

{
  "display_name": "DISPLAY_NAME",
  "network": {
    "network": "projects/PROJECT_ID/global/networks/NETWORK",
    "subnetwork": "projects/PROJECT_ID/regions/asia-sREGION/subnetworks/SUBNETWORK"
  },
  "node_pools": [
    {
      "id": "login",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 200
      },
      "lustres": [
        "projects/PROJECT_ID/locations/ZONE/instances/LUSTRE"
      ]
    },
    {
      "id": "a4",
      "machine_spec": {
        "machine_type": "a4-highgpu-8g",
        "accelerator_type": "NVIDIA_B200",
        "accelerator_count": 8,
        "reservation_affinity": {
          "reservation_affinity_type": RESERVATION_AFFINITY_TYPE,
          "key": "compute.googleapis.com/reservation-name",
          "values": [
            "projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME"
          ]
        }
      },
      "provisioning_model": "RESERVATION",
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "hyperdisk-balanced",
        "boot_disk_size_gb": 200
      },
      "lustres": [
        "projects/PROJECT_ID/locations/ZONE/instances/LUSTRE"
      ]
    }
  ],
  "orchestrator_spec": {
    "slurm_spec": {
      "home_directory_storage": "projects/PROJECT_ID/locations/ZONE/instances/FILESTORE",
      "partitions": [
        {
          "id": "a4",
          "node_pool_ids": [
            "a4"
          ]
        }
      ],
      "login_node_pool_id": "login"
    }
  }
}

GPU com script de inicialização

Este exemplo demonstra como adicionar um script personalizado a um pool de nós. Esse script é executado em todos os nós desse pool na inicialização. Para configurar isso, adicione os campos relevantes à definição do pool de nós, além das configurações gerais. Para uma lista de parâmetros e suas descrições, consulte Referência de parâmetros.

{
  "display_name": "DISPLAY_NAME",
  "network": {
    "network": "projects/PROJECT_ID/global/networks/NETWORK",
    "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK"
  },
  "node_pools": [
    {
      "id": "login",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 200
      },
      "startup_script" : "#Example script\nsudo mkdir -p /data\necho 'Script Finished'\n",
    },
    {
      "id": "a4",
      "machine_spec": {
        "machine_type": "a4-highgpu-8g",
        "accelerator_type": "NVIDIA_B200",
        "accelerator_count": 8,
        "reservation_affinity": {
          "reservationAffinityType": "RESERVATION_AFFINITY_TYPE",
          "key": "compute.googleapis.com/reservation-name",
          "values": [
            "projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME"
          ]
        }
      },
      "provisioning_model": "PROVISIONING_MODEL",
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "enable_public_ips": true,
      "zone": "ZONE",
      "boot_disk": {
        "boot_disk_type": "hyperdisk-balanced",
        "boot_disk_size_gb": 200
      },
      "startup_script" : "#Example script\nsudo mkdir -p /data\necho 'Script Finished'\n",
    }
  ],
  "orchestrator_spec": {
    "slurm_spec": {
      "home_directory_storage": "projects/PROJECT_ID/locations/ZONE/instances/FILESTORE",
      "partitions": [
        {
          "id": "a4",
          "node_pool_ids": [
            "a4"
          ]
        }
      ],
      "login_node_pool_id": "login"
    }
  }
}

Cluster somente CPU

Para provisionar um ambiente de cluster de treinamento, primeiro defina a configuração completa dele em um arquivo JSON. Esse arquivo funciona como o projeto do cluster, especificando tudo, desde o nome e as configurações de rede até o hardware para os nós de login e de trabalho.

Para uma lista de parâmetros, consulte Referência de parâmetro.

{
  "display_name": "DISPLAY_NAME",
  "network": {
    "network": "projects/PROJECT_ID/global/networks/NETWORK",
    "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK"
  },
  "node_pools": [
    {
      "id": "cpu",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "zone": "ZONE",
      "enable_public_ips": true,
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 120
      }
    },
    {
      "id": "login",
      "machine_spec": {
        "machine_type": "n2-standard-8",
      }
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "zone": "ZONE",
      "enable_public_ips": true,
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 120
      }
    },
  ],
  "orchestrator_spec": {
    "slurm_spec": {
      "home_directory_storage": "projects/PROJECT_ID/locations/ZONE/instances/FILESTORE",
      "partitions": [
        {
          "id": "cpu",
          "node_pool_ids": [
            "cpu"
          ]
        }
      ],
      "login_node_pool_id": "login"
    }
  }
}

CPU com configuração avançada do Slurm

Este exemplo demonstra como personalizar o orquestrador Slurm com parâmetros avançados. Use esse modelo se você precisar de controle refinado sobre o comportamento de programação de jobs, como definir pesos de prioridade multifator, configurar a substituição de jobs e executar scripts de prólogo e epílogo para configuração e limpeza automatizadas de jobs.

Para uma lista de parâmetros, consulte Referência de parâmetro.

{
  "display_name": "DISPLAY_NAME",
  "network": {
    "network": "projects/PROJECT_ID/global/networks/NETWORK",
    "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK"
  },
  "node_pools": [
    {
      "id": "cpu",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "zone": "ZONE",
      "enable_public_ips": true,
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 120
      }
    },
    {
      "id": "login",
      "machine_spec": {
        "machine_type": "n2-standard-8"
      },
      "scaling_spec": {
        "min_node_count": MIN_NODE_COUNT,
        "max_node_count": MAX_NODE_COUNT
      },
      "zone": "ZONE",
      "enable_public_ips": true,
      "boot_disk": {
        "boot_disk_type": "pd-standard",
        "boot_disk_size_gb": 120
      }
    }
  ],
  "orchestrator_spec": {
    "slurm_spec": {
      "home_directory_storage": "projects/PROJECT_ID/locations/ZONE/instances/FILESTORE",
      "accounting": {
        "accounting_storage_enforce": "ACCOUNTING_STORAGE_ENFORCE"
      },
      "scheduling": {
        "priority_type": "PRIORITY_TYPE",
        "priority_weight_age": PRIORITY_WEIGHT_AGE,
        "priority_weight_assoc": PRIORITY_WEIGHT_ASSOC,
        "priority_weight_fairshare": PRIORITY_WEIGHT_FAIRSHARE,
        "priority_weight_job_size": PRIORITY_WEIGHT_JOB_SIZE,
        "priority_weight_partition": PRIORITY_WEIGHT_PARTITION,
        "priority_weight_qos": PRIORITY_WEIGHT_QOS,
        "priority_weight_tres": "PRIORITY_WEIGHT_TRES",
        "preempt_type": "PREEMPT_TYPE",
        "preempt_mode": "PREEMPT_MODE",
        "preempt_exempt_time": "PREEMPT_EXEMPT_TIME"
      },
      "prolog_bash_scripts": [
        "#!/bin/bash\necho 'First prolog script running'",
        "#!/bin/bash\necho 'Second prolog script running'"
      ],
      "epilog_bash_scripts": [
        "#!/bin/bash\necho 'Epilog script running'"
      ]
      "partitions": [
        {
          "id": "cpu",
          "node_pool_ids": [
            "cpu"
          ]
        }
      ],
      "login_node_pool_id": "login"
    }
  }
}

Depois que o cluster for definido em um arquivo JSON, use os seguintes comandos da API REST para implantar e gerenciar o cluster. Os exemplos usam um alias gcurl, que é um atalho autenticado conveniente para interagir com os endpoints da API. Esses comandos abrangem todo o ciclo de vida, desde a implantação inicial do cluster até a atualização, passando por verificação do status, listagem de todos os clusters e, por fim, exclusão.

Autenticação

alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

Criar um arquivo JSON

Crie um arquivo JSON (por exemplo, @cpu-cluster.json) para especificar a configuração do cluster de treinamento de modelo.

Implantar o cluster

Depois de criar o arquivo de configuração JSON, você pode implantar o cluster usando a API REST.

Defina as variáveis de ambiente

Antes de executar o comando, defina as seguintes variáveis de ambiente. Isso torna o comando da API mais limpo e fácil de gerenciar.

PROJECT_ID: o ID do seu projeto Google Cloud em que o cluster será criado.
REGION: a Google Cloud região do cluster e dos recursos dele.
ZONE: a Google Cloud zona em que os recursos do cluster serão provisionados.
CLUSTER_ID: um identificador exclusivo para seu cluster de treinamento, que também é usado como prefixo para nomear recursos relacionados.

Execute o comando de criação

Agora, execute o comando gcurl a seguir. Ele usa o arquivo JSON (neste exemplo, cpu-cluster.json) como o corpo da solicitação e as variáveis de ambiente que você acabou de definir para construir o endpoint de API e os parâmetros de consulta.

  gcurl -X POST -d @cpu-cluster.json https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters?model_development_cluster_id=CLUSTER_ID

Quando a implantação começar, um ID de operação será gerado. Copie esse ID. Você vai precisar dele para validar seu cluster na próxima etapa.

  gcurl -X POST -d @cpu-cluster.json https://us-central1-aiplatform.googleapis.com/v1beta1/projects/managedtraining-project/locations/us-central1/modelDevelopmentClusters?model_development_cluster_id=training
  {
      "name": "projects/1059558423163/locations/us-central1/operations/2995239222190800896",
      "metadata": {
      "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateModelDevelopmentClusterOperationMetadata",
      "genericMetadata": {
        "createTime": "2025-10-24T14:16:59.233332Z",
        "updateTime": "2025-10-24T14:16:59.233332Z"
      },
      "progressMessage": "Create Model Development Cluster request received, provisioning..."
  }

Validar a implantação do cluster

Acompanhe o progresso da implantação usando o ID da operação fornecido quando você implantou o cluster. Por exemplo, 2995239222190800896 é o ID da operação no exemplo citado anteriormente.

    gcurl https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

Em resumo

Ao enviar a configuração do cluster com o comando POST gcurl, você inicia o provisionamento do cluster, que é uma operação assíncrona de longa duração. A API retorna imediatamente uma resposta que contém um Operation ID. É fundamental salvar esse ID, já que ele será usado nas etapas a seguir para monitorar o progresso da implantação, verificar se o cluster foi criado com sucesso e gerenciar o ciclo de vida dele.

Referência de parâmetros

A lista a seguir descreve todos os parâmetros usados nos exemplos de configuração. Os parâmetros são organizados em grupos lógicos com base no recurso que configuram.

Configurações gerais e de rede

DISPLAY_NAME: um nome exclusivo para o cluster de treinamento. A string só pode conter caracteres alfanuméricos minúsculos, precisa começar com uma letra e tem um limite de 10 caracteres.
PROJECT_ID: o ID do projeto do Google Cloud .
REGION: a Google Cloud região em que o cluster e os recursos dele vão estar localizados.
NETWORK: a rede de nuvem privada virtual a ser usada para os recursos do cluster.
ZONE: a Google Cloud zona do cluster e dos recursos dele.
SUBNETWORK: a sub-rede a ser usada para os recursos do cluster.

Configuração do pool de nós

Os parâmetros a seguir são usados para definir os pools de nós para nós de login e de trabalho.

Configurações comuns do pool de nós

ID: um identificador exclusivo para o pool de nós no cluster (por exemplo, "login", "a4", "cpu").
PROVISIONING_MODEL: o modelo de provisionamento para o nó de trabalho (por exemplo, ON_DEMAND, SPOT, RESERVATION, FLEX_START).
MACHINE_TYPE: o tipo de máquina para o nó de trabalho. Os valores aceitos são a3-megagpu-8g, a3-ultragpu-8g, a4-highgpu-8g.
MIN_NODE_COUNT: o MIN_NODE_COUNT precisa ser igual ao MAX_NODE_COUNT.
MAX_NODE_COUNT: para o pool de nós de login, o MAX_NODE_COUNT precisa ser igual ao MIN_NODE_COUNT.
ENABLE_PUBLIC_IPS: um booleano (true ou false) para determinar se o nó de login tem um endereço IP público.
BOOT_DISK_TYPE: o tipo de disco de inicialização do nó de login (por exemplo, pd-standard, pd-ssd).
BOOT_DISK_SIZE_GB: o tamanho do disco de inicialização em GB para o nó de login.

Configurações específicas do worker

ACCELERATOR_TYPE: o acelerador de GPU correspondente a ser anexado aos nós de trabalho. Os valores aceitos são:
- NVIDIA_H100_MEGA_80GB
- NVIDIA_H200_141GB
- NVIDIA_B200
ACCELERATOR_COUNT: o número de aceleradores a serem anexados a cada nó de worker.
RESERVATION_AFFINITY_TYPE: a afinidade de reserva do pool de nós (por exemplo, SPECIFIC_RESERVATION).
RESERVATION_NAME: o nome da reserva a ser usada no pool de nós.

Configuração do orquestrador e do armazenamento

Esses campos são definidos no bloco orchestrator_spec.slurm_spec do arquivo JSON.

Configurações principais do Slurm e de armazenamento

FILESTORE (corresponde a home_directory_storage): o nome completo do recurso da instância do Filestore a ser montada como o diretório /home.
LUSTRE (corresponde a lustres em um objeto node_pools): uma lista de instâncias gerenciadas do Lustre preexistentes para ativar nos nós do cluster e ter acesso a arquivos de alta performance.
LOGIN_NODE_POOL_ID (corresponde a login_node_pool_id): o ID do pool de nós que deve ser usado para nós de login.
partitions: uma lista de objetos de partição, em que cada objeto exige um id e uma lista de node_pool_ids.

Configurações avançadas do Slurm

prolog_bash_scripts: uma lista de strings, em que cada string contém o conteúdo completo de um script Bash a ser executado antes do início de um job.
epilog_bash_scripts: uma lista de strings, em que cada string contém o conteúdo completo de um script Bash a ser executado após a conclusão de um job.
ACCOUNTING_STORAGE_ENFORCE: impõe limites de contabilidade para o uso de armazenamento.
PRIORITY_TYPE: o algoritmo de prioridade de programação a ser usado (por exemplo, priority/multifactor).
priority_weight_*: um conjunto de valores inteiros que atribuem peso a diferentes fatores no cálculo da prioridade de programação (por exemplo, priority_weight_age, priority_weight_fairshare).
PREEMPT_TYPE: o plug-in de remoção para usar (por exemplo, preempt/partition_prio).
PREEMPT_MODE: o modo do plug-in de remoção (por exemplo, REQUEUE).
PREEMPT_EXEMPT_TIME: o período após o início de um job em que ele não pode ser interrompido.

A seguir

Use seu cluster de treinamento persistente ativo para executar as cargas de trabalho de machine learning.

Executar um job no cluster: envie um CustomJob para executar um job de treinamento no cluster permanente.
- Saiba como executar um job de treinamento distribuído
Orquestre seu treinamento com o Vertex AI Pipelines: para fluxos de trabalho repetíveis e de nível de produção, automatize o processo de envio de jobs usando o Vertex AI Pipelines.
- Saiba como orquestrar jobs em um cluster de treinamento
Veja e gerencie seu cluster: liste os clusters atuais, verifique o status deles e confira os detalhes da configuração usando a Google Cloud CLI ou o console Google Cloud .
- Saiba como gerenciar seu cluster de treinamento
Exclua o cluster para interromper os custos: os clusters de treinamento são permanentes e geram custos enquanto estão ativos.
- Saiba como excluir seu cluster de treinamento

Criar cluster Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Definir a configuração do cluster

Somente GPU com Filestore

GPU com Filestore e Managed Lustre

GPU com script de inicialização

Cluster somente CPU

CPU com configuração avançada do Slurm

Autenticação

Criar um arquivo JSON

Implantar o cluster

Defina as variáveis de ambiente

Execute o comando de criação

Validar a implantação do cluster

Em resumo

Referência de parâmetros

Configurações gerais e de rede

Configuração do pool de nós

Configurações comuns do pool de nós

Configurações específicas do worker

Configuração do orquestrador e do armazenamento

Configurações principais do Slurm e de armazenamento

Configurações avançadas do Slurm

A seguir

Criar cluster