3步跑通Sage-A1.5-OptiQ-4bit:optiq serve与mlx-lm新手快速上手教程

原创2026-10-23 19:26:211,826 阅读
文章标签:大模型本地部署模型量化多模态AI Agent强化学习

3步跑通Sage-A1.5-OptiQ-4bit:optiq serve与mlx-lm新手快速上手教程

Sage-A1.5-OptiQ-4bit 是上海AI实验室 35B MoE 智能体模型 Sage-A1.5 的混合精度 4-bit MLX 量化版本,专为 Apple Silicon 设计。它把约 72 GB 的 bf16 权重压缩到磁盘上仅 22 GB 左右,只需 3 步:安装 mlx-optiq、用 optiq serve 启动本地服务、用 mlx-lm 快速跑通文本对话,新手也能轻松上手。

📦 项目速览:这个量化模型有什么特别?

Sage-A1.5 采用 Qwen3.6-35B-A3B 架构:40 层、256 个专家、每 token 仅激活 8 个专家(约 3B 激活参数),并带 Qwen3-VL 视觉塔。OptiQ 的量化思路是「该省的省、该保的保」:

属性 值
语言塔 混合 4/8-bit(512 个张量:118 个 4-bit、394 个 8-bit)
视觉塔 保留 bf16,放在独立 sidecar 文件中
磁盘占用 语言 20.6 GB + 视觉 0.9 GB + MTP 头 0.5 GB
Group size 64
上下文长度 262,144 tokens(256K 长上下文)

💡 命名说明:沿用 llama.cpp 混合量化的命名习惯,"4bit" 表示主导精度,而不是加权平均值。

🖥️ 硬件建议:Apple Silicon Mac。检查点本身约 22 GB,再加上运行时开销,建议 32 GB 及以上统一内存以获得稳妥体验。

每层的 4/8-bit 分配来自同架构 Qwen3.6-35B-A3B 的 KL 散度敏感度扫描结果,本仓库 512/512 张量全部精确匹配配方,无一回退到平铺 4-bit。

第一步:安装运行环境 🛠️

只需要一条 pip 命令装好 MLX 原生的量化与推理工具链(无需 PyTorch、无需云端):

pip install mlx-optiq

如果你还想用 mlx-lm 跑纯文本对话,顺手再装一下:

pip install mlx-lm

第二步:用 optiq serve 启动本地推理服务 🚀

这是本项目的推荐用法,一条命令即可启动带投机解码加速的本地服务:

optiq serve --model mlx-community/Sage-A1.5-OptiQ-4bit --ngram-draft 16

参数说明:

参数 作用
--model 指定模型仓库,首次运行会自动下载检查点
--ngram-draft 16 启用 N-gram 投机解码加速生成速度

⚠️ 注意:该模型暂不支持 --mtp 参数(Qwen3.6-35B-A3B 家族的 MTP 头无法加载进 OptiQ 的 speculator),提速请统一使用 --ngram-draft。

另外,optiq serve 会自动读取仓库中的 generation_config.json,官方推荐的采样参数开箱即用。

第三步:用 mlx-lm 快速跑通文本对话 💬

mlx-lm 是 Apple 官方的 MLX 大模型运行时,原生支持这个检查点。它会加载 model*.safetensors 文件、自动忽略视觉 sidecar,所以同一个仓库两种运行时都能直接加载:

from mlx_lm import load, generate

model, tokenizer = load("mlx-community/Sage-A1.5-OptiQ-4bit")
print(generate(model, tokenizer, prompt="Explain KV caching.", max_tokens=2048))

想理解图片?走 OptiQ 的 Python API 🖼️

mlx-lm 只负责文本;图片理解需要经由 OptiQ 引擎加载 bf16 视觉塔:

from optiq.runtime.engine import OptiqEngine

eng = OptiqEngine("mlx-community/Sage-A1.5-OptiQ-4bit")
st = eng.generate("What is in this image?", images=["figure.png"], max_tokens=2048)
print(st.text)

📁 仓库关键文件一览

文件 作用
README.md 项目说明、验证结果与使用方法
config.json 模型架构与逐层量化位宽(quantization 块)
generation_config.json 官方推荐采样参数,optiq serve 自动读取
optiq/metadata.json 每层 4/8-bit 位宽分配图(bit map)
optiq/mtp.safetensors MTP 投机解码头(约 0.5 GB)
optiq_vision.safetensors bf16 视觉塔 sidecar(333 个张量)
model-00001-of-00005.safetensors 语言塔权重分片 1(共 5 个分片)
model.safetensors.index.json 权重索引,方便运行时定位张量
chat_template.jinja 对话模板(基于 Qwen3.6,含可选验证协议开关)
processor_config.json Qwen3VL 图像/视频处理器配置
tokenizer_config.json 分词器配置,max_length 262,144

⚙️ 为什么采样参数如此重要?

上游模型卡没有附带 generation_config.json。作者实测发现:不加 presence_penalty 时,量化模型在开放式问题上会"推理超过 16,384 tokens 却不给出答案";而加上官方推荐参数后,同样的问题分别只用约 4,900 和 800 个推理 token 就正确作答。

推荐参数(已内置于 generation_config.json):

参数 值
temperature 1.0
top_p 0.95
top_k 20
min_p 0
presence_penalty 1.5

optiq serve 会自动应用这些值;用其他运行时(如 mlx-lm)时请手动传入相同参数,效果更佳。

✅ 快速验证:跑起来之后试试这些

作者在 Apple Silicon 上用 optiq serve 实测过以下场景,全部通过:

  • 问"France 的首都,只回答一个词" → Paris
  • 问"17 × 23" → 391
  • 给出 get_weather 工具后问天气 → 正确输出 get_weather({"city": "Paris"})
  • 输入一张产品发布横幅图片 → 正确读出产品名、日期与特性
  • 让模型写迭代版斐波那契函数 → 基线情况处理正确

你的模型跑起来后,先拿"17 × 23"这类简单问题做冒烟测试是最快的验证方式。

❓ 新手常见问题

Q1:内存不够、加载时崩溃怎么办? 检查点约 22 GB,加上 KV cache 和运行时开销,建议 32 GB 以上统一内存的 Mac;长上下文场景会进一步吃内存,可用 max_tokens 与更短的上下文先做测试。

Q2:加了 --mtp 报错或无效? 这是预期行为——本模型暂不支持 MTP 头加载,请改用 --ngram-draft 16 获得加速。

Q3:mlx-lm 能看到图片吗? 不能。mlx-lm 只加载语言塔权重(model*.safetensors),图片理解请使用 optiq.runtime.engine.OptiqEngine。

Q4:量化会明显掉智商吗? 混合精度正是为了控制精度损失:敏感层(如注意力投影、共享专家)保持 8-bit,其余层下压到 4-bit;512 个张量全部按敏感度配方精确匹配,没有一张量级"踩空"。

总结

Sage-A1.5-OptiQ-4bit 让 35B MoE 智能体模型在 Apple Silicon 上变得真正可本地化:pip install mlx-optiq 装环境 → optiq serve --ngram-draft 16 起服务 → mlx-lm 跑文本、OptiqEngine 看图,三步即可体验 256K 长上下文的智能体推理。建议从 README.md 与 optiq/metadata.json 开始,逐步深入量化细节,祝上手顺利!🎉

登录后查看全文
Sage-A1.5-OptiQ-4bit