从源码构建 Ray

要为 Ray 仓库贡献代码，请按照以下说明从最新的 master 分支构建。

提示

如果只编辑 Python 文件，请按照构建 Ray（仅限 Python）的说明进行，以避免长时间构建。

如果您已经按照构建 Ray（仅限 Python）中的说明进行了操作，并希望切换到本节中的完整构建，则需要先卸载。

Fork Ray 仓库

Fork 开源仓库是贡献代码时的最佳实践，因为它允许您进行和测试更改，而不会影响原始项目，确保了干净有序的协作过程。您可以通过向主项目的仓库提交 pull request 来提议更改。

1. 导航到Ray GitHub 仓库。

2. 按照以下GitHub 说明，并执行以下操作：

   1. 使用您偏好的方式Fork 仓库。

   2. 克隆到您的本地机器。

   3. 将您的仓库连接到上游（主项目）Ray 仓库以同步更改。

准备一个 Python 虚拟环境

创建一个虚拟环境以防止版本冲突，并使用独立的、项目特定的 Python 环境进行开发。

conda

设置一个名为 myenv 的 conda 环境

conda create -c conda-forge python=3.9 -n myenv

激活您的虚拟环境，告诉 shell/终端使用这个特定的 Python

conda activate myenv

每次启动新的 shell/终端以在 Ray 上工作时，都需要激活虚拟环境。

venv

使用 Python 集成的 venv 模块在当前目录中创建一个名为 myenv 的虚拟环境

python -m venv myenv

这包含一个目录，其中包含项目本地 Python 使用的所有包。您只需执行此步骤一次。

激活您的虚拟环境，告诉 shell/终端使用这个特定的 Python

source myenv/bin/activate

每次启动新的 shell/终端以在 Ray 上工作时，都需要激活虚拟环境。

创建新的虚拟环境时，pip 和 wheel 的版本可能较旧。为避免安装包时出现问题，请使用 pip 模块安装最新版本的 pip（自身）和 wheel

python -m pip install --upgrade pip wheel

构建 Ray（仅限 Python）

注意

除非另有说明，否则目录和文件路径是相对于项目根目录的。

RLlib, Tune, Autoscaler 和大多数 Python 文件不需要您构建和编译 Ray。请按照以下说明在本地开发 Ray 的 Python 文件，无需构建 Ray。

1. 确保您已经按照上述说明克隆了 Ray 的 git 仓库。

2. 确保您已经按照上述说明激活了 Python（虚拟）环境。

3. Pip 安装 最新的 Ray wheels。有关说明，请参阅每日发布 (Nightlies)。

# For example, for Python 3.9:
pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp39-cp39-manylinux2014_x86_64.whl

4. 用本地可编辑副本替换已安装包中的 Python 文件。我们提供了一个简单的脚本来帮助您完成此操作：python python/ray/setup-dev.py。运行此脚本将删除 ray pip 包捆绑的 ray/tune、ray/rllib、ray/autoscaler 目录（以及其他目录），并将其替换为指向您本地代码的链接。这样，更改 git 克隆中的文件将直接影响已安装 Ray 的行为。

# This replaces `<package path>/site-packages/ray/<package>`
# with your local `ray/python/ray/<package>`.
python python/ray/setup-dev.py

注意

[高级] 您还可以选择跳过为您选择的目录创建符号链接。

# This links all folders except "_private" and "dashboard" without user prompt.
python python/ray/setup-dev.py -y --skip _private dashboard

警告

如果您以这种方式设置环境，请勿运行 pip uninstall ray 或 pip install -U（对于 Ray 或 Ray wheels）。要卸载或升级，必须首先 rm -rf pip 安装位置（通常是 site-packages/ray 位置的目录），然后重新进行 pip 安装（参见上面的命令），最后再次运行上面的 setup-dev.py 脚本。

