源码地图

Ray 源码很大，直接从仓库根目录开始读容易迷路。更好的方式是围绕一个问题读：一次 f.remote() 到底经过哪些模块？

先看哪些目录

路径	你应该关注什么
python/ray/remote_function.py	@ray.remote 包装函数后的 Python 侧入口
python/ray/actor.py	Actor 类包装、ActorHandle 和方法提交
python/ray/_private/worker.py	Python Worker、Driver 初始化和 Core Worker 交互
src/ray/core_worker/	Core Worker，任务提交、对象引用、依赖管理
src/ray/raylet/	Raylet、调度、Worker 管理、对象管理
src/ray/gcs/	GCS 服务与集群元数据
src/ray/object_manager/	对象传输、pull/push、位置管理
dashboard/	Dashboard、State API 相关实现

具体文件名会随着版本变化，但这些模块边界长期稳定。

按调用链阅读

阅读时不要先纠结 C++ 的每个细节。先建立边界：

• Python 层负责把用户 API 变成运行时调用。
• Core Worker 负责进程内运行时状态和任务提交。
• Raylet 负责节点级调度和 Worker 管理。
• Object Manager / Store 负责对象数据。
• GCS 负责集群元数据。

对照 Mini Ray

Ray 源码模块	Mini Ray 文件	学习重点
remote_function.py	RemoteFunction	.remote() 为什么返回引用
actor.py	RemoteActorClass、ActorHandle	Actor 方法如何变成消息
Core Worker	Runtime	任务提交和对象引用如何串起来
Raylet Scheduler	ResourceScheduler	资源声明如何限制执行
Object Store	ObjectStore	未完成对象、ready 事件、异常传播
Actor Worker	actor_loop	Actor 状态和串行队列

这个对照表是本教程的核心。你先读 Mini Ray，再看 Ray 源码，会更容易理解真实实现为什么复杂。

推荐源码阅读顺序

1. 从 python/ray/remote_function.py 找到远程函数包装逻辑。
2. 找 .remote() 如何进入任务提交路径。
3. 看 Python Worker 如何持有 Core Worker 句柄。
4. 跟到 Core Worker 的 submit task 接口。
5. 看任务参数和返回对象如何用 ObjectRef 表示。
6. 再看 Raylet 如何选择 Worker。
7. 最后补 GCS、Object Manager 和故障恢复。

不建议一开始读什么

不要一开始就读：

• 全部 protobuf 定义。
• 所有调度策略细节。
• Dashboard 前后端。
• KubeRay Operator。
• Ray Data / Train / Serve 上层库。

这些都重要，但它们不是理解 Ray Core 的第一步。

源码阅读时问自己什么

每读一个函数，问四个问题：

1. 它运行在哪个进程里？Driver、Worker、Raylet 还是 GCS？
2. 它处理的是控制信息还是对象数据？
3. 它同步返回，还是创建了未来某个结果？
4. 失败时异常在哪里记录，谁会看到？

这四个问题能帮你避免把所有组件混成一团。

小练习

打开 Ray 仓库，找出函数远程调用和 Actor 远程调用在 Python 层的入口。然后对照 Mini Ray：

• RemoteFunction.remote()
• RemoteActorClass.remote()
• ActorMethod.remote()

写一张表说明它们分别创建了什么运行时对象、返回了什么引用或句柄。