VALL-E-X 零样本多语言 TTS 实战指南：从安装、语音克隆到跨语言合成全解析

• 语音
• AI 应用

VALL-E-X 是微软提出的零样本（zero-shot）语音合成模型的开源实现，本仓库完整复现了论文思路并开放了预训练权重，支持英语、中文、日语三种语言的文本转语音、3~10 秒录音的声音克隆、跨语言合成与口音控制。读完本文，你将掌握该项目的完整安装流程、Python API 的每个核心参数、自定义音色 prompt 的制作方法，以及 AR/NAR 两阶段模型与 G2P 文本处理链路的源码级原理，可直接上手落地属于自己的 TTS 应用。

一、项目定位：微软 VALL-E X 论文的开源复现

VALL-E X 最初由微软在其研究论文中提出，但官方并未发布代码或预训练模型。本仓库（VALL-E X）由社区复现并重新训练了一个开源可用的模型，且预训练模型权重已向公众开放，可用于研究与实际应用。项目整体定位与更多细节可参见 model-card.md。

从更新日志可以看到项目的能力演进脉络：

• 2023.08.14：预训练模型权重发布；
• 2023.08.20：加入中文版 README；
• 2023.08.23：加入长文本生成功能；
• 2023.08.30：将 EnCodec 解码器替换为 Vocos 解码器，显著提升音质；
• 2023.09.10：支持 AR decoder 的 batch decoding（对应推理时的best_of多路采样），以获得更稳定的生成结果。

1.1 六大核心能力

1. 多语言 TTS：支持英语（en）、中文（zh）、日语（ja）三种语言的自然、有表现力语音合成；
2. 零样本语音克隆：仅需 3~10 秒的任意说话人录音即可生成个性化、高质量的语音，完美还原其音色；
3. 语音情感控制：可合成与给定说话人录音相同情感的语音，增强表现力；
4. 零样本跨语言语音合成：用与说话人母语不同的另一种语言合成，在不影响口音和流利度的同时保留其音色与情感（例如日语母语者合成英文/中文）；
5. 口音控制：允许控制合成音频的口音，例如"中文带英语口音"或反之；
6. 声学环境保留：当说话人录音来自不同声学环境时，模型会保留该环境特征，使合成语音更自然。

1.2 支持的语言

二、环境准备与本地安装

2.1 环境要求

• Python 3.10（必须）；
• CUDA 11.7 ~ 12.0；
• PyTorch 2.0+；
• GPU 运行需至少 6GB 显存（几乎覆盖所有 NVIDIA GPU）；
• 如需制作 prompt，还需安装ffmpeg并将其所在目录加入环境变量PATH。

2.2 安装步骤

git clone https://gitcode.com/gh_mirrors/va/VALL-E-X cd VALL-E-X pip install -r requirements.txt

requirements.txt 中的核心依赖包括：

• torch/torchvision/torchaudio：深度学习框架与音频 IO；
• encodec：用于把波形编码为离散音频 token 的神经编解码器；
• vocos：替换 EnCodec 解码器的神经网络声码器，负责把 token 还原为高质量波形；
• openai-whisper：语音识别模型，用于在声音克隆时自动转写 prompt 音频的文本；
• gradio==3.41.2：图形界面框架；
• langid：语言检测；
• nltk/jieba/sudachipy/sudachidict_core：英语、中文、日语的分句工具；
• tokenizers/unidecode/inflect/cn2an/pypinyin/eng_to_ipa/pyopenjtalk-prebuilt：G2P（文本到音素）转换链路；
• wget：首次运行时自动下载模型权重。

2.3 模型文件的自动下载与手动补充

第一次运行程序（无论是 Python API 还是 UI）时会自动下载模型。若下载失败，请按以下步骤手动补齐（注意目录与文件名的字母大小写）：

1. 在安装目录下检查是否存在checkpoints文件夹，没有则手动创建（./checkpoints/）；
2. 检查其中是否有vallex-checkpoint.pt文件，没有则从模型发布页面手动下载vallex-checkpoint.pt放入该目录；
3. 检查是否存在whisper文件夹，没有则创建（./whisper/）；
4. 检查其中是否有medium.pt文件，没有则从 OpenAI Whisper 模型页面手动下载medium.pt放入该目录。

这一逻辑可以在 utils/generation.py 的preload_models()中看到：启动时会检查./checkpoints/vallex-checkpoint.pt是否存在，不存在则调用wget自动下载，失败时抛出异常并提示手动下载位置。

