使用 Pathways 執行共置的 Python

為避免透過 Google Kubernetes Engine (GKE) 上的單一 Pathways 控制器,轉送資料載入和檢查點等主機繫結工作,請使用 JAX 共置 Python API,在 Cloud TPU worker VM 上執行這些函式。

本文檔適用於機器學習工程師,說明共置 Python 如何與 Pathways 搭配運作。您將瞭解如何使用 JobSet 資訊清單或 Cluster Toolkit 建構、部署及驗證邊車容器。

事前準備

請完成下列前置作業:

必要的角色

授予下列 Identity and Access Management (IAM) 角色:

  • 您的使用者帳戶:
    • Artifact Registry 寫入者 (roles/artifactregistry.writer) Google Cloud 角色,以便將 自訂 sidecar 映像檔推送至 Artifact Registry。
    • Google Cloud 專案的 Kubernetes Engine 開發人員 (roles/container.developer),以便在 GKE 上部署 JobSet 資源、轉送通訊埠及讀取 Pod 記錄。
  • GKE 節點集區服務帳戶:如果節點集區使用 --workload-metadata=GCE_METADATA 旗標,Pathways Pod 會使用這個服務帳戶,如「建立具備 Pathways 的 GKE 叢集」一節所述:
    • 託管私人存放區的 Google Cloud 專案具備 Artifact Registry 讀取者 (roles/artifactregistry.reader) 角色,可提取自訂 sidecar 映像檔。
    • Cloud Storage 臨時 bucket 的 Storage 物件管理員 (roles/storage.objectAdmin),用於編譯快取和其他暫存檔案。

選用:如要允許 Pathways 資源管理工具 (pathways-rm) 容器新增值區生命週期規則,讓舊的編譯快取項目過期,請一併授予暫存值區的儲存空間管理員角色 (roles/storage.admin)。如果沒有這個角色,pathways-rm 容器會記錄警告,並繼續使用快取。如要略過生命週期更新,請將 --enable_gcs_olm=false 旗標傳遞至 pathways-rm 容器。

如果節點集區改用 Workload Identity Federation for GKE,請將臨時 bucket 角色授予 Pathways Pod 使用的 Kubernetes 服務帳戶,或其繫結的 IAM 服務帳戶。根據預設,除非 JobSet 資訊清單設定 serviceAccountName 欄位,否則 Pathways Pod 會使用 default 服務帳戶。保留節點集區服務帳戶的 Artifact Registry 讀取者角色。

共置 Python 如何與 Pathways 搭配運作

在 Pathways 中,JAX 控制器指令碼會在單一 CPU 主機上執行,而 Cloud TPU 工作站 Pod 則會執行 C++ pathways-worker 容器。如要在 worker 主機上執行 @colocated_python 函式和 @colocated_python_class 方法,共置 Python 會使用下列元件:

  • JAX 控制器:使用 jax.experimental.colocated_python 模組將每個 Cloud TPU 晶片與主機 CPU 裝置配對,並使用 cloudpickle 程式庫序列化 Python 函式和類型中繼資料。
  • pathways-proxy 容器 (位於 pathways-head Pod):透過 gRPC 接收序列化函式,並將其轉送至 worker VM 上的 pathways-worker 容器,該 VM 擁有呼叫的輸入 CPU 裝置。傳遞 --sidecar_name=external 旗標,將 pathways-proxy 容器設定為指定 colocated-python-sidecar 容器。
  • pathways-worker 容器 (位於每個 worker Pod):將序列化函式載入本機邊車容器、透過本機 gRPC 觸發執行作業,並透過共用的記憶體內 emptyDir 磁碟區 (medium: Memory) 交換陣列緩衝區。
  • colocated-python-sidecar 容器 (位於各個 worker Pod):在每個 VM 的本機 shard 中,於隔離的 Python 3.12 執行階段中解壓縮並執行函式一次,並將輸出陣列直接寫入共用主機記憶體。

如要進一步瞭解 Pathways 架構,請參閱「Pathways 元件」。

執行流程

