exo-explore/exo
GitHub: exo-explore/exo
将多台设备自动组建为分布式 AI 推理集群，在本地运行单机无法容纳的前沿大模型。
Stars: 42402 | Forks: 2912
4 × 512GB M3 Ultra Mac Studio running DeepSeek v3.1 (8-bit) and Kimi-K2-Thinking (4-bit)
## 基准测试Qwen3-235B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA
Source: Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5
DeepSeek v3.1 671B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA
Source: Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5
Kimi K2 Thinking (native 4-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA
Source: Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5
该 macOS App 需要 macOS Tahoe 26.2 或更高版本。
在此下载最新构建版本：[EXO-latest.dmg](https://assets.exolabs.net/EXO-latest.dmg)。
该应用将请求修改系统设置和安装新网络配置文件的权限。这方面的改进正在进行中。
**用于集群隔离的自定义 Namespace：**
macOS App 包含一项自定义 namespace 功能，允许你将 exo 集群与同一网络上的其他集群隔离。这是通过 `EXO_LIBP2P_NAMESPACE` 设置配置的：
- **使用场景**：
- 在同一网络上运行多个独立的 exo 集群
- 将开发/测试集群与生产集群隔离
- 防止意外加入集群
- **配置**：在 App 的高级设置中访问此设置（或在从源码运行时设置 `EXO_LIBP2P_NAMESPACE` 环境变量）
该 namespace 会在启动时记录以供调试。
#### 卸载 macOS App
推荐的卸载方式是通过 App 本身：点击菜单栏图标 → Advanced → Uninstall。这将干净地移除所有系统组件。
如果你已经删除了 App，可以运行独立的卸载脚本：
```
sudo ./app/EXO/uninstall-exo.sh
```
这将移除：
- 网络设置 LaunchDaemon
- 网络配置脚本
- 日志文件
- “exo” 网络位置
**注意：** 你需要在“系统设置” → “通用” → “登录项”中手动移除 EXO。
### 在 macOS 上启用 RDMA
RDMA 是 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. 选择“Options”进入恢复模式。
4. 当恢复界面出现时，从 Utilities 菜单中打开 Terminal。
5. 在 Terminal 中输入：
rdma_ctl enable
并按 Enter。
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. 不同版本的 MacOS 上的 RDMA 端口可能无法互相发现。请确保所有设备上的 OS 版本完全一致（即使是 beta 版本号）。
## 环境变量
exo 支持多个用于配置的环境变量：
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `EXO_MODELS_PATH` | 搜索预下载模型的路径（以冒号分隔）（例如，在 NFS 挂载或共享存储上） | None |
| `EXO_MODELS_DIR` | exo 下载和存储模型的目录 | `~/.local/share/exo/models` (Linux) 或 `~/.exo/models` (macOS) |
| `EXO_OFFLINE` | 在无互联网连接下运行（仅使用本地模型） | `false` |
| `EXO_ENABLE_IMAGE_MODELS` | 启用图像模型支持 | `false` |
| `EXO_LIBP2P_NAMESPACE` | 用于集群隔离的自定义 namespace | None |
| `EXO_FAST_SYNCH` | 控制 MLX_METAL_FAST_SYNCH 行为（用于 JACCL 后端） | Auto |
| `EXO_TRACING_ENABLED` | 启用分布式追踪以进行性能分析 | `false` |
**示例用法：**
```
# 使用来自 NFS 挂载的预下载 models
EXO_MODELS_PATH=/mnt/nfs/models:/opt/ai-models uv run exo
# 在离线模式下运行
EXO_OFFLINE=true uv run exo
# 启用图像模型
EXO_ENABLE_IMAGE_MODELS=true uv run exo
# 使用自定义 namespace 进行集群隔离
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
}
// ...possibly more placements...
]
}
```
这将返回此模型的所有有效部署位置。选择一个你喜欢的位置。
要选择第一个，可以通过管道传给 `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` 字段中填入你想要的部署位置（完整的 payload 类型必须与 `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
}'
# 列出 models (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](docs/api.md) 中的 API 文档。
- [src/exo/master/api.py](src/exo/master/api.py) 中的 API 类型和端点。
## 性能测试
`exo-bench` 工具用于测量不同部署配置下的模型预填充和 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 数、每秒生成 token 数 以及每种配置的峰值内存使用量。
## 硬件加速器支持
在 macOS 上，exo 使用 GPU。在 Linux 上，exo 目前运行于 CPU。我们正在努力扩展硬件加速器支持。如果你希望支持新的硬件平台，请[搜索现有的功能请求](https://github.com/exo-explore/exo/issues)并点赞，以便我们了解社区关注哪些硬件。
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何为 exo 做贡献的指南。标签：AI集群, Apache-2.0, Apex, Apple Silicon, MacOS, MITM代理, MLX, Python, RDMA, Thunderbolt, XML注入, 人工智能, 分布式推理, 分布式计算, 可视化界面, 大模型推理, 开源, 异常处理, 张量并行, 无后门, 本地AI, 机器学习, 模型分片, 流量捕获, 用户模式Hook绕过, 网络拓扑, 设备发现, 资源调度, 边缘计算, 逆向工具, 高性能计算