三、Python 快速上手：首次文本合成

项目对外暴露的核心 API 集中在 utils/generation.py：

• preload_models()：下载并加载全部模型（VALL-E、EnCodec、Vocos）；
• generate_audio(text, prompt=None, language='auto', accent='no-accent')：核心合成函数；
• SAMPLE_RATE：由 macros.py 定义，值为24000（24kHz）。

3.1 基本使用

from utils.generation import SAMPLE_RATE, generate_audio, preload_models from scipy.io.wavfile import write as write_wav from IPython.display import Audio # download and load all models preload_models() # generate audio from text text_prompt = """ Hello, my name is Nose. And uh, and I like hamburger. Hahaha... But I also have other interests such as playing tactic toast. """ audio_array = generate_audio(text_prompt) # save audio to disk write_wav("vallex_generation.wav", SAMPLE_RATE, audio_array) # play text in notebook Audio(audio_array, rate=SAMPLE_RATE)

3.2 参数说明

generate_audio的四个参数中，language与accent默认分别为'auto'与'no-accent'。当language='auto'时，源码使用langid.classify(text)自动检测语言（仅支持 en/zh/ja 三种）；检测到的语言会映射为[ZH]/[JA]/[EN]语言 token 包裹在文本前后（见 macros.py 的lang2token映射），作为模型的输入条件。

四、多语言合成与混合语言标记

4.1 语言自动检测

不指定language时模型自动检测语言。也可以显式指定，例如合成日语：

text_prompt = """ チュソクは私のお気に入りの祭りです。 私は数日間休んで、友人や家族との時間を過ごすことができます。 """ audio_array = generate_audio(text_prompt)

4.2 混合语言：language='mix'

VALL-E-X 即使在同一句话中混合多种语言也能完美控制口音，但需要手动用语言标记标注各句所属语言，以便 G2P 工具识别：

text_prompt = """ [EN]The Thirty Years' War was a devastating conflict that had a profound impact on Europe.[EN] [ZH]这是历史的开始。 如果您想听更多，请继续。[ZH] """ audio_array = generate_audio(text_prompt, language='mix')

从源码看，当language='auto'时模型会对整段文本做一次语言检测；而混合模式下，文本本身携带的[EN]/[ZH]/[JA]标记会被 G2P 环节逐一解析。见 utils/g2p/cleaners.py 的cje_cleaners：它用正则r'\[EN\](https://link.gitcode.com/i/a29773ab4900054467758bc4782a8357)\[EN\]'等三个模式分别匹配标记段，按位置排序后逐段转音素，并为每个音素标注其语言（output_langs），这个语言序列最终会传给模型的text_language，用于逐 token 的语言嵌入控制。

4.3 G2P 文本处理链路

文本到音素的完整链路位于 utils/g2p/init.py 的PhonemeBpeTokenizer.tokenize()：

1. 通过_clean_text(text, ['cje_cleaners'])把文本转为 IPA 音素序列，并返回逐音素的语言标签；
2. 将空格替换为_；
3. 用 BPE tokenizer（./utils/g2p/bpe_69.json）把音素序列编码为 token id。

其中中文经chinese_to_ipa、日文经japanese_to_ipa2、英文经english_to_ipa2转换为 IPA（见 utils/g2p/cleaners.py）。文本侧词表大小定义在 models/macros.py（NUM_TEXT_TOKENS = 2048），而 G2P 输出符号表为 69 个符号（对应bpe_69.json，见 model-card.md 架构表）。

五、预设音色（Presets）

仓库在 presets 目录下提供了十几款开箱即用的说话人音色（*.npz文件），例如dingzhen、paimon、vctk_1、librispeech_1、seel、neutral、en2zh_tts_1、zh2en_tts_1等。

VALL-E X 会尝试匹配给定预设音色的音调、音高、情感和韵律，同时尽量保留音乐、环境噪声等声学特征。

text_prompt = """ I am an innocent boy with a smoky voice. It is a great honor for me to speak at the United Nations today. """ audio_array = generate_audio(text_prompt, prompt="dingzhen")

源码中prompt参数的加载逻辑（utils/generation.py）依次尝试：

1. 将prompt直接作为文件路径；
2. 否则尝试./presets/{prompt}.npz；
3. 否则尝试./customs/{prompt}.npz；
4. 都不存在则抛出ValueError(f"Cannot find prompt {prompt}")。

