Esegui Python in co-locazione con Pathways

Per evitare di instradare il lavoro associato all'host, come il caricamento dei dati e il checkpoint, tramite un singolo controller Pathways su Google Kubernetes Engine (GKE), esegui queste funzioni sulle VM worker di Cloud TPU utilizzando l'API Python JAX collocata.

Questo documento, rivolto ai machine learning engineer, descrive come Python collocato funziona con Pathways. Scopri come creare, eseguire il deployment e verificare un container sidecar con un manifest JobSet o Cluster Toolkit.

Prima di iniziare

Completa i seguenti prerequisiti:

Ruoli obbligatori

Concedi i seguenti ruoli Identity and Access Management (IAM):

  • Il tuo account utente:
    • Artifact Registry Writer (roles/artifactregistry.writer) sul tuo progetto Google Cloud per eseguire il push delle immagini sidecar personalizzate in Artifact Registry.
    • Sviluppatore Kubernetes Engine (roles/container.developer) nel tuo progetto Google Cloud per eseguire il deployment delle risorse JobSet, inoltrare le porte e leggere i log dei pod su GKE.
  • Service account del pool di nodi GKE: i pod Pathways utilizzano questo account di servizio quando i node pool utilizzano il flag --workload-metadata=GCE_METADATA, come configurato in Crea un cluster GKE con Pathways:
    • Artifact Registry Reader (roles/artifactregistry.reader) sul progetto Google Cloud che ospita il tuo repository privato per eseguire il pull delle immagini sidecar personalizzate.
    • Storage Object Admin (roles/storage.objectAdmin) sul bucket di archiviazione temporanea di Cloud Storage per la cache di compilazione e altri file temporanei.

(Facoltativo) Per consentire al container del gestore delle risorse Pathways (pathways-rm) di aggiungere una regola del ciclo di vita del bucket che fa scadere le voci della cache di compilazione precedenti, concedi anche il ruolo Storage Admin (roles/storage.admin) sul bucket temporaneo. Senza questo ruolo, il container pathways-rm registra un avviso e continua a utilizzare la cache. Per saltare l'aggiornamento del ciclo di vita, passa il flag --enable_gcs_olm=false al container pathways-rm.

Se i tuoi node pool utilizzano Workload Identity Federation for GKE, concedi il ruolo di bucket temporaneo al account di servizio Kubernetes utilizzato dai pod Pathways o al account di servizio IAM associato. Per impostazione predefinita, i pod Pathways utilizzano il account di servizio default, a meno che il manifest JobSet non imposti il campo serviceAccountName. Mantieni il ruolo Artifact Registry Reader nel account di servizio del node pool.

Come funziona Python in co-locazione con Pathways

In Pathways, lo script del controller JAX viene eseguito su un singolo host CPU, mentre i pod dei worker Cloud TPU eseguono il container C++ pathways-worker. Per eseguire funzioni @colocated_python e metodi @colocated_python_class sugli host worker, Python collocato utilizza i seguenti componenti:

  • Il tuo controller JAX: utilizza il modulo jax.experimental.colocated_python per accoppiare ogni chip Cloud TPU con un dispositivo CPU host e serializzare la funzione Python e i metadati del tipo con la libreria cloudpickle.
  • Il container pathways-proxy (nel pod pathways-head): riceve la funzione serializzata tramite gRPC e la indirizza al container pathways-worker sulle VM worker proprietarie dei dispositivi CPU di input della chiamata. Se passi il flag --sidecar_name=external, il container pathways-proxy viene configurato in modo da avere come target il container colocated-python-sidecar.
  • Il container pathways-worker (su ogni pod worker): carica la funzione serializzata nel container sidecar locale, attiva l'esecuzione su gRPC locale e scambia i buffer di array tramite un volume emptyDir in memoria condiviso (medium: Memory).
  • Il container colocated-python-sidecar (su ogni pod worker): decomprime ed esegue la funzione in un runtime Python 3.12 isolato una volta per VM negli shard locali della VM, scrivendo gli array di output direttamente nella memoria host condivisa.

