排解 Pathways on Cloud 問題

本頁面可協助機器學習 (ML) 工程師和平台管理員,診斷及解決 Google Cloud上 Pathways 工作負載的問題。請參閱本指南,瞭解如何檢查元件記錄、確認叢集和切片是否就緒、監控 Megascale XLA (MXLA) 移轉指標,以及修正常見的執行階段錯誤。在各個部分中,請根據您的環境選取「GKE」或「Cluster Director」分頁標籤。

事前準備

事前準備

GKE

繼續操作前,請先完成下列必要條件:

Cluster Director

繼續操作前,請先完成下列必要條件:

查看記錄

GKE

您可以使用 gcluster job logs 指令,直接查看 Pathways 工作負載的記錄 (傳遞 --main-only=false 即可納入 worker Pod 記錄):

gcluster job logs WORKLOAD_NAME \
    --cluster=CLUSTER \
    --project=PROJECT_ID \
    --location=LOCATION \
    --main-only=false

更改下列內容:

  • WORKLOAD_NAME:使用 Cluster Toolkit 時的工作負載名稱,或使用 kubectl 時的 JobSet 名稱。
  • CLUSTER:GKE 叢集名稱。
  • PROJECT_ID:Google Cloud 專案 ID。
  • LOCATION:建立 GKE 叢集的區域或可用區。

如要使用 kubectl 列出工作負載的所有 Pod,請依 JobSet 名稱標籤篩選:

kubectl get pods \
    -l jobset.sigs.k8s.io/jobset-name=WORKLOAD_NAME

如要查看工作負載狀態或列出失敗的工作,請使用 gcluster job list 指令:

gcluster job list --status Failed \
    --cluster=CLUSTER \
    --project=PROJECT_ID \
    --location=LOCATION

或者,您也可以在 Cloud Logging Logs Explorer 中,執行下列查詢,並根據專案、位置、叢集和工作負載調整:

resource.type="k8s_container"
resource.labels.project_id="PROJECT_ID"
resource.labels.location="LOCATION"
resource.labels.cluster_name="CLUSTER"
resource.labels.namespace_name="default"
resource.labels.pod_name:"WORKLOAD_NAME"

這項查詢會比對多個 Pathways Kubernetes 容器,名稱包括 pathways-rm、pathways-proxy、pathways-worker 和 workload-container。如要判斷是哪個容器造成問題,請新增容器名稱篩選器,例如 resource.labels.container_name:"CONTAINER_NAME",其中 CONTAINER_NAME 是容器名稱。

Cluster Director

Pathways 指令碼會將記錄寫入共用檔案系統:

  • Pathways 服務工作會在您執行 sbatch 的目錄中寫入 pathways-service-SERVICE_JOB_ID.out 和 pathways-service-SERVICE_JOB_ID.err,例如 ~/pathways。
  • Pathways 資源管理工具、IFRT Proxy 伺服器和 TPU 工作站會寫入 ~/pathways/service_SERVICE_JOB_ID/logs,包括 rm.log、proxy.log,以及每個 worker 任務一個 slice-*.out 和 slice-*.err 檔案。
  • MaxText 工作負載範例會將記錄寫入 maxtext-llama31-JOB_ID.err。

在登入節點上,檢查 Pathways 工作的狀態,並找出工作 ID:

squeue -u ${USER}

監控 Pathways 元件和指標

下列各節適用於 GKE 上的 Pathways。

健康狀態監控功能

您可以查看容器記錄中的項目,監控各種 Pathways 元件的健康狀態。

pathways-proxy 容器寫入下列記錄項目後,即可處理新的連線要求。如要查看記錄,請執行下列指令:

kubectl logs HEAD_POD_NAME --container pathways-proxy

將 HEAD_POD_NAME 替換為 Pathways head Pod 的名稱。

輸出內容會包含類似以下的一行:

I1101 04:51:41.967764       1 proxy_server.cc:125] IFRT proxy server started with status OK

