Zonos-v0.1 开源 TTS 全指南:从零克隆声音、细粒度情感控制的 Transformer 与 Hybrid 双模型实战

原创2026-10-14 12:33:201,632 阅读
文章标签:语音音频基础模型AI 应用

Zonos-v0.1 开源 TTS 全指南:从零克隆声音、细粒度情感控制的 Transformer 与 Hybrid 双模型实战

本指南以 Zonos 仓库 README.md 为主线,结合 zonos/model.py、zonos/conditioning.py、gradio_interface.py 等源码,系统讲解 Zonos-v0.1 的架构原理、安装部署(含 Docker)、Python API 调用、声音克隆与多语言 TTS 实战,以及每一条 conditioning 参数的取值范围与调优技巧,帮助你从零搭建一个可复现、可扩展的 44kHz 高质量 TTS 服务。

Zonos-v0.1 端到端架构:文本经 eSpeak 音素化后,由 Prefix Conditioner 与 Transformer/Hybrid Backbone 预测 DAC token,最终由 DAC 解码器还原为 44kHz 语音

Zonos-v0.1 是一个基于超过 20 万小时多语言语音数据训练的开源权重文本转语音(TTS)模型。它由 Zyphra 发布,主打零样本(zero-shot)声音克隆与细粒度音频控制:仅凭一段几秒钟的参考音频即可克隆说话人音色,同时可以精确调节语速、音高变化、音频质量以及快乐、恐惧、悲伤、愤怒等情绪。模型原生输出 44kHz 语音,官方宣称在表达力与质量上可与一流商用 TTS 服务比肩。

本文面向两类读者:一是想在本地快速跑通 Zonos 并体验声音克隆的开发者;二是想深入理解其 conditioning 机制、采样算法与 backbone 实现,以便做二次开发或精细调参的研究者。读完本文,你将掌握完整的安装路径、Python 最小可运行示例、Gradio WebUI 的每个滑块含义、Docker 部署方案,以及每一类 conditioning 输入的取值范围、默认值和"最佳实践"。


一、模型总览:两种骨干网络与端到端流程

1.1 Zonos 是什么

根据仓库 README.md 的描述,Zonos-v0.1 具备以下核心能力:

  • 零样本 TTS 与声音克隆:输入目标文本 + 一段 10–30 秒的说话人样本,即可生成高质量 TTS 输出;
  • 音频前缀(audio prefix)输入:文本之外可再附加一段音频前缀,进一步提升与目标说话人的匹配度,还能触发诸如"耳语"这类仅靠说话人 embedding 难以复现的行为;
  • 多语言支持:英语、日语、中文、法语、德语;
  • 音频质量与情绪控制:语速、音高、最大频率、音频质量,以及幸福、愤怒、悲伤、恐惧等情绪均可微调;
  • 速度:在 RTX 4090 上实时率(real-time factor)约为 2x,即每 1 秒计算可生成约 2 秒音频(此为官方 README 声明,实际以运行环境为准);
  • Gradio WebUI:仓库自带开箱即用的 Web 界面;
  • Docker 一键部署:仓库内置 Dockerfile 与 docker-compose.yml,简化安装与部署。

1.2 端到端生成流程

README 用一句话概括了 Zonos 的架构:"text normalization and phonemization via eSpeak, followed by DAC token prediction through a transformer or hybrid backbone",即:

  1. 文本预处理:对输入文本做数字/符号归一化(zonos/conditioning.py 中的 normalize_numbers、normalize_jp_text 等),再通过 eSpeak 转成带重音标记的音素序列;
  2. 前缀条件编码(Prefix Conditioning):把音素、说话人 embedding、情绪向量、语速、fmax、pitch_std、language_id 等各类条件拼装并投影到同一维度,构成前缀序列;
  3. DAC token 预测:由 Transformer 或 Hybrid(Mamba+Attention) 骨干网络自回归式预测 DAC(Descript Audio Codec)token,支持延迟模式(delay pattern)与 classifier-free guidance(CFG)采样;
  4. DAC 解码:将 9 个 codebook 的 token 序列交由 zonos/autoencoder.py 中的 DAC 自编码器(descript/dac_44khz)解码,还原为 44.1kHz 的波形。

