Ejecuta Python coubicado con Pathways

Para evitar enrutar el trabajo vinculado al host, como la carga de datos y la creación de puntos de control, a través de un solo controlador de Pathways en Google Kubernetes Engine (GKE), ejecuta esas funciones en tus VMs de trabajador de Cloud TPU con la API de Python de JAX ubicada en el mismo lugar.

En este documento, que está dirigido a ingenieros de aprendizaje automático, se describe cómo funciona Python coubicado con Pathways. Aprenderás a compilar, implementar y verificar un contenedor sidecar con un manifiesto de JobSet o el Cluster Toolkit.

Antes de comenzar

Completa los siguientes requisitos previos:

Roles obligatorios

Otorga los siguientes roles de Identity and Access Management (IAM):

  • Tu cuenta de usuario:
    • Escritor de Artifact Registry (roles/artifactregistry.writer) en tu proyecto de Google Cloud para enviar imágenes de archivo de ayuda personalizadas a Artifact Registry.
    • Desarrollador de Kubernetes Engine (roles/container.developer) en tu proyecto de Google Cloud para implementar recursos deJobSet, reenviar puertos y leer registros de Pods en GKE.
  • Cuenta de servicio del grupo de nodos de GKE: Los Pods de Pathways usan esta cuenta de servicio cuando tus grupos de nodos usan la marca --workload-metadata=GCE_METADATA, como se configura en Crea un clúster de GKE con Pathways:
    • Lector de Artifact Registry (roles/artifactregistry.reader) en el proyecto de Google Cloud que aloja tu repositorio privado para extraer imágenes de sidecar personalizadas.
    • Administrador de objetos de almacenamiento (roles/storage.objectAdmin) en tu bucket temporal de Cloud Storage para la caché de compilación y otros archivos temporales.

Opcional: Para permitir que el contenedor del administrador de recursos de Pathways (pathways-rm) agregue una regla de ciclo de vida del bucket que venza las entradas de caché de compilación antiguas, otorga también el rol de Administrador de almacenamiento (roles/storage.admin) en el bucket temporal. Sin este rol, el contenedor de pathways-rm registra una advertencia y sigue usando la caché. Para omitir la actualización del ciclo de vida, pasa la marca --enable_gcs_olm=false al contenedor pathways-rm.

Si tus grupos de nodos usan Workload Identity Federation for GKE, otorga el rol de bucket temporal a la cuenta de servicio de Kubernetes que usan los Pods de Pathways o a su cuenta de servicio de IAM vinculada. De forma predeterminada, los Pods de Pathways usan la cuenta de servicio default, a menos que el manifiesto de JobSet establezca el campo serviceAccountName. Mantén el rol de lector de Artifact Registry en la cuenta de servicio del grupo de nodos.

Cómo funciona Python coubicado con Pathways

En Pathways, la secuencia de comandos del controlador de JAX se ejecuta en un solo host de CPU, mientras que los Pods de trabajadores de Cloud TPU ejecutan el contenedor de C++ pathways-worker. Para ejecutar funciones de @colocated_python y métodos de @colocated_python_class en hosts de trabajadores, Python ubicado en el mismo lugar usa los siguientes componentes:

  • Tu controlador de JAX: Usa el módulo jax.experimental.colocated_python para vincular cada chip de Cloud TPU con un dispositivo de CPU host y serializar tu función de Python y los metadatos de tipo con la biblioteca cloudpickle.
  • El contenedor pathways-proxy (en el Pod pathways-head): Recibe la función serializada a través de gRPC y la enruta al contenedor pathways-worker en las VMs de trabajador que poseen los dispositivos de CPU de entrada de la llamada. Cuando pasas la marca --sidecar_name=external, se configura el contenedor pathways-proxy para que se oriente al contenedor colocated-python-sidecar.
  • El contenedor pathways-worker (en cada Pod de trabajador): Carga la función serializada en el contenedor sidecar local, activa la ejecución a través de gRPC local e intercambia búferes de arrays a través de un volumen emptyDir compartido en la memoria (medium: Memory).
  • El contenedor colocated-python-sidecar (en cada Pod de trabajador): Desempaqueta y ejecuta la función en un entorno de ejecución aislado de Python 3.12 una vez por VM en los fragmentos locales de esa VM, escribiendo los arrays de salida directamente en la memoria del host compartida.