pathways-rm 容器寫入下列記錄項目時,就表示已準備好處理新的連線要求:

kubectl logs HEAD_POD_NAME --container pathways-rm

輸出內容會包含類似以下的一行:

I1101 04:50:41.967764       1 server_lib.cc:1473] Pathways Server serving on POD_IP:29001

POD_IP 是 Pod 的 IP 位址,可能會在 Pod 重新啟動或重新排程時變更。

如要確認所有 TPU 切片都已準備就緒,請查看 pathways-rm 容器記錄中的 Pathways Slices Now Ready:

kubectl logs HEAD_POD_NAME --container pathways-rm

舉例來說,下列記錄項目顯示 2 個切片都已準備就緒:

I1101 04:52:41.967764       1 multi_job_allocator.cc:1063] *** 2/2 Pathways Slices Now Ready ***

只要 Proxy 伺服器準備就緒,Pathways 用戶端就能連線至 IFRT Proxy 伺服器,即使並非所有配量都已就緒也沒問題。在 TPU slice 準備就緒前,工作會使用虛擬 slice。虛擬切片可讓程式碼在 TPU 無法使用時執行。

如要確認 pathways-worker 容器是否已準備就緒,請查看其記錄:

kubectl logs WORKER_POD_NAME --container pathways-worker

將 WORKER_POD_NAME 替換為 Pathways worker Pod 的名稱。

worker 準備就緒後,輸出內容會包含類似下列的行:

I1101 04:50:41.967764       1 server_lib.cc:1473] Pathways Server serving on POD_IP:29005

POD_IP 是 Pod 的 IP 位址,可能會在 Pod 重新啟動或重新排程時變更。

指標收集

Pathways 可將低階系統指標寫入 Cloud Monitoring,以便偵錯。這些指標包括:

  • 資料中心網路 (DCN) 傳輸延遲時間
  • 集體作業延遲時間
  • 主機到裝置的傳輸延遲時間
  • 裝置到主機的傳輸延遲時間

您可以在執行 GKE 叢集的Google Cloud 專案 Monitoring 資訊主頁中找到指標。

如要在 Metrics Explorer 中監控這些指標,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的「Metrics Explorer」頁面。
  2. 在「選取指標」欄位中,依指標名稱篩選。
  3. 如要依工作負載名稱和日期範圍篩選,請按一下 新增篩選器,然後依 pod_name 篩選。
  4. 在「Aggregation」(匯總) 部分,根據您監控的指標和工作負載,選擇匯總類型。

DCN 傳輸延遲時間

這項 Megascale XLA (MXLA) 指標會評估多切片流量的網路傳輸延遲時間累積分布。系統發出要求,透過 DCN 移轉資料時,就會開始計算延遲時間,並在收到資料移轉完成的確認訊息時結束。如要監控這項指標,請依 dcn_transfer_latencies 指標名稱篩選。

集體作業延遲時間

這項 MXLA 指標會評估多切片流量的端對端集體延遲時間累積分佈。系統發出集體作業要求時,會開始測量延遲時間,並在收到資料移轉完成的確認訊息時結束。如要監控這項指標,請依 collective_end_to_end_latencies 指標名稱篩選。

主機到裝置的傳輸延遲時間

這項 MXLA 指標會評估多配量流量的主機到裝置傳輸延遲時間累積分布。延遲時間的計算方式如下:從系統發出要求,將資料從主機移轉至 TPU 裝置時開始,到系統收到資料移轉完成的確認訊息時結束。如要監控這項指標,請依 host_to_device_transfer_latencies 指標名稱篩選。

裝置到主機的傳輸延遲時間

這項 MXLA 指標會評估多切片流量的裝置到主機傳輸延遲時間累積分布。延遲時間會從系統發出要求,將資料從 TPU 裝置移轉至主機時開始計算,並在收到資料移轉完成的確認訊息時結束。如要監控這項指標,請依 device_to_host_transfer_latencies 指標名稱篩選。