从源码结构看,以上四个环节在 zonos/model.py 的 Zonos 类中被封装为四个核心成员:autoencoder(DAC 解码器)、backbone(Transformer/Hybrid 骨干)、prefix_conditioner(条件前缀编码器)、spk_clone_model(说话人 embedding 模型,首次调用 make_speaker_embedding 时才惰性加载)。


二、系统要求与依赖

2.1 系统要求

项目 要求
操作系统 Linux(推荐 Ubuntu 22.04/24.04)、macOS
GPU 6GB+ 显存;Hybrid 模型额外要求 Nvidia 3000 系列或更新的 GPU

注意:Zonos 也可以在 CPU 上运行(前提是内存充足),但速度远慢于 GPU,通常不足以支撑交互式使用。

2.2 系统级依赖:eSpeak-ng

Zonos 依赖 eSpeak 库进行音素化(phonemization)。以 Ubuntu 为例:

apt install -y espeak-ng # 适用于 Ubuntu
# brew install espeak-ng # 适用于 MacOS

在 pyproject.toml 的依赖中,phonemizer>=3.3.0 负责调用 eSpeak 后端;在 macOS 上,zonos/conditioning.py 会通过环境变量 PHONEMIZER_ESPEAK_LIBRARY 指向 Homebrew 安装的 libespeak-ng.dylib。

2.3 Python 依赖与安装方式

官方推荐使用 uv 进行安装(可用 pip install -U uv 安装)。核心依赖见 pyproject.toml,包括 torch>=2.5.1、torchaudio>=2.5.1、transformers>=4.48.1、gradio>=5.15.0、phonemizer、inflect、kanjize、sudachipy 等。

方式一:新建 uv 虚拟环境安装(推荐)

uv sync
uv sync --extra compile # 可选,运行 hybrid 模型需要
uv pip install -e .

方式二:用 uv 安装到当前激活环境

uv pip install -e .
uv pip install -e .[compile] # 可选,运行 hybrid 模型需要

方式三:用 pip 安装到当前激活环境

pip install -e .
pip install --no-build-isolation -e .[compile] # 可选,运行 hybrid 模型需要

[compile] 可选依赖包含 flash-attn>=2.7.3、mamba-ssm>=2.2.4、causal-conv1d>=1.5.0.post8(见 pyproject.toml)。其中 mamba-ssm 是运行 hybrid 模型的必要条件,而 flash-attn/mamba-ssm/causal-conv1d 在 pyproject.toml 中被列入 no-build-isolation-package,编译安装前请确认 CUDA 环境就绪。

2.4 验证安装

仓库提供了最小示例脚本 sample.py:

uv run sample.py
# python sample.py

运行成功后会在项目根目录生成 sample.wav。该脚本的逻辑与下文"Python 快速上手"一致。


三、Python 快速上手:最小生成流程

README 给出了完整的 Python 示例,这是使用 Zonos 的最核心路径。下面逐行拆解其关键 API 与参数。

import torch
import torchaudio
from zonos.model import Zonos
from zonos.conditioning import make_cond_dict
from zonos.utils import DEFAULT_DEVICE as device

# model = Zonos.from_pretrained("Zyphra/Zonos-v0.1-hybrid", device=device)
model = Zonos.from_pretrained("Zyphra/Zonos-v0.1-transformer", device=device)

wav, sampling_rate = torchaudio.load("assets/exampleaudio.mp3")
speaker = model.make_speaker_embedding(wav, sampling_rate)

cond_dict = make_cond_dict(text="Hello, world!", speaker=speaker, language="en-us")
conditioning = model.prepare_conditioning(cond_dict)

codes = model.generate(conditioning)

