---

exo 将你的所有设备连接成一个 AI 集群。exo 不仅能够运行超出单台设备容量的大型模型，而且通过 对 Thunderbolt RDMA 的 day-0 支持，让你在添加更多设备时模型运行速度更快。

功能特性

• 自动设备发现：运行 exo 的设备会自动发现彼此，无需手动配置。
• Thunderbolt RDMA：exo 内置 对 Thunderbolt 5 RDMA 的 day-0 支持，可将设备间延迟降低 99%。
• 拓扑感知自动并行：exo 会根据设备拓扑的实时视图，自动找出在所有可用设备间拆分模型的最佳方式。它会考虑设备资源以及每条链路之间的网络延迟/带宽。
• 张量并行（Tensor Parallelism）：exo 支持模型分片（sharding），在 2 台设备上可获得最高 1.8 倍加速，在 4 台设备上可获得最高 3.2 倍加速。
• MLX 支持：exo 使用 MLX 作为推理后端，并使用 MLX distributed 进行分布式通信。
• 多 API 兼容：兼容 OpenAI Chat Completions API、Claude Messages API、OpenAI Responses API 和 Ollama API——可直接使用你现有的工具和客户端。
• 自定义模型支持：从 HuggingFace Hub 加载自定义模型，扩展可用模型的范围。

仪表盘

exo 包含一个内置仪表盘，用于管理集群和与模型对话。

4 × 512GB M3 Ultra Mac Studio 运行 DeepSeek v3.1（8-bit）和 Kimi-K2-Thinking（4-bit）

基准测试

Qwen3-235B（8-bit）在 4 × M3 Ultra Mac Studio 上使用张量并行 RDMA

来源： Jeff Geerling：Mac Studio 上的 15 TB VRAM —— Thunderbolt 5 RDMA

DeepSeek v3.1 671B（8-bit）在 4 × M3 Ultra Mac Studio 上使用张量并行 RDMA

来源： Jeff Geerling：Mac Studio 上的 15 TB VRAM —— Thunderbolt 5 RDMA

Kimi K2 Thinking（原生 4-bit）在 4 × M3 Ultra Mac Studio 上使用张量并行 RDMA

来源： Jeff Geerling：Mac Studio 上的 15 TB VRAM —— Thunderbolt 5 RDMA

---

快速开始

运行 exo 的设备会自动发现彼此，无需任何手动配置。每台设备都提供 API 和仪表盘用于与集群交互（运行在 http://localhost:52415）。

有两种方式运行 exo：

从源码运行（macOS）

如果你已安装 Nix，可以跳过以下大部分步骤直接运行 exo：

nix run .#exo

注意： 要接受 Cachix 二进制缓存（并避免使用 Xcode Metal ToolChain），请在 /etc/nix/nix.conf 中添加：

trusted-users = root    （或你的用户名）
experimental-features = nix-command flakes

然后重启 Nix 守护进程：sudo launchctl kickstart -k system/org.nixos.nix-daemon

前置要求：

• Xcode（提供 MLX 编译所需的 Metal ToolChain）

• brew（用于 macOS 的简单包管理）

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

• uv（用于 Python 依赖管理）

• node（用于构建仪表盘）

  brew install uv node
  

• rust（用于构建 Rust 绑定，目前需要 nightly 版本）

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  rustup toolchain install nightly
  

• macmon（用于 Apple Silicon 的硬件监控）

  请安装本仓库使用的指定 fork 版本，而非 Homebrew 的 macmon。 Homebrew 的 macmon 0.6.1 在 Apple M5 上仍会崩溃。

  cargo install --git https://github.com/swiftraccoon/macmon \
    --rev 9154d234f763fbeffdcb4135d0bbbaf80609699b \
    macmon \
    --force
  

克隆仓库，构建仪表盘，然后运行 exo：

# 克隆 exo
git clone https://github.com/exo-explore/exo

# 构建仪表盘
cd exo/dashboard && npm install && npm run build && cd ..

# 运行 exo
uv run exo

这将启动 exo 仪表盘和 API，地址为 http://localhost:52415/

