Wenn Sie hostgebundene Aufgaben wie das Laden von Daten und das Erstellen von Prüfpunkten nicht über einen einzelnen Pathways-Controller in der Google Kubernetes Engine (GKE) weiterleiten möchten, führen Sie diese Funktionen auf Ihren Cloud TPU-Worker-VMs mit der colocated Python API von JAX aus.
In diesem Dokument, das sich an ML-Entwickler richtet, wird beschrieben, wie colokalisiertes Python mit Pathways funktioniert. Sie erfahren, wie Sie einen Sidecar-Container mit einem JobSet-Manifest oder dem Cluster Toolkit erstellen, bereitstellen und prüfen.
Hinweis
Erfüllen Sie die folgenden Voraussetzungen:
- GKE-Cluster mit Pathways erstellen
- Installieren Sie das
kubectl-Befehlszeilentool und dasgke-gcloud-auth-plugin-Plug-in. - Installieren Sie die Google Cloud CLI.
- Installieren Sie Docker.
- Aktivieren Sie die Kubernetes Engine API und die Artifact Registry API.
- Erstellen Sie einen Cloud Storage-Scratch-Bucket für temporäre Pathways-Dateien.
- Wenn Sie ein benutzerdefiniertes Sidecar-Image erstellen möchten, erstellen Sie ein Artifact Registry-Docker-Repository.
- Installieren Sie Python 3.12 in der Clientumgebung, in der Ihre JAX-Arbeitslast ausgeführt wird.
- Optional: Wenn Sie die Bereitstellung mit dem Cluster Toolkit vornehmen möchten, installieren Sie Version 1.108.0 oder höher der
gcluster-Befehlszeile.
Erforderliche Rollen
Weisen Sie die folgenden IAM-Rollen (Identity and Access Management) zu:
- Ihr Nutzerkonto:
- Artifact Registry Writer (
roles/artifactregistry.writer) für Ihr Google Cloud -Projekt, um benutzerdefinierte Sidecar-Images in Artifact Registry zu übertragen. - Kubernetes Engine-Entwickler (
roles/container.developer) für Ihr Google Cloud -Projekt, umJobSet-Ressourcen bereitzustellen, Ports weiterzuleiten und Pod-Logs in der GKE zu lesen.
- Artifact Registry Writer (
- GKE-Knotenpool-Dienstkonto: Pathways-Pods verwenden dieses Dienstkonto, wenn Ihre Knotenpools das Flag
--workload-metadata=GCE_METADATAverwenden, wie unter GKE-Cluster mit Pathways erstellen konfiguriert:- Artifact Registry-Leser (
roles/artifactregistry.reader) für das Projekt in Google Cloud , das Ihr privates Repository hostet, um benutzerdefinierte Sidecar-Images abzurufen. - Storage-Objekt-Administrator (
roles/storage.objectAdmin) für Ihren Cloud Storage-Scratch-Bucket für den Kompilierungscache und andere temporäre Dateien.
- Artifact Registry-Leser (
Optional: Damit der Pathways-Ressourcenmanager-Container (pathways-rm) eine Bucket-Lebenszyklusregel hinzufügen kann, die alte Compilation-Cache-Einträge ablaufen lässt, weisen Sie dem Scratch-Bucket auch die Rolle Storage-Administrator (roles/storage.admin) zu. Ohne diese Rolle protokolliert der pathways-rm-Container eine Warnung und verwendet den Cache weiterhin. Wenn Sie die Aktualisierung des Lebenszyklus überspringen möchten, übergeben Sie das Flag --enable_gcs_olm=false an den Container pathways-rm.
Wenn Ihre Knotenpools stattdessen die Workload Identity-Föderation für GKE verwenden, weisen Sie die Rolle für den Scratch-Bucket dem Kubernetes-Dienstkonto zu, das die Pathways-Pods verwenden, oder dem zugehörigen IAM-Dienstkonto. Standardmäßig verwenden Pathways-Pods das Dienstkonto default, sofern im JobSet-Manifest nicht das Feld serviceAccountName festgelegt ist. Behalten Sie die Rolle „Artifact Registry-Leser“ für das Dienstkonto des Knotenpools bei.
Funktionsweise von gemeinsam bereitgestelltem Python mit Pathways
In Pathways wird Ihr JAX-Controller-Script auf einem einzelnen CPU-Host ausgeführt, während Cloud TPU-Worker-Pods den C++-Container pathways-worker ausführen. Zum Ausführen von @colocated_python-Funktionen und @colocated_python_class-Methoden auf Worker-Hosts verwendet das am selben Ort befindliche Python die folgenden Komponenten:
- Ihr JAX-Controller: Verwendet das Modul
jax.experimental.colocated_python, um jeden Cloud TPU-Chip mit einem Host-CPU-Gerät zu koppeln und Ihre Python-Funktion und Typmetadaten mit der Bibliothekcloudpicklezu serialisieren. - Der
pathways-proxy-Container (impathways-head-Pod): Empfängt die serialisierte Funktion über gRPC und leitet sie an denpathways-worker-Container auf den Worker-VMs weiter, die die Eingabe-CPU-Geräte des Aufrufs besitzen. Wenn Sie das Flag--sidecar_name=externalübergeben, wird der Containerpathways-proxyso konfiguriert, dass er auf den Containercolocated-python-sidecarausgerichtet ist. - Der
pathways-worker-Container (auf jedem Worker-Pod): Lädt die serialisierte Funktion in den lokalen Sidecar-Container, löst die Ausführung über lokales gRPC aus und tauscht Array-Zwischenspeicher über ein freigegebenes In-Memory-emptyDir-Volume (medium: Memory) aus. - Der
colocated-python-sidecar-Container (auf jedem Worker-Pod): Entpackt die Funktion und führt sie in einer isolierten Python 3.12-Laufzeit einmal pro VM über die lokalen Shards dieser VM aus. Die Ausgabearrays werden direkt in den freigegebenen Hostspeicher geschrieben.
Weitere Informationen zur Pathways-Architektur finden Sie unter Pathways-Komponenten.
Ablauf der Ausführung
Wenn Sie eine dekorierte Funktion aufrufen, führt Pathways sie in zwei Phasen im gesamten Cluster aus:
- Funktionsrouting: Das
jax.experimental.colocated_python-Modul packt die Funktion in ein Interim Framework Runtime (IFRT)-Programm und sendet es an denpathways-proxy-Container. Der Proxy leitet das Programm nur an Worker-VMs weiter, die die Eingabe-Shards enthalten. Es wird einmal pro VM für alle lokalen Shards ausgeführt. - Ausführung im gemeinsam genutzten Speicher: Der
pathways-worker-Container schreibt Eingabe-Shards in das gemeinsam genutzte In-Memory-Volume (/tmp/sidecaroder/tmp/shared-memory) und ruft dencolocated-python-sidecar-Container über Loopback-TCP (localhost:50051) oder einen Unix-Domain-Socket (/sock/sidecar.sock) auf. Ausgabearrays werden über den gemeinsam genutzten Speicher ohne gRPC-Kopien zurückgegeben und direkt in den High-Bandwidth Memory (HBM) der Cloud TPU verschoben, wenn sie auf Cloud TPU-Geräten platziert werden.
Informationen zur Verwendung der JAX API, z. B. zum Erkennen von gemeinsam genutzten CPU-Geräten und zum Deklarieren von Ausgabespezifikationen für die asynchrone Weiterleitung, finden Sie im Leitfaden zu gemeinsam genutzten Python-Geräten in JAX.
Gestaltungsrichtlinien
Beachten Sie beim Schreiben von am selben Ort befindlichen Python-Funktionen die folgenden Richtlinien:
- Erfasste Variablen minimieren: Übergeben Sie Arraydaten als fragmentierte
jax.Array-Argumente, anstatt große Arrays oder nicht serialisierbare Objekte (z. B. geöffnete Dateien oder Netzwerkclients) in Closures zu erfassen. Öffnen Sie Dateien oder Clients in einer@colocated_python_class-Instanz auf dem Worker. @colocated_python_class-Zustand nach Neustarts neu erstellen: Stateful-Sidecar-Objekte bleiben über Schritte hinweg im Arbeitsspeicher erhalten, werden aber nicht automatisch gespeichert, wenn ein Worker-Pod neu gestartet wird oder sich die Anzahl der Slices während des elastischen Trainings ändert. Zustandsorientierte Objekte nach einer Neuskalierung oder einem Neustart von einem Prüfpunkt neu erstellen.
Vordefinierte Images und Tags
Google Cloud veröffentlicht vordefinierte Pathways-Images in einem öffentlichen Artifact Registry-Repository:
- Colocated Python Sidecar:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG - Pathways-Ressourcenmanager und -Worker:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG - IFRT-Proxyserver:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG
Verwenden Sie übereinstimmende Tags für die Images server, proxy_server und colocated_python_sidecar.
Vordefinierte Sidecar-Images unterstützen die JAX-Versionen 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0 und 0.12.0.1. Ersetzen Sie TAG durch eines der folgenden Tag-Formate:
jax-JAX_VERSION(empfohlen): Ein rollierendes Tag für eine bestimmte JAX-Version, z. B.jax-0.12.0.1.YYYYMMDD-jax_JAX_VERSION: ein Build-Tag mit Datumsstempel, z. B.20261110-jax_0.12.0.1.
Wenn Sie eine genaue Image-Version benötigen, die sich nie ändert, pinnen Sie das Image anhand seines SHA-256-Digests an. Verwenden Sie den Befehl gcloud artifacts docker images describe, um einen Image-Digest zu suchen:
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)"
Ersetzen Sie JAX_VERSION durch Ihre JAX-Version, z. B. 0.12.0.1.
Benutzerdefiniertes Sidecar-Image erstellen
Das vordefinierte Sidecar-Image enthält die Pakete jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle und absl-py. Wenn Ihre am selben Ort befindlichen Python-Funktionen nur diese Pakete verwenden, fahren Sie mit Pathways-JobSet mit dem Sidecar bereitstellen oder Mit Cluster Toolkit bereitstellen fort.
Wenn Sie benutzerdefinierte Python-Abhängigkeiten hinzufügen möchten, legen Sie sie über das vordefinierte Image, das Ihrer JAX-Version entspricht:
Erstellen Sie in einem leeren Build-Verzeichnis eine
requirements.txt-Datei für Ihre zusätzlichen Pakete. Lassen Sie die Paketejaxundjaxlibweg, die bereits in der Datei/opt/venv/server_constraints.txtinstalliert und angepinnt sind:grainErstellen Sie eine
Dockerfile, die die Pakete in der Dateirequirements.txtinstalliert, eingeschränkt durch die Datei/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 cleanLassen Sie die Anweisungen
ENTRYPOINTundCMDdes Basis-Images unverändert. Wenn die Dateirequirements.txtPakete von Git-URLs installiert, fügen Sie die folgendeRUN-Anweisung vor deruv pip install-RUN-Anweisung hinzu, da das schlanke Basis-Image dasgit-Tool weglässt:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*Authentifizieren Sie Docker für Ihre Artifact Registry-Region mit dem Befehl
gcloud auth configure-docker:gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.devErsetzen Sie
REGISTRY_LOCATIONdurch Ihren Artifact Registry-Standort, z. B.usoderus-central1.Erstellen Sie Ihr benutzerdefiniertes Sidecar-Image und übertragen Sie es per Push:
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}"Ersetzen Sie Folgendes:
JAX_VERSION: Ihre JAX-Version, z. B.0.12.0.1.REGISTRY_LOCATION: Ihr Artifact Registry-Speicherort, z. B.usoderus-central1.PROJECT_ID: IhreGoogle Cloud -Projekt-ID.REPOSITORY: der Name Ihres Artifact Registry-Docker-Repositorys.
Pathways-JobSet mit dem Sidecar bereitstellen
Sie können Pathways mit dem Sidecar entweder durch Anwenden eines JobSet-Manifests mit dem kubectl-Befehlszeilentool in diesem Abschnitt oder durch direktes Senden des Jobs mit der gcluster-Befehlszeile in Mit Cluster Toolkit bereitstellen bereitstellen.
So generieren Sie ein JobSet-Manifest und wenden es an:
Erstellen Sie ein
JobSet-Manifest (pathways-colocated-jobset.yaml) mit einem der folgenden Tools:- Der
pathways-utils-Python-Builder: Konfigurieren Sie einenJobSetmit demPathwaysJobSet-Builder, indem Sie die Methoden.add_colocated_python("SIDECAR_IMAGE")und.export_yaml("pathways-colocated-jobset.yaml")aufrufen. Wenn Sie das Paketpathwaysutils(Version0.1.14oder früher von PyPI) verwenden, übergeben Sie auch das Argumentproxy_container_kwargs={"args": ["--sidecar_name=external"]}an den KonstruktorPathwaysJobSetoder installieren Sie das Paketpathways-utilsaus dem Zweigmain. - Cluster Toolkit (
gcluster): Führen Sie den Befehlgcluster job submitmit dem Flag--pathways-colocated-python-sidecar-imageaus und hängen Sie das Flag--dry-run-out=pathways-colocated-jobset.yamlan, um das Manifest lokal zu rendern, ohne den Job zu senden.
Ersetzen Sie
SIDECAR_IMAGEdurch den URI Ihres benutzerdefinierten Sidecar-Images oder den URI des vordefiniertencolocated_python_sidecar-Images.Beide Generatoren konfigurieren das Manifest für Folgendes:
- Führen Sie den Container
colocated-python-sidecarim FeldinitContainersmitrestartPolicy: Alwaysin jedem Worker-Pod aus. Diegcluster-CLI benennt den replizierten Worker-Jobworker, während derPathwaysJobSet-Builder ihnpathways-workernennt. - Übergeben Sie das Flag
--sidecar_name=externalan den Containerpathways-proxyund verbinden Sie den Containerpathways-workerüber Loopback-TCP auflocalhost:50051mit dem Sidecar. Wenn der Containerpathways-proxyim FeldinitContainersausgeführt wird, wird auchrestartPolicy: Alwaysverwendet. - Stellen Sie ein In-Memory-
emptyDir-Volume mitmedium: Memoryin beiden Worker-Pod-Containern bereit: unter/tmp/sidecaringcluster-Manifesten oder unter/tmp/shared-memoryinPathwaysJobSet-Manifesten. Beide Generatoren legen auch die UmgebungsvariableCLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORYfür den Sidecar und das Flag--cloud_pathways_sidecar_shm_directoryfür denpathways-worker-Container fest.
- Der
Wenden Sie das
JobSet-Manifest an und warten Sie, bis die Pods den StatusRunningerreicht haben:kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAMEErsetzen Sie
JOBSET_NAMEdurch denmetadata.name-Wert IhresJobSet.
Führen Sie eine JAX-Clientsitzung pro JobSet-Bereitstellung aus. Nachdem die Verbindung eines Clients getrennt wurde, kann ein neu gestarteter pathways-worker-Container einen laufenden Sidecar nicht wiederverwenden. Löschen Sie die JobSet und erstellen Sie sie neu, bevor Sie eine weitere Sitzung starten.
Dateien in einem speicherinternen emptyDir-Volume werden auf die Pod-Speichernutzung angerechnet. Legen Sie das Feld emptyDir.sizeLimit (z. B. 175Gi) für das Volume für gemeinsam genutzten Arbeitsspeicher fest, um die Nutzung pro Knoten zu begrenzen. Standardmäßig behalten beide Container freigegebenen Arbeitsspeicher für 30 Sekunden Inaktivität zur Wiederverwendung bei. Wenn Sie dieses Zeitfenster ändern möchten, legen Sie das Flag --pathways_sidecar_shared_memory_idle_release_secs=SECONDS im Feld args des Containers colocated-python-sidecar (neben dem Flag --port=50051 oder --unix_domain_socket_path) und das Flag --cloud_pathways_shared_memory_idle_release_secs=SECONDS im Feld args des Containers pathways-worker fest. Ersetzen Sie SECONDS durch das Zeitlimit für Inaktivität in Sekunden. Wenn Sie beide Flags auf 0 setzen, werden freigegebene Seiten innerhalb von etwa 1 Sekunde freigegeben. Dadurch wird die Speichernutzung reduziert, was jedoch zu zusätzlichem Zuordnungsaufwand führt.
Optional: Unix Domain Socket verwenden
Wenn Sie einen Unix-Domain-Socket (UDS) unter /sock/sidecar.sock verwenden möchten, anstatt einen TCP-Port auf Worker-Pods zu öffnen, die hostNetwork: true festlegen, wenden Sie die folgenden Überschreibungen auf Ihr JobSet-Manifest an, bevor Sie den Befehl kubectl apply ausführen:
- Stellen Sie ein
emptyDir: {}-Volume mit dem Namensidecar-socketunter/socksowohl im Containerpathways-workerals auch im Containercolocated-python-sidecarbereit. - Legen Sie
args: ["--unix_domain_socket_path=/sock/sidecar.sock"]und einexecstartupProbe(test -S /sock/sidecar.sock) für den Containercolocated-python-sidecarfest. - Hängen Sie das Flag
--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sockan das Feldargsdes Containerspathways-proxyan.
Mit Cluster Toolkit bereitstellen
Im Cluster Toolkit (gcluster-Version 1.108.0 oder höher) wird durch die Übergabe des Flags --pathways-colocated-python-sidecar-image an den Befehl gcluster job submit der Container colocated-python-sidecar über Loopback-TCP (localhost:50051) konfiguriert, das In-Memory-Volume unter /tmp/sidecar bereitgestellt und das Flag --sidecar_name=external festgelegt. Übergeben Sie die Flags --pathways-server-image und --pathways-proxy-server-image explizit, damit alle drei Images übereinstimmende cloud-pathways-Tags verwenden.
Senden Sie ein Pathways-Deployment ohne Head mit Ihrem Sidecar-Image, damit Sie interaktive Client-Skripts dafür ausführen können:
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
Ersetzen Sie Folgendes:
BUCKET_NAME: Ihr Cloud Storage-Scratch-Bucket.JAX_VERSION: Ihre JAX-Version, z. B.0.12.0.1.SIDECAR_IMAGE: der URI Ihres benutzerdefinierten oder vordefinierten Sidecar-Images.WORKLOAD: ein eindeutigerJobSet-Name (maximal 22 Zeichen).CLUSTER: der Name Ihres GKE-Cluster.PROJECT_ID: IhreGoogle Cloud -Projekt-ID.LOCATION: die Region oder Zone Ihres GKE-Cluster.WORKLOAD_NODEPOOL_COUNT: die Anzahl der Cloud TPU-Slices, z. B.1.COMPUTE_TYPE: der Cloud TPU-Maschinentyp, z. B.ct5lp-hightpu-4toderct6e-standard-4t.TOPOLOGY: die Cloud TPU-Slice-Topologie, z. B.4x8oder2x4.
Sie können auch anpassen, wie der Befehl gcluster job submit den Job ausführt oder exportiert:
- Batcharbeitslasten: Wenn Sie einen containerisierten Batchjob im Pod
pathways-headanstelle eines monitorlosen Deployments ausführen möchten, ersetzen Sie das Flag--pathways-headlessdurch die Flags--image="CLIENT_IMAGE"und--command="COMMAND". Verwenden Sie ein Python 3.12-JAX-Client-Image, das mitserver_constraints.txt-Pins erstellt wurde, und übergeben Sie Ihren Einstiegsbefehl (z. B.python colocated_example.py). - Lokales Manifest-Rendering: Hängen Sie das Flag
--dry-run-out=pathways-colocated-jobset.yamlan, um das ManifestJobSetlokal zu rendern, ohne es zu senden. - Nachfolgende Headless-Sitzungen: Führen Sie den Befehl
gcluster job cancelaus und reichen Sie den Job noch einmal ein, bevor Sie eine weitere Clientsitzung starten.
Colocated Python-Arbeitslast ausführen
Führen Sie Ihr JAX-Clientskript mit der Umgebungsvariable JAX_PLATFORMS=proxy für den Container pathways-proxy aus, entweder im Arbeitslastcontainer pathways-head oder über die Portweiterleitung:
Um die Serialisierungsabhängigkeiten mit Ihrem Sidecar-Image abzugleichen, extrahieren Sie die Datei
/opt/venv/server_constraints.txtund installieren Sie die entsprechenden Pakete in einer virtuellen Python 3.12-Umgebung: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 pathwaysutilsErsetzen Sie
JAX_VERSIONdurch Ihre JAX-Version, z. B.0.12.0.1.Wenn Sie den Client außerhalb des
pathways-head-Pods ausführen, leiten Sie den lokalen Port29000in einem separaten Terminal an denpathways-proxy-Container weiter: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:29000Ersetzen Sie
JOBSET_NAMEdurch denmetadata.name-Wert IhresJobSet(oder denWORKLOAD-Namen, den Sie an den Befehlgcluster job submitübergeben haben).Speichern Sie das folgende Script als
colocated_example.py. Dieses Skript weist auf dem gemeinsam genutzten CPU-Gerät jedes Cloud TPU-Workers ein 4-MiB-NumPy-Array im gemeinsam genutzten Hostspeicher zu und überträgt es an den 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}" )Führen Sie das Script für den IFRT-Proxyserver aus:
JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \ python colocated_example.pyDie Ausgabe sieht etwa so aus:
TPU devices: 8, colocated CPU devices: 8 Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0Übergeben Sie in Multislice-Produktionsarbeitslasten ein fragmentiertes
jax.Array-Argument, das auf den Geräten platziert ist, die vomcolocated_python.colocated_cpu_devices(mesh)-Aufruf zurückgegeben werden, und legen Sie den Parameterout_specs_fnmit der Methode.specialize(out_specs_fn=...)fest, damit Pathways einen parallelen Aufruf über alle Worker-Sidecars hinweg ausführt, ohne zu warten.Führen Sie keine Clientscripts in einem
worker-Pod mit der UmgebungsvariablenJAX_PLATFORMS=cpuaus, da diese Einstellung JAX lokal auf einer CPU ausführt und Pathways umgeht. Sie können die MeldungIFRT proxy server disconnected: CANCELLEDignorieren, die beim Beenden ausgegeben wird.
Weitere Nutzungsmuster finden Sie in den folgenden Ressourcen:
- Colocated Python-Notebook für JAX: Funktionsspezialisierung und zustandsorientierte
@colocated_python_class-Objekte - MaxText-Modul
multihost_dataloading.py:RemoteIterator-Multihost-Eingabepipeline, die colocated Python verwendet - Orbax Pathways-Prüfpunkte und Multi-Tier-Prüfpunkte mit Pathways: verteilte Prüfpunkte auf Worker-Sidecars mit dem Aufruf
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)(oder der Einstellungcolocated_python_checkpointing=Truein MaxText) und der Optionuse_colocated_python=Truefür Multi-Tier-Prüfpunkte
Sidecar-Bereitstellung prüfen
Führen Sie den Befehl kubectl logs auf einem monitorlosen JobSet aus, bevor Sie ihn abbrechen oder löschen oder während eine Batcharbeitslast noch ausgeführt wird. In Batch-JobSet-Bereitstellungen löscht der JobSet-Controller worker-Pods, sobald der pathways-head-Job abgeschlossen ist. Sehen Sie sich stattdessen die abgeschlossenen Batch-Logs in Cloud Logging an, wie unter Fehlerbehebung für Pathways in der Cloud beschrieben.
Führen Sie die folgenden Schritte aus, um ein laufendes Deployment mit dem kubectl-Befehlszeilentool zu überprüfen:
Prüfen Sie die Logs des Containers
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-sidecarErsetzen Sie
JOBSET_NAMEdurch denmetadata.name-Wert IhresJobSet(oder denWORKLOAD-Namen, den Sie an den Befehlgcluster job submitübergeben haben). Wenn Sie Ihr Manifest mit demPathwaysJobSet-Builder generiert haben, legen Siereplicatedjob-name=pathways-workerin der VariablenROLE_LABELfest.Die Ausgabe sieht etwa so aus:
Started SidecarGrpcServer on localhost:50051 ... SidecarServer agreed on protocol version: 6 Installed shared memory allocator for colocated Python using file /tmp/sidecar/pathways_shm_sidecarPrüfen Sie, ob in der Ausgabe die gRPC-Startmeldung und nach dem ersten
@colocated_python-Aufruf die Meldung des Shared-Memory-Allocators angezeigt wird. Manifeste, die mit demPathwaysJobSet-Builder generiert wurden, verwenden das Verzeichnis/tmp/shared-memoryund UDS-Bereitstellungen protokollierenunix:/sock/sidecar.sockanstelle vonlocalhost:50051.Prüfen Sie die
pathways-worker-Containerlogs im selben Pod:kubectl logs "${WORKER_POD}" -c pathways-worker \ | grep -iE "shared memory|external sidecar"Die Ausgabe sieht etwa so aus:
Enabled shared memory for external sidecar in /tmp/sidecar External sidecar connected to backing GRPC sidecar at localhost:50051Prüfen Sie, ob der Container
pathways-workerden freigegebenen Speicher aktiviert und eine Verbindung zum Sidecar hergestellt hat.
Wenn Sie den Befehl kubectl exec ausführen, um das Verzeichnis für den freigegebenen Speicher zu prüfen, geben Sie den Container colocated-python-sidecar mit dem Flag -c colocated-python-sidecar an, da der Container pathways-worker keine Shell enthält.
Fehlerbehebung für colocated Python
In den folgenden Abschnitten wird beschrieben, wie Sie häufige Probleme mit gemeinsam bereitgestelltem Python beheben können.
Unable to unpickle Fehler
Wenn Ihre Arbeitslast mit dem folgenden Fehler fehlschlägt, unterscheiden sich die Python- oder Paketversionen zwischen Ihrem JAX-Client und dem Sidecar-Container:
jax.errors.JaxRuntimeError: UNKNOWN: Unable to unpickle the callable and specialization
Prüfen Sie, ob auf Ihrem Client Python 3.12 (python --version) ausgeführt wird, und installieren Sie Clientpakete mit dem Flag -c constraints.txt, das aus dem Sidecar-Image extrahiert wurde.
Weitere Informationen finden Sie unter Colocated Python-Arbeitslast ausführen.
Abhängigkeitskonflikt während einer docker build-Ausführung
Wenn der Befehl uv pip install mit dem Fehler No solution found when resolving dependencies fehlschlägt, steht ein Pin in Ihrer requirements.txt-Datei im Konflikt mit der Datei /opt/venv/server_constraints.txt. Entfernen Sie die Pakete jax und jaxlib aus der Datei requirements.txt und lockern Sie die Versions-Pins für Pakete wie numpy, ml-dtypes oder scipy.
Fehler „Sidecar nicht aktiviert“
Wenn der pathways-proxy-Container mit dem Fehler Sidecar create args were set, but sidecar was not enabled beendet wird, fügen Sie das Flag --sidecar_name=external dem Feld args des pathways-proxy-Containers hinzu.
Sidecar already initialized Fehler
Wenn Ihre Arbeitslast mit dem Fehler FAILED_PRECONDITION: Sidecar already initialized fehlschlägt, wurde der Container pathways-worker durch eine frühere Clienttrennung neu gestartet, während der Container colocated-python-sidecar initialisiert blieb. Löschen Sie die JobSet und erstellen Sie sie neu, bevor Sie eine weitere Clientsitzung starten.
Fehler bei der Verbindung mit gemeinsam genutztem Speicher oder Sidecar
Führen Sie die folgenden Prüfungen durch, um Fehler bei der Bereitstellung von gemeinsam genutztem Speicher, gRPC-Verbindungen oder Hostspeicher zu beheben:
Failed to stat sidecar_shm_directory: Stellen Sie das Volume für gemeinsam genutzten ArbeitsspeicheremptyDirim entsprechenden Pfad (/tmp/sidecaroder/tmp/shared-memory) sowohl im Containerpathways-workerals auch im Containercolocated-python-sidecarbereit.Timed out connecting to sidecar gRPC serviceoderFailed to connect to external sidecar: Prüfen Sie, ob der Containercolocated-python-sidecarim FeldinitContainersmitrestartPolicy: Alwaysausgeführt wird und ob alle dreicloud-pathways-Images übereinstimmende Tags verwenden. Prüfen Sie, ob die TCP- (--port=50051) oder UDS-Einstellungen (/sock-Volume und--unix_domain_socket_path=/sock/sidecar.sock) zwischen den Containernpathways-proxyundcolocated-python-sidecarübereinstimmen.- Worker-Host-Speicher nach großen Array-Bursts nicht mehr verfügbar: Setzen Sie das Flag
--pathways_sidecar_shared_memory_idle_release_secs=0für den Containercolocated-python-sidecar(zusammen mit dem Flag--port=50051oder--unix_domain_socket_path) und das Flag--cloud_pathways_shared_memory_idle_release_secs=0für den Containerpathways-worker. Wenn Sie beide Flags auf0setzen, wird nicht verwendeter gemeinsamer Speicher innerhalb von etwa 1 Sekunde freigegeben. Alternativ können Sie die maximale Menge an Host-Array-Daten reduzieren, die Ihre Arbeitslast gleichzeitig im Arbeitsspeicher hält.
Bereinigen
Wenn Sie vermeiden möchten, dass Ihrem Google Cloud Konto die in diesem Dokument verwendeten Ressourcen in Rechnung gestellt werden, löschen Sie Ihre Bereitstellung und die temporären Artefakte, wenn Sie fertig sind:
JobSet-Manifest: Löschen Sie dieJobSet-Ressource:kubectl delete jobset JOBSET_NAMEErsetzen Sie
JOBSET_NAMEdurch denmetadata.name-Wert IhresJobSet.Cluster Toolkit: Brechen Sie den bereitgestellten Job ab:
gcluster job cancel WORKLOAD \ --cluster=CLUSTER \ --project=PROJECT_ID \ --location=LOCATIONErsetzen Sie Folgendes:
WORKLOAD: der Name Ihres Pathways-Jobs.CLUSTER: der Name Ihres GKE-Cluster.PROJECT_ID: IhreGoogle Cloud -Projekt-ID.LOCATION: die Region oder Zone Ihres GKE-Cluster.
Optional: Löschen Sie alle benutzerdefinierten Sidecar-Images in Artifact Registry und entfernen Sie temporäre Objekte in Ihrem Cloud Storage-Scratch-Bucket. Wenn Sie Ihren GKE-Cluster nicht mehr benötigen, löschen Sie ihn. Folgen Sie dazu den Schritten unter Bereinigen in GKE-Cluster mit Pathways erstellen.
Nächste Schritte
- JAX-Arbeitslasten zu Pathways portieren
- Ausfallsicheres Training mit Pathways
- Batcharbeitslast mit Pathways ausführen
- Interaktive Arbeitslast mit Pathways ausführen
- Fehlerbehebung für Pathways in der Cloud
- Arbeitslasten mit Pathways im Cluster Toolkit ausführen