Per saperne di più sull'architettura di Pathways, consulta Componenti di Pathways.

Flusso di esecuzione

Quando richiami una funzione decorata, Pathways la esegue nel cluster in due fasi:

  1. Routing delle funzioni: il modulo jax.experimental.colocated_python pacchettizza la funzione in un programma Interim Framework Runtime (IFRT) e lo invia al container pathways-proxy. Il proxy inoltra il programma solo alle VM worker che contengono gli shard di input, eseguendolo una volta per VM su tutti gli shard locali.
  2. Esecuzione della memoria condivisa: il container pathways-worker scrive gli shard di input nel volume condiviso in memoria (/tmp/sidecar o /tmp/shared-memory) e richiama il container colocated-python-sidecar tramite TCP di loopback (localhost:50051) o un socket di dominio Unix (/sock/sidecar.sock). Gli array di output vengono restituiti tramite la memoria condivisa senza copie gRPC e vengono spostati direttamente nella memoria ad alta larghezza di banda (HBM) di Cloud TPU quando vengono posizionati sui dispositivi Cloud TPU.

Per l'utilizzo dell'API JAX, ad esempio per scoprire i dispositivi CPU in co-locazione e dichiarare le specifiche di output per l'invio asincrono, consulta la guida di Python in co-locazione con JAX.

Linee guida per il layout

Quando scrivi funzioni Python collocate, segui queste linee guida:

  • Riduci al minimo le variabili acquisite: passa i dati degli array come argomenti jax.Array frammentati anziché acquisire array di grandi dimensioni o oggetti non serializzabili (come file aperti o client di rete) nelle chiusure. Apri file o client all'interno di un'istanza @colocated_python_class sul worker.
  • Ricrea lo stato di @colocated_python_class dopo i riavvii: gli oggetti sidecar stateful vengono mantenuti in memoria tra i passaggi, ma non vengono salvati automaticamente se un pod worker si riavvia o se il numero di sezioni cambia durante l'addestramento elastico. Ricrea gli oggetti stateful da un checkpoint dopo la scalabilità o i riavvii.

Immagini e tag predefiniti

Google Cloud pubblica immagini Pathways predefinite in un repository Artifact Registry pubblico:

  • Sidecar Python in co-location: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Pathways resource manager and worker: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • Server proxy IFRT: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

Utilizza tag corrispondenti nelle immagini server, proxy_server e colocated_python_sidecar.

Le immagini sidecar predefinite supportano le versioni JAX 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0 e 0.12.0.1. Sostituisci TAG con uno dei seguenti formati di tag:

  • jax-JAX_VERSION (consigliato): un tag in sequenza per una release JAX specifica, ad esempio jax-0.12.0.1.
  • YYYYMMDD-jax_JAX_VERSION: un tag di build con data, ad esempio 20261110-jax_0.12.0.1.

Se hai bisogno di una versione immagine esatta che non cambia mai, blocca l'immagine in base al digest SHA-256. Per cercare un digest dell'immagine, utilizza il comando 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)"

Sostituisci JAX_VERSION con la tua versione di JAX, ad esempio 0.12.0.1.

Crea un'immagine sidecar personalizzata

L'immagine sidecar predefinita include i pacchetti jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle e absl-py. Se le tue funzioni Python collocate utilizzano solo questi pacchetti, vai a Esegui il deployment di un JobSet Pathways con il sidecar o Esegui il deployment con Cluster Toolkit.

