Exécuter du code Python colocalisé avec Pathways

Pour éviter de router les tâches liées à l'hôte, telles que le chargement des données et la création de points de contrôle, via un seul contrôleur Pathways sur Google Kubernetes Engine (GKE), exécutez ces fonctions sur vos VM de nœud de calcul Cloud TPU à l'aide de l'API Python colocalisée JAX.

Ce document, destiné aux ingénieurs en machine learning, décrit le fonctionnement de Python colocalisé avec Pathways. Vous allez apprendre à créer, déployer et vérifier un conteneur side-car avec un fichier manifeste JobSet ou Cluster Toolkit.

Avant de commencer

Remplissez les conditions préalables suivantes :

Rôles requis

Attribuez les rôles IAM (Identity and Access Management) suivants :

  • Votre compte utilisateur :
    • Rédacteur Artifact Registry (roles/artifactregistry.writer) sur votre projet Google Cloud pour transférer des images side-car personnalisées vers Artifact Registry.
    • Développeur Kubernetes Engine (roles/container.developer) sur votre projet Google Cloud pour déployer des ressources JobSet, transférer des ports et lire les journaux de pods sur GKE.
  • Compte de service du pool de nœuds GKE : les pods Pathways utilisent ce compte de service lorsque vos pools de nœuds utilisent l'option --workload-metadata=GCE_METADATA, comme configuré dans Créer un cluster GKE avec Pathways :
    • Lecteur Artifact Registry (roles/artifactregistry.reader) sur le projet Google Cloud qui héberge votre dépôt privé pour extraire des images side-car personnalisées.
    • Administrateur des objets Storage (roles/storage.objectAdmin) sur votre bucket de travail Cloud Storage pour le cache de compilation et d'autres fichiers temporaires.

Facultatif : Pour permettre au conteneur du gestionnaire de ressources Pathways (pathways-rm) d'ajouter une règle de cycle de vie de bucket qui fait expirer les anciennes entrées du cache de compilation, accordez également le rôle Administrateur de l'espace de stockage (roles/storage.admin) sur le bucket de travail. Sans ce rôle, le conteneur pathways-rm consigne un avertissement et continue d'utiliser le cache. Pour ignorer la mise à jour du cycle de vie, transmettez l'option --enable_gcs_olm=false au conteneur pathways-rm.

Si vos pools de nœuds utilisent Workload Identity Federation for GKE, accordez le rôle de bucket de travail au compte de service Kubernetes utilisé par les pods Pathways ou au compte de service IAM associé. Par défaut, les pods Pathways utilisent le compte de service default, sauf si votre fichier manifeste JobSet définit le champ serviceAccountName. Conservez le rôle de lecteur Artifact Registry sur le compte de service du pool de nœuds.

Fonctionnement de Python colocalisé avec Pathways

Dans Pathways, votre script de contrôleur JAX s'exécute sur un seul hôte de processeur, tandis que les pods de nœuds de calcul Cloud TPU exécutent le conteneur C++ pathways-worker. Pour exécuter des fonctions @colocated_python et des méthodes @colocated_python_class sur des hôtes de nœuds de calcul, Python colocalisé utilise les composants suivants :

  • Votre contrôleur JAX : utilise le module jax.experimental.colocated_python pour associer chaque puce Cloud TPU à un appareil CPU hôte, et sérialiser votre fonction Python et vos métadonnées de type avec la bibliothèque cloudpickle.
  • Le conteneur pathways-proxy (dans le pod pathways-head) : reçoit la fonction sérialisée via gRPC et l'achemine vers le conteneur pathways-worker sur les VM de nœud de calcul qui possèdent les appareils de processeur d'entrée de l'appel. L'option --sidecar_name=external configure le conteneur pathways-proxy pour cibler le conteneur colocated-python-sidecar.
  • Le conteneur pathways-worker (sur chaque pod de nœud de calcul) : charge la fonction sérialisée dans le conteneur side-car local, déclenche l'exécution sur gRPC local et échange des tampons de tableau via un volume emptyDir en mémoire partagé (medium: Memory).
  • Le conteneur colocated-python-sidecar (sur chaque pod de nœud de calcul) : décompresse et exécute la fonction dans un environnement d'exécution Python 3.12 isolé une fois par VM sur les segments locaux de cette VM, en écrivant les tableaux de sortie directement dans la mémoire de l'hôte partagé.