请查看 RDMA 相关章节，以在 macOS >=26.2 上启用此功能！

从源码运行（Linux）

前置条件：

• uv（用于 Python 依赖管理）
• node（用于构建仪表盘）- 版本 18 或更高
• rust（用于构建 Rust 绑定，目前需要 nightly 版本）

安装方法：

选项 1：使用系统包管理器（以 Ubuntu/Debian 为例）：

# 安装 Node.js 和 npm
sudo apt update
sudo apt install nodejs npm

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

# 安装 Rust（使用 rustup）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly

选项 2：在 Linux 上使用 Homebrew（如偏好此方式）：

# 在 Linux 上安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install uv node

# 安装 Rust（使用 rustup）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly

注意： macmon 包仅适用于 macOS，Linux 上不需要。

克隆仓库，构建仪表盘，然后运行 exo：

# 克隆 exo
git clone https://github.com/exo-explore/exo

# 构建仪表盘
cd exo/dashboard && npm install && npm run build && cd ..

# 运行 exo
uv run exo

这会在 http://localhost:52415/ 启动 exo 仪表盘和 API。

Linux 用户重要提示： 目前，exo 在 Linux 上仅使用 CPU 运行。Linux 平台的 GPU 支持正在开发中。如果您希望看到对特定 Linux 硬件的支持，请搜索现有的功能请求或创建新的功能请求。

配置选项：

• --no-worker：在不运行 worker 组件的情况下启动 exo。适用于仅作为协调器（coordinator）的节点，这类节点负责网络和编排，但不执行推理任务。对于 GPU 资源不足但网络连接良好的机器很有帮助。

  uv run exo --no-worker
  

文件位置（Linux）：

exo 在 Linux 上遵循 XDG 基础目录规范：

• 配置文件：~/.config/exo/（或 $XDG_CONFIG_HOME/exo/）
• 数据文件：~/.local/share/exo/（或 $XDG_DATA_HOME/exo/）
• 缓存文件：~/.cache/exo/（或 $XDG_CACHE_HOME/exo/）
• 日志文件：~/.cache/exo/exo_log/（自动日志轮转）
• 自定义模型卡片：~/.local/share/exo/custom_model_cards/

您可以通过设置相应的 XDG 环境变量来覆盖这些位置。

macOS 应用

exo 提供了一个 macOS 应用，可在您的 Mac 后台运行。

macOS 应用需要 macOS Tahoe 26.2 或更高版本。

在此下载最新版本：EXO-latest.dmg。

应用会请求修改系统设置和安装新网络配置文件的权限。相关改进正在进行中。

用于集群隔离的自定义命名空间：

macOS 应用包含自定义命名空间功能，允许您将 exo 集群与同一网络上的其他集群隔离。此功能通过 EXO_LIBP2P_NAMESPACE 设置进行配置：

• 使用场景：

  • 在同一网络上运行多个独立的 exo 集群
  • 将开发/测试集群与生产集群隔离
  • 防止意外加入集群

• 配置：在应用的高级设置中访问此设置（或在从源码运行时设置 EXO_LIBP2P_NAMESPACE 环境变量）

命名空间会在启动时记录，用于调试目的。

卸载 macOS 应用

推荐的卸载方式是通过应用本身：点击菜单栏图标 → 高级 → 卸载。这会干净地移除所有系统组件。

如果您已经删除了应用，可以运行独立的卸载脚本：

sudo ./app/EXO/uninstall-exo.sh

这会移除：

• 网络设置的 LaunchDaemon
• 网络配置脚本
• 日志文件
• "exo" 网络位置

注意： 您需要手动从系统设置 → 通用 → 登录项中移除 EXO。

---

在 macOS 上启用 RDMA

RDMA（远程直接内存访问，Remote Direct Memory Access）是 macOS 26.2 新增的功能。它适用于任何配备 Thunderbolt 5 的 Mac（M4 Pro Mac Mini、M4 Max Mac Studio、M4 Max MacBook Pro、M3 Ultra Mac Studio）。

