用mlx-vlm Python API跑Qwen3.6-35B-A3B-MLX-4bit:从模型加载到推理的开发者教程

原创2026-11-10 15:18:421,677 阅读
文章标签:大模型多模态模型量化本地部署Qwen

用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,两种方式任选:

  1. 命令行下载(推荐,直接得到本地目录):
hf download lmstudio-community/Qwen3.6-35B-A3B-MLX-4bit --local-dir ./models/qwen3.6-mlx
  1. 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 上流畅运行,长文本、图片问答、本地知识库问答都能开箱即用 🚀

登录后查看全文
Qwen3.6-35B-A3B-MLX-4bit