wavs = model.autoencoder.decode(codes).cpu()
torchaudio.save("sample.wav", wavs[0], model.autoencoder.sampling_rate)

3.1 加载模型:Zonos.from_pretrained

zonos/model.py 中的 from_pretrained 会:

  1. 通过 hf_hub_download 从 Hugging Face Hub 下载 config.json 与 model.safetensors;
  2. 解析配置为 ZonosConfig(见 zonos/config.py,含 eos_token_id=1024、masked_token_id=1025 等);
  3. 根据配置自动选择 backbone:若 config.backbone.ssm_cfg 为空(纯 Transformer)则优先路由到纯 PyTorch 实现的 TorchZonosBackbone(见 zonos/backbone/init.py 与 zonos/backbone/_torch.py,代码注释指出该选择"for increased performance and lower latency");否则使用 mamba-ssm 实现的 Mamba+Attention 混合骨干(zonos/backbone/_mamba_ssm.py);
  4. 以 torch.bfloat16 精度加载权重。

DEFAULT_DEVICE 定义在 zonos/utils.py 中:优先使用当前 CUDA 设备,否则回退到 CPU(macOS 的 MPS 当前被注释禁用)。

两个可选模型 id:

  • Zyphra/Zonos-v0.1-transformer:纯 Transformer 骨干,入门与 CPU/低显存场景首选;
  • Zyphra/Zonos-v0.1-hybrid:Mamba + Attention 混合骨干,需要 [compile] 扩展包与 Nvidia 3000 系以上 GPU,支持 vqscore_8、ctc_loss、dnsmos_ovrl、speaker_noised 等更多 conditioning。

3.2 生成说话人 embedding:make_speaker_embedding

wav, sampling_rate = torchaudio.load("assets/exampleaudio.mp3")
speaker = model.make_speaker_embedding(wav, sampling_rate)

底层实现位于 zonos/speaker_cloning.py 的 SpeakerEmbeddingLDA:

  • 从 Zyphra/Zonos-v0.1-speaker-embedding 仓库下载 ResNet293_SimAM_ASP_base.pt(ResNet293 + SimAM + 注意力统计池化)与 ResNet293_SimAM_ASP_base_LDA-128.pt(128 维 LDA 投影);
  • 输入音频先重采样到 16kHz,提取 80 维 log-Fbank 特征,经 ResNet293 提取 256 维 embedding,再经 LDA 线性层投影得到说话人向量;
  • make_speaker_embedding 返回 bfloat16 且带 batch 维的 embedding(zonos/model.py)。

参考音频建议:只含语音的干净片段;同一说话人的多段干净样本可拼接成长样本(可能提升克隆质量);若启用去噪后仍输出嘈杂,建议先做音源分离再克隆。

3.3 构造条件字典:make_cond_dict

make_cond_dict 是构造模型条件输入的最重要辅助函数(zonos/conditioning.py),其签名与默认值如下:

make_cond_dict(
    text: str = "It would be nice to have time for testing, indeed.",
    language: str = "en-us",
    speaker: torch.Tensor | None = None,
    emotion: list[float] = [0.3077, 0.0256, 0.0256, 0.0256, 0.0256, 0.0256, 0.2564, 0.3077],
    fmax: float = 22050.0,
    pitch_std: float = 20.0,
    speaking_rate: float = 15.0,
    vqscore_8: list[float] = [0.78] * 8,
    ctc_loss: float = 0.0,
    dnsmos_ovrl: float = 4.0,
    speaker_noised: bool = False,
    unconditional_keys: Iterable[str] = {"vqscore_8", "dnsmos_ovrl"},
    device: torch.device | str = DEFAULT_DEVICE,
)

