Loading...

文章背景图

IndexTTS:B 站开源零样本音色克隆与多情绪可控 TTS|部署与使用全指南

2026-10-26
1
- 字
- 分钟
|

图1 IndexTTS 官方标识与 bilibili index 署名(README 官方素材,浅色版)

IndexTTS · B 站开源零样本音色克隆与多情绪可控语音合成 · 中文部署与使用全指南

项目仓库: https://github.com/index-tts/index-tts

开源协议:bilibili Model Use License Agreement(附独立 DISCLAIMER,商用与大规模使用需核对协议条款) · 开发语言:Python(PyTorch 2.8) · 依赖管理:uv(强制使用以保证依赖一致) · WebUI:Gradio · WebUI 默认端口:7860(--host 0.0.0.0 --port 7860) · 官方生产部署:vLLM Recipe · 当前主线版本:IndexTTS-2.5(同仓库兼容 IndexTTS-2、1.5 旧版)


1 项目简介

IndexTTS 是由 Bilibili Index Team 维护的工业级可控、高效零样本文本转语音(Zero-shot TTS)系统:只需要一段参考音频,即可克隆其中的音色生成新语音。仓库主线最新版本为 IndexTTS-2.5,支持中文、英语、日语、西班牙语、阿拉伯语,提供细粒度情绪控制、语速控制与发音控制(中文拼音 / 英语 CMU 音素 / 日语假名),官方称推理速度快于 IndexTTS-2,并保留跨语言与音色—情绪解耦能力。同仓库还保留 IndexTTS-2、IndexTTS-1.5 等历史版本的推理代码与模型入口。

非官方声明:本文依据官方 README、docs/README_zh.md、LICENSE、DISCLAIMER、webui.py 与 pyproject.toml 整理部署步骤;项目由 Bilibili Index Team 开发维护,官方在 README 中明确:核心团队唯一官方渠道为本仓库,其他任何网站或服务均非官方。本文不代理官方立场,模型效果、参数与许可条款以仓库最新版本为准。

1.1 核心信息一览

项目项 内容
项目名称 IndexTTS(主线 IndexTTS-2.5,兼容 IndexTTS-2 / 1.5)
仓库地址 github.com/index-tts/index-tts
项目定位 零样本音色克隆 + 多模态情绪可控的工业级 TTS 系统
开源协议 bilibili Model Use License Agreement(见 LICENSE),使用前须阅读 DISCLAIMER
开发语言 / 框架 Python >=3.10,<3.12;PyTorch 2.8、torchaudio 2.8;Gradio 5.45(WebUI)
依赖管理 uv(官方要求使用以获得一致的 Python 版本与依赖锁定)
支持语言(2.5) 中文 ZH、英语 EN、日语 JP、西班牙语 ES、阿拉伯语 AR
情绪控制方式 情绪参考音频、情绪向量(8 维)、文本情绪描述、use_emo_text、情绪强度 emo_alpha
语速控制 duration_factor,范围 0.5–2.0,默认 1.0
部署方式 本地:uv 源码环境 + Gradio WebUI / Python API;生产:官方 vLLM Recipe(仓库未内置 Dockerfile / Compose)
WebUI 默认端口 7860(webui.py 默认 --host 0.0.0.0 --port 7860)
模型权重渠道 HuggingFace IndexTeam/IndexTTS-2.5、IndexTeam/IndexTTS-2;ModelScope 同名模型仓库
系统入口 WebUI:uv run webui.py;Python API:indextts.infer_v2_5 / indextts.infer_v2;命令行入口:indextts、indextts2
社区联系 Discord https://discord.gg/uT32E7KDmy;邮箱 indexspeech@bilibili.com(商用合作)

1.2 适用场景

  • 希望仅凭一段干净参考音频克隆目标音色,用于配音、有声书、内容创作与研究实验。
  • 需要在合成语音中施加可控情绪:悲伤、高兴、愤怒、害怕、厌恶、忧郁、惊讶、平静,并调节情绪强度。
  • 多语言内容生产:中文、英文、日文、西班牙文、阿拉伯文文本在同一套工具内合成,并支持跨语言音色迁移。
  • 需要纠正多音字发音(拼音标注)、英语多音字(CMU 音素标注)与日语多音字(假名标注)。
  • 需要控制语速(放慢 / 加快),或在生产环境通过 vLLM 方式提供批量推理服务。
  • 语音技术研究与效果复现:对比零样本克隆、情绪解耦、发音可控等技术指标。

