什么是 Ray

Ray 是一个用于扩展 AI 和 Python 应用的开源统一计算框架。它以"分布式即本地"为核心理念，通过简单的装饰器 (@ray.remote) 和函数调用，将单机 Python 代码平滑地扩展到集群环境。Ray 的设计目标是统一从数据预处理、分布式训练、模型服务、强化学习到 LLM 工作负载等场景的基础设施。

资料来源：README.rst:1-40

按社区讨论（#58008），Ray 已正式加入 PyTorch 基金会，与 PyTorch、vLLM、DeepSpeed 等项目并列，进一步强化其作为 AI 基础设施核心组件的定位。

核心架构组件

Ray 的运行时由多个进程协同构成，可分为 Head 节点 与 Worker 节点 两类角色，每类节点上都运行若干专用进程：

Raylet 是节点上的"本地调度器 + 资源代理"，由 C++ 实现，负责维护本地资源视图、调度 Task/Plasma 对象，以及与 GCS 通信同步全局视图。资料来源：src/ray/raylet/raylet.cc:1-60

对象存储使用 Apache Arrow 兼容的列式格式，支持零拷贝共享同一节点上的大对象（如模型权重、DataFrame）。资料来源：doc/source/ray-overview/ray-architecture.rst:1-80

数据流与请求路径

flowchart LR
    A[Python Worker<br/>@ray.remote] --> B[Raylet 本地调度]
    B --> C{本地资源充足?}
    C -- 是 --> D[本节点 Worker 执行]
    C -- 否 --> E[GCS Server<br/>全局调度]
    E --> F[远端节点 Raylet]
    F --> G[远端 Worker 执行]
    D --> H[Object Store<br/>结果写入]
    G --> H
    H --> A

当用户提交一个 remote 函数调用时，Python 端的 worker.py 会对参数进行序列化与对象引用（ObjectRef）封装，再经由 gRPC 提交给本节点 Raylet；Raylet 根据资源与位置亲和性决定本地执行或转发至 GCS 进行全局调度。资料来源：python/ray/worker.py:1-100

Ray 库生态

Ray 在统一内核之上构建了多套面向领域的库，覆盖数据、训练、服务、强化学习与 LLM 全流程。官方文档中明确列出了以下套件：

• Ray Core：Task、Actor、Object 与 Placement Group 等底层原语。
• Ray Data：分布式数据预处理与 ETL，基于流式执行器。
• Ray Train：多节点/多 GPU 的训练编排。
• Ray Serve：在线模型服务与流量路由。
• Ray RLlib：强化学习算法库。
• Ray Tune：超参数搜索与实验调度。
• Ray LLM：面向 LLM 推理与微调的扩展。

资料来源：doc/source/ray-overview/ray-libraries.rst:1-80

这种"内核 + 库"分层是 Ray 2.0 RFC（#22833）的核心设计原则，避免在每个领域重复造调度与容错基础设施。

部署、作业与扩展面

Ray 支持单机（ray.init()）与集群两种部署模式。集群模式下，Ray Cluster Launcher（KubeRay、AWS、YARN 等适配器）负责拉起 Head 与 Worker 节点；作业生命周期由 JobConfig 与 GCS 中的 JobTable 管理。资料来源：python/ray/job_config.py:1-60

社区路线图（#54923）显示 Q3 2025 的重点仍落在 Ray Core/Data/Train/LLM/Serve/RL 的可靠性、性能与开发者体验改进上，包括 #2.56.0 中关于多数据集运行、iter_batches 稳定性提升等。社区同时长期关注 Rust API（#20609）的诉求，希望将 Actor/Task 模型暴露给非 Python 生态。

Ray Core 是 Ray 分布式计算框架的基础层，提供三个核心抽象：任务（Task）、Actor 与 对象（Object）。它们共同构成了 Ray 的编程模型：任务表达无状态并行计算，Actor 表达有状态的分布式服务，对象则作为任务与 Actor 之间传递、共享的不可变值。三者通过 ObjectRef（对象引用）在 worker、raylet 与 GCS 之间流转，构成完整的分布式运行时。

