為避免透過 Google Kubernetes Engine (GKE) 上的單一 Pathways 控制器,轉送資料載入和檢查點等主機繫結工作,請使用 JAX 共置 Python API,在 Cloud TPU worker VM 上執行這些函式。
本文檔適用於機器學習工程師,說明共置 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 臨時 bucket。
- 如果您打算建構自訂 sidecar 映像檔,請建立 Artifact Registry Docker 存放區。
- 在執行 JAX 工作負載的用戶端環境中,安裝 Python 3.12。
- 選用:如要使用 Cluster Toolkit 部署,請安裝 1.108.0 以上版本的
gclusterCLI。
必要的角色
授予下列 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 記錄。
- Artifact Registry
寫入者
(
- GKE 節點集區服務帳戶:如果節點集區使用
--workload-metadata=GCE_METADATA旗標,Pathways Pod 會使用這個服務帳戶,如「建立具備 Pathways 的 GKE 叢集」一節所述:- 託管私人存放區的 Google Cloud 專案具備 Artifact Registry 讀取者 (
roles/artifactregistry.reader) 角色,可提取自訂 sidecar 映像檔。 - Cloud Storage 臨時 bucket 的 Storage 物件管理員 (
roles/storage.objectAdmin),用於編譯快取和其他暫存檔案。
- 託管私人存放區的 Google Cloud 專案具備 Artifact Registry 讀取者 (
選用:如要允許 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-headPod):透過 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 會分兩個階段在叢集中執行:
- 函式轉送:
jax.experimental.colocated_python模組會將函式封裝至臨時架構執行階段 (IFRT) 程式,並傳送至pathways-proxy容器。Proxy 只會將程式轉送至含有輸入 shard 的 worker VM,並在所有本機 shard 中,每個 VM 執行一次。 - 共用記憶體執行:
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 版本相符的預先建構映像檔:
在空白建構目錄中,為額外套件建立
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。建構及推送自訂 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 資訊清單,請完成下列步驟:
使用下列任一工具產生
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):執行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容器。gclusterCLI 會將 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旗標。
套用
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"]和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 標記。
使用 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-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 用戶端指令碼:
如要讓序列化依附元件與 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。如果您在
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 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}" )對 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環境變數的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選項,在 worker sidecar 上建立分散式查核點
驗證 sidecar 部署作業
在取消或
刪除無頭 之前,或在批次工作負載仍在執行時,對無頭 JobSet 執行 kubectl logs 指令。在批次 JobSet 部署作業中,JobSet 控制器會在 pathways-head 工作完成後立即刪除 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容器已啟用共用記憶體,並連線至 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 叢集」中的「清除」步驟刪除叢集。