1.3 能力边界(官方口径)

  • 参考音频即音色:零样本克隆依赖 spk_audio_prompt 参考音频;官方未提供上传长期训练、专属声纹模型的本地训练流程(自定义训练属于研究范畴,以仓库后续文档为准)。
  • 情绪与音色解耦:情绪参考音频 / 情绪向量控制情绪倾向,音色由说话人参考音频决定;官方说明开启随机采样(use_random=True)会降低音色克隆保真度。
  • 发音控制覆盖范围有限:拼音仅支持 checkpoints/pinyin.vocab 中有效的合法组合;英语音素以 CMU 词典条目为准;未列出的标注组合不保证生效。
  • IndexTTS-2 的时长控制:官方在 News 中说明"精确合成时长控制"功能在当前版本尚未启用。
  • 低显存自动降级:webui.py 内置显存阈值 10.0 GB;检测到显存低于阈值时自动启用半精度并默认跳过 QwenEmotion 加载,文本情绪描述控制在该状态下不可用(可用 --qwen_emo 强制加载)。
  • 官方 README 未逐字给出各版本模型的固定显存下限、磁盘容量清单与离线安装包;硬件余量以 tools/gpu_check.py 检测结果与实际加载日志为准,以官方仓库最新说明为准。

2 功能特性

2.1 零样本音色克隆

  • 单段参考音频即可作为说话人提示(spk_audio_prompt),无需为目标音色单独训练模型。
  • 2.5 版本在合成时通过 lang 指定目标语言,支持跨语言音色迁移;音色与情绪在模型层面解耦,可分别控制。

2.2 多模态情绪控制

  • 情绪参考音频:另传一段情绪音频 emo_audio_prompt,让输出继承其情绪倾向。
  • 情绪强度 emo_alpha:指定情绪参考音频对结果的影响程度,取值 0.0–1.0,默认 1.0(100%)。
  • 情绪向量:不传情绪音频时,直接传入 8 维浮点列表,顺序为 [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]。
  • 文本自动转情绪向量 use_emo_text:把台词脚本本身转换为情绪向量;官方建议配合约 0.6 或更低的 emo_alpha 以获得更自然的语音。
  • 显式情绪描述 emo_text:把台词文本与情绪描述文本分开控制,情绪描述单独转换为情绪向量。
  • 随机采样 use_random:推理时引入随机性,默认 False;官方提示开启后会降低音色克隆保真度。

2.3 语速与发音控制(2.5)

  • 语速 duration_factor:大于 1.0 放慢,小于 1.0 加快,范围 0.5–2.0,默认 1.0。
  • 中文拼音标注:在多音字处使用 <词|拼音> 标注,如 <行|XING2>。
  • 英语 CMU 音素标注:如 <minute|M IH1 . N AH0 T> 与 <minute|M AY0 . N UW1 T> 区分不同读音。
  • 日语假名标注:如 <上手|じょうず> / <上手|うわて> 区分多音字读法。

2.4 性能与部署选项

  • 半精度推理:2.5 使用 BF16、2 使用 FP16,官方说明半精度推理更快、显存占用更低、质量损失很小。
  • 可选加速:DeepSpeed、编译 CUDA 内核(--cuda_kernel)、GPT2 加速引擎(--accel,依赖 flash-attn)、torch.compile 优化 s2mel;官方提示 DeepSpeed 在部分系统上反而可能变慢,需结合硬件实测。
  • vLLM 生产部署:官方提供 IndexTTS-2.5 的 vLLM Recipe 用于生产环境服务化。
  • 模型自动补全:WebUI 启动时检查模型目录必需文件,缺失时自动从 HuggingFace / ModelScope 下载;示例音频首次启动按需下载,不再依赖 Git LFS。

3 官方界面预览

图2 IndexTTS-2.5 官方演示视频封面(README 素材,演示跨语言合成效果,跳转 B 站演示页)

图2 为 README 中 IndexTTS-2.5 演示视频封面,对应 B 站演示片与官方 Demo 页面;演示音频与跨语言效果以官方 Demo 为准。

图3 IndexTTS-2 官方宣传图:一句 prompt 生成丰富情绪语音(README 素材)

图3 为 README 中 IndexTTS-2 演示宣传图,体现"文本提示 → 丰富情绪语音"的能力定位。本地 uv run webui.py 启动后的 Gradio 界面包含说话人参考音频、情绪参考音频 / 情绪向量、文本输入、语言选择、语速与情绪强度等控件,具体布局以本地启动版本为准。