排解常見錯誤

GKE

無法雜湊加速器設定警告

下列訊息僅為警告,不會影響 JAX 程式碼的效能:

INFO:jax._src.cache_key:get (_hash_accelerator_config): unable to hash accelerator config, falling back to hashing devices + platform: UNIMPLEMENTED: GetTopologyForDevices is not supported for the IFRT proxy client. (type <class 'jaxlib.xla_extension.XlaRuntimeError'>)

資源的「logging.logEntries.create」權限遭拒

如果看到下列錯誤,請確認 Vertex AI Workbench 使用的 Compute Engine 服務帳戶,具備將記錄項目寫入 Logging 的權限:

INFO:absl:Created 'ArrayHandler' with primary_host=0, replica-id=0
WARNING:absl:pathwaysutils: Detected Pathways-on-Cloud backend. Applying changes.
Failed to submit 1 logs.
Traceback (most recent call last):
  File "/opt/conda/lib/python3.10/site-packages/google/api_core/grpc_helpers.py", line 65, in error_remapped_callable
    return callable_(**args, **kwargs)
  File "/opt/conda/lib/python3.10/site-packages/grpc/_channel.py", line 1181, in __call__
    return _end_unary_response_blocking(state, call, False, None)
  File "/opt/conda/lib/python3.10/site-packages/google/api_core/grpc_helpers.py", line 1006, in _end_unary_response_blocking
    raise _InactiveRpcError(state) # pytype: disable-not-instantiable
grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
  status = StatusCode.PERMISSION_DENIED
  details = "Permission 'logging.logEntries.create' denied on resource (or it may not exist)."
  debug_error_string = "UNKNOWN:Error received from peer ipv4:216.239.34.174:443 {created_time:"2024-10-03T20:30:44.820425276+00.00", grpc_status:7, grpc_message:"Permission \'logging.logEntries.create\' denied on resource (or it may not exist)."}"
>

如要修正這個問題,請將記錄檔寫入者 (roles/logging.logWriter) 角色授予 Compute Engine 服務帳戶。

無法連線至 IFRT Proxy 伺服器

當您首次執行 JAX 指令,將 IFRT 指令傳送至 Pathways 叢集時,指令可能會停止回應約一分鐘,然後顯示類似下列的 RuntimeError:

RuntimeError: Unable to initialize backend 'proxy': UNAVAILABLE: Unable to establish connection to ifrt_proxy server, please check provided address example-workload-proxy-0-0.example-workload.default.svc.example-cluster-domain.:38676'; detailed error: DNS resolution failed (set JAX_PLATFORMS='' to automatically choose an available backend)

如果看到這則錯誤訊息,表示 IFRT Proxy 用戶端無法連線至 IFRT Proxy 伺服器。請確認下列事項:

  • 確認虛擬私有雲 (VPC) 網路設定正確。
  • 確認防火牆規則允許連線。
  • 確認 Pathways 叢集已佈建。
  • 查看容器記錄中的啟動錯誤訊息。

連線至 IFRT Proxy 伺服器時,ALTS 握手失敗或通訊端關閉

在 Workload Identity Federation for GKE 節點集區中,如果執行不含 hostNetwork: true 欄位的自訂資訊清單,可能會看到 Alts handshake failed (TSI_INTERNAL_ERROR) 或 UNAVAILABLE: Unable to establish connection to ifrt_proxy server ... Socket closed。如要解決這個問題,請在 pathways-proxy 容器和 JAX 用戶端容器上設定 IFRT_PROXY_USE_INSECURE_GRPC_CREDENTIALS: "true" 環境變數 (兩端必須相符)。新增這個環境變數會停用 ALTS,並改用不安全的 gRPC,因此請務必只在受信任的叢集網路中使用。

已有連至 Pathways 叢集的連線

Pathways 叢集一次只能與一個用戶端維持工作階段。如果兩個獨立的筆記本嘗試連線至同一個 Pathways 叢集,其中一個會連線,另一個則會顯示下列錯誤:

