君主 🦋

君主 是一个基于可扩展演员消息传递的 PyTorch 分布式编程框架。它提供了：

1. 具有可扩展消息传递的远程演员：演员被分组到称为网格的集合中，消息可以广播给所有成员。
2. 通过监督树实现容错：演员和进程形成一棵树，失败会沿着树向上传播，从而提供良好的默认错误处理行为，并支持细粒度的故障恢复。
3. 点对点 RDMA 传输：可以在进程中低成本注册任何 GPU 或 CPU 内存，并使用基于 libibverbs 的单边传输。
4. 分布式张量：演员可以操作跨进程划分的张量对象。

君主代码通过简单的 Python API 指令式地描述如何创建进程和演员：

from monarch.actor import Actor, endpoint, this_host

# 启动 8 个训练进程，每个 GPU 一个
training_procs = this_host().spawn_procs({"gpus": 8})


# 定义在每个进程中运行的演员
class Trainer(Actor):
    @endpoint
    def train(self, step: int): ...


# 创建训练器
trainers = training_procs.spawn("trainers", Trainer)

# 告诉所有训练器执行一步
fut = trainers.train.call(step=0)

# 等待所有训练器完成
fut.get()

君主概念介绍 提供了这些功能的使用入门。

⚠️ 早期开发警告 君主目前处于实验阶段。您可能会遇到一些 bug、功能不完整以及未来版本中可能发生变化的 API。项目欢迎修复 bug，但为了确保协调一致，在开始工作之前，建议先讨论任何重大更改。推荐您在问题跟踪器中表明您的贡献意向，可以通过提交新问题或认领现有问题来实现。

📖 文档

请访问 此链接 查看君主的托管文档。

安装

从预构建的 wheel 包安装

君主提供了与您安装的 PyTorch 版本无关的预构建 wheel 包：

稳定版

pip install torchmonarch

夜间版

pip install --pre torchmonarch

或者安装特定的夜间版本：

pip install torchmonarch==0.3.0.dev20260106

从源码构建并安装

注意：从源码构建需要额外的系统依赖。这些依赖仅在 构建时 需要，运行时不需要。

君主使用 uv 进行快速可靠的 Python 包管理。如果您尚未安装 uv：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者在 macOS 上
brew install uv

配置 PyTorch 索引：默认情况下，君主使用 pytorch-cu128 索引（CUDA 12.8）构建。如需使用其他 CUDA 版本：

• 编辑 pyproject.toml 中的 [tool.uv.sources]，指向不同的索引（例如 pytorch-cu126、pytorch-cu130 或 pytorch-cpu）
• 或者在运行 uv 时使用 --extra-index-url：

  uv sync --extra-index-url https://download.pytorch.org/whl/cu126
  

理解张量引擎

君主包含 分布式张量 和 RDMA API。由于这些功能与硬件相关，您可以选择以更轻量级的版本（仅含演员）进行开发，方法是设置 USE_TENSOR_ENGINE=0。

默认情况下，君主启用张量引擎进行构建。若要禁用它：

USE_TENSOR_ENGINE=0 uv sync

注意：禁用张量引擎后，您将无法使用分布式张量或 RDMA API。使用张量引擎需要 Torch，而最新稳定版的 Torch 与最新版本的 Torchmonarch 具有 ABI 兼容性。

按平台划分的构建依赖

在 Fedora 发行版上

# 安装夜间版 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly

# 安装非 Python 依赖
sudo dnf install -y cmake ninja-build protobuf-compiler libunwind

# 根据您的机器安装正确的 CUDA 和 CUDA 工具包版本
sudo dnf install cuda-toolkit-12-8 cuda-12-8

# 安装 clang-devel、nccl-devel 和 libstdc++-static
sudo dnf install clang-devel libnccl-devel libstdc++-static

# 安装 RDMA 库（用于张量引擎构建）
sudo dnf install -y libibverbs rdma-core libmlx5 libibverbs-devel rdma-core-devel

# 克隆并同步依赖
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# 以开发模式安装所有依赖
uv sync

# 或者不启用张量引擎
USE_TENSOR_ENGINE=0 uv sync

# 验证安装
uv run python -c "from monarch import actor; print('Monarch 安装成功')"

# 重新构建（例如修改了 Rust 代码之后）
USE_TENSOR_ENGINE=0 uv pip install -e .

在 Ubuntu 发行版上

