用mlx-vlm Python API跑Qwen3.6-35B-A3B-MLX-4bit:从模型加载到推理的开发者教程
用mlx-vlm Python API跑Qwen3.6-35B-A3B-MLX-4bit:从模型加载到推理的开发者教程
本文是一份面向开发者的完整教程,教你如何用 mlx-vlm 的 Python API 加载 Qwen3.6-35B-A3B-MLX-4bit 多模态模型,并快速完成文本对话与图文推理。模型由 LM Studio 团队基于 Qwen 官方权重做 4-bit MLX 量化,专为 Apple Silicon 优化,无需 GPU 服务器,在 Mac 本地即可运行。
一、模型速览:35B 总参数、3B 激活的多模态 MoE
在动手之前,先花 30 秒了解它"是什么"👇 架构细节可查阅仓库中的 config.json。
| 项目 | 规格 |
|---|---|
| 架构 | Qwen3_5MoeForConditionalGeneration(MoE 混合专家) |
| 总参数 / 激活参数 | 约 35B / 约 3B(每 token 从 256 个专家中路由激活 8 个) |
| 层数 | 40 层(线性注意力为主,每 4 层 1 个全注意力) |
| 上下文长度 | 262,144 tokens(约 256K) |
| 支持模态 | 文本 + 图像 + 视频(image-text-to-text) |
| 量化方式 | 4-bit affine(group_size=64),MoE 门控层保留 8-bit 以保精度 |
| 权重体积 | 约 19GB,分为 4 个 safetensors 分片 |
💡 为什么 A3B 很快? MoE 架构下每次前向只激活约 3B 参数,再叠加 4-bit 量化,因此在 M 系列芯片上推理速度非常可观,同时 256K 长上下文也让它适合处理长文档。
二、环境准备:硬件要求与一键安装 mlx-vlm
硬件要求:
- 🍎 Apple Silicon 芯片(M1 及以上)+ macOS
- 统一内存建议 32GB 及以上(权重约 19GB,还需预留 KV Cache 空间;24GB 机器可尝试,但长上下文可能受限)
安装依赖(一条命令搞定,会自动带上 MLX 框架):
pip install mlx-vlm
三、获取模型:下载 Qwen3.6-35B-A3B-MLX-4bit 权重
模型仓库 ID 为 lmstudio-community/Qwen3.6-35B-A3B-MLX-4bit,两种方式任选:
- 命令行下载(推荐,直接得到本地目录):
hf download lmstudio-community/Qwen3.6-35B-A3B-MLX-4bit --local-dir ./models/qwen3.6-mlx
- LM Studio 图形界面:搜索模型名下载后,直接使用其本地路径即可。
下载完成后,目录内应包含权重分片(如 model-00001-of-00004.safetensors)、config.json 与 tokenizer.json 等文件,权重到分片的映射关系记录在 model.safetensors.index.json 中。
四、模型加载:一行 load 完成
mlx-vlm 的加载 API 非常简洁,核心就是 load 函数:
from mlx_vlm import load
# 传本地目录路径(或仓库 ID 自动拉取)
model, processor = load("./models/qwen3.6-mlx")
model:推理主体,负责generate生成;processor:多模态处理器,自动完成图像/视频切片、以及套用仓库内的 chat_template.jinja 对话模板(该模板原生支持工具调用格式,方便后续接入 Function Calling)。
五、推理实战:从文本对话到图文问答
5.1 文本对话
response = model.generate("用一句话解释什么是 MoE 架构",
max_tokens=256, temperature=0.7)
print(response["response"])
5.2 图文问答(Vision)
图像直接通过 image 参数传入即可,处理器会自动按 16 像素 patch 切分并送入视觉编码器(配置见 preprocessor_config.json):
response = model.generate("这张图片里有什么?",
image="cat.jpg", max_tokens=256)
print(response["response"])
模型同样支持视频输入(video="clip.mp4"),默认按 2fps 抽帧、最多 768 帧,详见 processor_config.json。
5.3 常用采样参数速查
官方推荐的默认参数来自 generation_config.json,可按需调整:
| 参数 | 官方默认 | 说明 |
|---|---|---|
temperature |
1.0 | 温度,调低(如 0.3~0.7)输出更稳定 |
top_p |
0.95 | 核采样阈值 |
top_k |
20 | 候选词数量上限 |
max_tokens |
自定 | 生成长度上限,控制显存/耗时 |
repeat_penalty / stop |
自定 | 抑制重复 / 自定义停止词 |
六、仓库文件速查
| 文件 | 作用 |
|---|---|
| README.md | 模型说明与量化来源(LM Studio 团队 + mlx_vlm) |
| config.json | 架构与量化配置(4-bit / 8-bit 门控) |
| generation_config.json | 官方默认采样参数 |
| chat_template.jinja | 对话模板(含工具调用) |
| processor_config.json | 图像/视频处理器参数 |
| tokenizer.json / vocab.json | 分词器与词表(约 248K 词元) |
| model-00001-of-00004.safetensors ~ model-00004-of-00004.safetensors | 4 个量化权重分片 |
七、常见问题排查(FAQ)
- 加载时报内存不足? 权重本身约 19GB,请确认统一内存 ≥ 24GB 并关闭其他占内存应用;长上下文推理建议 32GB+。
- 图像识别结果异常? 先确认
image路径正确、格式常见(JPG/PNG),必要时把大图缩小后重试。 - 想更快出结果? 适当调小
max_tokens与上下文长度;MoE + 4bit 已经很快,通常无需额外操作。 - 想在命令行直接跑? 无需写脚本,mlx-vlm 自带 CLI:
python -m mlx_vlm.generate "你好" --model ./models/qwen3.6-mlx。
总结
至此你已经完成 mlx-vlm 模型加载 → 文本/图文推理 的全流程:pip install mlx-vlm → 下载 Qwen3.6-35B-A3B-MLX-4bit 权重 → load() 一行加载 → generate() 生成回答。借助 MoE 稀疏激活与 4-bit 量化,这台"35B 级别"的多模态模型就能在你的 Mac 上流畅运行,长文本、图片问答、本地知识库问答都能开箱即用 🚀