INFO:absl:Created ArrayHandler with primary_host=0, replica_id=0
WARNING:absl:pathwaysutils: Detected Pathways-on-Cloud backend. Applying changes.
E0927 21:19:52.919607   37624 rpc_helper.cc:56] Connection to IFRT proxy server was terminated: CANCELLED: Cancelled
E0927 21:20:03.467547   37719 rpc_helper.cc:56] Connection to IFRT proxy server was terminated: CANCELLED: Cancelled
E0927 21:20:14.011645   37807 rpc_helper.cc:56] Connection to IFRT proxy server was terminated: CANCELLED: Cancelled
E0927 21:20:24.557955   37924 rpc_helper.cc:56] Connection to IFRT proxy server was terminated: CANCELLED: Cancelled
---------------------------------------------------------------------------
XlaRuntimeError                           Traceback (most recent call last)
File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:887, in backends()
    885   continue
--> 887 backend = _init_backend(platform)
    888 _backends[platform] = backend

File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:973, in _init_backend(platform)
    972 logger.debug("Initializing backend '%s'", platform)
--> 973 backend = registration.factory()
    974 # TODO: consider raising more descriptive errors directly from backend
    975 # factories instead of returning None.

File /opt/conda/lib/python3.10/site-packages/pathwaysutils/proxy_backend.py:24, in register_backend_factory.<locals>.<lambda>()
     21 def register_backend_factory():
     22   xla_bridge.register_backend_factory(
     23       "proxy",
---> 24       lambda: ifrt_proxy.get_client(
     25           jax.config.read("jax_backend_target"),
     26           ifrt_proxy.ClientConnectionOptions(),
     27       ),
     28       priority=-1,
     29   )

XlaRuntimeError: UNAVAILABLE: Unable to establish connection to ifrt_proxy server, please check provided address example-workload-proxy-0-0.example-workload.default.svc.example-cluster-domain.:38676'; detailed error: Connection to IFRT proxy server was terminated: CANCELLED: Cancelled

During handling of the above exception, another exception occurred:

RuntimeError                              Traceback (most recent call last)
Cell In[2], line 4
      1 import pathwaysutils
      3 import jax
----> 4 print(jax.devices())

File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:1085, in devices(backend)
   1060 def devices(
   1061     backend: str | xla_client.Client | None = None
   1062 ) -> list[xla_client.Device]:
   1063   """Returns a list of all devices for a given backend.
   1064
   1065   .. currentmodule:: jaxlib.xla_extension
   (...)
   1083     List of Device subclasses.
   1084   """
-> 1085   return get_backend(backend).devices()

File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:1019, in get_backend(platform)
   1015 @lru_cache(maxsize=None)  # don't use util.memoize because there is no X64 dependence.
   1016 def get_backend(
   1017     platform: None | str | xla_client.Client = None
   1018 ) -> xla_client.Client:
-> 1019   return _get_backend_uncached(platform)

File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:998, in _get_backend_uncached(platform)
    994   return platform
    996 platform = (platform or _XLA_BACKEND.value or _PLATFORM_NAME.value or None)
--> 998 bs = backends()
    999 if platform is not None:
   1000   platform = canonicalize_platform(platform)

File /opt/conda/lib/python3.10/site-packages/jax/_src/xla_bridge.py:903, in backends()
    901       else:
    902         err_msg += " (you may need to uninstall the failing plugin package, or set JAX_PLATFORMS=cpu to skip this backend.)"
--> 903       raise RuntimeError(err_msg)
    905 assert _default_backend is not None
    906 if not config.jax_platforms.value:

RuntimeError: Unable to initialize backend 'proxy': UNAVAILABLE: Unable to establish connection to ifrt_proxy server, please check provided address 'example-workload-proxy-0-0.example-workload.default.svc.example-cluster-domain.:38676'; detailed error: Connection to IFRT proxy server was terminated: CANCELLED: Cancelled (set JAX_PLATFORMS='' to automatically choose an available backend)

