raullenchai/Rapid-MLX · 上手攻略

• 仓库：raullenchai/Rapid-MLX
• 链接：https://github.com/raullenchai/Rapid-MLX
• 分类：ai
• 作者：Tom
• 更新：2026-07-22

是什么

Rapid-MLX 是目前 Apple Silicon 上速度最快的本地 AI 推理引擎，专为 M 系列芯片优化，基于 Apple MLX 框架重写所有核心 kernel，纯 Metal GPU 加速，无任何 llama.cpp 回退或 Python 桥接层。相比同场景的 Ollama，吞吐量提升约 4.2 倍，首 token 时间（TTFT）可低至 0.08 秒（缓存命中）。它同时是一个功能完整的OpenAI API 兼容服务器，让你的现有工具链（Cursor、Aider、Claude Code、LangChain）无需修改即可切换到本地模型。

解决什么问题

1. 本地 AI 推理太慢：Ollama 等通用方案在 Mac 上受限于 Metal 绑定或桥接开销，Rapid-MLX 通过 MLX 原生 kernel 榨干 GPU 带宽。
2. 工具调用可靠性差：默认 17 种 tool-call parser，支持 Qwen、GPT-OSS 等主流模型，100% tool calling 到达率，告别模型输出纯文本 tool 调用的问题。
3. 多模型管理割裂：一个 CLI 管理 128+ 模型别名，按机器 RAM 自动推荐规模，无需手动选型。
4. 云 API 成本高：在 96 GB Mac Studio 上跑 120B 模型，完全免费，且支持 cloud routing 自动将请求分发到本地或云端。

快速安装

推荐：一键脚本（自动检测 RAM + 装 Python）

curl -fsSL https://rapidmlx.com/install.sh | bash

安装脚本会自动： - 检测你的 RAM 大小，选择匹配的默认模型（8–23 GB → qwen3.5-4b-4bit；24–47 GB → gpt-oss-20b-mxfp4-q8；48–95 GB → qwen3.6-35b-8bit；96 GB+ → gpt-oss-120b-mxfp4-q8） - 安装 Python 3.10+（如缺失） - 创建隔离 venv：~/.rapid-mlx/ - 软链 CLI 到 ~/.local/bin/rapid-mlx

⚠️ 安全注意：如不信任 curl | bash，可先下载 release 的 install.sh 资产，用 cosign 验签 SHA256SUMS.txt 后再执行——详见 SECURITY.md。

Homebrew（最简单 macOS 方式）

brew install rapid-mlx
# 升级
brew upgrade rapid-mlx

需要 homebrew-core 已收录（v0.10.12+）。

uv（隔离工具安装）

uv tool install rapid-mlx@latest

pip（需 Python 3.10+，macOS 系统 Python 通常是 3.9，需先 brew install python@3.12）

python3.12 -m pip install rapid-mlx
pip install -U rapid-mlx  # 升级

安装后自检

rapid-mlx doctor

核心用法

1. 终端聊天（即刻体验）

rapid-mlx chat
# 默认模型：qwen3.5-4b-4bit，首次运行自动下载权重（约 2.5 GB）
# 输入 /help 查看斜杠命令，/exit 退出
# --no-think 跳过思维链（Qwen3.5/3.6 默认开启）
rapid-mlx chat qwen3.5-9b-4bit --no-think

2. 启动 OpenAI 兼容 API 服务器

rapid-mlx serve qwen3.5-9b-4bit
# 服务地址：http://localhost:8000/v1
# 支持 /v1/chat/completions、/v1/responses、/v1/messages（Claude Code）、/v1/embeddings、/v1/audio/*

3. curl 调用示例

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Say hello"}]}'

4. Python OpenAI SDK 调用

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
print(client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Say hello"}],
).choices[0].message.content)

5. Claude Code / Anthropic SDK（使用 /v1/messages 路由）

from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:8000")
# 不需要 api_key（本地 server 不校验）

6. 代理给 Cursor / Aider

Cursor 添加 API Provider 时，Base URL 填 http://localhost:8000/v1，API Key 填 not-needed 即可。

7. Tier-1 Agent 自动配置

rapid-mlx serve gpt-oss-20b-mxfp4-q8 &   # 先启动服务
rapid-mlx agents codex --setup && codex  # 自动配置 Codex CLI
rapid-mlx agents claude-code --setup      # 配置 Claude Code（只需设一个 env var）

支持的 8 个 Agent：Codex CLI、Claude Code、OpenCode、Qwen Code、OpenHands、Hermes Agent、Aider、Kilo Code。

支持的 3 个框架：LangChain（含 LangGraph）、PydanticAI、smolagents。

8. 查看可用模型

rapid-mlx models          # 列出所有 128+ 别名
rapid-mlx info qwen3.5-4b-4bit  # 查看特定模型的详细信息（量化方式、KV codec 等）

9. 可选扩展：VLM（视觉模型）

pip install 'rapid-mlx[vision]'  # Qwen-VL 等多模态模型支持

典型适用场景

坑与注意

1. Qwen3.5/3.6 默认开启思维链（CoT）：如果你觉得速度慢/输出太长，加 --no-think 标志。
2. Python 版本：macOS 系统默认 Python 是 3.9，不支持 rapid-mlx（需要 3.10+）。用 Homebrew 或 uv 安装更新的 Python。
3. OOM（内存不足）：模型太大。参考 RAM 分级表选更小的量化版本，或参考OOM 排障指南。
4. Tool Call 输出纯文本：自动恢复机制处理大多数 case；如仍有问题，用 --tool-call-parser 显式指定解析器。参考排障文档。
5. 端口 8000 被占用：用 --port 指定其他端口。
6. 匿名遥测：默认关闭，首次需手动 rapid-mlx telemetry enable才会收集。不收集 prompts、completions、路径、IP 或 API key。

与同类对比

一句话结论

在 Apple Silicon Mac 上做本地 AI 推理，Rapid-MLX 是目前最快、工具链最完整的方案——一个命令安装、一个命令启动，原有 OpenAI/Anthropic 工具无需修改即可切换。