3步在MacBook上跑通Hy-Memory-30B-A3B-4bit:MLX本地部署快速教程
3步在MacBook上跑通Hy-Memory-30B-A3B-4bit:MLX本地部署快速教程
Hy-Memory-30B-A3B-4bit 是腾讯混元 MoE 大模型的 4bit 量化 MLX 版本,专为 Apple Silicon 优化,让你的 MacBook 用 16GB 统一内存就能本地部署约 300 亿参数的"长期记忆"模型。本教程带你 3 步完成 MLX 本地部署,一条命令即可体验它的记忆提取与智能推理能力。
部署前速览:硬件与模型参数
⚡ 硬件要求
- Apple Silicon 芯片(M1 及以后)
- 统一内存 ≥ 16GB(推荐 32GB 以上更从容)
- 已安装 Python 3.8+
📊 模型速览
| 特性 | 说明 |
|---|---|
| 总参数 | 约 30B,每 token 仅激活约 3B |
| 架构 | 48 层,128 个路由专家每次激活 8 个 + 1 个共享专家 |
| 量化 | 4bit affine,group size 64(约 4.505 bits/权重) |
| 体积 | 16GB(safetensors 分 4 片) |
| 长项 | 长期记忆写入:决定记什么、怎么记、新证据如何更新记忆库 |
💡 为什么 30B 模型只要 16GB?因为 4bit 量化把权重压缩到原来的约 1/4;而决定"走哪条专家"的路由器(router)保持高精度不量化,保证激活选择不出错,详见 config.json。
第一步:安装 mlx-lm(一条命令)
打开终端(Terminal),执行:
pip install mlx-lm
mlx-lm 是 Apple 官方的 MLX 语言模型工具链,负责加载、推理和下载模型,整个依赖会自动装好。
第二步:一行命令下载并运行推理
python -m mlx_lm generate --model mlx-community/Hy-Memory-30B-A3B-4bit \
--prompt "My name is Alex. I live in Seattle and I'm vegetarian." \
--max-tokens 512 --temp 0.0
- 首次运行会自动下载约 16GB 的权重文件(即仓库中的 model-00001-of-00004.safetensors 等 4 个分片),耐心等进度条走完即可。
- 权重索引结构可查看 model.safetensors.index.json,分词器为 tokenizer.json。
- 之后再次运行会直接命中本地缓存,秒级启动。
如果想在 Mac 上手动克隆完整仓库(离线部署),地址为:
git clone https://gitcode.com/hf_mirrors/mlx-community/Hy-Memory-30B-A3B-4bit
第三步:调出"记忆"能力——推理模式与场景配置
模型自带思考开关(reasoning_effort:no_think / low / high,默认不思考),模板定义在 chat_template.jinja 中。
1)开启深度推理:适合"记忆库如何随新消息更新"这类需要逐步思考的问题:
python -m mlx_lm generate --model mlx-community/Hy-Memory-30B-A3B-4bit \
--chat-template-config '{"reasoning_effort": "high"}' \
--prompt 'Memory bank: ["Alex lives in Seattle"]. New message: "I moved to Portland." Which memory changes, and to what?'
2)记忆提取场景(官方推荐用法):用 system prompt 指定输出 JSON 记忆列表,温度设为 0.0:
python -m mlx_lm generate --model mlx-community/Hy-Memory-30B-A3B-4bit \
--system-prompt 'Extract explicit user facts and preferences from the conversation. Return only a JSON object with a "memories" list of strings.' \
--prompt "My name is Alex. I live in Seattle and I'm vegetarian." \
--max-tokens 512 --temp 0.0
3)Python 调用(接入自己的应用):
from mlx_lm import load, generate
model, tokenizer = load("mlx-community/Hy-Memory-30B-A3B-4bit")
该模型还支持按模板进行工具调用(tool calls),方便嵌入 Agent 工作流。更多参数细节见 README.md。
为什么它能跑在 MacBook 上?原理一句话讲清
MLX 官方的 mlx-lm 原本没有 hy_v3 模型模块,本仓库自带了模型类实现 hy_v3.py,并在 config.json 中通过 "model_file": "hy_v3.py" 指向它——所以 mlx_lm.load 加载权重时会直接构建这个 MoE 模型,无需任何额外配置。
这套实现经过逐位验证:与原版 transformers 的 bfloat16 权重对比,32 个 token 的贪心续写结果完全一致,logits 相关系数 0.9965,精度损失可忽略。
文件导航
| 文件 | 作用 |
|---|---|
| README.md | 模型说明、量化细节与完整用法 |
| config.json | 架构与量化配置(4bit、group 64、model_file 指向) |
| hy_v3.py | Hy V3 MoE 模型的 MLX 实现(仓库自包含,关键!) |
| chat_template.jinja | 聊天模板,支持思考开关与工具调用 |
| model.safetensors.index.json | 权重索引(4 片共 16GB) |
| tokenizer.json | 分词器 |
常见问题
Q:下载很慢或中断怎么办? 直接重跑同一条命令,mlx-lm 会续传/复用已下载的分片。
Q:16GB 内存的机器加载失败? 模型权重本身就约 16GB,建议 32GB 统一内存的机型,或关闭其他大型应用再试。
Q:输出太"急"、不思考? 加上 --chat-template-config '{"reasoning_effort": "high"}' 即可让它先推理、后作答。
恭喜!🎉 到这里你就在 MacBook 上完成了 Hy-Memory-30B-A3B-4bit 的 MLX 本地部署,可以尽情探索它的长期记忆能力了。