任务（Task）

任务由 @ray.remote 装饰的 Python 函数定义，调用时通过 .remote() 异步提交，立即返回一个 ObjectRef，函数体随后在某个工作节点的 worker 进程内执行。任务是无状态的，每次调用相互独立。

@ray.remote(num_cpus=1)
def add(x, y):
    return x + y

ref = add.remote(1, 2)
result = ray.get(ref)

提交的路径在 worker 中封装为对 raylet 的 gRPC 调用，并由本地 CoreWorker 调度到对应节点。worker.py 中 submit_task、_submit_task 等函数负责把函数句柄、参数与调度策略一起打包发送到 raylet；而 _raylet.pyx 中的 submit_task 则通过 Cython 桥接到底层 CoreWorker::SubmitTask，完成跨语言序列化与调度请求 资料来源：python/ray/_private/worker.py:1500-1620、资料来源：python/ray/_raylet.pyx:2400-2480。

任务调度依赖 scheduling_strategy（如 DEFAULT、SPREAD、PlacementGroupSchedulingStrategy）以及资源声明 num_cpus、num_gpus、resources，这些选项由 BaseFunctionOptions / TaskOptions 携带并下发到调度器 资料来源：python/ray/_private/worker.py:1450-1495。

Actor

Actor 是 Ray 中的有状态计算单元，使用 @ray.remote 装饰一个 Python 类，使其实例化与方法调用都在某个长期存在的 worker 进程内进行。Actor 持有跨调用持久的状态，可通过 __init__ 初始化，对外暴露的方法同样返回 ObjectRef。

@ray.remote(num_cpus=2)
class Counter:
    def __init__(self):
        self.value = 0
    def inc(self):
        self.value += 1
        return self.value

Actor 通过 actor_cls.remote(...) 创建，参数包括 name（全局命名，便于跨集群访问）、lifetime（DETACHED/NON_DETACHED）、max_restarts、max_task_retries 等。worker.py 中的 _make_actor 将类信息序列化后提交给 raylet，由 raylet 在选定节点拉起一个长期 worker 进程，并分配 ActorID 资料来源：python/ray/_private/worker.py:1700-1820。

方法调用最终通过 _invoke_actor_task 发送到该 Actor 专属的 CoreWorker；任务在 Actor 内部串行或并发执行（取决于 max_concurrency），并在失败时依据 max_restarts 进行恢复 资料来源：python/ray/_private/worker.py:1820-1900。

对象（Object）

对象是 Ray 分布式对象存储中的不可变值。ray.put(value) 将 Python 对象序列化后写入本地或远端 raylet 的 Plasma 存储，并返回一个 ObjectRef；ray.get(ref) 则会阻塞直到依赖的 ObjectRef 全部就绪，并把对象反序列化回 Python 进程。

data_ref = ray.put(np.arange(10))
total = sum.remote(data_ref)

对象的元数据存放在 GCS，数据本体存储在 raylet 的共享内存区域；当 ObjectRef 被跨任务传递时，下游任务的执行节点若未持有该对象，会触发 raylet 之间的对象传输。native_ray_runtime.cc 中的 Get、Put 等 C++ 接口与 _raylet.pyx 中的 Python 端桥接共同完成此流程 资料来源：cpp/src/ray/runtime/native_ray_runtime.cc:120-260、资料来源：python/ray/_raylet.pyx:2700-2780。

任务、Actor 与对象的协同

下图展示了三大抽象在一次端到端调用中的数据流：

flowchart LR
    A[用户代码 .remote()] --> B[worker.py<br/>提交任务]
    B --> C[CoreWorker<br/>序列化参数]
    C --> D[raylet<br/>调度]
    D --> E[远端 worker<br/>执行]
    E --> F[(对象存储)]
    F --> G[ray.get 拉取]
    G --> H[结果返回]
    P[ray.put] --> F
    AC[actor.remote] --> AS[Actor worker<br/>常驻进程]
    AS --> F

