Zusammengeführten Python-Code mit Pathways ausführen

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:

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, um JobSet-Ressourcen bereitzustellen, Ports weiterzuleiten und Pod-Logs in der GKE zu lesen.
  • GKE-Knotenpool-Dienstkonto: Pathways-Pods verwenden dieses Dienstkonto, wenn Ihre Knotenpools das Flag --workload-metadata=GCE_METADATA verwenden, 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.

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 Bibliothek cloudpickle zu serialisieren.
  • Der pathways-proxy-Container (im pathways-head-Pod): Empfängt die serialisierte Funktion über gRPC und leitet sie an den pathways-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 Container pathways-proxy so konfiguriert, dass er auf den Container colocated-python-sidecar ausgerichtet 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:

  1. Funktionsrouting: Das jax.experimental.colocated_python-Modul packt die Funktion in ein Interim Framework Runtime (IFRT)-Programm und sendet es an den pathways-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.
  2. Ausführung im gemeinsam genutzten Speicher: Der pathways-worker-Container schreibt Eingabe-Shards in das gemeinsam genutzte In-Memory-Volume (/tmp/sidecar oder /tmp/shared-memory) und ruft den colocated-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:

  1. Erstellen Sie in einem leeren Build-Verzeichnis eine requirements.txt-Datei für Ihre zusätzlichen Pakete. Lassen Sie die Pakete jax und jaxlib weg, die bereits in der Datei /opt/venv/server_constraints.txt installiert und angepinnt sind:

    grain
    
  2. Erstellen Sie eine Dockerfile, die die Pakete in der Datei requirements.txt installiert, 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 clean
    

    Lassen Sie die Anweisungen ENTRYPOINT und CMD des Basis-Images unverändert. Wenn die Datei requirements.txt Pakete von Git-URLs installiert, fügen Sie die folgende RUN-Anweisung vor der uv pip install-RUN-Anweisung hinzu, da das schlanke Basis-Image das git-Tool weglässt:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Authentifizieren Sie Docker für Ihre Artifact Registry-Region mit dem Befehl gcloud auth configure-docker:

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

    Ersetzen Sie REGISTRY_LOCATION durch Ihren Artifact Registry-Standort, z. B. us oder us-central1.

  4. 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. us oder us-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:

  1. Erstellen Sie ein JobSet-Manifest (pathways-colocated-jobset.yaml) mit einem der folgenden Tools:

    • Der pathways-utils-Python-Builder: Konfigurieren Sie einen JobSet mit dem PathwaysJobSet-Builder, indem Sie die Methoden .add_colocated_python("SIDECAR_IMAGE") und .export_yaml("pathways-colocated-jobset.yaml") aufrufen. Wenn Sie das Paket pathwaysutils (Version 0.1.14 oder früher von PyPI) verwenden, übergeben Sie auch das Argument proxy_container_kwargs={"args": ["--sidecar_name=external"]} an den Konstruktor PathwaysJobSet oder installieren Sie das Paket pathways-utils aus dem Zweig main.
    • Cluster Toolkit (gcluster): Führen Sie den Befehl gcluster job submit mit dem Flag --pathways-colocated-python-sidecar-image aus und hängen Sie das Flag --dry-run-out=pathways-colocated-jobset.yaml an, um das Manifest lokal zu rendern, ohne den Job zu senden.

    Ersetzen Sie SIDECAR_IMAGE durch den URI Ihres benutzerdefinierten Sidecar-Images oder den URI des vordefinierten colocated_python_sidecar-Images.

    Beide Generatoren konfigurieren das Manifest für Folgendes:

    • Führen Sie den Container colocated-python-sidecar im Feld initContainers mit restartPolicy: Always in jedem Worker-Pod aus. Die gcluster-CLI benennt den replizierten Worker-Job worker, während der PathwaysJobSet-Builder ihn pathways-worker nennt.
    • Übergeben Sie das Flag --sidecar_name=external an den Container pathways-proxy und verbinden Sie den Container pathways-worker über Loopback-TCP auf localhost:50051 mit dem Sidecar. Wenn der Container pathways-proxy im Feld initContainers ausgeführt wird, wird auch restartPolicy: Always verwendet.
    • Stellen Sie ein In-Memory-emptyDir-Volume mit medium: Memory in beiden Worker-Pod-Containern bereit: unter /tmp/sidecar in gcluster-Manifesten oder unter /tmp/shared-memory in PathwaysJobSet-Manifesten. Beide Generatoren legen auch die Umgebungsvariable CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY für den Sidecar und das Flag --cloud_pathways_sidecar_shm_directory für den pathways-worker-Container fest.
  2. Wenden Sie das JobSet-Manifest an und warten Sie, bis die Pods den Status Running erreicht haben:

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

    Ersetzen Sie JOBSET_NAME durch den metadata.name-Wert Ihres JobSet.

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 Namen sidecar-socket unter /sock sowohl im Container pathways-worker als auch im Container colocated-python-sidecar bereit.
  • Legen Sie args: ["--unix_domain_socket_path=/sock/sidecar.sock"] und ein execstartupProbe (test -S /sock/sidecar.sock) für den Container colocated-python-sidecar fest.
  • Hängen Sie das Flag --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock an das Feld args des Containers pathways-proxy an.

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 eindeutiger JobSet-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-4t oder ct6e-standard-4t.
  • TOPOLOGY: die Cloud TPU-Slice-Topologie, z. B. 4x8 oder 2x4.

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-head anstelle eines monitorlosen Deployments ausführen möchten, ersetzen Sie das Flag --pathways-headless durch die Flags --image="CLIENT_IMAGE" und --command="COMMAND". Verwenden Sie ein Python 3.12-JAX-Client-Image, das mit server_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.yaml an, um das Manifest JobSet lokal zu rendern, ohne es zu senden.
  • Nachfolgende Headless-Sitzungen: Führen Sie den Befehl gcluster job cancel aus 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:

  1. Um die Serialisierungsabhängigkeiten mit Ihrem Sidecar-Image abzugleichen, extrahieren Sie die Datei /opt/venv/server_constraints.txt und 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 pathwaysutils
    

    Ersetzen Sie JAX_VERSION durch Ihre JAX-Version, z. B. 0.12.0.1.

  2. Wenn Sie den Client außerhalb des pathways-head-Pods ausführen, leiten Sie den lokalen Port 29000 in einem separaten Terminal an den pathways-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:29000
    

    Ersetzen Sie JOBSET_NAME durch den metadata.name-Wert Ihres JobSet (oder den WORKLOAD-Namen, den Sie an den Befehl gcluster job submit übergeben haben).

  3. 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}"
    )
    
  4. 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.py
    

    Die 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 vom colocated_python.colocated_cpu_devices(mesh)-Aufruf zurückgegeben werden, und legen Sie den Parameter out_specs_fn mit 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 Umgebungsvariablen JAX_PLATFORMS=cpu aus, da diese Einstellung JAX lokal auf einer CPU ausführt und Pathways umgeht. Sie können die Meldung IFRT proxy server disconnected: CANCELLED ignorieren, die beim Beenden ausgegeben wird.

