当前 v0.11.0 版本

macMLX v0.11.0

当前版本让 macMLX 成为本地智能体后端:Codex 对接新的 /v1/responses,Claude Code 对接带 thinking 与 count_tokens 的 /v1/messages;回放的推理会传到聊天模板;在混合与滑动窗口模型上,智能体轮次会复用之前的历史;Xcode 27 与 Apple Foundation Models 客户端已做端到端核验;Gemma 4 E4B 与稠密 Qwen3.5/3.6 可以读图。

兼容性与升级说明

兼容性
新接口明确说明自身边界:/v1/responses 是无状态的,且逐个处理请求;Claude Code 的每个模型别名都必须映射到本地模型;端到端运行只覆盖 Xcode 27 在 Qwen3.6-27B 上、Apple Foundation Models 客户端在它与 Gemma 4 E4B 上,且不含图像;读图只适用于附带视觉塔的 E4B 形状 Gemma 4 检查点与稠密 Qwen3.5/3.6 检查点,图像请求不会在提示缓存中记录任何内容。多词元预测解码不属于这一版本。
升级
升级前请查看标签版 v0.11.0 更新日志。不带 max_tokens 或 max_completion_tokens 的 chat completion 现在最多可生成 32,768 个词元,而不是 2,048 个,连续批处理器的每行上限也随之升到 32,768;提供工具的请求现在一律走单流路径,但 tool_choice "none" 与 tools: [] 仍会批处理;chat completion 的回答现在从第一个非空白文本开始;/v1/messages 接受 tool_choice 的 none、any 与 tool(any 与 tool 提供全部工具但不强制调用),并以 Anthropic 的错误形状报告未知模型或加载失败;GET /v1/models 会列出模型目录中的每个聊天模型;视觉 Gemma 4 或 Qwen3.5/3.6 检查点此前以文本方式加载时留在 SSD 上的提示缓存条目会各未命中一次。

已交付

已发布0.1.0

Apple 芯片 macOS 安装

macMLX 支持运行 macOS 14 或更高版本的 Apple 芯片 Mac。

请使用项目当前安装与 Gatekeeper 指南;不要仅为打开应用而关闭系统级安全保护。

核验

已发布0.1.0

Swift 进程内推理

默认引擎在 Swift 进程内加载并运行 MLX 模型。

模型加载、生成、缓存与服务通过 MacMLXCore 使用 Apple MLX;默认推理路径不需要 Python 运行时。

核验

已发布0.1.0

Apple 芯片统一内存

MLX 数组使用 Mac 的 CPU/GPU 共享内存系统。

统一内存减少 CPU 编排与集成 GPU 计算之间的显式传输,但模型权重、激活值和 KV 缓存仍会占用有限的物理内存。

核验

已发布0.1.0

共享代码,进程内各自运行

应用与 CLI 都导入 MacMLXCore,推理和服务由核心负责。

两个产品共享实现与行为;当应用和 CLI 分别运行在不同进程时,它们不会共享同一个内存中引擎实例。

核验

已发布0.1.0

默认路径无需 Python

已发布的默认引擎为 Swift 原生,不需要 Python 运行时。

可选兼容引擎可能使用子进程与其他运行时,因此这并不表示项目任何地方都没有 Python。

核验

已发布0.5.3

OpenAI 端点兼容

聊天、传统补全、模型列表与嵌入使用兼容的请求和响应结构。

兼容范围按端点界定。/x/models 下的模型加载与卸载是 macMLX 扩展,不属于 OpenAI 兼容的模型管理。

核验

已发布0.5.3

Anthropic Messages 兼容

v0.5.3 提供 POST /v1/messages,并支持流式响应。

这里只兼容 Messages API,不代表兼容完整 Anthropic API。

核验

已发布0.3.7

部分 Ollama 端点

macMLX 支持 /api/version、/api/tags、/api/show、/api/chat 与 /api/generate。

该兼容层自 v0.3.7 起提供;它只覆盖选定端点,不是完整 Ollama API 的无差别替代。

核验

已发布0.5.0

MCP 服务端

CLI 可向 MCP 客户端提供本地推理能力。

MCP 服务端在 v0.5.0 发布,与聊天侧调用外部工具的路由功能不同。

核验

已发布0.5.3

MCP 客户端池

v0.5.3 包含受管理的 MCP 客户端连接。

客户端池负责管理外部 MCP 进程与连接;聊天侧集成工具路由是另一个在 v0.6.0 发布的能力。

核验

已发布0.6.0

聊天集成工具路由

v0.6.0 为 OpenAI、Anthropic 与 GUI MCP 循环交付多轮工具路由。

各协议的验证明确约束工具调用历史;该路由与 MCP 服务端及客户端池基础设施不同。

核验

已发布0.5.3

本地嵌入

POST /v1/embeddings 已在 v0.5.3 发布。

系统可以检测编码器模型家族,但若使用不合适的聊天模型,仍可能生成缺乏语义保证的向量。

核验

已发布0.5.0

精确前缀 RAM 与 SSD 缓存

内存热层与内容寻址 SSD 冷层支持提升和降级。