Para obtener más información sobre la arquitectura de Pathways, consulta Componentes de Pathways.

Flujo de ejecución

Cuando invocas una función decorada, Pathways la ejecuta en todo el clúster en dos etapas:

  1. Enrutamiento de funciones: El módulo jax.experimental.colocated_python empaqueta la función en un programa de entorno de ejecución de framework intermedio (IFRT) y lo envía al contenedor pathways-proxy. El proxy reenvía el programa solo a las VMs de trabajador que contienen los fragmentos de entrada y se ejecuta una vez por VM en todos los fragmentos locales.
  2. Ejecución de memoria compartida: El contenedor pathways-worker escribe fragmentos de entrada en el volumen compartido en la memoria (/tmp/sidecar o /tmp/shared-memory) y, luego, invoca el contenedor colocated-python-sidecar a través de TCP de bucle invertido (localhost:50051) o un socket de dominio de Unix (/sock/sidecar.sock). Los arrays de salida se devuelven a través de la memoria compartida sin copias de gRPC y se mueven directamente a la memoria de gran ancho de banda (HBM) de Cloud TPU cuando se colocan en dispositivos de Cloud TPU.

Para conocer el uso de la API de JAX, como descubrir dispositivos de CPU ubicados en el mismo lugar y declarar especificaciones de salida para el envío asíncrono, consulta la guía de Python de JAX ubicado en el mismo lugar.

Lineamientos de diseño

Cuando escribas funciones de Python coubicadas, sigue estos lineamientos:

  • Minimiza las variables capturadas: Pasa los datos del array como argumentos jax.Array fragmentados en lugar de capturar arrays grandes o objetos no serializables (como archivos abiertos o clientes de red) en cierres. Abrir archivos o clientes dentro de una instancia de @colocated_python_class en el trabajador
  • Vuelve a crear el estado de @colocated_python_class después de los reinicios: Los objetos de sidecar con estado persisten en los pasos de la memoria, pero no se guardan automáticamente si se reinicia un Pod de trabajador o si cambian los recuentos de porciones durante el entrenamiento elástico. Vuelve a crear objetos con estado a partir de un punto de control después de cambiar el escalamiento o reiniciar.

Imágenes y etiquetas compiladas previamente

Google Cloud publica imágenes de Pathways compiladas previamente en un repositorio público de Artifact Registry:

  • Sidecar de Python ubicado en el mismo lugar: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Administrador de recursos y trabajador de Pathways: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • Servidor proxy de IFRT: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

Usa etiquetas que coincidan en las imágenes server, proxy_server y colocated_python_sidecar.

Las imágenes de archivo de complemento precompiladas admiten las versiones de JAX 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0 y 0.12.0.1. Reemplaza TAG por uno de los siguientes formatos de etiqueta:

  • jax-JAX_VERSION (recomendado): Es una etiqueta progresiva para una versión específica de JAX, como jax-0.12.0.1.
  • YYYYMMDD-jax_JAX_VERSION: es una etiqueta de compilación con marca de fecha, como 20261110-jax_0.12.0.1.

Si necesitas una versión de imagen exacta que nunca cambie, fija la imagen por su resumen SHA-256. Para buscar un resumen de imagen, usa el 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)"

Reemplaza JAX_VERSION por tu versión de JAX, como 0.12.0.1.

Compila una imagen de archivo adicional personalizada

La imagen de sidecar compilada previamente incluye los paquetes jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle y absl-py. Si tus funciones de Python ubicadas en el mismo lugar solo usan estos paquetes, ve a Implementa un JobSet de Pathways con el archivo adicional o Implementa con Cluster Toolkit.