Pour en savoir plus sur l'architecture Pathways, consultez Composants Pathways.

Flux d'exécution

Lorsque vous appelez une fonction décorée, Pathways l'exécute sur votre cluster en deux étapes :

  1. Routage des fonctions : le module jax.experimental.colocated_python empaquette la fonction dans un programme Interim Framework Runtime (IFRT) et l'envoie au conteneur pathways-proxy. Le proxy ne transfère le programme qu'aux VM de nœud de calcul contenant les segments d'entrée, et s'exécute une fois par VM sur tous les segments locaux.
  2. Exécution en mémoire partagée : le conteneur pathways-worker écrit des segments d'entrée dans le volume partagé en mémoire (/tmp/sidecar ou /tmp/shared-memory) et appelle le conteneur colocated-python-sidecar via TCP en boucle (localhost:50051) ou un socket de domaine Unix (/sock/sidecar.sock). Les tableaux de sortie sont renvoyés via la mémoire partagée sans copies gRPC et sont déplacés directement dans la mémoire à haut débit (HBM) de Cloud TPU lorsqu'ils sont placés sur des appareils Cloud TPU.

Pour en savoir plus sur l'utilisation de l'API JAX, par exemple pour découvrir les appareils CPU colocalisés et déclarer des spécifications de sortie pour l'envoi asynchrone, consultez le guide Python colocalisé JAX.

Principes de conception

Lorsque vous écrivez des fonctions Python colocalisées, suivez ces consignes :

  • Réduire les variables capturées : transmettez les données de tableau en tant qu'arguments jax.Array segmentés plutôt que de capturer de grands tableaux ou des objets non sérialisables (tels que des fichiers ouverts ou des clients réseau) dans des fermetures. Ouvrez des fichiers ou des clients dans une instance @colocated_python_class sur le nœud de calcul.
  • Recréer l'état @colocated_python_class après les redémarrages : les objets side-car avec état sont conservés en mémoire d'une étape à l'autre, mais ne sont pas enregistrés automatiquement si un pod de nœud de calcul redémarre ou si le nombre de tranches change pendant l'entraînement élastique. Recréez des objets avec état à partir d'un point de contrôle après un redimensionnement ou un redémarrage.

Images et tags prédéfinis

Google Cloud publie des images Pathways prédéfinies dans un dépôt Artifact Registry public :

  • Side-car Python colocalisé : us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Gestionnaire de ressources et nœud de calcul Pathways : us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • Serveur proxy IFRT : us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

Utilisez des tags correspondants dans les images server, proxy_server et colocated_python_sidecar.

Les images side-car prédéfinies sont compatibles avec les versions de JAX 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0 et 0.12.0.1. Remplacez TAG par l'un des formats de tag suivants :

  • jax-JAX_VERSION (recommandé) : tag de version pour une version JAX spécifique, telle que jax-0.12.0.1.
  • YYYYMMDD-jax_JAX_VERSION : tag de compilation horodaté, tel que 20261110-jax_0.12.0.1.

Si vous avez besoin d'une version d'image exacte qui ne change jamais, épinglez l'image par son condensé SHA-256. Pour rechercher un condensé d'image, utilisez la commande gcloud artifacts docker images describe :

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
gcloud artifacts docker images describe \
    "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
    --format="value(image_summary.digest)"

Remplacez JAX_VERSION par votre version de JAX, par exemple 0.12.0.1.

Créer une image side-car personnalisée

L'image side-car prédéfinie inclut les packages jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle et absl-py. Si vos fonctions Python colocalisées n'utilisent que ces packages, passez à Déployer un JobSet Pathways avec le side-car ou Déployer avec Cluster Toolkit.