任务与 Actor 的方法调用都返回 ObjectRef，因此可以使用 ray.wait 协调依赖，并结合 DAG 进行组合。compiled_dag_node.py 提供了将多个 ObjectRef 组合成 DAG 的能力，在执行前由 ray.dag 进行编译与优化，以便在大规模流水线中复用对象与任务结构 资料来源：python/ray/dag/compiled_dag_node.py:1-120。

运行环境的差异（如 conda 依赖、working_dir、环境变量）由 RuntimeEnv 描述，并在任务或 Actor 调度时下发到目标节点；rdt_manager.py 提供了面向部署场景的 RDT（Ray Deployment Tooling）增强，用于细粒度地管理 runtime env 的安装与回收 资料来源：python/ray/_private/runtime_env/runtime_env.py:1-180、资料来源：python/ray/experimental/rdt/rdt_manager.py:1-90。

与社区关注点的关联

• 对比 Dask（issue #642）：Ray 与 Dask 在 Python 上的并行思路相似，但 Ray 把 Task/Actor/Object 抽象统一到同一个调度与对象存储层，而非分别针对图计算与任务图，这使 Ray 既能跑数据并行任务，也能承载有状态的服务。
• Rust API（issue #20609）：Rust API 的目标就是把上文 _raylet.pyx 与 native_ray_runtime.cc 中的 C++/Cython 能力以原生语言暴露，意味着任务、Actor 与对象这三大抽象会首先被 Rust 端落地。
• Ray 2.0 / 后续版本路线（issue #22833、#54923）：在 Ray 2.0 之后，可观测性、调度语义与稳定性改进直接体现在任务调度策略、Actor 重启行为与对象存储生命周期上，是核心抽象持续演进的体现。

概述

