raullenchai/Rapid-MLX
GitHub: raullenchai/Rapid-MLX
专为 Apple Silicon 深度优化的本地 AI 推理引擎，提供 OpenAI 兼容 API，支持主流编程助手和 Agent 框架直接接入，无需云端即可高速运行大语言模型。
Stars: 2017 | Forks: 257
Rapid-MLX
在你的 Mac 上运行 AI。比任何其他方案都更快。
在你的 Mac 上本地运行 AI 模型 —— 无需云服务，无 API 费用。兼容 Cursor、Claude Code 以及任何 OpenAI 兼容的应用。
pip install → serve Gemma 4 26B → chat + tool calling → works with PydanticAI, LangChain, Aider, and more.
| | 你的 Mac | 模型 | 速度 (tok/s = 词/秒) | 适用场景 |
|:---|:---:|:---:|:---:|:---:|
| **16 GB** MacBook Air | Qwen3.5-4B | 160 tok/s | 聊天、编程、工具 |
| **32+ GB** Mac Mini / Studio | Nemotron-Nano 30B | 141 tok/s | 🆕 最快的 30B，100% 工具支持 |
| **32+ GB** Mac Mini / Studio | Qwen3.6-35B | 95 tok/s | 256 专家，262K 上下文 |
| **64 GB** Mac Mini / Studio | Qwen3.5-35B | 83 tok/s | 智能与速度的最佳平衡 |
| **96+ GB** Mac Studio / Pro | Qwen3.5-122B | 57 tok/s | 前沿级别的智能 |
| **128+ GB** Mac Studio Ultra | 🆕 DeepSeek V4 Flash 158B-A13B | 31-56 tok/s | Day-0 前沿 MoE，1M 上下文 |
本地 AI 新手？快速术语表
- **tok/s** (每秒 token 数) —— 大致相当于 AI 每秒生成的单词数。越高越快。
- **4bit / 8bit** —— 模型的压缩级别。4bit 使用更少内存（推荐）；8bit 质量更高。
- **TTFT** (首个 token 的时间) —— AI 开始回复前的等待时间。
- **Tool calling (工具调用)** —— AI 可以调用你代码中的函数。被 Cursor、Claude Code 和编程助手广泛使用。
- **OpenAI API 兼容** —— Rapid-MLX 使用与 ChatGPT API 相同的语言，因此任何兼容 ChatGPT 的应用只需更改服务器地址即可与 Rapid-MLX 配合使用。
- **Ollama / llama.cpp** —— 其他流行的本地 AI 运行工具。Rapid-MLX 在 Apple Silicon 上的速度快了 2-4 倍。
## 快速入门
**步骤 1 —— 安装** (选择其中一种方式):
```
# Homebrew（推荐 — 开箱即用，无 Python 版本问题）
brew install raullenchai/rapid-mlx/rapid-mlx
# pip（需要 Python 3.10+ — macOS 自带 3.9，如有需要请先安装 Python）
pip install rapid-mlx
# 或使用一键命令自动设置（如需要会安装 Python）
curl -fsSL https://raullenchai.github.io/Rapid-MLX/install.sh | bash
```
**步骤 2 —— 启动模型服务:**
```
rapid-mlx serve qwen3.5-4b
```
首次运行会下载模型 (~2.5 GB) —— 你会看到一个进度条。请等待出现 `Ready: http://localhost:8000/v1`。
**步骤 3 —— 聊天** (打开**第二个**终端标签页):
```
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"default","messages":[{"role":"user","content":"Say hello"}]}'
```
完成 —— 你现在已经在 `localhost:8000` 上运行了一个兼容 OpenAI 的 AI 服务器。将任何应用指向 `http://localhost:8000/v1` 即可直接使用。
更多安装选项
**从源码安装** (用于开发):
```
git clone https://github.com/raullenchai/Rapid-MLX.git
cd Rapid-MLX && pip install -e .
```
**视觉模型** (会增加 torch + torchvision，额外约 2.5 GB):
```
pip install 'rapid-mlx[vision]'
```
**音频** (通过 mlx-audio 实现 TTS/STT):
```
pip install 'rapid-mlx[audio]'
```
**使用 Python 尝试** (确保服务器正在运行，然后执行 `pip install openai`):
```
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed") # any value works, no real key needed
response = client.chat.completions.create(
model="default",
messages=[{"role": "user", "content": "Say hello"}],
)
print(response.choices[0].message.content)
```
## 兼容工具
### Agent 框架 (经 MHI 测试)
| 框架 | 类型 | 备注 |
|---------|------|-------|
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Agent | 62 个工具，多轮对话 ([测试](tests/integrations/test_hermes.py)) |
| [PydanticAI](https://ai.pydantic.dev) | 框架 | 类型化 agent，结构化输出 ([测试](tests/integrations/test_pydantic_ai_full.py)) |
| [LangChain](https://langchain.com) | 框架 | `ChatOpenAI`，工具，流式传输 ([测试](tests/integrations/test_langchain.py)) |
| [smolagents](https://github.com/huggingface/smolagents) | 框架 | CodeAgent + ToolCallingAgent ([测试](tests/integrations/test_smolagents_full.py)) |
| [OpenClaude](https://github.com/Gitlawb/openclaude) (Anthropic SDK) | Agent | `CLAUDE_CODE_USE_OPENAI=1` ([测试](tests/integrations/test_anthropic_sdk.py)) |
| [Aider](https://aider.chat) | Agent | 命令行编辑并提交，架构师模式 ([测试](tests/integrations/test_aider.sh)) |
| [Goose](https://github.com/block/goose) | Agent | 通过 `OLLAMA_HOST` 使用 Ollama 提供者 |
| [OpenCode](https://github.com/sst/opencode) | TUI Agent | 类似 Claude Code 的终端体验，兼容 OpenAI 提供者 |
| [Claw Code](https://github.com/ultraworkers/claw-code) | Agent | OpenAI 与 Anthropic 端点 |
### UI / IDE 客户端
| 客户端 | 状态 | 设置方式 |
|--------|--------|-------|
| [Cursor](https://cursor.com) | 兼容 | 设置 → OpenAI Base URL |
| [Continue.dev](https://continue.dev) | 兼容 | VS Code / JetBrains 插件 |
| [LibreChat](https://librechat.ai) | 已测试 | Docker ([测试](tests/integrations/test_librechat_docker.py)) |
| [Open WebUI](https://github.com/open-webui/open-webui) | 已测试 | Docker ([测试](tests/integrations/test_openwebui.py)) |
| 任何 OpenAI 兼容应用 | 兼容 | 指向 `http://localhost:8000/v1` |
### 模型-框架指数 (MHI)
MHI 用于衡量模型与特定 agent 框架协同工作的效果。它综合了三个维度:
| 维度 | 权重 | 衡量内容 | 来源 |
|---|---|---|---|
| **Tool Calling (工具调用)** | 50% | 模型+框架能否正确执行函数调用？ | `rapid-mlx agents --test` |
| **HumanEval** | 30% | 模型能否生成正确的代码？ | [HumanEval](https://github.com/openai/human-eval) (10 项任务) |
| **MMLU** | 20% | 框架是否会降低基础能力？ | [tinyMMLU](https://huggingface.co/datasets/tinyBenchmarks/tinyMMLU) (10 项任务) |
**MHI = 0.50 × ToolCalling + 0.30 × HumanEval + 0.20 × MMLU** (0-100 分制)
| 模型 | 最佳 MHI | 最佳框架 | Tool Calling |
|---|---|---|---|
| **Qwopus 27B** | **92** | 全部 (Hermes, PydanticAI, LangChain, smolagents) | 100% |
| **Qwen3.5 27B** | **82** | Hermes / PydanticAI / LangChain | 100% |
| **Llama 3.3 70B** | **83** | smolagents (基于文本) | 100% |
| **Nemotron Nano 30B** | **59** | PydanticAI / LangChain | 91-93% |
| **Gemma 4 26B** | **62** | Hermes / smolagents | 100% |
完整 MHI 表 (25 种模型-框架组合) + 方法论
**MHI = 0.50 × ToolCalling + 0.30 × HumanEval + 0.20 × MMLU** (0-100 分制)
运行 `rapid-mlx agents` 查看所有支持的 agent，运行 `python3 scripts/mhi_eval.py` 在你自己的配置下计算 MHI。
| 模型 + 框架 | Tool Calling | HumanEval | MMLU | **MHI** |
|---|---|---|---|---|
| **Qwopus 27B** + Hermes | 100% | 80% | 90% | **92** |
| **Qwopus 27B** + PydanticAI | 100% | 80% | 90% | **92** |
| **Qwen3.5 27B** + Hermes | 100% | 40% | 100% | **82** |
| **Llama 3.3 70B** + smolagents | 100% | 50% | 90% | **83** |
| **DeepSeek-R1 32B** + smolagents | 100% | 30% | 100% | **79** |
| **Gemma 4 26B** + Hermes | 100% | 0% | 60% | **62** |
| **Nemotron Nano 30B** + PydanticAI | 93% | 0% | 60% | **59** |
**常用应用快速设置:**
**Cursor:** 设置 → 模型 → 添加模型:
```
OpenAI API Base: http://localhost:8000/v1
API Key: not-needed
Model name: default (or qwen3.5-9b — either works)
```
Cursor 的 agent/composer 模式会自动使用工具调用 —— Rapid-MLX 结合 Qwen3.5 模型原生支持这些调用，无需额外标志。
**Claw Code:**
```
export OPENAI_BASE_URL=http://localhost:8000/v1
export OPENAI_API_KEY=not-needed
claw --model "openai/default" prompt "summarize this repo"
```
**OpenClaude:**
```
CLAUDE_CODE_USE_OPENAI=1 OPENAI_BASE_URL=http://localhost:8000/v1 \
OPENAI_API_KEY=not-needed OPENAI_MODEL=default openclaude -p "hello"
```
**Hermes Agent** (`~/.hermes/config.yaml`):
```
model:
provider: "custom"
default: "default"
base_url: "http://localhost:8000/v1"
context_length: 32768
```
**Goose:**
```
GOOSE_PROVIDER=ollama OLLAMA_HOST=http://localhost:8000 \
GOOSE_MODEL=default goose run --text "hello"
```
**Claude Code:**
```
OPENAI_BASE_URL=http://localhost:8000/v1 claude
```
更多客户端设置指南
**Continue.dev** (`~/.continue/config.yaml`):
```
models:
- name: rapid-mlx
provider: openai
model: default
apiBase: http://localhost:8000/v1
apiKey: not-needed
```
**Aider:**
```
aider --openai-api-base http://localhost:8000/v1 --openai-api-key not-needed
```
**Swival** (`~/.swival/config.toml`):
```
[profiles.rapidmlx]
provider = "generic"
base_url = "http://127.0.0.1:8000"
model = "default"
```
运行命令:
```
swival --profile rapidmlx "summarize this repo"
```
**Open WebUI** (Docker 一行命令):
```
docker run -d -p 3000:8080 \
--add-host=host.docker.internal:host-gateway \
-e ENABLE_OLLAMA_API=False \
-e OPENAI_API_BASE_URL=http://host.docker.internal:8000/v1 \
-e OPENAI_API_KEY=not-needed \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
```
**OpenCode** (项目根目录下的 `opencode.json`):
```
{
"provider": {
"openai": {
"api": "http://localhost:8000/v1",
"models": {
"default": {
"name": "rapid-mlx local",
"limit": { "context": 32768, "output": 8192 }
}
},
"options": { "apiKey": "not-needed" }
}
}
}
```
**PydanticAI** (`pip install pydantic-ai`):
```
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
model = OpenAIChatModel(
model_name="default",
provider=OpenAIProvider(
base_url="http://localhost:8000/v1",
api_key="not-needed",
),
)
agent = Agent(model)
print(agent.run_sync("What is 2+2?").output)
```
**smolagents** (`pip install smolagents`):
```
from smolagents import CodeAgent, OpenAIServerModel
model = OpenAIServerModel(
model_id="default",
api_base="http://localhost:8000/v1",
api_key="not-needed",
)
agent = CodeAgent(tools=[], model=model)
agent.run("What is 5 multiplied by 7?")
```
**LibreChat** (`librechat.yaml` 中的 `endpoints.custom`):
```
- name: "Rapid-MLX"
apiKey: "rapid-mlx"
baseURL: "http://localhost:8000/v1/"
models:
default: ["default"]
fetch: true
titleConvo: true
titleModel: "current_model"
modelDisplayLabel: "Rapid-MLX"
```
**Anthropic SDK** (`pip install anthropic`):
```
from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:8000", api_key="not-needed")
message = client.messages.create(
model="default",
max_tokens=1024,
messages=[{"role": "user", "content": "Say hello"}],
)
print(message.content[0].text)
```
## 选择你的模型
### 哪款适合我的 Mac？
模型必须能装进你 Mac 的内存中。如果你的 Mac 变慢或活动监视器显示内存压力为红色，请从下表中选择更小的模型。
| 你的 Mac | 最佳模型 | 占用内存 | 速度 | 质量 |
|----------|-----------|---------|-------|---------|
| **16 GB** MacBook Air/Pro | [Qwen3.5-4B 4bit](https://huggingface.co/mlx-community/Qwen3.5-4B-MLX-4bit) | 2.4 GB | 160 tok/s | 适合聊天和简单任务 |
| **24 GB** MacBook Pro | [Qwen3.5-9B 4bit](https://huggingface.co/mlx-community/Qwen3.5-9B-4bit) | 5.1 GB | 108 tok/s | 优秀的全能选手 |
| **32 GB** Mac Mini / Studio | [Qwen3.5-27B 4bit](https://huggingface.co/mlx-community/Qwen3.5-27B-4bit) | 15.3 GB | 39 tok/s | 稳健的编程模型 |
| **32 GB** Mac Mini / Studio | 🆕 [Nemotron-Nano 30B 4bit](https://huggingface.co/lmstudio-community/NVIDIA-Nemotron-3-Nano-30B-A3B-MLX-4bit) | 18 GB | 141 tok/s | 最快的 30B，100% 工具调用 |
| **32 GB** Mac Mini / Studio | [Qwen3.6-35B-A3B 4bit](https://huggingface.co/mlx-community/Qwen3.6-35B-A3B-4bit) | 20 GB | 95 tok/s | 256 MoE 专家，262K 上下文 |
| **36 GB** MacBook Pro M3/M4 Pro | [Qwen3.5-27B 4bit](https://huggingface.co/mlx-community/Qwen3.5-27B-4bit) | 15.3 GB | 39 tok/s | 与 32 GB 相同 —— 为长上下文留出更多余量 |
| **48 GB** Mac Mini / Studio | [Qwen3.5-35B-A3B 8bit](https://huggingface.co/mlx-community/Qwen3.5-35B-A3B-8bit) | 37 GB | 83 tok/s | **最佳甜点** —— 智能 + 快速 |
| **64 GB** Mac Mini / Studio | [Qwen3.5-35B-A3B 8bit](https://huggingface.co/mlx-community/Qwen3.5-35B-A3B-8bit) | 37 GB | 83 tok/s | 同款模型，为 KV 缓存留出更多空间 |
| **96 GB** Mac Studio / Pro | [Qwen3.5-122B mxfp4](https://huggingface.co/nightmedia/Qwen3.5-122B-A10B-Text-mxfp4-mlx) | 65 GB | 57 tok/s | 最佳模型，轻松容纳 |
| **128 GB** Mac Studio / Pro | 🆕 [DeepSeek V4 Flash 2-bit DQ](https://huggingface.co/mlx-community/DeepSeek-V4-Flash-2bit-DQ) 91 GB | 56 tok/s | 158B-A13B 前沿 MoE，day-0 (仅聊天) |
| **192 GB** Mac Studio / Pro | [Qwen3.5-122B 8bit](https://huggingface.co/mlx-community/Qwen3.5-122B-A10B-8bit) | 130 GB | 44 tok/s | 最高质量 |
| **256 GB** Mac Studio Ultra | 🆕 [DeepSeek V4 Flash 8-bit](https://huggingface.co/mlx-community/DeepSeek-V4-Flash-8bit) | 136 GB | 31 tok/s | 158B-A13B 前沿 MoE，1M 上下文 (仅聊天) |
### 复制粘贴命令
选择与你 Mac 匹配的配置。支持简短的别名 —— 运行 `rapid-mlx models` 查看所有可用模型。
```
# 16 GB — 轻量、快速
rapid-mlx serve qwen3.5-4b --port 8000
# 24 GB — 最佳小模型
rapid-mlx serve qwen3.5-9b --port 8000
# 32 GB — 强大的 Coding 模型
rapid-mlx serve qwen3.5-27b --port 8000
# 32 GB — Nemotron Nano（最快的 30B，141 tok/s，NVIDIA MoE）
rapid-mlx serve nemotron-30b --port 8000
# 32+ GB — Qwen 3.6（256 experts，262K context）
rapid-mlx serve qwen3.6-35b --port 8000
# 64 GB — 甜点位
rapid-mlx serve qwen3.5-35b --prefill-step-size 8192 --port 8000 # faster first response
# 96+ GB — 最佳模型
rapid-mlx serve qwen3.5-122b --prefill-step-size 8192 --port 8000
# Coding agent — 快速 MoE，非常适合 Claude Code / Cursor
rapid-mlx serve qwen3-coder --prefill-step-size 8192 --port 8000 # MoE = only uses part of the model, so it's fast
# Vision — 图像理解（见下方注释）
rapid-mlx serve qwen3-vl-4b --mllm --port 8000
```
解析器自动检测与手动覆盖
解析器会**从模型名称中自动检测** —— 你无需为支持的模型系列指定 `--tool-call-parser` 或 `--reasoning-parser`。显式标志始终会覆盖自动检测。
| 模型系列 | 自动检测的 `--tool-call-parser` | 自动检测的 `--reasoning-parser` | 备注 |
|-------------|---------------------|---------------------|-------|
| Qwen3.5 (所有大小) | `hermes` | `qwen3` | **推荐** —— 100% 工具调用 |
| 🆕 Qwen3.6 | `qwen3_coder_xml` | `qwen3` | XML 工具格式，262K 上下文 |
| Qwen3-Coder-Next | `hermes` | *(无)* | 快速编程，非思考模式 |
| DeepSeek R1-0528 / V3.1 | `deepseek_v31` | `deepseek_r1` | 专用 V3.1 解析器 |
| DeepSeek R1 (旧版) | `deepseek` | `deepseek_r1` | 带推理功能 |
| DeepSeek V3 / V2.5 | `deepseek` | *(无)* | 无推理解析器 |
| GLM-4.7 | `glm47` | *(无)* | 100% 工具调用 |
| MiniMax-M2.5 | `minimax` | `minimax` | XML 工具格式 |
| GPT-OSS | `harmony` | `harmony` | 原生格式 |
| Kimi-Linear | `kimi` | *(无)* | Kimi 工具格式 |
| Llama 3.x | `llama` | *(无)* | JSON 工具格式 |
| Mistral / Devstral | `hermes` | *(无)* | 兼容 Hermes |
| Gemma | `hermes` | *(无)* | 兼容 Hermes |
| Phi-3/4 | `hermes` | *(无)* | 兼容 Hermes |
全部 17 种解析器均包含自动恢复功能 —— 如果量化模型输出了格式错误的文本工具调用，它们会被自动转换回结构化格式。
## 基准测试
在 **Mac Studio M3 Ultra (256GB)** 上测试。Rapid-MLX 使用 Apple 的 [MLX 框架](https://github.com/ml-explore/mlx) —— 专为统一内存构建并带有原生 Metal 计算内核 —— 这就是为什么它在大多数模型上能击败基于 C++ 的引擎 (Ollama, llama.cpp)。Ollama 的数据测试自 **v0.20.4** (最新版，带有 MLX 后端)。
| 模型 | Rapid-MLX | 最佳替代方案 | 加速比 |
|-------|----------|-----------------|---------|
| **Phi-4 Mini 14B** | **180** tok/s | 77 (mlx-lm) / 56 (Ollama) | **2.3x** / **3.2x** |
| **Qwen3.5-4B** | **160** tok/s | 155 (mlx-lm serve) | **1.0x** |
| **Nemotron-Nano 30B** | **141** tok/s · 100% 工具支持 | — | — |
| 🆕 **DeepSeek V4 Flash 158B-A13B** (2-bit DQ) | **56** tok/s | — (唯一的 MLX 引擎，day-0) | — |
| 🆕 **DeepSeek V4 Flash 158B-A13B** (8-bit) | **31** tok/s | — (唯一的 MLX 引擎，day-0) | — |
| **GPT-OSS 20B** | **127** tok/s · 100% 工具支持 | 79 (mlx-lm serve) | **1.6x** |
| **Qwen3.5-9B** | **108** tok/s | 41 (Ollama) | **2.6x** |
| **Qwen3.6-35B-A3B** | **95** tok/s · 100% 工具支持 | — | — |
| **Kimi-Linear-48B** | **94** tok/s · 100% 工具支持 | — (唯一引擎) | — |
| **Gemma 4 26B-A4B** | **85** tok/s | 68 (Ollama) | **1.3x** |
| **Gemma 4 E4B** | **83** tok/s | — | — |
| **Qwen3.5-35B-A3B** | **83** tok/s · 100% 工具支持 | 75 (oMLX) | **1.1x** |
| **Qwen3-Coder 80B** | **74** tok/s · 100% 工具支持 | 69 (mlx-lm serve) | **1.1x** |
| **Qwen3.5-122B** | **44** tok/s · 100% 工具支持 | 43 (mlx-lm serve) | ~1.0x |
| **Gemma 4 31B** | **31** tok/s | — | — |
*包含所有模型、TTFT 表格、DeltaNet 快照和引擎对比的完整基准数据见下方。*
TTFT —— Prompt Cache 优势
Prompt cache 能让多轮对话保持快速。对于标准 transformer，KV cache 裁剪可以实现低于 100ms 的 TTFT。对于混合 RNN 模型 (Qwen3.5 DeltaNet)，我们使用状态快照 —— 这是首项在 MLX 上为不可裁剪架构引入 prompt cache 的技术。
**纯 KV cache (transformer):**
| 模型 | Rapid-MLX (已缓存) | mlx-lm serve | 加速比 |
|-------|-------------------|-------------------|---------|
| Kimi-Linear-48B | **0.08s** | — | — |
| Llama 3.2 3B | **0.10s** | — | — |
| Hermes-3-Llama 8B | **0.10s** | 0.18s | 1.8x |
| Phi-4 Mini 14B | **0.13s** | 0.15s | 1.2x |
| Devstral-Small-2 24B | **0.13s** | 0.38s | 2.9x |
| Mistral Small 24B | **0.13s** | 0.38s | 2.9x |
| GLM-4.7-Flash 9B | **0.13s** | 0.23s | 1.8x |
| GLM-4.5-Air | **0.14s** | 0.47s | 3.4x |
| Qwen3-Coder-Next 80B | **0.16s** | 0.27s | 1.7x |
| GPT-OSS 20B | **0.16s** | 0.27s | 1.7x |
| Qwen3.5-9B | **0.22s** | 0.26s | 1.2x |
| Gemma 4 E4B | **0.25s** | — (day-0) | — |
| Gemma 4 26B-A4B | **0.25s** | — (day-0) | — |
| Gemma 4 31B | **0.34s** | 0.57s (mlx-vlm bf16) | **1.7x** |
**DeltaNet 状态快照 (混合 RNN + 注意力):**
Qwen3.5 使用 Gated DeltaNet (75% RNN) + 全注意力 (25% KV)。其他引擎在每次请求时都会从头重建整个缓存 —— 我们在系统 prompt 边界处对 RNN 状态进行快照，在大约 0.1ms 内恢复，而不是重新通过循环层运行数百个 token。
| 模型 | 冷启动 TTFT | 快照 TTFT | 加速比 |
|-------|-----------|---------------|---------|
| Qwen3-Coder-Next 6bit (48L) | 0.66s | **0.16s** | **4.3x** |
| Qwen3.5-35B-A3B 8bit (40L) | 0.49s | **0.19s** | **2.6x** |
| Qwen3.5-27B 4bit (40L) | 0.58s | **0.27s** | **2.1x** |
| Qwen3.5-9B 4bit (40L) | 0.27s | **0.22s** | **1.2x** |
| Qwen3.5-4B 4bit (32L) | 0.24s | **0.16s** | **1.5x** |
功能对比
| 功能 | Rapid-MLX | oMLX | Ollama | llama.cpp | mlx-lm serve |
|---------|-----------|------|--------|-----------|-------------|
| **Tool calling** | 100% (Qwen/GLM/GPT-OSS/Kimi) | N/A | 100% (Qwen) | 80% (Phi-4) | N/A |
| **工具调用恢复** | 100% | N/A | 100% | 100% | N/A |
| **工具注入回退** | 是 | 否 | 否 | 否 | 否 |
| **思考标签泄漏** | 0% | N/A | 0% | 0% | N/A |
| **Prompt cache** | KV + DeltaNet | 否 | 否 | 否 | 否 |
| **视觉** | 是 | 是 | 是 | 否 | 否 |
| **音频 (STT/TTS)** | 是 | 否 | 否 | 否 | 否 |
| **17 种工具解析器** | 是 | 否 | 否 | 否 | 否 |
| **云端路由** | 是 | 否 | 否 | 否 | 否 |
| **流式传输** | 是 | 是 | 是 | 是 | 是 |
| **OpenAI API** | 是 | 是 | 是 | 是 | 是 |
各模型优化技术
| 技术 | 作用 | 适用模型 |
|-----------|-------------|--------|
| **KV prompt cache** | 将 KV cache 裁剪至公共前缀，跳过重新预填充 | 所有 transformer 模型 |
| **DeltaNet 状态快照** | 在前缀边界深度复制 RNN 状态，在约 0.1ms 内恢复 | Qwen3.5 (4B, 9B, 27B, 35B, 122B), Qwen3-Coder-Next |
| **混合缓存同步** | 保持可裁剪的 KV + 不可裁剪的 RNN 层同步 | Qwen3.5 (Gated DeltaNet + 注意力) |
| **工具 logits 偏置** | 跳跃式解码 —— 将 logits 偏向结构化 token | 所有使用 `--enable-tool-logits-bias` 的模型 |
| **自动工具恢复** | 检测格式错误的文本工具调用，转换为结构化格式 | 所有 18 种解析器格式 (包括 Gemma 4) |
| **TurboQuant V 缓存** | 旋转 + Lloyd-Max 压缩 V 缓存 (在密集模型上节省 86%) | 所有使用 `--kv-cache-turboquant` 的模型 |
| **KV cache 量化** | 量化前缀缓存条目以减少内存 | 所有使用 `--kv-cache-quantization` 的模型 |
| **预填充分块** | 可配置的步长，用于大吞吐量的长 prompt | 所有模型 |
| **云端路由** | 当本地速度慢时，将高 token 请求卸载到云端 LLM | 所有使用 `--cloud-model` 的模型 |
评估基准 (20 个模型，4 套测试)
工具调用 (30 个场景)、编程 (HumanEval+)、推理 (MATH500)、通用知识 (MMLU-Pro)。顶级模型:
| 模型 | 解码 | 工具 | 编程 | 推理 | 通用 | 平均 |
|-------|--------|-------|------|--------|---------|-----|
| Qwen3.5-122B 8bit | 44 t/s | 87% | 90% | 90% | 90% | **89%** |
| Qwen3.5-35B 8bit | 83 t/s | 90% | 90% | 80% | 80% | **85%** |
| Qwen3-Coder-Next 4bit | 74 t/s | 90% | 90% | 70% | 70% | **80%** |
| Qwen3.5-27B 4bit | 39 t/s | 83% | 90% | 50% | 80% | **76%** |
| Qwen3.5-9B 4bit | 108 t/s | 83% | 70% | 60% | 70% | **71%** |
运行你自己的测试: `python scripts/benchmark_engines.py --engine rapid-mlx ollama --runs 3`
## 功能
### Tool Calling
完全兼容 OpenAI 的 tool calling，支持 17 种解析器格式，并在**量化模型出错时提供自动恢复功能**。处于 4-bit 的模型在多轮工具调用后性能会下降 —— Rapid-MLX 会自动检测格式错误的输出，并将其重新转换为结构化的 `tool_calls`。
### 推理分离
带有思维链的模型 (Qwen3, DeepSeek-R1) 会在单独的 `reasoning_content` 字段中输出推理过程 —— 在流式模式下与 `content` 完全分离。支持 Qwen3、DeepSeek-R1、MiniMax 和 GPT-OSS 推理格式。
### Prompt Cache
跨请求的持久缓存 —— 每轮只对新 token 进行预填充。对于标准 transformer，采用 KV cache 裁剪。对于混合模型 (Qwen3.5 DeltaNet)，RNN 状态快照从内存中恢复不可裁剪的层，而不是重新计算。所有架构上的 TTFT 均加快了 2-5 倍。默认开启，无需任何标志。
### 智能云端路由
当本地预填充缓慢时，大上下文请求会自动路由到云端 LLM (GPT-5, Claude 等)。路由基于缓存命中后的新 token 数量决定。`--cloud-model openai/gpt-5 --cloud-threshold 20000`
### 多模态
视觉、音频 (STT/TTS)、视频理解和文本嵌入 —— 全部通过同一个兼容 OpenAI 的 API 提供。
此外还有: logprobs API、结构化 JSON 输出 (`response_format`)、连续批处理、KV cache 量化 (`--kv-cache-quantization`) 以及 [2100+ 项测试](tests/)。
服务器标志参考
### 核心
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `` | HuggingFace 模型名称、本地路径或别名 (位置参数) | *(必填)* |
| `--host` | 绑定的主机 | `0.0.0.0` |
| `--port` | 绑定的端口 | `8000` |
| `--max-tokens` | 生成的默认最大 token 数 | `32768` |
### 工具调用与推理
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `--tool-call-parser` | 解析器: `hermes`, `minimax`, `qwen`, `llama`, `deepseek` 等 | *(自动检测)* |
| `--reasoning-parser` | 解析器: `qwen3`, `deepseek_r1`, `minimax`, `gpt_oss` | *(自动检测)* |
| `--enable-tool-logits-bias` | 用于加速工具调用的跳跃式解码 | 关闭 |
### 性能
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `--prefill-step-size` | 每次预填充的 token 块大小 | `2048` |
| `--kv-cache-turboquant` | TurboQuant V 缓存压缩 (3-4 bit，在密集模型上节省 86%) | 关闭 |
| `--kv-cache-quantization` | 量化前缀缓存条目以节省内存 | 关闭 |
| `--enable-prefix-cache` | 跨请求缓存公共前缀 | 关闭 |
| `--gpu-memory-utilization` | 使用的设备内存比例 (0.0-1.0) | `0.90` |
### 云端路由
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `--cloud-model` | litellm 模型字符串 (例如 `openai/gpt-5`) | *(禁用)* |
| `--cloud-threshold` | 触发云端路由的新 token 阈值 | `20000` |
### 安全与其他
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `--api-key` | 用于身份验证的 API 密钥 | *(无身份验证)* |
| `--rate-limit` | 每个客户端每分钟的请求数 | *(无限制)* |
| `--timeout` | 请求超时时间 (秒) | `300` |
| `--mllm` | 强制使用多模态 (视觉) 模式 | 自动检测 |
| `--mcp-config` | 用于工具集成的 MCP 配置文件 | *(无)* |
| `--embedding-model` | 启动时预加载嵌入模型 | *(无)* |
常见问题
**启动时出现“parameters not found in model”警告** —— 对于 VLM 来说是正常现象。视觉权重会被自动跳过。
**内存不足或极慢 (<5 tok/s)** —— 模型过大。查看[哪款适合我的 Mac？](#what-fits-my-mac) 尝试更小的量化版本 (4bit) 或更小的模型。
**空响应** —— 对于非思考模型，请移除 `--reasoning-parser`。
**工具调用以纯文本形式输出** —— 为你的模型设置正确的 `--tool-call-parser`。即使没有设置，Rapid-MLX 也能自动恢复大多数情况。
**其他问题？** 运行 `rapid-mlx doctor` 进行自检。
**首次响应慢** —— 两种不同原因: (1) Qwen3.5 模型在回答前会进行推理 —— 添加 `--no-thinking` 以跳过推理获取更快的响应，或 (2) 长 prompt 的冷启动 —— 添加 `--prefill-step-size 8192` 以加速处理。后续的对话轮次会命中 prompt cache，速度会快 10-30 倍。
**客户端断开后服务器挂起** —— 已在 v0.3.0+ 版本中修复。请升级到最新版。
## 可选附加组件
基础的 `pip install rapid-mlx` 约为 460 MB，涵盖所有纯文本模型。视觉、音频及其他功能作为可选附加组件提供:
| 附加组件 | 安装命令 | 增加体积 | 解锁功能 |
|---|---|---|---|
| `vision` | `pip install 'rapid-mlx[vision]'` | ~322 MB | Gemma 4, Qwen-VL, 视频理解 (mlx-vlm + opencv + torch) |
| `audio` | `pip install 'rapid-mlx[audio]'` | ~600 MB | TTS / STT (mlx-audio + spacy + scipy) |
| `embeddings` | `pip install 'rapid-mlx[embeddings]'` | ~50 MB | `/v1/embeddings` 端点 (mlx-embeddings) |
| `chat` | `pip install 'rapid-mlx[chat]'` | ~150 MB | 内置 Gradio 聊天 UI |
| `guided` | `pip install 'rapid-mlx[guided]'` | ~80 MB | Schema 约束的 JSON 生成 |
| `all` | `pip install 'rapid-mlx[all]'` | ~1.1 GB | 视觉 + 音频 + 聊天 + 嵌入 |
如果你是通过 Homebrew 安装的并需要视觉/音频支持，请在你自己的 Python 3.10+ venv 中使用 `pip install 'rapid-mlx[vision]'` (或 `[audio]`) —— 这能为你提供完整的功能集，而无需重新构建 brew formula。
## 故障排除
运行内置的自检程序 (通过 `pip install` 即可使用，无需开发工具):
```
rapid-mlx doctor
```
```
Rapid-MLX Doctor
============================================================
[metal] OK # Apple Silicon Metal GPU available
[imports] OK # Core modules import cleanly
[cli] OK # CLI commands respond
[model_load] OK # Inference pipeline works
Result: PASS
```
## 开发
### 快速开始
```
git clone https://github.com/raullenchai/Rapid-MLX.git
cd Rapid-MLX
pip install -e ".[dev]"
```
### 测试
分为两层: **面向用户的诊断工具** (随 pip 附带) 和 **开发者测试套件** (仅限源码检出)。
#### 开发者测试命令
| 命令 | 内容 | 耗时 | 需要服务器? |
|---------|------|------|---------------|
| `make lint` | ruff 代码检查 | ~10s | 否 |
| `make test` | pytest 单元套件 (2000+ 测试) | ~30s | 否 |
| `make smoke` | lint + 单元测试 | ~1 min | 否 |
| `make stress` | 8 个场景的压力测试 | ~5 min | 是 |
| `make soak` | 10 分钟 agent 稳定性测试 | 10 min | 是 |
对于压力/稳定性测试，请先启动一个服务器:
```
rapid-mlx serve mlx-community/Qwen3.5-4B-MLX-4bit --enable-auto-tool-choice --tool-call-parser hermes
# 在另一个终端中：
make stress
```
或直接使用脚本以获取更多选项:
```
python scripts/dev_test.py smoke # lint + unit
python scripts/dev_test.py stress --port 8000 # custom port
python scripts/dev_test.py full # everything
```
#### 回归测试套件 (多模型)
```
make check # 1 model (~10 min, auto starts server)
make full # 3 models + 11 agent profiles (~1 hr)
make benchmark # all local models (overnight)
```
### 架构
```
vllm_mlx/
server.py # App factory + model loading + CLI (1047 lines)
config/ # ServerConfig singleton
service/
helpers.py # Shared request helpers
postprocessor.py # Streaming pipeline (100% test coverage)
routes/
chat.py # /v1/chat/completions
completions.py # /v1/completions
anthropic.py # /v1/messages (Anthropic API)
health.py, models.py, embeddings.py, audio.py, mcp_routes.py
engine/ # BatchedEngine (continuous batching)
reasoning/ # 7 reasoning parsers (Qwen3, DeepSeek, MiniMax, ...)
tool_parsers/ # 20+ tool call parsers
agents/ # 11 agent profiles (YAML)
runtime/ # Model registry, cache persistence
doctor/ # User self-diagnostic
scripts/ # Dev-only (NOT shipped with pip)
dev_test.py # Unified test entry point
stress_test.py # 8-scenario stress test
agent_soak_test.py # 10-min agent soak test
cross_model_stress.py # Multi-model validation
tests/ # pytest unit tests (2000+)
harness/ # Regression baselines + thresholds
```
## 路线图
| 技术 | 预期收益 | 状态 |
|-----------|---------------|--------|
| [标准投机解码](https://arxiv.org/abs/2302.01318) —— 草稿模型加速 | 1.5-2.3x 解码 | 未开始 |
| [EAGLE-3](https://arxiv.org/abs/2503.01840) —— Metal 上的特征级草稿 | 3-6.5x 解码 | 未开始 |
| [ReDrafter](https://arxiv.org/abs/2403.09919) —— Apple 的 RNN 草稿头 | 1.4-1.5x 解码 | 未开始 |
## 贡献
我们欢迎任何规模的贡献！详情请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解设置和指南。
**简单的新手贡献** (无需下载模型):
- [添加模型别名](https://github.com/raullenchai/Rapid-MLX/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) —— 将简短名称映射到 HuggingFace 模型 ID
- [请求模型支持](https://github.com/raullenchai/Rapid-MLX/issues/new?template=model_support.yml) —— 告诉我们你需要哪个模型
**测试贡献** (需要配备 Apple Silicon 的 Mac):
- 对模型进行基准测试并分享结果
- 使用你最喜欢的 AI 客户端 (Cursor, Aider, LangChain 等) 进行测试
- [报告错误](https://github.com/raullenchai/Rapid-MLX/issues/new?template=bug_report.yml)
### 贡献者
## Star 历史
## 许可证
Apache 2.0 —— 详见 [LICENSE](LICENSE)。
标签：Agent框架, Aider, AI编程助手, Apple Silicon, Claude Code, Cursor, DLL 劫持, LangChain, LLM推理加速, Mac AI引擎, MacBook, Mac Mini, Mac Studio, MLX, OpenAI替代, Python, 人工智能, 大语言模型, 工具调用, 开源AI, 开源本地大模型, 提示词缓存, 无后门, 本地大模型, 本地大模型部署, 极低延迟, 模型路由, 用户模式Hook绕过, 端侧AI, 轻量级, 边缘计算, 逆向工具