2026年9月4日，ollama v0.33.3 正式发布。本次版本围绕多模态模型能力、生成参数兼容性、缓存提示词统计、MLX 运行时稳定性、macOS 持续集成测试以及底层推理组件升级展开。
该版本共包含 14 次提交、156 个文件变更，由 4 位贡献者参与，整体变更规模为 12,844 行新增与 6,387 行删除。核心更新包括：Gemma4 在 MLX 引擎中新增图像和音频输入支持；新增缓存提示词 Token 统计；尊重 GGUF 模型定义的默认生成参数；MLX、MLX-C 与 llama.cpp 完成版本更新；MLX 绑定错误处理与音频处理逻辑进一步完善；同时为 macOS 环境下的 MLX 单元测试补充了运行时依赖准备机制。
本次更新重点速览
- Gemma4 在 MLX 引擎中支持图像输入和音频输入
- 可报告缓存提示词 Token 数量
- GGUF 模型中定义的默认生成参数将被遵循
- MLX 与 MLX-C 完成版本升级
- llama.cpp 完成两次版本更新
- PR 运行流程接入 MLX 单元测试
- MLX 依赖文件完成去重处理
- MLX 运行错误统一在每次调用后读取和捕获
- MLX C 绑定层检查每一次 MLX-C 调用
- 音频模型采用共享音频解码与分块逻辑
- macOS 持续集成可自动准备匹配版本的 MLX Metal 运行时库
Gemma4 在 MLX 引擎中支持图像与音频输入
v0.33.3 最重要的能力更新之一，是 Gemma4 获得了图像和音频输入支持，且该能力落在 MLX 引擎中。
此前，多模态输入能力往往需要模型、推理引擎、输入预处理与运行时库之间同时配合。本次更新在 MLX 运行链路中补齐了 Gemma4 对图像和音频的输入支持，使图像模型和音频模型相关输入能够进入相应的处理流程。
与此配套的还有音频输入处理逻辑的调整。版本中新增了“共享音频解码与分块”机制，用于音频模型。该改动意味着音频数据的解码与切分不再采用重复的独立实现，而是统一为可共享的处理流程。对于需要输入音频内容的模型而言，解码和切块是进入模型推理前的重要步骤，统一处理逻辑能够让相关调用路径保持一致。
Gemma4 图像与音频输入支持，以及共享音频解码和分块处理，构成了本次 MLX 多模态能力更新的核心部分。
新增缓存提示词 Token 统计
v0.33.3 新增“报告缓存提示词 Token”的能力。
提示词在推理过程中可能包含可复用的缓存部分。此次版本将缓存提示词的 Token 数量纳入报告范围，使缓存提示词对应的 Token 信息能够被输出或记录。
这一更新对应的提交内容为“Report cached prompt tokens”，发布时间为 2026 年 9 月 3 日。
从版本更新说明来看，本次重点并非改变 Token 缓存机制本身，而是补充缓存提示词 Token 的统计与报告。也就是说，用户和调用方能够获得缓存提示词部分的 Token 数据，而不是仅关注整体提示词或生成结果中的 Token 信息。
遵循 GGUF 模型定义的默认生成参数
v0.33.3 新增对模型默认生成参数的遵循。
版本说明明确指出：Honor GGUF model defined default parameters，也就是尊重 GGUF 模型定义的默认参数。对应提交名称为“Honor model generation defaults”，发布时间为 2026 年 9 月 2 日。
生成参数直接影响模型输出过程，例如模型自身在文件中定义的默认生成配置。此前，模型定义中的默认参数是否被完整采用，可能受到运行时默认行为的影响。本次更新后，GGUF 模型中定义的默认生成参数将得到遵循。
这一改动的重点在于“模型定义的默认值”。当 GGUF 模型已经提供生成默认参数时，运行过程会尊重这些模型内置配置，而不是忽略模型定义并仅采用其他默认设置。
MLX 与 MLX-C 完成版本升级
本次版本中，MLX 与 MLX-C 均完成版本更新。
相关提交为“MLX, MLX-C: version bump”，发布时间为 2026 年 9 月 2 日，对应变更编号为 18080。
MLX 是本次多个功能更新的基础，包括 Gemma4 图像输入、Gemma4 音频输入、音频共享解码与分块、MLX 错误捕获，以及 macOS 环境中的 MLX 单元测试支持。因此，MLX 和 MLX-C 的同步版本提升是 v0.33.3 的底层关键更新之一。
除版本提升之外，本次还包含 MLX 依赖文件去重。对应提交为“mlx: dedup dependency files”，发布时间为 2026 年 9 月 1 日，对应变更编号为 18159。
依赖文件去重的目标是消除重复依赖文件，使 MLX 相关依赖管理更加集中。该改动与版本升级共同构成了 MLX 侧的基础维护内容。
llama.cpp 完成两次版本更新
v0.33.3 中 llama.cpp 出现两次版本更新。
第一项更新为：
- llama.cpp: version bump b10729
- 发布时间：2026 年 9 月 2 日
- 对应变更编号：18160
第二项更新为：
- llama.cpp: version bump b10760
- 发布时间：2026 年 9 月 3 日
- 对应变更编号：18199
从提交时间线可见，llama.cpp 在短时间内连续更新了两个版本标识，先更新至 b10729，随后继续升级至 b10760。最终 v0.33.3 所包含的是完成后续更新的底层状态。
llama.cpp 版本更新与 MLX、MLX-C 版本更新一起，构成了本次发布中推理底座的同步升级内容。
MLX 错误处理进一步加强
本次更新还强化了 MLX 运行过程中的错误捕获和调用检查。
相关内容包括两项提交：
- mlxrunner: capture MLX errors in a single buffer read after every call
- mlxrunner: check every mlx-c call in the MLX bindings
第一项调整要求 mlxrunner 在每一次调用之后，通过一次缓冲区读取来捕获 MLX 错误。这里的核心是“每次调用后读取”以及“单一缓冲区读取”。这意味着 MLX 错误信息的读取流程被集中化，并在每次调用后执行。
第二项调整要求 MLX 绑定层检查每一次 MLX-C 调用。也就是说，MLX 绑定中的 MLX-C 调用不再只依赖局部或阶段性的检查，而是对每一项调用进行检查。
两项改动共同覆盖了两个层面：
- mlxrunner 层面：每次调用后统一读取错误信息
- MLX 绑定层面：每一个 MLX-C 调用都执行检查
这部分更新与 Gemma4 多模态支持、音频处理支持共同出现，说明 MLX 相关功能增加的同时，运行错误的捕获与检查也得到同步完善。
修复 MLX 的 mtp_test 单元测试
v0.33.3 包含一项 MLX 单元测试修复：
- mlx: fix mtp_test unit test
- 发布时间：2026 年 9 月 3 日
- 对应变更编号：18203
该更新针对 mtp_test 单元测试进行修复。与此同时，持续集成流程中也接入了 MLX 单元测试执行能力。
对应提交为：
- ci: wire up MLX unit tests for PR runs
- 发布时间：2026 年 9 月 2 日
- 对应变更编号：17022
“为 PR 运行接入 MLX 单元测试”意味着在提交合并请求的验证流程中，MLX 单元测试将被接入。为了支持这一过程，版本还新增了一个用于 macOS 环境的脚本，负责准备 MLX Metal 运行时库。
macOS CI 自动准备 MLX Metal 运行时库
本次变更中新增了文件：
.github/scripts/prepare_mlx_darwin.sh
该脚本共新增 159 行，没有删除内容。它的用途是为 macOS 持续集成中的 MLX 单元测试准备预构建的 MLX Metal 运行时库。
脚本的设计背景很明确：构建 MLX 的成本较高。为了让 MLX 专用单元测试能够执行，脚本会寻找与当前检出代码中 MLX 版本和 MLX-C 版本相匹配的最新发布版本，下载该发布版本中的 macOS 压缩包，然后只提取其中的 MLX Metal 运行时目录到构建目录。
脚本查找的发布仓库默认值为：
ollama/ollama
可以通过环境变量 OLLAMA_MLX_RELEASE_REPO 覆盖默认仓库。
用于扫描发布标签的数量默认是 50，可以通过 OLLAMA_MLX_RELEASE_SCAN_LIMIT 设置。
缓存目录默认是：
.cache/mlx-darwin-release
可通过 OLLAMA_MLX_DARWIN_CACHE 修改。
目标目录默认是：
build/lib/ollama
可通过 OLLAMA_MLX_DARWIN_TARGET 修改。
脚本使用的压缩包缓存文件为：
.cache/mlx-darwin-release/ollama-darwin.tgz
用于记录匹配发布标签的文件为：
.cache/mlx-darwin-release/matched-tag
用于记录匹配版本固定值的文件为：
.cache/mlx-darwin-release/matched-pins
目标目录中还会使用：
build/lib/ollama/.mlx-release-pins
该文件用于记录已准备运行时库对应的 MLX 与 MLX-C 版本组合。
脚本如何判断 MLX Metal 运行时是否可用
脚本会在目标目录中查找名称符合 mlx_metal_v* 的目录。
对于每个候选目录，只有同时存在以下两个文件时，才被认为包含可用的 MLX Metal 运行时负载：
libmlx.dyliblibmlxc.dylib
如果目标目录中已经存在可用负载，并且 .mlx-release-pins 文件中的版本组合与当前仓库的版本组合一致，脚本会直接输出运行时已存在的信息并退出，不再下载。
当前版本组合来自两个文件：
MLX_VERSIONMLX_C_VERSION
脚本会读取这两个文件的内容，并去掉所有空白字符，然后以“MLX 版本加空格加 MLX-C 版本”的形式组合为当前固定值。
只有目标目录中的固定值与当前固定值完全一致，且对应目录中存在 libmlx.dylib 和 libmlxc.dylib 时，才会视为已经具备匹配的运行时库。
脚本仅在 macOS 环境中执行
脚本会先检查当前系统名称。
如果系统不是 Darwin，也就是不是 macOS，脚本会发出警告，说明 MLX Darwin 运行时准备仅支持 macOS，然后正常退出。
因此，该脚本的处理范围明确限定在 macOS 环境，不会尝试在其他系统上下载或提取 MLX Metal 动态库。
如果处于 GitHub Actions 环境中，警告会采用持续集成可识别的警告格式输出；如果不在该环境，则会将警告信息输出到标准错误流。
如何复用本地已缓存的 macOS 压缩包
在开始远程查找之前，脚本会先检查缓存中的压缩包、匹配标签以及版本固定值。
满足以下条件时，脚本会直接复用缓存：
- 缓存压缩包存在且非空
- 匹配标签文件存在
- 缓存记录的版本固定值与当前 MLX、MLX-C 版本固定值一致
满足这些条件后，脚本会直接从缓存的 macOS 压缩包中提取运行时负载，无需重新扫描远程发布标签，也无需重新下载文件。
在提取时，脚本会创建一个临时目录，解压压缩包，并创建目标目录。随后，它会先删除目标目录下原有的所有 mlx_metal_v* 目录，再从解压内容中查找对应目录并复制到目标目录。
如果压缩包中没有找到 mlx_metal_v* 目录，或者提取完成后仍然没有找到同时包含 libmlx.dylib 与 libmlxc.dylib 的可用负载，脚本会输出错误信息并终止。
提取成功后，脚本会把当前版本固定值写入目标目录中的 .mlx-release-pins，并输出所使用的发布标签信息。随后会列出目标目录中满足以下条件的文件：
libmlx.dyliblibmlxc.dylib- 扩展名为
.metallib的文件
这些文件的搜索深度最大为两层目录。
如何寻找匹配的发布版本
当本地没有可直接复用的缓存时，脚本会通过远程标签列表查找发布版本。
脚本从默认仓库的远程标签中读取以 v 开头的标签，并按照版本号倒序排序。随后，依据扫描上限处理标签列表，默认最多检查 50 个标签。
对每个候选标签，脚本会依次执行以下检查：
- 下载该标签对应的
MLX_VERSION文件 - 去除文件内容中的空白字符
- 判断其是否与当前代码中的
MLX_VERSION一致 - 如果不一致，则跳过该标签
- 下载该标签对应的
MLX_C_VERSION文件 - 去除文件内容中的空白字符
- 判断其是否与当前代码中的
MLX_C_VERSION一致 - 如果不一致，则跳过该标签
- 如果两个版本都匹配，则检查该标签的 macOS 发布压缩包是否存在
目标压缩包地址格式为：
https://github.com/ollama/ollama/releases/download/标签名/ollama-darwin.tgz
脚本会使用 HTTP 头请求检查压缩包地址是否可访问。
如果某个标签的 MLX 与 MLX-C 版本都匹配，但对应的压缩包地址无法访问，脚本会输出该标签版本匹配但发布文件不可用的信息，并继续检查下一个标签。
一旦找到 MLX_VERSION 与 MLX_C_VERSION 均匹配，且 ollama-darwin.tgz 可访问的标签，脚本将停止扫描，并把该标签作为匹配发布版本。
找不到匹配发布包时的处理方式
脚本特别考虑了一个预期场景：MLX 或 MLX-C 版本更新已经进入代码，但尚未发布包含匹配 macOS 产物的新版本。
在这种情况下，远程扫描可能找不到同时满足版本固定值和发布压缩包可用条件的标签。
如果最终没有找到匹配标签，脚本不会将这一情况视为硬性失败，而是发出警告后退出。警告内容表达的含义是：在发布构建产出与当前 MLX_VERSION 和 MLX_C_VERSION 相匹配的 ollama-darwin.tgz 之前，MLX 单元测试将暂时被禁用。
这与脚本开头的设计说明一致：如果不存在匹配版本的发布产物，只提示警告，从而覆盖 MLX 更新已合入但新的 macOS 发布包尚未生成的时间窗口。
找到匹配发布包后的下载与提取流程
当找到匹配标签和对应下载地址后，脚本会创建一个临时下载文件，其路径基于缓存压缩包路径并追加 .tmp 后缀。
下载过程使用重试机制：
- 最多重试 3 次
- 每次重试间隔 2 秒
下载完成后，临时文件会被移动为正式缓存压缩包：
.cache/mlx-darwin-release/ollama-darwin.tgz
随后，脚本会把匹配标签写入 matched-tag 文件，并将当前 MLX 与 MLX-C 版本固定值写入 matched-pins 文件。
最后，脚本执行提取流程，将发布压缩包中的 mlx_metal_v* 目录复制到：
build/lib/ollama
或者复制到通过环境变量指定的目标目录。
脚本在结束时还会清理临时目录和临时下载文件，避免临时资源残留。
其他提交内容与时间线
本次 v0.33.3 的提交时间线如下。
2026 年 8 月 31 日
- 修正代码审查期间发现的文档拼写错误
- 对应变更编号：17579
2026 年 9 月 1 日
- MLX 依赖文件去重
- 对应变更编号：18159
2026 年 9 月 2 日
- 构建相关的 Go 依赖更新
- 遵循模型生成默认参数
- 对应变更编号：16471
- MLX 与 MLX-C 版本提升
- 对应变更编号：18080
- llama.cpp 更新至 b10729
- 对应变更编号：18160
- 在 PR 运行中接入 MLX 单元测试
- 对应变更编号：17022
2026 年 9 月 3 日
- 报告缓存提示词 Token
- 对应变更编号：17943
- llama.cpp 更新至 b10760
- 对应变更编号：18199
- 修复 MLX 的 mtp_test 单元测试
- 对应变更编号：18203
- mlxrunner 在每次调用后通过单一缓冲区读取捕获 MLX 错误
- MLX 绑定层检查每一次 MLX-C 调用
- 音频模型共享音频解码与分块处理
- Gemma4 新增图像和音频输入支持
总结
代码地址：github.com/ollama/ollama
ollama v0.33.3 的更新重点集中在 MLX、多模态输入、生成参数兼容性和测试运行环境四个方向。
Gemma4 在 MLX 引擎中获得图像与音频输入能力，音频模型同时采用共享解码与分块流程。GGUF 模型定义的默认生成参数得到遵循，缓存提示词 Token 也可以被报告。
底层方面，MLX、MLX-C 与 llama.cpp 均完成更新，其中 llama.cpp 从 b10729 继续更新至 b10760。MLX 绑定层加强了每一次 MLX-C 调用的检查，mlxrunner 在每次调用后集中读取错误信息。
持续集成方面，MLX 单元测试被接入 PR 运行流程，并通过新增的 macOS 脚本自动寻找与当前 MLX 和 MLX-C 版本匹配的发布包，提取其中的 MLX Metal 动态库和相关资源。若匹配发布包暂未出现，脚本会发出警告并临时跳过相关 MLX 单元测试。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/weixin_48502062/article/details/164371628
