optiq serve 还是 mlx-lm?LensVLM-9B-OptiQ-4bit 双路径本地部署与 sidecar 架构完整指南
optiq serve 还是 mlx-lm?LensVLM-9B-OptiQ-4bit 双路径本地部署与 sidecar 架构完整指南
本文介绍 LensVLM-9B-OptiQ-4bit 在 Mac 上的两种本地部署方式:完整图文能力走 optiq serve,纯文本快速体验走 mlx-lm,并讲清 sidecar 架构如何让视觉塔独立存放。
先认识一下:它是什么模型?
LensVLM-9B-OptiQ-4bit 是苹果文档阅读多模态模型 LensVLM-9B 的 MLX 量化版,专为 Apple Silicon 打造。它不像普通 VLM 那样把长文档逐 token 塞进上下文,而是把页面渲染成"文字的压缩图片",先扫缩略图、再按需展开需要的页面,因此支持 262,144 token 的长上下文。
| 属性 | 值 |
|---|---|
| 基座模型 | apple/LensVLM-9B(Qwen3-VL 视觉编码器 + Qwen3.5-9B 语言塔) |
| 语言塔量化 | 混合 4/8-bit:116 层 4-bit、134 层 8-bit,共 250 层 |
| 视觉塔 | bf16 全精度,独立存放在 sidecar 文件 |
| 磁盘占用 | 约 8.0 GB(语言塔 7.10 GB + 视觉塔 0.91 GB),原版 bf16 需 17.5 GB |
| 量化参数 | group_size = 64 |
📦 也就是说,不到原版一半的体积,就能在 Mac 上跑完整的"看图读文档"能力。
Sidecar 架构:视觉塔为什么单独存放?
这个仓库最特别的设计是 sidecar(边车)架构:
- 语言塔被量化后拆成 model-00001-of-00002.safetensors 和 model-00002-of-00002.safetensors 两个分片;
- 视觉塔保持 bf16 全精度(视觉编码器一旦量化容易掉点),单独放进 optiq_vision.safetensors,内含 333 个张量;
- 逐层位宽配置记录在 optiq/metadata.json 和 config.json 的
quantization块中。
这种"主模型 + 边车"的布局带来一个巧妙的副作用:mlx-lm 加载时只会匹配 model*.safetensors,自动忽略 sidecar 视觉塔,所以同一个仓库天然兼容纯文本和图文两种运行方式,这就是下文"双路径"的由来。
部署路径一:optiq serve 完整图文模式(推荐)
想用它读文档、看截图,这是最省心的方式。mlx-optiq 是 MLX 原生的本地量化工具包,不需要 PyTorch、不依赖云。
一键安装与启动:
pip install mlx-optiq
optiq serve --model mlx-community/LensVLM-9B-OptiQ-4bit
启动后即可用命令行或 Python API 与模型对话。传入图片也很直接:
from optiq.runtime.engine import OptiqEngine
eng = OptiqEngine("mlx-community/LensVLM-9B-OptiQ-4bit")
st = eng.generate("What is in this image?", images=["page.png"], max_tokens=256)
print(st.text)
官方已验证该量化版视觉识别无误:红色圆圈、蓝色方块、绿色三角形都能正确读出。
部署路径二:mlx-lm 纯文本模式(最快上手)
如果你只关心文字问答、不传图片,用 mlx-lm 就能直接加载同一个仓库:
from mlx_lm import load, generate
model, tokenizer = load("mlx-community/LensVLM-9B-OptiQ-4bit")
print(generate(model, tokenizer, prompt="Explain KV caching.", max_tokens=200))
由于 mlx-lm 按 model*.safetensors 通配加载并忽略 sidecar,无需任何额外配置。官方测试确认事实问答、算术推理、迭代代码生成在量化后依然正确。
⚠️ 一个小提醒:LensVLM 是为文档阅读训练的,即使你只问纯文本问题,它也习惯先"扫描页面缩略图"再作答——答案是对的,但会带着文档阅读式的推理外壳。用它擅长的场景(读文档)体验最佳。
如何选:optiq serve 与 mlx-lm 快速对比
| 对比项 | optiq serve | mlx-lm |
|---|---|---|
| 图片输入 | ✅ 完整支持 | ❌ 不支持 |
| 视觉塔加载 | 加载 sidecar | 自动忽略 |
| 依赖 | mlx-optiq | mlx-lm |
| 适用场景 | 文档阅读、截图问答 | 纯文本快速验证 |
一句话决策:👉 要读图读文档就用 optiq serve;只想试试模型的文字能力就用 mlx-lm。
关键文件与配置速查
- README.md:模型说明、验证结果与用法总览
- optiq_vision.safetensors:bf16 视觉塔 sidecar
- optiq/metadata.json:逐层位宽分配表(
per_layer字段) - config.json:模型结构 +
quantization量化块(group_size=64、默认 4-bit) - processor_config.json:Qwen3VLProcessor 图像/视频预处理参数
- model.safetensors.index.json:语言塔权重分片索引
常见问题(FAQ)
Q:名字带 "4bit",为什么还有 8-bit?
A:沿用 llama.cpp 对混合量化的命名习惯——"4bit" 指主要精度而非平均值。实际分配是 116 层 4-bit + 134 层 8-bit,敏感层保留 8-bit 以保住质量,详细依据见 optiq/metadata.json 中的 recipe_note 说明。
Q:可以直接商用吗?
A:注意它的许可证是 Apple Machine Learning Research Model License(apple-amlr),继承自基座模型,并不是 Apache 2.0。使用前请先阅读许可证条款。
Q:16GB 内存的 Mac 跑得动吗?
A:模型文件约 8 GB,加上运行时开销,16GB 统一内存可运行,建议关闭大型应用;若同时处理长文档或大图,32GB 会更从容。