Per aggiungere dipendenze Python personalizzate, aggiungile all'immagine predefinita corrispondente alla tua versione di JAX:

  1. In una directory di build vuota, crea un file requirements.txt per i pacchetti aggiuntivi. Ometti i pacchetti jax e jaxlib, che sono già installati e bloccati nel file /opt/venv/server_constraints.txt:

    grain
    
  2. Crea un Dockerfile che installi i pacchetti nel file requirements.txt, vincolato dal file /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
    

    Lascia invariate le istruzioni ENTRYPOINT e CMD dell'immagine di base. Se il file requirements.txt installa pacchetti da URL Git, aggiungi la seguente istruzione RUN prima dell'istruzione uv pip install RUN, perché l'immagine di base slim omette lo strumento git:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Autentica Docker nella regione di Artifact Registry utilizzando il comando gcloud auth configure-docker:

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

    Sostituisci REGISTRY_LOCATION con la località di Artifact Registry, ad esempio us o us-central1.

  4. Crea ed esegui il push dell'immagine sidecar personalizzata:

    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}"
    

    Sostituisci quanto segue:

    • JAX_VERSION: la tua versione di JAX, ad esempio 0.12.0.1.
    • REGISTRY_LOCATION: la tua località di Artifact Registry, ad esempio us o us-central1.
    • PROJECT_ID: il tuo ID progettoGoogle Cloud .
    • REPOSITORY: il nome del tuo repository Docker Artifact Registry.

Esegui il deployment di un JobSet Pathways con il sidecar

Puoi eseguire il deployment di Pathways con il sidecar applicando un manifest JobSet con lo strumento a riga di comando kubectl in questa sezione o inviando il job direttamente con l'interfaccia a riga di comando gcluster in Esegui il deployment con Cluster Toolkit.

Per generare e applicare un manifest JobSet, completa i seguenti passaggi:

  1. Genera un manifest JobSet (pathways-colocated-jobset.yaml) con uno dei seguenti strumenti:

    • Builder Python pathways-utils: configura un JobSet con il builder PathwaysJobSet chiamando i metodi .add_colocated_python("SIDECAR_IMAGE") e .export_yaml("pathways-colocated-jobset.yaml"). Se utilizzi il pacchetto pathwaysutils (versione 0.1.14 o precedente di PyPI), passa anche l'argomento proxy_container_kwargs={"args": ["--sidecar_name=external"]} al costruttore PathwaysJobSet o installa il pacchetto pathways-utils dal ramo main.
    • Cluster Toolkit (gcluster): esegui il comando gcluster job submit con il flag --pathways-colocated-python-sidecar-image e aggiungi il flag --dry-run-out=pathways-colocated-jobset.yaml per eseguire il rendering del manifest localmente senza inviare il job.

    Sostituisci SIDECAR_IMAGE con l'URI dell'immagine sidecar personalizzata o con l'URI dell'immagine colocated_python_sidecar predefinita.

    Entrambi i generatori configurano il manifest per eseguire le seguenti operazioni:

    • Esegui il container colocated-python-sidecar nel campo initContainers con restartPolicy: Always in ogni pod worker. La CLI gcluster assegna al job replicato del worker il nome worker, mentre il builder PathwaysJobSet lo chiama pathways-worker.
    • Passa il flag --sidecar_name=external al container pathways-proxy e connetti il container pathways-worker al sidecar tramite TCP di loopback su localhost:50051. Quando il container pathways-proxy viene eseguito nel campo initContainers, utilizza anche restartPolicy: Always.
    • Monta un volume emptyDir in memoria con medium: Memory in entrambi i container dei pod worker: in /tmp/sidecar nei manifest gcluster o in /tmp/shared-memory nei manifest PathwaysJobSet. Entrambi i generatori impostano anche la variabile di ambiente CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY sul sidecar e il flag --cloud_pathways_sidecar_shm_directory sul container pathways-worker.
  2. Applica il manifest JobSet e attendi che i pod raggiungano lo stato Running:

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

    Sostituisci JOBSET_NAME con il valore metadata.name di JobSet.

Esegui una sessione client JAX per deployment JobSet. Dopo la disconnessione di un client, un container pathways-worker riavviato non può riutilizzare un sidecar in esecuzione. Elimina e ricrea JobSet prima di avviare un'altra sessione.

