Monarch 简介与安装

什么是 PyTorch Monarch？

PyTorch Monarch 是 Meta 开源的分布式编程框架，它基于可扩展的 Actor 消息传递机制为 PyTorch 提供分布式能力。官方对它的定位是解决传统 SPMD（单程序多数据）模式在大规模 AI 训练中的编写和调试难题。

Monarch 提供四大核心能力：

1. 远程 Actor 与可扩展消息：Actor 被组织成称为 Mesh 的集合，消息可以广播给所有成员；
2. 基于监督树的容错：Actor 与进程构成树形结构，故障沿树向上传播，提供良好的默认错误行为，并支持细粒度故障恢复；
3. 点对点 RDMA 传输：以极低代价注册进程中的任意 GPU 或 CPU 内存，基于 libibverbs 实现单边传输；
4. 分布式张量：Actor 可以直接操作跨进程分片的张量对象。

Monarch 用一个简单的 Python API 命令式地描述如何创建进程和 Actor：

from monarch.actor import Actor, endpoint, this_host

# 为 8 个 GPU 各启动一个 trainer 进程
training_procs = this_host().spawn_procs({"gpus": 8})


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


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

# 通知所有 trainer 前进一步
fut = trainers.train.call(step=0)

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

这就是一个完整的单控制器（Single-Controller）程序：你在一个 Python 脚本里，用标准的控制流（if、for、try-except）编排整个集群。

平台支持

• Monarch 运行在 Linux 和 macOS 上；
• 仅 CPU 的张量引擎可在 macOS 及无 GPU 的 Linux 主机上构建运行；
• GPU 特性（分布式张量、RDMA）需要 Linux 并安装受支持的 GPU 工具链。

安装指南

前置要求

• Linux 或 macOS（GPU 特性仅支持 Linux）
• Python 3.10 或更高版本
• 可选：CUDA 兼容 GPU（用于分布式张量和 RDMA 特性）
• 对 PyTorch 的基本了解

方式一：预编译 Wheel（推荐）

Monarch 提供的预编译 wheel 与你安装的 PyTorch 版本无关，直接用 pip 或 uv 安装即可。下面的 nightly 示例里 YYYYMMDD 要替换成那次构建的实际日期：

# 稳定版
pip install torchmonarch

# nightly 版
pip install --pre torchmonarch

# 指定版本：把 YYYYMMDD 换成该 nightly 的构建日期
pip install torchmonarch==0.8.0.devYYYYMMDD

如果你使用 uv 管理项目依赖：

uv add torchmonarch                        # 稳定版
uv add --prerelease=allow torchmonarch     # nightly
uv add torchmonarch==0.8.0.devYYYYMMDD     # 指定版本，替换 YYYYMMDD

💡 注意：PyPI 包名是 torchmonarch，导入时用 import monarch。

⚠️ 版本号写法：当前 nightly 形如 0.8.0.devYYYYMMDD，不带 v 前缀——早期文档里曾写作 v0.7.0.dev20260713，照抄会被 pip 认为是非法版本号。

方式二：从源码构建

源码构建需要额外的系统依赖（仅构建期需要，运行时不需要）。官方推荐使用 uv 进行包管理：

# 安装 uv（如果没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库并同步依赖（开发模式）
git clone https://github.com/meta-pytorch/monarch.git
cd monarch
uv sync

张量引擎开关：默认构建包含张量引擎（分布式张量 + RDMA API），需要 PyTorch。如果你只想要轻量的 Actor 能力（无 torch 依赖）：

USE_TENSOR_ENGINE=0 uv sync

GPU 平台选择：通过 MONARCH_GPU_PLATFORM 环境变量控制链接的 GPU 库，可选 cuda / rocm / none：

MONARCH_GPU_PLATFORM=none uv sync  # 强制 CPU 张量引擎
MONARCH_GPU_PLATFORM=cuda uv sync  # 主机同时装了 CUDA 和 ROCm 时显式指定

源码构建的完整系统依赖清单（Rust nightly 工具链、cmake、RDMA 库等）见官方仓库 README。

验证安装

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

下一步

安装完成后，让我们开始编写第一个 Monarch 程序：定义和启动你的第一个 Actor。