v0.5.0 发布的缓存复用完整精确前缀,不包含已发布的块共享或分页 KV 分配。

核验

已发布0.6.0

Trie 最长前缀复用

v0.6.0 可复用最长兼容缓存词元前缀。

多轮提示可裁剪到最长公共前缀,只增量预填充新增后缀,同时用量统计仍按完整提示计算。

核验

已发布0.5.0

有界模型池

预算、LRU 淘汰、固定、冷切换、空闲 TTL 与探针共同约束多模型使用。

模型池在 v0.5.0 发布并于 v0.5.3 加固;它不是统一自适应控制器。

核验

已发布0.5.0

受支持的 LoRA 适配器

原生引擎可应用受支持的 LoRA 适配器。

适配器兼容性取决于基础架构与权重,不宣称通用 LoRA 兼容。

核验

已发布0.5.3

检测 14 个 VLM 家族

模型库可检测 14 个视觉语言 model_type 家族。

这是有证据支持的家族数量,不保证每个检查点或处理器变体都能加载。

核验

已发布0.5.3

DeepSeek V3.2 Swift 覆盖层

v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。

真实检查点冒烟测试仍待完成,且缺少 FP8 反量化,因此不构成端到端或通用 MoE 声明。

核验

已发布0.6.0

资格门控的连续批处理

v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求,并自动回退到串行路径。

标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量;VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。

核验

已发布0.6.0

固定预填充准入节流

固定 prefillBatchSize 限制每个调度步骤接纳的行数。

已发布的节流采用固定配置,并非规划中的自适应内存控制器。

核验

已发布0.6.0

结构化输出

v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。

不支持的 Schema 关键字返回 400;VLM 与结构化输出、工具与结构化输出都是不支持的组合,会被明确拒绝而非静默降级。

核验

已发布0.6.0

推测解码

v0.6.0 通过 API 与 GUI 交付经典草稿模型路径。

接受率遥测用于呈现草稿效率;若目标使用不可裁剪的混合或线性注意力缓存,系统会检测并回退到标准解码。

核验

已发布0.6.0

API 兼容功能包

v0.6.0 新增 logit_bias、logprobs 与 top_logprobs、XTC、逐请求 LoRA 适配器和 tools。

明确的兼容矩阵约束参数组合,不支持的配对返回 400,而不会静默降级。

核验

已发布0.6.0

KV 缓存量化

v0.6.0 为兼容请求开放 kv_bits、kv_group_size 与 quantized_kv_start。

这些参数改变 KV 缓存精度,而非模型权重精度;非正数 kv_bits 会禁用该功能,兼容矩阵会拒绝不支持的模型或请求组合。

核验

已发布0.6.0

Hugging Face 缓存发现

v0.6.0 可发现配置的 Hugging Face 缓存根目录中的模型,无需重复下载权重。

发现仅确认本地候选项,并不保证通用加载;架构、分词器、处理器与检查点兼容性仍然适用。

核验

已发布0.6.2

Track G 已测试模型

v0.6.2 新增四个通过检查点实测的原生模型家族。

真实检查点生成实测:Seed-OSS-36B 4-bit 为 18.2 tok/s;Hunyuan V1 Dense 1.8B 4-bit 为 80.3 tok/s;Cohere Command R7B 7B 4-bit 为 21.7 tok/s;MiniCPM3-4B 4-bit 为 18.7 tok/s。结果仅适用于对应检查点,不构成整个家族的性能保证。

核验

理论支持0.6.2

InternLM3 理论支持

v0.6.2 交付通过等价性验证的 InternLM3 代码,支持等级为理论级。

真实生成尚未得到演示。公开检查点提供 tokenizer.model,但没有 tokenizer.json,而 Swift 分词器栈需要 tokenizer.json;在该加载路径边界改变前,支持仍为理论级。

核验

已发布0.1.0

temperature 与 top-p

temperature 与核采样 top-p 是已发布参数。

它们是当前已开放的核心采样控制。

核验

已发布0.7.0

硅活动面板

新的主窗口活动标签页显示实时 Apple 芯片读数、预填充/解码吞吐拆分,以及当前推理瓶颈与相应建议。

面板读取 GPU 占用、内存带宽、热与内存压力以及各电轨功耗,无需管理员权限或辅助进程。它是可观测性,而非性能保证:不可用的计数器会显示破折号并给出原因,空闲引擎显示无活动生成,估算值会被标注而非当作实测值。

核验

已发布0.7.0

推理瓶颈分类器

v0.7.0 将硬件采样与引擎实时的预填充或解码阶段融合,归因限制生成的因素。

由于分类器在进程内运行,它知道当前处于哪个推理阶段——这是外部 GPU 监视器无法获取的信号。它是经过平滑的启发式判断,而非性能剖析器:优先级为内存高于热、热高于计算或带宽,应用迟滞与三帧平滑,并自校准带宽上限,因此结论是指引而非真值测量。

核验

已发布0.7.0

免 sudo 的硅采样

运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。

IOReport 桥接通过 dlopen 解析,因此未来若某个 macOS 重命名或移除该私有框架,读数会降级为不可用而非无法启动。内存带宽以估算值呈现,ANE 提供功耗代理且不虚构利用率百分比,而无占空比信号的媒体引擎则被省略而非猜测。