4 官方跳转链接汇总

下表列出项目相关的全部官方入口,均可直接点击访问。

类别 链接 说明
仓库主页 https://github.com/index-tts/index-tts 源码、README、WebUI、推理脚本与预设
中文说明 docs/README_zh.md 官方简体中文部署与用法说明
Issues 反馈 https://github.com/index-tts/index-tts/issues Bug 反馈、环境问题与功能建议
IndexTTS-2.5 模型(HF) huggingface.co/IndexTeam/IndexTTS-2.5 2.5 权重与配置
IndexTTS-2 模型(HF) huggingface.co/IndexTeam/IndexTTS-2 2.0 权重与配置
IndexTTS-2.5 模型(ModelScope) modelscope.cn/models/IndexTeam/IndexTTS-2.5 国内镜像模型仓库
IndexTTS-2 模型(ModelScope) modelscope.cn/models/IndexTeam/IndexTTS-2 国内镜像模型仓库
2.5 在线 Demo(HF Space) huggingface.co/spaces/IndexTeam/IndexTTS-2.5-Demo 官方在线体验
2.5 演示页 index-tts.github.io/index-tts2-5.github.io/ 官方效果演示站
ModelScope Studio modelscope.cn/studios/IndexTeam/IndexTTS-2.5 官方在线 Studio
vLLM 生产部署 Recipe recipes.vllm.ai/IndexTeam/IndexTTS-2.5 生产环境服务化方案
论文(2.5) arxiv.org/abs/2601.03888 IndexTTS 2.5 Technical Report
论文(2) arxiv.org/abs/2506.21619 IndexTTS2 论文
论文(1.0) arxiv.org/abs/2502.05512 IndexTTS 原始论文
许可证 LICENSE bilibili Model Use License Agreement
免责声明 DISCLAIMER TTS 语音合成技术免责声明
Discord discord.gg/uT32E7KDmy 官方社区
旧版 1.5 说明 archive/README_INDEXTTS_1_5.md IndexTTS-1.5 历史版本用法

5 前置要求与服务器配置

5.1 软件前提

  • Git:用于克隆仓库,先从 git-scm.com 安装。
  • Python 版本区间:pyproject.toml 要求 >=3.10,<3.12;由 uv 自动创建匹配的 .venv,不要手动切换到其他版本再叠加安装。
  • uv 包管理器:官方明确要求使用 uv 以获得可靠安装:
pip install -U uv
# 其他安装方式见 https://docs.astral.sh/uv/getting-started/installation/
  • NVIDIA 驱动与 CUDA Toolkit(Linux / Windows):官方提示安装过程中若出现 CUDA 报错,需确保系统已安装 NVIDIA CUDA Toolkit 12.8 或更新版本;pyproject.toml 中 PyTorch 按 cu128 索引解析。
  • 可选加速依赖:DeepSpeed(--extra deepspeed)、flash-attn GPT2 加速引擎(--extra accel)、torch.compile 相关扩展(--extra torch_compile);Windows 上 DeepSpeed 官方提示可能较难安装,可去掉 --all-extras 后按需单独开启其他 extra。
  • 音频依赖:pyproject.toml 已声明 ffmpeg-python、librosa、openai-whisper 等;个别音频格式处理若报错,需按本机提示确认系统 ffmpeg 是否可用。
  • 模型网络:首次启动需访问 HuggingFace 或 ModelScope 下载模型权重与示例音频;国内网络可按第 8.2 节配置镜像。

5.2 硬件建议(官方口径)

项目 说明
GPU 官方 WebUI 内置 LOW_VRAM_THRESHOLD_GB = 10.0:显存小于 10 GB 自动走半精度并默认跳过 QwenEmotion;RTX 4090 上的 RTF 数据见官方 README 性能表(kv_cache=True)
显存策略 2.5 BF16 / 2 FP16 半精度可降低显存占用、提升速度;低显存可配合 --fp16 与关闭可选加速实测
CPU / 内存 官方 README 未给出固定 CPU 核数与内存下限;加载多模型与情绪模块时建议预留充足内存,以 tools/gpu_check.py 与实际日志为准
存储 需预留 2.5 与 2.0 两套检查点、配置文件与示例音频的空间;模型大小以 HuggingFace / ModelScope 实际下载为准
操作系统 官方在 Linux / Windows 上给出 CUDA 注意事项;macOS 不提供 CUDA 版 PyTorch 索引,可在 CPU / MPS 环境下按官方仓库最新说明实测

