Entraîner des modèles de machine learning à grande échelle sur GKE avec le checkpointing multicouche

Cette page explique comment utiliser les points de contrôle multiniveaux pour stocker et gérer de manière fiable les points de contrôle pendant l'entraînement de votre modèle de machine learning sur GKE. Le stockage et la gestion des points de contrôle sont essentiels pour les jobs d'entraînement à grande échelle, définis comme ceux utilisant plus de milliers de nœuds. Les interruptions de ces jobs à grande échelle sont fréquentes (potentiellement toutes les heures) et la récupération peut être lente.

Avantages

L'utilisation de la vérification multiniveau offre les avantages suivants :

  • Gestion entièrement orchestrée des données de point de contrôle, y compris les sauvegardes, la réplication et la restauration automatique pour les charges de travail suivantes :
  • Récupération rapide des jobs d'entraînement à partir d'un point de contrôle stocké dans le nœud local. Vous pouvez également effectuer une récupération à l'aide de points de contrôle stockés dans un autre nœud du cluster d'entraînement.
  • Restauration rapide des jobs d'entraînement à partir d'un point de contrôle stocké sur une sauvegarde Cloud Storage dans les pires scénarios, où il n'y a pas de points de contrôle dans le cluster.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Google Kubernetes Engine.
  • Activer l'API Google Kubernetes Engine
  • Si vous souhaitez utiliser la Google Cloud CLI pour cette tâche, installez puis initialisez la gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la commande gcloud components update. Il est possible que les versions antérieures de la gcloud CLI ne permettent pas d'exécuter les commandes de ce document.

Conditions requises

La création de points de contrôle multiniveau nécessite un cluster GKE version 1.32.4-gke.1415000 ou ultérieure.

Limites

  • Les clusters Autopilot ne sont pas compatibles.

Configurer des nœuds GKE pour utiliser la mise en point de contrôle multiniveau

Cette section explique comment configurer des nœuds GKE sur des clusters nouveaux et existants.

Configurer des nœuds sur un nouveau cluster

  1. Créez un cluster avec la vérification de l'état à plusieurs niveaux, le pilote CSI Cloud Storage FUSE et la Workload Identity Federation for GKE activés. Si vous utilisez des tranches de TPU pour votre charge de travail de machine learning, vous devez ajuster la commande de création de cluster pour inclure la configuration d'un pool de nœuds de tranche de TPU.

    gcloud container clusters create CLUSTER_NAME \
        --addons=HighScaleCheckpointing,GcsFuseCsiDriver  \
        --node-locations=NODE_LOCATION \
        --workload-pool=PROJECT_ID.svc.id.goog \
        --cluster-version=CLUSTER_VERSION
        --location=CLUSTER_LOCATION \
        --machine-type=MACHINE_TYPE \
        --num-nodes=NUM_NODES
    

    Remplacez les valeurs suivantes :

    • CLUSTER_NAME : nom du cluster.
    • NODE_LOCATION : zone de vos nœuds de cluster. C'est là que se trouve votre capacité de TPU.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • CLUSTER_VERSION : version de votre cluster. La version minimale compatible est la 1.32.4-gke.1415000.
    • CLUSTER_LOCATION : région dans laquelle vous souhaitez créer votre cluster.
    • MACHINE_TYPE : type de machine utilisé pour les nœuds qui exécutent des composants tels que le contrôleur JobSet et le contrôleur de point de contrôle multiniveau. Pour l'entraînement à grande échelle, nous vous recommandons d'utiliser au moins e2-standard-4 machines. Vous n'utiliserez pas ce type de machine pour l'entraînement de modèles. À la place, vous créerez des pools de nœuds distincts à cet effet, en utilisant souvent des familles de VM optimisées pour les accélérateurs.
    • NUM_NODES : nombre de nœuds à créer dans chacune des zones du cluster.

Configurer des nœuds sur un cluster existant