核验

已发布0.7.0

基准瓶颈归因

基准运行在生成过程中采样硅指标,并将限制其解码稳态的因素附加到保存的结果上。

归因给出解码限制项(内存、热、带宽或计算)及其置信度和背后的代表性硬件。过短而无法归因的运行会报告为不可用,而不是编造结论;低置信度或基于估算的判断会被标注。它描述的是一次实测运行,而非家族级基准保证。

核验

已发布0.7.0

OCR 模型识别

专用 OCR 检查点会获得区别于通用 Vision 徽章的 OCR 徽章,且 GLM-OCR 已端到端验证。

GLM-OCR 通过原有 VLM 路径加载,无需新增模型代码,并能读回图像文字。该徽章刻意保持克制:仅出现在真正能加载的模型上,因此被检测到但尚未移植的 OCR 家族(如 dots_ocr 或 deepseek-ocr)不会获得徽章。这是模型识别,而非通用 OCR 质量声明。

核验

已发布0.8.0

字节有界的冷 KV 层

v0.8.0 将磁盘冷 KV 缓存约束到明确的字节预算,按最旧优先清理,并提供关闭冷层的开关。

此前无上限的冷目录现遵循 Cold(SSD)预算,并同时接入 Hot(RAM)预算;首次启动时超出预算的目录会被裁剪,且只移除可再生的缓存,而非模型文件或设置。它并未新增块共享或分页分配;已发布的缓存仍只复用完整精确前缀。

核验

已发布0.8.0

以权重身份守护的冷条目

v0.8.0 将每个冷条目与模型权重身份指纹绑定,使权重替换后无法再提供陈旧 KV。

指纹覆盖模型 config 及每个 safetensors 分片;若同一路径后续换成重新下载、重新量化或替换的权重,陈旧条目会被拒绝并删除,而不是恢复为静默错误的输出。它是冷层复用的完整性守护,而非对所有缓存路径的正确性证明,也不改变已发布的精确前缀复用语义。

核验

已发布0.8.0

跨会话的持久冷索引

v0.8.0 持久化冷索引,使最长前缀复用可在重启后跨会话保留。

延续更早会话提示的后续轮次可直接从磁盘复用共享前缀;缺失、不可读或版本不匹配的索引会降级为精确命中,绝不会导致错误输出。复用仍为精确前缀,而非规划中的分页或块共享虚拟化;持久索引只是把既有的最长前缀复用延伸到进程重启之后。

核验

已发布0.8.0

脱离 actor 的冷层写入器

v0.8.0 将冷层写入从缓存 actor 迁移到专用的串行后台写入器。

持久化被逐出的 KV 快照(大型缓存可达数百毫秒)不再阻塞其他请求的缓存查找;写入通过临时文件加重命名原子落盘,磁盘上的结果保持不变。它将磁盘写入迁出以保持存储 actor 的响应性,并不改变缓存内容或已发布的复用语义。

核验

已发布0.9.0

进程内语音转文字与文字转语音

POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。

音频引擎为 mlx-audio-swift,因此默认路径仍不需要 Python 运行时,也不绕道 Core ML,模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成,会直接拒绝,而不是改用其他格式充数。这些路径已完成代码并有单元测试,但尚未在真实音频检查点上验证,因此不对转写或合成质量作任何宣称。

核验

已发布0.9.0

应用内的音频能力

转写以可取消的聊天附件形式提供,助手消息新增朗读按钮,模型库会列出音频检查点。

转写结果会落入输入框,便于发送前编辑;开始一次朗读会停止另一次。模型库需要独立扫描,因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json,常规格式检测无法分类;两个调度注册表都查不到的检查点会被有意略过,而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。

核验

已发布0.9.0

可检测的多词元预测草稿模型

草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。

注册与检测已交付;引擎有意没有接线使用它们进行解码。这不是已发布的多词元预测解码,也不改变任何生成路径。

核验

已发布0.9.0

应用已链接受控 MLX 构建

v0.9.0 是首个 GUI 真正链接 macMLX 自有补丁版 mlx-swift(而非上游版本)的 DMG。

Xcode 工程此前没有声明自己的 mlx-swift 依赖,因此在包 identity 冲突时,间接引入的上游副本获胜并被应用链接;此前每个版本发布的 GUI 都不包含那些 MacMLXCore 自身测试已逐条验证过的正确性 cherry-pick。CLI 因另一个 root 存在同样缺陷,已一并修复。这是把引擎恢复成原本预期的样子,而不是在其携带的修复之外改变推理行为。

核验

已发布0.10.0

Foundation Models 形状的 JSON Schema

自 v0.10.0 起,结构化输出接受 Apple Foundation Models 客户端为 @Generable 类型发送的 Schema 形状:嵌套对象、带 minItems 与 maxItems 的数组、指向根 $defs 或 definitions 的 $ref、字符串 const、任意类型的根、任意 Unicode 字符串的键与字面量,以及数字与整数的 minimum 或 maximum 范围。

