从 Hugging Face 到 MLX:DeepSeek-R1-Distill-Qwen-1.5B-chat-mlx-16bit 转换原理与复现全流程
从 Hugging Face 到 MLX:DeepSeek-R1-Distill-Qwen-1.5B-chat-mlx-16bit 转换原理与复现全流程
DeepSeek-R1-Distill-Qwen-1.5B-chat-mlx-16bit 是 DeepSeek-R1-Distill-Qwen-1.5B 的 16-bit MLX 转换版,让你无需 GPU、不依赖云端,就能在 Apple Silicon(M1 及以后芯片)的 Mac 上本地快速运行这款深度推理小模型。本文将讲清楚 Hugging Face 权重转换为 MLX 格式的原理,并带你完整复现一遍转换、验证与本地运行流程。
一、项目概览:这是什么模型?
这个仓库只有一样核心东西:同一份 DeepSeek-R1 蒸馏权重,换了一套更贴合 Apple 芯片的存储与计算格式。
| 属性 | 值 |
|---|---|
| 源模型 | deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B(Qwen2 架构) |
| 模型规模 | 约 17.77 亿参数(1,777,088,000) |
| 转换框架 | MLX(Apple 官方数组计算框架) |
| 量化精度 | 16-bit(fp16,接近原模型全精度) |
| 权重格式 | safetensors |
| 许可证 | MIT |
从 config.json 可以看到模型架构:model_type 为 qwen2,num_hidden_layers 为 28 层,hidden_size 为 1536,torch_dtype 为 bfloat16——这就是转换前的"原始规格"。
💡 "Distill"(蒸馏)意味着这个小模型是 DeepSeek-R1 大模型能力的"精华压缩版",用 1.5B 参数保留了较强的推理风格。
二、为什么要做 MLX 转换:它解决了什么问题
Hugging Face 上的模型通常以 PyTorch 的 .bin / .safetensors 格式发布,默认面向 NVIDIA CUDA 生态。直接拿到 Mac 上跑,会有两个痛点:
- 内存拷贝开销大:PyTorch 在 Apple 芯片上运行需要在 CPU 内存与统一内存之间频繁搬运张量;
- 算子未针对芯片优化:MLX 的算子直接调度 Metal GPU,与 CPU 共享统一内存,零拷贝。
MLX 转换做的事,就是"翻译"这三样:
| 翻译对象 | Hugging Face 侧 | MLX 侧 |
|---|---|---|
| 张量存储 | PyTorch 权重 | MLX 张量(Metal 友好布局) |
| 精度 | bfloat16 | 16-bit float |
| 元信息 | config.json 等 |
保留兼容 + safetensors 索引 |
转换只改权重表示,不改模型行为——架构、词表、对话行为完全继承源模型。
三、转换原理拆解:一条命令背后发生了什么
转换由 mlx-lm 工具完成,核心是一条命令(见 conversion_metadata.json 记录的原始命令):
python3 -m mlx_lm.convert --hf-path deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --mlx-path output/DeepSeek-R1-Distill-Qwen-1.5B-mlx-16bit
执行过程可以拆成 4 步:
- 下载并读取源权重:从 Hugging Face 拉取
DeepSeek-R1-Distill-Qwen-1.5B的全部权重与配置; - 逐张量映射架构:把每个权重(如
model.layers.0.self_attn.q_proj.weight、mlp.gate_proj.weight)按 Qwen2 架构写入 MLX 模型结构,保留 bias(该模型 QKV 投影带 bias,见 model.safetensors.index.json); - 定点精度:指定 16-bit,权重以 fp16 精度重新编码——相比 4-bit/8-bit 量化,几乎没有精度损失;
- 落盘输出:写出生成
model.safetensors和索引文件,并附带chat_template.jinja、tokenizer.json等推理必需的周边文件。
转换完成的仓库文件与用途对照:
| 文件 | 作用 |
|---|---|
| model.safetensors | 16-bit MLX 权重本体 |
| model.safetensors.index.json | 权重索引:总大小 3,554,176,000 字节、总参数 1,777,088,000 |
| config.json | 模型架构配置 |
| chat_template.jinja | 对话模板(含 DeepSeek-R1 风格的 think 推理块处理) |
| tokenizer.json / tokenizer_config.json | 分词器(Qwen2Tokenizer) |
| generation_config.json | 默认生成参数:temperature 0.6、top_p 0.95 |
| conversion_metadata.json | 转换元数据:版本、耗时、输出大小 |
| benchmark_results.json | 基准测试结果 |
四、复现全流程:从 0 到本地聊天 🚀
第 1 步:准备环境
需要一台 Apple Silicon Mac 和 Python 3 环境:
pip install mlx-lm==0.31.3
📌 建议锁定版本
0.31.3,与本项目转换时一致,可最大程度保证结果可复现。
第 2 步:(可选)克隆仓库核对文件
git clone https://gitcode.com/hf_mirrors/mlx-community/DeepSeek-R1-Distill-Qwen-1.5B-chat-mlx-16bit
克隆后可对照上文文件表核对权重、索引与配置文件是否完整。
第 3 步:执行转换
python3 -m mlx_lm.convert \
--hf-path deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
--mlx-path output/DeepSeek-R1-Distill-Qwen-1.5B-mlx-16bit
参考本次项目的真实数据(conversion_metadata.json):
- 转换耗时:1980.44 秒(约 33 分钟,主要花在下载 3GB+ 权重上)
- 输出大小:3.3 GB(3,565,664,186 字节)
- 转换日期:2026-09-11
第 4 步:验证与运行
转换完成后,用 CLI 直接开聊:
mlx_lm.chat --model output/DeepSeek-R1-Distill-Qwen-1.5B-mlx-16bit
或在 Python 中调用:
from mlx_lm import load, generate
model, tokenizer = load("output/DeepSeek-R1-Distill-Qwen-1.5B-mlx-16bit")
response = generate(model, tokenizer, prompt="你好,请介绍一下自己", max_tokens=256)
print(response)
看到流畅的中文回复,即表示转换链路全部打通 ✅
五、实测性能:M1 芯片上有多快?
本项目在 Apple M1(8GB 统一内存) 上做了 5 轮平均测试(单轮最大 256 tokens),完整数据见 benchmark_results.json:
| 指标 | 数值 |
|---|---|
| 生成速度 | 16.97 tokens/s |
| 首 token 延迟(TTFT) | 58.94 ms |
| 峰值显存占用 | 280.3 MB |
对日常对话和轻量推理来说,这个速度已经"打字追不上"了;280MB 的峰值占用也说明 1.5B 级模型在 8GB 内存的 Mac 上非常从容。
六、量化位宽怎么选?
本仓库是 16-bit 版本,适合内存充裕的机器。结合项目 README 的建议,可按硬件对号入座:
| 你的硬件 | 推荐量化 | 理由 |
|---|---|---|
| M1/M2(8GB) | 4-bit | 质量与内存的最佳平衡,可同时开其他应用 |
| M1/M2 Pro/Max(16–32GB) | 8-bit | 质量更好、内存依然可控 |
| M2/M3/M4 Ultra(64GB+) | 16-bit | 全精度、无质量损失 |
一句话:位宽越低省内存、损失越大;16-bit 是"研究/评测/内存不是问题"场景的首选。
七、常见疑问与使用限制
- 能在 Windows / 普通 PC 上跑吗? 不能。MLX 依赖 Apple Silicon 的统一内存架构,必须 M1 及以后的 Mac。
- 16-bit 和原模型效果一样吗? 架构与行为完全继承源模型,16-bit 下的精度损失微乎其微,适合做基线评测。
- 长文本会掉速吗? 低量化(4/8-bit)在超过 8K tokens 的超长上下文下性能可能下降;16-bit 相对更稳。
- 这只是权重转换,不是微调:模型的能力边界就是 DeepSeek-R1-Distill-Qwen-1.5B 本身。
八、总结
这个项目用一条 mlx_lm.convert 命令,把 Hugging Face 上的 DeepSeek-R1-Distill-Qwen-1.5B 完整"搬"进了 Apple 生态:16-bit 保真权重 + safetensors 格式 + 对话模板与分词器一应俱全,在 M1 上即可跑出约 17 tokens/s 的本地推理速度。
如果你想把自己的常用模型也搬到 Mac 上跑,照第四节的 4 步流程(装 mlx-lm → 转换 → 核对输出 → 运行验证)操作即可,全程无需编写任何模型代码。
延伸阅读(仓库内文件)
- 完整说明与使用示例:README.md
- 模型架构参数:config.json
- 转换命令与元数据:conversion_metadata.json
- 基准测试原始数据:benchmark_results.json