原始用戶端中斷連線後,第二個用戶端才能連線。如果連線意外中斷,您可能需要重新啟動 Pathways 叢集,其他用戶端才能連線。

LocalProxy.__init__() 收到非預期的關鍵字引數 'unbound_message'

如果匯入 pathwaysutils 後看到下列錯誤,請檢查環境中是否安裝了過時的 Flask 或 Werkzeug 版本 (如有需要,請將 pip3 替換為 pip):

pip3 list --outdated

如果列出 Flask 或 Werkzeug,請升級套件 (請注意,升級可能會影響專案中的其他套件或依附元件):

pip3 install --upgrade flask Werkzeug

Proxy 伺服器發生內部錯誤

"Internal error from proxy server during Array::IsDeleted(): UNAVAILABLE:Connection to IFRT proxy server was terminated: FAILED_PRECONDITION:
GrpcClientSession: writes no longer allowed."

這項錯誤表示 IFRT Proxy 伺服器與用戶端中斷連線。如要修正這個問題,請重新啟動用戶端。如果是筆記本,請重新啟動筆記本核心,然後重新執行筆記本。

SIGTERM 和 HBM 記憶體不足

如果記錄中出現與 RESOURCE_EXHAUSTED 錯誤相關聯的 SIGTERM 項目,可能表示發生高頻寬記憶體 (HBM) 記憶體不足 (OOM) 錯誤。在這種情況下,請減少 JAX 程式碼使用的 HBM 量。

INVALID_ARGUMENT

"INVALID_ARGUMENT : Permanent error, with a last message of Lifecycle
matches_prefix cannot specify more than 50 prefixes per config.; Error while
initializing persistent cache storage Cloud Storage"

如果傳遞至 --pathways-gcs-location 旗標的 Cloud Storage bucket 已達生命週期政策上限 (50 個前置字串),就會發生這項錯誤。如要解決這個問題,請刪除不再使用的 Cloud Storage 生命週期政策。

永久錯誤

Permanent error, with a last message of The specified bucket does not exist.; Error while initializing persistent cache storage gcs

如果您為 Pathways 容器提供無效的 Cloud Storage 位置,Pathways 資源管理工具或 Pathways worker 會顯示這項錯誤。

Error response from daemon

Error response from daemon: dockerfile parse error line 16: Unknown flag: exclude

如果使用舊版 Docker,就會發生這項錯誤。升級 Docker 版本。

IFRT Proxy 用戶端和伺服器無法達成協議

IFRT Proxy client and server failed to agree on the protocol version; supported versions: client = [1, 1], server = [3, 14]

這項錯誤表示您使用的是舊版 MaxText。重新建構最新的 MaxText 映像檔。

Cluster Director

setup_env.sh 失敗,並顯示 Enroot mktemp 錯誤

如果 setup_env.sh 失敗並顯示下列錯誤,表示 Enroot 的暫存目錄不存在:

mktemp: failed to create directory via template '/tmp/UID/tmp/enroot...'

如要修正這個問題,請執行 mkdir -p /tmp/$(id -u)/tmp,然後再次執行指令碼。

setup_env.sh 無法提取 Pathways 映像檔

如果 setup_env.sh 失敗並顯示 Couldn't pull ...,表示要求的 JAX_VERSION 沒有標記 Pathways 映像檔。使用支援的 JAX 版本。

叢集沒有 cpu 分區

如果 sinfo 未顯示 cpu 分區,表示叢集定義缺少 CPU 節點集,或分區名稱不同。Pathways 指令碼會將工作提交至名為 cpu 的分區。如要修正這個問題,請更新叢集藍圖,定義名為 cpu 的 CPU 分區,然後重新部署叢集,或更新 Pathways 工作指令碼中的分區名稱,使其與 sinfo 顯示的 CPU 分區相符。

TPU 節點未啟動

