3步跑通Sage-A1.5-OptiQ-4bit:optiq serve与mlx-lm新手快速上手教程
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 开始,逐步深入量化细节,祝上手顺利!🎉