Créer un cluster Cluster Director avec Pathways

Cette page explique aux administrateurs de plate-forme et aux ingénieurs en machine learning (ML) comment créer un cluster Cluster Director orchestré par Slurm et le configurer pour les charges de travail Pathways. En suivant ces étapes, vous provisionnez un cluster avec des tranches de TPU v6e, un nœud de contrôleur de processeur, un système de fichiers Google Cloud Managed Lustre partagé et l'environnement d'exécution /home/pathways. Pathways n'est pas préinstallé sur un cluster Cluster Director : après avoir créé le cluster, vous téléchargez les scripts Pathways sur le nœud de connexion et exécutez un script de configuration une fois.

Avant de commencer

  • Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

    gcloud

    Dans la console Google Cloud , activez Cloud Shell.

    Activer Cloud Shell

    En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement de shell dans lequel la Google Cloud CLI est déjà installée, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

    REST

    Pour utiliser les exemples API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à la gcloud CLI.

      Installez la Google Cloud CLI.

      Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

    Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud .

Avant de commencer

Avant de commencer, assurez-vous de remplir les conditions préalables suivantes :

  • Installez la Google Cloud CLI.
  • Activer l'API Hypercompute Cluster.
  • Assurez-vous que votre compte utilisateur et le compte de service Compute Engine par défaut disposent des rôles IAM (Identity and Access Management) requis pour créer un cluster Cluster Director et s'y connecter. Pour obtenir la liste des rôles, consultez la section Avant de commencer du guide de démarrage rapide de Cluster Director.
  • Créez une réservation de TPU v6e dans la zone où vous prévoyez de créer le cluster (par exemple, au moins quatre VM ct6e-standard-4t pour deux tranches 2x4).
  • Configurez sudo sans mot de passe sur les nœuds du cluster pour la récupération automatique des tranches. Demandez à votre administrateur de vous accorder le rôle "Connexion administrateur à l'OS Compute" (roles/compute.osAdminLogin) sur le projet.
  • Créez un bucket Cloud Storage pour les données de travail et les sorties de charge de travail Pathways, puis attribuez le rôle Utilisateur d'objets Storage (roles/storage.objectUser) sur le projet à votre compte utilisateur et au compte de service Compute Engine par défaut.

Configurer votre environnement local

Connectez-vous avec vos identifiants Google Cloud  :

gcloud auth login

Définissez les variables d'environnement suivantes avec des valeurs adaptées à votre charge de travail :

export PROJECT=PROJECT_ID
export REGION=REGION
export ZONE=ZONE
export CLUSTER_ID=CLUSTER_ID
export RESERVATION_NAME=RESERVATION_NAME

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • REGION : région dans laquelle vous créez des ressources.
  • ZONE : zone dans laquelle vous créez des ressources.
  • CLUSTER_ID : nom du cluster. Le nom peut contenir jusqu'à 10 caractères et ne peut utiliser que des chiffres et des lettres minuscules.
  • RESERVATION_NAME : nom de votre réservation de TPU v6e dans ZONE.

Créer un cluster Cluster Director

