XYZ-Aquila-mini-OptiQ-4bit-REAP-18B 部署指南：如何挑选 Mac、优化推理速度并搭建 API 服务

XYZ-Aquila-mini-OptiQ-4bit-REAP-18B 是一款专为 Apple Silicon（Mac M 系列芯片）优化的多模态大模型，仅占 18.7 GB 磁盘空间，结合 MLX 4bit 量化与 REAP 专家剪枝，一条命令即可启动本地推理或 OpenAI 兼容的 API 服务。本指南面向新手，带你逐步完成 Mac 选型、速度优化与服务搭建。

先看懂它：体积缩小 46%，速度却不降

这个模型来自 XYZAILab/XYZ-Aquila-mini，基于 qwen3_5_moe 架构（40 层，隐藏维度 2048），原生支持图像、视频、音频输入与工具调用。它最大的特点是用了 REAP 专家剪枝：

• 每层路由专家从 256 个砍到 128 个（保留 50%），磁盘体积从 34.6 GB 降到 18.7 GB
• 每个 token 激活的专家数量仍是 8 个（top-8 路由不变）——只是"专家库"变小了，所以更小却不更慢
• 保留的专家是逐位复制自父模型，没有反量化、没有重训练

对比项	父模型	本模型
磁盘占用	34.6 GB	18.7 GB（−46%）
每层路由专家	256	128
每 token 激活专家	8	8（不变）
量化方式	4bit	4bit 混合精度（部分层 8bit）
剪枝后 KL 散度	—	0.232（远低于"明显退化"的 1.0 门槛）

更详细的方法说明可看 README.md 的 Method 章节。

Mac 选型清单：18.7 GB 模型该配多大内存？

模型本体就要 18.7 GB，加上 KV 缓存、视觉塔（vision tower）和系统占用，统一内存（Unified Memory）是关键指标：

统一内存	可行性	说明
16 GB	❌ 不可行	权重已超出总内存，加载会失败
24 GB	⚠️ 勉强可跑	权重 18.7 GB + 短上下文，建议少开后台应用
32 GB	✅ 推荐	日常对话、中等长度上下文都从容
48 GB 及以上	🚀 最佳	频繁 256K 长上下文、多模态与 API 服务

挑选建议：

1. 认准 M 系列芯片（M1 及以上），MLX 原生调用 Metal，N 系列/Intel Mac 不适用
2. 预算允许直接选 32 GB 起步，这是"省心线"
3. 主要用途是长文档分析、长对话或多用户 API，选 48 GB+

快速开始：三步跑起第一次推理

第 1 步：安装 mlx-optiq

pip install mlx-optiq

第 2 步：启动模型（自动下载）

optiq serve --model mlx-community/XYZ-Aquila-mini-OptiQ-4bit-REAP-18B

第 3 步（可选）：用 mlx_lm 写脚本调用

from mlx_lm import load, generate
model, tok = load("mlx-community/XYZ-Aquila-mini-OptiQ-4bit-REAP-18B")
print(generate(model, tok, prompt="Hello", max_tokens=64))

如果希望离线管理模型文件，也可以把仓库 clone 到本地（首次拉取会自动获取 safetensors 权重）：

git clone https://gitcode.com/hf_mirrors/mlx-community/XYZ-Aquila-mini-OptiQ-4bit-REAP-18B

仓库核心文件一览：权重分片 model-00001-of-00005.safetensors ~ model-00005-of-00005.safetensors，以及 optiq/optiq_vision.safetensors（独立的视觉塔权重）。

优化推理速度的 5 个要点

1. 4bit 混合精度量化，显存与速度兼得 模型主体为 4bit、group_size 64 的 affine 量化，对敏感的层（如 out_proj、gate）自动升为 8bit。量化策略记录在 config.json 与 optiq_metadata.json 中（目标 4.5 bpw，实际约 4.99 bpw，共 94 个 8bit 层）。

2. 开启 KV 缓存量化，长上下文不吃内存 kv_config.json 为 10 个自注意力层（3/7/11/…/39）配置了 4bit 或 8bit 的 KV cache。这是它能撑起 256K 上下文（model_max_length: 262144，见 tokenizer_config.json）还能控制内存的关键——长对话时 KV 缓存不再膨胀。

3. 剪枝不剪速度 REAP 只缩小"存起来的专家库"，每个 token 仍激活 8 个专家，单次前向的计算量与父模型基本一致。这是它和普通"砍参数"压缩方案的本质区别。

4. 长文档场景优先用大内存机器跑 权重固定 18.7 GB，速度瓶颈主要在上下文长度。上下文越长，内存带宽压力越大，48 GB 机器 + 关闭无关应用收益最明显。

5. 注意 MTP sidecar 缺席 该检查点不带 MTP（multi-token prediction）模块，不要期望投机解码加速；想要更快的首 token 响应，优先保证内存充裕、避免内存压缩（swap）。

一条命令搭建 API 服务

optiq serve 会起一个 OpenAI 兼容的本地服务，搭好后你的应用只需把 base_url 指向本机即可：

pip install mlx-optiq
optiq serve --model mlx-community/XYZ-Aquila-mini-OptiQ-4bit-REAP-18B

验证服务可用：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"你好，介绍一下你自己"}]}'

由于 chat_template.jinja 内置了 qwen3_coder 工具解析协议，函数调用（tool calling） 开箱即用，可以直接驱动 Agent 应用。

质量怎么保证：剪枝损失有数据背书

• 剪枝排名规则通过校准数据（optiq 六领域混合样本）筛选，对未剪枝父模型测得 KL 散度仅 0.232——经验上超过 1.0 才可见退化
• 同架构、同 50% 保留率下的完整基准（Qwen3.6-35B 系列参考）：Capability Score 80.03 → 76.57，损失集中在 MMLU（−21.4），而程序类能力几乎无损（GSM8K +2.6、IFEval +4.3、HumanEval −1.3）
• 该检查点本身未单独跑基准，详见 README.md Details 表

常见问题 FAQ

Q：能看图、看视频吗？ 能。视觉塔权重在 optiq/optiq_vision.safetensors，分词器已内置图像/视频/音频占位符（见 tokenizer_config.json 的 image_token、video_token），属多模态模型。

Q：剪掉一半专家，回答质量会不会变差？ 保留专家是逐位复制，且每 token 激活数不变；KL 0.232 处于"人工审阅难分辨"的安全区间。

Q：16 GB 的 Mac 能跑吗？ 不建议。权重 18.7 GB 已超过总统一内存，加载阶段就会失败。

Q：上下文长度上限是多少？ 262144 tokens（256K）。受内存限制，24 GB 机器建议控制在万级 token 内，32 GB 以上可放心使用长上下文。

Q：权重文件在哪里核对？ 完整权重名到分片的映射在 model.safetensors.index.json（总大小约 19.17 GB 字节数，5 个分片）。

相关文件清单

文件	作用
README.md	模型说明、细节参数与使用方法
config.json	架构与逐层量化配置（qwen3_5_moe，4bit/8bit）
kv_config.json	自注意力层 KV 缓存 4/8bit 量化配置
optiq_metadata.json	OptiQ 混合精度量化元数据（逐层位宽）
tokenizer_config.json	分词器配置，256K 上下文、多模态 token
chat_template.jinja	对话模板，含工具调用协议
model.safetensors.index.json	权重分片索引
optiq/optiq_vision.safetensors	视觉塔权重

按这份指南走一遍：选对内存 → 装上 mlx-optiq → optiq serve 启动，你手上就有了一台免费、私有、256K 长上下文的本地多模态大模型 API 服务。