Python API实战:fish-audio-drama-3-bf16的load_model与generate调用完全教程

原创2026-10-17 15:48:301,428 阅读
文章标签:人工智能大模型语音音频本地部署

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|> 标签搭剧本式多角色合成。祝你合成愉快!🚀

登录后查看全文
fish-audio-drama-3-bf16