本頁面可協助機器學習 (ML) 工程師和平台管理員,診斷及解決 Google Cloud上 Pathways 工作負載的問題。請參閱本指南,瞭解如何檢查元件記錄、確認叢集和切片是否就緒、監控 Megascale XLA (MXLA) 移轉指標,以及修正常見的執行階段錯誤。在各個部分中,請根據您的環境選取「GKE」或「Cluster Director」分頁標籤。
事前準備
-
請根據您打算如何使用本頁範例,選取對應的分頁標籤:
gcloud
安裝 Google Cloud CLI,然後 使用聯合身分登入 gcloud CLI。 登入後,執行下列指令來初始化 Google Cloud CLI:
gcloud initREST
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
安裝 Google Cloud CLI,然後 使用聯合身分登入 gcloud CLI。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。
事前準備
GKE
繼續操作前,請先完成下列必要條件:
- 設定 Cluster Toolkit。
- 安裝 Kubernetes 工具。
- 安裝 Google Cloud CLI。
- 啟用 Kubernetes Engine API。
- 使用 Pathways 建立 Google Kubernetes Engine (GKE) 叢集。
- 如要在 Google Cloud 控制台中查看記錄和指標,請確認您具備專案的記錄檢視者 (
roles/logging.viewer) 和 Monitoring 檢視者 (roles/monitoring.viewer) Identity and Access Management (IAM) 角色。
Cluster Director
繼續操作前,請先完成下列必要條件:
- 建立 Cluster Director 叢集並設定 Pathways 環境。
- 確認您具備叢集登入節點的 SSH 存取權。
查看記錄
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 中監控這些指標,請按照下列步驟操作:
- 前往 Google Cloud 控制台的「Metrics Explorer」頁面。
- 在「選取指標」欄位中,依指標名稱篩選。
- 如要依工作負載名稱和日期範圍篩選,請按一下 新增篩選器,然後依
pod_name篩選。 - 在「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 進行彈性訓練」一文所述,設定檢查點和彈性切片重新調整。