IndexTTS-2.5 实战指南：零样本语音克隆、五语种合成与情感/发音/语速全维度可控的 TTS 技术详解

IndexTTS-2.5 是哔哩哔哩 IndexTeam 发布的零样本（zero-shot）文本转语音模型，仅凭一段参考音频即可克隆说话人音色，并支持中文、英文、日文、西班牙文、阿拉伯文五种语言之间的跨语言音色迁移，同时将情感表达与音色解耦、独立控制。本文以仓库内 README.md 为骨架，结合 config.yaml、LICENSE 及各权重文件，完整覆盖从环境安装、权重下载、推理 API 到配置项与已知限制的全链路实操，读完即可在你的 NVIDIA GPU 上跑通语音克隆、情感控制、发音纠偏与语速调节四类典型场景。

一、模型概览与核心特性

IndexTTS-2.5 是一个自回归（Autoregressive）零样本 TTS模型，整体由三部分组成：

• GPT 骨干（backbone）：负责从文本条件与参考音频条件中预测语义 token，参数量约 0.8B；
• flow-matching 语音转 Mel 解码器（speech-to-mel decoder）：将语义 token 流式生成 Mel 谱；
• BigVGAN 声码器（vocoder）：将 Mel 谱还原为22.05 kHz波形输出。

这一点与仓库中的 config.yaml 相互印证：配置中gpt段定义了 24 层、1280 维、20 头的 GPT 主干，s2mel段定义了基于 DiT 的 flow-matching 解码器与 WaveNet 输出层，vocoder段明确为bigvgan类型。

相对于 IndexTTS-2，IndexTTS-2.5 的主要升级点包括：

• 新增语种：在中文、英文基础上加入日文、西班牙文、阿拉伯文，共五语种支持；
• 推理速度更快；
• 新增语速控制（duration_factor参数）；
• 发音可控性大幅提升：中文拼音（带数字声调）、英文 CMU 音素、日文假名均可在文本中以<word|reading>形式显式指定。

模型官方信息一览（来源：README.md）：

二、环境要求与安装

官方文档明确要求的运行环境为：

• Python 3.10–3.11；
• NVIDIA GPU，推理时约需6 GB 显存（启用 bf16 精度后）；
• 使用uv作为 Python 包与虚拟环境管理工具。

安装步骤如下（按 README.md 原文）：

git clone https://gitcode.com/hf_mirrors/IndexTeam/IndexTTS-2.5.git && cd IndexTTS-2.5 pip install -U uv uv sync --all-extras

说明：本仓库以模型权重、配置文件与文档为主；推理所需的indextts包与webui.py位于 README 中给出的上游 index-tts 源码仓库，克隆后执行uv sync --all-extras即可解析全部依赖（含 Web UI 等扩展依赖）。

三、下载模型权重

权重支持从 HuggingFace 与 ModelScope 两条渠道获取，官方命令如下：

# HuggingFace uv tool install "huggingface-hub" hf download IndexTeam/IndexTTS-2.5 --local-dir=checkpoints # 或 ModelScope uv tool install "modelscope" modelscope download --model IndexTeam/IndexTTS-2.5 --local_dir checkpoints

权重统一放置到checkpoints/目录。本仓库内已经提供了其中核心权重与辅助文件，可直接对照：

• gpt.pth：GPT 骨干权重，对应配置gpt_checkpoint: gpt.pth；
• s2mel.pth：flow-matching speech-to-mel 解码器权重，对应配置s2mel_checkpoint: s2mel.pth；
• codec.pth：语义编解码器（semantic codec，codebook 大小 8192，见 config.yaml 的semantic_codec段）；
• feat1.pt / feat2.pt：分别对应配置中的spk_matrix（音色矩阵）与emo_matrix（情感矩阵）；
• wav2vec2bert_stats.pt：说话人表征（w2v-bert）的统计量文件；
• multilingual_zh_ja_yue_char_del.tiktoken：多语种（中/日/粤）字符级分词表；
• qwen0.6bemo4-merge：QwenEmotion 情感抽取小模型目录（详见下文“文本情感控制”）。