I file in un volume emptyDir in memoria vengono conteggiati ai fini della memoria utilizzata dal pod. Imposta il campo emptyDir.sizeLimit (ad esempio 175Gi) sul volume di memoria condivisa per limitare l'utilizzo per nodo. Per impostazione predefinita, entrambi i container conservano la memoria condivisa liberata per 30 secondi di inattività per il riutilizzo. Per modificare questa finestra, imposta sia il flag --pathways_sidecar_shared_memory_idle_release_secs=SECONDS nel campo args del container colocated-python-sidecar (insieme al flag --port=50051 o --unix_domain_socket_path) sia il flag --cloud_pathways_shared_memory_idle_release_secs=SECONDS nel campo args del container pathways-worker. Sostituisci SECONDS con il timeout di inattività in secondi. L'impostazione di entrambi i flag su 0 rilascia le pagine liberate entro circa 1 secondo, il che riduce la memoria utilizzata a scapito di un overhead di allocazione aggiuntivo.

(Facoltativo) Utilizza un socket di dominio Unix

Per utilizzare un socket di dominio Unix (UDS) in /sock/sidecar.sock anziché aprire una porta TCP sui pod worker che impostano hostNetwork: true, applica i seguenti override al manifest JobSet prima di eseguire il comando kubectl apply:

  • Monta un volume emptyDir: {} denominato sidecar-socket in /sock sia nel container pathways-worker sia nel container colocated-python-sidecar.
  • Imposta args: ["--unix_domain_socket_path=/sock/sidecar.sock"] e un exec startupProbe (test -S /sock/sidecar.sock) sul container colocated-python-sidecar.
  • Aggiungi il flag --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock al campo args del container pathways-proxy.

Esegui il deployment con Cluster Toolkit

In Cluster Toolkit (gcluster versione 1.108.0 o successive), il passaggio del flag --pathways-colocated-python-sidecar-image al comando gcluster job submit configura il container colocated-python-sidecar su TCP di loopback (localhost:50051), monta il volume in memoria in /tmp/sidecar e imposta il flag --sidecar_name=external. Passa esplicitamente i flag --pathways-server-image e --pathways-proxy-server-image in modo che tutte e tre le immagini utilizzino tag cloud-pathways corrispondenti.

Invia un deployment Pathways headless con l'immagine sidecar in modo da poter eseguire script client interattivi:

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

Sostituisci quanto segue:

  • BUCKET_NAME: il tuo bucket temporaneo Cloud Storage.
  • JAX_VERSION: la tua versione di JAX, ad esempio 0.12.0.1.
  • SIDECAR_IMAGE: l'URI dell'immagine sidecar personalizzata o predefinita.
  • WORKLOAD: un nome JobSet univoco (massimo 22 caratteri).
  • CLUSTER: il nome del tuo cluster GKE.
  • PROJECT_ID: il tuo ID progettoGoogle Cloud .
  • LOCATION: la regione o la zona del tuo cluster GKE.
  • WORKLOAD_NODEPOOL_COUNT: il numero di sezioni Cloud TPU, ad esempio 1.
  • COMPUTE_TYPE: il tipo di macchina Cloud TPU, ad esempio ct5lp-hightpu-4t o ct6e-standard-4t.
  • TOPOLOGY: la topologia della sezione Cloud TPU, ad esempio 4x8 o 2x4.

Puoi anche personalizzare il modo in cui il comando gcluster job submit esegue o esporta il job:

  • Workload batch: per eseguire un job batch containerizzato all'interno del pod pathways-head anziché un deployment headless, sostituisci il flag --pathways-headless con i flag --image="CLIENT_IMAGE" e --command="COMMAND". Utilizza un'immagine client JAX Python 3.12 creata con i pin server_constraints.txt e passa il comando di immissione (ad esempio python colocated_example.py).
  • Rendering del manifest locale: aggiungi il flag --dry-run-out=pathways-colocated-jobset.yaml per eseguire il rendering del manifest JobSet localmente senza inviarlo.
  • Sessioni headless successive: esegui il comando gcluster job cancel e invia nuovamente il job prima di avviare un'altra sessione client.