# 安装夜间版 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup toolchain install nightly
rustup default nightly

# 安装 Ubuntu 特有的系统依赖
sudo apt install -y cmake ninja-build protobuf-compiler libunwind-dev clang

# 将 clang 设置为默认的 C/C++ 编译器
export CC=clang
export CXX=clang++

# 根据您的机器安装正确的 CUDA 和 CUDA 工具包版本
sudo apt install -y cuda-toolkit-12-8 cuda-12-8

# 安装 RDMA 库（用于张量引擎构建）
sudo apt install -y rdma-core libibverbs1 libmlx5-1 libibverbs-dev

# 克隆并同步依赖
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# 以开发模式安装所有依赖
uv sync

# 或者不启用张量引擎（仅限 CPU）
USE_TENSOR_ENGINE=0 uv sync

# 验证安装
uv run python -c "from monarch import actor; print('Monarch 安装成功')"

# 重新构建（例如修改了 Rust 代码之后）
USE_TENSOR_ENGINE=0 uv pip install -e .

在非 CUDA 机器上

您也可以在非 CUDA 机器上（例如 macOS 笔记本电脑）构建君主，以便仅使用 CPU。

请注意，这不支持张量引擎，因为张量引擎需要 CUDA 和 RDMA 库。

# 安装夜间版 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly

# 克隆并同步依赖（不启用张量引擎）
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# 不启用张量引擎（仅限 CPU）
USE_TENSOR_ENGINE=0 uv sync

# 验证安装
uv run python -c "from monarch import actor; print('Monarch 安装成功')"

替代方案：使用 pip

如果您更倾向于使用 pip 而不是 uv：

# 在安装好系统依赖之后（见上文）

# 安装构建依赖

# 构建并安装 Monarch
pip install .

# 或者用于开发
pip install -e .

# 不使用 tensor_engine
USE_TENSOR_ENGINE=0 pip install -e .

运行示例

请查看 examples/ 目录，其中包含如何使用 Monarch API 的演示。

随着功能的稳定和完善，我们还将添加更多示例！

运行测试

我们同时拥有 Rust 和 Python 的单元测试。Rust 测试通过 cargo-nextest 运行，Python 测试则通过 pytest 运行。

Rust 测试

重要提示： Monarch 的 Rust 代码使用 PyO3 与 Python 进行交互，这意味着 Rust 二进制文件需要链接到 Python 库。在运行 Rust 测试之前，您需要激活一个 Python 环境（conda、venv 或 uv）：

# 如果使用 uv（推荐）
uv sync  # 这会创建并激活一个虚拟环境
uv run cargo nextest run  # 在 uv 环境中运行测试

# 或者如果使用 conda
conda activate monarchenv
cargo nextest run

# 或者如果使用 venv
source .venv/bin/activate
cargo nextest run

如果没有激活的 Python 环境，您将会遇到类似以下的 Python 链接错误：

error: could not find native static library `python3.12`, perhaps an -L flag is missing?

安装 cargo-nextest：

# 我们使用 cargo-nextest 来运行测试，因为它能在每个测试之间提供强大的进程隔离。
# 这里我们从源码安装它，但您也可以使用此处描述的预编译二进制文件：
# https://nexte.st/docs/installation/pre-built-binaries/
cargo install cargo-nextest --locked

cargo-nextest 支持所有 "cargo test" 的过滤标志。

Python 测试

# 安装测试依赖项（如果尚未通过 uv sync 安装）
uv sync --extra test

# 使用 uv 运行单元测试
uv run pytest python/tests/ -v -m "not oss_skip"

# 或者如果使用 pip
pip install -e '.[test]'
pytest python/tests/ -v -m "not oss_skip"

禁用不稳定的 CI 测试

如果某个测试在 OSS CI 中持续失败，并且需要在不进行代码更改的情况下暂时禁用，请在此仓库中打开一个标题格式为以下的 GitHub 问题：

DISABLED <测试名称>

每次 CI 运行开始时，scripts/fetch_disabled_tests.py 脚本会获取所有标题以 DISABLED 开头的未关闭问题，并跳过这些测试。关闭该问题后，测试将在下一次运行中重新启用。

命名格式：

• Rust（cargo nextest）： 使用测试名称，完全按照 nextest 输出中的显示形式： module::path::test_fn, 例如： DISABLED hyperactor proc::tests::test_child_lifecycle
• Python（pytest）： 使用测试函数名称，例如： DISABLED test_my_function