另外需要特别注意：w2v-bert-2.0、MaskGCT 语义 codec、CAMPPlus、BigVGAN 四个辅助模型不包含在仓库内，首次运行时会被自动下载到checkpoints/hf_cache/目录，无需手动干预。

四、推理实战：四类典型场景

推理统一通过indextts.infer_v2_5模块中的IndexTTS2类完成。首先构造模型实例：

from indextts.infer_v2_5 import IndexTTS2 tts = IndexTTS2(cfg_path="checkpoints/config.yaml", model_dir="checkpoints", use_bf16=True)

其中cfg_path指向 config.yaml，model_dir指向权重目录，use_bf16=True开启 bf16 以降低显存占用（约 6 GB 即可推理）。构造器还支持use_qwen_emo、use_emo_text、use_random等参数，分别控制情感模型加载、文本情感输入与情感随机采样，具体约束见第六节。

4.1 基础语音克隆（Voice Cloning）

tts.infer( spk_audio_prompt="prompt.wav", text="Hello, this is a voice cloning demo.", lang="EN", output_path="output.wav", )

• spk_audio_prompt：参考音频路径，零样本克隆的“样本来源”，无需任何微调即可模仿该音色；
• lang：文本语言标签，五语种分别使用ZH、EN、JA、ES、AR；
• 跨语言场景下，参考音频语种与text语种可以不同，即跨语言音色迁移（cross-lingual voice transfer）。

4.2 情感控制：8 维情感向量

情感以8 个浮点数组成的向量传入，顺序固定为：

[happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]

即：快乐、愤怒、悲伤、恐惧、厌恶、忧郁、惊讶、平静。

# 把“悲伤”拉到 0.8，其余情感保持 0 tts.infer( spk_audio_prompt="prompt.wav", text="快躲起来！是他要来了！", lang="ZH", output_path="output.wav", emo_vector=[0, 0, 0.8, 0, 0, 0, 0, 0], )

情感与音色在模型内部被解耦处理：情感矩阵权重保存在 feat2.pt（配置项emo_matrix），而音色矩阵保存在 feat1.pt（配置项spk_matrix）。从 config.yaml 的emo_num: [3, 17, 2, 8, 4, 5, 10, 24]可以看出，每个情感维度在情感矩阵中对应不同数量的离散强度等级，模型据此对情感进行细粒度插值控制。

4.3 发音控制：拼音 / CMU 音素 / 假名

针对多音字、外来词等易错发音，支持在文本中以<词|读音>形式显式指定读音：

# 中文拼音（数字声调）：银行(xíng) / 行走(háng) tts.infer( spk_audio_prompt="prompt.wav", text="他在银<行|XING2>里<行|HANG2>走了半天。", lang="ZH", output_path="output.wav", )

• 中文：使用带数字声调的拼音，如行|XING2；
• 英文：使用 CMU 音素；
• 日文：使用假名。

该能力由多语种分词表支撑，仓库内 multilingual_zh_ja_yue_char_del.tiktoken 即为此类多语种字符级处理而提供，这也是 2.5 相比 2.0 在发音可控性上的核心改进。

4.4 语速控制：duration_factor

duration_factor用于调节语速，取值范围为 0.5–2.0：

• > 1.0：放慢语速；
• < 1.0：加快语速。