值得注意的实现细节:

  • 默认会生成随机说话人 embedding(当 speaker=None 时),因此不传 speaker 也能合成语音;
  • language 必须属于 supported_language_codes(zonos/conditioning.py 中列出的一百多个 eSpeak 兼容语言代码,包含 en-us、ja、zh、fr-fr、de 等),否则断言失败;内部会把语言代码映射为 language_id;
  • emotion 向量在送入模型前会做 归一化(除以总和),其 8 个维度顺序固定为 Happiness、Sadness、Disgust、Fear、Surprise、Anger、Other、Neutral;
  • unconditional_keys 中列出的键会被从条件字典中删除(配合 prepare_conditioning 生成无条件分支);
  • 所有标量/列表会被转为 (1, 1, -1) 形状的 tensor 并搬到目标设备。

3.4 准备条件:prepare_conditioning

conditioning = model.prepare_conditioning(cond_dict)

zonos/model.py 的实现会调用 PrefixConditioner(zonos/conditioning.py):

  • 按配置构建各子条件器(EspeakPhonemeConditioner 负责文本→音素→embedding,FourierConditioner 负责连续值条件的傅里叶编码,IntegerConditioner 负责整数条件,PassthroughConditioner 直接透传说话人向量);
  • 若 cond_dict 缺少某个必需键(required_keys),会抛出 ValueError;
  • 结果在序列维度拼接后,经 LayerNorm 归一化并线性/MLP 投影到 backbone 的 d_model;
  • 最后把条件分支与无条件分支拼接(torch.cat),为后续 CFG 采样做准备——无条件分支默认取 required_keys 对应的值,或使用各条件器的学习到的无条件向量(uncond_type="learned")。

3.5 自回归生成:generate

codes = model.generate(conditioning)

generate 的关键参数(zonos/model.py):

参数 默认值 说明
max_new_tokens 86 * 30 最大新 token 数,对应约 30 秒音频(86 token/秒)
cfg_scale 2.0 classifier-free guidance 强度,1.0 目前会触发断言(未实现)
batch_size 1 批量大小
sampling_params dict(min_p=0.1) 采样参数,见下文"采样算法"
progress_bar True 是否显示进度条
callback None 每步回调 (frame, step, max_steps),可用于自定义停止逻辑与进度上报(Gradio 界面即用它驱动进度条)

生成过程的关键机制:

  1. 延迟模式(delay pattern):使用 zonos/codebook_pattern.py 的 apply_delay_pattern 将 9 个 codebook 的 token 按对角延迟排布(类似 MusicGen/RVQ delay pattern),解码端用 revert_delay_pattern 还原;
  2. 音频前缀:audio_prefix_codes 若提供(形状 [bsz, 9, prefix_audio_seq_len]),会被填入 codes 的前缀位置,使模型继续生成而不是从零开始;
  3. CFG:条件/无条件两路 logits 按 uncond + (cond - uncond) * cfg_scale 融合(zonos/model.py);
  4. EOS 处理:仅允许 codebook 0 预测 EOS token(logit_bias[:, 1:, self.eos_token_id] = -inf),检测到 EOS 后逐步把后续 codebook 填为 EOS,最多再生成 9 步收尾;
  5. 加速:hybrid(mamba_ssm)骨干支持 CUDA Graphs(can_use_cudagraphs),纯 torch 骨干则默认用 torch.compile(dynamic=True) 加速(zonos/model.py);
  6. 生成完毕后把 ≥1024 的 token(masked/EOS 占位)填 0,并按实际长度截断。

3.6 解码与保存

wavs = model.autoencoder.decode(codes).cpu()
torchaudio.save("sample.wav", wavs[0], model.autoencoder.sampling_rate)

zonos/autoencoder.py 中的 DACAutoencoder 封装了 Hugging Face 的 descript/dac_44khz 模型:

  • codebook_size 与 num_codebooks(9 个 codebook)取自 DAC 配置;
  • sampling_rate 为 44_100,因此保存的 wav 是 44.1kHz 原生采样率;
  • preprocess 会把任意采样率的音频重采样到 44.1kHz 并 padding 到 512 的整数倍,encode/decode 分别对应 DAC 的编解码(解码在支持设备上用 float16 autocast 加速)。