npz文件中包含三个键：audio_tokens（EnCodec 编码的音频 token）、text_tokens（音素 token）、lang_code（语言编号，映射见 macros.py 的lang2code：zh=0、ja=1、en=2）。

六、零样本声音克隆：制作你的专属 prompt

声音克隆是 VALL-E-X 最核心的玩法：使用任何人、角色甚至你自己的声音制作音频 prompt，之后模型就会以相似的声音合成文本。

6.1 制作 prompt

你只需提供一段3~10 秒的语音以及该语音对应的文本。文本也可以留空，让 Whisper 模型自动转写：

from utils.prompt_making import make_prompt ### Use given transcript make_prompt(name="paimon", audio_prompt_path="paimon_prompt.wav", transcript="Just, what was that? Paimon thought we were gonna get eaten.") ### Alternatively, use whisper make_prompt(name="paimon", audio_prompt_path="paimon_prompt.wav")

6.2 用新音色合成

from utils.generation import SAMPLE_RATE, generate_audio, preload_models from scipy.io.wavfile import write as write_wav # download and load all models preload_models() text_prompt = """ Hey, Traveler, Listen to this, This machine has taken my voice, and now it can talk just like me! """ audio_array = generate_audio(text_prompt, prompt="paimon") write_wav("paimon_cloned.wav", SAMPLE_RATE, audio_array)

6.3 内部处理流程源码解读

utils/prompt_making.py 的make_prompt完成以下步骤：

1. 用torchaudio.load读取音频，校验时长不超过 15 秒，否则抛出ValueError（README 建议 3~10 秒为最佳区间）；双声道自动取均值转为单声道；
2. 若未提供transcript，则加载 Whispermedium模型（下载到./whisper/）转写文本，并自动在文本尾部补充标点（transcribe_one）；
3. 用tokenize_audio（data/tokenizer.py）通过 EnCodec 编码器把波形转为离散音频 token（目标带宽 6.0，见 AudioTokenizer）；
4. 用PhonemeBpeTokenizer把文本转为音素 token；
5. 将结果保存为./customs/{name}.npz（含audio_tokens、text_tokens、lang_code三个数组）。

之后在generate_audio(text, prompt="paimon")时，模型会把 prompt 的音频 token 与文本 token 作为前缀条件（enroll_x_lens）拼接进推理序列，实现"听到谁的声音就像谁"的零样本克隆。

七、进阶玩法：口音控制与长文本生成

7.1 口音控制

accent参数控制合成口音，可选值为'no-accent'（默认）、'English'、'中文'、'日本語'。源码在推理前根据该参数把目标语言 token 映射到langdropdown2token（macros.py），并覆盖掉自动检测的语言：

# 用英语口音朗读中文 audio_array = generate_audio("你好，世界。", language='zh', accent='English')

例如跨语言合成的官方示例：用日语母语者作为 prompt，分别合成英文与中文；或让中文带英语口音、英语带中文口音。

7.2 长文本生成

由于单次生成存在序列长度限制（见 FAQ），项目提供了长文本生成函数：

