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:
- Crea un clúster de GKE con Pathways.
- Instala la herramienta de línea de comandos de
kubectly el complementogke-gcloud-auth-plugin. - Instala la Google Cloud CLI.
- Instala Docker.
- Habilita la API de Kubernetes Engine y la API de Artifact Registry.
- Crea un bucket de Cloud Storage temporal para los archivos temporales de Pathways.
- Si planeas compilar una imagen de archivo de complemento personalizada, crea un repositorio de Docker de Artifact Registry.
- Instala Python 3.12 en el entorno de cliente que ejecuta tu carga de trabajo de JAX.
- Opcional: Para implementar con
Cluster Toolkit,
instala la versión 1.108.0 o posterior de la
CLI de
gcluster.
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.
- Escritor de Artifact Registry
(
- 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.
- Lector de Artifact Registry
(
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_pythonpara 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 bibliotecacloudpickle. - El contenedor
pathways-proxy(en el Podpathways-head): Recibe la función serializada a través de gRPC y la enruta al contenedorpathways-workeren 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 contenedorpathways-proxypara que se oriente al contenedorcolocated-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 volumenemptyDircompartido 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:
- Enrutamiento de funciones: El módulo
jax.experimental.colocated_pythonempaqueta la función en un programa de entorno de ejecución de framework intermedio (IFRT) y lo envía al contenedorpathways-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. - Ejecución de memoria compartida: El contenedor
pathways-workerescribe fragmentos de entrada en el volumen compartido en la memoria (/tmp/sidecaro/tmp/shared-memory) y, luego, invoca el contenedorcolocated-python-sidecara 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.Arrayfragmentados 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_classen el trabajador - Vuelve a crear el estado de
@colocated_python_classdespué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, comojax-0.12.0.1.YYYYMMDD-jax_JAX_VERSION: es una etiqueta de compilación con marca de fecha, como20261110-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:
En un directorio de compilación vacío, crea un archivo
requirements.txtpara tus paquetes adicionales. Omite los paquetesjaxyjaxlib, que ya están instalados y fijados en el archivo/opt/venv/server_constraints.txt:grainCrea un
Dockerfileque instale los paquetes en el archivorequirements.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 cleanMantén sin cambios las instrucciones
ENTRYPOINTyCMDde la imagen base. Si el archivorequirements.txtinstala paquetes desde URLs de Git, agrega la siguiente instrucciónRUNantes de la instrucciónuv pip installRUN, ya que la imagen base slim omite la herramientagit:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*Autentica Docker en tu región de Artifact Registry con el comando
gcloud auth configure-docker:gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.devReemplaza
REGISTRY_LOCATIONpor la ubicación de Artifact Registry, comousous-central1.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, como0.12.0.1.REGISTRY_LOCATION: Es tu ubicación de Artifact Registry, comousous-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:
Genera un manifiesto
JobSet(pathways-colocated-jobset.yaml) con cualquiera de las siguientes herramientas:- El compilador de Python
pathways-utils: Configura unJobSetcon el compiladorPathwaysJobSetllamando a los métodos.add_colocated_python("SIDECAR_IMAGE")y.export_yaml("pathways-colocated-jobset.yaml"). Si usas el paquetepathwaysutils(versión0.1.14o anterior de PyPI), también pasa el argumentoproxy_container_kwargs={"args": ["--sidecar_name=external"]}al constructorPathwaysJobSeto instala el paquetepathways-utilsdesde la ramamain. - Cluster Toolkit (
gcluster): Ejecuta el comandogcluster job submitcon la marca--pathways-colocated-python-sidecar-imagey agrega la marca--dry-run-out=pathways-colocated-jobset.yamlpara renderizar el manifiesto de forma local sin enviar el trabajo.
Reemplaza
SIDECAR_IMAGEpor el URI de la imagen de sidecar personalizada o el URI de la imagencolocated_python_sidecarcompilada previamente.Ambos generadores configuran el manifiesto para que realice las siguientes acciones:
- Ejecuta el contenedor
colocated-python-sidecaren el campoinitContainersconrestartPolicy: Alwaysen cada Pod de trabajador. La CLI degclusterasigna el nombreworkeral trabajo replicado del trabajador, mientras que el compilador dePathwaysJobSetle asigna el nombrepathways-worker. - Pasa la marca
--sidecar_name=externalal contenedorpathways-proxyy conecta el contenedorpathways-workeral archivo adicional a través de TCP de bucle invertido enlocalhost:50051. Cuando el contenedorpathways-proxyse ejecuta en el campoinitContainers, también usarestartPolicy: Always. - Activa un volumen
emptyDiren memoria conmedium: Memoryen ambos contenedores de Pods de trabajador: en/tmp/sidecaren manifiestos degclustero en/tmp/shared-memoryen manifiestos dePathwaysJobSet. Ambos generadores también establecen la variable de entornoCLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORYen el archivo adicional y la marca--cloud_pathways_sidecar_shm_directoryen el contenedorpathways-worker.
- El compilador de Python
Aplica el manifiesto
JobSety espera a que los Pods alcancen el estadoRunning:kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAMEReemplaza
JOBSET_NAMEpor el valor demetadata.namede tuJobSet.
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: {}llamadosidecar-socketen/socken los contenedorespathways-workerycolocated-python-sidecar. - Establece
args: ["--unix_domain_socket_path=/sock/sidecar.sock"]y unexecstartupProbe(test -S /sock/sidecar.sock) en el contenedorcolocated-python-sidecar. - Agrega la marca
--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sockal campoargsdel contenedorpathways-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, como0.12.0.1.SIDECAR_IMAGE: Es el URI de la imagen de sidecar personalizada o precompilada.WORKLOAD: un nombre único deJobSet(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, como1.COMPUTE_TYPE: Es el tipo de máquina de Cloud TPU, comoct5lp-hightpu-4toct6e-standard-4t.TOPOLOGY: Es la topología de la porción de Cloud TPU, como4x8o2x4.
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-headen lugar de una implementación sin interfaz gráfica, reemplaza la marca--pathways-headlesspor las marcas--image="CLIENT_IMAGE"y--command="COMMAND". Usa una imagen de cliente de JAX de Python 3.12 compilada con fijaciones deserver_constraints.txty pasa tu comando de entrada (comopython colocated_example.py). - Renderización del manifiesto local: Agrega la
marca
--dry-run-out=pathways-colocated-jobset.yamlpara renderizar el manifiesto deJobSetde forma local sin enviarlo. - Sesiones sin interfaz gráfica posteriores: Ejecuta el comando
gcluster job cancely 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:
Para alinear las dependencias de serialización con tu imagen de archivo adicional, extrae el archivo
/opt/venv/server_constraints.txty, 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 pathwaysutilsReemplaza
JAX_VERSIONpor tu versión de JAX, como0.12.0.1.Si ejecutas el cliente fuera del Pod de
pathways-head, reenvía el puerto local29000al contenedor depathways-proxyen 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:29000Reemplaza
JOBSET_NAMEpor el valormetadata.namede tuJobSet(o el nombre deWORKLOADque pasaste al comandogcluster job submit).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}" )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.pyEl 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.0En las cargas de trabajo de producción de Multislice, pasa un argumento
jax.Arrayfragmentado colocado en los dispositivos que devuelve la llamada acolocated_python.colocated_cpu_devices(mesh)y establece el parámetroout_specs_fncon 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
workercon la variable de entornoJAX_PLATFORMS=cpu, ya que ese parámetro de configuración ejecuta JAX de forma local en una CPU y omite Pathways. Puedes ignorar cualquier mensajeIFRT proxy server disconnected: CANCELLEDque se imprima al salir.
Para obtener más patrones de uso, consulta los siguientes recursos:
- Notebook de Python de JAX ubicado en el mismo lugar:
especialización de funciones y objetos
@colocated_python_classcon estado - Módulo
multihost_dataloading.pyde MaxText: Canalización de entrada de varios hosts deRemoteIteratorque usa Python ubicado en el mismo lugar - Puntos de control de Orbax Pathways
y puntos de control de varios niveles con Pathways:
puntos de control distribuidos en sidecars de trabajadores con la llamada
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)(o el parámetro de configuracióncolocated_python_checkpointing=Trueen MaxText) y la opciónuse_colocated_python=Truepara puntos de control de varios niveles
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:
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-sidecarReemplaza
JOBSET_NAMEpor el valormetadata.namede tuJobSet(o el nombre deWORKLOADque pasaste al comandogcluster job submit). Si generaste el manifiesto con el compiladorPathwaysJobSet, establecereplicatedjob-name=pathways-workeren la variableROLE_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_sidecarConfirma 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 compiladorPathwaysJobSetusan el directorio/tmp/shared-memory, y las implementaciones de UDS registranunix:/sock/sidecar.socken lugar delocalhost:50051.Inspecciona los registros del contenedor
pathways-workeren 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:50051Confirma que el contenedor
pathways-workerhabilitó 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 volumenemptyDirde memoria compartida en la ruta de acceso coincidente (/tmp/sidecaro/tmp/shared-memory) en los contenedorespathways-workerycolocated-python-sidecar.Timed out connecting to sidecar gRPC serviceoFailed to connect to external sidecar: Confirma que el contenedorcolocated-python-sidecarse ejecute en el campoinitContainersconrestartPolicy: Alwaysy que las tres imágenes decloud-pathwaysusen etiquetas que coincidan. Verifica que la configuración de TCP (--port=50051) o UDS (volumen/socky--unix_domain_socket_path=/sock/sidecar.sock) coincida entre los contenedorespathways-proxyycolocated-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=0en el contenedorcolocated-python-sidecar(junto con la marca--port=50051o--unix_domain_socket_path) y la marca--cloud_pathways_shared_memory_idle_release_secs=0en el contenedorpathways-worker. Si configuras ambas marcas como0, 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 recursoJobSet:kubectl delete jobset JOBSET_NAMEReemplaza
JOBSET_NAMEpor el valor demetadata.namede tuJobSet.Cluster Toolkit: Cancela el trabajo implementado:
gcluster job cancel WORKLOAD \ --cluster=CLUSTER \ --project=PROJECT_ID \ --location=LOCATIONReemplaza 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.