需要注意:README 提示"最小示例每次运行都要重新加载模型",因此重复采样请优先使用 Gradio 界面(模型常驻内存),而不是反复执行脚本。


四、Gradio WebUI:可视化调参与批量生成

4.1 启动

uv run gradio_interface.py
# python gradio_interface.py

启动后默认监听 0.0.0.0:7860(gradio_interface.py),可通过环境变量 GRADIO_SHARE 控制是否开启 share 链接。界面会自动检测当前 backbone 是否支持 hybrid 架构:若未安装 mamba-ssm,则模型下拉框只提供 transformer 模型(gradio_interface.py)。

4.2 界面能力

gradio_interface.py 的 generate_audio 把 UI 输入映射到后端 API,主要分为四组:

输入区

  • Zonos Model Type:选择 Zyphra/Zonos-v0.1-transformer 或 Zyphra/Zonos-v0.1-hybrid;
  • Text to Synthesize:待合成文本(约 500 字符上限);
  • Language Code:从 supported_language_codes 中选择;
  • Optional Prefix Audio:可选音频前缀(默认 assets/silence_100ms.wav),模型将从该音频之后继续生成;
  • Optional Speaker Audio:可选说话人参考音频(用于克隆),首次上传时通过 make_speaker_embedding 计算并缓存 embedding,只有换了文件才重新计算;
  • Denoise Speaker?:是否开启说话人去噪(对应 speaker_noised)。

Conditioning 参数

  • DNSMOS Overall:1.0–5.0,默认 4.0(仅 hybrid);
  • Fmax (Hz):0–24000,默认 24000;
  • VQ Score:0.5–0.8,默认 0.78(仅 hybrid);
  • Pitch Std:0–300,默认 45;
  • Speaking Rate:5–30,默认 15。

Generation 参数

  • CFG Scale:1.0–5.0,默认 2.0;
  • Seed:默认 420,可随机化(每次生成前自动随机 seed 并回显实际使用的 seed,便于复现)。

Sampling / 高级参数(详见下文"采样算法"与"高级技巧")

  • NovelAI Unified Sampler:Linear(默认 0.5)、Confidence(默认 0.4)、Quadratic(默认 0.0);
  • Legacy sampling:Top P、Min K(代码中对应 top_k)、Min P;
  • Unconditional Toggles:勾选后对应 conditioning 置为无条件(默认勾选 emotion);
  • Emotion Sliders:Happiness/Sadness/Disgust/Fear/Surprise/Anger/Other/Neutral 八个 0–1 滑块。

UI 会根据模型实际拥有的 conditioner 动态显隐控件(gradio_interface.py):例如 transformer 模型没有 vqscore_8、dnsmos_ovrl、speaker_noised,对应控件会自动隐藏。


五、Conditioning 机制详解:每个参数的含义与取值

README 本身未逐条展开 conditioning,但仓库中的 CONDITIONING_README.md 与 zonos/conditioning.py 给出了权威说明。本节结合两者,按模型支持范围分组讲解。

5.1 两类模型都支持的 conditioning

espeak(文本音素化)

  • 类型:EspeakPhonemeConditioner
  • 职责:负责文本清洗(clean)、音素化(phonemize)、token 化与 embedding。文本预处理管线包含:非日文文本的数字/金额/序数词展开(normalize_numbers,如 $5.50 → "five dollars, fifty cents"),日文文本的 NFKC 归一化与假名/汉字读音化(normalize_jp_text,借助 sudachipy 分词与 kanjize 数字转汉字);
  • 进阶玩法:如果想改变某个词的发音,或直接输入原始音素(raw phonemes),可以在此层操作。音素表覆盖拉丁字母、标点与完整的 IPA 符号集(zonos/conditioning.py)。

speaker(说话人向量)

  • 类型:PassthroughConditioner,cond_dim=128,uncond_type=learned,projection=linear
  • 说明:来自 Zyphra/Zonos-v0.1-speaker-embedding 的说话人 embedding,支持任意长度输入。建议输入只含语音的干净参考片段;多段干净样本可拼接以提升克隆效果;超长片段建议裁掉不含语音的背景音乐段落。

