Nex-N2.5-mini-OptiQ-4bit 视觉能力指南:0.9GB 的 bf16 视觉塔如何让 Mac 看懂图片
Nex-N2.5-mini-OptiQ-4bit 视觉能力指南:0.9GB 的 bf16 视觉塔如何让 Mac 看懂图片
想在 Mac 上本地运行一个"能看图"的大模型?Nex-N2.5-mini-OptiQ-4bit 是一个值得关注的选择:它是 4-bit 混合精度量化的多模态模型,通过 0.9GB 的 bf16 视觉塔保留了完整的图片理解能力,让 Apple Silicon 设备无需云端即可看懂图片、图表与截图。
项目简介:一个能看图的 Agent 模型
Nex-N2.5-mini-OptiQ-4bit 是基于 Qwen3.5-35B-A3B 的 Agent 微调模型(Nex-N2.5-mini)的 MLX 量化版本,核心特点:
| 属性 | 说明 |
|---|---|
| 总参数 / 激活参数 | 35B 总参数,3B 激活(256 个专家) |
| 输入模态 | 文本 + 图片(image-text-to-text) |
| 量化方式 | 4-bit 为主、8-bit 敏感层的混合精度 |
| 视觉塔 | bf16 全精度,独立打包为 0.9GB 侧车文件 |
| 磁盘占用 | 22.2GB 语言模型 + 0.9GB 视觉塔 |
| 授权 | Apache 2.0 |
它的上游模型面向长程 Agent 任务(终端操作、编码、浏览器操作),官方数据为 Terminal-Bench 2.1 得分 73.4、SWE-Bench Pro 得分 43.8(bf16 原始模型)。
为什么视觉塔坚持 bf16?——0.9GB 的价值所在
量化压缩是"以空间换精度",但对多模态模型来说,不同模块对精度损失的敏感度完全不同:
- 语言模型:共 512 个量化层,其中 399 层保留 8-bit(敏感层),113 层压缩到 4-bit(稳健层),分组大小 64。这套分配方案复用了基础模型实测的敏感度配方,用 KL 散度敏感度扫描确定,磁盘体积只比纯 4-bit 量化多几个百分点。
- 视觉塔:不参与量化,完整保留 bf16 精度,单独存放在 optiq/optiq_vision.safetensors(约 0.9GB)。
这样做的原因很直观:视觉特征提取发生在图像进入语言模型之前,若视觉塔被压到 4-bit,颜色、文字、细节等微小特征会先一步丢失,后面的语言模型"无米下锅"。0.9GB 的额外开销换来了图片理解的保真度,对 36GB 内存的 Mac 来说完全可接受。
💡 参考数据:混合精度分配让基础模型的 Capability Score 达到 77.42,而均匀 4-bit 量化只有 76.92——精度花在了刀刃上。
仓库文件清单:每个文件是干什么的?
| 文件 | 作用 |
|---|---|
| README.md | 项目说明、量化细节、使用方法 |
| config.json | 模型架构与逐层量化配置(group_size: 64、敏感层 8-bit 清单) |
| optiq/optiq_vision.safetensors | bf16 视觉塔权重(0.9GB),图片输入的"眼睛" |
| optiq/metadata.json | 量化元数据:4/8-bit 层分布、基础模型信息 |
| kv_config.json | KV 缓存逐层混合精度配置,供 optiq serve 加载 |
| chat_template.jinja | 上游同款对话模板,控制思考行为 |
| model-00001-of-00005.safetensors | 语言模型分片权重(共 5 个分片,合计 22.2GB) |
| tokenizer.json | 分词器词表与格式定义 |
其中 config.json 里的 quantization 字段记录了每一层的 bit 宽度和分组大小,是混合精度方案的"施工图纸";optiq/metadata.json 则汇总了 399 层 8-bit + 113 层 4-bit 的总览。
快速上手:在 Mac 上启动视觉服务
第一步:获取模型
git clone https://gitcode.com/hf_mirrors/mlx-community/Nex-N2.5-mini-OptiQ-4bit
第二步:安装并启动服务(推荐,支持图片)
pip install mlx-optiq
optiq serve --model mlx-community/Nex-N2.5-mini-OptiQ-4bit --kv-config kv_config.json
启动后,服务器同时提供 OpenAI Chat/Responses API 和 Anthropic Messages API 接口。请求消息中的图片部分会自动路由到 bf16 视觉塔处理,文字和图片在同一个会话中完成理解与回复。optiq code 也能直接复用这个本地服务器,作为本地编码 Agent 的视觉底座。
第三步:只想纯文本?用 mlx-lm
pip install mlx-lm
from mlx_lm import load, generate
model, tokenizer = load("mlx-community/Nex-N2.5-mini-OptiQ-4bit")
response = generate(model, tokenizer, prompt="Explain quantum computing in simple terms.", max_tokens=200)
采样参数与思考控制:官方推荐配置
上游评测使用的采样参数,日常使用建议照搬:
| 参数 | 推荐值 | 说明 |
|---|---|---|
temperature |
0.7 | 平衡随机性与稳定性 |
top_p |
0.95 | 核采样阈值 |
top_k |
40 | 限制候选词数量 |
reasoning_effort |
none |
想要直接回答时设为 none,跳过思考 |
对话模板使用上游原版,已打包在 chat_template.jinja 中,加载模型时自动生效,无需手动配置。
KV 缓存混合精度:长上下文的内存优化
除了权重混合精度,KV 缓存也做了逐层分级。kv_config.json 按 layer_idx 声明了各注意力层 KV 缓存的 bit 宽度(4-bit 与 8-bit 交替出现),通过 optiq serve --kv-config 参数加载后,长对话、长文档场景下的内存占用会明显降低——这对 Mac 的统一内存架构尤其友好。
硬件要求与性能预期
- 内存建议:36GB 的 Mac 是官方验证过的运行环境(22.2GB 权重 + 0.9GB 视觉塔 + KV 缓存)
- 平台:Apple Silicon(MLX 原生,无 PyTorch、无云端依赖)
- 能力参考:混合精度方案的 Capability Score 为 77.42,显著优于均匀 4-bit 的 76.92
总结
Nex-N2.5-mini-OptiQ-4bit 的视觉能力设计思路可以概括为一句话:语言模型大胆量化,视觉塔完整保留。0.9GB 的 bf16 视觉塔是整套方案里"最贵的部分",也是 Mac 能真正看懂图片的关键——权重压缩省下的十几 GB 空间,换来的正是本地多模态 Agent 在个人电脑上落地的可能。如果你的 Mac 内存达到 36GB,这套"4-bit 语言模型 + bf16 眼睛"的组合值得一试。