请参阅注意事项以进行即时故障排除。

要在 macOS 上启用 RDMA，请按以下步骤操作：

1. 关闭 Mac。
2. 按住电源按钮 10 秒，直到出现启动菜单。
3. 选择"选项"进入恢复模式。
4. 当恢复界面出现时，从实用工具菜单打开终端。
5. 在终端中输入：

   rdma_ctl enable
   

   然后按回车键。
6. 重新启动 Mac。

之后，RDMA 将在 macOS 中启用，exo 会自动处理其余配置。

重要注意事项

1. 希望加入 RDMA 集群的设备必须与集群中的所有其他设备连接。
2. 线缆必须支持 TB5。
3. 在 Mac Studio 上，不能使用以太网端口旁边的 Thunderbolt 5 端口。
4. 如果从源码运行，请使用 tmp/set_rdma_network_config.sh 脚本，该脚本会禁用 Thunderbolt Bridge 并在每个 RDMA 端口上设置 DHCP。
5. RDMA 端口可能无法在不同版本的 macOS 上相互发现。请确保所有设备的操作系统版本完全匹配（包括 beta 版本号）。

---

环境变量

exo 支持多个用于配置的环境变量：

变量	描述	默认值
EXO_DEFAULT_MODELS_DIR	模型下载和缓存的默认目录。始终位于可写目录列表的首位。	~/.local/share/exo/models（Linux）或 ~/.exo/models（macOS）
EXO_MODELS_DIRS	以冒号分隔的额外可写目录，用于模型下载。按顺序在默认目录之后检查；使用第一个有足够可用空间的目录。	无
EXO_MODELS_READ_ONLY_DIRS	以冒号分隔的只读目录，用于搜索预下载的模型（例如 NFS 挂载、共享存储）。此处的模型无法删除。	无
EXO_OFFLINE	在无网络连接的情况下运行（仅使用本地模型）	false
EXO_ENABLE_IMAGE_MODELS	启用图像模型支持	false
EXO_LIBP2P_NAMESPACE	用于集群隔离的自定义命名空间	无
EXO_FAST_SYNCH	控制 MLX_METAL_FAST_SYNCH 行为（用于 JACCL 后端）	自动
EXO_TRACING_ENABLED	启用分布式追踪以进行性能分析	false

使用示例：

# 从 NFS 挂载使用预下载的模型（只读）
EXO_MODELS_READ_ONLY_DIRS=/mnt/nfs/models:/opt/ai-models uv run exo

# 将模型下载到外部 SSD（如果已满则回退到默认目录）
EXO_MODELS_DIRS=/Volumes/ExternalSSD/exo-models uv run exo

# 离线模式运行
EXO_OFFLINE=true uv run exo

# 启用图像模型
EXO_ENABLE_IMAGE_MODELS=true uv run exo

# 使用自定义命名空间进行集群隔离
EXO_LIBP2P_NAMESPACE=my-dev-cluster uv run exo

---

使用 API

exo 提供多种 API 兼容接口，以最大程度兼容现有工具：

• OpenAI Chat Completions API - 兼容 OpenAI 客户端
• Claude Messages API - 兼容 Anthropic 的 Claude 格式
• OpenAI Responses API - 兼容 OpenAI 的 Responses 格式
• Ollama API - 兼容 Ollama 及 OpenWebUI 等工具

如果你希望通过 API 与 exo 交互，以下示例展示了如何创建一个小型模型实例（mlx-community/Llama-3.2-1B-Instruct-4bit）、发送聊天补全请求以及删除实例。

---

1. 预览实例部署方案

/instance/previews 端点会预览模型的所有有效部署方案。

curl "http://localhost:52415/instance/previews?model_id=llama-3.2-1b"

示例响应：

{
  "previews": [
    {
      "model_id": "mlx-community/Llama-3.2-1B-Instruct-4bit",
      "sharding": "Pipeline",
      "instance_meta": "MlxRing",
      "instance": {...},
      "memory_delta_by_node": {"local": 729808896},
      "error": null
    }
    // ...可能有更多部署方案...
  ]
}