说明:官方 README 未逐字列出最低显存 GB 数、内存下限与采样率清单,本节未补充臆造数值;部署时先运行第 7.1 节的 GPU 检测工具,再按第 8 节调整半精度与加速开关。

5.3 端口分配

端口 服务 默认绑定 用途
7860 Gradio WebUI 0.0.0.0(webui.py 默认 --host 0.0.0.0 --port 7860) 浏览器本地 / 局域网访问演示界面

远程服务器使用 WebUI 时,建议通过 SSH 隧道或带认证的反向代理访问 7860 端口;不要把 Gradio 界面不加鉴权地直接暴露到不可信公网。生产批量服务以官方 vLLM Recipe 为准(第 6 章)。

6 方式一:官方生产服务化部署(vLLM Recipe)

6.1 仓库容器化现状(如实说明)

IndexTTS 仓库未随附官方 Dockerfile 与 docker-compose.yml,本章不编造容器编排文件。官方对生产环境批量推理给出的服务化路径是 vLLM Recipe:

使用前请先在该 Recipe 页面阅读其给定的基础镜像、模型挂载、环境变量、启动命令与服务端口;本章仅复述官方定位,Recipe 内的具体命令、端口与资源限制以页面最新版本为准,不要套用其他 TTS 项目的 Compose 配置。

6.2 服务化前置条件(本地已验证环境)

在按 Recipe 部署服务前,先在同一台机器上完成第 7 章的源码环境与模型下载,确认:

  1. uv sync --all-extras 依赖安装成功;
  2. 模型目录必需文件齐全(2.5:gpt.pth、s2mel.pth、codec.pth、multilingual_zh_ja_yue_char_del.tiktoken、wav2vec2bert_stats.pt;2:bpe.model、gpt.pth、s2mel.pth、wav2vec2bert_stats.pt);
  3. tools/gpu_check.py 能正确识别目标 GPU;
  4. 参考音频、文本长度与并发规模在本机实测通过,再迁移到 Recipe 服务化环境。

6.3 服务化合规提醒

  • vLLM 服务面向内部或授权用户提供推理时,应继续遵守 LICENSE 与 DISCLAIMER 的使用限制(第 11 章),不得绕过音色与情绪授权边界。
  • 服务端口、鉴权、限流与资源配额按 Recipe 与所在平台规范配置;本文不提供未经验证的一键 Compose 命令。

7 方式二:源码 / 本地 uv 环境运行

7.1 克隆仓库并检测 GPU

git clone https://github.com/index-tts/index-tts.git
cd index-tts

# 检测环境与识别到的 GPU
uv run tools/gpu_check.py

7.2 安装依赖(uv 强制使用)

# 安装 uv(如已安装可跳过)
pip install -U uv

# 同步全部 extra(webui + deepspeed + accel + torch_compile 等)
uv sync --all-extras

国内网络下载缓慢时,官方给出可用镜像示例:

uv sync --all-extras --default-index "https://mirrors.aliyun.com/pypi/simple"
# 或
uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

可选 extra 说明(来自 README 与 pyproject.toml):

Extra 用途 对应包 / 开关
webui Gradio 界面支持(推荐) gradio==5.45.0
deepspeed DeepSpeed 推理加速(部分系统可能反而变慢) deepspeed==0.17.1
accel GPT2 加速引擎 flash-attn==2.8.3.post1 等
torch_compile torch.compile 优化 s2mel Windows 由 triton-windows 满足

官方提示:所有 uv 命令会自动激活项目虚拟环境,不要在运行 uv 命令前手动激活任何虚拟环境,否则可能造成依赖冲突。Windows 上 DeepSpeed 安装困难时,去掉 --all-extras,按需手动添加 --extra webui 等其他功能。

7.3 下载模型权重

方式 A:HuggingFace CLI

uv tool install "huggingface-hub"

# IndexTTS-2.5 -> checkpoints
hf download IndexTeam/IndexTTS-2.5 --local-dir=checkpoints

# IndexTTS-2 -> checkpoints_2
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints_2

方式 B:ModelScope

uv tool install modelscope-hub

# IndexTTS-2.5
modelscope download --model IndexTeam/IndexTTS-2.5 --local_dir checkpoints

# IndexTTS-2
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints_2