Pour utiliser les points de contrôle multiniveaux avec un cluster existant, activez-les ainsi que le pilote CSI Cloud Storage FUSE et Workload Identity Federation for GKE à l'aide des commandes suivantes. La version de votre cluster existant doit être ultérieure à la version 1.32.3-gke.1170000.

  1. Activez Workload Identity Federation for GKE :

    gcloud container clusters update CLUSTER_NAME \
        --workload-pool=PROJECT_ID.svc.id.goog \
        --location=CLUSTER_LOCATION
    

    Remplacez les valeurs suivantes :

    • CLUSTER_NAME : nom du cluster.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • CLUSTER_LOCATION : région du cluster.
  2. Activez les points de contrôle multiniveaux et le pilote CSI Cloud Storage FUSE :

    gcloud container clusters update CLUSTER_NAME \
        --update-addons=HighScaleCheckpointing=ENABLED,GcsFuseCsiDriver=ENABLED \
        --location=CLUSTER_LOCATION
    

Configurer les autorisations pour utiliser les points de contrôle multiniveaux

Cette section explique comment configurer les autorisations pour utiliser les points de contrôle multiniveaux.

Accorder l'accès aux buckets Cloud Storage

Les volumes éphémères utilisés par le pilote CSI de point de contrôle multiniveau doivent utiliser des buckets Cloud Storage existants.

Pour stocker des points de contrôle dans un bucket Cloud Storage, la fonctionnalité de points de contrôle multiniveaux doit avoir accès au bucket. Attribuez le rôle IAM Utilisateur d'objets Storage (roles/storage.objectUser) sur le bucket au compte de service Kubernetes pour les points de contrôle multiniveaux.

gcloud storage buckets add-iam-policy-binding gs://GCS_BUCKET \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/gke-managed-checkpointing/sa/gke-checkpointing-multitier-node" \
    --role "roles/storage.objectUser"

Remplacez les valeurs suivantes :

(Facultatif) Accorder l'accès au compte de service Compute Engine par défaut

Si vos instances Compute Engine ont besoin d'un accès en lecture au bucket Cloud Storage, attribuez le rôle IAM Lecteur des objets de l'espace de stockage (roles/storage.objectViewer) au compte de service Compute Engine par défaut.

gcloud storage buckets add-iam-policy-binding gs://GCS_BUCKET \
    --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/storage.objectViewer

Déployer le contrôleur JobSet

Le contrôleur JobSet est chargé de gérer les jobs par lot qui exécutent l'entraînement de votre modèle sur GKE. Son allocation de ressources est ajustée pour gérer efficacement la charge de travail. Assurez-vous que votre lanceur de job d'entraînement déploie et utilise JobSet.

Pour augmenter la demande de mémoire à 1 Gio, la limite de mémoire à 2 Gio et la demande de processeur à 1 pour le conteneur du gestionnaire dans votre déploiement JobSet, exécutez la commande de correctif suivante :

kubectl patch -n jobset-system deploy jobset-controller-manager --type json \
    --patch '[{"op": "add", "path": "/spec/template/spec/containers/0/resources", "value": {"limits": {"memory": "2Gi"}, "requests": {"cpu": "1", "memory": "1Gi"}}}]'

Initialiser le pilote CSI de point de contrôle multiniveau

Cette section explique comment initialiser le pilote CSI Multi-Tier Checkpointing sur les nœuds où vos charges de travail seront exécutées. Le pilote CSI est chargé de gérer le stockage et la gestion des points de contrôle pendant le processus d'entraînement de votre modèle.

Créer une CheckpointConfiguration

