使用 Pathways 运行共置的 Python

为避免通过 Google Kubernetes Engine (GKE) 上的单个 Pathways 控制器路由主机绑定工作(例如数据加载和检查点),请使用 JAX 共置 Python API 在 Cloud TPU 工作器虚拟机上运行这些函数。

本文档面向机器学习工程师,介绍了共置 Python 如何与 Pathways 搭配使用。您将学习如何使用 JobSet 清单或 Cluster Toolkit 构建、部署和验证边车容器。

准备工作

完成以下前提条件:

所需的角色

授予以下 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 日志。
  • 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) 角色,用于编译缓存和其他临时文件。

可选:如需让 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-head Pod 中):通过 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 会分两个阶段在集群中运行该函数:

  1. 函数路由:jax.experimental.colocated_python 模块将函数打包到临时框架运行时 (IFRT) 程序中,并将其发送到 pathways-proxy 容器。代理仅将程序转发到持有输入分片的工作器虚拟机,每个虚拟机在所有本地分片上运行一次。
  2. 共享内存执行: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 版本匹配的预构建映像中:

  1. 在空 build 目录中,为额外软件包创建一个 requirements.txt 文件。省略 jax 和 jaxlib 软件包,因为它们已安装并固定在 /opt/venv/server_constraints.txt 文件中:

    grain
    
  2. 创建一个 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 install RUN 指令之前添加以下 RUN 指令,因为精简基础映像省略了 git 工具:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. 使用 gcloud auth configure-docker 命令向您的 Artifact Registry 区域验证 Docker:

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

    将 REGISTRY_LOCATION 替换为您的 Artifact Registry 位置,例如 us 或 us-central1。

  4. 构建并推送自定义边车映像:

    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 清单,请完成以下步骤:

  1. 使用以下任一工具生成 JobSet 清单 (pathways-colocated-jobset.yaml):

    • pathways-utils Python 构建器:通过调用 .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 容器。gcluster CLI 将工作器复制的作业命名为 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 标志。
  2. 应用 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"] 和 exec startupProbe (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-head Pod(而不是无头部署)中运行容器化批量作业,请将 --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 客户端脚本:

  1. 如需使序列化依赖项与边车映像保持一致,请提取 /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。

  2. 如果您在 pathways-head Pod 之外运行客户端,请在单独的终端中将本地端口 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 名称)。

  3. 将以下脚本保存为 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}"
    )
    
  4. 针对 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 环境变量的 worker Pod 中运行客户端脚本,因为该设置会在一个 CPU 上本地运行 JAX 并绕过 Pathways。您可以忽略退出时输出的任何 IFRT proxy server disconnected: CANCELLED 消息。

如需了解其他使用模式,请参阅以下资源:

验证边车部署

在取消或 删除无头 之前,或在批处理工作负载仍在运行时,对无头 JobSet 运行 kubectl logs 命令。在批处理 JobSet 部署中,pathways-head 作业完成后,JobSet 控制器会立即删除 worker Pod。请改为在 Cloud Logging 中查看已完成的批处理日志,如排查 Cloud 上的 Pathways 问题中所述。

如需使用 kubectl 命令行工具验证正在运行的部署,请完成以下步骤:

  1. 检查 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。

  2. 检查同一 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 集群中的清理步骤将其删除。

后续步骤