Para agregar dependencias de Python personalizadas, colócalas en capas sobre la imagen compilada previamente que coincida con tu versión de JAX:

  1. En un directorio de compilación vacío, crea un archivo requirements.txt para tus paquetes adicionales. Omite los paquetes jax y jaxlib, que ya están instalados y fijados en el archivo /opt/venv/server_constraints.txt:

    grain
    
  2. Crea un Dockerfile que instale los paquetes en el archivo requirements.txt, restringido por el archivo /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
    

    Mantén sin cambios las instrucciones ENTRYPOINT y CMD de la imagen base. Si el archivo requirements.txt instala paquetes desde URLs de Git, agrega la siguiente instrucción RUN antes de la instrucción uv pip install RUN, ya que la imagen base slim omite la herramienta git:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Autentica Docker en tu región de Artifact Registry con el comando gcloud auth configure-docker:

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

    Reemplaza REGISTRY_LOCATION por la ubicación de Artifact Registry, como us o us-central1.

  4. Compila y envía tu imagen de archivo adicional personalizada:

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

    Reemplaza lo siguiente:

    • JAX_VERSION: Es tu versión de JAX, como 0.12.0.1.
    • REGISTRY_LOCATION: Es tu ubicación de Artifact Registry, como us o us-central1.
    • PROJECT_ID: Es el ID del proyecto deGoogle Cloud .
    • REPOSITORY: Es el nombre de tu repositorio de Docker de Artifact Registry.

Implementa un JobSet de Pathways con el sidecar

Puedes implementar Pathways con el archivo adicional aplicando un manifiesto JobSet con la herramienta de línea de comandos kubectl en esta sección o enviando el trabajo directamente con la CLI de gcluster en Implementa con Cluster Toolkit.

Para generar y aplicar un manifiesto de JobSet, completa los siguientes pasos:

  1. Genera un manifiesto JobSet (pathways-colocated-jobset.yaml) con cualquiera de las siguientes herramientas:

    • El compilador de Python pathways-utils: Configura un JobSet con el compilador PathwaysJobSet llamando a los métodos .add_colocated_python("SIDECAR_IMAGE") y .export_yaml("pathways-colocated-jobset.yaml"). Si usas el paquete pathwaysutils (versión 0.1.14 o anterior de PyPI), también pasa el argumento proxy_container_kwargs={"args": ["--sidecar_name=external"]} al constructor PathwaysJobSet o instala el paquete pathways-utils desde la rama main.
    • Cluster Toolkit (gcluster): Ejecuta el comando gcluster job submit con la marca --pathways-colocated-python-sidecar-image y agrega la marca --dry-run-out=pathways-colocated-jobset.yaml para renderizar el manifiesto de forma local sin enviar el trabajo.

    Reemplaza SIDECAR_IMAGE por el URI de la imagen de sidecar personalizada o el URI de la imagen colocated_python_sidecar compilada previamente.

    Ambos generadores configuran el manifiesto para que realice las siguientes acciones:

    • Ejecuta el contenedor colocated-python-sidecar en el campo initContainers con restartPolicy: Always en cada Pod de trabajador. La CLI de gcluster asigna el nombre worker al trabajo replicado del trabajador, mientras que el compilador de PathwaysJobSet le asigna el nombre pathways-worker.
    • Pasa la marca --sidecar_name=external al contenedor pathways-proxy y conecta el contenedor pathways-worker al archivo adicional a través de TCP de bucle invertido en localhost:50051. Cuando el contenedor pathways-proxy se ejecuta en el campo initContainers, también usa restartPolicy: Always.
    • Activa un volumen emptyDir en memoria con medium: Memory en ambos contenedores de Pods de trabajador: en /tmp/sidecar en manifiestos de gcluster o en /tmp/shared-memory en manifiestos de PathwaysJobSet. Ambos generadores también establecen la variable de entorno CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY en el archivo adicional y la marca --cloud_pathways_sidecar_shm_directory en el contenedor pathways-worker.
  2. Aplica el manifiesto JobSet y espera a que los Pods alcancen el estado Running:

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

    Reemplaza JOBSET_NAME por el valor de metadata.name de tu JobSet.

Ejecuta una sesión de cliente de JAX por implementación de JobSet. Después de que un cliente se desconecta, un contenedor pathways-worker reiniciado no puede volver a usar un archivo de complemento en ejecución. Borra y vuelve a crear el JobSet antes de iniciar otra sesión.