Un CheckpointConfiguration est une ressource personnalisée Kubernetes qui spécifie les propriétés de déploiement du pilote CSI de point de contrôle multiniveau. Cette ressource est limitée au cluster.

  1. Créez le fichier manifeste checkpoint.yaml suivant.

    apiVersion: checkpointing.gke.io/v1
    kind: CheckpointConfiguration
    metadata:
      name: MTC_CONFIG_NAME-configuration
    spec:
        cloudStorageBucketName: GCS_BUCKET
        nodeSelector:
            node.kubernetes.io/instance-type: MACHINE_TYPE
        tolerations:
        - key: TOLERATION_KEY
            operator: Exists
            effect: NoSchedule
        inMemoryVolumeSize: IN_MEMORY_VOLUME_SIZE
        gcsFuseMountOptions:
        - implicit-dirs
        - metadata-cache:negative-ttl-secs:0
        - metadata-cache:ttl-secs:60
        - metadata-cache:stat-cache-max-size-mb:-1
        - metadata-cache:type-cache-max-size-mb:-1
        - file-system:kernel-list-cache-ttl-secs:0
        - read_ahead_kb=1024
        - write:enable-streaming-writes:true
    

    Remplacez les éléments suivants :

    • MTC_CONFIG_NAME : nom de votre CheckpointConfiguration. Ce nom est global pour le cluster et n'est pas spécifique au job.
    • GCS_BUCKET : nom du bucket Cloud Storage dans lequel vous allez stocker les données de point de contrôle. Utilisez le bucket que vous avez configuré à l'étape Configurer un bucket Cloud Storage avec des autorisations.
    • MACHINE_TYPE : type de machine pour les accélérateurs correspondants. Les valeurs possibles sont les suivantes :

      • TPU v5p : ct5p-hightpu-4t
      • TPU v5e : ct5e-hightpu-4t
      • TPU v6e : ct6e-standard-4t
      • Ironwood (TPU7x) : tpu7x-standard-4t
      • GPU NVIDIA H100 80 Go (série A3) :

      Pour en savoir plus sur l'exécution de charges de travail distribuées sur des GPU avec GKE, consultez Exécuter des GPU multi-instances. Pour les TPU, consultez Créer le pool de nœuds de tranche TPU.

    • TOLERATION_KEY : ce champ permet de planifier le pilote CSI sur des nœuds avec des rejets correspondants. Pour en savoir plus sur le fonctionnement des rejets sur différents types d'accélérateurs, consultez les pages suivantes :

    • IN_MEMORY_VOLUME_SIZE : taille du cache de point de contrôle en mémoire. Spécifiez la quantité et l'unité (par exemple, 200 Gio).Cette valeur doit être :

      • Taille du point de contrôle local pour les TPU multipliée par 2,2
      • Taille du point de contrôle local pour les GPU avec un seul pair, multipliée par 6,6.
  2. Appliquez le fichier manifeste :

    kubectl apply -f checkpoint.yaml
    
  3. Vérifiez que le pilote CSI est en cours d'exécution :

    kubectl get pod -n gke-managed-checkpointing
    

    Le résultat devrait ressembler à ce qui suit. Il y aura plusieurs entrées, une par nœud accéléré.

    NAME                                                          READY   STATUS    RESTARTS   AGE
    multitier-driver-e2b033a7-a4e7-496a-87a3-ffd7fcc2e57b-2d4fz   5/5     Running   0          114s
    

Désinstaller le pilote CSI de point de contrôle multiniveau

Si vous souhaitez annuler le déploiement du pilote CSI Multi-Tier Checkpointing, supprimez la ressource CheckpointConfiguration. Le contrôleur de point de contrôle multiniveau supprime le pilote CSI des nœuds. Cela supprime les disques RAM et libère de la mémoire pour d'autres charges de travail. Exemple :

kubectl delete -f checkpoint.yaml

Gérer la conservation des données et la récupération de mémoire pour les sauvegardes Cloud Storage

Vous êtes responsable de la mise en œuvre des règles de conservation pour les sauvegardes Cloud Storage des points de contrôle. La création de points de contrôle multiniveau n'écrit que des sauvegardes de points de contrôle dans Cloud Storage, et ne les modifie ni ne les supprime jamais.

De nombreux outils Open Source peuvent gérer la conservation et la récupération de mémoire, y compris les suivants :

L'exemple suivant utilise backup-warden, où le répertoire backup est installé sur un emplacement de sauvegarde qui utilise Cloud Storage FUSE :

# Add --delete option to actually delete the backups, as is it only shows what would be deleted (dry-run)
backup-warden -p backup \
    --hourly 24 \
    --daily 7 \
    --weekly 5 \
    --monthly always \
    --yearly always \
    --prefer-recent

Mettre à jour le fichier manifeste JobSet de la charge de travail

Mettez à jour le fichier manifeste JobSet de votre job pour inclure le volume de point de contrôle à grande échelle. Les détails dépendent de votre charge de travail.

