课程导读

这套教程假设你熟悉 Python，了解进程和线程的基本概念，知道什么是网络服务和操作系统资源；不要求你用过 Ray，也不要求你读过分布式系统论文。

学完这套教程，你应该能做到：

用 Ray 把一个串行 Python 程序改造成可并行执行的任务图。
解释 ray.remote、ObjectRef、Actor、对象存储和调度器之间是怎么配合的。
看懂 Ray Core 的主要源码目录，理解一次任务提交经过了哪些组件。
通过 Mini Ray 预览版，亲手跑通 Task、ObjectRef 和 Actor 的执行流程。

阶段	你会学到什么	对应章节
第 1 阶段	Ray 解决的问题、抽象模型和基本 API	起步
第 2 阶段	Task、ObjectRef、Actor、调度、对象存储	Ray Core 原理
第 3 阶段	可运行 Demo、常见错误、性能直觉	渐进式 Demo
第 4 阶段	用 Mini Ray 预览版观察运行时机制	Mini Ray 机制预览

项目目录

text

.
├── docs/
│   ├── guide/                 # Ray 原理讲解
│   ├── labs/                  # 真实 Ray Demo 教程
│   ├── mini-ray/              # Mini Ray 机制预览
│   └── references/            # 资料、术语和 FAQ
├── examples/
│   ├── ray_demos/             # 需要安装 ray 的官方 API 示例
│   └── mini_ray_runtime/      # 教学版 Mini Ray 运行时
├── package.json
└── README.md

本教程的写法

Ray 官方文档适合作为 API 手册查阅，但从零学习时有几个问题：

API 调用看起来简单，但背后运行时做了很多事，文档不会展开讲。
Task、ObjectRef、Actor、调度、容错这些概念同时出现，新手很难分清谁在解决什么问题。
Ray 源码目录跨度大，直接读容易迷路。

所以这里采用“问题驱动”的顺序：每章先讲一个具体的编程问题，比如“为什么我的循环跑不快”，再引入 Ray 的对应设计，然后通过 Demo 验证，最后简单指向源码位置。

学习建议

每章至少运行一次对应 Demo。Ray 的很多概念只有在你看到 ObjectRef 先返回、ray.get 后阻塞、Actor 方法串行更新状态之后，才会真正变清楚。

环境准备

本仓库有两套工具链，先分清它们的职责：

npm 只负责 VitePress 教程站点。它和 Ray 的运行时没有关系，只是用来把 wiki 在本地跑起来。
uv 负责 Python 环境。真实 Ray Demo、Mini Ray Demo 和 Mini Ray 测试都走 uv。

如果你只是想本地预览教程站点：

bash

npm install
npm run docs:dev

如果你要运行真实 Ray Demo，先用 uv 建虚拟环境并安装依赖：

bash

uv venv
uv pip install -r examples/ray_demos/requirements.txt
uv run python examples/ray_demos/01_tasks.py

教学版 Mini Ray 只依赖 Python 标准库，不需要安装 Ray：

bash

uv run python -m unittest discover -s examples/mini_ray_runtime/tests
uv run python examples/mini_ray_runtime/demos/01_tasks.py

Mini Ray 在这里承担什么角色

本教程里的 Mini Ray 是一个机制预览版。它不是 Ray 的替代品，也不是完整的实现课。它的作用是让你看到 ObjectRef、任务提交、对象存储、资源调度和 Actor 队列是如何连在一起的。

API 长这样：

python

import mini_ray as ray

ray.init(num_workers=4)

@ray.remote
def square(x):
    return x * x

refs = [square.remote(i) for i in range(8)]
print(ray.get(refs))

它不做多机通信，不实现共享内存，只保留几条核心运行时路径：

函数调用变成远程任务，立即返回 ObjectRef。
运行时维护对象状态和任务结果。
Worker Pool 异步执行任务，Scheduler 用逻辑资源控制并发。
Actor 用消息队列保存状态，串行执行方法。

完整的 Mini Ray 实现系列会放到独立站点 mini-ray.llm101.moe。当前站点先帮你把 Ray Core 的概念和使用方式理顺。

课程导读 ​

推荐路线 ​

项目目录 ​

本教程的写法 ​

环境准备 ​

Mini Ray 在这里承担什么角色 ​

课程导读

推荐路线

项目目录

本教程的写法

环境准备

Mini Ray 在这里承担什么角色