这将返回该模型的所有有效部署方案。选择你喜欢的方案。 要选择第一个，使用 jq 管道：

curl "http://localhost:52415/instance/previews?model_id=llama-3.2-1b" | jq -c '.previews[] | select(.error == null) | .instance' | head -n1

---

2. 创建模型实例

向 /instance 发送 POST 请求，在 instance 字段中指定你想要的部署方案（完整负载必须与 CreateInstanceParams 中的类型匹配），可从第 1 步复制：

curl -X POST http://localhost:52415/instance \
  -H 'Content-Type: application/json' \
  -d '{
    "instance": {...}
  }'

示例响应：

{
  "message": "Command received.",
  "command_id": "e9d1a8ab-...."
}

---

3. 发送聊天补全请求

现在，向 /v1/chat/completions 发送 POST 请求（与 OpenAI API 格式相同）：

curl -N -X POST http://localhost:52415/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mlx-community/Llama-3.2-1B-Instruct-4bit",
    "messages": [
      {"role": "user", "content": "What is Llama 3.2 1B?"}
    ],
    "stream": true
  }'

---

4. 删除实例

完成后，通过实例 ID 删除实例（可通过 /state 或 /instance 端点查找）：

curl -X DELETE http://localhost:52415/instance/YOUR_INSTANCE_ID

Claude Messages API 兼容性

使用 /v1/messages 端点，采用 Claude Messages API 格式：

curl -N -X POST http://localhost:52415/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mlx-community/Llama-3.2-1B-Instruct-4bit",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 1024,
    "stream": true
  }'

OpenAI Responses API 兼容性

使用 /v1/responses 端点，采用 OpenAI Responses API 格式：

curl -N -X POST http://localhost:52415/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mlx-community/Llama-3.2-1B-Instruct-4bit",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": true
  }'

Ollama API 兼容性

exo 支持 Ollama API 端点，以兼容 OpenWebUI 等工具：

# Ollama 聊天
curl -X POST http://localhost:52415/ollama/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mlx-community/Llama-3.2-1B-Instruct-4bit",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": false
  }'

# 列出模型（Ollama 格式）
curl http://localhost:52415/ollama/api/tags

从 HuggingFace 加载自定义模型

你可以从 HuggingFace Hub 添加自定义模型：

curl -X POST http://localhost:52415/models/add \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "mlx-community/my-custom-model"
  }'

安全提示：

配置中需要 trust_remote_code 的自定义模型必须显式启用（默认为 false）以确保安全。仅在信任模型远程代码执行的情况下启用此选项。模型从 HuggingFace 获取并作为自定义模型卡片本地存储。

其他有用的 API 端点：

• 列出所有模型：curl http://localhost:52415/models
• 仅列出已下载模型：curl http://localhost:52415/models?status=downloaded
• 搜索 HuggingFace：curl "http://localhost:52415/models/search?query=llama&limit=10"
• 查看实例 ID 和部署状态：curl http://localhost:52415/state

更多详情，请参阅：

• docs/api.md 中的 API 文档
• src/exo/master/api.py 中的 API 类型和端点

---

基准测试

exo-bench 工具用于测量不同部署配置下的模型预填充（prefill）和 Token 生成速度。这有助于优化模型性能并验证改进效果。

前置条件：

• 基准测试前节点应已运行 uv run exo
• 该工具使用 /bench/chat/completions 端点

基本用法：

uv run bench/exo_bench.py \
  --model Llama-3.2-1B-Instruct-4bit \
  --pp 128,256,512 \
  --tg 128,256

关键参数：

• --model：要基准测试的模型（短 ID 或 HuggingFace ID）
• --pp：提示词大小提示（逗号分隔的整数）
• --tg：生成长度（逗号分隔的整数）
• --max-nodes：将部署方案限制为 N 个节点（默认：4）
• --instance-meta：按 ring、jaccl 或 both 过滤（默认：both）
• --sharding：按 pipeline、tensor 或 both 过滤（默认：both）
• --repeat：每种配置的重复次数（默认：1）
• --warmup：每种部署方案的预热运行次数（默认：0）
• --json-out：结果输出文件（默认：bench/results.json）