若命令不可用,按 uv tool 输出提示把工具目录加入系统 PATH。部分小模型在首次运行时自动下载;HuggingFace 网络较慢时,先设置镜像再运行代码:

export HF_ENDPOINT="https://hf-mirror.com"

手动补拉示例音频(不经过 WebUI)

uv run python -c "from indextts.utils.examples_downloader import ensure_examples_available; ensure_examples_available()"

7.4 启动 WebUI

# IndexTTS-2.5(默认版本)
uv run webui.py

# IndexTTS-2
uv run webui.py --version 2 --model_dir ./checkpoints_2

浏览器打开:

http://127.0.0.1:7860

查看全部 WebUI 选项:

uv run webui.py -h

7.5 Python 脚本推理(命令行脚本)

# IndexTTS-2.5
PYTHONPATH="$PYTHONPATH:." uv run indextts/infer_v2_5.py \
  --cfg_path checkpoints/config.yaml \
  --model_dir checkpoints \
  --text "Hello world" \
  --lang EN

infer_v2_5.py 脚本参数(来自源码定义):--cfg_path(默认 checkpoints/config.yaml)、--model_dir(默认 checkpoints)、--prompt_wav(默认 examples/voice_01.wav)、--text、--lang(默认 ZH)、--output(默认 gen.wav)、--text_normalization(默认开启)。

7.6 Python API 调用

0. 初始化模型

# IndexTTS-2
from indextts.infer_v2 import IndexTTS2
tts = IndexTTS2(
    cfg_path="checkpoints_2/config.yaml",
    model_dir="checkpoints_2",
    use_fp16=False,
    use_cuda_kernel=False,
    use_deepspeed=False,
)

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

1. 单段参考音频克隆音色

text = "Translate for me, what is a surprise!"

# IndexTTS-2
tts.infer(spk_audio_prompt='examples/voice_01.wav', text=text,
          output_path="gen.wav", verbose=True)

# IndexTTS-2.5(多语言,需指定 lang)
tts.infer(spk_audio_prompt='examples/voice_01.wav', text=text, lang="EN",
          output_path="gen.wav", verbose=True)

2. 独立情绪参考音频控制情绪

text = "酒楼丧尽天良,开始借机竞拍房间,哎,一群蠢货。"

# IndexTTS-2
tts.infer(spk_audio_prompt='examples/voice_07.wav', text=text,
          output_path="gen.wav", emo_audio_prompt="examples/emo_sad.wav", verbose=True)

# IndexTTS-2.5
tts.infer(spk_audio_prompt='examples/voice_07.wav', text=text, lang="ZH",
          output_path="gen.wav", emo_audio_prompt="examples/emo_sad.wav", verbose=True)

3. 情绪强度 emo_alpha

指定情绪参考音频时,emo_alpha 调节其对输出的影响程度,范围 0.0–1.0,默认 1.0:

# IndexTTS-2.5
tts.infer(spk_audio_prompt='examples/voice_07.wav', text=text, lang="ZH",
          output_path="gen.wav", emo_audio_prompt="examples/emo_sad.wav",
          emo_alpha=0.9, verbose=True)

4. 情绪向量(8 维)

不传情绪音频,直接传入情绪强度列表,顺序为 [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm];use_random 引入随机性,默认 False,开启会降低克隆保真度:

text = "对不起嘛!我的记性真的不太好,但是和你在一起的事情,我都会努力记住的~"

# IndexTTS-2.5
tts.infer(spk_audio_prompt='examples/voice_09.wav', text=text, lang="ZH",
          output_path="gen.wav", emo_vector=[0, 0, 0.8, 0, 0, 0, 0, 0],
          use_random=False, verbose=True)

5. 由台词文本自动生成情绪 use_emo_text

开启 use_emo_text 后把脚本文本转为情绪向量;官方建议 emo_alpha 取 0.6 或更低以获得自然语音。IndexTTS-2.5 使用该模式时,构造模型必须带 use_qwen_emo=True,否则会抛出 RuntimeError(IndexTTS-2 不需要该开关):

# IndexTTS-2.5:构造时开启 use_qwen_emo
tts = IndexTTS2(cfg_path="checkpoints/config.yaml", model_dir="checkpoints",
                use_bf16=True, use_qwen_emo=True)

text = "快躲起来!是他要来了!他要来抓我们了!"
tts.infer(spk_audio_prompt='examples/voice_12.wav', text=text, lang="ZH",
          output_path="gen.wav", emo_alpha=0.6, use_emo_text=True,
          use_random=False, verbose=True)