Dans l'exemple suivant, vous allez créer un cluster avec deux tranches TPU v6e 2x4 (quatre VM ct6e-standard-4t) à partir de votre réservation, et un nœud de processeur pour le contrôleur Pathways. Tous les nœuds installent un système de fichiers Managed Lustre partagé sur /home. Pour en savoir plus sur les champs de la définition de cluster, consultez Créer un cluster personnalisé.

  1. Créez le cluster à l'aide de l'API REST :

    Créez le corps de la requête :

    cat <<EOF > "${CLUSTER_ID}_create.json"
{
  "networkResources": {
    "net": {
      "config": {
        "newNetwork": {
          "network": "projects/${PROJECT}/global/networks/${CLUSTER_ID}-net"
        }
      }
    }
  },
  "storageResources": {
    "home": {
      "config": {
        "newLustre": {
          "lustre": "projects/${PROJECT}/locations/${ZONE}/instances/${CLUSTER_ID}-lustre",
          "filesystem": "lustre",
          "capacityGb": "18000",
          "perUnitStorageThroughput": "500"
        }
      }
    }
  },
  "computeResources": {
    "crtpu": {
      "config": {
        "newReservedInstances": {
          "reservation": "projects/${PROJECT}/zones/${ZONE}/reservations/${RESERVATION_NAME}"
        }
      }
    },
    "crcpu": {
      "config": {
        "newOnDemandInstances": {
          "zone": "${ZONE}",
          "machineType": "n2-highmem-32"
        }
      }
    }
  },
  "orchestrator": {
    "slurm": {
      "loginNodes": {
        "count": "1",
        "zone": "${ZONE}",
        "machineType": "n2-standard-16",
        "enableOsLogin": true,
        "enablePublicIps": true,
        "bootDisk": {
          "type": "pd-balanced",
          "sizeGb": "100"
        },
        "storageConfigs": [
          {
            "id": "home",
            "localMount": "/home"
          }
        ]
      },
      "nodeSets": [
        {
          "id": "nstpu",
          "computeId": "crtpu",
          "staticNodeCount": "4",
          "maxDynamicNodeCount": "0",
          "enablePublicIps": true,
          "resourcePolicyConfig": {
            "acceleratorTopology": "2x4"
          },
          "computeInstance": {
            "bootDisk": {
              "type": "hyperdisk-balanced",
              "sizeGb": "100"
            }
          },
          "storageConfigs": [
            {
              "id": "home",
              "localMount": "/home"
            }
          ]
        },
        {
          "id": "nscpu",
          "computeId": "crcpu",
          "staticNodeCount": "1",
          "maxDynamicNodeCount": "0",
          "enablePublicIps": true,
          "computeInstance": {
            "bootDisk": {
              "type": "pd-balanced",
              "sizeGb": "100",
              "image": "projects/clusterdirector-public-images/global/images/family/tpu-v6e-v5p-ubuntu2204-slurm2605-v20260902"
            }
          },
          "storageConfigs": [
            {
              "id": "home",
              "localMount": "/home"
            }
          ]
        }
      ],
      "partitions": [
        {
          "id": "tpu",
          "nodeSetIds": ["nstpu"]
        },
        {
          "id": "cpu",
          "nodeSetIds": ["nscpu"]
        }
      ],
      "defaultPartition": "tpu",
      "config": {
        "requeueExitCodes": [1, 2, 134, 137, 139, 143]
      }
    }
  }
}
EOF

    Envoyez ensuite la requête :

    curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d @"${CLUSTER_ID}_create.json" \
    "https://hypercomputecluster.googleapis.com/v1alpha/projects/${PROJECT}/locations/${REGION}/clusters?clusterId=${CLUSTER_ID}"

    Le cluster inclut les éléments suivants :

    • Partition tpu : ensemble de nœuds statiques de VM TPU v6e réservées. staticNodeCount est le nombre de VM et acceleratorTopology est la topologie de chaque tranche. Chaque VM ct6e-standard-4t possède quatre puces. Une tranche 2x4 comporte donc deux VM. Pour plus de tranches, multipliez : deux tranches de 2x4 nécessitent un staticNodeCount de 4.
    • Partition cpu : une VM à la demande qui exécute le gestionnaire de ressources Pathways, le serveur proxy IFRT et le client MaxText. Les scripts Pathways envoient des jobs à une partition nommée cpu. La VM utilise le type de machine n2-highmem-32, car le service Pathways et MaxText ont besoin de jusqu'à 240 Go de mémoire lorsqu'ils enregistrent des points de contrôle. Il utilise également une image avec Slurm 26.05, qui est compatible avec les tranches de TPU, car le service Pathways envoie les jobs de travailleurs TPU à partir de cette VM.
    • requeueExitCodes : Slurm remet en file d'attente un job qui se termine avec l'un de ces codes. Ce paramètre permet à Slurm de redémarrer un job de travailleur TPU lorsque n'importe quelle VM de la tranche est préemptée, et pas seulement la première.

  2. Attendez que le cluster soit prêt. Vous pouvez suivre la progression sur la page Cluster Director de la console Google Cloud ou vérifier que reconciling est false dans le résultat de la commande suivante :

    curl -s \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://hypercomputecluster.googleapis.com/v1alpha/projects/${PROJECT}/locations/${REGION}/clusters/${CLUSTER_ID}"