請確認預留項目位於叢集的可用區,且有足夠的 ct6e-standard-4t VM,以及 staticNodeCount 和 acceleratorTopology 相符。

Pathways 服務結束,並顯示 Invalid partition name specified

PARTITION 變數有誤。從 sinfo 的輸出內容中選擇 TPU 分區。

Pathways 服務未就緒

如果服務記錄維持在 Waiting for at least MIN_SLICES=...,表示執行的切片數量不足。下列指令的 NODELIST(REASON) 欄會顯示原因,例如沒有可用容量,或 SLICE_SHAPE 值與 TPU 節點集不符:

squeue -u ${USER} -n pw-slice

Pathways 資源管理工具或 IFRT Proxy 伺服器未啟動

如果服務失敗,並顯示 Timed out waiting for Pathways Resource Manager 或 Timed out waiting for Pathways IFRT Proxy Server,表示 Pathways 容器未啟動。請查看記錄目錄中的 rm.log 和 proxy.log。

Pathways 服務意外停止

如果服務因 The Pathways Resource Manager or IFRT proxy exited 而停止,表示其中一個 worker 停止運作,服務也停止了 worker。請檢查記錄目錄中的 rm.log 和 proxy.log,然後再次啟動服務。

TPU 節點卡在不良狀態

如要復原節點,請在登入節點執行下列指令:

sudo scontrol update nodename=NODE \
    state=power_down_force

將 NODE 替換為節點名稱,如 sinfo 所示。

MaxText 找不到執行中的 Pathways 服務

如果 MaxText 失敗並顯示 No running Pathways service after 60 minutes,表示服務未執行或尚未就緒。查看服務記錄。如要等待更久,請在提交 run_maxtext.sh 時設定 SERVICE_WAIT_MINUTES。

MaxText 失敗,並顯示 RESOURCE_EXHAUSTED

模型不適合 TPU 記憶體。使用 2x4 或 4x4 切片,或設定 REDUCED_LAYERS=1。

MaxText 工作維持待處理狀態

除了 Pathways 服務使用的資源外,CPU 節點沒有 run_maxtext.sh 要求的 8 個 CPU 和 96 GB 記憶體。如要修正這個問題,請增加 cpu 分區的 CPU 和記憶體容量 (或節點數量),或減少 run_maxtext.sh 的資源要求。

無法連線至 IFRT Proxy 伺服器

如果用戶端停止回應或失敗,並顯示 UNAVAILABLE,表示無法連線至 Proxy 伺服器:

  • 確認服務記錄顯示 READY。
  • 確認 JAX_BACKEND_TARGET 與 ~/pathways/cluster.env 中的地址相符。
  • 如果您使用通訊埠轉送,請確認 SSH 通道仍在運作。
  • 如果用戶端在 VM 上執行,請確認 VM 位於叢集的子網路中。下列指令應會成功:

    nc -zv PROXY_IP 29000

    將 PROXY_IP 替換為服務記錄中的 IFRT Proxy IP 位址。

jax.devices() 列出 CPU 裝置,而非 TPU 裝置

您在匯入 jax 後設定了 JAX_PLATFORMS 和 JAX_BACKEND_TARGET 環境變數。重新啟動筆記本核心,並在匯入 jax 前設定變數。

連線至 IFRT Proxy 伺服器後立即發生的錯誤

用戶端的 jax 或 pathwaysutils 版本與 Pathways 伺服器不符。安裝 ~/pathways/venv 中的版本。

運算失敗,並顯示 DATA_LOSS 和 PlacementDataLoss

運算作業使用的裝置位於未執行的切片上。確認 MIN_SLICES 等於 MAX_SLICES,且每項 worker 工作都在執行中:

squeue -u ${USER} -n pw-slice

Spot 搶占後運算失敗

使用被占用的配量裝置進行的運算會失敗。如要從 Spot 預先分配中自動復原,請按照「使用 Pathways 進行彈性訓練」一文所述,設定檢查點和彈性切片重新調整。

後續步驟