emotion(情绪向量)

  • 类型:FourierConditioner,input_dim=8,uncond_type=learned
  • 顺序:Happiness、Sadness、Disgust、Fear、Surprise、Anger、Other、Neutral;
  • 注意:与文本情感纠缠(如愤怒文本更容易被调成愤怒,但想调成悲伤则效果打折);与 pitch_std 纠缠(更大的 pitch_std 对应更情绪化);与 VQScore/DNSMOS 纠缠(这两个指标偏好中性语音);
  • 负向提示技巧:CFG 的无条件分支若不用真无条件值,而是设成一个"高度中性"的情绪向量,会夸大情绪表达(把模型推离中性)。

fmax(最大频率)

  • 类型:FourierConditioner,min_val=0,max_val=24000,uncond_type=learned
  • 取值:22050 或 24000(对应 44.1/48kHz);由于模型采样率是 44.1kHz,两种取值在真实最大频率上不应有差异,但代表不同的数据切片,会产生略微不同的发声(voicing);较低值通常导致更低的质量;
  • 声音克隆建议使用 22050。

pitch_std(音高标准差)

  • 类型:FourierConditioner,min_val=0,max_val=400,uncond_type=learned
  • 取值建议:普通语音 20–45;表达性语音 60–150;更高通常产生更"疯狂"的样本。

speaking_rate(语速)

  • 类型:FourierConditioner,min_val=0,max_val=40,uncond_type=learned
  • 单位:每秒读取的音素数。30 非常快,10 偏慢;
  • 长文本注意:要保证给定语速下文本能在生成长度内读完。例如生成长度 10 秒、输入 300 音素时,要么语速 30(极快),要么生成更长的样本。模型单次生成上限约 30 秒,超长文本建议切段多次生成,而不是用不真实的低语速强行一次读完(不现实的语速对模型而言是分布外输入,易产生不良效果)。

language_id(语言标识)

  • 类型:IntegerConditioner,min_val=-1,max_val=126,uncond_type=learned
  • 说明:指示输出语言。映射表即 supported_language_codes 列表(zonos/conditioning.py),make_cond_dict 会自动把语言代码转换为对应的 id。

5.2 仅 hybrid 模型支持的 conditioning

vqscore_8(每 1/8 段目标 VQScore)

  • 类型:FourierConditioner,input_dim=8,min_val=0.5,max_val=0.8,uncond_type=learned
  • 说明:期望的输出音频 VQScore(无监督语音干净度估计)。高质量语音推荐 0.78。8 个维度对应音频的连续 8 等分(8 秒音频的第一个维度只代表第 1 秒)。推理时一般 8 维设成相同值;
  • 注意:VQScore 与表达力强相关——越高的 VQScore 越接近中性/干净,表达性语音建议置为 unconditional。

ctc_loss(CTC 损失值)

  • 类型:FourierConditioner,min_val=-1.0,max_val=1000,uncond_type=learned
  • 说明:编码训练时 CTC(时序分类)模型给出的"转录与音频匹配程度"。推理时始终用低值(如 0.0 或 1.0)。

dnsmos_ovrl(DNSMOS 总分)

  • 类型:FourierConditioner,min_val=1,max_val=5,uncond_type=learned
  • 说明:输出音频的 MOS 评分。与 VQScore 类似,但与情绪、语言有更强纠缠。英语干净中性语音设 4.0,否则建议 unconditional。

speaker_noised(说话人是否含噪)

  • 类型:IntegerConditioner,min_val=0,max_val=1,uncond_type=learned
  • 说明:指示说话人 embedding 是否带噪。置 True 可让模型**清洗(去噪)**说话人 embedding,此时 VQScore 与 DNSMOS 对清洗效果的影响更大——含噪输入建议置 True 并给高 VQScore;若克隆输出回声感强或行为异常,置 True 通常有帮助。