Esegui un workload Python collocato

Esegui lo script client JAX con la variabile di ambiente JAX_PLATFORMS=proxy sul container pathways-proxy, nel container del workload pathways-head o tramite il port forwarding:

  1. Per allineare le dipendenze di serializzazione con l'immagine sidecar, estrai il file /opt/venv/server_constraints.txt e installa i pacchetti corrispondenti in un ambiente virtuale 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
    

    Sostituisci JAX_VERSION con la tua versione di JAX, ad esempio 0.12.0.1.

  2. Se esegui il client all'esterno del pod pathways-head, inoltra la porta locale 29000 al container pathways-proxy in un terminale separato:

    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
    

    Sostituisci JOBSET_NAME con il valore metadata.name di JobSet (o il nome WORKLOAD che hai passato al comando gcluster job submit).

  3. Salva il seguente script come colocated_example.py. Questo script alloca un array NumPy da 4 MiB nella memoria host condivisa sul dispositivo CPU collocato di ogni worker Cloud TPU e lo trasferisce all'HBM di Cloud TPU:

    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. Esegui lo script sul server proxy IFRT:

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

    L'output è simile al seguente:

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

    Nei workload di produzione multislice, passa un argomento jax.Array con sharding posizionato sui dispositivi restituiti dalla chiamata colocated_python.colocated_cpu_devices(mesh) e imposta il parametro out_specs_fn con il metodo .specialize(out_specs_fn=...) in modo che Pathways esegua una chiamata parallela su tutti i sidecar dei worker senza attendere.

    Non eseguire script client all'interno di un pod worker con la variabile di ambiente JAX_PLATFORMS=cpu, perché questa impostazione esegue JAX localmente su una CPU e ignora Pathways. Puoi ignorare qualsiasi messaggio IFRT proxy server disconnected: CANCELLED stampato all'uscita.

Per ulteriori pattern di utilizzo, consulta le seguenti risorse:

Verifica il deployment del sidecar

Esegui il comando kubectl logs su un JobSet headless prima di annullarlo o eliminarlo o mentre un workload batch è ancora in esecuzione. Nei deployment batch JobSet, il controller JobSet elimina i pod worker non appena il job pathways-head viene completato. Visualizza i log dei batch completati in Cloud Logging, come descritto in Risolvi i problemi di Pathways su Cloud.

Per verificare un deployment in esecuzione con lo strumento a riga di comando kubectl, completa i seguenti passaggi:

  1. Esamina i log del container 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
    

    Sostituisci JOBSET_NAME con il valore metadata.name di JobSet (o il nome WORKLOAD che hai passato al comando gcluster job submit). Se hai generato il manifest con il builder PathwaysJobSet, imposta replicatedjob-name=pathways-worker nella variabile ROLE_LABEL.

    L'output è simile al seguente:

    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
    

    Verifica che l'output mostri il messaggio di avvio di gRPC e, dopo la prima chiamata @colocated_python, il messaggio dell'allocatore della memoria condivisa. I manifest generati con il builder PathwaysJobSet utilizzano la directory /tmp/shared-memory e i deployment UDS registrano unix:/sock/sidecar.sock anziché localhost:50051.

  2. Esamina i log del container pathways-worker nello stesso pod:

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

    L'output è simile al seguente:

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

    Verifica che il container pathways-worker abbia attivato la memoria condivisa e sia connesso al sidecar.

Quando esegui il comando kubectl exec per ispezionare la directory della memoria condivisa, scegli come target il container colocated-python-sidecar con il flag -c colocated-python-sidecar, perché il container pathways-worker non include una shell.

Risolvi i problemi relativi a Python in co-locazione