# To uninstall, delete the symlinks first.
rm -rf <package path>/site-packages/ray # Path will be in the output of `setup-dev.py`.
pip uninstall ray # or `pip install -U <wheel>`

准备在 Linux 上构建 Ray

提示

如果您只编辑 Tune/RLlib/Autoscaler 文件，请按照构建 Ray（仅限 Python）的说明进行，以避免长时间构建。

要在 Ubuntu 上构建 Ray，请运行以下命令

sudo apt-get update
sudo apt-get install -y build-essential curl clang-12 pkg-config psmisc unzip

# Install Bazelisk.
ci/env/install-bazel.sh

# Install node version manager and node 14
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 14
nvm use 14

注意

install-bazel.sh 脚本安装 bazelisk 用于构建 Ray。请注意，bazel 安装在 $HOME/bin/bazel；请确保它在可执行文件 PATH 中。如果您更喜欢使用 bazel，目前仅支持版本 6.5.0。

对于 RHELv8 (Redhat EL 8.0-64 Minimal)，运行以下命令

sudo yum groupinstall 'Development Tools'
sudo yum install psmisc

在 RedHat 中，请从此链接手动安装 Bazel：https://docs.bazel.build/versions/main/install-redhat.html

准备在 MacOS 上构建 Ray

提示

假设您已经在 Mac 上安装了 Brew 和 Bazel，并且也安装了 grpc 和 protobuf，请考虑使用命令 brew uninstall grpc, brew uninstall protobuf 删除这些（grpc 和 protobuf），以确保构建顺利进行。如果您之前构建过源代码，并且仍然因 No such file or directory: 等错误而失败，请尝试通过运行命令 brew uninstall binutils 和 bazel clean --expunge 清理主机上的先前构建。

要在 MacOS 上构建 Ray，首先安装这些依赖项

brew update
brew install wget

# Install Bazel.
ci/env/install-bazel.sh

在 Linux & MacOS 上构建 Ray（完整）

确保您已经按照上述说明在本地克隆了 Ray 的 git 仓库。您还需要安装 NodeJS 来构建仪表盘。

进入项目目录，例如

cd ray

现在您可以构建仪表盘。在您的本地 Ray 项目目录中，进入仪表盘客户端目录

cd python/ray/dashboard/client

然后您可以安装依赖并构建仪表盘

npm ci
npm run build

之后，您可以回到顶层 Ray 目录

cd -

现在让我们构建 Ray for Python。请确保您已按照上述说明激活了可能正在使用的任何 Python 虚拟 (或 conda) 环境。

进入 Ray 项目目录内的 python/ 目录，并使用 pip 安装项目

# Install Ray.
cd python/
# Install required dependencies.
pip install -r requirements.txt
# You may need to set the following two env vars if you have a macOS ARM64(M1) platform.
# See https://github.com/grpc/grpc/issues/25082 for more details.
# export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1
# export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1
pip install -e . --verbose  # Add --user if you see a permission denied error.

-e 表示“可编辑”（editable），因此您对 Ray 目录中文件所做的更改将生效，而无需重新安装软件包。

警告

如果您运行 python setup.py install，文件将从 Ray 目录复制到 Python 包目录 (/lib/python3.6/site-packages/ray)。这意味着您对 Ray 目录中的文件所做的更改将不会产生任何效果。

提示

如果在构建过程中机器内存不足或构建导致其他程序崩溃，请尝试将以下行添加到 ~/.bazelrc

build --local_ram_resources=HOST_RAM*.5 --local_cpu_resources=4

build --disk_cache=~/bazel-cache 选项对于加速重复构建也很有用。

注意

警告：如果您在构建 protobuf 时遇到错误，从 miniconda 切换到 anaconda 可能会有所帮助。

在 Windows 上构建 Ray（完整）

要求

以下链接在编写本节时是正确的。如果 URL 发生变化，请在组织网站上搜索。

• Bazel 6.5.0 (bazelbuild/bazel)