Par exemple, pour étendre l'exemple de JobSet de Déployer des TPU Multislice dans GKE, procédez comme suit :

  1. Ajoutez les lignes suivantes au conteneur jax-tpu.

    volumeMounts:
    - name: checkpoint
      mountPath: CHECKPOINT_DIR
    

    Remplacez CHECKPOINT_DIR par le chemin d'accès au répertoire de points de contrôle. Il s'agit de l'emplacement où le replicator.yaml est généré et où la fonctionnalité de point de contrôle à plusieurs niveaux effectue l'opération d'enregistrement du point de contrôle. Pour en savoir plus, consultez Intégrer les points de contrôle multiniveaux à votre application.

  2. Ajoutez les lignes suivantes au champ spec.template.spec de la spécification du job.

    volumes:
    - name: checkpoint
      csi:
        driver: multitier-checkpoint.csi.storage.gke.io
    

Intégrer les points de contrôle multiniveaux dans votre application

Pour partager des informations sur les emplacements des points de contrôle et l'état de préparation de la réplication, modifiez votre application pour qu'elle utilise le protocole suivant pour communiquer avec Multi-Tier Checkpointing.

Les frameworks et bibliothèques suivants implémentent déjà cette intégration :

  1. MaxText (avec Orbax) : MaxText est compatible de manière intégrée avec la création de points de contrôle multiniveau (MTC). Pour en savoir plus, consultez la documentation sur MaxText MTC.
  2. Tout modèle utilisant Orbax : l'intégration se compose de deux composants principaux : le module d'initialisation MTC pour la configuration initiale (par exemple, consultez MaxText) et le gestionnaire de points de contrôle du réplicateur pour enregistrer et restaurer des points de contrôle à partir d'un disque RAM local (par exemple, consultez MaxText).
  3. Exemple de référence PyTorch : cet exemple est disponible pour les charges de travail utilisant NeMo avec PyTorch.

Démarrage

Cette section décrit les étapes initiales que l'application doit suivre pour interagir avec les points de contrôle multiniveaux.

Le réplicateur est un composant essentiel de la création de points de contrôle multiniveaux, qui s'exécute sur chaque nœud dans le cadre du pilote CSI. Le réplicateur gère la réplication des points de contrôle entre les niveaux de stockage, du disque RAM local aux nœuds pairs et au stockage externe tel que Cloud Storage.

