![]()
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 为 README 中 IndexTTS-2.5 演示视频封面,对应 B 站演示片与官方 Demo 页面;演示音频与跨语言效果以官方 Demo 为准。

图3 为 README 中 IndexTTS-2 演示宣传图,体现"文本提示 →
丰富情绪语音"的能力定位。本地 uv run webui.py 启动后的
Gradio 界面包含说话人参考音频、情绪参考音频 /
情绪向量、文本输入、语言选择、语速与情绪强度等控件,具体布局以本地启动版本为准。
4 官方跳转链接汇总
下表列出项目相关的全部官方入口,均可直接点击访问。
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 章的源码环境与模型下载,确认:
uv sync --all-extras依赖安装成功;- 模型目录必需文件齐全(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); tools/gpu_check.py能正确识别目标 GPU;- 参考音频、文本长度与并发规模在本机实测通过,再迁移到 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.py7.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 -h7.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 ENinfer_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 超时。
处理:
- 先导出镜像环境变量再启动:
export HF_ENDPOINT="https://hf-mirror.com"- 或改用 ModelScope 渠道下载到对应目录(7.3 节方式 B);
- 确认
checkpoints/checkpoints_2目录必需文件齐全后再启动 WebUI; - 网络恢复后删除不完整的缓存目录重新下载,避免校验失败。
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 786110.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;官方后续版本可能调整模型渠道、依赖版本与界面参数,部署时以仓库最新说明为准。作者与本文不对因使用、修改或运行本项目产生的直接或间接损失承担责任,法律不得排除或限制的责任除外。