Pour ajouter des dépendances Python personnalisées, superposez-les sur l'image prédéfinie correspondant à votre version de JAX :

  1. Dans un répertoire de compilation vide, créez un fichier requirements.txt pour vos packages supplémentaires. Omettez les packages jax et jaxlib, qui sont déjà installés et épinglés dans le fichier /opt/venv/server_constraints.txt :

    grain
    
  2. Créez un fichier Dockerfile qui installe les packages du fichier requirements.txt, en respectant les contraintes du fichier /opt/venv/server_constraints.txt :

    ARG JAX_VERSION=0.12.0.1
    ARG IMAGE_REPO=us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways
    FROM ${IMAGE_REPO}/colocated_python_sidecar:jax-${JAX_VERSION}
    
    WORKDIR /app
    COPY requirements.txt .
    
    RUN uv pip install -r requirements.txt \
            -c /opt/venv/server_constraints.txt && \
        uv cache clean
    

    Conservez les instructions ENTRYPOINT et CMD de l'image de base sans les modifier. Si le fichier requirements.txt installe des packages à partir d'URL Git, ajoutez l'instruction RUN suivante avant l'instruction uv pip install RUN, car l'image de base slim omet l'outil git :

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Authentifiez Docker auprès de votre région Artifact Registry à l'aide de la commande gcloud auth configure-docker :

    gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.dev
    

    Remplacez REGISTRY_LOCATION par l'emplacement de votre dépôt Artifact Registry, par exemple us ou us-central1.

  4. Créez et transférez votre image side-car personnalisée :

    export JAX_VERSION=JAX_VERSION
    IMAGE_PREFIX=REGISTRY_LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY
    export SIDECAR_IMAGE="${IMAGE_PREFIX}/colocated-sidecar:jax-${JAX_VERSION}"
    
    docker build --build-arg JAX_VERSION="${JAX_VERSION}" \
        --tag "${SIDECAR_IMAGE}" .
    docker push "${SIDECAR_IMAGE}"
    

    Remplacez les éléments suivants :

    • JAX_VERSION : votre version de JAX, par exemple 0.12.0.1.
    • REGISTRY_LOCATION : votre emplacement Artifact Registry, par exemple us ou us-central1.
    • PROJECT_ID : ID de votre projetGoogle Cloud .
    • REPOSITORY : nom de votre dépôt Docker Artifact Registry.

Déployer un JobSet Pathways avec le side-car

Vous pouvez déployer Pathways avec le side-car en appliquant un fichier manifeste JobSet avec l'outil de ligne de commande kubectl dans cette section, ou en envoyant le job directement avec la CLI gcluster dans Déployer avec Cluster Toolkit.

Pour générer et appliquer un fichier manifeste JobSet, procédez comme suit :

  1. Générez un fichier manifeste JobSet (pathways-colocated-jobset.yaml) à l'aide de l'un des outils suivants :

    • Le compilateur Python pathways-utils : configurez un JobSet avec le compilateur PathwaysJobSet en appelant les méthodes .add_colocated_python("SIDECAR_IMAGE") et .export_yaml("pathways-colocated-jobset.yaml"). Si vous utilisez le package pathwaysutils (version 0.1.14 ou antérieure de PyPI), transmettez également l'argument proxy_container_kwargs={"args": ["--sidecar_name=external"]} au constructeur PathwaysJobSet ou installez le package pathways-utils à partir de la branche main.
    • Cluster Toolkit (gcluster) : exécutez la commande gcluster job submit avec l'option --pathways-colocated-python-sidecar-image et ajoutez l'option --dry-run-out=pathways-colocated-jobset.yaml pour afficher le fichier manifeste localement sans envoyer le job.

    Remplacez SIDECAR_IMAGE par l'URI de votre image side-car personnalisée ou par l'URI de l'image prédéfinie colocated_python_sidecar.

    Les deux générateurs configurent le fichier manifeste pour effectuer les opérations suivantes :

    • Exécutez le conteneur colocated-python-sidecar sous le champ initContainers avec restartPolicy: Always dans chaque pod de nœud de calcul. La CLI gcluster nomme le job répliqué du nœud de calcul worker, tandis que le compilateur PathwaysJobSet le nomme pathways-worker.
    • Transmettez l'option --sidecar_name=external au conteneur pathways-proxy et connectez le conteneur pathways-worker au side-car via le protocole TCP de bouclage sur localhost:50051. Lorsque le conteneur pathways-proxy s'exécute sous le champ initContainers, il utilise également restartPolicy: Always.
    • Installez un volume emptyDir en mémoire avec medium: Memory dans les deux conteneurs de pod de nœud de calcul : à /tmp/sidecar dans les fichiers manifestes gcluster ou à /tmp/shared-memory dans les fichiers manifestes PathwaysJobSet. Les deux générateurs définissent également la variable d'environnement CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY sur le side-car et l'option --cloud_pathways_sidecar_shm_directory sur le conteneur pathways-worker.
  2. Appliquez le fichier manifeste JobSet et attendez que les pods atteignent l'état Running :

    kubectl apply -f pathways-colocated-jobset.yaml
    kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAME
    

    Remplacez JOBSET_NAME par la valeur metadata.name de votre JobSet.

