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 :
- Créer un cluster GKE avec Pathways
- Installez l'outil de ligne de commande
kubectlet le plug-ingke-gcloud-auth-plugin. - Installez la Google Cloud CLI.
- Installez Docker.
- Activez l'API Kubernetes Engine et l'API Artifact Registry.
- Créez un bucket de travail Cloud Storage pour les fichiers temporaires Pathways.
- Si vous prévoyez de créer une image side-car personnalisée, créez un dépôt Docker Artifact Registry.
- Installez Python 3.12 dans l'environnement client qui exécute votre charge de travail JAX.
- Facultatif : Pour déployer avec Cluster Toolkit, installez la version 1.108.0 ou ultérieure de la CLI
gcluster.
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 ressourcesJobSet, transférer des ports et lire les journaux de pods sur GKE.
- Rédacteur Artifact Registry (
- 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.
- Lecteur Artifact Registry (
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_pythonpour 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èquecloudpickle. - Le conteneur
pathways-proxy(dans le podpathways-head) : reçoit la fonction sérialisée via gRPC et l'achemine vers le conteneurpathways-workersur les VM de nœud de calcul qui possèdent les appareils de processeur d'entrée de l'appel. L'option--sidecar_name=externalconfigure le conteneurpathways-proxypour cibler le conteneurcolocated-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 volumeemptyDiren 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 :
- Routage des fonctions : le module
jax.experimental.colocated_pythonempaquette la fonction dans un programme Interim Framework Runtime (IFRT) et l'envoie au conteneurpathways-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. - 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/sidecarou/tmp/shared-memory) et appelle le conteneurcolocated-python-sidecarvia 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.Arraysegmenté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_classsur le nœud de calcul. - Recréer l'état
@colocated_python_classaprè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 quejax-0.12.0.1.YYYYMMDD-jax_JAX_VERSION: tag de compilation horodaté, tel que20261110-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 :
Dans un répertoire de compilation vide, créez un fichier
requirements.txtpour vos packages supplémentaires. Omettez les packagesjaxetjaxlib, qui sont déjà installés et épinglés dans le fichier/opt/venv/server_constraints.txt:grainCréez un fichier
Dockerfilequi installe les packages du fichierrequirements.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 cleanConservez les instructions
ENTRYPOINTetCMDde l'image de base sans les modifier. Si le fichierrequirements.txtinstalle des packages à partir d'URL Git, ajoutez l'instructionRUNsuivante avant l'instructionuv pip installRUN, car l'image de base slim omet l'outilgit:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*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.devRemplacez
REGISTRY_LOCATIONpar l'emplacement de votre dépôt Artifact Registry, par exempleusouus-central1.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 exemple0.12.0.1.REGISTRY_LOCATION: votre emplacement Artifact Registry, par exempleusouus-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 :
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 unJobSetavec le compilateurPathwaysJobSeten appelant les méthodes.add_colocated_python("SIDECAR_IMAGE")et.export_yaml("pathways-colocated-jobset.yaml"). Si vous utilisez le packagepathwaysutils(version0.1.14ou antérieure de PyPI), transmettez également l'argumentproxy_container_kwargs={"args": ["--sidecar_name=external"]}au constructeurPathwaysJobSetou installez le packagepathways-utilsà partir de la branchemain. - Cluster Toolkit (
gcluster) : exécutez la commandegcluster job submitavec l'option--pathways-colocated-python-sidecar-imageet ajoutez l'option--dry-run-out=pathways-colocated-jobset.yamlpour afficher le fichier manifeste localement sans envoyer le job.
Remplacez
SIDECAR_IMAGEpar l'URI de votre image side-car personnalisée ou par l'URI de l'image prédéfiniecolocated_python_sidecar.Les deux générateurs configurent le fichier manifeste pour effectuer les opérations suivantes :
- Exécutez le conteneur
colocated-python-sidecarsous le champinitContainersavecrestartPolicy: Alwaysdans chaque pod de nœud de calcul. La CLIgclusternomme le job répliqué du nœud de calculworker, tandis que le compilateurPathwaysJobSetle nommepathways-worker. - Transmettez l'option
--sidecar_name=externalau conteneurpathways-proxyet connectez le conteneurpathways-workerau side-car via le protocole TCP de bouclage surlocalhost:50051. Lorsque le conteneurpathways-proxys'exécute sous le champinitContainers, il utilise égalementrestartPolicy: Always. - Installez un volume
emptyDiren mémoire avecmedium: Memorydans les deux conteneurs de pod de nœud de calcul : à/tmp/sidecardans les fichiers manifestesgclusterou à/tmp/shared-memorydans les fichiers manifestesPathwaysJobSet. Les deux générateurs définissent également la variable d'environnementCLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORYsur le side-car et l'option--cloud_pathways_sidecar_shm_directorysur le conteneurpathways-worker.
- Le compilateur Python
Appliquez le fichier manifeste
JobSetet attendez que les pods atteignent l'étatRunning:kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAMERemplacez
JOBSET_NAMEpar la valeurmetadata.namede votreJobSet.
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-socketsur/sockdans les conteneurspathways-workeretcolocated-python-sidecar. - Définissez
args: ["--unix_domain_socket_path=/sock/sidecar.sock"]et unexecstartupProbe(test -S /sock/sidecar.sock) sur le conteneurcolocated-python-sidecar. - Ajoutez l'option
--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sockau champargsdu conteneurpathways-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 exemple0.12.0.1.SIDECAR_IMAGE: URI de votre image side-car personnalisée ou prédéfinie.WORKLOAD: nomJobSetunique (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 exemple1.COMPUTE_TYPE: type de machine Cloud TPU, tel quect5lp-hightpu-4touct6e-standard-4t.TOPOLOGY: topologie de la tranche Cloud TPU, par exemple4x8ou2x4.
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-headau lieu d'un déploiement sans interface graphique, remplacez l'option--pathways-headlesspar les options--image="CLIENT_IMAGE"et--command="COMMAND". Utilisez une image de client JAX Python 3.12 créée avec des épinglesserver_constraints.txtet 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.yamlpour afficher le fichier manifesteJobSetlocalement sans l'envoyer. - Sessions sans interface graphique suivantes : exécutez la commande
gcluster job cancelet 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 :
Pour aligner les dépendances de sérialisation avec votre image side-car, extrayez le fichier
/opt/venv/server_constraints.txtet 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 pathwaysutilsRemplacez
JAX_VERSIONpar votre version de JAX, par exemple0.12.0.1.Si vous exécutez le client en dehors du pod
pathways-head, transférez le port local29000vers le conteneurpathways-proxydans 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:29000Remplacez
JOBSET_NAMEpar la valeurmetadata.namede votreJobSet(ou le nomWORKLOADque vous avez transmis à la commandegcluster job submit).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}" )Exécutez le script sur le serveur proxy IFRT :
JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \ python colocated_example.pyLe 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.0Dans les charges de travail de production multitranches, transmettez un argument
jax.Arraysegmenté placé sur les appareils renvoyés par l'appelcolocated_python.colocated_cpu_devices(mesh)et définissez le paramètreout_specs_fnavec 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
workeravec la variable d'environnementJAX_PLATFORMS=cpu, car ce paramètre exécute JAX localement sur un processeur et contourne Pathways. Vous pouvez ignorer tout messageIFRT proxy server disconnected: CANCELLEDaffiché à la sortie.
Pour en savoir plus sur les modèles d'utilisation, consultez les ressources suivantes :
- Notebook Python colocalisé JAX : spécialisation des fonctions et objets
@colocated_python_classavec état - Module MaxText
multihost_dataloading.py: pipeline d'entrée multi-hôteRemoteIteratorqui utilise Python colocalisé - Points de contrôle Orbax Pathways et Points de contrôle multiniveaux avec Pathways : points de contrôle distribués sur les side-cars de nœuds de calcul avec l'appel
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)(ou le paramètrecolocated_python_checkpointing=Truedans MaxText) et l'optionuse_colocated_python=Truepour les points de contrôle multiniveaux.
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 :
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-sidecarRemplacez
JOBSET_NAMEpar la valeurmetadata.namede votreJobSet(ou le nomWORKLOADque vous avez transmis à la commandegcluster job submit). Si vous avez généré votre fichier manifeste avec le compilateurPathwaysJobSet, définissezreplicatedjob-name=pathways-workerdans la variableROLE_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_sidecarVé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 compilateurPathwaysJobSetutilisent le répertoire/tmp/shared-memory, et les déploiements UDS enregistrentunix:/sock/sidecar.sockau lieu delocalhost:50051.Inspectez les journaux du conteneur
pathways-workersur 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:50051Vérifiez que le conteneur
pathways-workera 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éeemptyDirsur le chemin d'accès correspondant (/tmp/sidecarou/tmp/shared-memory) dans les conteneurspathways-workeretcolocated-python-sidecar.Timed out connecting to sidecar gRPC serviceouFailed to connect to external sidecar: vérifiez que le conteneurcolocated-python-sidecars'exécute sous le champinitContainersavecrestartPolicy: Alwayset que les trois imagescloud-pathwaysutilisent des tags correspondants. Vérifiez que vos paramètres TCP (--port=50051) ou UDS (volume/socket--unix_domain_socket_path=/sock/sidecar.sock) correspondent entre les conteneurspathways-proxyetcolocated-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=0sur le conteneurcolocated-python-sidecar(avec l'option--port=50051ou--unix_domain_socket_path) et l'option--cloud_pathways_shared_memory_idle_release_secs=0sur le conteneurpathways-worker. Définir les deux options sur0libè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 ressourceJobSet:kubectl delete jobset JOBSET_NAMERemplacez
JOBSET_NAMEpar la valeurmetadata.namede votreJobSet.Cluster Toolkit : annulez le job déployé :
gcluster job cancel WORKLOAD \ --cluster=CLUSTER \ --project=PROJECT_ID \ --location=LOCATIONRemplacez 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
- Transférer des charges de travail JAX vers Pathways
- Entraînement résilient avec Pathways
- Exécuter une charge de travail par lot avec Pathways
- Exécuter une charge de travail interactive avec Pathways
- Résoudre les problèmes liés à Pathways sur Cloud
- Exécuter des charges de travail avec Pathways dans Cluster Toolkit