5.3 无条件(unconditional)机制

PrefixConditioner.forward 会先校验 cond_dict 必须覆盖 required_keys(zonos/conditioning.py),否则抛 ValueError。make_cond_dict 的 unconditional_keys 参数会把对应键从字典中移除;对被移除的键,prepare_conditioning 生成无条件分支时使用各 conditioner 的学习到的无条件向量。在 Gradio 中,这就是"Unconditional Toggles":勾选即让模型"自动脑补"该条件(如 emotion 默认勾选,让模型自己决定情绪基调)。


六、采样算法:从 temperature 到 NovelAI Unified Sampler

README 未展开采样细节,但 zonos/sampling.py 提供了完整实现,且 Gradio 界面暴露了全部采样参数。理解这些参数有助于稳定输出质量。

generate 的 sampling_params 会原样传给 sample_from_logits(zonos/sampling.py),关键参数:

参数 默认 说明
temperature 1.0 随机度;设 0 时完全贪心(argmax)
top_p 0.0 nucleus 采样(累积概率截断),0 表示禁用;典型 0.1–0.9
top_k 0 只从 top-k 中采样,0 表示禁用
min_p 0.0 以最大 token 概率为基准的比例截断,典型 0.01–0.2;过高可能采不到任何 token 导致静音
linear / conf / quad 0.0 NovelAI Unified Sampler 三个系数
repetition_penalty 3.0 重复惩罚系数(窗口默认 2 个 token),通过 modify_logit_for_repetition_penalty 施加

Unified Sampler 要点(源码注释):linear 取值 0–1,决定 token 的"新异程度",越低越出人意料(但需要多 roll);conf(置信度)约 -2.0 * quad 到 2.0;quad(二次惩罚)约 -2.0 到 2.0。起点建议 quad = 1/3 - linear * 4/15,conf = -quad / 2。启用 Unified Sampler 时 temperature 应设为 1.0。

执行顺序(从代码实现可见):先应用重复惩罚 → softmax(除 temperature)→ 若 linear>0 应用 Unified Sampler → top_p → top_k → min_p → 最后按 multinomial 采样。multinomial 对 num_samples=1 采用 Gumbel-max 技巧(argmax(p / q),q 为指数分布),等价于多项式采样。


七、音频前缀(Audio Prefix):从参考音频"接着往下说"

README 将音频前缀列为重要特性:"Add text plus an audio prefix for even richer speaker matching. Audio prefixes can be used to elicit behaviours such as whispering"。其实现要点:

  1. Gradio 界面的 generate_audio 中,前缀音频先经 mean(0) 取单声道,再调用 autoencoder.preprocess(重采样到 44.1kHz + padding)与 autoencoder.encode 得到 audio_prefix_codes(形状 [1, 9, prefix_len]);
  2. generate 中这些 codes 被填入自回归序列前缀(zonos/model.py),模型从该音频之后继续生成;
  3. 默认 UI 使用 assets/silence_100ms.wav 作为"静音前缀",仓库 assets 目录也提供了该文件。

典型用法:给定一段目标说话人的长音频作为前缀,配合克隆 embedding,可显著提升音色匹配度;若要复现耳语等难以从静态 embedding 中学到的行为,可在前缀音频中提供示范片段。


八、Docker 部署

README 提供了两条 Docker 路径,仓库中的 Dockerfile 与 docker-compose.yml 已就绪。

8.1 方式一:docker compose 启动 Gradio 服务

git clone https://github.com/Zyphra/Zonos.git
cd Zonos

# 启动 Gradio WebUI
docker compose up

docker-compose.yml 的关键配置:使用 runtime: nvidia、network_mode: host、环境变量 NVIDIA_VISIBLE_DEVICES=0 指定 GPU,容器启动命令为 python3 gradio_interface.py。若你的 Docker 环境不支持 host 网络或 GPU runtime,需要按实际环境调整。

8.2 方式二:构建镜像进入容器开发

