Crea cluster

Se ti interessano i cluster di addestramento di Gemini Enterprise Agent Platform, contatta il tuo rappresentante di vendita per l'accesso.

Questa pagina fornisce il metodo diretto basato su API per creare e gestire un cluster di addestramento. Scoprirai come definire la configurazione completa del cluster, inclusi i nodi di accesso, le partizioni GPU ad alte prestazioni come A4 e le impostazioni dell'orchestratore Slurm, all'interno di un file JSON. Sono incluse anche informazioni su come utilizzare le chiamate curl e API REST per eseguire il deployment di questa configurazione, creare il cluster e gestirne il ciclo di vita con le operazioni GET, LIST, UPDATE e DELETE.

Definisci la configurazione del cluster

Crea un file JSON per definire la configurazione completa del cluster di training.

Se il criterio dell'organizzazione vieta gli indirizzi IP pubblici sulle istanze di calcolo, esegui il deployment del cluster di addestramento con il parametro enable_public_ips: false e utilizza Cloud NAT per l'uscita da internet.

Il primo passaggio per il provisioning di un cluster di addestramento è definire la sua configurazione completa in un file JSON. Questo file funge da progetto per il cluster, specificando tutto, dal nome e dalle impostazioni di rete all'hardware per i nodi di accesso e worker.

La sezione seguente fornisce diversi file di configurazione JSON completi che fungono da modelli pratici per una serie di casi d'uso comuni. Consulta questo elenco per trovare l'esempio più adatto alle tue esigenze e utilizzalo come punto di partenza.

Ogni esempio è seguito da una descrizione dettagliata dei parametri chiave utilizzati all'interno di quella configurazione specifica.

Solo GPU con Filestore

Questa è la configurazione standard. Fornisce un'istanza Filestore che funge da directory /home per il cluster, adatta all'uso generale e all'archiviazione dei dati utente.

L'esempio seguente mostra i contenuti di gpu-filestore.json. Questa specifica crea un cluster con una partizione GPU. Puoi utilizzarlo come modello e modificare valori come machineType o nodeCount in base alle tue esigenze.

Per un elenco dei parametri, consulta Riferimento ai parametri.

 {
  "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
      },
      "labels": { "example-key": "example-value" }
    },
    {
      "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": "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
      },
      "labels": { "example-key": "example-value" }
    }
  ],
  "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 con Filestore e Managed Lustre

Questa configurazione avanzata include l'istanza Filestore standard oltre a un file system Lustre ad alte prestazioni. Scegli questa opzione se i tuoi job di addestramento richiedono un accesso ad alta velocità effettiva a set di dati di grandi dimensioni.

Per un elenco dei parametri, consulta Riferimento ai parametri.