Los archivos de un volumen emptyDir en la memoria se tienen en cuenta para el uso de memoria del Pod. Establece el campo emptyDir.sizeLimit (como 175Gi) en el volumen de memoria compartida para limitar el uso por nodo. De forma predeterminada, ambos contenedores retienen la memoria compartida liberada durante 30 segundos de tiempo de inactividad para su reutilización. Para cambiar esa ventana, establece la marca --pathways_sidecar_shared_memory_idle_release_secs=SECONDS en el campo args del contenedor colocated-python-sidecar (junto con la marca --port=50051 o --unix_domain_socket_path) y la marca --cloud_pathways_shared_memory_idle_release_secs=SECONDS en el campo args del contenedor pathways-worker. Reemplaza SECONDS por el tiempo de espera de inactividad en segundos. Si configuras ambas marcas como 0, se liberarán las páginas liberadas en aproximadamente 1 segundo, lo que reduce el uso de memoria a costa de una sobrecarga de asignación adicional.

Opcional: Usa un socket de dominio Unix

Para usar un socket de dominio Unix (UDS) en /sock/sidecar.sock en lugar de abrir un puerto TCP en los Pods de trabajador que configuran hostNetwork: true, aplica las siguientes anulaciones a tu manifiesto de JobSet antes de ejecutar el comando kubectl apply:

  • Activa un volumen emptyDir: {} llamado sidecar-socket en /sock en los contenedores pathways-worker y colocated-python-sidecar.
  • Establece args: ["--unix_domain_socket_path=/sock/sidecar.sock"] y un exec startupProbe (test -S /sock/sidecar.sock) en el contenedor colocated-python-sidecar.
  • Agrega la marca --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock al campo args del contenedor pathways-proxy.

Implementa con Cluster Toolkit

En Cluster Toolkit (versión gcluster 1.108.0 o posterior), pasar la marca --pathways-colocated-python-sidecar-image al comando gcluster job submit configura el contenedor colocated-python-sidecar en TCP de bucle invertido (localhost:50051), activa el volumen en la memoria en /tmp/sidecar y establece la marca --sidecar_name=external. Pasa las marcas --pathways-server-image y --pathways-proxy-server-image de forma explícita para que las tres imágenes usen etiquetas cloud-pathways que coincidan.

Envía una implementación de Pathways sin interfaz gráfica con tu imagen de archivo adicional para que puedas ejecutar secuencias de comandos interactivas del cliente en ella:

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

Reemplaza lo siguiente:

  • BUCKET_NAME: Es tu bucket temporal de Cloud Storage.
  • JAX_VERSION: Es tu versión de JAX, como 0.12.0.1.
  • SIDECAR_IMAGE: Es el URI de la imagen de sidecar personalizada o precompilada.
  • WORKLOAD: un nombre único de JobSet (22 caracteres o menos).
  • CLUSTER: Es el nombre de tu clúster de GKE.
  • PROJECT_ID: Es el ID del proyecto deGoogle Cloud .
  • LOCATION: Es la región o zona del clúster de GKE.
  • WORKLOAD_NODEPOOL_COUNT: Es la cantidad de porciones de Cloud TPU, como 1.
  • COMPUTE_TYPE: Es el tipo de máquina de Cloud TPU, como ct5lp-hightpu-4t o ct6e-standard-4t.
  • TOPOLOGY: Es la topología de la porción de Cloud TPU, como 4x8 o 2x4.

También puedes personalizar cómo el comando gcluster job submit ejecuta o exporta el trabajo:

  • Cargas de trabajo por lotes: Para ejecutar un trabajo por lotes alojado en contenedores dentro del Pod de pathways-head en lugar de una implementación sin interfaz gráfica, reemplaza la marca --pathways-headless por las marcas --image="CLIENT_IMAGE" y --command="COMMAND". Usa una imagen de cliente de JAX de Python 3.12 compilada con fijaciones de server_constraints.txt y pasa tu comando de entrada (como python colocated_example.py).
  • Renderización del manifiesto local: Agrega la marca --dry-run-out=pathways-colocated-jobset.yaml para renderizar el manifiesto de JobSet de forma local sin enviarlo.
  • Sesiones sin interfaz gráfica posteriores: Ejecuta el comando gcluster job cancel y vuelve a enviar el trabajo antes de iniciar otra sesión de cliente.

