Ray 开发者指南全景API 稳定性契约、贡献流程与集群配置实战【免费下载链接】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本文以 Ray 官方文档 Developer guides 章节doc/source/ray-contribute/index.md为主线系统梳理面向 Ray 二次开发者的五大主题API 稳定性分级与注解、API 文档与生命周期政策、完整贡献流程含 AI 辅助贡献规范、ray.init/ray start集群配置以及架构白皮书索引。读完本文你将掌握如何为 Ray 新增/标注一个公共 API、如何把一次代码贡献从分支提交到合并落地以及如何在单机与多机场景下精确配置 Ray 集群资源、端口、TLS 与 Java 驱动。Developer guides开发者文档的入口与组织doc/source/ray-contribute/index.md是整个 Ray 开发者/贡献者文档的入口页通过 Sphinxtoctree将五个主题组织在一起stability.md定义 Ray 的 API 稳定性保证以及标注公共接口的PublicAPI、DeveloperAPI、Deprecated注解api-policy.md规定 API 的文档义务、升降级与废弃deprecation时间线getting-involved.md贡献工作流、代码风格、测试、CI 与代码审查流程configure.rst从 Python API 与命令行两个维度讲解 Ray 的配置方式whitepaper.mdRay 内核架构白皮书入口。入口页的元描述明确了其定位Start here to navigate the documentation for developing and contributing to Ray itself。下面依次深入每个主题并结合仓库源码给出底层实现证据。API 稳定性契约三档标签与三级稳定度Ray 为 Ray core 及各 AI 库data、train、tune、serve、rllib 等的公共 API 提供稳定性保证其保证通过装饰器/标注来声明。一个 API 可以被标注为以下三类之一PublicAPI暴露给终端用户使用的 API其下细分为 alpha、beta、stable 三个子级别DeveloperAPI显式暴露给高级Ray 用户与库开发者的 API接口可能在小版本之间变化Deprecated已废弃可能在未来的 Ray 版本中被移除。Ray 的稳定性定义参考了 Google stability level guidelines并在细节上做了适配。三个子级别的定义如下Alpha处于快速迭代期的组件面向一小批必须容忍变更的已知用户。用户数量应当是经过筛选、可控的集合使得逐个沟通成为可能。alpha 组件中必须允许并预期破坏性变更用户不得对稳定性有任何期待。Beta必须被视为已可宣告稳定但还需经过公开测试。beta 用户对变更的容忍度较低因此 beta 组件应当尽可能稳定但允许随时间发生最小化的、可能向后不兼容的变更。任何向后不兼容的变更必须在经过合理的废弃期后才可实施给用户留出迁移时间。Stable在主要 API 版本的生命周期内必须得到完整支持。除极端情况外同一 major 版本内不得对 stable 组件做破坏性变更。稳定性文档还通过autofunction直接引用 python/ray/util/annotations.py 中的三个注解定义并将未标注的函数一般可视为不属于 Ray 公共 API作为默认规则——这意味着不写注解即默认降级为 Developer API。注解的源码级实现从 python/ray/util/annotations.py 的源码可以看到三个装饰器的完整实现与行为差异PublicAPI支持两种用法裸装饰PublicAPI等价于stabilitystable, api_groupOthers和带参装饰PublicAPI(stabilitybeta, api_group...)。stability仅接受stable、beta、alpha三个取值源码中有assert stability in [stable, beta, alpha]。当stability为 alpha/beta 时装饰器会自动向对象 docstring 追加一句 PublicAPI (xxx):This API is in xxx and may change before becoming stable.从而让 API 文档直接呈现稳定性状态。DeveloperAPI只接受裸装饰用法保留**kwargs供未来扩展并会向 docstring 追加 DeveloperAPI:This API may change across minor Ray releases.。Deprecated支持message与warning两个关键字参数message同时追加到 docstring以.. warning::指令渲染和运行时警告文本warningTrue时装饰器会包装类的__init__或函数/方法在调用时发出RayDeprecationWarning该警告默认按模块过滤、只打印首次出现。_mark_annotated会给对象打上_annotated、_annotated_type、_annotated_api_group三个 magic token供ci/lint/check_api_annotations.py等静态检查脚本识别标注状态。API 政策文档义务与生命周期管理api-policy.md的核心是两张策略表声明 API 时承诺不同 Ray 版本间接口不随意变化因此对社区影响重大需要明确政策来约束贡献者并管理用户预期。API 文档政策政策 / 曝光级别Stable Public APIBeta Public APIAlpha Public APIDeprecatedDeveloper API该 API 必须写文档吗是是是是由开发者自行决定必须用 API 注解PublicAPI / DeveloperAPI / Deprecated标注吗是是是是否缺省即视为 Developer API可以是私有 API位于_internal模块或带下划线前缀吗否否否否否文档是 Ray 向用户暴露 API 的主要渠道之一错误信息会直接影响用户应用的可靠性与可维护性。API reference 直接从源码生成因此公共 API 的写法会直接影响文档构建行为——在新增或修改公共 API 前应了解文档构建对依赖 mock 与交叉链接的处理方式。API 生命周期政策政策 / 曝光级别Stable Public APIBeta Public APIAlpha Public APIDeprecated APIDeveloper API可以无任何告警直接升级到更高级别吗是是是否是可以降级吗怎么降仅可降为 Deprecated须发出警告并设定废弃截止时间六个月或 25 个 Ray 小版本取先到者仅可降为 Deprecated须发出警告并设定截止时间三个月或 12 个 Ray 小版本取先到者用户必须容忍并预期破坏性变更是无注解即默认为 Developer API可以移除或修改该 API 的参数吗可以。须发出警告并为原版本的消亡设定截止时间六个月或 25 个小版本先到者过渡期内新旧参数必须同时支持可以。须发出警告并设定截止时间三个月或 12 个小版本先到者过渡期内新旧参数必须同时支持用户必须容忍并预期破坏性变更否可以这两张表共同构成了 Ray 的 API 治理框架稳定级别越高变更成本越高所有降级与参数变更都必须经过警告 双参数并存过渡期的缓冲避免用户应用被突然破坏。贡献与参与从 issue 到合并的完整工作流getting-involved.md是 Ray 贡献者的主指南。Ray 不仅是分布式应用框架也是一个活跃的开源社区欢迎各种形式的贡献补丁与 PR 的代码审查、提交补丁、文档与示例、论坛与 issue 的社区参与、代码可读性改进、让代码库更健壮的测试用例、教程与博客等推广材料以及通过 Ray Enhancement Proposals (REP) 机制提出的重大特性变更。用标签导航 issue找到适合自己的任务Ray 用 GitHub 标签给 issue 分类帮助贡献者按兴趣与技能水平定位任务新手起步good-first-issue适合新贡献者上手的小问题、contribution-welcome适合社区贡献的、会被优先审查的问题按组件coreRay Coretasks、actors、objects、scheduling、data分布式数据处理、train分布式训练、tune超参调优、serve模型服务、rllib强化学习按类型bug缺陷修复、enhancement新特性或改进、docs文档改进。这些标签可在 GitHub 搜索中组合使用例如同时匹配组件与类型。搭建开发环境修改 Ray 源码的标准路径是fork 仓库 → clone → 从源码构建本地副本详见 doc/source/ray-contribute/development.md 的构建指引。仓库顶层目录布局见仓库根目录 AGENTS.md为src/ray/C 核心运行时、python/ray/Python API 与 data/serve/train/tune 等库、rllib/从python/ray/rllib符号链接、doc/source/Sphinx 文档。AI 辅助贡献政策Ray 在仓库根目录提供了 AGENTS.md供支持该约定的 AI 编码 Agent 自动加载。它定义了 AI 辅助 PR 必须遵守的贡献政策重复工作检查提交 PR 前用gh issue view/gh pr list确认该改动没有已在进行中的 issue 或 PR若已有 PR 覆盖同样改动应在其上评论而非另开 PR禁止低价值琐碎 PR不接受单个错别字、孤立样式调整、单个可变默认值、孤立类型注解等一次性琐碎修改机械性清理只有在与实质性工作捆绑、或事先与维护者协调时才可接受人类问责制不允许纯代码 Agent PR提交者必须端到端理解并捍卫改动逐一审查每个改动行并在本地运行相关测试PR 描述必须说明为何不重复已有工作、运行过的测试命令与结果、以及是否使用了 AI 辅助Fail-closed 行为若请求的工作是重复、琐碎或无法被人类测试和捍卫的不得开 PR而应返回简要说明。getting-involved.md将该文件全文 literalinclude 在文档中作为 AI 辅助贡献的权威参考。提交与合并的六个步骤同步最新 master先把最新 master 合并进开发分支git remote add upstream ray 的 upstream 地址 git pull . upstream/master保证测试与 lint 通过运行setup_hooks.sh仓库根目录安装 git hooks——推送前自动运行 linter并为每个 commit 添加Signed-off-by尾注。每个 commit 都需要该尾注才能通过 Developer Certificate of Origin (DCO) 检查若跳过了 hook用git commit -s手动签名。为新功能/缺陷修复补测试在python/ray/tests/对应文件中新增测试用例。写文档公共函数必须写文档并尽量给出使用示例详见doc/README.md的编辑与构建说明。处理评审意见评审期间若出现合并冲突运行git pull . upstream/master解决不要用 rebase对 GitHub 评审工具不友好合并时会 squash 所有 commit。评审通过并合并及时催促长时间无进展的 PR。PR 审查流程在ray-project组织内的贡献者创建 PR 后把审查人加到assignee审查人给出意见后添加author-action-required标签作者处理意见后移除该标签如此往复直到通过PR 通过后作者负责确保构建通过成功后打test-ok标签最终由 committer 合并。组织外贡献者PR 会被分配 assignee 主动跟进处理完意见后要主动催促 assignee。本地测试Python 与 C虽然 CI 会自动跑单测但官方建议先在本地跑相关测试以减轻审查负担。首次运行需安装测试依赖pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txtPython 测试整套测试规模太大建议只跑相关文件。例如python/ray/tests/test_basic.py中某个测试失败时# 直接调用 pytest -v ... 可能丢失导入路径 python -m pytest -v -s python/ray/tests/test_basic.py只跑单个测试python -m pytest -v -s test_file.py::name_of_the_testC 测试编译并运行全部 C 测试bazel test $(bazel query kind(cc_test, ...))运行单个测试并流式输出示例为ClientConnectionTestbazel test $(bazel query kind(cc_test, ...)) --test_filterClientConnectionTest --test_outputstreamed代码风格pydoc、格式化与 lint总体遵循 Google style guideC与 Black 风格PythonPython 导入遵循 PEP8。比严格遵循规范更重要的是与所在组件的局部风格保持一致。Python 文档采用 Google pydoc 格式的子集其规范要点来自getting-involved.md的 canonical 示例函数 docstring 第一句必须与引号同行且单行内结束不要引入多行首句用Examples:段落配合.. doctest::提供关键用例Args:中不要写类型类型只在签名中体现多行参数说明缩进四个空格Returns:不要写类型类 docstring 中在类级别记录__init__所有公共方法与属性都要有 docstringproperty在属性处记录。格式化与 lint 工具链pip install -c python/requirements_compiled.txt -r python/requirements/lint-requirements.txt # Python 格式化依赖 # C 需要 clang-format 12 pip install -U pre-commit3.5.0 pre-commit install # 提交前自动检查 pre-commit run ruff -a其他独立于 pre-commit 的检查器Python README 格式cd python python setup.py check --restructuredtext --strict --metadataBazel 格式bazel-format.shC 静态检查需 clang/clang-tidy 12check-git-clang-tidy-output.shpre-commit输出中的WARNING: clang-format is not installed!是无害提示真正的失败形如python/ray/util/sgd/tf/tf_runner.py:4:1: F401 numpy as np imported but unused。理解 CI 测试任务PR 打开后Ray 通过 Buildkite 自动运行 CIci/目录包含全部集成测试脚本通过pytest、bazel 测试或其他 bash 脚本调用。示例命令包括bazel test --build_tests_only //:all、pytest python/ray/serve/tests、python python/ray/serve/examples/echo_full.py。若 CI 失败看起来与自己的改动无关可先核对近期已知的 flaky 测试。API 兼容性风格指南单个注解难以完整表达 API 兼容语义例如公共 API 可能含实验性参数——此时应在 pydoc 中注明如random_shuffle选项是实验性的并尽量给实验性参数加下划线前缀如_owner。其他建议Python API 中尽量用*强制 kwargs 而非位置参数kwargs 更易保持向后兼容def foo_bar(file, *, opt1x, opt2y) pass回调类 API 预留**kwargs作为前向兼容占位符方便未来追加参数def tune_user_callback(model, score, **future_kwargs): pass社区示例与成为 committer贡献示例时把示例链接登记到对应库的examples.yml中- title: Serve a Java App skill_level: advanced link: tutorials/java contributor: community相对链接指向其他文档页http://直链也可contributor: community元数据让示例在示例库中被正确标注为社区示例。Committer 资格在项目活跃至少六个月、由至少一名 TSC 成员提名且展示了高质量代码贡献、深入代码审查、积极参与社区讨论、在项目一个或多个领域具备技术专长。Committer 的职责包括审查与合并 PR、保证代码质量与项目标准、维护项目健康方向、指导贡献者与审查人。配置 Rayray.init与ray start实战configure.rstdoc/source/ray-core/configure.rst系统讲解了从 Python API 与命令行配置 Ray 的完整方式。一个重要前提多节点场景必须先运行ray start启动集群服务再用 Python 中的ray.init连接单机场景直接ray.init()即可同时启动并连接集群服务。集群资源Ray 默认自动检测可用资源import ray # 单机下自动检测可用资源 ray.init()非集群模式下可通过ray.init覆盖资源声明# 未连接已有集群时可指定资源覆盖 ray.init(num_cpus8, num_gpus1) # 自定义资源 ray.init(num_gpus1, resources{Resource1: 4, Resource2: 16})命令行方式通过ray start传入# 启动 head 节点 $ ray start --head --num-cpusNUM_CPUS --num-gpusNUM_GPUS # 启动非 head 节点 $ ray start --addressaddress --num-cpusNUM_CPUS --num-gpusNUM_GPUS # 自定义资源 ray start [--head] --num-cpusNUM_CPUS --resources{Resource1: 4, Resource2: 16}命令行启动后Python 端连接已有集群注意连接已有集群时不要再指定资源ray.init(addressaddress)Worker gRPC 线程配置高 CPU 节点每个 Ray worker 进程都有自己的 gRPC runtime默认按整机 CPU 数配置内部线程数。worker 进程很多的节点上这会累积出很高的总线程数。可在启动 Ray 前设置RAY_worker_num_grpc_internal_threads为一个正整数来降低 worker 端 gRPC runtime 的 CPU 数提示且需要在每个想生效的节点上设置# head 节点 RAY_worker_num_grpc_internal_threads4 ray start --head # worker 节点 RAY_worker_num_grpc_internal_threads4 ray start --addressHEAD_ADDRESS最佳取值取决于工作负载建议在测量任务吞吐与 RPC 延迟的同时测试 1、2、4 等小值。日志与调试session 目录与临时目录每个 Ray session 有唯一名称默认格式为session_{timestamp}_{pid}timestamp格式为%Y-%m-%d_%H-%M-%S_%fpid属于启动进程。所有临时文件放在session 目录下它是root temporary path默认/tmp/ray的子目录因此默认 session 目录为/tmp/ray/{ray_session_name}可按名称排序找到最新 session。修改根临时目录命令行用ray start --temp-dir{你的临时路径}ray.init()目前没有稳定接口但可用_temp_dir参数指定。端口配置Ray 集群节点间需要双向通信每个节点开放特定端口接收请求。所有节点--node-manager-portnode manager 的 raylet 端口。默认随机值。--object-manager-portobject manager 的 raylet 端口。默认随机值。--runtime-env-agent-portruntime env agent 的 raylet 端口。默认随机值。--dashboard-agent-grpc-portdashboard agent 的 gRPC 监听端口。默认随机值。--dashboard-agent-listen-portdashboard agent 的 HTTP 监听端口。默认52365。--metrics-export-port暴露 Ray 指标用端口。默认随机值。--min-worker-portworker 绑定的最小端口号。默认10002。--max-worker-portworker 绑定的最大端口号。默认19999。端口号是 Ray 区分单节点上多个 worker 输入输出的依据每个 worker 占用一个端口因此默认每节点最多 10000 个 worker与 CPU 数无关。一般应给 Ray 提供较宽的 worker 端口范围以防与其他程序冲突调试时可显式指定短列表如--worker-port-list10000,10001,10002,10003,10004同样会限制 worker 数量。注意每个 raylet 随机分配 worker 端口不要依赖首个 worker 绑定--min-worker-port或列表首项同一宿主机跑多个 raylet 时最好给各自不重叠的端口段或传--min-worker-port0 --max-worker-port0让 worker 绑定端口 0 由操作系统分配空闲端口ray start默认 10002–19999不传选项不会启用该行为。Head 节点在上一节基础上额外开放--portRay GCS server 端口head 节点在该端口启动 GCS server。默认6379。--ray-client-server-portRay Client Server 监听端口。默认10001。--redis-shard-ports非主 Redis shard 的逗号分隔端口列表。默认随机值。--dashboard-grpc-port已废弃不再使用仅为向后兼容保留。--dashboard-port若--include-dashboard为 true默认head 节点必须开放。默认8265。若--include-dashboard为 true 但 dashboard 端口未开放会出现The agent on node ... failed的 gRPCUNAVAILABLE错误此时应用nmap/nc等工具确认8265端口可达。注意 dashboard 是独立子进程可能在后台静默崩溃因此刚才还通的端口现在不通是可能的不需要 dashboard 时设置--include-dashboardfalse。TLS 认证Ray 可在 gRPC 通道上启用 TLS使连接 head 需要凭据且 client/head/workers 之间传输的数据被加密。以自签名证书的静态 Kubernetes 集群为例的四步配置生成 CA 的私钥与自签名证书openssl req -x509 \ -sha256 -days 3650 \ -nodes \ -newkey rsa:2048 \ -subj /CN*.ray.io/CUS/LSan Francisco \ -keyout ca.key -out ca.crt用cat ca.key | base64编码后填入 secret.yaml或用kubectl create secret generic ca-tls --from-fileca.crt路径 --from-fileca.key路径直接创建 secret。为 Ray head 与 workers 分别生成私钥与自签名证书集群 YAML 的tlsConfigMap 内含gencert_head.sh与gencert_worker.sh两个脚本在 initContainer 中动态获取POD_IP写入[alt_names]依次生成 2048 位 RSA 私钥/etc/ray/tls/tls.key、CSR用tls.key与csr.conf以及用 CA 密钥对签发的自签名证书tls.crt。为 head 与 workers 设置环境变量启用 TLSRAY_USE_TLS1 或 0 决定是否启用 TLS启用时须设置下列变量。默认0。RAY_TLS_SERVER_CERTtls.crt证书文件位置Ray 用它向其他端点做双向认证。RAY_TLS_SERVER_KEYtls.key私钥文件位置用于证明你是某证书的授权持有者。RAY_TLS_CA_CERTca.crtCA 证书位置用于校验端点证书的签发机构。验证 TLS登录 worker Pod 后ray health-check --address service-ray-head.default.svc.cluster.local:6379FQDN 在证书 alt_names 中应连接成功而ray health-check --address service-ray-head:6379会因 Peer name service-ray-head is not in peer certificate 失败把DNS.3 service-ray-head加入 alt_names 并重新部署后即可工作。启用 TLS 会带来性能开销双向认证与加密小负载下开销占比明显大负载下相对变小具体取决于负载特征。Java 应用配置多节点集群中运行 Java 应用必须指定code search path告诉 Ray 启动 Java worker 时从哪里加载 jar$ java -classpath classpath \ -Dray.addressaddress \ -Dray.job.code-search-path/path/to/jars/ \ classname args/path/to/jars/指向包含 jar 的目录worker 会加载目录下所有 jar多个目录用:分隔。单机/本地模式无需配置。Ray 用 Typesafe Config 读取驱动选项可通过-Dkeyvalue系统属性或 classpath 根部的ray.confHOCON 格式可用系统属性ray.config-file自定义位置配置系统属性优先级高于配置文件。可用的驱动选项ray.addressString默认空连接已有集群的地址为空则新建集群。ray.job.code-search-pathString默认空Java worker 加载代码的目录列表:分隔也用于加载 Python 代码跨语言调用时必填。ray.job.namespaceString默认随机 UUIDjob 的命名空间用于 job 间隔离不同命名空间的 job 互不可见。架构白皮书索引whitepaper.md为想深入 Ray 内核的读者提供三份权威资料入口Ray 2.0 架构白皮书全面覆盖 Ray 内部机制、v1.0 版白皮书前一版本架构以及 Exoshuffle 论文深入讲解 Ray dataplane 的可扩展性与性能。这些资料与本文的 API 契约、贡献流程、配置实战互为补充前者讲Ray 内部如何工作本文则讲如何为 Ray 开发、贡献与部署配置。小结从入口页doc/source/ray-contribute/index.md展开的 Developer guides 覆盖了 Ray 二次开发的完整闭环API 稳定性契约alpha/beta/stable 三级与三类注解对应 python/ray/util/annotations.py 的实现规定了接口承诺的边界API 政策用两张表格约束了文档义务与降级/废弃时间线贡献指南打通了从标签找任务、AI 辅助贡献规范、本地测试到 PR 合并的全流程配置指南doc/source/ray-core/configure.rst给出资源、线程、日志、端口、TLS 与 Java 驱动的完整参数表白皮书则指向架构深潜的权威资料。无论你是想提交第一个补丁、为库新增公共 API还是部署一个多节点集群都可以在此章节中找到对应的规范与命令。【免费下载链接】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），仅供参考