叫用裝飾函式時,Pathways 會分兩個階段在叢集中執行:

  1. 函式轉送:jax.experimental.colocated_python 模組會將函式封裝至臨時架構執行階段 (IFRT) 程式,並傳送至 pathways-proxy 容器。Proxy 只會將程式轉送至含有輸入 shard 的 worker VM,並在所有本機 shard 中,每個 VM 執行一次。
  2. 共用記憶體執行:pathways-worker 容器會將輸入 shard 寫入記憶體內共用磁碟區 (/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 引數傳遞,而不是在閉包中擷取大型陣列或不可序列化的物件 (例如開啟的檔案或網路用戶端)。在 worker 的 @colocated_python_class 執行個體中開啟檔案或用戶端。
  • 重新啟動後重新建立 @colocated_python_class 狀態:有狀態的 Sidecar 物件會在記憶體中的步驟之間保留,但如果工作站 Pod 重新啟動,或彈性訓練期間切片數量變更,則不會自動儲存。重新調整資源配置或重新啟動後,從檢查點重新建立有狀態物件。

預先建立的映像檔和標記

Google Cloud 會在公開 Artifact Registry 存放區中,發布預先建構的 Pathways 映像檔:

  • 共置 Python sidecar: 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 Proxy 伺服器: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

在 server、proxy_server 和 colocated_python_sidecar 圖片中使用相符的標記。

預先建構的 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:加上日期戳記的版本標記,例如 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。

建構自訂 sidecar 映像檔

預先建構的 Sidecar 映像檔包含 jax、jaxlib、numpy、scipy、ml-dtypes、opt-einsum、cloudpickle 和 absl-py 套件。如果共置的 Python 函式只使用這些套件,請跳至「使用 Sidecar 部署 Pathways JobSet」或「使用 Cluster Toolkit 部署」。

如要新增自訂 Python 依附元件,請將其分層至與 JAX 版本相符的預先建構映像檔:

  1. 在空白建構目錄中,為額外套件建立 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. 建構及推送自訂 sidecar 映像檔:

    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 和 Sidecar,您可以使用本節中的 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):執行 gcluster job submit 指令並加上 --pathways-colocated-python-sidecar-image 旗標,然後附加 --dry-run-out=pathways-colocated-jobset.yaml 旗標,即可在本機轉譯資訊清單,而不提交工作。

    將 SIDECAR_IMAGE 替換為自訂 sidecar 映像檔 URI 或預先建構的 colocated_python_sidecar 映像檔 URI。

    這兩個產生器都會設定資訊清單,以執行下列操作:

    • 在每個 worker Pod 中,使用 restartPolicy: Always 執行 initContainers 欄位下的 colocated-python-sidecar 容器。gcluster CLI 會將 worker 複製工作命名為 worker,而 PathwaysJobSet 建構工具則會將其命名為 pathways-worker。
    • 將 --sidecar_name=external 旗標傳遞至 pathways-proxy 容器,並透過 localhost:50051 上的回送 TCP 將 pathways-worker 容器連線至 Sidecar。當 pathways-proxy 容器在 initContainers 欄位下執行時,也會使用 restartPolicy: Always。
    • 在兩個 worker Pod 容器中,使用 medium: Memory 掛接記憶體內 emptyDir 磁碟區:在 gcluster 資訊清單中的 /tmp/sidecar,或在 PathwaysJobSet 資訊清單中的 /tmp/shared-memory。這兩個產生器也會在 sidecar 上設定 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 容器無法重複使用執行中的 sidecar。請先刪除並重新建立 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 的 worker Pod 上開啟 TCP 通訊埠,請先將下列覆寫套用至 JobSet 資訊清單,再執行 kubectl apply 指令:

  • 在 pathways-worker 和 colocated-python-sidecar 容器中,將名為 sidecar-socket 的 emptyDir: {} 磁碟區掛接至 /sock。
  • 在 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 標記。

使用 sidecar 映像檔提交無頭 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 暫存 bucket。
  • JAX_VERSION:JAX 版本,例如 0.12.0.1。
  • SIDECAR_IMAGE:自訂或預先建構的 sidecar 映像檔 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. 如要讓序列化依附元件與 sidecar 映像檔保持一致,請擷取 /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 worker 的共置 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 Proxy 伺服器執行指令碼:

    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 在所有 worker sidecar 執行一個平行呼叫,不需等待。

    請勿在具有 JAX_PLATFORMS=cpu 環境變數的 worker Pod 中執行用戶端指令碼,因為該設定會在本機的一個 CPU 上執行 JAX,並略過 Pathways。您可以忽略結束時顯示的任何 IFRT proxy server disconnected: CANCELLED 訊息。

如需其他使用模式,請參閱下列資源:

驗證 sidecar 部署作業

在取消或 刪除無頭 之前,或在批次工作負載仍在執行時,對無頭 JobSet 執行 kubectl logs 指令。在批次 JobSet 部署作業中,JobSet 控制器會在 pathways-head 工作完成後立即刪除 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 容器已啟用共用記憶體,並連線至 Sidecar。

執行 kubectl exec 指令檢查共用記憶體目錄時,請使用 -c colocated-python-sidecar 旗標指定 colocated-python-sidecar 容器,因為 pathways-worker 容器不含殼層。

排解共置 Python 問題

以下各節說明如何解決常見的 Python 共置問題。

Unable to unpickle 個錯誤

如果工作負載失敗,並顯示下列錯誤,表示 JAX 用戶端和邊車容器的 Python 或套件版本不同:

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

確認用戶端執行 Python 3.12 (python --version),並使用從 sidecar 映像檔擷取的 -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,再啟動其他用戶端工作階段。

共用記憶體或 Sidecar 連線錯誤

請執行下列檢查,解決共用記憶體掛接、gRPC 連線或主機記憶體錯誤:

  • Failed to stat sidecar_shm_directory:在 pathways-worker 和 colocated-python-sidecar 容器中,將共用記憶體 emptyDir 磁碟區掛接在相符的路徑 (/tmp/sidecar 或 /tmp/shared-memory)。
  • Timed out connecting to sidecar gRPC service 或 Failed to connect to external sidecar:確認 colocated-python-sidecar 容器在 initContainers 欄位下執行,且 restartPolicy: Always 和所有三個 cloud-pathways 映像檔都使用相符的標記。檢查 pathways-proxy 和 colocated-python-sidecar 容器之間的 TCP (--port=50051) 或 UDS (/sock 磁碟區和 --unix_domain_socket_path=/sock/sidecar.sock) 設定是否相符。
  • 大型陣列突發後,Worker 主機記憶體不足:在 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 中的任何自訂 sidecar 映像檔,並移除 Cloud Storage 臨時 bucket 中的暫存物件。如果不再需要 GKE 叢集,請按照「使用 Pathways 建立 GKE 叢集」中的「清除」步驟刪除叢集。

後續步驟