Ray 调试教程
==================

最后更新：04/23/2025


.. _wuxibin89: https://github.com/wuxibin89

作者：`Ao Shen <https://aoshen524.github.io/>`_。

如何调试？
---------------------


Ray 分布式调试器 VSCode 扩展（推荐）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. 从 Ray 2.39 开始，Anyscale 引入了 `Ray Distributed Debugger <https://docs.ray.io/en/latest/ray-observability/ray-distributed-debugger.html>`_ VSCode 扩展。按照扩展的安装说明进行操作，然后使用您之前获得的仪表板 URL 将集群添加到扩展中。

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/debugger.png?raw=true
      :alt: Ray Distributed Debugger VSCode extension screenshot

2. 先决条件。

   确保已安装以下组件（有关更多详细信息，请参阅扩展的 README）：

   - Visual Studio Code  
   - `ray[default]` >= 2.9.1  
   - `debugpy` >= 1.8.0  

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/readme.png?raw=true
      :alt: VSCode with Ray prerequisites

3. 环境变量。

   要启用事后调试（即程序崩溃后调试），请设置：

   .. code-block:: bash

      export RAY_DEBUG_POST_MORTEM=1

   .. admonition:: Note
      :class: important

      在启动 Ray 之前，请务必移除所有旧版标志：

      - `RAY_DEBUG=legacy`  
      - `--ray-debugger-external`

4. 配置断点 在代码中设置 breakpoint() ，然后将作业提交到集群。此时扩展将显示断点信息。


   1. 在远程函数中插入 `breakpoint()` 调用。  
   2. 将作业提交到集群。  

   扩展将检测活动断点，并在 VSCode 中显示它们。

   **注意：**断点仅在用 `@ray.remote` 装饰的函数内部受支持。

5. 启动调试器。

   直接从命令行运行作业（请勿使用 `launch.json`）：

   .. code-block:: bash

      python job.py

6. 附加到断点。

   一旦进程遇到第一个 `breakpoint()`，请点击 VSCode 侧边栏中的 Ray Distributed Debugger 图标来附加调试器。

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/launch.png?raw=true
      :alt: Attaching VSCode debugger to Ray process

7. 使用多个 breakpoint() 进行调试。

   对于每个后续任务，首先断开当前调试器会话，然后再次点击扩展图标以附加到下一个断点。

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/disconnect.png?raw=true
      :alt: Disconnecting and reconnecting the debugger

旧版 Ray 调试器
~~~~~~~~~~~~~~~~~~~
1. Ray 内置了旧版 `debugger <https://docs.ray.io/en/latest/ray-observability/user-guides/debug-apps/ray-debugging.html>`_，允许您调试分布式应用程序。要启用调试器，请使用 ``RAY_DEBUG=legacy`` 和 ``--ray-debugger-external`` 启动 Ray 集群。

.. code-block:: bash

    # start head node
    RAY_DEBUG=legacy ray start --head --dashboard-host=0.0.0.0 --ray-debugger-external
    # start worker node
    RAY_DEBUG=legacy ray start --address='10.124.46.192:6379' --ray-debugger-external

2. 在代码中设置断点，然后将作业提交到集群。随后运行 ``ray debug`` 以等待断点：

.. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/legacy.png?raw=true