meta-pytorch/monarch
GitHub: meta-pytorch/monarch
一个基于可扩展 actor 模型的 PyTorch 分布式编程框架，提供容错、RDMA 传输和分布式 tensor 能力。
Stars: 1058 | Forks: 163
# Monarch 🦋
**Monarch** 是一个基于可扩展 actor 消息传递的 PyTorch 分布式编程框架。它提供：
1. 具备可扩展消息传递功能的远程 actor：Actor 被分组到称为 mesh 的集合中，并且消息可以广播给所有成员。
2. 通过 supervision tree 实现容错：Actor 和进程形成一棵树，故障会沿树向上传播，提供良好的默认错误行为，并支持细粒度的故障恢复。
3. 点对点 RDMA 传输：在进程中低成本注册任何 GPU 或 CPU 内存，支持基于 libibverbs 的单边传输。
4. 分布式 tensor：Actor 可以处理跨进程分片的 tensor 对象。
Monarch 代码通过简单的 Python API 以命令式方式描述如何创建进程和 actor：
```
from monarch.actor import Actor, endpoint, this_host
# spawn 8 个 trainer 进程，每个 gpu 一个
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)
# 告诉所有 trainers 执行一个 step
fut = trainers.train.call(step=0)
# 等待所有 trainers 完成
fut.get()
```
[Monarch 概念简介](https://meta-pytorch.org/monarch/generated/examples/getting_started.html) 提供了有关如何使用这些功能的介绍。
## 📖 文档
请通过[此链接](https://meta-pytorch.org/monarch/)查看 Monarch 的托管文档。
## 安装说明
### 从预构建的 Wheel 安装
Monarch 提供了预构建的 wheel，无论你安装了什么版本的 PyTorch 都可以使用。你可以使用 `pip` 或 `uv` 获取它们：
- **使用 PIP**：
- 稳定版：`pip install torchmonarch`
- 每日构建版：`pip install --pre torchmonarch`
- 指定版本：`pip install torchmonarch==v0.6.0.dev20260526`
- **使用 UV** - 注意，你也可以直接使用 `uv pip install ...` 并匹配上述 pip 命令；但下面的命令能正确地将 monarch 添加到你的 UV 项目中。
- 稳定版：`uv add torchmonarch`
- 每日构建版：`uv add --prerelease=allow torchmonarch`
- 指定版本：`uv add torchmonarch==v0.6.0.dev20260526`
### 从源码构建并安装
**注意**：从源码构建需要额外的系统依赖。这些依赖仅在**构建时**需要，在运行时不需要。
Monarch 使用 `uv` 进行快速、可靠的 Python 包管理。如果你还没有安装 `uv`：
```
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者在 macOS 上
brew install uv
```
**配置 PyTorch Index**：默认情况下，Monarch 会使用来自 `pytorch-cu132` index (CUDA 13.2) 的 PyTorch 进行构建。要使用不同的 CUDA 版本：
- 编辑 `pyproject.toml` 中的 `[tool.uv.sources]`，使其指向不同的 index（例如 `pytorch-cu130` 或 `pytorch-cpu`）
- 或者在运行 uv 时使用 `--extra-index-url`：
uv sync --extra-index-url https://download.pytorch.org/whl/cu130
#### 了解 Tensor Engine
Monarch 包含[分布式 tensor](https://meta-pytorch.org/monarch/generated/examples/getting_started.html#distributed-tensors)和 [RDMA](https://meta-pytorch.org/monarch/generated/examples/getting_started.html#point-to-point-rdma) API。Tensor engine 可以在任何平台上构建，包括仅限 CPU 的主机和 macOS；特定于 GPU 的组件（NCCL、RDMA、rdmaxcel）作为上层依赖，仅可在安装了 CUDA 或 ROCm 工具链的 Linux 环境下构建。如果你想要一个更轻量级的 Monarch 版本（仅包含 actor，无 torch 依赖），请设置 `USE_TENSOR_ENGINE=0`。
默认情况下，Monarch 在构建时会启用 tensor_engine。如果要构建不包含它的版本：
```
USE_TENSOR_ENGINE=0 uv sync
```
**注意**：构建不包含 tensor_engine 的版本意味着你将无法使用分布式 tensor 或 RDMA API。使用 tensor_engine 需要 Torch，且最新的稳定版 Torch 与最新的带版本号的 torchmonarch 保持 ABI 兼容。
**选择 GPU 平台**：`MONARCH_GPU_PLATFORM` 环境变量控制构建时链接哪些 GPU 库。它接受以下值：
- `cuda` — 基于 CUDA 构建 (NCCL + RDMA)。
- `rocm` — 基于 ROCm 构建。
- `none` — 即使在安装了 CUDA 或 ROCm 的主机上，也强制使用仅支持 CPU 的 tensor engine。
如果不设置该变量，系统会自动检测当前存在的工具链。如果同时安装了 CUDA 和 ROCm，则必须显式设置此变量；当你想在支持 GPU 的主机上使用 CPU tensor engine 时，`none` 是显式禁用的选项。
```
# 强制使用仅 CPU 的 tensor engine（无需 CUDA/ROCm/RDMA 库）
MONARCH_GPU_PLATFORM=none uv sync
# 在同时拥有 ROCm 的主机上强制使用 CUDA
MONARCH_GPU_PLATFORM=cuda uv sync
```
#### 各平台构建依赖
##### 在 Fedora 发行版上
```
# 安装 nightly rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly
# 安装 non-python 依赖
sudo dnf install -y cmake ninja-build protobuf-compiler libunwind
# 为您的机器安装正确的 cuda 和 cuda-toolkit 版本
sudo dnf install cuda-toolkit-13-2 cuda-13-2
# 安装 clang-devel、nccl-devel 和 libstdc++-static
sudo dnf install clang-devel libnccl-devel libstdc++-static
# 安装 RDMA 库（tensor_engine 构建需要）
sudo dnf install -y libibverbs rdma-core libmlx5 libibverbs-devel rdma-core-devel
# Clone 并 sync 依赖
git clone https://github.com/meta-pytorch/monarch.git
cd monarch
# 以开发模式安装所有依赖
uv sync
# 或者在不使用 tensor_engine 的情况下安装
USE_TENSOR_ENGINE=0 uv sync
# 验证安装
uv run python -c "from monarch import actor; print('Monarch installed successfully')"
# 重新构建（例如，在更改 Rust 代码后）
USE_TENSOR_ENGINE=0 uv pip install -e .
```
##### 在 Ubuntu 发行版上
```
# 安装 nightly rust toolchain
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-toolkit 版本
sudo apt install -y cuda-toolkit-13-2 cuda-13-2
# 安装 RDMA 库（tensor_engine 构建需要）
sudo apt install -y rdma-core libibverbs1 libmlx5-1 libibverbs-dev
# Clone 并 sync 依赖
git clone https://github.com/meta-pytorch/monarch.git
cd monarch
# 以开发模式安装所有依赖
uv sync
# 或者在不使用 tensor_engine（仅 CPU）的情况下安装
USE_TENSOR_ENGINE=0 uv sync
# 验证安装
uv run python -c "from monarch import actor; print('Monarch installed successfully')"
# 重新构建（例如，在更改 Rust 代码后）
USE_TENSOR_ENGINE=0 uv pip install -e .
```
##### 在非 CUDA 机器上
你也可以在非 CUDA 机器（例如 macOS 笔记本电脑）上构建 Monarch 以供仅限 CPU 的环境使用。Tensor engine 本身可以在 CPU 上运行；只是会跳过特定于 GPU 的部分（NCCL、RDMA、rdmaxcel）。自动检测机制会处理未安装 CUDA 或 ROCm 的主机。如果你的主机确实安装了 GPU 工具链，但你仍然希望使用 CPU tensor engine，请设置 `MONARCH_GPU_PLATFORM=none`。
```
# 安装 nightly rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly
# Clone 并 sync 依赖
git clone https://github.com/meta-pytorch/monarch.git
cd monarch
# 构建 CPU tensor engine（自动检测无 GPU）
uv sync
# 或者，完全跳过 tensor engine（仅 actors，无需 torch）
USE_TENSOR_ENGINE=0 uv sync
# 验证安装
uv run python -c "from monarch import actor; print('Monarch installed successfully')"
```
#### 替代方案：使用 pip
如果你更喜欢使用 pip 而不是 uv：
```
# 在安装系统依赖之后（见上文）
# 安装构建依赖
# 构建并安装 Monarch
pip install .
# 或者用于开发
pip install -e .
# 不使用 tensor_engine
USE_TENSOR_ENGINE=0 pip install -e .
```
### 从源码构建 Docker 镜像
要构建一个捆绑了你从源码构建的 Monarch 的 Docker 镜像（例如，为了在 Kubernetes 集群上运行 Monarch），请先构建一个 wheel，然后基于该 wheel 构建镜像。这会一并应用对 Rust 和 Python 代码的更改。
```
# 确保为 python 3.12 进行构建，因为 pytorch 基础镜像使用该 python 版本
uv python pin 3.12
# 构建二进制分发包，输出到 "dist/" 目录。
# --no-build-isolation 允许使用已缓存的 rust 构建，这可以加快后续的
# 迭代。
uv build --no-build-isolation --wheel
# 使用 docker：
# 使用您构建的 monarch 构建并标记 docker 镜像。您可以根据需要更新
# PYTORCH_TAG 以使用不同的基础镜像。
# 使用 nightly dockerfile 是因为它会使用您已经构建好的包，
# 而不是从 PyPI 下载。wheels 通过名为 "monarch-wheels" 的
# 构建上下文提供，Dockerfile 会从中进行复制。
docker build -f Dockerfile.nightly \
-t $USER/monarch:local-tag \
--build-arg PYTORCH_TAG=2.12.0.dev20260224-cuda12.8-cudnn9-runtime \
--build-context monarch-wheels=dist \
.
# Push 以便 kubernetes cluster 可以使用它。
# 可以 (a) Push 到 container registry，以便您的 cluster 可以访问它。
# 根据您的上传速度和 container 的大小，可能会比较慢。
docker push $USER/monarch:latest
# 或者 (b) 如果您有一个完全本地的 kubernetes cluster，您可以将其更改为
# manifest 中的 imagePullPolicy: Never，它将在本地使用该镜像。这是
# 最快的迭代速度。
# 使用 podman + kind：
# 相同的构建命令，将 "docker" 替换为 "podman"
# 将镜像保存到归档文件
podman save localhost/$USER/monarch:local-tag -o /tmp/monarch-image
# 然后 Push 到您的 kind cluster 进行本地开发：
KIND_EXPERIMENTAL_PROVIDER=podman kind load image-archive /tmp/monarch-image -n monarch-cluster
```
然后，将你的部署指向新镜像。确保在前面添加你用于 docker login 的镜像仓库地址（如 `ghcr.io` 或 `docker.io`），并且你首先已经推送了该镜像。
## 运行示例
查看 `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 # This creates and activates a virtual environment
uv run cargo nextest run # Run tests within the uv environment
# 或者如果使用 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 issue，标题格式如下：
```
DISABLED
```
在每次 CI 运行开始时，`scripts/fetch_disabled_tests.py` 会获取所有标题以 `DISABLED ` 开头的未关闭的 issue，并跳过指定的测试。
关闭该 issue 将会在下次运行时重新启用该测试。
**命名格式：**
- **Rust (cargo nextest)：** 使用在 nextest 输出中显示的确切测试名称：` `，例如
`DISABLED hyperactor proc::tests::test_child_lifecycle`
- **Python (pytest)：** 使用测试函数名称，例如
`DISABLED test_my_function`
### 在本地覆盖跳过规则
要运行当前通过 GitHub issue 禁用的测试，你可以在运行 `scripts/fetch_disabled_tests.py` 之前创建相关文件以覆盖获取到的跳过列表。该脚本不会覆盖已经存在的文件：
- **`disabled_tests.txt`** — 控制要跳过哪些 Python 测试。创建此文件时，仅需写入你想跳过的测试（或将其留空以跳过所有测试）。
- **`.config/nextest-filter.txt`** — 控制要跳过哪些 Rust 测试。在此处编写 nextest 过滤表达式（例如，使用 `all()` 运行所有测试，或使用 `not (test(some_test))` 仅跳过特定测试）。
例如，要在本地运行所有测试而不受未关闭的 issue 影响：
```
echo -n "" > disabled_tests.txt
echo "all()" > .config/nextest-filter.txt
uv run python scripts/fetch_disabled_tests.py # will skip both writes
uv run pytest python/tests/ -v -m "not oss_skip"
```
## 许可证
Monarch 采用 BSD-3 许可证，详情请见 [LICENSE](LICENSE) 文件。
标签：Vectored Exception Handling, 凭据扫描, 可视化界面, 请求拦截, 逆向工具, 通知系统