Ejecuta una carga de trabajo de Python coubicada

Ejecuta la secuencia de comandos del cliente de JAX con la variable de entorno JAX_PLATFORMS=proxy en el contenedor pathways-proxy, ya sea en el contenedor de carga de trabajo pathways-head o a través de la redirección de puertos:

  1. Para alinear las dependencias de serialización con tu imagen de archivo adicional, extrae el archivo /opt/venv/server_constraints.txt y, luego, instala los paquetes correspondientes en un entorno virtual de 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
    

    Reemplaza JAX_VERSION por tu versión de JAX, como 0.12.0.1.

  2. Si ejecutas el cliente fuera del Pod de pathways-head, reenvía el puerto local 29000 al contenedor de pathways-proxy en una terminal separada:

    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
    

    Reemplaza JOBSET_NAME por el valor metadata.name de tu JobSet (o el nombre de WORKLOAD que pasaste al comando gcluster job submit).

  3. Guarda la siguiente secuencia de comandos como colocated_example.py. Esta secuencia de comandos asigna un array de NumPy de 4 MiB en la memoria del host compartida en el dispositivo de CPU ubicado en el mismo lugar de cada trabajador de Cloud TPU y lo transfiere a la HBM de 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. Ejecuta la secuencia de comandos en el servidor proxy de IFRT:

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

    El resultado es similar a lo siguiente:

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

    En las cargas de trabajo de producción de Multislice, pasa un argumento jax.Array fragmentado colocado en los dispositivos que devuelve la llamada a colocated_python.colocated_cpu_devices(mesh) y establece el parámetro out_specs_fn con el método .specialize(out_specs_fn=...) para que Pathways ejecute una llamada paralela en todos los sidecars de trabajadores sin esperar.

    No ejecutes secuencias de comandos de cliente dentro de un Pod de worker con la variable de entorno JAX_PLATFORMS=cpu, ya que ese parámetro de configuración ejecuta JAX de forma local en una CPU y omite Pathways. Puedes ignorar cualquier mensaje IFRT proxy server disconnected: CANCELLED que se imprima al salir.

Para obtener más patrones de uso, consulta los siguientes recursos:

Verifica la implementación del archivo de configuración adicional

Ejecuta el comando kubectl logs en un JobSet sin interfaz gráfica antes de cancelarlo o borrarlo, o mientras aún se esté ejecutando una carga de trabajo por lotes. En las implementaciones por lotes de JobSet, el controlador de JobSet borra los Pods de worker en cuanto se completa el trabajo de pathways-head. En su lugar, consulta los registros de lotes completados en Cloud Logging, como se describe en Soluciona problemas de Pathways en Cloud.

Para verificar una implementación en ejecución con la herramienta de línea de comandos de kubectl, completa los siguientes pasos:

  1. Inspecciona los registros del contenedor 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
    

    Reemplaza JOBSET_NAME por el valor metadata.name de tu JobSet (o el nombre de WORKLOAD que pasaste al comando gcluster job submit). Si generaste el manifiesto con el compilador PathwaysJobSet, establece replicatedjob-name=pathways-worker en la variable ROLE_LABEL.

    El resultado es similar a lo siguiente:

    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
    

    Confirma que el resultado muestre el mensaje de inicio de gRPC y, después de la primera llamada a @colocated_python, el mensaje del asignador de memoria compartida. Los manifiestos generados con el compilador PathwaysJobSet usan el directorio /tmp/shared-memory, y las implementaciones de UDS registran unix:/sock/sidecar.sock en lugar de localhost:50051.

  2. Inspecciona los registros del contenedor pathways-worker en el mismo Pod:

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

    El resultado es similar a lo siguiente:

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

    Confirma que el contenedor pathways-worker habilitó la memoria compartida y se conectó al archivo adicional.

Cuando ejecutes el comando kubectl exec para inspeccionar el directorio de memoria compartida, orienta el contenedor colocated-python-sidecar con la marca -c colocated-python-sidecar, ya que el contenedor pathways-worker no incluye una shell.