在本地覆盖跳过设置

要运行当前因 GitHub 问题而被禁用的测试，您可以在运行 scripts/fetch_disabled_tests.py 之前创建以下文件来覆盖已获取的跳过列表。该脚本不会覆盖已经存在的文件：

• disabled_tests.txt — 控制哪些 Python 测试会被跳过。您可以在此文件中仅列出想要跳过的测试（或将其留空以不跳过任何测试）。
• .config/nextest-filter.txt — 控制哪些 Rust 测试会被跳过。您可以在此文件中编写 nextest 过滤表达式（例如 all() 表示运行所有测试，或 not (test(some_test)) 表示仅跳过特定测试）。

例如，要在本地运行所有测试而不受未关闭问题的影响：

echo -n "" > disabled_tests.txt
echo "all()" > .config/nextest-filter.txt
uv run python scripts/fetch_disabled_tests.py   # 将跳过这两处写入
uv run pytest python/tests/ -v -m "not oss_skip"

许可证

Monarch 采用 BSD-3 许可证，详情请参阅 LICENSE 文件。

Monarch 快速上手指南

Monarch 是一个基于可扩展 Actor 消息传递的 PyTorch 分布式编程框架。它支持远程 Actor、容错监督树、点对点 RDMA 传输以及分布式张量操作。

⚠️ 注意：Monarch 目前处于实验性开发阶段，API 可能会发生变化，生产环境使用请谨慎。

1. 环境准备

系统要求

• 操作系统：Linux (Fedora/Ubuntu) 或 macOS (仅 CPU 模式)
• Python：兼容主流 Python 版本
• 编译器工具链：需要 Rust nightly 工具链
• GPU 支持（可选）：若需使用分布式张量和 RDMA 功能，需安装 CUDA Toolkit (推荐 12.8) 及 RDMA 库 (libibverbs, rdma-core 等)。若仅需 Actor 功能，可在无 GPU 环境下运行。

前置依赖安装

安装 Rust Nightly

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup toolchain install nightly
rustup default nightly

安装系统级依赖 (以 Ubuntu 为例)

若需完整功能（含 Tensor Engine）：

sudo apt install -y cmake ninja-build protobuf-compiler libunwind-dev clang cuda-toolkit-12-8 cuda-12-8 rdma-core libibverbs1 libmlx5-1 libibverbs-dev

# 设置 clang 为默认编译器
export CC=clang
export CXX=clang++

若仅需 CPU 模式（无 Tensor Engine）：

sudo apt install -y cmake ninja-build protobuf-compiler libunwind-dev clang
export CC=clang
export CXX=clang++

安装 uv 包管理工具

Monarch 推荐使用 uv 进行依赖管理：

curl -LsSf https://astral.sh/uv/install.sh | sh

(macOS 用户也可使用 brew install uv)

2. 安装步骤

方式一：通过预编译 Wheel 安装（推荐）

最简单的方式，无需配置编译环境。

稳定版：

pip install torchmonarch

夜间构建版 (Nightly)：

pip install --pre torchmonarch

方式二：从源码构建

适用于开发者或需要特定 CUDA 版本的场景。

1. 克隆仓库

   git clone https://github.com/meta-pytorch/monarch.git
   cd monarch
   

2. 同步依赖并安装

   完整功能版 (需 CUDA 和 RDMA 环境):

   uv sync
   

   CPU only 版 (禁用 Tensor Engine，适合无显卡机器或 macOS):

   USE_TENSOR_ENGINE=0 uv sync
   

3. 验证安装

   uv run python -c "from monarch import actor; print('Monarch installed successfully')"
   

3. 基本使用

以下示例演示了如何启动多个训练进程、定义 Actor 并执行分布式调用。

from monarch.actor import Actor, endpoint, this_host

# 在当前主机上生成 8 个训练进程（对应 8 张 GPU）
training_procs = this_host().spawn_procs({"gpus": 8})


# 定义在每个进程上运行的 Actor
class Trainer(Actor):
    @endpoint
    def train(self, step: int): 
        # 在此处编写训练逻辑
        pass


# 创建 trainer 实例集合
trainers = training_procs.spawn("trainers", Trainer)

# 广播调用：让所有 trainer 执行一步训练
fut = trainers.train.call(step=0)

# 等待所有 trainer 完成
fut.get()

更多详细概念介绍和高级用法，请参考官方文档：Monarch Documentation