Exécutez une session client JAX par déploiement JobSet. Après la déconnexion d'un client, un conteneur pathways-worker redémarré ne peut pas réutiliser un side-car en cours d'exécution. Supprimez et recréez le JobSet avant de démarrer une autre session.

Les fichiers d'un volume emptyDir en mémoire sont comptabilisés dans l'utilisation de la mémoire du pod. Définissez le champ emptyDir.sizeLimit (par exemple, 175Gi) sur le volume de mémoire partagée pour limiter l'utilisation par nœud. Par défaut, les deux conteneurs conservent la mémoire partagée libérée pendant 30 secondes d'inactivité pour la réutiliser. Pour modifier cette fenêtre, définissez à la fois l'option --pathways_sidecar_shared_memory_idle_release_secs=SECONDS dans le champ args du conteneur colocated-python-sidecar (avec l'option --port=50051 ou --unix_domain_socket_path) et l'option --cloud_pathways_shared_memory_idle_release_secs=SECONDS dans le champ args du conteneur pathways-worker. Remplacez SECONDS par le délai d'inactivité en secondes. La définition des deux options sur 0 libère les pages libérées en environ une seconde, ce qui réduit l'utilisation de la mémoire au détriment d'une surcharge d'allocation supplémentaire.

Facultatif : Utiliser un socket de domaine Unix

Pour utiliser un socket de domaine Unix (UDS) sur /sock/sidecar.sock au lieu d'ouvrir un port TCP sur les pods de calcul qui définissent hostNetwork: true, appliquez les remplacements suivants à votre fichier manifeste JobSet avant d'exécuter la commande kubectl apply :

  • Installez un volume emptyDir: {} nommé sidecar-socket sur /sock dans les conteneurs pathways-worker et colocated-python-sidecar.
  • Définissez args: ["--unix_domain_socket_path=/sock/sidecar.sock"] et un exec startupProbe (test -S /sock/sidecar.sock) sur le conteneur colocated-python-sidecar.
  • Ajoutez l'option --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock au champ args du conteneur pathways-proxy.

Déployer avec Cluster Toolkit

Dans Cluster Toolkit (gcluster version 1.108.0 ou ultérieure), transmettre l'option --pathways-colocated-python-sidecar-image à la commande gcluster job submit configure le conteneur colocated-python-sidecar sur TCP en boucle (localhost:50051), installe le volume en mémoire sur /tmp/sidecar et définit l'option --sidecar_name=external. Transmettez explicitement les options --pathways-server-image et --pathways-proxy-server-image afin que les trois images utilisent des tags cloud-pathways correspondants.

Envoyez un déploiement Pathways sans interface graphique avec votre image side-car afin de pouvoir exécuter des scripts client interactifs sur celle-ci :

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"

gcluster job submit \
    --pathways \
    --pathways-headless \
    --pathways-gcs-location="gs://BUCKET_NAME/pathways-artifacts" \
    --pathways-server-image="${IMAGE_REPO}/server:jax-JAX_VERSION" \
    --pathways-proxy-server-image="${IMAGE_REPO}/proxy_server:jax-JAX_VERSION" \
    --pathways-colocated-python-sidecar-image="SIDECAR_IMAGE" \
    --name=WORKLOAD \
    --cluster=CLUSTER \
    --project=PROJECT_ID \
    --location=LOCATION \
    --num-slices=WORKLOAD_NODEPOOL_COUNT \
    --compute-type=COMPUTE_TYPE \
    --topology=TOPOLOGY

