从源代码构建 Ray

要为 Ray 存储库做贡献，请遵循以下说明从最新的 master 分支进行构建。

提示

如果您只编辑 Python 文件，请遵循 仅 Python 构建 Ray 的说明，以避免漫长的构建时间。

如果您已经按照 仅 Python 构建 Ray 中的说明进行操作，并且想切换到本节中的完整构建，您需要先卸载。

Fork Ray 存储库

Fork 一个开源存储库是贡献时的最佳实践，因为它允许您在不影响原始项目的情况下进行更改和测试，从而确保清晰有序的协作过程。您可以提交拉取请求到主项目的存储库来提出更改。

1. 导航到 Ray GitHub 存储库。

2. 遵循这些 GitHub 说明，并执行以下操作：

   1. Fork 存储库 使用您偏好的方法。

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

   3. 连接您的存储库 到上游 (主项目) Ray 存储库以同步更改。

准备 Python 虚拟环境

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

conda

设置一个名为 myenv 的 conda 环境

conda create -c conda-forge python=3.10 -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

仅 Python 构建 Ray

注意

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

RLlib、Tune、Autoscaler 和大多数 Python 文件不需要您构建和编译 Ray。请遵循这些说明，在本地开发 Ray 的 Python 文件而无需构建 Ray。

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

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

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

# For example, for Python 3.10:
pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp310-cp310-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 轮子)，如果以此方式设置环境。要卸载或升级，您必须先 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 文件，请遵循 仅 Python 构建 Ray 的说明，以避免漫长的构建时间。

要在 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://bazel.build/versions/6.5.0/install/redhat

准备在 MacOS 上构建 Ray

提示

假设您已经在 Mac 上安装了 Brew 和 Bazel，并且还在 Mac 上安装了 grpc 和 protobuf，请考虑删除它们 (grpc 和 protobuf) 以便通过以下命令顺利构建：brew uninstall grpc、brew uninstall 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 -

现在让我们为 Python 构建 Ray。确保按照上述说明激活您可能正在使用的任何 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 表示“可编辑”，因此您对 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 时遇到错误，切换到 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)

• Miniforge 3 (conda-forge/miniforge)

• 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. 将以下 Miniforge 子目录添加到 PATH。如果 Miniforge 是为所有用户安装的，则以下路径是正确的。如果 Miniforge 是为单个用户安装的，请相应地调整路径。

   • C:\ProgramData\miniforge3

   • C:\ProgramData\miniforge3\Scripts

   • C:\ProgramData\miniforge3\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_BUILD_CORE：如果设置并等于 1，则会构建核心部分。默认为 1。

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

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

• RAY_BUILD_REDIS：如果设置并等于 1，则会构建或获取 Redis 二进制文件。这些二进制文件仅用于测试。默认为 1。

• RAY_DISABLE_EXTRA_CPP：如果设置并等于 1，则常规 (非 cpp) 构建将不提供某些 cpp 接口。

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

• SKIP_THIRDPARTY_INSTALL_CONDA_FORGE：如果设置，安装将跳过构建所需的第三方包的安装。这在 conda-forge 上是活动的，其中 pip 不用于创建构建环境。

• 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.exe，如果未在 BAZEL_PATH 中找到。

为开发安装额外的依赖项

用于 linter (pre-commit) 的依赖项可以使用以下命令安装：

pip install -c python/requirements_compiled.txt pre-commit
pre-commit install

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

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

运行 Ray Data / ML 库测试的要求文件位于 python/requirements/ 目录下。

预提交钩子

Ray 使用 pre-commit python 包 的预提交钩子。 .pre-commit-config.yaml 文件配置了所有 linting 和格式化检查。要开始使用 pre-commit：

pip install pre-commit
pre-commit install

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

git commit -n

如果您在 pre-commit 方面遇到任何问题，请在此处报告问题。

快速、调试和优化构建

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

bazel run -c fastbuild //:gen_ray_pkg

这将使用相应的选项重新构建 Ray (这可能需要一些时间)。如果您需要构建所有目标，可以使用 bazel build //:all 而不是 bazel run //:gen_ray_pkg。

要使此更改永久生效，您可以将类似以下的行添加到您的用户级 ~/.bazelrc 文件中 (请勿与工作区级 .bazelrc 文件混淆)：

build --compilation_mode=fastbuild

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

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

构建文档

要了解有关构建文档的更多信息，请参阅 贡献 Ray 文档。

使用本地存储库作为依赖项

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

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

这将用一个引用您的 Ray 目录同级目录 (命名为 cython) 的 http_archive 规则替换现有的规则，该规则使用 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 psutil