6. 显式情绪描述 emo_text

台词脚本与情绪描述分开控制,情绪描述由 emo_text 传入并转换为情绪向量:

text = "快躲起来!是他要来了!"
emo_text = "你吓死我了!你是鬼吗?"

tts.infer(spk_audio_prompt='examples/voice_12.wav', text=text, lang="ZH",
          output_path="gen.wav", emo_alpha=0.6, use_emo_text=True,
          emo_text=emo_text, use_random=False, verbose=True)

7. 语速控制 duration_factor

大于 1.0 放慢,小于 1.0 加快,范围 0.5–2.0,默认 1.0:

# 放慢(1.2 倍时长)
tts.infer(spk_audio_prompt='examples/voice_01.wav', text="大家好,欢迎来到IndexTTS的语速控制演示。",
          lang="ZH", output_path="gen_slow.wav", duration_factor=1.2, verbose=True)

# 加快(0.8 倍时长)
tts.infer(spk_audio_prompt='examples/voice_01.wav', text="大家好,欢迎来到IndexTTS的语速控制演示。",
          lang="ZH", output_path="gen_fast.wav", duration_factor=0.8, verbose=True)

8. 发音控制标注示例(2.5)

他在银<行|XING2>里<行|HANG2>走了半天,发现这笔业务办不<行|HANG2>。

He had a <minute|M IH1 . N AH0 T> to examine the <minute|M AY0 . N UW1 T> details of the contract.

彼は料理が<上手|じょうず>だが、囲碁では<上手|うわて>に負けた。

9. 旧版 IndexTTS-1.5(Legacy)

from indextts.infer import IndexTTS
tts = IndexTTS(model_dir="checkpoints", cfg_path="checkpoints/config.yaml")
voice = "examples/voice_07.wav"
text = "在这里替换为你的旧版模型合成文本。"
tts.infer(voice, text, 'gen.wav')

更多旧版细节见 archive/README_INDEXTTS_1_5.md 与 index-tts:v1.5.0 分支。

8 配置项说明

8.1 WebUI 命令行参数(webui.py)

参数 默认值 取值 / 说明
--port 7860 Gradio 监听端口
--host 0.0.0.0 监听主机地址
--model_dir ./checkpoints 模型检查点目录;2.0 使用 ./checkpoints_2
--version 2.5 可选 2、2.5,选择加载的模型版本
--fp16 False 开启 FP16 推理(2.0;2.5 在支持时走 BF16)
--deepspeed False 开启 DeepSpeed 加速,需 --extra deepspeed
--cuda_kernel False 启用编译 CUDA 内核加速
--accel False 启用 GPT2 加速引擎,需 --extra accel(flash_attn)
--torch_compile False 启用 torch.compile 优化 s2mel,需对应 extra
--qwen_emo False 低显存时强制加载 QwenEmotion(默认低显存跳过)
--gui_seg_tokens 120 GUI 单段生成最大 token 数
--share False 生成 Gradio 公开临时分享链接(供 Colab 等平台使用)
--verbose False 开启详细日志

8.2 模型目录与必需文件

版本 目录(官方示例) 必需文件(webui.py 校验清单)
2.5 checkpoints gpt.pth、s2mel.pth、codec.pth、multilingual_zh_ja_yue_char_del.tiktoken、wav2vec2bert_stats.pt
2 checkpoints_2 bpe.model、gpt.pth、s2mel.pth、wav2vec2bert_stats.pt

配置文件 config.yaml 由 ensure_config_available 在缺失时自动补全。模型仓库映射:2 → IndexTeam/IndexTTS-2,2.5 → IndexTeam/IndexTTS-2.5。

8.3 Python API 构造参数(2.5)

参数 默认值 说明
cfg_path — 配置文件路径,如 checkpoints/config.yaml
model_dir — 模型目录,如 checkpoints
use_bf16 — 是否启用 BF16 半精度(2.5)
use_qwen_emo — 为 True 时加载 QwenEmotion,供 use_emo_text 使用

2.0 构造参数:cfg_path、model_dir、use_fp16、use_cuda_kernel、use_deepspeed。

8.4 infer() 推理参数