Remplacez les éléments suivants :

  • BUCKET_NAME : votre bucket de travail Cloud Storage.
  • JAX_VERSION : votre version de JAX, par exemple 0.12.0.1.
  • SIDECAR_IMAGE : URI de votre image side-car personnalisée ou prédéfinie.
  • WORKLOAD : nom JobSet unique (22 caractères maximum).
  • CLUSTER : nom de votre cluster GKE.
  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région ou zone de votre cluster GKE.
  • WORKLOAD_NODEPOOL_COUNT : nombre de tranches Cloud TPU, par exemple 1.
  • COMPUTE_TYPE : type de machine Cloud TPU, tel que ct5lp-hightpu-4t ou ct6e-standard-4t.
  • TOPOLOGY : topologie de la tranche Cloud TPU, par exemple 4x8 ou 2x4.

Vous pouvez également personnaliser la façon dont la commande gcluster job submit exécute ou exporte le job :

  • Charges de travail par lot : pour exécuter un job par lot conteneurisé dans le pod pathways-head au lieu d'un déploiement sans interface graphique, remplacez l'option --pathways-headless par les options --image="CLIENT_IMAGE" et --command="COMMAND". Utilisez une image de client JAX Python 3.12 créée avec des épingles server_constraints.txt et transmettez votre commande d'entrée (par exemple, python colocated_example.py).
  • Affichage du fichier manifeste local : ajoutez l'option --dry-run-out=pathways-colocated-jobset.yaml pour afficher le fichier manifeste JobSet localement sans l'envoyer.
  • Sessions sans interface graphique suivantes : exécutez la commande gcluster job cancel et renvoyez le job avant de démarrer une autre session client.

Exécuter une charge de travail Python colocalisée

Exécutez votre script client JAX avec la variable d'environnement JAX_PLATFORMS=proxy sur le conteneur pathways-proxy, soit dans le conteneur de charge de travail pathways-head, soit via le transfert de port :

  1. Pour aligner les dépendances de sérialisation avec votre image side-car, extrayez le fichier /opt/venv/server_constraints.txt et installez les packages correspondants dans un environnement virtuel Python 3.12 :

    IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
    docker run --rm --entrypoint cat \
        "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
        /opt/venv/server_constraints.txt > constraints.txt
    python3.12 -m venv .venv
    source .venv/bin/activate
    python -m pip install -c constraints.txt \
        jax jaxlib cloudpickle pathwaysutils
    

    Remplacez JAX_VERSION par votre version de JAX, par exemple 0.12.0.1.

  2. Si vous exécutez le client en dehors du pod pathways-head, transférez le port local 29000 vers le conteneur pathways-proxy dans un terminal distinct :

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=pathways-head"
    HEAD_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl port-forward "${HEAD_POD}" 29000:29000
    

    Remplacez JOBSET_NAME par la valeur metadata.name de votre JobSet (ou le nom WORKLOAD que vous avez transmis à la commande gcluster job submit).

  3. Enregistrez le script suivant sous le nom colocated_example.py. Ce script alloue un tableau NumPy de 4 Mio dans la mémoire de l'hôte partagé sur l'appareil CPU colocalisé de chaque nœud de calcul Cloud TPU et le transfère vers Cloud TPU HBM :

    import jax
    from jax.experimental import colocated_python
    import numpy as np
    import pathwaysutils
    
    pathwaysutils.initialize()
    
    @colocated_python.colocated_python
    def make_host_array(seed_arr: jax.Array) -> jax.Array:
      host_array = np.full(
          (1024, 1024), fill_value=float(seed_arr), dtype=np.float32
      )
      return jax.device_put(host_array, seed_arr.device)
    
    tpu_devices = jax.devices()
    cpu_devices = colocated_python.colocated_cpu_devices(tpu_devices)
    print(
        f"TPU devices: {len(tpu_devices)}, "
        f"colocated CPU devices: {len(cpu_devices)}"
    )
    
    host_arrays = [
        make_host_array(jax.device_put(np.int32(i + 1), cpu_dev))
        for i, cpu_dev in enumerate(cpu_devices)
    ]
    tpu_arrays = [
        jax.device_put(host_arr, tpu_dev)
        for host_arr, tpu_dev in zip(host_arrays, tpu_devices)
    ]
    for arr in tpu_arrays:
      arr.block_until_ready()
    
    print(
        f"Transferred {len(tpu_arrays)} arrays of shape {tpu_arrays[0].shape} "
        f"to TPU HBM; sample sum={float(tpu_arrays[0].sum()):.1f}"
    )
    
  4. Exécutez le script sur le serveur proxy IFRT :

    JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \
        python colocated_example.py
    

    Le résultat ressemble à ce qui suit :

    TPU devices: 8, colocated CPU devices: 8
    Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0
    

    Dans les charges de travail de production multitranches, transmettez un argument jax.Array segmenté placé sur les appareils renvoyés par l'appel colocated_python.colocated_cpu_devices(mesh) et définissez le paramètre out_specs_fn avec la méthode .specialize(out_specs_fn=...) afin que Pathways exécute un appel parallèle sur tous les side-cars de nœuds de calcul sans attendre.

    N'exécutez pas de scripts client dans un pod worker avec la variable d'environnement JAX_PLATFORMS=cpu, car ce paramètre exécute JAX localement sur un processeur et contourne Pathways. Vous pouvez ignorer tout message IFRT proxy server disconnected: CANCELLED affiché à la sortie.