Le fichier replicator.yaml agit comme un plan de contrôle dynamique entre votre job d'entraînement de ML (code du framework) et le composant Replicator. Votre application de ML génère ce fichier de manière programmatique sur le volume local (RAMDisk), qui est accessible à la fois par le job d'entraînement et le service Replicator. Ce fichier manifeste permet au framework de ML de fournir des instructions de configuration d'exécution et de gestion du cycle de vie au réplicateur, distinctes des paramètres d'infrastructure statiques (par exemple, la fréquence d'importation Cloud Storage) définis lors de la configuration du backend.

Pour obtenir un exemple concret de cette interaction, consultez :

Votre application doit effectuer les étapes suivantes au démarrage :

  1. Attendez que le fichier replicator.yaml soit absent, ce qui indique que le réplicateur est prêt à être configuré par votre application. Le fichier replicator.yaml est généré à l'emplacement CHECKPOINT_DIR que vous avez configuré dans la section Mettre à jour le fichier manifeste JobSet de la charge de travail.

    Lors de la création du job d'entraînement du modèle, le fichier replicator.yaml n'existe pas et votre application peut continuer immédiatement. Toutefois, si le job a été redémarré (par exemple, en raison d'un échec ou d'une intervention manuelle), le système peut toujours traiter l'instance de job précédente, et le replicator.yaml de cette instance peut toujours être présent sur le volume local.

  2. Votre application ou votre job de ML crée le fichier replicator.yaml avec une configuration semblable à celle-ci.

    Orbax

    job-name: orbax
    framework: orbax
    assume-data-parallelism: 3
    node-rank: 0
    nodes: 32
    peer-ranks: [1, 16] or peers-per-node: 2
    backup-interval-minutes: 30
    

    PyTorch

    job-name: nemo
    framework: pytorch.distributed
    node-rank: 0
    nodes: 32
    peer-ranks: [1, 16] or peers-per-node: 2
    backup-interval-minutes: 30
    

    Cet exemple de configuration comporte les champs suivants :

    • name : nom du job d'entraînement.
    • framework : framework de ML utilisé par le job d'entraînement.
    • node-rank : identifiant unique du nœud actuel dans le job d'entraînement distribué. Il représente le rang du nœud qui crée ce fichier. Chaque nœud participant à l'exécution aura son propre rang.
    • nodes : nombre total de nœuds participant au job d'entraînement distribué. Cette valeur provient des métadonnées du pod. Le job d'entraînement de ML peut également afficher cette valeur.
    • peer-ranks ou peers-per-node : deux autres façons de spécifier la topologie de réplication. Un seul de ces deux paramètres doit être présent.
      • peer-ranks : rangs explicites des nœuds pairs vers lesquels les données de point de contrôle du nœud actuel doivent être répliquées. Cela permet de contrôler précisément les nœuds spécifiques qui servent de partenaires de réplication.
      • peers-per-node : nombre de nœuds pairs par nœud que le réplicateur doit sélectionner automatiquement pour la réplication.
    • backup-interval-minutes : fréquence, en minutes, à laquelle les points de contrôle sont sauvegardés dans Cloud Storage. Nous vous recommandons de définir cette valeur sur 30 minutes ou plus. Votre application peut également demander une sauvegarde d'un point de contrôle spécifique. Pour en savoir plus, consultez Demander une sauvegarde d'un point de contrôle spécifique.
  3. Attendez que le nouveau fichier replicator.yaml soit supprimé par le système. Cela indique que le réplicateur a redémarré et effectué le nettoyage. Cette étape vous permet d'éviter les fichiers obsolètes ou temporaires sur le volume local lorsque votre application effectue les étapes de la section suivante.

Restaurer à partir du dernier point de contrôle correct connu (LKG)

  1. Une fois le réplicateur initialisé, la fonctionnalité de point de contrôle multiniveau crée un fichier .restore par nœud de calcul TPU ou GPU. Ces fichiers sont créés dans le même volume local installé que le fichier replicator.yaml, où le job enregistre les points de contrôle.

    Les fichiers sont nommés JOB_NAME-sSTEP-nNODE_RANK-wWORKER_INDEX.restore. Le nom de fichier inclut les valeurs suivantes :

    • JOB_NAME : valeur du champ job-name dans le fichier replicator.yaml.
    • STEP : étape de point de contrôle à restaurer, ou 0 s'il n'y a pas de point de contrôle à restaurer.
    • NODE_RANK : valeur du champ node-rank dans le fichier replicator.yaml.
    • WORKER_INDEX : index du nœud de calcul TPU ou GPU sur le nœud.

    Chaque fichier est l'un des éléments suivants :

    • Un lien symbolique : la création de points de contrôle multiniveaux a trouvé un point de contrôle à restaurer. Le lien pointe vers les données du point de contrôle pour l'étape STEP.
    • Un fichier vide : Multi-Tier Checkpointing n'a trouvé aucun point de contrôle complet à restaurer, que ce soit dans le cluster ou dans Cloud Storage. Par exemple, cela se produit lors de la première exécution d'un job d'entraînement. Le nom de fichier utilise toujours l'étape 0. Le job doit commencer l'entraînement depuis le début.

    Étant donné qu'un point de contrôle enregistré à l'étape 0 produit également un nom de fichier avec -s0-, vérifiez si le fichier .restore est un lien symbolique ou un fichier vide au lieu de vous fier à l'étape dans le nom de fichier.

  2. Restaurez chaque nœud de calcul à partir du fichier .restore correspondant ou démarrez sans point de contrôle si le fichier est vide. Orbax gère les deux cas. Pour obtenir un exemple, consultez l'exemple de gestionnaire de points de contrôle répliqués Orbax dans la section suivante.

Par défaut, le point de contrôle LKG est le point de contrôle complet le plus récent que le point de contrôle multiniveau peut trouver. Les points de contrôle dans le cluster (sur le disque RAM local et sur les nœuds pairs) sont privilégiés, et les sauvegardes Cloud Storage ne sont utilisées que lorsqu'il n'existe aucun point de contrôle complet dans le cluster. Pour remplacer cette sélection, consultez Restaurer à partir d'une sauvegarde spécifique.

Restaurer à partir d'une sauvegarde spécifique

Vous pouvez restaurer un job à partir d'une sauvegarde Cloud Storage spécifique au lieu du point de contrôle LKG, par exemple pour restaurer l'entraînement à un état antérieur. Avant de lancer le job, procédez comme suit :

  1. Recherchez la sauvegarde à partir de laquelle effectuer la restauration. La fonctionnalité Multi-Tier Checkpointing écrit les sauvegardes dans le bucket que vous avez configuré dans CheckpointConfiguration, dans un répertoire nommé d'après le job. Chaque sauvegarde est un sous-répertoire nommé d'après l'heure UTC à laquelle la sauvegarde a été effectuée, au format YYYY-MM-DD_HH-MM :

    gcloud storage ls gs://GCS_PATH/JOB_NAME/
    

    Remplacez les éléments suivants :

    • GCS_PATH : chemin d'accès Cloud Storage où les points de contrôle multiniveaux écrivent les sauvegardes. Cette valeur correspond au bucket que vous avez spécifié dans le champ cloudStorageBucketName de CheckpointConfiguration, y compris tout répertoire du bucket.
    • JOB_NAME : nom du job d'entraînement, tel que spécifié dans le champ job-name du fichier replicator.yaml.
  2. Dans le répertoire du job du bucket, créez un fichier nommé restore.version. Le fichier ne doit contenir que le nom du répertoire de sauvegarde, par exemple :

    echo "BACKUP_NAME" | gcloud storage cp - gs://GCS_PATH/JOB_NAME/restore.version
    

    Remplacez BACKUP_NAME par le nom du répertoire de sauvegarde, par exemple 2025-06-30_14-30.

  3. Démarrez la tâche.

Lorsque le fichier restore.version est présent, les points de contrôle multiniveaux se comportent comme suit :

  • Tous les nœuds sont restaurés à partir de la sauvegarde spécifiée. Les points de contrôle dans le cluster sont ignorés, même s'ils sont plus récents que la sauvegarde.
  • Le fichier restore.version est automatiquement supprimé une fois que le job a enregistré son premier point de contrôle après la restauration. Le remplacement ne s'applique qu'une seule fois : si le job redémarre ultérieurement, il est restauré à partir du point de contrôle LKG, comme d'habitude.
  • Si la sauvegarde spécifiée n'existe pas ou est incomplète, la restauration échoue et le job s'arrête. La création de points de contrôle multiniveau ne revient pas aux points de contrôle dans le cluster ni à d'autres sauvegardes. Le réplicateur de chaque nœud écrit la raison de l'échec dans un fichier replicator.failed du répertoire CHECKPOINT_DIR et conserve les points de contrôle locaux. Le fichier restore.version n'est pas supprimé. Par conséquent, le job échoue à chaque redémarrage jusqu'à ce que vous corrigiez le nom de la sauvegarde dans le fichier restore.version ou que vous supprimiez le fichier.

Enregistrez le point de contrôle.

Votre application effectue ces étapes plusieurs fois au cours du job d'entraînement. Les opérations d'enregistrement ont lieu dans l'emplacement CHECKPOINT_DIR que vous avez configuré dans Mettre à jour le fichier manifeste JobSet de la charge de travail.

Orbax

Créer des points de contrôle Orbax Le répertoire est nommé d'après le numéro de l'étape. Le réplicateur détecte le répertoire de point de contrôle nouvellement créé, effectue la réplication ou la sauvegarde selon les besoins, puis effectue un nettoyage automatique.

Pour en savoir plus sur l'utilisation du gestionnaire de points de contrôle du réplicateur Orbax, consultez le fichier MaxText checkpointing. Pour voir un exemple d'interaction avec le service de réplication, consultez le fichier MaxText max_utils.

PyTorch

Utilisez InClusterLocalCheckpointIO comme pytorch_lightning.CheckpointIO personnalisé pour activer les points de contrôle distribués corrects avec le stockage local. L'exemple de commande suivant active les points de contrôle multiniveaux à l'aide d'une implémentation de référence basée sur le framework NVIDIA NeMo :

torchrun train.py <other_train_flags> \
    --local-ckpt-dir=CHECKPOINT_DIR \
    --local-ckpt-interval=20 \
    --job-name=JOB_NAME \
    --enable-high-scale-ckpt

Remplacez les éléments suivants :

  • CHECKPOINT_DIR : chemin d'accès au répertoire de votre point de contrôle.
  • JOB_NAME : nom de la charge de travail de votre job d'entraînement.

Demander une sauvegarde d'un point de contrôle spécifique

Par défaut, les points de contrôle multiniveaux sauvegardent les points de contrôle dans Cloud Storage à l'intervalle que vous avez défini dans le fichier replicator.yaml. Votre application peut également demander la sauvegarde d'un point de contrôle spécifique, quel que soit l'intervalle (par exemple, le point de contrôle à la fin d'une époque ou d'une phase d'entraînement).