from utils.generation import generate_audio_from_long_text audio_array = generate_audio_from_long_text( text, prompt="dingzhen", language='auto', accent='no-accent', mode='sliding-window' # 或 'fixed-prompt' )

两种模式的差异（见 utils/generation.py 的 docstring 与实现）：

• fixed-prompt：全程使用用户提供的同一个 prompt，逐句生成音频后拼接。说话人特征最稳定；
• sliding-window：默认模式（未提供 prompt 时强制使用），每句生成后以 50% 概率把上一句的输出作为下一句的 prompt（audio_prompts = encoded_frames[:, :, -NUM_QUANTIZERS:]），以缓解累积误差，但说话人保持度略弱于 fixed-prompt。

分句由 utils/sentence_cutter.py 的split_text_into_sentences完成，按语言选择不同工具：英语用 NLTK 的sent_tokenize，中文用 jieba 按。！？……断句，日语用 SudachiPy 按句点（補助記号/句点）断句。

八、Gradio 图形界面：四步零代码体验

如果不想写代码，项目还提供了用户友好的 Gradio 界面：

python -X utf8 launch-ui.py

启动后会自动打开http://127.0.0.1:7860（见 launch-ui.py 的webbrowser.open与app.launch()）。界面共四个 Tab（launch-ui.py）：

界面中的语言选项为auto-detect/English/中文/日本語（Infer from prompt 另有Mix），口音选项为no-accent/English/中文/日本語，与 Python API 的参数一一对应。示例数据定义在 examples.py，其中使用了 prompts 目录下的en-1.wav、zh-1.wav、ja-2.ogg等样例音频。

九、模型原理与源码细节

9.1 两阶段架构：AR + NAR

VALL-E-X 与 Bark、VALL-E、AudioLM 类似，使用GPT 风格的自回归（AR）模型预测量化音频 token，再经神经编解码器还原波形。从 model-card.md 的架构表可知，模型由三个子模块组成：

具体实现见 models/vallex.py 的VALLE类：

• AR Decoder：以文本 token 序列为前缀，自回归地预测 EnCodec第 1 个 codebook的 token（词表 1,024），采样使用topk_sampling（topk_sampling），推理时支持 KV cache 加速与best_of多路 beam 采样（sum_logprobs累计对数概率并选取最优路，即更新日志中的 "batch decoding"）；
• NAR Decoders：以 AR 输出与文本为条件，非自回归地并行预测第 2~8 个 codebook的 token（共 7 层nar_predict_layers），每层取 argmax；
• 语言信息通过ar_language_embedding/nar_language_embedding注入：prompt 部分加prompt_language嵌入，合成文本部分加text_language嵌入（见 models/vallex.py）。

9.2 关键超参数

仓库根目录的 macros.py 定义了模型的全局超参数，同时是 API 的默认配置来源：

9.3 解码器：从 EnCodec 到 Vocos

音频 token 的词表大小（NUM_AUDIO_TOKENS = 1024）与 EnCodec 的 RVQ bins 对应（models/macros.py）。训练/推理链路中：

• 编码：EnCodec 24kHz 模型（目标带宽 6.0）把波形压成离散 token，见 data/tokenizer.py；
• 解码：preload_models()加载Vocos.from_pretrained('charactr/vocos-encodec-24khz')，用vocos.codes_to_features+vocos.decode还原波形（带宽 id 取 2），见 utils/generation.py。这就是更新日志中"用 Vocos 替换 EnCodec 解码器提升音质"的具体落点。

9.4 与 Bark 的对比（项目方陈述）

项目方在 README 中给出了与 Bark 的对比结论（属于作者陈述，供选型参考）：

• ✅ 轻量（约 1/3 大小）、快速（约 4 倍快）；
• ✅ 中文与日文合成质量更高；
• ✅ 跨语言合成没有外国口音；
• ✅ 开放且易于操作的声音克隆；
• ❌ 支持的语言较少；
• ❌ 没有用于合成音乐及特殊音效的 token。

十、硬件要求与常见问题（FAQ）

10.1 需要多少显存？

6GB GPU 显存即可满足，几乎所有 NVIDIA GPU 都满足要求。CPU 也能运行（pytorch 2.0+，CUDA 11.7 ~ 12.0），但速度会明显慢于 GPU。设备选择逻辑见 utils/generation.py：优先 CUDA，其次 MPS（Apple Silicon），最后回退 CPU。

10.2 为什么模型无法生成长文本？

当序列长度增加时，Transformer 的计算复杂度呈二次方增长。因此所有训练音频都保持在22 秒以下。使用时请确保音频 prompt 与生成音频的总长度小于 22 秒，以保证可接受的性能。这就是长文本功能需要先分句、逐句生成再拼接的原因。

10.3 checkpoint 在哪里下载？

• 第一次运行程序时，会自动使用wget将模型下载到./checkpoints/目录；
• 若下载失败，手动下载vallex-checkpoint.pt放入./checkpoints/（详见本文第二节的步骤）。

十一、Roadmap 与 License

11.1 待办事项（摘自 README）

• 添加中文 README
• 长文本生成
• 用 Vocos 解码器替换 Encodec 解码器
• 微调以实现更好的语音自适应
• 给非 python 用户的.bat脚本
• 更多...

11.2 开源许可

VALL-E-X 使用 MIT License，可自由用于研究与应用。

至此，你已经掌握了 VALL-E-X 从环境搭建、Python API 调用、预设音色、声音克隆到长文本与口音控制的完整实战路径，并理解了其 AR/NAR 两阶段模型、EnCodec/Vocos 编解码与 G2P 文本链路的核心原理。后续可以基于 utils/generation.py 的接口自由组合 prompt、语言与口音参数，构建自己的多语言语音克隆应用。

• 语音
• AI 应用