Schema 最多嵌套 32 层容器,$ref 展开后最多 4,096 个节点;递归 Schema 返回 400,null、联合类型、pattern 与 multipleOf 仍不支持。思考模型上的约束请求会以 enable_thinking 关闭渲染,且永远不会被报告为推理内容。v0.11.0 起,没有范围的 integer 会被限制在 64 位整数范围内,以保证总能解析,但范围内取什么值仍由模型决定。哪些 @Generable 类型经 Apple 客户端做过端到端运行,见 Xcode 27 与 Foundation Models 那条事实;此处接受某种 Schema 形状,本身并不等于经过验证的集成。

核验

已发布0.10.0

流式用量、max_completion_tokens 与缓存词元

v0.10.0 支持 stream_options.include_usage,并在 [DONE] 之前发送一个仅含用量的分块;接受 max_completion_tokens 作为 max_tokens 的新写法;并报告提示缓存命中了多少提示。

缓存词元在 OpenAI 形状的响应中以 prompt_tokens_details.cached_tokens 呈现,在 /v1/messages 中以 cache_read_input_tokens 呈现,此时 input_tokens 为未命中缓存的剩余部分。未命中以及从不查询缓存的路径上该值为 0;由于它是精确前缀判定信号,带 Origin 请求头的请求不会得到该值。非流式请求会忽略 include_usage,因为其响应体本已包含用量。这里只涵盖这些用量字段,而非所有 OpenAI 流式选项。

核验

已发布0.10.0

卸载即归还内存

v0.10.0 在释放聊天模型后清空 MLX 的缓冲区缓存,因此卸载、空闲清理或模型池淘汰会真正归还模型占用的内存,而不是把它留在缓存里。

在此版本之前,卸载 Mellum2-12B-A2.5B-Thinking-4bit 后,模型用过的 7,035 MB 中仍有 7,021 MB 留在 MLX 缓存里;改动后该缓存为空,仅剩 15 MB 活跃内存,几乎全部是提示缓存的内存层,而卸载不会释放这一层(默认最多 512 MiB)。这是对单个检查点的实测,并非对所有模型的保证。推测解码期间的取消可能让权重留待之后的清理,首次加载若在分配后失败,则留给下一次普通生成的清理。

核验

已发布0.10.0

重排器与嵌入模型计入模型池预算

在应用中,服务端会在加载前把 /v1/rerank 与 /v1/embeddings 的模型纳入模型池,因此它们与聊天模型一样计入预算、按最近最少使用淘汰,并按模型的 TTL 过期。

切换时现在会先释放驻留的重排器或嵌入模型并清空 MLX 缓存,再在生成锁下加载替代模型。POST /x/models/unload 接受模型 id,并按该确切 id 卸载驻留的重排器或嵌入模型;既不是它们、也不是当前聊天模型的 id 现在返回 404,而不再无论如何都卸载聊天模型。CLI 的服务端没有模型池,仍直接加载它们;模型标签页也不再提供固定它们的选项。/x/models 仍是 macMLX 扩展,不属于 OpenAI 兼容的模型管理。

核验

已发布0.10.0

基于 MLXRerankers 的重排

v0.10.0 通过 mlx-swift-lm 的 MLXRerankers 提供 POST /v1/rerank:BERT、RoBERTa 与 XLM-RoBERTa 交叉编码器,按 yes/no logit 差打分的 Qwen3 重排器,以及 Jina reranker v3。

在真实检查点上实际运行过的:ms-marco-MiniLM-L-6-v2 在关闭 TF32 时与 PyTorch fp32 参考在 logit 尺度上相差 2e-6 以内,在 M5 默认启用的 TF32 矩阵乘下相差 0.025 以内;Qwen3-Reranker-0.6B-4bit 会把回答问题的文档排在不回答的文档之前。XLM-RoBERTa 路径(BGE)与 Jina v3 尚未在真实检查点上运行,且 Jina v3 报告的是余弦相似度而非概率。分类头的判定比上游规则更窄,因此情感分类头仍是普通模型;对非重排检查点,双编码器余弦仍是回退路径。

核验

已发布0.10.0

原生检查点聊天模板

v0.10.0 通过 swift-jinja 2.5.1 渲染每个检查点自带的聊天模板,并移除两个内置覆盖;逐模型的 macmlx.chat_template.jinja 文件仍优先生效。