Vous pouvez demander une sauvegarde lorsque vous écrivez un point de contrôle en créant un fichier vide nommé _BACKUP_REQUESTED directement dans le répertoire de l'étape du point de contrôle. Le fichier doit être présent dans le répertoire lorsqu'il devient visible pour le point de contrôle à plusieurs niveaux.

Ce comportement est compatible avec Orbax. Vous pouvez créer ce fichier automatiquement de l'une des manières suivantes :

  • Si vous utilisez Orbax directement : enregistrez le point de contrôle en appelant la méthode ReplicatorCheckpointManager.save(step, args, backup=True).
  • Si vous utilisez MaxText : appelez la fonction save_checkpoint(..., backup=True).

Lorsqu'un point de contrôle inclut le fichier _BACKUP_REQUESTED, la création de points de contrôle multiniveaux se comporte comme suit :

  • Le point de contrôle est sauvegardé dans Cloud Storage dès qu'il est répliqué, même si l'intervalle de sauvegarde n'est pas écoulé. L'intervalle de sauvegarde basé sur le temps redémarre ensuite à partir de cette sauvegarde.
  • Si la sauvegarde précédente est toujours en cours d'importation, la nouvelle requête est ignorée et une erreur est consignée. Assurez-vous que le délai entre les sauvegardes demandées est supérieur au temps nécessaire pour importer une sauvegarde.
  • Pour ne sauvegarder que les points de contrôle demandés, définissez un intervalle de sauvegarde supérieur à la durée d'exécution totale prévue de votre job.

