mini-ray

用一个单机运行时，看懂任务调度、共享内存与 Python/C++ 边界。

一个面向学习的 alpha 多进程运行时：从 Python 调用到 C++ 核心，再到本地进程间的数据流，都可以亲手跑一遍。

简体中文 · English

核心能力 · 快速开始 · 运行预览 · 工作原理 · 边界 · 文档

mini-ray 是一个用于拆解运行时概念的教学项目，不是 Ray 的替代品。它只在一台机器上启动多个本地 进程，并使用 POSIX 共享内存，让你观察任务提交、ObjectRef、调度和对象存储如何连起来。

_{从一个 Python 函数开始，沿着本地多进程执行链路拿回结果。}

核心能力

你能探索什么	mini-ray 中的对应入口
本地任务执行	通过小型 Python API 提交本地多进程任务，并取得 ObjectRef 与结果。
ObjectRef 数据流	跟踪任务结果如何进入对象存储，并通过 POSIX 共享内存在本机进程间协作。
Python / C++ 边界	从 pybind11 绑定进入 C++ 的 CoreWorker、Scheduler 与 ObjectStore。
可运行的学习样例	使用对象存储、调度、任务、训练、调参与实验性 Actor / Dashboard 示例建立直觉。

快速开始

环境要求

• Linux 或 macOS，并支持 POSIX 共享内存
• Python 3.8+（完整 Quick Start；包元数据的 3.7+ 下限不覆盖 requirements.txt 的依赖）
• CMake 3.15+
• 支持 C++17 的编译器

git clone https://github.com/NEDONION/mini-ray.git
cd mini-ray

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

python examples/03_simple_task.py
python -m pytest tests -v

pip install -e . 会通过 CMake 构建 C++ 扩展。requirements.txt 同时包含可选 Dashboard 和机器学习 示例所需的依赖；GPU 不是必需条件，GAN 示例在 CUDA 不可用时会回退到 CPU。

最小 API

import miniray

miniray.init(num_workers=2)

@miniray.remote
def fibonacci(n):
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(n - 1):
        a, b = b, a + b
    return b

result = miniray.get(fibonacci.remote(10))
print(result)  # 55

miniray.shutdown()

想从任务提交和结果取回开始逐行跟踪，可直接运行 examples/03_simple_task.py。

运行预览

多进程训练 观察训练任务如何由本地进程协作完成。	GAN 实验 将教学运行时用于一个可视化的机器学习实验。
GPU 监控（可选） 有 CUDA 环境时，可观察 GAN 实验的 GPU 使用情况。

工作原理

flowchart LR
    User["Python 用户代码"] --> API["mini-ray Python API"]
    API --> Bindings["pybind11 绑定"]
    Bindings --> Worker["C++ CoreWorker"]
    Worker --> Scheduler["Scheduler"]
    Worker --> Store["ObjectStore"]
    Scheduler <--> Shared["POSIX 共享内存"]
    Store <--> Shared

Loading

C++ 层负责调度器和对象存储原语；Python 层提供面向学习的 API，并启动本地 Worker 进程。上图描述的是 单机内的执行路径，而非分布式集群架构。

关键组成

区域	仓库中已有的内容	从这里开始
运行时核心	ObjectStore、Scheduler、CoreWorker 与共享内存原语	doc/DESIGN.md
Python API	init、remote、get 与 shutdown	python/miniray/api.py
基础样例	对象存储、调度和任务演示	examples/
扩展实验	Actor、Tune、Train、Parameter Server 和 Dashboard 模块	python/miniray/

项目边界

• mini-ray 是面向学习的 alpha 项目，只支持单机、多进程运行。
• 不提供集群执行、分布式容错、自动扩缩容或 Windows 支持。
• API 与内部实现借鉴 Ray 的概念，但不与 Ray 兼容。
• 机器学习与 Dashboard 代码属于实验性示例，不应视为通用或生产级运行时。

文档

文档	内容
示例指南	从对象存储到训练与调参的样例入口
架构与设计说明	核心组件、调用链路与设计取舍
项目结构	目录职责与源码定位
CMake 构建指南	C++ 扩展的构建与排错
Actor 与工作流设计	实验性 Actor 和工作流模块说明

参与贡献

欢迎通过 Issues 提交问题、学习记录或改进建议，也欢迎提交小而 聚焦的 Pull Request。提交前请至少运行：

python -m pytest tests -v

延伸阅读

• Ray documentation
• Ray architecture paper
• pybind11 documentation