提示会在用户可能察觉的地方变化:tojson 现在在工具描述中输出 Python json.dumps 风格的结果,带 {#- 与 -#} 注释的模板按 Jinja 的方式渲染空白,带 answer 标签的 Hunyuan 历史轮次按 Python 的方式剥离。请求携带 tools 时 Command R7B 现在会渲染其 tool_use 模板,但 macMLX 没有解析其所要求动作标记的解析器,因此不支持该模型的工具调用。模板支持仍非通用。

核验

已发布0.10.0

基于 mlx-swift 0.32.3 的受控 MLX fork

v0.10.0 将受控 MLX fork 变基到 mlx-swift 0.32.3(core v0.32.2);该基线已包含 fork 此前携带的十三条修复中的十二条,因此 fork 现在自带五条:mlx#3922、mlx#4009、mlx#4660、mlx#4431 与 mlx#4775。

mlx#4009 修复了排序后的量化 MoE 乘积在 M5 硬件上、group size 为 32 且 K 不规整时破坏 92–97% 输出的问题。mlx#4660 防止卷积的通道填充在异步求值下混入错误数值,Qwen-VL 系列与 GLM-OCR 的 3 通道 patch embedding 都会走到这条路径;mlx#4775 修正量化 KV cache 中全负分组的缩放;mlx#4431 修复一个批量长上下文注意力核,目前没有任何 macMLX 路径会选中它。每一条在携带前都已用合成测试在本机复现,均未通过真实检查点复现。新基线还修复了 JIT 下量化 MoE gather 核的名称(mlx#4372),并按 macOS 27 要求的 Metal 4.1 语言版本编译内核。mlx-swift-lm 随之升至 3.32.3,预填充分块固定为旧的 .remainder 步长,这一点是通过阅读代码而非输出比对确认的;上游单独重写的 Gemma3Text 预填充不在覆盖范围内。携带修复是正确性修补,而非性能宣称。

核验

已发布0.10.0

音频下载保留在应用缓存中

借助受控的 mlx-audio-swift fork(上游 v0.1.5 加上缓存与列表修复),此前会向 ~/.cache/huggingface 再下载一份的语音家族现在从 ~/.mac-mlx/audio-models 加载,缓存快照也会依据 Hub 的完整文件列表补全。

仍会下载到默认 Hugging Face 缓存的有:从本地目录而非按仓库 id 加载的模型所用的分词器或编解码器、Kokoro 与 Kitten 的字素转音素模型,以及非英语 Kokoro 音色的 byT5 模型或词典。v0.9.0 留在那里的副本不会被删除;尚未经 Hub 列表确认的快照无法离线补全。音频加载现在在生成锁下进行,因此加载器自行发起的下载可能阻塞其他请求。这里没有任何测试运行音频推理;只有 moonshine-tiny、带 SNAC 编解码器的 VyvoTTS 与 SenseVoiceSmall 的门控缓存冒烟测试通过,因此不对转写或合成质量作任何宣称。

核验

已发布0.10.0

DMG 交付经过测试的依赖图

v0.10.0 提交了应用工作区的 lockfile,发布归档、CLI 压缩包与应用 CI 构建只使用各自 lockfile 记录的版本;若应用或 CLI 的 lockfile 对 MacMLXCore 所钉包的版本不同,CI 会失败。

v0.9.0 的归档在全新 runner 上解析依赖,交付了 swift-jinja 2.4.2,而所有聊天模板测试都运行在 2.3.6 上。这只是把依赖版本钉到测试实际使用的版本,并非可复现构建或代码签名的宣称,DMG 仍未签名。

核验

已发布0.11.0

OpenAI Responses API

v0.11.0 提供 POST /v1/responses,Codex 等使用 Responses API 的客户端可以对 macMLX 运行其智能体循环:文本、流式推理、函数工具与自定义工具、多轮工具结果、通过 text.format 的结构化输出,以及包含提示缓存命中的用量。

它是无状态的:不存储任何响应,store 会被忽略,previous_response_id、item_reference 条目、background 与文件 id 返回 400,因此客户端每轮都要发送完整对话,Codex 正是如此。web_search 等托管工具不会提供给模型,会被忽略而不是拒绝;none 以外的 tool_choice 与 parallel_tool_calls 只回显、不强制;图像必须是 base64 data URL;请求逐个处理,因此 Codex 子智能体会排队而不是并行运行。这是 Codex 所用的 Responses 接口,而非完整的 OpenAI Responses API。

核验

已发布0.11.0

/v1/messages 上的 Claude Code

v0.11.0 为 /v1/messages 增加 thinking,把模型的推理以 thinking 块返回,并新增 POST /v1/messages/count_tokens,返回 /v1/messages 据以生成的提示长度,因此 Claude Code 可以对接 macMLX 运行。

thinking 设为 disabled 会关闭思考模板的 enable_thinking,budget_tokens 会被接受但不强制。count_tokens 会像生成一样加载模型,并排在正在运行的生成之后。Claude Code 发送而 macMLX 不处理的字段,如 output_config、context_management、metadata 与 cache_control,会被接受并忽略。Claude Code 的每个模型别名都必须映射到本地模型,否则它会请求 claude-* id,macMLX 对此返回 404。这仍是 Messages API 兼容,而非完整的 Anthropic API。

核验

已发布0.11.0

推理内容回传

当客户端在 chat completions、/v1/messages 或 /v1/responses 中回放之前助手轮次的推理时,v0.11.0 会把它作为该轮的 reasoning_content 传给聊天模板,让思考模型在工具循环中看到自己的推理。

渲染与否由模板决定:Qwen3.x、Mellum2 与 Gemma 4 的模板只为最后一个用户问题之后的轮次渲染它(Gemma 4 只在其中带工具调用的轮次渲染),因此遇到新问题时,提示缓存的复用会回退到上一个问题的末尾。承载它的 encrypted_content 与 signature 字段只是 macmlx.r1. 前缀后的 base64 文本,并非加密。走原有视觉路径的模型与 Ollama 端点不在范围内;不带回放推理的请求渲染结果与以前完全相同。

核验

已发布0.11.0

混合与滑动窗口模型上的历史复用

在缓存含线性注意力层或滑动窗口层的模型上(如 Qwen3.6 或 Mellum2),v0.11.0 还会在对话历史末尾存一份缓存,下一轮智能体请求便能复用这段历史,而不必把整段对话重新预填充。

在 Qwen3.6-27B-4bit 上,1.7k 词元工具循环的第二轮复用了 1,712 个提示词元中的 1,662 个,耗时 1.0 秒,冷启动同一提示则为 2.8 秒;Mellum2 复用了 1,632 个中的 1,594 个。这些都是单次实测,并非对其他模型或提示的保证。历史增量不足 256 个词元的轮次不建立快照;大于 512 MiB 内存层的快照写入 SSD 层;缓存全由普通或量化注意力层组成、且没有滑动窗口层的模型不建立快照,仍像以前一样通过裁剪复用。这是精确前缀复用,而非分页 KV 或块共享。

核验

已发布0.11.0

Xcode 27 与 Foundation Models 端到端核验

为 v0.11.0,在 Qwen3.6-27B-4bit 上让真实运行的 macmlx serve 接在 Xcode 27 的本地托管模型提供方之后,并在 Qwen3.6-27B-4bit 与 Gemma 4 E4B 上接在 Apple 的 ChatCompletionsLanguageModel 之后:Xcode 会列出已下载的模型并能持续对话,respond、streamResponse、多轮会话、工具、贪心采样,以及所核验 @Generable 类型的引导生成均可工作。

GET /v1/models 现在列出模型目录中的每个聊天模型,因为 Xcode 会把空列表视为连接失败;带 Origin 请求头的请求仍只看到已加载的模型。@Guide(.pattern) 返回 400;在思考模型上,贪心采样可能一直循环推理直到上限。未核验:图像、其他模型、没有运行服务时应用看到什么,以及 Ollama 端点;除这些运行之外,不对生成质量作任何宣称。

核验

已发布0.11.0

Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图

v0.11.0 会把附带视觉塔的 E4B 形状 Gemma 4 检查点或稠密 qwen3_5 检查点作为视觉模型加载,并在文本生成路径上提供服务,因此其图像请求仍保留提示缓存、工具调用、结构化输出、logprobs 与推理回传。

检查点必须带有视觉配置、视觉塔权重、匹配的处理器元数据,并符合其对齐验证所覆盖的形状才会被识别;31B 稠密版与 26B-A4B 的 Gemma 4、E2B、gemma4_unified、qwen3_5_moe 以及其他任何检查点仍像以前一样按文本加载。图像请求只复用到第一张图像为止的提示缓存,不记录任何缓存,也从不推测解码,因此带图像的智能体会话在之后每一轮都会从该图像起重新预填充。对齐验证是在 gemma-4-e4b-it-8bit、Qwen3.6-27B-4bit 与 Qwen3.5-4B-MLX-8bit 上对照其文本加载完成的,不构成对其他检查点的宣称;Qwen3.5/3.6 读取图像中小字的效果也较差。

核验

当前限制

已发布0.6.0

资格门控的连续批处理

v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求,并自动回退到串行路径。

标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量;VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。

核验

已发布0.6.0

结构化输出

v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。

不支持的 Schema 关键字返回 400;VLM 与结构化输出、工具与结构化输出都是不支持的组合,会被明确拒绝而非静默降级。

核验

理论支持0.6.2

InternLM3 理论支持

v0.6.2 交付通过等价性验证的 InternLM3 代码,支持等级为理论级。

真实生成尚未得到演示。公开检查点提供 tokenizer.model,但没有 tokenizer.json,而 Swift 分词器栈需要 tokenizer.json;在该加载路径边界改变前,支持仍为理论级。

核验

已发布0.5.3

DeepSeek V3.2 Swift 覆盖层

v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。

真实检查点冒烟测试仍待完成,且缺少 FP8 反量化,因此不构成端到端或通用 MoE 声明。

核验

已发布0.7.0

免 sudo 的硅采样

运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。

IOReport 桥接通过 dlopen 解析,因此未来若某个 macOS 重命名或移除该私有框架,读数会降级为不可用而非无法启动。内存带宽以估算值呈现,ANE 提供功耗代理且不虚构利用率百分比,而无占空比信号的媒体引擎则被省略而非猜测。

核验

已发布0.9.0

进程内语音转文字与文字转语音

POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。

音频引擎为 mlx-audio-swift,因此默认路径仍不需要 Python 运行时,也不绕道 Core ML,模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成,会直接拒绝,而不是改用其他格式充数。这些路径已完成代码并有单元测试,但尚未在真实音频检查点上验证,因此不对转写或合成质量作任何宣称。

核验

已发布0.9.0

应用内的音频能力

转写以可取消的聊天附件形式提供,助手消息新增朗读按钮,模型库会列出音频检查点。

转写结果会落入输入框,便于发送前编辑;开始一次朗读会停止另一次。模型库需要独立扫描,因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json,常规格式检测无法分类;两个调度注册表都查不到的检查点会被有意略过,而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。

核验

已发布0.9.0

可检测的多词元预测草稿模型

草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。

注册与检测已交付;引擎有意没有接线使用它们进行解码。这不是已发布的多词元预测解码,也不改变任何生成路径。

核验

已发布0.10.0

Foundation Models 形状的 JSON Schema

自 v0.10.0 起,结构化输出接受 Apple Foundation Models 客户端为 @Generable 类型发送的 Schema 形状:嵌套对象、带 minItems 与 maxItems 的数组、指向根 $defs 或 definitions 的 $ref、字符串 const、任意类型的根、任意 Unicode 字符串的键与字面量,以及数字与整数的 minimum 或 maximum 范围。

Schema 最多嵌套 32 层容器,$ref 展开后最多 4,096 个节点;递归 Schema 返回 400,null、联合类型、pattern 与 multipleOf 仍不支持。思考模型上的约束请求会以 enable_thinking 关闭渲染,且永远不会被报告为推理内容。v0.11.0 起,没有范围的 integer 会被限制在 64 位整数范围内,以保证总能解析,但范围内取什么值仍由模型决定。哪些 @Generable 类型经 Apple 客户端做过端到端运行,见 Xcode 27 与 Foundation Models 那条事实;此处接受某种 Schema 形状,本身并不等于经过验证的集成。

核验

已发布0.10.0

基于 MLXRerankers 的重排

v0.10.0 通过 mlx-swift-lm 的 MLXRerankers 提供 POST /v1/rerank:BERT、RoBERTa 与 XLM-RoBERTa 交叉编码器,按 yes/no logit 差打分的 Qwen3 重排器,以及 Jina reranker v3。

在真实检查点上实际运行过的:ms-marco-MiniLM-L-6-v2 在关闭 TF32 时与 PyTorch fp32 参考在 logit 尺度上相差 2e-6 以内,在 M5 默认启用的 TF32 矩阵乘下相差 0.025 以内;Qwen3-Reranker-0.6B-4bit 会把回答问题的文档排在不回答的文档之前。XLM-RoBERTa 路径(BGE)与 Jina v3 尚未在真实检查点上运行,且 Jina v3 报告的是余弦相似度而非概率。分类头的判定比上游规则更窄,因此情感分类头仍是普通模型;对非重排检查点,双编码器余弦仍是回退路径。

核验

已发布0.10.0

原生检查点聊天模板

v0.10.0 通过 swift-jinja 2.5.1 渲染每个检查点自带的聊天模板,并移除两个内置覆盖;逐模型的 macmlx.chat_template.jinja 文件仍优先生效。

提示会在用户可能察觉的地方变化:tojson 现在在工具描述中输出 Python json.dumps 风格的结果,带 {#- 与 -#} 注释的模板按 Jinja 的方式渲染空白,带 answer 标签的 Hunyuan 历史轮次按 Python 的方式剥离。请求携带 tools 时 Command R7B 现在会渲染其 tool_use 模板,但 macMLX 没有解析其所要求动作标记的解析器,因此不支持该模型的工具调用。模板支持仍非通用。

核验

已发布0.10.0

音频下载保留在应用缓存中

借助受控的 mlx-audio-swift fork(上游 v0.1.5 加上缓存与列表修复),此前会向 ~/.cache/huggingface 再下载一份的语音家族现在从 ~/.mac-mlx/audio-models 加载,缓存快照也会依据 Hub 的完整文件列表补全。

仍会下载到默认 Hugging Face 缓存的有:从本地目录而非按仓库 id 加载的模型所用的分词器或编解码器、Kokoro 与 Kitten 的字素转音素模型,以及非英语 Kokoro 音色的 byT5 模型或词典。v0.9.0 留在那里的副本不会被删除;尚未经 Hub 列表确认的快照无法离线补全。音频加载现在在生成锁下进行,因此加载器自行发起的下载可能阻塞其他请求。这里没有任何测试运行音频推理;只有 moonshine-tiny、带 SNAC 编解码器的 VyvoTTS 与 SenseVoiceSmall 的门控缓存冒烟测试通过,因此不对转写或合成质量作任何宣称。

核验

已发布0.11.0

OpenAI Responses API

v0.11.0 提供 POST /v1/responses,Codex 等使用 Responses API 的客户端可以对 macMLX 运行其智能体循环:文本、流式推理、函数工具与自定义工具、多轮工具结果、通过 text.format 的结构化输出,以及包含提示缓存命中的用量。

它是无状态的:不存储任何响应,store 会被忽略,previous_response_id、item_reference 条目、background 与文件 id 返回 400,因此客户端每轮都要发送完整对话,Codex 正是如此。web_search 等托管工具不会提供给模型,会被忽略而不是拒绝;none 以外的 tool_choice 与 parallel_tool_calls 只回显、不强制;图像必须是 base64 data URL;请求逐个处理,因此 Codex 子智能体会排队而不是并行运行。这是 Codex 所用的 Responses 接口,而非完整的 OpenAI Responses API。

核验

已发布0.11.0

Xcode 27 与 Foundation Models 端到端核验

为 v0.11.0,在 Qwen3.6-27B-4bit 上让真实运行的 macmlx serve 接在 Xcode 27 的本地托管模型提供方之后,并在 Qwen3.6-27B-4bit 与 Gemma 4 E4B 上接在 Apple 的 ChatCompletionsLanguageModel 之后:Xcode 会列出已下载的模型并能持续对话,respond、streamResponse、多轮会话、工具、贪心采样,以及所核验 @Generable 类型的引导生成均可工作。

GET /v1/models 现在列出模型目录中的每个聊天模型,因为 Xcode 会把空列表视为连接失败;带 Origin 请求头的请求仍只看到已加载的模型。@Guide(.pattern) 返回 400;在思考模型上,贪心采样可能一直循环推理直到上限。未核验:图像、其他模型、没有运行服务时应用看到什么,以及 Ollama 端点;除这些运行之外,不对生成质量作任何宣称。

核验

已发布0.11.0

Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图

v0.11.0 会把附带视觉塔的 E4B 形状 Gemma 4 检查点或稠密 qwen3_5 检查点作为视觉模型加载,并在文本生成路径上提供服务,因此其图像请求仍保留提示缓存、工具调用、结构化输出、logprobs 与推理回传。

检查点必须带有视觉配置、视觉塔权重、匹配的处理器元数据,并符合其对齐验证所覆盖的形状才会被识别;31B 稠密版与 26B-A4B 的 Gemma 4、E2B、gemma4_unified、qwen3_5_moe 以及其他任何检查点仍像以前一样按文本加载。图像请求只复用到第一张图像为止的提示缓存,不记录任何缓存,也从不推测解码,因此带图像的智能体会话在之后每一轮都会从该图像起重新预填充。对齐验证是在 gemma-4-e4b-it-8bit、Qwen3.6-27B-4bit 与 Qwen3.5-4B-MLX-8bit 上对照其文本加载完成的,不构成对其他检查点的宣称;Qwen3.5/3.6 读取图像中小字的效果也较差。

核验

规划中

规划中future

分页 KV、块共享与 CoW

分页分配、共享块与写时复制分支处于规划阶段。

这些缓存虚拟化能力均未发布;已交付的缓存仅复用精确的 token 前缀(裁剪至最长公共前缀),没有共享块。

核验

规划中future

统一自适应内存守卫

跨缓存、模型池与并发的反馈控制器处于规划阶段。

已发布的内存探针和模型池上限是独立机制,不能称为该守卫。

核验

规划中future

扩展采样控制

top-k、min-p、presence、frequency 与 repetition 惩罚项,以及逐请求 seed 处于规划阶段。

DeepSeek 专家路由 top-k 是架构内部操作,与用户采样 top-k 无关。

核验

官方来源

  1. macMLX v0.11.0 · github.com
  2. Apple 芯片 macOS 安装
  3. 卸载即归还内存
  4. Apple 芯片统一内存
  5. Xcode 27 与 Foundation Models 端到端核验
  6. macMLX v0.11.0 · github.com
  7. MCP 客户端池
  8. 聊天集成工具路由
  9. 本地嵌入
  10. 以权重身份守护的冷条目
  11. Trie 最长前缀复用
  12. 重排器与嵌入模型计入模型池预算
  13. Track G 已测试模型
  14. DeepSeek V3.2 Swift 覆盖层
  15. 固定预填充准入节流
  16. 资格门控的连续批处理
  17. Foundation Models 形状的 JSON Schema
  18. 推测解码
  19. KV 缓存量化
  20. macMLX v0.11.0 · github.com
  21. InternLM3 理论支持
  22. temperature 与 top-p
  23. 硅活动面板
  24. 硅活动面板
  25. 推理瓶颈分类器
  26. 推理瓶颈分类器
  27. 免 sudo 的硅采样
  28. 免 sudo 的硅采样
  29. 基准瓶颈归因
  30. 基准瓶颈归因
  31. OCR 模型识别
  32. 字节有界的冷 KV 层
  33. 以权重身份守护的冷条目
  34. 跨会话的持久冷索引
  35. 脱离 actor 的冷层写入器
  36. 音频下载保留在应用缓存中
  37. 进程内语音转文字与文字转语音
  38. 应用内的音频能力
  39. 应用内的音频能力
  40. 可检测的多词元预测草稿模型
  41. 应用已链接受控 MLX 构建
  42. 音频下载保留在应用缓存中
  43. Foundation Models 形状的 JSON Schema
  44. Foundation Models 形状的 JSON Schema
  45. 基于 MLXRerankers 的重排
  46. 原生检查点聊天模板
  47. DMG 交付经过测试的依赖图
  48. DMG 交付经过测试的依赖图
  49. OpenAI Responses API
  50. OpenAI Responses API
  51. /v1/messages 上的 Claude Code
  52. 推理内容回传
  53. 混合与滑动窗口模型上的历史复用
  54. 混合与滑动窗口模型上的历史复用
  55. Xcode 27 与 Foundation Models 端到端核验
  56. Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
  57. Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
  58. 扩展采样控制
  59. 扩展采样控制