• Microsoft Visual Studio 2019 (或 Microsoft Build Tools 2019 - https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019)

• JDK 15 (https://www.oracle.com/java/technologies/javase-jdk15-downloads.html)

• Miniconda 3 (https://docs.conda.org.cn/en/latest/miniconda.html)

• git for Windows, 版本 2.31.1 或更高 (https://git-scm.cn/download/win)

您也可以使用包含的脚本安装 Bazel

# Install Bazel.
ray/ci/env/install-bazel.sh
# (Windows users: please manually place Bazel in your PATH, and point
# BAZEL_SH to MSYS2's Bash: ``set BAZEL_SH=C:\Program Files\Git\bin\bash.exe``)

步骤

1. 在 Windows 10 系统上启用开发者模式。这是 git 创建符号链接所必需的。

   1. 打开设置应用；

   2. 前往“更新和安全”；

   3. 前往左侧面板的“开发者选项”；

   4. 打开“开发者模式”。

2. 将以下 Miniconda 子目录添加到 PATH 中。如果 Miniconda 是为所有用户安装的，以下路径是正确的。如果 Miniconda 是为单个用户安装的，请相应调整路径。

   • C:\ProgramData\Miniconda3

   • C:\ProgramData\Miniconda3\Scripts

   • C:\ProgramData\Miniconda3\Library\bin

3. 定义环境变量 BAZEL_SH 指向 bash.exe。如果 git for Windows 是为所有用户安装的，bash 的路径应该是 C:\Program Files\Git\bin\bash.exe。如果 git 是为单个用户安装的，请相应调整路径。

4. Bazel 6.5.0 安装。前往 Bazel 6.5.0 发布网页并下载 bazel-4.2.1-windows-x86_64.exe。将 exe 复制到您选择的目录中。定义一个环境变量 BAZEL_PATH 指向完整的 exe 路径（示例：set BAZEL_PATH=C:\bazel\bazel.exe）。同时将 Bazel 目录添加到 PATH 中（示例：set PATH=%PATH%;C:\bazel）

5. 下载 ray 源代码并构建。

# cd to the directory under which the ray source tree will be downloaded.
git clone -c core.symlinks=true https://github.com/ray-project/ray.git
cd ray\python
pip install -e . --verbose

影响构建的环境变量

您可以使用以下环境变量调整构建过程（运行 pip install -e . 或 python setup.py install 时）

• RAY_INSTALL_JAVA：如果设置并等于 1，将执行额外的构建步骤来构建代码库的 java 部分

• RAY_INSTALL_CPP：如果设置并等于 1，将安装 ray-cpp

• RAY_DISABLE_EXTRA_CPP：如果设置并等于 1，常规（非 cpp）构建将不提供一些 cpp 接口

• SKIP_BAZEL_BUILD：如果设置并等于 1，将不执行任何 Bazel 构建步骤

• SKIP_THIRDPARTY_INSTALL_CONDA_FORGE：如果设置，安装程序将跳过安装构建所需的第三方软件包。这在不使用 pip 创建构建环境的 conda-forge 上处于活动状态。

• RAY_DEBUG_BUILD：可以设置为 debug、asan 或 tsan。任何其他值将被忽略

• BAZEL_ARGS：如果设置，将一组以空格分隔的参数传递给 Bazel。这对于在构建期间限制资源使用非常有用，例如。有关有效参数的更多信息，请参见https://bazel.build/docs/user-manual。

• IS_AUTOMATED_BUILD：在 conda-forge CI 中用于根据托管的 CI 机器调整构建

• SRC_DIR：可以设置为源代码检出根目录，默认为 None，即 cwd()

• BAZEL_SH：在 Windows 上用于查找 bash.exe，见下文

• BAZEL_PATH：在 Windows 上用于查找 bazel.exe，见下文

• MINGW_DIR：在 Windows 上用于在 BAZEL_PATH 中未找到时查找 bazel.exe

安装额外的开发依赖

Linter (scripts/format.sh) 的依赖项可以使用以下命令安装

pip install -c python/requirements_compiled.txt -r python/requirements/lint-requirements.txt

用于运行 python/ray/tests 下的 Ray 单元测试的依赖项可以使用以下命令安装

pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txt

用于运行 Ray Data / ML 库测试的需求文件位于 python/requirements/ 下。

Pre-commit Hooks

Ray 计划将来使用 pre-commit python package 替换从 scripts/format.sh 调用的 pre-push hooks。目前，我们已配置一个 .pre-commit-config.yaml，它运行与 scripts/format.sh 相同的所有检查，并附加一些额外的检查。目前这个开发者工具是可选的，由 scripts/format.sh 所做的任何格式化更改都应该被 pre-commit 捕获。要开始使用 pre-commit

pip install pre-commit
pre-commit install

这将把 pre-commit 安装到当前环境中，并在每次使用 git 提交新代码更改时启用 pre-commit 检查。要临时跳过 pre-commit 检查，可以在提交时使用 -n 或 --no-verify 标志

git commit -n

如果您发现 scripts/format.sh 所做的更改与 pre-commit 所做的不同，请在 Ray github 页面上报告问题。

快速、调试和优化构建

目前，Ray 是使用优化功能构建的，这可能需要很长时间并且会干扰调试。要执行快速、调试或优化构建，可以运行以下命令（分别通过 -c fastbuild/dbg/opt）

bazel build -c fastbuild //:ray_pkg

这将使用适当的选项重新构建 Ray（可能需要一段时间）。如果需要构建所有目标，可以使用 "//:all" 代替 //:ray_pkg。

要使此更改永久生效，可以将以下行添加到您的用户级别 ~/.bazelrc 文件中（不要与工作空间级别的 .bazelrc 文件混淆）

build --compilation_mode=fastbuild

如果这样做，请记住恢复此更改，除非您希望它影响未来的所有开发。

使用 dbg 而不是 fastbuild 会生成更多的调试信息，这使得使用 gdb 等调试器进行调试更容易。

构建文档

要了解如何构建文档，请参阅为 Ray 文档贡献。

使用本地仓库作为依赖

如果您想使用自定义依赖项（例如，使用不同版本的 Cython）构建 Ray，可以按照以下方式修改您的 .bzl 文件

http_archive(
  name = "cython",
  ...,
) if False else native.new_local_repository(
  name = "cython",
  build_file = "bazel/BUILD.cython",
  path = "../cython",
)

这将把现有的 http_archive 规则替换为一个引用 Ray 目录的同级目录（名为 cython），并使用 Ray 仓库中提供的构建文件 (bazel/BUILD.cython)。如果依赖项中已经包含 Bazel 构建文件，可以使用 native.local_repository 代替，并省略 build_file。

要测试切换回原始规则，将 False 更改为 True。

故障排除

如果在您的开发克隆中导入 Ray (python3 -c "import ray") 导致此错误

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File ".../ray/python/ray/__init__.py", line 63, in <module>
    import ray._raylet  # noqa: E402
  File "python/ray/_raylet.pyx", line 98, in init ray._raylet
    import ray.memory_monitor as memory_monitor
  File ".../ray/python/ray/memory_monitor.py", line 9, in <module>
    import psutil  # noqa E402
  File ".../ray/python/ray/thirdparty_files/psutil/__init__.py", line 159, in <module>
    from . import _psosx as _psplatform
  File ".../ray/python/ray/thirdparty_files/psutil/_psosx.py", line 15, in <module>
    from . import _psutil_osx as cext
ImportError: cannot import name '_psutil_osx' from partially initialized module 'psutil' (most likely due to a circular import) (.../ray/python/ray/thirdparty_files/psutil/__init__.py)

然后您应该运行以下命令

rm -rf python/ray/thirdparty_files/
python3 -m pip install setproctitle