Configurer l'environnement Pathways

L'environnement Pathways se trouve dans /home/pathways sur le système de fichiers partagé. Vous le configurez donc une fois par cluster. Il contient les images de conteneur Pathways, un environnement Python avec JAX et pathwaysutils, ainsi que les scripts Pathways.

  1. Connectez-vous au nœud de connexion. Pour découvrir d'autres méthodes de connexion, consultez Se connecter à un cluster.

    gcloud compute ssh ${CLUSTER_ID}-login-001 \
    --project=${PROJECT} \
    --zone=${ZONE} \
    --tunnel-through-iap

  2. Vérifiez que les partitions cpu et tpu existent et sont à l'état idle :

    sinfo -o "%P %a %D %T %N %f"

    Le résultat ressemble à ce qui suit :

    PARTITION AVAIL NODES STATE NODELIST FEATURES
tpu* up 4 idle ${CLUSTER_ID}-nstpu-[0-3]
cpu up 1 idle ${CLUSTER_ID}-nscpu-0

  3. Téléchargez les scripts Pathways sur le nœud de connexion :

    mkdir -p ~/pathways-scripts && cd ~/pathways-scripts
for f in setup_env.sh start_pathways.sh run_worker_slice.sh run_maxtext.sh; do
  curl -fsSLO "https://raw.githubusercontent.com/GoogleCloudPlatform/slurm-gcp/tpu-2605/pathways/scripts/${f}"
done

    Cette commande télécharge les scripts suivants :

    • setup_env.sh : effectue une configuration unique de l'environnement Pathways.
    • start_pathways.sh : démarre le service Pathways.
    • run_worker_slice.sh : démarre le nœud de calcul Pathways pour une tranche de TPU (envoyé par start_pathways.sh).
    • run_maxtext.sh : exécute un exemple de charge de travail d'entraînement MaxText.

  4. Exécutez le script de configuration. Cela prend environ cinq minutes :

    chmod +x *.sh
./setup_env.sh

    Le script extrait les images du serveur et du proxy Pathways, crée un environnement Python avec JAX, pathwaysutils et MaxText, copie les scripts dans /home/pathways et associe ~/pathways à /home/pathways. Il se termine par un résultat semblable à celui-ci :

    Environment ready: JAX 0.11.1

  5. Facultatif : Pour permettre à d'autres utilisateurs du cluster d'accéder à l'environnement Pathways, demandez-leur d'associer /home/pathways à leur répertoire d'accueil :

    ln -sfn /home/pathways ~/pathways

À ce stade, le cluster est prêt pour Pathways. Vous démarrez le service Pathways dans le cadre de l'exécution d'une charge de travail, car les charges de travail par lot et interactives le démarrent avec des paramètres différents. Pour en savoir plus, consultez Exécuter une charge de travail par lot avec Pathways et Exécuter une charge de travail interactive avec Pathways.

Si vous rencontrez des problèmes, consultez Résoudre les problèmes liés à Pathways sur Cloud.

Nettoyer

Pour éviter que les ressources utilisées sur cette page ne soient facturées sur votre compte Google Cloud , supprimez le cluster Cluster Director lorsque vous avez terminé :

curl -s -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://hypercomputecluster.googleapis.com/v1alpha/projects/${PROJECT}/locations/${REGION}/clusters/${CLUSTER_ID}"

Étapes suivantes