为避免通过 Google Kubernetes Engine (GKE) 上的单个 Pathways 控制器路由主机绑定工作(例如数据加载和检查点),请使用 JAX 共置 Python API 在 Cloud TPU 工作器虚拟机上运行这些函数。
本文档面向机器学习工程师,介绍了共置 Python 如何与 Pathways 搭配使用。您将学习如何使用 JobSet 清单或 Cluster Toolkit 构建、部署和验证边车容器。
准备工作
完成以下前提条件:
- 创建具有 Pathways 的 GKE 集群。
- 安装
kubectl命令行工具和gke-gcloud-auth-plugin插件。 - 安装 Google Cloud CLI。
- 安装 Docker。
- 启用 Kubernetes Engine API 和 Artifact Registry API。
- 为 Pathways 临时文件创建 Cloud Storage 暂存存储桶。
- 如果您计划构建自定义边车映像,请创建 Artifact Registry Docker 代码库。
- 在运行 JAX 工作负载的客户端环境中安装 Python 3.12。
- 可选:如需使用 Cluster Toolkit 进行部署,请安装 1.108.0 或更高版本的
gclusterCLI。
所需的角色
授予以下 Identity and Access Management (IAM) 角色:
- 您的用户账号:
- Google Cloud 项目的 Artifact Registry Writer (
roles/artifactregistry.writer) 角色,用于将自定义边车映像推送到 Artifact Registry。 - Kubernetes Engine
Developer
(
roles/container.developer) Google Cloud 角色,以便在 GKE 上部署JobSet资源、转发端口和读取 Pod 日志。
- Google Cloud 项目的 Artifact Registry Writer (
- GKE 节点池服务账号:当节点池使用
--workload-metadata=GCE_METADATA标志时,Pathways Pod 会使用此服务账号,如创建具有 Pathways 的 GKE 集群中所配置:- 托管您的私有仓库的 Google Cloud 项目上的 Artifact Registry Reader (
roles/artifactregistry.reader) 角色,用于拉取自定义边车映像。 - 针对 Cloud Storage 暂存存储桶的 Storage Object Admin (
roles/storage.objectAdmin) 角色,用于编译缓存和其他临时文件。
- 托管您的私有仓库的 Google Cloud 项目上的 Artifact Registry Reader (
可选:如需让 Pathways 资源管理器 (pathways-rm) 容器添加使旧编译缓存条目过期的存储桶生命周期规则,还需在暂存存储桶上授予 Storage Admin 角色 (roles/storage.admin)。如果没有此角色,pathways-rm 容器会记录警告并继续使用缓存。如需跳过生命周期更新,请将 --enable_gcs_olm=false 标志传递给 pathways-rm 容器。
如果您的节点池改用 Workload Identity Federation for GKE,请向 Pathways Pod 使用的 Kubernetes 服务账号或其绑定的 IAM 服务账号授予暂存存储桶角色。默认情况下,Pathways Pod 使用 default 服务账号,除非您的 JobSet 清单设置了 serviceAccountName 字段。在节点池服务账号上保留 Artifact Registry Reader 角色。
共置 Python 如何与 Pathways 搭配使用
在 Pathways 中,JAX 控制器脚本在单个 CPU 主机上运行,而 Cloud TPU 工作进程 Pod 运行 C++ pathways-worker 容器。为了在工作器主机上运行 @colocated_python 函数和 @colocated_python_class 方法,共置 Python 使用以下组件:
- 您的 JAX 控制器:使用
jax.experimental.colocated_python模块将每个 Cloud TPU 芯片与主机 CPU 设备配对,并使用cloudpickle库序列化 Python 函数和类型元数据。 pathways-proxy容器(在pathways-headPod 中):通过 gRPC 接收序列化函数,并将其路由到拥有调用输入 CPU 设备的工作器虚拟机上的pathways-worker容器。传递--sidecar_name=external标志会将pathways-proxy容器配置为以colocated-python-sidecar容器为目标。pathways-worker容器(在每个工作器 Pod 上):将序列化函数加载到本地边车容器中,通过本地 gRPC 触发执行,并通过共享内存中emptyDir卷 (medium: Memory) 交换数组缓冲区。colocated-python-sidecar容器(在每个工作器 Pod 上):在隔离的 Python 3.12 运行时中,针对每个虚拟机在其本地分片上运行一次函数,并将输出数组直接写入共享主机内存。
如需详细了解 Pathways 架构,请参阅 Pathways 组件。
执行流程
当您调用修饰函数时,Pathways 会分两个阶段在集群中运行该函数:
- 函数路由:
jax.experimental.colocated_python模块将函数打包到临时框架运行时 (IFRT) 程序中,并将其发送到pathways-proxy容器。代理仅将程序转发到持有输入分片的工作器虚拟机,每个虚拟机在所有本地分片上运行一次。 - 共享内存执行:
pathways-worker容器将输入分片写入内存中共享卷(/tmp/sidecar或/tmp/shared-memory),并通过环回 TCP (localhost:50051) 或 Unix 网域套接字 (/sock/sidecar.sock) 调用colocated-python-sidecar容器。输出数组通过共享内存返回,无需 gRPC 复制,并在放置到 Cloud TPU 设备上时直接移入 Cloud TPU 高带宽内存 (HBM)。
如需了解 JAX API 的用法(例如发现共置的 CPU 设备和声明异步分派的输出规范),请参阅 JAX 共置 Python 指南。
设计指导原则
编写共置 Python 函数时,请遵循以下准则:
- 尽量减少捕获的变量:将数组数据作为分片
jax.Array实参传递,而不是在闭包中捕获大型数组或不可序列化的对象(例如打开的文件或网络客户端)。在工作器上的@colocated_python_class实例中打开文件或客户端。 - 在重启后重新创建
@colocated_python_class状态:有状态边车对象会在内存中的各个步骤之间持久保存,但如果工作器 Pod 重启或切片计数在弹性训练期间发生变化,则不会自动保存。在重新扩缩或重启后,从检查点重新创建有状态对象。
预构建的映像和标记
Google Cloud 在公共 Artifact Registry 代码库中发布预构建的 Pathways 映像:
- 共置的 Python 边车:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG - Pathways 资源管理器和工作器:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG - IFRT 代理服务器:
us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG
在 server、proxy_server 和 colocated_python_sidecar 映像中使用匹配的标记。
预构建的边车映像支持 JAX 版本 0.10.1、0.10.2、0.11.0、0.11.1、0.11.2、0.12.0 和 0.12.0.1。将 TAG 替换为以下代码格式之一:
jax-JAX_VERSION(推荐):特定 JAX 版本的滚动标记,例如jax-0.12.0.1。YYYYMMDD-jax_JAX_VERSION:带有日期戳的 build 标记,例如20261110-jax_0.12.0.1。
如果您需要一个永不更改的确切映像版本,请通过其 SHA-256 摘要固定该映像。如需查找映像摘要,请使用 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)"
将 JAX_VERSION 替换为您的 JAX 版本,例如 0.12.0.1。
构建自定义边车映像
预构建的边车映像包含 jax、jaxlib、numpy、scipy、ml-dtypes、opt-einsum、cloudpickle 和 absl-py 软件包。如果您的共置 Python 函数仅使用这些软件包,请跳至使用边车部署 Pathways JobSet 或使用 Cluster Toolkit 进行部署。
如需添加自定义 Python 依赖项,请将其分层添加到与您的 JAX 版本匹配的预构建映像中:
在空 build 目录中,为额外软件包创建一个
requirements.txt文件。省略jax和jaxlib软件包,因为它们已安装并固定在/opt/venv/server_constraints.txt文件中:grain创建一个
Dockerfile,用于安装requirements.txt文件中的软件包,并受/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保持基础映像的
ENTRYPOINT和CMD指令不变。如果requirements.txt文件从 Git 网址安装软件包,请在uv pip installRUN指令之前添加以下RUN指令,因为精简基础映像省略了git工具:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*使用
gcloud auth configure-docker命令向您的 Artifact Registry 区域验证 Docker:gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.dev将
REGISTRY_LOCATION替换为您的 Artifact Registry 位置,例如us或us-central1。构建并推送自定义边车映像:
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}"替换以下内容:
JAX_VERSION:您的 JAX 版本,例如0.12.0.1。REGISTRY_LOCATION:您的 Artifact Registry 位置,例如us或us-central1。PROJECT_ID:您的Google Cloud 项目 ID。REPOSITORY:您的 Artifact Registry Docker 代码库名称。
部署具有 Sidecar 的 Pathways JobSet
您可以通过以下两种方式部署 Pathways 边车:使用本部分中的 kubectl 命令行工具应用 JobSet 清单,或使用通过 Cluster Toolkit 部署中的 gcluster CLI 直接提交作业。
如需生成并应用 JobSet 清单,请完成以下步骤:
使用以下任一工具生成
JobSet清单 (pathways-colocated-jobset.yaml):pathways-utilsPython 构建器:通过调用.add_colocated_python("SIDECAR_IMAGE")和.export_yaml("pathways-colocated-jobset.yaml")方法,使用PathwaysJobSet构建器配置JobSet。如果您使用pathwaysutils软件包(PyPI 中的0.1.14或更早版本),请同时将proxy_container_kwargs={"args": ["--sidecar_name=external"]}参数传递给PathwaysJobSet构造函数,或从main分支安装pathways-utils软件包。- Cluster Toolkit (
gcluster):运行带有--pathways-colocated-python-sidecar-image标志的gcluster job submit命令,并附加--dry-run-out=pathways-colocated-jobset.yaml标志,以便在本地呈现清单,而无需提交作业。
将
SIDECAR_IMAGE替换为您的自定义边车映像 URI 或预构建的colocated_python_sidecar映像 URI。这两个生成器都会将清单配置为执行以下操作:
- 在每个工作器 Pod 中,使用
restartPolicy: Always运行initContainers字段下的colocated-python-sidecar容器。gclusterCLI 将工作器复制的作业命名为worker,而PathwaysJobSet构建器将其命名为pathways-worker。 - 将
--sidecar_name=external标志传递给pathways-proxy容器,并通过localhost:50051上的环回 TCP 将pathways-worker容器连接到边车。当pathways-proxy容器在initContainers字段下运行时,它也会使用restartPolicy: Always。 - 在两个工作器 Pod 容器中装载具有
medium: Memory的内存中emptyDir卷:在gcluster清单中的/tmp/sidecar处,或在PathwaysJobSet清单中的/tmp/shared-memory处。这两个生成器还会在边车上设置CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY环境变量,并在pathways-worker容器上设置--cloud_pathways_sidecar_shm_directory标志。
应用
JobSet清单,并等待 Pod 达到Running状态:kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAME将
JOBSET_NAME替换为JobSet的metadata.name值。
每个 JobSet 部署运行一个 JAX 客户端会话。客户端断开连接后,重启的 pathways-worker 容器无法重复使用正在运行的边车。请先删除并重新创建 JobSet,然后再开始其他会话。
内存中 emptyDir 卷中的文件会计入 Pod 内存用量。在共享内存卷上设置 emptyDir.sizeLimit 字段(例如 175Gi),以限制每个节点的使用量。默认情况下,两个容器都会在空闲 30 秒后保留释放的共享内存,以供重复使用。如需更改该窗口,请在 colocated-python-sidecar 容器的 args 字段中设置 --pathways_sidecar_shared_memory_idle_release_secs=SECONDS 标志(与 --port=50051 或 --unix_domain_socket_path 标志一起),并在 pathways-worker 容器的 args 字段中设置 --cloud_pathways_shared_memory_idle_release_secs=SECONDS 标志。将 SECONDS 替换为空闲超时(以秒为单位)。将这两个标志都设置为 0 会在大约 1 秒内释放已释放的页面,这会减少内存用量,但会增加额外的分配开销。
可选:使用 Unix 网域套接字
如需在 /sock/sidecar.sock 处使用 Unix 网域套接字 (UDS),而不是在设置 hostNetwork: true 的工作器 Pod 上打开 TCP 端口,请在运行 kubectl apply 命令之前对 JobSet 清单应用以下替换:
- 在
pathways-worker和colocated-python-sidecar容器中的/sock处装载名为sidecar-socket的emptyDir: {}卷。 - 在
colocated-python-sidecar容器上设置args: ["--unix_domain_socket_path=/sock/sidecar.sock"]和execstartupProbe(test -S /sock/sidecar.sock)。 - 将
--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock标志附加到pathways-proxy容器的args字段。
使用 Cluster Toolkit 进行部署
在 Cluster Toolkit(gcluster 1.108.0 版或更高版本)中,将 --pathways-colocated-python-sidecar-image 标志传递给 gcluster job submit 命令,通过环回 TCP (localhost:50051) 配置 colocated-python-sidecar 容器,在 /tmp/sidecar 处装载内存中卷,并设置 --sidecar_name=external 标志。明确传递 --pathways-server-image 和 --pathways-proxy-server-image 标志,以便所有三个映像都使用匹配的 cloud-pathways 标记。
提交包含边车映像的无头 Pathways 部署,以便您可以针对该部署运行交互式客户端脚本:
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
替换以下内容:
BUCKET_NAME:您的 Cloud Storage 临时存储桶。JAX_VERSION:您的 JAX 版本,例如0.12.0.1。SIDECAR_IMAGE:您的自定义或预构建边车映像 URI。WORKLOAD:唯一的JobSet名称(不超过 22 个字符)。CLUSTER:您的 GKE 集群名称。PROJECT_ID:您的Google Cloud 项目 ID。LOCATION:您的 GKE 集群所在的区域或可用区。WORKLOAD_NODEPOOL_COUNT:Cloud TPU 切片的数量,例如1。COMPUTE_TYPE:Cloud TPU 机器类型,例如ct5lp-hightpu-4t或ct6e-standard-4t。TOPOLOGY:Cloud TPU 切片拓扑,例如4x8或2x4。
您还可以自定义 gcluster job submit 命令运行或导出作业的方式:
- 批处理工作负载:如需在
pathways-headPod(而不是无头部署)中运行容器化批量作业,请将--pathways-headless标志替换为--image="CLIENT_IMAGE"和--command="COMMAND"标志。使用通过server_constraints.txt固定版本构建的 Python 3.12 JAX 客户端映像,并传递您的入口命令(例如python colocated_example.py)。 - 本地清单呈现:附加
--dry-run-out=pathways-colocated-jobset.yaml标志,以便在本地呈现JobSet清单,而无需提交。 - 后续无头会话:在启动另一个客户端会话之前,请运行
gcluster job cancel命令并重新提交作业。
运行共置的 Python 工作负载
在 pathways-head 工作负载容器中或通过端口转发,使用 JAX_PLATFORMS=proxy 环境变量针对 pathways-proxy 容器运行 JAX 客户端脚本:
如需使序列化依赖项与边车映像保持一致,请提取
/opt/venv/server_constraints.txt文件,并在 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将
JAX_VERSION替换为您的 JAX 版本,例如0.12.0.1。如果您在
pathways-headPod 之外运行客户端,请在单独的终端中将本地端口29000转发到pathways-proxy容器: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将
JOBSET_NAME替换为JobSet的metadata.name值(或您传递给gcluster job submit命令的WORKLOAD名称)。将以下脚本保存为
colocated_example.py。此脚本在每个 Cloud TPU 工作器的共置 CPU 设备的共享主机内存中分配一个 4 MiB NumPy 数组,并将其传输到 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}" )针对 IFRT 代理服务器运行脚本:
JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \ python colocated_example.py输出类似于以下内容:
TPU devices: 8, colocated CPU devices: 8 Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0在多切片生产工作负载中,传递一个放置在
colocated_python.colocated_cpu_devices(mesh)调用返回的设备上的分片jax.Array参数,并使用.specialize(out_specs_fn=...)方法设置out_specs_fn参数,以便 Pathways 在所有工作器边车上运行一个并行调用,而无需等待。请勿在具有
JAX_PLATFORMS=cpu环境变量的workerPod 中运行客户端脚本,因为该设置会在一个 CPU 上本地运行 JAX 并绕过 Pathways。您可以忽略退出时输出的任何IFRT proxy server disconnected: CANCELLED消息。
如需了解其他使用模式,请参阅以下资源:
- JAX 共置 Python 笔记本:函数特化和有状态
@colocated_python_class对象 - MaxText
multihost_dataloading.py模块:RemoteIterator多主机输入流水线,使用共置的 Python - Orbax Pathways 检查点和使用 Pathways 的多层级检查点:使用
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)调用(或 MaxText 中的colocated_python_checkpointing=True设置)和use_colocated_python=True选项在工作器边车上进行分布式检查点,以实现多层级检查点
验证边车部署
在取消或
删除无头 之前,或在批处理工作负载仍在运行时,对无头 JobSet 运行 kubectl logs 命令。在批处理 JobSet 部署中,pathways-head 作业完成后,JobSet 控制器会立即删除 worker Pod。请改为在 Cloud Logging 中查看已完成的批处理日志,如排查 Cloud 上的 Pathways 问题中所述。
如需使用 kubectl 命令行工具验证正在运行的部署,请完成以下步骤:
检查
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将
JOBSET_NAME替换为JobSet的metadata.name值(或您传递给gcluster job submit命令的WORKLOAD名称)。如果您使用PathwaysJobSet构建器生成了清单,请在ROLE_LABEL变量中设置replicatedjob-name=pathways-worker。输出类似于以下内容:
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确认输出显示 gRPC 启动消息,并在第一次
@colocated_python调用后显示共享内存分配器消息。使用PathwaysJobSet构建器生成的清单使用/tmp/shared-memory目录,并且 UDS 部署会记录unix:/sock/sidecar.sock而不是localhost:50051。检查同一 Pod 上的
pathways-worker容器日志:kubectl logs "${WORKER_POD}" -c pathways-worker \ | grep -iE "shared memory|external sidecar"输出类似于以下内容:
Enabled shared memory for external sidecar in /tmp/sidecar External sidecar connected to backing GRPC sidecar at localhost:50051确认
pathways-worker容器已启用共享内存并连接到边车。
运行 kubectl exec 命令检查共享内存目录时,请使用 -c colocated-python-sidecar 标志定位到 colocated-python-sidecar 容器,因为 pathways-worker 容器不包含 shell。
排查共置 Python 问题
以下部分介绍了如何解决常见的 Python 共置问题。
Unable to unpickle 个错误
如果您的工作负载失败并出现以下错误,则表示 JAX 客户端和边车容器之间的 Python 或软件包版本不同:
jax.errors.JaxRuntimeError: UNKNOWN: Unable to unpickle the callable and specialization
检查您的客户端是否运行 Python 3.12 (python --version),并使用从边车映像中提取的 -c constraints.txt 标志安装客户端软件包。如需了解详情,请参阅运行共置的 Python 工作负载。
docker build 运行期间发生依赖项冲突
如果 uv pip install 命令失败并显示 No solution found when resolving dependencies 错误,则表示 requirements.txt 文件中的固定版本与 /opt/venv/server_constraints.txt 文件冲突。从 requirements.txt 文件中移除 jax 和 jaxlib 软件包,并放宽对 numpy、ml-dtypes 或 scipy 等软件包的版本限制。
“Sidecar 未启用”错误
如果 pathways-proxy 容器退出并显示 Sidecar create args were set, but sidecar was not enabled 错误,请将 --sidecar_name=external 标志添加到 pathways-proxy 容器的 args 字段。
Sidecar already initialized 个错误
如果您的工作负载因 FAILED_PRECONDITION: Sidecar already initialized 错误而失败,则表示之前的客户端断开连接重启了 pathways-worker 容器,而 colocated-python-sidecar 容器保持初始化状态。请先删除并重新创建 JobSet,然后再启动另一个客户端会话。
共享内存或边车连接错误
请使用以下检查来解决共享内存装载、gRPC 连接或主机内存错误:
Failed to stat sidecar_shm_directory:在pathways-worker和colocated-python-sidecar容器中的匹配路径(/tmp/sidecar或/tmp/shared-memory)处装载共享内存emptyDir卷。Timed out connecting to sidecar gRPC service或Failed to connect to external sidecar:确认colocated-python-sidecar容器在initContainers字段下运行,且值为restartPolicy: Always,并且所有三个cloud-pathways映像都使用匹配的标记。检查您的 TCP(--port=50051)或 UDS(/sock卷和--unix_domain_socket_path=/sock/sidecar.sock)设置在pathways-proxy和colocated-python-sidecar容器之间是否匹配。- 大型数组突发后工作器主机内存不足:在
colocated-python-sidecar容器上设置--pathways_sidecar_shared_memory_idle_release_secs=0标志(以及--port=50051或--unix_domain_socket_path标志),并在pathways-worker容器上设置--cloud_pathways_shared_memory_idle_release_secs=0标志。将这两个标志都设置为0会在大约 1 秒内释放未使用的共享内存。或者,减少工作负载一次性保留在内存中的主机数组数据峰值量。
清理
为避免因本文档中使用的资源导致您的 Google Cloud 账号产生费用,请在完成后删除部署和临时工件:
JobSet清单:删除JobSet资源:kubectl delete jobset JOBSET_NAME将
JOBSET_NAME替换为JobSet的metadata.name值。Cluster Toolkit:取消已部署的作业:
gcluster job cancel WORKLOAD \ --cluster=CLUSTER \ --project=PROJECT_ID \ --location=LOCATION替换以下内容:
WORKLOAD:Pathways 作业的名称。CLUSTER:您的 GKE 集群名称。PROJECT_ID:您的Google Cloud 项目 ID。LOCATION:您的 GKE 集群所在的区域或可用区。
可选:删除 Artifact Registry 中的所有自定义边车映像,并移除 Cloud Storage 暂存存储桶中的临时对象。当您不再需要 GKE 集群时,请按照使用 Pathways 创建 GKE 集群中的清理步骤将其删除。
后续步骤
- 将 JAX 工作负载移植到 Pathways
- 使用 Pathways 进行弹性训练
- 使用 Pathways 运行批量工作负载
- 使用 Pathways 运行交互式工作负载
- 排查 Pathways on Cloud 问题
- 在 Cluster Toolkit 中使用 Pathways 运行工作负载