Pour en savoir plus sur les modèles d'utilisation, consultez les ressources suivantes :

Vérifier le déploiement du side-car

Exécutez la commande kubectl logs sur un JobSet sans interface graphique avant de l'annuler ou de le supprimer, ou pendant qu'une charge de travail par lot est toujours en cours d'exécution. Dans les déploiements par lot JobSet, le contrôleur JobSet supprime les pods worker dès que le job pathways-head est terminé. Affichez plutôt les journaux des lots terminés dans Cloud Logging, comme décrit dans Résoudre les problèmes liés à Pathways sur Cloud.

Pour vérifier un déploiement en cours d'exécution avec l'outil de ligne de commande kubectl, procédez comme suit :

  1. Inspectez les journaux du conteneur colocated-python-sidecar :

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=worker"
    WORKER_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl logs "${WORKER_POD}" -c colocated-python-sidecar
    

    Remplacez JOBSET_NAME par la valeur metadata.name de votre JobSet (ou le nom WORKLOAD que vous avez transmis à la commande gcluster job submit). Si vous avez généré votre fichier manifeste avec le compilateur PathwaysJobSet, définissez replicatedjob-name=pathways-worker dans la variable ROLE_LABEL.

    Le résultat ressemble à ce qui suit :

    Started SidecarGrpcServer on localhost:50051
    ...
    SidecarServer agreed on protocol version: 6
    Installed shared memory allocator for colocated Python using file /tmp/sidecar/pathways_shm_sidecar
    

    Vérifiez que la sortie affiche le message de démarrage gRPC et, après le premier appel @colocated_python, le message de l'allocateur de mémoire partagée. Les fichiers manifestes générés avec le compilateur PathwaysJobSet utilisent le répertoire /tmp/shared-memory, et les déploiements UDS enregistrent unix:/sock/sidecar.sock au lieu de localhost:50051.

  2. Inspectez les journaux du conteneur pathways-worker sur le même pod :

    kubectl logs "${WORKER_POD}" -c pathways-worker \
        | grep -iE "shared memory|external sidecar"
    

    Le résultat ressemble à ce qui suit :

    Enabled shared memory for external sidecar in /tmp/sidecar
    External sidecar connected to backing GRPC sidecar at localhost:50051
    

    Vérifiez que le conteneur pathways-worker a activé la mémoire partagée et qu'il est connecté au side-car.

Lorsque vous exécutez la commande kubectl exec pour inspecter le répertoire de mémoire partagée, ciblez le conteneur colocated-python-sidecar avec l'option -c colocated-python-sidecar, car le conteneur pathways-worker n'inclut pas de shell.

Résoudre les problèmes liés à Python colocalisé

Les sections suivantes décrivent comment résoudre les problèmes courants liés à Python colocalisé.

Unable to unpickle erreur