Mise à niveau des clusters

Pour les mises à niveau de cluster, vous pouvez supprimer et recréer votre objet CheckpointConfiguration avant ou après la mise à niveau. Cette action est requise, car le daemonset du pilote de point de contrôle de nœud, déployé de manière dynamique par cet objet, ne sera pas mis à niveau automatiquement.

Si vous souhaitez conserver la même spécification de DaemonSet, vous n'avez rien à faire.

Résoudre les problèmes

Cette section fournit des conseils de dépannage pour résoudre les problèmes liés aux points de contrôle multiniveaux. Pour résoudre les problèmes de stockage généraux, consultez Résoudre les problèmes de Cloud Storage dans GKE.

La création de points de contrôle multiniveau n'est pas activée

L'erreur suivante indique que la création de points de contrôle multiniveau n'est pas activée sur votre cluster :

error: unable to recognize "checkpoint.yaml": no matches for kind "CheckpointConfiguration" in version "checkpointing.gke.io/v1"

Vous pouvez rencontrer cette erreur après avoir exécuté kubectl apply -f checkpoint.yaml à l'étape Créer une CheckpointConfiguration.

Pour résoudre ce problème, vérifiez si vous avez activé les points de contrôle multiniveaux sur votre cluster à l'aide de la commande suivante :

gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID
    --location CLUSTER_LOCATION

Si la création de points de contrôle multicouche est activée, le résultat doit ressembler à ceci :

addonsConfig:
  gcePersistentDiskCsiDriverConfig:
    enabled: true
  gcsFuseCsiDriverConfig:
    enabled: true
  highScaleCheckpointingConfig:
    enabled: true
  kubernetesDashboard:
    disabled: true
  networkPolicyConfig:
    disabled: true

Si la fonctionnalité de point de contrôle multiniveau n'est pas activée, mettez à jour votre cluster pour l'activer.

Le pilote CSI de Multi-Tier Checkpointing ne parvient pas à installer les volumes

Vous pouvez rencontrer ce problème si le pilote CSI ne parvient pas à installer le volume Cloud Storage. Il peut y avoir plusieurs lignes semblables à celle-ci.

kubectl get pod -n gke-managed-checkpointing
NAME                                                          READY   STATUS     RESTARTS   AGE
multitier-driver-14694e4d-774f-4104-8bba-f0bd82fd7557-5vxr9   0/5     Init:0/1   0          6m32s