Soluciona problemas de Python ubicado en el mismo lugar

En las siguientes secciones, se describe cómo resolver problemas habituales de Python coubicado.

Unable to unpickle error

Si tu carga de trabajo falla con el siguiente error, las versiones de Python o del paquete difieren entre tu cliente de JAX y el contenedor sidecar:

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

Verifica que tu cliente ejecute Python 3.12 (python --version) y, luego, instala los paquetes del cliente con la marca -c constraints.txt extraída de la imagen de archivo adicional. Para obtener más información, consulta Ejecuta una carga de trabajo de Python ubicada en el mismo lugar.

Conflicto de dependencia durante una ejecución de docker build

Si el comando uv pip install falla con el error No solution found when resolving dependencies, un pin en tu archivo requirements.txt entra en conflicto con el archivo /opt/venv/server_constraints.txt. Quita los paquetes jax y jaxlib del archivo requirements.txt y flexibiliza las fijaciones de versiones en paquetes como numpy, ml-dtypes o scipy.

Error: Sidecar no habilitado

Si el contenedor pathways-proxy se cierra con el error Sidecar create args were set, but sidecar was not enabled, agrega la marca --sidecar_name=external al campo args del contenedor pathways-proxy.

Sidecar already initialized error

Si tu carga de trabajo falla con el error FAILED_PRECONDITION: Sidecar already initialized, una desconexión anterior del cliente reinició el contenedor pathways-worker mientras el contenedor colocated-python-sidecar permaneció inicializado. Borra y vuelve a crear el JobSet antes de iniciar otra sesión de cliente.

Errores de conexión de sidecar o memoria compartida

Usa las siguientes verificaciones para resolver errores de activación de memoria compartida, conexión de gRPC o memoria del host:

  • Failed to stat sidecar_shm_directory: Activa el volumen emptyDir de memoria compartida en la ruta de acceso coincidente (/tmp/sidecar o /tmp/shared-memory) en los contenedores pathways-worker y colocated-python-sidecar.
  • Timed out connecting to sidecar gRPC service o Failed to connect to external sidecar: Confirma que el contenedor colocated-python-sidecar se ejecute en el campo initContainers con restartPolicy: Always y que las tres imágenes de cloud-pathways usen etiquetas que coincidan. Verifica que la configuración de TCP (--port=50051) o UDS (volumen /sock y --unix_domain_socket_path=/sock/sidecar.sock) coincida entre los contenedores pathways-proxy y colocated-python-sidecar.
  • El host del trabajador se queda sin memoria después de ráfagas de arrays grandes: Establece la marca --pathways_sidecar_shared_memory_idle_release_secs=0 en el contenedor colocated-python-sidecar (junto con la marca --port=50051 o --unix_domain_socket_path) y la marca --cloud_pathways_shared_memory_idle_release_secs=0 en el contenedor pathways-worker. Si configuras ambas marcas como 0, se libera la memoria compartida sin usar en aproximadamente 1 segundo. Como alternativa, reduce la cantidad máxima de datos del array de host que tu carga de trabajo mantiene en la memoria a la vez.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este documento, borra la implementación y los artefactos temporales cuando termines:

  • Manifiesto JobSet: Borra el recurso JobSet:

    kubectl delete jobset JOBSET_NAME
    

    Reemplaza JOBSET_NAME por el valor de metadata.name de tu JobSet.

  • Cluster Toolkit: Cancela el trabajo implementado:

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

    Reemplaza lo siguiente:

    • WORKLOAD: Es el nombre de tu trabajo de Pathways.
    • CLUSTER: Es el nombre de tu clúster de GKE.
    • PROJECT_ID: Es el ID del proyecto deGoogle Cloud .
    • LOCATION: Es la región o zona del clúster de GKE.

Opcional: Borra las imágenes de archivo de ayuda personalizadas en Artifact Registry y quita los objetos temporales de tu bucket temporal de Cloud Storage. Cuando ya no necesites el clúster de GKE, bórralo siguiendo los pasos de limpieza en Crea un clúster de GKE con Pathways.

¿Qué sigue?