# https://github.com/ray-project/ray 项目说明书
生成时间：2026-07-06 19:32:13 UTC
## 目录
- [Ray 概览与系统架构](#page-1)
- [Ray Core:任务、Actor 与对象](#page-2)
- [AI 库:Data、Train、Tune、RLlib、Serve、LLM](#page-3)
- [集群部署、Autoscaler 与可观测性](#page-4)
## Ray 概览与系统架构
### 相关页面
相关主题：[Ray Core:任务、Actor 与对象](#page-2), [AI 库:Data、Train、Tune、RLlib、Serve、LLM](#page-3), [集群部署、Autoscaler 与可观测性](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.rst](https://github.com/ray-project/ray/blob/master/README.rst)
- [python/ray/__init__.py](https://github.com/ray-project/ray/blob/master/python/ray/__init__.py)
- [doc/source/index.rst](https://github.com/ray-project/ray/blob/master/doc/source/index.rst)
- [doc/source/ray-overview/ray-libraries.rst](https://github.com/ray-project/ray/blob/master/doc/source/ray-overview/ray-libraries.rst)
- [doc/source/ray-overview/getting-started.rst](https://github.com/ray-project/ray/blob/master/doc/source/ray-overview/getting-started.rst)
- [doc/source/ray-overview/ray-architecture.rst](https://github.com/ray-project/ray/blob/master/doc/source/ray-overview/ray-architecture.rst)
- [python/ray/worker.py](https://github.com/ray-project/ray/blob/master/python/ray/worker.py)
- [src/ray/raylet/raylet.cc](https://github.com/ray-project/ray/blob/master/src/ray/raylet/raylet.cc)
- [src/ray/common/ray_config_def.h](https://github.com/ray-project/ray/blob/master/src/ray/common/ray_config_def.h)
- [python/ray/job_config.py](https://github.com/ray-project/ray/blob/master/python/ray/job_config.py)
# Ray 概览与系统架构
## 什么是 Ray
Ray 是一个用于扩展 AI 和 Python 应用的开源统一计算框架。它以"分布式即本地"为核心理念，通过简单的装饰器 (`@ray.remote`) 和函数调用，将单机 Python 代码平滑地扩展到集群环境。Ray 的设计目标是统一从数据预处理、分布式训练、模型服务、强化学习到 LLM 工作负载等场景的基础设施。
资料来源：[README.rst:1-40]()
按社区讨论（#58008），Ray 已正式加入 PyTorch 基金会，与 PyTorch、vLLM、DeepSpeed 等项目并列，进一步强化其作为 AI 基础设施核心组件的定位。
## 核心架构组件
Ray 的运行时由多个进程协同构成，可分为 **Head 节点** 与 **Worker 节点** 两类角色，每类节点上都运行若干专用进程：
| 组件 | 进程位置 | 主要职责 |
|------|---------|---------|
| GCS Server | 仅 Head | 全局元数据、调度视图、Actor 位置表 |
| Raylet (C++) | 所有节点 | 本地资源调度、Worker 管理、对象存储协调 |
| Object Store (Plasma) | 所有节点 | 分布式共享内存、零拷贝对象传输 |
| Dashboard Agent/Server | 所有/仅 Head | 观测面板、Prometheus 指标、作业状态 |
| Worker 进程 | 所有节点 | 执行用户 Task 与 Actor 方法 |
Raylet 是节点上的"本地调度器 + 资源代理"，由 C++ 实现，负责维护本地资源视图、调度 Task/Plasma 对象，以及与 GCS 通信同步全局视图。资料来源：[src/ray/raylet/raylet.cc:1-60]()
对象存储使用 Apache Arrow 兼容的列式格式，支持零拷贝共享同一节点上的大对象（如模型权重、DataFrame）。资料来源：[doc/source/ray-overview/ray-architecture.rst:1-80]()
### 数据流与请求路径
```mermaid
flowchart LR
A[Python Worker
@ray.remote] --> B[Raylet 本地调度]
B --> C{本地资源充足?}
C -- 是 --> D[本节点 Worker 执行]
C -- 否 --> E[GCS Server
全局调度]
E --> F[远端节点 Raylet]
F --> G[远端 Worker 执行]
D --> H[Object Store
结果写入]
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 的整体架构可概括为：**一个统一的内核（Ray Core）提供分布式原语，多套领域库在原语之上构建专用抽象，跨语言客户端（Python、Java、C++）通过 gRPC 与节点进程交互**。理解这一分层，有助于在实际使用中正确选择抽象层级：在性能敏感路径使用底层 Object/Task 原语，在业务编排层使用 Ray Data/Serve 等高级 API。
---
## Ray Core:任务、Actor 与对象
### 相关页面
相关主题：[Ray 概览与系统架构](#page-1), [AI 库:Data、Train、Tune、RLlib、Serve、LLM](#page-3), [集群部署、Autoscaler 与可观测性](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [python/ray/_private/worker.py](https://github.com/ray-project/ray/blob/main/python/ray/_private/worker.py)
- [python/ray/_raylet.pyx](https://github.com/ray-project/ray/blob/main/python/ray/_raylet.pyx)
- [python/ray/_private/runtime_env/runtime_env.py](https://github.com/ray-project/ray/blob/main/python/ray/_private/runtime_env/runtime_env.py)
- [python/ray/dag/compiled_dag_node.py](https://github.com/ray-project/ray/blob/main/python/ray/dag/compiled_dag_node.py)
- [python/ray/experimental/rdt/rdt_manager.py](https://github.com/ray-project/ray/blob/main/python/ray/experimental/rdt/rdt_manager.py)
- [cpp/src/ray/runtime/native_ray_runtime.cc](https://github.com/ray-project/ray/blob/main/cpp/src/ray/runtime/native_ray_runtime.cc)
# Ray Core:任务、Actor 与对象
Ray Core 是 Ray 分布式计算框架的基础层，提供三个核心抽象：**任务（Task）**、**Actor** 与 **对象（Object）**。它们共同构成了 Ray 的编程模型：任务表达无状态并行计算，Actor 表达有状态的分布式服务，对象则作为任务与 Actor 之间传递、共享的不可变值。三者通过 `ObjectRef`（对象引用）在 worker、raylet 与 GCS 之间流转，构成完整的分布式运行时。
## 任务（Task）
任务由 `@ray.remote` 装饰的 Python 函数定义，调用时通过 `.remote()` 异步提交，立即返回一个 `ObjectRef`，函数体随后在某个工作节点的 worker 进程内执行。任务是无状态的，每次调用相互独立。
```python
@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`。
```python
@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 进程。
```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 与对象的协同
下图展示了三大抽象在一次端到端调用中的数据流：
```mermaid
flowchart LR
A[用户代码 .remote()] --> B[worker.py
提交任务]
B --> C[CoreWorker
序列化参数]
C --> D[raylet
调度]
D --> E[远端 worker
执行]
E --> F[(对象存储)]
F --> G[ray.get 拉取]
G --> H[结果返回]
P[ray.put] --> F
AC[actor.remote] --> AS[Actor worker
常驻进程]
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 重启行为与对象存储生命周期上，是核心抽象持续演进的体现。
---
## AI 库:Data、Train、Tune、RLlib、Serve、LLM
### 相关页面
相关主题：[Ray 概览与系统架构](#page-1), [Ray Core:任务、Actor 与对象](#page-2), [集群部署、Autoscaler 与可观测性](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [python/ray/data/dataset.py](https://github.com/ray-project/ray/blob/main/python/ray/data/dataset.py)
- [python/ray/train/v2/_internal/execution/controller/controller.py](https://github.com/ray-project/ray/blob/main/python/ray/train/v2/_internal/execution/controller/controller.py)
- [python/ray/tune/tune.py](https://github.com/ray-project/ray/blob/main/python/ray/tune/tune.py)
- [python/ray/rllib](https://github.com/ray-project/ray/blob/main/python/ray/rllib)
- [python/ray/serve/api.py](https://github.com/ray-project/ray/blob/main/python/ray/serve/api.py)
- [python/ray/llm/_internal/serve/core/engine/protocol.py](https://github.com/ray-project/ray/blob/main/python/ray/llm/_internal/serve/core/engine/protocol.py)
# AI 库：Data、Train、Tune、RLlib、Serve、LLM
## 概述
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 解码、推测解码等大模型特有优化。
## 协同关系
| 库 | 主要职责 | 入口 | 通常与谁组合 |
| --- | --- | --- | --- |
| Data | 流式数据加载与转换 | `ray.data.from_*` | Train、LLM |
| Train | 分布式训练与检查点 | `Trainer(...).fit()` | Data、Serve |
| Tune | 超参搜索 | `tune.run` | Train、RLlib |
| RLlib | 强化学习 | `Algorithm(...).train()` | Tune、Serve |
| Serve | 在线模型服务 | `@serve.deployment` | Train、RLlib、LLM |
| LLM | 大模型推理 | `LLMEngine` | Serve |
## 总结
六个 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]。
---
## 集群部署、Autoscaler 与可观测性
### 相关页面
相关主题：[Ray 概览与系统架构](#page-1), [Ray Core:任务、Actor 与对象](#page-2), [AI 库:Data、Train、Tune、RLlib、Serve、LLM](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [python/ray/autoscaler/v2/autoscaler.py](https://github.com/ray-project/ray/blob/main/python/ray/autoscaler/v2/autoscaler.py)
- [python/ray/autoscaler/v2/instance_manager.py](https://github.com/ray-project/ray/blob/main/python/ray/autoscaler/v2/instance_manager.py)
- [python/ray/autoscaler/v2/prometheus_exporter.py](https://github.com/ray-project/ray/blob/main/python/ray/autoscaler/v2/prometheus_exporter.py)
- [python/ray/autoscaler/v2/sdk.py](https://github.com/ray-project/ray/blob/main/python/ray/autoscaler/v2/sdk.py)
- [python/ray/autoscaler/v2/tests/test_configs.py](https://github.com/ray-project/ray/blob/main/python/ray/autoscaler/v2/tests/test_configs.py)
- [python/ray/dashboard/dashboard.py](https://github.com/ray-project/ray/blob/main/python/ray/dashboard/dashboard.py)
- [python/ray/dashboard/modules/job/job_manager.py](https://github.com/ray-project/ray/blob/main/python/ray/dashboard/modules/job/job_manager.py)
- [python/ray/dashboard/modules/metrics/default_impl.py](https://github.com/ray-project/ray/blob/main/python/ray/dashboard/modules/metrics/default_impl.py)
- [python/ray/_private/authentication/authentication_token_setup.py](https://github.com/ray-project/ray/blob/main/python/ray/_private/authentication/authentication_token_setup.py)
- [doc/source/cluster/kubernetes/index.md](https://github.com/ray-project/ray/blob/main/doc/source/cluster/kubernetes/index.md)
# 集群部署、Autoscaler 与可观测性
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]()。
下面以一张表概括三类核心可观测信号：
| 信号类型 | 来源模块 | 端点示例 | 用途 |
| --- | --- | --- | --- |
| 集群指标 | `metrics/default_impl.py` | `GET /metrics` | 抓取 CPU/GPU/内存、Actor、Task 与 Autoscaler 指标 |
| Job 状态 | `job/job_manager.py` | `GET /api/jobs`、`/jobs/{id}/logs` | 跟踪 ray job 提交到 `SUCCEEDED`/`FAILED` 的全流程 |
| 节点伸缩 | `autoscaler/v2/prometheus_exporter.py` | 同 `/metrics` | 区分 PENDING、LAUNCHED、TERMINATED 节点数量 |
## 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 改进作为核心目标。读者在落地时，可结合本页引用的源码入口文件逐层下钻。
---
---
## Doramagic 踩坑日志
项目：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