tts.infer( spk_audio_prompt="prompt.wav", text="大家好，欢迎来到IndexTTS。", lang="ZH", output_path="output.wav", duration_factor=1.2, # 放慢到 1.2 倍时长 )

语速控制由 config.yaml 中s2mel段的length_regulator（时长调节器）实现，该模块以 512 通道对内容序列进行时长规整，is_discrete: false表示连续时长预测模式。

五、Web UI 交互界面

除 Python API 外，仓库提供开箱即用的图形界面：

uv run webui.py

在已执行uv sync --all-extras（安装全部扩展依赖）的前提下，该命令会启动本地 Web 服务，可在浏览器中完成参考音频上传、文本输入、语言与情感选择、试听与下载的完整流程，适合快速验证效果与产品原型。

六、配置详解：读懂 config.yaml

config.yaml 是模型初始化的唯一配置入口（version: 2.5），各关键段与仓库权重文件一一对应：

关于qwen0.6bemo4-merge：从 qwen0.6bemo4-merge/config.json 可以看出，这是一个Qwen3 架构的小型因果语言模型（Qwen3ForCausalLM，hidden_size 1024、28 层、16 注意力头、约 0.6B 量级、bf16 精度），经情感数据微调后用于从文本中抽取情感描述；qwen0.6bemo4-merge/Modelfile 表明该目录同时可由 Ollama 以<|endoftext|>为停止符加载。它只在需要“文本→情感”自动抽取时才会被加载（见下文限制）。

七、已知限制与使用约束

7.1 官方声明的能力边界（README.md）

• 长文本韵律不连续：长文本会被切分为多个片段，片段间以短暂静音拼接，因此跨片段边界不会建模完整韵律，长段落的情感与语调连贯性有限；
• 文本情感依赖额外模型：use_emo_text=True（文本描述驱动情感）需要 QwenEmotion 模型，它仅在构造IndexTTS2时传入use_qwen_emo=True才会加载；否则在推理时会直接报错；
• 随机采样损伤克隆保真度：开启情感随机采样（use_random=True）会降低语音克隆的相似度，需要随机多样性与音色保真之间做取舍；
• 音色授权责任：模型不会自动校验参考音频中说话人是否同意被克隆，获取授权是使用者的责任，且一切使用需遵守 LICENSE 条款。

7.2 许可条款要点（LICENSE）

仓库采用bilibili Model Use License Agreement，使用时需特别关注：

• 若你或关联公司的产品或服务月活用户超过 1 亿，或年营收超过人民币 10 亿元，必须另行向版权方申请单独许可；
• 不得使用该模型改进其他 AI 模型（IndexTTS 自身、其衍生作品或非商业 AI 模型除外）；
• 分发衍生作品时必须保留原始版权声明与本协议副本，并向下游明确“衍生作品的修改未经原版权方认可”；
• 禁止部署于医疗诊断、自动驾驶、军事、关键基础设施控制、大规模生物识别监控等高风险场景。

八、引用与延伸阅读

如果你在论文或技术报告中使用 IndexTTS-2.5，官方推荐引用如下（完整版本见 README.md）：

@misc{li2026indextts25technicalreport, title={IndexTTS 2.5 Technical Report}, author={Yunpei Li and Xun Zhou and Jinchao Wang and Lu Wang and Yong Wu and Siyi Zhou and Yiquan Zhou and Yining Wang and Yaogen Yang and Zhetao Hu and Shiyao Duan and Jiacheng Xu and Bin Xia and Jingchen Shu}, year={2026}, eprint={2601.03888}, archivePrefix={arXiv}, primaryClass={cs.SD}, }

深入阅读本仓库内的相关文件，可以进一步对照配置与权重的对应关系：README.md（官方说明与全部示例）、config.yaml（模型结构配置）、LICENSE（许可协议全文）。

总结

IndexTTS-2.5 以“一段参考音频 + 一段文本”即可完成高质量语音克隆，同时把情感、发音、语速三个维度都开放为显式可控参数：emo_vector让情感与音色解耦，<word|reading>让多音字与外来词发音精确可控，duration_factor让语速在 0.5–2.0 范围内自由调节。结合 config.yaml 中 GPT 骨干、flow-matching 解码器、语义 codec 与 BigVGAN 的完整配置链，以及约 6 GB 显存即可推理的轻量要求，它非常适合作为语音克隆、多语种配音与情感语音合成的生产级起点——只需在使用前确认说话人授权与许可条款即可。