Ray 分布式调试器#

Ray 分布式调试器包含一个调试器后端和一个 VS Code 扩展前端，通过交互式调试体验简化了调试过程。Ray 调试器使您能够

中断远程任务：在任何远程任务中设置断点。断点会暂停执行，并允许您使用 VS Code 进行调试。
事后调试：当 Ray 任务因未处理的异常而失败时，Ray 会自动冻结失败的任务并等待 Ray 调试器附加，从而允许您检查错误发生时程序的 C 状态。

Ray 分布式调试器为您抽象了调试分布式系统的复杂性，使您能够更有效地调试 Ray 应用程序，从而在开发工作流中节省时间和精力。

注意

Ray 分布式调试器前端仅在 VS Code 和其他与 VS Code 兼容的 IDE（如 Cursor）中可用。如果您需要支持其他 IDE，请在 GitHub 上提交功能请求。

设置环境#

创建一个新的虚拟环境并安装依赖项。

conda create -n myenv python=3.10
conda activate myenv
pip install "ray[default]" debugpy

启动 Ray 集群#

本地

运行 ray start --head 以启动本地 Ray 集群。

KubeRay (SSH)

按照 RayCluster 快速入门中的说明设置集群。您需要将 VS Code 连接到集群。例如，将以下内容添加到 ray-head 容器中，并确保 sshd 在 ray-head 容器中运行。

ports:
- containerPort: 22
  name: ssd

注意

如何在 ray-head 容器中运行 sshd 取决于您的设置。例如，您可以使用 supervisord。一种在交互模式下运行 sshd 进行测试的简单方法是登录到 head 节点 pod 并运行

sudo apt-get update && sudo apt-get install -y openssh-server
sudo mkdir -p /run/sshd
sudo /usr/sbin/sshd -D

然后，您可以通过运行以下命令通过 SSH 连接到集群：

kubectl port-forward service/raycluster-sample-head-svc 2222:22

在检查 ssh -p 2222 ray@localhost 可以正常工作后，按照 VS Code SSH 文档中的说明设置 VS Code。

KubeRay (Code Server，社区维护)

按照 RayCluster 快速入门中的说明设置集群。

一种更简单的方法是将基于浏览器的 VS Code (Code Server) 作为 sidecar 容器运行在 Ray head pod 中。这通过将 VS Code 放置在 Kubernetes 集群内部来消除网络连接问题。

将 sidecar 容器添加到 Ray head pod 并配置共享卷。修改您的 Ray head pod 模板，添加以下内容：

# In your RayCluster YAML, under spec.headGroupSpec.template.spec
containers:
  - name: ray-head
    # ... your existing ray-head configuration ...
    # Add this volumeMount:
    volumeMounts:
      - mountPath: /tmp/ray
        name: shared-ray-volume
  # Add this sidecar container:
  - name: vscode-debugger
    image: docker.io/onesizefitsquorum/code-server-with-ray-distributed-debugger:4.101.2
    ports:
      - containerPort: 8443
    volumeMounts:
      - mountPath: /tmp/ray
        name: shared-ray-volume
    env:
      # Specifies the default directory that opens when VSCode Web starts, pointing to the workspace containing the Ray runtime resources.
      - name: DEFAULT_WORKSPACE
        value: "/tmp/ray/session_latest/runtime_resources"
# Add this volume at the same level as `containers`:
volumes:
  - name: shared-ray-volume
    emptyDir: {}

Ray 集群运行后，转发 Code Server 端口：

kubectl port-forward pod/<ray-head-pod-name> 8443:8443

在浏览器中访问 http://127.0.0.1:8443 上的 VS Code，并使用 Ray 分布式调试器扩展连接到 http://127.0.0.1:8265。

有关更多详细信息，请参阅 Code Server with Ray Distributed Debugger 项目。

注册集群#

在 VS Code 的左侧导航栏中找到并单击 Ray 扩展。将 Ray 集群的 IP:PORT 添加到集群列表中。默认的 IP:PORT 是 127.0.0.1:8265。您可以在启动集群时更改它。确保您当前的机器可以访问该 IP 和端口。

创建 Ray 任务#

创建一个名为 job.py 的文件，其中包含以下代码片段。在 Ray 任务中添加 breakpoint()。如果您想使用下面的事后调试功能，请同时添加 RAY_DEBUG_POST_MORTEM=1 环境变量。

import ray
import sys

# Add the RAY_DEBUG_POST_MORTEM=1 environment variable
# if you want to activate post-mortem debugging
ray.init(
    runtime_env={
        "env_vars": {"RAY_DEBUG_POST_MORTEM": "1"},
    }
)


@ray.remote
def my_task(x):
    y = x * x
    breakpoint()  # Add a breakpoint in the Ray task.
    return y


@ray.remote
def post_mortem(x):
    x += 1
    raise Exception("An exception is raised.")
    return x


if len(sys.argv) == 1:
    ray.get(my_task.remote(10))
else:
    ray.get(post_mortem.remote(10))

运行您的 Ray 应用#

开始运行您的 Ray 应用。

python job.py

附加到暂停的任务#

当调试器命中断点时：

任务将进入暂停状态。
终端会清晰地指示调试器何时暂停任务并等待调试器附加。
暂停的任务会列在 Ray 调试器扩展中。
单击暂停任务名称旁边的播放图标以附加 VS Code 调试器。

开始和停止调试#

像在本地开发时一样调试您的 Ray 应用。完成当前断点的调试后，单击调试工具栏中的“**断开连接**”按钮，以便您可以加入“**暂停的任务**”列表中的另一个任务。

事后调试#

当 Ray 任务遇到未处理的异常时，使用事后调试。在这种情况下，Ray 会自动冻结失败的任务，等待 Ray 调试器附加。此功能允许您彻底检查和检视错误发生时程序的 C 状态。

运行引发异常的 Ray 任务#

使用额外的参数运行相同的 job.py 文件以引发异常。

python job.py raise-exception

附加到暂停的任务#

当应用程序抛出异常时：

调试器会冻结任务。
终端会清晰地指示调试器何时暂停任务并等待调试器附加。
暂停的任务会列在 Ray 调试器扩展中。
单击暂停任务名称旁边的播放图标以附加调试器并开始调试。

开始调试#

像在本地开发时一样调试您的 Ray 应用。

下一步#

有关调试 Ray 中分布式应用程序的指南，请参阅 General debugging。
有关使用 Ray 调试器的技巧，请参阅 Ray debugging。

Ray 分布式调试器#

设置环境#

启动 Ray 集群#

注册集群#

创建 Ray 任务#

运行您的 Ray 应用#

附加到暂停的任务#

开始和停止调试#

事后调试#

运行引发异常的 Ray 任务#

附加到暂停的任务#

开始调试#

分享反馈#

下一步#