Si votre charge de travail échoue avec l'erreur suivante, les versions de Python ou des packages diffèrent entre votre client JAX et le conteneur side-car :

jax.errors.JaxRuntimeError: UNKNOWN: Unable to unpickle the callable and specialization

Vérifiez que votre client exécute Python 3.12 (python --version) et installez les packages client avec l'option -c constraints.txt extraite de l'image side-car. Pour en savoir plus, consultez Exécuter une charge de travail Python colocalisée.

Conflit de dépendance lors d'une exécution docker build

Si la commande uv pip install échoue avec l'erreur No solution found when resolving dependencies, une épingle de votre fichier requirements.txt est en conflit avec le fichier /opt/venv/server_constraints.txt. Supprimez les packages jax et jaxlib du fichier requirements.txt et assouplissez les épinglages de version sur les packages tels que numpy, ml-dtypes ou scipy.

Erreur "Sidecar non activé"

Si le conteneur pathways-proxy se ferme avec l'erreur Sidecar create args were set, but sidecar was not enabled, ajoutez l'option --sidecar_name=external au champ args du conteneur pathways-proxy.

Sidecar already initialized erreur

Si votre charge de travail échoue avec l'erreur FAILED_PRECONDITION: Sidecar already initialized, une déconnexion client antérieure a redémarré le conteneur pathways-worker alors que le conteneur colocated-python-sidecar est resté initialisé. Supprimez et recréez le JobSet avant de démarrer une autre session client.

Erreurs de connexion à la mémoire partagée ou au side-car

Utilisez les vérifications suivantes pour résoudre les erreurs de montage de mémoire partagée, de connexion gRPC ou de mémoire hôte :

  • Failed to stat sidecar_shm_directory : installez le volume de mémoire partagée emptyDir sur le chemin d'accès correspondant (/tmp/sidecar ou /tmp/shared-memory) dans les conteneurs pathways-worker et colocated-python-sidecar.
  • Timed out connecting to sidecar gRPC service ou Failed to connect to external sidecar : vérifiez que le conteneur colocated-python-sidecar s'exécute sous le champ initContainers avec restartPolicy: Always et que les trois images cloud-pathways utilisent des tags correspondants. Vérifiez que vos paramètres TCP (--port=50051) ou UDS (volume /sock et --unix_domain_socket_path=/sock/sidecar.sock) correspondent entre les conteneurs pathways-proxy et colocated-python-sidecar.
  • Mémoire insuffisante sur l'hôte de nœud de calcul après des pics de tableaux volumineux : définissez l'option --pathways_sidecar_shared_memory_idle_release_secs=0 sur le conteneur colocated-python-sidecar (avec l'option --port=50051 ou --unix_domain_socket_path) et l'option --cloud_pathways_shared_memory_idle_release_secs=0 sur le conteneur pathways-worker. Définir les deux options sur 0 libère la mémoire partagée inutilisée en une seconde environ. Vous pouvez également réduire la quantité maximale de données de tableau hôte que votre charge de travail conserve en mémoire à un moment donné.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce document ne soient facturées sur votre compte Google Cloud , supprimez votre déploiement et vos artefacts temporaires lorsque vous avez terminé :

  • Fichier manifeste JobSet : supprimez la ressource JobSet :

    kubectl delete jobset JOBSET_NAME
    

    Remplacez JOBSET_NAME par la valeur metadata.name de votre JobSet.

  • Cluster Toolkit : annulez le job déployé :

    gcluster job cancel WORKLOAD \
        --cluster=CLUSTER \
        --project=PROJECT_ID \
        --location=LOCATION
    

    Remplacez les éléments suivants :

    • WORKLOAD : nom de votre job Pathways.
    • CLUSTER : nom de votre cluster GKE.
    • PROJECT_ID : ID de votre projetGoogle Cloud .
    • LOCATION : région ou zone de votre cluster GKE.

Facultatif : Supprimez toutes les images side-car personnalisées dans Artifact Registry et supprimez les objets temporaires de votre bucket de travail Cloud Storage. Lorsque vous n'avez plus besoin de votre cluster GKE, supprimez-le en suivant les étapes de nettoyage de la section Créer un cluster GKE avec Pathways.

Étapes suivantes