Rapid-MLX v0.15.0 中文教程：本地模型服务与 Agent 接入

Rapid-MLX 把 Apple Silicon 上的模型下载、MLX 推理、OpenAI/Anthropic 兼容接口和编码 Agent 配置放进同一个 CLI。2026 年 9 月 22 日发布的 v0.15.0是当前正式版，旧稿的 v0.14.3 已过期。这些数字说明需求持续存在，不代表独立用户数。

前置条件和选择模型

核心文本功能要求 Apple Silicon Mac 和 Python 3.10 以上。基础安装约为文本能力；图像、视觉、音频和视频是可选 extra，视频还要求 Python 3.11 以上及 ffmpeg。模型能否装下取决于统一内存、量化、上下文和并发。先运行 rapid-mlx recipe 看本机建议，再用 rapid-mlx info ALIAS 检查模型档案，不要把官方单机跑分直接当成采购依据。

路径一：Homebrew 安装并验证本地 API

brew install rapid-mlx
rapid-mlx --version
rapid-mlx recipe
rapid-mlx serve qwen3.5-9b-4bit

服务默认绑定 http://localhost:8000；OpenAI 兼容客户端使用 http://localhost:8000/v1。另开终端发一条最小请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5-9b-4bit","messages":[{"role":"user","content":"只回答 READY"}]}'

预期 HTTP 成功且响应带 choices/message；首次运行可能先下载权重。若端口被占用，先查现有进程或显式换端口；若内存不足，换更小量化并缩短上下文；Qwen 思考输出过长可按官方提示加 --no-think；工具调用被当作普通文本时，按模型档案显式设置对应 tool-call parser。

路径二：隔离安装并接入编码 Agent

uv tool install rapid-mlx@latest
# 或：python3.12 -m pip install "rapid-mlx==0.15.0"
rapid-mlx serve qwen3.5-9b-4bit
rapid-mlx agents codex --setup
rapid-mlx agents codex --test

uv 适合不想污染项目 Python 的用户；pip 路径应固定版本。Agent setup 会修改宿主配置，运行前备份相应文件，测试时从只读的“列出当前目录”开始。Claude Code、Codex 等宿主的工具权限仍由宿主管理，Rapid-MLX 只替换模型端点，不会替你限制 shell、Git 或文件写入。接入后同时查看服务日志和 Agent 输出，确认请求没有回退到云端。

网络、密钥与遥测边界

localhost 服务只适合本机客户端。Cursor 的 BYOK 请求会经过 Cursor 服务器，因此官方不会生成 localhost 配置。若你主动建立公网 HTTPS 隧道，服务端和配置端都要设置 RAPID_MLX_API_KEY，还需自行处理 TLS、防火墙和访问日志。v0.15.0 的官方构建默认开启粗粒度元数据遥测；官方说明不采集原始提示词、响应、文件路径、请求体和 API key。可先运行 rapid-mlx telemetry preview 看字段，再用 rapid-mlx telemetry off 或环境变量关闭。

升级和回滚检查

rapid-mlx telemetry status
brew upgrade rapid-mlx
# pip 用户：python -m pip install -U "rapid-mlx==0.15.0"
rapid-mlx --version
rapid-mlx doctor

从旧 tap 迁移时，按官方说明卸载旧 formula、untap 后再装 homebrew-core 版本。升级前记录模型别名、端口、parser、上下文和 Agent 配置；升级后重复同一条 curl、一次工具调用和一次 Agent 只读任务。v0.15.0 增加 Qwen-Image 2.1、MiMo-V2.6 Flash、Gemma 4 sidecar 与遥测控制，但大模型的内存档位不能从 release 文案替代本机验证。

与 Ollama 的实际区别

Ollama 覆盖 macOS、Windows 和 Linux，模型生态与通用部署范围更大。Rapid-MLX 聚焦 Apple Silicon 和 MLX，把多个 Agent 的配置、wire test、模型 recipe 及 Apple 统一内存优化放在一处。如果团队混合操作系统或已围绕 Ollama API 建好运维，迁移收益可能有限；如果全是 M 系列 Mac，并且要频繁给 Codex、Claude Code 或 Aider 切本地端点，Rapid-MLX 的专用路径更短。两者都必须在相同模型、量化、上下文和并发下复测。

常见问题