排查 Pathways on Cloud 问题

预览版

此产品或功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅 发布阶段说明。

准备工作

• 已安装 XPK
• 已安装 Kubernetes 工具
• 已安装 gcloud CLI
• 已启用 TPU API
• 已启用 Google Kubernetes Engine API
• 已创建 Google Kubernetes Engine 集群

本文档介绍了如何排查 Pathways 工作负载的问题。

查看日志

在 Cloud Logging Logs Explorer中， 使用以下查询，并根据您的项目、区域、集群和 工作负载进行调整。

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

替换以下内容：

• PROJECT：您的 Google Cloud 项目 ID
• LOCATION：您创建 GKE 集群的区域或可用区
• CLUSTER：GKE 集群的名称
• WORKLOAD_NAME：使用 XPK 时工作负载的名称，或使用 kubectl 时 JobSet 的名称

此查询将匹配多个 Pathways Kubernetes 容器，其名称类似于 pathways-rm、pathways-proxy、pathways-worker。您可以通过添加容器名称过滤条件（例如 resource.labels.container_name:"<container_name>"）来缩小导致问题的容器范围

监控

运行状况监控

您可以通过在容器日志中查找条目来监控各种 Pathways 组件的运行状况，例如：

写入以下日志时，pathways-proxy 已准备好处理新的连接请求：

kubectl logs ${HEAD_POD_NAME} --container pathways-proxy
...
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 [::]:29001

如需验证注册到 Pathways Resource Manager 的所有 TPU 是否已准备就绪，您可以查找 ***<num slices>/<num slices> Pathways Slices Now Ready ***，具体请查看pathways-rm 容器日志：

kubectl logs $HEAD_POD_NAME --container pathways-rm
...
I1101 04:52:41.967764       1 multi_job_allocator.cc:1063] *** 2/2 Pathways Slices Now Ready ***

只要代理服务器准备就绪，即使并非所有切片都准备就绪，Pathways 客户端也可以连接到 IFRT 代理服务器。在切片准备就绪之前，您的作业将使用虚拟切片。当 TPU 不可用时，虚拟切片可让您的代码运行。

写入以下日志时，pathways-worker 已准备好处理新的连接请求：

kubectl logs $WORKER_POD_NAME --container pathways-worker
...
I1101 04:50:41.967764       1 server_lib.cc:1473] Pathways Server serving on [::]:29001

指标收集

Pathways 可以将低级别系统指标写入 Cloud Monitoring 以进行调试。 这些指标包括：

• DCN 传输延迟时间
• 总体延迟时间
• 从主机到设备的传输延迟时间
• 从设备到主机的传输延迟时间

您可以在运行 GKE 集群的 {gcp_name} 项目的 Cloud Monitoring 信息中心内找到这些指标。

如需在 Metrics Explorer 中监控这些指标，请执行以下操作：

1. 前往 Metrics Explorer
2. 使用“选择指标”字段按指标名称进行过滤
3. 选择“添加过滤条件”并 按“pod_name”过滤，按工作负载名称和时间范围进行过滤
4. 根据您要监控的指标和工作负载，选择适当的“聚合类型”

DCN 传输延迟时间

这是一个 Megascale XLA (MXLA) 指标，用于衡量多切片流量的网络传输延迟时间的累积分布。延迟时间测量从发出通过 DCN 传输数据的请求开始，到收到数据传输已完成的确认时结束。如需监控此指标，请按 dcn_transfer_latencies 指标名称进行过滤。

总体延迟时间

这是一个 MXLA 指标，用于衡量多切片流量的端到端总体延迟时间的累积分布。延迟时间测量从发出总体请求开始，到收到数据传输已完成的确认时结束。如需监控此指标，请按 collective_e2e_latency 指标名称进行过滤。

主机到设备的传输延迟时间

这是一个 MXLA 指标，用于衡量多切片流量的从主机到设备的传输延迟时间的累积分布。延迟时间测量从发出通过 DCN 传输数据的请求开始，到收到数据传输已完成的确认时结束。如需监控此指标，请按 host_to_device_transfer_latencies 指标名称进行过滤。

从设备到主机的传输延迟

这是一个 MXLA 指标，用于衡量多切片流量的从设备到主机的传输延迟时间的累积分布。延迟时间测量从发出通过 DCN 传输数据的请求开始，到收到数据传输已完成的确认时结束。如需监控此指标，请按 device_to_host_transfer_latencies 指标名称进行过滤。

调试常见错误

无法对加速器配置警告进行哈希处理

以下消息仅为警告，不会影响 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 服务 账号具有向日志记录系统写入日志条目的权限 Google Cloud 。

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)."}"
>

如需解决此问题，请向 Compute Engine 服务帐号添加日志写入器 角色。

无法连接到 IFRT 代理服务器

如果您看到此错误，则表示您的 IFRT 代理客户端无法连接到 IFRT 代理服务器。

• 确保您的 VPC 网络配置正确
• 确保您的防火墙配置为允许连接
• 确保您的 Pathways 集群已预配
• 检查启动错误消息

当您的第一个 JAX 命令（该命令向 Pathways 集群发送 IFRT 命令） 尝试执行时，它将停止响应大约一分钟，然后显示类似以下内容的 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)

与 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 list --outdated (replacing pip with pip3 as needed)

如果列出了 Flask 或 Werkzeug，请考虑升级它们，但请注意，这样做可能会破坏项目中的其他软件包或依赖项：

 pip install flask Werkzeug --upgrade ()

来自代理服务器的内部错误

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

此错误表示 IFRT 代理服务器已与客户端断开连接。 您可以通过重启客户端来解决此问题。对于笔记本，您可以重启笔记本内核并重新运行笔记本。

SIGTERMS 和 HBM OOM

在与 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 存储桶已达到生命周期政策上限，则会出现此错误。如果发生这种情况，请清理不再使用的 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 位置时，系统会在 Resource Manager 或 Pathways 工作器上输出此错误。

来自守护程序的错误响应

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

这是由于 Docker 版本过旧所致，请升级您的 Docker 版本。

IFRT 代理客户端和服务器未能达成一致

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

这表示正在使用旧版 MaxText，请确保您重新构建最新的 MaxText 映像。

后续步骤

• 使用 Pathways 进行多主机推理
• 使用 Pathways 处理批量工作负载
• Pathways 互动模式
• 将 JAX 工作负载移植到 Pathways
• 使用 Pathways 进行弹性训练