docker build -t zonos .
docker run -it --gpus=all --net=host -v /path/to/Zonos:/Zonos -t zonos
cd /Zonos
python sample.py # 会在 /Zonos 下生成 sample.wav

Dockerfile 基于 pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel,安装 uv 与 espeak-ng 后,执行 uv pip install --system -e . 与 uv pip install --system -e .[compile]——注意它默认同时安装了 [compile] 扩展(flash-attn、mamba-ssm、causal-conv1d),因此镜像同时支持 transformer 与 hybrid 两种模型,但构建时间会明显更长。


九、进阶实践与常见问题

9.1 如何复现同一结果

设置固定随机种子即可:

torch.manual_seed(421)  # sample.py 中即使用该种子

generate 内部还涉及 torch.compile/CUDA Graphs,不同硬件上的数值可能有细微差异,但同一设备同一 seed 通常可稳定复现。Gradio 界面会回显实际使用的 seed。

9.2 长文本处理策略

结合 speaking_rate 一节可知:模型单次生成上限约 30 秒(max_new_tokens = 86 * 30,86 tokens/秒)。对超长文本,优先切段多次生成再拼接,避免用不真实低语速把全部音素塞进一次生成。

9.3 表达性语音 vs 干净语音的调参路线

  • 表达性:pitch_std 60–150;vqscore_8 与 dnsmos_ovrl 置 unconditional;可用高度中性的 emotion 向量做 CFG 负向提示放大情绪;
  • 干净中性:fmax 22050/24000、speaking_rate 15、pitch_std 20–45、vqscore_8 0.78、dnsmos_ovrl 4.0;
  • 克隆含噪样本:speaker_noised=True + 高 VQScore,必要时先做音源分离。

9.4 常见坑

  • cfg_scale=1.0:当前 generate 会断言失败(TODO 项),如需"无 CFG"请用接近 1 的值或自行改源码;
  • 缺失依赖报错:EspeakBackend 初始化失败通常是系统未装 espeak-ng;hybrid 模型加载失败通常是未装 mamba-ssm(Gradio 会降级只显示 transformer);
  • macOS MPS:DEFAULT_DEVICE 当前禁用 MPS(zonos/utils.py 中代码被注释),macOS 上会回退 CPU;
  • Windows:README 说明实验性 Windows 支持见官方 fork(本文按仓库说明如实转述,未提供外部链接)。

十、进一步阅读指引

若想深入源码,建议按以下顺序阅读:

  1. README.md:项目总览与使用入口(本文主题文档);
  2. CONDITIONING_README.md:全部 conditioning 的权威说明(本文第五节已归纳);
  3. zonos/model.py:Zonos 类、generate 自回归循环、CFG 与 CUDA Graphs;
  4. zonos/conditioning.py:make_cond_dict 与各 Conditioner 实现、音素化管线、语言代码表;
  5. zonos/sampling.py:采样算法全集(min-p、top-k/top-p、Unified Sampler、重复惩罚);
  6. zonos/autoencoder.py:DAC 44kHz 编解码封装;
  7. zonos/speaker_cloning.py:ResNet293 说话人 embedding 与 LDA 投影;
  8. zonos/backbone/_torch.py:纯 PyTorch Transformer 骨干(RoPE、GQA、SwiGLU);
  9. gradio_interface.py:WebUI 完整参数映射与动态显隐逻辑;
  10. sample.py、pyproject.toml、Dockerfile、docker-compose.yml:最小示例、依赖清单与容器化部署。

综上,Zonos-v0.1 是一个"开箱即用 + 深度可调"的 44kHz 开源 TTS 方案:通过 make_cond_dict 一行即可获得全部 conditioning 能力,通过 Gradio 界面可零代码体验克隆与调参,通过 generate 的 sampling_params 与 cfg_scale 可精细控制输出风格。本文给出的所有参数默认值与取值范围均直接取自仓库源码,可放心作为二次开发与实验的依据。

登录后查看全文
Zonos