Python API实战:fish-audio-drama-3-bf16的load_model与generate调用完全教程
Python API实战:fish-audio-drama-3-bf16的load_model与generate调用完全教程
fish-audio-drama-3-bf16 是 Fish Audio Drama 3 语音合成(Text-to-Speech)模型的 MLX 社区转换版,全程 bfloat16 零量化,专为 Apple Silicon 打造。本文用 Python API 带你完整跑通 load_model 与 generate 两步调用:支持 90+ 语言、声音克隆与多说话人,本地生成 44.1 kHz 高保真语音。🎙️
先搞懂模型:硬件要求与运行性能
这个仓库是 非官方社区转换:把 fishaudio/drama-3 的 block-FP8 routed experts 反量化为 bfloat16,其余权重保持 bfloat16,没有任何量化损失。代价是体积与内存:
| 项目 | 数值 |
|---|---|
| 磁盘占用 | 约 67 GB |
| 生成时峰值内存 | 约 74 GB |
| 最低硬件要求 | 96 GB 内存的 Mac |
| 实测速度(M3 Max / 128 GB) | 约 1.4 倍实时 |
| 流式首块音频延迟(声音已缓存) | 270 ~ 300 ms |
| 模型加载(热缓存)/ 首次调用 | 约 12 s / 约 3 s |
💡 如果你的 Mac 内存不足 96 GB,官方 README 推荐改用约 26 GB 的 4bit 量化版本(mlx-community/fish-audio-drama-3-4bit),但本文聚焦 bf16 满血版。
一键安装步骤:pip 安装 mlx-audio
Drama 3 的支持目前还在 mlx-audio 的 PR 评审中,合并前需要从 PR 分支安装,只需一条命令:
pip install "mlx-audio @ git+https://github.com/stickerdaniel/mlx-audio@fish-drama3"
安装完成后无需其他配置,模型权重会在首次 load_model 时自动按名称从 Hugging Face Hub 拉取并缓存。
load_model 加载模型:一行代码搞定
核心调用只有一行(源码见 README.md):
from mlx_audio.tts.utils import load_model
model = load_model("mlx-community/fish-audio-drama-3-bf16")
加载时发生的事:
- 读取 config.json 中的模型结构:
fish_drama3架构、bfloat16 精度,40 层文本主干(256 专家 MoE)+ 4 层音频解码器(10 个 codebook) - 载入 16 个分片权重
model-00001.safetensors~model-00016.safetensors与音频编解码器 codec.safetensors - 加载分词器 tokenizer.json 与 chat_template.jinja,其中内置了
<|speaker:0|>到<|speaker:15|>共 16 个说话人标签(见 tokenizer_config.json)
模型对象 model 可以复用,后续多次 generate 无需重新加载,声音缓存也会跨调用生效。
generate 生成语音:流式输出实战
最基础的流式合成调用:
for result in model.generate(
text="[sighs] Fine. If we miss it, it's on you.",
ref_audio="reference.wav",
ref_text="Transcript of the reference clip.",
stream=True,
first_chunk_frames=4,
):
print(result.audio.shape) # 44.1 kHz chunks
参数逐个拆解:
| 参数 | 说明 |
|---|---|
text |
要合成的文本,支持 [sighs]、[laughs] 这类拟声/情绪标注 |
ref_audio |
参考音频路径,用于声音克隆 |
ref_text |
参考音频对应文本的转写,必须准确提供 |
stream |
True 时以生成器逐块产出音频,首块延迟仅 270~300 ms |
first_chunk_frames |
首块包含的帧数,调小可进一步降低首包延迟 |
每块 result.audio 是 44.1 kHz 采样率的 numpy 数组,可直接用 soundfile 写出 WAV。不用流式时把 stream 去掉,generate 直接返回完整结果。
采样参数(temperature、top_p、top_k)控制生成的随机性与稳定性。README 给出的 CLI 参考组合是 0.7 / 0.7 / 30:
python -m mlx_audio.tts.generate --model mlx-community/fish-audio-drama-3-bf16 \
--text "[sighs] Fine. If we miss it, it's on you." \
--ref_audio reference.wav --ref_text "Transcript of the reference clip." \
--temperature 0.7 --top_p 0.7 --top_k 30
不想写 Python 时,这条命令行与 API 完全等价,适合作为冒烟测试。
多说话人与声音克隆进阶技巧
这个模型的多说话人(multi-speaker)能力来自词表中的特殊标签(见 tokenizer_config.json):
- 16 个说话人标签:
<|speaker:0|>~<|speaker:15|>,为不同角色分配不同标签 - 多个参考音频:为每个说话人分别提供
ref_audio/ref_text参考对,实现"一人一音色"的剧本式 TTS - 情绪控制:文本内嵌
[sighs]、[laughs]、[whispers]等标注即可改变语气
完整的标签用法与多参考组合方式,建议对照 mlx-audio 仓库 PR 分支中的 docs/models/tts/fish-drama3.md 模型文档(README 有链接指引)。
仓库关键文件速查表
所有文件均为仓库根目录下的相对路径,方便你按需取用:
| 文件 | 作用 |
|---|---|
| config.json | 模型架构:fish_drama3、bfloat16、MoE 专家数、音频解码器 codebook 数 |
| model-00001.safetensors 等 16 个分片 | 模型主权重 |
| codec.safetensors | 音频编解码器(VQ codec)权重 |
| tokenizer.json / special_tokens_map.json / tokenizer_config.json | 分词器与特殊 token 定义 |
| chat_template.jinja | 对话模板 |
| NOTICE | 逐条列出相对原版权重的转换修改 |
| LICENSE | Fish Audio Community License 全文 |
| README.md | 官方使用说明与性能数据 |
常见问题 FAQ
Q1:内存 64 GB 的 Mac 能跑吗? 不能。峰值内存约 74 GB,至少需要 96 GB 统一内存的 Mac。小内存设备请用 4bit 版本。
Q2:第一次调用很慢正常吗? 正常。模型加载约 12 s(热缓存),首次生成约 3 s 额外开销;声音缓存建立后,流式首块音频稳定在 270~300 ms。
Q3:生成的音频是什么格式?
默认 44.1 kHz 单声道 PCM 浮点数据,配合 soundfile 等库可保存为 WAV/MP3 等任意格式。
Q4:商用要注意什么? 模型遵循 LICENSE(Fish Audio Community License):研究与非商用免费;年收入低于 50 万美元可有限商用;对外提供托管 TTS 服务需单独书面授权;且禁止未经本人同意克隆可识别的真实人声。
总结:从 load_model 到 generate 只要 10 行
回看全流程——pip 安装 mlx-audio PR 分支 → load_model("mlx-community/fish-audio-drama-3-bf16") → generate(text=..., ref_audio=..., ref_text=...) 流式拿音频——核心代码不到 10 行。在 96 GB 内存的 Mac 上,你就拥有了一个零量化、支持 90+ 语言和多说话人的本地高保真 TTS 引擎。
想进一步调优?两个方向:用 first_chunk_frames 压低首包延迟、用 <|speaker:N|> 标签搭剧本式多角色合成。祝你合成愉快!🚀