兼容性事实
OpenAI 端点兼容
聊天、传统补全、模型列表与嵌入使用兼容的请求和响应结构。
兼容范围按端点界定。/x/models 下的模型加载与卸载是 macMLX 扩展，不属于 OpenAI 兼容的模型管理。
核验
Anthropic Messages 兼容
v0.5.3 提供 POST /v1/messages，并支持流式响应。
这里只兼容 Messages API，不代表兼容完整 Anthropic API。
核验
部分 Ollama 端点
macMLX 支持 /api/version、/api/tags、/api/show、/api/chat 与 /api/generate。
该兼容层自 v0.3.7 起提供；它只覆盖选定端点，不是完整 Ollama API 的无差别替代。
核验
MCP 服务端
CLI 可向 MCP 客户端提供本地推理能力。
MCP 服务端在 v0.5.0 发布，与聊天侧调用外部工具的路由功能不同。
核验
MCP 客户端池
v0.5.3 包含受管理的 MCP 客户端连接。
客户端池负责管理外部 MCP 进程与连接；聊天侧集成工具路由是另一个在 v0.6.0 发布的能力。
核验
聊天集成工具路由
v0.6.0 为 OpenAI、Anthropic 与 GUI MCP 循环交付多轮工具路由。
各协议的验证明确约束工具调用历史；该路由与 MCP 服务端及客户端池基础设施不同。
核验
本地嵌入
POST /v1/embeddings 已在 v0.5.3 发布。
系统可以检测编码器模型家族，但若使用不合适的聊天模型，仍可能生成缺乏语义保证的向量。
核验
交叉编码器重排
POST /v1/rerank 将每个查询-文档对联合分词，并通过单 logit 分类头打分。
分数现在反映查询与文档之间的交互，而不是两段独立嵌入文本的余弦相似度；后者保留为非重排检查点的回退路径。只有序列分类头恰好为单标签的检查点才会被判定为重排器，因此多标签模型不会被误认。该路径已完成代码并有单元测试，但尚未在真实重排检查点上验证。
核验
进程内语音转文字与文字转语音
POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。
音频引擎为 mlx-audio-swift，因此默认路径仍不需要 Python 运行时，也不绕道 Core ML，模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成，会直接拒绝，而不是改用其他格式充数。这些路径已完成代码并有单元测试，但尚未在真实音频检查点上验证，因此不对转写或合成质量作任何宣称。
核验
资格门控的连续批处理
v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求，并自动回退到串行路径。
标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量；VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。
核验
结构化输出
v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。
不支持的 Schema 关键字返回 400；VLM 与结构化输出、工具与结构化输出都是不支持的组合，会被明确拒绝而非静默降级。
核验
API 兼容功能包
v0.6.0 新增 logit_bias、logprobs 与 top_logprobs、XTC、逐请求 LoRA 适配器和 tools。
明确的兼容矩阵约束参数组合，不支持的配对返回 400，而不会静默降级。
核验
KV 缓存量化
v0.6.0 为兼容请求开放 kv_bits、kv_group_size 与 quantized_kv_start。
这些参数改变 KV 缓存精度，而非模型权重精度；非正数 kv_bits 会禁用该功能，兼容矩阵会拒绝不支持的模型或请求组合。
核验
端点兼容性矩阵
| 接口 | 端点 | 兼容边界 |
|---|---|---|
| OpenAI 聊天 | POST /v1/chat/completions | 兼容并支持流式响应 |
| OpenAI 传统补全 | POST /v1/completions | 兼容传统补全结构 |
| OpenAI 模型列表 | GET /v1/models | 兼容列表；加载/卸载是 /x/models 下的 macMLX 扩展 |
| OpenAI 嵌入 | POST /v1/embeddings | 兼容嵌入结构；仍需选择合适模型 |
| Anthropic | POST /v1/messages | 仅 Messages API（含流式），不是完整 Anthropic API |
| Ollama | /api/version、/api/tags、/api/show、/api/chat、/api/generate | 自 v0.3.7 起支持选定端点，不是完整替代 |
| 重排 | POST /v1/rerank | 经单 logit 头的交叉编码器打分；双编码器余弦为回退路径 |
| 音频 | POST /v1/audio/transcriptions、POST /v1/audio/speech | OpenAI 形状；macMLX 无法生成的输出容器会被拒绝，而不是替换 |
| 工具循环 | OpenAI、Anthropic 与 GUI MCP 路由 | 多轮工具路由于 v0.6.0 发布 |
| 结构化输出 | response_format：json_object 或受支持的 JSON Schema | 不支持的 Schema 以及工具/VLM 组合返回 400 |
| API 兼容功能包 | logit_bias、logprobs、top_logprobs、XTC、逐请求 LoRA、tools | 不支持的参数组合返回 400 |
| KV 缓存量化 | kv_bits、kv_group_size、quantized_kv_start | 仅限兼容请求；这不会量化模型权重 |
OpenAI 兼容聊天示例
使用明确的模型与消息调用本地服务。
curl http://localhost:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"your-mlx-model","messages":[{"role":"user","content":"Hello"}]}'