A documentação da Vertex AI não está mais sendo atualizada

Os serviços da Vertex AI agora fazem parte da plataforma de agentes do Gemini Enterprise. Confira as informações mais atualizadas na documentação da plataforma do agente.

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

Criar cluster

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

Esta página fornece o método direto orientado pela 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 incluímos como usar chamadas de API REST e curl para implantar essa configuração, criando o cluster e gerenciando o ciclo de vida dele com 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 dele em um arquivo JSON. Esse arquivo atua como o blueprint do cluster, especificando tudo, desde o nome e as configurações de rede até o hardware dos nós de login e de worker.

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 melhor atenda às suas necessidades e use-o como ponto de partida.

GPU com Filestore apenas: uma configuração padrão para treinamento de GPU de uso geral.
GPU com Filestore e Managed Lustre: uma configuração avançada para jobs com uso intenso de E/S.
GPU com script de inicialização: demonstra 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 que mostra configurações personalizadas do escalonador do Slurm.

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

GPU com Filestore apenas

Essa é a configuração padrão. Ela fornece uma instância do Filestore que serve como 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â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
      }
    },
    {
      "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 alta performance. 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âmetros.

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

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

Para uma lista de parâmetros, 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": "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 do Slurm com parâmetros avançados. Use esse modelo se precisar de controle refinado sobre o comportamento de agendamento de jobs, como definir pesos de prioridade multifator, configurar a preempçã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âmetros.

{
  "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 comandos da API REST a seguir para implantar e gerenciar o cluster. Os exemplos usam um alias gcurl, que é um atalho autenticado e 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 de um cluster, a obtenção do status, a listagem de todos os clusters e, por fim, a exclusão do cluster.

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

Implantar o cluster

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

Definir 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 projeto do Your Google Cloud project em que o cluster será criado.
REGION: A Google Cloud região para o cluster e os recursos dele.
ZONE: A Google Cloud zona em que os recursos do cluster serão provisionados.
CLUSTER_ID: um identificador exclusivo para o cluster de treinamento, que também é usado como prefixo para nomear recursos relacionados.

Executar 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 da operação será gerado. Copie esse ID. Você vai precisar dele para validar o 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

O envio da configuração do cluster com o comando gcurl POST inicia o provisionamento do cluster, que é uma operação assíncrona de longa duração. A API retorna imediatamente uma resposta contendo um Operation ID. É fundamental salvar esse ID, porque você vai usá-lo nas etapas a seguir para monitorar o progresso da implantação, verificar se o cluster foi criado 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 é limitada a 10 caracteres.
PROJECT_ID: o ID do projeto do Your Google Cloud .
REGION: A Google Cloud região em que o cluster e os recursos dele estarão localizados.
NETWORK: a rede da nuvem privada virtual a ser usada para os recursos do cluster.
ZONE: The Google Cloud zone para o cluster e os 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 worker.

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 para o 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 worker. 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 trabalho.
RESERVATION_AFFINITY_TYPE: a afinidade de reserva para o pool de nós (por exemplo, SPECIFIC_RESERVATION).
RESERVATION_NAME: o nome da reserva a ser usada para o 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 do 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 do Managed Lustre pré-existentes a serem montadas nos nós do cluster para 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: aplica limites de faturamento para uso do armazenamento.
PRIORITY_TYPE: o algoritmo de prioridade de agendamento a ser usado (por exemplo, priority/multifactor).
priority_weight_*: um conjunto de valores inteiros que atribuem peso a diferentes fatores no cálculo de prioridade de agendamento (por exemplo, priority_weight_age, priority_weight_fairshare).
PREEMPT_TYPE: o plug-in de preempção a ser usado (por exemplo, preempt/partition_prio).
PREEMPT_MODE: o modo do plug-in de preempção (por exemplo, REQUEUE).
PREEMPT_EXEMPT_TIME: o tempo após o início de um job durante o qual ele não pode ser preempted.

A seguir

Use o 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 persistente.
- Saiba como executar um job de treinamento distribuído
Orquestrar o 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
Visualizar e gerenciar o cluster: liste os clusters atuais, verifique o status deles, e confira os detalhes da configuração usando a Google Cloud CLI ou o Google Cloud console.
- Saiba como gerenciar o cluster de treinamento
Exclua o cluster para interromper os custos: os clusters de treinamento são persistentes e geram custos enquanto estão ativos.
- Saiba como excluir o cluster de treinamento

A documentação da Vertex AI não está mais sendo atualizada

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

GPU com Filestore apenas

GPU com Filestore e Managed Lustre

GPU com script de inicialização

Cluster somente de CPU

CPU com configuração avançada do Slurm

Autenticação

Criar um arquivo JSON

Implantar o cluster

Definir as variáveis de ambiente

Executar 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 do armazenamento

Configurações avançadas do Slurm

A seguir

Criar cluster