当前 v0.9.0 版本
macMLX v0.9.0
当前版本新增进程内语音转文字与文字转语音，将双编码器重排 MVP 换成真正的交叉编码器，并且是首个 GUI 真正链接 macMLX 自有补丁版 MLX 引擎的构建。
兼容性与升级说明
- 兼容性
- 新接口明确说明自身边界：音频与重排路径已完成代码并有单元测试，但尚未在真实检查点上验证；macMLX 无法生成的输出容器会被拒绝而非替换；两个调度注册表都查不到的音频检查点会被略过而非猜测；多词元预测可被检测，但有意未接入解码。
- 升级
- 升级前请查看标签版 v0.9.0 更新日志。这是首个真正携带引擎正确性 cherry-pick 的 DMG，其中包括在 M5 硬件上超过 32K KV 序列后返回非有限值的长上下文注意力缺陷；音频模型单独下载至 ~/.mac-mlx/audio-models。
已交付
Apple 芯片 macOS 安装
macMLX 支持运行 macOS 14 或更高版本的 Apple 芯片 Mac。
请使用项目当前安装与 Gatekeeper 指南；不要仅为打开应用而关闭系统级安全保护。
核验
Swift 进程内推理
默认引擎在 Swift 进程内加载并运行 MLX 模型。
模型加载、生成、缓存与服务通过 MacMLXCore 使用 Apple MLX；默认推理路径不需要 Python 运行时。
核验
Apple 芯片统一内存
MLX 数组使用 Mac 的 CPU/GPU 共享内存系统。
统一内存减少 CPU 编排与集成 GPU 计算之间的显式传输，但模型权重、激活值和 KV 缓存仍会占用有限的物理内存。
核验
共享代码，进程内各自运行
应用与 CLI 都导入 MacMLXCore，推理和服务由核心负责。
两个产品共享实现与行为；当应用和 CLI 分别运行在不同进程时，它们不会共享同一个内存中引擎实例。
核验
默认路径无需 Python
已发布的默认引擎为 Swift 原生，不需要 Python 运行时。
可选兼容引擎可能使用子进程与其他运行时，因此这并不表示项目任何地方都没有 Python。
核验
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 发布。
系统可以检测编码器模型家族，但若使用不合适的聊天模型，仍可能生成缺乏语义保证的向量。
核验
精确前缀 RAM 与 SSD 缓存
内存热层与内容寻址 SSD 冷层支持提升和降级。
v0.5.0 发布的缓存复用完整精确前缀，不包含已发布的块共享或分页 KV 分配。
核验
Trie 最长前缀复用
v0.6.0 可复用最长兼容缓存词元前缀。
多轮提示可裁剪到最长公共前缀，只增量预填充新增后缀，同时用量统计仍按完整提示计算。
核验
有界模型池
预算、LRU 淘汰、固定、冷切换、空闲 TTL 与探针共同约束多模型使用。
模型池在 v0.5.0 发布并于 v0.5.3 加固；它不是统一自适应控制器。
核验
受支持的 LoRA 适配器
原生引擎可应用受支持的 LoRA 适配器。
适配器兼容性取决于基础架构与权重，不宣称通用 LoRA 兼容。
核验
检测 14 个 VLM 家族
模型库可检测 14 个视觉语言 model_type 家族。
这是有证据支持的家族数量，不保证每个检查点或处理器变体都能加载。
核验
DeepSeek V3.2 Swift 覆盖层
v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。
真实检查点冒烟测试仍待完成，且缺少 FP8 反量化，因此不构成端到端或通用 MoE 声明。
核验
资格门控的连续批处理
v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求，并自动回退到串行路径。
标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量；VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。
核验
固定预填充准入节流
固定 prefillBatchSize 限制每个调度步骤接纳的行数。
已发布的节流采用固定配置，并非规划中的自适应内存控制器。
核验
结构化输出
v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。
不支持的 Schema 关键字返回 400；VLM 与结构化输出、工具与结构化输出都是不支持的组合，会被明确拒绝而非静默降级。
核验
推测解码
v0.6.0 通过 API 与 GUI 交付经典草稿模型路径。
接受率遥测用于呈现草稿效率；若目标使用不可裁剪的混合或线性注意力缓存，系统会检测并回退到标准解码。
核验
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 会禁用该功能，兼容矩阵会拒绝不支持的模型或请求组合。
核验
Hugging Face 缓存发现
v0.6.0 可发现配置的 Hugging Face 缓存根目录中的模型，无需重复下载权重。
发现仅确认本地候选项，并不保证通用加载；架构、分词器、处理器与检查点兼容性仍然适用。
核验
逐模型聊天模板覆盖
v0.6.2 按用户文件、内置 model_type、检查点模板的顺序解析模板。
内置覆盖具备标准路径等价性证据，但模板支持并非通用；检查点特定分支与 swift-jinja 不支持的语法仍可能构成边界。
核验
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。结果仅适用于对应检查点，不构成整个家族的性能保证。
核验
InternLM3 理论支持
v0.6.2 交付通过等价性验证的 InternLM3 代码，支持等级为理论级。
真实生成尚未得到演示。公开检查点提供 tokenizer.model，但没有 tokenizer.json，而 Swift 分词器栈需要 tokenizer.json；在该加载路径边界改变前，支持仍为理论级。
核验
temperature 与 top-p
temperature 与核采样 top-p 是已发布参数。
它们是当前已开放的核心采样控制。
核验
硅活动面板
新的主窗口活动标签页显示实时 Apple 芯片读数、预填充/解码吞吐拆分，以及当前推理瓶颈与相应建议。
面板读取 GPU 占用、内存带宽、热与内存压力以及各电轨功耗，无需管理员权限或辅助进程。它是可观测性，而非性能保证：不可用的计数器会显示破折号并给出原因，空闲引擎显示无活动生成，估算值会被标注而非当作实测值。
核验
推理瓶颈分类器
v0.7.0 将硬件采样与引擎实时的预填充或解码阶段融合，归因限制生成的因素。
由于分类器在进程内运行，它知道当前处于哪个推理阶段——这是外部 GPU 监视器无法获取的信号。它是经过平滑的启发式判断，而非性能剖析器：优先级为内存高于热、热高于计算或带宽，应用迟滞与三帧平滑，并自校准带宽上限，因此结论是指引而非真值测量。
核验
免 sudo 的硅采样
运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。
IOReport 桥接通过 dlopen 解析，因此未来若某个 macOS 重命名或移除该私有框架，读数会降级为不可用而非无法启动。内存带宽以估算值呈现，ANE 提供功耗代理且不虚构利用率百分比，而无占空比信号的媒体引擎则被省略而非猜测。
核验
基准瓶颈归因
基准运行在生成过程中采样硅指标，并将限制其解码稳态的因素附加到保存的结果上。
归因给出解码限制项（内存、热、带宽或计算）及其置信度和背后的代表性硬件。过短而无法归因的运行会报告为不可用，而不是编造结论；低置信度或基于估算的判断会被标注。它描述的是一次实测运行，而非家族级基准保证。
核验
OCR 模型识别
专用 OCR 检查点会获得区别于通用 Vision 徽章的 OCR 徽章，且 GLM-OCR 已端到端验证。
GLM-OCR 通过原有 VLM 路径加载，无需新增模型代码，并能读回图像文字。该徽章刻意保持克制：仅出现在真正能加载的模型上，因此被检测到但尚未移植的 OCR 家族（如 dots_ocr 或 deepseek-ocr）不会获得徽章。这是模型识别，而非通用 OCR 质量声明。
核验
字节有界的冷 KV 层
v0.8.0 将磁盘冷 KV 缓存约束到明确的字节预算，按最旧优先清理，并提供关闭冷层的开关。
此前无上限的冷目录现遵循 Cold（SSD）预算，并同时接入 Hot（RAM）预算；首次启动时超出预算的目录会被裁剪，且只移除可再生的缓存，而非模型文件或设置。它并未新增块共享或分页分配；已发布的缓存仍只复用完整精确前缀。
核验
以权重身份守护的冷条目
v0.8.0 将每个冷条目与模型权重身份指纹绑定，使权重替换后无法再提供陈旧 KV。
指纹覆盖模型 config 及每个 safetensors 分片；若同一路径后续换成重新下载、重新量化或替换的权重，陈旧条目会被拒绝并删除，而不是恢复为静默错误的输出。它是冷层复用的完整性守护，而非对所有缓存路径的正确性证明，也不改变已发布的精确前缀复用语义。
核验
跨会话的持久冷索引
v0.8.0 持久化冷索引，使最长前缀复用可在重启后跨会话保留。
延续更早会话提示的后续轮次可直接从磁盘复用共享前缀；缺失、不可读或版本不匹配的索引会降级为精确命中，绝不会导致错误输出。复用仍为精确前缀，而非规划中的分页或块共享虚拟化；持久索引只是把既有的最长前缀复用延伸到进程重启之后。
核验
脱离 actor 的冷层写入器
v0.8.0 将冷层写入从缓存 actor 迁移到专用的串行后台写入器。
持久化被逐出的 KV 快照（大型缓存可达数百毫秒）不再阻塞其他请求的缓存查找；写入通过临时文件加重命名原子落盘，磁盘上的结果保持不变。它将磁盘写入迁出以保持存储 actor 的响应性，并不改变缓存内容或已发布的复用语义。
核验
交叉编码器重排
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 无法生成，会直接拒绝，而不是改用其他格式充数。这些路径已完成代码并有单元测试，但尚未在真实音频检查点上验证，因此不对转写或合成质量作任何宣称。
核验
应用内的音频能力
转写以可取消的聊天附件形式提供，助手消息新增朗读按钮，模型库会列出音频检查点。
转写结果会落入输入框，便于发送前编辑；开始一次朗读会停止另一次。模型库需要独立扫描，因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json，常规格式检测无法分类；两个调度注册表都查不到的检查点会被有意略过，而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。
核验
可检测的多词元预测草稿模型
草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。
注册与检测已交付；引擎有意没有接线使用它们进行解码，因为迭代器需要目标模型输出草稿状态，而 macMLX 今天能加载的检查点都不具备这一点。这不是已发布的多词元预测解码，也不改变任何生成路径。
核验
应用已链接受控 MLX 构建
v0.9.0 是首个 GUI 真正链接 macMLX 自有补丁版 mlx-swift（而非上游版本）的 DMG。
Xcode 工程此前没有声明自己的 mlx-swift 依赖，因此在包 identity 冲突时，间接引入的上游副本获胜并被应用链接；此前每个版本发布的 GUI 都不包含那些 MacMLXCore 自身测试已逐条验证过的正确性 cherry-pick。CLI 因另一个 root 存在同样缺陷，已一并修复。这是把引擎恢复成原本预期的样子，而不是在其携带的修复之外改变推理行为。
核验
已携带的上游 MLX 正确性修复
钉定的 MLX 构建携带十三条上游正确性修复，其中三条会在不报错的情况下返回错误数值。
超过 32K KV 序列后，NAX 注意力核会让 tile 位置在 16 位类型上回绕，并从错误偏移读取掩码（mlx#3361）；排序后的专家分发在聚合矩阵超过 32768 行时会漏写若干行（mlx#3922）；group size 为 32 的量化向量-矩阵乘法从不分发最后一整块之外的尾列（mlx#4251）。这三条在携带前已在本机复现。其中多数只影响 M5 硬件；携带修复是正确性修补，而非性能宣称。
核验
当前限制
资格门控的连续批处理
v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求，并自动回退到串行路径。
标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量；VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。
核验
结构化输出
v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。
不支持的 Schema 关键字返回 400；VLM 与结构化输出、工具与结构化输出都是不支持的组合，会被明确拒绝而非静默降级。
核验
InternLM3 理论支持
v0.6.2 交付通过等价性验证的 InternLM3 代码，支持等级为理论级。
真实生成尚未得到演示。公开检查点提供 tokenizer.model，但没有 tokenizer.json，而 Swift 分词器栈需要 tokenizer.json；在该加载路径边界改变前，支持仍为理论级。
核验
DeepSeek V3.2 Swift 覆盖层
v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。
真实检查点冒烟测试仍待完成，且缺少 FP8 反量化，因此不构成端到端或通用 MoE 声明。
核验
免 sudo 的硅采样
运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。
IOReport 桥接通过 dlopen 解析，因此未来若某个 macOS 重命名或移除该私有框架，读数会降级为不可用而非无法启动。内存带宽以估算值呈现，ANE 提供功耗代理且不虚构利用率百分比，而无占空比信号的媒体引擎则被省略而非猜测。
核验
进程内语音转文字与文字转语音
POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。
音频引擎为 mlx-audio-swift，因此默认路径仍不需要 Python 运行时，也不绕道 Core ML，模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成，会直接拒绝，而不是改用其他格式充数。这些路径已完成代码并有单元测试，但尚未在真实音频检查点上验证，因此不对转写或合成质量作任何宣称。
核验
应用内的音频能力
转写以可取消的聊天附件形式提供，助手消息新增朗读按钮，模型库会列出音频检查点。
转写结果会落入输入框，便于发送前编辑；开始一次朗读会停止另一次。模型库需要独立扫描，因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json，常规格式检测无法分类；两个调度注册表都查不到的检查点会被有意略过，而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。
核验
交叉编码器重排
POST /v1/rerank 将每个查询-文档对联合分词，并通过单 logit 分类头打分。
分数现在反映查询与文档之间的交互，而不是两段独立嵌入文本的余弦相似度；后者保留为非重排检查点的回退路径。只有序列分类头恰好为单标签的检查点才会被判定为重排器，因此多标签模型不会被误认。该路径已完成代码并有单元测试，但尚未在真实重排检查点上验证。
核验
可检测的多词元预测草稿模型
草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。
注册与检测已交付；引擎有意没有接线使用它们进行解码，因为迭代器需要目标模型输出草稿状态，而 macMLX 今天能加载的检查点都不具备这一点。这不是已发布的多词元预测解码，也不改变任何生成路径。
核验
规划中
分页 KV、块共享与 CoW
分页分配、共享块与写时复制分支处于规划阶段。
这些缓存虚拟化能力均未发布；已交付的缓存仅复用完整精确前缀。
核验
统一自适应内存守卫
跨缓存、模型池与并发的反馈控制器处于规划阶段。
已发布的内存探针和模型池上限是独立机制，不能称为该守卫。
核验
扩展采样控制
top-k、min-p、presence、frequency 与 repetition 惩罚项，以及逐请求 seed 处于规划阶段。
DeepSeek 专家路由 top-k 是架构内部操作，与用户采样 top-k 无关。
核验
官方来源
- macMLX v0.9.0 · github.com
- Apple 芯片 macOS 安装
- KV 缓存量化
- Apple 芯片统一内存
- 部分 Ollama 端点
- macMLX v0.9.0 · github.com
- MCP 客户端池
- 聊天集成工具路由
- 本地嵌入
- 以权重身份守护的冷条目
- Trie 最长前缀复用
- 有界模型池
- Track G 已测试模型
- DeepSeek V3.2 Swift 覆盖层
- 固定预填充准入节流
- 资格门控的连续批处理
- 结构化输出
- 推测解码
- KV 缓存量化
- 逐模型聊天模板覆盖
- macMLX v0.9.0 · github.com
- InternLM3 理论支持
- temperature 与 top-p
- 硅活动面板
- 硅活动面板
- 推理瓶颈分类器
- 推理瓶颈分类器
- 免 sudo 的硅采样
- 免 sudo 的硅采样
- 基准瓶颈归因
- 基准瓶颈归因
- OCR 模型识别
- 字节有界的冷 KV 层
- 以权重身份守护的冷条目
- 跨会话的持久冷索引
- 脱离 actor 的冷层写入器
- 交叉编码器重排
- 交叉编码器重排
- 进程内语音转文字与文字转语音
- 进程内语音转文字与文字转语音
- 应用内的音频能力
- 应用内的音频能力
- 可检测的多词元预测草稿模型
- 应用已链接受控 MLX 构建
- 已携带的上游 MLX 正确性修复
- 扩展采样控制
- 扩展采样控制