如何快速上手Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit:5分钟用mlx-audio生成第一段语音
如何快速上手Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit:5分钟用mlx-audio生成第一段语音
🎙️ 本教程面向新手,带你用 mlx-audio 在 5 分钟内跑通 Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit 文本转语音(TTS)模型:一条命令即可生成第一段语音,还能参考一段音频实现音色克隆,并在 Apple Silicon(M 系列芯片)上享受 MLX 框架带来的高效推理。
这个模型是什么?
Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit 是 Qwen 团队开源的 1.7B 参数语音生成模型,经过以下两点改造,特别适合在 Mac 上本地运行:
- MLX 格式:由
mlx-audio 0.3.0转换而来,充分利用 Apple Silicon 统一内存,推理快、占用低; - 8bit 量化:采用 affine 量化(
bits: 8、group_size: 64,见 config.json),在几乎不损失音质的前提下显著压缩显存需求。
它的核心卖点有两个:
- 12Hz 语音编码:模型名中的
12Hz指语音 tokenizer 的帧率(约 12.5 帧/秒,配置见 speech_tokenizer/config.json),音频以 24kHz 采样率输出,兼顾自然度与生成速度; - CustomVoice 音色克隆:内置 9 位预设音色(含四川话、北京话口音),也可以传入一段参考音频
ref_audio,让模型模仿该音色说话——这就是 "CustomVoice" 的含义。
一键安装步骤:准备运行环境
模型本身不需要手动下载,mlx-audio 会自动从仓库拉取。你只需要安装依赖:
pip install -U mlx-audio
💡 建议使用 Python 3.9+,并在 M 系列芯片的 Mac 上运行以获得最佳体验。
安装完成后,仓库内的 README.md 记录了完整的用法说明,generation_config.json 中则预置了推荐的采样参数(temperature: 0.9、top_k: 50 等),一般无需手动调整。
最快配置方法:一条命令生成语音
打开终端,执行下面这条 CLI 命令(来自 README.md 官方示例):
python -m mlx_audio.tts.generate --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit --text "Hello, this is a test."
首次运行会自动下载并缓存模型文件(model.safetensors 及分片索引 model.safetensors.index.json),之后再生成就快了。运行结束后,你会在当前目录得到一段 .wav 音频文件——恭喜,你的第一段语音已经生成!🎉
用 Python 调用:三步搞定音色克隆
如果想用代码集成,或需要参考音频克隆音色,只需几行 Python(示例同样来自 README.md):
from mlx_audio.tts.utils import load_model
from mlx_audio.tts.generate import generate_audio
model = load_model("mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit")
generate_audio(
model=model,
text="你好,这是一段用参考音色的测试语音。",
ref_audio="path_to_audio.wav", # 你的参考音频,用于模仿音色
file_prefix="test_audio",
)
ref_audio 参数是 CustomVoice 的关键:传入一段清晰的人声录音,模型就会以相似音色朗读 text 中的文字。
多语言与方言支持:能说什么话?
从 config.json 的 codec_language_id 配置可以看到,模型支持 10 种语言:
| 语言 | 语言 | 语言 |
|---|---|---|
| 中文 | 英文 | 日语 |
| 韩语 | 德语 | 法语 |
| 俄语 | 西班牙语 | 意大利语 |
| 葡萄牙语 | —— | —— |
此外还内置两种方言:beijing_dialect(北京话)和 sichuan_dialect(四川话)。
预设音色方面,配置中的 spk_id 字段定义了 9 位角色,其中 eric 带四川口音、dylan 带北京口音,可以直接在应用中切换使用。
常见问题排查
Q:首次运行很慢? 首次需要下载模型并构建缓存,属正常现象;后续生成会明显变快。
Q:生成结果没有按我期望的音色读?
不带 ref_audio 时使用内置音色;想模仿特定声音请确保参考音频是人声清晰、无背景噪音的录音。
Q:内存不够用?
该版本已是 8bit 量化(见 config.json 中 quantization 字段),是本仓库中体积与精度平衡较好的选择;仍不足时可尝试更短的文本或更低内存占用的设备。
Q:词汇表和分词器在哪里? 文本侧的 tokenizer 由 vocab.json、merges.txt 和 tokenizer_config.json 定义;语音侧由 speech_tokenizer/ 目录下的编码器/解码器模型构成,一般无需手动改动。
总结
到这里,你已经完成了 Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit 的完整上手路径:
pip install -U mlx-audio安装依赖;- 一条 CLI 命令生成第一段语音;
- 用
ref_audio参数实现参考音色克隆; - 按需切换 10 种语言与 9 位内置音色。
在 Apple Silicon 上本地运行 TTS,既能保护隐私,又可获得接近实时的生成速度。接下来可以试试:用朋友的 10 秒录音作为 ref_audio,生成一句方言问候语——这就是 CustomVoice 最有趣的地方 🚀