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

最后更新：04/23/2025


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

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

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


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

1. 从 Ray 2.39 开始，Anyscale 推出了 `Ray 分布式调试器 <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 分布式调试器 VSCode 扩展截图

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 和 Ray 先决条件

3. 环境变量。

   要启用事后调试，请设置：

   .. code-block:: bash

      export RAY_DEBUG_POST_MORTEM=1

   .. admonition:: 注意
      :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 分布式调试器图标以附加调试器。

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/launch.png?raw=true
      :alt: 将 VSCode 调试器附加到 Ray 进程

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

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

   .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray/disconnect.png?raw=true
      :alt: 断开和重新连接调试器

旧版 Ray 调试器
~~~~~~~~~~~~~~~~~~~
1. Ray 包含一个内置的旧版 `调试器 <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

    # 启动头节点
    RAY_DEBUG=legacy ray start --head --dashboard-host=0.0.0.0 --ray-debugger-external
    # 启动工作节点
    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