参数 默认值 说明
spk_audio_prompt 必填 说话人参考音频路径,决定克隆音色
text 必填 待合成台词文本
lang — 2.5 目标语言:ZH / EN / JP / ES / AR
output_path 必填 输出 WAV 路径
verbose False 打印详细推理日志
emo_audio_prompt None 情绪参考音频路径
emo_alpha 1.0 情绪强度,0.0–1.0
emo_vector None 8 维情绪向量,顺序 [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]
use_random False 随机采样;开启降低克隆保真度
use_emo_text False 由台词文本自动转换情绪向量;2.5 需构造时 use_qwen_emo=True
emo_text None 显式情绪描述文本,与台词分开控制
duration_factor 1.0 语速时长倍数,0.5–2.0,大于 1 放慢、小于 1 加快

8.5 环境变量与镜像

变量 取值 说明
HF_ENDPOINT https://hf-mirror.com HuggingFace 国内镜像;模型 / 小权重下载前在 shell 导出
PyPI 镜像 aliyun / tsinghua 地址 通过 uv sync --default-index "..." 指定,见 7.2 节

9 常用运维命令

# 查看 WebUI 全部参数
uv run webui.py -h

# 检测 GPU 与环境
uv run tools/gpu_check.py

# 重新同步依赖(更新代码或 lockfile 后)
uv sync --all-extras

# 单独安装示例音频(未启动 WebUI 时)
uv run python -c "from indextts.utils.examples_downloader import ensure_examples_available; ensure_examples_available()"

# 启动 2.5 WebUI(指定端口与地址)
uv run webui.py --host 0.0.0.0 --port 7860

# 启动 2.0 WebUI
uv run webui.py --version 2 --model_dir ./checkpoints_2

# 前台停止 WebUI:Ctrl+C;重启重复执行启动命令

更新代码与模型:

git pull
uv sync --all-extras
# 模型目录按需重新执行 hf download / modelscope download

备份与数据:

  • 备份 checkpoints/、checkpoints_2/ 模型目录与 config.yaml,避免重复下载;
  • 备份 examples/ 参考音频与自己保存的音色 / 情绪预设;
  • 合成产物按业务需要单独归档;仓库内运行时音频与预设不要提交到公开仓库。

vLLM 生产环境的启停、日志、扩缩容与健康检查命令,以官方 Recipe 页面给出的服务定义为准(第 6.1 节)。

10 常见故障排查

10.1 安装阶段 CUDA 报错

现象:uv sync 过程中 PyTorch / DeepSpeed / flash-attn 编译或导入报 CUDA 相关错误。

处理:按官方提示确认 Linux / Windows 已安装 NVIDIA CUDA Toolkit 12.8 或更新版本,驱动与 PyTorch cu128 索引匹配;先执行 uv run tools/gpu_check.py 确认驱动可被识别。DeepSpeed 在 Windows 安装困难时,去掉 --all-extras 改为 --extra webui 等最小集合。

10.2 模型或示例音频下载失败 / 超时

现象:启动 WebUI 时卡在下载权重,或报连接 HuggingFace 超时。

处理:

  1. 先导出镜像环境变量再启动:
export HF_ENDPOINT="https://hf-mirror.com"
  1. 或改用 ModelScope 渠道下载到对应目录(7.3 节方式 B);
  2. 确认 checkpoints / checkpoints_2 目录必需文件齐全后再启动 WebUI;
  3. 网络恢复后删除不完整的缓存目录重新下载,避免校验失败。

10.3 低显存下情绪文本控制不可用

现象:界面提示"该预设使用了情绪描述文本控制,当前显存不足未加载该模型",或 use_emo_text 报错。

原因:显存低于 10.0 GB 阈值时,webui.py 默认跳过 QwenEmotion 加载。

处理:低显存机器改用情绪参考音频或情绪向量方式;如确需文本情绪控制,显式追加 --qwen_emo 强制加载(2.5 Python API 构造时传 use_qwen_emo=True),并关注显存占用。

10.4 use_emo_text 抛出 RuntimeError(2.5)

现象:2.5 推理时开启 use_emo_text 报缺少情绪模型的运行时错误。

处理:初始化模型时必须带上 use_qwen_emo=True(见 7.6 节第 5 步);IndexTTS-2 不需要该开关。

10.5 依赖冲突 / 环境串台

现象:uv 命令报版本冲突,或导入到其他已激活虚拟环境的 Python 里。

处理:官方明确要求不要手动激活虚拟环境,直接用 uv run <命令> 执行;退出当前 shell 后重新进入仓库目录再执行 uv sync --all-extras;不要把系统 Python 的 site-packages 混入项目 .venv。

10.6 可选加速模块导入失败

