IndexTTS 使用教程-cmzhiku

项目简介

IndexTTS 是哔哩哔哩 IndexTeam 开源的零样本配音项目。当前版本是 2026 年 8 月发布的 IndexTTS-2.5，仓库约 2.4 万星，协议是 B 站模型使用协议，不是随便能商用的那种宽松协议。给它一小段人声，再给一段文字，它就用这段声音把字念出来。

2.5 支持中文、英文、日文、西班牙文、阿拉伯文，音色和情绪可以分开控：同一段参考声音，情绪可以另给一段录音，也可以直接写一句情绪描述。语速用 duration_factor 调，范围 0.5 到 2.0，大于 1 是放慢，小于 1 是加快。模型大约 8 亿参数。

和 Codex 的接法是把仓库交给它，让它按官方说明用 uv 装环境、把 2.5 模型下到本机，再用你的参考录音把口播稿按场景配完。本机需要一张英伟达显卡。官方演示页上的影视重配音样片，就是这个系列拿来展示效果的。

📎 相关链接（点击展开）

核心亮点

🎙️ 几秒录音就能念

不用微调训练。一段干净人声当参考，后面打字都用这个嗓子。

🎭 情绪和嗓子分开

另给一段带情绪的录音，或写一句情绪描述。浓淡用 emo_alpha 调，建议文字情绪从 0.6 往下试。

⏩ 语速单独调

duration_factor 从 0.5 到 2.0。卡画面长短时放慢或加快，不用重录。

🌏 五种语言

中文、英文、日文、西班牙文、阿拉伯文。同一段中文参考音可以念外语。

它能做什么、输出什么

项目	说明
输入	一段参考人声（wav），加要念的文字。情绪可以再加一段录音、8 个情绪数值，或一句情绪描述
适用类型	口播、解说、带情绪的台词、同一条视频的外语版
输出	wav 音频。网页演示和 Python 接口都能指定输出文件
语言	中文、英文、日文、西班牙文、阿拉伯文。2.5 还能标拼音、英文音标、日文假名来纠发音
规格	2.5 约 8 亿参数。情绪向量顺序：开心、生气、难过、害怕、厌恶、忧郁、惊讶、平静

环境要求

环境	建议配置
操作系统	Windows、Linux 都按仓库说明走。Windows 上 DeepSpeed 经常装不上，不要开这个附加项
运行环境	先装 git 和 uv。依赖只用 uv 装，官方不保证用 conda 或单独 pip 能装对
硬件	英伟达显卡。安装报 CUDA 错误时，本机 CUDA 工具包要 12.8 或更新。官方没写死显存数字，2.5 用 BF16 可以少占显存
没有显卡	本机跑不了。可以先看官方演示页里的样片。不要改用不明来源的在线代跑网站，仓库声明只有 GitHub 这一个官方渠道
关键依赖	uv、网页演示附加项 webui、2.5 模型权重。第一次打开网页演示还会自动下示例音频

如何使用

💡 主线用 IndexTTS-2.5。仓库拉下来之后，三步：uv 装网页演示、下 2.5 模型、跑网页演示。Windows 不要装 DeepSpeed。

步骤 1

克隆仓库并装环境

在 GitHub 搜索 index-tts，进 index-tts/index-tts 这个仓库，克隆到本地。然后只加网页演示这一项，避开 Windows 上难装的 DeepSpeed。

bash

cd index-tts
pip install -U uv
uv sync --extra webui

步骤 2

下载 2.5 模型

权重下到仓库里的 checkpoints 目录。国内访问慢时，先按文末折叠区里的镜像设置环境变量，再执行下载。

bash

uv tool install "huggingface-hub"
hf download IndexTeam/IndexTTS-2.5 --local-dir=checkpoints

也可以改用 ModelScope，包名同样是 IndexTeam/IndexTTS-2.5，目录仍是 checkpoints。

步骤 3

先在网页里听一次

跑起来后，按终端打印的本机地址打开。上传你自己的一段干净人声，打一行字生成。确认嗓子对，再交给脚本批量跑。

bash

uv run tools/gpu_check.py
uv run webui.py

步骤 4

用 Python 按场景出音频

2.5 的类在 infer_v2_5 里。文字情绪必须在初始化时打开 use_qwen_emo，否则一调用就报 RuntimeError。参考录音换成你自己的文件。

python

from indextts.infer_v2_5 import IndexTTS2
tts = IndexTTS2(cfg_path="checkpoints/config.yaml", model_dir="checkpoints", use_bf16=True, use_qwen_emo=True)
tts.infer(spk_audio_prompt="my_voice.wav", text="封面这一段兴奋一点。", lang="ZH", output_path="封面.wav", emo_text="兴奋", emo_alpha=0.6, use_emo_text=True)
tts.infer(spk_audio_prompt="my_voice.wav", text="结尾平静一点。", lang="ZH", output_path="结尾.wav", duration_factor=1.1)

常用参数：

参数	作用
`spk_audio_prompt`	参考人声，决定嗓子
`lang`	ZH / EN / JA / ES / AR
`emo_audio_prompt`	另一段带情绪的录音，和嗓子分开
`emo_alpha`	情绪有多浓，0 到 1，默认 1。文字情绪建议 0.6 或更低
`emo_text`	用一句话描述情绪。要同时开 use_emo_text，并且初始化时 use_qwen_emo=True
`emo_vector`	8 个小数，顺序见上面的能力表。和情绪录音二选一
`duration_factor`	0.5 到 2.0。大于 1 放慢，小于 1 加快
`use_random`	打开后音色会漂，克隆不像本人。配音保持默认关闭

步骤 5

结合 Codex 使用

把仓库目录交给 Codex，把下面这段原话发过去。它会按官方说明装环境、下模型，再用你放进去的参考录音把口播稿按场景存成 wav。

提示词

按仓库说明用 uv 装好网页演示，不要装 DeepSpeed。把 IndexTTS-2.5 下到 checkpoints。用我放进来的参考录音，把这份口播稿按场景配音：封面兴奋一点，结尾平静一点，每段用场景名存成 wav。

✅ 装完先跑 gpu_check 和网页演示听一句。嗓子不对就换更干净的参考录音，不要先怪模型。

典型应用场景

🎬 口播配音

稿子按场景切开，每段用自己的声音念，封面和结尾可以要不同语气。

🎧 解说

录一段平时说话的声音当参考，长稿分成几段生成，避免一口气太长念飘。

🎭 带情绪的台词

同一嗓子，情绪描述换成高兴或难过。浓淡不够再补一段情绪参考录音。

🌐 一条视频的外语版

中文参考音念英文或日文。官方跨语言评测就是中文音色说目标语言。

⏱️ 卡画面时长

句子太短或太长时只改 duration_factor，不用重录。

🔤 专有名词读错

中文可以标拼音，英文可以标音标，日文可以标假名，让它按这个音念。

性能表现

数字来自仓库 README 里 IndexTTS-2.5 技术报告的表，评测集是 CV3-Eval。WER 越低越好，说话人相似度越高越像参考音。

指标	官方数字
参数量	0.8B
零样本平均（2.5 / 2.5-RL）	WER 6.75 / 6.00，说话人相似度 73.18 / 73.63
中文零样本（2.5）	WER 4.36，说话人相似度 77.10
跨语言平均，中文音色说外语（2.5 / RL）	WER 6.22 / 6.17，相似度 68.62 / 70.20
RTX 4090 综合 RTF，越低越快	2.5 bf16 为 0.2065，2.0 fp16 为 0.3257