Ray 从源码构建开发环境完全指南Python-only 快循环、C 全量构建与 manylinux Wheel【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/rayRay 是一个面向 AI 场景的分布式计算引擎由核心分布式运行时Core Distributed Runtime与一套加速 ML 工作负载的 AI 库RLlib、Tune、Data、Serve、Train 等组成。本指南以 doc/source/ray-contribute/development.md 为主体系统讲解如何在最新 master 分支上从源码搭建 Ray 开发环境从仅改 Python 文件的快循环开发到包含 C 的全量可编辑安装再到可分发的 manylinux Wheel 与 Ray Docker 镜像构建。读完本文你将能根据目标改 Python 逻辑、改 C 内核、打包分发、构建镜像选择正确的构建路径并掌握相关环境变量、Bazel 构建选项与常见故障排查方法。:local: :backnone: none按目标选择构建路径向 Ray 仓库贡献代码前先判断你的改动落在哪一层不同目标对应不同构建方式并非所有人都需要编译 C纯 Python 开发快循环不涉及 C只需编辑 Python 文件无需编译见 Python-only 快循环开发。需要 C 的构建按下述场景选择其一可分发的 manylinux Wheel在 manylinux 构建容器中产出.whl用于集群安装、本地验证打包产物或分发给他人见 构建可分发的 manylinux Wheel。Ray 镜像构建 nightly 风格的rayproject/ray或rayproject/ray-llm镜像见 构建 Ray 镜像。全量源码构建可编辑安装修改 C 代码或构建完整 Ray见 全量源码构建。环境准备Fork Ray 仓库向开源仓库贡献时Fork 是推荐做法你可以在不影响原项目的前提下自由修改与测试最后通过 Pull Request 向主仓库提交变更。具体步骤为进入 Ray 的官方 GitHub 仓库页面。按 GitHub 官方的 Fork 流程完成三步操作Fork 仓库到自己的账号Clone 到本地**连接上游upstream**主仓库以便后续同步最新变更。说明本仓库为只读镜像实际参与协作时请基于自己的 Fork 工作。本文只讲解查看、构建与配置方式。准备 Python 虚拟环境如果目标是构建可分发的 manylinux Wheel 或 Ray 镜像可以跳过本节否则建议先创建隔离的虚拟环境避免依赖版本冲突。::::{tab-set}:::{tab-item} conda创建名为myenv的 conda 环境conda create -c conda-forge python3.10 -n myenv激活环境每次新开 shell 或终端都需要执行conda activate myenv::::::{tab-item} venv用 Python 内置的venv模块在当前目录创建虚拟环境myenv只需执行一次python -m venv myenv激活环境每次新开 shell 或终端都需要执行source myenv/bin/activate新创建的虚拟环境可能自带较旧的pip与wheel建议先升级它们以避免后续安装问题python -m pip install --upgrade pip wheel:::::::Python-only 快循环开发RLlib、Tune、Autoscaler 以及绝大多数 Python 文件都不需要编译 C。若你只改 Python 代码按下面四步即可让本地 git 克隆中的改动直接生效克隆 Ray 仓库见上文 Fork 一节。激活 Python 虚拟环境见上文准备一节。pip 安装最新的 Ray wheel例如 Python 3.10pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp310-cp310-manylinux2014_x86_64.whl用本地可编辑副本替换已安装包中的 Python 文件运行仓库内的脚本python python/ray/setup-dev.py。该脚本会删除 pip 包自带的ray/tune、ray/rllib、ray/autoscaler等目录以及其他目录替换为指向你本地代码的符号链接。此后改动 git 克隆中的文件会直接改变已安装 Ray 的行为# 将 package path/site-packages/ray/package 替换为本地 ray/python/ray/package python python/ray/setup-dev.py也可以跳过特定目录的符号链接创建# 除 _private 和 dashboard 外全部建立链接且不询问确认 python python/ray/setup-dev.py -y --skip _private dashboardsetup-dev.py 的链接机制从 python/ray/setup-dev.py 的实现可以更精确地理解这个脚本的行为。它通过do_link()为packages_to_link字典中列出的每个包建立符号链接包括llm、serve/llm、data/llm.py、rllib其本地路径是仓库根的../../../rllib、air、tune、train、autoscaler、cloudpickle、data、scripts、internal、tests、experimental、util、workflow、serve、dag、widgets、cluster_utils.py、_private、_common、dashboard等。该脚本还支持两个互为排斥的参数--skip/-s跳过列表中文件夹的链接--allow/-a仅链接白名单内的文件夹两者同时使用会报错退出。在 POSIX 系统上使用ln -s创建软链接并自动检测目标目录写权限必要时通过sudo完成在 Windows 上则使用mklink /J目录联接或mklink /H硬链接。值得一提的实现细节是链接serve包时会先把已安装包中的serve/generated目录临时挪到/tmp/ray/_serve/建链后再移回本地目录以保留生成文件。卸载与升级注意事项:::warning 采用上述方式搭建环境后不要直接运行pip uninstall ray或pip install -U无论对 Ray 还是 Ray wheel。正确的卸载/升级顺序是先rm -rf删除 pip 安装目录通常是site-packages/ray再重新 pip 安装见上文命令最后再次运行setup-dev.py脚本。 :::# 卸载先删除符号链接。 rm -rf package path/site-packages/ray # 路径会在 setup-dev.py 的输出中给出 pip uninstall ray # 或 pip install -U wheel脚本末尾的提示也印证了这一点当 pip 安装新版本 Ray 时需先删除包符号链接防止 pip 覆盖 git 仓库中的文件见 python/ray/setup-dev.py。构建可分发的 manylinux Wheel:::dropdown Setup :open:开始前请确认已具备Ray 仓库的克隆见 Fork 一节已安装 uv已安装 Docker。 :::使用仓库根目录的build-wheel.sh脚本构建可分发的 manylinux.whl# 为主机构建 manylinux wheel ./build-wheel.sh 3.12 # 指定自定义输出目录 ./build-wheel.sh 3.12 ./dist不带参数运行./build-wheel.sh可查看支持的 Python 版本与全部选项。无论宿主系统是什么输出始终是 manylinux wheel与 CI 和 PyPI 使用的格式一致。支持的构建宿主包括 Linux x86_64、Linux aarch64 与 macOS ARM64。build-wheel.sh 背后的机制查看 build-wheel.sh 可以发现它本身是一个轻量包装脚本检测宿主平台Darwin-arm64 →macosx_12_0_arm64、Linux-x86_64 →manylinux2014_x86_64、Linux-aarch64 →manylinux2014_aarch64其余平台报错退出从.rayciversion读取 raymake 版本然后借助uv run --with拉取对应平台的raymakewheel 并转交 ci/build/build_wheel.py 执行。ci/build/build_wheel.py 中定义了构建的关键配置支持的 Python 版本为3.10、3.11、3.12、3.13、3.14wheel 构建依赖ci/docker/ray-wheel.wanda.yaml描述的 wanda 规格构建环境变量包含PYTHON_VERSION、MANYLINUX_VERSION从 rayci.env 中解析、BUILDKITE_COMMIT取自 git 当前提交、IS_LOCAL_BUILDtrue等。也就是说本地构建与 CI 走的是同一套 wanda 构建规格这也是本地产物与 CI/PyPI 产物同构的根源。直接用 Docker 构建 manylinux wheelpython/README-building-wheels.md给出了不依赖 build-wheel.sh、直接使用 manylinux 容器构建的方式。在仓库根目录执行docker run -ti --rm \ -e HOST_UID$(id -u) \ -e HOST_GID$(id -g) \ -e BUILDKITE_COMMIT$(git rev-parse HEAD) \ -e BUILD_ONE_PYTHON_ONLYpy39 \ -w /ray -v $(pwd):/ray \ -e HOME/tmp \ quay.io/pypa/manylinux2014_x86_64:2026.01.02-1 \ /ray/python/build-wheel-manylinux2014.shPython 3.9 的 wheel 会输出到.whl目录。可以通过修改BUILDKITE_COMMIT改变 wheel 内嵌的提交字符串不改动代码通过BUILD_ONE_PYTHON_ONLY选择不同的 Python 版本。aarch64 架构请改用quay.io/pypa/manylinux2014_aarch64镜像。macOS wheel 则运行./python/build-wheel-macos.sh脚本会多次使用sudo可能需要输入密码。注意该构建方式在容器内会对仓库做全量重建建议在干净的克隆上执行。构建 Ray 镜像:::dropdown Setup :open:开始前请确认已具备Ray 仓库的克隆见 Fork 一节已安装 uv已安装 Docker。 :::使用仓库根目录的build-image.sh脚本构建 Ray 镜像# 构建默认 Ray 镜像 ./build-image.sh ray # 指定 Python 版本 ./build-image.sh ray -p 3.12 # 构建 GPU 镜像 ./build-image.sh ray --platform cu12.8.1-cudnn运行./build-image.sh --help可查看支持的镜像类型、Python 版本与平台变体。镜像构建配置解析与 wheel 构建类似build-image.sh 也是薄包装它根据宿主平台选择 raymake wheel 后转交 ci/build/build_image.py。后者通过_BASE_TYPE_MAP将镜像类型映射到 wanda 配置键ray/ray-extra对应rayray-llm/ray-llm-extra对应ray-llm镜像的 Python 版本、平台cpu/cuda/tpu 等与架构信息统一从仓库根目录的 ray-images.json 加载并据此拼出形如ray-py3.12-cpu、ray-py3.12-cu12.8.1-cudnn的 wanda 输出镜像名。镜像构建的 Dockerfile 与 wanda 规格分别位于 docker/ 与 ci/docker/ 目录例如 docker/ray/Dockerfile 与 ci/docker/ray-image.Dockerfile。全量源码构建:::tip 如果你已经按 Python-only 方式搭建过环境、现在想切换到全量构建请先按上文卸载与升级注意事项卸载 Ray。 :::全量构建会编译 C 内核、Python 绑定与 Dashboard 前端耗时明显更长如果只改 Tune、RLlib 或 Autoscaler 文件优先走 Python-only 快循环路径。Linux 构建准备以 Ubuntu 为例sudo apt-get update sudo apt-get install -y build-essential curl clang-12 pkg-config psmisc unzip # 安装 Bazelisk。 ci/env/install-bazel.sh # 安装 node version manager 与 node 14 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 14 nvm use 14install-bazel.sh脚本安装的是bazeliskbazel会被放到$HOME/bin/bazel请确保它在PATH中。如果希望直接使用bazel仅支持 7.5.0 这一版本仓库根目录的 .bazelversion 内容即为7.5.0。从 ci/env/install-bazel.sh 源码可以看到脚本固定使用BAZELISK_VERSIONv1.16.0会按OSTYPE区分 msys/darwin/linux并在 Windows 上跳过安装提示手动放置 Bazel。macOS 构建准备如果安装了 grpc 或 protobuf建议先卸载以保证构建顺畅brew uninstall grpc、brew uninstall protobuf。若构建报No such file or directory错误可清理历史构建brew uninstall binutils与bazel clean --expunge。brew update brew install wget # 安装 Bazel。 ci/env/install-bazel.shLinux 与 macOS 全量构建步骤确认已有 Ray 仓库的本地克隆并安装 NodeJS 以构建 Dashboard。进入项目目录例如cd ray先构建 Dashboard 前端。进入 Dashboard 客户端目录cd python/ray/dashboard/client安装依赖并构建npm ci npm run build回到 Ray 顶层目录cd -接下来构建 Ray 的 Python 包。确保已激活 Python 虚拟或 conda环境进入python/目录后用 pip 安装# 安装 Ray。 cd python/ # 安装所需依赖。 pip install -r requirements.txt # 如果你使用 macOS ARM64(M1) 平台可能需要设置下面两个环境变量。 # 详见 https://github.com/grpc/grpc/issues/25082 # export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL1 # export GRPC_PYTHON_BUILD_SYSTEM_ZLIB1 pip install -e . --verbose # 遇到权限不足错误时加 --user-e表示可编辑editable此后对 Ray 目录内文件的修改无需重装即可生效。:::warning不要运行python setup.py install。该命令会把文件从 Ray 目录复制到包目录如/lib/python3.6/site-packages/ray导致后续对 Ray 目录的修改不生效。 :::构建期间如果内存不足可在~/.bazelrc中加入build --local_resourcesmemoryHOST_RAM*.5 --local_resourcescpu4build --disk_cache~/bazel-cache还能显著加速重复构建。另外如果构建 protobuf 报错从 miniforge 切换到 anaconda 环境可能有帮助。Windows 全量构建环境要求以下链接在文档编写时有效如 URL 变更请自行检索Bazel 7.5.0Microsoft Visual Studio 2019或 Microsoft Build Tools 2019JDK 15Miniforge 3git for Windows 2.31.1 或更高版本也可以使用仓库自带脚本安装 Bazel# 安装 Bazel。 ray/ci/env/install-bazel.sh # Windows 用户请手动将 Bazel 放入 PATH并把 BAZEL_SH 指向 MSYS2 的 Bash # set BAZEL_SHC:\Program Files\Git\bin\bash.exe步骤在 Windows 10 上开启开发者模式使 git 能创建符号链接。路径为设置 → 更新和安全 → 左侧开发者选项 → 打开开发人员模式。将 Miniforge 的以下子目录加入 PATH如果 Miniforge 为所有用户安装路径如下单用户安装请相应调整C:\ProgramData\miniforge3C:\ProgramData\miniforge3\ScriptsC:\ProgramData\miniforge3\Library\bin定义环境变量BAZEL_SH指向bash.exe。git for Windows 为所有用户安装时路径为C:\Program Files\Git\bin\bash.exe单用户安装请相应调整。安装 Bazel 7.5.0下载bazel-7.5.0-windows-x86_64.exe复制到任意目录定义环境变量BAZEL_PATH指向完整 exe 路径如set BAZEL_PATHC:\bazel\bazel.exe并把 Bazel 目录加入PATH如set PATH%PATH%;C:\bazel。下载 Ray 源码并构建# cd 到 ray 源码树将要下载到的目录。 git clone -c core.symlinkstrue 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 传递一组空格分隔的参数可用于限制构建资源占用等具体参数参见 Bazel 用户手册。IS_AUTOMATED_BUILDconda-forge CI 使用用于在托管 CI 机器上微调构建。SRC_DIR可设为源码检出根目录默认None即cwd()。BAZEL_SHWindows 上用于定位bash.exe。BAZEL_PATHWindows 上用于定位bazel.exe。MINGW_DIRWindows 上在BAZEL_PATH找不到bazel.exe时用于定位它。快速、调试与优化构建默认情况下 Ray 以优化模式构建耗时长且不利于调试。可通过-c指定构建模式fastbuild、dbg或optbazel run -c fastbuild //:gen_ray_pkg这条命令会用相应选项重建 Ray可能耗时较长。如需构建所有目标用bazel build //:all代替bazel run //:gen_ray_pkg。若要永久生效可在用户级~/.bazelrc中加入注意与工作区级.bazelrc区分build --compilation_modefastbuild记得在不需要时还原该配置。将fastbuild换成dbg会生成更多调试信息便于使用gdb等调试器。使用本地仓库替换依赖如果想用自定义依赖构建 Ray例如换一个 Cython 版本可以按下述方式修改.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目录的本地仓库规则并使用仓库自带的 bazel/cython.BUILD 作为构建文件。如果该依赖自身已带 Bazel 构建文件可用native.local_repository并省略build_file。把False改回True即可切回原规则。开发工具链安装开发所需额外依赖安装 linterpre-commit相关依赖pip install -c python/requirements_compiled.txt pre-commit pre-commit install安装运行python/ray/tests下单元测试所需的依赖pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txtRay Data 与 ML 库测试所需的依赖文件位于 python/requirements/ 下包含data/、ml/、serve/、llm/、doc/、docker/等子目录例如 python/requirements/test-requirements.txt、python/requirements/data/pyarrow-nightly.txt 等。Pre-commit 钩子Ray 使用 pre-commit 中。启用方式pip install pre-commit pre-commit install安装后每次git commit都会自动执行这些检查。如需临时跳过可用-n/--no-verify参数git commit -n如果遇到 pre-commit 相关问题可按项目惯例到仓库的 issue 页面报告。仓库还提供了 setup_hooks.sh它会把 ci/lint/pre-push 与 ci/lint/prepare-commit-msg 链接为 git hooks便于提交前自动执行 lint 检查。构建文档关于构建 Ray 文档的详细说明参见 Contributing to the Ray documentation。常见问题排查如果从开发克隆中导入 Raypython3 -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该问题通常发生在混合使用预编译 wheel 与本地产物时wheel 内捆绑的thirdparty_files中的 psutil 与当前平台的编译产物不匹配删除后改用 pip 安装系统级 psutil 即可。小结围绕 Ray 的开发工作选择正确的构建路径能大幅节省时间目标推荐路径关键入口仅修改 PythonTune/RLlib/Autoscaler 等Python-only 快循环python/ray/setup-dev.py产出可分发的 wheelmanylinux Wheel 构建build-wheel.sh、ci/build/build_wheel.py产出 nightly 风格镜像Ray 镜像构建build-image.sh、ci/build/build_image.py修改 C / 全量构建可编辑全量构建pip install -e . ci/env/install-bazel.sh从 development.md 的流程到 ci/build/ 与 python/ray/setup-dev.py 的实现可以看出Ray 的本地开发链路与 CI 高度一致wheel 与镜像构建都复用同一套 wanda 规格Python 快循环则通过符号链接把已安装包与 git 工作区绑定。掌握这些入口后无论是提交 C 补丁还是调试 Python 逻辑都能以最小的编译代价完成验证。【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考