Le sezioni seguenti descrivono come risolvere i problemi comuni di Python in co-locazione.

Unable to unpickle errore

Se il workload non riesce con il seguente errore, le versioni di Python o dei pacchetti differiscono tra il client JAX e il container sidecar:

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

Verifica che il client esegua Python 3.12 (python --version) e installa i pacchetti client con il flag -c constraints.txt estratto dall'immagine sidecar. Per saperne di più, consulta Esegui un workload Python in co-locazione.

Conflitto di dipendenze durante un'esecuzione di docker build

Se il comando uv pip install non va a buon fine con l'errore No solution found when resolving dependencies, un pin nel file requirements.txt è in conflitto con il file /opt/venv/server_constraints.txt. Rimuovi i pacchetti jax e jaxlib dal file requirements.txt e allenta i blocchi delle versioni su pacchetti come numpy, ml-dtypes o scipy.

Errore Sidecar non abilitato

Se il container pathways-proxy si chiude con l'errore Sidecar create args were set, but sidecar was not enabled, aggiungi il flag --sidecar_name=external al campo args del container pathways-proxy.

Sidecar already initialized errore

Se il workload non va a buon fine con l'errore FAILED_PRECONDITION: Sidecar already initialized, una disconnessione precedente del client ha riavviato il container pathways-worker mentre il container colocated-python-sidecar è rimasto inizializzato. Elimina e ricrea JobSet prima di avviare un'altra sessione client.

Errori di connessione alla memoria condivisa o al sidecar

Utilizza i seguenti controlli per risolvere gli errori di montaggio della memoria condivisa, di connessione gRPC o di memoria host:

  • Failed to stat sidecar_shm_directory: monta il volume di memoria condivisa emptyDir nel percorso corrispondente (/tmp/sidecar o /tmp/shared-memory) sia nel container pathways-worker sia nel container colocated-python-sidecar.
  • Timed out connecting to sidecar gRPC service o Failed to connect to external sidecar: verifica che il container colocated-python-sidecar venga eseguito nel campo initContainers con restartPolicy: Always e che tutte e tre le immagini cloud-pathways utilizzino tag corrispondenti. Verifica che le impostazioni TCP (--port=50051) o UDS (volume /sock e --unix_domain_socket_path=/sock/sidecar.sock) corrispondano tra i container pathways-proxy e colocated-python-sidecar.
  • Memoria esaurita dell'host worker dopo burst di array di grandi dimensioni: imposta il flag --pathways_sidecar_shared_memory_idle_release_secs=0 sul container colocated-python-sidecar (insieme al flag --port=50051 o --unix_domain_socket_path) e il flag --cloud_pathways_shared_memory_idle_release_secs=0 sul container pathways-worker. L'impostazione di entrambi i flag su 0 libera la memoria condivisa inutilizzata entro circa 1 secondo. In alternativa, riduci la quantità massima di dati dell'array host che il workload conserva in memoria contemporaneamente.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo documento, elimina il deployment e gli artefatti temporanei al termine:

  • Manifest JobSet: elimina la risorsa JobSet:

    kubectl delete jobset JOBSET_NAME
    

    Sostituisci JOBSET_NAME con il valore metadata.name di JobSet.

  • Cluster Toolkit: annulla il job di cui è stato eseguito il deployment:

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

    Sostituisci quanto segue:

    • WORKLOAD: il nome del tuo job Pathways.
    • CLUSTER: il nome del tuo cluster GKE.
    • PROJECT_ID: il tuo ID progettoGoogle Cloud .
    • LOCATION: la regione o la zona del tuo cluster GKE.

(Facoltativo) Elimina le immagini sidecar personalizzate in Artifact Registry e rimuovi gli oggetti temporanei nel bucket temporaneo di Cloud Storage. Quando non hai più bisogno del cluster GKE, eliminalo seguendo i passaggi di pulizia descritti in Crea un cluster GKE con Pathways.

Passaggi successivi