带过滤的示例：

uv run bench/exo_bench.py \
  --model Llama-3.2-1B-Instruct-4bit \
  --pp 128,512 \
  --tg 128 \
  --max-nodes 2 \
  --sharding tensor \
  --repeat 3 \
  --json-out my-results.json

该工具输出性能指标，包括每种配置的每秒提示词 Token 数（prompt_tps）、每秒生成 Token 数（generation_tps）和峰值内存使用量。

---

硬件加速器支持

在 macOS 上，exo 使用 GPU。在 Linux 上，exo 目前运行在 CPU 上。我们正在努力扩展硬件加速器支持。如果你希望支持新的硬件平台，请搜索现有功能请求并点赞，以便我们了解社区重视的硬件。

---

贡献

请参阅 CONTRIBUTING.md 了解如何为 exo 做出贡献的指南。

exo 快速上手指南

环境准备

系统要求

平台	要求
macOS	macOS Tahoe 26.2+（推荐），支持 Apple Silicon
Linux	主流发行版，目前仅支持 CPU 运行
硬件	Thunderbolt 5 设备可启用 RDMA 加速（M4 Pro/Max、M3 Ultra 等）

前置依赖

macOS 必需：

• Xcode（提供 Metal 工具链）
• Homebrew
• uv（Python 包管理）
• Node.js（构建仪表盘）
• Rust（nightly 工具链）
• macmon（硬件监控，需指定版本）

Linux 必需：

• uv
• Node.js 18+
• Rust nightly

---

安装步骤

macOS 安装

方式一：使用 Nix（推荐，可跳过大部分步骤）

# 添加 Cachix 缓存配置到 /etc/nix/nix.conf
# trusted-users = root
# experimental-features = nix-command flakes

# 重启 Nix 守护进程后运行
sudo launchctl kickstart -k system/org.nixos.nix-daemon
nix run .#exo

方式二：手动安装

# 1. 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 安装依赖
brew install uv node

# 3. 安装 Rust nightly
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly

# 4. 安装指定版本 macmon（Homebrew 版本在 M5 上不稳定）
cargo install --git https://github.com/swiftraccoon/macmon \
  --rev 9154d234f763fbeffdcb4135d0bbbaf80609699b \
  macmon --force

# 5. 克隆并构建
git clone https://github.com/exo-explore/exo
cd exo/dashboard && npm install && npm run build && cd ..

# 6. 运行
uv run exo

方式三：macOS App（最简单）

下载：EXO-latest.dmg

需要 macOS 26.2+，首次运行需授权修改系统设置和网络配置。

---

Linux 安装

# Ubuntu/Debian 示例
sudo apt update
sudo apt install nodejs npm

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

# 安装 Rust nightly
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly

# 克隆并构建
git clone https://github.com/exo-explore/exo
cd exo/dashboard && npm install && npm run build && cd ..

# 运行
uv run exo

注意： Linux 目前仅支持 CPU 推理，GPU 支持正在开发中。

---

基本使用

启动服务

# 默认启动（自动发现集群设备）
uv run exo

# 仅作为协调节点（不执行推理）
uv run exo --no-worker

服务启动后：

• 仪表盘：http://localhost:52415
• API 端点：http://localhost:52415/v1/chat/completions

使用 OpenAI 兼容 API

curl http://localhost:52415/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

启用 RDMA 加速（macOS 26.2+）

1. 关机后按住电源键 10 秒进入恢复模式
2. 选择「Options」→「Utilities」→「Terminal」
3. 执行：rdma_ctl enable
4. 重启

需满足：所有设备 Thunderbolt 5 直连、TB5 线缆、Mac Studio 避开以太网口旁的 TB 口。

---

配置文件位置

类型	路径
配置	~/.config/exo/
数据	~/.local/share/exo/
缓存	~/.cache/exo/
日志	~/.cache/exo/exo_log/
自定义模型	~/.local/share/exo/custom_model_cards/