Ray 在分布式运行时 Ray Core 之上构建了一组面向 AI 工程化场景的高阶库，覆盖数据准备、分布式训练、超参搜索、强化学习、模型服务与 LLM 推理等领域。这一组库共享 Actor、Task、Placement Group、Object Store 等底层原语，但在 API 入口、依赖和发布节奏上相互独立，可单独安装或组合使用。Ray 在 2.0 路线图中明确把"更高的易用性与生态互操作"作为核心目标，正是这套库的协同体现 [社区上下文：#22833]。

Ray Data：流式分布式数据集

Dataset 是 Ray Data 的核心类，位于 python/ray/data/dataset.py，对外提供惰性求值的流水线抽象 资料来源：[python/ray/data/dataset.py:30-120]。通过 from_items、range_*、read_*、read_parquet 等接口构造后，开发者能够以 map、map_batches、filter、split、iter_batches 等算子对分片进行转换与消费；执行时调度由框架自动完成，支持节点间 shuffle 与 resource 感知 资料来源：[python/ray/data/dataset.py:120-260]。在 Ray 2.56 中，iter_batches 进一步减少内部缓冲并在结束时关闭执行器，以提升稳定性 [社区上下文：release notes]。

Ray Train v2：分布式训练控制器

Ray Train v2 重写了控制器模型，Controller 类位于 python/ray/train/v2/_internal/execution/controller/controller.py，负责协调 worker 子集、生命周期管理、检查点（checkpoint）持久化与故障恢复 资料来源：[python/ray/train/v2/_internal/execution/controller/controller.py:1-120]。与 v1 相比，v2 显式分离了调度策略、Placement Group 协商以及 Torch / JAX / XGBoost / Lightning 等多种 backend，并通过 Trainer 统一入口暴露 fit() 迭代式 API。Train 与 Data 通过 Dataset 流水线与 CheckpointStorage 接口天然衔接。

Ray Tune：超参搜索与实验编排

python/ray/tune/tune.py 提供 tune.run 作为主要入口，配合 tune.grid_search、tune.uniform、tune.choice 等搜索空间定义以及 SearchAlgorithm、TrialScheduler 组件执行随机搜索、贝叶斯、Hyperband、BOHB、ASHA 等策略 资料来源：[python/ray/tune/tune.py:1-200]。Tune 与 Train 深度集成，支持以 Trainable 接口运行端到端训练实验，并可复用 RLlib 的算法作为 Trainable。

RLlib：强化学习算法库

python/ray/rllib 是相对独立的子包，提供 PPO、SAC、DQN、IMPALA、APPO 等多种 algorithm 实现，核心抽象包括 Trainer、Algorithm、Policy、SampleBatch 与 Env 适配器。RLlib 既可单独 Algorithm().train() 调用，也可与 Tune 组合进行多 seed 扫描或 HPO 资料来源：[python/ray/rllib]。

Ray Serve：在线服务与流量路由

python/ray/serve/api.py 暴露了 Serve 的 Python 高级 API，@serve.deployment 是构建可弹性扩缩副本的核心装饰器，serve.run 负责将部署图下发到集群 Controller，ingress、HTTP/gRPC 路由、副本扩缩均由 Serve Runtime 管理 资料来源：[python/ray/serve/api.py:1-180]。Train 产出的 Checkpoint 可直接被 Serve 通过 Predictor.deployment() 加载到线上。

Ray LLM：LLM 推理引擎

python/ray/llm 是较新的子包，专注于 LLM 推理服务。其核心抽象 LLMEngine 在 python/ray/llm/_internal/serve/core/engine/protocol.py 中以协议类形式存在，定义 chat、generate、completion、estimate_num_iters 等调用语义，便于与 vLLM 等推理后端解耦 资料来源：[python/ray/llm/_internal/serve/core/engine/protocol.py:1-200]。上层构建在 Ray Serve 之上，提供 OpenAI 兼容端点、PD 解码、推测解码等大模型特有优化。

协同关系

总结

六个 AI 库沿"数据 → 训练 → 调参/RL → 服务/推理"的链路组织，共享 Ray Core 资源层同时保持独立发布。Ray 2.56 在 Data 稳定性、Train v2 控制器、LLM 引擎协议等方面持续演进，Q3 2025 roadmap 也把 Core、Data、Train、LLM、Serve、RL 的可靠性与 DX 列为优先方向 [社区上下文：#54923]。Ray 已加入 PyTorch Foundation，未来与 PyTorch、vLLM、DeepSpeed 等基础设施的协同将进一步加深 [社区上下文：#58008]。

Ray 的生产部署由三层相互协作的子系统组成：Kubernetes/本地集群的部署入口、Autoscaler v2 的弹性伸缩控制回路，以及 Dashboard 提供的指标与 Job 可观测性。本页基于 python/ray/autoscaler/v2/、python/ray/dashboard/、python/ray/_private/authentication/ 与 doc/source/cluster/kubernetes/ 等源码说明它们的设计与协作方式。

Autoscaler v2：基于 SDK 的弹性伸缩

Autoscaler v2 的入口是 RayAutoscaler 类，它通过 SDK 与 Ray 集群的 GCS 交互，而不是旧版依赖外部 ray autoscaler 进程拉起本地节点的方式。__init__ 方法会读取传入的资源视图、节点提供器与实例状态，并构造一个事件驱动的伸缩循环。资料来源：python/ray/autoscaler/v2/autoscaler.py:1-80。

伸缩主循环由 update 或 _poll 触发的周期性评估构成：它会调用 InstanceManager 的方法、对比目标与现状、并把增删节点的需求写入待处理队列。在新增节点分支中，InstanceManager.launch_new_node 会结合 node_type_config 选择机型并调用 node_provider，随后将状态推为 ALLOCATED；对于已经判定为失效的实例，terminate_nodes 会调用提供器回收并最终回到 DELETED。资料来源：python/ray/autoscaler/v2/instance_manager.py:1-120。

为方便外部消费，Autoscaler v2 把内部状态机暴露为 Prometheus 指标：prometheus_exporter.py 中定义了 AUTOSCALER_LAUNCHED_NODES、AUTOSCALER_PENDING_NODES、AUTOSCALER_TERMINATED_NODES 等计数器与 gauge，供 Grafana 等工具抓取。资料来源：python/ray/autoscaler/v2/prometheus_exporter.py:1-60。

Autoscaler v2 还提供高层 SDK python/ray/autoscaler/v2/sdk.py，让用户通过 request_resources、cancel_request 等方法以资源视角提交伸缩请求；而 tests/test_configs.py 则验证了节点类型配置在最小、最大、异步场景下的正确性。资料来源：python/ray/autoscaler/v2/sdk.py:1-40、python/ray/autoscaler/v2/tests/test_configs.py:1-40]()。

Dashboard 与可观测性

Dashboard 服务由 python/ray/dashboard/dashboard.py 启动，基于 aiohttp 暴露 HTTP 接口并注册若干子模块，其中与运维最相关的是 metrics 与 job。DashboardHead 在启动时构造指标注册中心并加载各模块的 routes。资料来源：python/ray/dashboard/dashboard.py:1-80。

modules/metrics/default_impl.py 实现了默认的指标采集与导出流程：它通过 PrometheusMetricSink 与 C/C++ 层的 MetricsAgent 进行 IPC，从 /metrics 端点输出 OpenTelemetry 兼容的文本格式。除了 Ray Core 自带的指标，这里还会自动注入 autoscaler_* 系列指标，形成横跨核心运行时与伸缩器的统一视图。资料来源：python/ray/dashboard/modules/metrics/default_impl.py:1-100。

modules/job/job_manager.py 提供 Job 提交、状态跟踪与日志拉取能力：JobManager.submit_job 会通过 RuntimeEnvAgent 下发 job；JobInfo 则持久化 YAML 配置、运行状态、开始/结束时间等字段；tail_logs 与 list_jobs 端点支撑 Dashboard 上面 Job 视图的实时刷新。资料来源：python/ray/dashboard/modules/job/job_manager.py:1-120。

下面以一张表概括三类核心可观测信号：

Kubernetes 部署与认证

生产路径推荐使用 KubeRay Operator：doc/source/cluster/kubernetes/index.md 给出了 RayCluster、RayJob 与 RayService 三种 CRD，以及 kuberay-apiserver、kuberay-operator 的部署步骤。Operator 通过 watch CR 状态、把 spec 中的节点数量下发给 autoscaler-sidecar，再由 RayAutoscaler 实际拉起 Pod，呼应上一节的伸缩回路。资料来源：doc/source/cluster/kubernetes/index.md:1-120。

集群安全方面，2.x 版本引入了基于 token 的认证。authentication_token_setup.py 在启动 head 节点时检测 RAY_AUTH_TOKEN 或本地 token 文件，缺省为本地生成一份 ~/.ray/auth_token；RayletClient、JobSubmissionClient 在请求头中携带该 token，未授权请求将被 GCS 拒绝。这套机制与 Dashboard/Job API 共用，使 KubeRay 集群具备一致的访问控制。资料来源：python/ray/_private/authentication/authentication_token_setup.py:1-80。

总结与社区关注点

整体来看，Ray 通过 Autoscaler v2 的事件循环、KubeRay 的声明式 CR 与 Dashboard 的 metrics/job 子模块，形成从「资源请求」到「可视化」的闭环。社区中长期关注的方向包括 Kubernetes 上更细粒度的弹性策略、Autoscaler 指标的更丰富可视化，以及与 PyTorch Foundation 内项目（例如 vLLM、DeepSpeed）的可观测性互通，例如 issue #54923 提出的 Ray Q3 2025 路线图就明确将可靠性与 DX 改进作为核心目标。读者在落地时，可结合本页引用的源码入口文件逐层下钻。

Pitfall Log / 踩坑日志

项目：ray-project/ray

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ray-project/ray | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ray-project/ray | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ray-project/ray | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ray-project/ray | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ray-project/ray | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ray-project/ray | release_recency=unknown