{
  "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 con script di avvio

Questo esempio mostra come aggiungere uno script personalizzato a un pool di nodi. Questo script viene eseguito su tutti i nodi del pool all'avvio. Per configurare questa impostazione, aggiungi i campi pertinenti alla definizione del pool di nodi oltre alle impostazioni generali. Per un elenco dei parametri e delle relative descrizioni, consulta Riferimento ai parametri.

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

Per eseguire il provisioning di un ambiente di cluster di addestramento, devi prima definire la sua configurazione completa in un file JSON. Questo file funge da progetto per il cluster, specificando tutto, dal nome e dalle impostazioni di rete all'hardware per i nodi di accesso e worker.

Per un elenco dei parametri, consulta Riferimento ai parametri.

{
  "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 con configurazione Slurm avanzata

Questo esempio mostra come personalizzare l'orchestratore Slurm con parametri avanzati. Utilizza questo modello se hai bisogno di un controllo granulare sul comportamento di pianificazione dei job, ad esempio impostando pesi di priorità multifattoriale, configurando la preemption dei job ed eseguendo script prolog ed epilog per la configurazione e la pulizia automatizzate dei job.

Per un elenco dei parametri, consulta Riferimento ai parametri.

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

Una volta definito il cluster in un file JSON, utilizza i seguenti comandi dell'API REST per eseguire il deployment e gestire il cluster. Gli esempi utilizzano un alias gcurl, che è una scorciatoia autenticata e comoda per interagire con gli endpoint API. Questi comandi coprono l'intero ciclo di vita, dall'implementazione iniziale del cluster all'aggiornamento di un cluster, all'ottenimento del relativo stato, all'elenco di tutti i cluster e infine all'eliminazione del cluster.

Autenticazione

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

Crea un file JSON

Crea un file JSON (ad esempio, @cpu-cluster.json) per specificare la configurazione del cluster di addestramento del modello.

Esegui il deployment del cluster

Dopo aver creato il file di configurazione JSON, puoi eseguire il deployment del cluster utilizzando l'API REST.

Imposta le variabili di ambiente

Prima di eseguire il comando, imposta le seguenti variabili di ambiente. In questo modo, il comando API è più pulito e più facile da gestire.

  • PROJECT_ID: l'ID progetto Google Cloud in cui verrà creato il cluster.
  • REGION: La Google Cloud regione del cluster e delle relative risorse.
  • ZONE: la zona Google Cloud in cui verranno sottoposte a provisioning le risorse del cluster.
  • CLUSTER_ID: un identificatore univoco per il cluster di addestramento, che viene utilizzato anche come prefisso per denominare le risorse correlate.

Esegui il comando create

Ora esegui il seguente comando gcurl. Utilizza il file JSON (in questo esempio, cpu-cluster.json) come corpo della richiesta e le variabili di ambiente che hai appena impostato per creare l'endpoint API e i parametri di query.

  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
    

Una volta avviato il deployment, verrà generato un ID operazione. Assicurati di copiare questo ID. Ti servirà per convalidare il cluster nel passaggio successivo.

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

Convalida il deployment del cluster

Monitora l'avanzamento del deployment utilizzando l'ID operazione fornito quando hai eseguito il deployment del cluster. Ad esempio, 2995239222190800896 è l'ID operazione nell'esempio citato in precedenza.

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

In sintesi

L'invio della configurazione del cluster con il comando gcurl POST avvia il provisioning del cluster, che è un'operazione asincrona a lunga esecuzione. L'API restituisce immediatamente una risposta contenente un Operation ID. È fondamentale salvare questo ID, poiché lo utilizzerai nei passaggi successivi per monitorare l'avanzamento del deployment, verificare che il cluster sia stato creato correttamente e gestirne il ciclo di vita.

Riferimento ai parametri

Il seguente elenco descrive tutti i parametri utilizzati negli esempi di configurazione. I parametri sono organizzati in gruppi logici in base alla risorsa che configurano.

Impostazioni generali e di rete

  • DISPLAY_NAME: un nome univoco per il cluster di addestramento. La stringa può contenere solo caratteri alfanumerici minuscoli, deve iniziare con una lettera e non può superare i 10 caratteri.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REGION: la regione Google Cloud in cui si troveranno il cluster e le relative risorse.
  • NETWORK: la rete Virtual Private Cloud da utilizzare per le risorse del cluster.
  • ZONE: la Google Cloud zona per il cluster e le relative risorse.
  • SUBNETWORK: La subnet da utilizzare per le risorse del cluster.

Configurazione del node pool

I seguenti parametri vengono utilizzati per definire i node pool per i nodi di accesso e di lavoro.

Impostazioni comuni del pool di nodi

  • ID: un identificatore univoco per il pool di nodi all'interno del cluster (ad esempio, "login", "a4", "cpu").
  • PROVISIONING_MODEL: il modello di provisioning per il nodo worker (ad esempio ON_DEMAND, SPOT, RESERVATION, FLEX_START).
  • MACHINE_TYPE: Il tipo di macchina per il nodo di lavoro. I valori supportati sono a3-megagpu-8g, a3-ultragpu-8g, a4-highgpu-8g.
  • MIN_NODE_COUNT: MIN_NODE_COUNT deve essere uguale a MAX_NODE_COUNT.
  • MAX_NODE_COUNT: Per il pool di nodi di accesso, MAX_NODE_COUNT deve essere uguale a MIN_NODE_COUNT.
  • ENABLE_PUBLIC_IPS: un valore booleano (true o false) per determinare se il nodo di accesso ha un indirizzo IP pubblico.
  • BOOT_DISK_TYPE: Il tipo di disco di avvio per il nodo di accesso (ad esempio, pd-standard, pd-ssd).
  • BOOT_DISK_SIZE_GB: le dimensioni del disco di avvio in GB per il nodo di accesso.
  • LABELS: un insieme di coppie chiave/valore per etichettare il pool di nodi.

Impostazioni di archiviazione aggiuntive

  • FILESTORES (corrisponde a filestores all'interno di un oggetto node_pools): un elenco di istanze Filestore preesistenti da montare sul pool di nodi per l'accesso condiviso ai file.
  • LUSTRES (corrisponde a lustres all'interno di un oggetto node_pools): un elenco di istanze Lustre preesistenti da montare sul pool di nodi per l'accesso ai file ad alte prestazioni.

Impostazioni specifiche del worker

  • ACCELERATOR_TYPE: l'acceleratore GPU corrispondente da collegare ai nodi worker. I valori supportati sono:
    • NVIDIA_H100_MEGA_80GB
    • NVIDIA_H200_141GB
    • NVIDIA_B200
  • ACCELERATOR_COUNT: Il numero di acceleratori da collegare a ogni nodo worker.
  • RESERVATION_AFFINITY_TYPE (corrisponde a machine_spec.reservation_affinity.reservationAffinityType): l'affinità di prenotazione per il pool di nodi. Questo parametro deve essere SPECIFIC_RESERVATION, l'unico valore supportato. Quando viene utilizzato SPECIFIC_RESERVATION, devi specificare la prenotazione in machine_spec.reservation_affinity.values.
  • RESERVATION_NAME: il nome della prenotazione da utilizzare per il pool di nodi. Questo valore viene utilizzato nel nome completo della risorsa di prenotazione fornito in machine_spec.reservation_affinity.values, ad esempio projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME. È necessaria una prenotazione quando RESERVATION_AFFINITY_TYPE è SPECIFIC_RESERVATION.

Configurazione dell'orchestratore e dello spazio di archiviazione

Questi campi sono definiti all'interno del blocco orchestrator_spec.slurm_spec del file JSON.

Impostazioni di base di Slurm e Storage

  • HOME_DIRECTORY_STORAGE (corrisponde a home_directory_storage): il nome completo della risorsa dell'istanza di archiviazione preesistente da montare come directory /home. Può essere un'istanza Filestore o Lustre.
  • LOGIN_NODE_POOL_ID (corrisponde a login_node_pool_id): l'ID del pool di nodi da utilizzare per i nodi di accesso.
  • partitions: un elenco di oggetti partizione, in cui ogni oggetto richiede un id e un elenco di node_pool_ids.

Impostazioni avanzate di Slurm

  • prolog_bash_scripts: un elenco di stringhe, dove ogni stringa contiene l'intero contenuto di uno script Bash da eseguire prima dell'inizio di un job.
  • epilog_bash_scripts: un elenco di stringhe, dove ogni stringa contiene l'intero contenuto di uno script Bash da eseguire al termine di un job.
  • ACCOUNTING_STORAGE_ENFORCE: impone limiti contabili per l'utilizzo dello spazio di archiviazione.
  • PRIORITY_TYPE: L'algoritmo di priorità di pianificazione da utilizzare (ad esempio, priority/multifactor).
  • priority_weight_*: un insieme di valori interi che assegnano un peso diverso ai vari fattori nel calcolo della priorità di pianificazione (ad esempio, priority_weight_age, priority_weight_fairshare).
  • PREEMPT_TYPE: il plug-in di preempt da utilizzare (ad esempio preempt/partition_prio).
  • PREEMPT_MODE: la modalità del plug-in di preemptive (ad esempio, REQUEUE).
  • PREEMPT_EXEMPT_TIME: il periodo di tempo dopo l'inizio di un job durante il quale non può essere interrotto.

Configurazione di runtime

Questi campi sono definiti all'interno del blocco runtime_spec del file JSON.

  • service_account: il account di servizio predefinito utilizzato dal cluster durante l'esecuzione di qualsiasi carico di lavoro. Se non viene specificato, viene utilizzato il account di servizio Compute Engine predefinito. Questo campo non può essere aggiornato dopo la creazione del cluster.

Passaggi successivi

Utilizza il cluster di addestramento permanente attivo per eseguire i carichi di lavoro di machine learning.