Weitere Nutzungsmuster finden Sie in den folgenden Ressourcen:

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:

  1. 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-sidecar
    

    Ersetzen Sie JOBSET_NAME durch den metadata.name-Wert Ihres JobSet (oder den WORKLOAD-Namen, den Sie an den Befehl gcluster job submit übergeben haben). Wenn Sie Ihr Manifest mit dem PathwaysJobSet-Builder generiert haben, legen Sie replicatedjob-name=pathways-worker in der Variablen ROLE_LABEL fest.

    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_sidecar
    

    Prü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 dem PathwaysJobSet-Builder generiert wurden, verwenden das Verzeichnis /tmp/shared-memory und UDS-Bereitstellungen protokollieren unix:/sock/sidecar.sock anstelle von localhost:50051.

  2. 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:50051
    

    Prüfen Sie, ob der Container pathways-worker den 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 Arbeitsspeicher emptyDir im entsprechenden Pfad (/tmp/sidecar oder /tmp/shared-memory) sowohl im Container pathways-worker als auch im Container colocated-python-sidecar bereit.
  • Timed out connecting to sidecar gRPC service oder Failed to connect to external sidecar: Prüfen Sie, ob der Container colocated-python-sidecar im Feld initContainers mit restartPolicy: Always ausgeführt wird und ob alle drei cloud-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 Containern pathways-proxy und colocated-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=0 für den Container colocated-python-sidecar (zusammen mit dem Flag --port=50051 oder --unix_domain_socket_path) und das Flag --cloud_pathways_shared_memory_idle_release_secs=0 für den Container pathways-worker. Wenn Sie beide Flags auf 0 setzen, 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 die JobSet-Ressource:

    kubectl delete jobset JOBSET_NAME
    

    Ersetzen Sie JOBSET_NAME durch den metadata.name-Wert Ihres JobSet.

  • Cluster Toolkit: Brechen Sie den bereitgestellten Job ab:

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

    Ersetzen 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