现象:加 --accel 报 flash_attn 导入失败;加 --torch_compile 报 triton 缺失;加 --deepspeed 报 DeepSpeed 未安装。

处理:按提示安装对应 extra:uv sync --extra accel、uv sync --extra torch_compile、uv sync --extra deepspeed;安装失败时先去掉对应开关以最小可用环境跑通基础合成,再单独排查加速依赖。

10.7 端口 7860 被占用

现象:WebUI 启动报端口已被占用。

处理:改用其他端口:

uv run webui.py --port 7861

10.8 发音标注不生效

现象:拼音 / 音素 / 假名标注未被按预期读出。

排查:

  • 中文拼音确认处于 checkpoints/pinyin.vocab 支持的合法组合内;
  • 英语音素使用 CMU 词典有效条目;
  • 日语假名标注格式为 <词|假名>;
  • 标注括号与分隔符保持官方示例格式,不要替换为其他符号。

10.9 合成音色与参考音频偏差较大

排查:确认参考音频干净、无人声重叠与强背景噪声;避免开启 use_random=True;情绪参考音频与说话人参考音频分别来自授权对象;长文本按 --gui_seg_tokens 分段处理,必要时缩短单段文本重试。

11 风险与合规说明

11.1 许可证范围(bilibili Model Use License Agreement)

  • 本项目模型权重与代码按 LICENSE 授予有限、非独占、不可转让、免许可费的使用许可,输出结果与衍生作品同样受协议约束。
  • 大规模使用门槛:若使用方或其关联方产品 / 服务上月月活超过 1 亿,或上一年度年营收超过 人民币 10 亿元,必须事先向权利方单独申请许可,未取得书面授权前不得行使协议权利。
  • 模型训练限制:除 bilibili indextts2 本身、其衍生作品与非商业 AI 模型外,不得使用本模型或衍生作品去改进其他 AI 模型。
  • 高风险场景禁用:协议明确禁止直接或间接部署于医疗诊断、自动驾驶、军事应用、关键基础设施控制、大规模生物特征监控、自动化决策(如信用 / 雇佣评估)等高风险场景;坚持部署需自行完成全部合规义务,权利方不承担相应后果。
  • 下游传递义务:分发衍生作品时须保留原始版权声明与协议副本,并向接收方施加同等合同条款;衍生作品的修改需在分发页注明"原权利方不背书、不保证、不承担责任"。
  • 法律适用:协议受中华人民共和国法律管辖;争议优先友好协商,协商不成提交上海仲裁委员会仲裁;中英文版本冲突时以中文版本为准。
  • 商业使用与合作请联系官方邮箱 indexspeech@bilibili.com,取得书面授权后再用于收费产品、SaaS 或商业配音。

11.2 声音与肖像授权(DISCLAIMER 口径)

DISCLAIMER 明确规定,使用者不得:

  • 合成政治人物、公众人物或任何未经授权个人的声音;
  • 创建诋毁、侮辱、歧视或损害他人名誉与权益的内容;
  • 进行欺诈、身份盗用或任何形式违法活动;
  • 传播虚假信息或制造社会恐慌;
  • 侵犯他人知识产权、肖像权或隐私权;
  • 未经授权将合成声音用于商业目的;
  • 违反金融、医疗等特定行业法规;
  • 创建或使用涉及未成年人的不当声音内容;
  • 制作威胁国家安全的内容;
  • 违反所在地区关于深度伪造技术的法律法规。

11.3 使用建议

  • 只克隆本人拥有、或已取得书面授权的参考音频;参考音频中的说话人需清晰、权属明确。
  • 对外发布 AI 合成语音时,按当地法规标注"内容由 AI 合成",不得冒充真人进行身份欺骗、电信营销或金融话术。
  • 使用第三方数据集、第三方参考音频或第三方权重时,自行取得必要授权并承担合规责任。
  • 合成文本内容由使用者自负其责;开发者不对用户使用本项目产生的直接或间接后果承担责任(协议第 3 章风险分配)。

11.4 免责声明

本指南依据官方公开文档整理,命令、参数、端口与许可条款均来自仓库 README、docs/README_zh.md、LICENSE、DISCLAIMER、webui.py 与 pyproject.toml;官方后续版本可能调整模型渠道、依赖版本与界面参数,部署时以仓库最新说明为准。作者与本文不对因使用、修改或运行本项目产生的直接或间接损失承担责任,法律不得排除或限制的责任除外。

评论交流

文章目录