Pour résoudre ce problème, vérifiez les événements de pod du pilote CSI, comme illustré dans l'exemple suivant :

kubectl describe pod multitier-driver-14694e4d-774f-4104-8bba-f0bd82fd7557-5vxr9 -n gke-managed-checkpointing

Events:
  Type     Reason       Age                 From               Message
  ----     ------       ----                ----               -------
  Normal   Scheduled    17m                 default-scheduler  Successfully assigned gke-managed-checkpointing/multitier-driver-14694e4d-774f-4104-8bba-f0bd82fd7557-5vxr9 to gke-my-cluster-default-pool-353c773f-6d8q
  Warning  FailedMount  82s (x16 over 17m)  kubelet            MountVolume.SetUp failed for volume "gcs" : rpc error: code = PermissionDenied desc = failed to get GCS bucket "checkpointing-test-bucket": googleapi: Error 403: Caller does not have storage.objects.list access to the Google Cloud Storage bucket. Permission 'storage.objects.list' denied on resource (or it may not exist)., forbidden

Si le problème est dû à l'erreur PermissionDenied du bucket Cloud Storage, comme illustré dans l'exemple, vous pouvez le résoudre en configurant correctement les autorisations.

Erreur : Aucun espace restant sur le dispositif

Si l'enregistrement des points de contrôle échoue avec une erreur No space left on device (avec Orbax, RESOURCE_EXHAUSTED ... os_error_code='28'), le disque RAM des points de contrôle multiniveaux est plein. Cette erreur est généralement due aux causes suivantes :

  • Le disque RAM est trop petit pour vos points de contrôle. L'erreur se produit lors des premiers enregistrements de points de contrôle après le démarrage du job, puis se reproduit après chaque redémarrage. Pour résoudre ce problème, augmentez la valeur inMemoryVolumeSize comme décrit dans Créer une CheckpointConfiguration, puis supprimez et recréez la CheckpointConfiguration lorsqu'aucun job d'entraînement n'est en cours d'exécution.

  • Un pod de pilote CSI a redémarré pendant l'exécution du job. Le job s'est exécuté normalement avant l'erreur. Lorsqu'un pod de pilote CSI redémarre, la réplication s'arrête sur tous les nœuds et les anciens points de contrôle ne sont plus supprimés. Le disque RAM se remplit et le job échoue. Ce comportement est intentionnel : avec un disque RAM correctement dimensionné, le job échoue après quelques enregistrements de points de contrôle au lieu de continuer sans réplication ni sauvegardes.

    Pour vérifier si un pod de pilote CSI a redémarré, exécutez la commande suivante :

    kubectl get pod -n gke-managed-checkpointing -l k8s-app=high-scale-checkpointing \
        -o custom-columns='NAME:.metadata.name,REPLICATOR_STARTED:.status.containerStatuses[?(@.name=="replication-worker")].state.running.startedAt'
    

    Le résultat ressemble à ce qui suit :

    NAME                                                          REPLICATOR_STARTED
    multitier-driver-fccd5b85-d40a-4194-b825-0e3d9e45ace3-24dxl   2026-11-12T22:53:55Z
    multitier-driver-fccd5b85-d40a-4194-b825-0e3d9e45ace3-fw58s   2026-11-10T00:24:46Z
    

    Si le code temporel REPLICATOR_STARTED d'un pod est postérieur au démarrage de votre job, cela signifie que l'outil de réplication sur ce nœud a redémarré pendant le job. Cette vérification couvre à la fois un pod de pilote CSI remplacé et un conteneur qui a redémarré dans le même pod.

    Pour résoudre ce problème, vérifiez si votre JobSet comporte un failurePolicy qui redémarre le job. Si c'est le cas, le job est automatiquement récupéré lorsqu'il redémarre, et il est restauré à partir du dernier point de contrôle du cluster. Si ce n'est pas le cas, envisagez d'ajouter un failurePolicy à votre JobSet et redémarrez le job manuellement. Si les pods du pilote CSI redémarrent de manière répétée, vérifiez les journaux du pod redémarré. Si vous avez besoin d'aide, contactez Cloud Customer Care.

Étapes suivantes