Zonos-v0.1 开源 TTS 全指南:从零克隆声音、细粒度情感控制的 Transformer 与 Hybrid 双模型实战
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 是一个基于超过 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",即:
- 文本预处理:对输入文本做数字/符号归一化(zonos/conditioning.py 中的
normalize_numbers、normalize_jp_text等),再通过 eSpeak 转成带重音标记的音素序列; - 前缀条件编码(Prefix Conditioning):把音素、说话人 embedding、情绪向量、语速、fmax、pitch_std、language_id 等各类条件拼装并投影到同一维度,构成前缀序列;
- DAC token 预测:由 Transformer 或 Hybrid(Mamba+Attention) 骨干网络自回归式预测 DAC(Descript Audio Codec)token,支持延迟模式(delay pattern)与 classifier-free guidance(CFG)采样;
- 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 会:
- 通过
hf_hub_download从 Hugging Face Hub 下载config.json与model.safetensors; - 解析配置为
ZonosConfig(见 zonos/config.py,含eos_token_id=1024、masked_token_id=1025等); - 根据配置自动选择 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); - 以
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 界面即用它驱动进度条) |
生成过程的关键机制:
- 延迟模式(delay pattern):使用 zonos/codebook_pattern.py 的
apply_delay_pattern将 9 个 codebook 的 token 按对角延迟排布(类似 MusicGen/RVQ delay pattern),解码端用revert_delay_pattern还原; - 音频前缀:
audio_prefix_codes若提供(形状[bsz, 9, prefix_audio_seq_len]),会被填入 codes 的前缀位置,使模型继续生成而不是从零开始; - CFG:条件/无条件两路 logits 按
uncond + (cond - uncond) * cfg_scale融合(zonos/model.py); - EOS 处理:仅允许 codebook 0 预测 EOS token(
logit_bias[:, 1:, self.eos_token_id] = -inf),检测到 EOS 后逐步把后续 codebook 填为 EOS,最多再生成 9 步收尾; - 加速:hybrid(mamba_ssm)骨干支持 CUDA Graphs(
can_use_cudagraphs),纯 torch 骨干则默认用torch.compile(dynamic=True)加速(zonos/model.py); - 生成完毕后把 ≥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"。其实现要点:
- Gradio 界面的
generate_audio中,前缀音频先经mean(0)取单声道,再调用autoencoder.preprocess(重采样到 44.1kHz + padding)与autoencoder.encode得到audio_prefix_codes(形状[1, 9, prefix_len]); generate中这些 codes 被填入自回归序列前缀(zonos/model.py),模型从该音频之后继续生成;- 默认 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_std60–150;vqscore_8与dnsmos_ovrl置 unconditional;可用高度中性的 emotion 向量做 CFG 负向提示放大情绪; - 干净中性:
fmax22050/24000、speaking_rate15、pitch_std20–45、vqscore_80.78、dnsmos_ovrl4.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(本文按仓库说明如实转述,未提供外部链接)。
十、进一步阅读指引
若想深入源码,建议按以下顺序阅读:
- README.md:项目总览与使用入口(本文主题文档);
- CONDITIONING_README.md:全部 conditioning 的权威说明(本文第五节已归纳);
- zonos/model.py:
Zonos类、generate自回归循环、CFG 与 CUDA Graphs; - zonos/conditioning.py:
make_cond_dict与各 Conditioner 实现、音素化管线、语言代码表; - zonos/sampling.py:采样算法全集(min-p、top-k/top-p、Unified Sampler、重复惩罚);
- zonos/autoencoder.py:DAC 44kHz 编解码封装;
- zonos/speaker_cloning.py:ResNet293 说话人 embedding 与 LDA 投影;
- zonos/backbone/_torch.py:纯 PyTorch Transformer 骨干(RoPE、GQA、SwiGLU);
- gradio_interface.py:WebUI 完整参数映射与动态显隐逻辑;
- sample.py、pyproject.toml、Dockerfile、docker-compose.yml:最小示例、依赖清单与容器化部署。
综上,Zonos-v0.1 是一个"开箱即用 + 深度可调"的 44kHz 开源 TTS 方案:通过 make_cond_dict 一行即可获得全部 conditioning 能力,通过 Gradio 界面可零代码体验克隆与调参,通过 generate 的 sampling_params 与 cfg_scale 可精细控制输出风格。本文给出的所有参数默认值与取值范围均直接取自仓库源码,可放心作为二次开发与实验的依据。
