如何自己把Hugging Face模型转成MLX?以Confucius4-R2T2-8bit为例的mlx_audio.convert完整教程
如何自己把Hugging Face模型转成MLX?以Confucius4-R2T2-8bit为例的mlx_audio.convert完整教程
本文以 Confucius4-R2T2-8bit 为例,手把手教你用 mlx_audio.convert 把 Hugging Face 上的语音识别(ASR)模型一行命令转换成 MLX 格式,让支持 28 种语言的低延迟流式识别模型跑在自己的 Apple Silicon 芯片上。
💡 核心关键词:Hugging Face 模型转 MLX、mlx_audio.convert 教程、ASR 模型量化、Confucius4-R2T2-8bit 🏷️ 长尾关键词:MLX 模型转换步骤、mlx 8bit 量化、Apple 芯片本地跑语音识别
一、为什么要把 HF 模型转成 MLX?
Hugging Face 上很多模型默认以 PyTorch 权重发布,直接部署往往依赖 CUDA 环境。而如果你用的是 MacBook / Mac mini / Mac Studio,把模型转成 MLX 格式有明显好处:
| 优势 | 说明 |
|---|---|
| 🍎 原生适配 Apple Silicon | 利用统一内存,无需 GPU 显存单独占用 |
| 📦 体积更小 | 支持 8-bit 量化,权重可从数 GB 压缩到原来的 1/2~1/4 |
| ⚡ 推理更快 | MLX 后端针对 Apple GPU 优化,本地实时推理体验好 |
| 🔒 本地运行 | 音频数据不出本机,适合隐私敏感的语音场景 |
本例中的 Confucius4-R2T2-8bit 正是这样一个转换产物:它把语言模型部分量化到 8-bit,转换后总权重仅约 2.46 GB(见 model.safetensors.index.json 中的 total_size),音频编码器保持 bf16 精度以保证识别质量。
二、认识示例模型:Confucius4-R2T2 是什么?
- 来源:网易有道基于
Qwen3-ASR-1.7B微调的低延迟、append-only 流式 ASR 模型; - 架构:
qwen3_asr,与 Qwen3-ASR 一致(config.json),可被mlx-audio直接加载; - 语言:支持中文、英文、粤语等 28 种语言(config.json);
- 流式特性:按 160ms 音频分块、以已确认文本作为前缀提示的"稳定前缀"协议工作,适合实时字幕、听写等低延迟场景。
关于它的具体转换背景,可以直接看仓库说明:README.md 和版权声明 NOTICE。
三、转换前准备:环境与输入
- 准备一台 Apple Silicon 设备(M 系列芯片),安装 Python 环境;
- 安装 mlx 与 mlx-audio(建议本例使用的 mlx 0.32.2 版本):
pip install mlx mlx-audio
- 准备原始 HF 模型:本例输入是 Hugging Face 上的
netease-youdao/Confucius4-R2T2(bf16 原始权重),无需任何手工修改。
⚠️ 注意:MLX 的量化结果是设备相关的(不同芯片产生的量化张量略有差异),这也是为什么转换时会记录所用设备。本例在 Apple M5 Max 上完成。
四、mlx_audio.convert 一行命令转换(核心步骤)
这是全文最重要的一步 🎯,完整命令如下(同样记录在 README.md 中):
python -m mlx_audio.convert --hf-path netease-youdao/Confucius4-R2T2 \
--mlx-path Confucius4-R2T2-8bit --model-domain stt -q --q-bits 8 --q-group-size 64
参数逐项解读
| 参数 | 值 | 作用 |
|---|---|---|
--hf-path |
netease-youdao/Confucius4-R2T2 |
原始模型地址(HF 仓库名或本地路径) |
--mlx-path |
Confucius4-R2T2-8bit |
转换输出的本地目录 |
--model-domain |
stt |
指定任务域为语音转文本(speech-to-text) |
-q |
— | 开启量化 |
--q-bits |
8 |
量化到 8-bit |
--q-group-size |
64 |
每 64 个参数共享一组量化缩放因子 |
执行完成后,会在 Confucius4-R2T2-8bit 目录下得到一份标准的 MLX 模型文件集:权重(model.safetensors)、权重索引、config.json、tokenizer.json、merges.txt、vocab.json 等,可直接被 mlx-audio 加载。
五、如何验证转换成功?
转换完成后建议做三个"体检",本仓库就是现成的对照样本:
1️⃣ 检查量化配置 —— 打开 config.json,应能看到:
"quantization": { "group_size": 64, "bits": 8, "mode": "affine" }
bits: 8 对应 --q-bits 8,group_size: 64 对应 --q-group-size 64,affine 表示仿射量化(scale + bias 双参数)。
2️⃣ 检查权重索引 —— 在 model.safetensors.index.json 中,被量化的语言模型权重会带有 .scales / .biases 后缀(如 model.layers.10.mlp.down_proj.scales);而 audio_tower.*(音频编码器)保持原始精度、不带量化后缀——这正是"编码器保持 bf16"的落点。
3️⃣ 检查辅助文件 —— generation_config.json(查看)、preprocessor_config.json(Whisper 风格特征提取,128 维 mel)、tokenizer_config.json 等应齐全,说明分词器与音频预处理配置都正确迁移。
六、转换后怎么用?
非流式识别只需几行 Python(示例来自 README.md):
from mlx_audio.stt.utils import load_model, load_audio
model = load_model("mlx-community/Confucius4-R2T2-8bit")
print(model.generate(load_audio("audio.wav"), language="English").text)
如果要体验它真正的卖点——流式低延迟识别,则需要 R2T2 循环:每 160ms 送入一个音频块,把已确认文本作为前缀提示回喂模型,在 | 处截断输出、回滚一个 token 后提交其余部分。该逻辑属于上层封装,本模型仓库提供的是底层权重与配置。
七、常见问题与注意事项
| 问题 | 说明 |
|---|---|
| ❓ 为什么音频编码器没有量化? | 声学编码器对精度敏感,本例将其保持 bf16 以保护识别质量;语言模型(占大头)才做 8-bit 量化 |
| ❓ 换一台 Mac 能直接用我转好的权重吗? | 可以加载,但 MLX 量化结果与设备相关,追求最佳效果建议在本机重新转换 |
| ❓ 想换 4-bit / 更少显存怎么办? | 把 --q-bits 改为 4 等更小值,并按需调整 --q-group-size,精度会有所下降 |
| ⚖️ 授权合规 | 权重受《网易有道模型使用许可协议》约束(见 LICENSE、MODEL_LICENSE_zh),免费商用但月活超 1 亿或年收入超 1 亿人民币需单独申请许可,使用与分发前请通读条款 |
八、总结:三步完成 HF → MLX 转换
- ✅ 安装
mlx+mlx-audio,准备原始 HF 模型; - ✅ 执行一条
python -m mlx_audio.convert ...命令(本例:--model-domain stt -q --q-bits 8 --q-group-size 64); - ✅ 用
config.json的量化字段与权重索引验证产物,即可load_model本地运行。
按同样方法,你可以把其它支持的音频模型(ASR / TTS)批量迁移到 MLX 生态,享受更小体积与更快的 Apple 芯片推理速度。祝转换顺利 🚀